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

26.3 KB
Raw Blame
/**
 * Sprites — the animation-track registry (issue #3015).
 *
 * Frame-count and fps bounds used to be GLOBAL and walk-shaped: one 6–16 /
 * 4–24 range applied to every animation, because the walk cycle was the only
 * animation that existed. #2985 made the persisted target *track-keyed*
 * (`animationTargets.walk`), but nothing described what tracks exist or what
 * each one's legal range is — so a 3-frame ambient loop (a tree in the wind)
 * was unrepresentable. The shipped 4-frame scanner action proves the registry
 * supports a real non-walk range below walk's floor.
 *
 * This module is that description. One row per known track carries its own
 * bounds, defaults, directionality, and the `runtimeContract` field names it
 * occupies — so adding a track is a row here plus its pipeline, never a hunt
 * for hard-coded 6/16 literals. `walk` is the first and (today) only row and
 * reproduces its historical values exactly; `walkBounds.js` now re-reads this
 * row rather than defining the range itself.
 *
 * **Sharp-free leaf, deliberately.** `server/lib/validation.js` builds its Zod
 * ranges from these rows and must not drag the native image graph
 * (sharp/ffmpeg, via walkPostprocess) into the request-validation graph — the
 * same split walkBounds.js was created for, now one level deeper. This module
 * imports NOTHING. `animationTracks.test.js` asserts that transitively.
 *
 * **Unknown track ids are an error, not a fallback.** `getAnimationTrack('nope')`
 * throws instead of quietly handing back walk's range — a mis-keyed track that
 * silently validated against walk's 6–16 would let a 4-frame action be rejected
 * for reasons no message explains. Absent (`undefined`/`null`) means "the
 * default track" and resolves to `walk`, which is what preserves every existing
 * call site; an empty string is *present and invalid*, so it throws.
 *
 * **Which records may carry a track is registry data too (#3017).** The whole
 * sprite animation surface used to be gated on a literal `kind !== 'character'`
 * check, which is why `place` and `object` records had no animation path at all
 * — a tree in the wind or a flickering lamp was unrepresentable not because the
 * atlas couldn't hold it but because the gate refused the record. Each row now
 * declares the record `kinds` that may carry it, and the gates ask the registry
 * (`tracksForKind` / `kindSupportsTrack`) instead of naming a kind. Walk stays
 * character-only, so behavior is unchanged today; a row that lists `place` is
 * all it takes to unlock those records, with no gate edit anywhere.
 *
 * **The per-track WORKFLOW is registry data too (#3136).** `scanner` and
 * `ambient` each shipped as a ~300-line clone of walk's state/start/package/
 * approve/invalidate stack — identical control flow differing only in which
 * reference image seeds the render, what the on-disk selection/set files are
 * called, and which prompt text goes to the provider. Those differences are now
 * either FIELDS on the row (`selectionKind`/`setKind`) or derived from one
 * (`directional` decides both the facing count and which locked reference seeds
 * the render), and `animationTrackWorkflow.js` is the one implementation both
 * drive. A user-defined track is therefore a row plus a prompt template — no new
 * service module, no new routes.
 *
 * **`walk` is the only COMPILED-IN row (#3152).** Every other track — including
 * `scanner` and `ambient`, which shipped as compiled rows through #3018/#3045 —
 * now lives in the user-defined store `animationTrackStore.js` reads, seeded
 * from `data.reference/sprites/animation-tracks.json` by migration 211. That
 * store is what makes "a chest opening" or "a flower blossoming" a user action
 * rather than a PortOS code change, and it is why this table shrank to one row
 * instead of growing a fourth. The MERGE cannot live here: this module does file
 * I/O nowhere and imports nothing (see the leaf note above), so the store
 * imports this and never the reverse. Callers that must see user rows resolve
 * `getEffectiveAnimationTracks()` and pass it through the `tracks` parameter
 * every reader below already takes.
 *
 * A stored row carries two fields a compiled one doesn't: `promptTemplate` (the
 * i2v wording `trackPrompts.js` falls back to, since a user row has no compiled
 * builder) and `builtin: false`. `assertAnimationTrackRows` validates a stored
 * row exactly as it validates this table's, so a bad row fails loudly at load
 * rather than corrupting a render hours later.
 */

/** The default track — and the only one compiled into this build (#3152). */
export const WALK_TRACK = 'walk';
/**
 * The seeded short directional character action (#3018) and non-directional
 * environment loop (#3045).
 *
 * Still NAMED here because `atlas.js` dispatches its two bespoke evidence chains
 * on these exact ids and existing on-disk sets carry them — but they are no
 * longer ROWS in `ANIMATION_TRACKS`: migration 211 moved both into the
 * user-defined store, where a user can retune or delete them like any other
 * track. Resolve them through `getEffectiveAnimationTracks()`; a `getAnimationTrack`
 * call against the compiled table alone will (correctly) throw for them.
 */
export const SCANNER_TRACK = 'scanner';
export const AMBIENT_TRACK = 'ambient';

/**
 * Every animation track compiled into this build — `walk`, and only `walk`
 * (#3152). Merge with the user-defined store via `getEffectiveAnimationTracks()`
 * before handing this to any reader that must see a user's tracks.
 *
 * - `minFrameCount` / `maxFrameCount` — the authoring range the packer clamps
 *   into and the Zod schemas range-check against.
 * - `defaultFrameCount` / `defaultFps` — the bottom rung of the target
 *   precedence chain (see `animationTargets.js`).
 * - `directional` — true when the track occupies one atlas ROW per facing
 *   (walk: 8 directions); a future ambient loop would be false (one row).
 *   Load-bearing since #3017: `trackRowCount` turns it into the number of rows
 *   the track's cells may occupy, and the compiler refuses a cell outside them.
 * - `kinds` — the sprite record kinds that may carry this track. The animation
 *   gates read this instead of testing for `'character'`, so unlocking a record
 *   kind is a data change here rather than a hunt through the service layer.
 * - `contractFrameCountField` / `contractFpsField` — the field names this track
 *   occupies in an app's `publishBinding.runtimeContract` (#2982). Named here so
 *   the app rung of the precedence chain is track-driven rather than hard-coded
 *   to `walkFrameCount`. `contractFpsField` may be `null` for a track whose
 *   speed an app has no say in.
 * - `selectionKind` / `setKind` (#3136) — the `kind` discriminators the track's
 *   on-disk review selection and finalized set carry. Registry data because the
 *   atlas compiler VALIDATES them (`atlas.js`), so a track's on-disk contract
 *   and the compiler's expectation cannot drift.
 * - `finalErrorCode` (#3136) — the `code` on the 409 a finalized set answers
 *   generate/approve with. Named per row so an existing client that matches on
 *   `SCANNER_SET_FINAL` keeps working after the clone collapsed.
 * - `standaloneContract` (#3136) — true when this track's frame count is enough
 *   ON ITS OWN to describe a publishable atlas, because a record can be
 *   published with only this track authored. Walk (a character's baseline) and
 *   ambient (a place's) qualify; a short ACTION like scanner always rides beside
 *   the walk it shares rows with, so pinning only its span describes no atlas
 *   that could exist. DECLARED rather than inferred from registration order: it
 *   is a load-bearing publish-validation rule, and #3152 merges rows from a
 *   user-ordered store where "first row for this kind" would silently change.
 * - `builtin` (#3152) — true for a row compiled into this build, false for one
 *   loaded from the user-defined store. Read by the store's merge (a user row may
 *   not shadow `walk`) and by the prompt resolver (a builtin row has a compiled
 *   prompt builder; a stored one carries `promptTemplate` instead).
 * - `promptTemplate` (#3152, stored rows ONLY) — the i2v instruction sent to the
 *   provider for this track, as literal text. A builtin row omits it and resolves
 *   through the compiled builder in `trackPrompts.js`; a stored row must carry it,
 *   because there is no code to fall back to.
 *
 * Which locked reference an i2v render is seeded from is DERIVED, not declared:
 * a directional track renders one clip per facing and so must seed from that
 * facing's own anchor (`sourceReferenceFor` below), while a non-directional one
 * has no per-facing anchor and seeds from the single locked main. Stating it as
 * a field would let a row claim a pairing that cannot work.
 */
export const ANIMATION_TRACKS = Object.freeze({
  [WALK_TRACK]: Object.freeze({
    id: WALK_TRACK,
    label: 'Walk cycle',
    directional: true,
    // A walk cycle is a character gait — a place or an object has no gait to
    // author, so walk stays character-only and every existing gate keeps its
    // exact behavior. What changed in #3017 is only WHERE that fact lives.
    kinds: Object.freeze(['character']),
    minFrameCount: 6,
    maxFrameCount: 16,
    defaultFrameCount: 12,
    minFps: 4,
    maxFps: 24,
    defaultFps: 10,
    contractFrameCountField: 'walkFrameCount',
    // `spriteRuntimeContractSchema` deliberately declares no fps key (a
    // distance-driven consumer has no animation-fps concept), so today this is
    // reachable only by a legacy/hand-built contract object — kept, not
    // nulled, because dropping it would change resolution behavior for those.
    // A second track copying this row should decide its own answer.
    contractFpsField: 'walkFps',
    // Walk predates the generic workflow and keeps its own bespoke service
    // (walk.js — reprocess, trims, per-direction reopen, source-frame
    // extraction, set-level targets), so these describe its on-disk contract
    // for the compiler's benefit without routing it through the generic module.
    selectionKind: 'reviewed-directional-walk-selection',
    setKind: 'finalized-eight-direction-walk-set',
    finalErrorCode: 'WALK_SET_FINAL',
    // A character publishes off its walk — the compile path requires a finalized
    // walk set before it emits anything at all.
    standaloneContract: true,
    // The one mandatory built-in. `scanner` and `ambient` were `builtin: true`
    // rows here until #3152 moved them into the user-defined store as seed data.
    builtin: true,
  }),
});

// There is deliberately no `ANIMATION_TRACK_IDS` export (#3152 removed it). It
// would now mean "the COMPILED ids" — `['walk']` — while reading as "every track
// id", which is the wrong answer at every call site that wanted it: those want the
// merged table's ids and must ask `getEffectiveAnimationTrackIds()` in
// `animationTrackStore.js`. Iterate `Object.keys(ANIMATION_TRACKS)` inline when you
// genuinely mean the compiled rows only.

/**
 * The min/default/max triples every row must keep in order.
 *
 * Exported because three places need this exact pairing and had each spelled their
 * own copy: the assert below, the request schemas in `server/lib/validation.js`
 * (which front-run the assert so the form gets a per-field 400), and the client's
 * pre-submit check. A fourth knob added to one copy and missed in another is the
 * drift this prevents.
 */
export const TRACK_BOUND_TRIPLES = Object.freeze([
  Object.freeze(['minFrameCount', 'defaultFrameCount', 'maxFrameCount']),
  Object.freeze(['minFps', 'defaultFps', 'maxFps']),
]);

/**
 * The fields of a row a USER authors, as opposed to the ones PortOS derives.
 *
 * The complement is deliberate and load-bearing: everything NOT listed here
 * (`contractFrameCountField`, `contractFpsField`, `selectionKind`, `setKind`,
 * `finalErrorCode`, `standaloneContract`, `builtin`) names a file on disk, a
 * publish-contract key, or a cross-row invariant that `assertAnimationTrackRows`
 * requires to be globally unique — so it is derived from the id rather than typed
 * (see `animationTrackCrud.js`). Named here, beside the assert that validates the
 * whole row, so the request schema and the service's whitelist build from ONE list
 * instead of two that fail in opposite directions when they drift: a field in the
 * schema but not the whitelist validates and is then silently dropped, and one in
 * the whitelist but not the schema is rejected as an unrecognized key.
 */
export const AUTHORED_TRACK_FIELDS = Object.freeze([
  'label', 'directional', 'kinds',
  'minFrameCount', 'maxFrameCount', 'defaultFrameCount',
  'minFps', 'maxFps', 'defaultFps',
  'promptTemplate',
]);

/**
 * The five on-disk / publish-contract discriminators a track's id determines, plus
 * the `contractFpsField` a user-defined row always declines.
 *
 * Derived rather than typed because `assertAnimationTrackRows` requires each to be
 * globally unique and they name artifacts the atlas compiler re-verifies — a typo in
 * one would hand this track another's evidence chain. Lives here, beside that
 * assert, so one module knows a row's whole shape.
 *
 * `contractFpsField` is `null` to match both seeded rows: PortOS's fps is
 * preview-only (a distance-driven consumer owns its timing), so a new track claiming
 * an fps contract key would offer the app a knob nothing reads.
 */
export function deriveTrackFields(id) {
  const camel = id.replace(/-([a-z0-9])/g, (_m, c) => c.toUpperCase());
  return {
    contractFrameCountField: `${camel}FrameCount`,
    contractFpsField: null,
    selectionKind: `reviewed-${id}-selection`,
    setKind: `finalized-${id}-set`,
    finalErrorCode: `${id.replace(/-/g, '_').toUpperCase()}_SET_FINAL`,
  };
}

/**
 * Validate a registry's rows, throwing on the first violation.
 *
 * Called at module load below (the navManifest.js / catalogTypes.js idiom): a
 * row missing a bound would otherwise boot clean and surface much later as
 * `NaN` out of a Math.min, or as `z.number().min(undefined)` throwing at the
 * first sprite render. A bad row should block boot with a message naming the
 * field, not corrupt a render hours later.
 *
 * Exported and pure — taking the table as an argument — so the guard can be
 * proven against a synthetic multi-row fixture. Asserting set-uniqueness over
 * the real (currently single-row) table would only re-derive the
 * implementation: the whole guard could be deleted and such a test would stay
 * green, which is exactly the regression it exists to prevent.
 */
export function assertAnimationTrackRows(tracks) {
  const claimedContractFields = new Map();
  const claimedOnDiskKinds = new Map();
  for (const id of Object.keys(tracks)) {
    const row = tracks[id];
    if (row.id !== id) throw new Error(`animationTracks: row '${id}' declares mismatched id '${row.id}'`);
    if (typeof row.label !== 'string' || !row.label) throw new Error(`animationTracks: track '${id}' needs a label`);
    if (typeof row.directional !== 'boolean') throw new Error(`animationTracks: track '${id}' needs a boolean 'directional'`);
    // 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.
    if (!Array.isArray(row.kinds) || !row.kinds.length) {
      throw new Error(`animationTracks: track '${id}' needs a non-empty 'kinds' array`);
    }
    if (row.kinds.some((kind) => typeof kind !== 'string' || !kind)) {
      throw new Error(`animationTracks: track '${id}' has a non-string entry in 'kinds'`);
    }
    for (const field of ['minFrameCount', 'maxFrameCount', 'defaultFrameCount', 'minFps', 'maxFps', 'defaultFps']) {
      if (!Number.isInteger(row[field])) throw new Error(`animationTracks: track '${id}' needs an integer '${field}'`);
    }
    if (typeof row.contractFrameCountField !== 'string' || !row.contractFrameCountField) {
      throw new Error(`animationTracks: track '${id}' needs a contractFrameCountField`);
    }
    if (row.contractFpsField !== null && (typeof row.contractFpsField !== 'string' || !row.contractFpsField)) {
      throw new Error(`animationTracks: track '${id}' needs a contractFpsField (or null)`);
    }
    // #3136 — the workflow shape.
    for (const field of ['selectionKind', 'setKind', 'finalErrorCode']) {
      if (typeof row[field] !== 'string' || !row[field]) {
        throw new Error(`animationTracks: track '${id}' needs a non-empty '${field}'`);
      }
    }
    if (typeof row.standaloneContract !== 'boolean') {
      throw new Error(`animationTracks: track '${id}' needs a boolean 'standaloneContract'`);
    }
    // #3152 — where the row came from, and (for a stored row) its prompt.
    if (typeof row.builtin !== 'boolean') {
      throw new Error(`animationTracks: track '${id}' needs a boolean 'builtin'`);
    }
    // EXACTLY ONE prompt source per row — the invariant, stated as itself rather
    // than as two provenance checks. A row's prompt is either the compiled builder
    // `trackPrompts.js` holds for it (`builtin`, no template) or its own
    // `promptTemplate` (stored). Neither means a throw out of `buildTrackVideoPrompt`
    // AFTER the user clicked generate; both means two definitions of one track's
    // wording, where the stored value silently wins over the text
    // `prompts.test.js` pins. Refuse either at load, where the message names the row.
    const hasTemplate = typeof row.promptTemplate === 'string' && !!row.promptTemplate.trim();
    if (hasTemplate === row.builtin) {
      throw new Error(
        row.builtin
          ? `animationTracks: builtin track '${id}' must not carry a 'promptTemplate' — its prompt is the compiled builder`
          : `animationTracks: user-defined track '${id}' needs a non-empty 'promptTemplate'`,
      );
    }
    // Two tracks sharing a selection/set `kind` is the same class of bug as two
    // sharing a contract field: the compiler validates a set by its `kind`, so a
    // duplicate would let one track's finalized set satisfy the other's evidence
    // check and compile the wrong frames into its span.
    for (const knob of ['selectionKind', 'setKind']) {
      const owner = claimedOnDiskKinds.get(row[knob]);
      if (owner) {
        throw new Error(
          `animationTracks: on-disk kind '${row[knob]}' is claimed by both '${owner.id}.${owner.knob}' and '${id}.${knob}'`,
        );
      }
      claimedOnDiskKinds.set(row[knob], { id, knob });
    }
    for (const [min, def, max] of TRACK_BOUND_TRIPLES) {
      if (!(row[min] <= row[def] && row[def] <= row[max])) {
        throw new Error(`animationTracks: track '${id}' needs ${min} <= ${def} <= ${max}`);
      }
    }
    // Two tracks must not claim the same runtimeContract field. The anticipated
    // failure is a second row copy-pasted from walk's: `resolveAnimationTarget`
    // would then read the WALK's `walkFrameCount` for that track and, whenever
    // that value happens to land inside its range, return it with
    // `frameCountLocked: true` — silently pinning one track to another's
    // contract and throwing a lock error citing a binding that never mentioned
    // it. The knob name rides along so a row that names ONE field for BOTH of
    // its knobs doesn't report as "claimed by both 'walk' and 'walk'".
    for (const knob of ['contractFrameCountField', 'contractFpsField']) {
      const field = row[knob];
      if (field === null) continue;
      const owner = claimedContractFields.get(field);
      if (owner) {
        throw new Error(
          `animationTracks: contract field '${field}' is claimed by both '${owner.id}.${owner.knob}' and '${id}.${knob}'`,
        );
      }
      claimedContractFields.set(field, { id, knob });
    }
  }
  // Every record kind any row admits must have EXACTLY ONE standalone track —
  // the baseline it publishes off. Zero means a record of that kind can be
  // authored but never publish (its runtime contract could name no required
  // field, and the compiler has no evidence chain to require); more than one
  // means "which set must be finalized before compiling?" has two answers. This
  // is a cross-row invariant, so it runs after the per-row loop.
  const standaloneByKind = new Map();
  for (const id of Object.keys(tracks)) {
    if (!tracks[id].standaloneContract) continue;
    for (const kind of tracks[id].kinds) {
      standaloneByKind.set(kind, [...(standaloneByKind.get(kind) || []), id]);
    }
  }
  for (const id of Object.keys(tracks)) {
    for (const kind of tracks[id].kinds) {
      const owners = standaloneByKind.get(kind) || [];
      if (owners.length !== 1) {
        throw new Error(
          `animationTracks: record kind '${kind}' needs exactly one standaloneContract track, has ${owners.length}${owners.length ? ` (${owners.join(', ')})` : ''}`,
        );
      }
    }
  }
}

assertAnimationTrackRows(ANIMATION_TRACKS);

/**
 * The locked reference artifact a track's image-to-video render is seeded from:
 * `'anchor'` (this facing's own locked directional anchor) or `'main'` (the one
 * locked main reference).
 *
 * DERIVED from `directional` rather than declared, because only one pairing can
 * work. A directional track renders one clip per facing, so seeding all eight
 * rows from the single main would render the same south-facing clip eight times
 * and pass every later check — nothing downstream re-reads which facing was
 * asked for. The inverse has no anchor to read at all: a place record never
 * generates directional anchors.
 */
export function sourceReferenceFor(id, tracks = ANIMATION_TRACKS) {
  return getAnimationTrack(id, tracks).directional ? 'anchor' : 'main';
}

/**
 * The one track a record of `kind` publishes off — its baseline, whose finalized
 * set the compile path requires and whose frame count alone is a valid runtime
 * contract. `null` for a kind no row admits.
 *
 * One definition, asked by the publish-contract schema (which field is required)
 * and the compile dispatch (which evidence chain to validate). Those two used to
 * answer it separately — one by registration order, one as
 * `ambient-and-not-walk` — and agreed only by coincidence.
 */
export function primaryTrackForKind(kind, tracks = ANIMATION_TRACKS) {
  if (typeof kind !== 'string' || !kind) return null;
  return Object.values(tracks).find((row) => row.standaloneContract && row.kinds.includes(kind)) || null;
}

/** True when `id` names a track in `tracks` (the shipped registry by default). */
export function isAnimationTrack(id, tracks = ANIMATION_TRACKS) {
  return typeof id === 'string' && Object.prototype.hasOwnProperty.call(tracks, id);
}

/**
 * The registry row for `id`. Absent (`undefined`/`null`) resolves to the default
 * track; anything else unrecognized THROWS rather than falling back, so a typo
 * can never be validated against walk's range by accident.
 *
 * The table is a parameter — the same idiom `assertAnimationTrackRows(tracks)`
 * uses — so a caller that must work across a *set* of tracks (the atlas grid,
 * #3016) can be exercised against a synthetic multi-row table while the shipped
 * registry has one row, WITHOUT that caller growing a private lookup that
 * bypasses this unknown-id boundary.
 */
export function getAnimationTrack(id, tracks = ANIMATION_TRACKS) {
  const key = id === undefined || id === null ? WALK_TRACK : id;
  if (!isAnimationTrack(key, tracks)) {
    throw new Error(
      `Unknown animation track '${String(key)}' — known tracks: ${Object.keys(tracks).join(', ')}.`,
    );
  }
  return tracks[key];
}

/**
 * The atlas rows one track's cells may occupy, given how many facings the grid
 * has: every row for a directional track, exactly one (row 0) for a
 * non-directional one.
 *
 * `directionCount` is a PARAMETER rather than an import because this module is
 * a true leaf — `animationTracks.test.js` asserts it imports nothing at all —
 * and the canonical direction list lives in `prompts.js`. Callers that already
 * know the grid pass its real height; `atlasGrid.js` supplies the default.
 */
export function trackRowCount(id, directionCount, tracks = ANIMATION_TRACKS) {
  const row = getAnimationTrack(id, tracks);
  if (!Number.isInteger(directionCount) || directionCount < 1) {
    throw new Error(`animationTracks: trackRowCount needs a positive direction count, got ${directionCount}`);
  }
  return row.directional ? directionCount : 1;
}

/**
 * Every track a record of this `kind` may carry, in registration order.
 *
 * This is the whole of the "track-presence gate" (#3017): a record kind with no
 * rows has no animation path, and a kind with at least one does — replacing the
 * literal `kind !== 'character'` test the sprite services used to make. An
 * absent/blank kind matches nothing rather than defaulting to a kind, so a
 * malformed record can't inherit character's permissions.
 */
export function tracksForKind(kind, tracks = ANIMATION_TRACKS) {
  if (typeof kind !== 'string' || !kind) return [];
  return Object.values(tracks).filter((row) => row.kinds.includes(kind));
}

/**
 * True when a record of `kind` may carry the named track. A predicate, not a
 * boundary: an unrecognized track id answers `false` rather than throwing,
 * because the gates call this to DECIDE. The row is an O(1) lookup, so this
 * asks it directly instead of rebuilding `tracksForKind`'s array to re-find it.
 */
export function kindSupportsTrack(kind, id, tracks = ANIMATION_TRACKS) {
  if (!isAnimationTrack(id, tracks)) return false;
  return typeof kind === 'string' && !!kind && tracks[id].kinds.includes(kind);
}

// Round-then-clamp, with unusable input (NaN, non-numeric) falling back to the
// knob's default rather than to a bound — the two knobs differ only in which
// three row fields they read.
const clampInto = (n, min, max, fallback) => {
  const v = Math.round(Number(n));
  if (!Number.isFinite(v)) return fallback;
  return Math.max(min, Math.min(max, v));
};

/**
 * Clamp a requested frame count into `track`'s authoring range.
 *
 * `tracks` is the same injectable table every reader above takes (#3152) —
 * callers that must clamp a USER-DEFINED track pass the effective table, since a
 * stored row is unknown to the compiled default and would throw.
 */
export function clampTrackFrameCount(n, track, tracks = ANIMATION_TRACKS) {
  const row = getAnimationTrack(track, tracks);
  return clampInto(n, row.minFrameCount, row.maxFrameCount, row.defaultFrameCount);
}

/** Clamp a requested playback fps into `track`'s authoring range. */
export function clampTrackFps(n, track, tracks = ANIMATION_TRACKS) {
  const row = getAnimationTrack(track, tracks);
  return clampInto(n, row.minFps, row.maxFps, row.defaultFps);
}