@wonderyard/vivarium 0.1.8 → 1.0.0

package/dist/blueprint/helpers.d.ts

@@ -1,9 +1,36 @@
 import { Neighborhood } from '../automaton/types';
+/**
+ * Helper functions for constructing count arrays used in conditions.
+ * Accessed via `vi.helpers`.
+ */
 export declare class Helpers {
     private neighborhoodName?;
     constructor(neighborhoodName?: Neighborhood | undefined);
+    /**
+     * Returns every valid count value except the ones specified.
+     *
+     * @param value - A number or array of numbers to exclude.
+     * @returns An array of all valid count values minus the excluded ones.
+     */
     not(value: number | number[]): number[];
+    /**
+     * Generates a range of whole numbers from `min` to `max` (inclusive).
+     *
+     * @param min - The start of the range (must be ≥ 0).
+     * @param max - The end of the range (must be ≤ 8 and greater than `min`). For cross neighborhoods, should not exceed 4.
+     * @returns An array of numbers from `min` to `max`.
+     */
     between(min: number, max: number): number[];
+    /**
+     * Returns all even count values (zero included) for the current neighborhood type.
+     *
+     * @returns `[0, 2, 4, 6, 8]` for square, `[0, 2, 4]` for cross.
+     */
     even(): number[];
+    /**
+     * Returns all odd count values for the current neighborhood type.
+     *
+     * @returns `[1, 3, 5, 7]` for square, `[1, 3]` for cross.
+     */
     odd(): number[];
 }

package/dist/blueprint/helpers.js

@@ -2,12 +2,25 @@ class s {
   constructor(r) {
     this.neighborhoodName = r;
   }
+  /**
+   * Returns every valid count value except the ones specified.
+   *
+   * @param value - A number or array of numbers to exclude.
+   * @returns An array of all valid count values minus the excluded ones.
+   */
   not(r) {
     const e = this.neighborhoodName === "cross" ? /* @__PURE__ */ new Set([0, 1, 2, 3, 4]) : /* @__PURE__ */ new Set([0, 1, 2, 3, 4, 5, 6, 7, 8]);
     return typeof r == "number" ? e.delete(r) : Array.isArray(r) && r.forEach((o) => {
       e.delete(o);
     }), Array.from(e);
   }
+  /**
+   * Generates a range of whole numbers from `min` to `max` (inclusive).
+   *
+   * @param min - The start of the range (must be ≥ 0).
+   * @param max - The end of the range (must be ≤ 8 and greater than `min`). For cross neighborhoods, should not exceed 4.
+   * @returns An array of numbers from `min` to `max`.
+   */
   between(r, e) {
     if (r < 0)
       throw new Error("min cannot be less than 0");
@@ -20,9 +33,19 @@ class s {
       o.push(n);
     return o;
   }
+  /**
+   * Returns all even count values (zero included) for the current neighborhood type.
+   *
+   * @returns `[0, 2, 4, 6, 8]` for square, `[0, 2, 4]` for cross.
+   */
   even() {
     return this.neighborhoodName === "cross" ? [0, 2, 4] : [0, 2, 4, 6, 8];
   }
+  /**
+   * Returns all odd count values for the current neighborhood type.
+   *
+   * @returns `[1, 3, 5, 7]` for square, `[1, 3]` for cross.
+   */
   odd() {
     return this.neighborhoodName === "cross" ? [1, 3] : [1, 3, 5, 7];
   }

package/dist/blueprint/ref-blueprint.d.ts

@@ -2,20 +2,37 @@ import { Automaton, Element, Kind, RefType } from '../automaton/types';
 import { BaseBlueprint } from './base-blueprint';
 import { RuleBlueprint } from './rule-blueprint';
 import { AnyNeighbor, BlueprintContext } from './types';
+/**
+ * Base class for element and kind blueprints. Provides the {@link RefBlueprint.to | to} method for defining rules.
+ */
 export declare abstract class RefBlueprint extends BaseBlueprint {
     protected automaton: Automaton;
     id: string;
     name: string;
     type: RefType;
     constructor(automaton: Automaton, ref: Element | Kind);
+    /**
+     * Creates a new rule that transitions cells of this element (or kind) to another element or neighbor reference.
+     *
+     * @param elementBlueprintOrNeighbor - The target element, or a neighbor position reference (e.g. `vi.neighbor.TOP`).
+     * @returns A {@link RuleBlueprint} for chaining conditions.
+     */
     to(elementBlueprintOrNeighbor: ElementBlueprint | AnyNeighbor): RuleBlueprint;
 }
+/**
+ * Blueprint for an element. Returned by {@link VivariumBlueprint.element | vivarium().element()}.
+ * Use {@link RefBlueprint.to | to()} to define rules on this element.
+ */
 export declare class ElementBlueprint extends RefBlueprint {
     protected context: BlueprintContext;
     type: "element";
     id: string;
     constructor(context: BlueprintContext, automaton: Automaton, element: Element);
 }
+/**
+ * Blueprint for a kind. Returned by {@link VivariumBlueprint.kind | vivarium().kind()}.
+ * Use {@link RefBlueprint.to | to()} to define shared rules for all elements extending this kind.
+ */
 export declare class KindBlueprint extends RefBlueprint {
     protected context: BlueprintContext;
     type: "kind";

package/dist/blueprint/ref-blueprint.js

@@ -1,5 +1,5 @@
 import { BaseBlueprint as r } from "./base-blueprint.js";
-import { R as n } from "../rule-blueprint--dHAjnu3.js";
+import { R as n } from "../rule-blueprint-DGODv9IV.js";
 import { toRefIdOrPoint as p } from "./utils.js";
 import { A as u } from "../constants-D4GX9YB2.js";
 class o extends r {
@@ -9,6 +9,12 @@ class o extends r {
   id;
   name;
   type;
+  /**
+   * Creates a new rule that transitions cells of this element (or kind) to another element or neighbor reference.
+   *
+   * @param elementBlueprintOrNeighbor - The target element, or a neighbor position reference (e.g. `vi.neighbor.TOP`).
+   * @returns A {@link RuleBlueprint} for chaining conditions.
+   */
   to(e) {
     this.assertNotCreated();
     const t = {

package/dist/blueprint/rule-blueprint.d.ts

@@ -2,17 +2,55 @@ import { Automaton, Rule, Strategy } from '../automaton/types';
 import { BaseBlueprint } from './base-blueprint';
 import { RefBlueprint } from './ref-blueprint';
 import { AnyNeighbor, BlueprintContext } from './types';
+/**
+ * Blueprint for a rule. Provides methods to add conditions. Returned by {@link RefBlueprint.to | element.to()} or {@link RefBlueprint.to | kind.to()}.
+ */
 export declare class RuleBlueprint extends BaseBlueprint {
     protected context: BlueprintContext;
     protected automaton: Automaton;
     protected rule: Rule;
     constructor(context: BlueprintContext, automaton: Automaton, rule: Rule);
     private condition;
+    /**
+     * Adds a count condition to the rule. The rule passes only if the number of matching neighbors
+     * equals one of the specified count values.
+     *
+     * @param refBlueprintOrNeighbor - The element, kind, or neighbor reference to count.
+     * @param count - The accepted count values. Can be individual numbers or arrays. When omitted, matches any count from 1 to the neighborhood size.
+     * @returns A {@link RuleBlueprintWithAccept} for chaining more conditions or setting an accept strategy.
+     */
     count(refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor, ...count: (number | number[])[]): RuleBlueprintWithAccept;
+    /**
+     * Adds an `is` condition to the rule. Checks whether a specific neighbor position matches a given element, kind, or another neighbor position.
+     *
+     * @param neighbor - The neighbor position to inspect (e.g. `vi.neighbor.TOP`).
+     * @param refBlueprintOrNeighbor - The element, kind, or neighbor position to compare against.
+     * @returns A {@link RuleBlueprintWithAccept} for chaining more conditions or setting an accept strategy.
+     */
     is(neighbor: AnyNeighbor, refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor): RuleBlueprintWithAccept;
+    /**
+     * Adds a chance condition to the rule. The rule passes with a probability of `part / whole`.
+     *
+     * @param part - The numerator of the probability fraction.
+     * @param whole - The denominator of the probability fraction. Defaults to `100`.
+     * @returns A {@link RuleBlueprintWithAccept} for chaining more conditions or setting an accept strategy.
+     */
     chance(part: number, whole?: number): RuleBlueprintWithAccept;
 }
-declare class RuleBlueprintWithAccept extends RuleBlueprint {
+/**
+ * Extended rule blueprint that additionally exposes the {@link RuleBlueprintWithAccept.accept | accept} method
+ * for choosing how multiple conditions are evaluated.
+ */
+export declare class RuleBlueprintWithAccept extends RuleBlueprint {
+    /**
+     * Sets the acceptance strategy for multiple conditions on this rule.
+     *
+     * - `"all"` (default) — every condition must pass.
+     * - `"any"` — at least one condition must pass.
+     * - `"one"` — exactly one condition must pass.
+     * - `"none"` — no condition must pass (negation).
+     *
+     * @param strategy - The acceptance strategy.
+     */
     accept(strategy: Strategy): void;
 }
-export {};

package/dist/blueprint/rule-blueprint.js

@@ -1,7 +1,8 @@
-import { R as m } from "../rule-blueprint--dHAjnu3.js";
+import { R as o, a as l } from "../rule-blueprint-DGODv9IV.js";
 import "./base-blueprint.js";
 import "./utils.js";
 import "../constants-D4GX9YB2.js";
 export {
-  m as RuleBlueprint
+  o as RuleBlueprint,
+  l as RuleBlueprintWithAccept
 };

package/dist/blueprint/vivarium-blueprint.d.ts

@@ -3,16 +3,52 @@ import { BaseBlueprint } from './base-blueprint';
 import { Helpers } from './helpers';
 import { ElementBlueprint, KindBlueprint } from './ref-blueprint';
 import { Cross, Square } from '../common/constants';
+/**
+ * The main builder for defining a vivarium. Use it to create elements, kinds, and rules,
+ * then call {@link VivariumBlueprint.create | create} to produce an {@link Automaton} that can be passed to {@link setup}.
+ */
 export declare class VivariumBlueprint<N extends Neighborhood = "square"> extends BaseBlueprint {
     private neighborhoodName?;
     protected automaton: Automaton;
     protected context: {
         created: boolean;
     };
+    /**
+     * Named constants for referring to specific positions in the neighborhood.
+     * Available positions depend on the neighborhood type.
+     *
+     * For `"square"`: `TOP_LEFT`, `TOP`, `TOP_RIGHT`, `LEFT`, `SELF`, `RIGHT`, `BOTTOM_LEFT`, `BOTTOM`, `BOTTOM_RIGHT`.
+     *
+     * For `"cross"`: `TOP`, `LEFT`, `SELF`, `RIGHT`, `BOTTOM`.
+     */
     neighbor: N extends "cross" ? typeof Cross : typeof Square;
+    /**
+     * Helper functions for constructing count arrays used in conditions.
+     * Includes {@link Helpers.not | not}, {@link Helpers.between | between}, {@link Helpers.even | even}, and {@link Helpers.odd | odd}.
+     */
     helpers: Helpers;
     constructor(neighborhoodName?: N | undefined);
+    /**
+     * Defines a new element in the vivarium.
+     *
+     * @param name - A unique name identifying this element.
+     * @param color - A unique color used to draw this element. Accepts CSS named colors or hex values (e.g. `"green"`, `"#FF7A45"`).
+     * @param extensions - An optional array of kinds this element extends.
+     * @returns An {@link ElementBlueprint} that can be used to define rules.
+     */
     element(name: string, color: Color, extensions?: KindBlueprint[]): ElementBlueprint;
+    /**
+     * Defines a new kind in the vivarium. A kind groups elements that share common behavior.
+     *
+     * @param name - A unique name identifying this kind.
+     * @returns A {@link KindBlueprint} that can be used to define shared rules.
+     */
     kind(name: string): KindBlueprint;
+    /**
+     * Finalizes the vivarium and produces an {@link Automaton} object. After calling this method,
+     * no further elements, kinds, or rules can be added.
+     *
+     * @returns The compiled {@link Automaton} to pass to {@link setup}.
+     */
     create(): Automaton;
 }

package/dist/blueprint/vivarium-blueprint.js

@@ -1,4 +1,4 @@
-import { n as o } from "../rule-blueprint--dHAjnu3.js";
+import { n as o } from "../rule-blueprint-DGODv9IV.js";
 import { BaseBlueprint as n } from "./base-blueprint.js";
 import { Helpers as a } from "./helpers.js";
 import { ElementBlueprint as h, KindBlueprint as m } from "./ref-blueprint.js";
@@ -14,8 +14,28 @@ class C extends n {
   }
   automaton;
   context = { created: !1 };
+  /**
+   * Named constants for referring to specific positions in the neighborhood.
+   * Available positions depend on the neighborhood type.
+   *
+   * For `"square"`: `TOP_LEFT`, `TOP`, `TOP_RIGHT`, `LEFT`, `SELF`, `RIGHT`, `BOTTOM_LEFT`, `BOTTOM`, `BOTTOM_RIGHT`.
+   *
+   * For `"cross"`: `TOP`, `LEFT`, `SELF`, `RIGHT`, `BOTTOM`.
+   */
   neighbor;
+  /**
+   * Helper functions for constructing count arrays used in conditions.
+   * Includes {@link Helpers.not | not}, {@link Helpers.between | between}, {@link Helpers.even | even}, and {@link Helpers.odd | odd}.
+   */
   helpers;
+  /**
+   * Defines a new element in the vivarium.
+   *
+   * @param name - A unique name identifying this element.
+   * @param color - A unique color used to draw this element. Accepts CSS named colors or hex values (e.g. `"green"`, `"#FF7A45"`).
+   * @param extensions - An optional array of kinds this element extends.
+   * @returns An {@link ElementBlueprint} that can be used to define rules.
+   */
   element(t, e, r = []) {
     this.assertNotCreated(), this.assertUniqueName(t), this.assertUniqueColor(e);
     const s = {
@@ -27,6 +47,12 @@ class C extends n {
     };
     return this.automaton.elements.push(s), new h(this.context, this.automaton, s);
   }
+  /**
+   * Defines a new kind in the vivarium. A kind groups elements that share common behavior.
+   *
+   * @param name - A unique name identifying this kind.
+   * @returns A {@link KindBlueprint} that can be used to define shared rules.
+   */
   kind(t) {
     this.assertNotCreated(), this.assertUniqueName(t);
     const e = {
@@ -36,6 +62,12 @@ class C extends n {
     };
     return this.automaton.kinds.push(e), new m(this.context, this.automaton, e);
   }
+  /**
+   * Finalizes the vivarium and produces an {@link Automaton} object. After calling this method,
+   * no further elements, kinds, or rules can be added.
+   *
+   * @returns The compiled {@link Automaton} to pass to {@link setup}.
+   */
   create() {
     this.assertNotCreated(), this.assertNotEmpty();
     const t = this.automaton;

package/dist/main.d.ts

@@ -1,2 +1,6 @@
 export { vivarium } from './vivarium/vivarium';
 export { setup } from './webgpu/setup';
+export { VivariumBlueprint } from './blueprint/vivarium-blueprint';
+export { RefBlueprint, ElementBlueprint, KindBlueprint, } from './blueprint/ref-blueprint';
+export { RuleBlueprint, RuleBlueprintWithAccept, } from './blueprint/rule-blueprint';
+export { Helpers } from './blueprint/helpers';

package/dist/main.js

@@ -1,6 +1,17 @@
-import { vivarium as e } from "./vivarium/vivarium.js";
-import { setup as p } from "./webgpu/setup.js";
+import { vivarium as t } from "./vivarium/vivarium.js";
+import { setup as i } from "./webgpu/setup.js";
+import { VivariumBlueprint as u } from "./blueprint/vivarium-blueprint.js";
+import { ElementBlueprint as m, KindBlueprint as n, RefBlueprint as f } from "./blueprint/ref-blueprint.js";
+import { R as B, a } from "./rule-blueprint-DGODv9IV.js";
+import { Helpers as R } from "./blueprint/helpers.js";
 export {
-  p as setup,
-  e as vivarium
+  m as ElementBlueprint,
+  R as Helpers,
+  n as KindBlueprint,
+  f as RefBlueprint,
+  B as RuleBlueprint,
+  a as RuleBlueprintWithAccept,
+  u as VivariumBlueprint,
+  i as setup,
+  t as vivarium
 };

package/dist/rule-blueprint-DGODv9IV.js

@@ -0,0 +1,84 @@
+import { BaseBlueprint as r } from "./blueprint/base-blueprint.js";
+import { toRefIdOrPoint as s } from "./blueprint/utils.js";
+import { n as c, c as a } from "./constants-D4GX9YB2.js";
+const h = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+let o = (i = 21) => {
+  let t = "", e = crypto.getRandomValues(new Uint8Array(i |= 0));
+  for (; i--; )
+    t += h[e[i] & 63];
+  return t;
+};
+class u extends r {
+  constructor(t, e, n) {
+    super(), this.context = t, this.automaton = e, this.rule = n;
+  }
+  condition(t) {
+    return this.assertNotCreated(), this.rule.when = [...this.rule.when, t], new l(this.context, this.automaton, this.rule);
+  }
+  /**
+   * Adds a count condition to the rule. The rule passes only if the number of matching neighbors
+   * equals one of the specified count values.
+   *
+   * @param refBlueprintOrNeighbor - The element, kind, or neighbor reference to count.
+   * @param count - The accepted count values. Can be individual numbers or arrays. When omitted, matches any count from 1 to the neighborhood size.
+   * @returns A {@link RuleBlueprintWithAccept} for chaining more conditions or setting an accept strategy.
+   */
+  count(t, ...e) {
+    let n = this.automaton.neighborhood === "cross" ? [1, 2, 3, 4] : [1, 2, 3, 4, 5, 6, 7, 8];
+    return e.length !== 0 && (n = e.flat()), this.condition({
+      type: "count",
+      id: o(),
+      check: s(t),
+      count: n
+    });
+  }
+  /**
+   * Adds an `is` condition to the rule. Checks whether a specific neighbor position matches a given element, kind, or another neighbor position.
+   *
+   * @param neighbor - The neighbor position to inspect (e.g. `vi.neighbor.TOP`).
+   * @param refBlueprintOrNeighbor - The element, kind, or neighbor position to compare against.
+   * @returns A {@link RuleBlueprintWithAccept} for chaining more conditions or setting an accept strategy.
+   */
+  is(t, e) {
+    return this.condition({
+      type: "is",
+      id: o(),
+      compare: c[t],
+      with: s(e)
+    });
+  }
+  /**
+   * Adds a chance condition to the rule. The rule passes with a probability of `part / whole`.
+   *
+   * @param part - The numerator of the probability fraction.
+   * @param whole - The denominator of the probability fraction. Defaults to `100`.
+   * @returns A {@link RuleBlueprintWithAccept} for chaining more conditions or setting an accept strategy.
+   */
+  chance(t, e = 100) {
+    return t < 0 && (t = 0), e <= 0 && (e = 1), t > e && (t = e), t = Math.floor(t), e = Math.floor(e), this.condition({
+      type: "chance",
+      id: o(),
+      ratio: { part: t, whole: e }
+    });
+  }
+}
+class l extends u {
+  /**
+   * Sets the acceptance strategy for multiple conditions on this rule.
+   *
+   * - `"all"` (default) — every condition must pass.
+   * - `"any"` — at least one condition must pass.
+   * - `"one"` — exactly one condition must pass.
+   * - `"none"` — no condition must pass (negation).
+   *
+   * @param strategy - The acceptance strategy.
+   */
+  accept(t) {
+    this.assertNotCreated(), this.rule.accept = a[t];
+  }
+}
+export {
+  u as R,
+  l as a,
+  o as n
+};

package/dist/simulation/simulation.browser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vivarium/vivarium.d.ts

@@ -1,3 +1,9 @@
 import { Neighborhood } from '../automaton/types';
 import { VivariumBlueprint } from '../blueprint/vivarium-blueprint';
+/**
+ * Creates a new vivarium builder used to define elements, kinds, and rules.
+ *
+ * @param neighborhoodName - The neighborhood type to use. Defaults to `"square"` (Moore neighborhood, 8 neighbors). Use `"cross"` for a von Neumann neighborhood (4 neighbors).
+ * @returns A {@link VivariumBlueprint} instance.
+ */
 export declare function vivarium<N extends Neighborhood = "square">(neighborhoodName?: N): VivariumBlueprint<N>;

package/dist/webgpu/compiler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/webgpu/setup.d.ts

@@ -1,4 +1,75 @@
+import { TgpuUniform } from 'typegpu';
 import { Automaton } from '../automaton/types';
+import * as d from "typegpu/data";
+export declare const setSeed: (s: TgpuUniform<d.F32>) => void;
+export declare const gridLayout: import('typegpu').TgpuBindGroupLayout<{
+    dimensions: {
+        uniform: d.Vec2u;
+    };
+    colors: {
+        storage: (elementCount: number) => d.WgslArray<d.U32>;
+        access: "mutable";
+    };
+    newColors: {
+        storage: (elementCount: number) => d.WgslArray<d.U32>;
+        access: "mutable";
+    };
+    ids: {
+        storage: (elementCount: number) => d.WgslArray<d.U32>;
+        access: "mutable";
+    };
+    newIds: {
+        storage: (elementCount: number) => d.WgslArray<d.U32>;
+        access: "mutable";
+    };
+}>;
+export declare const automatonLayout: import('typegpu').TgpuBindGroupLayout<{
+    neighborhood: {
+        uniform: d.U32;
+    };
+    elements: {
+        storage: (elementCount: number) => d.WgslArray<d.WgslStruct<{
+            color: d.U32;
+            ruleStart: d.U32;
+            ruleEnd: d.U32;
+        }>>;
+        access: "readonly";
+    };
+    rules: {
+        storage: (elementCount: number) => d.WgslArray<d.WgslStruct<{
+            toType: d.U32;
+            toId: d.U32;
+            toNeighbor: d.Vec2u;
+            accept: d.U32;
+            conditionsStart: d.U32;
+            conditionsEnd: d.U32;
+        }>>;
+        access: "readonly";
+    };
+    conditions: {
+        storage: (elementCount: number) => d.WgslArray<d.WgslStruct<{
+            opcode: d.U32;
+            checkId: d.U32;
+            countOrWithId: d.U32;
+            checkPointOrComparePoint: d.Vec2u;
+            withPoint: d.Vec2u;
+            chance: d.F32;
+        }>>;
+        access: "readonly";
+    };
+}>;
+export declare const mainCompute: import('typegpu').TgpuComputeFn<{
+    pos: d.BuiltinGlobalInvocationId;
+}>;
+/**
+ * Initializes the WebGPU simulation for a given canvas and automaton. The grid is randomly initialized
+ * with the defined elements.
+ *
+ * @param options - An object containing the `canvas` element and the compiled `automaton`.
+ * @param options.canvas - The HTML canvas element. Its `width` and `height` define the grid dimensions.
+ * @param options.automaton - The compiled automaton produced by {@link VivariumBlueprint.create | vivarium().create()}.
+ * @returns An object with an `evolve` function that advances the simulation by one step, a `setAutomaton` function to update the automaton, and the underlying `tgpuRoot`.
+ */
 export declare const setup: ({ canvas, automaton, }: {
     canvas: HTMLCanvasElement;
     automaton: Automaton;