@pibbl/core 0.0.1

package/dist/lib/hooks/use-layout-box.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/hooks/use-layout-box.ts"],
+  "sourcesContent": ["import { getLayoutBox } from '../layout/context.js';\nimport type { LayoutBox } from '../layout/types.js';\n\n/**\n * Returns the current stable child-local allocation without scheduling work.\n *\n * @returns The current parent-assigned layout box in logical coordinates. See {@link LayoutBox}.\n *\n * @see {@link LayoutBox}\n */\nexport function useLayoutBox(): Readonly<LayoutBox> {\n  return getLayoutBox();\n}\n"],
+  "mappings": "AAAA,SAAS,oBAAoB;AAUtB,SAAS,eAAoC;AAClD,SAAO,aAAa;AACtB;",
+  "names": []
+}

package/dist/lib/hooks/use-line-path.d.ts

@@ -0,0 +1,14 @@
+import type { LinePathOptions } from "../geometry/line.js";
+import type { createLinePath } from "../geometry/line.js";
+/**
+ * Creates a memoized Path2D for a set of line coordinates.
+ * @param coords - Ordered horizontal and vertical coordinate pairs.
+ * @param config - Whether to close the path by connecting its last vertex to its first.
+ * @returns A memoized Path2D
+ *
+ * @see {@link LinePathOptions}
+ * @see {@link createLinePath}
+ */
+export declare function useLinePath(coords: [number, number][], config?: {
+    closePath?: boolean;
+}): Path2D;

package/dist/lib/hooks/use-line-path.js

@@ -0,0 +1,13 @@
+import { createLinePath } from "../geometry/line.js";
+import { useValueMemoSlot } from "./use-value-memo-slot.js";
+function useLinePath(coords, config) {
+  return useValueMemoSlot(
+    "linePath",
+    () => createLinePath({ coords, closePath: config?.closePath }),
+    [...coords.flat(), config?.closePath]
+  );
+}
+export {
+  useLinePath
+};
+//# sourceMappingURL=use-line-path.js.map

package/dist/lib/hooks/use-line-path.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/hooks/use-line-path.ts"],
+  "sourcesContent": ["import type { LinePathOptions } from '../geometry/line.js';\nimport { createLinePath } from '../geometry/line.js';\nimport { useValueMemoSlot } from './use-value-memo-slot.js';\n\n/**\n * Creates a memoized Path2D for a set of line coordinates.\n * @param coords - Ordered horizontal and vertical coordinate pairs.\n * @param config - Whether to close the path by connecting its last vertex to its first.\n * @returns A memoized Path2D\n *\n * @see {@link LinePathOptions}\n * @see {@link createLinePath}\n */\nexport function useLinePath(\n  coords: [number, number][],\n  config?: { closePath?: boolean },\n): Path2D {\n  return useValueMemoSlot(\n    'linePath',\n    () => createLinePath({ coords, closePath: config?.closePath }),\n    [...coords.flat(), config?.closePath],\n  );\n}\n"],
+  "mappings": "AACA,SAAS,sBAAsB;AAC/B,SAAS,wBAAwB;AAW1B,SAAS,YACd,QACA,QACQ;AACR,SAAO;AAAA,IACL;AAAA,IACA,MAAM,eAAe,EAAE,QAAQ,WAAW,QAAQ,UAAU,CAAC;AAAA,IAC7D,CAAC,GAAG,OAAO,KAAK,GAAG,QAAQ,SAAS;AAAA,EACtC;AACF;",
+  "names": []
+}

package/dist/lib/hooks/use-paint-target.d.ts

@@ -0,0 +1,3 @@
+import type { PibblEventHandlers, PibblEventTargetOptions, PibblEventTargetSnapshot, PibblPointerEvents } from '../events/types.js';
+/** @internal Keeps a built-in drawing primitive in paint hit testing by default. */
+export declare function usePaintTarget(handlers: PibblEventHandlers, options: PibblEventTargetOptions, pointerEvents?: PibblPointerEvents): PibblEventTargetSnapshot;

package/dist/lib/hooks/use-paint-target.js

@@ -0,0 +1,34 @@
+import {
+  createTarget,
+  releaseTarget,
+  updateTarget
+} from "../events/registrations.js";
+import { GLOBAL_STATE } from "../global-state.js";
+import { requireHookContext, useHookSlot } from "./hook-slot.js";
+const UNFOCUSED_SNAPSHOT = Object.freeze({
+  isFocused: false,
+  isFocusVisible: false
+});
+function usePaintTarget(handlers, options, pointerEvents = "auto") {
+  const { componentRefs, pibblInstance } = requireHookContext();
+  const hookIndex = GLOBAL_STATE.componentHookIndex;
+  const slot = useHookSlot(
+    "paintTarget",
+    (teardowns) => {
+      const target2 = createTarget(pibblInstance, componentRefs, hookIndex);
+      teardowns.add(() => releaseTarget(target2));
+      return target2;
+    }
+  );
+  const target = slot.value;
+  if (pointerEvents === "none") {
+    releaseTarget(target);
+  } else {
+    updateTarget(target, handlers, options, true);
+  }
+  return pibblInstance.eventRoot.focusPolicy?.snapshot(target) ?? UNFOCUSED_SNAPSHOT;
+}
+export {
+  usePaintTarget
+};
+//# sourceMappingURL=use-paint-target.js.map

package/dist/lib/hooks/use-paint-target.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/hooks/use-paint-target.ts"],
+  "sourcesContent": ["import type {\n  PibblEventHandlers,\n  PibblEventTargetOptions,\n  PibblEventTargetSnapshot,\n  PibblPointerEvents,\n} from '../events/types.js';\nimport {\n  createTarget,\n  releaseTarget,\n  updateTarget,\n  type PibblEventTargetRegistration,\n} from '../events/registrations.js';\nimport { GLOBAL_STATE } from '../global-state.js';\nimport { requireHookContext, useHookSlot } from './hook-slot.js';\n\nconst UNFOCUSED_SNAPSHOT: PibblEventTargetSnapshot = Object.freeze({\n  isFocused: false,\n  isFocusVisible: false,\n});\n\n/** @internal Keeps a built-in drawing primitive in paint hit testing by default. */\nexport function usePaintTarget(\n  handlers: PibblEventHandlers,\n  options: PibblEventTargetOptions,\n  pointerEvents: PibblPointerEvents = 'auto',\n): PibblEventTargetSnapshot {\n  const { componentRefs, pibblInstance } = requireHookContext();\n  const hookIndex = GLOBAL_STATE.componentHookIndex;\n  const slot = useHookSlot<PibblEventTargetRegistration>(\n    'paintTarget',\n    teardowns => {\n      const target = createTarget(pibblInstance, componentRefs, hookIndex);\n      teardowns.add(() => releaseTarget(target));\n      return target;\n    },\n  );\n  const target = slot.value;\n  if (pointerEvents === 'none') {\n    releaseTarget(target);\n  } else {\n    updateTarget(target, handlers, options, true);\n  }\n  return pibblInstance.eventRoot.focusPolicy?.snapshot(target) ??\n    UNFOCUSED_SNAPSHOT;\n}\n"],
+  "mappings": "AAMA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP,SAAS,oBAAoB;AAC7B,SAAS,oBAAoB,mBAAmB;AAEhD,MAAM,qBAA+C,OAAO,OAAO;AAAA,EACjE,WAAW;AAAA,EACX,gBAAgB;AAClB,CAAC;AAGM,SAAS,eACd,UACA,SACA,gBAAoC,QACV;AAC1B,QAAM,EAAE,eAAe,cAAc,IAAI,mBAAmB;AAC5D,QAAM,YAAY,aAAa;AAC/B,QAAM,OAAO;AAAA,IACX;AAAA,IACA,eAAa;AACX,YAAMA,UAAS,aAAa,eAAe,eAAe,SAAS;AACnE,gBAAU,IAAI,MAAM,cAAcA,OAAM,CAAC;AACzC,aAAOA;AAAA,IACT;AAAA,EACF;AACA,QAAM,SAAS,KAAK;AACpB,MAAI,kBAAkB,QAAQ;AAC5B,kBAAc,MAAM;AAAA,EACtB,OAAO;AACL,iBAAa,QAAQ,UAAU,SAAS,IAAI;AAAA,EAC9C;AACA,SAAO,cAAc,UAAU,aAAa,SAAS,MAAM,KACzD;AACJ;",
+  "names": ["target"]
+}

package/dist/lib/hooks/use-playback.d.ts

@@ -0,0 +1,21 @@
+import type { PibblAnimationProgram, PibblPlayback, PibblPlaybackOptions } from '../animation/types.js';
+import type { SignalValue } from '../signals/types.js';
+type PibblPlaybackOptionsInput = {
+    readonly [K in keyof PibblPlaybackOptions]: SignalValue<PibblPlaybackOptions[K]>;
+};
+/**
+ * Creates one component-owned animation playback handle for a hook slot.
+ *
+ * @param programInput - Animation program, optionally supplied by a signal. See
+ * {@link SignalValue} , {@link PibblAnimationProgram} .
+ * @param optionsInput - Playback configuration, optionally supplied by a signal. See
+ * {@link SignalValue} , {@link PibblPlaybackOptionsInput} .
+ * @returns Stable mount-owned playback controls and reactive status/time values. See
+ * {@link PibblPlayback} .
+ *
+ * @see {@link SignalValue}
+ * @see {@link PibblAnimationProgram}
+ * @see {@link PibblPlayback}
+ */
+export declare function usePlayback(programInput: SignalValue<PibblAnimationProgram>, optionsInput?: SignalValue<PibblPlaybackOptionsInput>): PibblPlayback;
+export {};

package/dist/lib/hooks/use-playback.js

@@ -0,0 +1,87 @@
+import {
+  createAnimationPlaybackController,
+  normalizeAnimationPlaybackCandidate
+} from "../animation/playback.js";
+import { GLOBAL_STATE } from "../global-state.js";
+import { isSignal } from "../signals/graph.js";
+import { resolveSignalValue } from "../signals/resolve-signal-value.js";
+import { requireHookContext, useHookSlot } from "./hook-slot.js";
+function isCurrentSlot(slot) {
+  return !slot.componentRefs.teardowns.closed && !slot.pibblInstance.mainTeardowns.closed && GLOBAL_STATE.pibblInstances.get(slot.pibblInstance.canvas) === slot.pibblInstance && slot.pibblInstance.refs.get(slot.componentRefs.id) === slot.componentRefs;
+}
+function controllerOptions(candidate, onEvent, onError) {
+  return {
+    ...candidate,
+    onEvent: typeof candidate.onEvent === "function" ? onEvent : candidate.onEvent,
+    onError: typeof candidate.onError === "function" ? onError : candidate.onError
+  };
+}
+function usePlayback(programInput, optionsInput = {}) {
+  const { componentRefs, pibblInstance } = requireHookContext();
+  const program = resolveSignalValue(programInput);
+  const options = resolvePlaybackOptions(optionsInput);
+  const candidate = normalizeAnimationPlaybackCandidate(program, options);
+  const candidateOptions = candidate.options;
+  const slot = useHookSlot("playback", (teardowns) => {
+    let value;
+    const controller = createAnimationPlaybackController(
+      candidate.program,
+      candidateOptions
+    );
+    const onEvent = (event) => {
+      if (isCurrentSlot(value)) value.latestOptions.onEvent?.(event);
+    };
+    const onError = (error) => {
+      if (isCurrentSlot(value)) value.latestOptions.onError?.(error);
+    };
+    value = {
+      controller,
+      componentRefs,
+      pibblInstance,
+      latestOptions: {},
+      mountSettled: false,
+      onError,
+      onEvent,
+      renderRevision: 0
+    };
+    controller.adopt(
+      candidate.program,
+      controllerOptions(candidateOptions, onEvent, onError)
+    );
+    teardowns.add(() => controller.dispose());
+    return value;
+  }).value;
+  const revision = ++slot.renderRevision;
+  const transaction = GLOBAL_STATE.renderTransaction;
+  if (!transaction) {
+    throw new Error("usePlayback requires an active Pibbl render transaction.");
+  }
+  transaction.onFinish((success) => {
+    if (!success || revision !== slot.renderRevision || !isCurrentSlot(slot)) return;
+    slot.controller.adopt(
+      candidate.program,
+      controllerOptions(candidateOptions, slot.onEvent, slot.onError)
+    );
+    slot.latestOptions = candidateOptions;
+    if (!slot.mountSettled) {
+      slot.mountSettled = true;
+      if (candidateOptions.autoplay === true) slot.controller.handle.play();
+    }
+  });
+  return slot.controller.handle;
+}
+function resolvePlaybackOptions(input) {
+  const source = resolveSignalValue(input);
+  let resolved;
+  for (const key in source) {
+    const value = source[key];
+    if (!isSignal(value)) continue;
+    resolved ??= { ...source };
+    resolved[key] = resolveSignalValue(value);
+  }
+  return resolved ?? source;
+}
+export {
+  usePlayback
+};
+//# sourceMappingURL=use-playback.js.map

package/dist/lib/hooks/use-playback.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/hooks/use-playback.ts"],
+  "sourcesContent": ["import {\n  createAnimationPlaybackController,\n  normalizeAnimationPlaybackCandidate,\n  type AnimationPlaybackController,\n} from '../animation/playback.js';\nimport type {\n  PibblAnimationProgram,\n  PibblPlayback,\n  PibblPlaybackEvent,\n  PibblPlaybackOptions,\n} from '../animation/types.js';\nimport { GLOBAL_STATE } from '../global-state.js';\nimport { isSignal } from '../signals/graph.js';\nimport { resolveSignalValue } from '../signals/resolve-signal-value.js';\nimport type { SignalValue } from '../signals/types.js';\nimport type { PibblComponentRefs, PibblInstance } from '../types.js';\nimport { requireHookContext, useHookSlot } from './hook-slot.js';\n\ntype PibblPlaybackOptionsInput = {\n  readonly [K in keyof PibblPlaybackOptions]: SignalValue<PibblPlaybackOptions[K]>;\n};\n\ninterface PibblPlaybackHookSlot {\n  readonly controller: AnimationPlaybackController;\n  readonly componentRefs: PibblComponentRefs<any>;\n  readonly pibblInstance: PibblInstance;\n  latestOptions: PibblPlaybackOptions;\n  mountSettled: boolean;\n  readonly onError: (error: unknown) => void;\n  readonly onEvent: (event: PibblPlaybackEvent) => void;\n  renderRevision: number;\n}\n\nfunction isCurrentSlot(slot: PibblPlaybackHookSlot): boolean {\n  return !slot.componentRefs.teardowns.closed &&\n    !slot.pibblInstance.mainTeardowns.closed &&\n    GLOBAL_STATE.pibblInstances.get(slot.pibblInstance.canvas) === slot.pibblInstance &&\n    slot.pibblInstance.refs.get(slot.componentRefs.id) === slot.componentRefs;\n}\n\nfunction controllerOptions(\n  candidate: PibblPlaybackOptions,\n  onEvent: (event: PibblPlaybackEvent) => void,\n  onError: (error: unknown) => void,\n): PibblPlaybackOptions {\n  return {\n    ...candidate,\n    onEvent: typeof candidate.onEvent === 'function' ?\n      onEvent : candidate.onEvent,\n    onError: typeof candidate.onError === 'function' ?\n      onError : candidate.onError,\n  };\n}\n\n/**\n * Creates one component-owned animation playback handle for a hook slot.\n *\n * @param programInput - Animation program, optionally supplied by a signal. See\n * {@link SignalValue} , {@link PibblAnimationProgram} .\n * @param optionsInput - Playback configuration, optionally supplied by a signal. See\n * {@link SignalValue} , {@link PibblPlaybackOptionsInput} .\n * @returns Stable mount-owned playback controls and reactive status/time values. See\n * {@link PibblPlayback} .\n *\n * @see {@link SignalValue}\n * @see {@link PibblAnimationProgram}\n * @see {@link PibblPlayback}\n */\nexport function usePlayback(\n  programInput: SignalValue<PibblAnimationProgram>,\n  optionsInput: SignalValue<PibblPlaybackOptionsInput> = {},\n): PibblPlayback {\n  const { componentRefs, pibblInstance } = requireHookContext();\n  const program = resolveSignalValue(programInput);\n  const options = resolvePlaybackOptions(optionsInput);\n  const candidate = normalizeAnimationPlaybackCandidate(program, options);\n  const candidateOptions = candidate.options;\n  const slot = useHookSlot<PibblPlaybackHookSlot>('playback', teardowns => {\n    let value!: PibblPlaybackHookSlot;\n    const controller = createAnimationPlaybackController(\n      candidate.program,\n      candidateOptions,\n    );\n    const onEvent = (event: PibblPlaybackEvent): void => {\n      if (isCurrentSlot(value)) value.latestOptions.onEvent?.(event);\n    };\n    const onError = (error: unknown): void => {\n      if (isCurrentSlot(value)) value.latestOptions.onError?.(error);\n    };\n    value = {\n      controller,\n      componentRefs,\n      pibblInstance,\n      latestOptions: {},\n      mountSettled: false,\n      onError,\n      onEvent,\n      renderRevision: 0,\n    };\n    controller.adopt(\n      candidate.program,\n      controllerOptions(candidateOptions, onEvent, onError),\n    );\n    teardowns.add(() => controller.dispose());\n    return value;\n  }).value;\n  const revision = ++slot.renderRevision;\n  const transaction = GLOBAL_STATE.renderTransaction;\n  if (!transaction) {\n    throw new Error('usePlayback requires an active Pibbl render transaction.');\n  }\n  transaction.onFinish(success => {\n    if (!success || revision !== slot.renderRevision || !isCurrentSlot(slot)) return;\n    slot.controller.adopt(\n      candidate.program,\n      controllerOptions(candidateOptions, slot.onEvent, slot.onError),\n    );\n    slot.latestOptions = candidateOptions;\n    if (!slot.mountSettled) {\n      slot.mountSettled = true;\n      if (candidateOptions.autoplay === true) slot.controller.handle.play();\n    }\n  });\n  return slot.controller.handle;\n}\n\nfunction resolvePlaybackOptions(\n  input: SignalValue<PibblPlaybackOptionsInput>,\n): PibblPlaybackOptions {\n  const source = resolveSignalValue(input);\n  let resolved: Record<PropertyKey, unknown> | undefined;\n  for (const key in source) {\n    const value = source[key as keyof PibblPlaybackOptionsInput];\n    if (!isSignal(value)) continue;\n    resolved ??= { ...source };\n    resolved[key] = resolveSignalValue(value as SignalValue<unknown>);\n  }\n  return (resolved ?? source) as PibblPlaybackOptions;\n}\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,OAEK;AAOP,SAAS,oBAAoB;AAC7B,SAAS,gBAAgB;AACzB,SAAS,0BAA0B;AAGnC,SAAS,oBAAoB,mBAAmB;AAiBhD,SAAS,cAAc,MAAsC;AAC3D,SAAO,CAAC,KAAK,cAAc,UAAU,UACnC,CAAC,KAAK,cAAc,cAAc,UAClC,aAAa,eAAe,IAAI,KAAK,cAAc,MAAM,MAAM,KAAK,iBACpE,KAAK,cAAc,KAAK,IAAI,KAAK,cAAc,EAAE,MAAM,KAAK;AAChE;AAEA,SAAS,kBACP,WACA,SACA,SACsB;AACtB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,SAAS,OAAO,UAAU,YAAY,aACpC,UAAU,UAAU;AAAA,IACtB,SAAS,OAAO,UAAU,YAAY,aACpC,UAAU,UAAU;AAAA,EACxB;AACF;AAgBO,SAAS,YACd,cACA,eAAuD,CAAC,GACzC;AACf,QAAM,EAAE,eAAe,cAAc,IAAI,mBAAmB;AAC5D,QAAM,UAAU,mBAAmB,YAAY;AAC/C,QAAM,UAAU,uBAAuB,YAAY;AACnD,QAAM,YAAY,oCAAoC,SAAS,OAAO;AACtE,QAAM,mBAAmB,UAAU;AACnC,QAAM,OAAO,YAAmC,YAAY,eAAa;AACvE,QAAI;AACJ,UAAM,aAAa;AAAA,MACjB,UAAU;AAAA,MACV;AAAA,IACF;AACA,UAAM,UAAU,CAAC,UAAoC;AACnD,UAAI,cAAc,KAAK,EAAG,OAAM,cAAc,UAAU,KAAK;AAAA,IAC/D;AACA,UAAM,UAAU,CAAC,UAAyB;AACxC,UAAI,cAAc,KAAK,EAAG,OAAM,cAAc,UAAU,KAAK;AAAA,IAC/D;AACA,YAAQ;AAAA,MACN;AAAA,MACA;AAAA,MACA;AAAA,MACA,eAAe,CAAC;AAAA,MAChB,cAAc;AAAA,MACd;AAAA,MACA;AAAA,MACA,gBAAgB;AAAA,IAClB;AACA,eAAW;AAAA,MACT,UAAU;AAAA,MACV,kBAAkB,kBAAkB,SAAS,OAAO;AAAA,IACtD;AACA,cAAU,IAAI,MAAM,WAAW,QAAQ,CAAC;AACxC,WAAO;AAAA,EACT,CAAC,EAAE;AACH,QAAM,WAAW,EAAE,KAAK;AACxB,QAAM,cAAc,aAAa;AACjC,MAAI,CAAC,aAAa;AAChB,UAAM,IAAI,MAAM,0DAA0D;AAAA,EAC5E;AACA,cAAY,SAAS,aAAW;AAC9B,QAAI,CAAC,WAAW,aAAa,KAAK,kBAAkB,CAAC,cAAc,IAAI,EAAG;AAC1E,SAAK,WAAW;AAAA,MACd,UAAU;AAAA,MACV,kBAAkB,kBAAkB,KAAK,SAAS,KAAK,OAAO;AAAA,IAChE;AACA,SAAK,gBAAgB;AACrB,QAAI,CAAC,KAAK,cAAc;AACtB,WAAK,eAAe;AACpB,UAAI,iBAAiB,aAAa,KAAM,MAAK,WAAW,OAAO,KAAK;AAAA,IACtE;AAAA,EACF,CAAC;AACD,SAAO,KAAK,WAAW;AACzB;AAEA,SAAS,uBACP,OACsB;AACtB,QAAM,SAAS,mBAAmB,KAAK;AACvC,MAAI;AACJ,aAAW,OAAO,QAAQ;AACxB,UAAM,QAAQ,OAAO,GAAsC;AAC3D,QAAI,CAAC,SAAS,KAAK,EAAG;AACtB,iBAAa,EAAE,GAAG,OAAO;AACzB,aAAS,GAAG,IAAI,mBAAmB,KAA6B;AAAA,EAClE;AACA,SAAQ,YAAY;AACtB;",
+  "names": []
+}

package/dist/lib/hooks/use-reaction.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Options controlling when a signal reaction runs and how it is named for diagnostics.
+ *
+ * @see {@link useReaction}
+ */
+export interface PibblReactionOptions {
+    /** Optional label used in diagnostics. See {@link PibblReactionOptions}. */
+    readonly debugName?: string;
+}
+/**
+ * Owns one Complete-phase imperative reaction for a mounted hook slot.
+ *
+ * @param setup - Setup callback; its optional returned cleanup runs when replaced or disposed.
+ * @param dependencies - Values controlling when setup is repeated.
+ * @param options - Optional diagnostic name for this reaction. See {@link PibblReactionOptions}.
+ *
+ * @see {@link PibblReactionOptions}
+ */
+export declare function useReaction(setup: () => void | (() => void), dependencies?: readonly unknown[], options?: PibblReactionOptions): void;

package/dist/lib/hooks/use-reaction.js

@@ -0,0 +1,245 @@
+import { GLOBAL_STATE } from "../global-state.js";
+import { queueReactionCompletion } from "../scheduler/realm-scheduler.js";
+import {
+  recordReactionCleanup,
+  recordReactionConsumerCreated,
+  recordReactionConsumerReleased,
+  recordReactionEdgeCreated,
+  recordReactionEdgeReleased,
+  recordReactionFailure,
+  recordReactionRun,
+  untracked,
+  withSignalTracking,
+  withSignalWriteForbidden
+} from "../signals/graph.js";
+import {
+  beginReactiveCollection,
+  collectReactiveDependency,
+  disposeReactiveConsumer,
+  finishReactiveCollection,
+  linkReactiveEdgeToSource,
+  unlinkReactiveEdgeFromSource
+} from "../signals/edge.js";
+import {
+  requireHookContext,
+  useHookSlot,
+  withHooksForbidden
+} from "./hook-slot.js";
+function useReaction(setup, dependencies, options = {}) {
+  const { componentRefs, pibblInstance } = requireHookContext();
+  const dependencySnapshot = snapshotDependencies(dependencies);
+  const slot = useHookSlot("reaction", (teardowns) => {
+    let value;
+    value = {
+      active: true,
+      cancelPending: void 0,
+      cleanup: void 0,
+      componentRefs,
+      consumer: void 0,
+      pibblInstance,
+      dependencies: void 0,
+      debugName: options.debugName,
+      mounted: false,
+      pending: false,
+      pendingGeneration: 0,
+      renderRevision: 0,
+      setup
+    };
+    teardowns.add(() => disposeReaction(value));
+    return value;
+  }).value;
+  const transaction = GLOBAL_STATE.renderTransaction;
+  if (!transaction) {
+    throw new Error("useReaction requires an active Pibbl render transaction.");
+  }
+  const dependenciesChanged = !slot.mounted || !dependencySnapshotsEqual(
+    slot.dependencies,
+    dependencySnapshot
+  );
+  const revision = ++slot.renderRevision;
+  transaction.onFinish((success) => {
+    if (!success || revision !== slot.renderRevision || !isCurrentSlot(slot)) {
+      return;
+    }
+    slot.setup = setup;
+    slot.dependencies = dependencySnapshot;
+    if (!slot.mounted) {
+      slot.mounted = true;
+      slot.consumer = createReactionConsumer(() => scheduleReaction(slot), slot.componentRefs);
+    }
+    if (dependenciesChanged) {
+      clearPendingReaction(slot);
+      runReaction(slot);
+    }
+  });
+}
+function createReactionConsumer(invalidate, ownerComponent) {
+  const state = {
+    kind: "reaction",
+    ownerComponent,
+    dependencyHead: void 0,
+    dependencyTail: void 0,
+    dependencyFreeHead: void 0,
+    dependencyFreeCount: 0,
+    dependencyCount: 0,
+    dependencyHighWater: 0,
+    collectionCursor: void 0,
+    collectionGeneration: 0,
+    collecting: false,
+    disposed: false,
+    addDependency(node) {
+      if (state.collecting) collectReactiveDependency(state, node);
+    },
+    notify() {
+      if (!state.disposed) invalidate();
+    }
+  };
+  recordReactionConsumerCreated();
+  return state;
+}
+function collectReactionReads(consumer, callback) {
+  beginReactiveCollection(consumer);
+  consumer.collecting = true;
+  let result;
+  let failure;
+  let failed = false;
+  try {
+    result = withSignalTracking(consumer, callback);
+  } catch (error) {
+    failed = true;
+    failure = error;
+  } finally {
+    consumer.collecting = false;
+    finishReactiveCollection(
+      consumer,
+      (edge) => {
+        if (!edge.sourceLinked) {
+          const source = edge.source;
+          linkReactiveEdgeToSource(edge, source.observe?.());
+          recordReactionEdgeCreated();
+        }
+        edge.observedVersion = edge.source.version;
+        edge.collectionKind = void 0;
+      },
+      releaseReactionEdge
+    );
+  }
+  if (failed) throw failure;
+  return result;
+}
+function scheduleReaction(slot) {
+  if (!slot.active || slot.pending) return;
+  slot.pending = true;
+  const generation = ++slot.pendingGeneration;
+  slot.cancelPending = queueReactionCompletion(() => {
+    if (!slot.active || !slot.pending || generation !== slot.pendingGeneration) {
+      return;
+    }
+    slot.pending = false;
+    slot.cancelPending = void 0;
+    runReaction(slot);
+  });
+}
+function runReaction(slot) {
+  if (!slot.active || slot.consumer === void 0) return;
+  const failures = [];
+  const cleanup = slot.cleanup;
+  slot.cleanup = void 0;
+  if (cleanup !== void 0) {
+    try {
+      runCleanup(cleanup);
+    } catch (error) {
+      recordReactionFailure();
+      failures.push(error);
+    }
+  }
+  recordReactionRun();
+  try {
+    const nextCleanup = collectReactionReads(
+      slot.consumer,
+      () => withSignalWriteForbidden(
+        "Cannot write to a signal during useReaction setup.",
+        () => withHooksForbidden(
+          "Pibbl hooks cannot be called inside useReaction setup.",
+          slot.setup
+        )
+      )
+    );
+    if (typeof nextCleanup === "function") slot.cleanup = nextCleanup;
+  } catch (error) {
+    recordReactionFailure();
+    failures.push(error);
+  }
+  throwReactionFailures(failures, slot.debugName);
+}
+function runCleanup(cleanup) {
+  recordReactionCleanup();
+  untracked(() => withSignalWriteForbidden(
+    "Cannot write to a signal during useReaction cleanup.",
+    () => withHooksForbidden(
+      "Pibbl hooks cannot be called inside useReaction cleanup.",
+      cleanup
+    )
+  ));
+}
+function disposeReaction(slot) {
+  if (!slot.active) return;
+  slot.active = false;
+  clearPendingReaction(slot);
+  if (slot.consumer !== void 0) {
+    slot.consumer.disposed = true;
+    disposeReactiveConsumer(slot.consumer, releaseReactionEdge);
+    slot.consumer = void 0;
+    recordReactionConsumerReleased();
+  }
+  const cleanup = slot.cleanup;
+  slot.cleanup = void 0;
+  if (cleanup !== void 0) {
+    try {
+      runCleanup(cleanup);
+    } catch (error) {
+      recordReactionFailure();
+      throw error;
+    }
+  }
+}
+function clearPendingReaction(slot) {
+  slot.pending = false;
+  slot.pendingGeneration++;
+  const cancel = slot.cancelPending;
+  slot.cancelPending = void 0;
+  cancel?.();
+}
+function releaseReactionEdge(edge) {
+  if (!edge.sourceLinked) return;
+  unlinkReactiveEdgeFromSource(edge);
+  recordReactionEdgeReleased();
+}
+function snapshotDependencies(dependencies) {
+  return dependencies === void 0 ? void 0 : [...dependencies];
+}
+function dependencySnapshotsEqual(previous, next) {
+  if (previous === void 0 || next === void 0) return previous === next;
+  if (previous.length !== next.length) return false;
+  for (let index = 0; index < previous.length; index++) {
+    if (!Object.is(previous[index], next[index])) return false;
+  }
+  return true;
+}
+function isCurrentSlot(slot) {
+  return slot.active && !slot.componentRefs.teardowns.closed && !slot.pibblInstance.mainTeardowns.closed && GLOBAL_STATE.pibblInstances.get(slot.pibblInstance.canvas) === slot.pibblInstance && slot.pibblInstance.refs.get(slot.componentRefs.id) === slot.componentRefs;
+}
+function throwReactionFailures(failures, debugName) {
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) {
+    const label = debugName === void 0 ? "" : ` "${debugName}"`;
+    throw new AggregateError(
+      failures,
+      `Pibbl reaction${label} setup and cleanup failed.`
+    );
+  }
+}
+export {
+  useReaction
+};
+//# sourceMappingURL=use-reaction.js.map

package/dist/lib/hooks/use-reaction.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/hooks/use-reaction.ts"],
+  "sourcesContent": ["import { GLOBAL_STATE } from '../global-state.js';\nimport { queueReactionCompletion } from '../scheduler/realm-scheduler.js';\nimport {\n  recordReactionCleanup,\n  recordReactionConsumerCreated,\n  recordReactionConsumerReleased,\n  recordReactionEdgeCreated,\n  recordReactionEdgeReleased,\n  recordReactionFailure,\n  recordReactionRun,\n  untracked,\n  withSignalTracking,\n  withSignalWriteForbidden,\n} from '../signals/graph.js';\nimport {\n  beginReactiveCollection,\n  collectReactiveDependency,\n  disposeReactiveConsumer,\n  finishReactiveCollection,\n  linkReactiveEdgeToSource,\n  unlinkReactiveEdgeFromSource,\n  type ReactiveEdge,\n  type SignalDependencyConsumer,\n} from '../signals/edge.js';\nimport type { PibblComponentRefs, PibblInstance } from '../types.js';\nimport {\n  requireHookContext,\n  useHookSlot,\n  withHooksForbidden,\n} from './hook-slot.js';\n\n/**\n * Options controlling when a signal reaction runs and how it is named for diagnostics.\n *\n * @see {@link useReaction}\n */\nexport interface PibblReactionOptions {\n  /** Optional label used in diagnostics. See {@link PibblReactionOptions}. */\n  readonly debugName?: string;\n}\n\ninterface ReactionConsumerState extends SignalDependencyConsumer {\n  readonly kind: 'reaction';\n  readonly ownerComponent: PibblComponentRefs<any>;\n  collecting: boolean;\n  disposed: boolean;\n}\n\ninterface PibblReactionHookSlot {\n  active: boolean;\n  cancelPending: (() => void) | undefined;\n  cleanup: (() => void) | undefined;\n  readonly componentRefs: PibblComponentRefs<any>;\n  consumer: ReactionConsumerState | undefined;\n  readonly pibblInstance: PibblInstance;\n  dependencies: readonly unknown[] | undefined;\n  readonly debugName: string | undefined;\n  mounted: boolean;\n  pending: boolean;\n  pendingGeneration: number;\n  renderRevision: number;\n  setup: () => void | (() => void);\n}\n\n/**\n * Owns one Complete-phase imperative reaction for a mounted hook slot.\n *\n * @param setup - Setup callback; its optional returned cleanup runs when replaced or disposed.\n * @param dependencies - Values controlling when setup is repeated.\n * @param options - Optional diagnostic name for this reaction. See {@link PibblReactionOptions}.\n *\n * @see {@link PibblReactionOptions}\n */\nexport function useReaction(\n  setup: () => void | (() => void),\n  dependencies?: readonly unknown[],\n  options: PibblReactionOptions = {},\n): void {\n  const { componentRefs, pibblInstance } = requireHookContext();\n  const dependencySnapshot = snapshotDependencies(dependencies);\n  const slot = useHookSlot<PibblReactionHookSlot>('reaction', teardowns => {\n    let value!: PibblReactionHookSlot;\n    value = {\n      active: true,\n      cancelPending: undefined,\n      cleanup: undefined,\n      componentRefs,\n      consumer: undefined,\n      pibblInstance,\n      dependencies: undefined,\n      debugName: options.debugName,\n      mounted: false,\n      pending: false,\n      pendingGeneration: 0,\n      renderRevision: 0,\n      setup,\n    };\n    teardowns.add(() => disposeReaction(value));\n    return value;\n  }).value;\n\n  const transaction = GLOBAL_STATE.renderTransaction;\n  if (!transaction) {\n    throw new Error('useReaction requires an active Pibbl render transaction.');\n  }\n  const dependenciesChanged = !slot.mounted || !dependencySnapshotsEqual(\n    slot.dependencies,\n    dependencySnapshot,\n  );\n  const revision = ++slot.renderRevision;\n  transaction.onFinish(success => {\n    if (!success || revision !== slot.renderRevision || !isCurrentSlot(slot)) {\n      return;\n    }\n    slot.setup = setup;\n    slot.dependencies = dependencySnapshot;\n    if (!slot.mounted) {\n      slot.mounted = true;\n      slot.consumer = createReactionConsumer(() => scheduleReaction(slot), slot.componentRefs);\n    }\n    if (dependenciesChanged) {\n      clearPendingReaction(slot);\n      runReaction(slot);\n    }\n  });\n}\n\nfunction createReactionConsumer(\n  invalidate: () => void,\n  ownerComponent: PibblComponentRefs<any>,\n): ReactionConsumerState {\n  const state: ReactionConsumerState = {\n    kind: 'reaction',\n    ownerComponent,\n    dependencyHead: undefined,\n    dependencyTail: undefined,\n    dependencyFreeHead: undefined,\n    dependencyFreeCount: 0,\n    dependencyCount: 0,\n    dependencyHighWater: 0,\n    collectionCursor: undefined,\n    collectionGeneration: 0,\n    collecting: false,\n    disposed: false,\n    addDependency(node): void {\n      if (state.collecting) collectReactiveDependency(state, node);\n    },\n    notify(): void {\n      if (!state.disposed) invalidate();\n    },\n  };\n  recordReactionConsumerCreated();\n  return state;\n}\n\nfunction collectReactionReads<T>(\n  consumer: ReactionConsumerState,\n  callback: () => T,\n): T {\n  beginReactiveCollection(consumer);\n  consumer.collecting = true;\n  let result!: T;\n  let failure: unknown;\n  let failed = false;\n  try {\n    result = withSignalTracking(consumer, callback);\n  } catch (error) {\n    failed = true;\n    failure = error;\n  } finally {\n    consumer.collecting = false;\n    finishReactiveCollection(\n      consumer,\n      edge => {\n        if (!edge.sourceLinked) {\n          const source = edge.source!;\n          linkReactiveEdgeToSource(edge, source.observe?.());\n          recordReactionEdgeCreated();\n        }\n        edge.observedVersion = edge.source!.version;\n        edge.collectionKind = undefined;\n      },\n      releaseReactionEdge,\n    );\n  }\n  if (failed) throw failure;\n  return result;\n}\n\nfunction scheduleReaction(slot: PibblReactionHookSlot): void {\n  if (!slot.active || slot.pending) return;\n  slot.pending = true;\n  const generation = ++slot.pendingGeneration;\n  slot.cancelPending = queueReactionCompletion(() => {\n    if (\n      !slot.active ||\n      !slot.pending ||\n      generation !== slot.pendingGeneration\n    ) {\n      return;\n    }\n    slot.pending = false;\n    slot.cancelPending = undefined;\n    runReaction(slot);\n  });\n}\n\nfunction runReaction(slot: PibblReactionHookSlot): void {\n  if (!slot.active || slot.consumer === undefined) return;\n  const failures: unknown[] = [];\n  const cleanup = slot.cleanup;\n  slot.cleanup = undefined;\n  if (cleanup !== undefined) {\n    try {\n      runCleanup(cleanup);\n    } catch (error) {\n      recordReactionFailure();\n      failures.push(error);\n    }\n  }\n\n  recordReactionRun();\n  try {\n    const nextCleanup = collectReactionReads(\n      slot.consumer,\n      () => withSignalWriteForbidden(\n        'Cannot write to a signal during useReaction setup.',\n        () => withHooksForbidden(\n          'Pibbl hooks cannot be called inside useReaction setup.',\n          slot.setup,\n        ),\n      ),\n    );\n    if (typeof nextCleanup === 'function') slot.cleanup = nextCleanup;\n  } catch (error) {\n    recordReactionFailure();\n    failures.push(error);\n  }\n  throwReactionFailures(failures, slot.debugName);\n}\n\nfunction runCleanup(cleanup: () => void): void {\n  recordReactionCleanup();\n  untracked(() => withSignalWriteForbidden(\n    'Cannot write to a signal during useReaction cleanup.',\n    () => withHooksForbidden(\n      'Pibbl hooks cannot be called inside useReaction cleanup.',\n      cleanup,\n    ),\n  ));\n}\n\nfunction disposeReaction(slot: PibblReactionHookSlot): void {\n  if (!slot.active) return;\n  slot.active = false;\n  clearPendingReaction(slot);\n  if (slot.consumer !== undefined) {\n    slot.consumer.disposed = true;\n    disposeReactiveConsumer(slot.consumer, releaseReactionEdge);\n    slot.consumer = undefined;\n    recordReactionConsumerReleased();\n  }\n  const cleanup = slot.cleanup;\n  slot.cleanup = undefined;\n  if (cleanup !== undefined) {\n    try {\n      runCleanup(cleanup);\n    } catch (error) {\n      recordReactionFailure();\n      throw error;\n    }\n  }\n}\n\nfunction clearPendingReaction(slot: PibblReactionHookSlot): void {\n  slot.pending = false;\n  slot.pendingGeneration++;\n  const cancel = slot.cancelPending;\n  slot.cancelPending = undefined;\n  cancel?.();\n}\n\nfunction releaseReactionEdge(edge: ReactiveEdge): void {\n  if (!edge.sourceLinked) return;\n  unlinkReactiveEdgeFromSource(edge);\n  recordReactionEdgeReleased();\n}\n\nfunction snapshotDependencies(\n  dependencies: readonly unknown[] | undefined,\n): readonly unknown[] | undefined {\n  return dependencies === undefined ? undefined : [...dependencies];\n}\n\nfunction dependencySnapshotsEqual(\n  previous: readonly unknown[] | undefined,\n  next: readonly unknown[] | undefined,\n): boolean {\n  if (previous === undefined || next === undefined) return previous === next;\n  if (previous.length !== next.length) return false;\n  for (let index = 0; index < previous.length; index++) {\n    if (!Object.is(previous[index], next[index])) return false;\n  }\n  return true;\n}\n\nfunction isCurrentSlot(slot: PibblReactionHookSlot): boolean {\n  return slot.active &&\n    !slot.componentRefs.teardowns.closed &&\n    !slot.pibblInstance.mainTeardowns.closed &&\n    GLOBAL_STATE.pibblInstances.get(slot.pibblInstance.canvas) === slot.pibblInstance &&\n    slot.pibblInstance.refs.get(slot.componentRefs.id) === slot.componentRefs;\n}\n\nfunction throwReactionFailures(\n  failures: readonly unknown[],\n  debugName: string | undefined,\n): void {\n  if (failures.length === 1) throw failures[0];\n  if (failures.length > 1) {\n    const label = debugName === undefined ? '' : ` \"${debugName}\"`;\n    throw new AggregateError(\n      failures,\n      `Pibbl reaction${label} setup and cleanup failed.`,\n    );\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/hooks/use-rect-path.d.ts

@@ -0,0 +1,20 @@
+import { PixelGridAlignment } from '../types.js';
+/**
+ * Creates a memoized Path2D for a rectangle. Useful when
+ * defining events efficiently.
+ * @param x - Horizontal rectangle origin.
+ * @param y - Vertical rectangle origin.
+ * @param width - Horizontal extent in logical units.
+ * @param height - Vertical extent in logical units.
+ * @param config - Pixel alignment, stroke width, and uniform or per-corner rounding. See
+ * {@link PixelGridAlignment} .
+ * @returns A memoized Path2D
+ *
+ * @see {@link PixelGridAlignment}
+ */
+export declare function useRectPath(x: number, y: number, width: number, height: number, config?: {
+    alignToPixelGrid?: PixelGridAlignment;
+    lineWidth?: number;
+    cornerRadius?: number;
+    cornerRadii?: readonly (number | null | undefined)[];
+}): Path2D;

package/dist/lib/hooks/use-rect-path.js

@@ -0,0 +1,25 @@
+import { createRectanglePath } from "../geometry/rectangle.js";
+import { resolveNumericCornerRadii } from "../geometry/rounded-corners.js";
+import { adjustRectangleToPixelGrid } from "../util/pixel-grid-adjustments.js";
+import { useValueMemoSlot } from "./use-value-memo-slot.js";
+function useRectPath(x, y, width, height, config) {
+  const radii = resolveNumericCornerRadii(4, config ?? {});
+  const alignToPixelGrid = config?.alignToPixelGrid;
+  if (alignToPixelGrid) {
+    ({ x, y, width, height } = adjustRectangleToPixelGrid(
+      config?.lineWidth ?? 0,
+      x,
+      y,
+      width,
+      height,
+      alignToPixelGrid
+    ));
+  }
+  return useValueMemoSlot("rectPath", () => {
+    return createRectanglePath({ x, y, width, height, cornerRadii: radii });
+  }, [x, y, width, height, ...radii]);
+}
+export {
+  useRectPath
+};
+//# sourceMappingURL=use-rect-path.js.map

package/dist/lib/hooks/use-rect-path.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/hooks/use-rect-path.ts"],
+  "sourcesContent": ["import { PixelGridAlignment } from '../types.js';\nimport { createRectanglePath } from '../geometry/rectangle.js';\nimport { resolveNumericCornerRadii } from '../geometry/rounded-corners.js';\nimport { adjustRectangleToPixelGrid } from '../util/pixel-grid-adjustments.js';\nimport { useValueMemoSlot } from './use-value-memo-slot.js';\n\n/**\n * Creates a memoized Path2D for a rectangle. Useful when\n * defining events efficiently.\n * @param x - Horizontal rectangle origin.\n * @param y - Vertical rectangle origin.\n * @param width - Horizontal extent in logical units.\n * @param height - Vertical extent in logical units.\n * @param config - Pixel alignment, stroke width, and uniform or per-corner rounding. See\n * {@link PixelGridAlignment} .\n * @returns A memoized Path2D\n *\n * @see {@link PixelGridAlignment}\n */\nexport function useRectPath(\n  x: number,\n  y: number,\n  width: number,\n  height: number,\n  config?: {\n    alignToPixelGrid?: PixelGridAlignment;\n    lineWidth?: number;\n    cornerRadius?: number;\n    cornerRadii?: readonly (number | null | undefined)[];\n  },\n): Path2D {\n  const radii = resolveNumericCornerRadii(4, config ?? {});\n  const alignToPixelGrid = config?.alignToPixelGrid;\n\n  if (alignToPixelGrid) {\n    ({ x, y, width, height } = adjustRectangleToPixelGrid(\n      config?.lineWidth ?? 0,\n      x,\n      y,\n      width,\n      height,\n      alignToPixelGrid,\n    ));\n  }\n\n  return useValueMemoSlot('rectPath', () => {\n    return createRectanglePath({ x, y, width, height, cornerRadii: radii });\n  }, [x, y, width, height, ...radii]);\n}\n"],
+  "mappings": "AACA,SAAS,2BAA2B;AACpC,SAAS,iCAAiC;AAC1C,SAAS,kCAAkC;AAC3C,SAAS,wBAAwB;AAe1B,SAAS,YACd,GACA,GACA,OACA,QACA,QAMQ;AACR,QAAM,QAAQ,0BAA0B,GAAG,UAAU,CAAC,CAAC;AACvD,QAAM,mBAAmB,QAAQ;AAEjC,MAAI,kBAAkB;AACpB,KAAC,EAAE,GAAG,GAAG,OAAO,OAAO,IAAI;AAAA,MACzB,QAAQ,aAAa;AAAA,MACrB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,SAAO,iBAAiB,YAAY,MAAM;AACxC,WAAO,oBAAoB,EAAE,GAAG,GAAG,OAAO,QAAQ,aAAa,MAAM,CAAC;AAAA,EACxE,GAAG,CAAC,GAAG,GAAG,OAAO,QAAQ,GAAG,KAAK,CAAC;AACpC;",
+  "names": []
+}

package/dist/lib/hooks/use-ref.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A stable mutable container whose current value does not itself schedule rendering.
+ *
+ * @see {@link useRef}
+ */
+export interface PibblRef<T> {
+    /** Mutable value retained by the ref container. See {@link PibblRef}. */
+    current: T | undefined;
+}
+/**
+ * Hook: Creates a reference object, similar to React's useRef.
+ * @param init The initial reference value
+ * @returns A reference with a `current` property containing the value
+ *
+ * @see {@link PibblRef}
+ */
+export declare function useRef<T>(init?: T): PibblRef<T>;

package/dist/lib/hooks/use-ref.js

@@ -0,0 +1,8 @@
+import { useHookSlot } from "./hook-slot.js";
+function useRef(init) {
+  return useHookSlot("ref", () => ({ current: init })).value;
+}
+export {
+  useRef
+};
+//# sourceMappingURL=use-ref.js.map

package/dist/lib/hooks/use-ref.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/hooks/use-ref.ts"],
+  "sourcesContent": ["import { useHookSlot } from './hook-slot.js';\n\n/**\n * A stable mutable container whose current value does not itself schedule rendering.\n *\n * @see {@link useRef}\n */\nexport interface PibblRef<T> {\n  /** Mutable value retained by the ref container. See {@link PibblRef}. */\n  current: T | undefined;\n}\n\n/**\n * Hook: Creates a reference object, similar to React's useRef.\n * @param init The initial reference value\n * @returns A reference with a `current` property containing the value\n *\n * @see {@link PibblRef}\n */\nexport function useRef<T>(init?: T): PibblRef<T> {\n  return useHookSlot('ref', () => ({ current: init })).value;\n}\n"],
+  "mappings": "AAAA,SAAS,mBAAmB;AAmBrB,SAAS,OAAU,MAAuB;AAC/C,SAAO,YAAY,OAAO,OAAO,EAAE,SAAS,KAAK,EAAE,EAAE;AACvD;",
+  "names": []
+}

package/dist/lib/hooks/use-region.d.ts

@@ -0,0 +1,11 @@
+import type { PathGeometry } from '../geometry/path-geometry.js';
+import { type PibblEventTargetRegistration } from '../events/registrations.js';
+import type { PibblInstance } from '../types.js';
+export declare function createRegion(instance: PibblInstance, component?: import("../types.js").PibblComponentRefs<any>, slot?: number): PibblEventTargetRegistration;
+export declare function updateRegion(instance: PibblInstance, region: PibblEventTargetRegistration, { path, fill, lineInteractionWidth, cursor, }: {
+    path?: Path2D | PathGeometry;
+    fill?: boolean;
+    lineInteractionWidth?: number;
+    cursor?: string;
+}): void;
+export declare function releaseRegion(instance: PibblInstance, region: PibblEventTargetRegistration): void;