@pibbl/core 0.0.1

package/dist/lib/transitions/embers-physics.js

@@ -0,0 +1,161 @@
+import { finite } from "./capture.js";
+function resolveEmbersPhysics(options) {
+  const vector = (value, name) => Object.freeze([
+    finite(value[0], `${name}.x`),
+    finite(value[1], `${name}.y`)
+  ]);
+  const restitution = finite(
+    options.restitution ?? 0.5,
+    "physics.restitution",
+    0
+  );
+  if (restitution > 1)
+    throw new RangeError("physics.restitution must be between zero and one.");
+  if (options.collide !== void 0 && typeof options.collide !== "function")
+    throw new TypeError("physics.collide must be a synchronous function.");
+  if (options.obstacles && (typeof options.obstacles.read !== "function" || options.collide))
+    throw new TypeError(
+      "physics.obstacles requires read() and cannot be combined with collide."
+    );
+  return Object.freeze({
+    obstacles: options.obstacles,
+    gravity: vector(options.gravity ?? [0, -60], "physics.gravity"),
+    wind: vector(options.wind ?? [0, -45], "physics.wind"),
+    drag: finite(options.drag ?? 4, "physics.drag", 0),
+    restitution,
+    collide: options.collide
+  });
+}
+function emberSimulation(kernel, options, region, linger, burnWidth) {
+  let previous = 0, remainder = 0, needsReset = true, disposed = false;
+  const step = 1e3 / 60;
+  let obstacleRevision;
+  let boxLength = 0, ellipseLength = 0, polygonLength = 0;
+  return {
+    reset() {
+      previous = 0;
+      remainder = 0;
+      needsReset = true;
+    },
+    get disposed() {
+      return disposed;
+    },
+    dispose() {
+      disposed = true;
+      kernel.dispose();
+    },
+    advance(elapsed, progressAt) {
+      if (disposed || elapsed <= previous) return;
+      const { exports, values } = kernel();
+      if (needsReset) {
+        exports.resetPhysics();
+        needsReset = false;
+      }
+      remainder += Math.min(elapsed - previous, step * 4);
+      previous = elapsed;
+      if (remainder + 1e-8 >= step && options.obstacles) {
+        const batch = options.obstacles.read();
+        if (batch.revision !== obstacleRevision) {
+          const { boxes, ellipses, polygons } = batch;
+          if (!Number.isFinite(batch.revision) || boxes.length % 10 || ellipses.length % 10 || boxes.length + ellipses.length + polygons.length > 8192)
+            throw new RangeError(
+              "Invalid ember obstacle batch or capacity exceeded (8192 numbers)."
+            );
+          for (const packed of [boxes, ellipses, polygons])
+            for (const value of packed)
+              if (!Number.isFinite(value))
+                throw new RangeError("Ember obstacles must be finite.");
+          for (const packed of [boxes, ellipses])
+            for (let i = 0; i < packed.length; i += 10)
+              if (packed[i + 2] <= 0 || packed[i + 3] <= 0)
+                throw new RangeError(
+                  "Ember obstacle extents must be positive."
+                );
+          for (let at = 0; at < polygons.length; ) {
+            const count = polygons[at];
+            if (!Number.isInteger(count) || count < 3 || at + 6 + count * 2 > polygons.length)
+              throw new RangeError("Invalid ember obstacle polygon.");
+            at += 6 + count * 2;
+          }
+          values.set(boxes, 22400);
+          values.set(ellipses, 22400 + boxes.length);
+          values.set(polygons, 22400 + boxes.length + ellipses.length);
+          boxLength = boxes.length;
+          ellipseLength = ellipses.length;
+          polygonLength = polygons.length;
+          obstacleRevision = batch.revision;
+        }
+      }
+      while (remainder + 1e-8 >= step) {
+        const time = elapsed - remainder + step;
+        remainder = Math.max(0, remainder - step);
+        const q = progressAt(time);
+        exports.births(time, linger);
+        for (let i = 0; i < 1200; i++)
+          values[11166 + i] = progressAt(values[12366 + i]);
+        exports.sample(
+          q,
+          1,
+          time,
+          linger,
+          0,
+          burnWidth,
+          region.x,
+          region.y,
+          region.width,
+          region.height,
+          Math.min(512, Math.max(1, Math.ceil(region.width / 2)))
+        );
+        exports.stepPhysics(
+          time,
+          step / 1e3,
+          ...options.gravity,
+          ...options.wind,
+          options.drag,
+          linger
+        );
+        if (options.obstacles)
+          exports.collideObstacles(
+            boxLength,
+            ellipseLength,
+            polygonLength,
+            options.restitution
+          );
+        if (options.collide)
+          for (let i = 0; i < 1200; i++) {
+            const s = 14e3 + i * 7;
+            if (values[s + 4] < 0) continue;
+            const from = [values[s + 5], values[s + 6]], to = [values[s], values[s + 1]];
+            if (from[0] === to[0] && from[1] === to[1]) continue;
+            const hit = options.collide(from, to);
+            if (!hit) continue;
+            const fraction = finite(hit.fraction, "collision.fraction", 0);
+            const nx = finite(hit.normal?.[0], "collision.normal.x"), ny = finite(hit.normal?.[1], "collision.normal.y"), length = Math.hypot(nx, ny);
+            if (fraction > 1 || length < 1e-8)
+              throw new RangeError(
+                "Ember collision requires a fraction in [0, 1] and a nonzero normal."
+              );
+            exports.collidePhysics(
+              i,
+              fraction,
+              nx / length,
+              ny / length,
+              options.restitution
+            );
+          }
+      }
+    },
+    present() {
+      if (!needsReset && !disposed) kernel().exports.presentPhysics();
+      else {
+        const { values } = kernel();
+        for (let i = 0; i < 1200; i++) values[1566 + i * 8 + 5] = -1;
+      }
+    }
+  };
+}
+export {
+  emberSimulation,
+  resolveEmbersPhysics
+};
+//# sourceMappingURL=embers-physics.js.map

package/dist/lib/transitions/embers-physics.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/transitions/embers-physics.ts"],
+  "sourcesContent": ["import type { PibblEmbersOptions } from './embers.js';\nimport { finite } from \"./capture.js\";\nimport type { lazyTransitionKernel } from \"./wasm/kernel.js\";\n/**\n * Collision information produced by an ember's physical interaction.\n *\n * @see {@link PibblEmbersPhysicsOptions}\n */\nexport interface PibblEmberCollision {\n  /** Fraction of the swept segment at impact, from zero to one. */\n  readonly fraction: number;\n  /** Outward surface normal in the receiving primitive's local coordinates. */\n  readonly normal: readonly [number, number];\n}\n/**\n * Collision and physical motion options for transition embers.\n *\n * @see {@link PibblEmberCollision}\n * @see {@link PibblEmbersOptions}\n */\nexport interface PibblEmbersPhysicsOptions {\n  /** Local units/second\u00B2. Default [0, -60]. */\n  readonly gravity?: readonly [number, number];\n  /** Target air velocity in local units/second. Default [0, -45]. */\n  readonly wind?: readonly [number, number];\n  /** Velocity damping per second. Default 4. */\n  readonly drag?: number;\n  /** Bounce coefficient, zero to one. Default 0.5. */\n  readonly restitution?: number;\n  /** Packed committed solids in receiver-local coordinates (e.g. physicsObstacles2D).\n   * Revision must change whenever data changes. Up to 8192 packed numbers.\n   * Sweeps run as one WASM batch; mutually exclusive with collide.\n   */\n  readonly obstacles?: Readonly<{\n    /**\n     * Reads the current committed values required by this integration. See\n     * {@link PibblEmbersPhysicsOptions}.\n     * @returns The current obstacle revision and packed geometry arrays.\n     */\n    read(): Readonly<{\n      /**\n       * Revision used to detect changes to the underlying state or geometry. See\n       * {@link PibblEmbersPhysicsOptions}.\n       */\n      revision: number;\n      /** Packed box obstacle data consumed by the simulation. See {@link PibblEmbersPhysicsOptions}. */\n      boxes: Float64Array;\n      /**\n       * Packed ellipse obstacle data consumed by the simulation. See\n       * {@link PibblEmbersPhysicsOptions}.\n       */\n      ellipses: Float64Array;\n      /**\n       * Packed polygon obstacle data consumed by the simulation. See\n       * {@link PibblEmbersPhysicsOptions}.\n       */\n      polygons: Float64Array;\n    }>;\n  }>;\n  /**\n   * Synchronous point sweep, called in Advance. Return the closest hit, if any.\n   * @param from - Previous particle position.\n   * @param to - Proposed particle position.\n   * @returns Collision information, or undefined when motion is unobstructed. See\n   * {@link PibblEmberCollision} .\n   */\n  readonly collide?: (\n    from: readonly [number, number],\n    to: readonly [number, number],\n  ) => PibblEmberCollision | undefined;\n}\nexport function resolveEmbersPhysics(options: PibblEmbersPhysicsOptions) {\n  const vector = (value: readonly [number, number], name: string) =>\n    Object.freeze([\n      finite(value[0], `${name}.x`),\n      finite(value[1], `${name}.y`),\n    ] as const);\n  const restitution = finite(\n    options.restitution ?? 0.5,\n    \"physics.restitution\",\n    0,\n  );\n  if (restitution > 1)\n    throw new RangeError(\"physics.restitution must be between zero and one.\");\n  if (options.collide !== undefined && typeof options.collide !== \"function\")\n    throw new TypeError(\"physics.collide must be a synchronous function.\");\n  if (\n    options.obstacles &&\n    (typeof options.obstacles.read !== \"function\" || options.collide)\n  )\n    throw new TypeError(\n      \"physics.obstacles requires read() and cannot be combined with collide.\",\n    );\n  return Object.freeze({\n    obstacles: options.obstacles,\n    gravity: vector(options.gravity ?? [0, -60], \"physics.gravity\"),\n    wind: vector(options.wind ?? [0, -45], \"physics.wind\"),\n    drag: finite(options.drag ?? 4, \"physics.drag\", 0),\n    restitution,\n    collide: options.collide,\n  });\n}\ntype Kernel = ReturnType<ReturnType<typeof lazyTransitionKernel>>;\nexport function emberSimulation(\n  kernel: Kernel,\n  options: ReturnType<typeof resolveEmbersPhysics>,\n  region: Readonly<{ x: number; y: number; width: number; height: number }>,\n  linger: number,\n  burnWidth: number,\n) {\n  let previous = 0,\n    remainder = 0,\n    needsReset = true,\n    disposed = false;\n  const step = 1000 / 60;\n  let obstacleRevision: number | undefined;\n  let boxLength = 0,\n    ellipseLength = 0,\n    polygonLength = 0;\n  return {\n    reset() {\n      previous = 0;\n      remainder = 0;\n      needsReset = true;\n    },\n    get disposed() {\n      return disposed;\n    },\n    dispose() {\n      disposed = true;\n      kernel.dispose();\n    },\n    advance(elapsed: number, progressAt: (time: number) => number) {\n      if (disposed || elapsed <= previous) return;\n      const { exports, values } = kernel();\n      if (needsReset) {\n        exports.resetPhysics!();\n        needsReset = false;\n      }\n      remainder += Math.min(elapsed - previous, step * 4);\n      previous = elapsed;\n      if (remainder + 1e-8 >= step && options.obstacles) {\n        const batch = options.obstacles.read();\n        if (batch.revision !== obstacleRevision) {\n          const { boxes, ellipses, polygons } = batch;\n          if (\n            !Number.isFinite(batch.revision) ||\n            boxes.length % 10 ||\n            ellipses.length % 10 ||\n            boxes.length + ellipses.length + polygons.length > 8192\n          )\n            throw new RangeError(\n              \"Invalid ember obstacle batch or capacity exceeded (8192 numbers).\",\n            );\n          for (const packed of [boxes, ellipses, polygons])\n            for (const value of packed)\n              if (!Number.isFinite(value))\n                throw new RangeError(\"Ember obstacles must be finite.\");\n          for (const packed of [boxes, ellipses])\n            for (let i = 0; i < packed.length; i += 10)\n              if (packed[i + 2]! <= 0 || packed[i + 3]! <= 0)\n                throw new RangeError(\n                  \"Ember obstacle extents must be positive.\",\n                );\n          for (let at = 0; at < polygons.length;) {\n            const count = polygons[at]!;\n            if (\n              !Number.isInteger(count) ||\n              count < 3 ||\n              at + 6 + count * 2 > polygons.length\n            )\n              throw new RangeError(\"Invalid ember obstacle polygon.\");\n            at += 6 + count * 2;\n          }\n          values.set(boxes, 22400);\n          values.set(ellipses, 22400 + boxes.length);\n          values.set(polygons, 22400 + boxes.length + ellipses.length);\n          boxLength = boxes.length;\n          ellipseLength = ellipses.length;\n          polygonLength = polygons.length;\n          obstacleRevision = batch.revision;\n        }\n      }\n      while (remainder + 1e-8 >= step) {\n        const time = elapsed - remainder + step;\n        remainder = Math.max(0, remainder - step);\n        const q = progressAt(time);\n        exports.births!(time, linger);\n        for (let i = 0; i < 1200; i++)\n          values[11166 + i] = progressAt(values[12366 + i]!);\n        exports.sample!(\n          q,\n          1,\n          time,\n          linger,\n          0,\n          burnWidth,\n          region.x,\n          region.y,\n          region.width,\n          region.height,\n          Math.min(512, Math.max(1, Math.ceil(region.width / 2))),\n        );\n        exports.stepPhysics!(\n          time,\n          step / 1000,\n          ...options.gravity,\n          ...options.wind,\n          options.drag,\n          linger,\n        );\n        if (options.obstacles)\n          exports.collideObstacles!(\n            boxLength,\n            ellipseLength,\n            polygonLength,\n            options.restitution,\n          );\n        if (options.collide)\n          for (let i = 0; i < 1200; i++) {\n            const s = 14000 + i * 7;\n            if (values[s + 4]! < 0) continue;\n            const from = [values[s + 5]!, values[s + 6]!] as const,\n              to = [values[s]!, values[s + 1]!] as const;\n            if (from[0] === to[0] && from[1] === to[1]) continue;\n            const hit = options.collide(from, to);\n            if (!hit) continue;\n            const fraction = finite(hit.fraction, \"collision.fraction\", 0);\n            const nx = finite(hit.normal?.[0], \"collision.normal.x\"),\n              ny = finite(hit.normal?.[1], \"collision.normal.y\"),\n              length = Math.hypot(nx, ny);\n            if (fraction > 1 || length < 1e-8)\n              throw new RangeError(\n                \"Ember collision requires a fraction in [0, 1] and a nonzero normal.\",\n              );\n            exports.collidePhysics!(\n              i,\n              fraction,\n              nx / length,\n              ny / length,\n              options.restitution,\n            );\n          }\n      }\n    },\n    present() {\n      if (!needsReset && !disposed) kernel().exports.presentPhysics!();\n      else {\n        const { values } = kernel();\n        for (let i = 0; i < 1200; i++) values[1566 + i * 8 + 5] = -1;\n      }\n    },\n  };\n}\n"],
+  "mappings": "AACA,SAAS,cAAc;AAsEhB,SAAS,qBAAqB,SAAoC;AACvE,QAAM,SAAS,CAAC,OAAkC,SAChD,OAAO,OAAO;AAAA,IACZ,OAAO,MAAM,CAAC,GAAG,GAAG,IAAI,IAAI;AAAA,IAC5B,OAAO,MAAM,CAAC,GAAG,GAAG,IAAI,IAAI;AAAA,EAC9B,CAAU;AACZ,QAAM,cAAc;AAAA,IAClB,QAAQ,eAAe;AAAA,IACvB;AAAA,IACA;AAAA,EACF;AACA,MAAI,cAAc;AAChB,UAAM,IAAI,WAAW,mDAAmD;AAC1E,MAAI,QAAQ,YAAY,UAAa,OAAO,QAAQ,YAAY;AAC9D,UAAM,IAAI,UAAU,iDAAiD;AACvE,MACE,QAAQ,cACP,OAAO,QAAQ,UAAU,SAAS,cAAc,QAAQ;AAEzD,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AACF,SAAO,OAAO,OAAO;AAAA,IACnB,WAAW,QAAQ;AAAA,IACnB,SAAS,OAAO,QAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,iBAAiB;AAAA,IAC9D,MAAM,OAAO,QAAQ,QAAQ,CAAC,GAAG,GAAG,GAAG,cAAc;AAAA,IACrD,MAAM,OAAO,QAAQ,QAAQ,GAAG,gBAAgB,CAAC;AAAA,IACjD;AAAA,IACA,SAAS,QAAQ;AAAA,EACnB,CAAC;AACH;AAEO,SAAS,gBACd,QACA,SACA,QACA,QACA,WACA;AACA,MAAI,WAAW,GACb,YAAY,GACZ,aAAa,MACb,WAAW;AACb,QAAM,OAAO,MAAO;AACpB,MAAI;AACJ,MAAI,YAAY,GACd,gBAAgB,GAChB,gBAAgB;AAClB,SAAO;AAAA,IACL,QAAQ;AACN,iBAAW;AACX,kBAAY;AACZ,mBAAa;AAAA,IACf;AAAA,IACA,IAAI,WAAW;AACb,aAAO;AAAA,IACT;AAAA,IACA,UAAU;AACR,iBAAW;AACX,aAAO,QAAQ;AAAA,IACjB;AAAA,IACA,QAAQ,SAAiB,YAAsC;AAC7D,UAAI,YAAY,WAAW,SAAU;AACrC,YAAM,EAAE,SAAS,OAAO,IAAI,OAAO;AACnC,UAAI,YAAY;AACd,gBAAQ,aAAc;AACtB,qBAAa;AAAA,MACf;AACA,mBAAa,KAAK,IAAI,UAAU,UAAU,OAAO,CAAC;AAClD,iBAAW;AACX,UAAI,YAAY,QAAQ,QAAQ,QAAQ,WAAW;AACjD,cAAM,QAAQ,QAAQ,UAAU,KAAK;AACrC,YAAI,MAAM,aAAa,kBAAkB;AACvC,gBAAM,EAAE,OAAO,UAAU,SAAS,IAAI;AACtC,cACE,CAAC,OAAO,SAAS,MAAM,QAAQ,KAC/B,MAAM,SAAS,MACf,SAAS,SAAS,MAClB,MAAM,SAAS,SAAS,SAAS,SAAS,SAAS;AAEnD,kBAAM,IAAI;AAAA,cACR;AAAA,YACF;AACF,qBAAW,UAAU,CAAC,OAAO,UAAU,QAAQ;AAC7C,uBAAW,SAAS;AAClB,kBAAI,CAAC,OAAO,SAAS,KAAK;AACxB,sBAAM,IAAI,WAAW,iCAAiC;AAC5D,qBAAW,UAAU,CAAC,OAAO,QAAQ;AACnC,qBAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,kBAAI,OAAO,IAAI,CAAC,KAAM,KAAK,OAAO,IAAI,CAAC,KAAM;AAC3C,sBAAM,IAAI;AAAA,kBACR;AAAA,gBACF;AACN,mBAAS,KAAK,GAAG,KAAK,SAAS,UAAS;AACtC,kBAAM,QAAQ,SAAS,EAAE;AACzB,gBACE,CAAC,OAAO,UAAU,KAAK,KACvB,QAAQ,KACR,KAAK,IAAI,QAAQ,IAAI,SAAS;AAE9B,oBAAM,IAAI,WAAW,iCAAiC;AACxD,kBAAM,IAAI,QAAQ;AAAA,UACpB;AACA,iBAAO,IAAI,OAAO,KAAK;AACvB,iBAAO,IAAI,UAAU,QAAQ,MAAM,MAAM;AACzC,iBAAO,IAAI,UAAU,QAAQ,MAAM,SAAS,SAAS,MAAM;AAC3D,sBAAY,MAAM;AAClB,0BAAgB,SAAS;AACzB,0BAAgB,SAAS;AACzB,6BAAmB,MAAM;AAAA,QAC3B;AAAA,MACF;AACA,aAAO,YAAY,QAAQ,MAAM;AAC/B,cAAM,OAAO,UAAU,YAAY;AACnC,oBAAY,KAAK,IAAI,GAAG,YAAY,IAAI;AACxC,cAAM,IAAI,WAAW,IAAI;AACzB,gBAAQ,OAAQ,MAAM,MAAM;AAC5B,iBAAS,IAAI,GAAG,IAAI,MAAM;AACxB,iBAAO,QAAQ,CAAC,IAAI,WAAW,OAAO,QAAQ,CAAC,CAAE;AACnD,gBAAQ;AAAA,UACN;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA,OAAO;AAAA,UACP,OAAO;AAAA,UACP,OAAO;AAAA,UACP,OAAO;AAAA,UACP,KAAK,IAAI,KAAK,KAAK,IAAI,GAAG,KAAK,KAAK,OAAO,QAAQ,CAAC,CAAC,CAAC;AAAA,QACxD;AACA,gBAAQ;AAAA,UACN;AAAA,UACA,OAAO;AAAA,UACP,GAAG,QAAQ;AAAA,UACX,GAAG,QAAQ;AAAA,UACX,QAAQ;AAAA,UACR;AAAA,QACF;AACA,YAAI,QAAQ;AACV,kBAAQ;AAAA,YACN;AAAA,YACA;AAAA,YACA;AAAA,YACA,QAAQ;AAAA,UACV;AACF,YAAI,QAAQ;AACV,mBAAS,IAAI,GAAG,IAAI,MAAM,KAAK;AAC7B,kBAAM,IAAI,OAAQ,IAAI;AACtB,gBAAI,OAAO,IAAI,CAAC,IAAK,EAAG;AACxB,kBAAM,OAAO,CAAC,OAAO,IAAI,CAAC,GAAI,OAAO,IAAI,CAAC,CAAE,GAC1C,KAAK,CAAC,OAAO,CAAC,GAAI,OAAO,IAAI,CAAC,CAAE;AAClC,gBAAI,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,EAAG;AAC5C,kBAAM,MAAM,QAAQ,QAAQ,MAAM,EAAE;AACpC,gBAAI,CAAC,IAAK;AACV,kBAAM,WAAW,OAAO,IAAI,UAAU,sBAAsB,CAAC;AAC7D,kBAAM,KAAK,OAAO,IAAI,SAAS,CAAC,GAAG,oBAAoB,GACrD,KAAK,OAAO,IAAI,SAAS,CAAC,GAAG,oBAAoB,GACjD,SAAS,KAAK,MAAM,IAAI,EAAE;AAC5B,gBAAI,WAAW,KAAK,SAAS;AAC3B,oBAAM,IAAI;AAAA,gBACR;AAAA,cACF;AACF,oBAAQ;AAAA,cACN;AAAA,cACA;AAAA,cACA,KAAK;AAAA,cACL,KAAK;AAAA,cACL,QAAQ;AAAA,YACV;AAAA,UACF;AAAA,MACJ;AAAA,IACF;AAAA,IACA,UAAU;AACR,UAAI,CAAC,cAAc,CAAC,SAAU,QAAO,EAAE,QAAQ,eAAgB;AAAA,WAC1D;AACH,cAAM,EAAE,OAAO,IAAI,OAAO;AAC1B,iBAAS,IAAI,GAAG,IAAI,MAAM,IAAK,QAAO,OAAO,IAAI,IAAI,CAAC,IAAI;AAAA,MAC5D;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/lib/transitions/embers.d.ts

@@ -0,0 +1,67 @@
+import { type PibblEmbersPhysicsOptions } from './embers-physics.js';
+import { type PibblTransitionEffect } from './fade.js';
+/**
+ * Appearance, motion, and timing controls for an ember visibility transition.
+ *
+ * @see {@link PibblEmbersPhysicsOptions}
+ * @see {@link embers}
+ */
+export interface PibblEmbersOptions {
+    /** Local coordinates enclosing the subject; the burn travels upward through this area. */
+    readonly region: Readonly<{
+        /**
+         * Horizontal coordinate or displacement in the containing coordinate system. See
+         * {@link PibblEmbersOptions}.
+         */
+        x: number;
+        /**
+         * Vertical coordinate or displacement in the containing coordinate system. See
+         * {@link PibblEmbersOptions}.
+         */
+        y: number;
+        /**
+         * Horizontal extent in the units of the containing geometry or surface. See
+         * {@link PibblEmbersOptions}.
+         */
+        width: number;
+        /**
+         * Vertical extent in the units of the containing geometry or surface. See
+         * {@link PibblEmbersOptions}.
+         */
+        height: number;
+    }>;
+    /**
+     * Depth of the darkened char region along the ember transition boundary. See
+     * {@link PibblEmbersOptions}.
+     */
+    readonly charDepth?: number;
+    /**
+     * Width of the glowing burn region along the transition boundary. See {@link PibblEmbersOptions}.
+     */
+    readonly burnWidth?: number;
+    /** Horizontal drift in local units; negative blows left. */
+    readonly wind?: number;
+    /**
+     * Seed used for deterministic sampling or simulation initialization. See
+     * {@link PibblEmbersOptions}.
+     */
+    readonly seed?: number;
+    /**
+     * Maximum airborne particle lifetime in milliseconds; completion includes this tail. Default
+     * 700.
+     */
+    readonly linger?: number;
+    /** Opt-in local force simulation and collision. Requires a positive linger. */
+    readonly physics?: PibblEmbersPhysicsOptions;
+}
+/**
+ * A seeded burn/char front over one captured subtree, with outward drifting fragments.
+ *
+ * @param options - Ember emission, motion, appearance, and optional collision settings. See
+ * {@link PibblEmbersOptions} .
+ * @returns An ember transition effect. See {@link PibblTransitionEffect}.
+ *
+ * @see {@link PibblEmbersOptions}
+ * @see {@link PibblTransitionEffect}
+ */
+export declare function embers(options: PibblEmbersOptions): PibblTransitionEffect;

package/dist/lib/transitions/embers.js

@@ -0,0 +1,196 @@
+import { emberSimulation, resolveEmbersPhysics } from "./embers-physics.js";
+import { lazyTransitionKernel } from "./wasm/kernel.js";
+import { bytes } from "./wasm/embers-bytes.js";
+const createKernel = lazyTransitionKernel(bytes, 2);
+const createPhysicsKernel = lazyTransitionKernel(bytes, 4);
+import { opacity } from "../../filters/native.js";
+import { filterBoundaryExecutor } from "../../filters/filter-executor.js";
+import { GLOBAL_STATE } from "../global-state.js";
+import { getOptionalService } from "../optional-services.js";
+import { PIBBL_FILTER_EXECUTOR } from "../style/filter-types.js";
+import { defineTransitionEffect } from "./fade.js";
+const SCRATCH = /* @__PURE__ */ Symbol("pibbl.transition.embers");
+class EmberSurfaces {
+  constructor(instance) {
+    this.instance = instance;
+  }
+  instance;
+  surfaces = [];
+  used = false;
+  committed = false;
+  beginRender() {
+    this.used = false;
+  }
+  endRender(success) {
+    if (success && this.used) {
+      this.committed = true;
+      return;
+    }
+    if (success || !this.committed) this.dispose();
+  }
+  context(index, width, height) {
+    const canvas = this.surfaces[index] ??= new OffscreenCanvas(width, height);
+    if (canvas.width !== width) canvas.width = width;
+    if (canvas.height !== height) canvas.height = height;
+    const context = canvas.getContext("2d");
+    if (!context) throw new Error("Embers requires a Canvas 2D surface.");
+    context.reset();
+    return context;
+  }
+  dispose() {
+    for (const surface of this.surfaces) {
+      surface.width = 0;
+      surface.height = 0;
+    }
+    this.surfaces = [];
+    this.instance.optionalServices.delete(SCRATCH);
+  }
+}
+const clamp = (value) => Math.max(0, Math.min(1, value));
+function embers(options) {
+  const region = Object.freeze({ ...options.region });
+  const charDepth = options.charDepth ?? 65, burnWidth = options.burnWidth ?? 12;
+  const wind = options.wind ?? 110, seed = options.seed ?? 0, linger = options.linger ?? 700;
+  for (const [name, value] of Object.entries({ ...region, charDepth, burnWidth, wind, seed, linger })) {
+    if (!Number.isFinite(value)) throw new RangeError(`embers ${name} must be finite.`);
+  }
+  if (!(region.width > 0 && region.height > 0) || charDepth < 0 || burnWidth < 0 || linger < 0) throw new RangeError("embers requires a positive region and nonnegative charDepth/burnWidth/linger.");
+  const physics = options.physics === void 0 ? void 0 : resolveEmbersPhysics(options.physics);
+  if (physics && linger === 0) throw new RangeError("Ember physics requires a positive linger.");
+  const sampler = (kernel, simulation) => (q, phase, frame) => {
+    if (simulation?.disposed) return [opacity({ amount: 0 })];
+    if ((!frame.active || !linger) && q === 1) return [];
+    if ((!frame.active || !linger) && q === 0) return [opacity({ amount: 0 })];
+    const executor = {
+      render: filterBoundaryExecutor.render,
+      prepare() {
+        return {
+          executor: filterBoundaryExecutor,
+          reverseInfluence: (output) => ({ ...output }),
+          process(source, windows) {
+            const instance = GLOBAL_STATE.currentPibblInstance;
+            if (!instance) throw new Error("Embers requires an active Pibbl instance.");
+            const scratch = getOptionalService(instance, SCRATCH, () => new EmberSurfaces(instance));
+            scratch.used = true;
+            const c = scratch.context(0, source.width, source.height);
+            const tint = scratch.context(1, source.width, source.height);
+            const matrix = windows.source.renderTransform;
+            const roughness = Math.min(5, region.height * 0.015);
+            const front = region.y + region.height + roughness * 2 - q * (region.height + roughness * 4);
+            const segments = Math.min(512, Math.max(1, Math.ceil(region.width / 2)));
+            const { exports, values } = kernel();
+            exports.births(frame.elapsed, linger);
+            if (linger) for (let i = 0; i < 1200; i++) values[11166 + i] = frame.progressAt(values[12366 + i]);
+            exports.sample(q, phase === "enter" ? 1 : 0, frame.elapsed, linger, wind, burnWidth, region.x, region.y, region.width, region.height, segments);
+            simulation?.present();
+            const bandPath = (depth) => {
+              c.beginPath();
+              for (let i = 0; i <= segments; i++) c.lineTo(values[i * 2], values[i * 2 + 1]);
+              for (let i = segments; i >= 0; i--) c.lineTo(values[i * 2], values[i * 2 + 1] + depth);
+              c.closePath();
+            };
+            const path = (depth) => {
+              c.beginPath();
+              c.moveTo(region.x, region.y + region.height + charDepth + 40);
+              for (let i = 0; i <= segments; i++) c.lineTo(values[i * 2], values[i * 2 + 1] + depth);
+              c.lineTo(region.x + region.width, values[segments * 2 + 1] + depth);
+              c.lineTo(region.x + region.width, region.y + region.height + charDepth + 40);
+              c.closePath();
+            };
+            if (q > 0) {
+              c.save();
+              c.setTransform(matrix);
+              path(0);
+              c.clip();
+              c.setTransform(1, 0, 0, 1, 0, 0);
+              c.drawImage(source, 0, 0);
+              c.restore();
+              c.setTransform(matrix);
+              c.globalCompositeOperation = "source-atop";
+              const strength = clamp((1 - q) / 0.12);
+              for (let band = 48; band > 0 && charDepth > 0; band--) {
+                const depth = charDepth * band / 48;
+                c.save();
+                bandPath(depth);
+                c.clip();
+                c.fillStyle = `rgba(27,16,12,${0.12 * strength})`;
+                c.fillRect(region.x, front - roughness * 2, region.width, depth + roughness * 4);
+                c.restore();
+              }
+              if (burnWidth > 0) {
+                c.save();
+                c.globalAlpha = strength;
+                c.filter = `blur(${Math.min(3, burnWidth * 0.16) * windows.density}px)`;
+                bandPath(burnWidth * 1.45);
+                c.fillStyle = "#8d2a0c";
+                c.fill();
+                c.filter = "none";
+                bandPath(burnWidth * 0.85);
+                c.fillStyle = "#d9510c";
+                c.fill();
+                bandPath(burnWidth * 0.48);
+                c.fillStyle = "#ff942c";
+                c.fill();
+                bandPath(burnWidth * 0.2);
+                c.fillStyle = "#ffd27c";
+                c.fill();
+                c.restore();
+              }
+              for (let i = 0; i < 180; i++) {
+                const offset = 1026 + i * 3;
+                const x = values[offset], y = values[offset + 1], r = values[offset + 2];
+                const heat = c.createRadialGradient(x, y, 0, x, y, r);
+                heat.addColorStop(0, `rgba(255,222,145,${strength * 0.5})`);
+                heat.addColorStop(0.3, `rgba(247,92,15,${strength * 0.4})`);
+                heat.addColorStop(1, "rgba(100,20,0,0)");
+                c.fillStyle = heat;
+                c.fillRect(x - r, y - r, r * 2, r * 2);
+              }
+            }
+            c.setTransform(matrix);
+            tint.drawImage(source, 0, 0);
+            tint.globalCompositeOperation = "source-in";
+            tint.fillStyle = "#fff4cf";
+            tint.fillRect(0, 0, source.width, source.height);
+            const ash = scratch.context(2, source.width, source.height);
+            ash.drawImage(source, 0, 0);
+            ash.globalCompositeOperation = "source-in";
+            ash.fillStyle = "#766b60";
+            ash.fillRect(0, 0, source.width, source.height);
+            c.globalCompositeOperation = "source-over";
+            for (let i = 0; i < 1200; i++) {
+              const offset = 1566 + i * 8, alpha = values[offset + 5];
+              if (alpha < 0) continue;
+              const x = values[offset], y = values[offset + 1], size = values[offset + 2];
+              const sample = new DOMPoint(x, y).matrixTransform(matrix);
+              const dx = values[offset + 3], dy = values[offset + 4], age = values[offset + 7];
+              c.save();
+              c.globalAlpha = alpha;
+              c.translate(x + dx, y + dy);
+              c.rotate(values[offset + 6]);
+              const cooling = clamp((age - 0.2) / 0.8);
+              c.globalAlpha = alpha * (1 - cooling);
+              c.drawImage(tint.canvas, sample.x, sample.y, size * windows.density, size * windows.density, -size / 2, -size / 2, size, size);
+              if (cooling > 0) {
+                c.globalAlpha = alpha * cooling;
+                c.drawImage(ash.canvas, sample.x, sample.y, size * windows.density, size * windows.density, -size / 2, -size / 2, size, size);
+              }
+              c.restore();
+            }
+            return c.canvas.transferToImageBitmap();
+          }
+        };
+      }
+    };
+    return [Object.freeze({ [PIBBL_FILTER_EXECUTOR]: executor })];
+  };
+  return defineTransitionEffect(sampler(createKernel(seed)), linger, physics ? () => {
+    const kernel = createPhysicsKernel(seed);
+    const simulation = emberSimulation(kernel, physics, region, linger, burnWidth);
+    return { sample: sampler(kernel, simulation), advance: simulation.advance, reset: simulation.reset, dispose: simulation.dispose };
+  } : void 0);
+}
+export {
+  embers
+};
+//# sourceMappingURL=embers.js.map

package/dist/lib/transitions/embers.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/transitions/embers.ts"],
+  "sourcesContent": ["import { emberSimulation, resolveEmbersPhysics, type PibblEmbersPhysicsOptions } from './embers-physics.js';\nimport { lazyTransitionKernel } from './wasm/kernel.js';\nimport { bytes } from './wasm/embers-bytes.js';\nconst createKernel = lazyTransitionKernel(bytes, 2);\nconst createPhysicsKernel = lazyTransitionKernel(bytes, 4);\nimport { opacity } from '../../filters/native.js';\nimport { filterBoundaryExecutor, type CustomPreparedFilter } from '../../filters/filter-executor.js';\nimport { GLOBAL_STATE } from '../global-state.js';\nimport { getOptionalService } from '../optional-services.js';\nimport { PIBBL_FILTER_EXECUTOR, type PibblFilterExecutor } from '../style/filter-types.js';\nimport type { PibblInstance } from '../types.js';\nimport { defineTransitionEffect, type PibblTransitionEffect } from './fade.js';\n\n/**\n * Appearance, motion, and timing controls for an ember visibility transition.\n *\n * @see {@link PibblEmbersPhysicsOptions}\n * @see {@link embers}\n */\nexport interface PibblEmbersOptions {\n  /** Local coordinates enclosing the subject; the burn travels upward through this area. */\n  readonly region: Readonly<{\n    /**\n     * Horizontal coordinate or displacement in the containing coordinate system. See\n     * {@link PibblEmbersOptions}.\n     */\n    x: number;\n    /**\n     * Vertical coordinate or displacement in the containing coordinate system. See\n     * {@link PibblEmbersOptions}.\n     */\n    y: number;\n    /**\n     * Horizontal extent in the units of the containing geometry or surface. See\n     * {@link PibblEmbersOptions}.\n     */\n    width: number;\n    /**\n     * Vertical extent in the units of the containing geometry or surface. See\n     * {@link PibblEmbersOptions}.\n     */\n    height: number;\n  }>;\n  /**\n   * Depth of the darkened char region along the ember transition boundary. See\n   * {@link PibblEmbersOptions}.\n   */\n  readonly charDepth?: number;\n  /**\n   * Width of the glowing burn region along the transition boundary. See {@link PibblEmbersOptions}.\n   */\n  readonly burnWidth?: number;\n  /** Horizontal drift in local units; negative blows left. */\n  readonly wind?: number;\n  /**\n   * Seed used for deterministic sampling or simulation initialization. See\n   * {@link PibblEmbersOptions}.\n   */\n  readonly seed?: number;\n  /**\n   * Maximum airborne particle lifetime in milliseconds; completion includes this tail. Default\n   * 700.\n   */\n  readonly linger?: number;\n  /** Opt-in local force simulation and collision. Requires a positive linger. */\n  readonly physics?: PibblEmbersPhysicsOptions;\n}\nconst SCRATCH = Symbol('pibbl.transition.embers');\nclass EmberSurfaces {\n  private surfaces: OffscreenCanvas[] = [];\n  used = false;\n  private committed = false;\n  constructor(private readonly instance: PibblInstance) {}\n  beginRender(): void { this.used = false; }\n  endRender(success: boolean): void {\n    if (success && this.used) { this.committed = true; return; }\n    if (success || !this.committed) this.dispose();\n  }\n  context(index: number, width: number, height: number): OffscreenCanvasRenderingContext2D {\n    const canvas = this.surfaces[index] ??= new OffscreenCanvas(width, height);\n    if (canvas.width !== width) canvas.width = width;\n    if (canvas.height !== height) canvas.height = height;\n    const context = canvas.getContext('2d');\n    if (!context) throw new Error('Embers requires a Canvas 2D surface.');\n    context.reset();\n    return context;\n  }\n  dispose(): void {\n    for (const surface of this.surfaces) { surface.width = 0; surface.height = 0; }\n    this.surfaces = [];\n    this.instance.optionalServices.delete(SCRATCH);\n  }\n}\nconst clamp = (value: number) => Math.max(0, Math.min(1, value));\n\n/**\n * A seeded burn/char front over one captured subtree, with outward drifting fragments.\n *\n * @param options - Ember emission, motion, appearance, and optional collision settings. See\n * {@link PibblEmbersOptions} .\n * @returns An ember transition effect. See {@link PibblTransitionEffect}.\n *\n * @see {@link PibblEmbersOptions}\n * @see {@link PibblTransitionEffect}\n */\nexport function embers(options: PibblEmbersOptions): PibblTransitionEffect {\n  const region = Object.freeze({ ...options.region });\n  const charDepth = options.charDepth ?? 65, burnWidth = options.burnWidth ?? 12;\n  const wind = options.wind ?? 110, seed = options.seed ?? 0, linger = options.linger ?? 700;\n  for (const [name, value] of Object.entries({ ...region, charDepth, burnWidth, wind, seed, linger })) {\n    if (!Number.isFinite(value)) throw new RangeError(`embers ${name} must be finite.`);\n  }\n  if (!(region.width > 0 && region.height > 0) || charDepth < 0 || burnWidth < 0 || linger < 0) throw new RangeError('embers requires a positive region and nonnegative charDepth/burnWidth/linger.');\n  const physics = options.physics === undefined ? undefined : resolveEmbersPhysics(options.physics);\n  if (physics && linger === 0) throw new RangeError('Ember physics requires a positive linger.');\n  const sampler = (kernel: ReturnType<typeof createKernel>, simulation?: ReturnType<typeof emberSimulation>): import('./fade.js').TransitionSampler => (q, phase, frame) => {\n    if (simulation?.disposed) return [opacity({ amount: 0 })];\n    if ((!frame.active || !linger) && q === 1) return [];\n    if ((!frame.active || !linger) && q === 0) return [opacity({ amount: 0 })];\n    const executor: PibblFilterExecutor = {\n      render: filterBoundaryExecutor.render,\n      prepare(): CustomPreparedFilter {\n        return {\n          executor: filterBoundaryExecutor,\n          reverseInfluence: output => ({ ...output }),\n          process(source, windows) {\n            const instance = GLOBAL_STATE.currentPibblInstance;\n            if (!instance) throw new Error('Embers requires an active Pibbl instance.');\n            const scratch = getOptionalService(instance, SCRATCH, () => new EmberSurfaces(instance));\n            scratch.used = true;\n            const c = scratch.context(0, source.width, source.height);\n            const tint = scratch.context(1, source.width, source.height);\n            const matrix = windows.source.renderTransform;\n            const roughness = Math.min(5, region.height * .015);\n            const front = region.y + region.height + roughness * 2 - q * (region.height + roughness * 4);\n            const segments = Math.min(512, Math.max(1, Math.ceil(region.width / 2)));\n            const { exports, values } = kernel();\n            exports.births!(frame.elapsed, linger);\n            // The controller remains the source of truth for reversal history.\n            if (linger) for (let i = 0; i < 1200; i++) values[11166 + i] = frame.progressAt(values[12366 + i]!);\n            exports.sample!(q, phase === 'enter' ? 1 : 0, frame.elapsed, linger, wind, burnWidth, region.x, region.y, region.width, region.height, segments);\n            simulation?.present();\n            const bandPath = (depth: number) => {\n              c.beginPath();\n              for (let i = 0; i <= segments; i++) c.lineTo(values[i * 2]!, values[i * 2 + 1]!);\n              for (let i = segments; i >= 0; i--) c.lineTo(values[i * 2]!, values[i * 2 + 1]! + depth);\n              c.closePath();\n            };\n            const path = (depth: number) => {\n              c.beginPath(); c.moveTo(region.x, region.y + region.height + charDepth + 40);\n              for (let i = 0; i <= segments; i++) c.lineTo(values[i * 2]!, values[i * 2 + 1]! + depth);\n              c.lineTo(region.x + region.width, values[segments * 2 + 1]! + depth);\n              c.lineTo(region.x + region.width, region.y + region.height + charDepth + 40); c.closePath();\n            };\n            if (q > 0) {\n            c.save(); c.setTransform(matrix); path(0); c.clip();\n            c.setTransform(1, 0, 0, 1, 0, 0); c.drawImage(source, 0, 0); c.restore();\n            c.setTransform(matrix); c.globalCompositeOperation = 'source-atop';\n            const strength = clamp((1 - q) / .12);\n            // Continuous overlapping contour bands avoid vertical striping at the hot edge.\n            for (let band = 48; band > 0 && charDepth > 0; band--) {\n              const depth = charDepth * band / 48;\n              c.save();\n              bandPath(depth); c.clip();\n              c.fillStyle = `rgba(27,16,12,${.12 * strength})`;\n              c.fillRect(region.x, front - roughness * 2, region.width, depth + roughness * 4);\n              c.restore();\n            }\n            // A connected thermal front carries the light; individual coals only\n            // add texture. Source-atop preserves holes in the captured silhouette.\n            if (burnWidth > 0) {\n              c.save(); c.globalAlpha = strength;\n              c.filter = `blur(${Math.min(3, burnWidth * .16) * windows.density}px)`;\n              bandPath(burnWidth * 1.45); c.fillStyle = '#8d2a0c'; c.fill();\n              c.filter = 'none';\n              bandPath(burnWidth * .85); c.fillStyle = '#d9510c'; c.fill();\n              bandPath(burnWidth * .48); c.fillStyle = '#ff942c'; c.fill();\n              bandPath(burnWidth * .2); c.fillStyle = '#ffd27c'; c.fill();\n              c.restore();\n            }\n            for (let i = 0; i < 180; i++) {\n              const offset = 1026 + i * 3;\n              const x = values[offset]!, y = values[offset + 1]!, r = values[offset + 2]!;\n              const heat = c.createRadialGradient(x, y, 0, x, y, r);\n              heat.addColorStop(0, `rgba(255,222,145,${strength * .5})`);\n              heat.addColorStop(.3, `rgba(247,92,15,${strength * .4})`);\n              heat.addColorStop(1, 'rgba(100,20,0,0)');\n              c.fillStyle = heat; c.fillRect(x - r, y - r, r * 2, r * 2);\n            }\n            }\n            c.setTransform(matrix);\n            // Tint a copy of the subject once. Sampling small patches means transparent\n            // gaps cannot emit particles, without reading pixels back from the canvas.\n            tint.drawImage(source, 0, 0); tint.globalCompositeOperation = 'source-in';\n            tint.fillStyle = '#fff4cf'; tint.fillRect(0, 0, source.width, source.height);\n            const ash = scratch.context(2, source.width, source.height);\n            ash.drawImage(source, 0, 0); ash.globalCompositeOperation = 'source-in';\n            ash.fillStyle = '#766b60'; ash.fillRect(0, 0, source.width, source.height);\n            c.globalCompositeOperation = 'source-over';\n            for (let i = 0; i < 1200; i++) {\n              const offset = 1566 + i * 8, alpha = values[offset + 5]!;\n              if (alpha < 0) continue;\n              const x = values[offset]!, y = values[offset + 1]!, size = values[offset + 2]!;\n              const sample = new DOMPoint(x, y).matrixTransform(matrix);\n              const dx = values[offset + 3]!, dy = values[offset + 4]!, age = values[offset + 7]!;\n              c.save(); c.globalAlpha = alpha;\n              c.translate(x + dx, y + dy); c.rotate(values[offset + 6]!);\n              // Hot fragments cool continuously into dim ash rather than switching off.\n              const cooling = clamp((age - .2) / .8);\n              c.globalAlpha = alpha * (1 - cooling);\n              c.drawImage(tint.canvas, sample.x, sample.y, size * windows.density, size * windows.density, -size / 2, -size / 2, size, size);\n              if (cooling > 0) {\n                c.globalAlpha = alpha * cooling;\n                c.drawImage(ash.canvas, sample.x, sample.y, size * windows.density, size * windows.density, -size / 2, -size / 2, size, size);\n              }\n              c.restore();\n            }\n            return c.canvas.transferToImageBitmap();\n          },\n        };\n      },\n    };\n    return [Object.freeze({ [PIBBL_FILTER_EXECUTOR]: executor })];\n  };\n  return defineTransitionEffect(sampler(createKernel(seed)), linger, physics ? () => {\n    const kernel = createPhysicsKernel(seed);\n    const simulation = emberSimulation(kernel, physics, region, linger, burnWidth);\n    return { sample: sampler(kernel, simulation), advance: simulation.advance, reset: simulation.reset, dispose: simulation.dispose };\n  } : undefined);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/transitions/fade.d.ts

@@ -0,0 +1,41 @@
+import type { PibblVisibilityTransitionOptions } from "../hooks/use-visibility-transition.js";
+import type { embers } from "./embers.js";
+import type { PibblFilter } from '../style/filter-types.js';
+declare const effectBrand: unique symbol;
+/**
+ * Immutable, inert visual definition; mounted state belongs to its controller.
+ *
+ * @see {@link fade}
+ * @see {@link PibblVisibilityTransitionOptions}
+ * @see {@link embers}
+ */
+export interface PibblTransitionEffect {
+    readonly [effectBrand]: true;
+}
+export interface TransitionFrame {
+    readonly active: boolean;
+    readonly elapsed: number;
+    readonly progressAt: (elapsed: number) => number;
+}
+export type TransitionSampler = (progress: number, phase: 'enter' | 'exit', frame: TransitionFrame) => readonly PibblFilter[];
+/**
+ * A uniform fade of the receiving primitive and all of its descendants together.
+ *
+ * @returns A fade effect to use with a visibility transition. See {@link PibblTransitionEffect}.
+ *
+ * @see {@link PibblTransitionEffect}
+ */
+export declare function fade(): PibblTransitionEffect;
+export declare function transitionEffectSampler(definition: PibblTransitionEffect): TransitionSampler;
+/** @internal Shared registration for first-party definitions. */
+export declare function defineTransitionEffect(sample: TransitionSampler, tail?: number, create?: () => TransitionRuntime): PibblTransitionEffect;
+export declare function transitionEffectTail(definition: PibblTransitionEffect): number;
+/** Private controller-owned state for effects that simulate during Advance. */
+export interface TransitionRuntime {
+    readonly sample: TransitionSampler;
+    advance?(elapsed: number, progressAt: (time: number) => number): void;
+    reset?(): void;
+    dispose?(): void;
+}
+export declare function createTransitionRuntime(effect: PibblTransitionEffect): TransitionRuntime;
+export {};

package/dist/lib/transitions/fade.js

@@ -0,0 +1,31 @@
+import { opacity } from "../../filters/native.js";
+const definitions = /* @__PURE__ */ new WeakMap();
+function fade() {
+  return defineTransitionEffect((progress) => progress === 1 ? [] : [opacity({ amount: progress })]);
+}
+function transitionEffectSampler(definition) {
+  const record = definitions.get(definition);
+  if (!record) throw new TypeError("Expected a Pibbl transition effect definition.");
+  return record.sample;
+}
+function defineTransitionEffect(sample, tail = 0, create) {
+  const definition = Object.freeze({});
+  definitions.set(definition, { sample, tail, create });
+  return definition;
+}
+function transitionEffectTail(definition) {
+  transitionEffectSampler(definition);
+  return definitions.get(definition).tail;
+}
+function createTransitionRuntime(effect) {
+  const sample = transitionEffectSampler(effect);
+  return definitions.get(effect).create?.() ?? { sample };
+}
+export {
+  createTransitionRuntime,
+  defineTransitionEffect,
+  fade,
+  transitionEffectSampler,
+  transitionEffectTail
+};
+//# sourceMappingURL=fade.js.map

package/dist/lib/transitions/fade.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/transitions/fade.ts"],
+  "sourcesContent": ["import type { PibblVisibilityTransitionOptions } from '../hooks/use-visibility-transition.js';\nimport type { embers } from './embers.js';\nimport { opacity } from '../../filters/native.js';\nimport type { PibblFilter } from '../style/filter-types.js';\n\ndeclare const effectBrand: unique symbol;\n/**\n * Immutable, inert visual definition; mounted state belongs to its controller.\n *\n * @see {@link fade}\n * @see {@link PibblVisibilityTransitionOptions}\n * @see {@link embers}\n */\nexport interface PibblTransitionEffect { readonly [effectBrand]: true }\nexport interface TransitionFrame {\n  readonly active: boolean;\n  readonly elapsed: number;\n  readonly progressAt: (elapsed: number) => number;\n}\nexport type TransitionSampler = (progress: number, phase: 'enter' | 'exit', frame: TransitionFrame) => readonly PibblFilter[];\nconst definitions = new WeakMap<PibblTransitionEffect, { sample: TransitionSampler; tail: number; create?: () => TransitionRuntime }>();\n/**\n * A uniform fade of the receiving primitive and all of its descendants together.\n *\n * @returns A fade effect to use with a visibility transition. See {@link PibblTransitionEffect}.\n *\n * @see {@link PibblTransitionEffect}\n */\nexport function fade(): PibblTransitionEffect {\n  return defineTransitionEffect(progress => progress === 1 ? [] : [opacity({ amount: progress })]);\n}\nexport function transitionEffectSampler(definition: PibblTransitionEffect): TransitionSampler {\n  const record = definitions.get(definition);\n  if (!record) throw new TypeError('Expected a Pibbl transition effect definition.');\n  return record.sample;\n}\n\n/** @internal Shared registration for first-party definitions. */\nexport function defineTransitionEffect(sample: TransitionSampler, tail = 0, create?: () => TransitionRuntime): PibblTransitionEffect {\n  const definition = Object.freeze({}) as PibblTransitionEffect;\n  definitions.set(definition, { sample, tail, create });\n  return definition;\n}\n\nexport function transitionEffectTail(definition: PibblTransitionEffect): number {\n  transitionEffectSampler(definition);\n  return definitions.get(definition)!.tail;\n}\n\n/** Private controller-owned state for effects that simulate during Advance. */\nexport interface TransitionRuntime {\n  readonly sample: TransitionSampler;\n  advance?(elapsed: number, progressAt: (time: number) => number): void;\n  reset?(): void;\n  dispose?(): void;\n}\nexport function createTransitionRuntime(effect: PibblTransitionEffect): TransitionRuntime {\n  const sample = transitionEffectSampler(effect);\n  return definitions.get(effect)!.create?.() ?? { sample };\n}\n"],
+  "mappings": "AAEA,SAAS,eAAe;AAkBxB,MAAM,cAAc,oBAAI,QAA8G;AAQ/H,SAAS,OAA8B;AAC5C,SAAO,uBAAuB,cAAY,aAAa,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,SAAS,CAAC,CAAC,CAAC;AACjG;AACO,SAAS,wBAAwB,YAAsD;AAC5F,QAAM,SAAS,YAAY,IAAI,UAAU;AACzC,MAAI,CAAC,OAAQ,OAAM,IAAI,UAAU,gDAAgD;AACjF,SAAO,OAAO;AAChB;AAGO,SAAS,uBAAuB,QAA2B,OAAO,GAAG,QAAyD;AACnI,QAAM,aAAa,OAAO,OAAO,CAAC,CAAC;AACnC,cAAY,IAAI,YAAY,EAAE,QAAQ,MAAM,OAAO,CAAC;AACpD,SAAO;AACT;AAEO,SAAS,qBAAqB,YAA2C;AAC9E,0BAAwB,UAAU;AAClC,SAAO,YAAY,IAAI,UAAU,EAAG;AACtC;AASO,SAAS,wBAAwB,QAAkD;AACxF,QAAM,SAAS,wBAAwB,MAAM;AAC7C,SAAO,YAAY,IAAI,MAAM,EAAG,SAAS,KAAK,EAAE,OAAO;AACzD;",
+  "names": []
+}

package/dist/lib/transitions/hologram.d.ts

@@ -0,0 +1,47 @@
+import { type PibblTransitionEffect } from './fade.js';
+import { type TransitionRegion } from './capture.js';
+/**
+ * Color, scanning, and distortion controls for a hologram visibility transition.
+ *
+ * @see {@link hologram}
+ */
+export interface PibblHologramOptions {
+    /** Logical region over which the effect is evaluated. See {@link TransitionRegion}. */
+    readonly region: TransitionRegion;
+    /** Entry location or direction used by the transition. See {@link PibblHologramOptions}. */
+    readonly entry?: Readonly<{
+        /**
+         * Horizontal coordinate or displacement in the containing coordinate system. See
+         * {@link PibblHologramOptions}.
+         */
+        x: number;
+        /**
+         * Vertical coordinate or displacement in the containing coordinate system. See
+         * {@link PibblHologramOptions}.
+         */
+        y: number;
+    }>;
+    /** Hue control for the transition's emitted color. See {@link PibblHologramOptions}. */
+    readonly hue?: number;
+    /** Brightness control for the transition effect. See {@link PibblHologramOptions}. */
+    readonly brightness?: number;
+    /** Fog intensity used by the hologram effect. See {@link PibblHologramOptions}. */
+    readonly fog?: number;
+    /** Distortion intensity used by the hologram effect. See {@link PibblHologramOptions}. */
+    readonly glitch?: number;
+    /**
+     * Seed used for deterministic sampling or simulation initialization. See
+     * {@link PibblHologramOptions}.
+     */
+    readonly seed?: number;
+}
+/**
+ * A diffuse scan reconstructs the captured subject while interference settles.
+ *
+ * @param options - Hologram appearance and animation settings. See {@link PibblHologramOptions}.
+ * @returns A hologram transition effect. See {@link PibblTransitionEffect}.
+ *
+ * @see {@link PibblHologramOptions}
+ * @see {@link PibblTransitionEffect}
+ */
+export declare function hologram(options: PibblHologramOptions): PibblTransitionEffect;