@hypen-space/web 0.4.980 → 0.5.3

package/dist/variants.js

@@ -0,0 +1,206 @@
+/**
+ * Shared variant (responsive breakpoint + interaction state) support.
+ *
+ * The engine emits applicator props using the canonical key format:
+ *
+ *   <camelBase><variant?><argSuffix>
+ *
+ *   - camelBase:  camelCase applicator name, e.g. "padding", "backgroundColor"
+ *   - variant?:   "@<bp>" and/or ":<state>", in that order if combined.
+ *                   bp    in { sm, md, lg, xl, 2xl }
+ *                   state in { hover, focus, active, disabled,
+ *                              focus-visible, focus-within }
+ *                 combined example: "backgroundColor@md:hover" (BOTH md AND hover)
+ *   - argSuffix:  ".<index>" (almost always ".0") or ".<name>" for named args.
+ *
+ * Examples emitted by the engine:
+ *   "padding.0", "padding@md.0", "backgroundColor:hover.0",
+ *   "backgroundColor@md:hover.0".
+ *
+ * IMPORTANT: the variant marker sits BETWEEN the base name and the ".0" arg
+ * suffix. A lookup that forgets the ".0" (e.g. building just "padding@md")
+ * MISSES the real key. Always parse the variant out of the full key.
+ *
+ * Both the DOM applicator path and the Canvas renderer import this module so
+ * breakpoint pixels, state names, and precedence stay byte-compatible across
+ * renderers. The DOM renderer leans on the CSS engine for actual resolution
+ * (media queries + pseudo-classes), so it only needs PARSE_* here; Canvas does
+ * its own paint/layout and therefore also uses the runtime resolver.
+ */
+/**
+ * Tailwind breakpoint min-widths (px). Order matters: ascending min-width.
+ * Mirrors the DOM `BREAKPOINTS` table and the iOS reference.
+ */
+export const BREAKPOINTS = {
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    "2xl": 1536,
+};
+/** Breakpoint names in ascending min-width order (sm < md < lg < xl < 2xl). */
+export const BREAKPOINT_ORDER = ["sm", "md", "lg", "xl", "2xl"];
+/** Interaction-state names recognised in variant keys (same set as the DOM). */
+export const VALID_STATES = [
+    "hover",
+    "focus",
+    "active",
+    "disabled",
+    "focus-visible",
+    "focus-within",
+];
+const VALID_STATE_SET = new Set(VALID_STATES);
+/**
+ * Parse a prop key into `{ base, breakpoint, state, arg }`.
+ *
+ * Splits the arg suffix first (the LAST `.<token>`), then peels the variant
+ * markers (`@bp` and/or `:state`) off the remainder. An unknown breakpoint or
+ * state is left as part of the base name (caller decides what to do); this
+ * matches the DOM behaviour where an invalid `@invalid` / `:invalid` simply
+ * never matches a real variant.
+ *
+ * Examples:
+ *   "padding.0"                  -> { base:"padding", breakpoint:null, state:null, arg:"0" }
+ *   "padding@md.0"               -> { base:"padding", breakpoint:"md", state:null, arg:"0" }
+ *   "backgroundColor:hover.0"    -> { base:"backgroundColor", breakpoint:null, state:"hover", arg:"0" }
+ *   "backgroundColor@md:hover.0" -> { base:"backgroundColor", breakpoint:"md", state:"hover", arg:"0" }
+ *   "backgroundColor@md:hover"   -> { base:"backgroundColor", breakpoint:"md", state:"hover", arg:null }
+ */
+export function parseVariantKey(key) {
+    let work = key;
+    let arg = null;
+    // Peel the arg suffix: the segment after the LAST dot, but only if that dot
+    // comes AFTER any variant markers (so we never split inside "focus-within"
+    // — that has no dot — and never treat "padding" alone as having an arg).
+    const lastDot = work.lastIndexOf(".");
+    if (lastDot > 0) {
+        arg = work.slice(lastDot + 1);
+        work = work.slice(0, lastDot);
+    }
+    // Peel the state marker (":state") off the end of the remainder.
+    let state = null;
+    const colon = work.indexOf(":");
+    if (colon !== -1) {
+        const candidate = work.slice(colon + 1);
+        if (VALID_STATE_SET.has(candidate)) {
+            state = candidate;
+            work = work.slice(0, colon);
+        }
+    }
+    // Peel the breakpoint marker ("@bp").
+    let breakpoint = null;
+    const at = work.indexOf("@");
+    if (at !== -1) {
+        const candidate = work.slice(at + 1);
+        if (candidate in BREAKPOINTS) {
+            breakpoint = candidate;
+            work = work.slice(0, at);
+        }
+    }
+    return { base: work, breakpoint, state, arg };
+}
+/**
+ * Precedence rank for a parsed variant (higher wins). Combines the breakpoint
+ * tier and the state tier into a single sortable number.
+ *
+ * Precedence (low -> high), later overrides earlier:
+ *   base
+ *     < breakpoints ascending (sm < md < lg < xl < 2xl)
+ *     < disabled < hover < focus < active
+ *
+ * State always outranks any breakpoint (a `:hover` override beats a `@2xl`
+ * sizing override on the same prop), matching the iOS reference where state
+ * overrides are merged AFTER the responsive base. Within the same state tier,
+ * a higher breakpoint still breaks the tie so `@md:hover` beats `:hover`.
+ */
+const STATE_RANK = {
+    disabled: 1,
+    hover: 2,
+    // focus-visible / focus-within are focus-flavoured states: they share the
+    // `focus` precedence slot (NOT base/0) so they outrank hover and lose to
+    // active, matching the engine's `state_rank` in portable/variant.rs.
+    focus: 3,
+    "focus-visible": 3,
+    "focus-within": 3,
+    active: 4,
+};
+// State tier must be weighted by a value strictly greater than the largest
+// possible breakpoint tier so the bp tiebreak can never leak across state
+// bands (mirrors the engine's STATE_STEP > max-breakpoint invariant). Derived
+// from BREAKPOINT_ORDER.length so adding breakpoints can't silently break it.
+const STATE_WEIGHT = BREAKPOINT_ORDER.length + 1;
+function variantRank(breakpoint, state) {
+    const bpTier = breakpoint ? BREAKPOINT_ORDER.indexOf(breakpoint) + 1 : 0; // 0..len
+    const stateTier = state ? STATE_RANK[state] ?? 0 : 0; // 0..4
+    // State tier dominates; breakpoint tier breaks ties within a state tier.
+    return stateTier * STATE_WEIGHT + bpTier;
+}
+/**
+ * Is a parsed variant currently applicable, given the viewport width and the
+ * active interaction states? A combined key requires BOTH conditions.
+ */
+function variantApplies(parsed, width, states) {
+    if (parsed.breakpoint) {
+        const minWidth = BREAKPOINTS[parsed.breakpoint];
+        if (minWidth === undefined || width < minWidth)
+            return false;
+    }
+    if (parsed.state) {
+        if (!states[parsed.state])
+            return false;
+    }
+    return true;
+}
+/**
+ * Resolve variant-bearing props against the current viewport width and active
+ * interaction states, producing a flat map of `base -> winning value`.
+ *
+ * Input keys are the already-normalised flat applicator keys (variant markers
+ * present, arg suffix already stripped by the applicator-grouping pass), e.g.
+ * `{ padding: 8, "padding@md": 16, "backgroundColor:hover": "red" }`.
+ *
+ * Only bases that actually have at least one applicable variant appear in the
+ * result with an overridden value; a base with only its plain entry resolves to
+ * that plain value. The caller merges the result over the node's base props.
+ */
+export function resolveVariantProps(props, width, states) {
+    // base -> { value, rank }
+    const winners = new Map();
+    for (const key of Object.keys(props)) {
+        const parsed = parseVariantKey(key);
+        // Only consider entries that carry a variant marker. Plain keys (no bp/state)
+        // are the base and are handled implicitly via rank 0 below so a base with a
+        // single applicable variant still falls back to base when the variant is off.
+        if (!parsed.breakpoint && !parsed.state) {
+            // Seed the base value at rank 0 so variant lookups have a fallback and so
+            // a base that ALSO has variants resolves correctly when none apply.
+            const existing = winners.get(parsed.base);
+            if (!existing || existing.rank === 0) {
+                winners.set(parsed.base, { value: props[key], rank: 0 });
+            }
+            continue;
+        }
+        if (!variantApplies(parsed, width, states))
+            continue;
+        const rank = variantRank(parsed.breakpoint, parsed.state);
+        const existing = winners.get(parsed.base);
+        if (!existing || rank >= existing.rank) {
+            winners.set(parsed.base, { value: props[key], rank });
+        }
+    }
+    const out = {};
+    for (const [base, win] of winners) {
+        out[base] = win.value;
+    }
+    return out;
+}
+/** True if any key in `props` carries a variant marker (`@bp` or `:state`). */
+export function hasVariantProps(props) {
+    for (const key of Object.keys(props)) {
+        const parsed = parseVariantKey(key);
+        if (parsed.breakpoint || parsed.state)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=variants.js.map

package/dist/variants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.js","sourceRoot":"","sources":["../src/variants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAA2B;IACjD,EAAE,EAAE,GAAG;IACP,EAAE,EAAE,GAAG;IACP,EAAE,EAAE,IAAI;IACR,EAAE,EAAE,IAAI;IACR,KAAK,EAAE,IAAI;CACZ,CAAC;AAEF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;AAEnF,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAsB;IAC7C,OAAO;IACP,OAAO;IACP,QAAQ;IACR,UAAU;IACV,eAAe;IACf,cAAc;CACf,CAAC;AACF,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;AAc9C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,IAAI,GAAG,GAAG,CAAC;IACf,IAAI,GAAG,GAAkB,IAAI,CAAC;IAE9B,4EAA4E;IAC5E,2EAA2E;IAC3E,yEAAyE;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;QAC9B,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,iEAAiE;IACjE,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACxC,IAAI,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,KAAK,GAAG,SAAS,CAAC;YAClB,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,sCAAsC;IACtC,IAAI,UAAU,GAAkB,IAAI,CAAC;IACrC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;QACd,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACrC,IAAI,SAAS,IAAI,WAAW,EAAE,CAAC;YAC7B,UAAU,GAAG,SAAS,CAAC;YACvB,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAChD,CAAC;AAYD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAA2B;IACzC,QAAQ,EAAE,CAAC;IACX,KAAK,EAAE,CAAC;IACR,0EAA0E;IAC1E,yEAAyE;IACzE,qEAAqE;IACrE,KAAK,EAAE,CAAC;IACR,eAAe,EAAE,CAAC;IAClB,cAAc,EAAE,CAAC;IACjB,MAAM,EAAE,CAAC;CACV,CAAC;AAEF,2EAA2E;AAC3E,0EAA0E;AAC1E,8EAA8E;AAC9E,8EAA8E;AAC9E,MAAM,YAAY,GAAG,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC;AAEjD,SAAS,WAAW,CAAC,UAAyB,EAAE,KAAoB;IAClE,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;IACnF,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO;IAC7D,yEAAyE;IACzE,OAAO,SAAS,GAAG,YAAY,GAAG,MAAM,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc,CACrB,MAAwB,EACxB,KAAa,EACb,MAAoB;IAEpB,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,KAAK,GAAG,QAAQ;YAAE,OAAO,KAAK,CAAC;IAC/D,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAA2B,CAAC;YAAE,OAAO,KAAK,CAAC;IAChE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA8B,EAC9B,KAAa,EACb,MAAoB;IAEpB,0BAA0B;IAC1B,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4C,CAAC;IAEpE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QACpC,8EAA8E;QAC9E,4EAA4E;QAC5E,8EAA8E;QAC9E,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACxC,0EAA0E;YAC1E,oEAAoE;YACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACrC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;YAC3D,CAAC;YACD,SAAS;QACX,CAAC;QAED,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;YAAE,SAAS;QAErD,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,IAAI,IAAI,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YACvC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC;QAClC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;IACxB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,KAA8B;IAC5D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;IACrD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypen-space/web",
-  "version": "0.4.980",
+  "version": "0.5.3",
   "description": "Hypen web renderers - DOM and Canvas rendering for browsers",
   "type": "module",
   "main": "./dist/index.js",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@chenglou/pretext": "^0.0.3",
-    "@hypen-space/core": "^0.4.980",
+    "@hypen-space/core": "^0.5.3",
     "taffy-layout": "^2.0.3"
   },
   "devDependencies": {

package/src/canvas/QUICKSTART.md

@@ -30,7 +30,7 @@ bun add @hypen-space/core @hypen-space/web @hypen-space/web-engine
 ```typescript
 import { app, HypenModuleInstance } from "@hypen-space/core";
 import { Engine } from "@hypen-space/web-engine";
-import { createHypenClient } from "@hypen-space/web/canvas";
+import { CanvasRenderer } from "@hypen-space/web/canvas";
 
 // Define state
 type AppState = {
@@ -54,12 +54,17 @@ async function main() {
   const engine = new Engine();
   await engine.init();
 
-  // Create renderer + patch subscription in one call
-  createHypenClient(canvas, engine, {
+  // Create renderer
+  const renderer = new CanvasRenderer(canvas, engine, {
     devicePixelRatio: window.devicePixelRatio,
     backgroundColor: "#ffffff",
   });
 
+  // Connect renderer
+  engine.setRenderCallback((patches) => {
+    renderer.applyPatches(patches);
+  });
+
   // Create module
   const instance = new HypenModuleInstance(engine, appModule);
 
@@ -244,15 +249,14 @@ Container {
 ## Configuration Options
 
 ```typescript
-const { renderer } = createHypenClient(canvas, engine, {
+const renderer = new CanvasRenderer(canvas, engine, {
   // Display
   devicePixelRatio: window.devicePixelRatio,  // HiDPI support
   backgroundColor: "#ffffff",                  // Canvas background
   
   // Features
-  enableAccessibility: true,      // Screen reader support
+  enableAccessibility: true,      // Screen readers + Tab focus + text editing
   enableHitTesting: true,         // Mouse events
-  enableInputOverlay: true,       // Text input support
   
   // Debug
   showLayoutBounds: false,        // Show red boxes around elements
@@ -349,7 +353,7 @@ let timeoutId: number;
 ### 3. Measure Performance
 
 ```typescript
-const { renderer } = createHypenClient(canvas, engine, {
+const renderer = new CanvasRenderer(canvas, engine, {
   logPerformance: true,  // Logs FPS and frame times
 });
 ```
@@ -361,18 +365,19 @@ const { renderer } = createHypenClient(canvas, engine, {
 Make sure to set `devicePixelRatio`:
 
 ```typescript
-const { renderer } = createHypenClient(canvas, engine, {
+const renderer = new CanvasRenderer(canvas, engine, {
   devicePixelRatio: window.devicePixelRatio,
 });
 ```
 
 ### Text Input Not Working
 
-Ensure `enableInputOverlay` is true:
+Text editing runs through the accessibility mirror (canvas fallback
+content), so `enableAccessibility` must be true (the default):
 
 ```typescript
-const { renderer } = createHypenClient(canvas, engine, {
-  enableInputOverlay: true,
+const renderer = new CanvasRenderer(canvas, engine, {
+  enableAccessibility: true,
 });
 ```
 

package/src/canvas/README.md

@@ -13,12 +13,10 @@ The Canvas Renderer is a complete alternative to the DOM renderer that draws all
 
 ## Quick Start
 
-`createHypenClient` is the recommended one-call wiring (constructs the renderer and subscribes to engine patches). `CanvasRenderer` is still exported directly for advanced setups.
-
 ```typescript
 import { app } from "@hypen-space/core";
 import { Engine } from "@hypen-space/web-engine";
-import { createHypenClient } from "@hypen-space/web/canvas";
+import { CanvasRenderer } from "@hypen-space/web/canvas";
 
 // Setup canvas
 const canvas = document.getElementById("app") as HTMLCanvasElement;
@@ -27,8 +25,13 @@ const canvas = document.getElementById("app") as HTMLCanvasElement;
 const engine = new Engine();
 await engine.init();
 
-// Create canvas renderer + patch subscription in one call
-createHypenClient(canvas, engine);
+// Create canvas renderer
+const renderer = new CanvasRenderer(canvas, engine);
+
+// Set render callback
+engine.setRenderCallback((patches) => {
+  renderer.applyPatches(patches);
+});
 
 // Render UI
 await engine.renderSource(`
@@ -141,35 +144,61 @@ Handles text measurement and rendering:
 - **Text Alignment**: left, center, right, top, middle, bottom
 - **Caching**: Text metrics are cached for performance
 
-### 5. Input Overlay (`input.ts`)
-
-Since canvas can't handle text input natively, we use DOM overlays:
-
-**Strategy:**
-1. When canvas input is focused, create a real `<input>` element
-2. Position it exactly over the canvas input (invisible to user)
-3. Style it to match the canvas input appearance
-4. Capture input and update state
-5. Remove overlay when focus is lost
-
-**Supports:**
-- Single-line text input
-- Multi-line textarea
-- Number input
-- Custom styling
-
-### 6. Accessibility (`accessibility.ts`)
-
-Maintains a shadow DOM tree for screen readers:
+### 5. Native Text Editing (`editing.ts`)
+
+Text, caret, and selection inside `Input`/`Textarea` are painted **on the
+canvas** — there is no visible DOM overlay. The browser does the actual
+editing (typing, caret movement, word-jumps, select-all, clipboard, undo,
+IME composition) in a single hidden **proxy textarea** positioned at the
+caret (the Monaco/xterm.js approach); the `TextEditController` reads
+`value`/`selectionStart`/`selectionEnd` after each event and the canvas
+paints the result. Focus and accessibility stay on the node's mirror
+element (below) — browsers won't run text editing on unrendered fallback
+content, which is why the keystroke stream needs the proxy. Positioning the
+proxy at the caret also puts the IME candidate window next to the painted
+text.
+
+**Editing visuals (painted in `paint.ts#paintInput`):**
+- Selection highlight and blinking caret via shared `text-geometry.ts` math
+- IME composition range underlined (dashed)
+- Single-line inputs pan horizontally (`scrollX`) to keep the caret visible
+- Click/drag on the canvas maps point → character offset → `setSelectionRange`
+
+Two-way binding dispatches `__hypen_bind {path, value}` on input (suppressed
+during IME composition; flushed at `compositionend`).
+
+### 6. Accessibility & Focus (`accessibility.ts`, `focus.ts`)
+
+A live DOM mirror of the virtual tree is rendered as a **transparent
+positioned overlay** above the canvas (the Flutter-web approach), with every
+element absolutely positioned at its painted bounds and `pointer-events:
+none` so the canvas keeps all pointer interaction.
+
+Canvas *fallback content* was evaluated first and rejected on evidence:
+Chromium exposes fallback elements to the accessibility tree (names, roles,
+focus, Tab order all work) but gives them **zero geometry** — and screen
+reader browse modes (VoiceOver cursor, rotor, touch exploration) are
+geometry-driven, so they skip boundless elements entirely.
 
 **Strategy:**
-1. Create hidden DOM tree that mirrors canvas structure
-2. Use semantic HTML (button, input, etc.)
-3. Update shadow DOM when patches are applied
-4. Support keyboard navigation
-5. ARIA labels and roles
-
-This makes the canvas renderer fully accessible without impacting visual rendering.
+1. Mirror elements use semantic HTML (button, input, h1-h6, ...) driven by
+   the engine-derived `Semantics` block, invisibly rendered (transparent
+   text/background; placeholders and selection suppressed via a shared
+   stylesheet) so AT gets real boxes and native focus rings land exactly
+   over the painted controls
+2. The mirror is synced **incrementally** from the patch stream
+   (create/insert/move/remove/detach/attach) — element identity survives
+   re-renders and router navigation, so AT focus/virtual-cursor position
+   is never destroyed by an update; element positions are refreshed after
+   every canvas render
+3. Real DOM focus on mirror elements is the **single source of truth** for
+   focus: Tab/Shift+Tab work natively, `focusin`/`focusout` drive
+   `node.focused` and the painted focus ring, and the canvas hit-test path
+   funnels into the same place by focusing the node's mirror element
+4. Enter/Space on a mirror `<button>` (or AT activation) dispatches the
+   node's action — identical payload to a canvas click
+5. The `<canvas>` itself is `aria-hidden` — the overlay carries all
+   semantics
 
 ## Supported Components
 
@@ -200,9 +229,9 @@ const renderer = new CanvasRenderer(canvas, engine, {
   backgroundColor: "#ffffff",                  // Canvas background
   
   // Features
-  enableAccessibility: true,      // Shadow DOM for screen readers
+  enableAccessibility: true,      // Fallback-content mirror: screen readers,
+                                  // Tab focus, and text-input editing
   enableHitTesting: true,         // Mouse event handling
-  enableInputOverlay: true,       // DOM overlays for text input
   
   // Performance (future)
   enableDirtyRects: false,        // Only redraw changed regions