@hypen-space/web 0.4.980 → 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;
 }
 
@@ -191,13 +225,7 @@ export function renderText(
   ctx.save();
   ctx.font = font;
   ctx.fillStyle = style.color;
-  // Use `middle` baseline so we can position each glyph at the visual centre
-  // of its line box. With `top`, canvas draws from the top of the EM square
-  // and any extra `line-height − font-size` space lands as padding BELOW the
-  // glyph — visible as `+` inside a round FAB drifting toward the top of
-  // the circle. CSS centres glyphs within the line box; matching that
-  // requires `middle` + half-lineHeight offset.
-  ctx.textBaseline = "middle";
+  ctx.textBaseline = "top";
 
   const metrics = measureText(ctx, text, style, width, maxLines, textOverflow);
 
@@ -212,8 +240,7 @@ export function renderText(
   // Render each line
   for (let i = 0; i < metrics.lines.length; i++) {
     const line = metrics.lines[i];
-    // Centre of the line box (top of line + half of line-height).
-    const lineY = startY + i * metrics.lineHeight + metrics.lineHeight / 2;
+    const lineY = startY + i * metrics.lineHeight;
 
     // Calculate X based on text alignment
     let lineX = x;

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;
 
@@ -27,6 +36,20 @@ export interface VirtualNode {
 
   // Scroll state (managed by ScrollManager, not serialised)
   scrollState?: ScrollState;
+
+  // Pointer-pressed (active) state, tracked by the event manager from
+  // mousedown/mouseup so `:active` paint variants can resolve.
+  pressed?: boolean;
+
+  // --- Variant resolution bookkeeping (managed by applyVariants) ---
+  // Set of applicator base names that have at least one `@bp`/`:state` variant
+  // key on this node. Computed lazily; null means "not yet scanned", an empty
+  // set means "scanned, no variants".
+  variantBases?: Set<string> | null;
+  // Snapshot of the node's original (variant-free) base values, captured the
+  // first time a variant override is applied so each frame resolves from the
+  // un-overridden base instead of compounding overrides.
+  variantOriginals?: Record<string, unknown>;
 }
 
 export interface Layout {
@@ -98,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/utils.ts

@@ -12,42 +12,6 @@ import type { BoxSpacing, Rectangle, Point, VirtualNode } from "./types.js";
 // and treating `3.5rem` as 3.5px, collapsing whole layouts to 1/16 size.
 const ROOT_FONT_PX = 16;
 
-/**
- * Active layout viewport — used to resolve `vw` / `vh` correctly during a
- * layout pass. Set by `computeLayout` (layout.ts) at entry and cleared on
- * exit. Layout traversal is synchronous, so a single module-level slot is
- * sufficient and avoids threading a `viewport` parameter through every
- * `cssLengthToPx` call site (there are dozens).
- *
- * Falls back to `window.innerWidth` / `window.innerHeight` outside a layout
- * pass (e.g. for direct callers that resolve sizes ahead of layout). When
- * neither is available — e.g. headless tests — `vw`/`vh` degrade to the
- * pre-fix unitless-pixel behavior.
- */
-let currentViewport: { width: number; height: number } | null = null;
-
-export function setCurrentViewport(viewport: { width: number; height: number } | null): void {
-  currentViewport = viewport;
-}
-
-export function getCurrentViewport(): { width: number; height: number } | null {
-  return currentViewport;
-}
-
-function resolveViewportPx(unit: "vw" | "vh", n: number): number {
-  if (currentViewport) {
-    const dim = unit === "vw" ? currentViewport.width : currentViewport.height;
-    return (n / 100) * dim;
-  }
-  if (typeof window !== "undefined") {
-    const dim = unit === "vw" ? window.innerWidth : window.innerHeight;
-    if (Number.isFinite(dim) && dim > 0) return (n / 100) * dim;
-  }
-  // Last resort: treat as unitless px so the layout still gets a numeric
-  // value (matches pre-fix behavior in the no-viewport case).
-  return n;
-}
-
 /**
  * Parse a CSS length string (or number) into pixels.
  * Returns `null` for `"auto"` or unparseable input; returns `null` for `%`
@@ -69,8 +33,10 @@ export function cssLengthToPx(value: any): number | null {
     case "px": return n;
     case "rem":
     case "em": return n * ROOT_FONT_PX;
+    // We don't have a viewport reference here; treat vw/vh as unitless px
+    // fallback so the layout gets _some_ numeric value rather than zero.
     case "vw":
-    case "vh": return resolveViewportPx(unit, n);
+    case "vh": return n;
     // Typographic point — 1/72 inch at CSS reference density (96dpi).
     case "pt": return n * (96 / 72);
     // Density-independent (dp) and scale-independent (sp) logical pixels
@@ -86,38 +52,6 @@ export function cssLengthToPx(value: any): number | null {
   }
 }
 
-/**
- * Resolve a CSS `line-height` value to a pixel value.
- *
- * Unitless numbers (e.g. `1`, `1.5`, `"1.25"`) are CSS multipliers of the
- * font-size — `line-height: 1` (Tailwind's `leading-none`) means line box =
- * 1 × font-size, NOT 1 pixel. Without this branch, `cssLengthToPx("1")`
- * returned literally `1`, and a Column of `leading-none` Texts collapsed
- * each line to 1px tall — emoji + label in a bottom-tab button rendered at
- * the same y and overlapped.
- *
- * Anything with an explicit unit (`16px`, `1.5em`, `1rem`, `120%` is
- * rejected → null since Taffy/measure expects px) falls through to
- * `cssLengthToPx`.
- */
-export function resolveLineHeight(value: any, fontSize: number): number | null {
-  if (value === undefined || value === null) return null;
-  if (typeof value === "number" && Number.isFinite(value)) {
-    // Unitless number: multiplier of font-size (matches CSS spec).
-    return value * fontSize;
-  }
-  if (typeof value === "string") {
-    const s = value.trim();
-    if (s === "" || s === "auto" || s === "normal") return null;
-    // Pure numeric string with no unit → unitless multiplier.
-    if (/^-?\d*\.?\d+$/.test(s)) {
-      const n = parseFloat(s);
-      return Number.isFinite(n) ? n * fontSize : null;
-    }
-  }
-  return cssLengthToPx(value);
-}
-
 /**
  * Parse a CSS length string for Taffy's Dimension type. Keeps `%` values as
  * the tagged percentage string, turns `"auto"`/empty/invalid into `"auto"`,

package/src/canvas/variants.ts

@@ -0,0 +1,172 @@
+/**
+ * Canvas variant application.
+ *
+ * The Canvas renderer reads winning values directly off `node.props.<base>`
+ * (e.g. `props.padding`, `props.backgroundColor`) in both layout.ts and
+ * paint.ts. To support responsive breakpoints and interaction-state variants
+ * WITHOUT rewriting every call site, we resolve variant keys once per frame
+ * (just before layout) and stamp the winning value onto the base key.
+ *
+ * Resolution itself is delegated to the shared, renderer-agnostic helper in
+ * `../variants.ts`, so breakpoint pixels, state names, and precedence stay
+ * byte-compatible with the DOM renderer.
+ *
+ * Per-node bookkeeping (`variantBases`, `variantOriginals`) lives on the
+ * VirtualNode so each frame:
+ *   1. restores the original (variant-free) base value, then
+ *   2. re-applies the current winner for the present width + active states.
+ * This makes the pass idempotent and reversible — when a hover ends or the
+ * canvas shrinks below a breakpoint, the base value comes back automatically.
+ */
+
+import type { VirtualNode } from "./types.js";
+import {
+  resolveVariantProps,
+  parseVariantKey,
+  type ActiveStates,
+} from "../variants.js";
+
+/**
+ * Lazily compute (and cache) the set of applicator base names on this node that
+ * carry at least one variant key. Returns the cached set on subsequent calls.
+ *
+ * The cache is invalidated by `invalidateVariantCache`, called from the
+ * renderer whenever a SetProp/RemoveProp changes the node's prop keys.
+ */
+function getVariantBases(node: VirtualNode): Set<string> {
+  if (node.variantBases != null) return node.variantBases;
+  const bases = new Set<string>();
+  for (const key of Object.keys(node.props)) {
+    const parsed = parseVariantKey(key);
+    if (parsed.breakpoint || parsed.state) bases.add(parsed.base);
+  }
+  node.variantBases = bases;
+  return bases;
+}
+
+/**
+ * Drop the cached variant state so it is recomputed on the next frame.
+ * Call after any prop mutation that may add/remove variant keys.
+ *
+ * Also drops the `variantOriginals` snapshot: a SetProp can change the *base*
+ * value of a base that carries a variant (e.g. `padding.0` updated while
+ * `padding@md.0` exists). The snapshot was taken from the previous frame's
+ * props, so restoring it would clobber the engine's new base value with the
+ * stale one whenever the variant isn't currently active. Clearing it forces the
+ * next frame to re-snapshot from the current (post-SetProp) props.
+ */
+export function invalidateVariantCache(node: VirtualNode): void {
+  node.variantBases = null;
+  node.variantOriginals = undefined;
+}
+
+/**
+ * Derive the active interaction states for a node from its tracked flags and
+ * props, mirroring the DOM/CSS pseudo-class semantics:
+ *   - hover    : pointer is over the node (or a child resolved to it)
+ *   - focus    : node holds canvas focus
+ *   - active   : pointer is currently pressed on the node
+ *   - disabled : node opts out via `disabled`/`enabled:false`
+ */
+function activeStatesFor(node: VirtualNode): ActiveStates {
+  const disabled =
+    node.props.disabled === true ||
+    node.props.disabled === "true" ||
+    node.props.enabled === false ||
+    node.props.enabled === "false";
+  return {
+    hover: !!node.hovered,
+    focus: !!node.focused,
+    active: !!node.pressed,
+    disabled,
+  };
+}
+
+/**
+ * Resolve and apply variant overrides for a single node, in place.
+ *
+ * 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): boolean {
+  const bases = getVariantBases(node);
+  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) {
+    for (const base of bases) {
+      const orig = node.variantOriginals[base];
+      if (orig === undefined) {
+        // The base had no plain value originally — remove any override we wrote.
+        delete node.props[base];
+      } else {
+        node.props[base] = orig;
+      }
+    }
+  }
+
+  const resolved = resolveVariantProps(
+    node.props as Record<string, unknown>,
+    width,
+    activeStatesFor(node),
+  );
+
+  // Capture originals (once we know which bases are involved) and apply winners.
+  const originals: Record<string, unknown> = {};
+  for (const base of bases) {
+    originals[base] = node.props[base];
+  }
+  node.variantOriginals = originals;
+
+  for (const base of bases) {
+    if (base in resolved) {
+      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): boolean {
+  let changed = applyVariantsToNode(root, width);
+  for (const child of root.children) {
+    if (applyVariants(child, width)) changed = true;
+  }
+  return changed;
+}
+
+/**
+ * Re-derive a node's cached computed fields (`visible`, `opacity`) from its
+ * current `props`. These are read on the hot paint/hit-test path, so they are
+ * cached on the node — but {@link applyVariants} can rewrite the underlying
+ * props (`visible@md`, `opacity:disabled`) after the create/setProp caches were
+ * set, so this must run after every variant pass or the cache goes stale.
+ * Single source of truth so the create / setProp / post-variant sites can't
+ * drift apart.
+ */
+export function deriveNodeComputed(node: VirtualNode): void {
+  const o = parseFloat(node.props.opacity as string);
+  node.opacity = Number.isFinite(o) ? o : 1;
+  node.visible = node.props.visible === undefined ? true : !!node.props.visible;
+}

package/src/dom/README.md

@@ -37,17 +37,18 @@ src/dom/
 
 ### Browser Import
 
-The recommended one-call wiring is `createHypenClient`. The bare `DOMRenderer` constructor is still exported for advanced cases (custom subscription, multi-listener fan-out, etc.).
-
 ```typescript
 import { app, HypenModuleInstance } 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();
 
-createHypenClient(document.body, engine);
+const renderer = new DOMRenderer(document.body, engine);
+engine.setRenderCallback((patches) => {
+  renderer.applyPatches(patches);
+});
 ```
 
 ### Server Import
@@ -78,7 +79,7 @@ All components are registered by default:
 ### Custom Components
 
 ```typescript
-const { renderer } = createHypenClient(document.body, engine);
+const renderer = new DOMRenderer(document.body, engine);
 const registry = renderer.getComponentRegistry();
 
 registry.register("mycomponent", {
@@ -140,7 +141,7 @@ Style applicators are registered by default:
 ### Custom Applicators
 
 ```typescript
-const { renderer } = createHypenClient(document.body, engine);
+const renderer = new DOMRenderer(document.body, engine);
 const applicators = renderer.getApplicatorRegistry();
 
 applicators.register("shadow", (el, value) => {
@@ -182,7 +183,7 @@ Canvas components have special applicators for drawing:
 
 ```typescript
 // Register canvas applicators
-const { renderer } = createHypenClient(document.body, engine);
+const renderer = new DOMRenderer(document.body, engine);
 const applicators = renderer.getApplicatorRegistry();
 
 // Canvas-specific applicators

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,
+};