@pibbl/core 0.0.1

package/dist/features/particles/lib/system/binding.js

@@ -0,0 +1,122 @@
+import {
+  pibblInternalCurrentRenderOwner,
+  pibblInternalOnRenderFinish,
+  useInternalHookSlot
+} from "@pibbl/core/internal";
+import {
+  getParticleSystemController
+} from "./controller.js";
+function useParticleSystemBinding(input) {
+  const owner = pibblInternalCurrentRenderOwner();
+  const controller = getParticleSystemController(input.system);
+  const slot = useInternalHookSlot(
+    "particle-system-binding",
+    (teardowns) => {
+      let value;
+      const observers = Object.freeze({
+        onEvent(event) {
+          value.latestOnEvent?.(event);
+        },
+        onError(error) {
+          value.latestOnError?.(error);
+        }
+      });
+      value = {
+        controller,
+        committedController: void 0,
+        owner,
+        committed: void 0,
+        pending: void 0,
+        reservation: void 0,
+        latestOnEvent: void 0,
+        latestOnError: void 0,
+        revision: 0,
+        disposed: false,
+        observers
+      };
+      teardowns.add(() => {
+        value.disposed = true;
+        const pending = value.pending;
+        value.controller.cancelBindingReservation(value.reservation);
+        value.reservation = void 0;
+        value.pending = void 0;
+        if (pending !== void 0 && pending !== value.committed) {
+          value.controller.discardBindingCandidate(
+            pending,
+            "dispose-pending-binding"
+          );
+        }
+        value.committedController?.releaseBinding(value.owner, value.committed);
+        value.committedController = void 0;
+        value.committed = void 0;
+      });
+      return value;
+    }
+  ).value;
+  if (slot.owner !== owner) {
+    throw new Error("A Pibbl particle binding hook changed render ownership.");
+  }
+  if (slot.controller !== controller) {
+    slot.controller.cancelBindingReservation(slot.reservation);
+    slot.controller = controller;
+    slot.pending = void 0;
+    slot.reservation = void 0;
+  }
+  const reservation = controller.reserveBinding(owner, input.backend);
+  slot.reservation = reservation;
+  let candidate;
+  try {
+    candidate = input.create(owner);
+    controller.validateBindingCandidate(reservation, candidate);
+  } catch (error) {
+    controller.cancelBindingReservation(reservation);
+    slot.reservation = void 0;
+    if (candidate !== void 0 && candidate !== slot.committed) {
+      controller.discardBindingCandidate(candidate, "dispose-invalid-binding");
+    }
+    throw error;
+  }
+  const revision = ++slot.revision;
+  slot.pending = candidate;
+  pibblInternalOnRenderFinish(owner, (success) => {
+    if (slot.disposed) return;
+    if (revision !== slot.revision) {
+      controller.cancelBindingReservation(reservation);
+      if (candidate !== slot.committed) {
+        controller.discardBindingCandidate(candidate, "dispose-stale-binding");
+      }
+      return;
+    }
+    slot.pending = void 0;
+    slot.reservation = void 0;
+    if (!success) {
+      candidate.finishTransaction?.(false);
+      controller.recordRendererTransaction(owner, false);
+      if (slot.committedController !== controller) {
+        slot.committedController?.recordRendererTransaction(owner, false);
+      }
+      controller.cancelBindingReservation(reservation);
+      if (candidate !== slot.committed) {
+        controller.discardBindingCandidate(candidate, "dispose-failed-binding");
+      }
+      return;
+    }
+    slot.latestOnEvent = input.onEvent;
+    slot.latestOnError = input.onError;
+    const previousController = slot.committedController;
+    const previousCandidate = slot.committed;
+    controller.adoptBinding(reservation, candidate, slot.observers);
+    slot.committedController = controller;
+    slot.committed = candidate;
+    if (previousController !== void 0 && previousController !== controller) {
+      previousController.releaseBinding(slot.owner, previousCandidate);
+    }
+    candidate.finishTransaction?.(true);
+    controller.recordRendererTransaction(owner, true);
+  });
+  return candidate;
+}
+export {
+  useParticleSystemBinding
+};
+//# sourceMappingURL=binding.js.map

package/dist/features/particles/lib/system/binding.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/features/particles/lib/system/binding.ts"],
+  "sourcesContent": ["import {\n  pibblInternalCurrentRenderOwner,\n  pibblInternalOnRenderFinish,\n  useInternalHookSlot,\n  type PibblInternalRenderOwner,\n} from \"@pibbl/core/internal\";\nimport type { CompiledEffect2D } from \"../compiler.js\";\nimport type {\n  PibblParticleExecution,\n  PibblParticleSystem,\n  PibblParticleSystemEvent,\n  PibblParticleSystemStatus,\n} from \"../types.js\";\nimport {\n  getParticleSystemController,\n  type ParticleBindingObservers,\n  type ParticleBindingReservation,\n  type ParticleSystemController,\n} from \"./controller.js\";\n\nexport type CompiledParticleEffect = CompiledEffect2D;\n\nexport interface ParticleBindingFrameState {\n  readonly liveCount: number;\n  readonly nextAutomaticBirthMilliseconds: number | null;\n  readonly latestDeathMilliseconds: number | null;\n}\n\nexport interface ParticleBindingBurstRequest {\n  readonly generation: number;\n  readonly emitterIndex: number;\n  readonly count: number | undefined;\n  readonly birthTimeMilliseconds: number;\n  readonly seed: number;\n  readonly seedSalt: number;\n  readonly origin: readonly [number, number];\n  readonly spawnEpoch: number;\n}\n\nexport interface ParticleBindingBurstResult extends ParticleBindingFrameState {\n  readonly requested: number;\n  readonly accepted: number;\n  readonly rejected: number;\n}\n\nexport interface ParticleBindingCandidate {\n  readonly owner: PibblInternalRenderOwner;\n  readonly backend: \"canvas\";\n  readonly execution: PibblParticleExecution;\n  readonly compiled: CompiledParticleEffect;\n  readonly parameters: Readonly<Float64Array>;\n  requestRender(): void;\n  adoptFrame(frame: ParticleSystemFrame): ParticleBindingFrameState | void;\n  requestedBurstCount?(\n    emitterIndex: number,\n    count: number | undefined,\n    seed: number,\n  ): number;\n  emitBurst?(request: ParticleBindingBurstRequest): ParticleBindingBurstResult;\n  clear(): ParticleBindingFrameState | void;\n  finishTransaction?(success: boolean): void;\n  dispose(): void;\n}\n\nexport interface ParticleSystemFrame {\n  readonly generation: number;\n  readonly frameId: number;\n  readonly logicalTime: number;\n  readonly effectTimeMilliseconds: number;\n  readonly previousEffectTimeMilliseconds: number;\n  readonly seed: number;\n  readonly status: PibblParticleSystemStatus;\n}\n\nexport interface ParticleSystemBindingInput {\n  readonly system: PibblParticleSystem;\n  readonly backend: \"canvas\";\n  readonly create: (owner: PibblInternalRenderOwner) => ParticleBindingCandidate;\n  readonly onEvent?: (event: PibblParticleSystemEvent) => void;\n  readonly onError?: (error: unknown) => void;\n}\n\ninterface ParticleBindingHookSlot {\n  controller: ParticleSystemController;\n  committedController: ParticleSystemController | undefined;\n  owner: PibblInternalRenderOwner;\n  committed: ParticleBindingCandidate | undefined;\n  pending: ParticleBindingCandidate | undefined;\n  reservation: ParticleBindingReservation | undefined;\n  latestOnEvent: ((event: PibblParticleSystemEvent) => void) | undefined;\n  latestOnError: ((error: unknown) => void) | undefined;\n  revision: number;\n  disposed: boolean;\n  readonly observers: ParticleBindingObservers;\n}\n\n/**\n * Reserves, validates, and transactionally adopts one renderer-owned particle\n * candidate. The factory is deliberately called only after conflict checking.\n */\nexport function useParticleSystemBinding(\n  input: ParticleSystemBindingInput,\n): ParticleBindingCandidate {\n  const owner = pibblInternalCurrentRenderOwner();\n  const controller = getParticleSystemController(input.system);\n  const slot = useInternalHookSlot<ParticleBindingHookSlot>(\n    \"particle-system-binding\",\n    (teardowns) => {\n      let value!: ParticleBindingHookSlot;\n      const observers: ParticleBindingObservers = Object.freeze({\n        onEvent(event: PibblParticleSystemEvent) {\n          value.latestOnEvent?.(event);\n        },\n        onError(error: unknown) {\n          value.latestOnError?.(error);\n        },\n      });\n      value = {\n        controller,\n        committedController: undefined,\n        owner,\n        committed: undefined,\n        pending: undefined,\n        reservation: undefined,\n        latestOnEvent: undefined,\n        latestOnError: undefined,\n        revision: 0,\n        disposed: false,\n        observers,\n      };\n      teardowns.add(() => {\n        value.disposed = true;\n        const pending = value.pending;\n        value.controller.cancelBindingReservation(value.reservation);\n        value.reservation = undefined;\n        value.pending = undefined;\n        if (pending !== undefined && pending !== value.committed) {\n          value.controller.discardBindingCandidate(\n            pending,\n            \"dispose-pending-binding\",\n          );\n        }\n        value.committedController?.releaseBinding(value.owner, value.committed);\n        value.committedController = undefined;\n        value.committed = undefined;\n      });\n      return value;\n    },\n  ).value;\n\n  if (slot.owner !== owner) {\n    throw new Error(\"A Pibbl particle binding hook changed render ownership.\");\n  }\n  if (slot.controller !== controller) {\n    slot.controller.cancelBindingReservation(slot.reservation);\n    slot.controller = controller;\n    slot.pending = undefined;\n    slot.reservation = undefined;\n  }\n\n  const reservation = controller.reserveBinding(owner, input.backend);\n  slot.reservation = reservation;\n  let candidate: ParticleBindingCandidate | undefined;\n  try {\n    candidate = input.create(owner);\n    controller.validateBindingCandidate(reservation, candidate);\n  } catch (error) {\n    controller.cancelBindingReservation(reservation);\n    slot.reservation = undefined;\n    if (candidate !== undefined && candidate !== slot.committed) {\n      controller.discardBindingCandidate(candidate, \"dispose-invalid-binding\");\n    }\n    throw error;\n  }\n\n  const revision = ++slot.revision;\n  slot.pending = candidate;\n  pibblInternalOnRenderFinish(owner, (success) => {\n    if (slot.disposed) return;\n    if (revision !== slot.revision) {\n      controller.cancelBindingReservation(reservation);\n      if (candidate !== slot.committed) {\n        controller.discardBindingCandidate(candidate, \"dispose-stale-binding\");\n      }\n      return;\n    }\n    slot.pending = undefined;\n    slot.reservation = undefined;\n    if (!success) {\n      candidate.finishTransaction?.(false);\n      controller.recordRendererTransaction(owner, false);\n      if (slot.committedController !== controller) {\n        slot.committedController?.recordRendererTransaction(owner, false);\n      }\n      controller.cancelBindingReservation(reservation);\n      if (candidate !== slot.committed) {\n        controller.discardBindingCandidate(candidate, \"dispose-failed-binding\");\n      }\n      return;\n    }\n    slot.latestOnEvent = input.onEvent;\n    slot.latestOnError = input.onError;\n    const previousController = slot.committedController;\n    const previousCandidate = slot.committed;\n    controller.adoptBinding(reservation, candidate, slot.observers);\n    slot.committedController = controller;\n    slot.committed = candidate;\n    if (previousController !== undefined && previousController !== controller) {\n      previousController.releaseBinding(slot.owner, previousCandidate);\n    }\n    candidate.finishTransaction?.(true);\n    controller.recordRendererTransaction(owner, true);\n  });\n  return candidate;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/features/particles/lib/system/controller.d.ts

@@ -0,0 +1,58 @@
+import { type PibblFlowField2D } from "../flow/hook.js";
+import { type PibblInternalRenderOwner } from "@pibbl/core/internal";
+import type { PibblParticleEffect2D, PibblParticleSystem, PibblParticleSystemEvent, PibblParticleSystemOptions } from "../types.js";
+import type { CompiledParticleEffect, ParticleBindingCandidate } from "./binding.js";
+type ParticleEffect = PibblParticleEffect2D;
+export interface ParticleBindingObservers {
+    readonly onEvent?: (event: PibblParticleSystemEvent) => void;
+    readonly onError?: (error: unknown) => void;
+}
+export interface ParticleBindingReservation {
+    readonly owner: PibblInternalRenderOwner;
+    readonly backend: "canvas";
+    readonly token: object;
+}
+export interface ParticleEffectCandidate {
+    readonly effect: ParticleEffect;
+    readonly compiled: CompiledParticleEffect;
+    readonly options: PibblParticleSystemOptions;
+    readonly debugName: string | undefined;
+}
+export interface ParticleSystemControllerSnapshot {
+    readonly disposed: boolean;
+    readonly generation: number;
+    readonly seed: number;
+    readonly effectTimeMilliseconds: number;
+    readonly previousEffectTimeMilliseconds: number;
+    readonly binding: "canvas" | "unbound";
+    readonly parameterEpochs: number;
+}
+export interface ParticleSystemController {
+    readonly flow: PibblFlowField2D | undefined;
+    readonly handle: PibblParticleSystem;
+    readonly compiled: CompiledParticleEffect;
+    readonly bindingCandidate: ParticleBindingCandidate | undefined;
+    readonly currentSpawnEpoch: number;
+    readonly simulationParameters: Readonly<Float64Array>;
+    readonly renderParameters: Readonly<Float64Array>;
+    prepareEffect(effect: ParticleEffect, options?: PibblParticleSystemOptions): ParticleEffectCandidate;
+    cancelEffect(candidate: ParticleEffectCandidate): void;
+    adoptEffect(candidate: ParticleEffectCandidate): void;
+    reserveBinding(owner: PibblInternalRenderOwner, backend: "canvas"): ParticleBindingReservation;
+    validateBindingCandidate(reservation: ParticleBindingReservation, candidate: ParticleBindingCandidate): void;
+    cancelBindingReservation(reservation: ParticleBindingReservation | undefined): void;
+    discardBindingCandidate(candidate: ParticleBindingCandidate, operation: string): void;
+    adoptBinding(reservation: ParticleBindingReservation, candidate: ParticleBindingCandidate, observers?: ParticleBindingObservers): void;
+    releaseBinding(owner: PibblInternalRenderOwner, candidate?: ParticleBindingCandidate): void;
+    recordRendererTransaction(owner: PibblInternalRenderOwner, success: boolean): void;
+    spawnParameters(epoch: number): Readonly<Float64Array>;
+    retainSpawnEpoch(epoch: number, count?: number): void;
+    releaseSpawnEpoch(epoch: number, count?: number): void;
+    snapshot(): ParticleSystemControllerSnapshot;
+    dispose(): void;
+}
+/** Creates one hook-owned particle controller over the realm scheduler. */
+export declare function createParticleSystemController(owner: PibblInternalRenderOwner, initialEffect: ParticleEffect, initialOptions?: PibblParticleSystemOptions): ParticleSystemController;
+export declare function getParticleSystemController(system: PibblParticleSystem): ParticleSystemController;
+export declare function particleSystemControllerSnapshot(system: PibblParticleSystem): ParticleSystemControllerSnapshot;
+export {};