Give a song, a track or an item a sound FX of its own (#355)

A sound FX for one place in a song had to be a project asset, which
then stood in every picker. Now every pick of a sound FX in a song
can make one the song keeps for that place alone, on top of the
embedded assets of the first two parts.

- Create sound FX sits at the end of the Sound FX row of the song,
  a track and an item, and of the menu of a track's FX button. It
  makes "Sound FX 1", 2, … per song with the Input wired to the
  Output, picks it and opens it. That is one undo step.
- Embed a copy, while the place names a project FX, gives the place
  a copy under the same name.
- While the place names its own, the menu shows it with the mark and
  offers Edit sound FX and Make project asset.
- Picking anything else lets it go in the same undo step. For a
  track or an item `settleEmbedded` did that already. For the song's
  own row `AssetPropertyCommand` now settles the song after `fx`.
- The mark `•` moved to the core. `assetRefLabel` puts it in front of
  an embedded asset, so the inspector rows show it like the timeline.
- `FieldHandlers.moreChoices` lets a caller end a reference menu
  with entries of its own. `embeddedPatternName` is `embeddedName`
  with a base now.

Tests:
- Unit own-fx (new): 6 green, 6 counter-checks each red
- Unit embedded and 80 neighbouring files: 1434 green
- e2e 65 (melektaus-atx): ALL PASSED, 51 checks (2 new)
- Gate (melektaus-atx): CHECK EXIT 0, 270 files, 4178 tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/core/commands/assetCommands.ts

@@ -42,6 +42,7 @@ import { type Command, CommandError } from './Command';
 import { nextAssetName } from './naming';
 import { requireAsset, requirePropDef, requireStateMachine, requireVariablesAsset } from './require';
 import { SetBagValueCommand } from './SetBagValueCommand';
+import { SetSongCommand } from './songCommands';
 
 export function buildAsset(type: AssetType, name: string, id = newId()): Asset {
   const base = { id, name, props: initialPropsFor(type) };
@@ -539,9 +540,13 @@ export class SetMachineStartCommand implements Command {
   }
 }
 
-/** An embedded pattern follows the tempo and the meter of its song (#355), in the same undo step. */
+/**
+ * An embedded pattern follows the tempo and the meter of its song (#355), in the same undo step. A
+ * song that picks another sound FX lets go of the one it kept to itself, in that step too.
+ */
 abstract class AssetPropertyCommand extends SetBagValueCommand<Asset> {
   private followed: { id: string; previous: PropertyValue | undefined }[] = [];
+  private settled: SetSongCommand | null = null;
 
   protected constructor(
     private readonly assetId: string,
@@ -559,9 +564,13 @@ abstract class AssetPropertyCommand extends SetBagValueCommand<Asset> {
       setBagValue(pattern.props, this.key, asset.props[this.key]);
       return { id: pattern.id, previous };
     });
+    this.settled =
+      asset.type === 'song' && this.key === ASSET_FX_KEY ? new SetSongCommand(asset.id, {}) : null;
+    this.settled?.execute(project);
   }
 
   override undo(project: Project): void {
+    this.settled?.undo(project);
     for (const { id, previous } of this.followed)
       setBagValue(requireAsset(project, id).props, this.key, previous);
     super.undo(project);

src/core/music/embedded.ts

@@ -5,6 +5,8 @@
  * track or an item. `settleEmbedded` holds a song to that after every edit, so a split, a duplicate
  * or a paste gets a copy of its own and what nothing uses any more goes.
  */
+import type { Graph } from '../graph/Graph';
+import { SOUND_FX_INPUT, SOUND_FX_OUTPUT } from '../graph/nested';
 import { newId } from '../ids';
 import type { Asset, PatternAsset, SongAsset } from '../model/Asset';
 import type { AssetType } from '../model/AssetTypes';
@@ -40,6 +42,13 @@ export function isEmbedded(asset: Asset): boolean {
   return (asset.owner ?? '') !== '';
 }
 
+/** In front of the name of what the song keeps to itself, wherever it is named. */
+export const EMBEDDED_MARK = '•';
+
+export function markedName(asset: Asset): string {
+  return isEmbedded(asset) ? `${EMBEDDED_MARK} ${asset.name}` : asset.name;
+}
+
 /** The assets a list offers: all but those a song keeps to itself. */
 export function listedAssets(project: Project): Asset[] {
   return project.assets.filter((a) => !isEmbedded(a));
@@ -93,14 +102,27 @@ export function clockFollowers(project: Project, asset: Asset, key: string): Pat
   return embeddedIn(project, asset.id).filter((a): a is PatternAsset => a.type === 'pattern');
 }
 
-/** "Pattern 1", 2, 3 …: the first number none of what the song keeps to itself has. */
-export function embeddedPatternName(project: Project, songId: string): string {
+/** "Pattern 1", 2, 3 … ("Sound FX 1" …): the first number none of what the song keeps to itself has. */
+export function embeddedName(project: Project, songId: string, base: string): string {
   return nextNumberedName(
     embeddedIn(project, songId).map((a) => a.name),
-    'Pattern',
+    base,
   );
 }
 
+/** What a sound FX made in a song starts as (#355): the Input wired to the Output, so it lets the sound through. */
+export function passThroughFxGraph(): Graph {
+  const input = newId();
+  const output = newId();
+  return {
+    nodes: [
+      { id: input, type: SOUND_FX_INPUT, x: 0, y: 0, params: {} },
+      { id: output, type: SOUND_FX_OUTPUT, x: 260, y: 0, params: {} },
+    ],
+    edges: [{ id: newId(), from: { node: input, port: 'out' }, to: { node: output, port: 'in' } }],
+  };
+}
+
 /**
  * The instrument a pattern made at `tick` on a track is played with: that of the pattern item there
  * that starts last before it, else of the first one after; '' on a track without one.

src/core/properties/assetRef.ts

@@ -1,7 +1,7 @@
 import type { Asset } from '../model/Asset';
 import { type AssetType, isPlaceableType } from '../model/AssetTypes';
 import { findAsset, type Project } from '../model/Project';
-import { listedAssets } from '../music/embedded';
+import { listedAssets, markedName } from '../music/embedded';
 import { NO_FX } from './assetFx';
 import { MASTER_BUS } from './buses';
 
@@ -9,13 +9,15 @@ export const NO_ASSET_LABEL = 'None';
 export const MASTER_LABEL = 'Master';
 
 /**
- * The asset's name, "None" for the empty id, `<id>?` when it no longer resolves – a dangling
- * reference shows its id rather than passing for an empty field.
+ * The asset's name, marked for one a song keeps to itself (#355), "None" for the empty id, `<id>?`
+ * when it no longer resolves – a dangling reference shows its id rather than passing for an empty
+ * field.
  */
 export function assetRefLabel(project: Project | null, id: string): string {
   if (id === '' || id === NO_FX) return NO_ASSET_LABEL;
   if (id === MASTER_BUS) return MASTER_LABEL;
-  return (project ? findAsset(project, id) : undefined)?.name ?? `${id}?`;
+  const asset = project ? findAsset(project, id) : undefined;
+  return asset ? markedName(asset) : `${id}?`;
 }
 
 /**

src/editor/inspector/assetSection.ts

@@ -44,6 +44,7 @@ import { findAsset, type Project } from '../../core/model/Project';
 import { isRowHiddenWhenEmbedded } from '../../core/music/embedded';
 import type { PropertyBag, PropertyValue } from '../../core/model/Properties';
 import { readScope, readSharedScope, type Scope, scopeOf, sharedScopeOf } from '../../core/model/Scope';
+import { ASSET_FX_KEY } from '../../core/properties/assetFx';
 import { type NestedKind, VARIABLE_KINDS } from '../../core/properties/kinds';
 import {
   COMMON_PROPS,
@@ -59,6 +60,7 @@ import { FontPreview } from '../font/FontPreview';
 import { clearSaved, hasSaved } from '../saves';
 import { SoundPreview } from '../sound/SoundPreview';
 import type { VariablesOwner } from '../state';
+import { ownFxEntries } from '../song/ownFx';
 import { aspectActions, sizeCommand } from './aspectAction';
 import { buildCutRows, CUT_ROW_KEYS, refreshCutRows } from './cutSection';
 import { actionIf, createFieldRow, type FieldHandlers } from './fieldFactory';
@@ -241,13 +243,20 @@ function buildProps(host: InspectorHost, asset: Asset, schema: readonly Property
   }
 }
 
-/** Previews straight into the asset while editing; the command records the value from before the preview. */
+/**
+ * Previews straight into the asset while editing; the command records the value from before the
+ * preview. A song's Sound FX may also be one of its own (#355).
+ */
 function assetHandlers(host: InspectorHost, assetId: string, def: PropertyDef): FieldHandlers {
   const spec = assetValue(host.state, assetId, def.key);
+  const isSongFx = def.key === ASSET_FX_KEY && findAsset(host.state.project, assetId)?.type === 'song';
+  const place = (id: string) => new SetAssetPropertyCommand(assetId, def.key, id);
+  const own = isSongFx ? (current: string) => ownFxEntries(host.state, assetId, current, place) : undefined;
   return {
     ...previewingHandlers<Asset>(host, spec),
     ...listSource(host, def, () => ({ kind: 'asset', assetId, key: def.key })),
     ...structFields<Asset>(host, def, spec, (path) => ({ kind: 'asset', assetId, key: def.key, path })),
+    ...(own ? { moreChoices: own } : {}),
   };
 }
 

src/editor/inspector/fieldFactory.ts

@@ -43,6 +43,7 @@ import {
   HStack,
   Label,
   Menu,
+  type MenuEntry,
   type MenuItem,
   NumberField,
   type Size,
@@ -98,6 +99,11 @@ export interface FieldHandlers {
    * what it holds.
    */
   structFieldHandlers?: (path: readonly string[], field: StructFieldDef) => FieldHandlers;
+  /**
+   * What the menu of a reference row ends with, asked on every open with the id it holds – a sound
+   * FX the song makes for that place alone (#355). Only the caller knows the place.
+   */
+  moreChoices?: (current: string) => MenuEntry[];
 }
 
 export interface FieldRow {
@@ -457,7 +463,7 @@ function referenceField(
   const labelOf = (id: string) => (id === '' ? none : ref.label(ctx.project(), id));
   const button = new Dropdown(labelOf(current));
   button.onClick = () => {
-    const items: MenuItem[] = [
+    const items: MenuEntry[] = [
       { label: none, current: current === '', onSelect: () => handlers.onChange('') },
       // Built on click, not once per row: assets are created, renamed and deleted while the
       // inspector stands. Searchable: one sliced sheet alone contributes an entry per frame.
@@ -466,6 +472,7 @@ function referenceField(
         current: choice.id === current,
         onSelect: () => handlers.onChange(choice.id),
       })),
+      ...(handlers.moreChoices?.(current) ?? []),
     ];
     new Menu(items, { searchable: true }).openBelow(button);
   };

src/editor/inspector/songSection.ts

@@ -12,6 +12,7 @@ import {
   TRACK_MAX_DB,
   TRACK_MIN_DB,
 } from '../../core/music/song';
+import { ownFxEntries } from '../song/ownFx';
 import { createFieldRow } from './fieldFactory';
 import { addNameField, addNote, addTitle, type InspectorHost } from './host';
 import { previewingHandlers } from './previewHandlers';
@@ -155,17 +156,20 @@ function buildTrack(host: InspectorHost, asset: SongAsset, track: SongTrack): vo
   addNote(host, `Track of the song "${asset.name}", ${count} ${count === 1 ? 'item' : 'items'}.`);
   addNote(host, 'Its Sound FX takes everything on it together, before its volume and pan.', 'small');
   for (const def of TRACK_ROWS) {
+    const commit = (value: SongTrack[keyof SongTrack]) =>
+      new SetSongCommand(
+        asset.id,
+        { tracks: withTrack(state.project, asset.id, track.id, { [def.key]: value }) },
+        `Set track ${def.key}`,
+      );
     const handlers = previewingHandlers<SongTrack, SongTrack[keyof SongTrack]>(host, {
       target: () => findAssetOf(state.project, asset.id, 'song')?.tracks.find((t) => t.id === track.id),
       read: (target) => target[def.key as keyof SongTrack],
       write: (target, value) => Object.assign(target, { [def.key]: value }),
-      commit: (value) =>
-        new SetSongCommand(
-          asset.id,
-          { tracks: withTrack(state.project, asset.id, track.id, { [def.key]: value }) },
-          `Set track ${def.key}`,
-        ),
+      commit,
     });
+    if (def.key === FX_ROW.key)
+      handlers.moreChoices = (current) => ownFxEntries(state, asset.id, current, commit);
     const row = createFieldRow(host, def, track[def.key as keyof SongTrack], handlers);
     host.fields.set(def.key, row);
     host.body.add(row.row);
@@ -180,17 +184,20 @@ function buildItem(host: InspectorHost, asset: SongAsset, item: SongItem, picked
   const others = picked > 1 ? ` ${picked - 1} more picked.` : '';
   addNote(host, `${ASSET_TYPE_LABELS[item.kind]} "${what}" on ${track?.name ?? 'a track'}.${others}`);
   for (const def of itemRows(item)) {
+    const commit = (value: SongItem[keyof SongItem]) =>
+      new SetSongCommand(
+        asset.id,
+        { items: withItem(state.project, asset.id, item.id, { [def.key]: value }) },
+        `Set item ${def.key}`,
+      );
     const handlers = previewingHandlers<SongItem, SongItem[keyof SongItem]>(host, {
       target: () => findAssetOf(state.project, asset.id, 'song')?.items.find((i) => i.id === item.id),
       read: (target) => target[def.key as keyof SongItem],
       write: (target, value) => Object.assign(target, { [def.key]: value }),
-      commit: (value) =>
-        new SetSongCommand(
-          asset.id,
-          { items: withItem(state.project, asset.id, item.id, { [def.key]: value }) },
-          `Set item ${def.key}`,
-        ),
+      commit,
     });
+    if (def.key === FX_ROW.key)
+      handlers.moreChoices = (current) => ownFxEntries(state, asset.id, current, commit);
     const row = createFieldRow(host, def, item[def.key as keyof SongItem], handlers);
     host.fields.set(def.key, row);
     host.body.add(row.row);

src/editor/song/SongTimeline.ts

@@ -10,10 +10,11 @@ import { CompoundCommand } from '../../core/commands/CompoundCommand';
 import { SetSongCommand, SetSongLoopCommand, type SongParts } from '../../core/commands/songCommands';
 import {
   embeddedCopy,
-  embeddedPatternName,
+  embeddedName,
   embeddedUsedBy,
   instrumentNear,
   isEmbedded,
+  markedName,
   listedAssets,
   songClockProps,
 } from '../../core/music/embedded';
@@ -70,6 +71,7 @@ import {
 } from '../music/timeView';
 import { snapDown, snapNear } from '../pattern/rollEdit';
 import type { EditorState } from '../state';
+import { ownFxEntries } from './ownFx';
 import { removeTrack } from './songActions';
 import {
   clampMove,
@@ -127,8 +129,6 @@ const SOLO_COLOR = 0xc9c23a;
 const FX_COLOR = 0x8fb8de;
 /** Height of an item's name strip; what it plays is drawn below. */
 const LABEL_STRIP = 15;
-/** In front of the name of what the song keeps to itself (#355). */
-export const EMBEDDED_MARK = '•';
 /** The letter on a lit mute, solo or FX button. */
 const DARK_LABEL = textStyle('small').clone();
 DARK_LABEL.fill = 0x30343c;
@@ -1068,7 +1068,7 @@ export class SongTimeline extends Widget {
     const start = snapDown(tick, songGrid(asset.props));
     const create = new CreateAssetCommand(
       'pattern',
-      embeddedPatternName(project, asset.id),
+      embeddedName(project, asset.id, 'Pattern'),
       {
         ...songClockProps(asset.props),
         [PATTERN_BARS_KEY]: 1,
@@ -1098,14 +1098,13 @@ export class SongTimeline extends Widget {
     return true;
   }
 
-  /** The sound FX a track goes through (#346): none, or one of the project's, by name. */
+  /** The sound FX a track goes through (#346): none, one of the project's by name, or its own (#355). */
   private openTrackFxMenu(asset: SongAsset, track: SongTrack, global: Vec2): void {
-    const set = (fx: string) =>
-      this.commit(
-        asset,
-        { tracks: asset.tracks.map((t) => (t.id === track.id ? { ...t, fx } : t)) },
-        'Set track sound FX',
-      );
+    const parts = (fx: string) => ({
+      tracks: asset.tracks.map((t) => (t.id === track.id ? { ...t, fx } : t)),
+    });
+    const place = (fx: string) => new SetSongCommand(asset.id, parts(fx), 'Set track sound FX');
+    const set = (fx: string) => this.commit(asset, parts(fx), 'Set track sound FX');
     const effects = listedAssets(this.state.project)
       .filter((a) => a.type === 'soundfx')
       .sort((a, b) => a.name.localeCompare(b.name));
@@ -1113,6 +1112,7 @@ export class SongTimeline extends Widget {
       { label: 'No sound FX', current: track.fx === '', onSelect: () => set('') },
       ...(effects.length > 0 ? [{ separator: true as const }] : []),
       ...effects.map((fx) => ({ label: fx.name, current: fx.id === track.fx, onSelect: () => set(fx.id) })),
+      ...ownFxEntries(this.state, asset.id, track.fx, place),
     ]).open(global.x, global.y);
   }
 
@@ -1247,8 +1247,7 @@ export class SongTimeline extends Widget {
   /** Its asset's name, with a mark in front for one the song keeps to itself (#355). */
   private labelOf(item: SongItem): string {
     const asset = findAsset(this.state.project, item.asset);
-    if (!asset) return 'missing';
-    return isEmbedded(asset) ? `${EMBEDDED_MARK} ${asset.name}` : asset.name;
+    return asset ? markedName(asset) : 'missing';
   }
 
   private contentOf(item: SongItem): 'notes' | 'wave' | 'none' {

src/editor/song/ownFx.ts

@@ -0,0 +1,64 @@
+/**
+ * A sound FX of its own for a song, a track or an item (#355): the entries every pick of a sound FX
+ * in a song ends with. The FX made here is kept by the song and named by that one place, so the
+ * place letting go of it takes it away (`settleEmbedded`).
+ */
+import { CreateAssetCommand, MakeProjectAssetCommand } from '../../core/commands/assetCommands';
+import type { Command } from '../../core/commands/Command';
+import { CompoundCommand } from '../../core/commands/CompoundCommand';
+import type { SoundFxAsset } from '../../core/model/Asset';
+import { findAssetOf } from '../../core/model/Project';
+import { EMBEDDED_MARK, embeddedName, passThroughFxGraph } from '../../core/music/embedded';
+import type { MenuEntry } from '../../ui';
+import type { EditorState } from '../state';
+
+/** The command that makes the place name the sound FX of this id. */
+export type FxPlace = (fxId: string) => Command;
+
+/**
+ * Its own FX with Edit and Make project asset while the place names one; else Create sound FX, and
+ * Embed a copy while it names one of the project's.
+ */
+export function ownFxEntries(
+  state: EditorState,
+  songId: string,
+  current: string,
+  place: FxPlace,
+): MenuEntry[] {
+  const project = state.project;
+  if (!findAssetOf(project, songId, 'song')) return [];
+  const picked = findAssetOf(project, current, 'soundfx');
+  if (picked?.owner === songId)
+    return [
+      { separator: true },
+      { label: `${EMBEDDED_MARK} ${picked.name}`, current: true, onSelect: () => state.openAsset(picked.id) },
+      { label: 'Edit sound FX', onSelect: () => state.openAsset(picked.id) },
+      { label: 'Make project asset', onSelect: () => state.execute(new MakeProjectAssetCommand(picked.id)) },
+    ];
+  return [
+    { separator: true },
+    { label: 'Create sound FX', onSelect: () => createOwnFx(state, songId, place) },
+    ...(picked ? [{ label: 'Embed a copy', onSelect: () => createOwnFx(state, songId, place, picked) }] : []),
+  ];
+}
+
+/**
+ * A sound FX the song keeps for the place, named there and opened right away, in one undo step: one
+ * that lets the sound through, or a copy of `from`.
+ */
+export function createOwnFx(
+  state: EditorState,
+  songId: string,
+  place: FxPlace,
+  from?: SoundFxAsset,
+): string | null {
+  const name = from?.name ?? embeddedName(state.project, songId, 'Sound FX');
+  const create = new CreateAssetCommand('soundfx', name, {}, songId);
+  const fx = create.asset as SoundFxAsset;
+  fx.graph = from ? structuredClone(from.graph) : passThroughFxGraph();
+  if (from) fx.props = structuredClone(from.props);
+  const label = from ? 'Embed a copy' : 'Create sound FX';
+  if (!state.execute(new CompoundCommand(label, [create, place(fx.id)]))) return null;
+  state.openAsset(fx.id);
+  return fx.id;
+}