@pibbl/core 0.0.1

package/dist/features/textures/lib/electric-shared.js

@@ -0,0 +1,43 @@
+import { validateSeed } from "./palette.js";
+function range(value, min, max, name) {
+  if (!Number.isFinite(value) || value < min || value > max)
+    throw new RangeError(`${name} must be ${min}..${max}.`);
+  return value;
+}
+function point(p) {
+  return { x: range(p.x, 0, 1, "Point x"), y: range(p.y, 0, 1, "Point y") };
+}
+function electricOptions(o) {
+  return {
+    seed: validateSeed(o.seed),
+    branching: range(o.branching ?? 0.6, 0, 1, "Branching"),
+    glow: range(o.glow ?? 1, 0, 2, "Glow")
+  };
+}
+function drawCore(context, p, strength, glow, radius = 0.038) {
+  if (strength <= 0) return;
+  const ctx = context.canvas.getContext("2d"), scale = Math.min(context.canvas.width, context.canvas.height);
+  const x = p.x * context.canvas.width, y = p.y * context.canvas.height;
+  const r = scale * radius * (0.5 + glow);
+  const gradient = ctx.createRadialGradient(x, y, 0, x, y, r);
+  gradient.addColorStop(0, `rgba(255,249,255,${strength})`);
+  gradient.addColorStop(0.1, `rgba(239,191,255,${strength * 0.95})`);
+  gradient.addColorStop(
+    0.35,
+    `rgba(179,60,255,${strength * 0.4 * glow / 2})`
+  );
+  gradient.addColorStop(1, "rgba(91,30,255,0)");
+  ctx.fillStyle = gradient;
+  ctx.fillRect(x - r, y - r, r * 2, r * 2);
+  ctx.fillStyle = `rgba(255,250,255,${strength})`;
+  ctx.beginPath();
+  ctx.arc(x, y, Math.max(0.65, scale * 4e-3), 0, Math.PI * 2);
+  ctx.fill();
+}
+export {
+  drawCore,
+  electricOptions,
+  point,
+  range
+};
+//# sourceMappingURL=electric-shared.js.map

package/dist/features/textures/lib/electric-shared.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/textures/lib/electric-shared.ts"],
+  "sourcesContent": ["import type { ElectricSource } from './electric-sources.js';\nimport type { LightningMessage, LightningOptions } from './lightning.js';\nimport type { TendrilsMessage, TendrilsOptions } from './tendrils.js';\nimport type { TextureContext } from \"@pibbl/core\";\nimport { validateSeed } from \"./palette.js\";\n\n/**\n * Coordinates are normalized to the complete texture, including its halo padding.\n *\n * @see {@link ElectricSource}\n * @see {@link LightningOptions}\n * @see {@link TendrilsOptions}\n * @see {@link LightningMessage}\n */\nexport interface ElectricPoint {\n  /**\n   * Horizontal coordinate or displacement in the containing coordinate system. See\n   * {@link ElectricPoint}.\n   */\n  readonly x: number;\n  /**\n   * Vertical coordinate or displacement in the containing coordinate system. See\n   * {@link ElectricPoint}.\n   */\n  readonly y: number;\n}\n/**\n * Deterministic seed, branching, and glow shared by electrical texture recipes.\n *\n * @see {@link TendrilsOptions}\n * @see {@link LightningOptions}\n */\nexport interface ElectricOptions {\n  /**\n   * Seed used for deterministic sampling or simulation initialization. See {@link ElectricOptions}\n   * .\n   */\n  readonly seed?: number;\n  /** 0..1, controls the number of secondary branches. */\n  readonly branching?: number;\n  /** 0..2, scales the soft halo without widening the white core. */\n  readonly glow?: number;\n}\n/**\n * Pause or reseed/reset commands shared by electrical textures.\n *\n * @see {@link TendrilsMessage}\n * @see {@link LightningMessage}\n */\nexport type ElectricControl =\n  | {\n      /** The literal \"pause\" identifying this variant. See {@link ElectricControl}. */\n      readonly type: \"pause\";\n      /** Whether simulation or playback advancement is suspended. See {@link ElectricControl}. */\n      readonly paused: boolean;\n    }\n  | {\n      /** The literal \"reset\" identifying this variant. See {@link ElectricControl}. */\n      readonly type: \"reset\";\n      /**\n       * Seed used for deterministic sampling or simulation initialization. See\n       * {@link ElectricControl}.\n       */\n      readonly seed?: number;\n    };\nexport function range(value: number, min: number, max: number, name: string) {\n  if (!Number.isFinite(value) || value < min || value > max)\n    throw new RangeError(`${name} must be ${min}..${max}.`);\n  return value;\n}\nexport function point(p: ElectricPoint): ElectricPoint {\n  return { x: range(p.x, 0, 1, \"Point x\"), y: range(p.y, 0, 1, \"Point y\") };\n}\nexport function electricOptions(o: ElectricOptions) {\n  return {\n    seed: validateSeed(o.seed),\n    branching: range(o.branching ?? 0.6, 0, 1, \"Branching\"),\n    glow: range(o.glow ?? 1, 0, 2, \"Glow\"),\n  };\n}\nexport function drawCore(\n  context: TextureContext,\n  p: ElectricPoint,\n  strength: number,\n  glow: number,\n  radius = 0.038,\n) {\n  if (strength <= 0) return;\n  const ctx = context.canvas.getContext(\"2d\")!,\n    scale = Math.min(context.canvas.width, context.canvas.height);\n  const x = p.x * context.canvas.width,\n    y = p.y * context.canvas.height;\n  const r = scale * radius * (0.5 + glow);\n  const gradient = ctx.createRadialGradient(x, y, 0, x, y, r);\n  gradient.addColorStop(0, `rgba(255,249,255,${strength})`);\n  gradient.addColorStop(0.1, `rgba(239,191,255,${strength * 0.95})`);\n  gradient.addColorStop(\n    0.35,\n    `rgba(179,60,255,${(strength * 0.4 * glow) / 2})`,\n  );\n  gradient.addColorStop(1, \"rgba(91,30,255,0)\");\n  ctx.fillStyle = gradient;\n  ctx.fillRect(x - r, y - r, r * 2, r * 2);\n  ctx.fillStyle = `rgba(255,250,255,${strength})`;\n  ctx.beginPath();\n  ctx.arc(x, y, Math.max(0.65, scale * 0.004), 0, Math.PI * 2);\n  ctx.fill();\n}\n"],
+  "mappings": "AAIA,SAAS,oBAAoB;AA6DtB,SAAS,MAAM,OAAe,KAAa,KAAa,MAAc;AAC3E,MAAI,CAAC,OAAO,SAAS,KAAK,KAAK,QAAQ,OAAO,QAAQ;AACpD,UAAM,IAAI,WAAW,GAAG,IAAI,YAAY,GAAG,KAAK,GAAG,GAAG;AACxD,SAAO;AACT;AACO,SAAS,MAAM,GAAiC;AACrD,SAAO,EAAE,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,SAAS,GAAG,GAAG,MAAM,EAAE,GAAG,GAAG,GAAG,SAAS,EAAE;AAC1E;AACO,SAAS,gBAAgB,GAAoB;AAClD,SAAO;AAAA,IACL,MAAM,aAAa,EAAE,IAAI;AAAA,IACzB,WAAW,MAAM,EAAE,aAAa,KAAK,GAAG,GAAG,WAAW;AAAA,IACtD,MAAM,MAAM,EAAE,QAAQ,GAAG,GAAG,GAAG,MAAM;AAAA,EACvC;AACF;AACO,SAAS,SACd,SACA,GACA,UACA,MACA,SAAS,OACT;AACA,MAAI,YAAY,EAAG;AACnB,QAAM,MAAM,QAAQ,OAAO,WAAW,IAAI,GACxC,QAAQ,KAAK,IAAI,QAAQ,OAAO,OAAO,QAAQ,OAAO,MAAM;AAC9D,QAAM,IAAI,EAAE,IAAI,QAAQ,OAAO,OAC7B,IAAI,EAAE,IAAI,QAAQ,OAAO;AAC3B,QAAM,IAAI,QAAQ,UAAU,MAAM;AAClC,QAAM,WAAW,IAAI,qBAAqB,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAC1D,WAAS,aAAa,GAAG,oBAAoB,QAAQ,GAAG;AACxD,WAAS,aAAa,KAAK,oBAAoB,WAAW,IAAI,GAAG;AACjE,WAAS;AAAA,IACP;AAAA,IACA,mBAAoB,WAAW,MAAM,OAAQ,CAAC;AAAA,EAChD;AACA,WAAS,aAAa,GAAG,mBAAmB;AAC5C,MAAI,YAAY;AAChB,MAAI,SAAS,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACvC,MAAI,YAAY,oBAAoB,QAAQ;AAC5C,MAAI,UAAU;AACd,MAAI,IAAI,GAAG,GAAG,KAAK,IAAI,MAAM,QAAQ,IAAK,GAAG,GAAG,KAAK,KAAK,CAAC;AAC3D,MAAI,KAAK;AACX;",
+  "names": []
+}

package/dist/features/textures/lib/electric-sources.d.ts

@@ -0,0 +1,50 @@
+import type { TendrilsMessage, TendrilsOptions } from "./tendrils.js";
+import { type ElectricPoint } from "./electric-shared.js";
+/**
+ * A weighted attachment site in normalized texture coordinates.
+ *
+ * @see {@link ElectricPoint}
+ * @see {@link ElectricSourceMessage}
+ * @see {@link TendrilsOptions}
+ */
+export interface ElectricSource {
+    /** Stable identifier of this resource or connection. See {@link ElectricSource}. */
+    readonly id: string;
+    /** A point in the operation's coordinate system. See {@link ElectricPoint}. */
+    readonly point: ElectricPoint;
+    /** Relative sampling weight or source intensity. See {@link ElectricSource}. */
+    readonly weight: number;
+}
+/**
+ * Upserts, removes, or replaces the named source electrodes of an electrical texture.
+ *
+ * @see {@link ElectricSource}
+ * @see {@link TendrilsMessage}
+ */
+export type ElectricSourceMessage = {
+    /** The literal "upsert-source" identifying this variant. See {@link ElectricSourceMessage}. */
+    readonly type: "upsert-source";
+    /** Named electrode to insert or replace. See {@link ElectricSource}. */
+    readonly source: ElectricSource;
+} | {
+    /** The literal "remove-source" identifying this variant. See {@link ElectricSourceMessage}. */
+    readonly type: "remove-source";
+    /** Stable identifier of this resource or connection. See {@link ElectricSourceMessage}. */
+    readonly id: string;
+} | {
+    /** The literal "set-sources" identifying this variant. See {@link ElectricSourceMessage}. */
+    readonly type: "set-sources";
+    /** Named electrical source electrodes. See {@link ElectricSource}. */
+    readonly sources: readonly ElectricSource[];
+};
+export declare const MAX_ELECTRIC_SOURCES = 512;
+export declare function sourceId(id: string): string;
+export declare function source(value: ElectricSource): ElectricSource;
+export declare function sources(values: readonly ElectricSource[]): ElectricSource[];
+export interface SourceSite {
+    id: string;
+    point: ElectricPoint;
+    weight: number;
+    hash: number;
+}
+export declare function site(value: ElectricSource): SourceSite;

package/dist/features/textures/lib/electric-sources.js

@@ -0,0 +1,43 @@
+import { point, range } from "./electric-shared.js";
+const MAX_ELECTRIC_SOURCES = 512;
+function sourceId(id) {
+  if (typeof id !== "string" || id.length < 1 || id.length > 128)
+    throw new RangeError("Electric source id must contain 1..128 characters.");
+  return id;
+}
+function source(value) {
+  return {
+    id: sourceId(value.id),
+    point: point(value.point),
+    weight: range(value.weight, 0, 1e6, "Source weight")
+  };
+}
+function sources(values) {
+  if (!Array.isArray(values) || values.length > MAX_ELECTRIC_SOURCES)
+    throw new RangeError(
+      "Electric sources must be an array of at most 512 sites."
+    );
+  const ids = /* @__PURE__ */ new Set();
+  const result = values.map((value) => {
+    const next = source(value);
+    if (ids.has(next.id))
+      throw new TypeError(`Duplicate electric source id: ${next.id}`);
+    ids.add(next.id);
+    return next;
+  });
+  return result.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+function site(value) {
+  let hash = 2166136261;
+  for (let i = 0; i < value.id.length; i++)
+    hash = Math.imul(hash ^ value.id.charCodeAt(i), 16777619);
+  return { ...value, point: { ...value.point }, hash };
+}
+export {
+  MAX_ELECTRIC_SOURCES,
+  site,
+  source,
+  sourceId,
+  sources
+};
+//# sourceMappingURL=electric-sources.js.map

package/dist/features/textures/lib/electric-sources.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/textures/lib/electric-sources.ts"],
+  "sourcesContent": ["import type { TendrilsMessage, TendrilsOptions } from './tendrils.js';\nimport { point, range, type ElectricPoint } from \"./electric-shared.js\";\n\n/**\n * A weighted attachment site in normalized texture coordinates.\n *\n * @see {@link ElectricPoint}\n * @see {@link ElectricSourceMessage}\n * @see {@link TendrilsOptions}\n */\nexport interface ElectricSource {\n  /** Stable identifier of this resource or connection. See {@link ElectricSource}. */\n  readonly id: string;\n  /** A point in the operation's coordinate system. See {@link ElectricPoint}. */\n  readonly point: ElectricPoint;\n  /** Relative sampling weight or source intensity. See {@link ElectricSource}. */\n  readonly weight: number;\n}\n/**\n * Upserts, removes, or replaces the named source electrodes of an electrical texture.\n *\n * @see {@link ElectricSource}\n * @see {@link TendrilsMessage}\n */\nexport type ElectricSourceMessage =\n  | {\n      /** The literal \"upsert-source\" identifying this variant. See {@link ElectricSourceMessage}. */\n      readonly type: \"upsert-source\";\n      /** Named electrode to insert or replace. See {@link ElectricSource}. */\n      readonly source: ElectricSource;\n    }\n  | {\n      /** The literal \"remove-source\" identifying this variant. See {@link ElectricSourceMessage}. */\n      readonly type: \"remove-source\";\n      /** Stable identifier of this resource or connection. See {@link ElectricSourceMessage}. */\n      readonly id: string;\n    }\n  | {\n      /** The literal \"set-sources\" identifying this variant. See {@link ElectricSourceMessage}. */\n      readonly type: \"set-sources\";\n      /** Named electrical source electrodes. See {@link ElectricSource}. */\n      readonly sources: readonly ElectricSource[];\n    };\n\nexport const MAX_ELECTRIC_SOURCES = 512;\nexport function sourceId(id: string): string {\n  if (typeof id !== \"string\" || id.length < 1 || id.length > 128)\n    throw new RangeError(\"Electric source id must contain 1..128 characters.\");\n  return id;\n}\nexport function source(value: ElectricSource): ElectricSource {\n  return {\n    id: sourceId(value.id),\n    point: point(value.point),\n    weight: range(value.weight, 0, 1_000_000, \"Source weight\"),\n  };\n}\nexport function sources(values: readonly ElectricSource[]): ElectricSource[] {\n  if (!Array.isArray(values) || values.length > MAX_ELECTRIC_SOURCES)\n    throw new RangeError(\n      \"Electric sources must be an array of at most 512 sites.\",\n    );\n  const ids = new Set<string>();\n  const result = values.map((value) => {\n    const next = source(value);\n    if (ids.has(next.id))\n      throw new TypeError(`Duplicate electric source id: ${next.id}`);\n    ids.add(next.id);\n    return next;\n  });\n  return result.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));\n}\nexport interface SourceSite {\n  id: string;\n  point: ElectricPoint;\n  weight: number;\n  hash: number;\n}\nexport function site(value: ElectricSource): SourceSite {\n  let hash = 2166136261;\n  for (let i = 0; i < value.id.length; i++)\n    hash = Math.imul(hash ^ value.id.charCodeAt(i), 16777619);\n  return { ...value, point: { ...value.point }, hash };\n}\n"],
+  "mappings": "AACA,SAAS,OAAO,aAAiC;AA2C1C,MAAM,uBAAuB;AAC7B,SAAS,SAAS,IAAoB;AAC3C,MAAI,OAAO,OAAO,YAAY,GAAG,SAAS,KAAK,GAAG,SAAS;AACzD,UAAM,IAAI,WAAW,oDAAoD;AAC3E,SAAO;AACT;AACO,SAAS,OAAO,OAAuC;AAC5D,SAAO;AAAA,IACL,IAAI,SAAS,MAAM,EAAE;AAAA,IACrB,OAAO,MAAM,MAAM,KAAK;AAAA,IACxB,QAAQ,MAAM,MAAM,QAAQ,GAAG,KAAW,eAAe;AAAA,EAC3D;AACF;AACO,SAAS,QAAQ,QAAqD;AAC3E,MAAI,CAAC,MAAM,QAAQ,MAAM,KAAK,OAAO,SAAS;AAC5C,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACF,QAAM,MAAM,oBAAI,IAAY;AAC5B,QAAM,SAAS,OAAO,IAAI,CAAC,UAAU;AACnC,UAAM,OAAO,OAAO,KAAK;AACzB,QAAI,IAAI,IAAI,KAAK,EAAE;AACjB,YAAM,IAAI,UAAU,iCAAiC,KAAK,EAAE,EAAE;AAChE,QAAI,IAAI,KAAK,EAAE;AACf,WAAO;AAAA,EACT,CAAC;AACD,SAAO,OAAO,KAAK,CAAC,GAAG,MAAO,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,CAAE;AACvE;AAOO,SAAS,KAAK,OAAmC;AACtD,MAAI,OAAO;AACX,WAAS,IAAI,GAAG,IAAI,MAAM,GAAG,QAAQ;AACnC,WAAO,KAAK,KAAK,OAAO,MAAM,GAAG,WAAW,CAAC,GAAG,QAAQ;AAC1D,SAAO,EAAE,GAAG,OAAO,OAAO,EAAE,GAAG,MAAM,MAAM,GAAG,KAAK;AACrD;",
+  "names": []
+}

package/dist/features/textures/lib/lightning.d.ts

@@ -0,0 +1,72 @@
+import { type ElectricControl, type ElectricOptions, type ElectricPoint } from "./electric-shared.js";
+/**
+ * Electrical appearance, electrode positions, topology frequency, and base-connection controls.
+ *
+ * @see {@link ElectricOptions}
+ * @see {@link ElectricPoint}
+ * @see {@link lightning}
+ * @see {@link LightningMessage}
+ */
+export interface LightningOptions extends ElectricOptions {
+    /** Position of the positive electrode. See {@link ElectricPoint}. */
+    readonly positive?: ElectricPoint;
+    /** Position of the negative electrode. See {@link ElectricPoint}. */
+    readonly negative?: ElectricPoint;
+    /** Boundary edge used as the electrical connection's origin. See {@link LightningOptions}. */
+    readonly edge?: "top" | "right" | "bottom" | "left";
+    /** Enables the configured base connection; manual connections remain independent. */
+    readonly active?: boolean;
+    /** Topology refreshes per second, 1..30. Connections survive several refreshes. */
+    readonly frequency?: number;
+    /** Whether to draw the electrode contact core. See {@link LightningOptions}. */
+    readonly contactCore?: boolean;
+}
+/**
+ * Control, connection management, and live configuration commands for a lightning texture.
+ *
+ * @see {@link ElectricControl}
+ * @see {@link ElectricPoint}
+ * @see {@link LightningOptions}
+ */
+export type LightningMessage = ElectricControl | {
+    /** The literal "connect" identifying this variant. See {@link LightningMessage}. */
+    readonly type: "connect";
+    /** Stable identifier of this resource or connection. See {@link LightningMessage}. */
+    readonly id: string;
+    /** Position of the positive electrode. See {@link ElectricPoint}. */
+    readonly positive: ElectricPoint;
+    /** Position of the negative electrode. See {@link ElectricPoint}. */
+    readonly negative: ElectricPoint;
+} | {
+    /** The literal "disconnect" identifying this variant. See {@link LightningMessage}. */
+    readonly type: "disconnect";
+    /** Stable identifier of this resource or connection. See {@link LightningMessage}. */
+    readonly id: string;
+} | {
+    /** The literal "configure" identifying this variant. See {@link LightningMessage}. */
+    readonly type: "configure";
+    /** Position of the positive electrode. See {@link ElectricPoint}. */
+    readonly positive?: ElectricPoint;
+    /** Position of the negative electrode. See {@link ElectricPoint}. */
+    readonly negative?: ElectricPoint;
+    /** Boundary edge used as the electrical connection's origin. See {@link LightningOptions}. */
+    readonly edge?: LightningOptions["edge"];
+    /** Current active operation or its presentation configuration. See {@link LightningMessage}. */
+    readonly active?: boolean;
+    /** Amount of secondary electrical branching. See {@link LightningMessage}. */
+    readonly branching?: number;
+    /** Intensity of the electrical halo around the core. See {@link LightningMessage}. */
+    readonly glow?: number;
+    /** Rate at which the pattern or motion repeats. See {@link LightningMessage}. */
+    readonly frequency?: number;
+};
+/**
+ * Persistent branching arcs between artistic positive/negative points.
+ *
+ * @param config - Lightning geometry, timing, and appearance settings. See
+ * {@link LightningOptions} .
+ * @returns A lightning texture recipe for useTexture.
+ *
+ * @see {@link LightningOptions}
+ */
+export declare function lightning(config?: LightningOptions): import("@pibbl/core").TextureRecipe<LightningMessage>;

package/dist/features/textures/lib/lightning.js

@@ -0,0 +1,139 @@
+import { ElectricMemory } from "./wasm/electric.js";
+import { lazyKernel } from "./wasm/memory.js";
+import { bytes } from "./wasm/lightning-bytes.js";
+const wasmModule = /* @__PURE__ */ lazyKernel(bytes);
+import { defineTexture } from "@pibbl/core";
+import { validateSeed } from "./palette.js";
+import {
+  electricOptions,
+  point,
+  range
+} from "./electric-shared.js";
+function options(o) {
+  if (o.edge !== void 0 && !["top", "right", "bottom", "left"].includes(o.edge))
+    throw new TypeError("Unknown lightning edge.");
+  return {
+    ...electricOptions(o),
+    positive: point(o.positive ?? { x: 0.2, y: 0.5 }),
+    negative: point(o.negative ?? { x: 0.8, y: 0.5 }),
+    edge: o.edge,
+    active: o.active ?? true,
+    frequency: range(o.frequency ?? 15, 1, 30, "Frequency"),
+    contactCore: o.contactCore ?? false
+  };
+}
+function salt(id) {
+  let n = 0;
+  for (let i = 0; i < id.length; i++)
+    n = Math.imul(n, 31) + id.charCodeAt(i) | 0;
+  return n;
+}
+const recipe = /* @__PURE__ */ defineTexture({
+  defaultPlacement: { mode: "stretch" },
+  create(context, input) {
+    if (input.active !== false) context.requestFrame();
+    const config = options(input);
+    return {
+      kernel: new ElectricMemory(wasmModule()),
+      config,
+      inputKey: JSON.stringify(input),
+      time: 0,
+      paused: false,
+      connections: /* @__PURE__ */ new Map()
+    };
+  },
+  update(s, input, context) {
+    const key = JSON.stringify(input);
+    if (key === s.inputKey) return;
+    const next = options(input);
+    if (next.seed !== s.config.seed) {
+      s.time = 0;
+      s.connections.clear();
+      s.kernel.clearConnections();
+    }
+    s.config = next;
+    s.inputKey = key;
+    context.invalidate();
+    if (!s.paused && (next.active || s.connections.size))
+      context.requestFrame();
+  },
+  receive(s, m, context) {
+    switch (m.type) {
+      case "pause":
+        s.paused = m.paused;
+        break;
+      case "reset":
+        s.config.seed = m.seed === void 0 ? s.config.seed : validateSeed(m.seed);
+        s.time = 0;
+        s.connections.clear();
+        s.kernel.clearConnections();
+        break;
+      case "configure":
+        s.config = options({ ...s.config, ...m });
+        break;
+      case "connect": {
+        if (typeof m.id !== "string" || m.id.length > 128)
+          throw new RangeError(
+            "Connection id must be a string of at most 128 characters."
+          );
+        const positive = point(m.positive), negative = point(m.negative), old = s.connections.get(m.id);
+        if (old) {
+          old.positive = positive;
+          old.negative = negative;
+          old.active = true;
+          old.strength = 1;
+        } else if (s.connections.size < 24)
+          s.connections.set(
+            m.id,
+            Object.assign(s.kernel.connection(), {
+              positive,
+              negative,
+              strength: 1,
+              active: true,
+              salt: salt(m.id)
+            })
+          );
+        break;
+      }
+      case "disconnect": {
+        const old = s.connections.get(m.id);
+        if (old) old.active = false;
+        break;
+      }
+      default:
+        throw new TypeError("Unknown lightning message.");
+    }
+    context.invalidate();
+    if (!s.paused && (s.config.active || s.connections.size))
+      context.requestFrame();
+  },
+  advance(s, frame, context) {
+    if (s.paused) return;
+    const dt = Math.min(50, frame.delta) / 1e3;
+    s.time += dt;
+    s.kernel.advanceLightning(dt);
+    for (const [id, c] of s.connections) {
+      if (c.strength < 5e-3) {
+        c.release();
+        s.connections.delete(id);
+      }
+    }
+    context.invalidate();
+    if (s.config.active || s.connections.size) context.requestFrame();
+  },
+  rasterize(s, context) {
+    s.kernel.lightning(s.config, s.time, s.connections.values());
+    s.kernel.draw(context, s.config.glow);
+  },
+  dispose(s) {
+    s.connections.clear();
+    s.kernel.dispose();
+  }
+});
+function lightning(config = {}) {
+  return recipe(config);
+}
+export {
+  lightning
+};
+//# sourceMappingURL=lightning.js.map

package/dist/features/textures/lib/lightning.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/textures/lib/lightning.ts"],
+  "sourcesContent": ["import { ElectricMemory, type ElectricConnection } from \"./wasm/electric.js\";\nimport { lazyKernel } from \"./wasm/memory.js\";\nimport { bytes } from \"./wasm/lightning-bytes.js\";\nconst wasmModule = /* @__PURE__ */ lazyKernel(bytes);\nimport { defineTexture } from \"@pibbl/core\";\nimport { validateSeed } from \"./palette.js\";\nimport {\n  electricOptions,\n  point,\n  range,\n  type ElectricControl,\n  type ElectricOptions,\n  type ElectricPoint,\n} from \"./electric-shared.js\";\n\n/**\n * Electrical appearance, electrode positions, topology frequency, and base-connection controls.\n *\n * @see {@link ElectricOptions}\n * @see {@link ElectricPoint}\n * @see {@link lightning}\n * @see {@link LightningMessage}\n */\nexport interface LightningOptions extends ElectricOptions {\n  /** Position of the positive electrode. See {@link ElectricPoint}. */\n  readonly positive?: ElectricPoint;\n  /** Position of the negative electrode. See {@link ElectricPoint}. */\n  readonly negative?: ElectricPoint;\n  /** Boundary edge used as the electrical connection's origin. See {@link LightningOptions}. */\n  readonly edge?: \"top\" | \"right\" | \"bottom\" | \"left\";\n  /** Enables the configured base connection; manual connections remain independent. */\n  readonly active?: boolean;\n  /** Topology refreshes per second, 1..30. Connections survive several refreshes. */\n  readonly frequency?: number;\n  /** Whether to draw the electrode contact core. See {@link LightningOptions}. */\n  readonly contactCore?: boolean;\n}\n/**\n * Control, connection management, and live configuration commands for a lightning texture.\n *\n * @see {@link ElectricControl}\n * @see {@link ElectricPoint}\n * @see {@link LightningOptions}\n */\nexport type LightningMessage =\n  | ElectricControl\n  | {\n      /** The literal \"connect\" identifying this variant. See {@link LightningMessage}. */\n      readonly type: \"connect\";\n      /** Stable identifier of this resource or connection. See {@link LightningMessage}. */\n      readonly id: string;\n      /** Position of the positive electrode. See {@link ElectricPoint}. */\n      readonly positive: ElectricPoint;\n      /** Position of the negative electrode. See {@link ElectricPoint}. */\n      readonly negative: ElectricPoint;\n    }\n  | {\n      /** The literal \"disconnect\" identifying this variant. See {@link LightningMessage}. */\n      readonly type: \"disconnect\";\n      /** Stable identifier of this resource or connection. See {@link LightningMessage}. */\n      readonly id: string;\n    }\n  | {\n      /** The literal \"configure\" identifying this variant. See {@link LightningMessage}. */\n      readonly type: \"configure\";\n      /** Position of the positive electrode. See {@link ElectricPoint}. */\n      readonly positive?: ElectricPoint;\n      /** Position of the negative electrode. See {@link ElectricPoint}. */\n      readonly negative?: ElectricPoint;\n      /** Boundary edge used as the electrical connection's origin. See {@link LightningOptions}. */\n      readonly edge?: LightningOptions[\"edge\"];\n      /** Current active operation or its presentation configuration. See {@link LightningMessage}. */\n      readonly active?: boolean;\n      /** Amount of secondary electrical branching. See {@link LightningMessage}. */\n      readonly branching?: number;\n      /** Intensity of the electrical halo around the core. See {@link LightningMessage}. */\n      readonly glow?: number;\n      /** Rate at which the pattern or motion repeats. See {@link LightningMessage}. */\n      readonly frequency?: number;\n    };\nfunction options(o: LightningOptions) {\n  if (\n    o.edge !== undefined &&\n    ![\"top\", \"right\", \"bottom\", \"left\"].includes(o.edge)\n  )\n    throw new TypeError(\"Unknown lightning edge.\");\n  return {\n    ...electricOptions(o),\n    positive: point(o.positive ?? { x: 0.2, y: 0.5 }),\n    negative: point(o.negative ?? { x: 0.8, y: 0.5 }),\n    edge: o.edge,\n    active: o.active ?? true,\n    frequency: range(o.frequency ?? 15, 1, 30, \"Frequency\"),\n    contactCore: o.contactCore ?? false,\n  };\n}\ntype Connection = ElectricConnection;\ninterface State {\n  kernel: ElectricMemory;\n  config: ReturnType<typeof options>;\n  inputKey: string;\n  time: number;\n  paused: boolean;\n  connections: Map<string, Connection>;\n}\nfunction salt(id: string) {\n  let n = 0;\n  for (let i = 0; i < id.length; i++)\n    n = (Math.imul(n, 31) + id.charCodeAt(i)) | 0;\n  return n;\n}\nconst recipe = /* @__PURE__ */ defineTexture<\n  LightningOptions,\n  State,\n  LightningMessage\n>({\n  defaultPlacement: { mode: \"stretch\" },\n  create(context, input) {\n    if (input.active !== false) context.requestFrame();\n    const config = options(input);\n    return {\n      kernel: new ElectricMemory(wasmModule()),\n      config,\n      inputKey: JSON.stringify(input),\n      time: 0,\n      paused: false,\n      connections: new Map(),\n    };\n  },\n  update(s, input, context) {\n    const key = JSON.stringify(input);\n    if (key === s.inputKey) return;\n    const next = options(input);\n    if (next.seed !== s.config.seed) {\n      s.time = 0;\n      s.connections.clear();\n      s.kernel.clearConnections();\n    }\n    s.config = next;\n    s.inputKey = key;\n    context.invalidate();\n    if (!s.paused && (next.active || s.connections.size))\n      context.requestFrame();\n  },\n  receive(s, m, context) {\n    switch (m.type) {\n      case \"pause\":\n        s.paused = m.paused;\n        break;\n      case \"reset\":\n        s.config.seed =\n          m.seed === undefined ? s.config.seed : validateSeed(m.seed);\n        s.time = 0;\n        s.connections.clear();\n        s.kernel.clearConnections();\n        break;\n      case \"configure\":\n        s.config = options({ ...s.config, ...m });\n        break;\n      case \"connect\": {\n        if (typeof m.id !== \"string\" || m.id.length > 128)\n          throw new RangeError(\n            \"Connection id must be a string of at most 128 characters.\",\n          );\n        const positive = point(m.positive),\n          negative = point(m.negative),\n          old = s.connections.get(m.id);\n        if (old) {\n          old.positive = positive;\n          old.negative = negative;\n          old.active = true;\n          old.strength = 1;\n        } else if (s.connections.size < 24)\n          s.connections.set(\n            m.id,\n            Object.assign(s.kernel.connection(), {\n              positive,\n              negative,\n              strength: 1,\n              active: true,\n              salt: salt(m.id),\n            }),\n          );\n        break;\n      }\n      case \"disconnect\": {\n        const old = s.connections.get(m.id);\n        if (old) old.active = false;\n        break;\n      }\n      default:\n        throw new TypeError(\"Unknown lightning message.\");\n    }\n    context.invalidate();\n    if (!s.paused && (s.config.active || s.connections.size))\n      context.requestFrame();\n  },\n  advance(s, frame, context) {\n    if (s.paused) return;\n    const dt = Math.min(50, frame.delta) / 1000;\n    s.time += dt;\n    s.kernel.advanceLightning(dt);\n    for (const [id, c] of s.connections) {\n      if (c.strength < 0.005) {\n        c.release();\n        s.connections.delete(id);\n      }\n    }\n    context.invalidate();\n    if (s.config.active || s.connections.size) context.requestFrame();\n  },\n  rasterize(s, context) {\n    s.kernel.lightning(s.config, s.time, s.connections.values());\n    s.kernel.draw(context, s.config.glow);\n  },\n  dispose(s) {\n    s.connections.clear();\n    s.kernel.dispose();\n  },\n});\n/**\n * Persistent branching arcs between artistic positive/negative points.\n *\n * @param config - Lightning geometry, timing, and appearance settings. See\n * {@link LightningOptions} .\n * @returns A lightning texture recipe for useTexture.\n *\n * @see {@link LightningOptions}\n */\nexport function lightning(config: LightningOptions = {}) {\n  return recipe(config);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/features/textures/lib/material-field.d.ts

@@ -0,0 +1,12 @@
+import type { ProceduralTextureProps } from "./procedural-texture.js";
+/**
+ * The supported static material generators: marble, paper, and cellular.
+ *
+ * @see {@link ProceduralTextureProps}
+ */
+export type TextureKind = "marble" | "paper" | "cellular";
+export type MaterialGenerator = (width: number, height: number, seed: number, scale: number, detail: number, previous?: Float32Array) => Float32Array;
+export declare const marbleField: MaterialGenerator;
+export declare const paperField: MaterialGenerator;
+export declare const cellularField: MaterialGenerator;
+export declare function materialField(width: number, height: number, kind: TextureKind, seed: number, scale: number, detail: number, previous?: Float32Array): Float32Array;

package/dist/features/textures/lib/material-field.js

@@ -0,0 +1,31 @@
+import { reuseFieldMemory, lazyKernel } from "./wasm/memory.js";
+import { bytes as marbleBytes } from "./wasm/marble-bytes.js";
+import { bytes as paperBytes } from "./wasm/paper-bytes.js";
+import { bytes as cellularBytes } from "./wasm/cellular-bytes.js";
+function generator(bytes) {
+  const module = lazyKernel(bytes);
+  return (width, height, seed, scale, detail, previous) => {
+    const owner = reuseFieldMemory(previous, module(), width, height);
+    const field = owner.fields[0];
+    owner.kernel.run(field.byteOffset, width, height, seed, scale, detail);
+    return field;
+  };
+}
+const marbleField = /* @__PURE__ */ generator(marbleBytes);
+const paperField = /* @__PURE__ */ generator(paperBytes);
+const cellularField = /* @__PURE__ */ generator(cellularBytes);
+const generators = {
+  marble: marbleField,
+  paper: paperField,
+  cellular: cellularField
+};
+function materialField(width, height, kind, seed, scale, detail, previous) {
+  return generators[kind](width, height, seed, scale, detail, previous);
+}
+export {
+  cellularField,
+  marbleField,
+  materialField,
+  paperField
+};
+//# sourceMappingURL=material-field.js.map

package/dist/features/textures/lib/material-field.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/textures/lib/material-field.ts"],
+  "sourcesContent": ["import type { ProceduralTextureProps } from './procedural-texture.js';\nimport { reuseFieldMemory, lazyKernel } from \"./wasm/memory.js\";\nimport { bytes as marbleBytes } from \"./wasm/marble-bytes.js\";\nimport { bytes as paperBytes } from \"./wasm/paper-bytes.js\";\nimport { bytes as cellularBytes } from \"./wasm/cellular-bytes.js\";\n/**\n * The supported static material generators: marble, paper, and cellular.\n *\n * @see {@link ProceduralTextureProps}\n */\nexport type TextureKind = \"marble\" | \"paper\" | \"cellular\";\nexport type MaterialGenerator = (\n  width: number,\n  height: number,\n  seed: number,\n  scale: number,\n  detail: number,\n  previous?: Float32Array,\n) => Float32Array;\nfunction generator(bytes: string): MaterialGenerator {\n  const module = lazyKernel(bytes);\n  return (width, height, seed, scale, detail, previous) => {\n    const owner = reuseFieldMemory(previous, module(), width, height);\n    const field = owner.fields[0];\n    owner.kernel.run(field.byteOffset, width, height, seed, scale, detail);\n    return field;\n  };\n}\nexport const marbleField = /* @__PURE__ */ generator(marbleBytes);\nexport const paperField = /* @__PURE__ */ generator(paperBytes);\nexport const cellularField = /* @__PURE__ */ generator(cellularBytes);\nconst generators: Record<TextureKind, MaterialGenerator> = {\n  marble: marbleField,\n  paper: paperField,\n  cellular: cellularField,\n};\nexport function materialField(\n  width: number,\n  height: number,\n  kind: TextureKind,\n  seed: number,\n  scale: number,\n  detail: number,\n  previous?: Float32Array,\n): Float32Array {\n  return generators[kind](width, height, seed, scale, detail, previous);\n}\n"],
+  "mappings": "AACA,SAAS,kBAAkB,kBAAkB;AAC7C,SAAS,SAAS,mBAAmB;AACrC,SAAS,SAAS,kBAAkB;AACpC,SAAS,SAAS,qBAAqB;AAevC,SAAS,UAAU,OAAkC;AACnD,QAAM,SAAS,WAAW,KAAK;AAC/B,SAAO,CAAC,OAAO,QAAQ,MAAM,OAAO,QAAQ,aAAa;AACvD,UAAM,QAAQ,iBAAiB,UAAU,OAAO,GAAG,OAAO,MAAM;AAChE,UAAM,QAAQ,MAAM,OAAO,CAAC;AAC5B,UAAM,OAAO,IAAI,MAAM,YAAY,OAAO,QAAQ,MAAM,OAAO,MAAM;AACrE,WAAO;AAAA,EACT;AACF;AACO,MAAM,cAA8B,0BAAU,WAAW;AACzD,MAAM,aAA6B,0BAAU,UAAU;AACvD,MAAM,gBAAgC,0BAAU,aAAa;AACpE,MAAM,aAAqD;AAAA,EACzD,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,UAAU;AACZ;AACO,SAAS,cACd,OACA,QACA,MACA,MACA,OACA,QACA,UACc;AACd,SAAO,WAAW,IAAI,EAAE,OAAO,QAAQ,MAAM,OAAO,QAAQ,QAAQ;AACtE;",
+  "names": []
+}

package/dist/features/textures/lib/palette.d.ts

@@ -0,0 +1,45 @@
+import type { ProceduralTextureProps } from "./procedural-texture.js";
+import type { ReactionDiffusionProps } from "./reaction-diffusion.js";
+/**
+ * Ordered colors forming a texture's presentation ramp.
+ *
+ * @see {@link texturePalettes}
+ * @see {@link ProceduralTextureProps}
+ * @see {@link ReactionDiffusionProps}
+ */
+export type TexturePalette = readonly string[];
+/**
+ * Built-in immutable color ramps for procedural texture presentation.
+ *
+ * @see {@link TexturePalette}
+ */
+export declare const texturePalettes: Readonly<{
+    /** Dark blue through teal to pale yellow. See {@link texturePalettes}. */
+    lagoon: readonly string[];
+    /** Warm ivory through lavender to deep blue. See {@link texturePalettes}. */
+    porcelain: readonly string[];
+    /** Dark violet through coral to pale yellow. See {@link texturePalettes}. */
+    ember: readonly string[];
+}>;
+export declare function paletteLut(palette: TexturePalette): Uint8ClampedArray;
+/**
+ * The width and height of a texture's raster grid.
+ *
+ * @see {@link TexturePalette}
+ * @see {@link ReactionDiffusionProps}
+ * @see {@link ProceduralTextureProps}
+ */
+export interface TextureResolution {
+    /**
+     * Horizontal extent in the units of the containing geometry or surface. See
+     * {@link TextureResolution}.
+     */
+    readonly width: number;
+    /**
+     * Vertical extent in the units of the containing geometry or surface. See
+     * {@link TextureResolution}.
+     */
+    readonly height: number;
+}
+export declare function validateResolution(value?: TextureResolution): TextureResolution;
+export declare function validateSeed(seed?: number): number;

package/dist/features/textures/lib/palette.js

@@ -0,0 +1,52 @@
+const texturePalettes = Object.freeze({
+  /** Dark blue through teal to pale yellow. See {@link texturePalettes}. */
+  lagoon: Object.freeze(["#081e2c", "#125568", "#50b8ad", "#e5efb3"]),
+  /** Warm ivory through lavender to deep blue. See {@link texturePalettes}. */
+  porcelain: Object.freeze(["#f2e7d4", "#b7a9c0", "#536194", "#172955"]),
+  /** Dark violet through coral to pale yellow. See {@link texturePalettes}. */
+  ember: Object.freeze(["#241526", "#893955", "#e88470", "#ffe3aa"])
+});
+function paletteLut(palette) {
+  if (palette.length < 2 || palette.length > 16)
+    throw new RangeError("Texture palette requires 2\u201316 #RRGGBB colors.");
+  const colors = palette.map((color) => {
+    if (!/^#[0-9a-f]{6}$/i.test(color))
+      throw new TypeError("Texture palette colors must use #RRGGBB.");
+    return [
+      parseInt(color.slice(1, 3), 16),
+      parseInt(color.slice(3, 5), 16),
+      parseInt(color.slice(5, 7), 16)
+    ];
+  });
+  const lut = new Uint8ClampedArray(256 * 4);
+  for (let i = 0; i < 256; i++) {
+    const position = i / 255 * (colors.length - 1);
+    const lo = Math.min(colors.length - 2, Math.floor(position)), mix = position - lo;
+    for (let c = 0; c < 3; c++)
+      lut[i * 4 + c] = colors[lo][c] * (1 - mix) + colors[lo + 1][c] * mix;
+    lut[i * 4 + 3] = 255;
+  }
+  return lut;
+}
+function validateResolution(value = { width: 256, height: 160 }) {
+  if (![value.width, value.height].every(
+    (n) => Number.isInteger(n) && n >= 8 && n <= 1024
+  ) || value.width * value.height > 262144) {
+    throw new RangeError(
+      "Texture resolution must contain integer dimensions from 8 to 1024 and at most 262144 cells."
+    );
+  }
+  return { width: value.width, height: value.height };
+}
+function validateSeed(seed = 42) {
+  if (!Number.isInteger(seed) || seed < 0 || seed > 4294967295)
+    throw new RangeError("Texture seed must be an unsigned 32-bit integer.");
+  return seed;
+}
+export {
+  paletteLut,
+  texturePalettes,
+  validateResolution,
+  validateSeed
+};
+//# sourceMappingURL=palette.js.map

package/dist/features/textures/lib/palette.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/features/textures/lib/palette.ts"],
+  "sourcesContent": ["import type { ProceduralTextureProps } from './procedural-texture.js';\nimport type { ReactionDiffusionProps } from './reaction-diffusion.js';\n/**\n * Ordered colors forming a texture's presentation ramp.\n *\n * @see {@link texturePalettes}\n * @see {@link ProceduralTextureProps}\n * @see {@link ReactionDiffusionProps}\n */\nexport type TexturePalette = readonly string[];\n/**\n * Built-in immutable color ramps for procedural texture presentation.\n *\n * @see {@link TexturePalette}\n */\nexport const texturePalettes = Object.freeze({\n  /** Dark blue through teal to pale yellow. See {@link texturePalettes}. */\n  lagoon: Object.freeze([\"#081e2c\", \"#125568\", \"#50b8ad\", \"#e5efb3\"]),\n  /** Warm ivory through lavender to deep blue. See {@link texturePalettes}. */\n  porcelain: Object.freeze([\"#f2e7d4\", \"#b7a9c0\", \"#536194\", \"#172955\"]),\n  /** Dark violet through coral to pale yellow. See {@link texturePalettes}. */\n  ember: Object.freeze([\"#241526\", \"#893955\", \"#e88470\", \"#ffe3aa\"]),\n});\n\nexport function paletteLut(palette: TexturePalette): Uint8ClampedArray {\n  if (palette.length < 2 || palette.length > 16)\n    throw new RangeError(\"Texture palette requires 2\u201316 #RRGGBB colors.\");\n  const colors = palette.map((color) => {\n    if (!/^#[0-9a-f]{6}$/i.test(color))\n      throw new TypeError(\"Texture palette colors must use #RRGGBB.\");\n    return [\n      parseInt(color.slice(1, 3), 16),\n      parseInt(color.slice(3, 5), 16),\n      parseInt(color.slice(5, 7), 16),\n    ];\n  });\n  const lut = new Uint8ClampedArray(256 * 4);\n  for (let i = 0; i < 256; i++) {\n    const position = (i / 255) * (colors.length - 1);\n    const lo = Math.min(colors.length - 2, Math.floor(position)),\n      mix = position - lo;\n    for (let c = 0; c < 3; c++)\n      lut[i * 4 + c] = colors[lo][c] * (1 - mix) + colors[lo + 1][c] * mix;\n    lut[i * 4 + 3] = 255;\n  }\n  return lut;\n}\n\n/**\n * The width and height of a texture's raster grid.\n *\n * @see {@link TexturePalette}\n * @see {@link ReactionDiffusionProps}\n * @see {@link ProceduralTextureProps}\n */\nexport interface TextureResolution {\n  /**\n   * Horizontal extent in the units of the containing geometry or surface. See\n   * {@link TextureResolution}.\n   */\n  readonly width: number;\n  /**\n   * Vertical extent in the units of the containing geometry or surface. See\n   * {@link TextureResolution}.\n   */\n  readonly height: number;\n}\nexport function validateResolution(\n  value: TextureResolution = { width: 256, height: 160 },\n): TextureResolution {\n  if (\n    ![value.width, value.height].every(\n      (n) => Number.isInteger(n) && n >= 8 && n <= 1024,\n    ) ||\n    value.width * value.height > 262144\n  ) {\n    throw new RangeError(\n      \"Texture resolution must contain integer dimensions from 8 to 1024 and at most 262144 cells.\",\n    );\n  }\n  return { width: value.width, height: value.height };\n}\nexport function validateSeed(seed = 42): number {\n  if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)\n    throw new RangeError(\"Texture seed must be an unsigned 32-bit integer.\");\n  return seed;\n}\n"],
+  "mappings": "AAeO,MAAM,kBAAkB,OAAO,OAAO;AAAA;AAAA,EAE3C,QAAQ,OAAO,OAAO,CAAC,WAAW,WAAW,WAAW,SAAS,CAAC;AAAA;AAAA,EAElE,WAAW,OAAO,OAAO,CAAC,WAAW,WAAW,WAAW,SAAS,CAAC;AAAA;AAAA,EAErE,OAAO,OAAO,OAAO,CAAC,WAAW,WAAW,WAAW,SAAS,CAAC;AACnE,CAAC;AAEM,SAAS,WAAW,SAA4C;AACrE,MAAI,QAAQ,SAAS,KAAK,QAAQ,SAAS;AACzC,UAAM,IAAI,WAAW,oDAA+C;AACtE,QAAM,SAAS,QAAQ,IAAI,CAAC,UAAU;AACpC,QAAI,CAAC,kBAAkB,KAAK,KAAK;AAC/B,YAAM,IAAI,UAAU,0CAA0C;AAChE,WAAO;AAAA,MACL,SAAS,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE;AAAA,MAC9B,SAAS,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE;AAAA,MAC9B,SAAS,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE;AAAA,IAChC;AAAA,EACF,CAAC;AACD,QAAM,MAAM,IAAI,kBAAkB,MAAM,CAAC;AACzC,WAAS,IAAI,GAAG,IAAI,KAAK,KAAK;AAC5B,UAAM,WAAY,IAAI,OAAQ,OAAO,SAAS;AAC9C,UAAM,KAAK,KAAK,IAAI,OAAO,SAAS,GAAG,KAAK,MAAM,QAAQ,CAAC,GACzD,MAAM,WAAW;AACnB,aAAS,IAAI,GAAG,IAAI,GAAG;AACrB,UAAI,IAAI,IAAI,CAAC,IAAI,OAAO,EAAE,EAAE,CAAC,KAAK,IAAI,OAAO,OAAO,KAAK,CAAC,EAAE,CAAC,IAAI;AACnE,QAAI,IAAI,IAAI,CAAC,IAAI;AAAA,EACnB;AACA,SAAO;AACT;AAqBO,SAAS,mBACd,QAA2B,EAAE,OAAO,KAAK,QAAQ,IAAI,GAClC;AACnB,MACE,CAAC,CAAC,MAAM,OAAO,MAAM,MAAM,EAAE;AAAA,IAC3B,CAAC,MAAM,OAAO,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK;AAAA,EAC/C,KACA,MAAM,QAAQ,MAAM,SAAS,QAC7B;AACA,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO,EAAE,OAAO,MAAM,OAAO,QAAQ,MAAM,OAAO;AACpD;AACO,SAAS,aAAa,OAAO,IAAY;AAC9C,MAAI,CAAC,OAAO,UAAU,IAAI,KAAK,OAAO,KAAK,OAAO;AAChD,UAAM,IAAI,WAAW,kDAAkD;AACzE,SAAO;AACT;",
+  "names": []
+}

package/dist/features/textures/lib/presentation.d.ts

@@ -0,0 +1,54 @@
+import type { ReactionDiffusionProps } from "./reaction-diffusion.js";
+import type { ProceduralTextureProps } from "./procedural-texture.js";
+/**
+ * Borrowed sources are valid only during the synchronous renderer callback.
+ *
+ * @see {@link TextureRenderer}
+ */
+export interface TextureRenderFrame {
+    /** Current offscreen texture raster available to the presentation callback. See {@link TextureRenderFrame}. */
+    readonly source: OffscreenCanvas;
+    /** White with texture intensity as alpha, allocated lazily on first access. */
+    readonly mask: OffscreenCanvas;
+    /**
+     * Horizontal extent in the units of the containing geometry or surface. See
+     * {@link TextureRenderFrame}.
+     */
+    readonly width: number;
+    /**
+     * Vertical extent in the units of the containing geometry or surface. See
+     * {@link TextureRenderFrame}.
+     */
+    readonly height: number;
+    /** Width of the underlying texture raster in pixels. See {@link TextureRenderFrame}. */
+    readonly textureWidth: number;
+    /** Height of the underlying texture raster in pixels. See {@link TextureRenderFrame}. */
+    readonly textureHeight: number;
+}
+/**
+ * Custom presentation callback receiving an offscreen context and the current texture raster
+ * frame.
+ *
+ * @param context - Offscreen drawing context to paint into.
+ * @param texture - Current texture surface and frame metadata. See {@link TextureRenderFrame}.
+ *
+ * @see {@link TextureRenderFrame}
+ * @see {@link ReactionDiffusionProps}
+ * @see {@link ProceduralTextureProps}
+ */
+export type TextureRenderer = (context: OffscreenCanvasRenderingContext2D, texture: Readonly<TextureRenderFrame>) => void;
+export declare class TextureRaster {
+    readonly width: number;
+    readonly height: number;
+    readonly surface: OffscreenCanvas;
+    readonly context: OffscreenCanvasRenderingContext2D;
+    private maskRaster?;
+    private maskSurface?;
+    private maskContext?;
+    private maskDirty;
+    constructor(width: number, height: number);
+    update(field: Float32Array, lut: Uint8ClampedArray, gain?: number): void;
+    private getMask;
+    draw(ctx: OffscreenCanvasRenderingContext2D, width: number, height: number, backingWidth: number, backingHeight: number, render?: TextureRenderer): void;
+    dispose(): void;
+}