@oxy.so/bloom 7.0.1 → 7.1.1

package/assets/character-runtime/README.md

@@ -0,0 +1,55 @@
+# Recovered character renderer
+
+Serve this directory unchanged from a static URL and pass runtime.mjs's URL to
+AgentAvatarProvider. The runtime loads lazily when an avatar becomes visible.
+Serve .mjs as JavaScript and .wasm as application/wasm.
+
+The four generated engine files are preserved byte for byte from the supplied
+local beta. integrity.json records their SHA-256 hashes. The complete supplied
+folder, including single-thread and threaded versions, was also backed up. The
+supplied folder contained no engine source or license text; this directory does
+not assign Bloom's license to those binaries.
+
+runtime.mjs is an adapter for the original engine, retaining its appearance,
+materials and animations. It owns loading, selection, input, display scaling and
+resource lifetime. There is no replacement mesh renderer in the product.
+
+Beta characters share one engine per document and all avatars share a 30fps
+clock. Legacy contours isolate rendering modules to keep native geometry caches
+from returning another silhouette; one worker prepares their scenes. Unused
+modules are released. Static portrait preparation is serialized, cached (up to 64 images), and
+releases its graphics surfaces after painting. Offscreen/background characters
+stop rendering; pause and reduced motion freeze a complete visible frame. The
+binary's initial reduced-motion flag can produce transparent frames; the adapter
+freezes its own clock after painting instead.
+
+Current editing supports the beta's original catalog combinations and actual
+availability constraints. appearance-codec.mjs validates explicit RGB and optional eye
+transform edits through the original engine. Untouched presets keep their bytes.
+
+legacy-geometry.mjs transforms copies of prepared scene assemblies: existing
+Bloom contours deform the body, pose deltas, normals and fur roots. The packaged
+meshes, manifest and WASM remain untouched. The parser checks structural mesh
+keys, counts, finite values and layout; it is tied to these recovered binaries.
+legacy-worker.mjs applies the deformation before the original renderer consumes
+it. The original wave and working activity operate on this geometry.
+
+Eight distinct paper/blob contours use this path. Circle, triangle, flower,
+diamond and heart recipes reuse the original beta shapes instead of duplicates.
+Alien avatars are removed from the visible catalog, with saved-data compatibility. The
+migrated bodies use the original catalog eyes at their authored proportions and
+animations; old expression/eye transform fields no longer alter the 3D face.
+Migrated bodies support original eyewear and accessories. Headwear, Bulb, bow
+and Tuft receive rigid contour-relative translations; eyewear and headphones
+keep original placement. A bounded reference cache identifies attachment meshes
+without changing eyes, materials or fur vectors. Intact presets retain authored
+signature reactions; edited and migrated bodies fall back to the original Wave.
+Mascots and hidden faces still use SVG.
+Original material/grain effects become the beta's 3D surface.
+
+Browser gates (with Storybook running) are scripts/verify-character-avatars.mjs
+and scripts/verify-legacy-avatars.mjs. They inspect painted pixels, interaction,
+activity, transitions and resource cleanup, not just preparation callbacks.
+
+The optional native bridge uses separate WebViews, which cannot share the web
+engine/context caches. Physical-device validation remains pending.

package/assets/character-runtime/appearance-codec.mjs

@@ -0,0 +1,149 @@
+/**
+ * Bounded codec for the original renderer's ORBAST1 appearance records.
+ * Verified against the 108 recovered presets. Unsupported extensions fail closed;
+ * opaque model fields are retained, never guessed into new geometry parameters.
+ * This is an optional runtime asset and imports no package into Bloom's graph.
+ */
+const MAGIC = 'ORBAST1\0';
+const RIG = 'ORBRIG1\0';
+const HERE = 'ORBHERE1';
+const LIMIT = 65536;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+const fail = (message) => { throw new Error(`Appearance codec: ${message}`); };
+const finite = (n) => typeof n === 'number' && Number.isFinite(n) && Math.abs(n) <= 3.4028234663852886e38;
+function vector(value, n, label, positive = false) {
+  if (!Array.isArray(value) || value.length !== n || value.some(v => !finite(v) || (positive && v <= 0))) fail(`invalid ${label}`);
+  return value.slice();
+}
+function transform(value) {
+  return { position: vector(value.position ?? [0,0,0],3,'position'), rotation: vector(value.rotation ?? [0,0,0],3,'rotation'), scale: vector(value.scale ?? [1,1,1],3,'scale',true) };
+}
+class Reader {
+  constructor(bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.length > LIMIT) fail('expected at most 64 KB of Uint8Array');
+    this.b = bytes; this.v = new DataView(bytes.buffer,bytes.byteOffset,bytes.byteLength); this.i = 0;
+  }
+  need(n) { if (!Number.isInteger(n) || n < 0 || this.i+n > this.b.length) fail('truncated record'); }
+  bytes(n) { this.need(n); const b=this.b.slice(this.i,this.i+n);this.i+=n;return b; }
+  u8() { this.need(1);return this.b[this.i++]; }
+  bool() { const n=this.u8();if(n>1)fail('invalid presence flag');return n; }
+  u32() { this.need(4);const n=this.v.getUint32(this.i,true);this.i+=4;return n; }
+  count() { const n=this.u32();if(n>256)fail('collection exceeds limit');return n; }
+  f() { this.need(4);const n=this.v.getFloat32(this.i,true);this.i+=4;if(!finite(n))fail('non-finite scalar');return n; }
+  vec(n) { return Array.from({length:n},()=>this.f()); }
+  str() { const n=this.u32();if(n>4096)fail('string exceeds limit');return textDecoder.decode(this.bytes(n)); }
+  zero(n=1) { for(let j=0;j<n;j++)if(this.u8()!==0)fail('unsupported model extension'); }
+  tag(s) { return this.i+s.length <= this.b.length && s.split('').every((c,j)=>this.b[this.i+j]===c.charCodeAt(0)); }
+  trans() { return {position:this.vec(3),rotation:this.vec(3),scale:this.vec(3)}; }
+  optional(fn) { return this.bool() ? fn.call(this) : null; }
+  map(read) { const entries=[];const keys=new Set();for(let n=this.count();n;n--){const key=this.str();if(keys.has(key))fail('duplicate map key');keys.add(key);entries.push([key,read.call(this)]);}return Object.fromEntries(entries); }
+}
+class Writer {
+  constructor() { this.a=[]; }
+  bytes(b) { for(const n of b)this.a.push(n);if(this.a.length>LIMIT)fail('record exceeds 64 KB'); }
+  u8(n) { if(!Number.isInteger(n)||n<0||n>255)fail('invalid byte');this.a.push(n); }
+  u32(n) { if(!Number.isInteger(n)||n<0||n>4096)fail('invalid length');const b=new Uint8Array(4);new DataView(b.buffer).setUint32(0,n,true);this.bytes(b); }
+  f(n) { if(!finite(n))fail('non-finite scalar');const b=new Uint8Array(4);new DataView(b.buffer).setFloat32(0,n,true);this.bytes(b); }
+  vec(a,n) { vector(a,n,'vector').forEach(v=>this.f(v)); }
+  str(s) { if(typeof s!=='string')fail('invalid string');const b=textEncoder.encode(s);this.u32(b.length);this.bytes(b); }
+  tag(s) { this.bytes(textEncoder.encode(s)); }
+  zero(n=1) { for(let j=0;j<n;j++)this.u8(0); }
+  trans(t) { this.vec(t.position,3);this.vec(t.rotation,3);this.vec(t.scale,3); }
+  optional(v,fn) { this.u8(v==null?0:1);if(v!=null)fn.call(this,v); }
+  map(m,fn) { const entries=Object.entries(m);if(entries.length>256)fail('collection exceeds limit');this.u32(entries.length);for(const[k,v]of entries){this.str(k);fn.call(this,v);} }
+  finish() { if(this.a.length>LIMIT)fail('record exceeds 64 KB');return Uint8Array.from(this.a); }
+}
+function readModel(r) {
+  // Only the observed zero-valued model prefix is supported; its schema is unknown.
+  r.zero(4);
+  const m={bodyScale:r.vec(3),upperBodyStart:r.f(),upperBodyScale:r.f(),eyes:[]};
+  for(let j=0;j<2;j++){r.zero();m.eyes.push(r.optional(r.trans));}
+  // Unnamed flags and scalar remain opaque until their semantics are proven.
+  m.opaqueEyeFlags=[r.bool(),r.bool(),r.bool()];
+  m.opaqueEyeScalar=m.eyes.some(Boolean)?r.f():null;
+  m.eyeScale=r.vec(3);m.pupilScale=r.vec(3);
+  m.eyewear=r.optional(r.trans);r.zero();
+  m.accessories=r.map(r.trans);
+  m.materials=r.map(function(){const flags=this.u8();if(flags>7)fail('unsupported material flags');return {flags,albedo:flags&1?this.vec(3):null,roughness:flags&2?this.f():null,reflectance:flags&4?this.f():null};});
+  r.zero();m.headphonesCushionScale=r.vec(3);return m;
+}
+function writeModel(w,m) {
+  w.zero(4);w.vec(m.bodyScale,3);w.f(m.upperBodyStart);w.f(m.upperBodyScale);
+  if(!Array.isArray(m.eyes)||m.eyes.length!==2)fail('expected two eye transforms');
+  for(const eye of m.eyes){w.zero();w.optional(eye,w.trans);}
+  if(!Array.isArray(m.opaqueEyeFlags)||m.opaqueEyeFlags.length!==3)fail('invalid model flags');
+  for(const n of m.opaqueEyeFlags){if(n!==0&&n!==1)fail('invalid model flag');w.u8(n);}
+  if(m.eyes.some(Boolean))w.f(m.opaqueEyeScalar);
+  w.vec(m.eyeScale,3);w.vec(m.pupilScale,3);w.optional(m.eyewear,w.trans);w.zero();
+  w.map(m.accessories,w.trans);
+  w.map(m.materials,function(mat){const flags=mat.flags;if(!Number.isInteger(flags)||flags<0||flags>7)fail('unsupported material flags');this.u8(flags);if(flags&1)this.vec(mat.albedo,3);if(flags&2)this.f(mat.roughness);if(flags&4)this.f(mat.reflectance);});
+  w.zero();w.vec(m.headphonesCushionScale,3);
+}
+/** Decode only recognized, fully consumed record layouts. */
+export function decodeAppearance(bytes) {
+  const r=new Reader(bytes);if(!r.tag(MAGIC))fail('unsupported record version');r.i+=8;
+  const a={version:1,shape:r.str(),color:r.str(),eyes:r.str(),eyewear:r.str()};
+  a.accessories=Array.from({length:r.count()},()=>r.str());a.accessoryColors=r.map(r.str);
+  a.constrained=r.bool();a.depth=r.f();a.model=r.optional(function(){return readModel(this);});
+  a.rig=null;a.hereCharacter=null;
+  if(r.tag(RIG)){r.i+=8;a.rig=r.vec(5);}
+  if(r.tag(HERE)){r.i+=8;a.hereCharacter={id:r.str(),name:r.str()};}
+  if(r.i!==bytes.length)fail('unsupported trailing extension');return a;
+}
+/** Encode a decoded record without changing its selection or opaque metadata. */
+export function encodeAppearance(a) {
+  if(a.version!==1)fail('unsupported record version');const w=new Writer();w.tag(MAGIC);
+  for(const k of ['shape','color','eyes','eyewear'])w.str(a[k]);
+  if(!Array.isArray(a.accessories)||a.accessories.length>256)fail('invalid accessories');
+  w.u32(a.accessories.length);a.accessories.forEach(v=>w.str(v));w.map(a.accessoryColors,w.str);
+  if(a.constrained!==0&&a.constrained!==1)fail('invalid constrained flag');w.u8(a.constrained);w.f(a.depth);
+  w.optional(a.model,function(m){writeModel(this,m);});
+  if(a.rig){w.tag(RIG);w.vec(a.rig,5);}
+  if(a.hereCharacter){w.tag(HERE);w.str(a.hereCharacter.id);w.str(a.hereCharacter.name);}
+  return w.finish();
+}
+function defaultModel() {
+  return {bodyScale:[1,1,1],upperBodyStart:Math.fround(.35),upperBodyScale:1,eyes:[null,null],opaqueEyeFlags:[0,0,0],opaqueEyeScalar:null,eyeScale:[1,1,1],pupilScale:[1,1,1],eyewear:null,accessories:{},materials:{},headphonesCushionScale:[1,1,1]};
+}
+function rgb(value) {
+  if(typeof value==='string'){
+    if(!/^#[\da-f]{6}$/i.test(value))fail('bodyColor must be #RRGGBB');
+    return [1,3,5].map(i=>parseInt(value.slice(i,i+2),16)/255);
+  }
+  const a=vector(value,3,'bodyColor');if(a.some(v=>v<0||v>1))fail('bodyColor outside [0,1]');return a;
+}
+/**
+ * Return validated/normalized original-engine state. Does not mutate input bytes
+ * or the Character. Caller restores the result once after selections settle.
+ * Named Here presets are protected: demotion changes their authored appearance.
+ * Explicit {allowPresetDemotion:true} opts into this visible change for research;
+ * consumers should normally customize an already editable component state.
+ * Supports bodyColor (#RRGGBB or RGB01), bodyScale, eyeTransforms (two transforms),
+ * eyeScale, pupilScale, restingEyeClosure and eyeGazeScale. Unsupported keys throw.
+ * Eye transform rotations are degrees; positions use renderer body units.
+ */
+export function customizeAppearance(engine,bytes,patch,options={}) {
+  const allowed=new Set(['bodyColor','bodyScale','eyeTransforms','eyeScale','pupilScale','restingEyeClosure','eyeGazeScale']);
+  if(!patch||typeof patch!=='object'||Array.isArray(patch))fail('invalid patch');
+  for(const key of Object.keys(patch))if(!allowed.has(key))fail(`unsupported patch ${key}`);
+  if(typeof engine?.validateAppearance!=='function'||typeof engine?.normalizeAppearance!=='function')fail('original validator is required');
+  const a=decodeAppearance(bytes);
+  if(Object.keys(patch).length===0)return bytes.slice();
+  if(a.hereCharacter&&!options.allowPresetDemotion)fail('named preset customization would change its authored appearance');
+  a.hereCharacter=null;a.model??=defaultModel();const m=a.model;
+  if(patch.bodyColor!==undefined){const prev=m.materials.body??{flags:0,albedo:null,roughness:null,reflectance:null};m.materials.body={...prev,flags:prev.flags|1,albedo:rgb(patch.bodyColor)};}
+  for(const key of ['bodyScale','eyeScale','pupilScale'])if(patch[key]!==undefined)m[key]=vector(patch[key],3,key,true);
+  if(patch.eyeTransforms!==undefined){
+    if(!Array.isArray(patch.eyeTransforms)||patch.eyeTransforms.length!==2)fail('expected two eyeTransforms');
+    m.eyes=patch.eyeTransforms.map(transform);m.opaqueEyeFlags=[0,1,1];m.opaqueEyeScalar??=0;
+  }
+  if(patch.restingEyeClosure!==undefined||patch.eyeGazeScale!==undefined){
+    a.rig??=[0,1,1,1,1];
+    if(patch.restingEyeClosure!==undefined){const n=patch.restingEyeClosure;if(!finite(n)||n<0||n>1)fail('invalid restingEyeClosure');a.rig[0]=n;}
+    if(patch.eyeGazeScale!==undefined){const v=vector(patch.eyeGazeScale,2,'eyeGazeScale');if(v.some(n=>n<0))fail('negative eyeGazeScale');a.rig[3]=v[0];a.rig[4]=v[1];}
+  }
+  const result=encodeAppearance(a);const error=engine.validateAppearance(result);if(error)fail(error);
+  const normalized=engine.normalizeAppearance(result);const normalizedError=engine.validateAppearance(normalized);if(normalizedError)fail(normalizedError);
+  return normalized;
+}

package/assets/character-runtime/integrity.json

@@ -0,0 +1,6 @@
+{
+  "orbit-characters.mjs": "f3ba670dadba954df1618af83fa314641a4cfddd3597aca93a191c264374eed7",
+  "orbit-characters.data": "ffefb69b44f815cccb5f07b4d951d479e527dbabdca68ad9986cf695f9b9c440",
+  "orbit-characters.wasm": "c15f3692305c1385a12524e877199ba279b8d53e6bd37a9e533d626f12fcb94b",
+  "preparation-worker.mjs": "3caeea63dc364a0dc852a16b704323874902eb0f2a02cc9a2ddf4dc414ae8368"
+}

package/assets/character-runtime/legacy-engine.mjs

@@ -0,0 +1,105 @@
+import createModule from './orbit-characters.mjs';
+
+const pool = new Map();
+const pending = new Map();
+let worker,
+  idleTimer,
+  sequence = 0;
+function preparationWorker() {
+  if (worker) return worker;
+  worker = new Worker(new URL('./legacy-worker.mjs', import.meta.url), {
+    type: 'module',
+  });
+  worker.onmessage = ({ data }) => {
+    const entry = pending.get(data.id);
+    if (!entry) return;
+    pending.delete(data.id);
+    entry.complete(data);
+  };
+  worker.onerror = () => {
+    const failed = [...pending.values()];
+    pending.clear();
+    worker?.terminate();
+    worker = undefined;
+    for (const entry of failed)
+      entry.complete({
+        error: 'Legacy character preparation failed',
+        milliseconds: 0,
+      });
+  };
+  return worker;
+}
+
+/** Separate geometry caches for different contours; one shared preparation worker.
+ * Unused rendering modules are released, never retained in an unbounded catalog.
+ */
+export async function acquireLegacyEngine(points) {
+  clearTimeout(idleTimer);
+  const key = JSON.stringify(points);
+  let entry = pool.get(key);
+  if (!entry) {
+    entry = { references: 0, module: null };
+    entry.module = createModule({
+      locateFile: (file) => new URL(file, import.meta.url).href,
+    }).then((module) => {
+      module.orbitPrepare = (id, appearance, quality, cacheKey, activities) => {
+        const request = ++sequence;
+        pending.set(request, {
+          owner: entry,
+          complete: (result) => {
+            module.orbitCompletePreparation(
+              id,
+              result.bytes ?? null,
+              result.error || '',
+              result.milliseconds || 0,
+            );
+          },
+        });
+        try {
+          preparationWorker().postMessage({
+            id: request,
+            appearance,
+            quality,
+            key: cacheKey,
+            activities,
+            points,
+          });
+        } catch (error) {
+          pending.delete(request);
+          module.orbitCompletePreparation(id, null, String(error), 0);
+        }
+      };
+      return module;
+    });
+    pool.set(key, entry);
+  }
+  entry.references++;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    if (--entry.references !== 0) return;
+    pool.delete(key);
+    for (const [id, request] of pending)
+      if (request.owner === entry) pending.delete(id);
+    if (!pool.size)
+      idleTimer = setTimeout(() => {
+        if (!pool.size) {
+          worker?.terminate();
+          worker = undefined;
+        }
+      }, 0);
+  };
+  try {
+    return { module: await entry.module, release };
+  } catch (error) {
+    release();
+    throw error;
+  }
+}
+
+export const legacyEngineStats = () => ({
+  modules: pool.size,
+  pending: pending.size,
+  worker: !!worker,
+});

package/assets/character-runtime/legacy-geometry.mjs

@@ -0,0 +1,166 @@
+// Adapter for the recovered renderer's prepared vertex layout. Packaged meshes,
+// resource manifests, the WASM binary, and the appearance record stay untouched.
+const decoder = new TextDecoder(), encoder = new TextEncoder();
+const BODY = ':body:no-shadow:studio-fur-v6:';
+// Highlights are separate non-shadow-casting meshes in the original renderer.
+const SURFACES = [':surface:shadow', ':surface:no-shadow'];
+const SURFACE_KEY = /^[a-f0-9]{64}:surface:(?:shadow|no-shadow)$/;
+const FUR_SURFACE_KEY = /^[a-f0-9]{64}:surface:shadow:studio-fur-v6:/;
+const STRIDE = 96, TAU = Math.PI * 2;
+function invalid(message) { throw new Error(`Unsupported prepared avatar geometry: ${message}`); }
+function finite(value) { if (!Number.isFinite(value)) invalid('non-finite coordinate'); return value; }
+function findAll(bytes, text) {
+  const needle = encoder.encode(text), result = [];
+  outer: for (let i = 0; i <= bytes.length - needle.length; i++) {
+    if (bytes[i] !== needle[0]) continue;
+    for (let j = 1; j < needle.length; j++) if (bytes[i + j] !== needle[j]) continue outer;
+    result.push(i);
+  }
+  return result;
+}
+
+/** Inspect the bounded, length-prefixed mesh records; reject unknown layouts. */
+export function inspectLegacyAssembly(bytes) {
+  if (!(bytes instanceof Uint8Array) || bytes.length < 400) invalid('truncated assembly');
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const uint = at => { if (at < 0 || at + 4 > bytes.length) invalid('truncated count'); return view.getUint32(at, true); };
+  const bodies = findAll(bytes, BODY);
+  if (bodies.length !== 1) invalid('expected one furry body');
+  const bodyStart = bodies[0] - 64;
+  const starts = [bodyStart, ...SURFACES.flatMap(kind => findAll(bytes, kind)
+    .map(i => i - 64)
+    .filter(i => {
+      if (i <= bodyStart || i < 4) return false;
+      const length = uint(i - 4);
+      if (length < 79 || length > 8192 || i + length > bytes.length) return false;
+      const name = decoder.decode(bytes.subarray(i, i + length));
+      return SURFACE_KEY.test(name) || FUR_SURFACE_KEY.test(name);
+    }))
+    .sort((a, b) => a - b)];
+  const meshCount = uint(0);
+  if (meshCount !== starts.length || meshCount > 40) invalid('mesh count/key mismatch');
+  const parts = starts.map((nameOffset, part) => {
+    const nameLength = uint(nameOffset - 4), name = decoder.decode(bytes.subarray(nameOffset, nameOffset + nameLength));
+    if (nameLength < 79 || nameLength > 8192 || nameOffset + nameLength > bytes.length || !/^[a-f0-9]{64}:/.test(name)) invalid('mesh identity');
+    if (part === 0 ? !name.includes(BODY) : !SURFACE_KEY.test(name) && !FUR_SURFACE_KEY.test(name)) invalid('mesh kind');
+    const vertexCount = uint(nameOffset + nameLength), vertexOffset = nameOffset + nameLength + 4;
+    if (vertexCount < 3 || vertexCount > 1000000) invalid('vertex count');
+    let at = vertexOffset + vertexCount * STRIDE;
+    const count32 = uint(at); at += 4;
+    if (count32 > 6000000 || at + count32 * 4 > bytes.length) invalid('32-bit indices');
+    for (let i = 0; i < count32; i++) if (uint(at + i * 4) >= vertexCount) invalid('index outside mesh');
+    at += count32 * 4;
+    const count16 = uint(at); at += 4;
+    if (count16 > 6000000 || at + count16 * 2 > bytes.length) invalid('16-bit indices');
+    for (let i = 0; i < count16; i++) if (view.getUint16(at + i * 2, true) >= vertexCount) invalid('index outside mesh');
+    at += count16 * 2;
+    // Empty supplemental vertex buffer followed by three boolean mesh flags.
+    if (at + 7 > bytes.length || uint(at) !== 0 || bytes[at + 4] > 1 || bytes[at + 5] > 1 || bytes[at + 6] > 1) invalid('mesh flags');
+    const hasFur = bytes[at + 6] === 1; at += 7;
+    const furCount = hasFur ? uint(at) : 0, furOffset = hasFur ? at + 4 : 0;
+    if (furCount > 1000000 || hasFur && furOffset + furCount * 64 > bytes.length) invalid('fur records');
+    const geometryEnd = hasFur ? furOffset + furCount * 64 : at;
+    if (geometryEnd > (starts[part + 1] === undefined ? bytes.length : starts[part + 1] - 4)) invalid('overlapping meshes');
+    if (part === 0 && !hasFur) invalid('body lacks fur layout');
+    if (FUR_SURFACE_KEY.test(name) && !hasFur) invalid('accessory lacks fur layout');
+    const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+    for (let i = 0; i < vertexCount; i++) for (let k = 0; k < 24; k++) {
+      const value = finite(view.getFloat32(vertexOffset + i * STRIDE + k * 4, true));
+      if (k < 3) { min[k] = Math.min(min[k], value); max[k] = Math.max(max[k], value); }
+    }
+    return { part, name, nameOffset, nameLength, vertexCount, vertexOffset, furCount, furOffset, bounds: { min, max } };
+  });
+  return { body: parts[0], parts };
+}
+
+function mapper({ points, radii, depthScale = 1 }) {
+  if (!Number.isFinite(depthScale) || depthScale <= 0 || depthScale > 4) invalid('depth scale');
+  if (points && radii || !points && !radii) invalid('provide points or radii');
+  const count = (points || radii).length;
+  if (count < 16 || count > 65536) invalid('contour resolution');
+  if (points) for (const p of points) { if (p.length !== 2) invalid('contour point'); p.forEach(finite); }
+  else for (const radius of radii) if (!(finite(radius) > 0)) invalid('contour radius');
+  return (x, y, z) => {
+    const radius = Math.hypot(x, y), angle = (Math.atan2(y, x) + TAU) % TAU;
+    const slot = angle / TAU * count, index = Math.floor(slot), t = slot - index, next = (index + 1) % count;
+    if (points) return [radius * (points[index][0] * (1 - t) + points[next][0] * t), radius * (points[index][1] * (1 - t) + points[next][1] * t), z * depthScale];
+    const scale = radii[index] * (1 - t) + radii[next] * t;
+    return [x * scale, y * scale, z * depthScale];
+  };
+}
+function derivative(map, p) {
+  const epsilon = .00005, base = map(...p);
+  const columns = [0, 1, 2].map(k => { const q = [...p]; q[k] += epsilon; return map(...q).map((v, i) => (v - base[i]) / epsilon); });
+  const [a, b, c] = columns;
+  const cross = (u, v) => [u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]];
+  const inverse = [cross(b, c), cross(c, a), cross(a, b)];
+  const determinant = a.reduce((sum, v, i) => sum + v * inverse[0][i], 0);
+  if (Math.abs(determinant) < .000001) invalid('singular contour');
+  return { base, vector: v => [0, 1, 2].map(i => columns.reduce((sum, col, j) => sum + col[i] * v[j], 0)), normal: v => [0, 1, 2].map(i => inverse.reduce((sum, col, j) => sum + col[i] * v[j], 0) / determinant) };
+}
+
+/** Rigid attachment anchors on the source circle, in the engine's XY units.
+ * Headwear attaches at the crown, bow at the chin, tuft on the upper-left rim.
+ * Eyewear and headphones retain the original engine's face/ear fitting.
+ */
+export function legacyAttachmentOffset(points, accessory) {
+  let anchor;
+  if (accessory === 'bow') anchor = [0, -1, 0];
+  else if (accessory === 'three_lobe') anchor = [-.5, Math.sqrt(.75), 0];
+  else if (['beanie', 'hat', 'beret', 'orb', 'crown'].includes(accessory)) anchor = [0, 1, 0];
+  else return undefined;
+  return mapper({ points })(...anchor).map((value, i) => value - anchor[i]);
+}
+
+/**
+ * Deform a COPY of one prepared circular body. points samples its new XY outline
+ * counterclockwise from +X, in renderer units (the source circle radius is 1).
+ * radii is the alternative polar representation. geometryKey is a SHA-256 hex
+ * identity of the source + deformation, used for the renderer's geometry cache.
+ * Attachments may explicitly transform a numbered part around an origin.
+ */
+export function deformLegacyAssembly(bytes, options) {
+  const info = inspectLegacyAssembly(bytes), result = bytes.slice();
+  if (!/^[a-f0-9]{64}$/.test(options.geometryKey || '')) invalid('missing geometry cache key');
+  const view = new DataView(result.buffer), map = mapper(options);
+  const read = at => [0, 1, 2].map(i => view.getFloat32(at + i * 4, true));
+  const write = (at, values) => values.forEach((v, i) => view.setFloat32(at + i * 4, finite(v), true));
+  const unit = v => { const n = Math.hypot(...v); return n > 1e-9 ? v.map(x => x / n) : v; };
+  function transform(part, mapping) {
+    for (let i = 0; i < part.vertexCount; i++) {
+      const at = part.vertexOffset + i * STRIDE, p = read(at), d = derivative(mapping, p);
+      // The two pose positions are DELTAS: preserve zero as zero and deform the
+      // target position before subtracting the newly transformed base.
+      for (const offset of [24, 48]) { const delta = read(at + offset), target = mapping(...p.map((v, k) => v + delta[k])); write(at + offset, target.map((v, k) => v - d.base[k])); }
+      for (const offset of [12, 36, 60, 84]) write(at + offset, unit(d.normal(read(at + offset))));
+      write(at, d.base);
+    }
+    for (let i = 0; i < part.furCount; i++) {
+      const at = part.furOffset + i * 64, d = derivative(mapping, read(at));
+      write(at, d.base); write(at + 12, unit(d.normal(read(at + 12)))); write(at + 24, unit(d.vector(read(at + 24))));
+    }
+    result.set(encoder.encode(options.geometryKey), part.nameOffset);
+  }
+  transform(info.body, map);
+  for (const attachment of options.attachments || []) {
+    const part = info.parts[attachment.part];
+    if (!part || part.part === 0) invalid('attachment index');
+    const scale = attachment.scale || [1, 1, 1], origin = attachment.origin || [0, 0, 0], translate = attachment.translate || [0, 0, 0];
+    if ([scale, origin, translate].some(v => v.length !== 3 || v.some(x => !Number.isFinite(x))) || scale.some(x => x <= 0)) invalid('attachment transform');
+    transform(part, (...p) => p.map((v, k) => (v - origin[k]) * scale[k] + origin[k] + translate[k]));
+    // Independent transformed parts must not alias the body's cache identity.
+    const key = options.attachmentKeys?.[attachment.part];
+    if (!/^[a-f0-9]{64}$/.test(key || '')) invalid('attachment cache key');
+    result.set(encoder.encode(key), part.nameOffset);
+  }
+  // Keep original extents while admitting moved accessories and the new body.
+  const transformed = [info.body, ...(options.attachments || []).map(a => info.parts[a.part])];
+  for (const part of transformed) for (let i = 0; i < part.vertexCount; i++) {
+    const p = read(part.vertexOffset + i * STRIDE);
+    for (let k = 0; k < 3; k++) {
+      view.setFloat32(4 + k * 4, Math.min(view.getFloat32(4 + k * 4, true), p[k]), true);
+      view.setFloat32(16 + k * 4, Math.max(view.getFloat32(16 + k * 4, true), p[k]), true);
+    }
+  }
+  return result;
+}

package/assets/character-runtime/legacy-worker.mjs

@@ -0,0 +1,85 @@
+// Shared preparation worker. Only copies of completed scenes are deformed;
+// the recovered engine, packaged meshes and native manifests remain intact.
+import createModule from './orbit-characters.mjs';
+import { decodeAppearance, encodeAppearance } from './appearance-codec.mjs';
+import {
+  deformLegacyAssembly,
+  inspectLegacyAssembly,
+  legacyAttachmentOffset,
+} from './legacy-geometry.mjs';
+const engine = createModule({
+  locateFile: (file) => new URL(file, import.meta.url).href,
+});
+const digest = async (value) =>
+  Array.from(
+    new Uint8Array(
+      await crypto.subtle.digest('SHA-256', typeof value === 'string' ? new TextEncoder().encode(value) : value),
+    ),
+    (byte) => byte.toString(16).padStart(2, '0'),
+  ).join('');
+// Cache only identities, never the large prepared buffers. The same face with
+// no accessories tells us exactly which meshes belong to eyes and eyewear.
+const faceIdentities = new Map();
+async function accessoryTransforms(module, data, source) {
+  const appearance = decodeAppearance(data.appearance);
+  // The editor selects one accessory. Preserve any unknown multi-accessory
+  // state rather than guessing which of its pieces should move together.
+  if (appearance.accessories.length !== 1) return {};
+  const translate = legacyAttachmentOffset(data.points, appearance.accessories[0]);
+  if (!translate || translate.every(value => Math.abs(value) < 1e-6)) return {};
+  appearance.accessories = [];
+  appearance.accessoryColors = {};
+  if (appearance.model) appearance.model.accessories = {};
+  const bytes = encodeAppearance(appearance);
+  const key = `${await digest(bytes)}:${data.quality}:${data.activities}`;
+  let names = faceIdentities.get(key);
+  if (!names) {
+    const base = module.orbitPrepareAssembly(bytes, data.quality, `${data.key}:attachment-base`, data.activities);
+    if (!base.bytes) throw new Error(base.error || 'Accessory reference preparation failed');
+    names = new Set(inspectLegacyAssembly(base.bytes).parts.slice(1).map(part => part.name));
+    faceIdentities.set(key, names);
+    if (faceIdentities.size > 32) faceIdentities.delete(faceIdentities.keys().next().value);
+  }
+  // Do not move anything unless every original face mesh survives unchanged.
+  const current = new Set(source.parts.slice(1).map(part => part.name));
+  if ([...names].some(name => !current.has(name))) return {};
+  const attachments = source.parts.slice(1)
+    .filter(part => !names.has(part.name))
+    .map(part => ({ part: part.part, translate }));
+  const attachmentKeys = {};
+  for (const attachment of attachments) attachmentKeys[attachment.part] = await digest(
+    JSON.stringify([source.parts[attachment.part].name, translate]),
+  );
+  return { attachments, attachmentKeys };
+}
+let queue = Promise.resolve();
+self.onmessage = ({ data }) => {
+  queue = queue.then(async () => {
+    try {
+      const module = await engine;
+      const result = module.orbitPrepareAssembly(
+        data.appearance,
+        data.quality,
+        data.key,
+        data.activities,
+      );
+      if (result.bytes) {
+        const source = inspectLegacyAssembly(result.bytes);
+        const geometryKey = await digest(
+          JSON.stringify([source.body.name, data.points]),
+        );
+        result.bytes = deformLegacyAssembly(result.bytes, {
+          points: data.points,
+          geometryKey,
+          ...await accessoryTransforms(module, data, source),
+        });
+      }
+      self.postMessage(
+        { id: data.id, ...result },
+        result.bytes ? [result.bytes.buffer] : [],
+      );
+    } catch (error) {
+      self.postMessage({ id: data.id, error: String(error), milliseconds: 0 });
+    }
+  });
+};