diff --git a/docs/BEARING.md b/docs/BEARING.md index 664d68d1..0fe22f00 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -4,6 +4,14 @@ Current direction and active tensions. Historical ship data is in `CHANGELOG.md` ## Recent Ships +- `LX-018` — localization catalog data is now honest: generated non-English + DOGFOOD catalogs do not embed copied English fallback strings, English + fallback catalogs load separately at runtime, and non-production builds can + expose loud missing-localization markers. +- `DX-031` / `DX-034` — Blocks now have public metadata, schema, data-binding, + command-intent, lifecycle, active-binding, first-party definition, DOGFOOD + documentation, and fixture-demo proof. The visible product layer is still + emerging; the architecture is ahead of the rendered catalog. - `4.4.1` — framed-shell polish and background-fill recovery after `4.4.0`. - `4.2.0` — [RE-007](./design/RE-007-migrate-framed-shell-onto-runtime-engine-seams.md) lands the framed shell on the runtime-engine seams and ships @@ -16,24 +24,71 @@ Current direction and active tensions. Historical ship data is in `CHANGELOG.md` ## Active Gravity -### 1. Product Surface Depth -- Formalization of the layout and viewport engine. -- Deepening DOGFOOD story quality and variant polish. +### 1. Visible DOGFOOD Product Truth +- DOGFOOD now exposes two partially visible product surfaces at once: Blocks and + localization. +- The next work should improve what users can see in DOGFOOD before adding + another abstract layer. +- The localization pipeline is honest; the bottleneck is visible catalog + coverage. -### 2. Machine-Readable Interactivity -- Interactive component documentation for the MCP rendering server. -- Refinement of the AI tool boundary for Bijou-authored apps. +### 2. Blocks Crossing From Contracts To Product +- Blocks have a strong data-flow and composition spine. +- `AppShell`, `ReaderSurface`, `InspectorPanel`, and the fixture + `CounterDemoBlock` prove the path, but the rendered standard catalog is not + finished. +- New Block work should consume the existing contracts, not invent provider, + lifecycle, callback, or localization policy while rendering. -### 3. Data Visualization Maturity -- Expansion of the sparkline/brailleChart/stats toolkit. -- Implementation of deeper, interactive chart types. +### 3. Localization Coverage Before Preference Polish +- English fallback is separate from selected-locale catalogs. +- Missing selected-locale strings are now real missing data, not disguised + English. +- The next value comes from moving visible DOGFOOD strings into the source + string table and regenerating honest locale catalogs. ## Tensions -- **Notification Hit-Testing**: Toast hit-testing remains outside the retained layout system, creating a mismatch between global overlays and local pane viewports. -- **Ambiguous Graphemes**: RE-016 (ambiguous-width emoji icons) lacks a universal fix; width remains dependent on the terminal's rendering context. -- **Frame Timing**: Integration of high-fidelity frame timing with the performance overlay for fine-grained bottleneck detection. +- **Visible English Debt**: DOGFOOD still has too many hard-coded English strings + in navigation, settings, Blocks docs, preview chrome, common actions, and + status labels. +- **Product Proof Lag**: Blocks have better contracts than visible rendered + proof. AppShell rendering must consume existing data-flow contracts instead of + creating a parallel prop/callback path. +- **Persistence Timing**: Locale preference persistence matters, but it is less + valuable until enough of DOGFOOD visibly responds to locale changes. +- **Measurement Temptation**: A localization dashboard would be useful, but + coverage must improve before a dashboard becomes the next highest-value move. ## Next Target -The immediate focus is the **layout and viewport formalization** to ensure split panes and scroll regions share a unified interaction model. +The immediate focus is +[LX-014 — Expand DOGFOOD Catalog Coverage](./method/backlog/asap/LX-014-expand-dogfood-catalog-coverage.md). + +LX-014 should stay product-facing and narrow: + +- move visible DOGFOOD strings into the source string table +- cover top navigation, settings/menu labels, Blocks docs, Blocks preview + chrome, Counter demo labels, i18n docs, common actions, and common + loading/empty/error/status labels +- regenerate locale catalogs without copying English fallback data into + non-English payloads +- ratchet hard-coded localization debt down +- preserve the existing runtime fallback policy + +Non-goals for the next cycle: + +- no locale preference persistence +- no localization dashboard +- no translation workbench +- no portable preference system +- no new Blocks architecture +- no rendered AppShell work +- no broad standard Block catalog expansion + +Expected sequence: + +1. `LX-014` expands visible DOGFOOD catalog coverage. +2. `LX-013` persists selected locale through a port/adapter. +3. Blocks product proof resumes with less visible localization debt underneath + the showcase. diff --git a/docs/VISION.md b/docs/VISION.md index bf781c11..ddc6a6f1 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -17,6 +17,10 @@ mindmap Accessible Localizable Resilient Viewports + Product Surfaces + Blocks + Localization + DOGFOOD Proof Empirical Documentation DOGFOOD Living Field Guide @@ -38,10 +42,20 @@ A rendering foundation built on typed arrays and zero-allocation hot paths. The ### 3. Humane Interaction A shell model that remains truthful under the pressures of keyboard, mouse, compact viewports, and localization. Accessibility and internationalization are substrate properties, not afterthoughts. -### 4. Empirical Documentation -DOGFOOD is the canonical proving ground. Every component and pattern is verified in a living product surface within the repository. +### 4. Product Surfaces +Bijou's architecture becomes credible only when it survives visible product +surfaces. Blocks and localization are the current pressure points: Blocks must +move from contracts into real reusable product assemblies, and localization must +make DOGFOOD visibly usable without hiding missing translations behind copied +English fallback data. -### 5. Agent-First Legibility +### 5. Empirical Documentation +DOGFOOD is the canonical proving ground. Every component, Block, localization +flow, and pattern is verified in a living product surface within the repository. +Documentation should not merely describe the system; it should expose the system +working under real product pressure. + +### 6. Agent-First Legibility The system is designed to be codable and inspectable by both humans and AI. MCP rendering services and interactive documentation provide a machine-readable interface to the toolkit. ---