Skip to content

ROADMAP.md

Latest commit

 

History

History
287 lines (191 loc) · 17.6 KB

ROADMAP.md

File metadata and controls

287 lines (191 loc) · 17.6 KB

Geometra roadmap

Phased plan to grow Geometra from a capable layout-on-geometry stack into a broadly credible UI framework (Yoga + Pretext via Textura).

Routing competitiveness work is tracked in ROUTING_COMPETITIVENESS_CHECKLIST.md.

Phase A — Foundation (shipping now)

  • Web font readiness before first paint (waitForFonts + tree collection).
  • Keyboard focus that repaints when focus changes; click-to-focus for focusable boxes.
  • Canvas debug overlay for layout bounds; optional focus ring styling.
  • Harden tests around hit dispatch and font family parsing.

Phase B — Apps that feel “real”

  • Text input: caret, IME/composition, selection, undo baseline; align Pretext metrics with canvas paint.
  • Font policy: document generic families, variable fonts, and server/client metric parity.
  • Runtime accessibility: hidden DOM mirror or accessibility tree API + docs for canvas mode.
  • Protocol: versioned WS frames; compatibility notes.

Phase C — Platform & ecosystem

  • Virtualized lists / large scroll regions; focus trap for overlays.
  • Dev overlay (layout time, node count, hit targets).
  • Visual/regression and geometry snapshot testing in CI.
  • Optional component layer (@geometra/ui) built only on core primitives.

Deferred / research

  • Full RTL/document direction pass through Textura props — logical-axis layout props (marginInlineStart/End, paddingInlineStart/End, borderInlineStart/End, insetInlineStart/End, block-axis equivalents) via Yoga Edge.Start/Edge.End.
  • Animation primitives beyond current animation.ts helpers (choreography, gestures, keyframe scrubbing).
  • Non-canvas render targets (WebGPU, PDF) consuming the same geometry — WebGPU text rendering via canvas atlas; @geometra/renderer-pdf raw PDF 1.4 generation.

Post-1.0 execution plan (1.x)

This plan prioritizes adoption-critical capabilities while preserving the core invariant: Tree -> Yoga WASM -> Geometry -> Pixels.

Tracking fields:

  • Status: todo | in_progress | blocked | done
  • Owner: @unassigned by default

1.1.0 — RTL and bidi baseline

Goal: make mixed-direction text and interaction credible for production apps.

Acceptance criteria:

  • Status: done | Owner: @codex | Direction model is explicit: root and per-node dir (ltr/rtl/auto) semantics are documented and enforced consistently.
  • Status: done | Owner: @codex | Caret movement semantics are correct for bidi text (left/right visual movement, home/end behavior, word jumps) with integration tests.
  • Status: done | Owner: @codex | Selection range mapping and paint are stable for mixed LTR/RTL runs in canvas and terminal renderers. (terminal selection UI is intentionally out of scope for baseline; documented limits apply)
  • Status: done | Owner: @codex | Text measurement and geometry mapping stay parity-safe across local canvas and server/client paths. (covered and tracked in RTL_PARITY_MATRIX.md)
  • Status: done | Owner: @codex | Known limitations (complex scripts edge cases, terminal constraints) are explicitly documented.

Definition of done:

  • Core/canvas/terminal test suites pass with new bidi/RTL coverage.
  • Release notes include interaction semantics changes and migration notes.
  • No measurable regressions in existing text input and hit-test perf baselines.

1.2.0 — Animation model v2 (geometry-native)

Goal: ship deterministic, declarative animations that stay renderer-agnostic.

Acceptance criteria:

  • Status: done | Owner: @codex | Add a declarative animation API for geometry-driven transitions (position/size) and paint properties (opacity/color).
  • Status: done | Owner: @codex | Add interrupt/cancel/resume semantics that are deterministic across rapid state updates.
  • Status: done | Owner: @codex | Add reduced-motion policy and explicit defaults for accessibility-sensitive behavior.
  • Status: done | Owner: @codex | Add deterministic frame-step test harness for unit/integration assertions (no timing flake).
  • Status: done | Owner: @codex | Provide representative demo scenarios (list reorder, dialog enter/exit, focus transition polish).

Definition of done:

  • Animation behavior is consistent across canvas and terminal where applicable.
  • New tests are stable in CI and validated under bursty update conditions.
  • Docs define supported properties, timing functions, and interruption rules.

1.3.0 — Additional render target proof

Goal: prove one extra backend can consume shared geometry without divergence.

Acceptance criteria:

  • Status: done | Owner: @codex | Select and document target (WebGPU or PDF) with rationale and non-goals.
  • Status: done | Owner: @codex | Implement MVP renderer path that consumes existing geometry output (no protocol fork).
  • Status: done | Owner: @codex | Add renderer-agnostic fixture reuse to assert semantic/layout parity with existing backends.
  • Status: done | Owner: @codex | Document feature support matrix and fallback behavior.

Definition of done:

  • New backend passes fixture suite for agreed MVP surface.
  • CI includes backend smoke check.
  • API/export docs reflect support status and constraints.

1.4.0 — Transport efficiency and scale hardening

Goal: improve high-frequency server/client behavior under realistic load.

Acceptance criteria:

  • Status: done | Owner: @codex | Add optional binary frame encoding path behind explicit protocol version/capability negotiation. (GEOM v1 JSON envelope; resize.capabilities.binaryFraming)
  • Status: done | Owner: @codex | Add backpressure-aware batching/coalescing policy with bounded memory behavior. (bufferedAmount deferral, full-frame resync, coalescePatches for duplicate paths)
  • Status: done | Owner: @codex | Expose frame budget instrumentation (encode/decode/apply timings, coalesced patch delta, binary/deferred counts). (onFrameMetrics client; onTransportMetrics server; optional dropped counters deferred)
  • Status: done | Owner: @codex | Add large-app stress scenarios (rapid input + layout churn + reconnect) with deterministic pass criteria. (server-rapid-update-integration, server-transport-stress, client-reconnect)

Definition of done:

  • Conformance fixtures cover text and binary paths. (protocol-binary-conformance, binary-frame tests)
  • Latency/throughput results are documented against baseline scenarios. (TRANSPORT_1_4.md CI baseline table + protocol-perf-smoke thresholds)
  • Reconnect/resync correctness remains stable under chaos tests. (integration + mock reconnect suites)

1.5.0 — UI primitives and developer tooling

Goal: reduce adoption friction with high-quality primitives and better introspection.

Status: done (see packages/ui/README.md, INTEGRATION_COOKBOOK.md, demos/local-canvas).

Acceptance criteria:

  • Status: done | Owner: @codex | Expand @geometra/ui with advanced primitives (see packages/ui/README.md; remaining niche widgets can follow in minors).
  • Status: done | Owner: @codex | Add behavior contracts + interaction/a11y fixtures for each new primitive. (primitives.test.ts)
  • Status: done | Owner: @codex | Extend dev overlay into inspector view (HUD: frame, nodes, depth, root, focus + Tab ordinal, optional hitPathAtPoint via inspectorProbe).
  • Status: done | Owner: @codex | Publish integration cookbooks for common app stacks and DOM-assumption migration patterns. (INTEGRATION_COOKBOOK.md)

Definition of done:

  • @geometra/ui primitives are tested, documented, and versioned with clear stability labels. (packages/ui/README.md)
  • Inspector tooling is usable in demos with negligible hot-path overhead when disabled.
  • Starter templates demonstrate at least two advanced primitives and inspector workflow. (demos/local-canvas — toast, dataTable, layoutInspector + inspectorProbe)

1.6.0 — Fonts, metrics, and adoption depth

Goal: close Phase B font/metrics documentation gaps and deepen ecosystem guidance without changing the core pipeline contract.

Status: done

Acceptance criteria:

  • Status: done | Owner: @codex | Document generic families, waitForFonts, variable-font caveats, and server/client metric parity expectations. (FONTS_AND_METRICS.md)
  • Status: done | Owner: @codex | Expand visual-regression coverage for font-sensitive paint (visual-regression.test.ts — per-node ctx.font audit).
  • Status: done | Owner: @codex | Formalize post-v1 protocol evolution guidance. (PROTOCOL_EVOLUTION.md)

Definition of done:

  • README or north-star docs link the font/metrics policy from developer entry points. (CLAUDE.md)
  • Release notes call out font/measurement and protocol guidance. (RELEASE_NOTES_1_6.md)

1.7.0 — Developer observability and geometry CI

Goal: make frame-level debugging and layout-level regression testing easier without expanding the core pipeline surface.

Status: done

Acceptance criteria:

  • Status: done | Owner: @codex | Expose per-frame canvas render wall time in the layout inspector HUD and as CanvasRenderer.lastRenderWallMs for external telemetry.
  • Status: done | Owner: @codex | Document geometry snapshot / layout JSON testing patterns for CI. (GEOMETRY_SNAPSHOT_TESTING.md)

Definition of done:

  • Inspector remains zero overhead when layoutInspector is disabled.
  • Developer entry docs link geometry snapshot guidance. (CLAUDE.md, INTEGRATION_COOKBOOK.md)

1.8.0 — Layout vs paint observability and geometry CI

Goal: split Yoga/layout wall time from canvas paint in the inspector, and lock a minimal geometry snapshot into the release gate.

Status: done

Acceptance criteria:

  • Status: done | Owner: @codex | Optional Renderer.setFrameTimings({ layoutMs }) called from createApp after computeLayout; CanvasRenderer stores lastLayoutWallMs and shows layout ms in the inspector HUD.
  • Status: done | Owner: @codex | Dedicated geometry snapshot test + npm run test:geometry; wired into release:gate. (geometry-snapshot-ci.test.ts, __snapshots__/)

Definition of done:

  • Backends without setFrameTimings unchanged (method optional on Renderer).
  • Docs updated (GEOMETRY_SNAPSHOT_TESTING.md, canvas README, RELEASE_NOTES_1_8.md).

Release polish checklist

Tracking fields:

  • Status: todo | in_progress | blocked | done
  • Owner: @unassigned by default

0.3.2 — Text input and IME quality

  • Status: done | Owner: @codex | Add a dedicated text-input demo covering caret, selection, insert/delete, and undo/redo.
  • Status: done | Owner: @codex | Add integration tests for composition lifecycle (start/update/end) and mixed key/composition flows.
  • Status: done | Owner: @codex | Validate caret geometry across multiline and edge positions.
  • Status: done | Owner: @codex | Verify selection replacement plus backspace/delete boundary behavior.
  • Status: done | Owner: @codex | Add regression tests for focus switching during active composition.
  • Status: done | Owner: @codex | Document text-input semantics in README/API docs.

0.3.3 — Keyboard/focus contract and a11y

  • Status: done | Owner: @codex | Write a concise interaction spec (Tab/Shift+Tab, Enter/Escape, arrow behavior, focus order rules).
  • Status: done | Owner: @codex | Align core + terminal/canvas behavior with the interaction spec.
  • Status: done | Owner: @codex | Add end-to-end focus traversal tests for multiple focusable regions.
  • Status: done | Owner: @codex | Expand accessibility tree coverage for common patterns (headings, nav, lists, buttons, forms).
  • Status: done | Owner: @codex | Add semantic output snapshots for representative UI trees.
  • Status: done | Owner: @codex | Document accessibility guarantees and known limitations.

0.3.4 — Protocol and reliability hardening

  • Status: done | Owner: @codex | Add protocol version fixtures and compatibility tests (including mismatch handling).
  • Status: done | Owner: @codex | Add tests for geometry diff correctness under rapid update bursts.
  • Status: done | Owner: @codex | Validate error surfacing and recovery behavior in server/client flows.
  • Status: done | Owner: @codex | Add reconnect/retry integration scenario with state resync.
  • Status: done | Owner: @codex | Ensure protocol changes are explicit and backward-safe.

0.3.5 — Performance guardrails

  • Status: done | Owner: @codex | Add microbenchmarks for hit-testing, text measurement, and geometry diffing.
  • Status: done | Owner: @codex | Establish baseline metrics and acceptable regression thresholds.
  • Status: done | Owner: @codex | Wire benchmark/performance checks into CI reporting.
  • Status: done | Owner: @codex | Add smoke perf test for large tree updates (worst-case UI churn).
  • Status: done | Owner: @codex | Track perf notes in release checklist before each tag.

Docs and developer experience (parallel track)

  • Status: done | Owner: @codex | Keep README/API exports aligned with shipped behavior every release.
  • Status: done | Owner: @codex | Add a testing matrix doc (unit vs integration vs renderer-specific).
  • Status: done | Owner: @codex | Provide copy-paste examples for terminal input/focus wiring.
  • Status: done | Owner: @codex | Add release playbook checklist (version bump, tests, notes, verification).
  • Status: done | Owner: @codex | Add known caveats section for environment-specific behavior.

Release readiness gate (every release)

  • Status: done | Owner: @codex | Core unit tests pass.
  • Status: done | Owner: @codex | Terminal integration suite passes.
  • Status: done | Owner: @codex | Renderer-specific smoke checks pass.
  • Status: done | Owner: @codex | Lint/build pass in CI.
  • Status: done | Owner: @codex | Changelog/release notes include behavior changes plus migration notes.
  • Status: done | Owner: @codex | npm published versions verified after release workflow completes.

Next frontier checklist (toward 1.0 quality)

Tracking fields:

  • Status: todo | in_progress | blocked | done
  • Owner: @unassigned by default

0.4.0 — Input parity and editing completeness

  • Status: done | Owner: @codex | Add vertical caret movement (ArrowUp/ArrowDown) for multi-line text input with stable column intent.
  • Status: done | Owner: @codex | Add word-jump and line-boundary movement semantics (Alt+Arrow, Home, End) with tests.
  • Status: done | Owner: @codex | Implement pointer-driven text selection drag in canvas and align with text-input helpers.
  • Status: done | Owner: @codex | Add copy/cut/paste integration tests for selection + edit history behavior.
  • Status: done | Owner: @codex | Add IME stress scenarios (focus changes, rapid composition updates, cancellation) across canvas + terminal where applicable.

0.4.1 — Scrolling, virtualization, and large-app ergonomics

  • Status: done | Owner: @codex | Add scroll-container keyboard behavior contract (focus retention, key routing, wheel/scroll sync).
  • Status: done | Owner: @codex | Implement virtualized list primitive example with stable focus and selection behavior.
  • Status: done | Owner: @codex | Add integration tests for large scroll regions with rapid update bursts.
  • Status: done | Owner: @codex | Add dev overlay panel with node count, layout time, and repaint hot spots.

0.4.2 — Accessibility and semantics depth

  • Status: done | Owner: @codex | Expand a11y tree attributes (state/disabled/expanded/selected) and test mappings.
  • Status: done | Owner: @codex | Add focus trap primitives and tests for modal/overlay flows.
  • Status: done | Owner: @codex | Add form-like semantics examples (labels, input groups, error text relationships).
  • Status: done | Owner: @codex | Add regression snapshots for accessibility tree shape across representative app templates.

0.4.3 — Protocol v2 planning and transport resilience

  • Status: done | Owner: @codex | Draft protocol-v2 RFC with backward-compat strategy and migration policy.
  • Status: done | Owner: @codex | Add message batching/coalescing tests for high-frequency input and layout churn.
  • Status: done | Owner: @codex | Add chaos-style reconnect tests (out-of-order frames, delayed patches, duplicate messages).
  • Status: done | Owner: @codex | Add protocol conformance fixtures runnable by both client and server packages.

0.4.4 — Visual quality and renderer confidence

  • Status: done | Owner: @codex | Add canvas visual regression snapshots for text selection, focus ring, gradients, and clipping.
  • Status: done | Owner: @codex | Add terminal renderer golden-output fixtures for z-index, clipping, and overflow behavior.
  • Status: done | Owner: @codex | Add renderer-agnostic fixture suite to assert geometry-in -> expected semantic/layout-out.

0.4.5 — Ecosystem readiness and adoption

  • Status: done | Owner: @codex | Publish @geometra/ui starter primitives (button/input/list/dialog) built only on core exports.
  • Status: done | Owner: @codex | Add end-to-end starter templates (canvas local app, terminal app, server/client app).
  • Status: done | Owner: @codex | Produce migration guide for teams moving from DOM-centric event/layout assumptions.
  • Status: done | Owner: @codex | Define 1.0 release criteria and freeze policy for protocol + interaction contract.
⚡