Add a timeline strip with playback controls and keyframe editing to the menu editor

apps/spindle/src/components/menus/ButtonInspector.tsx

@@ -11,6 +11,7 @@ import type {
 	MenuHighlightColours,
 	Title,
 	Menu,
+	MenuDocument,
 	MenuDomain,
 	TextStyle,
 	FontEntry,
@@ -41,6 +42,8 @@ export function ButtonInspector({
 	buttonPreviewState,
 	onButtonPreviewStateChange,
 	availableFonts,
+	document,
+	onAddKeyframeAtPlayhead,
 }: {
 	button: MenuButton;
 	buttonNode: Extract<SceneNode, { type: 'button' }>;
@@ -59,7 +62,13 @@ export function ButtonInspector({
 	buttonPreviewState: ButtonVisualState;
 	onButtonPreviewStateChange?: (state: ButtonVisualState) => void;
 	availableFonts?: FontEntry[];
+	/** Authored document — used to summarise this button's animation tracks. */
+	document?: MenuDocument | null;
+	/** Add a highlight-colour keyframe at the current preview playhead. */
+	onAddKeyframeAtPlayhead?: (buttonId: string) => void;
 }) {
+	const animationTracks = (document?.animation ?? []).filter((t) => t.nodeId === button.id);
+	const keyframeCount = animationTracks.reduce((sum, t) => sum + t.keyframes.length, 0);
 	const isDefault = defaultFocusId === button.id;
 
 	return (
@@ -248,20 +257,37 @@ export function ButtonInspector({
 				);
 			})()}
 
-			{/* Highlight */}
-			<CollapsibleSection title="Highlight Mode" defaultOpen>
-				<select
-					className="inspector-panel__select"
-					value={button.highlightMode}
-					onChange={(e) =>
-						onUpdateButton(button.id, {
-							highlightMode: e.target.value as 'static' | 'animated',
-						})
-					}
-				>
-					<option value="static">Static</option>
-					<option value="animated">Animated</option>
-				</select>
+			{/* Highlight animation — driven by `document.animation` tracks; edited
+			    on the timeline strip below the canvas, not here. */}
+			<CollapsibleSection title="Highlight Animation" defaultOpen>
+				<p className="inspector-panel__hint text-muted">
+					{keyframeCount === 0
+						? 'No animated highlight yet. Add a keyframe to start one, then drag and edit it on the timeline.'
+						: `${keyframeCount} keyframe${keyframeCount === 1 ? '' : 's'} across ${animationTracks.length} track${
+								animationTracks.length === 1 ? '' : 's'
+							} — edit on the timeline below the canvas.`}
+				</p>
+				{onAddKeyframeAtPlayhead &&
+					(() => {
+						const isMotion = document?.backgroundMode === 'motion';
+						return (
+							<div className="inspector-panel__actions-row">
+								<button
+									type="button"
+									className="btn btn--sm btn--ghost"
+									onClick={() => onAddKeyframeAtPlayhead(button.id)}
+									disabled={!isMotion}
+									title={
+										isMotion
+											? 'Add a highlight-colour keyframe at the current preview playhead'
+											: 'Keyframe animation requires a motion background — set the background mode to Motion first'
+									}
+								>
+									Add keyframe at playhead
+								</button>
+							</div>
+						);
+					})()}
 			</CollapsibleSection>
 
 			{/* Overlay Colours */}

apps/spindle/src/components/menus/InspectorPanel.tsx

@@ -111,6 +111,10 @@ export interface InspectorPanelProps {
 	formatProfile?: FormatProfile;
 	/** Reassign the current menu's semantic role. */
 	onUpdateRole?: (role: MenuRole) => void;
+	/** Add a highlight-colour keyframe for a button at the current preview
+	 * playhead position — the "Add keyframe at playhead" affordance in
+	 * `ButtonInspector`'s Highlight Animation row. */
+	onAddKeyframeAtPlayhead?: (buttonId: string) => void;
 }
 
 export function InspectorPanel({
@@ -156,6 +160,7 @@ export function InspectorPanel({
 	availableFonts,
 	formatProfile,
 	onUpdateRole,
+	onAddKeyframeAtPlayhead,
 }: InspectorPanelProps) {
 	const inspectorTitle = getInspectorTitle(selectedNode, selectedButton);
 	const inspectorSubtitle = getInspectorSubtitle(selectedNode, selectedButton, buttons);
@@ -241,6 +246,8 @@ export function InspectorPanel({
 						buttonPreviewState={buttonPreviewState ?? 'normal'}
 						onButtonPreviewStateChange={onButtonPreviewStateChange}
 						availableFonts={availableFonts}
+						document={document ?? null}
+						onAddKeyframeAtPlayhead={onAddKeyframeAtPlayhead}
 					/>
 				) : selectedNode.type === 'text' ? (
 					<TextNodeInspector

apps/spindle/src/components/menus/MenuEditor.test.ts

@@ -0,0 +1,51 @@
+// Tests for `collectSubtreeNodeIds`, the helper that finds every id in a
+// scene node's own subtree (itself plus, for a `group`, every descendant).
+//
+// (c) Copyright 2026 Liminal HQ, Scott Morris
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from 'vitest';
+import type { SceneNode } from '../../types/project';
+import { collectSubtreeNodeIds } from './MenuEditor';
+
+describe('collectSubtreeNodeIds', () => {
+	it('returns just its own id for a leaf node', () => {
+		const shape: SceneNode = { type: 'shape', id: 'shape-1', x: 0, y: 0, width: 10, height: 10 };
+		expect(collectSubtreeNodeIds(shape)).toEqual(['shape-1']);
+	});
+
+	it('collects a group and all of its direct children', () => {
+		const group: SceneNode = {
+			type: 'group',
+			id: 'group-1',
+			name: 'Group',
+			children: [
+				{ type: 'shape', id: 'child-1', x: 0, y: 0, width: 10, height: 10 },
+				{ type: 'text', id: 'child-2', content: 'hi', x: 0, y: 0, width: 10, height: 10 },
+			],
+		};
+		expect(collectSubtreeNodeIds(group)).toEqual(['group-1', 'child-1', 'child-2']);
+	});
+
+	it('recurses into nested groups', () => {
+		// Regression test: deleting a top-level group removes its whole child
+		// subtree from `scene.nodes`, so the animation-track cleanup must walk
+		// the same subtree — not just the group's own id — or a deeply nested
+		// child's track is orphaned and trips `menu.animation-node-missing`.
+		const nested: SceneNode = {
+			type: 'group',
+			id: 'outer',
+			name: 'Outer',
+			children: [
+				{
+					type: 'group',
+					id: 'inner',
+					name: 'Inner',
+					children: [{ type: 'shape', id: 'leaf', x: 0, y: 0, width: 10, height: 10 }],
+				},
+				{ type: 'shape', id: 'sibling', x: 0, y: 0, width: 10, height: 10 },
+			],
+		};
+		expect(collectSubtreeNodeIds(nested)).toEqual(['outer', 'inner', 'leaf', 'sibling']);
+	});
+});