@hypen-space/web 0.4.46 → 0.4.82

package/src/canvas/text.ts

@@ -1,15 +1,40 @@
 /**
  * Text Rendering System
  *
- * Text measurement, wrapping, and rendering
+ * Text measurement, wrapping, and rendering using pretext for accurate
+ * multilingual line breaking (CJK, bidi, emoji, etc.). Falls back to
+ * basic word-splitting in environments without OffscreenCanvas (e.g. tests).
  */
 
 import type { FontStyle, TextMetrics, TextStyle } from "./types.js";
 import { createFontString } from "./utils.js";
+import {
+  prepareWithSegments,
+  layoutWithLines,
+  clearCache as pretextClearCache,
+} from "@chenglou/pretext";
 import { frameworkLoggers } from "@hypen-space/core/logger";
 
 const log = frameworkLoggers.canvas;
 
+/**
+ * Whether pretext is available (requires a working canvas with measureText)
+ */
+let pretextAvailable: boolean | null = null;
+
+function isPretextAvailable(): boolean {
+  if (pretextAvailable !== null) return pretextAvailable;
+  try {
+    // Probe by running a minimal prepare — throws if neither OffscreenCanvas
+    // nor a real DOM canvas is available (e.g. jsdom in tests).
+    prepareWithSegments("x", "16px sans-serif");
+    pretextAvailable = true;
+  } catch {
+    pretextAvailable = false;
+  }
+  return pretextAvailable;
+}
+
 /**
  * Text metrics cache
  */
@@ -23,59 +48,9 @@ function getCacheKey(text: string, fontStyle: FontStyle, maxWidth?: number): str
 }
 
 /**
- * Measure text dimensions
- */
-export function measureText(
-  ctx: CanvasRenderingContext2D,
-  text: string,
-  fontStyle: FontStyle,
-  maxWidth?: number
-): TextMetrics {
-  const cacheKey = getCacheKey(text, fontStyle, maxWidth);
-  const cached = textMetricsCache.get(cacheKey);
-  if (cached) return cached;
-
-  const font = createFontString(fontStyle.fontSize, fontStyle.fontWeight, fontStyle.fontFamily);
-  ctx.save();
-  ctx.font = font;
-
-  const lineHeight = fontStyle.lineHeight || fontStyle.fontSize * 1.2;
-
-  // No wrapping needed
-  if (!maxWidth) {
-    const metrics = ctx.measureText(text);
-    const result: TextMetrics = {
-      width: metrics.width,
-      height: lineHeight,
-      lines: [text],
-      lineHeight,
-    };
-    ctx.restore();
-    textMetricsCache.set(cacheKey, result);
-    return result;
-  }
-
-  // Wrap text
-  const lines = wrapText(ctx, text, maxWidth);
-  const width = Math.max(...lines.map((line) => ctx.measureText(line).width));
-  const height = lines.length * lineHeight;
-
-  const result: TextMetrics = {
-    width,
-    height,
-    lines,
-    lineHeight,
-  };
-
-  ctx.restore();
-  textMetricsCache.set(cacheKey, result);
-  return result;
-}
-
-/**
- * Wrap text to fit within maxWidth
+ * Fallback word wrap for environments without pretext support
  */
-function wrapText(ctx: CanvasRenderingContext2D, text: string, maxWidth: number): string[] {
+function wrapTextFallback(ctx: CanvasRenderingContext2D, text: string, maxWidth: number): string[] {
   const lines: string[] = [];
   const paragraphs = text.split("\n");
 
@@ -103,6 +78,73 @@ function wrapText(ctx: CanvasRenderingContext2D, text: string, maxWidth: number)
   return lines.length > 0 ? lines : [""];
 }
 
+/**
+ * Measure text dimensions. Uses pretext for accurate multilingual line
+ * breaking when available, falls back to basic word-splitting otherwise.
+ */
+export function measureText(
+  ctx: CanvasRenderingContext2D,
+  text: string,
+  fontStyle: FontStyle,
+  maxWidth?: number
+): TextMetrics {
+  const cacheKey = getCacheKey(text, fontStyle, maxWidth);
+  const cached = textMetricsCache.get(cacheKey);
+  if (cached) return cached;
+
+  const font = createFontString(fontStyle.fontSize, fontStyle.fontWeight, fontStyle.fontFamily);
+  const lineHeight = fontStyle.lineHeight || fontStyle.fontSize * 1.2;
+
+  let result: TextMetrics;
+
+  if (isPretextAvailable()) {
+    // pretext handles text shaping, segmentation, and line breaking
+    const prepared = prepareWithSegments(text, font);
+    const effectiveMaxWidth = maxWidth || Infinity;
+    const linesResult = layoutWithLines(prepared, effectiveMaxWidth, lineHeight);
+
+    const lines = linesResult.lines.map((l) => l.text);
+    const width = lines.length > 0
+      ? Math.max(...linesResult.lines.map((l) => l.width))
+      : 0;
+
+    result = {
+      width,
+      height: linesResult.height || lineHeight,
+      lines: lines.length > 0 ? lines : [""],
+      lineHeight,
+    };
+  } else {
+    // Fallback: use ctx.measureText with basic word splitting
+    ctx.save();
+    ctx.font = font;
+
+    if (!maxWidth) {
+      const metrics = ctx.measureText(text);
+      result = {
+        width: metrics.width,
+        height: lineHeight,
+        lines: [text],
+        lineHeight,
+      };
+    } else {
+      const lines = wrapTextFallback(ctx, text, maxWidth);
+      const width = Math.max(...lines.map((line) => ctx.measureText(line).width));
+      result = {
+        width,
+        height: lines.length * lineHeight,
+        lines,
+        lineHeight,
+      };
+    }
+
+    ctx.restore();
+  }
+
+  textMetricsCache.set(cacheKey, result);
+  return result;
+}
+
 /**
  * Render text with style
  */
@@ -153,10 +195,11 @@ export function renderText(
 }
 
 /**
- * Clear text metrics cache
+ * Clear text metrics cache (both local and pretext internal caches)
  */
 export function clearTextCache(): void {
   textMetricsCache.clear();
+  pretextClearCache();
 }
 
 /**

package/src/canvas/types.ts

@@ -24,6 +24,9 @@ export interface VirtualNode {
   focusable: boolean;
   focused: boolean;
   hovered: boolean;
+
+  // Scroll state (managed by ScrollManager, not serialised)
+  scrollState?: ScrollState;
 }
 
 export interface Layout {
@@ -121,6 +124,29 @@ export interface LayoutFunction {
   };
 }
 
+export interface ScrollState {
+  /** Current scroll offset (pixels from origin) */
+  scrollX: number;
+  scrollY: number;
+
+  /** Scroll velocity for momentum (px/ms) */
+  velocityX: number;
+  velocityY: number;
+
+  /** Total scrollable content size (set during layout) */
+  scrollWidth: number;
+  scrollHeight: number;
+
+  /** Whether a touch/pointer sequence is active */
+  touching: boolean;
+
+  /** Timestamp of last velocity sample */
+  lastTouchTime: number;
+
+  /** Scrollbar fade-out opacity (0–1) */
+  scrollbarOpacity: number;
+}
+
 export interface DirtyRect extends Rectangle {
   frameId: number;
 }

package/src/canvas/utils.ts

@@ -7,8 +7,14 @@
 import type { BoxSpacing, Rectangle, Point, VirtualNode } from "./types.js";
 
 /**
- * Parse spacing value (margin, padding)
- * Supports: number, "10", "10 20", "10 20 30 40"
+ * Parse spacing value (margin, padding).
+ *
+ * Supports the same forms as the DOM and native renderers:
+ * - `number` — all sides
+ * - `"10"`, `"10 20"`, `"10 20 30"`, `"10 20 30 40"` — CSS shorthand string
+ * - `{top, right, bottom, left}` — named keys
+ * - `{0, 1, ...}` — positional applicator args from the engine, mapped via
+ *   CSS shorthand semantics (1=all, 2=v/h, 3=t/h/b, 4=t/r/b/l)
  */
 export function parseSpacing(value: any): BoxSpacing {
   if (typeof value === "number") {
@@ -17,29 +23,53 @@ export function parseSpacing(value: any): BoxSpacing {
 
   if (typeof value === "string") {
     const parts = value.split(/\s+/).map((v) => parseFloat(v) || 0);
-    if (parts.length === 1) {
-      return { top: parts[0], right: parts[0], bottom: parts[0], left: parts[0] };
-    }
-    if (parts.length === 2) {
-      return { top: parts[0], right: parts[1], bottom: parts[0], left: parts[1] };
-    }
-    if (parts.length === 4) {
-      return { top: parts[0], right: parts[1], bottom: parts[2], left: parts[3] };
-    }
+    return spacingFromArray(parts);
   }
 
   if (typeof value === "object" && value !== null) {
-    return {
-      top: parseFloat(value.top) || 0,
-      right: parseFloat(value.right) || 0,
-      bottom: parseFloat(value.bottom) || 0,
-      left: parseFloat(value.left) || 0,
-    };
+    // Named-keys form takes priority when any side is named.
+    if (
+      value.top !== undefined ||
+      value.right !== undefined ||
+      value.bottom !== undefined ||
+      value.left !== undefined
+    ) {
+      return {
+        top: parseFloat(value.top) || 0,
+        right: parseFloat(value.right) || 0,
+        bottom: parseFloat(value.bottom) || 0,
+        left: parseFloat(value.left) || 0,
+      };
+    }
+
+    // Positional form: walk contiguous "0", "1", … keys.
+    const args: number[] = [];
+    for (let i = 0; value[String(i)] !== undefined; i++) {
+      args.push(parseFloat(value[String(i)]) || 0);
+    }
+    if (args.length > 0) {
+      return spacingFromArray(args);
+    }
   }
 
   return { top: 0, right: 0, bottom: 0, left: 0 };
 }
 
+/** CSS shorthand: 1=all, 2=v/h, 3=t/h/b, 4=t/r/b/l. */
+function spacingFromArray(parts: number[]): BoxSpacing {
+  if (parts.length === 1) {
+    return { top: parts[0], right: parts[0], bottom: parts[0], left: parts[0] };
+  }
+  if (parts.length === 2) {
+    return { top: parts[0], right: parts[1], bottom: parts[0], left: parts[1] };
+  }
+  if (parts.length === 3) {
+    return { top: parts[0], right: parts[1], bottom: parts[2], left: parts[1] };
+  }
+  // 4+ values: top, right, bottom, left
+  return { top: parts[0], right: parts[1], bottom: parts[2], left: parts[3] };
+}
+
 /**
  * Parse size value (width, height)
  * Returns pixel value or null for "auto"

package/src/canvas/virtualize.ts

@@ -0,0 +1,81 @@
+/**
+ * Windowed / Virtual Rendering
+ *
+ * For scrollable containers with many children, determines which children
+ * intersect the visible viewport so the paint system can skip off-screen nodes.
+ * This is paint-level virtualization only -- all children still get layout
+ * computed (Taffy handles that efficiently). We just skip painting off-screen
+ * children.
+ */
+
+import type { VirtualNode, Rectangle } from "./types.js";
+import { isScrollable } from "./scroll.js";
+
+/** Number of pixels to render beyond the visible viewport edges. */
+const OVERSCAN = 100;
+
+/** Minimum child count before virtualization kicks in. */
+export const VIRTUALIZE_THRESHOLD = 20;
+
+/**
+ * Return the subset of `parent.children` whose layouts overlap the visible
+ * viewport of the parent container.
+ *
+ * - For non-scrollable containers every child is returned unchanged.
+ * - For scrollable containers the visible rect is the parent's layout bounds
+ *   offset by the current scroll position, expanded by OVERSCAN pixels on
+ *   each axis to prevent pop-in during fast scrolling.
+ *
+ * Children without a computed layout are always included (defensive -- they
+ * may need painting for side-effects).
+ */
+export function getVisibleChildren(
+  parent: VirtualNode,
+  viewport: Rectangle,
+): VirtualNode[] {
+  if (!isScrollable(parent)) {
+    return parent.children;
+  }
+
+  const ss = parent.scrollState;
+  if (!ss) {
+    return parent.children;
+  }
+
+  // The visible window in *content coordinates* (i.e. coordinates that
+  // children are laid out in). The viewport rectangle is already in the
+  // parent's coordinate space; we shift it by the scroll offset so that
+  // it matches where the children actually are in the layout.
+  const visibleMinX = viewport.x + ss.scrollX - OVERSCAN;
+  const visibleMaxX = viewport.x + ss.scrollX + viewport.width + OVERSCAN;
+  const visibleMinY = viewport.y + ss.scrollY - OVERSCAN;
+  const visibleMaxY = viewport.y + ss.scrollY + viewport.height + OVERSCAN;
+
+  const visible: VirtualNode[] = [];
+
+  for (const child of parent.children) {
+    // Always include children without layout (safety net).
+    if (!child.layout) {
+      visible.push(child);
+      continue;
+    }
+
+    const cl = child.layout;
+    const childMinX = cl.x;
+    const childMaxX = cl.x + cl.width;
+    const childMinY = cl.y;
+    const childMaxY = cl.y + cl.height;
+
+    // Standard AABB intersection test.
+    if (
+      childMaxX > visibleMinX &&
+      childMinX < visibleMaxX &&
+      childMaxY > visibleMinY &&
+      childMinY < visibleMaxY
+    ) {
+      visible.push(child);
+    }
+  }
+
+  return visible;
+}

package/src/dom/applicators/index.ts

@@ -274,7 +274,7 @@ export class ApplicatorRegistry {
    * Apply multiple applicators
    */
   applyAll(element: HTMLElement, applicators: Record<string, any>): void {
-    //console.log(`[ApplicatorRegistry] Applying applicators:`, applicators);
+
 
     // Group applicators by their base name (treat applicators like components with arguments)
     // e.g., "onClick.0", "onClick.id", "onClick.title" -> onClick: {0: ..., id: ..., title: ...}

package/src/dom/applicators/margin.ts

@@ -12,21 +12,67 @@ const getNumericValue = (value: any): number | null => {
   return null;
 };
 
+// Extract a CSS length value, supporting numbers, strings ("auto", "10px",
+// percentages), or `{0: value}` positional form. Returns null if no value.
+const getCssLengthValue = (value: any): string | null => {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "number") return `${value}px`;
+  if (typeof value === "string") return value;
+  if (typeof value === "object") {
+    if (value["0"] !== undefined) {
+      const inner = value["0"];
+      if (typeof inner === "number") return `${inner}px`;
+      if (typeof inner === "string") return inner;
+    }
+  }
+  return null;
+};
+
+// Format a value as a CSS length: numbers become "Npx", strings pass through
+const toCssLength = (v: any): string => {
+  if (typeof v === "number") return `${v}px`;
+  return String(v);
+};
+
+// Collect positional args ("0", "1", "2", "3") in order, stopping at the first gap.
+const positionalArgs = (value: any): any[] => {
+  const args: any[] = [];
+  for (let i = 0; value[String(i)] !== undefined; i++) {
+    args.push(value[String(i)]);
+  }
+  return args;
+};
+
 export const marginHandler: ApplicatorHandler = (el, value) => {
   if (typeof value === "number") {
     el.style.margin = `${value}px`;
-  } else if (typeof value === "object") {
-    // Handle {0: value} format from .margin(value)
-    if (value["0"] !== undefined && Object.keys(value).length === 1) {
-      el.style.margin = `${value["0"]}px`;
-    } else {
-      if (value.left !== undefined) el.style.marginLeft = `${value.left}px`;
-      if (value.right !== undefined) el.style.marginRight = `${value.right}px`;
-      if (value.top !== undefined) el.style.marginTop = `${value.top}px`;
-      if (value.bottom !== undefined) el.style.marginBottom = `${value.bottom}px`;
-    }
-  } else {
+    return;
+  }
+
+  if (typeof value !== "object" || value === null) {
     el.style.margin = String(value);
+    return;
+  }
+
+  // Named-keys form: { top, right, bottom, left }
+  if (
+    value.left !== undefined ||
+    value.right !== undefined ||
+    value.top !== undefined ||
+    value.bottom !== undefined
+  ) {
+    if (value.left !== undefined) el.style.marginLeft = toCssLength(value.left);
+    if (value.right !== undefined) el.style.marginRight = toCssLength(value.right);
+    if (value.top !== undefined) el.style.marginTop = toCssLength(value.top);
+    if (value.bottom !== undefined) el.style.marginBottom = toCssLength(value.bottom);
+    return;
+  }
+
+  // Positional form mirrors CSS shorthand: .margin(v), .margin(v, h),
+  // .margin(t, h, b), .margin(t, r, b, l)
+  const args = positionalArgs(value);
+  if (args.length > 0) {
+    el.style.margin = args.map(toCssLength).join(" ");
   }
 };
 

package/src/dom/applicators/padding.ts

@@ -12,21 +12,55 @@ const getNumericValue = (value: any): number | null => {
   return null;
 };
 
+// Format a value as a CSS length: numbers become "Npx", strings pass through
+const toCssLength = (v: any): string => {
+  if (typeof v === "number") return `${v}px`;
+  return String(v);
+};
+
+// Collect positional args ("0", "1", "2", "3") in order, stopping at the first
+// gap. Returns an empty array if no positional args are present.
+const positionalArgs = (value: any): any[] => {
+  const args: any[] = [];
+  for (let i = 0; value[String(i)] !== undefined; i++) {
+    args.push(value[String(i)]);
+  }
+  return args;
+};
+
 export const paddingHandler: ApplicatorHandler = (el, value) => {
   if (typeof value === "number") {
     el.style.padding = `${value}px`;
-  } else if (typeof value === "object") {
-    // Handle {0: value} format from .padding(value)
-    if (value["0"] !== undefined && Object.keys(value).length === 1) {
-      el.style.padding = `${value["0"]}px`;
-    } else {
-      if (value.left !== undefined) el.style.paddingLeft = `${value.left}px`;
-      if (value.right !== undefined) el.style.paddingRight = `${value.right}px`;
-      if (value.top !== undefined) el.style.paddingTop = `${value.top}px`;
-      if (value.bottom !== undefined) el.style.paddingBottom = `${value.bottom}px`;
-    }
-  } else {
+    return;
+  }
+
+  if (typeof value !== "object" || value === null) {
     el.style.padding = String(value);
+    return;
+  }
+
+  // Named-keys form: { top, right, bottom, left }
+  if (
+    value.left !== undefined ||
+    value.right !== undefined ||
+    value.top !== undefined ||
+    value.bottom !== undefined
+  ) {
+    if (value.left !== undefined) el.style.paddingLeft = toCssLength(value.left);
+    if (value.right !== undefined) el.style.paddingRight = toCssLength(value.right);
+    if (value.top !== undefined) el.style.paddingTop = toCssLength(value.top);
+    if (value.bottom !== undefined) el.style.paddingBottom = toCssLength(value.bottom);
+    return;
+  }
+
+  // Positional form: .padding(v), .padding(v, h), .padding(t, h, b), .padding(t, r, b, l)
+  // Mirrors CSS shorthand semantics so users can write
+  //   .padding(10, 16)         // -> 10px 16px
+  //   .padding(8, 12, 4)       // -> 8px 12px 4px
+  //   .padding(8, 12, 4, 6)    // -> 8px 12px 4px 6px
+  const args = positionalArgs(value);
+  if (args.length > 0) {
+    el.style.padding = args.map(toCssLength).join(" ");
   }
 };
 

package/src/dom/components/icon.ts

@@ -0,0 +1,84 @@
+/**
+ * Icon Component
+ *
+ * Renders SVG icons from pre-resolved path data injected by the engine.
+ * The engine resolves Icon("heart") → SVG paths at render time and sends
+ * the path data in the Create patch props. This handler just renders them.
+ */
+
+import type { ComponentHandler } from "./index.js";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+export const iconHandler: ComponentHandler = {
+  create(): HTMLElement {
+    const el = document.createElement("span");
+    el.style.display = "inline-flex";
+    el.style.alignItems = "center";
+    el.style.justifyContent = "center";
+    el.style.verticalAlign = "middle";
+    el.dataset.hypenType = "icon";
+    return el;
+  },
+
+  applyProps(el: HTMLElement, props: Record<string, any>): void {
+    // Server-resolved icon data (from engine's ResourceRegistry)
+    const paths: Array<{
+      d: string;
+      fill?: string;
+      stroke?: string;
+      strokeWidth?: number;
+      strokeLinecap?: string;
+      strokeLinejoin?: string;
+    }> = props.__iconPaths;
+    const viewBox: string = props.__iconViewBox || "0 0 24 24";
+
+    // Size and color from DSL props
+    const size = props.size || props["size.0"] || 24;
+    const color = props.color || props["color.0"] || "currentColor";
+
+    if (paths && Array.isArray(paths)) {
+      // Render from pre-resolved SVG path data
+      const svg = document.createElementNS(SVG_NS, "svg");
+      svg.setAttribute("xmlns", SVG_NS);
+      svg.setAttribute("width", String(size));
+      svg.setAttribute("height", String(size));
+      svg.setAttribute("viewBox", viewBox);
+      svg.setAttribute("fill", "none");
+      svg.style.display = "block";
+
+      for (const pathData of paths) {
+        const path = document.createElementNS(SVG_NS, "path");
+        path.setAttribute("d", pathData.d);
+        path.setAttribute("fill", pathData.fill || "none");
+        path.setAttribute(
+          "stroke",
+          (pathData.stroke || "currentColor") === "currentColor"
+            ? color
+            : pathData.stroke || color
+        );
+        if (pathData.strokeWidth != null) {
+          path.setAttribute("stroke-width", String(pathData.strokeWidth));
+        }
+        if (pathData.strokeLinecap) {
+          path.setAttribute("stroke-linecap", pathData.strokeLinecap);
+        }
+        if (pathData.strokeLinejoin) {
+          path.setAttribute("stroke-linejoin", pathData.strokeLinejoin);
+        }
+        svg.appendChild(path);
+      }
+
+      el.innerHTML = "";
+      el.appendChild(svg);
+    } else {
+      // Fallback: no resolved icon data — show placeholder
+      const name = props["0"] || props.name || "?";
+      el.textContent = name;
+      el.style.width = `${size}px`;
+      el.style.height = `${size}px`;
+      el.style.fontSize = `${Math.round(Number(size) * 0.6)}px`;
+      el.style.color = color;
+    }
+  },
+};

package/src/dom/components/index.ts

@@ -83,8 +83,10 @@ export class ComponentRegistry {
     const { routeHandler } = require("./route.js");
     const { hypenAppHandler } = require("./hypenapp.js");
     const { appHandler } = require("./app.js");
+    const { iconHandler } = require("./icon.js");
 
     this.register("app", appHandler);
+    this.register("icon", iconHandler);
     this.register("column", columnHandler);
     this.register("row", rowHandler);
     this.register("text", textHandler);