Files
jsonPrism/docs/ROADMAP.md
T
poli0981andClaude Opus 4.8 40c8c81028 feat(android): build & package a sideloadable APK (Tauri 2, Android 12+) (#90)
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>
2026-06-15 22:54:34 +07:00

14 KiB
Raw Permalink Blame History

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 .json file 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-parser XMLBuilder integration
  • Configurable root element name, item name, declaration, indent
  • Attribute convention: keys starting with @_ become attributes
  • Array handling: each item wrapped with itemName element when array is root
  • XML declaration prepended conditionally
  • 8 unit tests including round-trip via XMLParser

TOML converter

  • smol-toml stringify integration
  • Rejects non-object roots (array, scalar, null) with clear error
  • sortKeys option, 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 TABLE inference 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 (requestIdleCallback with setTimeout(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-drop events (hook: useTauriDragDrop)
  • App icons: SVG source committed (src-tauri/icons/icon.svg), generated formats via npm 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_info for 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)
  • Velopack skipped — 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 + 4 resheader elements (resmimetype, version, reader, writer)
  • Input contract: flat object { "Key": "value" }; nested objects → reject with helpful error
  • Optional _comment key (configurable via commentKey option) → 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
  • sortKeys option for stable diffs across locale files
  • includeSchema option (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 detectShape output 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.binary flag.
  • Reverse conversion — optional Converter<T>.reverse() interface method; JSONL, CSV/TSV, YAML, TOML, RESX → JSON. New DirectionToggle component, direction persisted to localStorage.
  • Reverse batch processing — drop non-JSON files, get a .zip of .json outputs 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 knip for dead-code analysis: knip.json config, npm run knip script, 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).

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.html decoder for the /jsonPrism/ base).
  • First-launch legal consent gate (web only) — accept License/Terms/Privacy/Disclaimer, persisted to localStorage with a version for re-prompting; skipped on desktop.
  • Windows installer license-acceptance page via Tauri bundle.licenseFile (src-tauri/license.rtf), covering both NSIS .exe and WiX .msi.
  • Lazy-load routes + the CodeMirror editor; refined manualChunks (react/router/i18n/cm-core/cm-langs/per-parser/ui); removed the bson initial-graph leak via lib/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.android in tauri.conf.json: minSdkVersion: 31, deterministic versionCode (MAJOR*10000+MINOR*100+PATCH)
  • tauri android init → Android Gradle project at src-tauri/gen/android/, committed (source only; build outputs + secrets gitignored via nested + root .gitignore)
  • Verified minSdk = 31 propagated to app/build.gradle.kts; Rust compiles for all 4 ABIs (validated against NDK r27/r30)
  • Release signing wired in app/build.gradle.kts from a gitignored keystore.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; chains tauri:icon)
  • CI: android job in release.yml builds + 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-dialog fires the SAF picker, plugin-fs reads the content:// 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 .zip via 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.