@rig-c/core 2.65.2 → 2.66.0

package/docs/AUTHORING.md

@@ -12045,3 +12045,79 @@ for `declared` and the run says so on a line of its own.
   `@rig-c/play` or `rigc preview`.
 - **Not a second poser.** Everything it draws is a pose `render` would have drawn at
   the same frame; where it disagrees with `render --geometry`, it is wrong (`IN04`).
+
+## 14. Read a named mesh at setup
+
+`rig-c/core` promises `readSetupMesh(view, target)` and the types
+`SetupMeshTarget` and `SetupMesh` (issue #1538). It reads any named mesh or linked
+mesh, including one the setup pose does not select, without a player, animation
+step or change to the document's setup selection.
+
+```ts
+import { readModel, underNoSkin, readSetupMesh } from 'rig-c/core';
+import type { SetupMeshTarget, SetupMesh } from 'rig-c/core';
+
+const view = underNoSkin(readModel(modelText));
+const target: SetupMeshTarget = { slot: 'flag', attachment: 'alternate' };
+const mesh: SetupMesh = readSetupMesh(view, target);
+// mesh.vertices: full-double world x,y pairs, y up; no crop/camera conversion.
+```
+
+| field | contract |
+| --- | --- |
+| `target.slot`, `target.attachment` | exact slot name and attachment **table key**; a record's display name, path or atlas region is not an alias |
+| `target.skin` omitted | retain the supplied view, including `readModel`'s `all`; use `underNoSkin` for a fresh skeleton's view |
+| `target.skin: null` | no skin set: default-table fallback, no skin-required bones or constraints activated |
+| `target.skin: name` | the named view, with default-table fallback; only the named skin's activation lists apply |
+| `target.skin: 'all'` | all activation lists; a uniquely filled key resolves, identical definitions keep the existing resolver's first supplying skin, differing definitions are refused because the model does not carry the Spine file's merge order |
+| `mesh.slot`, `mesh.attachment`, `mesh.skin` | requested slot and table key, and the table's supplying skin (which can be the default fallback); a linked mesh retains its own identity |
+| `mesh.vertices` | fresh mutable `number[]`, flat x,y in world units; stored coordinates and weights use the poser's float32 reading and influence order, without normalization |
+| `mesh.triangles`, `mesh.hull` | fresh mutable triangle indices; hull is the number of leading hull **vertices**, or `null` when absent |
+
+Definition equality ignores object property insertion order at every depth,
+including weighted binding records. Array positions, object key presence and
+leaf values remain significant; leaves use `Object.is`, so positive and negative
+zero are distinct when retained in a model. Reordering object keys alone is not
+a different definition. A genuine value, shape or array-order difference still
+produces the same named all-skin refusal; no merge order is inferred.
+
+The setup matrices come from the raw setup poser's existing constraint path,
+including setup sliders and reset physics. A selected mesh is bit-identical to
+`poseRawSetup(view)`'s geometry, including any setup-slider deform. An unselected
+mesh uses its stored vertices through those same matrices: the API never switches
+an attachment to ask what a slider or path constraint would do after a switch.
+A linked mesh borrows its source vertices, triangles and hull; unweighted
+vertices use the queried slot's bone, weighted vertices their named bindings.
+Its `timelines` flag controls source-deform inheritance only when selected, as
+in the existing setup poser. An inactive bone keeps the existing zero world
+matrix; an attachment read does not activate it.
+
+Every result is detached: changing its object or arrays changes no document,
+pose, cached topology or subsequent read. Missing slots, attachments and skins,
+and region, clipping, path or bounding-box targets, throw `CoreInputError`
+naming the requested identity and the problem. Examples include
+`setup mesh slot "s" attachment "missing" under skin null: no such attachment`
+and `…: region is not a mesh`. Ambiguous all-skin definitions name their skins
+and say `choose a named skin`; unknown skin retains `underSkin`'s existing
+`--skin "missing": no such skin` refusal. Existing setup/non-finite refusals
+propagate; the read does not manufacture a partial result when setup is absent.
+
+`S1538` controls exercise literal coordinates, detached data, linked meshes,
+skin lookup and activation, setup-slider deform, and the official runtime's
+`computeWorldVertices` using ordinary JS output arrays at tolerance 0. The
+runtime stores local mesh coordinates and weights in float32, but an output
+`Float32Array` would add a second rounding that this API does not perform.
+
+**Measured nonselected slider distinction.** In spine-core 4.3.13,
+`computeWorldVertices(skeleton, slot, …)` over an unselected mesh still reads
+the **selected slot's deform array**, even for a linked mesh with
+`timelines: false`. `S1538_09` measures a slider at time 0.5 interpolating
+local offsets `(1,2)` and `(3,4)` to `(2,3)`, with a selected source mesh,
+a linked mesh inheriting its timeline, and an independent linked mesh.
+All three selected reads are exact. Four of the six nonselected calls to the
+official method reuse the selected deform; their maximum absolute difference
+from this API is `2.9999999999999982` world units. The other two nonselected
+calls, with the independent linked mesh selected, agree exactly. The API's
+nonselected output is the stored source geometry through the unchanged setup
+matrices; it does not borrow a different selection's deform. The control
+checks both results and the source of the difference, without an epsilon.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.65.2",
+  "version": "2.66.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/core/deform.ts

@@ -180,9 +180,9 @@
  */
 import type { ModelSlot, ModelVertices } from '../model.ts';
 import { bezierPolyline, keyIndexAt, type CoreAnimationTimelines, type CoreCurve } from './animation.ts';
-import { activeBones, shownRow, type CompiledDocument, type CoreShown, type CoreSkin, type ShownResolution } from './index.ts';
+import { activeBones, shownAttachment, shownRow, type CompiledDocument, type CoreShown, type CoreSkin, type ShownResolution } from './index.ts';
 import { fillingSkins, slotTimelinesApply, type SlotTimelineGate } from './skins.ts';
-import type { CoreGeometry, ShownGeometry } from './vertices.ts';
+import type { ShownGeometry } from './vertices.ts';
 
 /** The far end the deform curve's recurrence runs to — the header's measurement. */
 export const DEFORM_CURVE_END = 0.99999999;
@@ -515,6 +515,111 @@ export function timelineIdentity(slot: string, shown: CoreShown): string | null
 
 const nameOf = (a: CoreAttachmentTimeline): string => `${a.skin}/${a.slot}/${a.attachment}`;
 
+/** The part of an attachment state that depends only on the document view and placeholder. */
+interface AttachmentIdentity {
+  readonly entry: ShownGeometry;
+  readonly identity: string | null;
+  readonly vertices: ModelVertices | null;
+  readonly count: number | undefined;
+  readonly fillers: readonly string[];
+}
+
+/** Like shownAttachment's cache, scoped to the view; a new skin view resolves its own records. */
+const identitiesOfView = new WeakMap<CompiledDocument, Map<string, Map<string, AttachmentIdentity | null>>>();
+
+function readIdentity(doc: CompiledDocument, resolve: (doc: CompiledDocument, slot: ModelSlot) => ShownResolution, slot: ModelSlot, placeholder: string): AttachmentIdentity | null {
+  const s = resolve(doc, { ...slot, setup: placeholder });
+  if (s === null || 'conflict' in s || s.record.geometry === undefined) return null;
+  const g = s.record.geometry;
+  const source = g.kind === 'linkedmesh' ? doc.skins.find((k) => k.name === g.skin)?.attachments[g.slot]?.[g.source] : s.record;
+  const sg = source?.geometry;
+  return Object.freeze({
+    entry: Object.freeze({ slot: slot.name, bone: slot.bone, name: shownRow(s).name, placeholder: s.placeholder, skin: s.skin, geometry: g }),
+    identity: timelineIdentity(slot.name, s),
+    vertices: sg !== undefined && sg.kind !== 'region' && sg.kind !== 'linkedmesh' ? sg.vertices : null,
+    count: source?.sequenceCount,
+    fillers: Object.freeze(fillingSkins(doc, slot.name, s.placeholder).map((k) => `"${k}"`)),
+  });
+}
+
+function identityOf(doc: CompiledDocument, resolve: (doc: CompiledDocument, slot: ModelSlot) => ShownResolution, slot: ModelSlot, placeholder: string | null): AttachmentIdentity | null {
+  if (placeholder === null) return null;
+  // A planted resolver may read changing state outside the document. Only the document's own reader is immutable.
+  if (resolve !== shownAttachment) return readIdentity(doc, resolve, slot, placeholder);
+  let slots = identitiesOfView.get(doc);
+  if (slots === undefined) identitiesOfView.set(doc, slots = new Map());
+  let placeholders = slots.get(slot.name);
+  if (placeholders === undefined) slots.set(slot.name, placeholders = new Map());
+  if (placeholders.has(placeholder)) return placeholders.get(placeholder) as AttachmentIdentity | null;
+  const identity = readIdentity(doc, resolve, slot, placeholder);
+  placeholders.set(placeholder, identity);
+  return identity;
+}
+
+/** Index only immutable timeline identity. Times, mixes and the values they compute are never cached. */
+const attachmentsByIdentity = new WeakMap<readonly CoreAttachmentTimeline[], ReadonlyMap<string, readonly CoreAttachmentTimeline[]>>();
+type AttachmentSlots = AttachmentApplication['timelines']['slots'];
+type AttachmentSwitch = NonNullable<AttachmentSlots[number]['timelines'][number]['keys']>;
+const switchesBySlot = new WeakMap<AttachmentSlots, ReadonlyMap<string, readonly AttachmentSwitch[]>>();
+
+function matchingAttachments(timelines: readonly CoreAttachmentTimeline[], identity: string): readonly CoreAttachmentTimeline[] | undefined {
+  let index = attachmentsByIdentity.get(timelines);
+  if (index === undefined) {
+    const rows = new Map<string, CoreAttachmentTimeline[]>();
+    for (const a of timelines) {
+      const name = nameOf(a);
+      const found = rows.get(name);
+      if (found === undefined) rows.set(name, [a]);
+      else found.push(a);
+    }
+    attachmentsByIdentity.set(timelines, index = rows);
+  }
+  return index.get(identity);
+}
+
+function slotSwitches(slots: AttachmentSlots, slot: string): readonly AttachmentSwitch[] | undefined {
+  let index = switchesBySlot.get(slots);
+  if (index === undefined) {
+    const rows = new Map<string, AttachmentSwitch[]>();
+    for (const target of slots) {
+      for (const tl of target.timelines) {
+        if (tl.kind !== 'attachment' || tl.keys === undefined) continue;
+        const found = rows.get(target.name);
+        if (found === undefined) rows.set(target.name, [tl.keys]);
+        else found.push(tl.keys);
+      }
+    }
+    switchesBySlot.set(slots, index = rows);
+  }
+  return index.get(slot);
+}
+
+/** Allocated only when a matching timeline or a mixed deform actually has per-pose state. */
+interface AttachmentValues {
+  deform: number[] | null;
+  frame: number | null;
+  seen: string[];
+}
+
+function applyAttachment(now: AttachmentIdentity | null, values: AttachmentValues | null, timelines: readonly CoreAttachmentTimeline[], t: number, blend: AttachmentApplication | null, evalDeform: DeformEvaluator, blendOf: DeformBlender, evalFrame: SequenceEvaluator): AttachmentValues | null {
+  if (now === null || now.identity === null) return values;
+  const matching = matchingAttachments(timelines, now.identity);
+  if (matching === undefined) return values;
+  values ??= { deform: null, frame: null, seen: [] };
+  if (!values.seen.includes(now.identity)) values.seen.push(now.identity);
+  for (const a of matching) {
+    if (a.deform !== null && now.vertices !== null) {
+      const target = evalDeform(now.vertices, a.deform, t);
+      if (target !== null) values.deform = blend === null ? target : blendOf(now.vertices, values.deform, target, blend.alpha, blend.additive);
+    }
+    if (a.sequence !== null && now.count !== undefined) {
+      const f = evalFrame(a.sequence, now.count, t);
+      if (f !== null) values.frame = f;
+    }
+  }
+  return values;
+}
+
 /**
  * Every slot's shown geometry at one pose — the setup's (`sample` null) or a
  * sample's — with the deform array and the series' frame its attachment
@@ -528,6 +633,11 @@ const nameOf = (a: CoreAttachmentTimeline): string => `${a.skin}/${a.slot}/${a.a
  * differently is left to the slots' own absence. `why` names what the core
  * does not pose: a timeline moving a record whose placeholder several skins
  * fill (the header's ⚠️).
+ *
+ * Identity is kept per document view, slot and placeholder, and timelines
+ * indexed by their record identity. A slot with no per-pose values reuses its
+ * frozen entry; deform arrays and sequence frames are evaluated afresh.
+ * Sliders select identities in application order, never a cached posed value.
  */
 export function attachmentStates(
   doc: CompiledDocument,
@@ -557,66 +667,39 @@ export function attachmentStates(
     const live = gate(doc, slot, active);
     let placeholder = placeholders.get(slot.name) ?? null;
     const base = live ? mixed?.get(slot.name) : undefined;
-    let deform: number[] | null = base?.deform ?? null;
-    let frame: number | null = null;
-    const seen: string[] = base === undefined ? [] : [...base.seen];
-    // What the slot shows now, the record its timelines are keyed as, and what a deform or a frame is computed on.
-    const state = (): { s: CoreShown; identity: string | null; vertices: ModelVertices | null; count: number | undefined } | null => {
-      if (placeholder === null) return null;
-      const s = resolve(doc, { ...slot, setup: placeholder });
-      if (s === null || 'conflict' in s || s.record.geometry === undefined) return null;
-      const g = s.record.geometry;
-      const source = g.kind === 'linkedmesh' ? doc.skins.find((k) => k.name === g.skin)?.attachments[g.slot]?.[g.source] : s.record;
-      const sg = source?.geometry;
-      const vertices = sg !== undefined && sg.kind !== 'region' && sg.kind !== 'linkedmesh' ? sg.vertices : null;
-      return { s, identity: timelineIdentity(slot.name, s), vertices, count: source?.sequenceCount };
-    };
-    const apply = (timelines: readonly CoreAttachmentTimeline[], t: number, blend: { alpha: number; additive: boolean } | null): void => {
-      const now = state();
-      if (now === null || now.identity === null) return;
-      for (const a of timelines) {
-        if (nameOf(a) !== now.identity) continue;
-        if (!seen.includes(now.identity)) seen.push(now.identity);
-        if (a.deform !== null && now.vertices !== null) {
-          const target = evalDeform(now.vertices, a.deform, t);
-          if (target !== null) deform = blend === null ? target : blendOf(now.vertices, deform, target, blend.alpha, blend.additive);
-        }
-        if (a.sequence !== null && now.count !== undefined) {
-          const f = evalFrame(a.sequence, now.count, t);
-          if (f !== null) frame = f;
-        }
-      }
-    };
-    if (sample !== null && live) apply(sample.timelines.attachments, sample.t, null);
-    for (const app of live ? sliders : []) {
-      // The slider's attachment key first, as the slot timelines are (`applySliderSlots` in `./constraints_slider.ts`); a switch to another placeholder clears what the timelines set.
-      for (const target of app.timelines.slots) {
-        if (target.name !== slot.name) continue;
-        for (const tl of target.timelines) {
-          if (tl.kind !== 'attachment' || tl.keys === undefined) continue;
-          const i = keyIndexAt(tl.keys, app.at);
-          if (i < 0) continue;
-          const next = tl.keys[i].name ?? null;
-          if (next !== placeholder) {
-            deform = null;
-            frame = null;
+    let values: AttachmentValues | null = base === undefined || (base.deform === null && base.seen.length === 0) ? null : { deform: base.deform, frame: null, seen: [...base.seen] };
+    let now = identityOf(doc, resolve, slot, placeholder);
+    if (sample !== null && live) values = applyAttachment(now, values, sample.timelines.attachments, sample.t, null, evalDeform, blendOf, evalFrame);
+    if (live) for (const app of sliders) {
+      // Each slider switches first, clearing only the per-pose values; then its attachment timelines apply to the new identity.
+      const switches = slotSwitches(app.timelines.slots, slot.name);
+      if (switches !== undefined) for (const keys of switches) {
+        const i = keyIndexAt(keys, app.at);
+        if (i < 0) continue;
+        const next = keys[i].name ?? null;
+        if (next !== placeholder) {
+          if (values !== null) {
+            values.deform = null;
+            values.frame = null;
           }
           placeholder = next;
+          now = identityOf(doc, resolve, slot, placeholder);
         }
       }
-      apply(app.timelines.attachments, app.at, { alpha: app.alpha, additive: app.additive });
+      values = applyAttachment(now, values, app.timelines.attachments, app.at, app, evalDeform, blendOf, evalFrame);
     }
-    const now = state();
     if (now === null) continue;
-    const entry: ShownGeometry = { slot: slot.name, bone: slot.bone, name: shownRow(now.s).name, placeholder: now.s.placeholder, skin: now.s.skin, geometry: now.s.record.geometry as CoreGeometry };
+    // The cached entry is frozen. A pose with a deform/frame owns its wrapper and values; later poses cannot write into it.
+    const entry = values === null || (values.deform === null && values.frame === null) ? now.entry : { ...now.entry };
     shown.push(entry);
-    const fillers = fillingSkins(doc, slot.name, now.s.placeholder).map((k) => `"${k}"`);
-    if (seen.length > 0 && fillers.length > 1) {
-      why.push(`slot "${slot.name}" shows placeholder "${now.s.placeholder}", which skins ${fillers.join(', ')} fill, and ${seen.map((x) => `"${x}"`).join(', ')} key(s) it — which record --skin all shows, and so whether the timeline moves it, is the Spine file's skin order, not the model's`);
+    if (values !== null && values.seen.length > 0 && now.fillers.length > 1) {
+      why.push(`slot "${slot.name}" shows placeholder "${now.entry.placeholder}", which skins ${now.fillers.join(', ')} fill, and ${values.seen.map((x) => `"${x}"`).join(', ')} key(s) it — which record --skin all shows, and so whether the timeline moves it, is the Spine file's skin order, not the model's`);
       continue;
     }
-    if (deform !== null) entry.deform = deform;
-    if (frame !== null) entry.frame = frame;
+    if (values !== null) {
+      if (values.deform !== null) entry.deform = values.deform;
+      if (values.frame !== null) entry.frame = values.frame;
+    }
   }
   return { shown, why };
 }

package/src/core/entry.ts

@@ -24,14 +24,15 @@
  * a Bézier segment as, so that a fitter holds its tolerance to the poser's
  * own evaluation rather than to a mirror of it, issue #1417 — re-exported,
  * never copied, because a copy is the drift the request exists to remove;
- * `CA12` holds the identity).
+ * `CA12` holds the identity; `readSetupMesh`, issue #1538, the named setup
+ * geometry read requested by the player, with `SetupMesh` and `SetupMeshTarget`).
  * The list is `scripts/install_smoke.ts`'s `OBSERVED_SYMBOLS` rows for
  * `./core`, and a symbol added here and not there is not promised.
  */
 export { readModel, underSkin, underNoSkin, CoreInputError, CORE_DOCUMENT_SPEC, CORE_DOCUMENT_SPECS, CORE_BLEND_MODES, activeBones } from './index.ts';
 export type { CompiledDocument, CoreSlotRow, CoreBlendMode } from './index.ts';
-export { poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setupBounds, physicsClockStep, PHYSICS_CLOCK_LEAD } from './raw.ts';
-export type { RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawReset } from './raw.ts';
+export { readSetupMesh, poseRawSetup, poseRawAnimation, poseRawAnimationEach, loopedTime, setupBounds, physicsClockStep, PHYSICS_CLOCK_LEAD } from './raw.ts';
+export type { SetupMesh, SetupMeshTarget, RawPose, RawBone, RawDrawn, RawClip, RawClipped, RawEvent, RawReset } from './raw.ts';
 export { poseWalkSetup, poseLoopingWalk } from './walk.ts';
 export { openTrack } from './track.ts';
 export type { LiveTrack, TrackOptions, AdjustableLocals, BoneLocals, LocalAdjust, PhysicsEnvironment } from './track.ts';

package/src/core/index.ts

@@ -1196,10 +1196,11 @@ const shownOfView = new WeakMap<CompiledDocument, Map<string, Map<string, ShownR
  * The answer reads the view's skins and the slot's name and placeholder only,
  * so it is resolved once per view, slot and placeholder and kept (issue
  * #1134: every sample of a walk resolved every slot again). Read-only to every
- * caller; a view built anew resolves its own.
+ * caller; a view built anew resolves its own. An explicit placeholder reads
+ * another table key without changing the slot (issue #1538).
  */
-export function shownAttachment(doc: CompiledDocument, slot: ModelSlot): ShownResolution {
-  if (slot.setup === null) return null;
+export function shownAttachment(doc: CompiledDocument, slot: ModelSlot, placeholder: string | null = slot.setup): ShownResolution {
+  if (placeholder === null) return null;
   let bySlot = shownOfView.get(doc);
   if (bySlot === undefined) {
     bySlot = new Map();
@@ -1210,9 +1211,9 @@ export function shownAttachment(doc: CompiledDocument, slot: ModelSlot): ShownRe
     byPlaceholder = new Map();
     bySlot.set(slot.name, byPlaceholder);
   }
-  if (byPlaceholder.has(slot.setup)) return byPlaceholder.get(slot.setup) as ShownResolution;
-  const resolved = resolveShown(doc, slot.name, slot.setup);
-  byPlaceholder.set(slot.setup, resolved);
+  if (byPlaceholder.has(placeholder)) return byPlaceholder.get(placeholder) as ShownResolution;
+  const resolved = resolveShown(doc, slot.name, placeholder);
+  byPlaceholder.set(placeholder, resolved);
   return resolved;
 }
 

package/src/core/raw.ts

@@ -113,7 +113,7 @@
  * naming why (`CoreInputError`): a renderer handed a pose with a block
  * missing would draw a different picture in silence.
  */
-import { activeBones, CoreInputError, drawWalkOf, poseSetup, rawNumber, readColour, shownAttachment, sourceOfDoc, underNoSkin, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
+import { activeBones, CoreInputError, drawWalkOf, poseSetup, rawNumber, readColour, shownAttachment, sourceOfDoc, underNoSkin, underSkin, type CompiledDocument, type CorePlant, type CoreSlotRow } from './index.ts';
 import { posedBoneWorld, posedBoneWorldAlone, posedSlots, type CoreAnimationTimelines, type LocalAdjust, type TimelinePlant } from './animation.ts';
 import { constraintsAbsentWhy, pathAnimationsWhy } from './constraints.ts';
 import { freshStepContext, rotatePhysics, steppedPreviousPassWhy, translatePhysics, DEFAULT_PHYSICS_ENVIRONMENT, type PhysicsEnvironment, type PhysicsStepContext } from './constraints_physics.ts';
@@ -121,8 +121,9 @@ import { attachmentStates } from './deform.ts';
 import { drawOrderAt, type CoreDrawOrderKey } from './draw_order.ts';
 import { eventsFired, type CoreEventRow } from './events.ts';
 import { REGION_TRIANGLES, REGION_UVS, type CoreClippedRow, type ShapeClipper } from './clipping.ts';
-import { meshArraysOf, poseGeometry, type CoreAttachmentRow, type CoreClipRow, type ShownGeometry } from './vertices.ts';
+import { meshArraysOf, poseGeometry, worldVertices, type CoreAttachmentRow, type CoreClipRow, type ShownGeometry } from './vertices.ts';
 import { RUNTIME_DEG, type CoreWorld } from './world.ts';
+import { fillingSkins } from './skins.ts';
 import type { SliderApplication } from './constraints_slider.ts';
 
 /** One bone, posed: the world transform and the runtime getters' four readings (the header's `bones`). */
@@ -465,6 +466,81 @@ export function poseRawSetup(doc: CompiledDocument, plant: CorePlant = {}): RawP
   return setupPoseIn(doc, plant, RAW_MODE);
 }
 
+/** A table key to read, with an optional skin-view override; omitted skin keeps the supplied view. */
+export interface SetupMeshTarget {
+  readonly slot: string;
+  readonly attachment: string;
+  /** A named skin (with default fallback), `all`, or `null` for no skin set. */
+  readonly skin?: string | null;
+}
+
+/** A detached named mesh in setup world units, y up; hull counts vertices, not coordinates. */
+export interface SetupMesh {
+  slot: string;
+  /** The requested attachment table key, even when the record states another display name. */
+  attachment: string;
+  /** The skin whose table supplied the requested record, including a fallback. */
+  skin: string;
+  vertices: number[];
+  triangles: number[];
+  hull: number | null;
+}
+
+/** Model definitions by value: object key order is irrelevant, array positions and signed zero are not. */
+function sameSetupMeshDefinition(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b) && a.length !== b.length) return false;
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length && keys.every((key) =>
+    Object.prototype.hasOwnProperty.call(right, key) && sameSetupMeshDefinition(left[key], right[key]));
+}
+
+/**
+ * Read a named mesh without changing the setup selection or playing anything
+ * (issue #1538). Setup constraints and reset physics use the raw poser's own
+ * path. A selected mesh includes its setup-slider deform; an unselected mesh
+ * reads its stored geometry through those same matrices, with no hypothetical
+ * attachment switch or deform. Linked meshes use their source topology and
+ * bindings, and the queried slot's bone for unweighted vertices; `timelines`
+ * affects only a selected mesh's setup-slider deform, as in `poseRawSetup`.
+ *
+ * Skin resolution is the supplied view's unless explicitly overridden. Under
+ * `all`, differing definitions of the requested mesh are refused: the model
+ * does not carry the file order that would choose one. Object property order
+ * does not distinguish definitions; array positions and Object.is leaf values
+ * do. Identical definitions keep the resolver's first supplying skin. All arrays are fresh.
+ */
+export function readSetupMesh(doc: CompiledDocument, target: SetupMeshTarget): SetupMesh {
+  const view = target.skin === undefined ? doc : target.skin === null ? underNoSkin(doc) : underSkin(doc, target.skin);
+  const where = `setup mesh slot ${JSON.stringify(target.slot)} attachment ${JSON.stringify(target.attachment)} under skin ${JSON.stringify(view.skin)}`;
+  const slot = view.slots.find((s) => s.name === target.slot);
+  if (slot === undefined) throw new CoreInputError(`${where}: no such slot`);
+  const resolved = shownAttachment(view, slot, target.attachment);
+  if (resolved === null) throw new CoreInputError(`${where}: no such attachment`);
+  const fills = fillingSkins(view, slot.name, target.attachment);
+  const definitions = fills.map((name) => view.skins.find((k) => k.name === name)?.attachments[slot.name]?.[target.attachment]);
+  if ('conflict' in resolved || definitions.some((r) => !sameSetupMeshDefinition(r, definitions[0]))) {
+    throw new CoreInputError(`${where}: skins [${fills.join(', ')}] fill this attachment differently; choose a named skin`);
+  }
+  const geometry = resolved.record.geometry;
+  const mesh = geometry?.kind === 'linkedmesh'
+    ? view.skins.find((s) => s.name === geometry.skin)?.attachments[geometry.slot]?.[geometry.source]?.geometry
+    : geometry;
+  if (mesh?.kind !== 'mesh') throw new CoreInputError(`${where}: ${resolved.record.kind} is not a mesh`);
+  const { world, shown, drawOrder } = setupPosed(view, {}, RAW_MODE);
+  const selected = shown.find((s) => s.slot === slot.name && s.placeholder === target.attachment && s.skin === resolved.skin);
+  const bone = world.get(slot.bone);
+  if (bone === undefined) throw new CoreInputError(`${where}: no setup transform for bone ${JSON.stringify(slot.bone)}`);
+  const vertices = selected === undefined
+    ? numbersOf(worldVertices(mesh.vertices, bone, world).map(rawNumber), `${where} vertex`, RAW_MODE)
+    : rawDrawn(view, [selected], world, drawOrder, {}).drawn[0].vertices;
+  return { slot: slot.name, attachment: target.attachment, skin: resolved.skin, vertices: [...vertices], triangles: [...mesh.triangles], hull: mesh.hull ?? null };
+}
+
 /** `poseRawSetup` in `mode` — under `keep`, a value that is not finite stays in the pose (`./walk.ts`). */
 export function setupPoseIn(doc: CompiledDocument, plant: CorePlant, mode: WalkMode): RawPose {
   const { world, shown, slots, drawOrder } = setupPosed(doc, plant, mode);