The Worker now runs first for every request except the content-hashed bundles under /assets/ (run_worker_first: ["/*", "!/assets/*"]) and counts it against a per-client limit before serving it: - SITE_LIMITER: pages and public files, 120 requests / 60 s - API_LIMITER: every /api/* request, 60 / 60 s - VERIFY_LIMITER: /api/turnstile/verify on top, 30 / 60 s (unchanged) Over the limit, pages get a plain-text 429 in the four UI languages and the API a JSON 429 (rate_limited); both carry Retry-After: 60. Clients are keyed on their IPv4 address or the /64 of their IPv6 address, never logged. Pages still go through env.ASSETS.fetch(), so _headers, _redirects and the SPA fallback apply as before. A failing limiter lets requests through. Previews get their own counters (namespace_id 4204/4206). Docs: DEPLOYMENT, PRIVACY (wording only, nothing new collected, no re-consent), SECURITY, CONTRIBUTING, READMEs, CLAUDE.md, ROADMAP, CHANGELOG. Version 2.0.2 (versionCode 20002). Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
21 KiB
JSONPrism Roadmap
This document is the single source of truth for what's done, what's next, and why.
Update it as work lands — keep the project status honest.
Current release: v2.0.2 (2026-10-27). The web app runs at https://jsonprism.poli0981.dev (Cloudflare Workers); desktop and Android builds are on GitHub Releases.
Phase 0 — Scaffold ✅
Status: complete (2026-05-12) Duration: ~1 day
Foundation: build tooling, app shell, converter framework, four working converters, full docs.
What landed:
- Vite 6 + React 19 + TypeScript 5.7 strict
- Tailwind v4 + shadcn-ready theme tokens
- Routing, theming, i18n (EN + VI), error boundary
- Converter interface + registry + shape detection
- Working: JSONL, CSV, TSV, YAML
- Stubs with detailed plans: XML, TOML, Markdown, SQL, RESX
- CI + GH Pages deploy workflows
- Full documentation suite
Phase 1 — Polish & Foundations ✅
Status: complete (2026-05-12) Actual: ~1 day
Goal: make the four working converters production-quality and the UX delightful enough to share publicly.
Tasks
1.1 Editor upgrade
- Replace
<textarea>input with CodeMirror 6 +@codemirror/lang-json - Line numbers + active-line highlight
- Folding for nested structures
- Theme: custom Prism Spectrum tokens applied to lezer highlight tags
- Parse-error linting (visible gutter markers)
- Output panel uses CodeMirror in read-only mode with format-specific syntax — deferred at the time; landed in 2.0.0 (Phase 8)
1.2 Settings panel
- Side sheet (Radix Dialog) that opens per-converter options
- Form widgets auto-generated from
optionSchema: Switch, segmented enum, number input, text input - Settings persist to localStorage per format
- "Reset to defaults" button with toast confirmation
1.3 Per-format options exposed in UI
- JSONL: pretty toggle
- CSV/TSV: header toggle, newline (LF/CRLF), nested strategy (json/flatten)
- YAML: indent (2–8), quote style
1.4 File handling
- Drag-drop a single
.jsonfile onto the input panel - "Open file…" button via hidden file input
- Drop overlay with Prism Spectrum styling
- Auto-detect file encoding — non-issue; FileReader uses UTF-8 by default and modern editors don't emit BOM
1.5 Notifications
- Sonner toast for: copy success/failure, download started, file loaded/failed, options reset
- Dismissible, bottom-right, dark/light aware via ThemeProvider integration
1.6 Testing
- Vitest + @testing-library/react + jsdom configured
- Unit tests for all Phase 1 converters (happy path + edge cases): 35+ tests
- Tests for
parseJsonInput,detectShape,options-storage - CI runs tests between typecheck and build
1.7 Polish
- Keyboard shortcuts: ⌘/Ctrl+K (clear), ⌘/Ctrl+S (download) — ⌘/Ctrl+K removed in 2.0.0: it clashed with the browser's search shortcut
- Status bar showing: input bytes, output bytes, parse time, shortcut hints
- Shape detection hint (scalar / object / array / flat-object / array-of-objects)
- Disabled-format chips show "P2"/"P3" badge with tooltip
- Cmd/Ctrl+, to open settings — deferred at the time; added in a later 1.x release
Deliverable
A polished, single-file converter UX with four production-grade converters. Ready to demo publicly and share in the Discord open-source server. 35+ unit tests passing.
Phase 2 — Four more formats + batch + Tauri
Split into three sub-phases for digestibility.
Phase 2A — Four new converters ✅
Status: complete (2026-05-12) Actual: ~1 day
XML converter
fast-xml-parserXMLBuilderintegration- Configurable root element name, item name, declaration, indent
- Attribute convention: keys starting with
@_become attributes - Array handling: each item wrapped with
itemNameelement when array is root - XML declaration prepended conditionally
- 8 unit tests including round-trip via
XMLParser
TOML converter
smol-tomlstringifyintegration- Rejects non-object roots (array, scalar, null) with clear error
sortKeysoption, recursive- Nested tables emitted naturally via smol-toml
- 7 unit tests including round-trip via
parse
Markdown table converter
- Hand-rolled, zero deps
- Header row from union of all object keys (preserve insertion order)
- Alignment markers per column (left/center/right/none)
- Pipe escaping in cell values
- Newlines →
<br>per GFM - Nested values JSON-stringified
- 11 unit tests
SQL INSERT converter
- Hand-rolled, zero deps
- Dialect support: standard / postgres / mysql / sqlite / mssql
- Identifier quoting per dialect (double-quote / backtick / bracket) with proper escaping
- Value escaping per dialect (booleans differ across all 5)
- Multi-row INSERT with configurable chunk size
- Optional
CREATE TABLEinference from first row's types - Missing keys across rows →
NULL - 19 unit tests (helpers + integration; 5 dialects × value types)
Phase 2B — Batch processing ✅
Status: complete (2026-05-12) Actual: ~1 day
- Drag-drop multiple files onto a dropzone (
react-dropzone) - Batch queue panel showing: filename, size, status (queued/processing/done/error), output size
- Hard limit: 500 files (
BATCH_MAX_FILES) - Process in chunks to keep UI responsive (
requestIdleCallbackwithsetTimeout(0)fallback) - "Download all (.zip)" via fflate (chosen over JSZip for ~12× smaller bundle)
- Per-file error display without blocking the rest of the queue
- AbortController-based cancellation
- Smart drop routing: 1 file → editor, 2+ files → batch panel auto-opens
- Zustand store with item map + display order for O(1) per-item updates
- Filename collision handling in the zip
- 20+ unit tests including round-trip zip decode
Phase 2C — Tauri 2 desktop wrapper ✅
Status: complete (2026-05-12) Actual: ~1 day
src-tauri/scaffold with Tauri 2.x (Cargo.toml,tauri.conf.json,lib.rs)- Tauri serves Vite-built
dist/; dev mode runs Vite + Tauri window with HMR - Native file open/save dialogs via
plugin-dialog+plugin-fs - OS drag-drop integration via
tauri://drag-dropevents (hook:useTauriDragDrop) - App icons: SVG source committed (
src-tauri/icons/icon.svg), generated formats vianpm run tauri:icon - Bundle targets: Windows (MSI + NSIS
.exe), macOS (DMG + .app, min 12.0), Linux (AppImage + deb) - CSP and capability file locked down (scoped to user dirs only)
- Custom Rust command
host_infofor diagnostics - GitHub Actions release workflow (matrix: Windows / macOS ARM / macOS Intel / Linux); draft release on
v*tag - Vite config detects Tauri context and adjusts base path + dev server
- Frontend
isTauri()runtime gate keeps web bundle free of Tauri imports (tree-shaken) Velopackskipped — using Tauri's native bundler (avoids the two-tool overhead PhantomMAC has)
Deliverable (full Phase 2)
8/9 formats production-ready. Batch up to 500 files. Desktop builds for Windows / macOS / Linux. JSONPrism becomes a "real" tool, not just a website.
Currently at Phase 2A — only RESX (Phase 3) remains as a stub.
Phase 3 — RESX & i18n integration ✅
Status: complete (2026-05-12) Actual: ~1 day
Goal: ship the .NET RESX converter and integrate with existing AutoClickForge / PhantomMAC localization workflows.
Tasks
3.1 RESX converter
- Hand-rolled XML output (skip fast-xml-parser; the template is too rigid)
- Standard RESX 2.0 header with
xsd:schema+ 4resheaderelements (resmimetype, version, reader, writer) - Input contract: flat object
{ "Key": "value" }; nested objects → reject with helpful error - Optional
_commentkey (configurable viacommentKeyoption) → emits<comment>element on the<data> - XML escaping for text content (&, <, >) and attribute context (quotes)
- Number and boolean coercion to string
- Null/undefined coerced to empty string
sortKeysoption for stable diffs across locale filesincludeSchemaoption (Visual Studio expects schema; tests verify byte-exact match)- 17 unit tests covering schema, comment shape, escaping, sort order, error paths
3.2 Smart UI for the RESX use case
- Format picker highlights suggested formats based on
detectShapeoutput via subtle ring - Flat-object detection surfaces RESX first in the suggestion list
- Batch processor preserves locale segment in filenames:
strings.vi.json→strings.vi.resx
3.3 Documentation
docs/RESX-MIGRATION.md— tutorial: i18next JSON → .NET RESX, with flatten script, batch flow, Visual Studio verification, comment support, CI sketch- Cross-link with PhantomMAC / AutoClickForge i18n docs in the worked example
Deliverable
9/9 formats production-ready. RESX integration documented as a real migration path between i18next-based web projects and .NET WPF projects. JSONPrism reaches 1.0.
Phase 4 — Binary formats & reverse conversion ✅
Status: complete (shipped in v1.1.0)
Post-1.0 expansion: three binary target formats and bidirectional conversion.
- BSON / CBOR / MessagePack converters — output rendered as base64 (default) or hex; downloads decode back to raw bytes. New
ConverterMeta.binaryflag. - Reverse conversion — optional
Converter<T>.reverse()interface method; JSONL, CSV/TSV, YAML, TOML, RESX → JSON. NewDirectionTogglecomponent, direction persisted to localStorage. - Reverse batch processing — drop non-JSON files, get a
.zipof.jsonoutputs back.
12/12 formats production-ready.
Phase 5 — Maintenance & refactor ✅
Status: complete (shipped in v1.5.0)
Codebase hygiene plus a small UX addition — no converter behavior changed.
- Decomposed three oversized components (
BatchPanel,ConverterWorkspace,InputPanel) into focused pure utilities, leaf components, and hooks — behavior-preserving, all 193 tests still green. - Integrated
knipfor dead-code analysis:knip.jsonconfig,npm run knipscript, and a CI step. Initial sweep removed orphaned code and a phantom dependency. - Scroll-to-top button on the long, scrollbar-hidden About page (respects
prefers-reduced-motion).
Phase 6 — Legal gates, error pages & load performance ✅
Status: complete (shipped in v1.6.0)
Compliance + reliability + first-paint performance. No converter behavior changed.
- Custom error pages: reusable
ErrorState, 404 catch-all, generic/error/:code(403/419/5xx variants), offline banner, and a chunk-load error boundary folded into the existing crash boundary's look. - GitHub Pages SPA deep-link fix (
public/404.html+index.htmldecoder for the/jsonPrism/base). Removed in 2.0.0: the web app moved to Cloudflare Workers, which has an SPA fallback. - First-launch legal consent gate (web only) — accept License/Terms/Privacy/Disclaimer, persisted to
localStoragewith a version for re-prompting; skipped on desktop. - Windows installer license-acceptance page via Tauri
bundle.licenseFile(src-tauri/license.rtf), covering both NSIS.exeand WiX.msi. - Lazy-load routes + the CodeMirror editor; refined
manualChunks(react/router/i18n/cm-core/cm-langs/per-parser/ui); removed thebsoninitial-graph leak vialib/bytes.ts. +16 tests (209 total).
Phase 7 — Android (sideload APK) 🔜
Status: in progress — the APK has shipped with every release since v1.7.0 (2026-06-16); only the real-device checks below remain.
Goal: ship JSONPrism as an Android app users sideload from a .apk. Same React UI, no behavior change to the converters. Minimum Android 12 (API 31) — older devices are blocked by the OS.
Tasks
bundle.androidintauri.conf.json:minSdkVersion: 31, deterministicversionCode(MAJOR*10000+MINOR*100+PATCH)tauri android init→ Android Gradle project atsrc-tauri/gen/android/, committed (source only; build outputs + secrets gitignored via nested + root.gitignore)- Verified
minSdk = 31propagated toapp/build.gradle.kts; Rust compiles for all 4 ABIs (validated against NDK r27/r30) - Release signing wired in
app/build.gradle.ktsfrom a gitignoredkeystore.properties(graceful unsigned fallback when absent) - Self-hosted fonts via
@fontsource(Geist / Instrument Serif / JetBrains Mono) — removed Google Fonts<link>, tightened CSP, app renders correctly offline (Instrument Serif dropped in 2.0.0: it has no Vietnamese glyphs) - Local scripts:
tauri:android:init/tauri:android:dev/tauri:android:build(universal APK; chainstauri:icon) - CI:
androidjob inrelease.ymlbuilds + signs (keystore from secrets) + uploads the universal APK to the same draft release - Docs: README / README.vi "Android" sections + maintainer notes in
docs/TAURI-NOTES.md - Emulator-validated: signed APK installs on Android 12+, blocked on API < 31 (
INSTALL_FAILED_OLDER_SDK), launches, renders (CodeMirror + self-hosted fonts), runs converters, fully offline - Native file open works —
plugin-dialogfires the SAF picker,plugin-fsreads thecontent://URI;basenameFromPath()recovers a clean filename (unit-tested) - Found: layout needs WebView Chromium ≥ 111 (Tailwind v4); fine on updated Android 12+ devices, broken on the API 31 emulator's stock Chromium 91 — see
docs/TAURI-NOTES.md - Add CI signing secrets (
ANDROID_KEYSTORE_BASE64,ANDROID_KEYSTORE_PASSWORD, …) — maintainer action; the signed APK is attached to v1.7.0–v1.7.2 - Remaining manual checks: save
.zipvia SAF, all 12 converters end-to-end, theme + 4 locales, upgrade-in-place on a real device
Deliverable
A signed universal .apk attached to each GitHub release, installable on Android 12+. Same converter feature set as web/desktop, fully offline.
Phase 8 — 2.0.0: Cloudflare, hardening & technical UI ✅
Status: complete (shipped in v2.0.0, 2026-10-22)
A platform release: a new home for the web app, a human check and analytics confined to the web build, a toolchain jump, an audit of every converter, a UI refresh and a hardened pipeline. Same 12 formats, same layout.
Tasks
8.1 Cloudflare Workers + custom domain
- Web app served by the Cloudflare Worker
jsonprism(Workers Static Assets, SPA fallback) at https://jsonprism.poli0981.dev; config inwrangler.jsonc, operations indocs/DEPLOYMENT.md - Cloudflare Workers Builds deploys every push to
main; the GitHub Pages deploy workflow andpublic/404.htmlare gone /api/*Worker inworker/:POST /api/turnstile/verify(same-origin only, 4 KB body cap, 30 requests / 60 s rate limit) andGET /api/health; structured Workers Logs without IPs, tokens or user content- 2.0.2: per-client rate limits for the whole site — the Worker runs first for everything except the hashed
/assets/*bundles; pages 120 / 60 s, API 60 / 60 s, verify 30 / 60 s; IPv6 keyed on its /64; 429 withRetry-After - Static headers in
public/_headers(CSP, HSTS, COOP, Permissions-Policy, immutable/assets/*),/jsonPrism/*→ 301 inpublic/_redirects,robots.txt,sitemap.xml,.well-known/security.txt, Open Graph image - GitHub Pages keeps only a path-preserving redirect to the new domain (
pages-redirect.yml, run by hand) production-smoke.ymlwaits for each pushed commit to go live, then checks headers, routes, redirects and the API
8.2 Turnstile & Web Analytics (web only)
- Cloudflare Turnstile inside the Consent Gate, verified server-side by the Worker; a pass is remembered for 7 days; if Cloudflare is unreachable the user may continue after a warning
- Cloudflare Web Analytics (cookieless page views): production hostname only, after consent, toggle under Appearance, off by default when the browser sends Global Privacy Control
- Neither service exists in desktop or Android builds
CONSENT_VERSION2 asks every user again; the gate shows on web, Android, macOS and Linux (Windows relies on the installer license page)
8.3 Toolchain: TypeScript 7 / Node 26
- Node.js 26 (
.nvmrc,engines), npm 11; CI installs withnpm ci --ignore-scripts - TypeScript 7 native compiler for
tsc, plus a TypeScript 6 API alias for typescript-eslint; ES2025 target with an ES2023libto keep the Android WebView (Chromium 111) and macOS 12 floors - Majors: React 19.3, React Router 8.5 (
react-routeronly), Vite 8.3, Tailwind CSS 4.3, i18next 26, ESLint 10, Vitest 5 (app+workerprojects), Knip 6, Tauri 2.12 - Removed:
react-router-dom, Instrument Serif, the Tauri os plugin
8.4 Audit fixes
- CSV: columns from every row (not just the first), optional
escapeFormulaeguard, reverse only converts canonical numbers - SQL: MySQL backslash escaping, MSSQL
N'…'+ NVARCHAR and 1000-row batches, CREATE TABLE types inferred across all rows, dotted table names quoted per part - RESX: reverse keeps strings such as
"007", rejects DOCTYPE, validates XML; resheaders always written; CR encoded - XML: invalid element names sanitised, nested arrays wrapped, control characters replaced, output validated
- BSON > 16 MiB → clear error; YAML
quoteStyleworks again + alias/merge-key limits; TOML reports nulls with their path, keeps big integers, stable key order - Batch: real binary in the ZIP for BSON/CBOR/MessagePack, processing twice keeps results, abort returns items to the queue
- Accurate JSON error line/column on every engine; precision warning for integers beyond 2^53
- Desktop/Android: trimmed capabilities and fs scope, stricter CSP,
allowBackup="false", downloads through the native save dialog - Performance: inputs > 256 KB and all batches convert in a Web Worker; read-only, virtualised output editor; streaming ZIP
- Accessibility (live regions, editor names, ≥ 24 px targets,
<html lang>), i18n (ja + zh-CN completed, parity test in CI), local-only logger + "Copy diagnostics" on About
8.5 Technical UI refresh
- Blueprint grid, mono uppercase labels, corner ticks, per-theme prism colours (light-theme contrast ≥ 4.5:1)
- Header: animated wordmark,
v2.0.0 · <commit>chip, EN/VI/JA/ZH switcher, Appearance menu (theme, hide scrollbars, analytics) - Terminal-style status bar, thin custom scrollbars, animations only under
motion-safe, no theme flash, per-route document titles
8.6 CI hardening
- Actions pinned to full commit SHAs,
persist-credentials: false, least-privilege job permissions - CI: format, lint, knip, TypeScript 7 typecheck, tests + coverage, build, Worker deploy dry run; SonarQube Cloud (CI-based analysis); Rust fmt + clippy
- Release: tag =
package.json=Cargo.tomlversion check, one draft release, tauri-action v1, macOS universal build,JSONPrism_<version>_android-universal.apk,SHA256SUMS.txt+ build-provenance attestations - Discord notifiers called with explicit webhook secrets; Dependabot grouped by package family with a cooldown
Deliverable
JSONPrism 2.0.0 on its own domain, with the human check and analytics confined to the web build. 864 tests in 92 files, 97% line coverage (converters incl. regression + contract tests, every UI component, hooks, stores, the Web Worker client, i18n parity across 4 locales, Worker).
Beyond — Ideas (no commitment)
Deferred from 2.0.0
- Lazy-load non-English locales — about 20 KB gzip off the first load
- PWA / offline install for the web app
- Code signing — Windows Authenticode and macOS notarization — plus a signed updater
- SBOM for release builds
- OpenSSF Scorecard
- End-to-end tests — Playwright (web), tauri-driver (desktop)
- JSON tools — JSON Schema, JSONPath and diff features
- More formats — INI,
.env, Java.properties, Excel.xlsx - Streaming NDJSON for very large files
- Community translation workflow (ja and zh-CN are AI-translated today)
- Drop the TypeScript 6 alias once TypeScript 7 ships an API that typescript-eslint supports
Other ideas
- Type generation: TypeScript types or Go structs from sample JSON
- CLI version: same converter modules, exposed as a Node CLI for CI pipelines
- VS Code extension: surface the converters in the editor command palette
- Sharing: hash-based shareable URLs (
#data=...) for sample inputs (privacy: opt-in only)
Nothing here is scheduled. An item moves into a numbered phase when work on it starts.
Tracking
Update this file when:
- A task is completed (mark it
- [x]and add a date if significant) - An estimate changes meaningfully
- The phase plan changes (and explain why in the commit message)
- A new phase is added to the "Beyond" section
The goal: anyone reading this should be able to answer "What's the current state of JSONPrism?" in 30 seconds.