@hypen-space/web 0.4.980 → 0.5.2

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,7 +249,7 @@ 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
@@ -349,7 +354,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,7 +366,7 @@ 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,
 });
 ```
@@ -371,7 +376,7 @@ const { renderer } = createHypenClient(canvas, engine, {
 Ensure `enableInputOverlay` is true:
 
 ```typescript
-const { renderer } = createHypenClient(canvas, engine, {
+const renderer = new CanvasRenderer(canvas, engine, {
   enableInputOverlay: 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(`

package/src/canvas/events.ts

@@ -14,6 +14,21 @@ interface IEngine {
   dispatchAction(name: string, payload?: any): void;
 }
 
+// Maps a DOM event type to the applicator prop names the engine may have set
+// on a node, in priority order. Multi-word events (`mouseenter`) need their
+// proper camelCase form (`onMouseEnter`) since the engine emits applicator
+// names verbatim. `mouseenter` also accepts `onHover` as an alias.
+const CANVAS_EVENT_PROP_NAMES: Record<string, string[]> = {
+  mouseenter: ["onMouseEnter", "onHover", "onmouseenter", "mouseenter"],
+  mouseleave: ["onMouseLeave", "onmouseleave", "mouseleave"],
+  mousedown: ["onMouseDown", "onmousedown", "mousedown"],
+  mouseup: ["onMouseUp", "onmouseup", "mouseup"],
+  dblclick: ["onDblClick", "onDoubleClick", "ondblclick", "dblclick"],
+  contextmenu: ["onContextMenu", "oncontextmenu", "contextmenu"],
+  keydown: ["onKeyDown", "onkeydown", "keydown"],
+  keyup: ["onKeyUp", "onkeyup", "keyup"],
+};
+
 /**
  * Canvas Event Manager
  */
@@ -210,6 +225,13 @@ export class CanvasEventManager {
 
     this.mouseDownNode = node;
 
+    // Track pressed (`:active`) state so paint-time `:active` variants resolve.
+    // Repaint so the active style appears immediately on press.
+    if (node) {
+      node.pressed = true;
+      this.requestRedraw();
+    }
+
     if (node && node.clickable) {
       this.dispatchNodeEvent(node, "mousedown", {
         button: e.button,
@@ -234,6 +256,13 @@ export class CanvasEventManager {
     const hit = this.hitTest(point);
     const node = this.findClickableAncestor(hit) ?? hit;
 
+    // Clear the pressed (`:active`) flag from the node that was pressed —
+    // release ends `:active` even if the pointer drifted off the node first.
+    if (this.mouseDownNode && this.mouseDownNode.pressed) {
+      this.mouseDownNode.pressed = false;
+      this.requestRedraw();
+    }
+
     if (node && node.clickable) {
       this.dispatchNodeEvent(node, "mouseup", {
         button: e.button,
@@ -383,13 +412,25 @@ export class CanvasEventManager {
    * Dispatch event to engine
    */
   private dispatchNodeEvent(node: VirtualNode, eventType: string, data: any): void {
-    // Engine emits event applicators in camelCase (`onClick`, `onChange`). The
-    // older flat form `onclick` is still accepted. After prop normalisation the
-    // value is either a string (action name) or an object carrying an action
-    // name at `"0"` plus an auxiliary payload (e.g. `{ "0": "@router.push",
-    // to: "/notifications" }` for `@router.push(to: "/notifications")`).
-    const camel = `on${eventType.charAt(0).toUpperCase()}${eventType.slice(1)}`;
-    let spec: unknown = node.props[camel] ?? node.props[`on${eventType}`] ?? node.props[eventType];
+    // Engine emits event applicators in camelCase (`onClick`, `onMouseEnter`).
+    // Multi-word DOM events like `mouseenter` must map to `onMouseEnter`, not
+    // the naive `onMouseenter` that `on${capitalize(eventType)}` would produce.
+    // The older flat form `onclick`/`onmouseenter` is still accepted. After
+    // prop normalisation the value is either a string (action name) or an
+    // object carrying an action name at `"0"` plus an auxiliary payload.
+    const propNames = CANVAS_EVENT_PROP_NAMES[eventType] ?? [
+      `on${eventType.charAt(0).toUpperCase()}${eventType.slice(1)}`,
+      `on${eventType}`,
+      eventType,
+    ];
+
+    let spec: unknown;
+    for (const name of propNames) {
+      if (node.props[name] != null) {
+        spec = node.props[name];
+        break;
+      }
+    }
 
     // Actionable components fall back to the bare `action` prop on click.
     if (spec == null && eventType === "click") {
@@ -429,6 +470,7 @@ export class CanvasEventManager {
     this.canvas.removeEventListener("contextmenu", this.boundOnContextMenu);
     this.canvas.removeEventListener("keydown", this.boundOnKeyDown);
     this.canvas.removeEventListener("keyup", this.boundOnKeyUp);
+    if (this.mouseDownNode) this.mouseDownNode.pressed = false;
     this.rootNode = null;
     this.hoveredNode = null;
     this.focusedNode = null;

package/src/canvas/index.ts

@@ -5,14 +5,6 @@
  */
 
 export { CanvasRenderer } from "./renderer.js";
-export {
-  createCanvasClient as createHypenClient,
-  createCanvasClient,
-  type CanvasClient as HypenClient,
-  type CanvasClient,
-  type CanvasClientOptions as HypenClientOptions,
-  type CanvasClientOptions,
-} from "../client.js";
 export { registerPainter } from "./paint.js";
 export { CanvasEventManager } from "./events.js";
 export { InputOverlay } from "./input.js";

package/src/canvas/layout.ts

@@ -7,15 +7,7 @@
  */
 
 import type { VirtualNode, Layout, BoxSpacing } from "./types.js";
-import {
-  parseSpacing,
-  parseSize,
-  cssLengthToPx,
-  cssLengthToDimension,
-  resolveLineHeight,
-  setCurrentViewport,
-  getCurrentViewport,
-} from "./utils.js";
+import { parseSpacing, parseSize, cssLengthToPx, cssLengthToDimension } from "./utils.js";
 import { measureText } from "./text.js";
 import { getImageNaturalAspect } from "./paint.js";
 
@@ -55,6 +47,19 @@ export async function initTaffyLayout(): Promise<boolean> {
   taffyInitPromise = (async () => {
     try {
       taffy = await import("taffy-layout");
+      // In a server runtime (Bun/Node — including test runs where a JSDOM
+      // `window` may be globally registered by another test file), load the
+      // WASM from node_modules via fs. This path is deterministic; the
+      // fetch-based branch below depends on a reachable origin/CDN and must
+      // never be selected just because a test polyfilled `window`.
+      const isServerRuntime =
+        typeof process !== "undefined" &&
+        !!(process.versions?.bun || process.versions?.node);
+      if (isServerRuntime) {
+        await taffy.loadTaffy();
+        taffyReady = true;
+        return;
+      }
       // Bundlers (esp. Bun's browser bundler) sometimes inline a file:// URL
       // for import.meta.url inside taffy_wasm.js, which the browser blocks
       // ("Not allowed to load local resource"). The package's own `loadTaffy`
@@ -62,26 +67,40 @@ export async function initTaffyLayout(): Promise<boolean> {
       // raw `__wbg_init` (default export of the `taffy-layout/wasm` subpath)
       // directly with an explicit Response.
       let usedExplicit = false;
-      if (typeof window !== "undefined" && typeof fetch === "function") {
-        const candidates = [
-          new URL("/taffy_wasm_bg.wasm", window.location.origin),
-          new URL("https://cdn.jsdelivr.net/npm/taffy-layout@2.0.3/pkg/taffy_wasm_bg.wasm"),
-          new URL("https://unpkg.com/taffy-layout@2.0.3/pkg/taffy_wasm_bg.wasm"),
-        ];
-        const rawWasm = await import(
-          /* @vite-ignore */ "taffy-layout/wasm" as string
-        );
-        const wbgInit = rawWasm.default as (input?: any) => Promise<unknown>;
-        for (const url of candidates) {
-          try {
-            const res = await fetch(url);
-            if (!res.ok) continue;
-            await wbgInit({ module_or_path: res });
-            usedExplicit = true;
-            break;
-          } catch {
-            // Try next candidate
+      // Only take the fetch path in a real browser. Test environments (and
+      // anything else that installs a fake `window` global) must fall through
+      // to `loadTaffy()`, which resolves the WASM from the package on disk —
+      // a fake window without `location.origin` used to throw here and
+      // silently disable Taffy for the rest of the process.
+      const isRealBrowser =
+        typeof window !== "undefined" &&
+        typeof fetch === "function" &&
+        typeof window.location?.origin === "string" &&
+        window.document?.defaultView === window;
+      if (isRealBrowser) {
+        try {
+          const candidates = [
+            new URL("/taffy_wasm_bg.wasm", window.location.origin),
+            new URL("https://cdn.jsdelivr.net/npm/taffy-layout@2.0.3/pkg/taffy_wasm_bg.wasm"),
+            new URL("https://unpkg.com/taffy-layout@2.0.3/pkg/taffy_wasm_bg.wasm"),
+          ];
+          const rawWasm = await import(
+            /* @vite-ignore */ "taffy-layout/wasm" as string
+          );
+          const wbgInit = rawWasm.default as (input?: any) => Promise<unknown>;
+          for (const url of candidates) {
+            try {
+              const res = await fetch(url);
+              if (!res.ok) continue;
+              await wbgInit({ module_or_path: res });
+              usedExplicit = true;
+              break;
+            } catch {
+              // Try next candidate
+            }
           }
+        } catch {
+          // Fall through to loadTaffy()
         }
       }
       if (!usedExplicit) {
@@ -180,22 +199,9 @@ function buildTaffyStyle(
   // `List` is the DSL's vertical-stack iterator (see dom/components/list.ts
   // — `flex-direction: column` is its default). Match that here so feeds
   // like Notifications stack their rows vertically instead of flowing
-  // sideways. The legacy `direction` prop can flip it to row, and so can
-  // a Tailwind `flex-row` class which lands on `props.flexDirection`
-  // (without this, top-tab strips built as `List.flex-row` stacked
-  // vertically because the List default won the tie-break).
-  const isListColumn =
-    type === "list" &&
-    props.direction !== "horizontal" &&
-    props.flexDirection !== "row";
-  // Button defaults to `flex-direction: column` to match the DOM renderer
-  // (see dom/components/button.ts). With Taffy's default `align-items:
-  // stretch`, treating Button as a row caused inner `Column { Icon, Text }`
-  // children to collapse onto each other (icon overlapping label). Only
-  // apply the column default when no explicit `flexDirection` is set so a
-  // Tailwind `flex-row` on a button still wins.
-  const isButtonColumn = type === "button" && props.flexDirection === undefined;
-  const isColumn = !isStack && (type === "column" || isListColumn || isButtonColumn || props.flexDirection === "column");
+  // sideways. The `direction` prop can still flip it to row.
+  const isListColumn = type === "list" && props.direction !== "horizontal";
+  const isColumn = !isStack && (type === "column" || isListColumn || props.flexDirection === "column");
   const isGrid = !isStack && (type === "grid" || props.display === "grid");
 
   if (isStack) {
@@ -386,7 +392,7 @@ function buildTaffyStyle(
     // Taffy defaults to `box-sizing: border-box`, so we add the
     // padding/border ourselves into `size.height`.
     const fontSize = cssLengthToPx(props.fontSize) ?? 16;
-    const lineHeight = resolveLineHeight(props.lineHeight, fontSize) ?? fontSize * 1.5;
+    const lineHeight = cssLengthToPx(props.lineHeight) ?? fontSize * 1.5;
     const minRows = type === "textarea" ? Math.max(1, Number(props.rows) || 3) : 1;
     const padTop = cssLengthToPx(props.paddingTop ?? props.padding) ?? 0;
     const padBottom = cssLengthToPx(props.paddingBottom ?? props.padding) ?? 0;
@@ -408,30 +414,7 @@ function buildTaffyStyle(
       (parent.type.toLowerCase() === "grid" || parent.props.display === "grid");
     const widthIn = parentIsGridLayout && props.width === "100%" ? undefined : props.width;
     const heightIn = parentIsGridLayout && props.height === "100%" ? undefined : props.height;
-
-    // Mirror the DOM rule `[data-hypen-type="row"]:has(> [data-hypen-flex])
-    // { width: 100% }` (and the symmetric column case). When a flex
-    // container has no explicit main-axis size and any child opts into
-    // weighted growth (`flex` / `flexGrow > 0`), Taffy would otherwise
-    // size the container to its min-content — so a Row of `flex-1`
-    // segmented-control buttons stayed pill-sized instead of stretching
-    // across the parent. Only do this when at least one child explicitly
-    // asks for flex, matching the DOM `:has(> [data-hypen-flex])` guard.
-    const isRowContainer = !isStack && !isGrid && !isColumn;
-    const isColumnContainer = !isStack && !isGrid && isColumn;
-    const childAsksFlex = node.children.some((c) => {
-      const fg = parseFloat(c.props.flexGrow);
-      if (Number.isFinite(fg) && fg > 0) return true;
-      const f = parseFloat(c.props.flex);
-      return Number.isFinite(f) && f > 0;
-    });
-    let resolvedWidth = toDimension(widthIn);
-    let resolvedHeight = toDimension(heightIn);
-    if (childAsksFlex) {
-      if (isRowContainer && widthIn === undefined) resolvedWidth = "100%";
-      if (isColumnContainer && heightIn === undefined) resolvedHeight = "100%";
-    }
-    style.size = { width: resolvedWidth, height: resolvedHeight };
+    style.size = { width: toDimension(widthIn), height: toDimension(heightIn) };
   }
 
   // --- Min / Max constraints -------------------------------------------------
@@ -806,17 +789,12 @@ function buildTree(
   // container with size 0×0, and downstream siblings were placed on top of
   // each other ("1,431 likes" overlapping the caption row was the visible
   // symptom).
-  // `props[0] != null` — not `props[0]` truthy. The number `0`, the empty
-  // string, and `false` are valid text content; falsy guards here let
-  // those cases skip the measurement leaf and inherit a 0-height container,
-  // which made siblings stack on top of each other (a bound `0` overlapping
-  // the next line was the visible symptom in calorie-counter's hero).
-  if (node.type.toLowerCase() === "text" && props[0] != null && node.children.length === 0) {
-    const text = String(props[0]);
+  if (node.type.toLowerCase() === "text" && props[0] && node.children.length === 0) {
+    const text = String(props[0] || "");
     const fontSize = cssLengthToPx(props.fontSize) ?? 16;
     const fontWeight = props.fontWeight || "normal";
     const fontFamily = props.fontFamily || "system-ui, sans-serif";
-    const lineHeight = resolveLineHeight(props.lineHeight, fontSize) ?? fontSize * 1.2;
+    const lineHeight = cssLengthToPx(props.lineHeight) ?? fontSize * 1.2;
 
     const p = parseSpacing(props.padding || 0);
     if (props.paddingTop !== undefined) p.top = cssLengthToPx(props.paddingTop) ?? 0;
@@ -1130,30 +1108,18 @@ export function computeLayout(
   x: number = 0,
   y: number = 0,
 ): void {
-  // Publish the active viewport so `cssLengthToPx` can resolve `vw` / `vh`
-  // against the actual canvas dimensions during this layout pass. Without
-  // this, `vh` falls back to `window.innerHeight` (wrong inside an iframe
-  // or scaled preview pane) or, worse, to a unitless pixel value that
-  // collapses entire layouts. Layout is synchronous, so a try/finally
-  // restoring the previous slot is safe under nested or re-entrant calls.
-  const prevViewport = getCurrentViewport();
-  setCurrentViewport({ width: availableWidth, height: availableHeight });
-  try {
-    if (taffyReady && taffy) {
+  if (taffyReady && taffy) {
+    computeLayoutTaffy(ctx, node, availableWidth, availableHeight, x, y);
+    // After the first pass, Taffy's grid auto-row sizing for aspect-ratio
+    // image leaves can collapse rows (the leaf's max-content height is 0
+    // before column widths are known). Detect that pattern and re-run
+    // with explicit `gridAutoRows` derived from the now-known column
+    // width — see `annotateCollapsedAspectGrids`.
+    if (annotateCollapsedAspectGrids(node)) {
       computeLayoutTaffy(ctx, node, availableWidth, availableHeight, x, y);
-      // After the first pass, Taffy's grid auto-row sizing for aspect-ratio
-      // image leaves can collapse rows (the leaf's max-content height is 0
-      // before column widths are known). Detect that pattern and re-run
-      // with explicit `gridAutoRows` derived from the now-known column
-      // width — see `annotateCollapsedAspectGrids`.
-      if (annotateCollapsedAspectGrids(node)) {
-        computeLayoutTaffy(ctx, node, availableWidth, availableHeight, x, y);
-      }
-    } else {
-      computeLayoutFallback(ctx, node, availableWidth, availableHeight, x, y);
     }
-  } finally {
-    setCurrentViewport(prevViewport);
+  } else {
+    computeLayoutFallback(ctx, node, availableWidth, availableHeight, x, y);
   }
 }
 
@@ -1243,13 +1209,12 @@ function computeLayoutFallback(
     if (height === null) height = size;
   }
 
-  // Same `!= null` rule as above — `0` / `""` / `false` are valid text.
-  if (node.type.toLowerCase() === "text" && node.props[0] != null) {
-    const text = String(node.props[0]);
+  if (node.type.toLowerCase() === "text" && node.props[0]) {
+    const text = String(node.props[0] || "");
     const fontSize = cssLengthToPx(props.fontSize) ?? 16;
     const fontWeight = props.fontWeight || "normal";
     const fontFamily = props.fontFamily || "system-ui, sans-serif";
-    const lineHeight = resolveLineHeight(props.lineHeight, fontSize) ?? fontSize * 1.2;
+    const lineHeight = cssLengthToPx(props.lineHeight) ?? fontSize * 1.2;
 
     const maxWidth = width || availableAfterMargin.width - padding.left - padding.right;
     const maxLinesRaw = props.maxLines;