automatick 0.0.1 → 0.0.3

package/README.md

@@ -101,6 +101,8 @@ Useful when `step` is expensive (large grids, n-body simulations, fluid solvers)
 | `automatick/react/performance` | `<PerformanceOverlay>` |
 | `automatick/react/context` | `<SimulationContext>` |
 
+All entry points use named exports. If you'd rather have a single namespace object, use `import * as Automatick from 'automatick'` and call `Automatick.createEngine(...)` — same for any subpath.
+
 ## License
 
 MIT

package/dist/{chunk-YNLOTPDY.js → chunk-A375T3UD.js}

@@ -1,3 +1,7 @@
+import {
+  isInitFn
+} from "./chunk-IKR53C2U.js";
+
 // src/engine.ts
 var PERF_BUFFER_SIZE = 120;
 var SimulationEngine = class {
@@ -16,15 +20,40 @@ var SimulationEngine = class {
   listeners = /* @__PURE__ */ new Set();
   historyListeners = /* @__PURE__ */ new Set();
   perfBuffer = [];
+  rafId = null;
+  rafCancel = null;
   constructor(config) {
-    this.initFn = config.init;
+    const init = config.init;
+    if (isInitFn(init)) {
+      this.initFn = init;
+    } else {
+      const seed = structuredClone(init);
+      this.initFn = () => structuredClone(seed);
+    }
     this.stepFn = config.step;
     this.shouldStopFn = config.shouldStop;
     this.maxTime = config.maxTime;
     this.delayMs = config.delayMs ?? 0;
     this.ticksPerFrame = config.ticksPerFrame ?? 1;
-    this.params = { ...config.initialParams };
+    this.params = config.initialParams ? { ...config.initialParams } : {};
     this.data = this.initFn(this.params);
+    if (config.render) {
+      this.listeners.add(config.render);
+      config.render(this.getSnapshot());
+    }
+    const autoFrame = config.autoFrame ?? true;
+    if (autoFrame) {
+      const raf = globalThis.requestAnimationFrame;
+      const caf = globalThis.cancelAnimationFrame;
+      if (typeof raf === "function" && typeof caf === "function") {
+        const loop = (now) => {
+          this.handleAnimationFrame(now);
+          this.rafId = raf(loop);
+        };
+        this.rafCancel = caf;
+        this.rafId = raf(loop);
+      }
+    }
   }
   getSnapshot() {
     return {
@@ -141,6 +170,11 @@ var SimulationEngine = class {
     }
   }
   destroy() {
+    if (this.rafId !== null && this.rafCancel) {
+      this.rafCancel(this.rafId);
+    }
+    this.rafId = null;
+    this.rafCancel = null;
     this.listeners.clear();
     this.historyListeners.clear();
   }
@@ -160,7 +194,9 @@ var SimulationEngine = class {
       this.data = this.stepFn({
         data: this.data,
         params: this.params,
-        tick: this.tick
+        tick: this.tick,
+        status: this.status,
+        stepDurationMs: this.lastStepMs
       });
       const t1 = performance.now();
       this.lastStepMs = t1 - t0;

package/dist/chunk-IKR53C2U.js

@@ -0,0 +1,12 @@
+// src/sim.ts
+function isInitFn(init) {
+  return typeof init === "function";
+}
+function defineSim(sim) {
+  return sim;
+}
+
+export {
+  isInitFn,
+  defineSim
+};

package/dist/chunk-LMHH7YPE.js

@@ -0,0 +1,89 @@
+// src/worker/serialize.ts
+function deserializeWorkerMessage(raw) {
+  return raw;
+}
+function serializeMainMessage(msg) {
+  return msg;
+}
+
+// src/worker/workerRunner.ts
+var PERF_BUFFER_SIZE = 120;
+function createWorkerRunner(worker, config) {
+  const listeners = /* @__PURE__ */ new Set();
+  let currentSnapshot = {
+    data: void 0,
+    params: config.initialParams,
+    tick: 0,
+    status: "idle",
+    stepDurationMs: 0
+  };
+  const perfBuffer = [];
+  function send(msg) {
+    worker.postMessage(serializeMainMessage(msg));
+  }
+  function emit() {
+    for (const l of listeners) {
+      l(currentSnapshot);
+    }
+  }
+  function pushPerf(snapshot) {
+    if (snapshot.tick <= 0) return;
+    const last = perfBuffer[perfBuffer.length - 1];
+    if (last && last.tick === snapshot.tick) return;
+    if (perfBuffer.length >= PERF_BUFFER_SIZE) perfBuffer.shift();
+    perfBuffer.push({ tick: snapshot.tick, stepMs: snapshot.stepDurationMs });
+  }
+  worker.onmessage = (event) => {
+    const msg = deserializeWorkerMessage(event.data);
+    switch (msg.kind) {
+      case "snapshot":
+        currentSnapshot = msg.snapshot;
+        pushPerf(msg.snapshot);
+        emit();
+        break;
+      case "error":
+        currentSnapshot = { ...currentSnapshot, status: "stopped" };
+        emit();
+        break;
+    }
+  };
+  worker.onerror = () => {
+    currentSnapshot = { ...currentSnapshot, status: "stopped" };
+    emit();
+  };
+  return {
+    getSnapshot: () => currentSnapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    play: () => send({ kind: "play" }),
+    pause: () => send({ kind: "pause" }),
+    stop: () => send({ kind: "stop" }),
+    seek: (tick) => send({ kind: "seek", tick }),
+    advance: (count = 1) => send({ kind: "advance", count }),
+    setParams: (patch) => send({ kind: "setParams", patch }),
+    resetWith: (patch) => send({ kind: "resetWith", patch }),
+    setConfig: (patch) => send({ kind: "setConfig", patch }),
+    recordDrawTime(tick, ms) {
+      for (let i = perfBuffer.length - 1; i >= 0; i--) {
+        if (perfBuffer[i].tick === tick) {
+          perfBuffer[i].drawMs = ms;
+          return;
+        }
+      }
+    },
+    getPerformance: () => perfBuffer,
+    destroy() {
+      listeners.clear();
+      send({ kind: "destroy" });
+      worker.terminate();
+    }
+  };
+}
+
+export {
+  createWorkerRunner
+};

package/dist/chunk-VPS3ZXWI.js

@@ -0,0 +1,132 @@
+// src/worker/createSimWorker.ts
+var WORKER_SCRIPT = `
+let engine = null;
+let loopTimer = null;
+let snapshotIntervalMs = 16;
+let lastSnapshotMs = 0;
+let ticksPerFrame = 1;
+let delayMs = 0;
+
+function emitSnapshot() {
+  if (!engine) return;
+  postMessage({ kind: 'snapshot', snapshot: engine.getSnapshot() });
+  lastSnapshotMs = performance.now();
+}
+
+function tickLoop() {
+  if (!engine || engine.getStatus() !== 'playing') return;
+
+  for (let i = 0; i < ticksPerFrame; i++) {
+    engine.advance(1);
+    const s = engine.getStatus();
+    if (s === 'stopped') { emitSnapshot(); return; }
+    if (s !== 'paused') break;
+  }
+
+  // advance() transitions to paused; resume playing for the next batch
+  if (engine.getStatus() === 'paused') engine.play();
+
+  if (performance.now() - lastSnapshotMs >= snapshotIntervalMs) emitSnapshot();
+  loopTimer = setTimeout(tickLoop, delayMs);
+}
+
+function stopLoop() {
+  if (loopTimer !== null) { clearTimeout(loopTimer); loopTimer = null; }
+}
+
+self.onmessage = async (event) => {
+  const msg = event.data;
+  try {
+    switch (msg.kind) {
+      case 'init': {
+        delayMs = msg.config.delayMs || 0;
+        ticksPerFrame = msg.config.ticksPerFrame || 1;
+        snapshotIntervalMs = msg.config.snapshotIntervalMs || 16;
+
+        const [simMod, engineMod] = await Promise.all([
+          import(msg.moduleUrl),
+          import(msg.engineUrl),
+        ]);
+        const sim = simMod.default;
+        // Merge sim.defaultParams under the patch sent from main \u2014 the main
+        // thread sees the sim module via a URL, so it can't apply defaults.
+        const initialParams = { ...(sim.defaultParams || {}), ...(msg.params || {}) };
+        engine = engineMod.createEngine({
+          init: sim.init,
+          step: sim.step,
+          shouldStop: sim.shouldStop,
+          initialParams,
+          maxTime: msg.config.maxTime,
+          // Worker host owns its own setTimeout-driven loop; rAF wouldn't exist here anyway.
+          autoFrame: false,
+        });
+        emitSnapshot();
+        break;
+      }
+      case 'play':
+        if (!engine) return;
+        engine.play(); emitSnapshot(); stopLoop(); loopTimer = setTimeout(tickLoop, 0);
+        break;
+      case 'pause':
+        if (!engine) return;
+        stopLoop(); engine.pause(); emitSnapshot();
+        break;
+      case 'stop':
+        if (!engine) return;
+        stopLoop(); engine.stop(); emitSnapshot();
+        break;
+      case 'seek':
+        if (!engine) return;
+        stopLoop(); engine.seek(msg.tick); emitSnapshot();
+        break;
+      case 'advance':
+        if (!engine) return;
+        engine.advance(msg.count); emitSnapshot();
+        break;
+      case 'setParams':
+        if (!engine) return;
+        engine.setParams(msg.patch); emitSnapshot();
+        break;
+      case 'resetWith':
+        if (!engine) return;
+        stopLoop(); engine.resetWith(msg.patch); emitSnapshot();
+        break;
+      case 'setConfig':
+        if (msg.patch.delayMs !== undefined) delayMs = msg.patch.delayMs;
+        if (msg.patch.ticksPerFrame !== undefined) ticksPerFrame = msg.patch.ticksPerFrame;
+        if (msg.patch.snapshotIntervalMs !== undefined) snapshotIntervalMs = msg.patch.snapshotIntervalMs;
+        break;
+      case 'destroy':
+        stopLoop();
+        if (engine) { engine.destroy(); engine = null; }
+        self.close();
+        break;
+    }
+  } catch (err) {
+    postMessage({ kind: 'error', error: { message: err.message, stack: err.stack } });
+  }
+};
+`;
+function createSimWorker(options) {
+  const blob = new Blob([WORKER_SCRIPT], { type: "text/javascript" });
+  const blobUrl = URL.createObjectURL(blob);
+  const worker = new Worker(blobUrl, { type: "module" });
+  worker.addEventListener("message", function cleanup(event) {
+    if (event.data?.kind === "snapshot" || event.data?.kind === "error") {
+      URL.revokeObjectURL(blobUrl);
+      worker.removeEventListener("message", cleanup);
+    }
+  });
+  worker.postMessage({
+    kind: "init",
+    moduleUrl: options.moduleUrl,
+    engineUrl: options.engineUrl,
+    params: options.initialParams,
+    config: options.config
+  });
+  return worker;
+}
+
+export {
+  createSimWorker
+};

package/dist/engine.cjs

@@ -24,6 +24,13 @@ __export(engine_exports, {
   createEngine: () => createEngine
 });
 module.exports = __toCommonJS(engine_exports);
+
+// src/sim.ts
+function isInitFn(init) {
+  return typeof init === "function";
+}
+
+// src/engine.ts
 var PERF_BUFFER_SIZE = 120;
 var SimulationEngine = class {
   data;
@@ -41,15 +48,40 @@ var SimulationEngine = class {
   listeners = /* @__PURE__ */ new Set();
   historyListeners = /* @__PURE__ */ new Set();
   perfBuffer = [];
+  rafId = null;
+  rafCancel = null;
   constructor(config) {
-    this.initFn = config.init;
+    const init = config.init;
+    if (isInitFn(init)) {
+      this.initFn = init;
+    } else {
+      const seed = structuredClone(init);
+      this.initFn = () => structuredClone(seed);
+    }
     this.stepFn = config.step;
     this.shouldStopFn = config.shouldStop;
     this.maxTime = config.maxTime;
     this.delayMs = config.delayMs ?? 0;
     this.ticksPerFrame = config.ticksPerFrame ?? 1;
-    this.params = { ...config.initialParams };
+    this.params = config.initialParams ? { ...config.initialParams } : {};
     this.data = this.initFn(this.params);
+    if (config.render) {
+      this.listeners.add(config.render);
+      config.render(this.getSnapshot());
+    }
+    const autoFrame = config.autoFrame ?? true;
+    if (autoFrame) {
+      const raf = globalThis.requestAnimationFrame;
+      const caf = globalThis.cancelAnimationFrame;
+      if (typeof raf === "function" && typeof caf === "function") {
+        const loop = (now) => {
+          this.handleAnimationFrame(now);
+          this.rafId = raf(loop);
+        };
+        this.rafCancel = caf;
+        this.rafId = raf(loop);
+      }
+    }
   }
   getSnapshot() {
     return {
@@ -166,6 +198,11 @@ var SimulationEngine = class {
     }
   }
   destroy() {
+    if (this.rafId !== null && this.rafCancel) {
+      this.rafCancel(this.rafId);
+    }
+    this.rafId = null;
+    this.rafCancel = null;
     this.listeners.clear();
     this.historyListeners.clear();
   }
@@ -185,7 +222,9 @@ var SimulationEngine = class {
       this.data = this.stepFn({
         data: this.data,
         params: this.params,
-        tick: this.tick
+        tick: this.tick,
+        status: this.status,
+        stepDurationMs: this.lastStepMs
       });
       const t1 = performance.now();
       this.lastStepMs = t1 - t0;

package/dist/engine.d.cts

@@ -1,28 +1,50 @@
-import { StepArgs } from './sim.cjs';
+import { SimInit } from './sim.cjs';
+import { State, SimulationStatus } from './state.cjs';
 
-type SimulationStatus = 'idle' | 'playing' | 'paused' | 'stopped';
 type TickPerformance = {
     tick: number;
     stepMs: number;
     drawMs?: number;
 };
-type EngineConfig<Data, Params> = {
-    init: (params: Params) => Data;
-    step: (args: StepArgs<Data, Params>) => Data;
+type EngineConfig<Data, Params = Record<string, never>> = {
+    /**
+     * Initial simulation state — value or `(params) => Data`. See `SimInit`.
+     * When a value is passed, the engine `structuredClone`s it on each (re)init.
+     */
+    init: SimInit<Data, Params>;
+    step: (state: State<Data, Params>) => Data;
     shouldStop?: (data: Data, params: Params) => boolean;
-    initialParams: Params;
+    /**
+     * Initial param values. Optional — when omitted, the engine seeds an empty
+     * params object and `Params` defaults to `Record<string, never>`.
+     */
+    initialParams?: Params;
     maxTime?: number;
     delayMs?: number;
     ticksPerFrame?: number;
+    /**
+     * Optional render callback — sugar for the vanilla path. When provided, the
+     * engine calls it once with the initial state (right after init) and on
+     * every state emit thereafter, equivalent to `engine.subscribe(render)`
+     * followed by an initial paint. `subscribe` remains the lower-level
+     * primitive; React adapter and worker callers wire their own subscribers.
+     */
+    render?: (snapshot: State<Data, Params>) => void;
+    /**
+     * Drive `handleAnimationFrame` from an internal `requestAnimationFrame` loop.
+     * Defaults to `true` so vanilla callers don't have to write the loop. The
+     * React adapter and worker host pass `false` because they either own the
+     * frame loop themselves or run in an environment that has none. The loop is
+     * created at construction and torn down by `destroy()`. If
+     * `globalThis.requestAnimationFrame` is missing (server, worker), the option
+     * is silently a no-op.
+     *
+     * Note: when `true`, the rAF closure pins this engine in memory — vanilla
+     * consumers must call `destroy()` to let it be garbage-collected.
+     */
+    autoFrame?: boolean;
 };
-type EngineSnapshot<Data, Params> = {
-    data: Data;
-    params: Params;
-    tick: number;
-    status: SimulationStatus;
-    stepDurationMs: number;
-};
-declare class SimulationEngine<Data, Params> {
+declare class SimulationEngine<Data, Params = Record<string, never>> {
     private data;
     private params;
     private tick;
@@ -38,14 +60,16 @@ declare class SimulationEngine<Data, Params> {
     private readonly listeners;
     private readonly historyListeners;
     private readonly perfBuffer;
+    private rafId;
+    private rafCancel;
     constructor(config: EngineConfig<Data, Params>);
-    getSnapshot(): EngineSnapshot<Data, Params>;
+    getSnapshot(): State<Data, Params>;
     getStatus(): SimulationStatus;
     getPerformance(): readonly TickPerformance[];
     setDelayMs(ms: number): void;
     setTicksPerFrame(n: number): void;
     recordDrawTime(tick: number, ms: number): void;
-    subscribe(listener: (snapshot: EngineSnapshot<Data, Params>) => void): () => void;
+    subscribe(listener: (snapshot: State<Data, Params>) => void): () => void;
     subscribeHistory(listener: (entry: {
         tick: number;
         data: Data;
@@ -67,6 +91,6 @@ declare class SimulationEngine<Data, Params> {
     private emit;
     private emitHistory;
 }
-declare function createEngine<Data, Params>(config: EngineConfig<Data, Params>): SimulationEngine<Data, Params>;
+declare function createEngine<Data, Params = Record<string, never>>(config: EngineConfig<Data, Params>): SimulationEngine<Data, Params>;
 
-export { type EngineConfig, type EngineSnapshot, SimulationEngine, type SimulationStatus, type TickPerformance, createEngine };
+export { type EngineConfig, SimulationEngine, SimulationStatus, State, type TickPerformance, createEngine };

package/dist/engine.d.ts

@@ -1,28 +1,50 @@
-import { StepArgs } from './sim.js';
+import { SimInit } from './sim.js';
+import { State, SimulationStatus } from './state.js';
 
-type SimulationStatus = 'idle' | 'playing' | 'paused' | 'stopped';
 type TickPerformance = {
     tick: number;
     stepMs: number;
     drawMs?: number;
 };
-type EngineConfig<Data, Params> = {
-    init: (params: Params) => Data;
-    step: (args: StepArgs<Data, Params>) => Data;
+type EngineConfig<Data, Params = Record<string, never>> = {
+    /**
+     * Initial simulation state — value or `(params) => Data`. See `SimInit`.
+     * When a value is passed, the engine `structuredClone`s it on each (re)init.
+     */
+    init: SimInit<Data, Params>;
+    step: (state: State<Data, Params>) => Data;
     shouldStop?: (data: Data, params: Params) => boolean;
-    initialParams: Params;
+    /**
+     * Initial param values. Optional — when omitted, the engine seeds an empty
+     * params object and `Params` defaults to `Record<string, never>`.
+     */
+    initialParams?: Params;
     maxTime?: number;
     delayMs?: number;
     ticksPerFrame?: number;
+    /**
+     * Optional render callback — sugar for the vanilla path. When provided, the
+     * engine calls it once with the initial state (right after init) and on
+     * every state emit thereafter, equivalent to `engine.subscribe(render)`
+     * followed by an initial paint. `subscribe` remains the lower-level
+     * primitive; React adapter and worker callers wire their own subscribers.
+     */
+    render?: (snapshot: State<Data, Params>) => void;
+    /**
+     * Drive `handleAnimationFrame` from an internal `requestAnimationFrame` loop.
+     * Defaults to `true` so vanilla callers don't have to write the loop. The
+     * React adapter and worker host pass `false` because they either own the
+     * frame loop themselves or run in an environment that has none. The loop is
+     * created at construction and torn down by `destroy()`. If
+     * `globalThis.requestAnimationFrame` is missing (server, worker), the option
+     * is silently a no-op.
+     *
+     * Note: when `true`, the rAF closure pins this engine in memory — vanilla
+     * consumers must call `destroy()` to let it be garbage-collected.
+     */
+    autoFrame?: boolean;
 };
-type EngineSnapshot<Data, Params> = {
-    data: Data;
-    params: Params;
-    tick: number;
-    status: SimulationStatus;
-    stepDurationMs: number;
-};
-declare class SimulationEngine<Data, Params> {
+declare class SimulationEngine<Data, Params = Record<string, never>> {
     private data;
     private params;
     private tick;
@@ -38,14 +60,16 @@ declare class SimulationEngine<Data, Params> {
     private readonly listeners;
     private readonly historyListeners;
     private readonly perfBuffer;
+    private rafId;
+    private rafCancel;
     constructor(config: EngineConfig<Data, Params>);
-    getSnapshot(): EngineSnapshot<Data, Params>;
+    getSnapshot(): State<Data, Params>;
     getStatus(): SimulationStatus;
     getPerformance(): readonly TickPerformance[];
     setDelayMs(ms: number): void;
     setTicksPerFrame(n: number): void;
     recordDrawTime(tick: number, ms: number): void;
-    subscribe(listener: (snapshot: EngineSnapshot<Data, Params>) => void): () => void;
+    subscribe(listener: (snapshot: State<Data, Params>) => void): () => void;
     subscribeHistory(listener: (entry: {
         tick: number;
         data: Data;
@@ -67,6 +91,6 @@ declare class SimulationEngine<Data, Params> {
     private emit;
     private emitHistory;
 }
-declare function createEngine<Data, Params>(config: EngineConfig<Data, Params>): SimulationEngine<Data, Params>;
+declare function createEngine<Data, Params = Record<string, never>>(config: EngineConfig<Data, Params>): SimulationEngine<Data, Params>;
 
-export { type EngineConfig, type EngineSnapshot, SimulationEngine, type SimulationStatus, type TickPerformance, createEngine };
+export { type EngineConfig, SimulationEngine, SimulationStatus, State, type TickPerformance, createEngine };

package/dist/engine.js

@@ -1,7 +1,8 @@
 import {
   SimulationEngine,
   createEngine
-} from "./chunk-YNLOTPDY.js";
+} from "./chunk-A375T3UD.js";
+import "./chunk-IKR53C2U.js";
 export {
   SimulationEngine,
   createEngine

package/dist/react/EngineContext.d.cts

@@ -1,5 +1,6 @@
 import React from 'react';
-import { EngineSnapshot, TickPerformance } from '../engine.cjs';
+import { TickPerformance } from '../engine.cjs';
+import { State } from '../state.cjs';
 import '../sim.cjs';
 
 /**
@@ -8,8 +9,8 @@ import '../sim.cjs';
  * and to record draw timing back to the engine's performance buffer.
  */
 type EngineContextValue = {
-    subscribe: (listener: (snapshot: EngineSnapshot<unknown, unknown>) => void) => () => void;
-    getSnapshot: () => EngineSnapshot<unknown, unknown>;
+    subscribe: (listener: (snapshot: State<unknown, unknown>) => void) => () => void;
+    getSnapshot: () => State<unknown, unknown>;
     recordDrawTime: (tick: number, ms: number) => void;
     getPerformance: () => readonly TickPerformance[];
 };

package/dist/react/EngineContext.d.ts

@@ -1,5 +1,6 @@
 import React from 'react';
-import { EngineSnapshot, TickPerformance } from '../engine.js';
+import { TickPerformance } from '../engine.js';
+import { State } from '../state.js';
 import '../sim.js';
 
 /**
@@ -8,8 +9,8 @@ import '../sim.js';
  * and to record draw timing back to the engine's performance buffer.
  */
 type EngineContextValue = {
-    subscribe: (listener: (snapshot: EngineSnapshot<unknown, unknown>) => void) => () => void;
-    getSnapshot: () => EngineSnapshot<unknown, unknown>;
+    subscribe: (listener: (snapshot: State<unknown, unknown>) => void) => () => void;
+    getSnapshot: () => State<unknown, unknown>;
     recordDrawTime: (tick: number, ms: number) => void;
     getPerformance: () => readonly TickPerformance[];
 };