spine-rigc 1.5.2 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,448 @@
1
+ /**
2
+ * The draw's last input the core lacked (issue #967, step 3c of issue #380):
3
+ * each drawn attachment's atlas PAGE and its PAGE UVs — the oracle's `uvs`
4
+ * block, what `src/render.ts`'s `pieceOf` reads off `sequence.regions[index]`
5
+ * and `sequence.getUVs(index)` — and `MeshAttachment.computeUVs`'s job, the
6
+ * mapping texture substitution calls, as pure functions.
7
+ *
8
+ * The model document does not carry the page layout (`ModelAtlasRect`'s 🔸 in
9
+ * `src/model.ts`: the page, `x`, `y` and `rotate` are the packer's
10
+ * arrangement, not the drawing), and this construct does not change that: the
11
+ * atlas is a second input, read by rigc's own reader (`parseAtlasText` and
12
+ * `atlasRegionLookup` in `src/atlas.ts`) and handed in as a lookup
13
+ * (`UvLookup`), so nothing here links the runtime or opens a file.
14
+ *
15
+ * ## How every rule below was fixed
16
+ *
17
+ * By loading hand-written atlases and skeletons through spine-core 4.3.13
18
+ * (`TextureAtlas`, `AtlasAttachmentLoader`, `SkeletonJson`) and reading what
19
+ * the loaded attachments hold — `sequence.getUVs(i)`, `sequence.regions[i]`,
20
+ * `region.page.name` — and what `MeshAttachment.computeUVs` writes, then
21
+ * comparing a formula over the atlas's own numbers, bit for bit (not on the
22
+ * oracle's grid). The runtime's source was not read. Regions were random:
23
+ * pages of power-of-two and other sizes, one to three pages, `bounds` anywhere
24
+ * on the page, 70% trimmed (`offsets` other than `0, 0, width, height`), and
25
+ * `rotate` spelled `0`, `90`, `180`, `270`, `true`, `false` and, for the
26
+ * branch rules, `45`, `-90`, `360` and `450`; mesh and art UVs spelled with
27
+ * five non-float32 decimals, some outside `[0, 1]`.
28
+ *
29
+ * ### The region's own numbers
30
+ *
31
+ * With `W, H` the page's `size`, the region's `u = x/W`, `v = y/H`, and its far
32
+ * corner `u2 = (x + width)/W`, `v2 = (y + height)/H` — with `width` and
33
+ * `height` exchanged at `rotate: 90` (and `true`) ONLY. 1,500 of 1,500
34
+ * regions, as doubles; exchanged at 270 as well missed 262, never exchanged
35
+ * 484. (That 270 is not exchanged is the runtime's, and the reason
36
+ * `pageFootprint` in `src/atlas.ts` derives the page rectangle rather than
37
+ * reading these two numbers.)
38
+ *
39
+ * ### A region attachment's four UVs
40
+ *
41
+ * In the corner order of its world vertices (bottom-left, upper-left,
42
+ * upper-right, bottom-right — `./vertices.ts`): at `degrees === 90`
43
+ * `(u2, v2) (u, v2) (u, v) (u2, v)`, at every other value — 0, 180, 270 and
44
+ * the odd spellings alike — `(u, v2) (u, v) (u2, v) (u2, v2)`; each held as
45
+ * float32. 1,500 of 1,500 through `Math.fround`; as doubles, 575 missed. The
46
+ * readings rejected, on the same 1,500:
47
+ *
48
+ * | reading | misses |
49
+ * | --- | ---: |
50
+ * | 270 turned as 90 over a transposed rectangle | 262 |
51
+ * | 90's corners the other way round, `(u, v) (u2, v) (u2, v2) (u, v2)` | 487 |
52
+ * | 180 turned, `(u2, v) (u2, v2) (u, v2) (u, v)` | 260 |
53
+ * | the trim inset into the UVs | 724 |
54
+ *
55
+ * The trim does not enter a region's UVs: it enters its corners
56
+ * (`regionCorners` in `./vertices.ts`, through `ModelAtlasRect`).
57
+ *
58
+ * ### A mesh's page UVs — `MeshAttachment.computeUVs`
59
+ *
60
+ * From the attachment's own UVs `(s, t)` — art space, over the untrimmed
61
+ * drawing — per `degrees`, in doubles, starting from `u = x/W`, `v = y/H`:
62
+ *
63
+ * | degrees | `u −=` | `v −=` | span `w, h` | `(u′, v′)` |
64
+ * | --- | --- | --- | --- | --- |
65
+ * | 90 | `(oh − oy − height)/W` | `(ow − ox − width)/H` | `oh/W, ow/H` | `u + t·w, v + (1 − s)·h` |
66
+ * | 180 | `(ow − ox − width)/W` | `oy/H` | `ow/W, oh/H` | `u + (1 − s)·w, v + (1 − t)·h` |
67
+ * | 270 | `oy/W` | `ox/H` | `oh/W, ow/H` | `u + (1 − t)·w, v + s·h` |
68
+ * | any other | `ox/W` | `(oh − oy − height)/H` | `ow/W, oh/H` | `u + s·w, v + t·h` |
69
+ *
70
+ * (`ox, oy, ow, oh` the region's `offsetX, offsetY, originalWidth,
71
+ * originalHeight`; `width, height` its `bounds` size.) The subtraction is its
72
+ * own step: called into a plain array, the rule read 6,000 of 6,000 calls bit
73
+ * for bit in doubles, while one fraction `(x − ox)/W` missed 936 and texels
74
+ * first, `(x − ox + s·ow)/W`, 2,227. Into a plain array the function writes
75
+ * these doubles — 4,000 of 4,000 calls wrote a value that is not a float32 —
76
+ * and what an attachment HOLDS is each through `Math.fround`, because its
77
+ * array is a `Float32Array`: 1,500 of 1,500 meshes, and `computeUVs` over the
78
+ * attachment's region and own UVs reproduced the held array on all 1,500. The
79
+ * rule through `Math.fround` held on 4,000 direct calls into a `Float32Array`,
80
+ * 400 per spelling, the odd spellings taking the last row.
81
+ *
82
+ * ⚠️ **The mesh's own UVs are read as the doubles the text spells, not as
83
+ * float32.** Reading them through `Math.fround` first missed 311 of 1,500
84
+ * meshes (worst 4.8e-7, one float32 step of a UV near 1); every intermediate
85
+ * in float32 missed 844. So `computeUvs` takes the model's `uvs` as they are.
86
+ *
87
+ * ### Which region, on which page
88
+ *
89
+ * - A region or mesh draws the atlas region named by its `path`, else its
90
+ * name — the oracle's `path` cell (`shownRow` in `./index.ts`). The first
91
+ * region of that name in the file wins (two regions named alike, the first
92
+ * drawn), and the name is compared as the atlas line spells it: a region
93
+ * line `art ` is not found as `art`, while CRLF line ends are not part of a
94
+ * name (`parseAtlasText` splits on them).
95
+ * - A **sequence**'s frame `i` draws `path + (start + i)`, the number padded
96
+ * with zeros to `digits` (`padStart`): `start` 1 and `digits` 0 when
97
+ * unstated — a three-frame `x` drew `x1, x2, x3`; `start 8, digits 0` drew
98
+ * `x8, x9, x10`; `start 99, digits 1` `x99, x100`; `start 5, digits 4`
99
+ * `x0005, x0006`. The atlas's own `index:` field is not how a frame is
100
+ * found: regions named `seq` with `index: 1` and `2` loaded as `Region not
101
+ * found in atlas: seq1`. Each frame draws on its own region's page: a
102
+ * four-frame series over two pages drew frames 0–1 on the first and 2–3 on
103
+ * the second, a mesh's frames alike.
104
+ * - The frame drawn is the one the pose shows (`./deform.ts`'s sequence rule,
105
+ * measured there through a region's corners), or the sequence's `setup` (0
106
+ * unstated) where no timeline set one.
107
+ * - A **linked mesh** draws its OWN `path`'s region (and its own sequence's
108
+ * frames — a link stating one drew `l1, l2, l3` from setup frame 2 whatever
109
+ * its source stated; a link stating none drew its own path) over its
110
+ * SOURCE's UVs: a link on page `a.png` whose source sat on `b.png` drew
111
+ * `a.png`, and its uvs were `computeUVs` of its own region over the
112
+ * source's `regionUVs`.
113
+ * - The page cell is the page's name as `parseAtlasText` trims it — the
114
+ * runtime's `page.name` for a page line ` p.png ` read `p.png`.
115
+ *
116
+ * ## What is posed, and what is left out
117
+ *
118
+ * Rows in the pose's draw order, one per slot showing a region, a mesh or a
119
+ * linked mesh — the slots the `attachments` block lists, whatever their bone
120
+ * or alpha. Which record a slot shows and the frame its series is at are the
121
+ * ones `./deform.ts`'s `attachmentStates` computes for the same pose, from the
122
+ * placeholders the sample's own timelines leave (`posedSlots`) and the
123
+ * sliders' applications (`posedBoneWorld`); at setup, from the setup
124
+ * placeholders and the sliders applied to the setup pose. That repeats the
125
+ * walk `poseSetup` and `poseAnimations` make, because neither returns the
126
+ * frame (issue #966 retains it in the raw entry); the gate holds the two
127
+ * walks to one answer by comparing both against the runtime.
128
+ *
129
+ * A region the atlas does not have is refused by name (`CoreInputError`):
130
+ * spine-core refuses to load the same pair. The block is left out, with the
131
+ * reason, where what a slot shows is not posed — the slots or the draw order
132
+ * absent — and where a linked mesh stating its own sequence is stepped by a
133
+ * sequence timeline counted over its source's frames, a case never measured.
134
+ *
135
+ * ## Purity
136
+ *
137
+ * As the rest of the core: nothing from the Spine runtime package, nothing
138
+ * from `src/transform.ts`, no clock, no randomness, no I/O.
139
+ */
140
+ import { activeBones, constraintRecords, CoreInputError, shownAttachment, type CompiledDocument, type CoreAnimation } from './index.ts';
141
+ import { posedBoneWorld, posedSlots } from './animation.ts';
142
+ import { applyConstraints } from './constraints.ts';
143
+ import type { SliderApplication } from './constraints_slider.ts';
144
+ import { attachmentStates } from './deform.ts';
145
+ import type { ShownGeometry } from './vertices.ts';
146
+ import { worldTransforms } from './world.ts';
147
+
148
+ /** A region as these rules read it — `AtlasRegion` in `src/atlas.ts` is one, and so is spine-core's `TextureAtlasRegion`. */
149
+ export interface UvRegion {
150
+ x: number;
151
+ y: number;
152
+ width: number;
153
+ height: number;
154
+ offsetX: number;
155
+ offsetY: number;
156
+ originalWidth: number;
157
+ originalHeight: number;
158
+ degrees: number;
159
+ }
160
+
161
+ /** A page as these rules read it: its trimmed name and its `size`. */
162
+ export interface UvPage {
163
+ name: string;
164
+ width: number;
165
+ height: number;
166
+ }
167
+
168
+ /** The region an atlas draws under a name, and its page — the first of that name, as the header states; `null` when there is none. */
169
+ export type UvLookup = (name: string) => { page: UvPage; region: UvRegion } | null;
170
+
171
+ /**
172
+ * The readings the header's tables rejected, each a switch — what the core
173
+ * suite's `CU` plants pass to show the gate names it. The functions below with
174
+ * none set are the rules measured; nothing but a plant sets one.
175
+ */
176
+ export interface UvReading {
177
+ /** A region at 90 in the other corner order, `(u, v) (u2, v) (u2, v2) (u, v2)` — the rotation flipped. */
178
+ rotationFlipped?: boolean;
179
+ /** A region at 270 turned as one at 90, over a transposed rectangle; a mesh at 270 mapped by 90's `(u + t·w, v + (1 − s)·h)`. */
180
+ turned270?: boolean;
181
+ /** A mesh's page UVs with the trim offsets dropped (`ox = oy = 0`, the original size the kept one). */
182
+ trimDropped?: boolean;
183
+ /** A mesh's own UVs read through `Math.fround` first. */
184
+ artAsFloat32?: boolean;
185
+ }
186
+
187
+ /** A region attachment's four page UVs as the runtime holds them — the header's rule, in the world corners' order. */
188
+ export function regionPageUvs(region: UvRegion, page: UvPage, reading: UvReading = {}): number[] {
189
+ const turned = region.degrees === 90 || (reading.turned270 === true && region.degrees === 270);
190
+ const u = region.x / page.width;
191
+ const v = region.y / page.height;
192
+ const u2 = (region.x + (turned ? region.height : region.width)) / page.width;
193
+ const v2 = (region.y + (turned ? region.width : region.height)) / page.height;
194
+ let out: number[];
195
+ if (turned) out = reading.rotationFlipped === true ? [u, v, u2, v, u2, v2, u, v2] : [u2, v2, u, v2, u, v, u2, v];
196
+ else out = [u, v2, u, v, u2, v, u2, v2];
197
+ return out.map(Math.fround);
198
+ }
199
+
200
+ /**
201
+ * `MeshAttachment.computeUVs`: art-space UVs over the untrimmed drawing mapped
202
+ * onto `region` of `page`, in doubles — the header's table. What texture
203
+ * substitution writes into its plain array; an attachment holds each value
204
+ * through `Math.fround` (`meshPageUvs`).
205
+ */
206
+ export function computeUvs(region: UvRegion, page: UvPage, art: readonly number[], reading: UvReading = {}): number[] {
207
+ const dropped = reading.trimDropped === true;
208
+ const ox = dropped ? 0 : region.offsetX;
209
+ const oy = dropped ? 0 : region.offsetY;
210
+ const ow = dropped ? region.width : region.originalWidth;
211
+ const oh = dropped ? region.height : region.originalHeight;
212
+ const W = page.width;
213
+ const H = page.height;
214
+ const s = reading.artAsFloat32 === true ? art.map(Math.fround) : art;
215
+ let u = region.x / W;
216
+ let v = region.y / H;
217
+ const out: number[] = [];
218
+ switch (region.degrees) {
219
+ case 90: {
220
+ u -= (oh - oy - region.height) / W;
221
+ v -= (ow - ox - region.width) / H;
222
+ const w = oh / W;
223
+ const h = ow / H;
224
+ for (let i = 0; i + 1 < s.length; i += 2) out.push(u + s[i + 1] * w, v + (1 - s[i]) * h);
225
+ return out;
226
+ }
227
+ case 180: {
228
+ u -= (ow - ox - region.width) / W;
229
+ v -= oy / H;
230
+ const w = ow / W;
231
+ const h = oh / H;
232
+ for (let i = 0; i + 1 < s.length; i += 2) out.push(u + (1 - s[i]) * w, v + (1 - s[i + 1]) * h);
233
+ return out;
234
+ }
235
+ case 270: {
236
+ u -= oy / W;
237
+ v -= ox / H;
238
+ const w = oh / W;
239
+ const h = ow / H;
240
+ if (reading.turned270 === true) for (let i = 0; i + 1 < s.length; i += 2) out.push(u + s[i + 1] * w, v + (1 - s[i]) * h);
241
+ else for (let i = 0; i + 1 < s.length; i += 2) out.push(u + (1 - s[i + 1]) * w, v + s[i] * h);
242
+ return out;
243
+ }
244
+ default: {
245
+ u -= ox / W;
246
+ v -= (oh - oy - region.height) / H;
247
+ const w = ow / W;
248
+ const h = oh / H;
249
+ for (let i = 0; i + 1 < s.length; i += 2) out.push(u + s[i] * w, v + s[i + 1] * h);
250
+ return out;
251
+ }
252
+ }
253
+ }
254
+
255
+ /** A mesh's page UVs as the attachment holds them: `computeUvs`, each through `Math.fround`. */
256
+ export function meshPageUvs(region: UvRegion, page: UvPage, art: readonly number[], reading: UvReading = {}): number[] {
257
+ return computeUvs(region, page, art, reading).map(Math.fround);
258
+ }
259
+
260
+ /** A record's series, as the parser reads the four fields: `start` 1, `digits` 0 and `setup` 0 when unstated. */
261
+ export interface UvSequence {
262
+ count: number;
263
+ start: number;
264
+ digits: number;
265
+ setup: number;
266
+ }
267
+
268
+ /** Every record's series, by `skin/slot/placeholder` — `readUvSequences`. */
269
+ export type UvSequences = ReadonlyMap<string, UvSequence>;
270
+
271
+ /** The region a series' frame draws: `path + (start + frame)`, padded with zeros to `digits` — the header's rule. */
272
+ export function frameRegionName(path: string, sequence: UvSequence, frame: number): string {
273
+ return path + String(sequence.start + frame).padStart(sequence.digits, '0');
274
+ }
275
+
276
+ const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
277
+ const whole = (v: unknown, min: number): v is number => typeof v === 'number' && Number.isInteger(v) && v >= min;
278
+
279
+ /**
280
+ * Every record's `sequence` in a `rigc-compiled/1` document, as the parser
281
+ * reads it — `readModel` keeps a series' count and nothing else of it, and a
282
+ * frame's region name needs `start` and `digits`. Refuses, naming the path, a
283
+ * field that is not a whole number (`count` of at least 1, the others of at
284
+ * least 0) or a `setup` that is not one of the frames.
285
+ */
286
+ export function readUvSequences(document: unknown): UvSequences {
287
+ const out = new Map<string, UvSequence>();
288
+ const problems: string[] = [];
289
+ const skins = isRecord(document) && Array.isArray(document.skins) ? document.skins : [];
290
+ skins.forEach((skin: unknown, k: number) => {
291
+ if (!isRecord(skin) || typeof skin.name !== 'string' || !isRecord(skin.attachments)) return;
292
+ for (const [slot, table] of Object.entries(skin.attachments)) {
293
+ if (!isRecord(table)) continue;
294
+ for (const [placeholder, record] of Object.entries(table)) {
295
+ if (!isRecord(record) || record.sequence === undefined) continue;
296
+ const where = `skins[${k}] "${skin.name}".attachments["${slot}"]["${placeholder}"].sequence`;
297
+ const seq = record.sequence;
298
+ if (!isRecord(seq)) {
299
+ problems.push(`${where} is not an object`);
300
+ continue;
301
+ }
302
+ const before = problems.length;
303
+ if (!whole(seq.count, 1)) problems.push(`${where}: count is ${JSON.stringify(seq.count) ?? 'absent'}, not a whole number of at least 1`);
304
+ for (const key of ['start', 'digits', 'setup'] as const) if (seq[key] !== undefined && !whole(seq[key], 0)) problems.push(`${where}: ${key} is ${JSON.stringify(seq[key])}, not a whole number of at least 0`);
305
+ if (problems.length !== before) continue;
306
+ const count = seq.count as number;
307
+ const setup = (seq.setup as number | undefined) ?? 0;
308
+ if (setup >= count) {
309
+ problems.push(`${where}: setup is ${setup}, and a ${count}-frame series has frames 0 to ${count - 1}`);
310
+ continue;
311
+ }
312
+ out.set(`${skin.name}/${slot}/${placeholder}`, { count, start: (seq.start as number | undefined) ?? 1, digits: (seq.digits as number | undefined) ?? 0, setup });
313
+ }
314
+ }
315
+ });
316
+ if (problems.length > 0) throw new CoreInputError(`the model document's sequences: ${problems.join('; ')}`);
317
+ return out;
318
+ }
319
+
320
+ /** What `poseUvs` reads besides the pose: the atlas lookup, the document's series, and a plant's reading. */
321
+ export interface UvSource {
322
+ lookup: UvLookup;
323
+ sequences: UvSequences;
324
+ reading?: UvReading;
325
+ }
326
+
327
+ /** One row of `uvs`: `[slot, attachment, page, uvs]`, the oracle's row. */
328
+ export type CoreUvRow = [string, string, string, Array<number | null>];
329
+
330
+ /**
331
+ * Each slot's shown record and its series' frame at the setup pose — what
332
+ * `poseSetup` hands `poseGeometry`: the setup placeholders, and the sliders
333
+ * applied to the setup bones (`applyConstraints`), each slider's attachment,
334
+ * deform and sequence keys applied in order by `attachmentStates`.
335
+ */
336
+ export function shownAtSetup(doc: CompiledDocument): { shown: ShownGeometry[]; why: string[] } {
337
+ const active = activeBones(doc);
338
+ const applied: SliderApplication[] = [];
339
+ applyConstraints(doc.bones, worldTransforms(doc.bones, active), active, constraintRecords(doc), null, applied);
340
+ const placeholders = new Map(doc.slots.map((s) => [s.name, s.setup]));
341
+ return attachmentStates(doc, shownAttachment, placeholders, null, applied);
342
+ }
343
+
344
+ /**
345
+ * Each slot's shown record and its series' frame at time `t` of `anim` — what
346
+ * `poseAnimations` hands `poseGeometry` under `--physics none`: the sliders
347
+ * `posedBoneWorld` applies at `t`, the placeholders the sample's own
348
+ * timelines leave (`posedSlots`), then `attachmentStates`.
349
+ */
350
+ export function shownAtSample(doc: CompiledDocument, anim: CoreAnimation, t: number): { shown: ShownGeometry[]; why: string[] } {
351
+ const sliders: SliderApplication[] = [];
352
+ posedBoneWorld(doc, anim.timelines, t, {}, anim.constraints, sliders);
353
+ const placeholders = new Map<string, string | null>();
354
+ posedSlots(doc, anim.timelines, t, {}, sliders, placeholders);
355
+ return attachmentStates(doc, shownAttachment, placeholders, { timelines: anim.timelines, t }, sliders);
356
+ }
357
+
358
+ /** One drawn attachment resolved to its atlas region: what `poseUvs` maps, and what a census reads. */
359
+ export interface DrawnRegion {
360
+ slot: string;
361
+ /** The attachment's name — the row's second cell. */
362
+ name: string;
363
+ kind: 'region' | 'mesh' | 'linkedmesh';
364
+ /** The region name drawn: the path, with the frame's number for a series. */
365
+ region: string;
366
+ /** The series' frame drawn, or `null` for a record with no series. */
367
+ frame: number | null;
368
+ found: { page: UvPage; region: UvRegion };
369
+ /** The attachment's own UVs for a mesh — a linked mesh's source's — or `null` for a region. */
370
+ art: readonly number[] | null;
371
+ }
372
+
373
+ /**
374
+ * Every slot of `order` showing a region, a mesh or a linked mesh, resolved to
375
+ * the atlas region it draws — the header's *Which region, on which page* — or
376
+ * why the pose is not posed. A region the atlas lacks is refused by name.
377
+ */
378
+ export function drawnRegions(doc: CompiledDocument, shown: readonly ShownGeometry[], order: readonly string[], source: UvSource): { drawn: DrawnRegion[] | null; why: string | null } {
379
+ const bySlot = new Map(shown.map((s) => [s.slot, s]));
380
+ const drawn: DrawnRegion[] = [];
381
+ const unmeasured: string[] = [];
382
+ for (const slot of order) {
383
+ const s = bySlot.get(slot);
384
+ if (s === undefined) continue;
385
+ const g = s.geometry;
386
+ if (g.kind !== 'region' && g.kind !== 'mesh' && g.kind !== 'linkedmesh') continue;
387
+ const record = doc.skins.find((k) => k.name === s.skin)?.attachments[s.slot]?.[s.placeholder];
388
+ if (record === undefined) throw new CoreInputError(`slot "${s.slot}": skin "${s.skin}" files no record under placeholder "${s.placeholder}" (readModel refuses it first)`);
389
+ const path = record.path ?? s.name;
390
+ const sequence = source.sequences.get(`${s.skin}/${s.slot}/${s.placeholder}`);
391
+ if (g.kind === 'linkedmesh' && sequence !== undefined && s.frame !== undefined) {
392
+ const sourceCount = doc.skins.find((k) => k.name === g.skin)?.attachments[g.slot]?.[g.source]?.sequenceCount;
393
+ if (sourceCount !== sequence.count) {
394
+ unmeasured.push(`slot "${s.slot}" shows linked mesh "${s.name}", whose own ${sequence.count}-frame series a sequence timeline steps over its source's ${sourceCount ?? 'unstated'} frame(s)`);
395
+ continue;
396
+ }
397
+ }
398
+ const frame = sequence === undefined ? null : (s.frame ?? sequence.setup);
399
+ const name = sequence === undefined || frame === null ? path : frameRegionName(path, sequence, frame);
400
+ const found = source.lookup(name);
401
+ if (found === null) {
402
+ throw new CoreInputError(
403
+ `slot "${s.slot}" shows "${s.name}", which draws atlas region "${name}"${frame === null ? '' : ` (frame ${frame} of its series over "${path}")`}, and the atlas has no region of that name — spine-core refuses to load the pair ("Region not found in atlas")`,
404
+ );
405
+ }
406
+ let art: readonly number[] | null = null;
407
+ if (g.kind === 'mesh') art = g.uvs;
408
+ else if (g.kind === 'linkedmesh') {
409
+ // A linked mesh draws its source's UVs over its own region (the header's *Which region*).
410
+ const from = doc.skins.find((k) => k.name === g.skin)?.attachments[g.slot]?.[g.source]?.geometry;
411
+ if (from?.kind !== 'mesh') throw new CoreInputError(`slot "${s.slot}": the linked mesh's source "${g.source}" carries no uvs (readModel refuses it first)`);
412
+ art = from.uvs;
413
+ }
414
+ drawn.push({ slot: s.slot, name: s.name, kind: g.kind, region: name, frame, found, art });
415
+ }
416
+ if (unmeasured.length > 0) return { drawn: null, why: `${unmeasured.join('; ')} — which of the two counts the runtime steps it over was not measured` };
417
+ return { drawn, why: null };
418
+ }
419
+
420
+ /**
421
+ * The `uvs` rows of one pose: `shown` (from `shownAtSetup`/`shownAtSample`) in
422
+ * `order`, the pose's draw order, every number through `round` (the oracle's,
423
+ * `gridRound`) — or why the block is left out. A region the atlas lacks is
424
+ * refused by name.
425
+ */
426
+ export function poseUvs(doc: CompiledDocument, shown: readonly ShownGeometry[], order: readonly string[], source: UvSource, round: (v: number) => number | null): { rows: CoreUvRow[] | null; why: string | null } {
427
+ const reading = source.reading ?? {};
428
+ const { drawn, why } = drawnRegions(doc, shown, order, source);
429
+ if (drawn === null) return { rows: null, why };
430
+ const rows = drawn.map((d): CoreUvRow => {
431
+ const uvs = d.art === null ? regionPageUvs(d.found.region, d.found.page, reading) : meshPageUvs(d.found.region, d.found.page, d.art, reading);
432
+ return [d.slot, d.name, d.found.page.name, uvs.map(round)];
433
+ });
434
+ return { rows, why: null };
435
+ }
436
+
437
+ /** Why a document's `uvs` blocks are not posed under the stepped phase, or null: a slider keying a slot's attachment or a series — its time is read off bones the step moves, and this walk poses them unstepped. */
438
+ export function steppedUvsWhy(doc: CompiledDocument): string | null {
439
+ const keyed = doc.constraints.flatMap((c) => {
440
+ if (c.kind !== 'slider') return [];
441
+ const anim = doc.animations.find((a) => a.name === c.animation);
442
+ if (anim === undefined) return [];
443
+ const switches = anim.timelines.slots.some((sl) => sl.timelines.some((tl) => tl.kind === 'attachment'));
444
+ const frames = anim.timelines.attachments.some((a) => a.sequence !== null);
445
+ return switches || frames ? [`slider "${c.name}" applies animation "${c.animation}", which keys ${switches ? 'a slot\'s attachment' : 'a sequence'}`] : [];
446
+ });
447
+ return keyed.length === 0 ? null : `${keyed.join('; ')} — under --physics step its time is read off stepped bones, and the uvs walk poses the sliders unstepped`;
448
+ }