Add an Android target alongside the desktop bundles. Users download a signed
universal .apk and sideload it; minSdk 31 blocks Android < 12 at install time.
- tauri.conf.json: bundle.android (minSdkVersion 31, versionCode 10601)
- commit the generated src-tauri/gen/android Gradle project (source only; build
outputs + keystore stay gitignored) with release signing wired from a
gitignored keystore.properties (graceful unsigned fallback when absent)
- self-host fonts via @fontsource (drop Google Fonts <link>, tighten CSP) so the
app renders fully offline
- robust native file open: basenameFromPath() recovers a filename from Android
content:// URIs; the native-open path filters extensions leniently so opaque
MediaStore URIs the dialog already vetted are not wrongly rejected
- npm scripts tauri:android:{init,dev,build}; android job in release.yml signs
from secrets and uploads the APK to the same draft release
- docs: README/README.vi Android sections, TAURI-NOTES maintainer notes (incl.
the WebView Chromium >= 111 requirement), ROADMAP phase 7
Validated on emulators: signed APK installs on Android 12+, blocked on API < 31
(INSTALL_FAILED_OLDER_SDK), launches, renders, runs converters, reads files via
the SAF picker, fully offline. New unit tests for basenameFromPath + lenient
filterByExtension; full gate green (format/typecheck/lint/knip/215 tests).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
14 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.
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 to Phase 2 (needs per-format language packages: yaml, xml, sql)
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)
- 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; Sheet trigger handles its own keyboard nav via Radix
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). - 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
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 - 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 - 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.
Beyond — Ideas (no commitment)
- JSON → Excel (.xlsx) via SheetJS — possible if Markdown/CSV doesn't cover the use case
- Reverse direction (other format → JSON): different mental model; might warrant a sibling app
- Schema inference: emit JSON Schema, 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)
These are deliberately deferred — Phase 1–5 first.
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.