@volter/game-editor 0.5.65

package/catalog/project-source/src/lib/audio/sfx.ts

@@ -0,0 +1,255 @@
+/**
+ * The game's own SFX voice: a small Web Audio graph this project owns, and the
+ * `SystemAdapters.audio` registration that lets the host silence it.
+ *
+ * ## Why the game owns the context
+ *
+ * This world is an R3F root. An R3F root renders through react-three-fiber
+ * against the HOST's renderer, and the host supplies no mixer of its own —
+ * audio is the game's, built with Web Audio directly inside the tree. That is
+ * the seam doctrine working as designed: an absent capability is absent, not
+ * faked by the host.
+ *
+ * ## Why it is still mutable from the editor
+ *
+ * A game-owned context is only orphaned if nothing can see it. `SystemAdapters`
+ * is the seam for exactly this: the game DECLARES what it implements through
+ * its entry's `systems` export (`export const systems = { audio:
+ * sfxAudioSystem() }` in `src/systems.ts`), and from the moment the host
+ * installs it the editor's mute button, the Audio debugger tab and
+ * `Game.play.pause()`'s silence-on-pause all reach this graph — without the
+ * host fabricating a mixer it does not have, and without a component calling
+ * a host registration.
+ *
+ * The graph is deliberately tiny: one gain node (the game's whole "sfx bus")
+ * into the destination. Mute rides that node, so muting composes with the
+ * per-voice envelopes below instead of fighting them.
+ */
+
+import type { AudioAdapter, AudioGraphNode } from '@volter/editor-project/adapter';
+
+/** A one-shot blip: a falling/rising saw with an exponential decay. Frequencies
+ *  in Hz, `duration` in seconds, `volume` linear (0–1), `end` the frequency to
+ *  glide to (defaults to a steady tone). A no-op when this environment has no
+ *  Web Audio at all — headless CI, an SSR pass — which is why callers never
+ *  guard. */
+export type PlayTone = (frequency: number, duration: number, volume: number, end?: number) => void;
+
+export interface GainDuckOptions {
+  /** Gain while ducked, in linear amplitude. */
+  duckGain?: number;
+  /** Seconds to reach the ducked level. */
+  attack?: number;
+  /** Seconds to remain ducked before restoring. */
+  hold?: number;
+  /** Seconds to restore the resting gain. */
+  release?: number;
+}
+
+/**
+ * Coordinate ducking on an ordinary Web Audio gain parameter. The project
+ * keeps the native AudioParam — this helper only owns the easy-to-get-wrong
+ * cancel/hold/restore automation for repeated triggers.
+ */
+export function createGainDucker(
+  context: BaseAudioContext,
+  gain: AudioParam,
+  options: GainDuckOptions = {},
+): { trigger(): void; dispose(): void } {
+  const restingGain = gain.value;
+  const duckGain = Math.max(0, options.duckGain ?? 0.35);
+  const attack = Math.max(0, options.attack ?? 0.02);
+  const hold = Math.max(0, options.hold ?? 0.12);
+  const release = Math.max(0, options.release ?? 0.25);
+
+  return {
+    trigger(): void {
+      const now = context.currentTime;
+      gain.cancelAndHoldAtTime(now);
+      gain.linearRampToValueAtTime(duckGain, now + attack);
+      gain.setValueAtTime(duckGain, now + attack + hold);
+      gain.linearRampToValueAtTime(restingGain, now + attack + hold + release);
+    },
+    dispose(): void {
+      const now = context.currentTime;
+      gain.cancelScheduledValues(now);
+      gain.setValueAtTime(restingGain, now);
+    },
+  };
+}
+
+/** What {@link createGameSfx} hands back: the voice, the adapter to register,
+ *  and the teardown the mounting component owns. */
+export interface GameSfx {
+  readonly tone: PlayTone;
+  /** Expose this through the root entry's `systems.audio` so
+   *  host mute/pause reach the graph. `null` when there is no real context to
+   *  silence — registering a no-op adapter would tell the host this world's
+   *  audio is under control when there is no audio at all. */
+  readonly adapter: AudioAdapter | null;
+  /** Close the context. Nothing else owns it. */
+  dispose(): void;
+}
+
+/** The silent stand-in for an environment with no Web Audio (jsdom, a headless
+ *  bot run). It reports no adapter, so `Game.play.pause()` says out loud that
+ *  this world has no audio seam rather than pretending it silenced one. */
+const SILENT: GameSfx = {
+  tone: () => {},
+  adapter: null,
+  dispose: () => {},
+};
+
+export function createGameSfx({ maxVoices = 24 }: { maxVoices?: number } = {}): GameSfx {
+  const Ctor: typeof AudioContext | undefined =
+    typeof AudioContext !== 'undefined' ? AudioContext : undefined;
+  if (!Ctor) return SILENT;
+
+  const context = new Ctor();
+  const bus = context.createGain();
+  bus.gain.value = 1;
+  bus.connect(context.destination);
+
+  let muted = false;
+  let priorGain = bus.gain.value;
+  let voiceSequence = 0;
+  const voiceLimit = Math.max(1, Math.floor(maxVoices));
+  const voices: Array<{
+    id: number;
+    oscillator: OscillatorNode;
+    gain: GainNode;
+  }> = [];
+
+  const releaseVoice = (voice: (typeof voices)[number]): void => {
+    const index = voices.indexOf(voice);
+    if (index >= 0) voices.splice(index, 1);
+    voice.oscillator.disconnect();
+    voice.gain.disconnect();
+  };
+
+  const stopVoice = (voice: (typeof voices)[number]): void => {
+    voice.oscillator.onended = null;
+    try {
+      voice.oscillator.stop();
+    } catch {
+      // It ended between the pool check and the stop call.
+    }
+    releaseVoice(voice);
+  };
+
+  const adapter: AudioAdapter = {
+    resume: () => {
+      if (context.state === 'suspended') void context.resume();
+    },
+    setMuted(next: boolean): void {
+      if (next === muted) return;
+      muted = next;
+      // Restore to whatever the bus held before muting, never a hardcoded 1 —
+      // so a pause taken while already user-muted resumes muted.
+      if (next) {
+        priorGain = bus.gain.value;
+        bus.gain.value = 0;
+      } else {
+        bus.gain.value = priorGain;
+      }
+    },
+    isMuted: () => muted,
+    graphSnapshot(): AudioGraphNode[] {
+      return [
+        {
+          id: 'destination',
+          type: 'AudioDestinationNode',
+          label: 'Output',
+          outputs: [],
+          state: context.state,
+        },
+        { id: 'sfx', type: 'GainNode', label: 'Game SFX', outputs: ['destination'] },
+        ...voices.map((voice) => ({
+          id: `voice-${voice.id}`,
+          type: 'OscillatorNode',
+          label: `One-shot voice ${voice.id} (${voices.length}/${voiceLimit})`,
+          outputs: ['sfx'],
+          state: 'started',
+        })),
+      ];
+    },
+  };
+
+  return {
+    tone(frequency, duration, volume, end = frequency): void {
+      // Autoplay policy starts every context suspended; the page has had user
+      // activation long before a shot is fired, so this is the cheap unlock.
+      if (context.state === 'suspended') void context.resume();
+      while (voices.length >= voiceLimit) stopVoice(voices[0]!);
+      const now = context.currentTime;
+      const oscillator = context.createOscillator();
+      const gain = context.createGain();
+      const voice = { id: ++voiceSequence, oscillator, gain };
+      voices.push(voice);
+      oscillator.onended = () => releaseVoice(voice);
+      oscillator.type = 'sawtooth';
+      oscillator.frequency.setValueAtTime(frequency, now);
+      oscillator.frequency.exponentialRampToValueAtTime(Math.max(20, end), now + duration);
+      gain.gain.setValueAtTime(volume, now);
+      gain.gain.exponentialRampToValueAtTime(0.0001, now + duration);
+      oscillator.connect(gain).connect(bus);
+      oscillator.start(now);
+      oscillator.stop(now + duration);
+    },
+    adapter,
+    dispose(): void {
+      for (const voice of [...voices]) stopVoice(voice);
+      bus.disconnect();
+      void context.close();
+    },
+  };
+}
+
+// --- The one voice, module-owned ---------------------------------------------
+//
+// Created on first use, kept for the page's lifetime: browsers cap live
+// AudioContexts, an Edit→Play remount reuses the same graph, and the entry's
+// `systems` export needs the adapter to exist when the host installs it —
+// which is right after mount, long before the first gunshot.
+
+let active: GameSfx | null = null;
+
+/** The game's one voice. */
+export function gameSfx(): GameSfx {
+  active ??= createGameSfx();
+  return active;
+}
+
+/** Play one tone through the game's voice — the call every mechanic makes. */
+export const gameTone: PlayTone = (frequency, duration, volume, end) => {
+  gameSfx().tone(frequency, duration, volume, end);
+};
+
+/**
+ * The entry `systems` export's audio slot: a LAZY forwarding adapter over the
+ * voice (constructed on first actual call, so importing the entry in Edit
+ * mode builds no AudioContext), or the positive absence for an environment
+ * with no Web Audio at all (jsdom, a headless bot run) — decided without
+ * constructing anything, stated, never simulated.
+ */
+export function sfxAudioSystem(): AudioAdapter | { present: false; evidence: string } {
+  if (typeof AudioContext === 'undefined') {
+    return {
+      present: false,
+      evidence:
+        'no Web Audio in this environment — `typeof AudioContext === "undefined"` ' +
+        '(src/lib/audio/sfx.ts)',
+    };
+  }
+  const live = (): AudioAdapter => {
+    const adapter = gameSfx().adapter;
+    if (!adapter) throw new Error('sfx: the Web Audio voice failed to construct.');
+    return adapter;
+  };
+  return {
+    resume: () => live().resume?.(),
+    setMuted: (next) => live().setMuted(next),
+    isMuted: () => live().isMuted(),
+    graphSnapshot: () => live().graphSnapshot?.() ?? [],
+  };
+}

package/catalog/project-source/src/lib/bake/asset-seed.ts

@@ -0,0 +1,128 @@
+/**
+ * The ASSET SEED — the procedural-asset family's serializable "what to build".
+ *
+ * Every parametric asset lib in this family (the humanoid, the walking
+ * castle, whatever you add next) exports the same PAIR: a declared params
+ * schema and the synchronous function that takes it (see `params.ts`'s
+ * `describeNumericParams`, which reads the tuning controls off that
+ * declaration). A seed is the JSON-able record of one call to that pair:
+ *
+ *   { generator, variant?, params?, palette? }
+ *
+ * That is deliberately the smallest thing that can round-trip through a save
+ * file, a network spawn packet, a URL, or a character creator's state.
+ * Because generation is synchronous and loads no assets, a seed is enough to
+ * REBUILD the asset anywhere — no baked GLB has to travel with it.
+ *
+ * FAMILY-LEVEL ON PURPOSE, and it lives HERE rather than in any one lib
+ * because `lib/bake` is already where the family's cross-member contracts
+ * live: `params.ts` (the schema-pair parameterization both Builders derive
+ * their controls from) and the bake host itself. `bake` is a `requires` of
+ * both `humanoid` and `castle`, so a seed is reachable from either without
+ * one lib depending on the other.
+ *
+ * The shape knows NOTHING about humanoids: a walking castle seed is
+ * `{ generator: 'castle', variant: 'keep', params: { towers: 4 },
+ * palette: { stone: 0x8a8a92 } }` and fits it exactly. Each lib supplies its
+ * own thin instance — the pair of functions that turn a seed into a built
+ * asset and a built asset's inputs back into a seed (the humanoid's is
+ * `src/lib/humanoid/seed.ts`). There is deliberately no registry, no
+ * dispatcher and no "seed system": resolving `generator` to a builder is one
+ * `switch` in your game, written where your game knows which libs it has.
+ *
+ * REMOVAL LINE: nothing in any render or bake path reads a seed. Delete this
+ * file and each lib's `seed.ts` and every generator still builds from its
+ * params exactly as before; you lose serialization, not generation.
+ */
+
+import { z } from 'zod';
+
+export const AssetSeedSchema = z
+  .object({
+    generator: z
+      .string()
+      .min(1)
+      .describe(
+        'Which parametric asset lib builds this — the lib id, e.g. "humanoid" or "castle". ' +
+          'Your game maps it to a builder; nothing here resolves it.',
+      ),
+    variant: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        'The generator’s own named starting point — a key of its character/preset index ' +
+          '(the humanoid’s CHARACTERS, the castle’s presets). Omitted = that lib’s default.',
+      ),
+    params: z
+      .record(z.string(), z.number())
+      .optional()
+      .describe(
+        'Numeric tuning params, validated by the generator’s OWN params schema (the same ' +
+          'declaration `describeNumericParams` reads its controls from). Merged OVER the ' +
+          'variant’s own params — an explicit value always wins.',
+      ),
+    palette: z
+      .record(z.string(), z.number())
+      .optional()
+      .describe(
+        'Material-slot colour overrides: slot name → 0xRRGGBB, merged over the variant’s ' +
+          'palette. Slot names are the generator’s own vocabulary; an unknown slot is inert ' +
+          'here and is reported by the generator if it validates its spec.',
+      ),
+  })
+  .strict();
+
+/** One serializable "what to build" — see the module header. */
+export type AssetSeed = z.infer<typeof AssetSeedSchema>;
+
+/** Thrown by `parseAssetSeed`. */
+export class AssetSeedError extends Error {
+  constructor(message: string) {
+    super(`asset seed: ${message}`);
+    this.name = 'AssetSeedError';
+  }
+}
+
+/**
+ * Validate an untrusted seed (save file, network packet, URL fragment) and
+ * return it typed. Loud and named on failure — a malformed seed must never
+ * quietly become "the default character".
+ */
+export function parseAssetSeed(value: unknown): AssetSeed {
+  const result = AssetSeedSchema.safeParse(value);
+  if (!result.success) {
+    throw new AssetSeedError(
+      result.error.issues
+        .slice(0, 6)
+        .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+        .join('; '),
+    );
+  }
+  return result.data;
+}
+
+/**
+ * Build a seed from a generator id plus optional parts, DROPPING empty ones —
+ * so a seed is stable to compare and cheap to store: `{ generator: 'humanoid' }`
+ * and `{ generator: 'humanoid', params: {}, palette: {} }` serialize the same.
+ */
+export function assetSeed(
+  generator: string,
+  parts: {
+    variant?: string | undefined;
+    params?: Readonly<Record<string, number>> | undefined;
+    palette?: Readonly<Record<string, number>> | undefined;
+  } = {},
+): AssetSeed {
+  const params =
+    parts.params && Object.keys(parts.params).length > 0 ? { ...parts.params } : undefined;
+  const palette =
+    parts.palette && Object.keys(parts.palette).length > 0 ? { ...parts.palette } : undefined;
+  return {
+    generator,
+    ...(parts.variant ? { variant: parts.variant } : {}),
+    ...(params ? { params } : {}),
+    ...(palette ? { palette } : {}),
+  };
+}

package/catalog/project-source/src/lib/bake/bake-schema.ts

@@ -0,0 +1,65 @@
+/**
+ * The schema fragments every parametric-asset bake tool repeats.
+ *
+ * A bake tool's genuinely own facts are its name, its prose, its build closure,
+ * and its validation thresholds — not the shape of an output file record or the
+ * dozen counters `bakeObject3DSource` returns. Those were copied verbatim into
+ * each tool, so a new field meant editing every lib. Libs `.extend()` these with
+ * whatever they additionally report.
+ *
+ * Plain data with explicit inputs and outputs; no registry and no tool factory.
+ * `defineTool` stays in each lib's own file, where its summary, permission, and
+ * impl belong.
+ */
+
+import { z } from 'zod';
+
+/** One file written by a bake. */
+export const BakeOutputFileSchema = z.object({
+  bytes: z.number(),
+  mediaType: z.string().optional(),
+  path: z.string(),
+  role: z.enum(['asset', 'provenance', 'other']).optional(),
+});
+
+/** What every Object3D bake reports. Extend for lib-specific counters. */
+export const BakeResultSchema = z.object({
+  animatedNodeCount: z.number(),
+  boneCount: z.number(),
+  clips: z.array(z.string()),
+  dryRun: z.boolean(),
+  files: z.array(BakeOutputFileSchema),
+  meshCount: z.number(),
+  model: z.string(),
+  provenanceOperationId: z.string().optional(),
+  skinnedMeshCount: z.number(),
+  totalBytes: z.number(),
+});
+
+/** Stable lowercase asset name for the generated GLB. */
+export const BakeAssetNameSchema = z
+  .string()
+  .regex(/^[a-z0-9][a-z0-9-_]{0,63}$/)
+  .describe('Stable lowercase asset name used for the generated GLB file.');
+
+export const BakeDryRunSchema = z
+  .boolean()
+  .default(false)
+  .describe('Generate and validate the complete batch without writing project files.');
+
+/**
+ * The `{ dryRun, name, params }` base every bake tool accepts. Pass the lib's
+ * own params schema already made partial and defaulted — that stays at the call
+ * site so `input.params` keeps the lib's exact type, which the build closure
+ * needs. This helper owns only the two fields that are identical everywhere.
+ */
+export function bakeInputSchema<P extends z.ZodTypeAny>(
+  params: P,
+  options: { defaultName: string },
+) {
+  return z.object({
+    dryRun: BakeDryRunSchema,
+    name: BakeAssetNameSchema.default(options.defaultName),
+    params,
+  });
+}

package/catalog/project-source/src/lib/bake/clip-layering.ts

@@ -0,0 +1,203 @@
+/**
+ * CLIP LAYERING — additive clips and per-bone masks, for any rigged asset.
+ *
+ * This is the family-level animation floor: a humanoid layers an expression or
+ * an aim pose over a walk, and a walking castle layers a drawbridge over its
+ * gait, by the same mechanism. It lives here in `lib/bake` — the
+ * procedural-asset family's shared home, required by `humanoid` and `castle`
+ * alike — precisely so the castle never has to import humanoid code to get it.
+ * Nothing in this file knows what a spine is.
+ *
+ * HELPERS, NOT A SYSTEM. Every function returns a real `THREE.AnimationClip`
+ * you then hand to a real `THREE.AnimationMixer` and drive with three's own
+ * API (`action.blendMode`, `.weight`, `.play()`). There is no layer manager,
+ * no rig-agnostic state machine, no registry — three already has the runtime
+ * (`AdditiveAnimationBlendMode` and one action per layer). What was missing was
+ * the two PREPARATION steps three makes you write by hand each time, and both
+ * are traps:
+ *
+ *   - `AnimationUtils.makeClipAdditive` MUTATES the clip you pass it, so
+ *     calling it on a clip that is also playing as a base layer silently turns
+ *     that layer into deltas about a reference pose. {@link additiveClip}
+ *     clones first.
+ *   - masking means filtering `clip.tracks` by node name, and a typo'd bone
+ *     name filters to nothing and animates nothing, silently.
+ *     {@link maskClip} throws instead.
+ *
+ * TYPICAL USE — an upper-body additive layer over a full-body base:
+ *
+ *   const base = mixer.clipAction(walk);
+ *   const layer = mixer.clipAction(
+ *     additiveClip(maskClip(aim, boneSubtreeNames(root, ['chest'], { animatedIn: aim }))),
+ *   );
+ *   layer.blendMode = THREE.AdditiveAnimationBlendMode;
+ *   base.play();
+ *   layer.setEffectiveWeight(0.8).play();
+ *
+ * REMOVAL LINE: delete this file. Nothing else in the family imports it — a
+ * game that does not layer clips loses nothing, and a game that does can write
+ * the four lines each helper wraps.
+ */
+
+import * as THREE from 'three';
+
+/** Every node name the clip animates, in first-appearance order. */
+export function clipAnimatedNodes(clip: THREE.AnimationClip): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const track of clip.tracks) {
+    const { nodeName } = THREE.PropertyBinding.parseTrackName(track.name);
+    if (!nodeName || seen.has(nodeName)) continue;
+    seen.add(nodeName);
+    out.push(nodeName);
+  }
+  return out;
+}
+
+export interface AdditiveClipOptions {
+  /** Name for the returned clip (default: `${clip.name}_Additive`). */
+  name?: string;
+  /** Frame of `reference` to subtract — the pose the layer is a DELTA FROM.
+   *  Default 0. */
+  referenceFrame?: number;
+  /** Clip the reference pose is sampled from (default: `clip` itself, i.e. the
+   *  layer is a delta from its own first frame). Pass the BASE clip's rest
+   *  frame when the layer was authored against a different neutral pose. */
+  reference?: THREE.AnimationClip;
+  /** Frames per second used to turn `referenceFrame` into a time. Default 30. */
+  fps?: number;
+}
+
+/**
+ * `THREE.AnimationUtils.makeClipAdditive`, on a CLONE.
+ *
+ * Three's own function converts in place and returns the same object, which is
+ * the sharp edge: the clip you passed is now deltas, and any action already
+ * playing it as a normal (base) layer is now playing a broken pose. This
+ * returns a new clip and leaves the input untouched, so the same source clip
+ * can be both a base layer and the source of an additive one.
+ *
+ * The returned clip is only meaningful on an action whose `blendMode` is
+ * `THREE.AdditiveAnimationBlendMode` — that is three's contract, not this
+ * helper's, and this helper deliberately does not create the action for you.
+ */
+export function additiveClip(
+  clip: THREE.AnimationClip,
+  options: AdditiveClipOptions = {},
+): THREE.AnimationClip {
+  const additive = clip.clone();
+  additive.name = options.name ?? `${clip.name}_Additive`;
+  THREE.AnimationUtils.makeClipAdditive(
+    additive,
+    options.referenceFrame ?? 0,
+    options.reference ?? additive,
+    options.fps ?? 30,
+  );
+  return additive;
+}
+
+export interface MaskClipOptions {
+  /** Name for the returned clip (default: `${clip.name}_Masked`). */
+  name?: string;
+  /** Keep the tracks that do NOT target the named nodes instead — the
+   *  complementary half of the same split. Default false. */
+  invert?: boolean;
+}
+
+/**
+ * A copy of `clip` carrying only the tracks that target the named nodes (or,
+ * with `invert`, only the tracks that do not).
+ *
+ * BOUNDARY SEMANTICS — the part that decides what a "split" actually means:
+ * a mask is a FLAT SET OF NODE NAMES, never a subtree. Naming a node puts THAT
+ * node on the mask's side and says nothing about its children, its parent, or
+ * its siblings. Use {@link boneSubtreeNames} to turn a split node into its
+ * subtree when that is what you want — and note what that does NOT include:
+ * a chain that hangs off an ANCESTOR of your split node is on the other side,
+ * even if it is anatomically "above" it. (Concretely for a humanoid rig: the
+ * clavicles hang off the chest vertebra, so an upper-body mask rooted at the
+ * ARM bones leaves clavicle motion on the TORSO side. That is usually right —
+ * see this lib's humanoid notes on the retargeter's clavicle pass-through —
+ * but it is a decision, so it is spelled out rather than implied.)
+ *
+ * Loud on a name the clip does not animate: a mask is written by hand against
+ * a rig, so a typo or a mask copied from a different skeleton is the expected
+ * failure, and silently filtering to nothing is the expected symptom.
+ */
+export function maskClip(
+  clip: THREE.AnimationClip,
+  nodes: Iterable<string>,
+  options: MaskClipOptions = {},
+): THREE.AnimationClip {
+  const wanted = new Set(nodes);
+  if (wanted.size === 0) {
+    throw new Error(`clip-layering: maskClip('${clip.name}') was given no node names`);
+  }
+  const animated = new Set(clipAnimatedNodes(clip));
+  const unknown = [...wanted].filter((name) => !animated.has(name));
+  if (unknown.length > 0) {
+    throw new Error(
+      `clip-layering: maskClip('${clip.name}') names ${unknown.length} node(s) the clip does ` +
+        `not animate: ${unknown.slice(0, 12).join(', ')} (it animates: ` +
+        `${[...animated].slice(0, 12).join(', ')}${animated.size > 12 ? ', …' : ''})`,
+    );
+  }
+  const invert = options.invert ?? false;
+  const tracks = clip.tracks.filter((track) => {
+    const { nodeName } = THREE.PropertyBinding.parseTrackName(track.name);
+    return wanted.has(nodeName) !== invert;
+  });
+  if (tracks.length === 0) {
+    throw new Error(
+      `clip-layering: maskClip('${clip.name}') kept no tracks — the mask covers ` +
+        `${invert ? 'every' : 'no'} animated node`,
+    );
+  }
+  return new THREE.AnimationClip(
+    options.name ?? `${clip.name}_Masked`,
+    clip.duration,
+    tracks.map((track) => track.clone()),
+    clip.blendMode,
+  );
+}
+
+export interface BoneSubtreeOptions {
+  /** Keep only the names this clip actually animates. Without it the result is
+   *  the full subtree, which {@link maskClip} will reject if the clip animates
+   *  only part of it — so pass the clip you are about to mask. */
+  animatedIn?: THREE.AnimationClip;
+}
+
+/**
+ * Every node name at or under each named split node, found by traversing
+ * `root`. The ergonomic way to build a mask from a handful of split points
+ * ("everything from the chest up") instead of listing forty bones.
+ *
+ * Loud on a split node that is not in `root`: naming a bone the rig does not
+ * have is the same authoring mistake {@link maskClip} guards, one step earlier.
+ */
+export function boneSubtreeNames(
+  root: THREE.Object3D,
+  splitNodes: Iterable<string>,
+  options: BoneSubtreeOptions = {},
+): string[] {
+  const requested = [...splitNodes];
+  if (requested.length === 0) {
+    throw new Error('clip-layering: boneSubtreeNames was given no split nodes');
+  }
+  const missing = requested.filter((name) => !root.getObjectByName(name));
+  if (missing.length > 0) {
+    throw new Error(
+      `clip-layering: boneSubtreeNames: '${root.name || 'root'}' has no node(s) ` +
+        `${missing.slice(0, 12).join(', ')}`,
+    );
+  }
+  const keep = options.animatedIn ? new Set(clipAnimatedNodes(options.animatedIn)) : null;
+  const out = new Set<string>();
+  for (const name of requested) {
+    root.getObjectByName(name)?.traverse((node) => {
+      if (node.name && (!keep || keep.has(node.name))) out.add(node.name);
+    });
+  }
+  return [...out];
+}