@hypen-space/web 0.4.950 → 0.4.952

package/src/client.ts

@@ -0,0 +1,88 @@
+/**
+ * createHypenClient — single-call wiring for renderer + engine.
+ *
+ * Replaces the boilerplate:
+ *   const renderer = new DOMRenderer(container, engine);
+ *   engine.onPatches((patches) => renderer.applyPatches(patches));
+ *
+ * Works with either a local Engine (`setRenderCallback`) or RemoteEngine
+ * (`onPatches`) — they expose different APIs but the same intent.
+ */
+
+import type { Patch } from "@hypen-space/core/types";
+import { DOMRenderer } from "./dom/renderer.js";
+import type { DebugConfig } from "./dom/debug.js";
+import { CanvasRenderer } from "./canvas/renderer.js";
+import type { CanvasRendererOptions } from "./canvas/types.js";
+
+interface PatchSourceLike {
+  dispatchAction(name: string, payload?: unknown): void;
+  onPatches?(callback: (patches: Patch[]) => void): unknown;
+  setRenderCallback?(callback: (patches: Patch[]) => void): void;
+}
+
+function attachPatchListener(
+  engine: PatchSourceLike,
+  callback: (patches: Patch[]) => void,
+): void {
+  if (typeof engine.onPatches === "function") {
+    engine.onPatches(callback);
+    return;
+  }
+  if (typeof engine.setRenderCallback === "function") {
+    engine.setRenderCallback(callback);
+    return;
+  }
+  throw new Error(
+    "createHypenClient: engine has neither onPatches() nor setRenderCallback() — cannot subscribe to patches.",
+  );
+}
+
+export interface DomClientOptions {
+  debug?: Partial<DebugConfig>;
+}
+
+export interface DomClient {
+  renderer: DOMRenderer;
+  destroy(): void;
+}
+
+export function createDomClient(
+  container: HTMLElement,
+  engine: PatchSourceLike,
+  options?: DomClientOptions,
+): DomClient {
+  const renderer = new DOMRenderer(container, engine as any, options?.debug);
+  attachPatchListener(engine, (patches) => renderer.applyPatches(patches));
+  return {
+    renderer,
+    destroy() {
+      // DOMRenderer has no destroy yet; clearing the container is the
+      // closest approximation. Patch subscriptions live on the engine —
+      // the caller controls engine lifetime, so we don't tear them down.
+      container.innerHTML = "";
+    },
+  };
+}
+
+export interface CanvasClientOptions extends Partial<CanvasRendererOptions> {}
+
+export interface CanvasClient {
+  renderer: CanvasRenderer;
+  destroy(): void;
+}
+
+export function createCanvasClient(
+  canvas: HTMLCanvasElement,
+  engine: PatchSourceLike,
+  options?: CanvasClientOptions,
+): CanvasClient {
+  const renderer = new CanvasRenderer(canvas, engine as any, options);
+  attachPatchListener(engine, (patches) => renderer.applyPatches(patches));
+  return {
+    renderer,
+    destroy() {
+      renderer.destroy();
+    },
+  };
+}

package/src/dom/README.md

@@ -37,18 +37,17 @@ 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 { DOMRenderer } from "@hypen-space/web";
+import { createHypenClient } from "@hypen-space/web/dom";
 
 const engine = new Engine();
 await engine.init();
 
-const renderer = new DOMRenderer(document.body, engine);
-engine.setRenderCallback((patches) => {
-  renderer.applyPatches(patches);
-});
+createHypenClient(document.body, engine);
 ```
 
 ### Server Import
@@ -79,7 +78,7 @@ All components are registered by default:
 ### Custom Components
 
 ```typescript
-const renderer = new DOMRenderer(document.body, engine);
+const { renderer } = createHypenClient(document.body, engine);
 const registry = renderer.getComponentRegistry();
 
 registry.register("mycomponent", {
@@ -141,7 +140,7 @@ Style applicators are registered by default:
 ### Custom Applicators
 
 ```typescript
-const renderer = new DOMRenderer(document.body, engine);
+const { renderer } = createHypenClient(document.body, engine);
 const applicators = renderer.getApplicatorRegistry();
 
 applicators.register("shadow", (el, value) => {
@@ -183,7 +182,7 @@ Canvas components have special applicators for drawing:
 
 ```typescript
 // Register canvas applicators
-const renderer = new DOMRenderer(document.body, engine);
+const { renderer } = createHypenClient(document.body, engine);
 const applicators = renderer.getApplicatorRegistry();
 
 // Canvas-specific applicators

package/src/dom/applicators/font.ts

@@ -5,8 +5,17 @@
 import type { ApplicatorHandler } from "./types.js";
 import { toCssLength } from "./size.js";
 
-// Track loaded Google Fonts to avoid duplicate link tags
-const loadedGoogleFonts = new Set<string>();
+// Track loaded Google Fonts per-document to avoid duplicate link tags
+const loadedGoogleFonts = new WeakMap<Document, Set<string>>();
+
+function getLoadedSet(doc: Document): Set<string> {
+  let set = loadedGoogleFonts.get(doc);
+  if (!set) {
+    set = new Set<string>();
+    loadedGoogleFonts.set(doc, set);
+  }
+  return set;
+}
 
 // System font keywords that shouldn't be loaded from Google Fonts
 const systemFontKeywords = new Set([
@@ -27,40 +36,42 @@ function isSystemFont(fontName: string): boolean {
 }
 
 /**
- * Load a Google Font by injecting a link tag.
+ * Load a Google Font by injecting a link tag into the given document.
  * @param fontName - The Google Font name (e.g., "Roboto", "Open Sans")
+ * @param doc - The Document to inject into.
  */
-function loadGoogleFont(fontName: string): void {
+function loadGoogleFont(fontName: string, doc: Document): void {
   const normalized = fontName.trim();
+  const loaded = getLoadedSet(doc);
 
   // Skip if already loaded or is a system font
-  if (loadedGoogleFonts.has(normalized) || isSystemFont(normalized)) {
+  if (loaded.has(normalized) || isSystemFont(normalized)) {
     return;
   }
 
   // Mark as loading to avoid duplicates
-  loadedGoogleFonts.add(normalized);
+  loaded.add(normalized);
 
   // Create link element for Google Fonts
-  const link = document.createElement("link");
+  const link = doc.createElement("link");
   link.rel = "stylesheet";
   link.href = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(normalized)}:wght@100;200;300;400;500;600;700;800;900&display=swap`;
 
   // Add to document head
-  document.head.appendChild(link);
+  doc.head.appendChild(link);
 }
 
 /**
  * Parse a fontFamily value and load any Google Fonts.
  * Returns a CSS-safe font-family string.
  */
-function processFontFamily(value: string): string {
+function processFontFamily(value: string, doc: Document): string {
   // Split by comma to handle font stacks
   const fonts = value.split(",").map(f => f.trim().replace(/["']/g, ""));
 
   for (const font of fonts) {
     if (!isSystemFont(font)) {
-      loadGoogleFont(font);
+      loadGoogleFont(font, doc);
     }
   }
 
@@ -86,7 +97,7 @@ export const fontHandlers: Record<string, ApplicatorHandler> = {
   fontFamily: (el, value) => {
     const fontValue = String(value);
     // Process font family and load Google Fonts as needed
-    el.style.fontFamily = processFontFamily(fontValue);
+    el.style.fontFamily = processFontFamily(fontValue, el.ownerDocument as Document);
   },
 
   textAlign: (el, value) => {
@@ -127,18 +138,20 @@ export const fontHandlers: Record<string, ApplicatorHandler> = {
 export const GoogleFonts = {
   /**
    * Preload a Google Font before it's used.
+   * Defaults to the global `document` if no doc is provided.
    */
-  preload: loadGoogleFont,
+  preload: (fontName: string, doc: Document = document) => loadGoogleFont(fontName, doc),
 
   /**
-   * Check if a font has been loaded.
+   * Check if a font has been loaded in the given document (defaults to global).
    */
-  isLoaded: (fontName: string) => loadedGoogleFonts.has(fontName.trim()),
+  isLoaded: (fontName: string, doc: Document = document) =>
+    getLoadedSet(doc).has(fontName.trim()),
 
   /**
-   * Get list of loaded fonts.
+   * Get list of loaded fonts for the given document (defaults to global).
    */
-  getLoadedFonts: () => Array.from(loadedGoogleFonts),
+  getLoadedFonts: (doc: Document = document) => Array.from(getLoadedSet(doc)),
 
   /**
    * Popular Google Fonts for reference.

package/src/dom/applicators/index.ts

@@ -53,26 +53,40 @@ const BREAKPOINTS: Record<string, string> = {
 };
 
 /**
- * Singleton stylesheet for variant CSS rules
+ * Per-document stylesheet for variant CSS rules
  */
-let variantStyleSheet: CSSStyleSheet | null = null;
+const variantStyleSheets = new Map<Document, CSSStyleSheet>();
 
 /**
- * Track inserted rules to avoid duplicates
+ * Track inserted rules to avoid duplicates (per-document)
  */
-const insertedRules = new Set<string>();
+const insertedRules = new Map<Document, Set<string>>();
 
 /**
- * Get or create the variant stylesheet
+ * Get or create the variant stylesheet for a document
  */
-function getVariantStyleSheet(): CSSStyleSheet {
-  if (!variantStyleSheet) {
-    const style = document.createElement('style');
+function getVariantStyleSheet(doc: Document): CSSStyleSheet {
+  let sheet = variantStyleSheets.get(doc);
+  if (!sheet) {
+    const style = doc.createElement('style');
     style.id = 'hypen-variants';
-    document.head.appendChild(style);
-    variantStyleSheet = style.sheet as CSSStyleSheet;
+    doc.head.appendChild(style);
+    sheet = style.sheet as CSSStyleSheet;
+    variantStyleSheets.set(doc, sheet);
   }
-  return variantStyleSheet;
+  return sheet;
+}
+
+/**
+ * Get or create the inserted-rules dedup set for a document
+ */
+function getInsertedRules(doc: Document): Set<string> {
+  let set = insertedRules.get(doc);
+  if (!set) {
+    set = new Set<string>();
+    insertedRules.set(doc, set);
+  }
+  return set;
 }
 
 /**
@@ -334,19 +348,21 @@ export class ApplicatorRegistry {
       const minWidth = BREAKPOINTS[breakpoint];
 
       if (minWidth) {
+        const doc = element.ownerDocument as Document;
+        const dedup = getInsertedRules(doc);
         const cssName = this.toKebabCase(prop);
         const cssValue = this.formatCssValue(cssName, value);
         const className = `hypen-${cssName.replace(/[^a-zA-Z0-9-]/g, '')}-${breakpoint}-${hashValue(value)}`;
         const ruleKey = `${className}:${cssValue}`;
 
         // Avoid duplicate rule insertion
-        if (!insertedRules.has(ruleKey)) {
-          const sheet = getVariantStyleSheet();
+        if (!dedup.has(ruleKey)) {
+          const sheet = getVariantStyleSheet(doc);
           sheet.insertRule(
             `@media (min-width: ${minWidth}) { .${className} { ${cssName}: ${cssValue}; } }`,
             sheet.cssRules.length
           );
-          insertedRules.add(ruleKey);
+          dedup.add(ruleKey);
         }
 
         element.classList.add(className);
@@ -362,19 +378,21 @@ export class ApplicatorRegistry {
       // Only handle known CSS pseudo-states
       const validStates = ['hover', 'focus', 'active', 'disabled', 'focus-visible', 'focus-within'];
       if (validStates.includes(state)) {
+        const doc = element.ownerDocument as Document;
+        const dedup = getInsertedRules(doc);
         const cssName = this.toKebabCase(prop);
         const cssValue = this.formatCssValue(cssName, value);
         const className = `hypen-${cssName.replace(/[^a-zA-Z0-9-]/g, '')}-${state}-${hashValue(value)}`;
         const ruleKey = `${className}:${cssValue}`;
 
         // Avoid duplicate rule insertion
-        if (!insertedRules.has(ruleKey)) {
-          const sheet = getVariantStyleSheet();
+        if (!dedup.has(ruleKey)) {
+          const sheet = getVariantStyleSheet(doc);
           sheet.insertRule(
             `.${className}:${state} { ${cssName}: ${cssValue}; }`,
             sheet.cssRules.length
           );
-          insertedRules.add(ruleKey);
+          dedup.add(ruleKey);
         }
 
         element.classList.add(className);

package/src/dom/canvas/index.ts

@@ -8,8 +8,8 @@ import type { ComponentHandler } from "../components/index.js";
 import type { ApplicatorHandler } from "../applicators/index.js";
 
 export const canvasHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("canvas");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("canvas");
     el.dataset.hypenType = "canvas";
     return el as any as HTMLElement;
   },

package/src/dom/components/app.ts

@@ -8,8 +8,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const appHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("div");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("div");
     el.style.display = "flex";
     el.style.flexDirection = "column";
     el.style.minHeight = "100vh";

package/src/dom/components/audio.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const audioHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("audio");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("audio");
     el.dataset.hypenType = "audio";
     return el as any as HTMLElement;
   },

package/src/dom/components/avatar.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const avatarHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("div");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("div");
     el.dataset.hypenType = "avatar";
     el.style.display = "inline-flex";
     el.style.alignItems = "center";
@@ -23,10 +23,11 @@ export const avatarHandler: ComponentHandler = {
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
+    const doc = el.ownerDocument as Document;
     // Image source - support named arg with .0 suffix, positional arg, or plain name
     const src = props["src.0"] || props["0"] || props.src || props.source;
     if (src !== undefined) {
-      const img = document.createElement("img");
+      const img = doc.createElement("img");
       img.src = String(src);
       img.style.width = "100%";
       img.style.height = "100%";

package/src/dom/components/badge.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const badgeHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("span");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("span");
     el.dataset.hypenType = "badge";
     el.style.display = "inline-block";
     el.style.padding = "4px 8px";

package/src/dom/components/button.ts

@@ -9,8 +9,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const buttonHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("button");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("button");
     // Reset default button styles for cross-platform consistency
     el.style.border = "none";
     el.style.background = "none";

package/src/dom/components/card.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const cardHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("div");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("div");
     el.dataset.hypenType = "card";
     el.style.backgroundColor = "#ffffff";
     el.style.borderRadius = "8px";

package/src/dom/components/center.ts

@@ -9,8 +9,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const centerHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("div");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("div");
     el.style.display = "flex";
     el.style.alignItems = "center";
     el.style.justifyContent = "center";

package/src/dom/components/checkbox.ts

@@ -5,15 +5,15 @@
 import type { ComponentHandler } from "./index.js";
 
 export const checkboxHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const wrapper = document.createElement("label");
+  create(doc: Document): HTMLElement {
+    const wrapper = doc.createElement("label");
     wrapper.dataset.hypenType = "checkbox";
     wrapper.style.display = "inline-flex";
     wrapper.style.alignItems = "center";
     wrapper.style.gap = "8px";
     wrapper.style.cursor = "pointer";
 
-    const input = document.createElement("input");
+    const input = doc.createElement("input");
     input.type = "checkbox";
     input.dataset.hypenCheckbox = "true";
     
@@ -23,6 +23,7 @@ export const checkboxHandler: ComponentHandler = {
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
+    const doc = el.ownerDocument as Document;
     const input = el.querySelector('input[type="checkbox"]') as HTMLInputElement;
     if (!input) return;
 
@@ -46,7 +47,7 @@ export const checkboxHandler: ComponentHandler = {
       textNodes.forEach(node => node.remove());
       
       // Add new label text
-      el.appendChild(document.createTextNode(String(label)));
+      el.appendChild(doc.createTextNode(String(label)));
     }
   },
 };

package/src/dom/components/column.ts

@@ -17,8 +17,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const columnHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("div");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("div");
     el.style.display = "flex";
     el.style.flexDirection = "column";
     el.style.alignItems = "stretch";

package/src/dom/components/container.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const containerHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("div");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("div");
     // Simple block container - wraps to content by default
     // Use .fillMaxWidth(true) to stretch
     el.dataset.hypenType = "container";

package/src/dom/components/divider.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const dividerHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("hr");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("hr");
     el.dataset.hypenType = "divider";
     el.style.border = "none";
     el.style.borderTop = "1px solid #e0e0e0";

package/src/dom/components/grid.ts

@@ -6,13 +6,13 @@
 
 import type { ComponentHandler } from "./index.js";
 
-// Inject global styles for grid children
-let gridStylesInjected = false;
-function ensureGridStyles(): void {
-  if (gridStylesInjected) return;
-  gridStylesInjected = true;
+// Inject global styles for grid children (per-document)
+const injectedDocs = new WeakSet<Document>();
+function ensureGridStyles(doc: Document): void {
+  if (injectedDocs.has(doc)) return;
+  injectedDocs.add(doc);
 
-  const style = document.createElement("style");
+  const style = doc.createElement("style");
   style.id = "hypen-grid-styles";
   style.textContent = `
     /* Grid children stretch to fill cells by default (matches Android behavior) */
@@ -21,14 +21,14 @@ function ensureGridStyles(): void {
       align-self: stretch;
     }
   `;
-  document.head.appendChild(style);
+  doc.head.appendChild(style);
 }
 
 export const gridHandler: ComponentHandler = {
-  create(): HTMLElement {
-    ensureGridStyles();
+  create(doc: Document): HTMLElement {
+    ensureGridStyles(doc);
 
-    const el = document.createElement("div");
+    const el = doc.createElement("div");
     el.style.display = "grid";
     el.dataset.hypenType = "grid";
     return el;

package/src/dom/components/heading.ts

@@ -5,17 +5,18 @@
 import type { ComponentHandler } from "./index.js";
 
 export const headingHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("h2");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("h2");
     el.dataset.hypenType = "heading";
     return el;
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
+    const doc = el.ownerDocument as Document;
     // Level property (1-6)
     if (props.level !== undefined) {
       const level = Math.max(1, Math.min(6, Number(props.level)));
-      const newEl = document.createElement(`h${level}`);
+      const newEl = doc.createElement(`h${level}`);
       newEl.dataset.hypenType = "heading";
       
       // Copy content and attributes

package/src/dom/components/hypenapp.ts

@@ -29,8 +29,8 @@ const activeInstances = new WeakMap<
 >();
 
 export const hypenAppHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("div");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("div");
     el.dataset.hypenType = "hypenapp";
     el.style.display = "contents"; // Don't affect layout
     return el;

package/src/dom/components/icon.ts

@@ -11,8 +11,8 @@ 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");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("span");
     el.style.display = "inline-flex";
     el.style.alignItems = "center";
     el.style.justifyContent = "center";
@@ -22,6 +22,7 @@ export const iconHandler: ComponentHandler = {
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
+    const doc = el.ownerDocument as Document;
     // Server-resolved icon data (from engine's ResourceRegistry)
     const paths: Array<{
       d: string;
@@ -39,7 +40,7 @@ export const iconHandler: ComponentHandler = {
 
     if (paths && Array.isArray(paths)) {
       // Render from pre-resolved SVG path data
-      const svg = document.createElementNS(SVG_NS, "svg");
+      const svg = doc.createElementNS(SVG_NS, "svg");
       svg.setAttribute("xmlns", SVG_NS);
       svg.setAttribute("width", String(size));
       svg.setAttribute("height", String(size));
@@ -48,7 +49,7 @@ export const iconHandler: ComponentHandler = {
       svg.style.display = "block";
 
       for (const pathData of paths) {
-        const path = document.createElementNS(SVG_NS, "path");
+        const path = doc.createElementNS(SVG_NS, "path");
         path.setAttribute("d", pathData.d);
         path.setAttribute("fill", pathData.fill || "none");
         path.setAttribute(

package/src/dom/components/image.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const imageHandler: ComponentHandler = {
-  create(): HTMLElement {
-    const el = document.createElement("img");
+  create(doc: Document): HTMLElement {
+    const el = doc.createElement("img");
     el.dataset.hypenType = "image";
     return el as any as HTMLElement;
   },