@pibbl/core 0.0.1

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

@@ -0,0 +1,103 @@
+import type { SignalCommitBatch } from '../signals/graph.js';
+export type PibblFramePhase = 'idle' | 'begin' | 'advance' | 'commit' | 'plan' | 'render' | 'complete';
+export interface PibblFrameSnapshot {
+    readonly frameId: number;
+    readonly hostTime: number;
+    readonly logicalTime: number;
+}
+export type PibblAdvanceLane = 'animation' | 'physics';
+export type PibblAdvanceParticipant = (snapshot: PibblFrameSnapshot, batch: SignalCommitBatch) => void;
+export type PibblBeginCommand = (snapshot: PibblFrameSnapshot, batch: SignalCommitBatch, sequence: number) => void;
+export interface PibblBeginCommandHandle {
+    readonly sequence: number;
+    cancel(): void;
+}
+export type PibblFrameCompletion = (snapshot: PibblFrameSnapshot) => void;
+export interface PibblCommitOutcome {
+    readonly applied: boolean;
+}
+export type PibblFrameCommitAcknowledgement = (snapshot: PibblFrameSnapshot, outcome: PibblCommitOutcome) => void;
+export type PibblSchedulerTraceRecord = {
+    readonly kind: 'scheduler-phase';
+    readonly collectedErrors: number;
+    /** Known from Plan onward; true includes empty/equality-suppressed batches. */
+    readonly commitApplied?: boolean;
+    /** Only present on idle: entries collected for subsequent error delivery. */
+    readonly errorCount?: number;
+    readonly phase: PibblFramePhase;
+    readonly frameId: number;
+    readonly hostTime: number;
+    readonly logicalTime: number;
+} | {
+    readonly kind: 'animation-command';
+    readonly frameId: number;
+    readonly logicalTime: number;
+    readonly sequence: number;
+    readonly command: string;
+    readonly debugName: string | undefined;
+} | {
+    readonly kind: 'animation-sample';
+    readonly frameId: number;
+    readonly logicalTime: number;
+    readonly registrationOrder: number;
+    readonly debugName: string | undefined;
+    readonly localTime: number;
+    readonly direction: 'forward' | 'reverse';
+} | {
+    readonly kind: 'animation-write';
+    readonly frameId: number;
+    readonly logicalTime: number;
+    readonly debugName: string | undefined;
+    readonly target: string;
+    readonly outcome: 'staged' | 'equality-suppressed';
+} | {
+    readonly kind: 'animation-milestone';
+    readonly frameId: number;
+    readonly logicalTime: number;
+    readonly debugName: string | undefined;
+    readonly event: string;
+    readonly programPath: readonly number[];
+    readonly iteration: number;
+} | {
+    readonly kind: 'animation-stepper';
+    readonly frameId: number;
+    readonly logicalTime: number;
+    readonly debugName: string | undefined;
+    readonly programPath: readonly number[];
+    readonly repeatIterations: readonly number[];
+    readonly appliedSteps: number;
+    readonly retainedRemainderMilliseconds: number;
+    readonly clampedElapsedMilliseconds: number;
+    readonly discardedElapsedMilliseconds: number;
+} | {
+    readonly kind: 'animation-error';
+    readonly frameId: number;
+    readonly logicalTime: number;
+    readonly debugName: string | undefined;
+    readonly error: unknown;
+};
+export type PibblSchedulerTraceCollector = (record: PibblSchedulerTraceRecord) => void;
+export interface SchedulerDriver {
+    requestFrame(callback: FrameRequestCallback): number;
+    cancelFrame(frameId: number): void;
+}
+export interface RealmSchedulerSnapshot {
+    readonly phase: PibblFramePhase;
+    readonly pendingHostFrames: number;
+    readonly registeredRoots: number;
+    readonly advanceParticipants: number;
+    readonly completionCallbacks: number;
+    readonly createdRootRegistrations: number;
+    readonly releasedRootRegistrations: number;
+    readonly createdBeginCommands: number;
+    readonly releasedBeginCommands: number;
+    readonly createdCompletionCallbacks: number;
+    readonly releasedCompletionCallbacks: number;
+    readonly dirtyInstances: number;
+    readonly dirtyRoots: number;
+    readonly registeredAdvanceParticipants: number;
+    readonly queuedFrameCompletions: number;
+    readonly queuedReactionCompletions: number;
+    readonly queuedBeginCommands: number;
+    readonly currentFrame: PibblFrameSnapshot | undefined;
+}

package/dist/lib/signals/edge.d.ts

@@ -0,0 +1,44 @@
+import type { SignalNode } from './graph.js';
+export interface ReactiveEdge {
+    source: SignalNode<unknown> | undefined;
+    consumer: SignalDependencyConsumer;
+    sourcePrevious: ReactiveEdge | undefined;
+    sourceNext: ReactiveEdge | undefined;
+    consumerPrevious: ReactiveEdge | undefined;
+    consumerNext: ReactiveEdge | undefined;
+    freeNext: ReactiveEdge | undefined;
+    collectionGeneration: number;
+    observedVersion: number;
+    everPublished: boolean;
+    sourceLinked: boolean;
+    collectionKind: 'new' | 'reused' | undefined;
+    releaseObservation: (() => void) | undefined;
+}
+export interface ReactiveNotificationCursor {
+    next: ReactiveEdge | undefined;
+    previous: ReactiveNotificationCursor | undefined;
+}
+export interface SignalDependencyConsumer {
+    dependencyHead: ReactiveEdge | undefined;
+    dependencyTail: ReactiveEdge | undefined;
+    dependencyFreeHead: ReactiveEdge | undefined;
+    dependencyFreeCount: number;
+    dependencyCount: number;
+    dependencyHighWater: number;
+    collectionCursor: ReactiveEdge | undefined;
+    collectionGeneration: number;
+    addDependency(node: SignalNode<unknown>): void;
+    notify(node: SignalNode<unknown>): void;
+    propagateInvalidation?: boolean;
+    renderInvalidation?: boolean;
+}
+export declare function beginReactiveCollection(consumer: SignalDependencyConsumer): number;
+export declare function collectReactiveDependency(consumer: SignalDependencyConsumer, source: SignalNode<unknown>): ReactiveEdge;
+export declare function finishReactiveCollection(consumer: SignalDependencyConsumer, publish: (edge: ReactiveEdge) => void, release: (edge: ReactiveEdge) => void): void;
+export declare function rollbackReactiveCollection(consumer: SignalDependencyConsumer): void;
+export declare function linkReactiveEdgeToSource(edge: ReactiveEdge, releaseObservation?: () => void): void;
+export declare function unlinkReactiveEdgeFromSource(edge: ReactiveEdge): void;
+export declare function unlinkReactiveEdgeFromConsumer(edge: ReactiveEdge): void;
+export declare function disposeReactiveConsumer(consumer: SignalDependencyConsumer, release: (edge: ReactiveEdge) => void): void;
+export declare function notifyReactiveEdges(source: SignalNode<unknown>, accepts?: (consumer: SignalDependencyConsumer) => boolean): unknown[];
+export declare function createDetachedReactiveEdge(consumer: SignalDependencyConsumer, source: SignalNode<unknown>): ReactiveEdge;

package/dist/lib/signals/edge.js

@@ -0,0 +1,245 @@
+function beginReactiveCollection(consumer) {
+  consumer.collectionGeneration++;
+  consumer.collectionCursor = consumer.dependencyHead;
+  return consumer.collectionGeneration;
+}
+function collectReactiveDependency(consumer, source) {
+  const generation = consumer.collectionGeneration;
+  let edge = consumer.collectionCursor;
+  if (edge?.source === source && edge.collectionGeneration !== generation) {
+    edge.collectionGeneration = generation;
+    edge.collectionKind = "reused";
+    consumer.collectionCursor = edge.consumerNext;
+    return edge;
+  }
+  for (edge = consumer.dependencyHead; edge !== void 0; edge = edge.consumerNext) {
+    if (edge.source !== source) continue;
+    if (edge.collectionGeneration !== generation) {
+      edge.collectionGeneration = generation;
+      edge.collectionKind = "reused";
+      consumer.collectionCursor = edge.consumerNext;
+    }
+    return edge;
+  }
+  edge = takeFreeReactiveEdge(consumer) ?? createReactiveEdge(consumer);
+  edge.source = source;
+  edge.collectionGeneration = generation;
+  edge.collectionKind = edge.everPublished ? "reused" : "new";
+  edge.observedVersion = source.version;
+  linkReactiveEdgeToConsumer(edge);
+  consumer.collectionCursor = edge.consumerNext;
+  return edge;
+}
+function finishReactiveCollection(consumer, publish, release) {
+  let edge = consumer.dependencyHead;
+  while (edge !== void 0) {
+    const next = edge.consumerNext;
+    if (edge.collectionGeneration === consumer.collectionGeneration) {
+      publish(edge);
+    } else {
+      release(edge);
+      unlinkReactiveEdgeFromConsumer(edge);
+      poolReactiveEdge(consumer, edge);
+    }
+    edge = next;
+  }
+  consumer.dependencyHighWater = Math.max(
+    consumer.dependencyHighWater,
+    consumer.dependencyCount
+  );
+  trimReactiveEdgePool(consumer);
+  consumer.collectionCursor = void 0;
+}
+function rollbackReactiveCollection(consumer) {
+  let edge = consumer.dependencyHead;
+  while (edge !== void 0) {
+    const next = edge.consumerNext;
+    if (edge.collectionGeneration === consumer.collectionGeneration && !edge.sourceLinked) {
+      unlinkReactiveEdgeFromConsumer(edge);
+      poolReactiveEdge(consumer, edge);
+    }
+    edge = next;
+  }
+  trimReactiveEdgePool(consumer);
+  consumer.collectionCursor = void 0;
+}
+function linkReactiveEdgeToSource(edge, releaseObservation) {
+  if (edge.sourceLinked) return;
+  const source = edge.source;
+  if (source === void 0) {
+    throw new Error("Cannot link a reactive edge without a source.");
+  }
+  edge.sourcePrevious = source.observerTail;
+  edge.sourceNext = void 0;
+  if (source.observerTail === void 0) {
+    source.observerHead = edge;
+  } else {
+    source.observerTail.sourceNext = edge;
+  }
+  source.observerTail = edge;
+  source.observerCount++;
+  edge.sourceLinked = true;
+  edge.releaseObservation = releaseObservation;
+}
+function unlinkReactiveEdgeFromSource(edge) {
+  if (!edge.sourceLinked) return;
+  const source = edge.source;
+  for (let cursor = source.activeObserverCursor; cursor !== void 0; cursor = cursor.previous) {
+    if (cursor.next === edge) cursor.next = edge.sourceNext;
+  }
+  if (edge.sourcePrevious === void 0) {
+    source.observerHead = edge.sourceNext;
+  } else {
+    edge.sourcePrevious.sourceNext = edge.sourceNext;
+  }
+  if (edge.sourceNext === void 0) {
+    source.observerTail = edge.sourcePrevious;
+  } else {
+    edge.sourceNext.sourcePrevious = edge.sourcePrevious;
+  }
+  source.observerCount--;
+  edge.sourceLinked = false;
+  edge.sourcePrevious = void 0;
+  edge.sourceNext = void 0;
+  const releaseObservation = edge.releaseObservation;
+  edge.releaseObservation = void 0;
+  releaseObservation?.();
+}
+function unlinkReactiveEdgeFromConsumer(edge) {
+  const consumer = edge.consumer;
+  if (edge.consumerPrevious === void 0) {
+    if (consumer.dependencyHead !== edge) return;
+    consumer.dependencyHead = edge.consumerNext;
+  } else {
+    edge.consumerPrevious.consumerNext = edge.consumerNext;
+  }
+  if (edge.consumerNext === void 0) {
+    consumer.dependencyTail = edge.consumerPrevious;
+  } else {
+    edge.consumerNext.consumerPrevious = edge.consumerPrevious;
+  }
+  consumer.dependencyCount--;
+  edge.consumerPrevious = void 0;
+  edge.consumerNext = void 0;
+}
+function disposeReactiveConsumer(consumer, release) {
+  let edge = consumer.dependencyHead;
+  while (edge !== void 0) {
+    const next = edge.consumerNext;
+    release(edge);
+    unlinkReactiveEdgeFromConsumer(edge);
+    edge.source = void 0;
+    edge.freeNext = void 0;
+    edge = next;
+  }
+  consumer.dependencyFreeHead = void 0;
+  consumer.dependencyFreeCount = 0;
+  consumer.collectionCursor = void 0;
+}
+function notifyReactiveEdges(source, accepts = () => true) {
+  const failures = [];
+  const cursor = {
+    next: source.observerHead,
+    previous: source.activeObserverCursor
+  };
+  source.activeObserverCursor = cursor;
+  try {
+    while (cursor.next !== void 0) {
+      const edge = cursor.next;
+      cursor.next = edge.sourceNext;
+      if (!edge.sourceLinked || edge.source !== source) continue;
+      if (!accepts(edge.consumer)) continue;
+      try {
+        edge.consumer.notify(source);
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+  } finally {
+    source.activeObserverCursor = cursor.previous;
+  }
+  return failures;
+}
+function createDetachedReactiveEdge(consumer, source) {
+  const edge = createReactiveEdge(consumer);
+  edge.source = source;
+  edge.collectionGeneration = consumer.collectionGeneration;
+  edge.observedVersion = source.version;
+  linkReactiveEdgeToConsumer(edge);
+  return edge;
+}
+function createReactiveEdge(consumer) {
+  return {
+    source: void 0,
+    consumer,
+    sourcePrevious: void 0,
+    sourceNext: void 0,
+    consumerPrevious: void 0,
+    consumerNext: void 0,
+    freeNext: void 0,
+    collectionGeneration: 0,
+    observedVersion: -1,
+    everPublished: false,
+    sourceLinked: false,
+    collectionKind: void 0,
+    releaseObservation: void 0
+  };
+}
+function linkReactiveEdgeToConsumer(edge) {
+  const consumer = edge.consumer;
+  edge.consumerPrevious = consumer.dependencyTail;
+  edge.consumerNext = void 0;
+  if (consumer.dependencyTail === void 0) {
+    consumer.dependencyHead = edge;
+  } else {
+    consumer.dependencyTail.consumerNext = edge;
+  }
+  consumer.dependencyTail = edge;
+  consumer.dependencyCount++;
+}
+function takeFreeReactiveEdge(consumer) {
+  const edge = consumer.dependencyFreeHead;
+  if (edge === void 0) return void 0;
+  consumer.dependencyFreeHead = edge.freeNext;
+  consumer.dependencyFreeCount--;
+  edge.freeNext = void 0;
+  return edge;
+}
+function poolReactiveEdge(consumer, edge) {
+  edge.source = void 0;
+  edge.collectionKind = void 0;
+  edge.observedVersion = Math.max(edge.observedVersion, 0);
+  edge.freeNext = consumer.dependencyFreeHead;
+  consumer.dependencyFreeHead = edge;
+  consumer.dependencyFreeCount++;
+}
+function trimReactiveEdgePool(consumer) {
+  if (consumer.dependencyFreeCount <= consumer.dependencyHighWater) return;
+  let retained = 0;
+  let edge = consumer.dependencyFreeHead;
+  let previous;
+  while (edge !== void 0) {
+    retained++;
+    if (retained > consumer.dependencyHighWater) {
+      if (previous === void 0) consumer.dependencyFreeHead = void 0;
+      else previous.freeNext = void 0;
+      consumer.dependencyFreeCount = consumer.dependencyHighWater;
+      return;
+    }
+    previous = edge;
+    edge = edge.freeNext;
+  }
+}
+export {
+  beginReactiveCollection,
+  collectReactiveDependency,
+  createDetachedReactiveEdge,
+  disposeReactiveConsumer,
+  finishReactiveCollection,
+  linkReactiveEdgeToSource,
+  notifyReactiveEdges,
+  rollbackReactiveCollection,
+  unlinkReactiveEdgeFromConsumer,
+  unlinkReactiveEdgeFromSource
+};
+//# sourceMappingURL=edge.js.map

package/dist/lib/signals/edge.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/signals/edge.ts"],
+  "sourcesContent": ["import type { SignalNode } from './graph.js';\n\nexport interface ReactiveEdge {\n  source: SignalNode<unknown> | undefined;\n  consumer: SignalDependencyConsumer;\n  sourcePrevious: ReactiveEdge | undefined;\n  sourceNext: ReactiveEdge | undefined;\n  consumerPrevious: ReactiveEdge | undefined;\n  consumerNext: ReactiveEdge | undefined;\n  freeNext: ReactiveEdge | undefined;\n  collectionGeneration: number;\n  observedVersion: number;\n  everPublished: boolean;\n  sourceLinked: boolean;\n  collectionKind: 'new' | 'reused' | undefined;\n  releaseObservation: (() => void) | undefined;\n}\n\nexport interface ReactiveNotificationCursor {\n  next: ReactiveEdge | undefined;\n  previous: ReactiveNotificationCursor | undefined;\n}\n\nexport interface SignalDependencyConsumer {\n  dependencyHead: ReactiveEdge | undefined;\n  dependencyTail: ReactiveEdge | undefined;\n  dependencyFreeHead: ReactiveEdge | undefined;\n  dependencyFreeCount: number;\n  dependencyCount: number;\n  dependencyHighWater: number;\n  collectionCursor: ReactiveEdge | undefined;\n  collectionGeneration: number;\n  addDependency(node: SignalNode<unknown>): void;\n  notify(node: SignalNode<unknown>): void;\n  propagateInvalidation?: boolean;\n  renderInvalidation?: boolean;\n}\n\nexport function beginReactiveCollection(\n  consumer: SignalDependencyConsumer,\n): number {\n  consumer.collectionGeneration++;\n  consumer.collectionCursor = consumer.dependencyHead;\n  return consumer.collectionGeneration;\n}\n\nexport function collectReactiveDependency(\n  consumer: SignalDependencyConsumer,\n  source: SignalNode<unknown>,\n): ReactiveEdge {\n  const generation = consumer.collectionGeneration;\n  let edge = consumer.collectionCursor;\n  if (\n    edge?.source === source &&\n    edge.collectionGeneration !== generation\n  ) {\n    edge.collectionGeneration = generation;\n    edge.collectionKind = 'reused';\n    consumer.collectionCursor = edge.consumerNext;\n    return edge;\n  }\n\n  for (edge = consumer.dependencyHead; edge !== undefined; edge = edge.consumerNext) {\n    if (edge.source !== source) continue;\n    if (edge.collectionGeneration !== generation) {\n      edge.collectionGeneration = generation;\n      edge.collectionKind = 'reused';\n      consumer.collectionCursor = edge.consumerNext;\n    }\n    return edge;\n  }\n\n  edge = takeFreeReactiveEdge(consumer) ?? createReactiveEdge(consumer);\n  edge.source = source;\n  edge.collectionGeneration = generation;\n  edge.collectionKind = edge.everPublished ? 'reused' : 'new';\n  edge.observedVersion = source.version;\n  linkReactiveEdgeToConsumer(edge);\n  consumer.collectionCursor = edge.consumerNext;\n  return edge;\n}\n\nexport function finishReactiveCollection(\n  consumer: SignalDependencyConsumer,\n  publish: (edge: ReactiveEdge) => void,\n  release: (edge: ReactiveEdge) => void,\n): void {\n  let edge = consumer.dependencyHead;\n  while (edge !== undefined) {\n    const next = edge.consumerNext;\n    if (edge.collectionGeneration === consumer.collectionGeneration) {\n      publish(edge);\n    } else {\n      release(edge);\n      unlinkReactiveEdgeFromConsumer(edge);\n      poolReactiveEdge(consumer, edge);\n    }\n    edge = next;\n  }\n  consumer.dependencyHighWater = Math.max(\n    consumer.dependencyHighWater,\n    consumer.dependencyCount,\n  );\n  trimReactiveEdgePool(consumer);\n  consumer.collectionCursor = undefined;\n}\n\nexport function rollbackReactiveCollection(\n  consumer: SignalDependencyConsumer,\n): void {\n  let edge = consumer.dependencyHead;\n  while (edge !== undefined) {\n    const next = edge.consumerNext;\n    if (\n      edge.collectionGeneration === consumer.collectionGeneration &&\n      !edge.sourceLinked\n    ) {\n      unlinkReactiveEdgeFromConsumer(edge);\n      poolReactiveEdge(consumer, edge);\n    }\n    edge = next;\n  }\n  trimReactiveEdgePool(consumer);\n  consumer.collectionCursor = undefined;\n}\n\nexport function linkReactiveEdgeToSource(\n  edge: ReactiveEdge,\n  releaseObservation?: () => void,\n): void {\n  if (edge.sourceLinked) return;\n  const source = edge.source;\n  if (source === undefined) {\n    throw new Error('Cannot link a reactive edge without a source.');\n  }\n  edge.sourcePrevious = source.observerTail;\n  edge.sourceNext = undefined;\n  if (source.observerTail === undefined) {\n    source.observerHead = edge;\n  } else {\n    source.observerTail.sourceNext = edge;\n  }\n  source.observerTail = edge;\n  source.observerCount++;\n  edge.sourceLinked = true;\n  edge.releaseObservation = releaseObservation;\n}\n\nexport function unlinkReactiveEdgeFromSource(edge: ReactiveEdge): void {\n  if (!edge.sourceLinked) return;\n  const source = edge.source!;\n  for (\n    let cursor = source.activeObserverCursor;\n    cursor !== undefined;\n    cursor = cursor.previous\n  ) {\n    if (cursor.next === edge) cursor.next = edge.sourceNext;\n  }\n  if (edge.sourcePrevious === undefined) {\n    source.observerHead = edge.sourceNext;\n  } else {\n    edge.sourcePrevious.sourceNext = edge.sourceNext;\n  }\n  if (edge.sourceNext === undefined) {\n    source.observerTail = edge.sourcePrevious;\n  } else {\n    edge.sourceNext.sourcePrevious = edge.sourcePrevious;\n  }\n  source.observerCount--;\n  edge.sourceLinked = false;\n  edge.sourcePrevious = undefined;\n  edge.sourceNext = undefined;\n  const releaseObservation = edge.releaseObservation;\n  edge.releaseObservation = undefined;\n  releaseObservation?.();\n}\n\nexport function unlinkReactiveEdgeFromConsumer(edge: ReactiveEdge): void {\n  const consumer = edge.consumer;\n  if (edge.consumerPrevious === undefined) {\n    if (consumer.dependencyHead !== edge) return;\n    consumer.dependencyHead = edge.consumerNext;\n  } else {\n    edge.consumerPrevious.consumerNext = edge.consumerNext;\n  }\n  if (edge.consumerNext === undefined) {\n    consumer.dependencyTail = edge.consumerPrevious;\n  } else {\n    edge.consumerNext.consumerPrevious = edge.consumerPrevious;\n  }\n  consumer.dependencyCount--;\n  edge.consumerPrevious = undefined;\n  edge.consumerNext = undefined;\n}\n\nexport function disposeReactiveConsumer(\n  consumer: SignalDependencyConsumer,\n  release: (edge: ReactiveEdge) => void,\n): void {\n  let edge = consumer.dependencyHead;\n  while (edge !== undefined) {\n    const next = edge.consumerNext;\n    release(edge);\n    unlinkReactiveEdgeFromConsumer(edge);\n    edge.source = undefined;\n    edge.freeNext = undefined;\n    edge = next;\n  }\n  consumer.dependencyFreeHead = undefined;\n  consumer.dependencyFreeCount = 0;\n  consumer.collectionCursor = undefined;\n}\n\nexport function notifyReactiveEdges(\n  source: SignalNode<unknown>,\n  accepts: (consumer: SignalDependencyConsumer) => boolean = () => true,\n): unknown[] {\n  const failures: unknown[] = [];\n  const cursor: ReactiveNotificationCursor = {\n    next: source.observerHead,\n    previous: source.activeObserverCursor,\n  };\n  source.activeObserverCursor = cursor;\n  try {\n    while (cursor.next !== undefined) {\n      const edge = cursor.next;\n      cursor.next = edge.sourceNext;\n      if (!edge.sourceLinked || edge.source !== source) continue;\n      if (!accepts(edge.consumer)) continue;\n      try {\n        edge.consumer.notify(source);\n      } catch (error) {\n        failures.push(error);\n      }\n    }\n  } finally {\n    source.activeObserverCursor = cursor.previous;\n  }\n  return failures;\n}\n\nexport function createDetachedReactiveEdge(\n  consumer: SignalDependencyConsumer,\n  source: SignalNode<unknown>,\n): ReactiveEdge {\n  const edge = createReactiveEdge(consumer);\n  edge.source = source;\n  edge.collectionGeneration = consumer.collectionGeneration;\n  edge.observedVersion = source.version;\n  linkReactiveEdgeToConsumer(edge);\n  return edge;\n}\n\nfunction createReactiveEdge(\n  consumer: SignalDependencyConsumer,\n): ReactiveEdge {\n  return {\n    source: undefined,\n    consumer,\n    sourcePrevious: undefined,\n    sourceNext: undefined,\n    consumerPrevious: undefined,\n    consumerNext: undefined,\n    freeNext: undefined,\n    collectionGeneration: 0,\n    observedVersion: -1,\n    everPublished: false,\n    sourceLinked: false,\n    collectionKind: undefined,\n    releaseObservation: undefined,\n  };\n}\n\nfunction linkReactiveEdgeToConsumer(edge: ReactiveEdge): void {\n  const consumer = edge.consumer;\n  edge.consumerPrevious = consumer.dependencyTail;\n  edge.consumerNext = undefined;\n  if (consumer.dependencyTail === undefined) {\n    consumer.dependencyHead = edge;\n  } else {\n    consumer.dependencyTail.consumerNext = edge;\n  }\n  consumer.dependencyTail = edge;\n  consumer.dependencyCount++;\n}\n\nfunction takeFreeReactiveEdge(\n  consumer: SignalDependencyConsumer,\n): ReactiveEdge | undefined {\n  const edge = consumer.dependencyFreeHead;\n  if (edge === undefined) return undefined;\n  consumer.dependencyFreeHead = edge.freeNext;\n  consumer.dependencyFreeCount--;\n  edge.freeNext = undefined;\n  return edge;\n}\n\nfunction poolReactiveEdge(\n  consumer: SignalDependencyConsumer,\n  edge: ReactiveEdge,\n): void {\n  edge.source = undefined;\n  edge.collectionKind = undefined;\n  edge.observedVersion = Math.max(edge.observedVersion, 0);\n  edge.freeNext = consumer.dependencyFreeHead;\n  consumer.dependencyFreeHead = edge;\n  consumer.dependencyFreeCount++;\n}\n\nfunction trimReactiveEdgePool(consumer: SignalDependencyConsumer): void {\n  if (consumer.dependencyFreeCount <= consumer.dependencyHighWater) return;\n  let retained = 0;\n  let edge = consumer.dependencyFreeHead;\n  let previous: ReactiveEdge | undefined;\n  while (edge !== undefined) {\n    retained++;\n    if (retained > consumer.dependencyHighWater) {\n      if (previous === undefined) consumer.dependencyFreeHead = undefined;\n      else previous.freeNext = undefined;\n      consumer.dependencyFreeCount = consumer.dependencyHighWater;\n      return;\n    }\n    previous = edge;\n    edge = edge.freeNext;\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/signals/graph.d.ts

@@ -0,0 +1,220 @@
+import type { Signal, SignalEquals, SignalOptions, WritableSignal } from './types.js';
+import type { PibblRenderTransaction } from '../types.js';
+import { type ReactiveEdge, type ReactiveNotificationCursor } from './edge.js';
+/** @internal One isolated formula generation owned by a render transaction. */
+export interface ComputedFormulaCandidate<T> {
+    readonly signal: Signal<T>;
+    readonly readers: Set<SignalDependencyCollector>;
+    changed: boolean;
+    evaluated: boolean;
+    value: T | undefined;
+}
+export interface SignalNode<T> {
+    value: T;
+    equals: SignalEquals<T>;
+    debugName: string | undefined;
+    version: number;
+    observerHead: ReactiveEdge | undefined;
+    observerTail: ReactiveEdge | undefined;
+    observerCount: number;
+    activeObserverCursor: ReactiveNotificationCursor | undefined;
+    observe?(): () => void;
+    validate?(): void;
+}
+export interface SignalDependencyCollector {
+    addDependency(node: SignalNode<unknown>): void;
+}
+export type SignalWriteOperation = 'direct' | 'staged';
+export type SignalWritePolicy = (node: SignalNode<unknown>, operation: SignalWriteOperation) => void;
+/** @internal Authorization seam owned by the animation writer-lease registry. */
+export interface SignalWriterLeasePolicy {
+    assertDirectWriteAllowed(node: SignalNode<unknown>): void;
+    captureStagedWrite(node: SignalNode<unknown>, writer: object): unknown;
+    assertStagedWriteAllowed(node: SignalNode<unknown>, writer: object, authorization: unknown): void;
+}
+export interface SignalGraphSnapshot {
+    readonly rendererConsumers: number;
+    readonly rendererEdges: number;
+    readonly computedSourceEdges: number;
+    readonly pendingComputedValidations: number;
+    readonly createdRendererConsumers: number;
+    readonly releasedRendererConsumers: number;
+    readonly createdRendererEdges: number;
+    readonly releasedRendererEdges: number;
+    readonly signalCommitNotifications: number;
+    readonly planComputedValidations: number;
+    readonly createdComputedSourceEdges: number;
+    readonly releasedComputedSourceEdges: number;
+    readonly lazyRendererConsumers: number;
+    readonly reusedRendererEdges: number;
+    readonly plainInputResolutions: number;
+    readonly signalInputResolutions: number;
+    readonly shallowInputCopies: number;
+    readonly receiverInputProvisions: number;
+    readonly adoptedReceiverInputProvisions: number;
+    readonly rolledBackReceiverInputProvisions: number;
+    readonly batchedObserverInvalidations: number;
+    readonly reactionConsumers: number;
+    readonly reactionEdges: number;
+    readonly reactionRuns: number;
+    readonly reactionCleanups: number;
+    readonly reactionFailures: number;
+}
+/** @internal Deterministic ownership and structural evidence for tests. */
+export declare function signalGraphSnapshot(): SignalGraphSnapshot;
+/** @internal Records one component consumer materialized by its first read. */
+export declare function recordLazyRendererConsumerCreated(): void;
+/** @internal Records one render edge reused by recollection or restoration. */
+export declare function recordRendererEdgeReused(restored?: boolean): void;
+/** @internal Records one declared plain input that took the identity path. */
+export declare function recordPlainInputResolution(): void;
+/** @internal Records one declared signal-valued input read. */
+export declare function recordSignalInputResolution(): void;
+/** @internal Records one copy-on-signal props or style object. */
+export declare function recordShallowInputCopy(): void;
+/** @internal Records one pre-evaluation receiver input provision. */
+export declare function recordReceiverInputProvisionCreated(): void;
+/** @internal Records one provision adopted by its receiver generation. */
+export declare function recordReceiverInputProvisionAdopted(): void;
+/** @internal Records one provision discarded without publication. */
+export declare function recordReceiverInputProvisionRolledBack(): void;
+/** @internal Adds one already-read source to the active dependency collector. */
+export declare function trackSignalDependency(node: SignalNode<unknown>): void;
+/** @internal Records one observer invalidation deduplicated by a public batch. */
+export declare function recordBatchedObserverInvalidation(): void;
+/** @internal Records one live component-owned reaction consumer. */
+export declare function recordReactionConsumerCreated(): void;
+/** @internal Records final release of one reaction consumer. */
+export declare function recordReactionConsumerReleased(): void;
+/** @internal Records one live reaction source edge. */
+export declare function recordReactionEdgeCreated(): void;
+/** @internal Records release of one reaction source edge. */
+export declare function recordReactionEdgeReleased(): void;
+/** @internal Records one reaction setup attempt. */
+export declare function recordReactionRun(): void;
+/** @internal Records one exact cleanup generation execution. */
+export declare function recordReactionCleanup(): void;
+/** @internal Records one setup or cleanup failure. */
+export declare function recordReactionFailure(): void;
+/** @internal Records one live renderer consumer for test diagnostics. */
+export declare function recordRendererConsumerCreated(): void;
+/** @internal Records release of one renderer consumer for test diagnostics. */
+export declare function recordRendererConsumerReleased(): void;
+/** @internal Records one live renderer dependency edge for test diagnostics. */
+export declare function recordRendererEdgeCreated(): void;
+/** @internal Records release of one renderer dependency edge for tests. */
+export declare function recordRendererEdgeReleased(): void;
+/**
+ * Runs a synchronous callback while coalescing signal notifications until the outer batch
+ * completes.
+ *
+ * @param callback - Synchronous work whose signal notifications are grouped.
+ * @returns The callback's return value.
+ *
+ * @see {@link signal}
+ * @see {@link computed}
+ * @see {@link WritableSignal}
+ */
+export declare function batch<T>(callback: () => T): T;
+/**
+ * Creates a synchronous writable signal with configurable equality and an optional diagnostic
+ * name.
+ *
+ * @param initialValue - Value stored before the first write.
+ * @param options - Equality comparison and optional diagnostic name. See {@link SignalOptions}.
+ * @returns A writable signal holding the initial value. See {@link WritableSignal}.
+ *
+ * @see {@link SignalOptions}
+ * @see {@link WritableSignal}
+ */
+export declare function signal<T>(initialValue: T, options?: SignalOptions<T>): WritableSignal<T>;
+/**
+ * @internal Presents a provisional value to reads and computed dependencies
+ * during one render without publishing an ordinary signal notification.
+ * This is reserved for a not-yet-successfully-mounted owner whose render
+ * transaction owns acceptance or restoration of every overlapping preview.
+ */
+export declare function provisionSignalValueForRender<T>(value: WritableSignal<T>, nextValue: T, transaction: PibblRenderTransaction): void;
+/**
+ * Creates a lazy, cached readonly signal whose dependencies are tracked during evaluation.
+ *
+ * @param compute - Synchronous calculation whose signal reads become dependencies.
+ * @param options - Equality comparison and optional diagnostic name. See {@link SignalOptions}.
+ * @returns A readonly, lazy, cached signal that recomputes when its dependencies change. See
+ * {@link Signal} .
+ *
+ * @see {@link SignalOptions}
+ * @see {@link Signal}
+ */
+export declare function computed<T>(compute: () => T, options?: SignalOptions<T>): Signal<T>;
+/** @internal Creates a nominal alias that retains one computed graph identity. */
+export declare function createComputedSignalAlias<T>(target: Signal<T>, read: () => T): Signal<T>;
+/** @internal Creates one unobserved formula generation for transactional render. */
+export declare function createComputedFormulaCandidate<T>(target: Signal<T>, compute: () => T): ComputedFormulaCandidate<T>;
+/** @internal Reads a provisional formula while attributing the stable node. */
+export declare function readComputedFormulaCandidate<T>(target: Signal<T>, candidate: ComputedFormulaCandidate<T>): T;
+/** @internal Publishes an evaluated formula generation after render success. */
+export declare function adoptComputedFormulaCandidate<T>(target: Signal<T>, candidate: ComputedFormulaCandidate<T>, compute: () => T): void;
+/** @internal Refreshes a committed formula and optionally invalidates its cache. */
+export declare function replaceComputedFormula<T>(target: Signal<T>, compute: () => T, invalidate: boolean): void;
+/** @internal Called during the scheduler Plan phase. */
+export declare function flushPendingComputedValidations(): void;
+/** @internal Whether the realm scheduler has graph Plan work to service. */
+export declare function hasPendingComputedValidations(): boolean;
+/** @internal Connects graph liveness to its host-agnostic scheduler owner. */
+export declare function setSignalGraphPlanWorkNotifier(notifier: () => void): void;
+/**
+ * Runs a callback without recording its signal reads as dependencies of the current consumer.
+ *
+ * @param callback - Synchronous work whose reads should not register dependencies.
+ * @returns The callback's return value.
+ *
+ * @see {@link Signal}
+ * @see {@link computed}
+ */
+export declare function untracked<T>(callback: () => T): T;
+/**
+ * Checks the nominal Pibbl signal identity rather than accepting objects that merely have a get
+ * method.
+ *
+ * @param value - Value to check for Pibbl's nominal signal brand.
+ * @returns True if the value is a Pibbl signal, narrowing its type accordingly. See {@link Signal}.
+ *
+ * @see {@link Signal}
+ */
+export declare function isSignal(value: unknown): value is Signal<unknown>;
+export declare function getSignalNode<T>(value: Signal<T>): SignalNode<T>;
+/** @internal Couples a non-signal resource publication to a staged writer. */
+export interface SignalCommitLifecycle {
+    /** Runs after all fallible commit validation and before signal observers. */
+    apply(): void;
+    /** Restores a completed apply if a later writer cannot publish. */
+    rollback?(): void;
+    /** Releases a candidate when its writer never reaches Commit. */
+    abort(): void;
+}
+export interface SignalCommitBatch {
+    read<T>(signal: WritableSignal<T>): T;
+    stage<T>(signal: WritableSignal<T>, value: T, writer: object): void;
+    registerLifecycle(writer: object, lifecycle: SignalCommitLifecycle): void;
+    discardWriter(writer: object): void;
+    commit(onApplied?: () => void): void;
+    clear(): void;
+}
+export declare function createSignalCommitBatch(): SignalCommitBatch;
+/** @internal Stages a candidate with rollback provenance for one owner. */
+export declare function stageSignalCommitBatchWithProvenance<T>(batch: SignalCommitBatch, provenance: object, signal: WritableSignal<T>, value: T, writer: object): void;
+/** @internal Discards only candidates staged with one owner's provenance. */
+export declare function discardSignalCommitBatchProvenance(batch: SignalCommitBatch, provenance: object): void;
+/** @internal Applies friend discardWriter semantics inside one owner provenance. */
+export declare function discardSignalCommitBatchWriterForProvenance(batch: SignalCommitBatch, provenance: object, writer: object): void;
+export declare function withSignalTracking<T>(collector: SignalDependencyCollector, callback: () => T): T;
+export declare function withSignalWritePolicy<T>(policy: SignalWritePolicy, callback: () => T): T;
+export declare function withSignalWriteForbidden<T>(reason: string, callback: () => T): T;
+export declare function withDirectSignalWriteForbidden<T>(reason: string, callback: () => T): T;
+/** @internal Checks the active direct-write policy without mutating a signal. */
+export declare function assertSignalCommandAllowed(): void;
+/** @internal Preflight a direct signal writer without changing values or versions. */
+export declare function assertDirectSignalWriteAllowed(value: Signal<unknown>): void;
+/** @internal Installs the singleton policy that validates active writer leases. */
+export declare function installSignalWriterLeasePolicy(policy: SignalWriterLeasePolicy): void;