@dailies-studio/particles 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dailies-studio/particles",
+  "version": "0.1.0",
+  "description": "First-party GLB particle emitter: a contracted react-three-fiber component whose emission is a pure function of (frame, seed) — seeded PCG32 + closed-form kinematics, never per-tick integration. Dogfoods the contract system's curve/gradient/asset kinds.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./controls": {
+      "types": "./src/controls.ts",
+      "default": "./src/controls.ts"
+    },
+    "./catalog": {
+      "types": "./src/catalog.ts",
+      "default": "./src/catalog.ts"
+    },
+    "./pcg32": {
+      "types": "./src/pcg32.ts",
+      "default": "./src/pcg32.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.6.1",
+    "three": "^0.185.1",
+    "@dailies-studio/contract": "0.1.0",
+    "@dailies-studio/engine": "0.1.0",
+    "@dailies-studio/runtime": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0"
+  },
+  "devDependencies": {
+    "@react-three/test-renderer": "^9.1.0",
+    "@types/react": "^19.0.0",
+    "@types/three": "^0.185.1",
+    "react": "^19.0.0"
+  }
+}

package/src/balloons.ts

@@ -0,0 +1,132 @@
+// The foil balloon cluster's layout model — the same discipline as
+// emission.ts: every balloon attribute is a pure function of (seed, index)
+// from its own PCG32 stream, and every pose is a closed-form function of
+// (attributes, config, rise, time). No simulation state anywhere; scrubbing
+// backwards, re-mounting and out-of-order export rendering see identical
+// balloons. React/three-free so the numbers are directly testable.
+import { pcg32 } from "./pcg32.js";
+
+export interface BalloonClusterConfig {
+  count: number;
+  seed: number;
+  /** Cluster anchor, fractions of the frame (x of width, y of height, 0/0 top-left). */
+  centerX: number;
+  centerY: number;
+  /** Cluster half-extent, fractions of the frame. */
+  spreadX: number;
+  spreadY: number;
+  /** Mean balloon height as a fraction of the frame height. */
+  size: number;
+  /** Ambient bob/tilt amount, 0..1. */
+  sway: number;
+}
+
+export interface BalloonAttributes {
+  /** Even slot across the cluster, -1..1. The hero (middle) balloon sits on 0. */
+  slot: number;
+  jitterX: number;
+  jitterY: number;
+  sizeScale: number;
+  /** World-space depth offset; the hero floats nearest the camera. */
+  zOffset: number;
+  /** Resting tilts, radians. */
+  tiltX: number;
+  tiltZ: number;
+  /** Yaw sway amplitude, radians. */
+  yawAmp: number;
+  /** Phase offset for every oscillator, 0..2π. */
+  phase: number;
+  /** Oscillator rate, rad/s over studio time. */
+  speed: number;
+  /** Extra entrance drop, 0..1. */
+  dropExtra: number;
+  /** Entrance stagger position, 0..1 (0 enters first). */
+  delayNorm: number;
+  /** Which foil color the balloon wears. */
+  colorIndex: 0 | 1;
+}
+
+/** Attributes for balloon `index` — one independent PCG32 stream per balloon,
+ *  keyed (seed, index). The DRAW ORDER below is part of the cluster's
+ *  identity: reordering the draws re-rolls every shipped template. */
+export function balloonAttributes(seed: number, index: number, count: number): BalloonAttributes {
+  const rng = pcg32(Math.max(0, Math.floor(seed)), index);
+  const jx = rng.next01();
+  const jy = rng.next01();
+  const jSize = rng.next01();
+  const jz = rng.next01();
+  const jTiltX = rng.next01();
+  const jTiltZ = rng.next01();
+  const jYaw = rng.next01();
+  const jPhase = rng.next01();
+  const jSpeed = rng.next01();
+  const jDrop = rng.next01();
+  const jDelay = rng.next01();
+  const jColor = rng.next01();
+
+  // The middle slot is the hero: biggest, centred, nearest the camera, first
+  // through the entrance — the reference framing every foil-balloon promo uses.
+  const hero = index === Math.floor((count - 1) / 2);
+  return {
+    slot: count <= 1 ? 0 : (index / (count - 1)) * 2 - 1,
+    jitterX: (jx - 0.5) * 0.5,
+    jitterY: (jy - 0.5) * 2,
+    sizeScale: hero ? 1.6 : 0.7 + jSize * 0.55,
+    zOffset: hero ? 0.25 : (jz - 0.5) * 0.5,
+    tiltX: (jTiltX - 0.5) * 0.24,
+    tiltZ: (jTiltZ - 0.5) * (hero ? 0.22 : 0.5),
+    yawAmp: 0.2 + jYaw * 0.35,
+    phase: jPhase * Math.PI * 2,
+    speed: 0.5 + jSpeed * 0.7,
+    dropExtra: jDrop,
+    delayNorm: hero ? 0 : 0.2 + jDelay * 0.8,
+    colorIndex: hero ? 0 : jColor < 0.4 ? 1 : 0,
+  };
+}
+
+export interface BalloonPose {
+  /** Frame fractions (x of width, y of height, 0/0 top-left). */
+  x: number;
+  y: number;
+  /** Balloon height as a fraction of the frame height. */
+  scale: number;
+  /** Radians. */
+  rotX: number;
+  rotY: number;
+  rotZ: number;
+}
+
+const clamp01 = (n: number): number => Math.min(1, Math.max(0, n));
+
+/** The closed-form pose at (rise, time). `rise` drives the staggered entrance
+ *  (each balloon starts after its `delayNorm` share and eases out); `time` is
+ *  studio seconds and drives the ambient bob/sway oscillators. */
+export function balloonPose(
+  a: BalloonAttributes,
+  cfg: BalloonClusterConfig,
+  rise: number,
+  timeSeconds: number,
+): BalloonPose {
+  const delay = 0.45 * a.delayNorm;
+  const local = clamp01((clamp01(rise) - delay) / (1 - delay));
+  const eased = 1 - (1 - local) ** 3;
+
+  const settledX = cfg.centerX + (a.slot * 0.85 + a.jitterX) * cfg.spreadX;
+  const settledY = cfg.centerY + a.jitterY * cfg.spreadY;
+  const drop = 1.05 + a.dropExtra * 0.4;
+
+  const t = timeSeconds;
+  const bobY = Math.sin(t * a.speed + a.phase) * 0.014 * cfg.sway * (0.6 + 0.4 * a.dropExtra);
+  const driftX = Math.cos(t * a.speed * 0.7 + a.phase * 1.3) * 0.008 * cfg.sway;
+  // A pendulum swing that dies out as the balloon settles.
+  const swing = (1 - eased) * 0.3 * Math.sin(a.phase + eased * 6);
+
+  return {
+    x: settledX + driftX,
+    y: settledY + (1 - eased) * drop + bobY,
+    scale: cfg.size * a.sizeScale,
+    rotX: a.tiltX,
+    rotY: Math.sin(t * a.speed * 0.5 + a.phase) * a.yawAmp * cfg.sway,
+    rotZ: a.tiltZ * eased + swing + Math.sin(t * a.speed * 0.8 + a.phase * 1.7) * 0.07 * cfg.sway,
+  };
+}

package/src/catalog.ts

@@ -0,0 +1,28 @@
+// The metadata entry ("@dailies-studio/particles/catalog"): everything the CLI
+// server needs to register this package's components as builtins. Deliberately
+// react/three-free (no component imports) — the server loads this in plain
+// node, exactly as it loads the primitives and effects catalogs.
+import type { Contract } from "@dailies-studio/contract";
+import { controls as particleEmitterControls, foilBalloonsControls } from "./controls.js";
+
+export const PARTICLES_MODULE = "@dailies-studio/particles" as const;
+
+export interface ParticleCatalogEntry {
+  /** Stable builtin id: `<module>#<exportName>`, the shared convention. */
+  id: string;
+  module: typeof PARTICLES_MODULE;
+  exportName: string;
+  /** Display name in the components palette. */
+  name: string;
+  contract: Contract;
+}
+
+function entry(exportName: string, name: string, contract: Contract): ParticleCatalogEntry {
+  return { id: `${PARTICLES_MODULE}#${exportName}`, module: PARTICLES_MODULE, exportName, name, contract };
+}
+
+/** Every entry is a `kind:"three"` layer on the shared stage. */
+export const PARTICLES_CATALOG: readonly ParticleCatalogEntry[] = [
+  entry("ParticleEmitter", "Particle Emitter", particleEmitterControls),
+  entry("FoilBalloons", "Foil Balloons", foilBalloonsControls),
+];

package/src/controls.ts

@@ -0,0 +1,147 @@
+// The emitter's contract — authored with the SAME DSL users get, because this
+// package exists to dogfood the contract system: number ranges, a hold-only
+// curve, a gradient, and a GLB asset all on one component. DEFAULTS is shared
+// with the component's prop destructuring so "no props" and "contract
+// defaults" are the same animation.
+import { c, defineControls } from "@dailies-studio/contract";
+import type { Contract, CurveValue, GradientValue } from "@dailies-studio/contract";
+import { LINEAR_HANDLES } from "@dailies-studio/engine";
+
+const H = (): [number, number, number, number] => [...LINEAR_HANDLES];
+
+export const DEFAULT_SCALE_OVER_LIFE: CurveValue = {
+  kind: "curve",
+  points: [
+    { x: 0, y: 0, handles: H() },
+    { x: 0.15, y: 1, handles: H() },
+    { x: 1, y: 0, handles: H() },
+  ],
+};
+
+export const DEFAULT_COLOR_OVER_LIFE: GradientValue = {
+  kind: "gradient",
+  stops: [
+    { at: 0, color: "#ffd166" },
+    { at: 1, color: "#ef476f" },
+  ],
+};
+
+export const DEFAULTS = {
+  emissionRate: 24,
+  particleLifetime: 1.6,
+  spread: 28,
+  speed: 2.2,
+  speedJitter: 0.3,
+  gravity: 1.6,
+  spin: 120,
+  seed: 1,
+  size: 0.12,
+  scaleOverLife: DEFAULT_SCALE_OVER_LIFE,
+  colorOverLife: DEFAULT_COLOR_OVER_LIFE,
+  glbSrc: null as string | null,
+} as const;
+
+export const FOIL_BALLOONS_DEFAULTS = {
+  count: 5,
+  seed: 7,
+  rise: 1,
+  centerX: 0.5,
+  centerY: 0.3,
+  spreadX: 0.36,
+  spreadY: 0.12,
+  size: 0.12,
+  sway: 0.5,
+  colorA: "#e2b13c",
+  colorB: "#9ccc3f",
+  shine: 0.65,
+} as const;
+
+/** The foil balloon cluster (foilBalloons.tsx). Positions and sizes are
+ *  FRACTIONS of the frame (x of width, y of height, 0/0 = top-left) rather
+ *  than px: a three layer always fills the composition viewport, so fractions
+ *  are the coordinate space that survives any comp size. */
+export const foilBalloonsControls: Contract = defineControls({
+  count: c.number({ default: FOIL_BALLOONS_DEFAULTS.count, min: 1, max: 12, step: 1, label: "Count" }),
+  // Randomness identity, exactly like the emitter's: animating the seed would
+  // re-roll the cluster every frame.
+  seed: c.number({
+    default: FOIL_BALLOONS_DEFAULTS.seed,
+    min: 0,
+    max: 99999,
+    step: 1,
+    animatable: false,
+    label: "Seed",
+  }),
+  // The entrance: 0 = every balloon below the frame, 1 = cluster settled.
+  // Keyframe this (a spring reads beautifully); each balloon staggers and
+  // eases inside the component as a closed-form function of this one value.
+  rise: c.number({ default: FOIL_BALLOONS_DEFAULTS.rise, min: 0, max: 1, step: 0.01, label: "Rise" }),
+  centerX: c.number({
+    default: FOIL_BALLOONS_DEFAULTS.centerX,
+    min: 0,
+    max: 1,
+    step: 0.001,
+    label: "Center X",
+  }),
+  centerY: c.number({
+    default: FOIL_BALLOONS_DEFAULTS.centerY,
+    min: 0,
+    max: 1,
+    step: 0.001,
+    label: "Center Y",
+  }),
+  spreadX: c.number({
+    default: FOIL_BALLOONS_DEFAULTS.spreadX,
+    min: 0,
+    max: 0.6,
+    step: 0.001,
+    label: "Spread X",
+  }),
+  spreadY: c.number({
+    default: FOIL_BALLOONS_DEFAULTS.spreadY,
+    min: 0,
+    max: 0.6,
+    step: 0.001,
+    label: "Spread Y",
+  }),
+  size: c.number({
+    default: FOIL_BALLOONS_DEFAULTS.size,
+    min: 0.02,
+    max: 0.4,
+    step: 0.001,
+    label: "Balloon size",
+  }),
+  sway: c.number({ default: FOIL_BALLOONS_DEFAULTS.sway, min: 0, max: 1, step: 0.01, label: "Sway" }),
+  colorA: c.color({ default: FOIL_BALLOONS_DEFAULTS.colorA, label: "Foil color A" }),
+  colorB: c.color({ default: FOIL_BALLOONS_DEFAULTS.colorB, label: "Foil color B" }),
+  shine: c.number({ default: FOIL_BALLOONS_DEFAULTS.shine, min: 0, max: 1, step: 0.01, label: "Shine" }),
+});
+
+export const controls: Contract = defineControls({
+  emissionRate: c.number({
+    default: DEFAULTS.emissionRate,
+    min: 0,
+    max: 200,
+    unit: "1/s",
+    label: "Emission rate",
+  }),
+  particleLifetime: c.number({
+    default: DEFAULTS.particleLifetime,
+    min: 0.05,
+    max: 20,
+    unit: "s",
+    label: "Particle lifetime",
+  }),
+  spread: c.number({ default: DEFAULTS.spread, min: 0, max: 180, unit: "deg" }),
+  speed: c.number({ default: DEFAULTS.speed, min: 0, max: 50 }),
+  speedJitter: c.number({ default: DEFAULTS.speedJitter, min: 0, max: 1, label: "Speed jitter" }),
+  gravity: c.number({ default: DEFAULTS.gravity, min: -20, max: 20 }),
+  spin: c.number({ default: DEFAULTS.spin, min: 0, max: 720, unit: "deg/s" }),
+  size: c.number({ default: DEFAULTS.size, min: 0.001, max: 10 }),
+  // Randomness identity: animating the seed would re-roll every particle each
+  // frame — it is deliberately not animatable.
+  seed: c.number({ default: DEFAULTS.seed, min: 0, max: 99999, step: 1, animatable: false }),
+  scaleOverLife: c.curve({ default: DEFAULT_SCALE_OVER_LIFE, label: "Scale over life" }),
+  colorOverLife: c.gradient({ default: DEFAULT_COLOR_OVER_LIFE, label: "Color over life" }),
+  glbSrc: c.asset({ assetKind: "glb", default: null, label: "GLB model" }),
+});

package/src/emission.ts

@@ -0,0 +1,149 @@
+// The emission model: every particle attribute is a CLOSED-FORM function of
+// (config, particleIndex, timeSeconds). No per-tick integration, no mutable
+// simulation state — position at time t is p0 + v0·age + ½g·age², so sampling
+// frame 300 before frame 10 (parallel export, backwards scrub) is exact by
+// construction (plan §4.4).
+//
+// Randomness discipline: particle i draws from its OWN pcg32(seed, i) stream
+// in a FIXED order (documented on ParticleAttributes). Changing the order or
+// count of draws changes every animation ever exported — treat it like a wire
+// format. New randomized attributes must draw AFTER the existing six.
+import { pcg32 } from "./pcg32.js";
+
+export interface EmissionConfig {
+  /** Particles born per second (> 0 to emit). */
+  emissionRate: number;
+  /** Seconds each particle lives (> 0). */
+  particleLifetime: number;
+  /** Cone half-angle around +Y, degrees, 0..180 (180 = full sphere). */
+  spreadDeg: number;
+  /** Initial speed, world units/sec. */
+  speed: number;
+  /** Fractional speed jitter in [0,1]: actual = speed · (1 ± jitter). */
+  speedJitter: number;
+  /** Downward acceleration, units/sec² (negative floats particles upward). */
+  gravity: number;
+  /** Max spin rate, deg/sec; each particle draws in [-max, +max]. */
+  spinMaxDegPerSec: number;
+  /** The contract seed: same seed = same animation, everywhere, forever. */
+  seed: number;
+}
+
+export type Vec3Tuple = readonly [number, number, number];
+
+/** The per-particle random draw, in draw order. Pure in (seed, index). */
+export interface ParticleAttributes {
+  /** Birth time in seconds: index / emissionRate. */
+  birth: number;
+  /** Unit launch direction (uniform on the spread cone around +Y). */
+  direction: Vec3Tuple;
+  /** Launch speed after jitter, units/sec. */
+  speed: number;
+  /** Unit spin axis (uniform on the sphere). */
+  spinAxis: Vec3Tuple;
+  /** Signed spin rate, radians/sec. */
+  spinRate: number;
+}
+
+const DEG = Math.PI / 180;
+
+/**
+ * Particle i's immutable attributes. Draw order (the wire format):
+ *   1. cone cap height  2. cone azimuth  3. speed jitter
+ *   4. spin-axis z      5. spin-axis azimuth  6. spin rate
+ */
+export function particleAttributes(cfg: EmissionConfig, index: number): ParticleAttributes {
+  // PCG32 seeding is 64-bit integer math; a fractional or non-finite seed
+  // (hand-edited document, direct props) must degrade deterministically,
+  // never throw inside a render effect.
+  const seed = Number.isFinite(cfg.seed) ? Math.trunc(cfg.seed) : 0;
+  const rng = pcg32(seed, index);
+
+  // Uniform on the spherical cap: cosθ uniform in [cos(spread), 1].
+  const cosSpread = Math.cos(Math.min(180, Math.max(0, cfg.spreadDeg)) * DEG);
+  const cosTheta = 1 - rng.next01() * (1 - cosSpread);
+  const sinTheta = Math.sqrt(Math.max(0, 1 - cosTheta * cosTheta));
+  const phi = rng.next01() * 2 * Math.PI;
+  const direction: Vec3Tuple = [
+    sinTheta * Math.cos(phi),
+    cosTheta,
+    sinTheta * Math.sin(phi),
+  ];
+
+  const jitter = Math.min(1, Math.max(0, cfg.speedJitter));
+  const speed = cfg.speed * (1 + (rng.next01() * 2 - 1) * jitter);
+
+  // Uniform on the sphere for the spin axis.
+  const az = rng.next01() * 2 - 1;
+  const aphi = rng.next01() * 2 * Math.PI;
+  const ar = Math.sqrt(Math.max(0, 1 - az * az));
+  const spinAxis: Vec3Tuple = [ar * Math.cos(aphi), az, ar * Math.sin(aphi)];
+
+  const spinRate = (rng.next01() * 2 - 1) * cfg.spinMaxDegPerSec * DEG;
+
+  return {
+    birth: index / cfg.emissionRate,
+    direction,
+    speed,
+    spinAxis,
+    spinRate,
+  };
+}
+
+/**
+ * CANDIDATE indices for particles alive at time t — a guaranteed superset of
+ * every index whose {@link particleState} gate (birth ≤ t < birth+lifetime)
+ * passes; callers filter through the gate. The bounds are widened by one
+ * index on each side because they are computed by MULTIPLICATION
+ * (floor(t·rate)) while the gate divides (t − i/rate): the two round
+ * differently, and at frame-reachable times (e.g. rate = fps) the tight
+ * bound excludes a gate-live particle for exactly one frame — a visible pop.
+ * A dead candidate costs one gate check; a dropped live particle costs a
+ * determinism bug.
+ */
+export function activeIndexRange(cfg: EmissionConfig, t: number): [number, number] {
+  if (!(cfg.emissionRate > 0) || !(cfg.particleLifetime > 0) || !(t >= 0)) return [0, 0];
+  // birth = i/rate ≤ t  →  i ≤ t·rate ; t < birth + L  →  i > (t - L)·rate
+  const end = Math.floor(t * cfg.emissionRate) + 2;
+  const start = Math.max(0, Math.floor((t - cfg.particleLifetime) * cfg.emissionRate) - 1);
+  return start < end ? [start, end] : [0, 0];
+}
+
+/** Capacity an instance buffer needs to hold every concurrently-live particle. */
+export function particleCapacity(cfg: EmissionConfig, cap = 4096): number {
+  if (!(cfg.emissionRate > 0) || !(cfg.particleLifetime > 0)) return 0;
+  return Math.min(cap, Math.ceil(cfg.emissionRate * cfg.particleLifetime) + 1);
+}
+
+export interface ParticleState {
+  position: Vec3Tuple;
+  /** Spin angle in radians around the particle's spinAxis. */
+  spinAngle: number;
+  /** Age fraction of lifetime in [0, 1). */
+  life01: number;
+}
+
+/**
+ * Closed-form state of one particle at absolute time t, or null when not alive.
+ * p = v0·age + ½·(0,-g,0)·age² — the emitter's local origin is the wrapper's
+ * transform, so position is relative to it.
+ */
+export function particleState(
+  attrs: ParticleAttributes,
+  cfg: EmissionConfig,
+  t: number,
+): ParticleState | null {
+  const age = t - attrs.birth;
+  if (!(age >= 0) || age >= cfg.particleLifetime) return null;
+  const s = attrs.speed;
+  const halfG = -0.5 * cfg.gravity * age * age;
+  return {
+    position: [
+      attrs.direction[0] * s * age,
+      attrs.direction[1] * s * age + halfG,
+      attrs.direction[2] * s * age,
+    ],
+    spinAngle: attrs.spinRate * age,
+    life01: age / cfg.particleLifetime,
+  };
+}

package/src/emitter.tsx

@@ -0,0 +1,223 @@
+// The GLB particle emitter — a contracted react-three-fiber component.
+// Rendering is an InstancedMesh whose per-instance matrices/colors are
+// recomputed from the CLOSED-FORM model on every studio-clock change; there is
+// no simulation state anywhere in this file. Time comes exclusively from
+// useStudioClock() (the harness/player provide it) — never from r3f's
+// wall-time clock, which would break scrubbing and out-of-order export.
+import React, { Suspense, useLayoutEffect, useMemo } from "react";
+import * as THREE from "three";
+import { useThree } from "@react-three/fiber";
+import { useGLTF } from "@react-three/drei";
+import { compileCurve, compileGradient } from "@dailies-studio/contract";
+import type { CurveValue, GradientValue } from "@dailies-studio/contract";
+import { useStudioClock } from "@dailies-studio/runtime";
+import {
+  activeIndexRange,
+  particleAttributes,
+  particleCapacity,
+  particleState,
+} from "./emission.js";
+import type { EmissionConfig, ParticleAttributes } from "./emission.js";
+import { DEFAULTS, DEFAULT_COLOR_OVER_LIFE, DEFAULT_SCALE_OVER_LIFE } from "./controls.js";
+
+export interface ParticleEmitterProps {
+  emissionRate?: number;
+  particleLifetime?: number;
+  spread?: number;
+  speed?: number;
+  speedJitter?: number;
+  gravity?: number;
+  spin?: number;
+  size?: number;
+  seed?: number;
+  scaleOverLife?: CurveValue;
+  colorOverLife?: GradientValue;
+  glbSrc?: string | null;
+}
+
+// Loop temporaries — module scope so the per-frame update allocates nothing.
+const M4 = new THREE.Matrix4();
+const POS = new THREE.Vector3();
+const SCL = new THREE.Vector3();
+const AXIS = new THREE.Vector3();
+const QUAT = new THREE.Quaternion();
+const COLOR = new THREE.Color();
+
+/** First mesh in a GLTF scene — the emitter's instanced geometry source. */
+export function firstMeshOf(scene: THREE.Object3D): THREE.Mesh | null {
+  let found: THREE.Mesh | null = null;
+  scene.traverse((o) => {
+    if (!found && (o as THREE.Mesh).isMesh) found = o as THREE.Mesh;
+  });
+  return found;
+}
+
+export interface ParticleInstancesProps {
+  geometry: THREE.BufferGeometry;
+  material: THREE.Material;
+  config: EmissionConfig;
+  size: number;
+  scaleOverLife: CurveValue;
+  colorOverLife: GradientValue;
+  /** Studio time in seconds (already resolved by the caller). */
+  timeSeconds: number;
+}
+
+/**
+ * The deterministic core renderer, exported for tests and advanced use:
+ * geometry/material in, closed-form instanced particles out.
+ */
+export function ParticleInstances(props: ParticleInstancesProps): React.ReactElement | null {
+  const { geometry, material, config, size, timeSeconds } = props;
+  const invalidate = useThree((s) => s.invalidate);
+
+  const capacity = particleCapacity(config);
+  const mesh = useMemo(() => {
+    if (capacity === 0) return null;
+    const m = new THREE.InstancedMesh(geometry, material, capacity);
+    // Closed-form positions leave the source geometry's bounds immediately;
+    // per-instance culling would need bounds we never compute.
+    m.frustumCulled = false;
+    m.count = 0;
+    return m;
+  }, [geometry, material, capacity]);
+  useLayoutEffect(() => {
+    if (!mesh) return;
+    return () => mesh.dispose(); // instance buffers only; geometry/material are the caller's
+  }, [mesh]);
+
+  // Per-particle randoms are pure in (seed, index) — cache them for the fields
+  // that feed the draw. Any of these changing re-rolls the population.
+  const attrCache = useMemo(() => {
+    void [
+      config.seed,
+      config.emissionRate,
+      config.spreadDeg,
+      config.speed,
+      config.speedJitter,
+      config.spinMaxDegPerSec,
+    ];
+    return new Map<number, ParticleAttributes>();
+  }, [
+    config.seed,
+    config.emissionRate,
+    config.spreadDeg,
+    config.speed,
+    config.speedJitter,
+    config.spinMaxDegPerSec,
+  ]);
+
+  const scaleFn = useMemo(() => compileCurve(props.scaleOverLife), [props.scaleOverLife]);
+  const colorFn = useMemo(() => compileGradient(props.colorOverLife), [props.colorOverLife]);
+
+  useLayoutEffect(() => {
+    if (!mesh) return;
+    // Bound the memo: indices grow ~rate·t over a long timeline, and old
+    // entries are just recomputable pure values — dropping them can only
+    // cost a recompute on a backwards scrub, never change a pixel.
+    if (attrCache.size > capacity * 4 + 64) attrCache.clear();
+    const [start, end] = activeIndexRange(config, timeSeconds);
+    let n = 0;
+    for (let i = start; i < end && n < capacity; i++) {
+      let attrs = attrCache.get(i);
+      if (!attrs) {
+        attrs = particleAttributes(config, i);
+        attrCache.set(i, attrs);
+      }
+      const st = particleState(attrs, config, timeSeconds);
+      if (!st) continue;
+      const s = Math.max(0, size * scaleFn(st.life01));
+      AXIS.set(attrs.spinAxis[0], attrs.spinAxis[1], attrs.spinAxis[2]);
+      QUAT.setFromAxisAngle(AXIS, st.spinAngle);
+      POS.set(st.position[0], st.position[1], st.position[2]);
+      SCL.set(s, s, s);
+      M4.compose(POS, QUAT, SCL);
+      mesh.setMatrixAt(n, M4);
+      // THREE.Color has no alpha channel — an 8-digit stop keeps its rgb.
+      COLOR.set(colorFn(st.life01).slice(0, 7));
+      mesh.setColorAt(n, COLOR);
+      n++;
+    }
+    mesh.count = n;
+    mesh.instanceMatrix.needsUpdate = true;
+    if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
+    invalidate(); // no-op under the harness ('never' + explicit advance); real in demand mode
+  }, [mesh, config, timeSeconds, size, scaleFn, colorFn, attrCache, capacity, invalidate]);
+
+  return mesh ? <primitive object={mesh} /> : null;
+}
+
+function GlbParticles(
+  props: Omit<ParticleInstancesProps, "geometry" | "material"> & { url: string },
+): React.ReactElement | null {
+  const gltf = useGLTF(props.url);
+  const mesh = useMemo(() => firstMeshOf(gltf.scene), [gltf.scene]);
+  if (!mesh) throw new Error(`GLB '${props.url}' contains no mesh to instance`);
+  // Clone: drei caches GLTFs by url; instanceColor tinting must never mutate
+  // another consumer's material.
+  const material = useMemo(() => {
+    const m = Array.isArray(mesh.material) ? mesh.material[0]! : mesh.material;
+    return m.clone();
+  }, [mesh]);
+  useLayoutEffect(() => {
+    // The clone is OURS — without disposal every crash-remount or glbSrc
+    // change leaks a compiled GPU program.
+    return () => material.dispose();
+  }, [material]);
+  const { url: _url, ...rest } = props;
+  return <ParticleInstances {...rest} geometry={mesh.geometry} material={material} />;
+}
+
+const DEFAULT_GEOMETRY = new THREE.TetrahedronGeometry(1);
+// Unlit: the gradient IS the look, with or without user lights.
+const DEFAULT_MATERIAL = new THREE.MeshBasicMaterial({ color: 0xffffff });
+
+/**
+ * The contracted emitter. Props mirror ./controls.ts one-to-one; DEFAULTS
+ * keeps "no props at all" identical to the contract's defaults.
+ */
+export function ParticleEmitter(props: ParticleEmitterProps): React.ReactElement {
+  const {
+    emissionRate = DEFAULTS.emissionRate,
+    particleLifetime = DEFAULTS.particleLifetime,
+    spread = DEFAULTS.spread,
+    speed = DEFAULTS.speed,
+    speedJitter = DEFAULTS.speedJitter,
+    gravity = DEFAULTS.gravity,
+    spin = DEFAULTS.spin,
+    size = DEFAULTS.size,
+    seed = DEFAULTS.seed,
+    scaleOverLife = DEFAULT_SCALE_OVER_LIFE,
+    colorOverLife = DEFAULT_COLOR_OVER_LIFE,
+    glbSrc = null,
+  } = props;
+
+  const clock = useStudioClock();
+  const timeSeconds = clock?.timeSeconds ?? 0;
+
+  const config = useMemo<EmissionConfig>(
+    () => ({
+      emissionRate,
+      particleLifetime,
+      spreadDeg: spread,
+      speed,
+      speedJitter,
+      gravity,
+      spinMaxDegPerSec: spin,
+      seed,
+    }),
+    [emissionRate, particleLifetime, spread, speed, speedJitter, gravity, spin, seed],
+  );
+
+  const shared = { config, size, scaleOverLife, colorOverLife, timeSeconds };
+  if (glbSrc) {
+    return (
+      <Suspense fallback={null}>
+        <GlbParticles url={glbSrc} {...shared} />
+      </Suspense>
+    );
+  }
+  return (
+    <ParticleInstances {...shared} geometry={DEFAULT_GEOMETRY} material={DEFAULT_MATERIAL} />
+  );
+}

package/src/foilBalloons.tsx

@@ -0,0 +1,228 @@
+// A cluster of mylar "foil" envelope balloons — the floating brand-object
+// look of fintech promo motion. A contracted kind:"three" citizen of the
+// shared stage, built the same way the emitter and the effect adapter are:
+//
+//  - Every pose is CLOSED-FORM (balloons.ts): a pure function of (seed,
+//    index, rise, studio time). No simulation, no accumulation — scrubbing
+//    backwards and out-of-order export rendering are exact.
+//  - Time comes exclusively from useStudioClock(); outside a stage the clock
+//    is null and the cluster renders its t=0 pose.
+//  - The foil shading is a TSL colorNode on MeshBasicNodeMaterial — UNLIT,
+//    like every effect: a fixed key-light lambert + specular streak + fresnel
+//    rim computed from the view-space normal. No scene lights, no environment
+//    map (the shared stage ships none), no tone mapping surprises; identical
+//    on the WebGPU and WebGL2 backends because TSL compiles to both.
+//  - The node graph is built once over uniforms; prop changes only write
+//    uniform.value — no pipeline recompiles while scrubbing.
+//
+// Geometry is procedural (an extruded rounded-rect pillow plus a triangular
+// flap prism, the envelope read) and module-scope: pure functions of
+// constants, shared by every instance, never disposed.
+import React, { useLayoutEffect, useMemo } from "react";
+import { useThree } from "@react-three/fiber";
+import {
+  Color,
+  ExtrudeGeometry,
+  Group,
+  Mesh,
+  MeshBasicNodeMaterial,
+  Shape,
+} from "three/webgpu";
+import { normalView, uniform, vec3 } from "three/tsl";
+import { useStudioClock } from "@dailies-studio/runtime";
+import { balloonAttributes, balloonPose } from "./balloons.js";
+import type { BalloonAttributes, BalloonClusterConfig } from "./balloons.js";
+import { FOIL_BALLOONS_DEFAULTS } from "./controls.js";
+
+export interface FoilBalloonsProps {
+  count?: number;
+  seed?: number;
+  rise?: number;
+  centerX?: number;
+  centerY?: number;
+  spreadX?: number;
+  spreadY?: number;
+  size?: number;
+  sway?: number;
+  colorA?: string;
+  colorB?: string;
+  shine?: number;
+}
+
+function roundedRectShape(width: number, height: number, radius: number): Shape {
+  const s = new Shape();
+  const x = -width / 2;
+  const y = -height / 2;
+  s.moveTo(x + radius, y);
+  s.lineTo(x + width - radius, y);
+  s.quadraticCurveTo(x + width, y, x + width, y + radius);
+  s.lineTo(x + width, y + height - radius);
+  s.quadraticCurveTo(x + width, y + height, x + width - radius, y + height);
+  s.lineTo(x + radius, y + height);
+  s.quadraticCurveTo(x, y + height, x, y + height - radius);
+  s.lineTo(x, y + radius);
+  s.quadraticCurveTo(x, y, x + radius, y);
+  return s;
+}
+
+/** The pillow body, normalized to height 1 and centred. The extrude bevel's
+ *  faceted normals are the point — a mylar balloon is creased, not smooth. */
+const BODY_GEOMETRY = (() => {
+  const g = new ExtrudeGeometry(roundedRectShape(1.34, 1.0, 0.3), {
+    depth: 0.22,
+    steps: 1,
+    bevelEnabled: true,
+    bevelThickness: 0.16,
+    bevelSize: 0.14,
+    bevelSegments: 5,
+    curveSegments: 12,
+  });
+  g.center();
+  g.computeBoundingBox();
+  const bb = g.boundingBox!;
+  const s = 1 / (bb.max.y - bb.min.y);
+  g.scale(s, s, s);
+  g.computeBoundingBox();
+  return g;
+})();
+
+const BODY_FRONT_Z = BODY_GEOMETRY.boundingBox!.max.z;
+
+/** The envelope flap: a shallow triangular prism sitting proud of the front
+ *  face. Same material as the body — the ridge reads through shading alone. */
+const FLAP_GEOMETRY = (() => {
+  const tri = new Shape();
+  tri.moveTo(-0.46, 0.3);
+  tri.lineTo(0.46, 0.3);
+  tri.lineTo(0, -0.14);
+  tri.closePath();
+  const g = new ExtrudeGeometry(tri, {
+    depth: 0.02,
+    steps: 1,
+    bevelEnabled: true,
+    bevelThickness: 0.025,
+    bevelSize: 0.025,
+    bevelSegments: 2,
+    curveSegments: 4,
+  });
+  return g;
+})();
+
+/** One foil material: fake-foil shading over the view-space normal —
+ *  key-light lambert, a bounce fill, a tight specular streak scaled by
+ *  `shine`, and a fresnel rim. Built over uniforms so prop changes mutate
+ *  `value` and never rebuild the node graph. */
+function makeFoilMaterial(colorHex: string, shineDefault: number) {
+  const colorU = uniform(new Color(colorHex));
+  const shineU = uniform(shineDefault);
+  const n = normalView.normalize();
+  const key = n.dot(vec3(0.34, 0.53, 0.78).normalize()).clamp(0, 1);
+  const fill = n.dot(vec3(-0.55, -0.3, 0.78).normalize()).clamp(0, 1);
+  const base = colorU
+    .mul(key.mul(0.55).add(0.38))
+    .add(colorU.mul(fill.pow(2).mul(0.22)));
+  const spec = key.pow(26).mul(shineU);
+  const rim = n.z.clamp(0, 1).oneMinus().pow(3).mul(0.3);
+  const material = new MeshBasicNodeMaterial();
+  material.colorNode = base.add(vec3(1.0, 0.98, 0.9).mul(spec.add(rim.mul(0.6))));
+  return { material, colorU, shineU };
+}
+
+/**
+ * The contracted cluster. Props mirror controls.ts one-to-one;
+ * FOIL_BALLOONS_DEFAULTS keeps "no props at all" identical to the contract's
+ * defaults.
+ */
+export function FoilBalloons(props: FoilBalloonsProps): React.ReactElement {
+  const {
+    count = FOIL_BALLOONS_DEFAULTS.count,
+    seed = FOIL_BALLOONS_DEFAULTS.seed,
+    rise = FOIL_BALLOONS_DEFAULTS.rise,
+    centerX = FOIL_BALLOONS_DEFAULTS.centerX,
+    centerY = FOIL_BALLOONS_DEFAULTS.centerY,
+    spreadX = FOIL_BALLOONS_DEFAULTS.spreadX,
+    spreadY = FOIL_BALLOONS_DEFAULTS.spreadY,
+    size = FOIL_BALLOONS_DEFAULTS.size,
+    sway = FOIL_BALLOONS_DEFAULTS.sway,
+    colorA = FOIL_BALLOONS_DEFAULTS.colorA,
+    colorB = FOIL_BALLOONS_DEFAULTS.colorB,
+    shine = FOIL_BALLOONS_DEFAULTS.shine,
+  } = props;
+
+  const viewport = useThree((s) => s.viewport);
+  const invalidate = useThree((s) => s.invalidate);
+  const clock = useStudioClock();
+  const timeSeconds = clock?.timeSeconds ?? 0;
+
+  const countInt = Math.min(12, Math.max(1, Math.round(count)));
+  const seedInt = Math.max(0, Math.floor(seed));
+
+  // Materials + uniforms: built once per mount, mutated per commit.
+  const shading = useMemo(
+    () => ({
+      a: makeFoilMaterial(FOIL_BALLOONS_DEFAULTS.colorA, FOIL_BALLOONS_DEFAULTS.shine),
+      b: makeFoilMaterial(FOIL_BALLOONS_DEFAULTS.colorB, FOIL_BALLOONS_DEFAULTS.shine),
+    }),
+    [],
+  );
+  useLayoutEffect(() => {
+    const { a, b } = shading;
+    return () => {
+      a.material.dispose(); // ours — leaking one leaks a compiled pipeline
+      b.material.dispose();
+    };
+  }, [shading]);
+
+  // The population: a pure function of (seed, count). Geometry and materials
+  // are shared, so a re-roll allocates only meshes and attribute records.
+  const rig = useMemo(() => {
+    const group = new Group();
+    const items: { mesh: Mesh; attrs: BalloonAttributes }[] = [];
+    for (let i = 0; i < countInt; i++) {
+      const attrs = balloonAttributes(seedInt, i, countInt);
+      const material = attrs.colorIndex === 0 ? shading.a.material : shading.b.material;
+      const body = new Mesh(BODY_GEOMETRY, material);
+      const flap = new Mesh(FLAP_GEOMETRY, material);
+      flap.position.set(0, 0.1, BODY_FRONT_Z - 0.01);
+      body.add(flap);
+      group.add(body);
+      items.push({ mesh: body, attrs });
+    }
+    return { group, items };
+  }, [countInt, seedInt, shading]);
+
+  // Every commit: write uniforms and recompute every pose closed-form. A
+  // dozen scalar writes and trig calls — cheaper than memo bookkeeping.
+  useLayoutEffect(() => {
+    // THREE.Color has no alpha channel — an 8-digit pick keeps its rgb.
+    shading.a.colorU.value.set(colorA.slice(0, 7));
+    shading.b.colorU.value.set(colorB.slice(0, 7));
+    shading.a.shineU.value = shine;
+    shading.b.shineU.value = shine;
+    const cfg: BalloonClusterConfig = {
+      count: countInt,
+      seed: seedInt,
+      centerX,
+      centerY,
+      spreadX,
+      spreadY,
+      size,
+      sway,
+    };
+    for (const { mesh, attrs } of rig.items) {
+      const pose = balloonPose(attrs, cfg, rise, timeSeconds);
+      // Frame fractions → world units: the viewport is the world-space rect
+      // of this instance's View at z=0 (the full composition).
+      mesh.position.set(
+        (pose.x - 0.5) * viewport.width,
+        (0.5 - pose.y) * viewport.height,
+        attrs.zOffset,
+      );
+      mesh.scale.setScalar(pose.scale * viewport.height);
+      mesh.rotation.set(pose.rotX, pose.rotY, pose.rotZ);
+    }
+    invalidate(); // no-op under the harness (frameloop 'never'); real in demand mode
+  });
+
+  return <primitive object={rig.group} />;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export { ParticleEmitter, ParticleInstances, firstMeshOf } from "./emitter.js";
+export type { ParticleEmitterProps, ParticleInstancesProps } from "./emitter.js";
+export { FoilBalloons } from "./foilBalloons.js";
+export type { FoilBalloonsProps } from "./foilBalloons.js";
+export {
+  controls,
+  DEFAULTS,
+  DEFAULT_COLOR_OVER_LIFE,
+  DEFAULT_SCALE_OVER_LIFE,
+  FOIL_BALLOONS_DEFAULTS,
+  foilBalloonsControls,
+} from "./controls.js";
+export { balloonAttributes, balloonPose } from "./balloons.js";
+export type { BalloonAttributes, BalloonClusterConfig, BalloonPose } from "./balloons.js";
+export { PARTICLES_CATALOG, PARTICLES_MODULE } from "./catalog.js";
+export type { ParticleCatalogEntry } from "./catalog.js";
+export {
+  activeIndexRange,
+  particleAttributes,
+  particleCapacity,
+  particleState,
+} from "./emission.js";
+export type {
+  EmissionConfig,
+  ParticleAttributes,
+  ParticleState,
+  Vec3Tuple,
+} from "./emission.js";
+export { pcg32 } from "./pcg32.js";
+export type { Pcg32 } from "./pcg32.js";

package/src/pcg32.ts

@@ -0,0 +1,43 @@
+// PCG32 (PCG-XSH-RR 64/32, O'Neill) — the emitter's ONLY randomness source.
+// Every particle owns an independent PCG stream keyed by (seed, particleIndex),
+// so particle i's attributes are a pure function of the contract's seed and its
+// index: scrubbing backwards, re-mounting, and out-of-order export rendering
+// all see identical particles (plan §4.4). BigInt keeps the 64-bit state
+// arithmetic exact and readable; streams are created once per particle and
+// memoized by the caller, so construction cost never sits on the frame path.
+//
+// Matches the reference pcg32 (pcg_basic.c): verified against the canonical
+// demo vectors in the test suite.
+
+const MULT = 6364136223846793005n;
+const MASK64 = (1n << 64n) - 1n;
+
+export interface Pcg32 {
+  /** Next uniform u32 in [0, 2^32). */
+  nextU32(): number;
+  /** Next uniform float in [0, 1) — u32 / 2^32. */
+  next01(): number;
+}
+
+/** pcg32_srandom_r(initstate, initseq) + pcg32_random_r, reference semantics. */
+export function pcg32(initstate: number | bigint, initseq: number | bigint): Pcg32 {
+  const inc = ((BigInt(initseq) << 1n) | 1n) & MASK64;
+  let state = 0n;
+  const step = (): number => {
+    const old = state;
+    state = (old * MULT + inc) & MASK64;
+    const xorshifted = Number(((old >> 18n) ^ old) >> 27n & 0xffffffffn);
+    const rot = Number(old >> 59n);
+    // 32-bit rotate right; >>> 0 keeps the result unsigned.
+    return ((xorshifted >>> rot) | (xorshifted << ((-rot) & 31))) >>> 0;
+  };
+  // Reference seeding: from state 0, one step lands on `inc` (0*MULT + inc),
+  // then initstate is added and one more step is taken (output discarded).
+  state = inc;
+  state = (state + (BigInt(initstate) & MASK64)) & MASK64;
+  step();
+  return {
+    nextU32: step,
+    next01: () => step() / 0x1_0000_0000,
+  };
+}