automatick 0.0.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Jerome Cukier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# automatick
+
+State-machine engine for tick-based simulations in React. You write the rules (`init`, `step`, params); automatick handles the loop, timing, status state machine, controls, and (optionally) running the simulation in a Web Worker.
+
+## Install
+
+```bash
+npm install automatick
+```
+
+React is an optional peer dependency — the engine has no React surface.
+
+## Quick start
+
+A simulation has three parts: a **sim module** (pure logic), a `<Simulation>` wrapper, and a render component reading state via `useSimulation()`.
+
+```ts
+// counterSim.ts
+import { defineSim } from 'automatick/sim';
+
+export default defineSim<{ count: number }, { increment: number }>({
+  defaultParams: { increment: 1 },
+  init: () => ({ count: 0 }),
+  step: ({ data, params }) => ({ count: data.count + params.increment }),
+});
+```
+
+```tsx
+// Counter.tsx
+import { Simulation } from 'automatick/react/simulation';
+import { useSimulation } from 'automatick/react/hooks';
+import { StandardControls } from 'automatick/react/controls';
+import counterSim from './counterSim';
+
+function Display() {
+  const { data, tick } = useSimulation<typeof counterSim>();
+  return <p>Tick {tick}: count is {data.count}</p>;
+}
+
+export default function Counter() {
+  return (
+    <Simulation sim={counterSim}>
+      <Display />
+      <StandardControls />
+    </Simulation>
+  );
+}
+```
+
+`StandardControls` gives you play/pause, reset, step, seek, and parameter inputs out of the box. For finer control, individual primitives live at `automatick/react/control-primitives`.
+
+## Web worker
+
+Same sim module, one prop change — the simulation now runs off the main thread:
+
+```tsx
+<Simulation worker={() => import('./counterSim')}>
+  <Display />
+  <StandardControls />
+</Simulation>
+```
+
+Useful when `step` is expensive (large grids, n-body simulations, fluid solvers) and you want the UI to stay responsive.
+
+## API at a glance
+
+`defineSim<Data, Params>({ init, step, shouldStop?, defaultParams })` declares a sim module.
+
+`step` receives `{ data, params, tick }` and returns the next `Data`.
+
+`shouldStop(data, params) => boolean` is an optional terminal predicate; the engine moves to `'stopped'` when it returns true.
+
+`useSimulation<typeof sim>()` returns the current snapshot and actions:
+
+| Field | Type | Description |
+|---|---|---|
+| `data` | `Data` | Current simulation state |
+| `params` | `Params` | Current parameters |
+| `tick` | `number` | Current tick (starts at 0) |
+| `status` | `'idle' \| 'playing' \| 'paused' \| 'stopped'` | Engine status |
+| `play()`, `pause()`, `stop()` | `() => void` | Lifecycle controls |
+| `seek(tick)` | `(n: number) => void` | Jump forward; pauses |
+| `advance(n?)` | `(n?: number) => void` | Step forward by `n` ticks (default 1) |
+| `setParams(patch)` | `(patch: Partial<Params>) => void` | Update params without reinit |
+| `resetWith(patch?)` | `(patch?: Partial<Params>) => void` | Re-run `init` with optional param patch |
+
+## Package entry points
+
+| Subpath | Exports |
+|---|---|
+| `automatick` | `createEngine`, engine + status types |
+| `automatick/sim` | `defineSim`, `SimModule`, `SimData`, `SimParams` |
+| `automatick/worker/runner` | Worker-side runtime |
+| `automatick/worker/create` | Worker host factory |
+| `automatick/worker/protocol` | Message protocol types |
+| `automatick/react/simulation` | `<Simulation>` |
+| `automatick/react/hooks` | `useSimulation()` |
+| `automatick/react/controls` | `<StandardControls>` |
+| `automatick/react/control-primitives` | Individual UI primitives |
+| `automatick/react/canvas` | `useSimulationCanvas()` |
+| `automatick/react/performance` | `<PerformanceOverlay>` |
+| `automatick/react/context` | `<SimulationContext>` |
+
+## License
+
+MIT

package/dist/chunk-66FUVAAG.js

@@ -0,0 +1,7 @@
+// src/react/SimulationContext.tsx
+import React from "react";
+var SimulationContext = React.createContext(null);
+
+export {
+  SimulationContext
+};

package/dist/chunk-AIKB2FNR.js

@@ -0,0 +1,17 @@
+import {
+  SimulationContext
+} from "./chunk-66FUVAAG.js";
+
+// src/react/hooks.ts
+import React from "react";
+function useSimulation() {
+  const ctx = React.useContext(SimulationContext);
+  if (!ctx) {
+    throw new Error("useSimulation must be used within a <Simulation>");
+  }
+  return ctx;
+}
+
+export {
+  useSimulation
+};

package/dist/chunk-HTH6FQ7C.js

@@ -0,0 +1,192 @@
+import {
+  useSimulation
+} from "./chunk-AIKB2FNR.js";
+
+// src/react/controlPrimitives.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var btnStyle = {
+  padding: "6px 12px",
+  borderRadius: 6,
+  border: "1px solid rgba(0,0,0,0.2)",
+  background: "#fff",
+  cursor: "pointer"
+};
+function PlayPauseButton(props) {
+  const { status, play, pause } = useSimulation();
+  const { playingLabel = "Pause", pausedLabel = "Play", disabled } = props;
+  const isPlaying = status === "playing";
+  const canPlay = status === "idle" || status === "paused";
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      style: btnStyle,
+      onClick: isPlaying ? pause : play,
+      disabled: disabled ?? (!canPlay && !isPlaying),
+      children: isPlaying ? playingLabel : pausedLabel
+    }
+  );
+}
+function StopButton(props) {
+  const { status, stop } = useSimulation();
+  const canStop = status === "playing" || status === "paused";
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      style: btnStyle,
+      onClick: stop,
+      disabled: props.disabled ?? !canStop,
+      children: props.label ?? "Stop"
+    }
+  );
+}
+function StepButton(props) {
+  const { status, advance } = useSimulation();
+  const ticks = props.ticks ?? 1;
+  const canStep = status === "idle" || status === "paused";
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      style: btnStyle,
+      onClick: () => advance(ticks),
+      disabled: props.disabled ?? !canStep,
+      title: "Advance one or more ticks while paused",
+      children: props.label ?? `Step${ticks > 1 ? ` (${ticks})` : ""}`
+    }
+  );
+}
+function ResetButton(props) {
+  const { resetWith } = useSimulation();
+  return /* @__PURE__ */ jsx("button", { type: "button", style: btnStyle, onClick: () => resetWith(), children: props.label ?? "Reset" });
+}
+function TickSeekSlider(props) {
+  const { tick, status, seek } = useSimulation();
+  const min = props.min ?? 0;
+  const max = props.max;
+  const disabled = status === "stopped";
+  if (!Number.isFinite(max)) return null;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        display: "flex",
+        gap: 10,
+        alignItems: "center",
+        width: "100%"
+      },
+      children: [
+        /* @__PURE__ */ jsx(
+          "input",
+          {
+            type: "range",
+            min,
+            max,
+            step: 1,
+            value: tick,
+            onChange: (e) => seek(Number(e.target.value)),
+            disabled,
+            style: { flex: 1 }
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            style: {
+              fontFamily: "monospace",
+              opacity: 0.8,
+              minWidth: 48,
+              textAlign: "right"
+            },
+            children: tick
+          }
+        )
+      ]
+    }
+  );
+}
+function ParamRangeField(props) {
+  const { params, setParams } = useSimulation();
+  const label = props.label ?? props.param;
+  const raw = params[props.param];
+  const numericValue = Number(raw);
+  return /* @__PURE__ */ jsxs(
+    "label",
+    {
+      style: {
+        display: "flex",
+        gap: 10,
+        alignItems: "center",
+        width: "100%"
+      },
+      children: [
+        /* @__PURE__ */ jsx("span", { style: { minWidth: 120, opacity: 0.9 }, children: label }),
+        /* @__PURE__ */ jsx(
+          "input",
+          {
+            type: "range",
+            min: props.min,
+            max: props.max,
+            step: props.step ?? 1,
+            value: Number.isFinite(numericValue) ? numericValue : props.min,
+            onChange: (e) => {
+              const v = Number(e.target.value);
+              setParams({ [props.param]: v });
+            },
+            style: { flex: 1 }
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            style: {
+              width: 72,
+              textAlign: "right",
+              fontFamily: "monospace",
+              opacity: 0.8
+            },
+            children: numericValue
+          }
+        )
+      ]
+    }
+  );
+}
+function ParamToggleField(props) {
+  const { params, setParams } = useSimulation();
+  const label = props.label ?? props.param;
+  const checked = Boolean(params[props.param]);
+  return /* @__PURE__ */ jsxs("label", { style: { display: "flex", gap: 10, alignItems: "center" }, children: [
+    /* @__PURE__ */ jsx("span", { style: { minWidth: 120, opacity: 0.9 }, children: label }),
+    /* @__PURE__ */ jsx(
+      "input",
+      {
+        type: "checkbox",
+        checked,
+        onChange: (e) => {
+          setParams({ [props.param]: e.target.checked });
+        }
+      }
+    )
+  ] });
+}
+function TickReadout(props) {
+  const { tick } = useSimulation();
+  return /* @__PURE__ */ jsxs("span", { style: { fontFamily: "monospace", opacity: 0.85 }, children: [
+    props.prefix ?? "",
+    "tick: ",
+    tick
+  ] });
+}
+
+export {
+  PlayPauseButton,
+  StopButton,
+  StepButton,
+  ResetButton,
+  TickSeekSlider,
+  ParamRangeField,
+  ParamToggleField,
+  TickReadout
+};

package/dist/chunk-OA6FGXTP.js

@@ -0,0 +1,9 @@
+// src/react/EngineContext.tsx
+import React from "react";
+var EngineContext = React.createContext(
+  null
+);
+
+export {
+  EngineContext
+};

package/dist/chunk-SK5SHIWY.js

@@ -0,0 +1,13 @@
+// src/react/stableCallback.ts
+import React from "react";
+function useStableCallback(fn) {
+  const fnRef = React.useRef(fn);
+  React.useEffect(() => {
+    fnRef.current = fn;
+  });
+  return React.useCallback((...args) => fnRef.current(...args), []);
+}
+
+export {
+  useStableCallback
+};

package/dist/chunk-YNLOTPDY.js

@@ -0,0 +1,206 @@
+// src/engine.ts
+var PERF_BUFFER_SIZE = 120;
+var SimulationEngine = class {
+  data;
+  params;
+  tick = 0;
+  status = "idle";
+  lastUpdateMs = null;
+  lastStepMs = 0;
+  initFn;
+  stepFn;
+  shouldStopFn;
+  maxTime;
+  delayMs;
+  ticksPerFrame;
+  listeners = /* @__PURE__ */ new Set();
+  historyListeners = /* @__PURE__ */ new Set();
+  perfBuffer = [];
+  constructor(config) {
+    this.initFn = config.init;
+    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.data = this.initFn(this.params);
+  }
+  getSnapshot() {
+    return {
+      data: this.data,
+      params: this.params,
+      tick: this.tick,
+      status: this.status,
+      stepDurationMs: this.lastStepMs
+    };
+  }
+  getStatus() {
+    return this.status;
+  }
+  getPerformance() {
+    return this.perfBuffer;
+  }
+  setDelayMs(ms) {
+    this.delayMs = ms;
+  }
+  setTicksPerFrame(n) {
+    this.ticksPerFrame = n;
+  }
+  recordDrawTime(tick, ms) {
+    for (let i = this.perfBuffer.length - 1; i >= 0; i--) {
+      if (this.perfBuffer[i].tick === tick) {
+        this.perfBuffer[i].drawMs = ms;
+        return;
+      }
+    }
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  subscribeHistory(listener) {
+    this.historyListeners.add(listener);
+    return () => {
+      this.historyListeners.delete(listener);
+    };
+  }
+  play() {
+    if (this.status === "stopped") return;
+    if (this.status === "playing") return;
+    this.status = "playing";
+    this.lastUpdateMs = null;
+    this.emit();
+  }
+  pause() {
+    if (this.status !== "playing") return;
+    this.status = "paused";
+    this.emit();
+  }
+  stop() {
+    if (this.status === "idle" || this.status === "stopped") return;
+    this.status = "stopped";
+    this.emit();
+  }
+  seek(targetTick) {
+    if (this.status === "stopped") return;
+    if (targetTick <= this.tick) {
+      if (this.status !== "paused") {
+        this.status = "paused";
+        this.emit();
+      }
+      return;
+    }
+    this.status = "paused";
+    this.lastUpdateMs = null;
+    this.advanceTicks(targetTick - this.tick);
+    if (this.status === "paused") {
+      this.emit();
+    }
+  }
+  advance(count = 1) {
+    if (this.status === "stopped") return;
+    if (this.status === "playing" || this.status === "idle") {
+      this.status = "paused";
+    }
+    this.lastUpdateMs = null;
+    this.advanceTicks(count);
+    if (this.status === "paused") {
+      this.emit();
+    }
+  }
+  setParams(patch) {
+    this.params = { ...this.params, ...patch };
+    this.emit();
+  }
+  resetWith(patch) {
+    if (patch) {
+      this.params = { ...this.params, ...patch };
+    }
+    this.data = this.initFn(this.params);
+    this.tick = 0;
+    this.status = "idle";
+    this.lastUpdateMs = null;
+    this.lastStepMs = 0;
+    this.perfBuffer.length = 0;
+    this.emit();
+  }
+  handleAnimationFrame(nowMs) {
+    if (this.status !== "playing") return;
+    if (this.lastUpdateMs === null) {
+      this.lastUpdateMs = nowMs;
+      return;
+    }
+    if (this.delayMs > 0 && nowMs - this.lastUpdateMs < this.delayMs) return;
+    this.lastUpdateMs = nowMs;
+    this.advanceTicks(this.ticksPerFrame);
+    if (this.status === "playing") {
+      this.emit();
+    }
+  }
+  destroy() {
+    this.listeners.clear();
+    this.historyListeners.clear();
+  }
+  /**
+   * Run step up to `count` ticks. Returns true if all ticks completed
+   * without termination, false if stopped early.
+   */
+  advanceTicks(count) {
+    for (let i = 0; i < count; i++) {
+      if (this.maxTime !== void 0 && this.tick >= this.maxTime) {
+        this.status = "stopped";
+        this.emit();
+        return false;
+      }
+      this.tick += 1;
+      const t0 = performance.now();
+      this.data = this.stepFn({
+        data: this.data,
+        params: this.params,
+        tick: this.tick
+      });
+      const t1 = performance.now();
+      this.lastStepMs = t1 - t0;
+      if (this.perfBuffer.length >= PERF_BUFFER_SIZE) {
+        this.perfBuffer.shift();
+      }
+      this.perfBuffer.push({ tick: this.tick, stepMs: this.lastStepMs });
+      this.emitHistory();
+      if (this.shouldStopFn?.(this.data, this.params)) {
+        this.status = "stopped";
+        this.emit();
+        return false;
+      }
+      if (this.maxTime !== void 0 && this.tick >= this.maxTime) {
+        this.status = "stopped";
+        this.emit();
+        return false;
+      }
+    }
+    return true;
+  }
+  emit() {
+    const snap = this.getSnapshot();
+    for (const l of this.listeners) {
+      l(snap);
+    }
+  }
+  emitHistory() {
+    if (this.historyListeners.size === 0) return;
+    const entry = { tick: this.tick, data: this.data };
+    for (const l of this.historyListeners) {
+      l(entry);
+    }
+  }
+};
+function createEngine(config) {
+  return new SimulationEngine(config);
+}
+
+export {
+  SimulationEngine,
+  createEngine
+};