@hypen-space/web 0.5.2 → 0.5.3

package/src/canvas/text.ts

@@ -36,9 +36,15 @@ function isPretextAvailable(): boolean {
 }
 
 /**
- * Text metrics cache
+ * Text metrics cache — bounded LRU. Every distinct (text, font, width,
+ * clamp) combination measured on the layout/paint hot path lands here, so
+ * without a cap a long-lived session (live feeds, ticking clocks, per-width
+ * generations from resizes) grows it forever. Map iteration order is
+ * insertion order; hits re-insert to keep hot entries at the tail and the
+ * oldest entry is evicted past the cap.
  */
 const textMetricsCache = new Map<string, TextMetrics>();
+const MAX_TEXT_METRICS_CACHE_SIZE = 4096;
 
 /**
  * Get cache key for text metrics
@@ -55,6 +61,13 @@ function wrapTextFallback(ctx: CanvasRenderingContext2D, text: string, maxWidth:
   const paragraphs = text.split("\n");
 
   for (const paragraph of paragraphs) {
+    // An empty paragraph is a blank line — dropping it would collapse
+    // consecutive newlines (and a trailing Enter in a Textarea).
+    if (paragraph === "") {
+      lines.push("");
+      continue;
+    }
+
     const words = paragraph.split(" ");
     let currentLine = "";
 
@@ -70,9 +83,7 @@ function wrapTextFallback(ctx: CanvasRenderingContext2D, text: string, maxWidth:
       }
     }
 
-    if (currentLine) {
-      lines.push(currentLine);
-    }
+    lines.push(currentLine);
   }
 
   return lines.length > 0 ? lines : [""];
@@ -98,7 +109,12 @@ export function measureText(
 ): TextMetrics {
   const cacheKey = `${getCacheKey(text, fontStyle, maxWidth)}|${maxLines ?? ""}|${textOverflow ?? ""}`;
   const cached = textMetricsCache.get(cacheKey);
-  if (cached) return cached;
+  if (cached) {
+    // Refresh recency so steady-state entries survive eviction.
+    textMetricsCache.delete(cacheKey);
+    textMetricsCache.set(cacheKey, cached);
+    return cached;
+  }
 
   const font = createFontString(fontStyle.fontSize, fontStyle.fontWeight, fontStyle.fontFamily);
   const lineHeight = fontStyle.lineHeight || fontStyle.fontSize * 1.2;
@@ -107,11 +123,25 @@ export function measureText(
   let width: number;
 
   if (isPretextAvailable()) {
-    const prepared = prepareWithSegments(text, font);
     const effectiveMaxWidth = maxWidth || Infinity;
-    const linesResult = layoutWithLines(prepared, effectiveMaxWidth, lineHeight);
-    lines = linesResult.lines.map((l) => l.text);
-    width = lines.length > 0 ? Math.max(...linesResult.lines.map((l) => l.width)) : 0;
+    // Hard line breaks: pretext treats "\n" as ordinary whitespace, so
+    // paragraphs are laid out separately (matching the fallback path and
+    // what Textarea editing needs). Empty paragraphs stay as blank lines.
+    lines = [];
+    width = 0;
+    for (const paragraph of text.split("\n")) {
+      if (paragraph === "") {
+        lines.push("");
+        continue;
+      }
+      const prepared = prepareWithSegments(paragraph, font);
+      const linesResult = layoutWithLines(prepared, effectiveMaxWidth, lineHeight);
+      const paragraphLines = linesResult.lines.map((l) => l.text);
+      lines.push(...(paragraphLines.length > 0 ? paragraphLines : [""]));
+      for (const l of linesResult.lines) {
+        width = Math.max(width, l.width);
+      }
+    }
     if (lines.length === 0) lines = [""];
   } else {
     ctx.save();
@@ -170,6 +200,10 @@ export function measureText(
   };
 
   textMetricsCache.set(cacheKey, result);
+  if (textMetricsCache.size > MAX_TEXT_METRICS_CACHE_SIZE) {
+    const oldest = textMetricsCache.keys().next().value;
+    if (oldest !== undefined) textMetricsCache.delete(oldest);
+  }
   return result;
 }
 

package/src/canvas/types.ts

@@ -4,6 +4,8 @@
  * Shared type definitions for the canvas renderer
  */
 
+import type { Semantics } from "@hypen-space/core/types";
+
 export interface VirtualNode {
   id: string;
   type: string;
@@ -11,6 +13,13 @@ export interface VirtualNode {
   children: VirtualNode[];
   parent: VirtualNode | null;
 
+  /**
+   * Engine-derived accessibility semantics (role, name, hidden, …) carried
+   * from the Create patch. Drives the transparent accessibility overlay,
+   * since the canvas bitmap itself exposes nothing to assistive technology.
+   */
+  semantics?: Semantics;
+
   // Computed layout
   layout?: Layout;
 
@@ -112,9 +121,13 @@ export interface CanvasRendererOptions {
   backgroundColor?: string;
 
   // Features
+  //
+  // enableAccessibility also gates text-input editing and keyboard focus:
+  // the accessibility mirror (a transparent positioned overlay above the
+  // canvas) is the renderer's focus system, and Input/Textarea edit
+  // sessions start from mirror focus.
   enableAccessibility?: boolean;
   enableHitTesting?: boolean;
-  enableInputOverlay?: boolean;
 
   // Performance
   enableDirtyRects?: boolean;

package/src/canvas/variants.ts

@@ -87,10 +87,20 @@ function activeStatesFor(node: VirtualNode): ActiveStates {
  *
  * No-op for nodes without any variant keys (the common case), so the per-frame
  * cost on a plain tree is one cached set lookup per node.
+ *
+ * Returns true when any base value differs from the previous frame's
+ * effective value — the renderer uses this to decide whether layout must
+ * re-run (variant winners can change spacing/size, not just paint props).
  */
-function applyVariantsToNode(node: VirtualNode, width: number): void {
+function applyVariantsToNode(node: VirtualNode, width: number): boolean {
   const bases = getVariantBases(node);
-  if (bases.size === 0) return;
+  if (bases.size === 0) return false;
+
+  // Snapshot the previous frame's effective values for change detection.
+  const previous: Record<string, unknown> = {};
+  for (const base of bases) {
+    previous[base] = node.props[base];
+  }
 
   // Restore originals from the previous frame so we resolve from a clean base.
   if (node.variantOriginals) {
@@ -123,18 +133,27 @@ function applyVariantsToNode(node: VirtualNode, width: number): void {
       node.props[base] = resolved[base];
     }
   }
+
+  for (const base of bases) {
+    if (node.props[base] !== previous[base]) return true;
+  }
+  return false;
 }
 
 /**
  * Walk the tree from `root` and apply variant overrides to every node using
  * `width` (the canvas/content width) as the viewport for breakpoint matching.
  * Called once per frame before layout.
+ *
+ * Returns true when any node's effective props changed since the previous
+ * frame (breakpoint crossed, hover/focus/active/disabled state flipped).
  */
-export function applyVariants(root: VirtualNode, width: number): void {
-  applyVariantsToNode(root, width);
+export function applyVariants(root: VirtualNode, width: number): boolean {
+  let changed = applyVariantsToNode(root, width);
   for (const child of root.children) {
-    applyVariants(child, width);
+    if (applyVariants(child, width)) changed = true;
   }
+  return changed;
 }
 
 /**

package/src/dom/a11y-styles.ts

@@ -0,0 +1,65 @@
+/**
+ * Global accessibility stylesheet.
+ *
+ * Injects a single <style> element (idempotent, guarded by id) that:
+ *  - honours `prefers-reduced-motion: reduce` by disabling transitions,
+ *    animations and smooth scrolling on Hypen-rendered nodes;
+ *  - renders a visible `:focus-visible` outline so keyboard users can see
+ *    which element is focused;
+ *  - keeps that focus indicator visible under `forced-colors: active`
+ *    (Windows High Contrast), which strips box-shadow but honours outline; and
+ *  - strengthens the outline under `prefers-contrast: more`.
+ *
+ * Scoped to `[data-hypen-id]` so it only affects Hypen-rendered elements and
+ * never the host page.
+ */
+
+const STYLE_ID = "hypen-a11y-styles";
+
+const A11Y_CSS = `
+@media (prefers-reduced-motion: reduce) {
+  [data-hypen-id] {
+    transition: none !important;
+    animation: none !important;
+    scroll-behavior: auto !important;
+  }
+}
+[data-hypen-id]:focus-visible {
+  outline: 2px solid #1a73e8;
+  outline-offset: 2px;
+}
+@media (forced-colors: active) {
+  /* Forced-colors mode removes box-shadow and author colors but honours
+     outline: pin the focus indicator to an outline in the system Highlight
+     color, and drop any box-shadow-based indicator a component style set. */
+  [data-hypen-id]:focus-visible {
+    outline: 2px solid Highlight;
+    box-shadow: none;
+  }
+}
+@media (prefers-contrast: more) {
+  /* A thicker outline for users who asked for higher contrast. */
+  [data-hypen-id]:focus-visible {
+    outline-width: 3px;
+  }
+}
+`;
+
+/**
+ * Inject the accessibility stylesheet once. Safe to call repeatedly and in
+ * non-DOM environments (server/tests without `document`), where it no-ops.
+ */
+export function ensureA11yStyles(): void {
+  if (typeof document === "undefined" || !document.head) {
+    return;
+  }
+
+  if (typeof document.getElementById === "function" && document.getElementById(STYLE_ID)) {
+    return;
+  }
+
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = A11Y_CSS;
+  document.head.appendChild(style);
+}

package/src/dom/applicators/aria.ts

@@ -0,0 +1,41 @@
+/**
+ * ARIA escape hatch applicator
+ *
+ * `.aria(key, value)` sets an arbitrary `aria-<key>` attribute on the element,
+ * e.g. `.aria("expanded", "true")` -> `aria-expanded="true"`.
+ *
+ * WEB-ONLY / NON-PORTABLE: this is a raw DOM escape hatch. It bypasses the
+ * engine-derived typed `Semantics` block, so the value does NOT reach the
+ * Canvas, iOS or Android renderers. Prefer the portable accessibility
+ * applicators (e.g. `.role()`, `.label()`) when one exists; reach for `.aria`
+ * only for DOM-specific ARIA attributes the typed semantics do not cover.
+ */
+
+import type { ApplicatorHandler } from "./types.js";
+
+/**
+ * The grouped args arrive as `{ "0": key, "1": value }` for `.aria(key, value)`.
+ * A single positional arg (`.aria("busy")`) arrives as the bare key string.
+ */
+export const ariaHandler: ApplicatorHandler = (el, value) => {
+  let key: unknown;
+  let attrValue: unknown = "";
+
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const args = value as Record<string, unknown>;
+    key = args["0"];
+    attrValue = "1" in args ? args["1"] : "";
+  } else {
+    key = value;
+  }
+
+  if (key === undefined || key === null || key === "") {
+    return;
+  }
+
+  el.setAttribute("aria-" + String(key), String(attrValue));
+};
+
+export const ariaHandlers: Record<string, ApplicatorHandler> = {
+  aria: ariaHandler,
+};

package/src/dom/applicators/events.ts

@@ -21,6 +21,8 @@ import {
   unregisterEvent,
   getKeyTarget,
   setKeyTarget,
+  getMeta,
+  setMeta,
 } from "../element-data.js";
 
 const log = frameworkLoggers.events;
@@ -197,6 +199,7 @@ function createEventHandler(
   eventType: string,
   options: EventHandlerOptions = {}
 ): ApplicatorHandler {
+  const actionMetaKey = `event:${eventType}`;
   return (element: HTMLElement, value: unknown) => {
     const { actionName, payload: customPayload } = extractActionDetails(value);
 
@@ -205,14 +208,18 @@ function createEventHandler(
       return;
     }
 
+    // Store the current action on the element; the persistent listener reads
+    // it per event, so re-applying with a different action (e.g. a keyed-
+    // reused node) replaces the dispatch target instead of stacking listeners.
+    setMeta(element, actionMetaKey, { actionName, customPayload });
+
     const disposables = getElementDisposables(element);
 
     // Track that we've registered this event type
     // The disposable stack handles cleanup automatically
-    const eventKey = `${eventType}:${actionName}`;
+    const eventKey = eventType;
     if (getRegisteredEvents(element).has(eventKey)) {
-      // Already registered - skip to avoid duplicates
-      // This can happen during re-renders
+      // Listener already installed — the meta update above retargets it
       return;
     }
     registerEvent(element, eventKey);
@@ -222,6 +229,12 @@ function createEventHandler(
 
     // Create the event listener
     const listener = (event: Event) => {
+      const current = getMeta<{ actionName: string; customPayload: Record<string, unknown> }>(
+        element,
+        actionMetaKey,
+      );
+      if (!current) return;
+
       // Handle throttling
       if (options.throttleMs && throttleTimer) {
         return;
@@ -240,8 +253,8 @@ function createEventHandler(
 
       // Build payload
       const payload =
-        Object.keys(customPayload).length > 0
-          ? { ...customPayload }
+        Object.keys(current.customPayload).length > 0
+          ? { ...current.customPayload }
           : options.extractPayload
             ? options.extractPayload(event, element)
             : extractEventData(event, element);
@@ -250,9 +263,9 @@ function createEventHandler(
       const engine = getEngine(element);
       if (engine) {
         try {
-          engine.dispatchAction(actionName, payload);
+          engine.dispatchAction(current.actionName, payload);
         } catch (err) {
-          log.error(`Error dispatching action "${actionName}":`, err);
+          log.error(`Error dispatching action "${current.actionName}":`, err);
         }
       }
     };
@@ -274,6 +287,24 @@ function createEventHandler(
   };
 }
 
+/**
+ * Dispatch the action encoded in an applicator value (e.g. `"@actions.save"`)
+ * to the element's engine. Shared by click wiring and keyboard activation so
+ * both routes dispatch identically. No-op if the value carries no action or
+ * the element has no engine.
+ */
+export function triggerElementAction(element: HTMLElement, value: unknown): void {
+  const { actionName, payload } = extractActionDetails(value);
+  if (!actionName) return;
+  const engine = getEngine(element);
+  if (!engine) return;
+  try {
+    engine.dispatchAction(actionName, payload);
+  } catch (err) {
+    log.error(`Error dispatching action "${actionName}":`, err);
+  }
+}
+
 /**
  * Create a keyboard event handler that filters by key
  */

package/src/dom/applicators/index.ts

@@ -41,6 +41,7 @@ import { backgroundHandlers } from "./background.js";
 import { displayHandlers } from "./display.js";
 import { transitionHandlers } from "./transition.js";
 import { BREAKPOINTS as VARIANT_BREAKPOINTS, VALID_STATES } from "../../variants.js";
+import { ariaHandlers } from "./aria.js";
 
 /**
  * Tailwind breakpoint values for responsive variants.
@@ -520,5 +521,9 @@ export class ApplicatorRegistry {
     for (const [name, handler] of Object.entries(transitionHandlers)) {
       this.register(name, handler as ApplicatorHandler);
     }
+
+    for (const [name, handler] of Object.entries(ariaHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
   }
 }