@rig-c/three 0.1.0 → 0.1.2

package/README.md

@@ -4,11 +4,15 @@ Draw a rig-c model in a native Three.js scene through `@rig-c/play`. `ThreeRig`
 is a flat `Group`: each drawn slot is a `Mesh` with native float32 geometry,
 with one shared shader material per page per instance. It poses no bones itself.
 
+## Install
+
 ```sh
 npm install @rig-c/three three @rig-c/play
 npm install --save-dev @types/three
 ```
 
+## Minimal usage
+
 ```ts
 import { loadModel } from '@rig-c/play';
 import { OrthographicCamera, Scene, WebGLRenderer } from 'three';
@@ -36,15 +40,17 @@ requestAnimationFrame(frame);
 ```
 
 Use the model document and image pages from `rigc build`, unchanged. Tested with
-Three.js **0.186.1** and play **1.10.0**. The API is 0.x.
+Three.js **0.186.1** and play **1.20.0** (`@rig-c/play >=1.20.0 <2`). The API is 0.x. See [`packages/three` in the repository](https://github.com/rig-c/adapters/tree/main/packages/three) for source and parity tests.
 
 ## Live object
 
 `play(name, options)`, `seek(seconds)`, `advance(dt)` and `update(dt)` forward to
-an independent `RigPlayer`; deltas are seconds, and the player's `timescale`
+an independent `RigPlayer` and consume its `liveFrame()` lease synchronously
+(`liveFrameChecks`, `poser`, `renderFrame(frame)`); deltas are seconds, and the player's `timescale`
 (alias `timeScale`) applies exactly once. The app owns the loop. `timescale = 0`
-holds the drawn frame and uploads no geometry. `drawnFrame()` is the exact record
-passed to the native renderer; `posedFrame(filter)`, `bone(name)` and `bounds()`
+holds the drawn frame and uploads no geometry. `draw()` returns a detached
+`PosedFrame`; `drawnFrame()` returns a detached snapshot of the last draw,
+including after direct mutations of `rig.player`; `posedFrame(filter)`, `bone(name)` and `bounds()`
 use play's readers. World bounds are in rig-local Y-up space, before this Group's
 transform. `resourceCounts()` reports owned meshes, geometries, page materials,
 clip textures and retained/shared pages. `destroy()` is idempotent and frees
@@ -60,7 +66,7 @@ both straight and premultiplied pixels: conflicting `pma` records are refused.
 ## Native drawing and scene placement
 
 `ThreeRenderer(root, assets, webglRenderer)` is available when the app owns the
-player. Call `render(player.posedFrame())`, then render the scene normally.
+player. Call `render(player.liveFrame())` (or `render(player.posedFrame())`), then render the scene normally.
 No internal canvas, offscreen bitmap of the rig, or fallback renderer draws it.
 Positions and page UVs come directly from the record; the full atlas page is
 sampled, so packed rotation needs no separate rule. The root stays Y-up and may

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as three from 'three';
 import { Group, WebGLRenderer, Texture, Mesh, BufferGeometry, ShaderMaterial, Camera } from 'three';
-import { ModelAssets, PosedFrame, RigPlayer, SlotFilter, PlayOptions, BoneWorld, PoseBounds, PosedSlot } from '@rig-c/play';
+import { ModelAssets, PosedFrame, LiveFrame, RigPlayer, SlotFilter, PlayOptions, BoneWorld, PoseBounds, PosedSlot } from '@rig-c/play';
 
 declare const getLivePageTextureCount: () => number;
 declare const getPageRefCount: (image: HTMLImageElement) => number;
@@ -31,14 +31,20 @@ declare class ThreeRenderer {
     private readonly pool;
     private readonly materials;
     private readonly retained;
+    private readonly liveViews;
+    private readonly retainedRuntimeFrame;
+    private accepted;
+    private hasRetained;
     constructor(root: Group, assets: ModelAssets, host: WebGLRenderer);
+    get drawnFrame(): PosedFrame | null;
     get geometryUploadCount(): number;
     get isDisposed(): boolean;
     resourceCounts(): ThreeRigResourceCounts;
     getPageTexture(name: string): Texture | undefined;
     private prepare;
     private material;
-    render(frame: PosedFrame): void;
+    render(frame: PosedFrame | LiveFrame): void;
+    private renderOrder;
     dispose(): void;
 }
 /** Read native float32 positions through the application's world and camera mapping. */
@@ -49,6 +55,8 @@ interface ThreeRigOptions {
     slots?: SlotFilter;
     timescale?: number;
     timeScale?: number;
+    liveFrameChecks?: boolean;
+    poser?: 'auto' | 'oracle';
 }
 /** A flat native Group. Advance from the app's loop using seconds, without an internal clock. */
 declare class ThreeRig extends Group {
@@ -64,6 +72,8 @@ declare class ThreeRig extends Group {
     advance(dt: number): void;
     update(dt: number): void;
     draw(): PosedFrame;
+    renderFrame(frame: PosedFrame | LiveFrame): void;
+    private drawCurrent;
     drawnFrame(): PosedFrame;
     posedFrame(slots?: SlotFilter | null): PosedFrame;
     bone(name: string): BoneWorld;

package/dist/index.js

@@ -1,3 +1,283 @@
+// packages/shared/src/live.ts
+var EMPTY = Object.freeze([]);
+var immutableLengths = /* @__PURE__ */ new WeakSet();
+var immutableSpans = /* @__PURE__ */ new WeakSet();
+var immutableMetadata = /* @__PURE__ */ new WeakSet();
+var IDENTITY_FIELDS = ["slot", "slotIndex", "attachment", "skin", "placeholder", "kind", "region", "page", "pma", "blend", "offset", "count"];
+function isImmutableSpan(value, indexed) {
+  if (!value || typeof value !== "object") return false;
+  if (immutableSpans.has(value)) return true;
+  if (Object.isFrozen(value) && Array.isArray(value)) {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    for (let i = 0; i < value.length; i++) {
+      const d = descriptors[i];
+      if (!d || !("value" in d) || typeof d.value !== "number") return false;
+    }
+    immutableSpans.add(value);
+    return true;
+  }
+  if (!indexed || value.length === 0) return false;
+  const d0 = Object.getOwnPropertyDescriptor(value, 0);
+  return Boolean(d0 && (!d0.writable || "get" in d0));
+}
+function frozenData(value) {
+  if (immutableMetadata.has(value)) return true;
+  if (!Object.isFrozen(value)) return false;
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (!IDENTITY_FIELDS.every((key) => {
+    const descriptor = descriptors[key];
+    return descriptor && "value" in descriptor && (descriptor.value === null || !["object", "function"].includes(typeof descriptor.value));
+  })) return false;
+  immutableMetadata.add(value);
+  return true;
+}
+function numbers(value, owner, field, slot) {
+  if (value && typeof value === "object" && immutableLengths.has(value)) return;
+  if (!value || typeof value !== "object" || !Number.isInteger(value.length) || value.length < 0) {
+    throw new Error(`${owner}: live ${slot === void 0 ? field : `slot "${slot}" ${field}`} needs an indexed buffer with nonnegative integer length`);
+  }
+  const length = Object.getOwnPropertyDescriptor(value, "length");
+  if (length && "value" in length && !length.writable && !length.configurable && Object.isFrozen(value)) immutableLengths.add(value);
+}
+var NumberSpan = class {
+  constructor(count) {
+    this.count = count;
+  }
+  count;
+  source = EMPTY;
+  offset = 0;
+};
+function numberSource(value) {
+  return value instanceof NumberSpan ? value.source : value;
+}
+function numberOffset(value) {
+  return value instanceof NumberSpan ? value.offset : 0;
+}
+function numberCount(value) {
+  return value instanceof NumberSpan ? value.count : value ? value.length : -1;
+}
+var LiveDrawViews = class {
+  constructor(owner = "PixiRenderer") {
+    this.owner = owner;
+  }
+  owner;
+  order = [];
+  rows = [];
+  validated = /* @__PURE__ */ new WeakSet();
+  read(frame) {
+    void frame.generation;
+    const { drawOrder, vertices, tint, attachments, count } = frame;
+    const owner = this.owner;
+    numbers(drawOrder, owner, "drawOrder");
+    numbers(vertices, owner, "vertices");
+    numbers(tint, owner, "tint");
+    if (!Number.isInteger(count) || count < 0 || count > drawOrder.length) {
+      throw new Error(`${owner}: live frame count=${count} needs an integer in 0..${drawOrder.length}`);
+    }
+    for (let i = 0; i < count; i++) {
+      const index = drawOrder[i];
+      const attachment = attachments[index];
+      if (!Number.isInteger(index) || !attachment || attachment.kind !== "region" && attachment.kind !== "mesh") {
+        throw new Error(`${owner}: live drawOrder[${i}]=${index} needs a region or mesh attachment`);
+      }
+      const a = attachment;
+      if (!this.validated.has(a)) {
+        if (typeof a.slot !== "string" || a.slot.length === 0 || typeof a.page !== "string" || a.page.length === 0 || a.kind === "region" && (typeof a.region !== "string" || a.region.length === 0)) {
+          throw new Error(`${owner}: live slot "${a.slot}" needs named slot, page and region metadata`);
+        }
+        if (!Number.isInteger(a.offset) || !Number.isInteger(a.count) || a.offset < 0 || a.count < 0 || !Number.isInteger(a.slotIndex) || a.slotIndex < 0) {
+          throw new Error(`${owner}: live slot "${a.slot}" has invalid vertex span ${a.offset}+${a.count} or tint slotIndex=${a.slotIndex}`);
+        }
+        if (frozenData(a)) this.validated.add(a);
+      }
+      numbers(a.uvs, owner, "uvs", a.slot);
+      numbers(a.triangles, owner, "triangles", a.slot);
+      if (a.dark !== null) numbers(a.dark, owner, "dark", a.slot);
+      if (a.clip !== null) numbers(a.clip.polygon, owner, "clip.polygon", a.slot);
+      if (a.offset + a.count > vertices.length || a.slotIndex * 4 + 4 > tint.length) {
+        throw new Error(`${owner}: live slot "${a.slot}" has invalid vertex span ${a.offset}+${a.count} or tint slotIndex=${a.slotIndex}`);
+      }
+      let row = this.rows[i];
+      if (!row || row.slot.kind !== a.kind || row.points.count !== a.count) {
+        const points = new NumberSpan(a.count);
+        const tint2 = new NumberSpan(4);
+        const common = { slot: a.slot, blend: a.blend, tint: tint2, page: a.page ?? "", pma: a.pma, uvs: EMPTY };
+        const slot2 = a.kind === "region" ? { ...common, kind: "region", region: a.region ?? "", corners: points } : { ...common, kind: "mesh", vertices: points, triangles: EMPTY };
+        row = { slot: slot2, points, tint: tint2 };
+        this.rows[i] = row;
+      }
+      row.points.source = vertices;
+      row.points.offset = a.offset;
+      row.tint.source = tint;
+      row.tint.offset = a.slotIndex * 4;
+      const slot = row.slot;
+      slot.slot = a.slot;
+      slot.blend = a.blend;
+      slot.page = a.page ?? "";
+      slot.pma = a.pma;
+      slot.uvs = a.uvs;
+      slot.dark = a.dark ?? void 0;
+      slot.clip = a.clip ?? void 0;
+      if (slot.kind === "region") slot.region = a.region ?? "";
+      else slot.triangles = a.triangles;
+      this.order[i] = slot;
+    }
+    this.order.length = count;
+    return this.order;
+  }
+  release() {
+    for (const row of this.rows) {
+      row.points.source = EMPTY;
+      row.tint.source = EMPTY;
+      row.slot.uvs = EMPTY;
+      row.slot.dark = void 0;
+      row.slot.clip = void 0;
+      if (row.slot.kind === "mesh") row.slot.triangles = EMPTY;
+    }
+  }
+};
+function identity(a) {
+  return JSON.stringify([a.slotIndex, a.slot, a.skin, a.placeholder, a.attachment, a.kind, a.page, a.region]);
+}
+function templateFromAttachment(a) {
+  const common = {
+    slot: a.slot,
+    z: a.slotIndex,
+    blend: a.blend,
+    tint: [1, 1, 1, 1]
+  };
+  return a.kind === "region" ? {
+    ...common,
+    kind: "region",
+    region: a.region ?? "",
+    corners: [],
+    page: a.page ?? "",
+    pma: a.pma,
+    uvs: Array.from(a.uvs)
+  } : {
+    ...common,
+    kind: "mesh",
+    page: a.page ?? "",
+    pma: a.pma,
+    vertices: [],
+    uvs: Array.from(a.uvs),
+    triangles: Array.from(a.triangles),
+    sequence: 0
+  };
+}
+function copyNumbers(target, source) {
+  if (ArrayBuffer.isView(source) && source instanceof Float64Array) {
+    target.set(source);
+  } else {
+    for (let i = 0; i < target.length; i++) target[i] = source[i];
+  }
+}
+function savedNumbers(source, offset, count) {
+  const result = new Array(count);
+  for (let i = 0; i < count; i++) result[i] = source[offset + i];
+  return result;
+}
+var RetainedRuntimeFrame = class {
+  constructor(owner = "PixiRig") {
+    this.owner = owner;
+  }
+  owner;
+  templates = /* @__PURE__ */ new WeakMap();
+  immutable = /* @__PURE__ */ new WeakSet();
+  checkedTemplates = /* @__PURE__ */ new Map();
+  rows = [];
+  vertices = new Float64Array(0);
+  tint = new Float64Array(0);
+  count = 0;
+  generation = 0;
+  retained = null;
+  capture(frame, seed) {
+    let snapshot = null;
+    const { count, attachments, drawOrder, vertices, tint } = frame;
+    if (this.vertices.length !== vertices.length) this.vertices = new Float64Array(vertices.length);
+    if (this.tint.length !== tint.length) this.tint = new Float64Array(tint.length);
+    copyNumbers(this.vertices, vertices);
+    copyNumbers(this.tint, tint);
+    for (let i = 0; i < count; i++) {
+      const a = attachments[drawOrder[i]];
+      let template = this.immutable.has(a) ? this.templates.get(a) : void 0;
+      if (!template) {
+        const key = identity(a);
+        template = this.checkedTemplates.get(key);
+        if (!template) {
+          if (seed) {
+            snapshot ??= seed();
+            template = snapshot.order[i];
+            if (!template || template.slot !== a.slot || template.kind !== a.kind || template.page !== a.page) {
+              throw new Error(`${this.owner}: live slot "${a.slot}" needs a matching snapshot metadata seed at draw index ${i}`);
+            }
+          } else {
+            template = templateFromAttachment(a);
+          }
+          if (this.checkedTemplates.size >= Math.max(64, frame.attachments.length * 2)) this.checkedTemplates.clear();
+          this.checkedTemplates.set(key, template);
+        }
+        if (frozenData(a)) {
+          this.immutable.add(a);
+          this.templates.set(a, template);
+        }
+      }
+      let row = this.rows[i];
+      if (!row) {
+        row = { template, offset: a.offset, count: a.count, tintOffset: a.slotIndex * 4 };
+        this.rows[i] = row;
+      }
+      row.template = template;
+      row.offset = a.offset;
+      row.count = a.count;
+      row.tintOffset = a.slotIndex * 4;
+      if (a.dark === null) row.dark = void 0;
+      else {
+        const dark = row.darkBuffer ??= [];
+        dark.length = a.dark.length;
+        for (let j = 0; j < dark.length; j++) dark[j] = a.dark[j];
+        row.dark = dark;
+      }
+      if (a.clip === null) row.clip = void 0;
+      else {
+        const clip = row.clipBuffer ??= { polygon: [], inverse: false, convex: true };
+        clip.polygon.length = a.clip.polygon.length;
+        for (let j = 0; j < clip.polygon.length; j++) clip.polygon[j] = a.clip.polygon[j];
+        clip.inverse = a.clip.inverse;
+        clip.convex = a.clip.convex;
+        row.clip = clip;
+      }
+    }
+    this.count = frame.count;
+    this.generation = frame.generation;
+    this.retained = null;
+  }
+  snapshot() {
+    if (this.retained) return this.retained;
+    const order = [];
+    for (let i = 0; i < this.count; i++) {
+      const { template, offset, count, tintOffset, dark, clip } = this.rows[i];
+      const common = { ...template, tint: savedNumbers(this.tint, tintOffset, 4) };
+      if (dark) common.dark = Array.from(dark);
+      else delete common.dark;
+      if (clip) common.clip = {
+        polygon: Array.from(clip.polygon),
+        inverse: clip.inverse,
+        convex: clip.convex
+      };
+      else delete common.clip;
+      order.push(template.kind === "region" ? { ...common, kind: "region", region: template.region, corners: savedNumbers(this.vertices, offset, count) } : { ...common, kind: "mesh", vertices: savedNumbers(this.vertices, offset, count), triangles: template.triangles, sequence: template.sequence });
+    }
+    this.retained = { order };
+    Object.defineProperty(this.retained, "generation", { value: this.generation, enumerable: false, configurable: true });
+    return this.retained;
+  }
+  /** Explicit draw() already requested a detached snapshot. */
+  retain(frame) {
+    this.retained = frame;
+  }
+};
+
 // packages/three/src/three.ts
 import { RigPlayer } from "@rig-c/play";
 import {
@@ -39,11 +319,12 @@ function hull(points) {
   };
   return [...half(sorted).slice(0, -1), ...half([...sorted].reverse()).slice(0, -1)];
 }
-function clipPolygon(clip, detail, capacity) {
+function clipPolygon(clip, detail, capacity, indexed = false) {
   const fail = (why) => {
     throw new Error(`${detail} has invalid clip: ${why} (expected finite simple nonzero-area polygon, boolean inverse/convex, at most GPU MAX_TEXTURE_SIZE=${capacity} vertices)`);
   };
-  if (!clip || typeof clip.inverse !== "boolean" || typeof clip.convex !== "boolean" || !Array.isArray(clip.polygon) || clip.polygon.length < 6 || clip.polygon.length % 2 !== 0) fail("invalid flags or polygon length");
+  const validPolygon = indexed ? Boolean(clip && clip.polygon && typeof clip.polygon === "object" && Number.isInteger(clip.polygon.length)) : Boolean(clip && Array.isArray(clip.polygon));
+  if (!clip || typeof clip.inverse !== "boolean" || typeof clip.convex !== "boolean" || !validPolygon || clip.polygon.length < 6 || clip.polygon.length % 2 !== 0) fail("invalid flags or polygon length");
   if (clip.polygon.length / 2 > capacity) fail(`THREE_CLIP_CAPACITY: found ${clip.polygon.length / 2} vertices`);
   const points = [];
   for (let i = 0; i < clip.polygon.length; i += 2) {
@@ -80,7 +361,7 @@ var livePages = /* @__PURE__ */ new Set();
 var getLivePageTextureCount = () => livePages.size;
 var getPageRefCount = (image) => pages.get(image)?.holders.size ?? 0;
 var getSharedPageTexture = (image) => pages.get(image)?.texture;
-var REGION_INDICES = [0, 1, 2, 2, 3, 0];
+var REGION_INDICES = Object.freeze([0, 1, 2, 2, 3, 0]);
 var VERTEX = `
 out vec2 vUV;
 out vec2 vPosition;
@@ -137,6 +418,16 @@ var ThreeRenderer = class {
   pool = /* @__PURE__ */ new Map();
   materials = /* @__PURE__ */ new Map();
   retained = /* @__PURE__ */ new Set();
+  liveViews = new LiveDrawViews("ThreeRenderer");
+  retainedRuntimeFrame = new RetainedRuntimeFrame("ThreeRenderer");
+  accepted = null;
+  hasRetained = false;
+  get drawnFrame() {
+    if (this.accepted) return this.accepted;
+    if (!this.hasRetained) return null;
+    this.accepted = this.retainedRuntimeFrame.snapshot();
+    return this.accepted;
+  }
   get geometryUploadCount() {
     return this.positionUploadCount + this.uvUploadCount + this.triangleUploadCount;
   }
@@ -150,7 +441,7 @@ var ThreeRenderer = class {
     const image = this.assets.pageImages.get(name);
     return image && this.retained.has(image) ? pages.get(image)?.texture : void 0;
   }
-  prepare(slot) {
+  prepare(slot, key, indexed) {
     const detail = `ThreeRenderer: slot "${slot?.slot ?? "<unnamed>"}" on page "${slot?.page ?? "<unnamed>"}"`;
     const fail = (why) => {
       throw new Error(`${detail}: ${why}`);
@@ -159,26 +450,58 @@ var ThreeRenderer = class {
     if (typeof slot.slot !== "string" || slot.slot.length === 0 || typeof slot.page !== "string" || slot.page.length === 0) fail("expected non-empty slot and page names");
     if (!["Normal", "Additive", "Multiply", "Screen"].includes(slot.blend)) fail(`blend=${slot.blend} (expected Normal, Additive, Multiply, Screen)`);
     if (typeof slot.pma !== "boolean") fail(`pma=${String(slot.pma)} (expected boolean)`);
-    if (!Number.isFinite(slot.z)) fail(`z=${String(slot.z)} (expected finite draw-order index)`);
+    if (!indexed && !Number.isFinite(slot.z)) fail(`z=${String(slot.z)} (expected finite draw-order index)`);
     const image = this.assets.pageImages.get(slot.page);
     if (!image || !(image.naturalWidth > 0 && image.naturalHeight > 0)) fail("page image absent or not decoded (expected positive naturalWidth/naturalHeight)");
     const valid = (values, count, field) => {
-      if (!Array.isArray(values) || values.length !== count) fail(`${field} length=${values?.length} (expected ${count})`);
-      for (let i = 0; i < count; i++) if (!Number.isFinite(values[i]) || !Number.isFinite(Math.fround(values[i]))) fail(`${field}[${i}]=${String(values[i])} (expected finite float32)`);
+      const source = numberSource(values), offset = numberOffset(values), length = numberCount(values);
+      if (!indexed && !Array.isArray(values) || length !== count) fail(`${field} length=${Array.isArray(values) || indexed ? length : void 0} (expected ${count})`);
+      for (let i = 0; i < count; i++) {
+        const value = source[offset + i];
+        if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value))) fail(`${field}[${i}]=${String(value)} (expected finite float32)`);
+      }
     };
     valid(slot.tint, 4, "tint");
     if (slot.dark !== void 0) valid(slot.dark, 3, "dark");
     const coords = slot.kind === "region" ? slot.corners : slot.vertices;
-    if (!Array.isArray(coords) || coords.length < 6 || coords.length % 2 !== 0) fail(`positions length=${coords?.length} (expected even length >=6)`);
-    valid(coords, slot.kind === "region" ? 8 : coords.length, slot.kind === "region" ? "corners" : "vertices");
-    valid(slot.uvs, coords.length, "uvs");
+    const coordCount = numberCount(coords);
+    if (!indexed && !Array.isArray(coords) || coordCount < 6 || coordCount % 2 !== 0) fail(`positions length=${Array.isArray(coords) || indexed ? coordCount : void 0} (expected even length >=6)`);
+    valid(coords, slot.kind === "region" ? 8 : coordCount, slot.kind === "region" ? "corners" : "vertices");
+    const prior = this.pool.get(key);
+    const priorPositions = prior?.mesh.geometry.getAttribute("position");
+    const sameVertexCount = !this.alwaysReuploadGeometry && prior !== void 0 && priorPositions !== void 0 && priorPositions.array.length === coordCount / 2 * 3;
+    if (!sameVertexCount || !isImmutableSpan(slot.uvs, indexed) || prior.uvs !== slot.uvs) {
+      valid(slot.uvs, coordCount, "uvs");
+    }
     const indices = slot.kind === "region" ? REGION_INDICES : slot.triangles;
-    if (!Array.isArray(indices) || indices.length < 3 || indices.length % 3 !== 0) fail(`triangles length=${indices?.length} (expected multiple of three >=3)`);
-    indices.forEach((v, i) => {
-      if (!Number.isInteger(v) || v < 0 || v >= coords.length / 2) fail(`triangles[${i}]=${v} (expected integer 0..${coords.length / 2 - 1})`);
-    });
-    if (slot.kind === "mesh" && !Number.isInteger(slot.sequence)) fail(`sequence=${slot.sequence} (expected integer)`);
-    return { slot, image, positions: coords, indices, polygon: slot.clip !== void 0 ? clipPolygon(slot.clip, detail, this.host.capabilities.maxTextureSize) : null };
+    if (!sameVertexCount || !isImmutableSpan(indices, indexed) || prior.indices !== indices) {
+      if (!indexed && !Array.isArray(indices) || indices.length < 3 || indices.length % 3 !== 0) fail(`triangles length=${indices?.length} (expected multiple of three >=3)`);
+      for (let i = 0; i < indices.length; i++) {
+        const v = indices[i];
+        if (!Number.isInteger(v) || v < 0 || v >= coordCount / 2) fail(`triangles[${i}]=${v} (expected integer 0..${coordCount / 2 - 1})`);
+      }
+    }
+    if (!indexed && slot.kind === "mesh" && !Number.isInteger(slot.sequence)) fail(`sequence=${slot.sequence} (expected integer)`);
+    const tintSource = numberSource(slot.tint), tintOffset = numberOffset(slot.tint);
+    const light = [
+      tintSource[tintOffset + 0],
+      tintSource[tintOffset + 1],
+      tintSource[tintOffset + 2],
+      tintSource[tintOffset + 3]
+    ];
+    const dark = slot.dark ? [slot.dark[0], slot.dark[1], slot.dark[2]] : [0, 0, 0];
+    return {
+      slot,
+      key,
+      image,
+      positions: coords,
+      indices,
+      polygon: slot.clip !== void 0 ? clipPolygon(slot.clip, detail, this.host.capabilities.maxTextureSize, indexed) : null,
+      light,
+      dark,
+      inverse: slot.clip?.inverse ?? false,
+      blend: slot.blend
+    };
   }
   material(item) {
     let material = this.materials.get(item.image);
@@ -216,71 +539,162 @@ var ThreeRenderer = class {
   }
   render(frame) {
     if (this.disposed) throw new Error("ThreeRenderer: render called after dispose (expected active renderer)");
-    if (!frame || !Array.isArray(frame.order)) throw new Error("ThreeRenderer: frame.order absent (expected PosedSlot array)");
-    const prepared = frame.order.map((s) => this.prepare(s));
+    if (!frame || typeof frame !== "object") throw new Error("ThreeRenderer: frame.order absent (expected PosedSlot array)");
+    if ("order" in frame) {
+      if (!Array.isArray(frame.order)) throw new Error("ThreeRenderer: frame.order absent (expected PosedSlot array)");
+      this.renderOrder(frame.order, false);
+      this.accepted = frame;
+      this.hasRetained = false;
+      return;
+    }
+    try {
+      this.renderOrder(this.liveViews.read(frame), true);
+      this.retainedRuntimeFrame.capture(frame);
+      this.accepted = null;
+      this.hasRetained = true;
+    } finally {
+      this.liveViews.release();
+    }
+  }
+  renderOrder(order, indexed) {
+    const occurrences = /* @__PURE__ */ new Map();
+    const prepared = order.map((s) => {
+      const slotName = typeof s?.slot === "string" && s.slot.length > 0 ? s.slot : "<unnamed>";
+      const occurrence = occurrences.get(slotName) ?? 0;
+      occurrences.set(slotName, occurrence + 1);
+      return this.prepare(s, `${slotName}\0${occurrence}`, indexed);
+    });
     const conventions = /* @__PURE__ */ new Map();
     for (const item of prepared) {
       const pma = conventions.get(item.image) ?? pages.get(item.image)?.pma;
       if (pma !== void 0 && pma !== item.slot.pma) throw new Error(`ThreeRenderer: slot "${item.slot.slot}" page "${item.slot.page}" pma=${item.slot.pma} conflicts with retained pma=${pma} (expected one convention per page image)`);
       conventions.set(item.image, item.slot.pma);
     }
-    const occurrences = /* @__PURE__ */ new Map();
     const active = [];
     prepared.forEach((item, index) => {
-      const occurrence = occurrences.get(item.slot.slot) ?? 0;
-      occurrences.set(item.slot.slot, occurrence + 1);
-      const key = `${item.slot.slot}\0${occurrence}`;
+      const { key } = item;
       let entry = this.pool.get(key);
       if (!entry) {
         const geometry = new BufferGeometry();
         const mesh2 = new Mesh(geometry, this.material(item));
         mesh2.frustumCulled = false;
         mesh2.name = item.slot.slot;
-        entry = { mesh: mesh2, polygon: null, polygonValues: [], uvs: null, indices: null };
+        entry = {
+          mesh: mesh2,
+          polygon: null,
+          polygonValues: [],
+          uvs: null,
+          indices: null,
+          light: item.light,
+          dark: item.dark,
+          inverse: item.inverse,
+          blend: item.blend,
+          needsWideIndex: false
+        };
+        const current = entry;
+        mesh2.onBeforeRender = () => {
+          const material = mesh2.material;
+          material.uniforms.light.value = current.light;
+          material.uniforms.dark.value = current.dark;
+          material.uniforms.polygon.value = current.polygon ?? material.uniforms.page.value;
+          material.uniforms.points.value = current.polygon === null ? 0 : current.polygonValues.length / 2;
+          material.uniforms.inverse.value = current.inverse;
+          material.blendEquation = material.blendEquationAlpha = AddEquation;
+          material.blendSrc = current.blend === "Multiply" ? DstColorFactor : OneFactor;
+          material.blendDst = current.blend === "Additive" ? OneFactor : current.blend === "Screen" ? OneMinusSrcColorFactor : OneMinusSrcAlphaFactor;
+          material.blendSrcAlpha = OneFactor;
+          material.blendDstAlpha = material.blendDst;
+          material.uniformsNeedUpdate = true;
+        };
         this.pool.set(key, entry);
       }
       const { mesh } = entry;
+      const positionCount = numberCount(item.positions);
       const oldPositions = mesh.geometry.getAttribute("position"), oldUVs = mesh.geometry.getAttribute("uv"), oldIndex = mesh.geometry.getIndex();
-      const needsWideIndex = item.indices.some((v) => v >= 65535);
-      if (oldPositions && oldPositions.array.length !== item.positions.length / 2 * 3 || oldUVs && oldUVs.array.length !== item.slot.uvs.length || oldIndex && (oldIndex.count !== item.indices.length || needsWideIndex && !(oldIndex.array instanceof Uint32Array))) {
+      let needsWideIndex = entry.needsWideIndex;
+      if (this.alwaysReuploadGeometry || entry.indices !== item.indices || !oldIndex) {
+        needsWideIndex = false;
+        if (positionCount / 2 > 65535) {
+          for (let i = 0; i < item.indices.length; i++) if (item.indices[i] >= 65535) {
+            needsWideIndex = true;
+            break;
+          }
+        }
+        entry.needsWideIndex = needsWideIndex;
+      }
+      if (oldPositions && oldPositions.array.length !== positionCount / 2 * 3 || oldUVs && oldUVs.array.length !== item.slot.uvs.length || oldIndex && (oldIndex.count !== item.indices.length || needsWideIndex && !(oldIndex.array instanceof Uint32Array))) {
         mesh.geometry.dispose();
         mesh.geometry = new BufferGeometry();
         entry.uvs = entry.indices = null;
       }
-      mesh.posedSlot = item.slot;
+      entry.light = item.light;
+      entry.dark = item.dark;
+      entry.inverse = item.inverse;
+      entry.blend = item.blend;
+      if (!indexed) {
+        mesh.posedSlot = item.slot;
+      } else {
+        const prior = mesh.posedSlot;
+        if (!prior || prior.slot !== item.slot.slot || prior.page !== item.slot.page || prior.pma !== item.slot.pma || prior.kind !== item.slot.kind || prior.blend !== item.slot.blend) {
+          mesh.posedSlot = item.slot.kind === "region" ? { kind: "region", slot: item.slot.slot, z: 0, page: item.slot.page, region: item.slot.region, pma: item.slot.pma, blend: item.slot.blend, corners: [], uvs: [], tint: item.light } : { kind: "mesh", slot: item.slot.slot, z: 0, page: item.slot.page, pma: item.slot.pma, blend: item.slot.blend, vertices: [], uvs: [], triangles: [], sequence: 0, tint: item.light };
+        }
+      }
       mesh.material = this.material(item);
       mesh.renderOrder = index;
-      const update = (name, values, size, force) => {
-        let attribute = mesh.geometry.getAttribute(name);
-        let changed = force || !attribute || attribute.array.length !== values.length;
-        if (!attribute || attribute.array.length !== values.length) {
-          attribute = new BufferAttribute(new Float32Array(values.length), size).setUsage(DynamicDrawUsage);
-          mesh.geometry.setAttribute(name, attribute);
+      const posLength = positionCount / 2 * 3;
+      let posAttr = mesh.geometry.getAttribute("position");
+      let posChanged = this.alwaysReuploadGeometry || !posAttr || posAttr.array.length !== posLength;
+      if (!posAttr || posAttr.array.length !== posLength) {
+        posAttr = new BufferAttribute(new Float32Array(posLength), 3).setUsage(DynamicDrawUsage);
+        mesh.geometry.setAttribute("position", posAttr);
+      }
+      const posArray = posAttr.array;
+      const posSource = numberSource(item.positions), posOffset = numberOffset(item.positions);
+      for (let i = 0, out = 0; i < positionCount; i += 2, out += 3) {
+        const x = Math.fround(posSource[posOffset + i]), y = Math.fround(posSource[posOffset + i + 1]);
+        if (posArray[out] !== x || posArray[out + 1] !== y || posArray[out + 2] !== 0) {
+          posArray[out] = x;
+          posArray[out + 1] = y;
+          posArray[out + 2] = 0;
+          posChanged = true;
+        }
+      }
+      if (posChanged) {
+        posAttr.needsUpdate = true;
+        this.positionUploadCount++;
+      }
+      if (this.alwaysReuploadGeometry || entry.uvs !== item.slot.uvs) {
+        const uvs = item.slot.uvs;
+        let uvAttr = mesh.geometry.getAttribute("uv");
+        let uvChanged = true;
+        if (!uvAttr || uvAttr.array.length !== uvs.length) {
+          uvAttr = new BufferAttribute(new Float32Array(uvs.length), 2).setUsage(DynamicDrawUsage);
+          mesh.geometry.setAttribute("uv", uvAttr);
         }
-        const array = attribute.array;
-        for (let i = 0; i < values.length; i++) if (array[i] !== Math.fround(values[i])) {
-          array[i] = values[i];
-          changed = true;
+        const uvArray = uvAttr.array;
+        for (let i = 0; i < uvs.length; i++) {
+          const v = Math.fround(uvs[i]);
+          if (uvArray[i] !== v) {
+            uvArray[i] = v;
+            uvChanged = true;
+          }
         }
-        if (changed) {
-          attribute.needsUpdate = true;
-          if (name === "position") this.positionUploadCount++;
-          else this.uvUploadCount++;
+        if (uvChanged) {
+          uvAttr.needsUpdate = true;
+          this.uvUploadCount++;
         }
-      };
-      const xyz = [];
-      for (let i = 0; i < item.positions.length; i += 2) xyz.push(item.positions[i], item.positions[i + 1], 0);
-      update("position", xyz, 3, this.alwaysReuploadGeometry);
-      if (this.alwaysReuploadGeometry || entry.uvs !== item.slot.uvs) {
-        update("uv", item.slot.uvs, 2, true);
-        entry.uvs = item.slot.uvs;
+        entry.uvs = uvs;
       }
       if (this.alwaysReuploadGeometry || entry.indices !== item.indices) {
         const before = mesh.geometry.getIndex();
         if (before && before.count === item.indices.length) {
           for (let i = 0; i < item.indices.length; i++) before.setX(i, item.indices[i]);
           before.needsUpdate = true;
-        } else mesh.geometry.setIndex([...item.indices]);
+        } else {
+          const copied = new Array(item.indices.length);
+          for (let i = 0; i < item.indices.length; i++) copied[i] = item.indices[i];
+          mesh.geometry.setIndex(copied);
+        }
         this.triangleUploadCount++;
         entry.indices = item.indices;
       }
@@ -300,21 +714,6 @@ var ThreeRenderer = class {
         entry.polygon = null;
         entry.polygonValues = [];
       }
-      const current = entry;
-      mesh.onBeforeRender = () => {
-        const material = mesh.material, slot = mesh.posedSlot;
-        material.uniforms.light.value = slot.tint;
-        material.uniforms.dark.value = slot.dark ?? [0, 0, 0];
-        material.uniforms.polygon.value = current.polygon ?? material.uniforms.page.value;
-        material.uniforms.points.value = current.polygon === null ? 0 : current.polygonValues.length / 2;
-        material.uniforms.inverse.value = slot.clip?.inverse ?? false;
-        material.blendEquation = material.blendEquationAlpha = AddEquation;
-        material.blendSrc = slot.blend === "Multiply" ? DstColorFactor : OneFactor;
-        material.blendDst = slot.blend === "Additive" ? OneFactor : slot.blend === "Screen" ? OneMinusSrcColorFactor : OneMinusSrcAlphaFactor;
-        material.blendSrcAlpha = OneFactor;
-        material.blendDstAlpha = material.blendDst;
-        material.uniformsNeedUpdate = true;
-      };
       active.push(mesh);
     });
     for (const entry of this.pool.values()) if (entry.mesh.parent === this.root) this.root.remove(entry.mesh);
@@ -361,7 +760,13 @@ var ThreeRig = class extends Group {
     if (!assets?.document || !(assets.pageImages instanceof Map) || !isWebGLHost(options?.renderer)) throw new Error("ThreeRig: expected ModelAssets and options.renderer WebGLRenderer");
     const scale = options.timescale ?? options.timeScale ?? 1;
     if (!Number.isFinite(scale) || scale < 0) throw new Error(`ThreeRig: timescale=${scale} (expected finite number >=0)`);
-    this.player = new RigPlayer(document.createElement("div"), assets, { mode: assets.regions === "none" ? "canvas" : "dom", skin: options.skin, slots: options.slots });
+    this.player = new RigPlayer(document.createElement("div"), assets, {
+      mode: assets.regions === "none" ? "canvas" : "dom",
+      skin: options.skin,
+      slots: options.slots,
+      liveFrameChecks: options.liveFrameChecks,
+      poser: options.poser
+    });
     this.renderer = new ThreeRenderer(this, assets, options.renderer);
     this.timescale = scale;
     try {
@@ -375,7 +780,7 @@ var ThreeRig = class extends Group {
   assets;
   player;
   renderer;
-  lastFrame;
+  lastFrame = null;
   destroyed = false;
   active() {
     if (this.destroyed) throw new Error("ThreeRig: called after destroy (expected active rig)");
@@ -383,20 +788,20 @@ var ThreeRig = class extends Group {
   play(name, options = {}) {
     this.active();
     this.player.play(name, options);
-    this.draw();
+    this.drawCurrent();
   }
   seek(time) {
     this.active();
     if (!Number.isFinite(time)) throw new Error(`ThreeRig: time=${time} (expected finite seconds)`);
     this.player.seek(time);
-    this.draw();
+    this.drawCurrent();
   }
   advance(dt) {
     this.active();
     if (!Number.isFinite(dt) || dt < 0) throw new Error(`ThreeRig: dt=${dt} (expected finite seconds >=0)`);
     if (this.timescale === 0) return;
     this.player.advance(dt);
-    this.draw();
+    this.drawCurrent();
   }
   update(dt) {
     this.advance(dt);
@@ -408,9 +813,29 @@ var ThreeRig = class extends Group {
     this.lastFrame = frame;
     return frame;
   }
+  renderFrame(frame) {
+    this.active();
+    if ("order" in frame) {
+      this.renderer.render(frame);
+      this.lastFrame = frame;
+      return;
+    }
+    if (frame.generation !== this.player.generation) {
+      throw new Error(`ThreeRig: live frame generation ${frame.generation} needs current player generation ${this.player.generation}`);
+    }
+    if (this.player.poser !== "runtime") {
+      this.renderFrame(this.player.posedFrame());
+      return;
+    }
+    this.renderer.render(frame);
+    this.lastFrame = null;
+  }
+  drawCurrent() {
+    this.renderFrame(this.player.poser === "runtime" ? this.player.liveFrame() : this.player.posedFrame());
+  }
   drawnFrame() {
     this.active();
-    return this.lastFrame;
+    return this.lastFrame ??= this.renderer.drawnFrame;
   }
   posedFrame(slots) {
     this.active();

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@rig-c/three",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Play rig-c model documents in a native Three.js scene through @rig-c/play.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/rig-c/adapters.git",
+    "url": "git+https://github.com/rig-c/adapters.git",
     "directory": "packages/three"
   },
+  "homepage": "https://github.com/rig-c/adapters/tree/main/packages/three#readme",
+  "bugs": {
+    "url": "https://github.com/rig-c/adapters/issues"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -24,7 +28,7 @@
   "sideEffects": false,
   "peerDependencies": {
     "three": "^0.186.1",
-    "@rig-c/play": "^1.10.0"
+    "@rig-c/play": "^1.20.0"
   },
   "devDependencies": {
     "@rig-c/adapters-shared": "workspace:*",