@pibbl/core 0.0.1

package/dist/lib/geometry/transform-mesh.d.ts

@@ -0,0 +1,39 @@
+import { type PathGuide } from './transform-guide.js';
+import { type PathRect, type PathTransform } from './path-transforms.js';
+/**
+ * Source rectangle, normalized cell boundaries, and horizontal/vertical path guides for a mesh
+ * transform.
+ *
+ * @see {@link PathRect}
+ * @see {@link PathGuide}
+ * @see {@link meshTransform}
+ */
+export interface MeshTransformOptions {
+    /** Source rectangle whose normalized cells are mapped through the guide mesh. See {@link PathRect}. */
+    readonly source: PathRect;
+    /**
+     * Strictly increasing normalized column boundaries, beginning at 0 and ending at 1. See
+     * {@link MeshTransformOptions}.
+     */
+    readonly columns: readonly number[];
+    /**
+     * Strictly increasing normalized row boundaries, beginning at 0 and ending at 1. See
+     * {@link MeshTransformOptions}.
+     */
+    readonly rows: readonly number[];
+    /** Boundary rows; each contains columns.length - 1 left-to-right edges. */
+    readonly horizontal: readonly (readonly PathGuide[])[];
+    /** Boundary columns; each contains rows.length - 1 top-to-bottom edges. */
+    readonly vertical: readonly (readonly PathGuide[])[];
+}
+/**
+ * Creates a mapping through a mesh bounded by horizontal and vertical path guides.
+ *
+ * @param options - Source rectangle and the four boundary guides used to deform it. See
+ * {@link MeshTransformOptions} .
+ * @returns A point mapping suitable for transformPath. See {@link PathTransform}.
+ *
+ * @see {@link MeshTransformOptions}
+ * @see {@link PathTransform}
+ */
+export declare function meshTransform(options: MeshTransformOptions): PathTransform;

package/dist/lib/geometry/transform-mesh.js

@@ -0,0 +1,129 @@
+import {
+  constant,
+  add,
+  sub,
+  scale,
+  lerp
+} from "./transform-math.js";
+import {
+  snapshotGuide,
+  sampleGuide
+} from "./transform-guide.js";
+import {
+  make,
+  rectangle,
+  coordinate,
+  normalize,
+  mergePairs,
+  sourceDomain
+} from "./path-transforms.js";
+function meshTransform(options) {
+  const source = rectangle(options.source);
+  const axis = (values) => {
+    const result = Array.from(values, (n) => coordinate(n));
+    if (result.length < 2 || result[0] !== 0 || result.at(-1) !== 1 || result.some((n, i) => i > 0 && n <= result[i - 1]))
+      throw new RangeError(
+        "Mesh axes must strictly increase from zero to one."
+      );
+    return result;
+  };
+  const columns = axis(options.columns), rows = axis(options.rows);
+  if (options.horizontal.length !== rows.length || options.vertical.length !== columns.length || options.horizontal.some((row) => row.length !== columns.length - 1) || options.vertical.some((col) => col.length !== rows.length - 1))
+    throw new RangeError("Mesh edge dimensions must match its axes.");
+  if ((columns.length - 1) * (rows.length - 1) > 4096)
+    throw new RangeError("Mesh exceeds 4096 cells.");
+  const horizontal = options.horizontal.map((row) => row.map(snapshotGuide));
+  const vertical = options.vertical.map((col) => col.map(snapshotGuide));
+  const ends = (guide) => {
+    const first = guide.spans[0], last = guide.spans.at(-1);
+    const a = bendSpanPoint(first, 0), b = bendSpanPoint(last, 1);
+    return guide.reverse ? [b, a] : [a, b];
+  };
+  const equal = (a, b) => {
+    if (a[0] !== b[0] || a[1] !== b[1])
+      throw new RangeError("Mesh edges must share exactly matching endpoints.");
+  };
+  for (let row = 0; row < rows.length - 1; row++)
+    for (let col = 0; col < columns.length - 1; col++) {
+      const t = ends(horizontal[row][col]), b = ends(horizontal[row + 1][col]), l = ends(vertical[col][row]), r = ends(vertical[col + 1][row]);
+      equal(t[0], l[0]);
+      equal(t[1], r[0]);
+      equal(b[0], l[1]);
+      equal(b[1], r[1]);
+    }
+  return make([
+    (accuracy) => {
+      const h = horizontal.map(
+        (row) => row.map((g) => sampleGuide(g, accuracy))
+      ), v = vertical.map((col) => col.map((g) => sampleGuide(g, accuracy)));
+      const error = 2 * Math.max(
+        ...h.flat().map((g) => g.error),
+        ...v.flat().map((g) => g.error)
+      );
+      return {
+        error: () => error,
+        domain: (p, margin) => sourceDomain(p, source, margin),
+        evaluate: (input) => {
+          const [u, w] = normalize(input, source), cells = [];
+          for (let row = 0; row < rows.length - 1; row++) {
+            if (w.v[1] < rows[row] || w.v[0] > rows[row + 1]) continue;
+            for (let col = 0; col < columns.length - 1; col++) {
+              if (u.v[1] < columns[col] || u.v[0] > columns[col + 1]) continue;
+              const localU = scale(
+                sub(
+                  {
+                    ...u,
+                    v: [
+                      Math.max(u.v[0], columns[col]),
+                      Math.min(u.v[1], columns[col + 1])
+                    ]
+                  },
+                  constant(columns[col])
+                ),
+                1 / (columns[col + 1] - columns[col])
+              );
+              const localV = scale(
+                sub(
+                  {
+                    ...w,
+                    v: [
+                      Math.max(w.v[0], rows[row]),
+                      Math.min(w.v[1], rows[row + 1])
+                    ]
+                  },
+                  constant(rows[row])
+                ),
+                1 / (rows[row + 1] - rows[row])
+              );
+              const top = h[row][col].evaluate(localU), bottom = h[row + 1][col].evaluate(localU), left = v[col][row].evaluate(localV), right = v[col + 1][row].evaluate(localV);
+              const a = ends(horizontal[row][col]), b = ends(horizontal[row + 1][col]);
+              cells.push(
+                [0, 1].map(
+                  (axis2) => sub(
+                    add(
+                      lerp(top[axis2], bottom[axis2], localV),
+                      lerp(left[axis2], right[axis2], localU)
+                    ),
+                    lerp(
+                      lerp(constant(a[0][axis2]), constant(a[1][axis2]), localU),
+                      lerp(constant(b[0][axis2]), constant(b[1][axis2]), localU),
+                      localV
+                    )
+                  )
+                )
+              );
+            }
+          }
+          if (!cells.length)
+            throw new RangeError("Point lies outside the mesh source.");
+          return cells.length === 1 ? cells[0] : mergePairs(cells);
+        }
+      };
+    }
+  ]);
+}
+import { bendSpanPoint } from "./path-bend-spans.js";
+export {
+  meshTransform
+};
+//# sourceMappingURL=transform-mesh.js.map

package/dist/lib/geometry/transform-mesh.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/geometry/transform-mesh.ts"],
+  "sourcesContent": ["import {\n  constant,\n  add,\n  sub,\n  scale,\n  lerp,\n  type Pair,\n} from './transform-math.js';\nimport {\n  snapshotGuide,\n  sampleGuide,\n  type PathGuide,\n} from './transform-guide.js';\nimport {\n  make,\n  rectangle,\n  coordinate,\n  normalize,\n  mergePairs,\n  sourceDomain,\n  type PathRect,\n  type PathTransform,\n} from './path-transforms.js';\n\n/**\n * Source rectangle, normalized cell boundaries, and horizontal/vertical path guides for a mesh\n * transform.\n *\n * @see {@link PathRect}\n * @see {@link PathGuide}\n * @see {@link meshTransform}\n */\nexport interface MeshTransformOptions {\n  /** Source rectangle whose normalized cells are mapped through the guide mesh. See {@link PathRect}. */\n  readonly source: PathRect;\n  /**\n   * Strictly increasing normalized column boundaries, beginning at 0 and ending at 1. See\n   * {@link MeshTransformOptions}.\n   */\n  readonly columns: readonly number[];\n  /**\n   * Strictly increasing normalized row boundaries, beginning at 0 and ending at 1. See\n   * {@link MeshTransformOptions}.\n   */\n  readonly rows: readonly number[];\n  /** Boundary rows; each contains columns.length - 1 left-to-right edges. */\n  readonly horizontal: readonly (readonly PathGuide[])[];\n  /** Boundary columns; each contains rows.length - 1 top-to-bottom edges. */\n  readonly vertical: readonly (readonly PathGuide[])[];\n}\n/**\n * Creates a mapping through a mesh bounded by horizontal and vertical path guides.\n *\n * @param options - Source rectangle and the four boundary guides used to deform it. See\n * {@link MeshTransformOptions} .\n * @returns A point mapping suitable for transformPath. See {@link PathTransform}.\n *\n * @see {@link MeshTransformOptions}\n * @see {@link PathTransform}\n */\nexport function meshTransform(options: MeshTransformOptions): PathTransform {\n  const source = rectangle(options.source);\n  const axis = (values: readonly number[]) => {\n    const result = Array.from(values, (n) => coordinate(n));\n    if (\n      result.length < 2 ||\n      result[0] !== 0 ||\n      result.at(-1) !== 1 ||\n      result.some((n, i) => i > 0 && n <= result[i - 1])\n    )\n      throw new RangeError(\n        'Mesh axes must strictly increase from zero to one.',\n      );\n    return result;\n  };\n  const columns = axis(options.columns),\n    rows = axis(options.rows);\n  if (\n    options.horizontal.length !== rows.length ||\n    options.vertical.length !== columns.length ||\n    options.horizontal.some((row) => row.length !== columns.length - 1) ||\n    options.vertical.some((col) => col.length !== rows.length - 1)\n  )\n    throw new RangeError('Mesh edge dimensions must match its axes.');\n  if ((columns.length - 1) * (rows.length - 1) > 4096)\n    throw new RangeError('Mesh exceeds 4096 cells.');\n  const horizontal = options.horizontal.map((row) => row.map(snapshotGuide));\n  const vertical = options.vertical.map((col) => col.map(snapshotGuide));\n  const ends = (guide: ReturnType<typeof snapshotGuide>) => {\n    const first = guide.spans[0],\n      last = guide.spans.at(-1)!;\n    const a = bendSpanPoint(first, 0),\n      b = bendSpanPoint(last, 1);\n    return guide.reverse ? [b, a] : [a, b];\n  };\n  const equal = (a: readonly number[], b: readonly number[]) => {\n    if (a[0] !== b[0] || a[1] !== b[1])\n      throw new RangeError('Mesh edges must share exactly matching endpoints.');\n  };\n  for (let row = 0; row < rows.length - 1; row++)\n    for (let col = 0; col < columns.length - 1; col++) {\n      const t = ends(horizontal[row][col]),\n        b = ends(horizontal[row + 1][col]),\n        l = ends(vertical[col][row]),\n        r = ends(vertical[col + 1][row]);\n      equal(t[0], l[0]);\n      equal(t[1], r[0]);\n      equal(b[0], l[1]);\n      equal(b[1], r[1]);\n    }\n  return make([\n    (accuracy) => {\n      const h = horizontal.map((row) =>\n          row.map((g) => sampleGuide(g, accuracy)),\n        ),\n        v = vertical.map((col) => col.map((g) => sampleGuide(g, accuracy)));\n      const error =\n        2 *\n        Math.max(\n          ...h.flat().map((g) => g.error),\n          ...v.flat().map((g) => g.error),\n        );\n      return {\n        error: () => error,\n        domain: (p, margin) => sourceDomain(p, source, margin),\n        evaluate: (input) => {\n          const [u, w] = normalize(input, source),\n            cells: Pair[] = [];\n          for (let row = 0; row < rows.length - 1; row++) {\n            if (w.v[1] < rows[row] || w.v[0] > rows[row + 1]) continue;\n            for (let col = 0; col < columns.length - 1; col++) {\n              if (u.v[1] < columns[col] || u.v[0] > columns[col + 1]) continue;\n              const localU = scale(\n                sub(\n                  {\n                    ...u,\n                    v: [\n                      Math.max(u.v[0], columns[col]),\n                      Math.min(u.v[1], columns[col + 1]),\n                    ],\n                  },\n                  constant(columns[col]),\n                ),\n                1 / (columns[col + 1] - columns[col]),\n              );\n              const localV = scale(\n                sub(\n                  {\n                    ...w,\n                    v: [\n                      Math.max(w.v[0], rows[row]),\n                      Math.min(w.v[1], rows[row + 1]),\n                    ],\n                  },\n                  constant(rows[row]),\n                ),\n                1 / (rows[row + 1] - rows[row]),\n              );\n              const top = h[row][col].evaluate(localU),\n                bottom = h[row + 1][col].evaluate(localU),\n                left = v[col][row].evaluate(localV),\n                right = v[col + 1][row].evaluate(localV);\n              const a = ends(horizontal[row][col]),\n                b = ends(horizontal[row + 1][col]);\n              cells.push(\n                [0, 1].map((axis) =>\n                  sub(\n                    add(\n                      lerp(top[axis], bottom[axis], localV),\n                      lerp(left[axis], right[axis], localU),\n                    ),\n                    lerp(\n                      lerp(constant(a[0][axis]), constant(a[1][axis]), localU),\n                      lerp(constant(b[0][axis]), constant(b[1][axis]), localU),\n                      localV,\n                    ),\n                  ),\n                ) as unknown as Pair,\n              );\n            }\n          }\n          if (!cells.length)\n            throw new RangeError('Point lies outside the mesh source.');\n          return cells.length === 1 ? cells[0] : mergePairs(cells);\n        },\n      };\n    },\n  ]);\n}\nimport { bendSpanPoint } from './path-bend-spans.js';\n"],
+  "mappings": "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",
+  "names": ["axis"]
+}

package/dist/lib/geometry/validation.d.ts

@@ -0,0 +1,6 @@
+export type GeometryErrorFactory = (property: string, value: unknown, reason: string) => Error;
+export declare function pathRangeError(property: string, value: unknown, reason: string): RangeError;
+export declare function finiteNumber(value: unknown, property: string, errorFactory?: GeometryErrorFactory): number;
+export declare function nonnegativeNumber(value: unknown, property: string, errorFactory?: GeometryErrorFactory): number;
+export declare function integerAtLeast(value: unknown, minimum: number, property: string, errorFactory?: GeometryErrorFactory): number;
+export declare function validateCoordinates(coords: readonly (readonly [number, number])[], property?: string, errorFactory?: GeometryErrorFactory): readonly (readonly [number, number])[];

package/dist/lib/geometry/validation.js

@@ -0,0 +1,42 @@
+function pathRangeError(property, value, reason) {
+  return new RangeError(`${property} ${reason}; received ${String(value)}`);
+}
+function finiteNumber(value, property, errorFactory = pathRangeError) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw errorFactory(property, value, "must be a finite number");
+  }
+  return value;
+}
+function nonnegativeNumber(value, property, errorFactory = pathRangeError) {
+  const number = finiteNumber(value, property, errorFactory);
+  if (number < 0) {
+    throw errorFactory(property, value, "must be nonnegative");
+  }
+  return number;
+}
+function integerAtLeast(value, minimum, property, errorFactory = pathRangeError) {
+  const number = finiteNumber(value, property, errorFactory);
+  if (!Number.isInteger(number)) {
+    throw errorFactory(property, value, "must be an integer");
+  }
+  if (number < minimum) {
+    throw errorFactory(property, value, `must be at least ${minimum}`);
+  }
+  return number;
+}
+function validateCoordinates(coords, property = "coords", errorFactory = pathRangeError) {
+  for (let index = 0; index < coords.length; index++) {
+    const [x, y] = coords[index];
+    finiteNumber(x, `${property}[${index}][0]`, errorFactory);
+    finiteNumber(y, `${property}[${index}][1]`, errorFactory);
+  }
+  return coords;
+}
+export {
+  finiteNumber,
+  integerAtLeast,
+  nonnegativeNumber,
+  pathRangeError,
+  validateCoordinates
+};
+//# sourceMappingURL=validation.js.map

package/dist/lib/geometry/validation.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/geometry/validation.ts"],
+  "sourcesContent": ["export type GeometryErrorFactory = (\n  property: string,\n  value: unknown,\n  reason: string,\n) => Error;\n\nexport function pathRangeError(\n  property: string,\n  value: unknown,\n  reason: string,\n): RangeError {\n  return new RangeError(`${property} ${reason}; received ${String(value)}`);\n}\n\nexport function finiteNumber(\n  value: unknown,\n  property: string,\n  errorFactory: GeometryErrorFactory = pathRangeError,\n): number {\n  if (typeof value !== 'number' || !Number.isFinite(value)) {\n    throw errorFactory(property, value, 'must be a finite number');\n  }\n  return value;\n}\n\nexport function nonnegativeNumber(\n  value: unknown,\n  property: string,\n  errorFactory: GeometryErrorFactory = pathRangeError,\n): number {\n  const number = finiteNumber(value, property, errorFactory);\n  if (number < 0) {\n    throw errorFactory(property, value, 'must be nonnegative');\n  }\n  return number;\n}\n\nexport function integerAtLeast(\n  value: unknown,\n  minimum: number,\n  property: string,\n  errorFactory: GeometryErrorFactory = pathRangeError,\n): number {\n  const number = finiteNumber(value, property, errorFactory);\n  if (!Number.isInteger(number)) {\n    throw errorFactory(property, value, 'must be an integer');\n  }\n  if (number < minimum) {\n    throw errorFactory(property, value, `must be at least ${minimum}`);\n  }\n  return number;\n}\n\nexport function validateCoordinates(\n  coords: readonly (readonly [number, number])[],\n  property = 'coords',\n  errorFactory: GeometryErrorFactory = pathRangeError,\n): readonly (readonly [number, number])[] {\n  for (let index = 0; index < coords.length; index++) {\n    const [x, y] = coords[index];\n    finiteNumber(x, `${property}[${index}][0]`, errorFactory);\n    finiteNumber(y, `${property}[${index}][1]`, errorFactory);\n  }\n  return coords;\n}\n"],
+  "mappings": "AAMO,SAAS,eACd,UACA,OACA,QACY;AACZ,SAAO,IAAI,WAAW,GAAG,QAAQ,IAAI,MAAM,cAAc,OAAO,KAAK,CAAC,EAAE;AAC1E;AAEO,SAAS,aACd,OACA,UACA,eAAqC,gBAC7B;AACR,MAAI,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,KAAK,GAAG;AACxD,UAAM,aAAa,UAAU,OAAO,yBAAyB;AAAA,EAC/D;AACA,SAAO;AACT;AAEO,SAAS,kBACd,OACA,UACA,eAAqC,gBAC7B;AACR,QAAM,SAAS,aAAa,OAAO,UAAU,YAAY;AACzD,MAAI,SAAS,GAAG;AACd,UAAM,aAAa,UAAU,OAAO,qBAAqB;AAAA,EAC3D;AACA,SAAO;AACT;AAEO,SAAS,eACd,OACA,SACA,UACA,eAAqC,gBAC7B;AACR,QAAM,SAAS,aAAa,OAAO,UAAU,YAAY;AACzD,MAAI,CAAC,OAAO,UAAU,MAAM,GAAG;AAC7B,UAAM,aAAa,UAAU,OAAO,oBAAoB;AAAA,EAC1D;AACA,MAAI,SAAS,SAAS;AACpB,UAAM,aAAa,UAAU,OAAO,oBAAoB,OAAO,EAAE;AAAA,EACnE;AACA,SAAO;AACT;AAEO,SAAS,oBACd,QACA,WAAW,UACX,eAAqC,gBACG;AACxC,WAAS,QAAQ,GAAG,QAAQ,OAAO,QAAQ,SAAS;AAClD,UAAM,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK;AAC3B,iBAAa,GAAG,GAAG,QAAQ,IAAI,KAAK,QAAQ,YAAY;AACxD,iBAAa,GAAG,GAAG,QAAQ,IAAI,KAAK,QAAQ,YAAY;AAAA,EAC1D;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/lib/global-state.d.ts

@@ -0,0 +1,63 @@
+import type { LayoutContext } from './layout/types.js';
+import type { PibblNode } from './element/types.js';
+import type { RenderTargetSnapshot } from './render-target.js';
+import type { PibblFrameSnapshot } from './scheduler/types.js';
+import type { PibblBackendDriver, PibblBackendFrame } from './backend/types.js';
+import type { Canvas, PibblComponentRefs, PibblClippingStackEntry, PibblInstance, PibblRenderTransaction, RenderingContext2D } from './types.js';
+export declare const NO_PENDING_ROOT: unique symbol;
+export type PendingRoot = PibblNode | typeof NO_PENDING_ROOT;
+/** @internal Exact Pibbl-owned presentation transforms for the active traversal. */
+export interface PibblPresentationTransformLineage {
+    readonly parent: PibblPresentationTransformLineage | undefined;
+    readonly localTransform: DOMMatrix;
+    /** Number of raw Canvas transform deltas absorbed before this Pibbl node. */
+    readonly untrackedCanvasTransformCount: number;
+}
+export interface GlobalState {
+    pibblInstances: Map<Canvas, PibblInstance>;
+    currentPibblInstance: PibblInstance | undefined;
+    componentRefs: PibblComponentRefs<any> | undefined;
+    canvas: Canvas | undefined;
+    componentIsMounting: boolean;
+    componentHookIndex: number;
+    backendDriver: PibblBackendDriver<unknown> | undefined;
+    backendFrame: PibblBackendFrame<unknown> | undefined;
+    backendEnvironment: unknown;
+    renderContext: RenderingContext2D | undefined;
+    renderTarget: RenderTargetSnapshot | undefined;
+    worldBaseTransform: DOMMatrix | undefined;
+    worldExactTransform: DOMMatrix | undefined;
+    worldPaintAnchorTransform: DOMMatrix | undefined;
+    presentationTransformLineage: PibblPresentationTransformLineage | undefined;
+    presentationTransformLineageTrackingDepth: number;
+    renderTransaction: PibblRenderTransaction | undefined;
+    frameSnapshot: PibblFrameSnapshot | undefined;
+    primitiveReceiverToken: object | undefined;
+    seenIds: Set<string> | undefined;
+    seenKeys: Set<string> | undefined;
+    clippingStack: PibblClippingStackEntry[];
+    htmlFilterDepth: number;
+    layoutStack: LayoutContext[] | undefined;
+    anonElementNames: WeakMap<any, string>;
+    anon: number;
+}
+export declare const GLOBAL_STATE: GlobalState;
+export declare function getComponentRefs(): PibblComponentRefs<any>;
+export declare function getCanvas(): Canvas;
+export declare function getCurrentPibblInstance(): PibblInstance;
+export declare function getInteractionRoot(pibblInstance: PibblInstance): PibblInstance;
+export declare function getPibblInstance(canvas: Canvas): PibblInstance;
+/**
+ * Used to get a name for an anonymous function.
+ * @param fn The anonymous function to get a name for
+ * @returns A name for the anonymous function
+ */
+export declare function getAnonElemName(fn: any): string;
+/**
+ * Useful for testing and HMR.
+ * DO NOT USE IN PROD
+ */
+export declare function clearSharedState(): void;
+export declare function cleanupPibblInstance(pibblInstance: PibblInstance): void;
+export declare function clearTempState(): void;
+export declare function clearComponentState(): void;

package/dist/lib/global-state.js

@@ -0,0 +1,176 @@
+import { unregisterRootInstance } from "./scheduler/realm-scheduler.js";
+import { runTeardown } from "./teardowns.js";
+const NO_PENDING_ROOT = /* @__PURE__ */ Symbol("PIBBL_NO_PENDING_ROOT");
+const GLOBAL_STATE = {
+  pibblInstances: /* @__PURE__ */ new Map(),
+  currentPibblInstance: void 0,
+  componentRefs: void 0,
+  canvas: void 0,
+  componentIsMounting: false,
+  componentHookIndex: 0,
+  backendDriver: void 0,
+  backendFrame: void 0,
+  backendEnvironment: void 0,
+  renderContext: void 0,
+  renderTarget: void 0,
+  worldBaseTransform: void 0,
+  worldExactTransform: void 0,
+  worldPaintAnchorTransform: void 0,
+  presentationTransformLineage: void 0,
+  presentationTransformLineageTrackingDepth: 0,
+  renderTransaction: void 0,
+  frameSnapshot: void 0,
+  primitiveReceiverToken: void 0,
+  seenIds: void 0,
+  seenKeys: void 0,
+  clippingStack: [],
+  htmlFilterDepth: 0,
+  layoutStack: void 0,
+  anonElementNames: /* @__PURE__ */ new WeakMap(),
+  anon: 0
+};
+function getComponentRefs() {
+  if (!GLOBAL_STATE.componentRefs) {
+    throw new Error("No component refs available");
+  }
+  return GLOBAL_STATE.componentRefs;
+}
+function getCanvas() {
+  if (!GLOBAL_STATE.canvas) {
+    throw new Error("No canvas available");
+  }
+  return GLOBAL_STATE.canvas;
+}
+function getCurrentPibblInstance() {
+  if (!GLOBAL_STATE.currentPibblInstance) {
+    throw new Error("No Pibbl instance available");
+  }
+  return GLOBAL_STATE.currentPibblInstance;
+}
+function getInteractionRoot(pibblInstance) {
+  return pibblInstance.interactionRoot ?? pibblInstance;
+}
+function getPibblInstance(canvas) {
+  const pibblInstance = GLOBAL_STATE.pibblInstances.get(canvas);
+  if (!pibblInstance) {
+    throw new Error("Pibbl instance not found");
+  }
+  return pibblInstance;
+}
+function getAnonElemName(fn) {
+  if (!GLOBAL_STATE.anonElementNames.has(fn)) {
+    GLOBAL_STATE.anonElementNames.set(fn, `Anon${GLOBAL_STATE.anon++}`);
+  }
+  return GLOBAL_STATE.anonElementNames.get(fn);
+}
+function clearSharedState() {
+  for (const pibblInstance of Array.from(GLOBAL_STATE.pibblInstances.values())) {
+    pibblInstance.controller.dispose();
+  }
+  GLOBAL_STATE.pibblInstances.clear();
+  GLOBAL_STATE.clippingStack = [];
+  GLOBAL_STATE.layoutStack = void 0;
+  GLOBAL_STATE.anonElementNames = /* @__PURE__ */ new WeakMap();
+  clearTempState();
+}
+function cleanupPibblInstance(pibblInstance) {
+  const { canvas } = pibblInstance;
+  if (pibblInstance.mainTeardowns.closed) {
+    return;
+  }
+  if (!pibblInstance.parent) {
+    unregisterRootInstance(pibblInstance);
+  }
+  if (GLOBAL_STATE.pibblInstances.get(canvas) === pibblInstance) {
+    GLOBAL_STATE.pibblInstances.delete(canvas);
+  }
+  pibblInstance.eventParent = void 0;
+  pibblInstance.focusParentBridge = void 0;
+  pibblInstance.mainTeardowns.execute();
+  runTeardown(() => pibblInstance.backendDriver.dispose());
+  runTeardown(() => {
+    for (const service of pibblInstance.optionalServices.values()) service.dispose();
+    pibblInstance.optionalServices.clear();
+  });
+  if (!pibblInstance.parent) {
+    for (const observers of pibblInstance.eventRoot.observers.values()) {
+      observers.clear();
+    }
+    pibblInstance.eventRoot.observers.clear();
+    pibblInstance.eventRoot.targets.clear();
+    for (const listeners of pibblInstance.eventRoot.listenersByComponent.values()) {
+      listeners.clear();
+    }
+    pibblInstance.eventRoot.listenersByComponent.clear();
+    pibblInstance.eventRoot.pointerCaptures.clear();
+    pibblInstance.eventRoot.onNodeRelease = void 0;
+    pibblInstance.eventRoot.onTargetUpdate = void 0;
+    pibblInstance.eventRoot.focusPolicy = void 0;
+    pibblInstance.eventRoot.renderTransaction = void 0;
+    pibblInstance.eventRoot.rootInstance = void 0;
+  }
+  pibblInstance.regions?.clear();
+  pibblInstance.paintEntries?.clear();
+  pibblInstance.cursorDefaults?.clear();
+  const interaction = pibblInstance.interaction;
+  if (interaction) {
+    if (interaction.cursorCanvas && interaction.cursorStyle && interaction.cursorCanvas.style.cursor === interaction.cursorStyle) {
+      interaction.cursorCanvas.style.removeProperty("cursor");
+    }
+    interaction.hoveredRegion = void 0;
+    interaction.primaryDown = void 0;
+    interaction.primaryUp = void 0;
+    interaction.auxiliaryDown.clear();
+    interaction.auxiliaryUp.clear();
+    interaction.clickStreakTarget = void 0;
+    interaction.clickStreak = 0;
+    interaction.cursorRegion = void 0;
+    interaction.cursorDefault = void 0;
+    interaction.pointerCanvas = void 0;
+    interaction.cursorCanvas = void 0;
+    interaction.cursorStyle = void 0;
+  }
+  pibblInstance.refs.clear();
+  pibblInstance.pendingRoot = NO_PENDING_ROOT;
+  pibblInstance.pendingUpdateParents = false;
+}
+function clearTempState() {
+  GLOBAL_STATE.seenIds = void 0;
+  GLOBAL_STATE.seenKeys = void 0;
+  GLOBAL_STATE.canvas = void 0;
+  GLOBAL_STATE.backendDriver = void 0;
+  GLOBAL_STATE.backendFrame = void 0;
+  GLOBAL_STATE.backendEnvironment = void 0;
+  GLOBAL_STATE.renderContext = void 0;
+  GLOBAL_STATE.renderTarget = void 0;
+  GLOBAL_STATE.worldBaseTransform = void 0;
+  GLOBAL_STATE.worldExactTransform = void 0;
+  GLOBAL_STATE.worldPaintAnchorTransform = void 0;
+  GLOBAL_STATE.presentationTransformLineage = void 0;
+  GLOBAL_STATE.presentationTransformLineageTrackingDepth = 0;
+  GLOBAL_STATE.renderTransaction = void 0;
+  GLOBAL_STATE.frameSnapshot = void 0;
+  GLOBAL_STATE.primitiveReceiverToken = void 0;
+  GLOBAL_STATE.layoutStack = void 0;
+  clearComponentState();
+}
+function clearComponentState() {
+  GLOBAL_STATE.componentRefs = void 0;
+  GLOBAL_STATE.componentIsMounting = false;
+  GLOBAL_STATE.componentHookIndex = 0;
+}
+export {
+  GLOBAL_STATE,
+  NO_PENDING_ROOT,
+  cleanupPibblInstance,
+  clearComponentState,
+  clearSharedState,
+  clearTempState,
+  getAnonElemName,
+  getCanvas,
+  getComponentRefs,
+  getCurrentPibblInstance,
+  getInteractionRoot,
+  getPibblInstance
+};
+//# sourceMappingURL=global-state.js.map

package/dist/lib/global-state.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/global-state.ts"],
+  "sourcesContent": ["import type { LayoutContext } from './layout/types.js';\nimport type { PibblNode } from './element/types.js';\nimport type { RenderTargetSnapshot } from './render-target.js';\nimport type { PibblFrameSnapshot } from './scheduler/types.js';\nimport { unregisterRootInstance } from './scheduler/realm-scheduler.js';\nimport type {\n  PibblBackendDriver,\n  PibblBackendFrame,\n} from './backend/types.js';\nimport type {\n  Canvas,\n  PibblComponentRefs,\n  PibblClippingStackEntry,\n  PibblInstance,\n  PibblRenderTransaction,\n  RenderingContext2D,\n} from './types.js';\nimport { runTeardown } from './teardowns.js';\n\nexport const NO_PENDING_ROOT = Symbol('PIBBL_NO_PENDING_ROOT');\nexport type PendingRoot = PibblNode | typeof NO_PENDING_ROOT;\n\n/** @internal Exact Pibbl-owned presentation transforms for the active traversal. */\nexport interface PibblPresentationTransformLineage {\n  readonly parent: PibblPresentationTransformLineage | undefined;\n  readonly localTransform: DOMMatrix;\n  /** Number of raw Canvas transform deltas absorbed before this Pibbl node. */\n  readonly untrackedCanvasTransformCount: number;\n}\n\nexport interface GlobalState {\n  pibblInstances: Map<Canvas, PibblInstance>;\n  currentPibblInstance: PibblInstance | undefined;\n  componentRefs: PibblComponentRefs<any> | undefined;\n  canvas: Canvas | undefined;\n  componentIsMounting: boolean;\n  componentHookIndex: number;\n  backendDriver: PibblBackendDriver<unknown> | undefined;\n  backendFrame: PibblBackendFrame<unknown> | undefined;\n  backendEnvironment: unknown;\n  renderContext: RenderingContext2D | undefined;\n  renderTarget: RenderTargetSnapshot | undefined;\n  worldBaseTransform: DOMMatrix | undefined;\n  worldExactTransform: DOMMatrix | undefined;\n  worldPaintAnchorTransform: DOMMatrix | undefined;\n  presentationTransformLineage: PibblPresentationTransformLineage | undefined;\n  presentationTransformLineageTrackingDepth: number;\n  renderTransaction: PibblRenderTransaction | undefined;\n  frameSnapshot: PibblFrameSnapshot | undefined;\n  primitiveReceiverToken: object | undefined;\n  seenIds: Set<string> | undefined;\n  seenKeys: Set<string> | undefined;\n  clippingStack: PibblClippingStackEntry[];\n  htmlFilterDepth: number;\n  layoutStack: LayoutContext[] | undefined;\n  anonElementNames: WeakMap<any, string>;\n  anon: number;\n}\n\nexport const GLOBAL_STATE: GlobalState = {\n  pibblInstances: new Map(),\n  currentPibblInstance: undefined,\n  componentRefs: undefined,\n  canvas: undefined,\n  componentIsMounting: false,\n  componentHookIndex: 0,\n  backendDriver: undefined,\n  backendFrame: undefined,\n  backendEnvironment: undefined,\n  renderContext: undefined,\n  renderTarget: undefined,\n  worldBaseTransform: undefined,\n  worldExactTransform: undefined,\n  worldPaintAnchorTransform: undefined,\n  presentationTransformLineage: undefined,\n  presentationTransformLineageTrackingDepth: 0,\n  renderTransaction: undefined,\n  frameSnapshot: undefined,\n  primitiveReceiverToken: undefined,\n  seenIds: undefined,\n  seenKeys: undefined,\n  clippingStack: [],\n  htmlFilterDepth: 0,\n  layoutStack: undefined,\n  anonElementNames: new WeakMap(),\n  anon: 0,\n};\n\nexport function getComponentRefs() {\n  if (!GLOBAL_STATE.componentRefs) {\n    throw new Error('No component refs available');\n  }\n  return GLOBAL_STATE.componentRefs;\n}\n\nexport function getCanvas() {\n  if (!GLOBAL_STATE.canvas) {\n    throw new Error('No canvas available');\n  }\n  return GLOBAL_STATE.canvas;\n}\n\nexport function getCurrentPibblInstance() {\n  if (!GLOBAL_STATE.currentPibblInstance) {\n    throw new Error('No Pibbl instance available');\n  }\n  return GLOBAL_STATE.currentPibblInstance;\n}\n\nexport function getInteractionRoot(pibblInstance: PibblInstance): PibblInstance {\n  return pibblInstance.interactionRoot ?? pibblInstance;\n}\n\nexport function getPibblInstance(canvas: Canvas) {\n  const pibblInstance = GLOBAL_STATE.pibblInstances.get(canvas);\n  if (!pibblInstance) {\n    throw new Error('Pibbl instance not found');\n  }\n  return pibblInstance;\n}\n\n/**\n * Used to get a name for an anonymous function.\n * @param fn The anonymous function to get a name for\n * @returns A name for the anonymous function\n */\nexport function getAnonElemName(fn: any) {\n  if (!GLOBAL_STATE.anonElementNames.has(fn)) {\n    GLOBAL_STATE.anonElementNames.set(fn, `Anon${GLOBAL_STATE.anon++}`);\n  }\n  return GLOBAL_STATE.anonElementNames.get(fn)!;\n}\n\n/**\n * Useful for testing and HMR.\n * DO NOT USE IN PROD\n */\nexport function clearSharedState() {\n  for (const pibblInstance of Array.from(GLOBAL_STATE.pibblInstances.values())) {\n    pibblInstance.controller.dispose();\n  }\n  GLOBAL_STATE.pibblInstances.clear();\n  GLOBAL_STATE.clippingStack = [];\n  GLOBAL_STATE.layoutStack = undefined;\n  GLOBAL_STATE.anonElementNames = new WeakMap<any, string>();\n  clearTempState();\n}\n\nexport function cleanupPibblInstance(pibblInstance: PibblInstance): void {\n  const { canvas } = pibblInstance;\n  if (pibblInstance.mainTeardowns.closed) {\n    return;\n  }\n\n  if (!pibblInstance.parent) {\n    unregisterRootInstance(pibblInstance);\n  }\n\n  if (GLOBAL_STATE.pibblInstances.get(canvas) === pibblInstance) {\n    GLOBAL_STATE.pibblInstances.delete(canvas);\n  }\n  pibblInstance.eventParent = undefined;\n  pibblInstance.focusParentBridge = undefined;\n  pibblInstance.mainTeardowns.execute();\n  runTeardown(() => pibblInstance.backendDriver.dispose());\n  runTeardown(() => {\n    for (const service of pibblInstance.optionalServices.values()) service.dispose();\n    pibblInstance.optionalServices.clear();\n  });\n  if (!pibblInstance.parent) {\n    for (const observers of pibblInstance.eventRoot.observers.values()) {\n      observers.clear();\n    }\n    pibblInstance.eventRoot.observers.clear();\n    pibblInstance.eventRoot.targets.clear();\n    for (const listeners of pibblInstance.eventRoot.listenersByComponent.values()) {\n      listeners.clear();\n    }\n    pibblInstance.eventRoot.listenersByComponent.clear();\n    pibblInstance.eventRoot.pointerCaptures.clear();\n    pibblInstance.eventRoot.onNodeRelease = undefined;\n    pibblInstance.eventRoot.onTargetUpdate = undefined;\n    pibblInstance.eventRoot.focusPolicy = undefined;\n    pibblInstance.eventRoot.renderTransaction = undefined;\n    pibblInstance.eventRoot.rootInstance = undefined;\n  }\n  pibblInstance.regions?.clear();\n  pibblInstance.paintEntries?.clear();\n  pibblInstance.cursorDefaults?.clear();\n  const interaction = pibblInstance.interaction;\n  if (interaction) {\n    if (\n      interaction.cursorCanvas &&\n      interaction.cursorStyle &&\n      interaction.cursorCanvas.style.cursor === interaction.cursorStyle\n    ) {\n      interaction.cursorCanvas.style.removeProperty('cursor');\n    }\n    interaction.hoveredRegion = undefined;\n    interaction.primaryDown = undefined;\n    interaction.primaryUp = undefined;\n    interaction.auxiliaryDown.clear();\n    interaction.auxiliaryUp.clear();\n    interaction.clickStreakTarget = undefined;\n    interaction.clickStreak = 0;\n    interaction.cursorRegion = undefined;\n    interaction.cursorDefault = undefined;\n    interaction.pointerCanvas = undefined;\n    interaction.cursorCanvas = undefined;\n    interaction.cursorStyle = undefined;\n  }\n  pibblInstance.refs.clear();\n  pibblInstance.pendingRoot = NO_PENDING_ROOT;\n  pibblInstance.pendingUpdateParents = false;\n}\n\nexport function clearTempState() {\n  GLOBAL_STATE.seenIds = undefined;\n  GLOBAL_STATE.seenKeys = undefined;\n  GLOBAL_STATE.canvas = undefined;\n  GLOBAL_STATE.backendDriver = undefined;\n  GLOBAL_STATE.backendFrame = undefined;\n  GLOBAL_STATE.backendEnvironment = undefined;\n  GLOBAL_STATE.renderContext = undefined;\n  GLOBAL_STATE.renderTarget = undefined;\n  GLOBAL_STATE.worldBaseTransform = undefined;\n  GLOBAL_STATE.worldExactTransform = undefined;\n  GLOBAL_STATE.worldPaintAnchorTransform = undefined;\n  GLOBAL_STATE.presentationTransformLineage = undefined;\n  GLOBAL_STATE.presentationTransformLineageTrackingDepth = 0;\n  GLOBAL_STATE.renderTransaction = undefined;\n  GLOBAL_STATE.frameSnapshot = undefined;\n  GLOBAL_STATE.primitiveReceiverToken = undefined;\n  GLOBAL_STATE.layoutStack = undefined;\n  clearComponentState();\n}\n\nexport function clearComponentState() {\n  GLOBAL_STATE.componentRefs = undefined;\n  GLOBAL_STATE.componentIsMounting = false;\n  GLOBAL_STATE.componentHookIndex = 0;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/hooks/hook-slot.d.ts

@@ -0,0 +1,30 @@
+import { Teardowns } from '../teardowns.js';
+import type { PibblComponentRefs, PibblInstance, PibblHookSlot } from '../types.js';
+export declare const HOOK_CONTEXT_ERROR = "Pibbl hooks can only be called while rendering a component.";
+export interface HookContext {
+    componentRefs: PibblComponentRefs<any>;
+    pibblInstance: PibblInstance;
+}
+export declare function requireHookContext(): HookContext;
+/**
+ * @internal Prevents hook calls from nested user callbacks.
+ *
+ * @param reason - Diagnostic explanation reported if the callback tries to use a hook.
+ * @param callback - Synchronous work to run with hooks forbidden.
+ * @returns The callback's return value.
+ *
+ * @see {@link useInternalHookSlot}
+ */
+export declare function withHooksForbidden<T>(reason: string, callback: () => T): T;
+export declare function useHookSlot<T>(kind: string, initialize: (teardowns: Teardowns) => T): PibblHookSlot<T>;
+/**
+ * Official-renderer friend hook for component-owned values and teardowns.
+ *
+ * @param kind - Hook kind used to validate stable hook ordering.
+ * @param initialize - Initializer receiving the slot's teardown collection. See {@link Teardowns}.
+ * @returns The current mounted hook slot. See {@link PibblHookSlot}.
+ *
+ * @see {@link withHooksForbidden}
+ */
+export declare function useInternalHookSlot<T>(kind: string, initialize: (teardowns: Teardowns) => T): PibblHookSlot<T>;
+export declare function finalizeHookSlots(componentRefs: PibblComponentRefs<any>): void;

package/dist/lib/hooks/hook-slot.js

@@ -0,0 +1,66 @@
+import { GLOBAL_STATE } from "../global-state.js";
+import { Teardowns } from "../teardowns.js";
+const HOOK_CONTEXT_ERROR = "Pibbl hooks can only be called while rendering a component.";
+let hookCallsForbiddenReason;
+function requireHookContext() {
+  if (hookCallsForbiddenReason !== void 0) {
+    throw new Error(hookCallsForbiddenReason);
+  }
+  const componentRefs = GLOBAL_STATE.componentRefs;
+  const pibblInstance = GLOBAL_STATE.currentPibblInstance;
+  if (!componentRefs || !pibblInstance || !GLOBAL_STATE.canvas) {
+    throw new Error(HOOK_CONTEXT_ERROR);
+  }
+  return { componentRefs, pibblInstance };
+}
+function withHooksForbidden(reason, callback) {
+  const previous = hookCallsForbiddenReason;
+  hookCallsForbiddenReason = reason;
+  try {
+    return callback();
+  } finally {
+    hookCallsForbiddenReason = previous;
+  }
+}
+function useHookSlot(kind, initialize) {
+  const { componentRefs } = requireHookContext();
+  const hookIndex = GLOBAL_STATE.componentHookIndex++;
+  let slot = componentRefs.hooks[hookIndex];
+  if (GLOBAL_STATE.componentIsMounting) {
+    const teardowns = new Teardowns();
+    teardowns.follow(componentRefs.teardowns);
+    slot = { kind, value: initialize(teardowns), teardowns };
+    componentRefs.hooks[hookIndex] = slot;
+  } else if (!slot) {
+    throw new Error(
+      `Rendered more Pibbl hooks than the previous render at hook ${hookIndex}.`
+    );
+  } else if (slot.kind !== kind) {
+    throw new Error(
+      `Pibbl hook order changed at hook ${hookIndex}: expected ${slot.kind}, received ${kind}.`
+    );
+  }
+  return slot;
+}
+function useInternalHookSlot(kind, initialize) {
+  return useHookSlot(kind, initialize);
+}
+function finalizeHookSlots(componentRefs) {
+  const usedHooks = GLOBAL_STATE.componentHookIndex;
+  if (usedHooks >= componentRefs.hooks.length) return;
+  for (const slot of componentRefs.hooks.slice(usedHooks)) {
+    slot.teardowns.execute();
+  }
+  throw new Error(
+    `Rendered fewer Pibbl hooks than the previous render: expected ${componentRefs.hooks.length}, received ${usedHooks}.`
+  );
+}
+export {
+  HOOK_CONTEXT_ERROR,
+  finalizeHookSlots,
+  requireHookContext,
+  useHookSlot,
+  useInternalHookSlot,
+  withHooksForbidden
+};
+//# sourceMappingURL=hook-slot.js.map

package/dist/lib/hooks/hook-slot.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/hooks/hook-slot.ts"],
+  "sourcesContent": ["import { GLOBAL_STATE } from '../global-state.js';\nimport { Teardowns } from '../teardowns.js';\nimport type { PibblComponentRefs, PibblInstance, PibblHookSlot } from '../types.js';\n\nexport const HOOK_CONTEXT_ERROR =\n  'Pibbl hooks can only be called while rendering a component.';\n\nlet hookCallsForbiddenReason: string | undefined;\n\nexport interface HookContext {\n  componentRefs: PibblComponentRefs<any>;\n  pibblInstance: PibblInstance;\n}\n\nexport function requireHookContext(): HookContext {\n  if (hookCallsForbiddenReason !== undefined) {\n    throw new Error(hookCallsForbiddenReason);\n  }\n  const componentRefs = GLOBAL_STATE.componentRefs;\n  const pibblInstance = GLOBAL_STATE.currentPibblInstance;\n  if (!componentRefs || !pibblInstance || !GLOBAL_STATE.canvas) {\n    throw new Error(HOOK_CONTEXT_ERROR);\n  }\n  return { componentRefs, pibblInstance };\n}\n\n/**\n * @internal Prevents hook calls from nested user callbacks.\n *\n * @param reason - Diagnostic explanation reported if the callback tries to use a hook.\n * @param callback - Synchronous work to run with hooks forbidden.\n * @returns The callback's return value.\n *\n * @see {@link useInternalHookSlot}\n */\nexport function withHooksForbidden<T>(\n  reason: string,\n  callback: () => T,\n): T {\n  const previous = hookCallsForbiddenReason;\n  hookCallsForbiddenReason = reason;\n  try {\n    return callback();\n  } finally {\n    hookCallsForbiddenReason = previous;\n  }\n}\n\nexport function useHookSlot<T>(\n  kind: string,\n  initialize: (teardowns: Teardowns) => T,\n): PibblHookSlot<T> {\n  const { componentRefs } = requireHookContext();\n  const hookIndex = GLOBAL_STATE.componentHookIndex++;\n  let slot = componentRefs.hooks[hookIndex] as PibblHookSlot<T> | undefined;\n\n  if (GLOBAL_STATE.componentIsMounting) {\n    const teardowns = new Teardowns();\n    teardowns.follow(componentRefs.teardowns);\n    slot = { kind, value: initialize(teardowns), teardowns };\n    componentRefs.hooks[hookIndex] = slot;\n  } else if (!slot) {\n    throw new Error(\n      `Rendered more Pibbl hooks than the previous render at hook ${hookIndex}.`,\n    );\n  } else if (slot.kind !== kind) {\n    throw new Error(\n      `Pibbl hook order changed at hook ${hookIndex}: expected ${slot.kind}, received ${kind}.`,\n    );\n  }\n\n  return slot;\n}\n\n/**\n * Official-renderer friend hook for component-owned values and teardowns.\n *\n * @param kind - Hook kind used to validate stable hook ordering.\n * @param initialize - Initializer receiving the slot's teardown collection. See {@link Teardowns}.\n * @returns The current mounted hook slot. See {@link PibblHookSlot}.\n *\n * @see {@link withHooksForbidden}\n */\nexport function useInternalHookSlot<T>(\n  kind: string,\n  initialize: (teardowns: Teardowns) => T,\n): PibblHookSlot<T> {\n  return useHookSlot(kind, initialize);\n}\n\nexport function finalizeHookSlots(componentRefs: PibblComponentRefs<any>): void {\n  const usedHooks = GLOBAL_STATE.componentHookIndex;\n  if (usedHooks >= componentRefs.hooks.length) return;\n\n  for (const slot of componentRefs.hooks.slice(usedHooks)) {\n    slot.teardowns.execute();\n  }\n  throw new Error(\n    `Rendered fewer Pibbl hooks than the previous render: expected ${componentRefs.hooks.length}, received ${usedHooks}.`,\n  );\n}\n"],
+  "mappings": "AAAA,SAAS,oBAAoB;AAC7B,SAAS,iBAAiB;AAGnB,MAAM,qBACX;AAEF,IAAI;AAOG,SAAS,qBAAkC;AAChD,MAAI,6BAA6B,QAAW;AAC1C,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC1C;AACA,QAAM,gBAAgB,aAAa;AACnC,QAAM,gBAAgB,aAAa;AACnC,MAAI,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,aAAa,QAAQ;AAC5D,UAAM,IAAI,MAAM,kBAAkB;AAAA,EACpC;AACA,SAAO,EAAE,eAAe,cAAc;AACxC;AAWO,SAAS,mBACd,QACA,UACG;AACH,QAAM,WAAW;AACjB,6BAA2B;AAC3B,MAAI;AACF,WAAO,SAAS;AAAA,EAClB,UAAE;AACA,+BAA2B;AAAA,EAC7B;AACF;AAEO,SAAS,YACd,MACA,YACkB;AAClB,QAAM,EAAE,cAAc,IAAI,mBAAmB;AAC7C,QAAM,YAAY,aAAa;AAC/B,MAAI,OAAO,cAAc,MAAM,SAAS;AAExC,MAAI,aAAa,qBAAqB;AACpC,UAAM,YAAY,IAAI,UAAU;AAChC,cAAU,OAAO,cAAc,SAAS;AACxC,WAAO,EAAE,MAAM,OAAO,WAAW,SAAS,GAAG,UAAU;AACvD,kBAAc,MAAM,SAAS,IAAI;AAAA,EACnC,WAAW,CAAC,MAAM;AAChB,UAAM,IAAI;AAAA,MACR,8DAA8D,SAAS;AAAA,IACzE;AAAA,EACF,WAAW,KAAK,SAAS,MAAM;AAC7B,UAAM,IAAI;AAAA,MACR,oCAAoC,SAAS,cAAc,KAAK,IAAI,cAAc,IAAI;AAAA,IACxF;AAAA,EACF;AAEA,SAAO;AACT;AAWO,SAAS,oBACd,MACA,YACkB;AAClB,SAAO,YAAY,MAAM,UAAU;AACrC;AAEO,SAAS,kBAAkB,eAA8C;AAC9E,QAAM,YAAY,aAAa;AAC/B,MAAI,aAAa,cAAc,MAAM,OAAQ;AAE7C,aAAW,QAAQ,cAAc,MAAM,MAAM,SAAS,GAAG;AACvD,SAAK,UAAU,QAAQ;AAAA,EACzB;AACA,QAAM,IAAI;AAAA,IACR,iEAAiE,cAAc,MAAM,MAAM,cAAc,SAAS;AAAA,EACpH;AACF;",
+  "names": []
+}