@oxy.so/bloom 7.1.2 → 7.1.4

package/assets/character-runtime/shared-textures.mjs

@@ -0,0 +1,420 @@
+// Exact-content sharing for the original engine's two immutable 512px assets
+// and its 576x960 RGBA8 atlas. Only these observed storage layouts are admitted.
+// All other textures retain independent native storage. Render targets never
+// share. Logical objects keep Emscripten's mutable metadata (.name) independent.
+export function createSharedTexturePool(gl) {
+  const textures = new WeakMap(),
+    physicalEntries = new WeakMap(),
+    live = new Set(),
+    entries = new Set();
+  const cache = new Map(),
+    bindings = new Map(),
+    methods = new Map();
+  const unpackNames = [
+    'UNPACK_ALIGNMENT',
+    'UNPACK_FLIP_Y_WEBGL',
+    'UNPACK_PREMULTIPLY_ALPHA_WEBGL',
+    'UNPACK_COLORSPACE_CONVERSION_WEBGL',
+    'UNPACK_ROW_LENGTH',
+    'UNPACK_IMAGE_HEIGHT',
+    'UNPACK_SKIP_PIXELS',
+    'UNPACK_SKIP_ROWS',
+    'UNPACK_SKIP_IMAGES',
+  ];
+  const unpack = new Map(
+    unpackNames.map((name) => [gl[name], gl.getParameter(gl[name])]),
+  );
+  let unit = gl.getParameter(gl.ACTIVE_TEXTURE),
+    unpackBuffer = null,
+    disposed = false;
+  let hits = 0,
+    copies = 0;
+  const key = (target) => `${unit}:${target}`;
+  const current = (target) => bindings.get(key(target));
+  function equalBytes(a, b) {
+    if (!a || !b || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+    return true;
+  }
+  function removeCache(entry) {
+    if (!entry.key) return;
+    const bucket = cache.get(entry.key);
+    bucket?.delete(entry);
+    if (!bucket?.size) cache.delete(entry.key);
+    entry.key = null;
+    entry.snapshot = null;
+  }
+  function release(entry, record) {
+    entry.refs.delete(record);
+    if (entry.refs.size) return;
+    removeCache(entry);
+    entries.delete(entry);
+    physicalEntries.delete(entry.real);
+    gl.deleteTexture(entry.real);
+  }
+  function own(real, record) {
+    const entry = { real, refs: new Set([record]), key: null, snapshot: null };
+    entries.add(entry);
+    physicalEntries.set(real, entry);
+    return entry;
+  }
+  function rebind(record) {
+    for (const [binding, value] of bindings) {
+      if (value !== record) continue;
+      const [at, target] = binding.split(':').map(Number);
+      gl.activeTexture(at);
+      gl.bindTexture(target, record.entry.real);
+    }
+    gl.activeTexture(unit);
+  }
+  function makePrivate(record) {
+    if (!record || record.deleted) return;
+    const previous = record.entry;
+    if (previous.refs.size === 1) {
+      removeCache(previous);
+      return;
+    }
+    // Only a completed, fully captured candidate can have multiple owners.
+    const previousBinding = gl.getParameter(gl.TEXTURE_BINDING_2D);
+    const real = gl.createTexture();
+    gl.bindTexture(record.target, real);
+    gl.texStorage2D(...record.storage);
+    if (unpackBuffer) gl.bindBuffer(gl.PIXEL_UNPACK_BUFFER, null);
+    for (const [parameter, value] of record.uploadUnpack)
+      gl.pixelStorei(parameter, value);
+    gl.texSubImage2D(
+      record.target,
+      0,
+      0,
+      0,
+      record.storage[3],
+      record.storage[4],
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      record.pixels,
+    );
+    if (unpackBuffer) gl.bindBuffer(gl.PIXEL_UNPACK_BUFFER, unpackBuffer);
+    for (const [parameter, value] of unpack) gl.pixelStorei(parameter, value);
+    for (const [parameter, value] of record.parameters)
+      gl.texParameteri(record.target, parameter, value);
+    if (record.mipmaps) gl.generateMipmap(record.target);
+    record.entry = own(real, record);
+    release(previous, record);
+    rebind(record);
+    gl.bindTexture(
+      record.target,
+      current(record.target)?.entry.real ?? previousBinding,
+    );
+    copies++;
+  }
+  function finish(record) {
+    if (
+      !record?.eligible ||
+      !record.pixels ||
+      (!record.mipmaps && record.storage[1] !== 1) ||
+      record.renderTarget
+    )
+      return;
+    const descriptor = JSON.stringify([
+      record.storage,
+      [...record.parameters].sort((a, b) => a[0] - b[0]),
+      [...record.uploadUnpack].sort((a, b) => a[0] - b[0]),
+    ]);
+    const bucket = cache.get(descriptor);
+    let match;
+    for (const entry of bucket || [])
+      if (equalBytes(entry.snapshot.pixels, record.pixels)) {
+        match = entry;
+        break;
+      }
+    if (match) {
+      if (match === record.entry) return;
+      const previous = record.entry;
+      match.refs.add(record);
+      record.entry = match;
+      record.pixels = match.snapshot.pixels;
+      release(previous, record);
+      rebind(record);
+      hits++;
+      return;
+    }
+    removeCache(record.entry);
+    record.entry.key = descriptor;
+    let allocatedBytes = 0;
+    for (let level = 0; level < record.storage[1]; level++)
+      allocatedBytes +=
+        4 *
+        Math.max(1, record.storage[3] >> level) *
+        Math.max(1, record.storage[4] >> level);
+    record.entry.snapshot = { pixels: record.pixels, allocatedBytes };
+    const next = bucket || new Set();
+    next.add(record.entry);
+    cache.set(descriptor, next);
+  }
+  function unknownMutation(target, method, args) {
+    const record = current(target);
+    if (record) {
+      makePrivate(record);
+      record.eligible = false;
+      record.pixels = null;
+    }
+    return gl[method](...args);
+  }
+  const api = {
+    createTexture() {
+      const virtual = Object.create(WebGLTexture.prototype);
+      const record = {
+        virtual,
+        target: null,
+        entry: null,
+        storage: null,
+        pixels: null,
+        uploadUnpack: null,
+        parameters: new Map(),
+        mipmaps: false,
+        eligible: false,
+        renderTarget: false,
+        deleted: false,
+      };
+      record.entry = own(gl.createTexture(), record);
+      textures.set(virtual, record);
+      live.add(record);
+      return virtual;
+    },
+    bindTexture(target, texture) {
+      const record = textures.get(texture);
+      if (record?.deleted)
+        throw new Error('Cannot bind a deleted logical texture');
+      if (record && !record.target) record.target = target;
+      bindings.set(key(target), record || null);
+      return gl.bindTexture(target, record ? record.entry.real : texture);
+    },
+    activeTexture(value) {
+      unit = value;
+      return gl.activeTexture(value);
+    },
+    pixelStorei(parameter, value) {
+      if (unpack.has(parameter)) unpack.set(parameter, value);
+      return gl.pixelStorei(parameter, value);
+    },
+    bindBuffer(target, buffer) {
+      if (target === gl.PIXEL_UNPACK_BUFFER) unpackBuffer = buffer;
+      return gl.bindBuffer(target, buffer);
+    },
+    texStorage2D(...args) {
+      const record = current(args[0]);
+      if (record) {
+        makePrivate(record);
+        record.storage = [...args];
+        record.pixels = null;
+        record.mipmaps = false;
+        record.eligible =
+          args[0] === gl.TEXTURE_2D &&
+          args[2] === gl.RGBA8 &&
+          ((args[1] === 10 && args[3] === 512 && args[4] === 512) ||
+            (args[1] === 1 && args[3] === 576 && args[4] === 960)) &&
+          !record.renderTarget;
+      }
+      return gl.texStorage2D(...args);
+    },
+    texSubImage2D(...args) {
+      const record = current(args[0]);
+      const full =
+        record?.eligible &&
+        args.length >= 9 &&
+        args[1] === 0 &&
+        args[2] === 0 &&
+        args[3] === 0 &&
+        args[4] === record.storage[3] &&
+        args[5] === record.storage[4] &&
+        args[6] === gl.RGBA &&
+        args[7] === gl.UNSIGNED_BYTE &&
+        args[8] instanceof Uint8Array &&
+        !unpackBuffer &&
+        [
+          'UNPACK_ROW_LENGTH',
+          'UNPACK_IMAGE_HEIGHT',
+          'UNPACK_SKIP_PIXELS',
+          'UNPACK_SKIP_ROWS',
+          'UNPACK_SKIP_IMAGES',
+        ].every((name) => !unpack.get(gl[name]));
+      if (!full) return unknownMutation(args[0], 'texSubImage2D', args);
+      const offset = args[9] || 0,
+        length = args[4] * args[5] * 4;
+      if (
+        !Number.isInteger(offset) ||
+        offset < 0 ||
+        offset + length > args[8].length
+      )
+        return unknownMutation(args[0], 'texSubImage2D', args);
+      makePrivate(record);
+      const result = gl.texSubImage2D(...args);
+      record.pixels = args[8].slice(offset, offset + length); // Never identify mutable WASM memory by pointer.
+      record.uploadUnpack = new Map(unpack);
+      record.mipmaps = false;
+      finish(record);
+      return result;
+    },
+    texParameteri(target, parameter, value) {
+      const record = current(target);
+      if (record && record.parameters.get(parameter) !== value) {
+        makePrivate(record);
+        record.parameters.set(parameter, value);
+      }
+      const result = gl.texParameteri(target, parameter, value);
+      finish(record);
+      return result;
+    },
+    texParameterf(...args) {
+      return unknownMutation(args[0], 'texParameterf', args);
+    },
+    generateMipmap(target) {
+      const record = current(target);
+      if (record?.eligible && record.mipmaps) return;
+      if (record) makePrivate(record);
+      const result = gl.generateMipmap(target);
+      if (record) {
+        record.mipmaps = true;
+        finish(record);
+      }
+      return result;
+    },
+    framebufferTexture2D(target, attachment, textureTarget, texture, level) {
+      const record = textures.get(texture);
+      if (record) {
+        makePrivate(record);
+        record.renderTarget = true;
+        record.eligible = false;
+        record.pixels = null;
+      }
+      return gl.framebufferTexture2D(
+        target,
+        attachment,
+        textureTarget,
+        record ? record.entry.real : texture,
+        level,
+      );
+    },
+    framebufferTextureLayer(target, attachment, texture, level, layer) {
+      const record = textures.get(texture);
+      if (record) {
+        makePrivate(record);
+        record.renderTarget = true;
+        record.eligible = false;
+        record.pixels = null;
+      }
+      return gl.framebufferTextureLayer(
+        target,
+        attachment,
+        record ? record.entry.real : texture,
+        level,
+        layer,
+      );
+    },
+    getFramebufferAttachmentParameter(...args) {
+      const value = gl.getFramebufferAttachmentParameter(...args);
+      const entry =
+        value && typeof value === 'object'
+          ? physicalEntries.get(value)
+          : undefined;
+      // FBO attachment always makes a texture private before it is attached.
+      return entry?.refs.size === 1
+        ? entry.refs.values().next().value.virtual
+        : value;
+    },
+    deleteTexture(texture) {
+      if (!texture) return;
+      const record = textures.get(texture);
+      if (!record) return gl.deleteTexture(texture);
+      if (record.deleted) return;
+      record.deleted = true;
+      for (const [binding, value] of bindings)
+        if (value === record) {
+          const [at, target] = binding.split(':').map(Number);
+          gl.activeTexture(at);
+          gl.bindTexture(target, null);
+          bindings.set(binding, null);
+        }
+      gl.activeTexture(unit);
+      release(record.entry, record);
+      live.delete(record);
+      record.pixels = null;
+    },
+    isTexture(texture) {
+      const record = textures.get(texture);
+      return record
+        ? !record.deleted && gl.isTexture(record.entry.real)
+        : gl.isTexture(texture);
+    },
+    getParameter(parameter) {
+      const targets = new Map([
+        [gl.TEXTURE_BINDING_2D, gl.TEXTURE_2D],
+        [gl.TEXTURE_BINDING_3D, gl.TEXTURE_3D],
+        [gl.TEXTURE_BINDING_CUBE_MAP, gl.TEXTURE_CUBE_MAP],
+        [gl.TEXTURE_BINDING_2D_ARRAY, gl.TEXTURE_2D_ARRAY],
+      ]);
+      if (targets.has(parameter))
+        return (
+          current(targets.get(parameter))?.virtual || gl.getParameter(parameter)
+        );
+      return gl.getParameter(parameter);
+    },
+  };
+  const writes = new Set([
+    'texImage2D',
+    'copyTexImage2D',
+    'copyTexSubImage2D',
+    'compressedTexImage2D',
+    'compressedTexSubImage2D',
+    'texStorage3D',
+    'texImage3D',
+    'texSubImage3D',
+    'copyTexSubImage3D',
+    'compressedTexImage3D',
+    'compressedTexSubImage3D',
+  ]);
+  const context = new Proxy(gl, {
+    get(target, property) {
+      if (Object.hasOwn(api, property)) return api[property];
+      if (methods.has(property)) return methods.get(property);
+      const value = Reflect.get(target, property, target);
+      if (typeof value !== 'function') return value;
+      if (!methods.has(property))
+        methods.set(
+          property,
+          writes.has(property)
+            ? (...args) => unknownMutation(args[0], property, args)
+            : value.bind(target),
+        );
+      return methods.get(property);
+    },
+  });
+  return {
+    context,
+    stats: () => ({
+      logicalTextures: live.size,
+      physicalTextures: entries.size,
+      pooledTextures: [...cache.values()].reduce((n, v) => n + v.size, 0),
+      // RGBA8 storage across allocated levels, including each asset's base level.
+      mipBytesSaved: [...cache.values()].reduce(
+        (total, bucket) =>
+          total +
+          [...bucket].reduce(
+            (sum, entry) =>
+              sum + (entry.refs.size - 1) * entry.snapshot.allocatedBytes,
+            0,
+          ),
+        0,
+      ),
+      hits,
+      copies,
+    }),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const record of [...live]) api.deleteTexture(record.virtual);
+      methods.clear();
+      bindings.clear();
+    },
+  };
+}

package/docs/agent-avatar.mdx

@@ -26,33 +26,70 @@ Host the package's complete `assets/character-runtime/` directory. The provider
 
 ## Editing
 
-The `character` recipe holds a `preset` and optional `selections` for shape, color, eyes, eyewear and accessory. Explicit selections override preset defaults. `none` removes eyewear or an accessory. The editor reads the engine's actual selection and availability, including shape-dependent eye styles. Changing shape clears an explicit eye override so an unsupported pair is not restored.
+The `character` recipe holds a `preset` and optional `selections` for shape, color, eyes, eyewear and accessory. Explicit selections override preset defaults. `none` removes eyewear or an accessory. Changing shape preserves all selected face and accessory parts. Editing the eyes, eyewear, accessories or color keeps the named preset's original body until a new shape is explicitly selected.
 
-The editor presents one shape catalog and one eye catalog through `ShapeArc` and `EmotionPicker`. The eye orbit offers the engine’s nine native styles for both original and migrated bodies, with unsupported combinations disabled. Migrated bodies default to the original oval eyes. Saved expression, eye-size, spacing and tilt fields no longer modify a migrated face; the engine owns its eye geometry and animation. The shared `GlossArt` palette and custom color picker edit either body source. Original presets keep their authored appearance until explicitly edited.
+All 21 shapes use that same recipe. The additional contours have ordinary shape IDs: `slender`, `pocket`, `petal`, `star`, `cloud`, `shield`, `pebble` and `squircle`. For example, `{ preset: 'lime_frog', selections: { shape: 'cloud', eyes: 'cyclops', color: 'blue', accessory: 'felipe_beret' } }` selects a blue cloud with one eye and Felipe's hat. A shape contributes geometry only; it never selects another preset, palette or set of parts. Named presets retain their own default colors, while switching bodies keeps the chosen palette color or explicit `bodyColor`. Historical paper/blob recipes retain their saved paint when first edited and are promoted into the same recipe format.
 
-Alien avatars have been removed from the available catalog. Saved aliens, mascots and hidden-face recipes retain compatibility rendering. The shape selector shows static silhouettes without eyes or accessories: original catalog PNGs and cached SVG contours for migrated bodies. Paper grain and material effects become the engine’s 3D surface. Migrated bodies accept the original eyewear and accessory catalog. Headwear, Bulb, bow and Tuft use rigid contour anchors; eyewear and headphones retain their original placement. Original meshes, materials and fur remain intact.
+The editor presents one shape catalog and one eye catalog through `ShapeArc` and `EmotionPicker`. Its eyes include the engine’s nine native styles, Todd’s authored eyes, Clippo’s eyes and a single-eye style. `eyes: 'todd'` and `accessory: 'felipe_beret'` select the actual eyes from Todd and the three-piece beret from Felipe across the body catalog. Their original meshes, materials and animation deltas are copied in the preparation worker, fitted to each body and included in cache identities. The editor uses a static Todd-eye thumbnail; the shape wheel still uses silhouettes. Historical recipes without an explicit eye selection default to oval eyes. Historical expression, eye-size, `eyeGap` and tilt fields remain readable without modifying a migrated face. The shared `GlossArt` palette and custom color picker edit either body source.
+
+Each shape defines its own eye positions and size. Changing the eye style preserves that layout; changing shape adopts the new body's layout. Eye depth follows the actual body surface so shallow styles remain visible on bodies such as Todd. Eyewear fits the composed eyes, and a final rigid adjustment keeps crown accessories clear of eyes and frames. `selections.eyes: 'cyclops'` uses one large white eye with a teal iris, dark pupil and highlight at the shape's face center. There is no eye-placement control in AgentCreator. Historical `character.eyeSpacing` and `eyeGap` values remain readable but do not override the 3D layout. The **Universal Customization** and **Single Eye** stories exercise the shared editor and cross-body eye selections.
+
+`selections.shape: 'todd'` selects Todd's original body independently of its eye style. Its selector silhouette is sampled from the original mesh; no avatar runs inside the shape wheel. Editing a named preset's face or accessories preserves its original body, while an explicit shape selection replaces that body and retains the selected parts.
+
+`{ character: { preset: 'clippo' } }` selects Clippo’s grey open-wire body, large white eyes, dark pupils and asymmetric brows. `selections.shape: 'clippo'` and `selections.eyes: 'clippo'` are independent choices: other eyes can use the clip body, and other bodies can use Clippo’s face. Its tube is generated as a real hollow silhouette with rounded ends, without fur; it uses the same native character, lighting, interaction and work controller. Color, eyewear and headwear remain editable. The shape and eye wheels use static SVG thumbnails. Storybook’s **Clippo** story provides React/Work controls and cross-body examples.
+
+Alien avatars have been removed from the available catalog. Saved aliens, mascots and hidden-face recipes retain compatibility rendering. The shape selector shows static silhouettes without eyes or accessories: original catalog PNGs and cached SVG contours for migrated bodies. Paper grain and material effects become the engine’s 3D surface. Migrated bodies accept the original eyewear and accessory catalog. Headwear, Bulb, bow and Tuft use rigid contour anchors; eyewear fits the final eye geometry and headphones use body anchors. Original meshes, materials and fur remain intact.
 
 ## Interaction and lifecycle
 
-`interactive` enables the original engine's pointer tracking and touch/drag interaction. Change `reactionKey` from an accessible button to replay its authored signature reaction for an intact preset, or the original 3D wave for customized and migrated bodies. Shape changes retain the last painted frame while the new geometry prepares. Changing `workingKey` starts a working episode and then returns to the interactive mode; `workingCycles` controls its duration. The creator’s **React** and **Work** buttons preview these original animations for both original and migrated bodies.
+`interactive` enables the original engine's pointer tracking and touch/drag interaction. Change `reactionKey` from an accessible button to play the authored signature selected by the current body. Named bodies retain their native profile, including Todd and Jojo, after face, color or accessory edits. Catalog shapes with an authored counterpart use its body profile. Bodies without a matching profile, including Clippo and distinct migrated contours, use Todd's original signature as their shared standard. Pointer/touch reactions use the same body profile and preserve the edited appearance. Shape changes retain the last painted frame while the new geometry prepares. Changing `workingKey` starts a working episode and then returns to the interactive mode; `workingCycles` controls its duration. The creator’s **React** and **Work** buttons preview these original animations for both original and migrated bodies. Work preserves the chosen body and fitted face and accessories. Both modes retain the same native character, prepared geometry and clock while resident. Activity props are prepared up front; a verified adapter selects the original controller. A 180 ms transition interpolates body/skin transforms and camera in 3D from the last presented pose; added work props follow their original animation. Work finishes its original outro before a queued reaction starts. Repeated requests invalidate stale stop timers. Pause-related appearance changes and offscreen reclamation have separate lifecycles.
 
 `paused`, reduced motion and `motion: 0` stop animation after a complete appearance frame. `portrait` prepares a static thumbnail. The beta can report readiness while drawing transparency if initialized with its reduced-motion flag; the adapter waits for painted pixels and then freezes its clock instead.
 
-Web shares the beta engine and one animation clock per document, with a shared budget of **four live renderers** across original and migrated avatars. Additional avatars retain real 3D pixels from their last completed frame while their GPU renderer is released. Pointer interaction and React/Work commands prioritize reclaiming a renderer; overflow images remain visible while that renderer prepares. A newly visible avatar without a cached frame waits for its first rendering slot. This bounds graphics resources; the recovered engine’s synchronous first preparation can still cause a long task, especially for uncached migrated contours. Leaving the viewport or hiding the document releases the renderer lease, and returning avatars can display their retained image before resuming animation.
+Web uses one physical WebGL2 context and a packed canvas shared by every visible, animated character. Each original or migrated avatar keeps its own animation, input, work state and render targets. `shared-surface.mjs` maps default-framebuffer operations into its region, resolves MSAA locally before the atlas copy, and clips presentation to prevent neighbouring avatars leaking into a fitted image. Deleting one character cannot destroy the shared context; the last lease releases it. The shared clock targets 30 fps with a round-robin submission allowance; this is a target, not a guarantee of 30 fps per avatar on every device.
+
+Shaders and linked programs are shared by exact source and attribute bindings. Logical program handles retain independent uniforms and Emscripten metadata; switching skips values already present on the physical program. Small avatars (up to 128 CSS pixels) use the original compact mesh. The drawing resolution uses DPR at most 1 up to 64 CSS pixels, 1.5 up to 128, and 2 above that, with a 64-pixel floor and 512-pixel ceiling. The original engine derives its fur draw count from that drawing size, so reducing prepared fur arrays would not reduce its draw calls. Original fur and materials remain in use. The two 512-pixel mipmapped RGBA8 images and the 576×960 RGBA8 atlas share storage only when bytes and parameters match exactly; mutation or framebuffer attachment creates an independent copy. Private render targets, mutable geometry buffers and other textures remain per-character.
+
+The scheduler submits at most eight avatars per batch within an 8 ms CPU allowance, then waits asynchronously on a WebGL fence before checking driver errors and copying images. This releases the JavaScript thread while the GPU finishes; it does not make that GPU work free. Native setup/probing and Emscripten’s own `GL.lastError` checks retain their behavior. A graphics error discards every pending image in that batch and reports failure to its touched characters. Appearance edits, resize and disposal wait for the batch to finish. Pointer capture happens synchronously on pointer-down; native input is queued in order. A single native render remains non-interruptible. Diagnostics separate `renderMilliseconds` (submission plus presentation CPU time) from `renderWaitMilliseconds` (elapsed wait and task dispatch, not a GPU timer).
+
+Original and migrated bodies share one rendering WASM module and one preparation worker (the worker owns its own WASM instance). Prepared geometry identities include the contour and attachment transform. Cold preparation is admitted serially, while already painted moving avatars remain resident. Its owner receives a render turn every batch until its first complete paint, preventing the resident crowd from delaying the next preparation. The most recent interaction receives priority on alternate batches; the remaining turns use round-robin scheduling. Exact contour preparations are cached with an 8 MiB/16-entry LRU bound, keyed by appearance bytes, quality, activity mode, contour and authored parts. Cache hits receive independent buffer copies; native delivery still waits for the GPU boundary. Offscreen/background characters release their lease and retain their last complete 2D image. Static portraits use a bounded 64-image cache and release rendering resources after painting. Storybook’s **Many Avatars** story exercises 48 original/migrated avatars with React/Work controls and scrolling. **Shared Parts** shows Todd’s eyes and Felipe’s beret on all 21 shapes, with default-part, pause and animation controls.
+
+### Physical-device measurements
+
+The [current controller/transition benchmark](./benchmarks/avatar-continuous-renderer.json) uses a Pixel 8a (Mali-G715, Android 16, Android WebView 148), with all avatars visible at 48 CSS pixels and 64 backing pixels. Original presets and migrated contours alternate. After every avatar is ready, a three-second warmup precedes a roughly five-second sample. Output pixel hashes confirm that every avatar moves; page RAF cadence is measured separately from each avatar's paint rate. The artifact records the exact tested asset hashes; it predates the authored Todd/Felipe part compositor.
+
+| Visible avatars | Median paints per avatar per second | Page RAF interval, p95 | Time until all are ready | WebGL contexts |
+| --- | --- | --- | --- | --- |
+| 24 | 4.42 | 25.1 ms | 14.85 s | 1 |
+| 48 | 2.29 | 25.1 ms | 24.80 s | 1 |
+
+These results remove context loss, but **do not deliver fluid 30 fps animation**. The [previous baseline](./benchmarks/avatar-shared-renderer.json) took 24.6/74.1 seconds until all avatars were ready, with mean paint rates of 3.76/2.59 Hz. Startup improves substantially; drawing throughput does not improve uniformly. An [intermediate snapshot](./benchmarks/avatar-deferred-renderer.json) isolates deferred GPU waiting before eager activity preparation. These are individual runs, not controlled repeated trials or sustained thermal measurements. Readiness uses a new document/engine and warm HTTP caches. Pixel-hash sampling adds readback overhead.
 
-Different migrated contours isolate their rendering modules because the recovered engine caches geometry by its original appearance key; they share one preparation worker. Unused contour modules are released. Use `portrait` for galleries and selectors. Static preparation is serialized and the image cache is bounded to 64 entries; unmount releases listeners and rendering resources. Storybook’s **Many Avatars** story exercises 48 original/migrated avatars with per-avatar React/Work controls and document scrolling.
+Current CPU submission/presentation p95 is 10.0/10.4 ms per batch at 24/48, excluding asynchronous GPU wait. Exact texture sharing avoids a calculated 109.85/224.47 MiB of duplicate requested mip storage. These are payload calculations, not total GPU memory measurements. Both runs have nine physical programs, all avatars moving, zero graphics errors and zero live contexts/characters/preparation jobs after cleanup. Interaction and same-character React/Work continuity are checked separately in browser gates.
 
 In the repository, run the scheduler tests and the browser budget check (with Storybook running):
 
 ```bash
-node --test scripts/test-avatar-render-budget.mjs
+node --test scripts/test-avatar-render-budget.mjs scripts/test-avatar-preparation-scope.mjs scripts/test-avatar-render-errors.mjs scripts/test-avatar-preparation-cache.mjs scripts/test-avatar-preparation-delivery.mjs scripts/test-avatar-gl-dispatch.mjs scripts/test-avatar-managed-commands.mjs scripts/test-avatar-character-recipe.mjs scripts/test-avatar-clippo-geometry.mjs scripts/test-avatar-authored-parts.mjs scripts/test-avatar-controller-mode.mjs scripts/test-avatar-pose-transition.mjs
+node scripts/verify-avatar-shared-surface.mjs
+node scripts/verify-avatar-shared-programs.mjs
+node scripts/verify-avatar-shared-textures.mjs
+node scripts/verify-avatar-runtime-errors.mjs
+node scripts/verify-avatar-preparation-scope.mjs
 node scripts/verify-avatar-render-budget.mjs
+node scripts/verify-avatar-shared-renderer.mjs
+node scripts/verify-avatar-deferred-input.mjs
+node scripts/verify-avatar-controller-continuity.mjs
+node scripts/verify-avatar-pose-transition.mjs
+node scripts/verify-avatar-authored-parts.mjs
+node scripts/verify-avatar-clippo.mjs
+node scripts/verify-avatar-editor.mjs
 ```
 
 `className` and `style` apply to the outer layout node through Bloom's NativeWind wrapper. `label` defaults to the translated “Agent avatar”; `locale` overrides the scope and `accessibilityLabel` overrides the name. Prefer a meaningful name when the avatar identifies an agent.
 
 ## Native and fallback
 
-The optional native bridge uses `react-native-webview` and requires an absolute runtime URL reachable by the device. Web is verified in Chrome; physical-device validation remains pending. Each native WebView owns a separate document, so the four-renderer web budget is **not an application-wide native limit**. Separate WebViews cannot share engine memory, graphics contexts or the web document’s viewport reclamation.
+The optional native bridge uses `react-native-webview` and requires an absolute runtime URL reachable by the device. The web adapter is also exercised in a physical Android WebView; that does not validate a React Native multi-WebView screen. Each native WebView owns a separate document, so context sharing is **per document, not application-wide on native**. Separate WebViews cannot share engine memory, graphics contexts or the web document’s viewport reclamation.
 
 An unavailable runtime or missing native peer displays the translated unavailable state. Consumers without a runtime provider retain the universal SVG renderer for procedural recipes. That renderer preserves the original contours, folds, expression springs and deterministic grain; it does not support the beta's new 3D parts.

package/docs/agent-creator.mdx

@@ -25,9 +25,17 @@ Mount under `BloomProvider` and give the editor a bounded height. Layout classes
 
 ## Appearance
 
-The preview is 162px. With `AgentAvatarProvider`, one shape arc combines the eleven original engine shapes with eight distinct migrated bodies: pebble, squircle, slender, pocket, petal, star, cloud and shield. Equivalent circle, triangle, flower, diamond and heart recipes reuse the original geometry. Alien avatars have been removed from the available catalog and examples; saved alien recipes remain readable for compatibility.
+The preview is 162px. With `AgentAvatarProvider`, one shape arc combines the eleven original engine shapes, Todd's original body, Clippo's wire body and eight distinct migrated bodies: pebble, squircle, slender, pocket, petal, star, cloud and shield. Equivalent circle, triangle, flower, diamond and heart recipes reuse the original geometry. `selections.shape: 'todd'` independently selects Todd's actual body with any eye style. Its static pink SVG thumbnail comes from projected intersections of the original body mesh, without loading an avatar renderer. Alien avatars have been removed from the available catalog and examples; saved alien recipes remain readable for compatibility.
 
-The eye orbit offers nine original 3D eye styles for both body sources. Migrated bodies default to oval eyes; historical expression, eye-size, spacing and tilt settings no longer alter their faces. The engine owns eye geometry and animation, and its capabilities disable unsupported combinations. Changing shape clears an incompatible eye override. Original presets keep their authored eyes until explicitly edited.
+Every shape writes the same `character.selections.shape` field. The eight added contour IDs are plain names such as `cloud` and `pebble`; selecting one keeps the current preset, named palette or custom RGB, eyes, eyewear and accessory. Crossing between contours and original geometry retains the mounted avatar. The renderer resolves the body geometry separately from the appearance. Historical saved recipes are promoted with their existing color instead of being reset to a different preset.
+
+The eye orbit offers nine original 3D eye styles plus Todd, Clippo and Single eye for both body sources. Changing shape preserves the selected eyes, eyewear and accessory. Named presets provide their original defaults; choosing another eye style retains the preset's body. Historical recipes without an explicit eye selection default to oval eyes. Historical expression, eye-size, `eyeGap` and tilt settings remain readable; the engine owns the 3D face geometry and animation.
+
+Known eye, color, eyewear and accessory choices stay available while a new appearance prepares. A pending capability response does not disable the controls or replace the current recipe with provisional defaults. Shape-comparison stories use one shared appearance across all bodies, including the same color, rather than giving old contours a separate flesh-colored default.
+
+**Eye placement belongs to the shape.** Each body defines eye positions and size; every interchangeable eye style uses that layout. Changing shape automatically adopts its face layout without introducing another editor control. Historical `character.eyeSpacing` values remain readable for saved-recipe compatibility and are ignored by the renderer. Storybook's **Universal Customization** story starts with Todd and shows the saved recipe beside the existing editor.
+
+**Single eye** (`selections.eyes: 'cyclops'`) selects a large white eye with a teal iris, dark pupil and highlight on any body. Its orbit thumbnail is static SVG artwork. It uses the selected shape’s face center and size. Storybook's **Single Eye** story shows it on the original and migrated shapes.
 
 Upright eye chips orbit at a 116px radius; dragging or a mouse wheel rotates the orbit. Hover, focus, backgrounding and reduced motion pause automatic movement. The shape selector uses a 210px circular track, an unbounded index, spring, drag and wheel geometry. Choose a silhouette by pressing it; keyboard arrows, Home and End select shapes on web. BloomProvider’s direction reverses horizontal movement in RTL.
 
@@ -35,7 +43,9 @@ Nine glossy color presets and the shared custom picker edit both original and mi
 
 The preview accepts pointer and touch reactions. **React** and **Work** buttons also support keyboard activation and preview the original engine’s animations on either body source. Working returns to the interactive preview after its episode. Eye chips and original shape chips use catalog PNG thumbnails. Migrated shape chips use cached static SVG silhouettes from their actual contours, matching the catalog’s flat pink artwork. The shape wheel renders no avatars or 3D canvases.
 
-The preset selector provides authored characters; eyewear and accessories use Bloom Select on both original and migrated bodies. Explicit selections survive switching between these bodies. Headwear, Bulb, bow and Tuft attach to migrated contour anchors; eyewear and headphones keep their original placement. Intact presets retain their authored signature reaction; edited and migrated bodies use the original 3D wave. Catalog titles retain their original English names by default. Hosts can translate them through `labels.characterOption(category, id, title)`; control labels follow the editor locale. Consumers without a runtime provider retain compatibility rendering and controls for saved procedural recipes.
+The named Clippo preset uses a grey open wire body, large ring eyes and asymmetric eyebrows. Its body and eyes are independent catalog choices; the Clippo eyes remain selected when choosing another original or migrated shape. Clippo chips use static SVG artwork, with an open stroked path for the body and no avatar renderer in the wheel. Saved configurations use `character.preset: 'clippo'` or `character.selections.shape` / `character.selections.eyes` with ID `clippo`.
+
+The preset selector provides authored characters; eyewear and accessories use Bloom Select on both original and migrated bodies. Explicit selections survive switching between these bodies. Headwear, Bulb, bow and Tuft attach to migrated contour anchors; eyewear fits the final eye geometry and headphones use body anchors. Reactions follow the body's original native signature after customization; catalog shapes with an authored counterpart use its profile, while unmatched shapes, Clippo and distinct migrated contours use Todd's signature as the shared standard. Work keeps the chosen body and fitted parts. Catalog titles retain their original English names by default. Hosts can translate them through `labels.characterOption(category, id, title)`; control labels follow the editor locale. Consumers without a runtime provider retain compatibility rendering and controls for saved procedural recipes.
 
 ## Preferences and speech
 

package/lib/commonjs/agent-avatar/AgentAvatar.js

@@ -19,7 +19,7 @@ const AgentAvatar = exports.AgentAvatar = /*#__PURE__*/(0, _react.memo)(function
   const legacy = runtimeUrl && !(0, _legacyRecipe.legacyRecipeUnsupported)(props.config);
   return beta || legacy ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_CharacterAvatar.CharacterAvatar, {
     ...props
-  }, beta ? 'character' : 'legacy') : /*#__PURE__*/(0, _jsxRuntime.jsx)(_ProceduralAvatar.ProceduralAvatar, {
+  }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_ProceduralAvatar.ProceduralAvatar, {
     ...props
   });
 });

package/lib/commonjs/agent-avatar/AgentAvatar.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","_CharacterAvatar","_ProceduralAvatar","_context","_legacyRecipe","_jsxRuntime","AgentAvatar","exports","memo","props","runtimeUrl","useContext","CharacterRuntimeContext","beta","config","character","preset","legacy","legacyRecipeUnsupported","jsx","CharacterAvatar","ProceduralAvatar"],"sourceRoot":"../../../src","sources":["agent-avatar/AgentAvatar.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,gBAAA,GAAAD,OAAA;AACA,IAAAE,iBAAA,GAAAF,OAAA;AACA,IAAAG,QAAA,GAAAH,OAAA;AACA,IAAAI,aAAA,GAAAJ,OAAA;AAA0D,IAAAK,WAAA,GAAAL,OAAA;AAG1D;AACO,MAAMM,WAAW,GAAAC,OAAA,CAAAD,WAAA,gBAAG,IAAAE,WAAI,EAAC,SAASF,WAAWA,CAACG,KAAuB,EAAE;EAC5E,MAAM;IAAEC;EAAW,CAAC,GAAG,IAAAC,iBAAU,EAACC,gCAAuB,CAAC;EAC1D,MAAMC,IAAI,GACRJ,KAAK,CAACK,MAAM,CAACC,SAAS,IAAIN,KAAK,CAACK,MAAM,CAACC,SAAS,CAACC,MAAM,KAAK,OAAO;EACrE,MAAMC,MAAM,GAAGP,UAAU,IAAI,CAAC,IAAAQ,qCAAuB,EAACT,KAAK,CAACK,MAAM,CAAC;EACnE,OAAOD,IAAI,IAAII,MAAM,gBACnB,IAAAZ,WAAA,CAAAc,GAAA,EAAClB,gBAAA,CAAAmB,eAAe;IAAA,GAAyCX;EAAK,GAAxCI,IAAI,GAAG,WAAW,GAAG,QAAsB,CAAC,gBAElE,IAAAR,WAAA,CAAAc,GAAA,EAACjB,iBAAA,CAAAmB,gBAAgB;IAAA,GAAKZ;EAAK,CAAG,CAC/B;AACH,CAAC,CAAC","ignoreList":[]}
+{"version":3,"names":["_react","require","_CharacterAvatar","_ProceduralAvatar","_context","_legacyRecipe","_jsxRuntime","AgentAvatar","exports","memo","props","runtimeUrl","useContext","CharacterRuntimeContext","beta","config","character","preset","legacy","legacyRecipeUnsupported","jsx","CharacterAvatar","ProceduralAvatar"],"sourceRoot":"../../../src","sources":["agent-avatar/AgentAvatar.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,gBAAA,GAAAD,OAAA;AACA,IAAAE,iBAAA,GAAAF,OAAA;AACA,IAAAG,QAAA,GAAAH,OAAA;AACA,IAAAI,aAAA,GAAAJ,OAAA;AAA0D,IAAAK,WAAA,GAAAL,OAAA;AAG1D;AACO,MAAMM,WAAW,GAAAC,OAAA,CAAAD,WAAA,gBAAG,IAAAE,WAAI,EAAC,SAASF,WAAWA,CAACG,KAAuB,EAAE;EAC5E,MAAM;IAAEC;EAAW,CAAC,GAAG,IAAAC,iBAAU,EAACC,gCAAuB,CAAC;EAC1D,MAAMC,IAAI,GACRJ,KAAK,CAACK,MAAM,CAACC,SAAS,IAAIN,KAAK,CAACK,MAAM,CAACC,SAAS,CAACC,MAAM,KAAK,OAAO;EACrE,MAAMC,MAAM,GAAGP,UAAU,IAAI,CAAC,IAAAQ,qCAAuB,EAACT,KAAK,CAACK,MAAM,CAAC;EACnE,OAAOD,IAAI,IAAII,MAAM,gBACnB,IAAAZ,WAAA,CAAAc,GAAA,EAAClB,gBAAA,CAAAmB,eAAe;IAAA,GAAKX;EAAK,CAAG,CAAC,gBAE9B,IAAAJ,WAAA,CAAAc,GAAA,EAACjB,iBAAA,CAAAmB,gBAAgB;IAAA,GAAKZ;EAAK,CAAG,CAC/B;AACH,CAAC,CAAC","ignoreList":[]}

package/lib/commonjs/agent-avatar/CharacterAvatar.js

@@ -15,6 +15,7 @@ var _characterHtml = require("./character-html.js");
 var _characterRuntimeModule = require("./character-runtime-module.js");
 var _characterWebview = require("./character-webview.js");
 var _legacyRecipe = require("./legacy-recipe.js");
+var _characterShapes = require("./character-shapes.js");
 var _messages2 = require("./messages.js");
 var _jsxRuntime = require("react/jsx-runtime");
 function WebCharacter({
@@ -171,7 +172,7 @@ function CharacterAvatar(props) {
     };
   }, []);
   (0, _react.useEffect)(() => setFailed(false), [runtimeUrl, config.character]);
-  const legacy = (0, _react.useMemo)(() => !config.character || config.character.preset === 'bloom' ? (0, _legacyRecipe.legacyRecipe)(config) : undefined, [config]);
+  const legacy = (0, _react.useMemo)(() => !config.character || config.character.preset === 'bloom' || (0, _characterShapes.isMigratedCharacterShape)(config.character.selections?.shape) ? (0, _legacyRecipe.legacyRecipe)(config) : undefined, [config]);
   const value = (0, _react.useMemo)(() => ({
     config,
     legacy,