@pibbl/core 0.0.1

package/dist/lib/components/img.js

@@ -0,0 +1,150 @@
+import { resolveTexturePaint } from "../textures/texture-protocol.js";
+import { definePrimitive } from "../define-primitive.js";
+import { useRectPath } from "../hooks/use-rect-path.js";
+import { useReaction } from "../hooks/use-reaction.js";
+import { useSignal } from "../hooks/use-signal.js";
+import { resolveLength } from "../style/resolve-length.js";
+import {
+  resolveOptionalLength,
+  stripLayoutParticipation
+} from "../style/resolve-built-in.js";
+import { registerOpaqueStyleProperties } from "../style/resolve-dispatch.js";
+import { adjustRectangleToPixelGrid } from "../util/pixel-grid-adjustments.js";
+import { wireCommonEvents } from "../util/wire-common-events.js";
+function renderImage(props, style, ctx) {
+  let {
+    src,
+    x = 0,
+    y = 0,
+    width,
+    height,
+    stroke,
+    strokeWidth,
+    opacity,
+    cursor,
+    alignToPixelGrid
+  } = style;
+  if (opacity !== void 0) {
+    ctx.globalAlpha = ctx.globalAlpha * opacity;
+  }
+  const loadedImage = useSignal(null);
+  const loadedImageValue = loadedImage.get();
+  const image = loadedImageValue && loadedImageValue.src === src ? loadedImageValue.element : null;
+  useReaction(() => {
+    let active = true;
+    const BrowserImage = globalThis.Image;
+    const element = new BrowserImage();
+    const settle = () => {
+      active = false;
+      element.onload = null;
+      element.onerror = null;
+    };
+    element.onload = () => {
+      if (!active) return;
+      settle();
+      loadedImage.set({ src, element });
+    };
+    element.onerror = () => {
+      if (!active) return;
+      settle();
+      loadedImage.set(null);
+    };
+    element.src = src;
+    return () => {
+      active = false;
+      element.onload = null;
+      element.onerror = null;
+      element.removeAttribute("src");
+    };
+  }, [src]);
+  width = width ?? image?.naturalWidth ?? image?.width ?? 0;
+  height = height ?? image?.naturalHeight ?? image?.height ?? 0;
+  if (alignToPixelGrid) {
+    ({ x, y, width, height } = adjustRectangleToPixelGrid(
+      strokeWidth ?? 0,
+      x,
+      y,
+      width,
+      height,
+      alignToPixelGrid
+    ));
+  }
+  const imagePath = useRectPath(x, y, width, height);
+  if (image) {
+    ctx.drawImage(image, x, y, width, height);
+  }
+  if (stroke && strokeWidth) {
+    ctx.strokeStyle = resolveTexturePaint(stroke, ctx, { x, y, width, height });
+    ctx.lineWidth = strokeWidth;
+    ctx.stroke(imagePath);
+  }
+  wireCommonEvents(
+    props,
+    imagePath,
+    true,
+    strokeWidth ?? 0,
+    cursor,
+    { x, y, width, height }
+  );
+}
+const Image = definePrimitive(renderImage, {
+  resolveStyle: resolveImageStyle,
+  measure: measureImage
+});
+registerOpaqueStyleProperties(Image, ["src", "stroke", "cursor"]);
+function resolveImageStyle(style, context) {
+  return {
+    ...stripLayoutParticipation(style),
+    x: 0,
+    y: 0,
+    width: resolveOptionalLength(
+      style.width,
+      context.percentageBasis.width,
+      "width",
+      context
+    ),
+    height: resolveOptionalLength(
+      style.height,
+      context.percentageBasis.height,
+      "height",
+      context
+    )
+  };
+}
+function measureImage({
+  style,
+  constraints
+}) {
+  if (style.width === void 0 || style.width === "auto" || style.height === void 0 || style.height === "auto") {
+    return {
+      status: "unsupported",
+      reason: "Image natural dimensions are unavailable during pure measurement"
+    };
+  }
+  const context = {
+    component: "Image",
+    algorithm: "measurement",
+    constraints
+  };
+  return {
+    status: "measured",
+    size: {
+      width: resolveLength(
+        style.width,
+        constraints.maxWidth,
+        "width",
+        context
+      ),
+      height: resolveLength(
+        style.height,
+        constraints.maxHeight,
+        "height",
+        context
+      )
+    }
+  };
+}
+export {
+  Image
+};
+//# sourceMappingURL=img.js.map

package/dist/lib/components/img.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/components/img.ts"],
+  "sourcesContent": ["import { resolveTexturePaint } from '../textures/texture-protocol.js';\nimport { definePrimitive } from '../define-primitive.js';\nimport type {\n  PibblEventFocusOptions,\n  PibblEventHandlers,\n  PibblEventParticipationOptions,\n} from '../events/types.js';\nimport { useRectPath } from '../hooks/use-rect-path.js';\nimport { useReaction } from '../hooks/use-reaction.js';\nimport { useSignal } from '../hooks/use-signal.js';\nimport type {\n  PibblPhysics2DPropExtension,\n  MeasureInput,\n  MeasureResult,\n  RenderingContext2D,\n  StyleResolutionContext,\n} from '../types.js';\nimport { resolveLength } from '../style/resolve-length.js';\nimport {\n  resolveOptionalLength,\n  stripLayoutParticipation,\n} from '../style/resolve-built-in.js';\nimport { registerOpaqueStyleProperties } from '../style/resolve-dispatch.js';\nimport type { ImgStyle, ResolvedImgStyle } from '../style/types.js';\nimport { adjustRectangleToPixelGrid } from '../util/pixel-grid-adjustments.js';\nimport { wireCommonEvents } from '../util/wire-common-events.js';\n\n/**\n * Authored inputs for Image, including the declared data and presentation options.\n *\n * @see {@link PibblEventHandlers}\n * @see {@link PibblEventParticipationOptions}\n * @see {@link PibblPhysics2DPropExtension}\n * @see {@link Image}\n */\nexport interface ImageProps extends PibblEventHandlers, PibblEventFocusOptions, PibblEventParticipationOptions, PibblPhysics2DPropExtension {}\n\ninterface LoadedImage {\n  src: string;\n  element: HTMLImageElement;\n}\n\nfunction renderImage(\n  props: ImageProps,\n  style: Readonly<ResolvedImgStyle>,\n  ctx: RenderingContext2D,\n) {\n  let {\n    src,\n    x = 0,\n    y = 0,\n    width,\n    height,\n    stroke,\n    strokeWidth,\n    opacity,\n    cursor,\n    alignToPixelGrid,\n  } = style;\n\n  if (opacity !== undefined) {\n    ctx.globalAlpha = ctx.globalAlpha * opacity;\n  }\n\n  const loadedImage = useSignal<LoadedImage | null>(null);\n  const loadedImageValue = loadedImage.get();\n  const image =\n    loadedImageValue && loadedImageValue.src === src ?\n      loadedImageValue.element : null;\n\n  useReaction(() => {\n    let active = true;\n    const BrowserImage = globalThis.Image;\n    const element = new BrowserImage();\n    const settle = () => {\n      active = false;\n      element.onload = null;\n      element.onerror = null;\n    };\n\n    element.onload = () => {\n      if (!active) return;\n      settle();\n      loadedImage.set({ src, element });\n    };\n    element.onerror = () => {\n      if (!active) return;\n      settle();\n      loadedImage.set(null);\n    };\n    element.src = src;\n\n    return () => {\n      active = false;\n      element.onload = null;\n      element.onerror = null;\n      element.removeAttribute('src');\n    };\n  }, [src]);\n\n  width = width ?? image?.naturalWidth ?? image?.width ?? 0;\n  height = height ?? image?.naturalHeight ?? image?.height ?? 0;\n\n  if (alignToPixelGrid) {\n    ({ x, y, width, height } = adjustRectangleToPixelGrid(\n      strokeWidth ?? 0,\n      x,\n      y,\n      width,\n      height,\n      alignToPixelGrid,\n    ));\n  }\n\n  const imagePath = useRectPath(x, y, width, height);\n\n  if (image) {\n    ctx.drawImage(image, x, y, width, height);\n  }\n\n  if (stroke && strokeWidth) {\n    ctx.strokeStyle = resolveTexturePaint(stroke, ctx, { x, y, width, height });\n    ctx.lineWidth = strokeWidth;\n    ctx.stroke(imagePath);\n  }\n\n  wireCommonEvents(\n    props,\n    imagePath,\n    true,\n    strokeWidth ?? 0,\n    cursor,\n    { x, y, width, height },\n  );\n}\n\n/**\n * Describes a Canvas image primitive for JSX or createElement authoring.\n *\n * @param props - Authored component inputs, supplied through JSX or createElement. See the linked\n * props and style types.\n * @throws When called directly; Pibbl mounts this component through JSX or createElement.\n *\n * @see {@link ImageProps}\n * @see {@link ImgStyle}\n */\nexport const Image = definePrimitive<\n  ImageProps,\n  ImgStyle,\n  ImgStyle,\n  ResolvedImgStyle\n>(renderImage, {\n  resolveStyle: resolveImageStyle,\n  measure: measureImage,\n});\nregisterOpaqueStyleProperties(Image, ['src', 'stroke', 'cursor']);\n\nfunction resolveImageStyle(\n  style: Readonly<ImgStyle>,\n  context: Readonly<StyleResolutionContext>,\n): ResolvedImgStyle {\n  return {\n    ...stripLayoutParticipation(style),\n    x: 0,\n    y: 0,\n    width: resolveOptionalLength(\n      style.width,\n      context.percentageBasis.width,\n      'width',\n      context,\n    ),\n    height: resolveOptionalLength(\n      style.height,\n      context.percentageBasis.height,\n      'height',\n      context,\n    ),\n  } as ResolvedImgStyle;\n}\n\nfunction measureImage({\n  style,\n  constraints,\n}: MeasureInput<ImageProps, ImgStyle>): MeasureResult {\n  if (\n    style.width === undefined || style.width === 'auto' ||\n    style.height === undefined || style.height === 'auto'\n  ) {\n    return {\n      status: 'unsupported',\n      reason: 'Image natural dimensions are unavailable during pure measurement',\n    };\n  }\n  const context = {\n    component: 'Image',\n    algorithm: 'measurement' as const,\n    constraints,\n  };\n  return {\n    status: 'measured',\n    size: {\n      width: resolveLength(\n        style.width,\n        constraints.maxWidth,\n        'width',\n        context,\n      )!,\n      height: resolveLength(\n        style.height,\n        constraints.maxHeight,\n        'height',\n        context,\n      )!,\n    },\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/components/layer-node-equality.d.ts

@@ -0,0 +1,65 @@
+import { type PibblElementEnhancerDescriptor } from '../element-enhancers.js';
+import type { PibblElement, PibblNodeInput } from '../element/types.js';
+interface LayerElementSnapshot {
+    readonly kind: 'element';
+    readonly type: PibblElement<any>['type'];
+    readonly key: string | undefined;
+    readonly enhancers: readonly PibblElementEnhancerDescriptor[];
+    readonly nonChildProps: readonly LayerPropertySnapshot[];
+    readonly style: readonly LayerPropertySnapshot[];
+    readonly children: LayerNodeSnapshot;
+}
+interface LayerArraySnapshot {
+    readonly kind: 'array';
+    readonly children: readonly LayerNodeSnapshot[];
+}
+interface LayerOpaqueSnapshot {
+    readonly kind: 'opaque';
+    readonly value: unknown;
+}
+interface LayerPropertySnapshot {
+    readonly key: PropertyKey;
+    readonly value: unknown;
+}
+/**
+ * Captured element structure used to compare managed-layer inputs.
+ *
+ * @see {@link haveSameLayerNodeTree}
+ * @see {@link snapshotLayerNodeTree}
+ */
+export type LayerNodeSnapshot = LayerElementSnapshot | LayerArraySnapshot | LayerOpaqueSnapshot;
+/**
+ * Materializes retained Layer children once before a private renderer owns them.
+ *
+ * @param node - Recursive child structure to materialize. See {@link PibblNodeInput}.
+ * @param receiver - Receiver name used in invalid-child diagnostics.
+ * @returns The ordered element descriptors retained by the layer. See {@link PibblElement}.
+ *
+ * @see {@link PibblNodeInput}
+ * @see {@link PibblElement}
+ */
+export declare function materializeRetainedLayerChildren(node: PibblNodeInput, receiver: string): readonly PibblElement<any>[];
+/**
+ * Captures Layer's successfully rendered tree without retaining mutable
+ * author-owned containers. Direct Layer children are already materialized;
+ * nested opaque iterables remain identity values and are never evaluated.
+ *
+ * @param node - Node tree to record.
+ * @returns A snapshot used for subsequent structural equality checks. See
+ * {@link LayerNodeSnapshot} .
+ *
+ * @see {@link LayerNodeSnapshot}
+ */
+export declare function snapshotLayerNodeTree(node: unknown): LayerNodeSnapshot;
+/**
+ * Compares an immutable successful-render snapshot with an already-materialized
+ * candidate tree. Opaque nested iterables compare only by identity.
+ *
+ * @param snapshot - Previously recorded node-tree snapshot, if any. See {@link LayerNodeSnapshot}.
+ * @param node - Current node tree to compare.
+ * @returns Whether the current tree matches the retained snapshot.
+ *
+ * @see {@link LayerNodeSnapshot}
+ */
+export declare function haveSameLayerNodeTree(snapshot: LayerNodeSnapshot | undefined, node: unknown): boolean;
+export {};

package/dist/lib/components/layer-node-equality.js

@@ -0,0 +1,91 @@
+import {
+  getElementEnhancerDescriptors
+} from "../element-enhancers.js";
+import { materializeContainerChildren } from "../element/children.js";
+import { isPibblElement } from "../element/create-element.js";
+function materializeRetainedLayerChildren(node, receiver) {
+  return materializeContainerChildren(node, receiver);
+}
+function snapshotLayerNodeTree(node) {
+  if (isPibblElement(node)) {
+    const props = splitProps(node.props);
+    return Object.freeze({
+      kind: "element",
+      type: node.type,
+      key: node.key,
+      enhancers: Object.freeze([...getElementEnhancerDescriptors(node)]),
+      nonChildProps: snapshotProperties(props.nonChild),
+      style: snapshotProperties(props.style),
+      children: snapshotLayerNodeTree(props.children)
+    });
+  }
+  if (Array.isArray(node)) {
+    return Object.freeze({
+      kind: "array",
+      children: Object.freeze(node.map(snapshotLayerNodeTree))
+    });
+  }
+  return Object.freeze({ kind: "opaque", value: node });
+}
+function haveSameLayerNodeTree(snapshot, node) {
+  if (!snapshot) return false;
+  switch (snapshot.kind) {
+    case "element":
+      return isPibblElement(node) && haveSameLayerElement(snapshot, node);
+    case "array":
+      return Array.isArray(node) && snapshot.children.length === node.length && snapshot.children.every(
+        (child, index) => haveSameLayerNodeTree(child, node[index])
+      );
+    case "opaque":
+      return snapshot.value === node;
+  }
+}
+function haveSameLayerElement(snapshot, element) {
+  if (snapshot.type !== element.type || snapshot.key !== element.key) {
+    return false;
+  }
+  const enhancers = getElementEnhancerDescriptors(element);
+  if (snapshot.enhancers.length !== enhancers.length || !snapshot.enhancers.every(
+    (descriptor, index) => descriptor === enhancers[index]
+  )) {
+    return false;
+  }
+  const props = splitProps(element.props);
+  return haveSameProperties(snapshot.nonChildProps, props.nonChild) && haveSameProperties(snapshot.style, props.style) && haveSameLayerNodeTree(snapshot.children, props.children);
+}
+function snapshotProperties(value) {
+  return Object.freeze(enumerableOwnKeys(value).map((key) => Object.freeze({
+    key,
+    value: value[key]
+  })));
+}
+function haveSameProperties(snapshot, value) {
+  const keys = enumerableOwnKeys(value);
+  return snapshot.length === keys.length && snapshot.every(
+    (property) => Object.prototype.propertyIsEnumerable.call(value, property.key) && value[property.key] === property.value
+  );
+}
+function enumerableOwnKeys(value) {
+  return Reflect.ownKeys(value).filter(
+    (key) => Object.prototype.propertyIsEnumerable.call(value, key)
+  );
+}
+function splitProps(props) {
+  const {
+    children,
+    style,
+    ...nonChild
+  } = props;
+  return {
+    children,
+    nonChild,
+    style: style ?? EMPTY_PROPS
+  };
+}
+const EMPTY_PROPS = Object.freeze({});
+export {
+  haveSameLayerNodeTree,
+  materializeRetainedLayerChildren,
+  snapshotLayerNodeTree
+};
+//# sourceMappingURL=layer-node-equality.js.map

package/dist/lib/components/layer-node-equality.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/components/layer-node-equality.ts"],
+  "sourcesContent": ["import {\n  getElementEnhancerDescriptors,\n  type PibblElementEnhancerDescriptor,\n} from '../element-enhancers.js';\nimport { materializeContainerChildren } from '../element/children.js';\nimport { isPibblElement } from '../element/create-element.js';\nimport type { PibblElement, PibblNodeInput } from '../element/types.js';\n\ninterface LayerElementSnapshot {\n  readonly kind: 'element';\n  readonly type: PibblElement<any>['type'];\n  readonly key: string | undefined;\n  readonly enhancers: readonly PibblElementEnhancerDescriptor[];\n  readonly nonChildProps: readonly LayerPropertySnapshot[];\n  readonly style: readonly LayerPropertySnapshot[];\n  readonly children: LayerNodeSnapshot;\n}\n\ninterface LayerArraySnapshot {\n  readonly kind: 'array';\n  readonly children: readonly LayerNodeSnapshot[];\n}\n\ninterface LayerOpaqueSnapshot {\n  readonly kind: 'opaque';\n  readonly value: unknown;\n}\n\ninterface LayerPropertySnapshot {\n  readonly key: PropertyKey;\n  readonly value: unknown;\n}\n\n/**\n * Captured element structure used to compare managed-layer inputs.\n *\n * @see {@link haveSameLayerNodeTree}\n * @see {@link snapshotLayerNodeTree}\n */\nexport type LayerNodeSnapshot =\n  | LayerElementSnapshot\n  | LayerArraySnapshot\n  | LayerOpaqueSnapshot;\n\n/**\n * Materializes retained Layer children once before a private renderer owns them.\n *\n * @param node - Recursive child structure to materialize. See {@link PibblNodeInput}.\n * @param receiver - Receiver name used in invalid-child diagnostics.\n * @returns The ordered element descriptors retained by the layer. See {@link PibblElement}.\n *\n * @see {@link PibblNodeInput}\n * @see {@link PibblElement}\n */\nexport function materializeRetainedLayerChildren(\n  node: PibblNodeInput,\n  receiver: string,\n): readonly PibblElement<any>[] {\n  return materializeContainerChildren(node, receiver);\n}\n\n/**\n * Captures Layer's successfully rendered tree without retaining mutable\n * author-owned containers. Direct Layer children are already materialized;\n * nested opaque iterables remain identity values and are never evaluated.\n *\n * @param node - Node tree to record.\n * @returns A snapshot used for subsequent structural equality checks. See\n * {@link LayerNodeSnapshot} .\n *\n * @see {@link LayerNodeSnapshot}\n */\nexport function snapshotLayerNodeTree(node: unknown): LayerNodeSnapshot {\n  if (isPibblElement(node)) {\n    const props = splitProps(node.props);\n    return Object.freeze({\n      kind: 'element',\n      type: node.type,\n      key: node.key,\n      enhancers: Object.freeze([...getElementEnhancerDescriptors(node)]),\n      nonChildProps: snapshotProperties(props.nonChild),\n      style: snapshotProperties(props.style),\n      children: snapshotLayerNodeTree(props.children),\n    });\n  }\n\n  if (Array.isArray(node)) {\n    return Object.freeze({\n      kind: 'array',\n      children: Object.freeze(node.map(snapshotLayerNodeTree)),\n    });\n  }\n\n  return Object.freeze({ kind: 'opaque', value: node });\n}\n\n/**\n * Compares an immutable successful-render snapshot with an already-materialized\n * candidate tree. Opaque nested iterables compare only by identity.\n *\n * @param snapshot - Previously recorded node-tree snapshot, if any. See {@link LayerNodeSnapshot}.\n * @param node - Current node tree to compare.\n * @returns Whether the current tree matches the retained snapshot.\n *\n * @see {@link LayerNodeSnapshot}\n */\nexport function haveSameLayerNodeTree(\n  snapshot: LayerNodeSnapshot | undefined,\n  node: unknown,\n): boolean {\n  if (!snapshot) return false;\n\n  switch (snapshot.kind) {\n    case 'element':\n      return isPibblElement(node) && haveSameLayerElement(snapshot, node);\n    case 'array':\n      return Array.isArray(node) &&\n        snapshot.children.length === node.length &&\n        snapshot.children.every((child, index) =>\n          haveSameLayerNodeTree(child, node[index])\n        );\n    case 'opaque':\n      return snapshot.value === node;\n  }\n}\n\nfunction haveSameLayerElement(\n  snapshot: LayerElementSnapshot,\n  element: PibblElement<any>,\n): boolean {\n  if (snapshot.type !== element.type || snapshot.key !== element.key) {\n    return false;\n  }\n\n  const enhancers = getElementEnhancerDescriptors(element);\n  if (\n    snapshot.enhancers.length !== enhancers.length ||\n    !snapshot.enhancers.every((descriptor, index) =>\n      descriptor === enhancers[index]\n    )\n  ) {\n    return false;\n  }\n\n  const props = splitProps(element.props);\n  return haveSameProperties(snapshot.nonChildProps, props.nonChild) &&\n    haveSameProperties(snapshot.style, props.style) &&\n    haveSameLayerNodeTree(snapshot.children, props.children);\n}\n\nfunction snapshotProperties(\n  value: Readonly<Record<PropertyKey, unknown>>,\n): readonly LayerPropertySnapshot[] {\n  return Object.freeze(enumerableOwnKeys(value).map(key => Object.freeze({\n    key,\n    value: value[key],\n  })));\n}\n\nfunction haveSameProperties(\n  snapshot: readonly LayerPropertySnapshot[],\n  value: Readonly<Record<PropertyKey, unknown>>,\n): boolean {\n  const keys = enumerableOwnKeys(value);\n  return snapshot.length === keys.length && snapshot.every(property =>\n    Object.prototype.propertyIsEnumerable.call(value, property.key) &&\n    value[property.key] === property.value\n  );\n}\n\nfunction enumerableOwnKeys(\n  value: Readonly<Record<PropertyKey, unknown>>,\n): readonly PropertyKey[] {\n  return Reflect.ownKeys(value).filter(key =>\n    Object.prototype.propertyIsEnumerable.call(value, key)\n  );\n}\n\nfunction splitProps(props: Readonly<Record<PropertyKey, unknown>>): {\n  children: unknown;\n  nonChild: Readonly<Record<PropertyKey, unknown>>;\n  style: Readonly<Record<PropertyKey, unknown>>;\n} {\n  const {\n    children,\n    style,\n    ...nonChild\n  } = props as Readonly<{\n    children?: unknown;\n    style?: Readonly<Record<PropertyKey, unknown>>;\n    [key: PropertyKey]: unknown;\n  }>;\n  return {\n    children,\n    nonChild,\n    style: style ?? EMPTY_PROPS,\n  };\n}\n\nconst EMPTY_PROPS: Readonly<Record<PropertyKey, unknown>> = Object.freeze({});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/components/layer.d.ts

@@ -0,0 +1,34 @@
+import { PibblNodeInput, SystemStyle } from '../types.js';
+import type { BoxStyle, LayoutItemStyle } from '../style/types.js';
+import { type PibblStructuralEventProps } from './structural-events.js';
+/**
+ * Authored inputs for Layer, including the declared data and presentation options.
+ *
+ * @see {@link PibblNodeInput}
+ * @see {@link Layer}
+ */
+export interface LayerProps extends PibblStructuralEventProps {
+    /** Descendant content or the callback that supplies it. See {@link PibblNodeInput}. */
+    children: PibblNodeInput;
+}
+/**
+ * Supported geometry and presentation properties for Layer.
+ *
+ * @see {@link SystemStyle}
+ * @see {@link BoxStyle}
+ * @see {@link LayoutItemStyle}
+ * @see {@link Layer}
+ */
+export interface LayerStyle extends SystemStyle, BoxStyle, LayoutItemStyle {
+}
+/**
+ * Describes a retained offscreen composition layer.
+ *
+ * @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 LayerProps}
+ * @see {@link LayerStyle}
+ */
+export declare const Layer: import("@pibbl/core").PibblPrimitiveComponent<LayerProps, import("@pibbl/core").PrimitiveInput<LayerProps, LayerStyle>>;

package/dist/lib/components/layer.js

@@ -0,0 +1,172 @@
+import { definePrimitive } from "../define-primitive.js";
+import { materializeContainerChildren } from "../element/children.js";
+import { createElement } from "../element/create-element.js";
+import { Fragment } from "../element/fragment.js";
+import { executeRender } from "../execute-render.js";
+import {
+  getPibblInstance,
+  getCurrentPibblInstance,
+  GLOBAL_STATE
+} from "../global-state.js";
+import { mountPibbl } from "../mount-pibbl.js";
+import { PibblPaintEntryKind } from "../events/paint-entry.js";
+import {
+  resolveRequiredLength,
+  stripLayoutParticipation
+} from "../style/resolve-built-in.js";
+import {
+  getSurfaceSnapshot
+} from "../surface/transform.js";
+import { getCurrentWorldTransform } from "../render-target.js";
+import { createLayerSurface } from "../surface/resolve-surface.js";
+import {
+  completeInstanceRenderRevision,
+  hasPendingInstanceRender
+} from "../scheduler/realm-scheduler.js";
+import {
+  haveSameLayerNodeTree,
+  snapshotLayerNodeTree
+} from "./layer-node-equality.js";
+import {
+  wireStructuralEvents
+} from "./structural-events.js";
+function renderLayer(props, style, ctx) {
+  wireStructuralEvents(props);
+  const materializedChildren = materializeContainerChildren(
+    props.children,
+    "Layer"
+  );
+  const nextRoot = createPrivateLayerRoot(materializedChildren);
+  const canvas = GLOBAL_STATE.canvas;
+  const { width = canvas.width, height = canvas.height } = style;
+  const componentRefs = GLOBAL_STATE.componentRefs;
+  const parentInstance = getCurrentPibblInstance();
+  const parentSurface = getSurfaceSnapshot(parentInstance);
+  const layerSurface = createLayerSurface(
+    width,
+    height,
+    parentSurface.backingPixelsPerLogicalUnitX,
+    parentSurface.backingPixelsPerLogicalUnitY
+  );
+  if (GLOBAL_STATE.componentIsMounting) {
+    const offscreenCanvas2 = new OffscreenCanvas(
+      layerSurface.backingWidth,
+      layerSurface.backingHeight
+    );
+    const controller = mountPibbl(offscreenCanvas2, nextRoot, {
+      parent: canvas,
+      surface: layerSurface
+    });
+    const childInstance = getPibblInstance(offscreenCanvas2);
+    childInstance.eventParent = componentRefs;
+    const interactionLayer2 = {
+      paintKind: PibblPaintEntryKind.NestedInstance,
+      instance: childInstance,
+      transform: new DOMMatrix(),
+      clippingStack: [],
+      bounds: createBounds(width, height),
+      resolveLocal: void 0
+    };
+    componentRefs.refs[0] = {
+      canvas: offscreenCanvas2,
+      interactionLayer: interactionLayer2,
+      logicalWidth: width,
+      logicalHeight: height,
+      focusRenderRevision: void 0,
+      retainedTree: void 0
+    };
+    componentRefs.teardowns.add(() => {
+      childInstance.eventParent = void 0;
+      parentInstance.paintEntries.delete(interactionLayer2);
+      controller.dispose();
+    });
+  }
+  const slot = componentRefs.refs[0];
+  const offscreenCanvas = slot.canvas;
+  const layerPibbl = getPibblInstance(offscreenCanvas);
+  const dimensionsChanged = slot.logicalWidth !== width || slot.logicalHeight !== height;
+  const surfaceChanged = offscreenCanvas.width !== layerSurface.backingWidth || offscreenCanvas.height !== layerSurface.backingHeight;
+  const { interactionLayer } = slot;
+  parentInstance.paintEntries.delete(interactionLayer);
+  interactionLayer.transform = getCurrentWorldTransform();
+  interactionLayer.clippingStack = Array.from(GLOBAL_STATE.clippingStack);
+  if (dimensionsChanged) {
+    interactionLayer.bounds = createBounds(width, height);
+  }
+  parentInstance.paintEntries.add(interactionLayer);
+  const focusPolicy = parentInstance.eventRoot.focusPolicy;
+  const focusRenderRevision = focusPolicy?.layerFocusRenderRevision?.(layerPibbl);
+  const shouldRender = GLOBAL_STATE.componentIsMounting || dimensionsChanged || surfaceChanged || !haveSameLayerNodeTree(slot.retainedTree, nextRoot) || slot.focusRenderRevision !== focusRenderRevision || hasPendingInstanceRender(layerPibbl);
+  if (shouldRender) {
+    if (layerPibbl.surface.kind !== "layer") {
+      throw new Error("Pibbl layer mounted without a derived surface.");
+    }
+    layerPibbl.surface.snapshot = layerSurface;
+    layerPibbl.surface.managed = true;
+    offscreenCanvas.width = layerSurface.backingWidth;
+    offscreenCanvas.height = layerSurface.backingHeight;
+    slot.logicalWidth = width;
+    slot.logicalHeight = height;
+    const renderedRevision = layerPibbl.requestedRenderRevision;
+    executeRender(
+      offscreenCanvas,
+      getCurrentPibblInstance().renderTimestamp,
+      nextRoot,
+      false
+    );
+    completeInstanceRenderRevision(layerPibbl, renderedRevision);
+    slot.retainedTree = snapshotLayerNodeTree(nextRoot);
+  } else {
+    parentInstance.eventRoot.focusPolicy?.replayRetainedSubtree(layerPibbl);
+  }
+  const renderedFocusPolicy = parentInstance.eventRoot.focusPolicy;
+  slot.focusRenderRevision = renderedFocusPolicy?.layerFocusRenderRevision?.(layerPibbl);
+  parentInstance.eventRoot.html?.recordLayer(parentInstance, layerPibbl, interactionLayer, ctx.globalAlpha, ctx.globalCompositeOperation);
+  ctx.drawImage(
+    offscreenCanvas,
+    0,
+    0,
+    offscreenCanvas.width,
+    offscreenCanvas.height,
+    0,
+    0,
+    width,
+    height
+  );
+}
+const Layer = definePrimitive(renderLayer, {
+  childInput: "structural",
+  resolveStyle: resolveLayerStyle
+});
+function resolveLayerStyle(style, context) {
+  return {
+    ...stripLayoutParticipation(style),
+    width: resolveRequiredLength(
+      style.width ?? context.allocation.width,
+      context.percentageBasis.width,
+      "width",
+      context
+    ),
+    height: resolveRequiredLength(
+      style.height ?? context.allocation.height,
+      context.percentageBasis.height,
+      "height",
+      context
+    )
+  };
+}
+function createPrivateLayerRoot(children) {
+  return createElement(Fragment, {
+    key: "pibbl-layer-root",
+    children
+  });
+}
+function createBounds(width, height) {
+  const bounds = new Path2D();
+  bounds.rect(0, 0, width, height);
+  return bounds;
+}
+export {
+  Layer
+};
+//# sourceMappingURL=layer.js.map

package/dist/lib/components/layer.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/components/layer.ts"],
+  "sourcesContent": ["import { definePrimitive } from '../define-primitive.js';\nimport { materializeContainerChildren } from '../element/children.js';\nimport { createElement } from '../element/create-element.js';\nimport { Fragment, type FragmentProps } from '../element/fragment.js';\nimport { executeRender } from '../execute-render.js';\nimport {\n  getPibblInstance,\n  getCurrentPibblInstance,\n  GLOBAL_STATE,\n} from '../global-state.js';\nimport { mountPibbl } from '../mount-pibbl.js';\nimport {\n  PibblNodeInput,\n  PibblInteractionLayer,\n  RenderingContext2D,\n  SystemStyle,\n} from '../types.js';\nimport { PibblPaintEntryKind } from '../events/paint-entry.js';\nimport {\n  resolveRequiredLength,\n  stripLayoutParticipation,\n} from '../style/resolve-built-in.js';\nimport type {\n  BoxStyle,\n  LayoutItemStyle,\n  ResolvedDrawingStyle,\n} from '../style/types.js';\nimport {\n  getSurfaceSnapshot,\n} from '../surface/transform.js';\nimport { getCurrentWorldTransform } from '../render-target.js';\nimport { createLayerSurface } from '../surface/resolve-surface.js';\nimport {\n  completeInstanceRenderRevision,\n  hasPendingInstanceRender,\n} from '../scheduler/realm-scheduler.js';\nimport type { PibblElement } from '../element/types.js';\nimport {\n  haveSameLayerNodeTree,\n  snapshotLayerNodeTree,\n  type LayerNodeSnapshot,\n} from './layer-node-equality.js';\nimport {\n  type PibblStructuralEventProps,\n  wireStructuralEvents,\n} from './structural-events.js';\n\n/**\n * Authored inputs for Layer, including the declared data and presentation options.\n *\n * @see {@link PibblNodeInput}\n * @see {@link Layer}\n */\nexport interface LayerProps extends PibblStructuralEventProps {\n  /** Descendant content or the callback that supplies it. See {@link PibblNodeInput}. */\n  children: PibblNodeInput;\n}\n\n/**\n * Supported geometry and presentation properties for Layer.\n *\n * @see {@link SystemStyle}\n * @see {@link BoxStyle}\n * @see {@link LayoutItemStyle}\n * @see {@link Layer}\n */\nexport interface LayerStyle extends SystemStyle, BoxStyle, LayoutItemStyle {}\n\ntype ResolvedLayerStyle = ResolvedDrawingStyle<LayerStyle> & {\n  width: number;\n  height: number;\n};\n\ninterface LayerSlot {\n  canvas: OffscreenCanvas;\n  interactionLayer: PibblInteractionLayer;\n  logicalWidth: number;\n  logicalHeight: number;\n  focusRenderRevision: number | undefined;\n  retainedTree: LayerNodeSnapshot | undefined;\n}\n\nfunction renderLayer(\n  props: LayerProps,\n  style: Readonly<ResolvedLayerStyle>,\n  ctx: RenderingContext2D,\n) {\n  wireStructuralEvents(props);\n  const materializedChildren = materializeContainerChildren(\n    props.children,\n    'Layer',\n  );\n  const nextRoot = createPrivateLayerRoot(materializedChildren);\n  const canvas = GLOBAL_STATE.canvas!;\n  const { width = canvas.width, height = canvas.height } = style;\n  const componentRefs = GLOBAL_STATE.componentRefs!;\n  const parentInstance = getCurrentPibblInstance();\n  const parentSurface = getSurfaceSnapshot(parentInstance);\n  const layerSurface = createLayerSurface(\n    width,\n    height,\n    parentSurface.backingPixelsPerLogicalUnitX,\n    parentSurface.backingPixelsPerLogicalUnitY,\n  );\n  if (GLOBAL_STATE.componentIsMounting) {\n    const offscreenCanvas = new OffscreenCanvas(\n      layerSurface.backingWidth,\n      layerSurface.backingHeight,\n    );\n    const controller = mountPibbl(offscreenCanvas, nextRoot, {\n      parent: canvas,\n      surface: layerSurface,\n    });\n    const childInstance = getPibblInstance(offscreenCanvas);\n    childInstance.eventParent = componentRefs;\n    const interactionLayer: PibblInteractionLayer = {\n      paintKind: PibblPaintEntryKind.NestedInstance,\n      instance: childInstance,\n      transform: new DOMMatrix(),\n      clippingStack: [],\n      bounds: createBounds(width, height),\n      resolveLocal: undefined,\n    };\n    componentRefs.refs[0] = {\n      canvas: offscreenCanvas,\n      interactionLayer,\n      logicalWidth: width,\n      logicalHeight: height,\n      focusRenderRevision: undefined,\n      retainedTree: undefined,\n    } satisfies LayerSlot;\n    componentRefs.teardowns.add(() => {\n      childInstance.eventParent = undefined;\n      parentInstance.paintEntries.delete(interactionLayer);\n      controller.dispose();\n    });\n  }\n\n  const slot = componentRefs.refs[0] as LayerSlot;\n  const offscreenCanvas = slot.canvas;\n  const layerPibbl = getPibblInstance(offscreenCanvas);\n  const dimensionsChanged = slot.logicalWidth !== width ||\n    slot.logicalHeight !== height;\n  const surfaceChanged =\n    offscreenCanvas.width !== layerSurface.backingWidth ||\n    offscreenCanvas.height !== layerSurface.backingHeight;\n\n  const { interactionLayer } = slot;\n  parentInstance.paintEntries.delete(interactionLayer);\n  interactionLayer.transform = getCurrentWorldTransform();\n  interactionLayer.clippingStack = Array.from(GLOBAL_STATE.clippingStack);\n  if (dimensionsChanged) {\n    interactionLayer.bounds = createBounds(width, height);\n  }\n  // Install the current bridge before entering the child render. Focus bounds\n  // collected by the child must never see the previous frame's transform.\n  parentInstance.paintEntries.add(interactionLayer);\n\n  const focusPolicy = parentInstance.eventRoot.focusPolicy;\n  const focusRenderRevision = focusPolicy?.layerFocusRenderRevision?.(layerPibbl);\n\n  const shouldRender =\n    GLOBAL_STATE.componentIsMounting ||\n    dimensionsChanged ||\n    surfaceChanged ||\n    !haveSameLayerNodeTree(slot.retainedTree, nextRoot) ||\n    slot.focusRenderRevision !== focusRenderRevision ||\n    hasPendingInstanceRender(layerPibbl);\n  if (shouldRender) {\n    if (layerPibbl.surface.kind !== 'layer') {\n      throw new Error('Pibbl layer mounted without a derived surface.');\n    }\n    layerPibbl.surface.snapshot = layerSurface;\n    layerPibbl.surface.managed = true;\n    offscreenCanvas.width = layerSurface.backingWidth;\n    offscreenCanvas.height = layerSurface.backingHeight;\n    slot.logicalWidth = width;\n    slot.logicalHeight = height;\n\n    const renderedRevision = layerPibbl.requestedRenderRevision;\n    executeRender(\n      offscreenCanvas,\n      getCurrentPibblInstance().renderTimestamp,\n      nextRoot,\n      false,\n    );\n    completeInstanceRenderRevision(layerPibbl, renderedRevision);\n    slot.retainedTree = snapshotLayerNodeTree(nextRoot);\n  } else {\n    parentInstance.eventRoot.focusPolicy?.replayRetainedSubtree(layerPibbl);\n  }\n  const renderedFocusPolicy = parentInstance.eventRoot.focusPolicy;\n  slot.focusRenderRevision =\n    renderedFocusPolicy?.layerFocusRenderRevision?.(layerPibbl);\n\n  parentInstance.eventRoot.html?.recordLayer(parentInstance, layerPibbl, interactionLayer, ctx.globalAlpha, ctx.globalCompositeOperation);\n\n  ctx.drawImage(\n    offscreenCanvas,\n    0,\n    0,\n    offscreenCanvas.width,\n    offscreenCanvas.height,\n    0,\n    0,\n    width,\n    height,\n  );\n\n}\n\n/**\n * Describes a retained offscreen composition layer.\n *\n * @param props - Authored component inputs, supplied through JSX or createElement. See the linked\n * props and style types.\n * @throws When called directly; Pibbl mounts this component through JSX or createElement.\n *\n * @see {@link LayerProps}\n * @see {@link LayerStyle}\n */\nexport const Layer = definePrimitive<\n  LayerProps,\n  LayerStyle,\n  LayerStyle,\n  ResolvedLayerStyle\n>(renderLayer, {\n  childInput: 'structural',\n  resolveStyle: resolveLayerStyle,\n});\n\nfunction resolveLayerStyle(\n  style: Readonly<LayerStyle>,\n  context: Parameters<NonNullable<\n    import('../types.js').PrimitiveCapabilities<\n      LayerProps,\n      LayerStyle,\n      LayerStyle,\n      ResolvedLayerStyle\n    >['resolveStyle']\n  >>[1],\n): ResolvedLayerStyle {\n  return {\n    ...stripLayoutParticipation(style),\n    width: resolveRequiredLength(\n      style.width ?? context.allocation.width,\n      context.percentageBasis.width,\n      'width',\n      context,\n    ),\n    height: resolveRequiredLength(\n      style.height ?? context.allocation.height,\n      context.percentageBasis.height,\n      'height',\n      context,\n    ),\n  } as ResolvedLayerStyle;\n}\n\nfunction createPrivateLayerRoot(\n  children: readonly PibblElement<any>[],\n): PibblElement<FragmentProps> {\n  return createElement(Fragment, {\n    key: 'pibbl-layer-root',\n    children,\n  });\n}\n\nfunction createBounds(width: number, height: number): Path2D {\n  const bounds = new Path2D();\n  bounds.rect(0, 0, width, height);\n  return bounds;\n}\n"],
+  "mappings": "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",
+  "names": ["offscreenCanvas", "interactionLayer"]
+}

package/dist/lib/components/line.d.ts

@@ -0,0 +1,51 @@
+import type { HorizontalLineStyle } from "./horizontal-line.js";
+import type { VerticalLineStyle } from "./vertical-line.js";
+import type { PibblEventFocusOptions, PibblEventHandlers, PibblEventParticipationOptions } from '../events/types.js';
+import { RenderingContext2D, SystemStyle } from '../types.js';
+import type { PibblPhysics2DPropExtension } from '../types.js';
+import type { BoxStyle, CursorStyle, LayoutItemStyle, PaintStyle, ResolvedDrawingStyle } from '../style/types.js';
+/**
+ * Authored inputs for Line, including the declared data and presentation options.
+ *
+ * @see {@link PibblEventHandlers}
+ * @see {@link PibblEventParticipationOptions}
+ * @see {@link PibblPhysics2DPropExtension}
+ * @see {@link Line}
+ */
+export interface LineProps extends PibblEventHandlers, PibblEventFocusOptions, PibblEventParticipationOptions, PibblPhysics2DPropExtension {
+}
+/**
+ * Supported geometry and presentation properties for Line.
+ *
+ * @see {@link SystemStyle}
+ * @see {@link BoxStyle}
+ * @see {@link LayoutItemStyle}
+ * @see {@link PaintStyle}
+ * @see {@link CursorStyle}
+ * @see {@link Line}
+ * @see {@link HorizontalLineStyle}
+ * @see {@link VerticalLineStyle}
+ */
+export interface LineStyle extends SystemStyle, BoxStyle, LayoutItemStyle, Omit<PaintStyle, 'fill'>, CursorStyle {
+    /** Ordered coordinate pairs describing the path vertices. See {@link LineStyle}. */
+    coords: [number, number][];
+    /**
+     * Width used for line hit testing independently of the visible stroke width. See
+     * {@link LineStyle}.
+     */
+    lineInteractionWidth?: number;
+}
+type ResolvedLineStyle = ResolvedDrawingStyle<LineStyle>;
+export declare function renderLine(props: LineProps, style: Readonly<ResolvedLineStyle>, ctx: RenderingContext2D): void;
+/**
+ * Describes a polyline primitive 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 LineProps}
+ * @see {@link LineStyle}
+ */
+export declare const Line: import("@pibbl/core").PibblPrimitiveComponent<LineProps, import("@pibbl/core").PrimitiveInput<LineProps, LineStyle>>;
+export {};