Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

31.8 KB
Raw Blame
/**
 * The per-track animation registry (#3015) — the rows themselves, the
 * unknown-track error boundary, the per-track clamps, and the sharp-free
 * property `server/lib/validation.js` depends on.
 *
 * The walk row is pinned to its historical values on purpose: #3015 is a
 * refactor, and a registry that quietly moved walk's floor would change every
 * render's geometry while looking like plumbing.
 *
 * **Compiled vs. effective, since #3152.** `ANIMATION_TRACKS` now holds only
 * `walk`; `scanner` and `ambient` are seeded rows in the user-defined store. So a
 * test about the SHIPPED SET of tracks resolves `EFFECTIVE` (the merge) while a
 * test about the compiled table asserts `walk` alone — and the difference is
 * itself asserted, because "walk is the only built-in" is the property #3152
 * exists to establish. The store's own behavior (merge, seed fallback, bad-row
 * rejection) lives in `animationTrackStore.test.js`.
 */

import { describe, it, expect } from 'vitest';
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import {
  WALK_TRACK, SCANNER_TRACK, AMBIENT_TRACK, ANIMATION_TRACKS,
  isAnimationTrack, getAnimationTrack, clampTrackFrameCount, clampTrackFps,
  assertAnimationTrackRows, trackRowCount, tracksForKind, kindSupportsTrack,
  sourceReferenceFor, primaryTrackForKind,
} from './spriteAnimationTracks.js';
import {
  getEffectiveAnimationTracks, getEffectiveAnimationTrackIds, animationTrackSeedPath,
} from './spriteAnimationTrackStore.js';
import { SPRITE_RECORD_KINDS } from '../services/sprites/recordsLogic.js';
import { AMBIENT_TRACK_ROW } from '../services/sprites/spriteTestFixtures.js';
import {
  staticImportSpecifiers, staticImportClosure, specifierMatchesPackage,
} from './staticImportGraph.js';
import {
  WALK_DEFAULT_FRAME_COUNT as CLIENT_DEFAULT_FRAME_COUNT,
  WALK_DEFAULT_FPS as CLIENT_DEFAULT_FPS,
  WALK_FRAME_COUNT_OPTIONS as CLIENT_FRAME_COUNT_OPTIONS,
  walkFpsOptionsFor as clientWalkFpsOptionsFor,
} from '../../client/src/lib/spriteTrimmer.js';

// This suite moved to server/lib with the registry it covers (#4901), but it
// still walks modules that stayed in services/sprites — so name both roots
// explicitly rather than deriving one from the test's own location.
const LIB_DIR = dirname(fileURLToPath(import.meta.url));
const SERVER_DIR = dirname(LIB_DIR);
const SPRITES_DIR = join(SERVER_DIR, 'services', 'sprites');

// The merged table this install actually serves — compiled `walk` plus the store
// rows, which on a machine that has authored its own tracks includes those too.
// Resolved once: the store caches its read, so every call in this file sees one
// consistent table. Use this for assertions about the SHAPE of whatever rows
// exist (a hand-authored row must satisfy the same guards a seeded one does).
const EFFECTIVE = getEffectiveAnimationTracks();
const effectiveTrack = (id) => getAnimationTrack(id, EFFECTIVE);

// The table a FRESH install serves — compiled `walk` plus `data.reference`'s seed,
// with no user-authored rows. Use this for assertions that enumerate the exact
// shipped set: against EFFECTIVE they assert that the developer running the suite
// has authored no tracks of their own, which is not a property of this repo (#3152
// exists to let them). One such assertion did read EFFECTIVE and turned red the
// day a character track was added on the machine running it.
const SHIPPED = Object.freeze({
  ...ANIMATION_TRACKS,
  ...Object.fromEntries(
    (JSON.parse(readFileSync(animationTrackSeedPath(), 'utf-8')).tracks || [])
      .map((row) => [row.id, Object.freeze({ ...row, builtin: false })]),
  ),
});

describe('the registry rows', () => {
  it('reproduces the walk track\'s historical bounds and defaults exactly', () => {
    // #3015 is a refactor — walk behaves identically end to end.
    expect(getAnimationTrack(WALK_TRACK)).toMatchObject({
      id: 'walk',
      directional: true,
      // #3017 moved the gate into the registry without loosening it: a walk
      // cycle is a character gait, so `place`/`object` are still refused.
      kinds: ['character'],
      minFrameCount: 6,
      maxFrameCount: 16,
      defaultFrameCount: 12,
      minFps: 4,
      maxFps: 24,
      defaultFps: 10,
      contractFrameCountField: 'walkFrameCount',
      contractFpsField: 'walkFps',
    });
  });

  it('compiles in walk and ONLY walk (#3152)', () => {
    // The property #3152 establishes. Asserted against the compiled constant
    // specifically — `EFFECTIVE` would pass here forever, since it contains the
    // seeded rows, so a regression that re-added `scanner` to the literal would
    // slip through a merged-table assertion.
    expect(Object.keys(ANIMATION_TRACKS)).toEqual([WALK_TRACK]);
    expect(ANIMATION_TRACKS[WALK_TRACK].builtin).toBe(true);
    for (const id of [SCANNER_TRACK, AMBIENT_TRACK]) {
      expect(ANIMATION_TRACKS[id], `${id} must be a stored row, not compiled in`).toBeUndefined();
      // …and still reachable through the merge, carrying the marker that says
      // where it came from. Both halves matter: "not compiled" without "still
      // served" would be satisfied by simply deleting the track.
      expect(effectiveTrack(id).builtin, `${id} must be marked user-defined`).toBe(false);
    }
  });

  it('registers the short scanner action independently of walk', () => {
    expect(effectiveTrack(SCANNER_TRACK)).toMatchObject({
      id: SCANNER_TRACK,
      directional: true,
      kinds: ['character'],
      minFrameCount: 2,
      maxFrameCount: 8,
      defaultFrameCount: 4,
      minFps: 2,
      maxFps: 12,
      defaultFps: 6,
      contractFrameCountField: 'scannerFrameCount',
      contractFpsField: null,
    });
  });

  it('registers the single-row ambient loop for places and objects', () => {
    expect(effectiveTrack(AMBIENT_TRACK)).toMatchObject({
      id: AMBIENT_TRACK,
      label: 'Ambient loop',
      directional: false,
      kinds: ['place', 'object', 'props'],
      minFrameCount: 2,
      maxFrameCount: 6,
      defaultFrameCount: 3,
      minFps: 2,
      maxFps: 12,
      defaultFps: 4,
      contractFrameCountField: 'ambientFrameCount',
      contractFpsField: null,
    });
  });

  it('describes every declared track completely', () => {
    // Mirrors the module-load guard in animationTracks.js (which is what
    // actually blocks boot on a bad row) so a shape violation reads as a named
    // assertion here rather than only as an import-time throw somewhere else.
    // Walks the EFFECTIVE table so a malformed SEEDED row is caught here too —
    // scoping this to the compiled table would have narrowed it to one row the
    // moment #3152 landed.
    for (const id of getEffectiveAnimationTrackIds()) {
      const row = EFFECTIVE[id];
      expect(row.id, `${id}.id must match its registry key`).toBe(id);
      expect(typeof row.label).toBe('string');
      expect(typeof row.directional).toBe('boolean');
      expect(Array.isArray(row.kinds) && row.kinds.length > 0, `${id}.kinds must be non-empty`).toBe(true);
      expect(typeof row.contractFrameCountField).toBe('string');
      // `null` is legal here — a track whose speed an app has no say in — so
      // this must stay as permissive as the module-load guard, or the first row
      // that uses the null form goes red while booting perfectly fine.
      expect(row.contractFpsField === null || typeof row.contractFpsField === 'string').toBe(true);
      for (const field of ['minFrameCount', 'maxFrameCount', 'defaultFrameCount', 'minFps', 'maxFps', 'defaultFps']) {
        expect(Number.isInteger(row[field]), `${id}.${field} must be an integer`).toBe(true);
      }
      expect(row.minFrameCount).toBeLessThanOrEqual(row.maxFrameCount);
      expect(row.minFps).toBeLessThanOrEqual(row.maxFps);
      expect(row.defaultFrameCount).toBeGreaterThanOrEqual(row.minFrameCount);
      expect(row.defaultFrameCount).toBeLessThanOrEqual(row.maxFrameCount);
      expect(row.defaultFps).toBeGreaterThanOrEqual(row.minFps);
      expect(row.defaultFps).toBeLessThanOrEqual(row.maxFps);
    }
  });

  it('accepts the shipped registry', () => {
    expect(() => assertAnimationTrackRows(ANIMATION_TRACKS)).not.toThrow();
  });

  it('is frozen so a caller cannot mutate the shared bounds', () => {
    expect(() => { ANIMATION_TRACKS.walk.minFrameCount = 1; }).toThrow();
    expect(ANIMATION_TRACKS.walk.minFrameCount).toBe(6);
  });
});

describe('the module-load row guard', () => {
  // Driven against SYNTHETIC rows, not the shipped table. Asserting properties
  // of the (single-row) real registry would only re-derive the implementation:
  // the guard could be deleted outright and such a test would stay green.
  const walk = getAnimationTrack(WALK_TRACK);
  const second = {
    ...walk, id: 'scanner', label: 'Scanner', minFrameCount: 3, defaultFrameCount: 4, maxFrameCount: 8,
    contractFrameCountField: 'scannerFrameCount', contractFpsField: 'scannerFps',
    // #3136: the on-disk `kind` discriminators are per-row unique for the same
    // reason the contract fields are, so a row copy-pasted from walk's must
    // rename them too or the guard (correctly) refuses it.
    selectionKind: 'reviewed-directional-scanner-selection',
    setKind: 'finalized-eight-direction-scanner-set',
    finalErrorCode: 'SCANNER_SET_FINAL',
    // Walk is `character`'s standalone baseline, so a SECOND character track must
    // not also claim it — exactly one per record kind (asserted below).
    standaloneContract: false,
  };
  const twoRows = (overrides = {}) => ({ walk, scanner: { ...second, ...overrides } });

  it('accepts a well-formed second row', () => {
    expect(() => assertAnimationTrackRows(twoRows())).not.toThrow();
  });

  it('rejects a second row that copy-pastes walk\'s contract field', () => {
    // The regression the guard exists for: resolveAnimationTarget would read
    // the WALK's walkFrameCount for the scanner and report it frameCountLocked.
    expect(() => assertAnimationTrackRows(twoRows({ contractFrameCountField: 'walkFrameCount' })))
      .toThrow(/claimed by both 'walk\.contractFrameCountField' and 'scanner\.contractFrameCountField'/);
  });

  it('names both knobs when ONE row claims one field for both of them', () => {
    expect(() => assertAnimationTrackRows({ scanner: { ...second, contractFpsField: 'scannerFrameCount' } }))
      .toThrow(/'scanner\.contractFrameCountField' and 'scanner\.contractFpsField'/);
  });

  it('rejects a row no record kind can carry (#3017)', () => {
    // A row with no kinds is unreachable work — nothing could ever carry it,
    // and the gate would refuse every record with a message blaming the record.
    expect(() => assertAnimationTrackRows(twoRows({ kinds: [] }))).toThrow(/needs a non-empty 'kinds' array/);
    expect(() => assertAnimationTrackRows(twoRows({ kinds: 'character' }))).toThrow(/needs a non-empty 'kinds' array/);
    expect(() => assertAnimationTrackRows(twoRows({ kinds: ['character', ''] }))).toThrow(/non-string entry in 'kinds'/);
  });

  it('lets a row opt out of an fps contract field with null', () => {
    expect(() => assertAnimationTrackRows(twoRows({ contractFpsField: null }))).not.toThrow();
    // …and two such rows don't collide on "null".
    expect(() => assertAnimationTrackRows({
      walk: { ...walk, contractFpsField: null }, scanner: { ...second, contractFpsField: null },
    })).not.toThrow();
  });

  it.each([
    ['a mismatched id', { id: 'nope' }, /mismatched id/],
    ['a missing label', { label: '' }, /needs a label/],
    ['a non-boolean directional', { directional: 'yes' }, /boolean 'directional'/],
    ['a non-integer bound', { maxFrameCount: 8.5 }, /integer 'maxFrameCount'/],
    ['a default outside its range', { defaultFrameCount: 99 }, /minFrameCount <= defaultFrameCount <= maxFrameCount/],
    ['a default fps outside its range', { defaultFps: 99 }, /minFps <= defaultFps <= maxFps/],
    ['an empty contract frame-count field', { contractFrameCountField: '' }, /needs a contractFrameCountField/],
    ['an undefined contract fps field', { contractFpsField: undefined }, /contractFpsField \(or null\)/],
    // #3136 — the workflow shape the generic track service dispatches on.
    ['a missing selectionKind', { selectionKind: '' }, /needs a non-empty 'selectionKind'/],
    ['a missing setKind', { setKind: undefined }, /needs a non-empty 'setKind'/],
    ['a missing finalErrorCode', { finalErrorCode: '' }, /needs a non-empty 'finalErrorCode'/],
    ['a non-boolean standaloneContract', { standaloneContract: 'yes' }, /boolean 'standaloneContract'/],
    ['a non-boolean builtin', { builtin: 'yes' }, /boolean 'builtin'/],
    // #3152 — exactly ONE prompt source per row, asserted in BOTH directions. The
    // second case is the one a provenance-shaped guard misses: a builtin row that
    // also carries a template has two definitions of its wording, and the stored one
    // silently wins over the text `prompts.test.js` pins.
    ['a stored row with no promptTemplate', { builtin: false }, /needs a non-empty 'promptTemplate'/],
    ['a stored row with a blank promptTemplate', { builtin: false, promptTemplate: '   ' }, /needs a non-empty 'promptTemplate'/],
    ['a builtin row carrying a promptTemplate', { promptTemplate: 'Animate it.' }, /must not carry a 'promptTemplate'/],
  ])('rejects %s', (_label, overrides, message) => {
    expect(() => assertAnimationTrackRows(twoRows(overrides))).toThrow(message);
  });

  it('requires exactly one standaloneContract track per record kind (#3136)', () => {
    // Zero means a record of that kind can be authored but never published: the
    // publish contract would require no field and the compiler would have no
    // evidence chain to demand. Two means "which set must be finalized before
    // compiling?" has two answers — and the publish schema would accept either
    // track's frame count alone as describing the atlas.
    expect(() => assertAnimationTrackRows(twoRows({ standaloneContract: true })))
      .toThrow(/record kind 'character' needs exactly one standaloneContract track, has 2 \(walk, scanner\)/);
    expect(() => assertAnimationTrackRows({
      walk: { ...walk, standaloneContract: false }, scanner: second,
    })).toThrow(/record kind 'character' needs exactly one standaloneContract track, has 0/);
  });

  it('rejects a second row that copy-pastes walk\'s on-disk set kind (#3136)', () => {
    // The mirror of the contract-field collision, one layer down: the atlas
    // compiler validates a finalized set by its `kind`, so two tracks sharing
    // one would let this track's set satisfy the OTHER's evidence check and
    // compile the wrong frames into its span.
    expect(() => assertAnimationTrackRows(twoRows({ setKind: 'finalized-eight-direction-walk-set' })))
      .toThrow(/claimed by both 'walk\.setKind' and 'scanner\.setKind'/);
    expect(() => assertAnimationTrackRows(twoRows({ selectionKind: 'reviewed-directional-walk-selection' })))
      .toThrow(/claimed by both 'walk\.selectionKind' and 'scanner\.selectionKind'/);
  });

});

describe('registry-derived source reference and primacy (#3136)', () => {
  it('derives the seeding reference from directionality, never declaring it', () => {
    // Only one pairing can work, which is why this is derived rather than a row
    // field: a directional track seeded from the single `main` would render the
    // SAME south-facing clip for all eight facings and pass every later check
    // (nothing downstream re-reads which facing was asked for), and a
    // non-directional one has no anchor to read at all — a place record never
    // generates directional anchors.
    expect(sourceReferenceFor(WALK_TRACK)).toBe('anchor');
    // SHIPPED, not EFFECTIVE — these name the seed's own flags, and the seed's
    // `_comment` says every row in it may be retuned or deleted. Read from the
    // live table, an operator deleting `scanner` (a supported edit) reds a test
    // about the shipped contract that they never touched.
    expect(sourceReferenceFor(SCANNER_TRACK, SHIPPED)).toBe('anchor');
    expect(sourceReferenceFor(AMBIENT_TRACK, SHIPPED)).toBe('main');
    // Reads the row it's HANDED, not the shipped table.
    expect(sourceReferenceFor('ambient', { ambient: AMBIENT_TRACK_ROW })).toBe('main');
    expect(() => sourceReferenceFor('unknown')).toThrow(/Unknown animation track/);
  });

  it('answers which track a record kind publishes off', () => {
    // ONE definition, shared by the publish-contract schema (which field is
    // required) and the compile dispatch (which evidence chain to validate).
    expect(primaryTrackForKind('character', SHIPPED)?.id).toBe(WALK_TRACK);
    expect(primaryTrackForKind('place', SHIPPED)?.id).toBe(AMBIENT_TRACK);
    expect(primaryTrackForKind('object', SHIPPED)?.id).toBe(AMBIENT_TRACK);
    expect(primaryTrackForKind('props', SHIPPED)?.id).toBe(AMBIENT_TRACK);
    // A short action a record can't publish off alone is never the primary.
    expect(primaryTrackForKind('character', SHIPPED)?.id).not.toBe(SCANNER_TRACK);
    // Absent/unknown answers null rather than defaulting to a kind.
    expect(primaryTrackForKind('nope', SHIPPED)).toBeNull();
    expect(primaryTrackForKind('', SHIPPED)).toBeNull();
    expect(primaryTrackForKind(undefined, SHIPPED)).toBeNull();
  });
});

describe('getAnimationTrack — absent vs unrecognized', () => {
  it('treats an absent id as the default track, preserving pre-#3015 call sites', () => {
    expect(getAnimationTrack().id).toBe(WALK_TRACK);
    expect(getAnimationTrack(undefined).id).toBe(WALK_TRACK);
    expect(getAnimationTrack(null).id).toBe(WALK_TRACK);
  });

  it('keeps unknown ids distinct from the shipped scanner track', () => {
    // The sentinel rule: "not set" resolves to the default; "set to something
    // this build does not know" is an error. Silently handing back walk's 6–16
    // would reject a legitimate 4-frame action for reasons nothing explains.
    expect(effectiveTrack(SCANNER_TRACK).id).toBe(SCANNER_TRACK);
    expect(() => getAnimationTrack('unknown')).toThrow(/Unknown animation track 'unknown'/);
  });

  it('treats an empty string as present-and-invalid, not absent', () => {
    expect(() => getAnimationTrack('')).toThrow(/Unknown animation track/);
  });

  it('rejects a non-string id and inherited Object keys', () => {
    expect(isAnimationTrack('toString')).toBe(false);
    expect(isAnimationTrack(7)).toBe(false);
    expect(() => getAnimationTrack('toString')).toThrow(/Unknown animation track/);
  });
});

describe('directionality and record-kind support (#3017)', () => {
  // `AMBIENT_TRACK_ROW` is a synthetic NON-directional row admitting the two
  // kinds that had no animation path at all. The shipped registry's only track
  // is directional and character-only, so a test written against it alone could
  // not tell "reads the row" from "hardcodes 8 / hardcodes 'character'" — the
  // same injected-table idiom the guard tests above use.
  const walk = getAnimationTrack(WALK_TRACK);
  const MIXED = { walk, ambient: AMBIENT_TRACK_ROW };

  it('accepts a well-formed non-directional row', () => {
    expect(() => assertAnimationTrackRows(MIXED)).not.toThrow();
  });

  it('turns directionality into a row count, scaled to the grid it is asked about', () => {
    expect(trackRowCount('walk', 8, MIXED)).toBe(8);
    expect(trackRowCount('walk', 4, MIXED)).toBe(4);
    // A track with no facing is ONE row whatever the grid height — that single
    // row is row 0, and the rest of its column span stays transparent.
    expect(trackRowCount('ambient', 8, MIXED)).toBe(1);
    expect(trackRowCount('ambient', 4, MIXED)).toBe(1);
  });

  it('refuses an unusable direction count rather than returning NaN rows', () => {
    expect(() => trackRowCount('walk', 0, MIXED)).toThrow(/positive direction count/);
    expect(() => trackRowCount('walk', 2.5, MIXED)).toThrow(/positive direction count/);
    // Unknown ids stay getAnimationTrack's boundary.
    expect(() => trackRowCount('nope', 8, MIXED)).toThrow(/Unknown animation track 'nope'/);
  });

  it('answers which tracks a record kind may carry — the whole track-presence gate', () => {
    expect(tracksForKind('character', MIXED).map((r) => r.id)).toEqual(['walk']);
    expect(tracksForKind('place', MIXED).map((r) => r.id)).toEqual(['ambient']);
    expect(tracksForKind('object', MIXED).map((r) => r.id)).toEqual(['ambient']);
    // The gate's negative case: a kind no row lists has no animation path.
    expect(tracksForKind('props', MIXED)).toEqual([]);
    // A malformed record must not inherit character's permissions by default.
    expect(tracksForKind('', MIXED)).toEqual([]);
    expect(tracksForKind(undefined, MIXED)).toEqual([]);
    expect(tracksForKind(null, MIXED)).toEqual([]);
  });

  it('reports per-track support, refusing an unknown track rather than throwing', () => {
    expect(kindSupportsTrack('character', 'walk', MIXED)).toBe(true);
    expect(kindSupportsTrack('place', 'walk', MIXED)).toBe(false);
    expect(kindSupportsTrack('place', 'ambient', MIXED)).toBe(true);
    // A predicate is the wrong place to throw — the gates use it to DECIDE.
    expect(kindSupportsTrack('character', 'nope', MIXED)).toBe(false);
  });

  it('admits ambient loops for non-character sprite kinds', () => {
    // SHIPPED, not EFFECTIVE: this names the exact set a fresh install carries,
    // so a track the developer authored locally must not appear in it.
    expect(tracksForKind('character', SHIPPED).map((r) => r.id)).toEqual([WALK_TRACK, SCANNER_TRACK]);
    for (const kind of ['place', 'object', 'props']) {
      expect(tracksForKind(kind, SHIPPED).map((r) => r.id), `${kind} carries the ambient loop`).toEqual([AMBIENT_TRACK]);
    }
  });

  it('spells every `kinds` entry from the real record vocabulary', () => {
    // The module-load guard can only check that `kinds` holds non-empty
    // strings, because animationTracks.js imports nothing (asserted below) and
    // the vocabulary lives in recordsLogic.js. So `kinds: ['charcter']` passes
    // every guard, makes the track uncarryable by anything, and surfaces only
    // as the baffling "No animation track applies to character records".
    // Cross-checked here, where reaching another module is fine — the same
    // place the client-mirror parity check lives.
    for (const id of getEffectiveAnimationTrackIds()) {
      for (const kind of EFFECTIVE[id].kinds) {
        expect(SPRITE_RECORD_KINDS, `${id}.kinds names an unknown record kind '${kind}'`).toContain(kind);
      }
    }
  });
});

describe('per-track clamps', () => {
  it('clamps into the named track\'s range and rounds', () => {
    expect(clampTrackFrameCount(2, WALK_TRACK)).toBe(6);
    expect(clampTrackFrameCount(99, WALK_TRACK)).toBe(16);
    expect(clampTrackFrameCount(11.6, WALK_TRACK)).toBe(12);
    expect(clampTrackFps(1, WALK_TRACK)).toBe(4);
    expect(clampTrackFps(240, WALK_TRACK)).toBe(24);
  });

  it('falls back to the track\'s default for unusable input', () => {
    expect(clampTrackFrameCount('nope', WALK_TRACK)).toBe(12);
    expect(clampTrackFps(undefined, WALK_TRACK)).toBe(10);
  });

  it('defaults to the walk track when none is named', () => {
    expect(clampTrackFrameCount(99)).toBe(16);
    expect(clampTrackFps(99)).toBe(24);
  });

  // Both clamp tests read SHIPPED: they assert the seed's own numeric bounds, so
  // against the live table an operator who retunes `scanner.maxFrameCount` — the
  // seed invites exactly that — would red a test about the shipped defaults.
  it('clamps scanner values against scanner bounds', () => {
    expect(clampTrackFrameCount(99, SCANNER_TRACK, SHIPPED)).toBe(8);
    expect(clampTrackFrameCount(-1, SCANNER_TRACK, SHIPPED)).toBe(2);
    expect(clampTrackFps(99, SCANNER_TRACK, SHIPPED)).toBe(12);
    expect(clampTrackFps(-1, SCANNER_TRACK, SHIPPED)).toBe(2);
  });

  it('clamps ambient values against the ambient range', () => {
    expect(clampTrackFrameCount(99, AMBIENT_TRACK, SHIPPED)).toBe(6);
    expect(clampTrackFrameCount(-1, AMBIENT_TRACK, SHIPPED)).toBe(2);
    expect(clampTrackFps(99, AMBIENT_TRACK, SHIPPED)).toBe(12);
    expect(clampTrackFps(-1, AMBIENT_TRACK, SHIPPED)).toBe(2);
  });
});

describe('walkBounds re-reads the walk row (no call-site churn)', () => {
  it('exposes exactly the registry values under its historical export names', async () => {
    const bounds = await import('../services/sprites/walkBounds.js');
    const row = getAnimationTrack(WALK_TRACK);
    expect({
      min: bounds.WALK_MIN_FRAME_COUNT,
      max: bounds.WALK_MAX_FRAME_COUNT,
      def: bounds.WALK_DEFAULT_FRAME_COUNT,
      minFps: bounds.WALK_MIN_FPS,
      maxFps: bounds.WALK_MAX_FPS,
      defFps: bounds.WALK_DEFAULT_FPS,
    }).toEqual({
      min: row.minFrameCount,
      max: row.maxFrameCount,
      def: row.defaultFrameCount,
      minFps: row.minFps,
      maxFps: row.maxFps,
      defFps: row.defaultFps,
    });
  });

  it('keeps clampFrameCount / clampFps behaving as the walk-track clamps', async () => {
    const { clampFrameCount, clampFps } = await import('../services/sprites/walkBounds.js');
    for (const n of [-1, 0, 5, 6, 11.6, 16, 99, 'nope', undefined, null]) {
      expect(clampFrameCount(n)).toBe(clampTrackFrameCount(n, WALK_TRACK));
      expect(clampFps(n)).toBe(clampTrackFps(n, WALK_TRACK));
    }
  });
});

describe('sharp-free leaf property', () => {
  // The property that actually matters is on `server/lib/validation.js`: it
  // builds its sprite frame-count/fps ranges from this registry, and the whole
  // reason walkBounds.js was split out (and now animationTracks.js beneath it)
  // is to keep the native image graph out of REQUEST VALIDATION. Asserting only
  // the three leaves would pass while someone routed sharp into validation.js
  // through any of its ~90 other closure members, so validation.js is the first
  // entry point here, not an afterthought.
  const NATIVE = ['sharp', 'canvas', 'fluent-ffmpeg', '@ffmpeg-installer/ffmpeg'];

  it.each([
    ['the request-validation graph', join(SERVER_DIR, 'lib', 'validation.js')],
    ['spriteAnimationTracks.js', join(LIB_DIR, 'spriteAnimationTracks.js')],
    // #3152: the store sits BETWEEN the leaf registry and validation.js — every
    // sprite Zod range now resolves through it — so if it ever reached sharp, the
    // whole split collapses at its narrowest point. It does file I/O (which the
    // leaf below may not), but native image deps are still forbidden.
    ['spriteAnimationTrackStore.js', join(LIB_DIR, 'spriteAnimationTrackStore.js')],
    ['walkBounds.js', join(SPRITES_DIR, 'walkBounds.js')],
    ['animationTargets.js', join(SPRITES_DIR, 'animationTargets.js')],
    // #3016: the atlas grid is the ONE definition of a column span, shared by
    // the compiler (which imports sharp) and the layout sidecar (which must
    // not). If either of these two ever reaches sharp, that split has silently
    // collapsed and the sidecar builder drags the native image graph along.
    ['atlasGrid.js', join(SPRITES_DIR, 'atlasGrid.js')],
    ['atlasLayout.js', join(SPRITES_DIR, 'atlasLayout.js')],
  ])('%s reaches no native image/video dependency', (_label, entry) => {
    const { packages } = staticImportClosure(entry);
    const offending = [...packages].filter((p) => NATIVE.some((n) => specifierMatchesPackage(p, n)));
    expect(offending, `must not reach ${offending.join(', ')}`).toEqual([]);
  });

  it('keeps animationTracks.js a true leaf — it imports nothing at all', () => {
    expect(staticImportSpecifiers(join(LIB_DIR, 'spriteAnimationTracks.js'))).toEqual([]);
  });

  it('runs the store→leaf dependency ONE way (#3152)', () => {
    // The store does file I/O; the leaf may not. So the store imports the leaf and
    // never the reverse — the assertion above already forbids ANY import from the
    // leaf, but state the direction explicitly, because "move the merge into
    // animationTracks.js" is the natural-looking refactor that would drag fs into
    // the request-validation graph and break the split this whole describe exists
    // to protect.
    expect(staticImportSpecifiers(join(LIB_DIR, 'spriteAnimationTrackStore.js')))
      .toContain('./spriteAnimationTracks.js');
    const leafClosure = staticImportClosure(join(LIB_DIR, 'spriteAnimationTracks.js'));
    expect([...leafClosure.files]).not.toContain(join(LIB_DIR, 'spriteAnimationTrackStore.js'));
  });

  it('actually walks the graph (positive control — the guard is not vacuous)', () => {
    // Three ways the assertions above could pass for the wrong reason: the walk
    // never follows relative imports, it never records bare packages, or an
    // unresolvable specifier silently truncates it. Pin the first two against a
    // module that genuinely reaches sharp.
    const walkBounds = staticImportClosure(join(SPRITES_DIR, 'walkBounds.js'));
    expect([...walkBounds.files]).toContain(join(LIB_DIR, 'spriteAnimationTracks.js'));

    const packer = staticImportClosure(join(SPRITES_DIR, 'walkPostprocess.js'));
    expect([...packer.packages], 'walkPostprocess is the native-graph module this split exists to fence off')
      .toContain('sharp');

    // …and that validation.js's closure is genuinely large, so a resolver gap
    // can't make its clean result meaningless.
    expect(staticImportClosure(join(SERVER_DIR, 'lib', 'validation.js')).files.size).toBeGreaterThan(20);
  });
});

describe('client mirror parity', () => {
  // `client/src/lib/spriteTrimmer.js` restates walk's bounds as literals so the
  // pickers can seed their option lists without importing a server module. The
  // registry is now the source of truth for a SET of ranges, so the first real
  // per-track bounds change — the entire motivation for #3015 — would silently
  // desync the picker from the server's Zod range and surface as a 400 with no
  // field-level explanation. Same guard shape as catalogTypes.parity.test.js.
  const walk = getAnimationTrack(WALK_TRACK);

  it('mirrors the walk defaults', () => {
    expect(CLIENT_DEFAULT_FRAME_COUNT).toBe(walk.defaultFrameCount);
    expect(CLIENT_DEFAULT_FPS).toBe(walk.defaultFps);
  });

  it('seeds the frame-count picker from the walk row\'s full range', () => {
    expect(CLIENT_FRAME_COUNT_OPTIONS[0]).toBe(walk.minFrameCount);
    expect(CLIENT_FRAME_COUNT_OPTIONS.at(-1)).toBe(walk.maxFrameCount);
  });

  it('seeds the fps picker within the walk row\'s range', () => {
    // The list is even-stepped, so it need not END exactly on the max — but it
    // must start at the floor, never offer a value the server would reject, AND
    // stay within one step of the ceiling. Without that upper pin the guard
    // passes in precisely the scenario it exists for: raise the row's maxFps and
    // the client's hard-coded 24 still satisfies "≤ max" while the picker
    // silently stops offering speeds the server now accepts.
    // Measure the ceiling against the UN-SPLICED base list: the helper splices a
    // non-even current value into its options so the <select> never lies, so
    // seeding it with `defaultFps` would let a row whose default sat near a
    // raised max (maxFps 30, defaultFps 30) satisfy the pin via the spliced-in
    // value while the picker still stopped at the client's hard-coded 24.
    // A non-finite argument short-circuits the splice and returns the base list.
    const options = clientWalkFpsOptionsFor(NaN);
    expect(options[0]).toBe(walk.minFps);
    expect(Math.max(...options)).toBeLessThanOrEqual(walk.maxFps);
    expect(walk.maxFps - Math.max(...options)).toBeLessThan(2);
  });

  it('keeps the publish form registry-driven instead of mirroring walk bounds', () => {
    // PublishWorkflow.jsx is a React component (not importable under the server
    // runner), so assert the source consumes each served definition's bounds
    // and cannot drift through reintroduced walk-specific constants.
    const src = readFileSync(
      join(SERVER_DIR, '..', 'client', 'src', 'components', 'sprites', 'PublishWorkflow.jsx'),
      'utf-8',
    );
    expect(src).toContain('min={definition.minFrameCount}');
    expect(src).toContain('max={definition.maxFrameCount}');
    expect(src).not.toMatch(/WALK_(?:MIN|MAX)_FRAME_COUNT/);
  });
});