@hypen-space/web 0.4.980 → 0.5.3

package/README.md

@@ -127,21 +127,24 @@ await hypen.unmount();
 
 ## DOM Renderer (Low-Level)
 
-For custom integrations, use the `createHypenClient` helper to wire a renderer and patch subscription in one call. The bare `DOMRenderer` constructor is still exported for advanced cases.
+For custom integrations:
 
 ```typescript
 import { app } from "@hypen-space/core";
 import { Engine } from "@hypen-space/web-engine";
-import { createHypenClient } from "@hypen-space/web/dom";
+import { DOMRenderer } from "@hypen-space/web";
 
 const engine = new Engine();
 await engine.init({ wasmUrl: "/hypen_engine_bg.wasm" });
 
-const { renderer } = createHypenClient(
-  document.getElementById("app")!,
-  engine,
-  { debug: { enabled: true, showHeatmap: true } },
-);
+const renderer = new DOMRenderer(document.getElementById("app")!, engine, {
+  enabled: true,
+  showHeatmap: true,
+});
+
+engine.setRenderCallback((patches) => {
+  renderer.applyPatches(patches);
+});
 
 engine.renderSource(`Column { Text("Hello!") }`);
 ```
@@ -237,17 +240,21 @@ Text("Hello")
 
 ## Canvas Renderer
 
-Hardware-accelerated rendering. `createHypenClient` is the recommended one-call wiring; `CanvasRenderer` remains exported for advanced use.
+Hardware-accelerated rendering:
 
 ```typescript
-import { createHypenClient } from "@hypen-space/web/canvas";
+import { CanvasRenderer } from "@hypen-space/web";
 
 const canvas = document.querySelector("canvas")!;
-const { renderer } = createHypenClient(canvas, engine, {
+const renderer = new CanvasRenderer(canvas, engine, {
   devicePixelRatio: window.devicePixelRatio,
   enableAccessibility: true,
   enableHitTesting: true,
 });
+
+engine.setRenderCallback((patches) => {
+  renderer.applyPatches(patches);
+});
 ```
 
 ## Remote UI
@@ -256,15 +263,15 @@ Connect to a server-driven UI:
 
 ```typescript
 import { RemoteEngine } from "@hypen-space/core";
-import { createHypenClient } from "@hypen-space/web/dom";
+import { DOMRenderer } from "@hypen-space/web";
 
+const renderer = new DOMRenderer(document.getElementById("app")!, engine);
 const remote = new RemoteEngine("ws://localhost:3000", {
   autoReconnect: true,
 });
 
-const { renderer } = createHypenClient(document.getElementById("app")!, remote);
-
 remote
+  .onPatches((patches) => renderer.applyPatches(patches))
   .onStateUpdate((state) => renderer.updateState(state))
   .onConnect(() => console.log("Connected"));
 

package/dist/canvas/accessibility.d.ts

@@ -3,27 +3,130 @@
  *
  * Maintain shadow DOM for screen readers
  */
+import type { Semantics } from "@hypen-space/core/types";
 import type { VirtualNode } from "./types.js";
 /**
- * Accessibility Manager
+ * Apply engine-derived accessibility semantics to a shadow-tree element.
+ *
+ * Unlike the DOM renderer, the canvas paints pixels — the accessible name is
+ * *not* otherwise exposed — so the derived name is applied directly as
+ * `aria-label` (whether derived or explicit). Roles are set only on generic
+ * hosts that don't convey them natively. `hidden` is handled by the caller
+ * (the node is omitted from the shadow tree entirely).
+ *
+ * Called at shadow-node create and again on every reactive `setSemantics`
+ * re-apply. Idempotent and clearing: attributes set on a previous pass that
+ * the new block no longer produces are removed.
+ */
+export declare function applyShadowSemantics(element: HTMLElement, semantics?: Semantics): void;
+/**
+ * Accessibility Mirror — positioned transparent semantics overlay
+ *
+ * A live DOM mirror of the virtual tree, rendered INVISIBLY over the canvas
+ * with every element absolutely positioned at its painted bounds (the
+ * Flutter-web / Google-Docs approach). Canvas *fallback content* was tried
+ * first and rejected on evidence: Chromium exposes fallback elements to the
+ * accessibility tree (names, roles, focus 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. A
+ * rendered-but-transparent overlay gets real boxes, which makes browse mode
+ * work and puts native focus rings exactly over the painted controls.
+ *
+ * Real DOM focus on mirror elements is the single source of truth for
+ * `node.focused`; the overlay is `pointer-events: none` throughout so the
+ * canvas keeps all pointer interaction.
+ *
+ * The mirror is synced **incrementally** from the same patch stream that
+ * drives the canvas (`create/insert/move/remove/detach/attach/...`), so
+ * mirror elements keep their identity across re-renders — a screen reader's
+ * virtual cursor or a keyboard user's focus survives reactive updates
+ * instead of being destroyed by a rebuild. Element positions are refreshed
+ * after each canvas render via {@link syncPositions}.
  */
 export declare class AccessibilityLayer {
-    private shadowRoot;
+    private mirrorRoot;
     private nodeMap;
     private enabled;
-    constructor(container: HTMLElement | null, enabled?: boolean);
+    /** Whether the environment can host a mirror at all. */
+    private supported;
+    private canvas;
+    /**
+     * Last box written to each mirror element, so the per-frame position sync
+     * only touches elements whose geometry actually changed — style writes on
+     * n absolutely-positioned elements per frame are what they cost.
+     */
+    private lastSyncedBounds;
+    private lastRootRect;
+    private boundReposition;
+    constructor(canvas: HTMLElement | null, enabled?: boolean);
+    private mount;
+    private unmount;
+    /** Pin the overlay root to the canvas's page rect. */
+    private repositionRoot;
+    /**
+     * Mirror a `create` patch: build the element (detached — a subsequent
+     * `insert` places it). Elements mirror the virtual tree 1:1; visibility
+     * and decorative hiding are expressed with `display:none` (which removes
+     * the subtree from the AT tree) instead of omission, so sibling order
+     * always matches the virtual tree and `beforeId` mapping stays exact.
+     *
+     * The mirror's accessibility metadata (role, name, busy, hidden) comes
+     * from the engine-derived {@link Semantics} block — the single source of
+     * truth shared with every other renderer — not from ad-hoc prop sniffing.
+     * Form *values* (input value/placeholder) still come from props, as those
+     * aren't semantics.
+     */
+    createNode(node: VirtualNode): void;
+    /**
+     * Mirror an `insert` or `attach` patch. Re-inserting an element that is
+     * already in the tree moves it (native `insertBefore` semantics), so
+     * `move` routes here too. An `attach` reinserts the exact element kept
+     * alive by {@link detachNode} — AT identity survives router navigation.
+     */
+    insertNode(parentId: string, id: string, beforeId?: string): void;
+    /**
+     * Mirror a `remove` patch: drop the element and purge the subtree's
+     * id mappings.
+     */
+    removeNode(node: VirtualNode): void;
+    private purge;
+    /**
+     * Mirror a `detach` patch: unlink the element but keep the subtree and
+     * all id mappings alive so a later `attach` reinserts the same elements
+     * (router subtree cache parity).
+     */
+    detachNode(id: string): void;
+    /**
+     * Full rebuild from a virtual tree. Only used when re-enabling the mirror
+     * (`setEnabled(true)`) and by `clear()` — steady-state sync is incremental.
+     */
+    rebuild(root: VirtualNode | null): void;
+    private mountSubtree;
+    /**
+     * `display:none` removes the subtree from the accessibility tree — used
+     * both for `visible: false` and for decorative (`semantics.hidden`) nodes.
+     */
+    private syncVisibility;
     /**
-     * Sync shadow DOM with virtual tree
+     * Write each mirror element's box to its node's painted (scroll-aware)
+     * bounds — called by the renderer after every canvas render, so AT
+     * geometry follows layout changes and container scrolling. Positions are
+     * parent-relative (every mirror element is absolutely positioned).
      */
-    syncTree(root: VirtualNode): void;
+    syncPositions(root: VirtualNode | null): void;
     /**
-     * Create shadow DOM element for virtual node
+     * `scrollX`/`scrollY` accumulate the ancestors' scroll offsets down the
+     * recursion (the same subtraction `getScrollAwareBounds` derives by
+     * walking up), keeping the pass O(n) instead of O(n·depth). Writes are
+     * skipped when the element's box is unchanged since the last sync.
      */
-    private createShadowNode;
+    private syncNodePosition;
     /**
-     * Get text content from node tree
+     * Choose the semantic HTML tag for a node's shadow element and set its
+     * non-accessibility content (text, input value/placeholder). Roles/names are
+     * applied separately from the semantics block.
      */
-    private getNodeText;
+    private createShadowElement;
     /**
      * Focus node in shadow DOM
      */
@@ -36,10 +139,14 @@ export declare class AccessibilityLayer {
      * Get shadow element by node ID
      */
     getElement(nodeId: string): HTMLElement | undefined;
+    /** The fallback-content root element (for focus delegation wiring). */
+    getRoot(): HTMLElement | null;
+    isEnabled(): boolean;
     /**
-     * Enable or disable accessibility layer
+     * Enable or disable the mirror. Re-enabling rebuilds from the given
+     * virtual tree (incremental sync has no history to replay).
      */
-    setEnabled(enabled: boolean): void;
+    setEnabled(enabled: boolean, root?: VirtualNode | null): void;
     /**
      * Cleanup
      */