@oxy.so/bloom 7.1.0 → 7.1.2

package/assets/character-runtime/managed-avatar.mjs

@@ -0,0 +1,258 @@
+import { renderBudget } from './render-budget.mjs';
+
+const snapshots = new Map();
+const waiting = new Map();
+const pixelsFor = (canvas) =>
+  Math.max(
+    64,
+    Math.min(
+      512,
+      Math.round(
+        Math.min(canvas.clientWidth, canvas.clientHeight) *
+          Math.min(devicePixelRatio || 1, 2),
+      ),
+    ),
+  );
+
+// Presentation lifetime is independent of the GPU lease. Overflow avatars keep
+// their real engine pixels and can reclaim a lease through pointer/command input.
+export function createManagedAvatar(canvas, initial, callbacks, factory) {
+  let props = initial,
+    controller,
+    disposed = false,
+    ready = false;
+  let visible = false,
+    hovered = false,
+    urgentUntil = 0,
+    timer;
+  let pendingWork = false,
+    pendingReaction = false,
+    starting = false;
+  let capabilities,
+    lastDiagnostics = {},
+    cacheKey = '',
+    cachedKey = '';
+  const still = () =>
+    props.portrait ||
+    props.paused ||
+    props.reduced ||
+    props.config.motion === 0;
+  const fingerprint = () =>
+    JSON.stringify([
+      props.config.character,
+      props.legacy,
+      props.config.lookAt,
+      pixelsFor(canvas),
+    ]);
+  const priority = () =>
+    pendingWork || pendingReaction || performance.now() < urgentUntil
+      ? 3
+      : hovered
+        ? 2
+        : props.interactive
+          ? 1
+          : 0;
+  const refresh = () =>
+    lease.update({
+      visible: (visible || props.portrait) && !document.hidden,
+      still: still(),
+      priority: still() ? 0 : priority(),
+      needsPaint: !ready,
+    });
+  function promote(duration = 5000) {
+    if (still()) return;
+    urgentUntil = performance.now() + duration;
+    clearTimeout(timer);
+    timer = setTimeout(refresh, duration + 1);
+    refresh();
+  }
+  function commands() {
+    if (!controller?.diagnostics?.()?.ready) return;
+    if (pendingWork)
+      promote(
+        2500 * Math.max(1, Math.min(10, props.workingCycles || 1)) + 1000,
+      );
+    else if (pendingReaction) promote();
+    if (pendingWork) {
+      pendingWork = false;
+      controller.work?.();
+    }
+    if (pendingReaction) {
+      pendingReaction = false;
+      controller.react?.();
+    }
+  }
+  const lease = renderBudget.register({
+    async start() {
+      starting = true;
+      try {
+        const created = await factory(canvas, props, {
+          onCapabilities(value) {
+            if (disposed) return;
+            capabilities = value;
+            callbacks.onCapabilities?.(value);
+          },
+          onError(error) {
+            if (!disposed) lease.fail(error);
+          },
+          onReady() {
+            if (!disposed) queueMicrotask(commands);
+          },
+          onPaint(settled = true) {
+            if (disposed || !settled) return;
+            if (!ready) {
+              ready = true;
+              lease.painted();
+              callbacks.onReady?.();
+            }
+            if (cachedKey !== cacheKey) {
+              const image = document.createElement('canvas');
+              image.width = canvas.width;
+              image.height = canvas.height;
+              image.getContext('2d').drawImage(canvas, 0, 0);
+              snapshots.delete(cacheKey);
+              snapshots.set(cacheKey, { image, capabilities });
+              if (snapshots.size > 64)
+                snapshots.delete(snapshots.keys().next().value);
+              cachedKey = cacheKey;
+              for (const receive of waiting.get(cacheKey) ?? []) receive();
+            }
+            callbacks.onPaint?.();
+          },
+        });
+        controller = created;
+        created.update(props, true);
+        return created;
+      } finally {
+        starting = false;
+      }
+    },
+    suspend(value) {
+      lastDiagnostics = value.diagnostics?.() ?? lastDiagnostics;
+      value.dispose();
+      if (controller === value) controller = undefined;
+    },
+    error(error) {
+      if (!disposed) callbacks.onError?.(error);
+    },
+  });
+  function paintSnapshot() {
+    if (disposed || ready || controller || starting) return;
+    const saved = snapshots.get(cacheKey);
+    if (!saved) return;
+    canvas.width = saved.image.width;
+    canvas.height = saved.image.height;
+    canvas.getContext('2d').drawImage(saved.image, 0, 0);
+    ready = true;
+    cachedKey = cacheKey;
+    capabilities = saved.capabilities;
+    callbacks.onCapabilities?.(capabilities);
+    callbacks.onReady?.();
+    callbacks.onPaint?.();
+    refresh();
+  }
+  function unwatch() {
+    const watchers = waiting.get(cacheKey);
+    watchers?.delete(paintSnapshot);
+    if (watchers?.size === 0) waiting.delete(cacheKey);
+  }
+  function appearance() {
+    const next = fingerprint();
+    if (next === cacheKey) return;
+    unwatch();
+    cacheKey = next;
+    ready = false;
+    if (!waiting.has(cacheKey)) waiting.set(cacheKey, new Set());
+    waiting.get(cacheKey).add(paintSnapshot);
+    paintSnapshot();
+  }
+  const update = (next) => {
+    if (disposed) return;
+    const work =
+      next.workingKey !== undefined && next.workingKey !== props.workingKey;
+    const reaction =
+      next.reactionKey !== undefined && next.reactionKey !== props.reactionKey;
+    props = next;
+    if (still()) {
+      pendingWork = false;
+      pendingReaction = false;
+    }
+    appearance();
+    const queueCommands = !controller?.diagnostics?.()?.ready;
+    if (!still() && (work || reaction)) {
+      if (queueCommands) {
+        pendingWork ||= work;
+        pendingReaction ||= reaction;
+      }
+      promote(
+        work
+          ? 2500 * Math.max(1, Math.min(10, props.workingCycles || 1)) + 5000
+          : 5000,
+      );
+    }
+    controller?.update(props, queueCommands);
+    refresh();
+  };
+  const enter = () => {
+    if (props.interactive) {
+      hovered = true;
+      refresh();
+    }
+  };
+  const leave = () => {
+    hovered = false;
+    refresh();
+  };
+  const down = (event) => {
+    if (!props.interactive || event.button !== 0 || !event.isPrimary || still())
+      return;
+    // Cold surfaces cannot receive the original pointer-down yet. Replay one
+    // original reaction once ready; warm surfaces receive their normal events.
+    if (!controller || !controller.diagnostics?.()?.ready)
+      pendingReaction = true;
+    promote();
+  };
+  canvas.addEventListener('pointerenter', enter);
+  canvas.addEventListener('pointerleave', leave);
+  canvas.addEventListener('pointerdown', down, true);
+  const intersection = new IntersectionObserver((entries) => {
+    visible = entries[0]?.isIntersecting === true;
+    refresh();
+  });
+  intersection.observe(canvas);
+  const resize = new ResizeObserver(() => {
+    appearance();
+    refresh();
+  });
+  resize.observe(canvas);
+  document.addEventListener('visibilitychange', refresh);
+  appearance();
+  refresh();
+  return {
+    update,
+    diagnostics: () => ({
+      ...lastDiagnostics,
+      ...controller?.diagnostics?.(),
+      ready,
+      pending: !ready || !!controller?.diagnostics?.()?.pending,
+      suspended: !controller,
+    }),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      clearTimeout(timer);
+      unwatch();
+      intersection.disconnect();
+      resize.disconnect();
+      canvas.removeEventListener('pointerenter', enter);
+      canvas.removeEventListener('pointerleave', leave);
+      canvas.removeEventListener('pointerdown', down, true);
+      document.removeEventListener('visibilitychange', refresh);
+      lease.dispose();
+    },
+  };
+}
+export const managedAvatarStats = () => ({
+  ...renderBudget.stats(),
+  snapshots: snapshots.size,
+});

package/assets/character-runtime/render-budget.mjs

@@ -0,0 +1,144 @@
+// One budget per document, including separately imported/versioned adapters.
+// Renderers retain their painted 2D canvas when their GPU lease is released.
+const key = Symbol.for('bloom.character.render-budget');
+export function createRenderBudget(
+  limit = 4,
+  schedule = (fn) => requestAnimationFrame(fn),
+) {
+  const entries = new Set();
+  let scheduled = false,
+    serial = 0,
+    peak = 0;
+  const resident = (entry) => entry.starting || entry.controller;
+  function wake() {
+    if (scheduled) return;
+    scheduled = true;
+    schedule(pump);
+  }
+  function stop(entry) {
+    entry.wanted = false;
+    if (entry.controller) {
+      const controller = entry.controller;
+      entry.controller = null;
+      entry.suspend(controller);
+    }
+  }
+  async function start(entry) {
+    entry.starting = true;
+    peak = Math.max(peak, [...entries].filter(resident).length);
+    try {
+      const controller = await entry.start();
+      if (!entry.wanted || entry.removed) entry.suspend(controller);
+      else entry.controller = controller;
+    } catch (error) {
+      entry.failed = true;
+      entry.error(error);
+    } finally {
+      entry.starting = false;
+      if (entry.removed) entries.delete(entry);
+      wake();
+    }
+  }
+  function pump() {
+    scheduled = false;
+    const eligible = [...entries].filter(
+      (e) => !e.removed && !e.failed && e.visible,
+    );
+    const selected = new Set();
+    // Explicit work/touch takes precedence. A single preparing surface keeps
+    // large lists from constructing dozens of native renderers in one task.
+    const ordered = eligible.sort(
+      (a, b) => b.priority - a.priority || b.order - a.order,
+    );
+    let preparing = [...entries].some((e) => resident(e) && e.needsPaint);
+    for (const e of ordered.filter((e) => e.priority >= 2)) {
+      if (selected.size === limit) break;
+      if (e.needsPaint && !resident(e) && preparing) continue;
+      selected.add(e);
+      if (e.needsPaint) preparing = true;
+    }
+    const pending = eligible
+      .filter((e) => e.needsPaint && !selected.has(e))
+      .sort(
+        (a, b) =>
+          Number(!!resident(b)) - Number(!!resident(a)) || a.order - b.order,
+      );
+    if (selected.size < limit && pending.length) {
+      const next =
+        pending.find((e) => resident(e)) ?? (!preparing ? pending[0] : null);
+      if (next) selected.add(next);
+    }
+    for (const e of ordered
+      .filter((e) => !e.needsPaint && !e.still)
+      .sort(
+        (a, b) =>
+          b.priority - a.priority ||
+          Number(!!resident(b)) - Number(!!resident(a)) ||
+          b.order - a.order,
+      )) {
+      if (selected.size === limit) break;
+      selected.add(e);
+    }
+    for (const e of entries) if (!selected.has(e)) stop(e);
+    let count = [...entries].filter(resident).length;
+    for (const e of selected) {
+      e.wanted = true;
+      if (!resident(e) && count < limit) {
+        count++;
+        void start(e);
+        break;
+      }
+    }
+  }
+  return {
+    register(options) {
+      const entry = {
+        visible: false,
+        priority: 0,
+        needsPaint: true,
+        still: false,
+        starting: false,
+        controller: null,
+        wanted: false,
+        removed: false,
+        failed: false,
+        order: ++serial,
+        ...options,
+      };
+      entries.add(entry);
+      wake();
+      return {
+        update(value) {
+          Object.assign(entry, value);
+          if (value.priority >= 2) entry.order = ++serial;
+          wake();
+        },
+        painted() {
+          if (entry.needsPaint) {
+            entry.needsPaint = false;
+            wake();
+          }
+        },
+        fail(error) {
+          entry.failed = true;
+          stop(entry);
+          entry.error(error);
+          wake();
+        },
+        dispose() {
+          entry.removed = true;
+          stop(entry);
+          if (!entry.starting) entries.delete(entry);
+          wake();
+        },
+      };
+    },
+    stats: () => ({
+      limit,
+      resident: [...entries].filter(resident).length,
+      registered: [...entries].filter((e) => !e.removed).length,
+      peak,
+    }),
+  };
+}
+export const renderBudget = (globalThis[key] ??= createRenderBudget());

package/assets/character-runtime/runtime.mjs

@@ -2,11 +2,14 @@
 import createModule from './orbit-characters.mjs';
 import { customizeAppearance, encodeAppearance } from './appearance-codec.mjs';
 import { acquireLegacyEngine, legacyEngineStats } from './legacy-engine.mjs';
+import { createManagedAvatar, managedAvatarStats } from './managed-avatar.mjs';
 
 let modulePromise;
 let serial = 0;
 let frame = 0;
 let lastFrame = -Infinity;
+let nextClient = 0;
+let lastRenderMilliseconds = 0;
 const clients = new Set();
 const category = { shape: 0, color: 1, eyes: 2, eyewear: 3, accessory: 4 };
 function engine() {
@@ -26,7 +29,18 @@ function tick(time) {
   if (document.hidden) return;
   if (time - lastFrame >= 1000 / 30 - 1) {
     lastFrame = time;
-    for (const client of [...clients]) client.render(time / 1000);
+    const batch = [...clients];
+    const started = performance.now();
+    for (let i = 0; i < batch.length; i++) {
+      const index = nextClient % batch.length;
+      nextClient = (index + 1) % batch.length;
+      const client = batch[index];
+      if (clients.has(client)) client.render(time / 1000);
+      // One native render cannot be interrupted, but a crowded page must not
+      // submit every remaining avatar after it has spent its frame allowance.
+      if (performance.now() - started >= 8) break;
+    }
+    lastRenderMilliseconds = performance.now() - started;
   }
   schedule();
 }
@@ -41,8 +55,12 @@ export async function createAvatar(canvas, initial, callbacks = {}) {
   if (!initial.config.character && !initial.legacy)
     throw new Error('A recovered character recipe is required');
   if (initial.portrait) return createPortrait(canvas, initial, callbacks);
-  if (initial.legacy) return createLegacyCharacter(canvas, initial, callbacks);
-  return createLiveCharacter(canvas, initial, callbacks);
+  return createManagedAvatar(canvas, initial, callbacks, createCharacter);
+}
+function createCharacter(canvas, initial, callbacks) {
+  return initial.legacy
+    ? createLegacyCharacter(canvas, initial, callbacks)
+    : createLiveCharacter(canvas, initial, callbacks);
 }
 
 async function createLiveCharacter(
@@ -224,14 +242,15 @@ async function createLiveCharacter(
           submitted &&
           fit &&
           !character.preparationStats().pending &&
-          !character.hasPendingUpdate()
+          !character.hasPendingUpdate() &&
+          fingerprint === pendingFingerprint
         ) {
           dirty = false;
           if (!ready) {
             ready = true;
             callbacks.onReady?.();
           }
-          callbacks.onPaint?.();
+          callbacks.onPaint?.(!transitionImage);
           if (activityMode && workDuration && !workTimer) {
             workTimer = setTimeout(() => {
               workTimer = undefined;
@@ -313,6 +332,14 @@ async function createLiveCharacter(
     dirty = true;
     wake();
   };
+  const work = () => {
+    if (!animate()) return;
+    clearTimeout(workTimer);
+    switchMode(true);
+    play(1);
+    workTimer = undefined;
+    workDuration = 2200 * Math.max(1, Math.min(10, props.workingCycles || 1));
+  };
   let appearanceTimer, pendingFingerprint;
   const applyAppearance = (value) => {
     const recipe = value;
@@ -415,7 +442,7 @@ async function createLiveCharacter(
       dirty = true;
     }
   };
-  const update = (next) => {
+  const update = (next, silent = false) => {
     if (disposed) return;
     props = next;
     const recipe = props.legacy
@@ -456,19 +483,16 @@ async function createLiveCharacter(
     character.setReducedMotion(false);
     if (
       hasWork &&
+      !silent &&
       previousWork !== props.workingKey &&
       props.workingKey !== undefined &&
       animate()
     ) {
-      clearTimeout(workTimer);
-      switchMode(true);
-      play(1);
-      workTimer = undefined;
-      // Count visible activity time, not time spent preparing its scene.
-      workDuration = 2200 * Math.max(1, Math.min(10, props.workingCycles || 1));
+      work();
     }
     if (
       hasWork &&
+      !silent &&
       previousReaction !== props.reactionKey &&
       props.reactionKey !== undefined
     )
@@ -597,6 +621,8 @@ async function createLiveCharacter(
   return {
     update,
     dispose,
+    react,
+    work,
     diagnostics: () => ({
       lastReaction,
       lastReactionKind,
@@ -619,12 +645,12 @@ async function createLegacyCharacter(canvas, initial, callbacks) {
     revision = 0,
     disposed = false,
     latest = initial;
-  const update = async (next) => {
+  const update = async (next, silent = false) => {
     if (disposed) return;
     latest = next;
     const key = JSON.stringify(next.legacy.points ?? null);
     if (shapeKey === key) {
-      controller?.update(next);
+      controller?.update(next, silent);
       return;
     }
     const snapshot = controller?.diagnostics().ready
@@ -661,7 +687,7 @@ async function createLegacyCharacter(canvas, initial, callbacks) {
         return;
       }
       controller = created;
-      controller.update(latest);
+      controller.update(latest, true);
     } catch (error) {
       if (!current()) return;
       shapeKey = undefined;
@@ -670,8 +696,8 @@ async function createLegacyCharacter(canvas, initial, callbacks) {
   };
   await update(initial);
   return {
-    update(next) {
-      void update(next).catch((error) => {
+    update(next, silent = false) {
+      void update(next, silent).catch((error) => {
         if (!disposed) callbacks.onError?.(error);
       });
     },
@@ -680,6 +706,8 @@ async function createLegacyCharacter(canvas, initial, callbacks) {
       ++revision;
       controller?.dispose();
     },
+    react: () => controller?.react(),
+    work: () => controller?.work(),
     diagnostics: () => controller?.diagnostics(),
   };
 }
@@ -746,7 +774,7 @@ function createPortrait(canvas, initial, callbacks) {
       };
       cancel = finish;
       try {
-        controller = await createLiveCharacter(
+        controller = await createManagedAvatar(
           canvas,
           { ...props, paused: true, interactive: false },
           {
@@ -772,6 +800,7 @@ function createPortrait(canvas, initial, callbacks) {
               queueMicrotask(finish);
             },
           },
+          createCharacter,
         );
         if (finished || !current()) {
           controller.dispose();
@@ -811,6 +840,8 @@ const registryKey = Symbol.for('bloom.character.runtimes');
 /** Diagnostics are read on demand; no DOM/debug updates run on the animation clock. */
 export function runtimeStats() {
   return {
+    renderMilliseconds: lastRenderMilliseconds,
+    budget: managedAvatarStats(),
     instances: instances.size,
     active: clients.size,
     scheduled: !!frame,

package/docs/adoption-matrix.mdx

@@ -113,7 +113,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `activity-heatmap` | `@oxy.so/bloom/activity-heatmap` + barrel | universal | `activity-heatmap.mdx` | yes | 1 |  |  |  |  |
 | `address` | `@oxy.so/bloom/address` + barrel | universal | `address.mdx` | yes | 2 | n/a¹ |  |  |  |
 | `admonition` | `@oxy.so/bloom/admonition` + barrel | universal | `admonition.mdx` | yes | 1 |  |  |  |  |
-| `agent-avatar` | `@oxy.so/bloom/agent-avatar` + barrel | universal | `agent-avatar.mdx` | yes | 14 |  |  |  |  |
+| `agent-avatar` | `@oxy.so/bloom/agent-avatar` + barrel | universal | `agent-avatar.mdx` | yes | 15 |  |  |  |  |
 | `agent-chat` | `@oxy.so/bloom/agent-chat` + barrel | web fork | `agent-chat.mdx` | yes | 3 | n/a¹ |  |  | reads |
 | `agent-creator` | `@oxy.so/bloom/agent-creator` + barrel | web fork | `agent-creator.mdx` | yes | 5 | reads |  |  |  |
 | `agent-limits-card` | `@oxy.so/bloom/agent-limits-card` + barrel | universal | `agent-limits-card.mdx` | yes | 2 |  |  |  | reads |
@@ -294,7 +294,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `sticker` | `@oxy.so/bloom/sticker` + barrel | web fork | `sticker.mdx` | yes | 1 |  |  |  |  |
 | `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 85 | n/a¹ |  |  |  |
 | `subtle-hover` | `@oxy.so/bloom/subtle-hover` + barrel | universal | `subtle-hover.mdx` | yes | 1 |  |  |  |  |
-| `surface` | `@oxy.so/bloom/surface` + barrel | web fork | `surface.mdx` | yes | 38 |  |  |  |  |
+| `surface` | `@oxy.so/bloom/surface` + barrel | web fork | `surface.mdx` | yes | 39 |  |  |  |  |
 | `surfaces` | `@oxy.so/bloom/surfaces` + barrel | web fork | `alert.mdx` | yes | 3 |  |  |  |  |
 | `swipe-row` | `@oxy.so/bloom/swipe-row` + barrel | universal | `swipe-row.mdx` | yes | 2 |  |  |  |  |
 | `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 7 | reads | reads |  | reads |
@@ -307,7 +307,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 5 |  | reads |  |  |
 | `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 17 | reads | reads |  |  |
 | `textarea` | `@oxy.so/bloom/textarea` + barrel | universal | `textarea.mdx` | yes | 4 | reads | reads |  | n/a¹ |
-| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 353 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 354 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 2 | n/a¹ |  |  |  |
 | `toast` | `@oxy.so/bloom/toast` + barrel | universal | `toast.mdx` | yes | 17 |  |  |  |  |
 | `tooltip` | `@oxy.so/bloom/tooltip` + barrel | web fork | `tooltip.mdx` | yes | 1 |  |  |  |  |

package/docs/agent-avatar.mdx

@@ -38,12 +38,21 @@ Alien avatars have been removed from the available catalog. Saved aliens, mascot
 
 `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. 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. Animated characters each need a graphics surface. Use `portrait` for galleries and selectors. Static thumbnail preparation is serialized, retains a bounded cache and releases its graphics surface after painting. Offscreen/background avatars pause; unmount releases listeners and rendering resources.
+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.
+
+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.
+
+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 scripts/verify-avatar-render-budget.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. Separate WebViews cannot share engine memory or graphics contexts.
+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.
 
 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/bottom-sheet.mdx

@@ -56,7 +56,7 @@ On web the open sheet owns the keyboard like a dialog does (`overlay/ModalKeyboa
 | `onDismiss?` | `() => void` | — | Fires when the sheet finishes closing. |
 | `enablePanDownToClose?` | `boolean` | `true` | |
 | `enableHandlePanningGesture?` | `boolean` | `true` | |
-| `onDismissAttempt?` | `() => boolean` | — | Return `false` to veto a dismiss attempt. |
+| `onDismissAttempt?` | `() => boolean` | — | Return `false` to veto user Back/backdrop/Escape/pan before closing. Explicit ref dismissal bypasses this guard and always reports completion. |
 | `detached?` | `boolean` | `false` | Float with horizontal margins and rounded corners on all sides. |
 | `showHandle?` | `boolean` | `true` | Toggle the drag handle pill. |
 | `backdropOpacity?` | `number` | `0.5` | Opacity (0–1) of the dimming backdrop once fully visible. |

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

@@ -53,12 +53,17 @@ function AgentAvatarProvider({
   }, [runtimeUrl]);
   const value = (0, _react.useMemo)(() => ({
     runtimeUrl,
-    capabilitiesByKey,
     reportCapabilities
-  }), [runtimeUrl, capabilitiesByKey, reportCapabilities]);
+  }), [runtimeUrl, reportCapabilities]);
+  const catalog = (0, _react.useMemo)(() => ({
+    capabilitiesByKey
+  }), [capabilitiesByKey]);
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_context.CharacterRuntimeContext.Provider, {
     value: value,
-    children: children
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_context.CharacterCapabilitiesContext.Provider, {
+      value: catalog,
+      children: children
+    })
   });
 }
 //# sourceMappingURL=AgentAvatarProvider.js.map