@rig-c/three 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rig-c
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,5 @@
+@rig-c/three is MIT licensed. It requires Three.js and @rig-c/play as peer
+dependencies. It reads rig-c model documents and links no Spine runtime.
+Shared workspace helpers, when used, are bundled into host libraries; the private
+@rig-c/adapters-shared workspace is not published. See LICENSE for this package's
+licence and each dependency's licence for its own terms.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @rig-c/three
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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';
+import { ThreeRig } from '@rig-c/three';
+
+const renderer = new WebGLRenderer({ alpha: true });
+renderer.setSize(800, 600);
+document.body.appendChild(renderer.domElement);
+const scene = new Scene();
+const camera = new OrthographicCamera(-400, 400, 300, -300, 0.1, 2000);
+camera.position.z = 1000;
+const assets = await loadModel({ modelUrl: '/rigs/walk/skeleton.model.json' });
+const rig = new ThreeRig(assets, { renderer });
+rig.play('walk');
+scene.add(rig);
+let previous: number | undefined;
+function frame(now: number) {
+  if (previous !== undefined) rig.update((now - previous) / 1000);
+  previous = now;
+  renderer.render(scene, camera);
+  requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+// On removal: rig.destroy(); assets.dispose(); renderer.dispose();
+```
+
+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. 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`
+(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()`
+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
+only this object's resources; it neither destroys the application renderer nor
+modifies another rig. Dispose the shared ModelAssets after all players using it
+are destroyed; the adapter does not own the load's blob URLs. Mutating playback after destroy is refused.
+
+Several rigs can share one `ModelAssets` load. Page textures are shared by image
+identity until the last renderer releases them; instance geometry, clip data and
+material uniforms remain separate. A page image cannot simultaneously declare
+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.
+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
+be translated, rotated and scaled under an orthographic or perspective camera.
+Use the Group's `renderOrder` to order separate flat rigs in overlapping scenes;
+slot meshes have explicit internal draw order. Materials retain depth testing
+for ordinary 3D occlusion and disable depth writing for translucent slots. They
+are double-sided with a single draw pass. The adapter changes no global camera,
+renderer colour space, sorting, depth or stencil state.
+
+The shader matches play's premultiplied two-colour expression and explicit
+Normal/Additive/Multiply/Screen RGB and alpha blend factors, without lighting,
+tone mapping or an extra colour-space conversion. Straight pages are multiplied
+once on upload; already-PMA pages are not. Texture UV orientation, linear
+filtering and mipmap policy are explicit.
+
+Clips are hard shader polygons in the same local plane as the geometry. Ordinary
+concave polygons retain their shape; `convex: true` and inverse clips use the
+convex hull, matching play's canvas reader. Per-slot point data is a float
+DataTexture, never an array truncated to a guessed uniform limit. A clip with
+more vertices than the actual renderer's `MAX_TEXTURE_SIZE` is refused as
+`THREE_CLIP_CAPACITY` before any scene/resource change; malformed, crossing or
+zero-area polygons are refused by slot and page as well. This is a WebGL2 host;
+`WebGPURenderer` is not this package's renderer.
+
+Geometry upload counters expose position, UV and triangle updates. Native
+resources are reused when their arrays remain unchanged. Capacity changes dispose
+the old geometry before replacing its attributes. The diagnostics
+`alwaysReuploadGeometry` and `releasePageTexturesOnDispose` exist for planted
+negative controls; keep their normal values `false` and `true` respectively.
+
+## Demo and verification
+
+From the repository, `bun run dev` serves `/three-demo.html`, including a flat
+object in a perspective scene. Query parameters: `?rig=walk&anim=walk&time=0.5&timescale=0&count=3&view=perspective`.
+The default camera is orthographic; paused queries permit deterministic capture.
+
+`bun run verify` discovers this host without workflow changes. It checks native
+float storage and transformed geometry, same-browser CanvasRenderer pictures,
+planted picture faults, exact pose parity, fixed updates, native held uploads,
+shared page lifetime, buffer deletion, package contents and installed exports.
+The release pipeline registers this package independently of the other hosts.

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+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';
+
+declare const getLivePageTextureCount: () => number;
+declare const getPageRefCount: (image: HTMLImageElement) => number;
+declare const getSharedPageTexture: (image: HTMLImageElement) => Texture<unknown, three.TextureEventMap> | undefined;
+interface ThreeSlotMesh extends Mesh<BufferGeometry, ShaderMaterial> {
+    posedSlot: PosedSlot;
+}
+interface ThreeRigResourceCounts {
+    meshes: number;
+    geometries: number;
+    materials: number;
+    clipTextures: number;
+    retainedPages: number;
+    livePageTextures: number;
+}
+/** Native meshes in Y-up local space. The application owns the WebGL renderer and camera. */
+declare class ThreeRenderer {
+    readonly root: Group;
+    readonly assets: ModelAssets;
+    readonly host: WebGLRenderer;
+    positionUploadCount: number;
+    uvUploadCount: number;
+    triangleUploadCount: number;
+    alwaysReuploadGeometry: boolean;
+    /** Negative-control switch; normal disposal always releases retained page textures. */
+    releasePageTexturesOnDispose: boolean;
+    private disposed;
+    private readonly pool;
+    private readonly materials;
+    private readonly retained;
+    constructor(root: Group, assets: ModelAssets, host: WebGLRenderer);
+    get geometryUploadCount(): number;
+    get isDisposed(): boolean;
+    resourceCounts(): ThreeRigResourceCounts;
+    getPageTexture(name: string): Texture | undefined;
+    private prepare;
+    private material;
+    render(frame: PosedFrame): void;
+    dispose(): void;
+}
+/** Read native float32 positions through the application's world and camera mapping. */
+declare function readMeshScreenVertices(mesh: ThreeSlotMesh, camera: Camera, width: number, height: number): number[];
+interface ThreeRigOptions {
+    renderer: WebGLRenderer;
+    skin?: string;
+    slots?: SlotFilter;
+    timescale?: number;
+    timeScale?: number;
+}
+/** A flat native Group. Advance from the app's loop using seconds, without an internal clock. */
+declare class ThreeRig extends Group {
+    readonly assets: ModelAssets;
+    readonly player: RigPlayer;
+    readonly renderer: ThreeRenderer;
+    private lastFrame;
+    private destroyed;
+    constructor(assets: ModelAssets, options: ThreeRigOptions);
+    private active;
+    play(name: string, options?: PlayOptions): void;
+    seek(time: number): void;
+    advance(dt: number): void;
+    update(dt: number): void;
+    draw(): PosedFrame;
+    drawnFrame(): PosedFrame;
+    posedFrame(slots?: SlotFilter | null): PosedFrame;
+    bone(name: string): BoneWorld;
+    bounds(): PoseBounds | null;
+    get time(): number;
+    get current(): string | null;
+    get timescale(): number;
+    set timescale(value: number);
+    get timeScale(): number;
+    set timeScale(value: number);
+    resourceCounts(): ThreeRigResourceCounts;
+    destroy(): void;
+}
+
+export { ThreeRenderer, ThreeRig, type ThreeRigOptions, type ThreeRigResourceCounts, type ThreeSlotMesh, getLivePageTextureCount, getPageRefCount, getSharedPageTexture, readMeshScreenVertices };

package/dist/index.js

@@ -0,0 +1,465 @@
+// packages/three/src/three.ts
+import { RigPlayer } from "@rig-c/play";
+import {
+  AddEquation,
+  BufferAttribute,
+  BufferGeometry,
+  CustomBlending,
+  DataTexture,
+  DoubleSide,
+  DstColorFactor,
+  DynamicDrawUsage,
+  FloatType,
+  GLSL3,
+  Group,
+  LinearFilter,
+  Mesh,
+  NearestFilter,
+  NoColorSpace,
+  OneFactor,
+  OneMinusSrcAlphaFactor,
+  OneMinusSrcColorFactor,
+  RGBAFormat,
+  ShaderMaterial,
+  Texture,
+  Vector3
+} from "three";
+
+// packages/three/src/clip.ts
+var cross = (a, b, c) => (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+function hull(points) {
+  const sorted = [...points].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const half = (items) => {
+    const result = [];
+    for (const p of items) {
+      while (result.length >= 2 && cross(result[result.length - 2], result[result.length - 1], p) <= 0) result.pop();
+      result.push(p);
+    }
+    return result;
+  };
+  return [...half(sorted).slice(0, -1), ...half([...sorted].reverse()).slice(0, -1)];
+}
+function clipPolygon(clip, detail, capacity) {
+  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");
+  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) {
+    const p = [clip.polygon[i], clip.polygon[i + 1]];
+    if (!p.every((v) => Number.isFinite(v) && Number.isFinite(Math.fround(v)))) fail(`vertex ${i / 2} contains ${p.join(",")}`);
+    const previous = points.at(-1);
+    if (!previous || previous[0] !== p[0] || previous[1] !== p[1]) points.push(p);
+  }
+  if (points.length > 1 && points[0][0] === points.at(-1)[0] && points[0][1] === points.at(-1)[1]) points.pop();
+  if (points.length < 3) fail("fewer than three distinct vertices");
+  for (let i = 0; i < points.length; i++) if (points.slice(0, i).some((p) => p[0] === points[i][0] && p[1] === points[i][1])) fail(`nonadjacent repeated vertex ${i}`);
+  const n = points.length;
+  let area = 0;
+  const on = (a, b, p) => cross(a, b, p) === 0 && p[0] >= Math.min(a[0], b[0]) && p[0] <= Math.max(a[0], b[0]) && p[1] >= Math.min(a[1], b[1]) && p[1] <= Math.max(a[1], b[1]);
+  for (let i = 0; i < n; i++) {
+    const a = points[i], b = points[(i + 1) % n];
+    area += a[0] * b[1] - a[1] * b[0];
+    for (let j = i + 2; j < n; j++) {
+      if (i === 0 && j === n - 1) continue;
+      const c = points[j], d = points[(j + 1) % n];
+      if (cross(a, b, c) * cross(a, b, d) < 0 && cross(c, d, a) * cross(c, d, b) < 0 || on(a, b, c) || on(a, b, d) || on(c, d, a) || on(c, d, b)) fail(`crossing edges ${i}/${j}`);
+    }
+  }
+  if (area === 0) fail("zero area");
+  return (clip.inverse || clip.convex ? hull(points) : points).flat();
+}
+
+// packages/three/src/three.ts
+function isWebGLHost(value) {
+  return typeof value === "object" && value !== null && "isWebGLRenderer" in value && value.isWebGLRenderer === true;
+}
+var pages = /* @__PURE__ */ new WeakMap();
+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 VERTEX = `
+out vec2 vUV;
+out vec2 vPosition;
+void main() {
+  vUV = uv;
+  vPosition = position.xy;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}`;
+var FRAGMENT = `
+precision highp float;
+uniform sampler2D page;
+uniform sampler2D polygon;
+uniform int points;
+uniform bool inverse;
+uniform vec4 light;
+uniform vec3 dark;
+in vec2 vUV;
+in vec2 vPosition;
+out vec4 outColor;
+void main() {
+  if (points > 0) {
+    bool inside = false;
+    vec2 b = texelFetch(polygon, ivec2(points - 1, 0), 0).xy;
+    for (int i = 0; i < points; i++) {
+      vec2 a = texelFetch(polygon, ivec2(i, 0), 0).xy;
+      if ((a.y > vPosition.y) != (b.y > vPosition.y)) {
+        float x = (b.x - a.x) * (vPosition.y - a.y) / (b.y - a.y) + a.x;
+        if (vPosition.x < x) inside = !inside;
+      }
+      b = a;
+    }
+    if (inverse ? inside : !inside) discard;
+  }
+  vec4 t = texture(page, vUV);
+  outColor = vec4((t.rgb * light.rgb + (t.a - t.rgb) * dark) * light.a, t.a * light.a);
+}`;
+var ThreeRenderer = class {
+  constructor(root, assets, host) {
+    this.root = root;
+    this.assets = assets;
+    this.host = host;
+    if (!root?.isGroup || !assets || !(assets.pageImages instanceof Map) || !isWebGLHost(host)) throw new Error("ThreeRenderer: expected Group, ModelAssets.pageImages Map and WebGLRenderer");
+  }
+  root;
+  assets;
+  host;
+  positionUploadCount = 0;
+  uvUploadCount = 0;
+  triangleUploadCount = 0;
+  alwaysReuploadGeometry = false;
+  /** Negative-control switch; normal disposal always releases retained page textures. */
+  releasePageTexturesOnDispose = true;
+  disposed = false;
+  pool = /* @__PURE__ */ new Map();
+  materials = /* @__PURE__ */ new Map();
+  retained = /* @__PURE__ */ new Set();
+  get geometryUploadCount() {
+    return this.positionUploadCount + this.uvUploadCount + this.triangleUploadCount;
+  }
+  get isDisposed() {
+    return this.disposed;
+  }
+  resourceCounts() {
+    return { meshes: this.pool.size, geometries: this.pool.size, materials: this.materials.size, clipTextures: [...this.pool.values()].filter((e) => e.polygon !== null).length, retainedPages: this.retained.size, livePageTextures: livePages.size };
+  }
+  getPageTexture(name) {
+    const image = this.assets.pageImages.get(name);
+    return image && this.retained.has(image) ? pages.get(image)?.texture : void 0;
+  }
+  prepare(slot) {
+    const detail = `ThreeRenderer: slot "${slot?.slot ?? "<unnamed>"}" on page "${slot?.page ?? "<unnamed>"}"`;
+    const fail = (why) => {
+      throw new Error(`${detail}: ${why}`);
+    };
+    if (!slot || slot.kind !== "region" && slot.kind !== "mesh") fail(`kind=${String(slot && slot.kind)} (expected region or mesh)`);
+    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)`);
+    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)`);
+    };
+    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 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 };
+  }
+  material(item) {
+    let material = this.materials.get(item.image);
+    if (material) return material;
+    let page = pages.get(item.image);
+    if (!page) {
+      const texture = new Texture(item.image);
+      texture.flipY = false;
+      texture.premultiplyAlpha = !item.slot.pma;
+      texture.generateMipmaps = false;
+      texture.minFilter = texture.magFilter = LinearFilter;
+      texture.colorSpace = NoColorSpace;
+      texture.needsUpdate = true;
+      page = { texture, pma: item.slot.pma, holders: /* @__PURE__ */ new Set() };
+      pages.set(item.image, page);
+      livePages.add(texture);
+    }
+    page.holders.add(this);
+    this.retained.add(item.image);
+    material = new ShaderMaterial({
+      glslVersion: GLSL3,
+      vertexShader: VERTEX,
+      fragmentShader: FRAGMENT,
+      uniforms: { page: { value: page.texture }, polygon: { value: page.texture }, points: { value: 0 }, inverse: { value: false }, light: { value: [1, 1, 1, 1] }, dark: { value: [0, 0, 0] } },
+      transparent: true,
+      depthWrite: false,
+      depthTest: true,
+      side: DoubleSide,
+      forceSinglePass: true,
+      toneMapped: false,
+      blending: CustomBlending
+    });
+    this.materials.set(item.image, material);
+    return material;
+  }
+  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));
+    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}`;
+      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 };
+        this.pool.set(key, entry);
+      }
+      const { mesh } = entry;
+      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))) {
+        mesh.geometry.dispose();
+        mesh.geometry = new BufferGeometry();
+        entry.uvs = entry.indices = null;
+      }
+      mesh.posedSlot = item.slot;
+      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 array = attribute.array;
+        for (let i = 0; i < values.length; i++) if (array[i] !== Math.fround(values[i])) {
+          array[i] = values[i];
+          changed = true;
+        }
+        if (changed) {
+          attribute.needsUpdate = true;
+          if (name === "position") this.positionUploadCount++;
+          else 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;
+      }
+      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]);
+        this.triangleUploadCount++;
+        entry.indices = item.indices;
+      }
+      if (item.polygon !== null && (entry.polygon === null || item.polygon.length !== entry.polygonValues.length || item.polygon.some((v, i) => v !== entry.polygonValues[i]))) {
+        const data = new Float32Array(item.polygon.length * 2);
+        for (let i = 0; i < item.polygon.length; i += 2) {
+          data[i * 2] = item.polygon[i];
+          data[i * 2 + 1] = item.polygon[i + 1];
+        }
+        entry.polygon?.dispose();
+        entry.polygon = new DataTexture(data, item.polygon.length / 2, 1, RGBAFormat, FloatType);
+        entry.polygon.minFilter = entry.polygon.magFilter = NearestFilter;
+        entry.polygon.needsUpdate = true;
+        entry.polygonValues = item.polygon;
+      } else if (item.polygon === null && entry.polygon !== null) {
+        entry.polygon.dispose();
+        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);
+    for (const mesh of active) this.root.add(mesh);
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const e of this.pool.values()) {
+      e.mesh.removeFromParent();
+      e.mesh.geometry.dispose();
+      e.polygon?.dispose();
+    }
+    this.pool.clear();
+    for (const material of this.materials.values()) material.dispose();
+    this.materials.clear();
+    if (this.releasePageTexturesOnDispose) for (const image of this.retained) {
+      const page = pages.get(image);
+      if (!page) continue;
+      page.holders.delete(this);
+      if (page.holders.size === 0) {
+        page.texture.dispose();
+        livePages.delete(page.texture);
+        pages.delete(image);
+      }
+    }
+    this.retained.clear();
+  }
+};
+function readMeshScreenVertices(mesh, camera, width, height) {
+  mesh.updateWorldMatrix(true, false);
+  camera.updateWorldMatrix(true, false);
+  const positions = mesh.geometry.getAttribute("position"), result = [];
+  for (let i = 0; i < positions.count; i++) {
+    const p = new Vector3().fromBufferAttribute(positions, i).applyMatrix4(mesh.matrixWorld).project(camera);
+    result.push((p.x + 1) * width / 2, (1 - p.y) * height / 2);
+  }
+  return result;
+}
+var ThreeRig = class extends Group {
+  constructor(assets, options) {
+    super();
+    this.assets = assets;
+    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.renderer = new ThreeRenderer(this, assets, options.renderer);
+    this.timescale = scale;
+    try {
+      this.lastFrame = this.draw();
+    } catch (error) {
+      this.renderer.dispose();
+      this.player.dispose();
+      throw error;
+    }
+  }
+  assets;
+  player;
+  renderer;
+  lastFrame;
+  destroyed = false;
+  active() {
+    if (this.destroyed) throw new Error("ThreeRig: called after destroy (expected active rig)");
+  }
+  play(name, options = {}) {
+    this.active();
+    this.player.play(name, options);
+    this.draw();
+  }
+  seek(time) {
+    this.active();
+    if (!Number.isFinite(time)) throw new Error(`ThreeRig: time=${time} (expected finite seconds)`);
+    this.player.seek(time);
+    this.draw();
+  }
+  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();
+  }
+  update(dt) {
+    this.advance(dt);
+  }
+  draw() {
+    this.active();
+    const frame = this.player.posedFrame();
+    this.renderer.render(frame);
+    this.lastFrame = frame;
+    return frame;
+  }
+  drawnFrame() {
+    this.active();
+    return this.lastFrame;
+  }
+  posedFrame(slots) {
+    this.active();
+    return this.player.posedFrame(slots);
+  }
+  bone(name) {
+    this.active();
+    return this.player.bone(name);
+  }
+  bounds() {
+    this.active();
+    return this.player.bounds();
+  }
+  get time() {
+    return this.player.time;
+  }
+  get current() {
+    return this.player.current;
+  }
+  get timescale() {
+    return this.player.timeScale;
+  }
+  set timescale(value) {
+    this.active();
+    if (!Number.isFinite(value) || value < 0) throw new Error(`ThreeRig: timescale=${value} (expected finite number >=0)`);
+    this.player.timeScale = value;
+  }
+  get timeScale() {
+    return this.timescale;
+  }
+  set timeScale(value) {
+    this.timescale = value;
+  }
+  resourceCounts() {
+    return this.renderer.resourceCounts();
+  }
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.renderer.dispose();
+    this.player.dispose();
+    this.removeFromParent();
+  }
+};
+export {
+  ThreeRenderer,
+  ThreeRig,
+  getLivePageTextureCount,
+  getPageRefCount,
+  getSharedPageTexture,
+  readMeshScreenVertices
+};

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@rig-c/three",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Play rig-c model documents in a native Three.js scene through @rig-c/play.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "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",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "three": "^0.186.1",
+    "@rig-c/play": "^1.10.0"
+  },
+  "devDependencies": {
+    "@rig-c/adapters-shared": "workspace:*",
+    "@types/three": "0.186.0"
+  },
+  "scripts": {
+    "build": "bun ../../scripts/build-packages.mjs --package packages/three"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}