@rig-c/core 2.84.0 → 2.85.0

package/docs/AUTHORING.md

@@ -12792,6 +12792,57 @@ for `declared` and the run says so on a line of its own.
 - **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`).
 
+### Texture scale — warning-only region reading
+
+```bash
+rigc texture-scale --candidate build/ --json texture-scale.json
+```
+
+`REGION_TEXTURE_MINIFIED` names each drawn region attachment whose **smallest
+sampled draw scale is below 0.5 world units per stored texture pixel**, with its
+slot, attachment, atlas region/page/index, stored texture width and height, and
+the animation and time of that sample (`animation: null`, `time: 0` for setup).
+The strict threshold applies to the measured value: a nominal authored 0.5 can
+read just below 0.5 after runtime transforms and floating-point storage.
+It is a warning, never an assertion or a build refusal. This separate reading
+changes no build, atlas or rendered frame. Scale 1.0 and exactly 0.5 stay silent.
+
+The scale is the smallest singular value of the texture-pixel → world 2×2
+map read from posed region corners and their page UVs. It includes attachment
+size/scale, parent transforms, constraints, rotation, reflection, anisotropy,
+shear, trimming and atlas rotation. Raw bone scale alone cannot give this value.
+The consumer's camera, device pixels and viewport scaling are outside it.
+
+Setup is always read, then every animation under `--skin <name>` (without it,
+no skin is set). `--fps <n>` defaults to 60. The sorted sample schedule combines
+that grid, each timeline's float32 key times, key-interval midpoints and the
+animation endpoint. Physics is stepped along this schedule, using the render
+clock. The JSON (`rigc-texture-scale/1`) records the exact schedule, threshold,
+rate, skin, count of distinct drawn region attachments and `warnings`.
+`--json` must be outside the candidate directory (symlinks are resolved). An
+existing file is replaced only when it is already a `rigc-texture-scale/1`
+report; a source artifact is refused before posing and left byte-identical.
+Text and JSON report the **minimum among these samples**, not a continuous
+minimum: interpolated transforms, shear and constraints can reach narrower
+extrema between them. Increase the rate to investigate; silence is not proof
+that no unsampled extreme exists. A tie keeps the first observation, setup first.
+
+Only selected, active region attachments with positive combined alpha,
+nonempty clipped geometry and a source rectangle containing alpha are read.
+Meshes, unselected attachments, alpha-zero regions and wholly clipped regions
+are excluded. This is a geometric draw reading; it does not test occlusion by
+later slots or whether the visible clipped portion samples only transparent
+texels. The threshold identifies potential minification without mipmaps; it
+does not assert visible dither for every source texture.
+
+**Remedies:** area-downsample the source texture and preserve the region's world
+width and height (and its placement) when rebuilding, or enable mipmaps in the
+consumer. For example, a 730×400 texture drawn at 0.167 can be area-downsampled
+to 122×67 while retaining world dimensions 121.91×66.8; the new draw scale is
+about 1.0. This removes high-frequency aliasing in the planted fixture, not a
+guarantee about arbitrary artwork or every consumer filter. rigc never resizes
+art automatically and this reading changes no atlas mipmap settings.
+
 ## 14. Read a named mesh at setup
 
 `rig-c/core` promises `readSetupMesh(view, target)` and the types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.84.0",
+  "version": "2.85.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/cli/core_commands.ts

@@ -1,3 +1,4 @@
+import { textureScaleReading, textureScaleLines, TEXTURE_SCALE_FPS } from '../texture_scale.ts';
 import { extremesOf, extremesText, extremesPlate, extremesLine, extremesRefusal } from '../extremes.ts';
 /**
  * The bodies of the commands that reach nothing of spine-core — `explain`,
@@ -53,7 +54,7 @@ import { writeWhole } from './write_whole.ts';
 import { GUIDE_FILE, GUIDE_RULE_TABLES_ELSEWHERE, guideAnswer, refusalLine } from '../guide.ts';
 import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, printAlphaClips, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPageEdges, readPoserFlag, readSheetFormat, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 
@@ -1254,6 +1255,40 @@ export function physicsLine(stepped: readonly string[], declared: readonly strin
   return `${head} — ${idle.length} of the ${declared.length} declared took none: ${idle.map((n) => JSON.stringify(n)).join(', ')} (${why})`;
 }
 
+/** Warning-only reading, independent of build and of raster output. */
+export function cmdTextureScale(flags: Record<string, string>): void {
+  const accepted = ['candidate', 'atlas', 'skin', 'fps', 'poser', 'json', 'help'];
+  const stray = Object.keys(flags).filter(k => !accepted.includes(k));
+  if (stray.length > 0) throw new UsageError(`texture-scale takes no --${stray.join(', --')}; use texture-scale --help`);
+  if (flags.candidate === undefined) throw new UsageError('texture-scale needs --candidate <dir | skeleton.json>');
+  const fps = readPositiveNumber(flags, 'fps', TEXTURE_SCALE_FPS, 1);
+  const { skeletonPath, atlasPath, atlasText } = resolveDrawable(flags.candidate, flags.atlas);
+  if (flags.json !== undefined) {
+    const target = realpathAhead(flags.json);
+    const within = relative(realpathSync(dirname(skeletonPath)), target);
+    if (within === '' || (within !== '..' && !within.startsWith(`..${sep}`) && !isAbsolute(within))) {
+      throw new UsageError('--json must name a report outside the candidate directory; texture-scale never writes into a build');
+    }
+    if (existsSync(target)) {
+      let isReport = false;
+      if (statSync(target).isFile()) {
+        try { isReport = (JSON.parse(readFileSync(target, 'utf8')) as { spec?: unknown }).spec === 'rigc-texture-scale/1'; } catch { /* An existing non-report is never replaced. */ }
+      }
+      if (!isReport) throw new UsageError('--json target exists and is not a rigc-texture-scale/1 report; name a new file outside the candidate directory');
+    }
+  }
+  const skeletonText = readSkeletonText(skeletonPath);
+  const candidate = loadCandidate({ skeletonText, atlasText, atlasDir: dirname(atlasPath), label: skeletonPath },
+    { skeleton: skeletonPath, atlas: atlasPath }, posersAsked(flags));
+  readPoserFlag(flags);
+  const skin = readSkinFlag(flags, [...candidate.facts.skins]);
+  refuseUnchosen(candidate.choice);
+  const read = throughPoser(candidate.choice, poser => textureScaleReading(poser, candidate.pages, skeletonText, fps, skin));
+  console.log(`poser: ${read.note}`);
+  for (const line of textureScaleLines(read.value.report)) console.log(line);
+  if (flags.json !== undefined) writeJson(flags.json, read.value.report);
+}
+
 /** Where `inspect` writes when `--out` is not given, and the name it takes inside a directory `--out` names. */
 export const DEFAULT_INSPECT_OUT = 'inspect.png';
 
@@ -2679,6 +2714,7 @@ export const CORE_COMMAND_RUNS: Readonly<Record<string, CommandRun>> = {
   check: ({ flags }) => cmdCheck(flags),
   render: ({ flags }) => cmdRender(flags),
   inspect: ({ flags }) => cmdInspect(flags),
+  'texture-scale': ({ flags }) => cmdTextureScale(flags),
   pose: ({ flags }) => cmdPose(flags),
   chainfit: ({ flags }) => cmdChainFit(flags),
   guide: ({ flags, positional }) => cmdGuide(flags, positional),

package/src/cli/shared.ts

@@ -1800,6 +1800,18 @@ export const COMMANDS: CommandDoc[] = [
       },
     },
   },
+  {
+    name: 'texture-scale',
+    runtime: false,
+    spineFormat: false,
+    usage: ['rigc texture-scale --candidate <dir | skeleton.json> [--skin <name>] [--fps 60] [--poser core|spine] [--json <out>]'],
+    flags: ['candidate', 'atlas', 'skin', 'fps', 'poser', 'json'],
+    overrides: {
+      fps: { meaning: 'sample setup and every animation at this rate (default 60), also including float32 key times, key-interval midpoints and endpoints; reports sampled minima, never continuous extrema' },
+      json: { meaning: 'write the report outside the candidate directory; an existing file is replaced only if it is a rigc-texture-scale/1 report' },
+    },
+    notes: ['REGION_TEXTURE_MINIFIED is a warning only: smallest singular value of texture-pixel to world map < 0.5. Names the region, texture size and sampled minimum with animation/time. Skips unselected, transparent and fully clipped regions; no occlusion or consumer camera test. Never changes a build. See docs/AUTHORING.md, Texture scale.'],
+  },
   {
     name: 'inspect',
     runtime: false,

package/src/render.ts

@@ -503,7 +503,7 @@ export function spinePoser(data: SkeletonData): Poser {
     slots: data.slots.map((slot) => ({ name: slot.name, bone: slot.boneData.name })),
     subset: (opts, skin) => slotSubsetOf(data, opts, skin),
     setup: (skin) => spinePosed(setupPosed(data, skin)),
-    animation: (name, skin, fps, count, visit, environment) => {
+    animation: (name, skin, fps, count, visit, environment, _channels, times) => {
       const skeleton = skeletonUnderSkin(data, skin);
       const state = new AnimationState(new AnimationStateData(data));
       // Not looping: the last frame sits at the animation's duration, and a looping
@@ -516,10 +516,11 @@ export function spinePoser(data: SkeletonData): Poser {
       const posed = spinePosed(skeleton);
       for (let i = 0; i <= count; i++) {
         if (i > 0) {
-          state.update(step);
+          const delta = times === undefined ? step : times[i] - times[i - 1];
+          state.update(delta);
           state.apply(skeleton);
           setSkeletonEnvironment(skeleton, environment?.(i));
-          skeleton.update(clock);
+          skeleton.update(times === undefined ? clock : physicsClockStep(delta));
           skeleton.updateWorldTransform(Physics.update);
         } else {
           state.apply(skeleton);
@@ -723,7 +724,7 @@ function drawPieces(skeleton: Skeleton, draw: DrawOptions): Piece[] {
       continue;
     }
     const drawn = subset === undefined || named === undefined || named.has(slot.data.name) === (subset.mode === 'slots');
-    const piece = drawn ? pieceOf(skeleton, slot, draw.texture, clipper) : null;
+    const piece = drawn ? pieceOf(skeleton, slot, draw.texture, clipper, draw.regionInfo) : null;
     if (piece !== null) pieces.push(piece);
     clipper?.clipEnd(slot);
   }
@@ -743,6 +744,7 @@ function pieceOf(
   slot: Slot,
   withTexture: boolean,
   clipper: SkeletonClipping | null,
+  withRegionInfo = false,
 ): Piece | null {
   const pose = slot.appliedPose;
   const attachment = pose.attachment;
@@ -765,7 +767,9 @@ function pieceOf(
   const darkPose = pose.darkColor;
   const dark: [number, number, number] | undefined =
     darkPose === null ? undefined : [darkPose.r, darkPose.g, darkPose.b];
-  const common = { tint, dark, slot: slot.data.name, page: region.page.name };
+  const common = { tint, dark, slot: slot.data.name, page: region.page.name,
+    ...(withRegionInfo && !isMesh ? { regionInfo: { attachment: attachment.name, region: region.name, index: region.index, width: region.width, height: region.height } } : {}),
+  };
   const texture = withTexture ? artUvsOf(attachment, region) : undefined;
   const uvs = attachment.sequence.getUVs(index);
 

package/src/render_core.ts

@@ -557,7 +557,9 @@ function pieces(
     const atlasRegion = draw.texture ? input.region(found.region) : null;
     if (draw.texture && atlasRegion === null) throw new CoreInputError(`slot "${d.slot}": atlas region "${found.region}" is not in the atlas`);
     const texture = atlasRegion === null ? undefined : artUvsOf(d, atlasRegion);
-    const common = { tint: tintOf(d), dark: darkOf(d), slot: d.slot, page: found.found.page.name };
+    const common = { tint: tintOf(d), dark: darkOf(d), slot: d.slot, page: found.found.page.name,
+      ...(draw.regionInfo && d.kind === 'region' ? { regionInfo: { attachment: d.attachment, region: found.region, index: input.region(found.region)?.index ?? -1, width: found.found.region.width, height: found.found.region.height } } : {}),
+    };
     const world = [...d.vertices];
     const piece: Piece =
       d.kind === 'mesh'
@@ -782,7 +784,7 @@ export function corePoser(
       const pose = poseRawSetup(input.doc, { through, ...observe });
       return corePosed(input, pose, through, [], values);
     },
-    animation: (name, skin, fps, count, visit, environment, channels) => {
+    animation: (name, skin, fps, count, visit, environment, channels, times) => {
       let values: ChannelValue[] | undefined;
       const observe = channels ? { readLocals: (bones: readonly import('./model.ts').ModelBone[], sliders: readonly import('./core/constraints_slider.ts').SliderApplication[]) => { values = localChannels(bones, sliders); } } : {};
       const input = inputOf(skin);
@@ -802,7 +804,7 @@ export function corePoser(
         if (ctx.time > 0 && ctx.states.get(r.name)?.lastTime === ctx.time) steppedNow.add(r.name);
         return moved;
       };
-      walk(input.doc, name, new Array<number>(count).fill(step), { through, physicsStep, ...observe }, (pose, i) => {
+      walk(input.doc, name, times === undefined ? new Array<number>(count).fill(step) : times.slice(1).map((t, i) => t - times[i]), { through, physicsStep, ...observe }, (pose, i) => {
         const stepped = [...steppedNow].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
         steppedNow.clear();
         if (drawFailed.length > 0) return;

package/src/render_shared.ts

@@ -324,6 +324,8 @@ export interface PinnedViewport {
 
 /** What every drawable has in common, whatever shape it is. */
 export interface PieceCommon {
+  /** Opt-in atlas identity for texture-scale; absent on ordinary renders. */
+  regionInfo?: { attachment: string; region: string; index: number; width: number; height: number };
   /**
    * World-space vertex positions, `x, y` per vertex.
    *
@@ -1101,6 +1103,8 @@ function coreFacts(skeletonText: string, atlasText: string | null, poser: Poser,
 
 /** What a sampler hands a posed frame's draw walk — `PoseOptions` with the subset already resolved. */
 export interface DrawOptions {
+  /** Texture-scale only: atlas identity and stored texture size on whole regions. */
+  regionInfo?: boolean;
   /** The slots drawn, resolved against the posed skeleton (`slotSubsetOf`); `undefined` draws every slot. */
   subset: SlotSubset | undefined;
   /** Every attachment whole, no clip applied — the framing box's reading. */
@@ -1159,8 +1163,11 @@ export interface Poser {
    * `i` from 0 to `count`, the pose at `i/fps`. The caller has checked `name`.
    * `environment(i)`, when given, is the change to the world the physics
    * answers set before the step that poses frame `i` (issue #1416).
+   * Optional `times` replaces the uniform grid with increasing absolute times
+   * starting at 0 (count = times.length - 1), stepped by adjacent differences.
+   * Used by texture-scale to include key times; ordinary renders are unchanged.
    */
-  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined, channels?: boolean): void;
+  animation(name: string, skin: string | undefined, fps: number, count: number, visit: (index: number, posed: Posed) => void, environment?: (index: number) => EnvironmentChange | undefined, channels?: boolean, times?: readonly number[]): void;
   /** The rest table for the (slot, attachment) pairs `shown` holds — see `AttachmentRest`. */
   rest(skin: string | undefined, shown: readonly AttachmentPose[][]): AttachmentRest[];
 }

package/src/texture_scale.ts

@@ -0,0 +1,153 @@
+/** Warning-only region minification, in world units per stored texture pixel. */
+import type { Piece, Poser, Posed } from './render_shared.ts';
+import type { Plate } from '../tools/plate.ts';
+import { walkTimelines } from './timelines.ts';
+import { hypot2 } from './numeric.ts';
+
+export const TEXTURE_SCALE_WARNING = 'REGION_TEXTURE_MINIFIED';
+export const TEXTURE_SCALE_THRESHOLD = 0.5;
+export const TEXTURE_SCALE_FPS = 60;
+export const TEXTURE_SCALE_LIMIT =
+  'Minimum among sampled poses only: grid + float32 key times + key-interval midpoints + endpoint; ' +
+  'interpolated scale/shear/constraints can have smaller extrema between samples. ' +
+  'World units per texture pixel, before consumer camera/viewport; no occlusion test.';
+
+export interface RegionScale {
+  slot: string;
+  attachment: string;
+  region: string;
+  index: number;
+  page: string;
+  texture: { width: number; height: number };
+  smallestSampledScale: number;
+  animation: string | null;
+  time: number;
+}
+export interface TextureScaleReport {
+  spec: 'rigc-texture-scale/1';
+  threshold: number;
+  fps: number;
+  skin: string | null;
+  sampling: string;
+  samples: Array<{ animation: string | null; times: number[] }>;
+  drawnRegions: number;
+  warnings: Array<RegionScale & { name: typeof TEXTURE_SCALE_WARNING }>;
+}
+
+/** Stable 2x2 sigma-min: |det| / sigma-max avoids subtracting nearly equal eigenvalues. */
+export function smallestSingularValue(a: number, b: number, c: number, d: number): number {
+  const scale = Math.max(Math.abs(a), Math.abs(b), Math.abs(c), Math.abs(d));
+  if (scale === 0) return 0;
+  a /= scale; b /= scale; c /= scale; d /= scale;
+  const sum = a * a + b * b + c * c + d * d;
+  const disc = hypot2(a * a + c * c - b * b - d * d, 2 * (a * b + c * d));
+  return scale * Math.abs(a * d - b * c) / Math.sqrt((sum + disc) / 2);
+}
+
+/** Texel-space affine map from three corresponding quad corners; includes trim, rotation, reflection and shear. */
+export function regionDrawScale(piece: Piece, page: Pick<Plate, 'width' | 'height'>): number {
+  const [x0, y0, x1, y1, x2, y2] = piece.world;
+  const u0 = piece.uvs[0] * page.width, v0 = piece.uvs[1] * page.height;
+  const u1 = piece.uvs[2] * page.width - u0, v1 = piece.uvs[3] * page.height - v0;
+  const u2 = piece.uvs[4] * page.width - u0, v2 = piece.uvs[5] * page.height - v0;
+  const det = u1 * v2 - u2 * v1;
+  if (det === 0) throw new Error(`slot ${JSON.stringify(piece.slot)}: region has a singular texture rectangle`);
+  return smallestSingularValue(
+    ((x1 - x0) * v2 - (x2 - x0) * v1) / det,
+    ((x2 - x0) * u1 - (x1 - x0) * u2) / det,
+    ((y1 - y0) * v2 - (y2 - y0) * v1) / det,
+    ((y2 - y0) * u1 - (y1 - y0) * u2) / det,
+  );
+}
+
+/** A schedule, not an extrema solver. Key times use the same float32 storage as the poser. */
+export function textureScaleTimes(skeletonText: string, animation: string, duration: number, fps: number): number[] {
+  if (!Number.isFinite(fps) || fps < 1) throw new Error(`texture-scale fps ${fps}: expected a finite number >= 1`);
+  const root = JSON.parse(skeletonText) as { animations?: Record<string, unknown> };
+  const keys = new Set<number>([0, duration]);
+  walkTimelines({ animations: { [animation]: root.animations?.[animation] } }, (_p, _k, _n, rows) => {
+    for (const row of rows) {
+      const t = Math.fround((row as { time?: number }).time ?? 0);
+      if (Number.isFinite(t) && t >= 0 && t <= duration) keys.add(t);
+    }
+  });
+  const sorted = [...keys].sort((a, b) => a - b);
+  const times = new Set(sorted);
+  for (let i = 1; i < sorted.length; i++) times.add((sorted[i - 1] + sorted[i]) / 2);
+  for (let i = 0; i / fps < duration; i++) times.add(i / fps);
+  return [...times].sort((a, b) => a - b);
+}
+
+/** Has a submitted triangle of positive area; fully clipped or collapsed geometry draws nothing. */
+function hasArea(p: Piece): boolean {
+  const ts = p.kind === 'region' ? [0, 1, 2, 2, 3, 0] : p.triangles;
+  for (let i = 0; i < ts.length; i += 3) {
+    const a = ts[i] * 2, b = ts[i + 1] * 2, c = ts[i + 2] * 2;
+    if (Math.abs((p.world[b] - p.world[a]) * (p.world[c + 1] - p.world[a + 1]) -
+      (p.world[b + 1] - p.world[a + 1]) * (p.world[c] - p.world[a])) > 0) return true;
+  }
+  return false;
+}
+
+/** Excludes wholly transparent source rectangles; no per-frame raster or screen-space occlusion claim. */
+function hasAlpha(piece: Piece, page: Plate): boolean {
+  const us = [0, 2, 4, 6].map(i => piece.uvs[i] * page.width);
+  const vs = [1, 3, 5, 7].map(i => piece.uvs[i] * page.height);
+  const x0 = Math.max(0, Math.round(Math.min(...us))), x1 = Math.min(page.width, Math.round(Math.max(...us)));
+  const y0 = Math.max(0, Math.round(Math.min(...vs))), y1 = Math.min(page.height, Math.round(Math.max(...vs)));
+  for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) if (page.data[(y * page.width + x) * 4 + 3] > 0) return true;
+  return false;
+}
+
+/** Streaming read: setup first, then animations in declaration order; ties keep the first observation. Never emits a build. */
+export function textureScaleReading(poser: Poser, pages: Map<string, Plate>, skeletonText: string, fps = TEXTURE_SCALE_FPS, skin?: string): { report: TextureScaleReport; regions: RegionScale[] } {
+  if (!Number.isFinite(fps) || fps < 1) throw new Error(`texture-scale fps ${fps}: expected a finite number >= 1`);
+  const readings = new Map<string, RegionScale>();
+  const slotBones = new Map(poser.slots.map(s => [s.name, s.bone]));
+  const alpha = new Map<string, boolean>();
+  const samples: TextureScaleReport['samples'] = [{ animation: null, times: [0] }];
+  const visit = (pose: Posed, animation: string | null, time: number): void => {
+    const unposed = new Set(pose.bones().filter(b => b.a === 0 && b.b === 0 && b.c === 0 && b.d === 0).map(b => b.name));
+    const drawn = new Map(pose.pieces({ subset: undefined, unclipped: false, texture: false }).map(p => [p.slot, p]));
+    for (const whole of pose.pieces({ subset: undefined, unclipped: true, texture: false, regionInfo: true })) {
+      if (unposed.has(slotBones.get(whole.slot) ?? '')) continue;
+      if (whole.kind !== 'region' || whole.regionInfo === undefined || !(whole.tint[3] > 0)) continue;
+      const visible = drawn.get(whole.slot);
+      if (visible === undefined || !hasArea(visible)) continue;
+      const info = whole.regionInfo;
+      const page = pages.get(whole.page);
+      if (page === undefined) throw new Error(`region ${JSON.stringify(info.region)}: page ${JSON.stringify(whole.page)} is absent`);
+      const key = JSON.stringify([whole.slot, info.attachment, whole.page, info.region, info.index]);
+      const sourceAlpha = alpha.get(key) ?? hasAlpha(whole, page);
+      alpha.set(key, sourceAlpha);
+      if (!sourceAlpha) continue;
+      const scale = regionDrawScale(whole, page);
+      if (!Number.isFinite(scale)) throw new Error(`region ${JSON.stringify(info.region)} at ${animation ?? 'setup'} t=${time}: draw scale ${scale} is not finite`);
+      const old = readings.get(key);
+      if (old === undefined || scale < old.smallestSampledScale) readings.set(key, {
+        slot: whole.slot, attachment: info.attachment, region: info.region, index: info.index, page: whole.page,
+        texture: { width: info.width, height: info.height }, smallestSampledScale: scale, animation, time,
+      });
+    }
+  };
+  visit(poser.setup(skin), null, 0);
+  for (const a of poser.animations) {
+    const times = textureScaleTimes(skeletonText, a.name, a.duration, fps);
+    samples.push({ animation: a.name, times });
+    poser.animation(a.name, skin, fps, times.length - 1, (i, posed) => visit(posed, a.name, times[i]), undefined, false, times);
+  }
+  const regions = [...readings.values()];
+  return { regions, report: {
+    spec: 'rigc-texture-scale/1', threshold: TEXTURE_SCALE_THRESHOLD, fps, skin: skin ?? null, sampling: TEXTURE_SCALE_LIMIT,
+    samples, drawnRegions: regions.length,
+    warnings: regions.filter(r => r.smallestSampledScale < TEXTURE_SCALE_THRESHOLD).map(r => ({ name: TEXTURE_SCALE_WARNING, ...r })),
+  } };
+}
+
+export function textureScaleLines(report: TextureScaleReport): string[] {
+  return [
+    `texture-scale: ${report.warnings.length} warning(s) / ${report.drawnRegions} drawn region attachment(s), threshold < ${report.threshold}, ${report.fps} fps + keys/midpoints/endpoints`,
+    report.sampling,
+    ...report.warnings.map(r => `WARN ${r.name}: region ${JSON.stringify(r.region)} slot ${JSON.stringify(r.slot)} attachment ${JSON.stringify(r.attachment)} texture ${r.texture.width}x${r.texture.height}, smallest sampled draw scale ${r.smallestSampledScale.toFixed(6)} at ${r.animation === null ? 'setup' : JSON.stringify(r.animation)} t=${r.time}s`),
+  ];
+}