automatick 0.0.1 → 0.0.2

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-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-YNLOTPDY.js → chunk-UU5V7HGM.js}

@@ -1,3 +1,7 @@
+import {
+  isInitFn
+} from "./chunk-IKR53C2U.js";
+
 // src/engine.ts
 var PERF_BUFFER_SIZE = 120;
 var SimulationEngine = class {
@@ -16,8 +20,16 @@ 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;
@@ -25,6 +37,23 @@ var SimulationEngine = class {
     this.ticksPerFrame = config.ticksPerFrame ?? 1;
     this.params = { ...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/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,8 +48,16 @@ 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;
@@ -50,6 +65,23 @@ var SimulationEngine = class {
     this.ticksPerFrame = config.ticksPerFrame ?? 1;
     this.params = { ...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,26 +1,44 @@
-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;
+    /**
+     * 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;
     maxTime?: number;
     delayMs?: number;
     ticksPerFrame?: number;
-};
-type EngineSnapshot<Data, Params> = {
-    data: Data;
-    params: Params;
-    tick: number;
-    status: SimulationStatus;
-    stepDurationMs: 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;
 };
 declare class SimulationEngine<Data, Params> {
     private data;
@@ -38,14 +56,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;
@@ -69,4 +89,4 @@ declare class SimulationEngine<Data, Params> {
 }
 declare function createEngine<Data, Params>(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,26 +1,44 @@
-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;
+    /**
+     * 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;
     maxTime?: number;
     delayMs?: number;
     ticksPerFrame?: number;
-};
-type EngineSnapshot<Data, Params> = {
-    data: Data;
-    params: Params;
-    tick: number;
-    status: SimulationStatus;
-    stepDurationMs: 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;
 };
 declare class SimulationEngine<Data, Params> {
     private data;
@@ -38,14 +56,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;
@@ -69,4 +89,4 @@ declare class SimulationEngine<Data, Params> {
 }
 declare function createEngine<Data, Params>(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-UU5V7HGM.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[];
 };

package/dist/react/Simulation.cjs

@@ -35,6 +35,11 @@ __export(Simulation_exports, {
 module.exports = __toCommonJS(Simulation_exports);
 var import_react4 = __toESM(require("react"), 1);
 
+// src/sim.ts
+function isInitFn(init) {
+  return typeof init === "function";
+}
+
 // src/engine.ts
 var PERF_BUFFER_SIZE = 120;
 var SimulationEngine = class {
@@ -53,8 +58,16 @@ 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;
@@ -62,6 +75,23 @@ var SimulationEngine = class {
     this.ticksPerFrame = config.ticksPerFrame ?? 1;
     this.params = { ...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 {
@@ -178,6 +208,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();
   }
@@ -197,7 +232,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;
@@ -271,7 +308,9 @@ function LocalSimulation(props) {
       initialParams,
       maxTime: props.maxTime,
       delayMs: props.delayMs,
-      ticksPerFrame: props.ticksPerFrame
+      ticksPerFrame: props.ticksPerFrame,
+      // The React adapter drives its own rAF loop tied to component lifecycle.
+      autoFrame: false
     });
   }
   const engine = engineRef.current;
@@ -312,7 +351,9 @@ function WorkerSimulation(props) {
   const [backend, setBackend] = import_react4.default.useState(
     null
   );
-  const [snapshot, setSnapshot] = import_react4.default.useState(null);
+  const [snapshot, setSnapshot] = import_react4.default.useState(
+    null
+  );
   const propsRef = import_react4.default.useRef(props);
   propsRef.current = props;
   import_react4.default.useEffect(() => {
@@ -329,7 +370,8 @@ function WorkerSimulation(props) {
         step: simModule.step,
         shouldStop: simModule.shouldStop,
         initialParams,
-        maxTime: p.maxTime
+        maxTime: p.maxTime,
+        autoFrame: false
       });
       if (cancelled) {
         engine.destroy();
@@ -452,6 +494,8 @@ function SimulationProvider({
   );
   const engineValue = import_react4.default.useMemo(
     () => ({
+      // TODO(#14): casts here bridge EngineContext's non-generic shape to
+      // the typed Backend<Data, Params>. Make EngineContext generic to drop them.
       subscribe: (listener) => backend.subscribe(
         listener
       ),

package/dist/react/Simulation.d.cts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import { SimModule } from '../sim.cjs';
+import '../state.cjs';
 
 type SimulationPropsLocal<Data, Params> = {
     sim: SimModule<Data, Params>;

package/dist/react/Simulation.d.ts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import { SimModule } from '../sim.js';
+import '../state.js';
 
 type SimulationPropsLocal<Data, Params> = {
     sim: SimModule<Data, Params>;

package/dist/react/Simulation.js

@@ -3,7 +3,8 @@ import {
 } from "../chunk-SK5SHIWY.js";
 import {
   createEngine
-} from "../chunk-YNLOTPDY.js";
+} from "../chunk-UU5V7HGM.js";
+import "../chunk-IKR53C2U.js";
 import {
   EngineContext
 } from "../chunk-OA6FGXTP.js";
@@ -26,7 +27,9 @@ function LocalSimulation(props) {
       initialParams,
       maxTime: props.maxTime,
       delayMs: props.delayMs,
-      ticksPerFrame: props.ticksPerFrame
+      ticksPerFrame: props.ticksPerFrame,
+      // The React adapter drives its own rAF loop tied to component lifecycle.
+      autoFrame: false
     });
   }
   const engine = engineRef.current;
@@ -67,7 +70,9 @@ function WorkerSimulation(props) {
   const [backend, setBackend] = React.useState(
     null
   );
-  const [snapshot, setSnapshot] = React.useState(null);
+  const [snapshot, setSnapshot] = React.useState(
+    null
+  );
   const propsRef = React.useRef(props);
   propsRef.current = props;
   React.useEffect(() => {
@@ -84,7 +89,8 @@ function WorkerSimulation(props) {
         step: simModule.step,
         shouldStop: simModule.shouldStop,
         initialParams,
-        maxTime: p.maxTime
+        maxTime: p.maxTime,
+        autoFrame: false
       });
       if (cancelled) {
         engine.destroy();
@@ -207,6 +213,8 @@ function SimulationProvider({
   );
   const engineValue = React.useMemo(
     () => ({
+      // TODO(#14): casts here bridge EngineContext's non-generic shape to
+      // the typed Backend<Data, Params>. Make EngineContext generic to drop them.
       subscribe: (listener) => backend.subscribe(
         listener
       ),

package/dist/react/SimulationContext.d.cts

@@ -1,6 +1,5 @@
 import React from 'react';
-import { SimulationStatus } from '../engine.cjs';
-import '../sim.cjs';
+import { SimulationStatus } from '../state.cjs';
 
 type SimulationContextValue<Data, Params> = {
     data: Data;

package/dist/react/SimulationContext.d.ts

@@ -1,6 +1,5 @@
 import React from 'react';
-import { SimulationStatus } from '../engine.js';
-import '../sim.js';
+import { SimulationStatus } from '../state.js';
 
 type SimulationContextValue<Data, Params> = {
     data: Data;

package/dist/react/hooks.d.cts

@@ -1,7 +1,7 @@
 import { SimulationContextValue } from './SimulationContext.cjs';
 import { SimModule } from '../sim.cjs';
 import 'react';
-import '../engine.cjs';
+import '../state.cjs';
 
 /**
  * Helper type: extract Data and Params from a SimModule type, or use them directly.

package/dist/react/hooks.d.ts

@@ -1,7 +1,7 @@
 import { SimulationContextValue } from './SimulationContext.js';
 import { SimModule } from '../sim.js';
 import 'react';
-import '../engine.js';
+import '../state.js';
 
 /**
  * Helper type: extract Data and Params from a SimModule type, or use them directly.

package/dist/react/useSimulationCanvas.cjs

@@ -59,11 +59,7 @@ function useSimulationCanvas(draw) {
       if (ctx) {
         const snap = engineCtx.getSnapshot();
         const t0 = performance.now();
-        drawRef.current(ctx, {
-          data: snap.data,
-          params: snap.params,
-          tick: snap.tick
-        });
+        drawRef.current(ctx, snap);
         engineCtx.recordDrawTime(snap.tick, performance.now() - t0);
       }
     }
@@ -74,11 +70,7 @@ function useSimulationCanvas(draw) {
         const ctx = canvas2.getContext("2d");
         if (!ctx) return;
         const t0 = performance.now();
-        drawRef.current(ctx, {
-          data: snap.data,
-          params: snap.params,
-          tick: snap.tick
-        });
+        drawRef.current(ctx, snap);
         engineCtx.recordDrawTime(snap.tick, performance.now() - t0);
       }
     );

package/dist/react/useSimulationCanvas.d.cts

@@ -1,18 +1,15 @@
 import React from 'react';
 import { SimModule } from '../sim.cjs';
+import { State } from '../state.cjs';
 
 /**
  * Draw callback signature for useSimulationCanvas.
- * Called imperatively on every engine snapshot — no React re-render involved.
+ * Called imperatively on every engine state emit — no React re-render involved.
  */
-type CanvasDrawFn<Data, Params> = (ctx: CanvasRenderingContext2D, snapshot: {
-    data: Data;
-    params: Params;
-    tick: number;
-}) => void;
+type CanvasDrawFn<Data, Params> = (ctx: CanvasRenderingContext2D, snapshot: State<Data, Params>) => void;
 type InferDraw<T, FallbackParams> = T extends SimModule<infer D, infer P> ? CanvasDrawFn<D, P> : CanvasDrawFn<T, FallbackParams>;
 /**
- * Subscribe to simulation snapshots and draw to a canvas without React re-renders.
+ * Subscribe to simulation state and draw to a canvas without React re-renders.
  *
  * Returns a ref to attach to a `<canvas>` element. The `draw` callback is called
  * directly from the engine's subscription — it bypasses React's state/reconciliation

package/dist/react/useSimulationCanvas.d.ts

@@ -1,18 +1,15 @@
 import React from 'react';
 import { SimModule } from '../sim.js';
+import { State } from '../state.js';
 
 /**
  * Draw callback signature for useSimulationCanvas.
- * Called imperatively on every engine snapshot — no React re-render involved.
+ * Called imperatively on every engine state emit — no React re-render involved.
  */
-type CanvasDrawFn<Data, Params> = (ctx: CanvasRenderingContext2D, snapshot: {
-    data: Data;
-    params: Params;
-    tick: number;
-}) => void;
+type CanvasDrawFn<Data, Params> = (ctx: CanvasRenderingContext2D, snapshot: State<Data, Params>) => void;
 type InferDraw<T, FallbackParams> = T extends SimModule<infer D, infer P> ? CanvasDrawFn<D, P> : CanvasDrawFn<T, FallbackParams>;
 /**
- * Subscribe to simulation snapshots and draw to a canvas without React re-renders.
+ * Subscribe to simulation state and draw to a canvas without React re-renders.
  *
  * Returns a ref to attach to a `<canvas>` element. The `draw` callback is called
  * directly from the engine's subscription — it bypasses React's state/reconciliation

package/dist/react/useSimulationCanvas.js

@@ -21,11 +21,7 @@ function useSimulationCanvas(draw) {
       if (ctx) {
         const snap = engineCtx.getSnapshot();
         const t0 = performance.now();
-        drawRef.current(ctx, {
-          data: snap.data,
-          params: snap.params,
-          tick: snap.tick
-        });
+        drawRef.current(ctx, snap);
         engineCtx.recordDrawTime(snap.tick, performance.now() - t0);
       }
     }
@@ -36,11 +32,7 @@ function useSimulationCanvas(draw) {
         const ctx = canvas2.getContext("2d");
         if (!ctx) return;
         const t0 = performance.now();
-        drawRef.current(ctx, {
-          data: snap.data,
-          params: snap.params,
-          tick: snap.tick
-        });
+        drawRef.current(ctx, snap);
         engineCtx.recordDrawTime(snap.tick, performance.now() - t0);
       }
     );

package/dist/sim.cjs

@@ -20,13 +20,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/sim.ts
 var sim_exports = {};
 __export(sim_exports, {
-  defineSim: () => defineSim
+  defineSim: () => defineSim,
+  isInitFn: () => isInitFn
 });
 module.exports = __toCommonJS(sim_exports);
+function isInitFn(init) {
+  return typeof init === "function";
+}
 function defineSim(sim) {
   return sim;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  defineSim
+  defineSim,
+  isInitFn
 });

package/dist/sim.d.cts

@@ -1,15 +1,31 @@
-/** Arguments passed to the `step` function on each tick. */
-type StepArgs<Data, Params> = {
-    data: Data;
-    params: Params;
-    tick: number;
-};
+import { State } from './state.cjs';
+
+/**
+ * Initial state for a simulation. Either a value of type `Data`, or a function
+ * `(params) => Data`. The function form is required when the initial state
+ * depends on params; otherwise pass the value directly.
+ *
+ * `Data` itself must not be a function — it has to be structured-cloneable so
+ * it can cross the worker boundary and be safely re-emitted on resetWith.
+ * That's what makes this union unambiguous: a `function` value is always the
+ * `(params) => Data` branch.
+ */
+type SimInit<Data, Params> = ((params: Params) => Data) | Data;
+/**
+ * Type guard that narrows a `SimInit` to its function branch. Defined as a
+ * user-typed predicate so we can do the narrowing without an `as` cast.
+ */
+declare function isInitFn<Data, Params>(init: SimInit<Data, Params>): init is (params: Params) => Data;
 /** A simulation module: the pure business logic that automatick drives. */
 type SimModule<Data, Params> = {
-    /** Create initial simulation state from params. Called on engine creation and on resetWith(). */
-    init: (params: Params) => Data;
+    /**
+     * Initial simulation state — value or `(params) => Data`. When a value is
+     * passed, the engine takes a fresh `structuredClone` on every (re)init so
+     * mutations inside `step` never leak across resets.
+     */
+    init: SimInit<Data, Params>;
     /** Advance the simulation by one tick. Must be pure and synchronous. */
-    step: (args: StepArgs<Data, Params>) => Data;
+    step: (state: State<Data, Params>) => Data;
     /** Optional termination predicate. Checked after each step. If it returns true, the simulation stops. */
     shouldStop?: (data: Data, params: Params) => boolean;
     /** Default parameter values. Used at engine creation if no params override is provided. */
@@ -37,4 +53,4 @@ type SimData<M> = M extends SimModule<infer D, infer _P> ? D : never;
 /** Extract the Params type from a SimModule. */
 type SimParams<M> = M extends SimModule<infer _D, infer P> ? P : never;
 
-export { type SimData, type SimModule, type SimParams, type StepArgs, defineSim };
+export { type SimData, type SimInit, type SimModule, type SimParams, defineSim, isInitFn };

package/dist/sim.d.ts

@@ -1,15 +1,31 @@
-/** Arguments passed to the `step` function on each tick. */
-type StepArgs<Data, Params> = {
-    data: Data;
-    params: Params;
-    tick: number;
-};
+import { State } from './state.js';
+
+/**
+ * Initial state for a simulation. Either a value of type `Data`, or a function
+ * `(params) => Data`. The function form is required when the initial state
+ * depends on params; otherwise pass the value directly.
+ *
+ * `Data` itself must not be a function — it has to be structured-cloneable so
+ * it can cross the worker boundary and be safely re-emitted on resetWith.
+ * That's what makes this union unambiguous: a `function` value is always the
+ * `(params) => Data` branch.
+ */
+type SimInit<Data, Params> = ((params: Params) => Data) | Data;
+/**
+ * Type guard that narrows a `SimInit` to its function branch. Defined as a
+ * user-typed predicate so we can do the narrowing without an `as` cast.
+ */
+declare function isInitFn<Data, Params>(init: SimInit<Data, Params>): init is (params: Params) => Data;
 /** A simulation module: the pure business logic that automatick drives. */
 type SimModule<Data, Params> = {
-    /** Create initial simulation state from params. Called on engine creation and on resetWith(). */
-    init: (params: Params) => Data;
+    /**
+     * Initial simulation state — value or `(params) => Data`. When a value is
+     * passed, the engine takes a fresh `structuredClone` on every (re)init so
+     * mutations inside `step` never leak across resets.
+     */
+    init: SimInit<Data, Params>;
     /** Advance the simulation by one tick. Must be pure and synchronous. */
-    step: (args: StepArgs<Data, Params>) => Data;
+    step: (state: State<Data, Params>) => Data;
     /** Optional termination predicate. Checked after each step. If it returns true, the simulation stops. */
     shouldStop?: (data: Data, params: Params) => boolean;
     /** Default parameter values. Used at engine creation if no params override is provided. */
@@ -37,4 +53,4 @@ type SimData<M> = M extends SimModule<infer D, infer _P> ? D : never;
 /** Extract the Params type from a SimModule. */
 type SimParams<M> = M extends SimModule<infer _D, infer P> ? P : never;
 
-export { type SimData, type SimModule, type SimParams, type StepArgs, defineSim };
+export { type SimData, type SimInit, type SimModule, type SimParams, defineSim, isInitFn };

package/dist/sim.js

@@ -1,7 +1,8 @@
-// src/sim.ts
-function defineSim(sim) {
-  return sim;
-}
+import {
+  defineSim,
+  isInitFn
+} from "./chunk-IKR53C2U.js";
 export {
-  defineSim
+  defineSim,
+  isInitFn
 };

package/dist/state.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/state.ts
+var state_exports = {};
+module.exports = __toCommonJS(state_exports);

package/dist/state.d.cts

@@ -0,0 +1,16 @@
+/**
+ * The unified engine state shape — passed to `step`, returned by `getSnapshot`,
+ * and delivered to the `render` callback. All three are operations on the
+ * engine's inner state, so they share one type.
+ */
+type State<Data, Params> = {
+    data: Data;
+    params: Params;
+    tick: number;
+    status: SimulationStatus;
+    /** Duration of the previous step in ms. `0` before the first step has run. */
+    stepDurationMs: number;
+};
+type SimulationStatus = 'idle' | 'playing' | 'paused' | 'stopped';
+
+export type { SimulationStatus, State };

package/dist/state.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The unified engine state shape — passed to `step`, returned by `getSnapshot`,
+ * and delivered to the `render` callback. All three are operations on the
+ * engine's inner state, so they share one type.
+ */
+type State<Data, Params> = {
+    data: Data;
+    params: Params;
+    tick: number;
+    status: SimulationStatus;
+    /** Duration of the previous step in ms. `0` before the first step has run. */
+    stepDurationMs: number;
+};
+type SimulationStatus = 'idle' | 'playing' | 'paused' | 'stopped';
+
+export type { SimulationStatus, State };

package/dist/worker/createSimWorker.cjs

@@ -78,6 +78,8 @@ self.onmessage = async (event) => {
           shouldStop: sim.shouldStop,
           initialParams: msg.params,
           maxTime: msg.config.maxTime,
+          // Worker host owns its own setTimeout-driven loop; rAF wouldn't exist here anyway.
+          autoFrame: false,
         });
         postMessage({ kind: 'ready' });
         emitSnapshot();

package/dist/worker/createSimWorker.d.cts

@@ -1,6 +1,5 @@
 import { WorkerConfig } from './protocol.cjs';
-import '../engine.cjs';
-import '../sim.cjs';
+import '../state.cjs';
 
 /**
  * Creates a Web Worker that loads a sim module and runs the engine.

package/dist/worker/createSimWorker.d.ts

@@ -1,6 +1,5 @@
 import { WorkerConfig } from './protocol.js';
-import '../engine.js';
-import '../sim.js';
+import '../state.js';
 
 /**
  * Creates a Web Worker that loads a sim module and runs the engine.

package/dist/worker/createSimWorker.js

@@ -54,6 +54,8 @@ self.onmessage = async (event) => {
           shouldStop: sim.shouldStop,
           initialParams: msg.params,
           maxTime: msg.config.maxTime,
+          // Worker host owns its own setTimeout-driven loop; rAF wouldn't exist here anyway.
+          autoFrame: false,
         });
         postMessage({ kind: 'ready' });
         emitSnapshot();

package/dist/worker/protocol.d.cts

@@ -1,5 +1,4 @@
-import { EngineSnapshot } from '../engine.cjs';
-import '../sim.cjs';
+import { State } from '../state.cjs';
 
 /**
  * Wire protocol types for main ↔ worker communication.
@@ -38,7 +37,7 @@ type MainToWorkerMessage<Params> = {
 /** Messages sent from the worker to the main thread. */
 type WorkerToMainMessage<Data, Params> = {
     kind: 'snapshot';
-    snapshot: EngineSnapshot<Data, Params>;
+    snapshot: State<Data, Params>;
 } | {
     kind: 'error';
     error: {

package/dist/worker/protocol.d.ts

@@ -1,5 +1,4 @@
-import { EngineSnapshot } from '../engine.js';
-import '../sim.js';
+import { State } from '../state.js';
 
 /**
  * Wire protocol types for main ↔ worker communication.
@@ -38,7 +37,7 @@ type MainToWorkerMessage<Params> = {
 /** Messages sent from the worker to the main thread. */
 type WorkerToMainMessage<Data, Params> = {
     kind: 'snapshot';
-    snapshot: EngineSnapshot<Data, Params>;
+    snapshot: State<Data, Params>;
 } | {
     kind: 'error';
     error: {

package/dist/worker/workerRunner.cjs

@@ -42,7 +42,6 @@ function createWorkerRunner(worker, config) {
     status: "idle",
     stepDurationMs: 0
   };
-  let errorMessage = null;
   function send(msg) {
     worker.postMessage(serializeMainMessage(msg));
   }
@@ -59,7 +58,6 @@ function createWorkerRunner(worker, config) {
         emit();
         break;
       case "error":
-        errorMessage = msg.error.message;
         currentSnapshot = { ...currentSnapshot, status: "stopped" };
         emit();
         break;
@@ -67,8 +65,7 @@ function createWorkerRunner(worker, config) {
         break;
     }
   };
-  worker.onerror = (event) => {
-    errorMessage = event.message ?? "Unknown worker error";
+  worker.onerror = () => {
     currentSnapshot = { ...currentSnapshot, status: "stopped" };
     emit();
   };

package/dist/worker/workerRunner.d.cts

@@ -1,6 +1,5 @@
-import { EngineSnapshot } from '../engine.cjs';
+import { State } from '../state.cjs';
 import { WorkerConfig } from './protocol.cjs';
-import '../sim.cjs';
 
 /**
  * Main-thread side of the worker runner.
@@ -14,8 +13,8 @@ type WorkerRunnerConfig<Params> = {
     config: WorkerConfig;
 };
 type WorkerRunner<Data, Params> = {
-    getSnapshot: () => EngineSnapshot<Data, Params>;
-    subscribe: (listener: (snapshot: EngineSnapshot<Data, Params>) => void) => () => void;
+    getSnapshot: () => State<Data, Params>;
+    subscribe: (listener: (snapshot: State<Data, Params>) => void) => () => void;
     play: () => void;
     pause: () => void;
     stop: () => void;

package/dist/worker/workerRunner.d.ts

@@ -1,6 +1,5 @@
-import { EngineSnapshot } from '../engine.js';
+import { State } from '../state.js';
 import { WorkerConfig } from './protocol.js';
-import '../sim.js';
 
 /**
  * Main-thread side of the worker runner.
@@ -14,8 +13,8 @@ type WorkerRunnerConfig<Params> = {
     config: WorkerConfig;
 };
 type WorkerRunner<Data, Params> = {
-    getSnapshot: () => EngineSnapshot<Data, Params>;
-    subscribe: (listener: (snapshot: EngineSnapshot<Data, Params>) => void) => () => void;
+    getSnapshot: () => State<Data, Params>;
+    subscribe: (listener: (snapshot: State<Data, Params>) => void) => () => void;
     play: () => void;
     pause: () => void;
     stop: () => void;

package/dist/worker/workerRunner.js

@@ -16,7 +16,6 @@ function createWorkerRunner(worker, config) {
     status: "idle",
     stepDurationMs: 0
   };
-  let errorMessage = null;
   function send(msg) {
     worker.postMessage(serializeMainMessage(msg));
   }
@@ -33,7 +32,6 @@ function createWorkerRunner(worker, config) {
         emit();
         break;
       case "error":
-        errorMessage = msg.error.message;
         currentSnapshot = { ...currentSnapshot, status: "stopped" };
         emit();
         break;
@@ -41,8 +39,7 @@ function createWorkerRunner(worker, config) {
         break;
     }
   };
-  worker.onerror = (event) => {
-    errorMessage = event.message ?? "Unknown worker error";
+  worker.onerror = () => {
     currentSnapshot = { ...currentSnapshot, status: "stopped" };
     emit();
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automatick",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "State-machine engine for tick-based simulations in React",
   "author": "jckr",
   "license": "MIT",
@@ -29,7 +29,7 @@
     }
   },
   "scripts": {
-    "build": "tsup src/engine.ts src/sim.ts src/worker/workerRunner.ts src/worker/createSimWorker.ts src/worker/protocol.ts src/react/Simulation.tsx src/react/hooks.ts src/react/useSimulationCanvas.ts src/react/PerformanceOverlay.tsx src/react/SimulationContext.tsx src/react/EngineContext.tsx src/react/SimulationControls.tsx src/react/controlPrimitives.tsx src/react/stableCallback.ts --format esm,cjs --dts --clean --external react --external react-dom --external react/jsx-runtime",
+    "build": "tsup src/engine.ts src/sim.ts src/state.ts src/worker/workerRunner.ts src/worker/createSimWorker.ts src/worker/protocol.ts src/react/Simulation.tsx src/react/hooks.ts src/react/useSimulationCanvas.ts src/react/PerformanceOverlay.tsx src/react/SimulationContext.tsx src/react/EngineContext.tsx src/react/SimulationControls.tsx src/react/controlPrimitives.tsx src/react/stableCallback.ts --format esm,cjs --dts --clean --external react --external react-dom --external react/jsx-runtime",
     "test": "vitest run"
   },
   "exports": {