automatick 0.0.1 → 0.0.3

package/dist/react/Simulation.js

@@ -1,9 +1,16 @@
 import {
   useStableCallback
 } from "../chunk-SK5SHIWY.js";
+import {
+  createSimWorker
+} from "../chunk-VPS3ZXWI.js";
+import {
+  createWorkerRunner
+} from "../chunk-LMHH7YPE.js";
 import {
   createEngine
-} from "../chunk-YNLOTPDY.js";
+} from "../chunk-A375T3UD.js";
+import "../chunk-IKR53C2U.js";
 import {
   EngineContext
 } from "../chunk-OA6FGXTP.js";
@@ -15,18 +22,35 @@ import {
 import React from "react";
 import { jsx } from "react/jsx-runtime";
 function LocalSimulation(props) {
-  const { sim, params: paramsProp, children, autoplay } = props;
+  const {
+    init,
+    step,
+    shouldStop,
+    defaultParams,
+    params: paramsProp,
+    children,
+    autoplay
+  } = props;
   const engineRef = React.useRef(null);
   if (!engineRef.current) {
-    const initialParams = paramsProp ? { ...sim.defaultParams, ...paramsProp } : sim.defaultParams;
+    let initialParams;
+    if (defaultParams && paramsProp) {
+      initialParams = { ...defaultParams, ...paramsProp };
+    } else if (defaultParams) {
+      initialParams = defaultParams;
+    } else if (paramsProp) {
+      initialParams = paramsProp;
+    }
     engineRef.current = createEngine({
-      init: sim.init,
-      step: sim.step,
-      shouldStop: sim.shouldStop,
+      init,
+      step,
+      shouldStop,
       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;
@@ -62,116 +86,70 @@ function LocalSimulation(props) {
   }, [engine]);
   return /* @__PURE__ */ jsx(SimulationProvider, { snapshot, backend: engine, children });
 }
+function engineUrl() {
+  return new URL("../standalone/engine.js", import.meta.url).href;
+}
 function WorkerSimulation(props) {
   const { children, autoplay } = props;
-  const [backend, setBackend] = React.useState(
+  const [runner, setRunner] = 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(() => {
-    let cancelled = false;
-    let runner = null;
-    (async () => {
-      const mod = await propsRef.current.worker();
-      const simModule = mod.default;
-      if (cancelled) return;
-      const p = propsRef.current;
-      const initialParams = p.params ? { ...simModule.defaultParams, ...p.params } : simModule.defaultParams;
-      const engine = createEngine({
-        init: simModule.init,
-        step: simModule.step,
-        shouldStop: simModule.shouldStop,
-        initialParams,
-        maxTime: p.maxTime
-      });
-      if (cancelled) {
-        engine.destroy();
-        return;
-      }
-      const delayMs = p.delayMs ?? 0;
-      const ticksPerFrame = p.ticksPerFrame ?? 1;
-      let loopTimer = null;
-      function stopLoop() {
-        if (loopTimer !== null) {
-          clearTimeout(loopTimer);
-          loopTimer = null;
-        }
-      }
-      function tickLoop() {
-        if (engine.getStatus() !== "playing") return;
-        for (let i = 0; i < ticksPerFrame; i++) {
-          engine.advance(1);
-          const s = engine.getStatus();
-          if (s === "stopped") return;
-          if (s !== "paused") break;
-        }
-        if (engine.getStatus() === "paused") {
-          engine.play();
-        }
-        loopTimer = setTimeout(tickLoop, delayMs);
+    const moduleUrl = props.worker.toString();
+    const initialParams = props.params ?? {};
+    const worker = createSimWorker({
+      moduleUrl,
+      engineUrl: engineUrl(),
+      initialParams,
+      config: {
+        maxTime: props.maxTime,
+        delayMs: props.delayMs,
+        ticksPerFrame: props.ticksPerFrame,
+        snapshotIntervalMs: props.snapshotIntervalMs
       }
-      runner = {
-        getSnapshot: () => engine.getSnapshot(),
-        subscribe: (listener) => engine.subscribe(listener),
-        play: () => {
-          engine.play();
-          stopLoop();
-          loopTimer = setTimeout(tickLoop, 0);
-        },
-        pause: () => {
-          stopLoop();
-          engine.pause();
-        },
-        stop: () => {
-          stopLoop();
-          engine.stop();
-        },
-        seek: (tick) => {
-          stopLoop();
-          engine.seek(tick);
-        },
-        advance: (count) => engine.advance(count),
-        setParams: (patch) => engine.setParams(patch),
-        resetWith: (patch) => {
-          stopLoop();
-          engine.resetWith(patch);
-        },
-        destroy: () => {
-          stopLoop();
-          engine.destroy();
-        },
-        recordDrawTime: (tick, ms) => engine.recordDrawTime(tick, ms),
-        getPerformance: () => engine.getPerformance()
-      };
-      if (!cancelled) {
-        setBackend(runner);
-        setSnapshot(engine.getSnapshot());
+    });
+    const r = createWorkerRunner(worker, {
+      initialParams,
+      config: {
+        maxTime: props.maxTime,
+        delayMs: props.delayMs,
+        ticksPerFrame: props.ticksPerFrame,
+        snapshotIntervalMs: props.snapshotIntervalMs
       }
-    })();
+    });
+    const unsub = r.subscribe((next) => setSnapshot(next));
+    setRunner(r);
     return () => {
-      cancelled = true;
-      runner?.destroy();
+      unsub();
+      r.destroy();
     };
   }, []);
   React.useEffect(() => {
-    if (!backend) return;
-    return backend.subscribe((next) => setSnapshot(next));
-  }, [backend]);
-  React.useEffect(() => {
-    if (autoplay && backend) backend.play();
-  }, [backend, autoplay]);
+    if (autoplay && runner) runner.play();
+  }, [runner, autoplay]);
   const isFirstRender = React.useRef(true);
   React.useEffect(() => {
     if (isFirstRender.current) {
       isFirstRender.current = false;
       return;
     }
-    if (props.params && backend) backend.setParams(props.params);
-  }, [backend, props.params]);
-  if (!snapshot || !backend) return null;
-  return /* @__PURE__ */ jsx(SimulationProvider, { snapshot, backend, children });
+    if (props.params && runner) runner.setParams(props.params);
+  }, [runner, props.params]);
+  React.useEffect(() => {
+    if (!runner) return;
+    if (props.delayMs === void 0 && props.ticksPerFrame === void 0 && props.snapshotIntervalMs === void 0)
+      return;
+    runner.setConfig({
+      delayMs: props.delayMs,
+      ticksPerFrame: props.ticksPerFrame,
+      snapshotIntervalMs: props.snapshotIntervalMs
+    });
+  }, [runner, props.delayMs, props.ticksPerFrame, props.snapshotIntervalMs]);
+  if (!snapshot || !runner || snapshot.data === void 0) return null;
+  return /* @__PURE__ */ jsx(SimulationProvider, { snapshot, backend: runner, children });
 }
 function SimulationProvider({
   snapshot,
@@ -207,6 +185,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
       ),
@@ -228,6 +208,19 @@ function Simulation(props) {
   if ("worker" in props && props.worker != null) {
     return /* @__PURE__ */ jsx(WorkerSimulation, { ...props });
   }
+  if ("sim" in props && props.sim != null) {
+    const { sim, ...rest } = props;
+    return /* @__PURE__ */ jsx(
+      LocalSimulation,
+      {
+        ...rest,
+        init: sim.init,
+        step: sim.step,
+        shouldStop: sim.shouldStop,
+        defaultParams: sim.defaultParams
+      }
+    );
+  }
   return /* @__PURE__ */ jsx(LocalSimulation, { ...props });
 }
 export {

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,19 +1,39 @@
-/** 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;
+type SimModule<Data, Params = Record<string, never>> = {
+    /**
+     * 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. */
-    defaultParams: Params;
+    /**
+     * Default parameter values. Optional — sims without tweakable params can
+     * omit this. When omitted, `Params` defaults to `Record<string, never>` and
+     * the engine seeds an empty params object.
+     */
+    defaultParams?: Params;
 };
 /**
  * Define a simulation module with full type inference.
@@ -31,10 +51,10 @@ type SimModule<Data, Params> = {
  * });
  * ```
  */
-declare function defineSim<Data, Params>(sim: SimModule<Data, Params>): SimModule<Data, Params>;
+declare function defineSim<Data, Params = Record<string, never>>(sim: SimModule<Data, Params>): SimModule<Data, Params>;
 /** Extract the Data type from a SimModule. */
 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,19 +1,39 @@
-/** 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;
+type SimModule<Data, Params = Record<string, never>> = {
+    /**
+     * 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. */
-    defaultParams: Params;
+    /**
+     * Default parameter values. Optional — sims without tweakable params can
+     * omit this. When omitted, `Params` defaults to `Record<string, never>` and
+     * the engine seeds an empty params object.
+     */
+    defaultParams?: Params;
 };
 /**
  * Define a simulation module with full type inference.
@@ -31,10 +51,10 @@ type SimModule<Data, Params> = {
  * });
  * ```
  */
-declare function defineSim<Data, Params>(sim: SimModule<Data, Params>): SimModule<Data, Params>;
+declare function defineSim<Data, Params = Record<string, never>>(sim: SimModule<Data, Params>): SimModule<Data, Params>;
 /** Extract the Data type from a SimModule. */
 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
 };