@automatajs/core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alex
+
+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 USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,461 @@
+# @automatajs/core
+
+[![npm version](https://img.shields.io/npm/v/@automatajs/core.svg)](https://www.npmjs.com/package/@automatajs/core) [![license](https://img.shields.io/npm/l/@automatajs/core)](LICENSE)
+
+> A focused cellular automata engine for the browser. Inspired by p5.js. Minimal API, instant feedback, decoupled rules and style.
+
+Zero dependencies. Works with any canvas-based environment.
+
+## Installation
+
+```sh
+npm install @automatajs/core
+```
+
+Or with your preferred package manager:
+
+```sh
+pnpm add @automatajs/core
+yarn add @automatajs/core
+```
+
+## Quick Start
+
+```typescript
+import { Automata, gameOfLife } from "@automatajs/core";
+
+const canvas = document.querySelector("canvas");
+const ca = new Automata(canvas, {
+  cols: 80,
+  rows: 60,
+  fps: 10,
+  rule: gameOfLife,
+});
+
+ca.randomize(0.3);
+ca.play();
+```
+
+## Writing Rules
+
+The rule function runs once per cell per generation and decides the next state.
+It receives a [`CellContext`](#cellcontext) and returns `0` (dead) or any positive integer (alive).
+
+```typescript
+import { Automata } from "@automatajs/core";
+
+// Game of Life rule
+function rule(ctx) {
+  if (ctx.self === 1) {
+    return ctx.neighborCount === 2 || ctx.neighborCount === 3 ? 1 : 0;
+  }
+  return ctx.neighborCount === 3 ? 1 : 0;
+}
+
+const ca = new Automata(canvas, { rule });
+```
+
+### CellContext
+
+Every rule (and style) function receives a `CellContext` object:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `self` | `number` | Current cell state (`0` = dead, `1+` = alive) |
+| `neighborCount` | `number` | Count of alive neighbors |
+| `neighbors` | `number[]` | Individual neighbor states (Moore: 8, Von Neumann: 4) |
+| `x` | `number` | Column coordinate |
+| `y` | `number` | Row coordinate |
+| `get(x, y)` | `number` | Read any cell on the grid |
+| `cols` | `number` | Grid width |
+| `rows` | `number` | Grid height |
+
+### `createRule(birth, survive)`
+
+Create a custom birth/survival rule from standard notation.
+
+```typescript
+import { createRule } from "@automatajs/core";
+
+// B3/S23 — Game of Life
+const gol = createRule([3], [2, 3]);
+
+// B36/S23 — HighLife
+const highLife = createRule([3, 6], [2, 3]);
+```
+
+## Styling Cells
+
+A `StyleFunction` controls the color of every individual cell. It can return:
+
+- `[r, g, b, a]` — RGBA tuple (0–255 each)
+- `"#rrggbb"` — CSS color string
+- `true` — use the default alive color
+- `false` — transparent / dead
+
+```typescript
+const ca = new Automata(canvas, {
+  rule: gameOfLife,
+  style: (state, ctx) => {
+    if (state === 0) return false;
+    // Neighbor heatmap: cool → warm
+    const t = ctx.neighborCount / 8;
+    return [Math.floor(255 * t), 80, 255 - Math.floor(255 * t), 255];
+  },
+});
+
+// Set dynamically
+ca.setStyle((state) => (state === 0 ? false : "#f472b6"));
+
+// Reset to default
+ca.setStyle(null);
+```
+
+## API Reference
+
+*Auto-generated from `src/engine.ts`.*
+
+### Constructor
+
+```typescript
+new Automata(canvas: HTMLCanvasElement, options?: AutomataOptions)
+```
+
+Creates a new `Automata` instance bound to a canvas element.
+The canvas auto-resizes to fill its parent container.
+Cell size is computed automatically from grid dimensions and available space.
+
+See [`AutomataOptions`](#automataoptionss) for all configuration options.
+
+### Grid Management
+
+**`getGrid(): Grid`**
+
+Get the underlying grid.
+
+---
+
+**`createGrid(cols: number, rows: number): void`**
+
+Create a new grid, replacing the current one.
+
+---
+
+**`clearGrid(): void`**
+
+Clear the grid.
+
+---
+
+**`randomize(density: number = 0.3): void`**
+
+Randomize the grid.
+
+---
+
+**`getCell(x: number, y: number): number`**
+
+Get cell state.
+
+---
+
+**`setCell(x: number, y: number, state: number): void`**
+
+Set cell state.
+
+---
+
+**`toggleCell(x: number, y: number): void`**
+
+Toggle cell state.
+
+---
+
+**`stamp(pattern: number[][], offsetX?: number, offsetY?: number): void`**
+
+Stamp a pattern onto the grid.
+
+### Simulation
+
+**`setRule(rule: RuleFunction): void`**
+
+Set the rule function.
+
+---
+
+**`setStyle(style: StyleFunction | null): void`**
+
+Set the style function for per-cell coloring. Pass null to reset to default.
+
+---
+
+**`step(): void`**
+
+Advance one generation.
+
+---
+
+**`play(): void`**
+
+Start the simulation loop.
+
+---
+
+**`pause(): void`**
+
+Pause the simulation.
+
+---
+
+**`reset(): void`**
+
+Reset to initial state (from last randomize or manual setup).
+
+---
+
+**`saveState(): void`**
+
+Save the current grid state as the initial state.
+
+---
+
+**`get playing(): boolean`**
+
+Is the simulation running?
+
+---
+
+**`get generation(): number`**
+
+Current generation count.
+
+---
+
+**`get fps(): number`**
+
+Get the current FPS setting.
+
+---
+
+**`setFrameRate(fps: number): void`**
+
+Set the target frames per second.
+
+---
+
+**`get population(): number`**
+
+Population count.
+
+---
+
+**`get cols(): number`**
+
+Grid dimensions.
+
+---
+
+**`onStep(fn: (gen: number) => void): void`**
+
+Register a callback after each step.
+
+### Rendering
+
+**`render(): void`**
+
+Force a re-render.
+
+---
+
+**`resize(): void`**
+
+Resize the canvas to fit its container.
+
+---
+
+**`setAliveColor(color: string): void`**
+
+Set alive cell color.
+
+---
+
+**`setDeadColor(color: string): void`**
+
+Set dead cell color.
+
+---
+
+**`setBackground(color: string): void`**
+
+Set background color.
+
+---
+
+**`toggleGridLines(show?: boolean): void`**
+
+Toggle grid lines on/off.
+
+---
+
+**`toDataURL(format?: "png" | "jpeg"): string`**
+
+Export canvas as data URL.
+
+### Interaction
+
+**`onCellClick(fn: CellCallback): void`**
+
+Set custom cell click handler.
+
+---
+
+**`onCellDrag(fn: CellCallback): void`**
+
+Set custom cell drag handler.
+
+---
+
+**`enableInteraction(): void`**
+
+Enable mouse/touch interaction.
+
+---
+
+**`disableInteraction(): void`**
+
+Disable mouse/touch interaction.
+
+### Lifecycle
+
+**`destroy(): void`**
+
+Clean up all resources.
+
+## Types
+
+*Auto-generated from `src/types.ts`.*
+
+### `GridOptions`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `wrap?` | `boolean` | true | Enable toroidal wrapping |
+| `neighborhood?` | `NeighborhoodType` | "moore" | Neighborhood type |
+
+### `CellContext`
+
+Context object passed to each cell during a rule evaluation. Provides easy access to the cell's own state, its neighbors, and the ability to read any cell on the grid.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `self` | `number` | — | Current state of this cell (0 = dead, 1+ = alive / multi-state) |
+| `x` | `number` | — | Column coordinate |
+| `y` | `number` | — | Row coordinate |
+| `neighborCount` | `number` | — | Number of alive neighbors (count of neighbors with state > 0) |
+| `neighbors` | `number[]` | — | Array of individual neighbor state values (Moore: 8, Von Neumann: 4) |
+| `cols` | `number` | — | Grid width |
+| `rows` | `number` | — | Grid height |
+
+### `AutomataOptions *(extends `GridOptions`)*`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `cols?` | `number` | — | Number of columns |
+| `rows?` | `number` | — | Number of rows |
+| `fps?` | `number` | 10 | Frames per second |
+| `aliveColor?` | `string` | "#22d3ee" | Color for alive cells |
+| `deadColor?` | `string` | "#0f172a" | Color for dead cells |
+| `backgroundColor?` | `string` | "#020617" | Background color |
+| `showGridLines?` | `boolean` | true | Show grid lines |
+| `gridLineColor?` | `string` | "#1e293b" | Grid line color |
+| `cellSize?` | `number` | — | Cell size in pixels (auto-calculated if omitted) |
+| `rule?` | `RuleFunction` | — | Rule function — determines next state for each cell |
+| `style?` | `StyleFunction` | — | Style function — determines visual appearance per cell (optional) |
+
+### `ExportOptions`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `scale?` | `number` | — |  |
+| `format?` | `"png" | "jpeg"` | — |  |
+
+### `NeighborhoodType`
+
+```typescript
+type NeighborhoodType = "moore" | "vonneumann"
+```
+
+### `RGBA`
+
+RGBA color tuple: [red, green, blue, alpha], each 0–255.
+
+```typescript
+type RGBA = [number, number, number, number]
+```
+
+### `StyleFunction`
+
+Style function signature. Determines the visual appearance of a cell based on its state and context. Return an RGBA color tuple, a CSS color string, or a boolean (true = alive color).
+
+Parameters:
+- `state` — Current state of the cell
+- `ctx` — Cell context with position and grid access
+
+```typescript
+type StyleFunction = (
+  state: number,
+  ctx: CellContext
+) => RGBA | string | boolean
+```
+
+### `CellCallback`
+
+```typescript
+type CellCallback = (x: number, y: number, state: number) => void
+```
+
+## Presets
+
+Built-in rules ready to use. Import directly or via the `presets` registry.
+
+*Auto-generated from `src/presets.ts`.*
+
+```typescript
+import { gameOfLife, highLife, seeds, presets } from "@automatajs/core";
+
+ca.setRule(gameOfLife);
+
+// Access by name via registry
+ca.setRule(presets["dayAndNight"]);
+```
+
+| Export | Description |
+|--------|-------------|
+| `gameOfLife` | Conway's Game of Life (B3/S23) - A dead cell with exactly 3 neighbors becomes alive. - A live cell with 2 or 3 neighbors survives. - All other cells die or stay dead. |
+| `highLife` | HighLife (B36/S23) Like Game of Life but also births at 6 neighbors. Famous for replicators. |
+| `seeds` | Seeds (B2/S) Dead cells with exactly 2 neighbors come alive; all live cells die. Creates explosive growth patterns. |
+| `dayAndNight` | Day & Night (B3678/S34678) Symmetric rule — patterns behave the same inverted. |
+| `diamoeba` | Diamoeba (B35678/S5678) Creates large diamond-shaped regions. |
+
+## Patterns
+
+Famous patterns as 2D arrays for stamping onto the grid.
+
+*Auto-generated from `src/presets.ts`.*
+
+```typescript
+import { Automata, gameOfLife, patterns } from "@automatajs/core";
+
+const ca = new Automata(canvas, { cols: 80, rows: 60, rule: gameOfLife });
+
+ca.stamp(patterns.glider, 10, 10);
+ca.stamp(patterns.gosperGliderGun, 2, 2);
+ca.play();
+```
+
+| Pattern | Size | Description |
+|---------|------|-------------|
+
+## License
+
+MIT

package/dist/engine.d.ts

@@ -0,0 +1,103 @@
+import { Grid } from "./grid";
+import type { AutomataOptions, RuleFunction, StyleFunction, CellCallback } from "./types";
+/**
+ * Main Automata engine class.
+ * Orchestrates grid, renderer, simulation loop, and interaction.
+ *
+ * Usage:
+ * ```ts
+ * const ca = new Automata(canvasElement, {
+ *   cols: 80,
+ *   rows: 60,
+ *   fps: 10,
+ *   rule: gameOfLife,
+ * });
+ * ca.randomize(0.3);
+ * ca.play();
+ * ```
+ */
+export declare class Automata {
+    private grid;
+    private initialGrid;
+    private renderer;
+    private interaction;
+    private rule;
+    private _fps;
+    private _generation;
+    private _playing;
+    private animFrameId;
+    private lastFrameTime;
+    private onStepCallbacks;
+    constructor(canvas: HTMLCanvasElement, options?: AutomataOptions);
+    /** Get the underlying grid. */
+    getGrid(): Grid;
+    /** Create a new grid, replacing the current one. */
+    createGrid(cols: number, rows: number): void;
+    /** Clear the grid. */
+    clearGrid(): void;
+    /** Randomize the grid. */
+    randomize(density?: number): void;
+    /** Get cell state. */
+    getCell(x: number, y: number): number;
+    /** Set cell state. */
+    setCell(x: number, y: number, state: number): void;
+    /** Toggle cell state. */
+    toggleCell(x: number, y: number): void;
+    /** Stamp a pattern onto the grid. */
+    stamp(pattern: number[][], offsetX?: number, offsetY?: number): void;
+    /** Set the rule function. */
+    setRule(rule: RuleFunction): void;
+    /** Set the style function for per-cell coloring. Pass null to reset to default. */
+    setStyle(style: StyleFunction | null): void;
+    /** Advance one generation. */
+    step(): void;
+    /** Start the simulation loop. */
+    play(): void;
+    /** Pause the simulation. */
+    pause(): void;
+    /** Reset to initial state (from last randomize or manual setup). */
+    reset(): void;
+    /** Save the current grid state as the initial state. */
+    saveState(): void;
+    /** Is the simulation running? */
+    get playing(): boolean;
+    /** Current generation count. */
+    get generation(): number;
+    /** Get the current FPS setting. */
+    get fps(): number;
+    /** Set the target frames per second. */
+    setFrameRate(fps: number): void;
+    /** Population count. */
+    get population(): number;
+    /** Grid dimensions. */
+    get cols(): number;
+    get rows(): number;
+    /** Register a callback after each step. */
+    onStep(fn: (gen: number) => void): void;
+    /** Force a re-render. */
+    render(): void;
+    /** Resize the canvas to fit its container. */
+    resize(): void;
+    /** Set alive cell color. */
+    setAliveColor(color: string): void;
+    /** Set dead cell color. */
+    setDeadColor(color: string): void;
+    /** Set background color. */
+    setBackground(color: string): void;
+    /** Toggle grid lines on/off. */
+    toggleGridLines(show?: boolean): void;
+    /** Export canvas as data URL. */
+    toDataURL(format?: "png" | "jpeg"): string;
+    /** Set custom cell click handler. */
+    onCellClick(fn: CellCallback): void;
+    /** Set custom cell drag handler. */
+    onCellDrag(fn: CellCallback): void;
+    /** Enable mouse/touch interaction. */
+    enableInteraction(): void;
+    /** Disable mouse/touch interaction. */
+    disableInteraction(): void;
+    /** Clean up all resources. */
+    destroy(): void;
+    private loop;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}