@pibbl/core 0.0.1

package/dist/lib/html/html-service.js

@@ -0,0 +1,281 @@
+import { GLOBAL_STATE } from "../global-state.js";
+import { withSignalWriteForbidden } from "../signals/graph.js";
+import { validateHtmlOverlay } from "./overlay-config.js";
+import { rectangleSvg } from "./portable-clips.js";
+const SVG = "http://www.w3.org/2000/svg";
+let nextId = 0;
+function requireHtmlService(owner) {
+  const root = owner.eventRoot;
+  if (!root.htmlOverlay || !root.canvas) throw new Error("HtmlBox requires an HTMLCanvasElement root configured with htmlOverlay.");
+  return root.html ??= new HtmlService(root);
+}
+class HtmlService {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  snapshots = /* @__PURE__ */ new Map();
+  pending;
+  transaction;
+  live = /* @__PURE__ */ new Set();
+  svg;
+  viewport;
+  disposed = false;
+  rendered = /* @__PURE__ */ new Set();
+  enterTransaction() {
+    const transaction = this.root.renderTransaction;
+    if (!transaction) throw new Error("HtmlBox requires an active render transaction.");
+    if (transaction === this.transaction) return;
+    this.transaction = transaction;
+    this.pending = new Map(this.snapshots);
+    this.rendered = /* @__PURE__ */ new Set();
+    transaction.onPublish(() => this.publish());
+    transaction.onFinish((success) => {
+      if (!success) this.reset();
+      this.pending = void 0;
+      this.transaction = void 0;
+      this.rendered.clear();
+    });
+  }
+  beginRender(instance) {
+    this.enterTransaction();
+    this.pending.set(instance, []);
+  }
+  suspend(instance) {
+    if (instance !== this.root.rootInstance) return;
+    this.enterTransaction();
+    this.root.renderTransaction.onPublish(() => {
+      this.root.focusPolicy?.suspendHtmlRegions?.();
+      if (this.viewport) this.viewport.hidden = true;
+      for (const slot of this.live) {
+        slot.region.active = false;
+        if (slot.shell) slot.shell.inert = true;
+      }
+    });
+  }
+  register(registration) {
+    assertEffects();
+    this.enterTransaction();
+    const owner = registration.slot.owner;
+    let entries = this.pending.get(owner);
+    if (!entries || entries === this.snapshots.get(owner)) this.pending.set(owner, entries = []);
+    entries.push(registration);
+    this.rendered.add(registration.slot);
+    this.root.focusPolicy?.observeHtmlRegion?.(registration.slot.region);
+  }
+  recordLayer(parent, child, bridge, opacity, composite) {
+    this.enterTransaction();
+    if (this.hasHosts(child)) {
+      assertEffects(composite);
+      const entries = this.pending.get(parent) ?? [];
+      if (!this.pending.has(parent)) this.pending.set(parent, entries);
+      entries.push({
+        child,
+        matrix: copy(bridge.transform),
+        clips: snapshotClips(bridge.clippingStack),
+        opacity,
+        bounds: { x: 0, y: 0, width: child.rootLayoutBox.width, height: child.rootLayoutBox.height }
+      });
+    }
+  }
+  hasHosts(instance) {
+    return (this.pending?.get(instance) ?? this.snapshots.get(instance) ?? []).length > 0;
+  }
+  release(slot) {
+    if (slot.disposed) return;
+    const transaction = this.root.renderTransaction;
+    if (transaction) {
+      transaction.onPublish(() => this.retire(slot));
+      transaction.onFinish((success) => {
+        if (!success) this.retire(slot);
+      });
+    } else this.retire(slot);
+  }
+  retire(slot) {
+    if (slot.disposed) return;
+    slot.disposed = true;
+    slot.region.active = false;
+    this.root.focusPolicy?.removeHtmlFocusRegion?.(slot.region);
+    try {
+      withSignalWriteForbidden("HtmlBox abort cleanup", () => slot.abort?.abort());
+    } finally {
+      slot.shell?.remove();
+      for (const clip of slot.clipping ?? []) clip.remove();
+      slot.clipping = [];
+      slot.update = void 0;
+      slot.region.content = void 0;
+      this.live.delete(slot);
+    }
+  }
+  publish() {
+    if (this.disposed || !this.pending) return;
+    const canvas = this.root.canvas;
+    const overlay = this.root.htmlOverlay;
+    validateHtmlOverlay(canvas, overlay);
+    const rootInstance = this.root.rootInstance;
+    if (rootInstance.surface.kind === "root" && (!rootInstance.surface.display.width || !rootInstance.surface.display.height)) {
+      this.root.focusPolicy?.suspendHtmlRegions?.();
+      if (this.viewport) this.viewport.hidden = true;
+      for (const slot of this.live) {
+        slot.region.active = false;
+        if (slot.shell) slot.shell.inert = true;
+      }
+      return;
+    }
+    const surface = rootInstance.surface.snapshot;
+    const rootMatrix = new DOMMatrix().scale(1 / surface.backingPixelsPerCssPixelX, 1 / surface.backingPixelsPerCssPixelY).multiply(surface.renderTransform);
+    const projections = [];
+    const visited = /* @__PURE__ */ new Set();
+    const walk = (instance, world, clips, opacity) => {
+      visited.add(instance);
+      for (const entry of this.pending.get(instance) ?? []) {
+        const inherited = clips.concat(entry.clips.map((clip) => {
+          if (clip.svgPath === void 0) throw new Error("HtmlBox cannot project a native Path2D clip. Use PathGeometry for clips enclosing HtmlBox.");
+          return { data: clip.svgPath, rule: clip.fillRule, matrix: world.multiply(clip.transform) };
+        }));
+        if ("child" in entry) {
+          const childWorld = world.multiply(entry.matrix);
+          walk(entry.child, childWorld, inherited.concat({ data: rectangleSvg(entry.bounds), matrix: childWorld, rule: "nonzero" }), opacity * entry.opacity);
+        } else if (!entry.slot.disposed) {
+          const hostWorld = world.multiply(entry.matrix);
+          if (![hostWorld.a, hostWorld.b, hostWorld.c, hostWorld.d, hostWorld.e, hostWorld.f].every(Number.isFinite)) throw new Error("HtmlBox transform must be finite.");
+          projections.push({ registration: entry, world: hostWorld, clips: inherited, opacity: opacity * entry.opacity });
+        }
+      }
+    };
+    walk(rootInstance, new DOMMatrix(), [], 1);
+    const desired = new Set(projections.map((p) => p.registration.slot));
+    for (const slot of this.live) if (!desired.has(slot)) this.retire(slot);
+    if (projections.length) this.ensureDOM();
+    if (this.viewport) this.viewport.hidden = false;
+    for (const [index, projection] of projections.entries()) this.apply(projection, rootMatrix, index);
+    this.snapshots = new Map([...this.pending].filter(([owner]) => visited.has(owner)));
+  }
+  ensureDOM() {
+    if (this.viewport) return;
+    const doc = this.root.canvas.ownerDocument;
+    this.viewport = doc.createElement("div");
+    this.viewport.dataset.pibblHtmlViewport = "";
+    this.viewport.style.cssText = "position:absolute;inset:0;overflow:clip;pointer-events:none";
+    this.svg = doc.createElementNS(SVG, "svg");
+    this.svg.setAttribute("width", "0");
+    this.svg.setAttribute("height", "0");
+    this.svg.setAttribute("aria-hidden", "true");
+    this.svg.style.cssText = "position:absolute;pointer-events:none";
+    this.root.htmlOverlay.append(this.svg, this.viewport);
+  }
+  apply(projection, rootMatrix, index) {
+    const { registration: r, world, clips, opacity } = projection;
+    const slot = r.slot;
+    const first = !slot.shell;
+    const doc = this.root.canvas.ownerDocument;
+    if (first) {
+      slot.shell = doc.createElement("div");
+      slot.shell.dataset.pibblHtmlBox = "";
+      slot.shell.style.cssText = "position:absolute;left:0;top:0;transform-origin:0 0;pointer-events:none;isolation:isolate";
+      slot.content = doc.createElement("div");
+      slot.content.dataset.pibblHtmlContent = "";
+      slot.content.style.cssText = "position:absolute;box-sizing:border-box";
+      slot.shell.append(slot.content);
+      this.viewport.append(slot.shell);
+      slot.clipping = [];
+      slot.abort = new doc.defaultView.AbortController();
+      slot.region.content = slot.content;
+      this.live.add(slot);
+    }
+    const matrix = rootMatrix.multiply(world);
+    const determinant = matrix.a * matrix.d - matrix.b * matrix.c;
+    const visible = r.border.width > 0 && r.border.height > 0 && determinant !== 0;
+    slot.shell.style.width = `${r.border.width}px`;
+    slot.shell.style.height = `${r.border.height}px`;
+    slot.shell.style.transform = cssMatrix(matrix);
+    slot.shell.style.zIndex = String(index);
+    slot.shell.style.opacity = String(opacity);
+    slot.shell.style.overflow = r.overflow;
+    slot.content.style.left = `${r.content.x}px`;
+    slot.content.style.top = `${r.content.y}px`;
+    slot.content.style.width = `${r.content.width}px`;
+    slot.content.style.height = `${r.content.height}px`;
+    slot.content.style.pointerEvents = r.interactive ? "auto" : "none";
+    slot.shell.inert = !visible || !r.interactive;
+    slot.shell.style.visibility = visible ? "visible" : "hidden";
+    slot.region.active = visible && r.interactive;
+    const corners = [[0, 0], [r.border.width, 0], [0, r.border.height], [r.border.width, r.border.height]].map(([x, y]) => world.transformPoint({ x, y }));
+    const xs = corners.map((p) => p.x), ys = corners.map((p) => p.y);
+    slot.region.rootBounds = { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs) - Math.min(...xs), height: Math.max(...ys) - Math.min(...ys) };
+    slot.callback = r.onFocusChange;
+    if (visible) this.applyClips(slot, clips, world.inverse());
+    try {
+      if (first) {
+        const update = withSignalWriteForbidden("HtmlBox mount", () => slot.mount(slot.content, r.data, slot.abort.signal));
+        if (typeof update !== "function") throw new TypeError("HtmlBox mount must synchronously return an update function.");
+        slot.update = update;
+      } else if (this.rendered.has(slot)) {
+        const result = withSignalWriteForbidden("HtmlBox update", () => slot.update(r.data));
+        if (result && typeof result.then === "function") throw new TypeError("HtmlBox update must be synchronous.");
+      }
+    } catch (error) {
+      this.retire(slot);
+      throw error;
+    }
+    slot.shell.inert = !visible || !r.interactive;
+    slot.shell.style.visibility = visible ? "visible" : "hidden";
+  }
+  applyClips(slot, clips, inverseWorld) {
+    const definitions = slot.clipping;
+    const doc = this.root.canvas.ownerDocument;
+    while (definitions.length < clips.length) {
+      const definition = doc.createElementNS(SVG, "clipPath");
+      definition.id = `pibbl-html-clip-${++nextId}`;
+      definition.setAttribute("clipPathUnits", "userSpaceOnUse");
+      definition.append(doc.createElementNS(SVG, "path"));
+      this.svg.append(definition);
+      definitions.push(definition);
+    }
+    clips.forEach((clip, index) => {
+      const definition = definitions[index];
+      const path = definition.firstElementChild;
+      setAttribute(path, "d", clip.data);
+      setAttribute(path, "clip-rule", clip.rule);
+      setAttribute(path, "transform", cssMatrix(inverseWorld.multiply(clip.matrix)));
+      if (index + 1 < clips.length) setAttribute(definition, "clip-path", `url(#${definitions[index + 1].id})`);
+      else definition.removeAttribute("clip-path");
+    });
+    slot.shell.style.clipPath = clips.length ? `url(#${definitions[0].id})` : "none";
+    while (definitions.length > clips.length) definitions.pop().remove();
+  }
+  reset() {
+    for (const slot of this.live) this.retire(slot);
+    this.snapshots.clear();
+    this.viewport?.remove();
+    this.svg?.remove();
+    this.viewport = void 0;
+    this.svg = void 0;
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.reset();
+  }
+}
+function assertEffects(composite = GLOBAL_STATE.renderContext?.globalCompositeOperation) {
+  if (GLOBAL_STATE.htmlFilterDepth || composite !== "source-over") throw new Error("HtmlBox cannot be enclosed by Canvas filters or non-default compositing. Use CSS effects inside its content instead.");
+}
+function copy(matrix) {
+  return new DOMMatrix([matrix.a, matrix.b, matrix.c, matrix.d, matrix.e, matrix.f]);
+}
+function snapshotClips(clips) {
+  return clips.map((clip) => ({ ...clip, transform: copy(clip.transform) }));
+}
+function cssMatrix(m) {
+  return `matrix(${m.a},${m.b},${m.c},${m.d},${m.e},${m.f})`;
+}
+function setAttribute(element, name, value) {
+  if (element.getAttribute(name) !== value) element.setAttribute(name, value);
+}
+export {
+  HtmlService,
+  requireHtmlService,
+  snapshotClips
+};
+//# sourceMappingURL=html-service.js.map

package/dist/lib/html/html-service.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/html/html-service.ts"],
+  "sourcesContent": ["import { GLOBAL_STATE } from '../global-state.js';\nimport { withSignalWriteForbidden } from '../signals/graph.js';\nimport type { PibblClippingStackEntry, PibblEventRoot, PibblInstance, PibblInteractionLayer, PibblRenderTransaction } from '../types.js';\nimport type { HtmlBoxRegistration, HtmlBoxSlot, HtmlBridge } from './types.js';\nimport { validateHtmlOverlay } from './overlay-config.js';\nimport { rectangleSvg } from './portable-clips.js';\n\nconst SVG = 'http://www.w3.org/2000/svg';\nlet nextId = 0;\ntype Entry = HtmlBoxRegistration | { child: PibblInstance; matrix: DOMMatrix; clips: readonly PibblClippingStackEntry[]; opacity: number; bounds: {x:number;y:number;width:number;height:number} };\ntype Clip = { data: string; matrix: DOMMatrix; rule: CanvasFillRule };\ninterface Projection { registration: HtmlBoxRegistration; world: DOMMatrix; clips: Clip[]; opacity: number; }\n\nexport function requireHtmlService(owner: PibblInstance): HtmlService {\n  const root = owner.eventRoot;\n  if (!root.htmlOverlay || !root.canvas) throw new Error('HtmlBox requires an HTMLCanvasElement root configured with htmlOverlay.');\n  return (root.html ??= new HtmlService(root)) as HtmlService;\n}\n\nexport class HtmlService implements HtmlBridge {\n  private snapshots = new Map<PibblInstance, Entry[]>();\n  private pending: Map<PibblInstance, Entry[]> | undefined;\n  private transaction: PibblRenderTransaction | undefined;\n  private live = new Set<HtmlBoxSlot>();\n  private svg: SVGSVGElement | undefined;\n  private viewport: HTMLDivElement | undefined;\n  private disposed = false;\n  private rendered = new Set<HtmlBoxSlot>();\n  constructor(private readonly root: PibblEventRoot) {}\n\n  private enterTransaction(): void {\n    const transaction = this.root.renderTransaction;\n    if (!transaction) throw new Error('HtmlBox requires an active render transaction.');\n    if (transaction === this.transaction) return;\n    this.transaction = transaction;\n    this.pending = new Map(this.snapshots);\n    this.rendered = new Set();\n    transaction.onPublish!(() => this.publish());\n    transaction.onFinish(success => {\n      if (!success) this.reset();\n      this.pending = undefined;\n      this.transaction = undefined;\n      this.rendered.clear();\n    });\n  }\n\n  beginRender(instance: PibblInstance): void {\n    this.enterTransaction();\n    this.pending!.set(instance, []);\n  }\n\n  suspend(instance: PibblInstance): void {\n    if (instance !== this.root.rootInstance) return;\n    this.enterTransaction();\n    this.root.renderTransaction!.onPublish!(() => {\n      this.root.focusPolicy?.suspendHtmlRegions?.();\n      if (this.viewport) this.viewport.hidden = true;\n      for (const slot of this.live) { slot.region.active = false; if (slot.shell) slot.shell.inert = true; }\n    });\n  }\n\n  register(registration: HtmlBoxRegistration): void {\n    assertEffects();\n    this.enterTransaction();\n    const owner = registration.slot.owner;\n    let entries = this.pending!.get(owner);\n    // A service first created during this render has no candidate array yet.\n    if (!entries || entries === this.snapshots.get(owner)) this.pending!.set(owner, entries = []);\n    entries.push(registration);\n    this.rendered.add(registration.slot);\n    this.root.focusPolicy?.observeHtmlRegion?.(registration.slot.region);\n  }\n\n  recordLayer(parent: PibblInstance, child: PibblInstance, bridge: PibblInteractionLayer, opacity: number, composite: GlobalCompositeOperation): void {\n    this.enterTransaction();\n    if (this.hasHosts(child)) {\n      assertEffects(composite);\n      const entries = this.pending!.get(parent) ?? [];\n      if (!this.pending!.has(parent)) this.pending!.set(parent, entries);\n      entries.push({ child, matrix: copy(bridge.transform), clips: snapshotClips(bridge.clippingStack), opacity,\n        bounds: { x: 0, y: 0, width: child.rootLayoutBox.width, height: child.rootLayoutBox.height } });\n    }\n  }\n\n  private hasHosts(instance: PibblInstance): boolean {\n    return (this.pending?.get(instance) ?? this.snapshots.get(instance) ?? []).length > 0;\n  }\n\n  release(slot: HtmlBoxSlot): void {\n    if (slot.disposed) return;\n    const transaction = this.root.renderTransaction;\n    if (transaction) {\n      transaction.onPublish!(() => this.retire(slot));\n      transaction.onFinish(success => { if (!success) this.retire(slot); });\n    } else this.retire(slot);\n  }\n\n  private retire(slot: HtmlBoxSlot): void {\n    if (slot.disposed) return;\n    slot.disposed = true;\n    slot.region.active = false;\n    this.root.focusPolicy?.removeHtmlFocusRegion?.(slot.region);\n    try { withSignalWriteForbidden('HtmlBox abort cleanup', () => slot.abort?.abort()); }\n    finally {\n      slot.shell?.remove();\n      for (const clip of slot.clipping ?? []) clip.remove();\n      slot.clipping = [];\n      slot.update = undefined;\n      slot.region.content = undefined;\n      this.live.delete(slot);\n    }\n  }\n\n  private publish(): void {\n    if (this.disposed || !this.pending) return;\n    const canvas = this.root.canvas!;\n    const overlay = this.root.htmlOverlay!;\n    validateHtmlOverlay(canvas, overlay);\n    const rootInstance = this.root.rootInstance!;\n    if (rootInstance.surface.kind === 'root' && (!rootInstance.surface.display.width || !rootInstance.surface.display.height)) {\n      this.root.focusPolicy?.suspendHtmlRegions?.();\n      if (this.viewport) this.viewport.hidden = true;\n      for (const slot of this.live) { slot.region.active = false; if (slot.shell) slot.shell.inert = true; }\n      return;\n    }\n    const surface = rootInstance.surface.snapshot!;\n    const rootMatrix = new DOMMatrix().scale(1 / surface.backingPixelsPerCssPixelX, 1 / surface.backingPixelsPerCssPixelY).multiply(surface.renderTransform);\n    const projections: Projection[] = [];\n    const visited = new Set<PibblInstance>();\n    const walk = (instance: PibblInstance, world: DOMMatrix, clips: Clip[], opacity: number) => {\n      visited.add(instance);\n      for (const entry of this.pending!.get(instance) ?? []) {\n        const inherited = clips.concat(entry.clips.map(clip => {\n          if (clip.svgPath === undefined) throw new Error('HtmlBox cannot project a native Path2D clip. Use PathGeometry for clips enclosing HtmlBox.');\n          return { data: clip.svgPath, rule: clip.fillRule, matrix: world.multiply(clip.transform) };\n        }));\n        if ('child' in entry) {\n          const childWorld = world.multiply(entry.matrix);\n          walk(entry.child, childWorld, inherited.concat({ data: rectangleSvg(entry.bounds), matrix: childWorld, rule: 'nonzero' }), opacity * entry.opacity);\n        } else if (!entry.slot.disposed) {\n          const hostWorld = world.multiply(entry.matrix);\n          if (![hostWorld.a,hostWorld.b,hostWorld.c,hostWorld.d,hostWorld.e,hostWorld.f].every(Number.isFinite)) throw new Error('HtmlBox transform must be finite.');\n          projections.push({ registration: entry, world: hostWorld, clips: inherited, opacity: opacity * entry.opacity });\n        }\n      }\n    };\n    walk(rootInstance, new DOMMatrix(), [], 1);\n    const desired = new Set(projections.map(p => p.registration.slot));\n    for (const slot of this.live) if (!desired.has(slot)) this.retire(slot);\n    if (projections.length) this.ensureDOM();\n    if (this.viewport) this.viewport.hidden = false;\n    for (const [index, projection] of projections.entries()) this.apply(projection, rootMatrix, index);\n    this.snapshots = new Map([...this.pending].filter(([owner]) => visited.has(owner)));\n  }\n\n  private ensureDOM(): void {\n    if (this.viewport) return;\n    const doc = this.root.canvas!.ownerDocument;\n    this.viewport = doc.createElement('div');\n    this.viewport.dataset.pibblHtmlViewport = '';\n    this.viewport.style.cssText = 'position:absolute;inset:0;overflow:clip;pointer-events:none';\n    this.svg = doc.createElementNS(SVG, 'svg');\n    this.svg.setAttribute('width', '0'); this.svg.setAttribute('height', '0');\n    this.svg.setAttribute('aria-hidden', 'true');\n    this.svg.style.cssText = 'position:absolute;pointer-events:none';\n    this.root.htmlOverlay!.append(this.svg, this.viewport);\n  }\n\n  private apply(projection: Projection, rootMatrix: DOMMatrix, index: number): void {\n    const { registration: r, world, clips, opacity } = projection;\n    const slot = r.slot;\n    const first = !slot.shell;\n    const doc = this.root.canvas!.ownerDocument;\n    if (first) {\n      slot.shell = doc.createElement('div'); slot.shell.dataset.pibblHtmlBox = '';\n      slot.shell.style.cssText = 'position:absolute;left:0;top:0;transform-origin:0 0;pointer-events:none;isolation:isolate';\n      slot.content = doc.createElement('div'); slot.content.dataset.pibblHtmlContent = '';\n      slot.content.style.cssText = 'position:absolute;box-sizing:border-box';\n      slot.shell.append(slot.content); this.viewport!.append(slot.shell);\n      slot.clipping = []; slot.abort = new (doc.defaultView!.AbortController)();\n      slot.region.content = slot.content;\n      this.live.add(slot);\n    }\n    const matrix = rootMatrix.multiply(world);\n    const determinant = matrix.a * matrix.d - matrix.b * matrix.c;\n    const visible = r.border.width > 0 && r.border.height > 0 && determinant !== 0;\n    slot.shell!.style.width = `${r.border.width}px`; slot.shell!.style.height = `${r.border.height}px`;\n    slot.shell!.style.transform = cssMatrix(matrix); slot.shell!.style.zIndex = String(index);\n    slot.shell!.style.opacity = String(opacity); slot.shell!.style.overflow = r.overflow;\n    slot.content!.style.left = `${r.content.x}px`; slot.content!.style.top = `${r.content.y}px`;\n    slot.content!.style.width = `${r.content.width}px`; slot.content!.style.height = `${r.content.height}px`;\n    slot.content!.style.pointerEvents = r.interactive ? 'auto' : 'none';\n    slot.shell!.inert = !visible || !r.interactive;\n    slot.shell!.style.visibility = visible ? 'visible' : 'hidden';\n    slot.region.active = visible && r.interactive;\n    const corners = [[0,0],[r.border.width,0],[0,r.border.height],[r.border.width,r.border.height]].map(([x,y]) => world.transformPoint({x,y}));\n    const xs = corners.map(p => p.x), ys = corners.map(p => p.y);\n    slot.region.rootBounds = { x: Math.min(...xs), y: Math.min(...ys), width: Math.max(...xs)-Math.min(...xs), height: Math.max(...ys)-Math.min(...ys) };\n    slot.callback = r.onFocusChange;\n    if (visible) this.applyClips(slot, clips, world.inverse());\n    try {\n      if (first) {\n        const update = withSignalWriteForbidden('HtmlBox mount', () => slot.mount(slot.content!, r.data, slot.abort!.signal));\n        if (typeof update !== 'function') throw new TypeError('HtmlBox mount must synchronously return an update function.');\n        slot.update = update;\n      } else if (this.rendered.has(slot)) {\n        const result: unknown = withSignalWriteForbidden('HtmlBox update', () => slot.update!(r.data));\n        if (result && typeof (result as PromiseLike<unknown>).then === 'function') throw new TypeError('HtmlBox update must be synchronous.');\n      }\n    } catch (error) { this.retire(slot); throw error; }\n    slot.shell!.inert = !visible || !r.interactive;\n    slot.shell!.style.visibility = visible ? 'visible' : 'hidden';\n  }\n\n  private applyClips(slot: HtmlBoxSlot, clips: Clip[], inverseWorld: DOMMatrix): void {\n    const definitions = slot.clipping!;\n    const doc = this.root.canvas!.ownerDocument;\n    while (definitions.length < clips.length) {\n      const definition = doc.createElementNS(SVG, 'clipPath');\n      definition.id = `pibbl-html-clip-${++nextId}`;\n      definition.setAttribute('clipPathUnits', 'userSpaceOnUse');\n      definition.append(doc.createElementNS(SVG, 'path'));\n      this.svg!.append(definition); definitions.push(definition);\n    }\n    clips.forEach((clip, index) => {\n      const definition = definitions[index]; const path = definition.firstElementChild!;\n      setAttribute(path, 'd', clip.data);\n      setAttribute(path, 'clip-rule', clip.rule);\n      setAttribute(path, 'transform', cssMatrix(inverseWorld.multiply(clip.matrix)));\n      if (index + 1 < clips.length) setAttribute(definition, 'clip-path', `url(#${definitions[index+1].id})`);\n      else definition.removeAttribute('clip-path');\n    });\n    slot.shell!.style.clipPath = clips.length ? `url(#${definitions[0].id})` : 'none';\n    while (definitions.length > clips.length) definitions.pop()!.remove();\n  }\n\n  private reset(): void {\n    for (const slot of this.live) this.retire(slot);\n    this.snapshots.clear();\n    this.viewport?.remove(); this.svg?.remove(); this.viewport = undefined; this.svg = undefined;\n  }\n  dispose(): void { if (this.disposed) return; this.disposed = true; this.reset(); }\n}\n\nfunction assertEffects(composite = GLOBAL_STATE.renderContext?.globalCompositeOperation): void {\n  if (GLOBAL_STATE.htmlFilterDepth || composite !== 'source-over') throw new Error('HtmlBox cannot be enclosed by Canvas filters or non-default compositing. Use CSS effects inside its content instead.');\n}\nfunction copy(matrix: DOMMatrixReadOnly): DOMMatrix { return new DOMMatrix([matrix.a,matrix.b,matrix.c,matrix.d,matrix.e,matrix.f]); }\nexport function snapshotClips(clips: readonly PibblClippingStackEntry[]): PibblClippingStackEntry[] {\n  return clips.map(clip => ({ ...clip, transform: copy(clip.transform) }));\n}\nfunction cssMatrix(m: DOMMatrixReadOnly): string { return `matrix(${m.a},${m.b},${m.c},${m.d},${m.e},${m.f})`; }\nfunction setAttribute(element: Element, name: string, value: string): void { if (element.getAttribute(name) !== value) element.setAttribute(name, value); }\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/html/overlay-config.d.ts

@@ -0,0 +1,3 @@
+import type { PibblInstance } from '../types.js';
+export declare function reserveHtmlOverlay(instance: PibblInstance, overlay: HTMLElement): void;
+export declare function validateHtmlOverlay(canvas: HTMLCanvasElement, overlay: HTMLElement): void;

package/dist/lib/html/overlay-config.js

@@ -0,0 +1,37 @@
+const leases = /* @__PURE__ */ new WeakMap();
+function reserveHtmlOverlay(instance, overlay) {
+  const canvas = instance.eventRoot.canvas;
+  if (!canvas || instance.parent) throw new Error("htmlOverlay requires an HTMLCanvasElement root, not a Layer.");
+  if (overlay?.nodeType !== 1 || overlay.namespaceURI !== "http://www.w3.org/1999/xhtml" || overlay.ownerDocument !== canvas.ownerDocument || !overlay.isConnected || !canvas.isConnected || canvas.parentElement !== overlay.parentElement || canvas.nextElementSibling !== overlay) {
+    throw new Error("htmlOverlay must be a connected HTML element immediately after the canvas in the same parent and document.");
+  }
+  if (leases.has(overlay) || overlay.childNodes.length) throw new Error("htmlOverlay must be empty and exclusively owned by one Pibbl root.");
+  leases.set(overlay, instance);
+  instance.eventRoot.htmlOverlay = overlay;
+  instance.mainTeardowns.add(() => {
+    instance.eventRoot.html?.dispose();
+    instance.eventRoot.html = void 0;
+    instance.eventRoot.htmlOverlay = void 0;
+    if (leases.get(overlay) === instance) leases.delete(overlay);
+  });
+}
+function validateHtmlOverlay(canvas, overlay) {
+  const view = canvas.ownerDocument.defaultView;
+  if (!canvas.isConnected || !overlay.isConnected || canvas.parentElement !== overlay.parentElement || canvas.nextElementSibling !== overlay) {
+    throw new Error("HtmlBox overlay and canvas must remain connected adjacent siblings.");
+  }
+  for (const element of [canvas, overlay]) {
+    const style = view.getComputedStyle(element);
+    if (style.transform !== "none" || ["paddingLeft", "paddingRight", "paddingTop", "paddingBottom", "borderLeftWidth", "borderRightWidth", "borderTopWidth", "borderBottomWidth"].some((key) => parseFloat(style[key]) !== 0)) {
+      throw new Error("HtmlBox canvas and overlay must have no independent CSS transform, padding, or border. Style their common wrapper instead.");
+    }
+  }
+  if (Math.abs(canvas.clientWidth - overlay.clientWidth) > 1 || Math.abs(canvas.clientHeight - overlay.clientHeight) > 1 || canvas.offsetLeft !== overlay.offsetLeft || canvas.offsetTop !== overlay.offsetTop) {
+    throw new Error("HtmlBox overlay must share the canvas content rectangle.");
+  }
+}
+export {
+  reserveHtmlOverlay,
+  validateHtmlOverlay
+};
+//# sourceMappingURL=overlay-config.js.map

package/dist/lib/html/overlay-config.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/html/overlay-config.ts"],
+  "sourcesContent": ["import type { PibblInstance } from '../types.js';\n\nconst leases = new WeakMap<HTMLElement, PibblInstance>();\n\nexport function reserveHtmlOverlay(instance: PibblInstance, overlay: HTMLElement): void {\n  const canvas = instance.eventRoot.canvas;\n  if (!canvas || instance.parent) throw new Error('htmlOverlay requires an HTMLCanvasElement root, not a Layer.');\n  if (overlay?.nodeType !== 1 || overlay.namespaceURI !== 'http://www.w3.org/1999/xhtml' ||\n      overlay.ownerDocument !== canvas.ownerDocument || !overlay.isConnected || !canvas.isConnected ||\n      canvas.parentElement !== overlay.parentElement || canvas.nextElementSibling !== overlay) {\n    throw new Error('htmlOverlay must be a connected HTML element immediately after the canvas in the same parent and document.');\n  }\n  if (leases.has(overlay) || overlay.childNodes.length) throw new Error('htmlOverlay must be empty and exclusively owned by one Pibbl root.');\n  leases.set(overlay, instance);\n  instance.eventRoot.htmlOverlay = overlay;\n  instance.mainTeardowns.add(() => {\n    instance.eventRoot.html?.dispose();\n    instance.eventRoot.html = undefined;\n    instance.eventRoot.htmlOverlay = undefined;\n    if (leases.get(overlay) === instance) leases.delete(overlay);\n  });\n}\n\nexport function validateHtmlOverlay(canvas: HTMLCanvasElement, overlay: HTMLElement): void {\n  const view = canvas.ownerDocument.defaultView!;\n  if (!canvas.isConnected || !overlay.isConnected || canvas.parentElement !== overlay.parentElement || canvas.nextElementSibling !== overlay) {\n    throw new Error('HtmlBox overlay and canvas must remain connected adjacent siblings.');\n  }\n  for (const element of [canvas, overlay]) {\n    const style = view.getComputedStyle(element);\n    if (style.transform !== 'none' || ['paddingLeft','paddingRight','paddingTop','paddingBottom','borderLeftWidth','borderRightWidth','borderTopWidth','borderBottomWidth'].some(key => parseFloat(style[key as keyof CSSStyleDeclaration] as string) !== 0)) {\n      throw new Error('HtmlBox canvas and overlay must have no independent CSS transform, padding, or border. Style their common wrapper instead.');\n    }\n  }\n  if (Math.abs(canvas.clientWidth - overlay.clientWidth) > 1 || Math.abs(canvas.clientHeight - overlay.clientHeight) > 1 || canvas.offsetLeft !== overlay.offsetLeft || canvas.offsetTop !== overlay.offsetTop) {\n    throw new Error('HtmlBox overlay must share the canvas content rectangle.');\n  }\n}\n"],
+  "mappings": "AAEA,MAAM,SAAS,oBAAI,QAAoC;AAEhD,SAAS,mBAAmB,UAAyB,SAA4B;AACtF,QAAM,SAAS,SAAS,UAAU;AAClC,MAAI,CAAC,UAAU,SAAS,OAAQ,OAAM,IAAI,MAAM,8DAA8D;AAC9G,MAAI,SAAS,aAAa,KAAK,QAAQ,iBAAiB,kCACpD,QAAQ,kBAAkB,OAAO,iBAAiB,CAAC,QAAQ,eAAe,CAAC,OAAO,eAClF,OAAO,kBAAkB,QAAQ,iBAAiB,OAAO,uBAAuB,SAAS;AAC3F,UAAM,IAAI,MAAM,4GAA4G;AAAA,EAC9H;AACA,MAAI,OAAO,IAAI,OAAO,KAAK,QAAQ,WAAW,OAAQ,OAAM,IAAI,MAAM,oEAAoE;AAC1I,SAAO,IAAI,SAAS,QAAQ;AAC5B,WAAS,UAAU,cAAc;AACjC,WAAS,cAAc,IAAI,MAAM;AAC/B,aAAS,UAAU,MAAM,QAAQ;AACjC,aAAS,UAAU,OAAO;AAC1B,aAAS,UAAU,cAAc;AACjC,QAAI,OAAO,IAAI,OAAO,MAAM,SAAU,QAAO,OAAO,OAAO;AAAA,EAC7D,CAAC;AACH;AAEO,SAAS,oBAAoB,QAA2B,SAA4B;AACzF,QAAM,OAAO,OAAO,cAAc;AAClC,MAAI,CAAC,OAAO,eAAe,CAAC,QAAQ,eAAe,OAAO,kBAAkB,QAAQ,iBAAiB,OAAO,uBAAuB,SAAS;AAC1I,UAAM,IAAI,MAAM,qEAAqE;AAAA,EACvF;AACA,aAAW,WAAW,CAAC,QAAQ,OAAO,GAAG;AACvC,UAAM,QAAQ,KAAK,iBAAiB,OAAO;AAC3C,QAAI,MAAM,cAAc,UAAU,CAAC,eAAc,gBAAe,cAAa,iBAAgB,mBAAkB,oBAAmB,kBAAiB,mBAAmB,EAAE,KAAK,SAAO,WAAW,MAAM,GAAgC,CAAW,MAAM,CAAC,GAAG;AACxP,YAAM,IAAI,MAAM,4HAA4H;AAAA,IAC9I;AAAA,EACF;AACA,MAAI,KAAK,IAAI,OAAO,cAAc,QAAQ,WAAW,IAAI,KAAK,KAAK,IAAI,OAAO,eAAe,QAAQ,YAAY,IAAI,KAAK,OAAO,eAAe,QAAQ,cAAc,OAAO,cAAc,QAAQ,WAAW;AAC5M,UAAM,IAAI,MAAM,0DAA0D;AAAA,EAC5E;AACF;",
+  "names": []
+}

package/dist/lib/html/portable-clips.d.ts

@@ -0,0 +1,4 @@
+import { PathGeometry } from '../geometry/path-geometry.js';
+import type { LayoutBox } from '../layout/types.js';
+export declare function portablePath(path: PathGeometry | Path2D): string | undefined;
+export declare function rectangleSvg(box: Readonly<LayoutBox>): string;

package/dist/lib/html/portable-clips.js

@@ -0,0 +1,20 @@
+import { PathGeometry } from "../geometry/path-geometry.js";
+import { toSvgPathData } from "../geometry/path-conversion.js";
+import { GLOBAL_STATE } from "../global-state.js";
+const snapshots = /* @__PURE__ */ new WeakMap();
+function portablePath(path) {
+  if (!GLOBAL_STATE.currentPibblInstance?.eventRoot.htmlOverlay || !(path instanceof PathGeometry)) return void 0;
+  const prior = snapshots.get(path);
+  if (prior?.revision === path.revision) return prior.data;
+  const data = toSvgPathData(path);
+  snapshots.set(path, { revision: path.revision, data });
+  return data;
+}
+function rectangleSvg(box) {
+  return `M${box.x} ${box.y}h${box.width}v${box.height}h${-box.width}Z`;
+}
+export {
+  portablePath,
+  rectangleSvg
+};
+//# sourceMappingURL=portable-clips.js.map

package/dist/lib/html/portable-clips.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/html/portable-clips.ts"],
+  "sourcesContent": ["import { PathGeometry } from '../geometry/path-geometry.js';\nimport { toSvgPathData } from '../geometry/path-conversion.js';\nimport { GLOBAL_STATE } from '../global-state.js';\nimport type { LayoutBox } from '../layout/types.js';\n\nconst snapshots = new WeakMap<PathGeometry, { revision: number; data: string }>();\nexport function portablePath(path: PathGeometry | Path2D): string | undefined {\n  if (!GLOBAL_STATE.currentPibblInstance?.eventRoot.htmlOverlay || !(path instanceof PathGeometry)) return undefined;\n  const prior = snapshots.get(path);\n  if (prior?.revision === path.revision) return prior.data;\n  const data = toSvgPathData(path);\n  snapshots.set(path, { revision: path.revision, data });\n  return data;\n}\nexport function rectangleSvg(box: Readonly<LayoutBox>): string {\n  return `M${box.x} ${box.y}h${box.width}v${box.height}h${-box.width}Z`;\n}\n"],
+  "mappings": "AAAA,SAAS,oBAAoB;AAC7B,SAAS,qBAAqB;AAC9B,SAAS,oBAAoB;AAG7B,MAAM,YAAY,oBAAI,QAA0D;AACzE,SAAS,aAAa,MAAiD;AAC5E,MAAI,CAAC,aAAa,sBAAsB,UAAU,eAAe,EAAE,gBAAgB,cAAe,QAAO;AACzG,QAAM,QAAQ,UAAU,IAAI,IAAI;AAChC,MAAI,OAAO,aAAa,KAAK,SAAU,QAAO,MAAM;AACpD,QAAM,OAAO,cAAc,IAAI;AAC/B,YAAU,IAAI,MAAM,EAAE,UAAU,KAAK,UAAU,KAAK,CAAC;AACrD,SAAO;AACT;AACO,SAAS,aAAa,KAAkC;AAC7D,SAAO,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,IAAI,CAAC,IAAI,KAAK;AACpE;",
+  "names": []
+}

package/dist/lib/html/types.d.ts

@@ -0,0 +1,110 @@
+import type { HtmlBox } from "../components/html-box.js";
+import type { GStyle } from '../components/g.js';
+import type { HtmlFocusRegion } from '../focus/html-focus-region.js';
+import type { PibblClippingStackEntry, PibblInstance, PibblInteractionLayer } from '../types.js';
+import type { LayoutBox } from '../layout/types.js';
+/**
+ * Updates mounted application HTML when the owning HtmlBox receives new props.
+ *
+ * @param props - Latest props for the mounted HTML content.
+ *
+ * @see {@link HtmlMountCallback}
+ */
+export type HtmlUpdateFunction<Props> = (props: Props) => void;
+/**
+ * Mounts application HTML into the supplied host and returns its prop-update callback; the abort
+ * signal marks teardown.
+ *
+ * @param element - Pibbl-owned host div into which application content may be mounted.
+ * @param initialProps - Props from the initial mount.
+ * @param signal - Lifetime signal aborted when the host is disposed.
+ * @returns An update callback for subsequent props; release application resources when the signal
+ * aborts. See {@link HtmlUpdateFunction} .
+ *
+ * @see {@link HtmlUpdateFunction}
+ * @see {@link HtmlBoxProps}
+ * @see {@link HtmlBox}
+ */
+export type HtmlMountCallback<Props> = (element: HTMLDivElement, initialProps: Props, signal: AbortSignal) => HtmlUpdateFunction<Props>;
+/**
+ * Focus state shared between an HTML host and Pibbl's logical focus management.
+ *
+ * @see {@link HtmlBoxProps}
+ */
+export interface HtmlBoxFocusState {
+    /**
+     * Whether an element inside the hosted HTML region currently has focus. See
+     * {@link HtmlBoxFocusState}.
+     */
+    readonly isFocusWithin: boolean;
+    /** Whether focus should be presented as keyboard-visible. See {@link HtmlBoxFocusState}. */
+    readonly isFocusVisible: boolean;
+}
+/**
+ * Props for a DOM-hosting region, including mount ownership, updates, and focus behavior.
+ *
+ * @see {@link HtmlMountCallback}
+ * @see {@link HtmlBoxFocusState}
+ * @see {@link HtmlBox}
+ */
+export interface HtmlBoxProps<Props> {
+    /**
+     * Application data supplied to the component or reported by the event. See {@link HtmlBoxProps}
+     * .
+     */
+    data: Props;
+    /** Creates mounted content and its owned lifecycle controls. See {@link HtmlMountCallback}. */
+    mount: HtmlMountCallback<Props>;
+    /** Whether this content participates in pointer targeting. See {@link HtmlBoxProps}. */
+    pointerEvents?: 'auto' | 'none';
+    /**
+     * Receives changes to focus within the hosted HTML region. See {@link HtmlBoxFocusState}.
+     * @param state - Current DOM and Pibbl focus ownership for the HTML region. See
+     * {@link HtmlBoxFocusState} .
+     */
+    onFocusChange?: (state: Readonly<HtmlBoxFocusState>) => void;
+}
+/**
+ * Layout and presentation of an application-owned HTML region anchored to Canvas geometry.
+ *
+ * @see {@link GStyle}
+ * @see {@link HtmlBox}
+ */
+export interface HtmlBoxStyle extends GStyle {
+    /** Opacity of the painted result. See {@link HtmlBoxStyle}. */
+    opacity?: number;
+}
+export interface HtmlBridge {
+    beginRender(instance: PibblInstance): void;
+    suspend(instance: PibblInstance): void;
+    recordLayer(parent: PibblInstance, child: PibblInstance, bridge: PibblInteractionLayer, opacity: number, composite: GlobalCompositeOperation): void;
+    dispose(): void;
+}
+export interface HtmlBoxRegistration {
+    slot: HtmlBoxSlot;
+    data: unknown;
+    matrix: DOMMatrix;
+    clips: readonly PibblClippingStackEntry[];
+    border: Readonly<LayoutBox>;
+    content: Readonly<LayoutBox>;
+    opacity: number;
+    interactive: boolean;
+    overflow: 'visible' | 'clip';
+    onFocusChange?: (state: Readonly<HtmlBoxFocusState>) => void;
+}
+export interface HtmlBoxSlot {
+    readonly owner: PibblInstance;
+    readonly mount: HtmlMountCallback<unknown>;
+    region: HtmlFocusRegion & {
+        content: HTMLDivElement | undefined;
+        rootBounds: Readonly<LayoutBox> | undefined;
+        active: boolean;
+    };
+    shell?: HTMLDivElement;
+    content?: HTMLDivElement;
+    clipping?: SVGClipPathElement[];
+    abort?: AbortController;
+    update?: HtmlUpdateFunction<unknown>;
+    disposed: boolean;
+    callback?: (state: Readonly<HtmlBoxFocusState>) => void;
+}

package/dist/lib/layout/absolute.d.ts

@@ -0,0 +1,57 @@
+import { ResponsiveStylePreparation, type PreparedQuery } from '../style/responsive.js';
+import type { PibblElement } from '../element/types.js';
+import type { BoxStyle, LayoutItemStyle, ResolvedBoxStyle } from '../style/types.js';
+import type { PibblNodeInput, StyleResolutionContext, SystemStyle } from '../types.js';
+import { type PibblStructuralEventProps } from '../components/structural-events.js';
+import type { LayoutBox } from './types.js';
+/**
+ * Supported geometry and presentation properties for Absolute.
+ *
+ * @see {@link BoxStyle}
+ * @see {@link LayoutItemStyle}
+ * @see {@link Absolute}
+ */
+export type AbsoluteStyle = BoxStyle & LayoutItemStyle;
+/**
+ * Authored inputs for Absolute, including the declared data and presentation options.
+ *
+ * @see {@link PibblNodeInput}
+ * @see {@link Absolute}
+ */
+export interface AbsoluteProps extends PibblStructuralEventProps {
+    /** Descendant content or the callback that supplies it. See {@link PibblNodeInput}. */
+    children: PibblNodeInput;
+}
+type LayoutReceiver = 'Absolute' | 'Overlay' | 'Flow' | 'Flex' | 'Grid';
+/**
+ * Describes absolute layout for JSX or createElement authoring.
+ *
+ * @param props - Authored component inputs, supplied through JSX or createElement. See the linked
+ * props and style types.
+ * @throws When called directly; Pibbl mounts this component through JSX or createElement.
+ *
+ * @see {@link AbsoluteProps}
+ * @see {@link AbsoluteStyle}
+ */
+export declare const Absolute: import("@pibbl/core").PibblPrimitiveComponent<AbsoluteProps, import("@pibbl/core").PrimitiveInput<AbsoluteProps, AbsoluteStyle>>;
+/** @internal Resolves a layout container without inspecting its children. */
+export declare function resolveContainerBox(style: Readonly<BoxStyle>, context: Readonly<StyleResolutionContext>, component: string, algorithm: string): ResolvedBoxStyle;
+export declare function placeAbsoluteChild(container: Readonly<LayoutBox>, child: PibblElement<any>): LayoutBox;
+/** @internal Carries normalized finite content size into the eventual render. */
+export declare function childWithUsedSize(child: PibblElement<any>, style: Readonly<SystemStyle>, width: number, height: number, receiverToken?: object, query?: PreparedQuery): PibblElement<any>;
+/** @internal Shared by the initial direct-child layout algorithms. */
+export declare function resolveDirectChildBox(container: Readonly<LayoutBox>, child: PibblElement<any>, algorithm: string, style?: Readonly<SystemStyle>): ResolvedBoxStyle;
+/** @internal Normalizes a descriptor without resolving or invoking its callback. */
+export declare function normalizeDirectChildStyle(child: PibblElement<any>, receiverToken?: object, queryBasis?: Readonly<LayoutBox>): Readonly<SystemStyle>;
+/** Carries responsive eligibility with this normalization, never with a token. */
+export declare function prepareDirectChildStyle(child: PibblElement<any>, receiverToken?: object, queryBasis?: Readonly<LayoutBox>): Readonly<SystemStyle> | ResponsiveStylePreparation<Readonly<SystemStyle>>;
+/** @internal Converts source-order descriptors to stable placed children. */
+export declare function placeDirectChildren(children: readonly PibblElement<any>[], contentBox: Readonly<LayoutBox>, place: (child: PibblElement<any>) => LayoutBox | {
+    box: LayoutBox;
+    element: PibblElement<any>;
+}, overflow: 'visible' | 'clip'): PibblElement<any>[];
+/** @internal Prepares one finite direct-child sequence for a layout boundary. */
+export declare function materializeLayoutChildren(children: PibblNodeInput, receiver: LayoutReceiver): readonly PibblElement<any>[];
+/** @internal Shares one direct sequence between an occurrence's measurement and paint. */
+export declare function prepareLayoutChildren(children: PibblNodeInput, receiver: LayoutReceiver): readonly PibblElement<any>[];
+export {};