fix(timeline): size a keyboard-created region by the zoom too

Reported on rc.8: adding a pill on a 30-minute recording still produced
something invisible, hidden behind the playhead it was created at.

The previous commit scaled only the toolbar buttons, because the zoom lives in
V4Timeline's local `nav` state and the shortcuts are handled in NewEditorShell.
That was the wrong line to draw: the empty lanes advertise the shortcut ("Press
Z to add zoom") and the buttons are labelled "Add Zoom (Z)", so the keyboard is
how most regions actually get created — and it kept the flat 2 s, which is 0.8px
at 0.42 px/s. Measured in a browser on the reported case (30 min across a 761px
panel): the button asked for 94.6 s, the shortcut for 2 s.

The rule now lives in timeline/newRegionDuration, outside the component: the
timeline publishes its scale (px per second) and both creation paths read it at
the moment the user acts. Module state read imperatively, never subscribed —
the value changes on every zoom notch and nothing renders it, so a subscription
would re-render the whole editor shell for a number only a keypress reads. Same
reasoning as playheadSec() in useTimeline.

Reading it at CLICK time rather than at render time also drops a one-notch
staleness: the old handler captured the duration computed by the render that
preceded the effect publishing the new scale.

Verified in a real browser, both paths: 761px / 1800 s → 94.61 s → a pill 40.0px
wide, identical for the button and for what the shortcut passes. Unit-tested in
newRegionDuration.test.ts, including the invariant that duration × scale is
PILL_CREATE_PX at any zoom.

Author: EtienneLescot

src/components/ai-edition/NewEditorShell.tsx

@@ -23,6 +23,7 @@ import {
 import { useUndoRedoShortcuts } from "@/lib/ai-edition/store/undo";
 import { useSequentialTimelineOps } from "@/lib/ai-edition/store/useSequentialTimelineOps";
 import { useTimeline } from "@/lib/ai-edition/store/useTimeline";
+import { newRegionDurationSec } from "@/lib/ai-edition/timeline/newRegionDuration";
 import { matchesShortcut } from "@/lib/shortcuts";
 import { nativeBridgeClient } from "@/native";
 import type { AiEditionProjectSummary } from "@/native/contracts";
@@ -911,29 +912,34 @@ export function NewEditorShell() {
 				deleteSelection();
 				return;
 			}
+			// Same size on screen as the toolbar buttons produce — these shortcuts are
+			// what the empty lanes advertise ("Press Z to add zoom"), so they are the
+			// way most regions get created. Left on the flat default they came out
+			// under two pixels on a 30-minute recording, hidden behind the playhead
+			// they were created at. See timeline/newRegionDuration.
 			if (matchesShortcut(e, shortcuts.addZoom, isMac)) {
 				e.preventDefault();
-				void tl.addZoom();
+				void tl.addZoom(newRegionDurationSec());
 				return;
 			}
 			if (matchesShortcut(e, shortcuts.addTrim, isMac)) {
 				e.preventDefault();
-				void tl.addTrim();
+				void tl.addTrim(newRegionDurationSec());
 				return;
 			}
 			if (matchesShortcut(e, shortcuts.addAnnotation, isMac)) {
 				e.preventDefault();
-				void tl.addAnnotation();
+				void tl.addAnnotation(newRegionDurationSec());
 				return;
 			}
 			if (matchesShortcut(e, shortcuts.addSpeed, isMac)) {
 				e.preventDefault();
-				void tl.addSpeed();
+				void tl.addSpeed(newRegionDurationSec());
 				return;
 			}
 			if (matchesShortcut(e, shortcuts.addCameraFullscreen, isMac)) {
 				e.preventDefault();
-				void tl.addCameraFullscreen();
+				void tl.addCameraFullscreen(newRegionDurationSec());
 				return;
 			}
 

src/components/ai-edition/v4/V4Timeline.tsx

@@ -39,6 +39,10 @@ import { useChatPromptBus } from "@/lib/ai-edition/store/useChatPromptBus";
 import { useEditorSettings } from "@/lib/ai-edition/store/useEditorSettings";
 import type { useTimeline } from "@/lib/ai-edition/store/useTimeline";
 import { formatSec } from "@/lib/ai-edition/timeline/format";
+import {
+	newRegionDurationSec,
+	setTimelineScale,
+} from "@/lib/ai-edition/timeline/newRegionDuration";
 import { ventilateSpanAcrossClips } from "@/lib/ai-edition/timeline/region-ventilation";
 import { coalesceRegionsForRuler } from "@/lib/ai-edition/timeline/timelineMap";
 import {
@@ -125,25 +129,9 @@ const PILL_HANDLE_OUT_PX = PILL_HANDLE_PX + PILL_MOVE_GAP_PX;
 const PILL_CONTENT_MIN_PX = 34;
 /** Edge-snap radius while dragging a pill, in screen px. */
 const PILL_SNAP_PX = 8;
-/**
- * Width a pill created from the toolbar aims for on screen. Its DURATION is
- * whatever that width is worth at the current zoom: dezoomed you get a long
- * region, zoomed in a short one, and either way a pill you can see, read and
- * grab the moment it appears.
- *
- * A fixed 2 s did the opposite — on a 65-minute timeline zoomed out it is half a
- * pixel. It only ever looked usable because the old 1.5%-of-the-timeline minimum
- * width inflated it in the RENDERING, which is the lie this branch removed. Same
- * intent, honest implementation: the width now comes from the duration actually
- * stored, so what you see is what the effect covers.
- *
- * Sized to clear PILL_CONTENT_MIN_PX, so a new pill shows its icon and label
- * immediately with room left to grab either handle.
- */
-const PILL_CREATE_PX = 40;
-/** Floor on that duration. Only bites past ~30x zoom, where 40px is worth a few
- *  hundredths of a second and the region would be born unusable. */
-const PILL_CREATE_MIN_SEC = 0.25;
+// The size a newly created pill aims for (PILL_CREATE_PX) lives in
+// timeline/newRegionDuration, because the keyboard shortcuts create regions too
+// and they are handled in NewEditorShell, outside this component.
 /** Visual separation between two clip cards. Taken off each clip's own width
  *  (see .tlClip) rather than inserted between them, so it cannot displace the
  *  clips that follow — which is what a flex `gap` did, once per junction. */
@@ -470,13 +458,13 @@ export function V4Timeline({
 	// `total`, which is a duration in disguise and so scales with the recording.
 	const navSpan = Math.max(0.02, nav.end - nav.start);
 	const pxPerSec = viewportWidthPx / navSpan / total;
-	// Duration handed to the toolbar's create buttons, so the pill they produce is
-	// PILL_CREATE_PX wide whatever the zoom. Only THIS path scales: the keyboard
-	// shortcuts and the agent keep useTimeline's flat default, since neither knows
-	// the zoom (`nav` is local state here). Before the panel is measured there is
-	// no zoom to read, so the default stands.
-	const createDurationSec =
-		pxPerSec > 0 ? Math.max(PILL_CREATE_MIN_SEC, PILL_CREATE_PX / pxPerSec) : undefined;
+	// Publish the scale so the keyboard shortcuts (NewEditorShell) size a new
+	// region exactly like the buttons below do — `nav` never leaves this
+	// component, so without this they fall back to a flat default and a pill
+	// created with `Z` comes out invisible on a long recording.
+	useEffect(() => {
+		setTimelineScale(pxPerSec);
+	}, [pxPerSec]);
 
 	// ── region lanes ────────────────────────────────────────────────
 	// zoom/speed/annotation: one pill per row, never coalesced — each carries
@@ -1339,9 +1327,12 @@ export function V4Timeline({
 								title={tool.label}
 								aria-label={tool.label}
 								onClick={() => {
-									if (tool.id === "speed") void tl.addSpeed(createDurationSec);
-									if (tool.id === "comment") void tl.addAnnotation(createDurationSec);
-									if (tool.id === "cut") void tl.addTrim(createDurationSec);
+									// Read at CLICK time: a render-time value would be one zoom
+									// notch stale when the user zooms and immediately creates.
+									const dur = newRegionDurationSec();
+									if (tool.id === "speed") void tl.addSpeed(dur);
+									if (tool.id === "comment") void tl.addAnnotation(dur);
+									if (tool.id === "cut") void tl.addTrim(dur);
 								}}
 							>
 								{tool.icon}
@@ -1352,7 +1343,7 @@ export function V4Timeline({
 							className={styles.tlToolBtn}
 							title={t("buttons.addZoom")}
 							aria-label={t("buttons.addZoom")}
-							onClick={() => void tl.addZoom(createDurationSec)}
+							onClick={() => void tl.addZoom(newRegionDurationSec())}
 						>
 							<ZoomIn size={15} />
 						</button>
@@ -1375,7 +1366,7 @@ export function V4Timeline({
 							className={styles.tlToolBtn}
 							title={t("buttons.addCameraFullscreen")}
 							aria-label={t("buttons.addCameraFullscreen")}
-							onClick={() => void tl.addCameraFullscreen(createDurationSec)}
+							onClick={() => void tl.addCameraFullscreen(newRegionDurationSec())}
 						>
 							<Maximize2 size={15} />
 						</button>

src/lib/ai-edition/timeline/newRegionDuration.test.ts

@@ -0,0 +1,50 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+	newRegionDurationSec,
+	PILL_CREATE_MIN_SEC,
+	PILL_CREATE_PX,
+	setTimelineScale,
+} from "./newRegionDuration";
+
+describe("newRegionDurationSec", () => {
+	beforeEach(() => setTimelineScale(0));
+
+	it("trades duration for a constant width", () => {
+		// The reported case: 30 minutes across a ~760px panel is 0.42 px/s, where a
+		// flat 2 s region is under a pixel — invisible behind the playhead it was
+		// created at. At that scale 40px is worth a minute and a half.
+		setTimelineScale(760 / 1800);
+		expect(newRegionDurationSec()).toBeCloseTo(94.7, 1);
+
+		// Zoom in 50x and the same gesture creates a region 50x shorter — the pill
+		// on screen is the same size either way, which is the whole point.
+		setTimelineScale((760 / 1800) * 50);
+		expect(newRegionDurationSec()).toBeCloseTo(1.89, 2);
+	});
+
+	it("stays at the floor when the pixels are worth almost nothing", () => {
+		// 40px of a 3-second clip zoomed to the ceiling: without the floor the
+		// region would be born a few hundredths of a second long.
+		setTimelineScale(10_000);
+		expect(newRegionDurationSec()).toBe(PILL_CREATE_MIN_SEC);
+	});
+
+	it("says nothing at all before the timeline has been measured", () => {
+		// First paint, or no timeline mounted: callers fall back to their own
+		// default rather than deriving a length from a width of zero.
+		expect(newRegionDurationSec()).toBeUndefined();
+		setTimelineScale(Number.NaN);
+		expect(newRegionDurationSec()).toBeUndefined();
+		setTimelineScale(Number.POSITIVE_INFINITY);
+		expect(newRegionDurationSec()).toBeUndefined();
+	});
+
+	it("keeps the width it promises", () => {
+		for (const pxPerSec of [0.2, 1, 7.5, 120]) {
+			setTimelineScale(pxPerSec);
+			const width = (newRegionDurationSec() as number) * pxPerSec;
+			// Above the floor the duration is exactly PILL_CREATE_PX worth of time.
+			expect(width).toBeCloseTo(PILL_CREATE_PX, 6);
+		}
+	});
+});

src/lib/ai-edition/timeline/newRegionDuration.ts

@@ -0,0 +1,52 @@
+/**
+ * How long a region should be when the USER creates one, so the pill they get is
+ * always the same comfortable size on screen.
+ *
+ * A 30-minute recording has to fit the panel's width, so the default view is
+ * heavily dezoomed — around 0.4 px per second. A fixed 2 s region is under a
+ * pixel there: invisible, and hidden behind the very playhead it was created at.
+ * What has to stay constant is the WIDTH; the duration is whatever that width is
+ * worth at the current zoom, which is why it can be 95 s zoomed out and 2 s
+ * zoomed in for the same gesture.
+ *
+ * (A flat 2 s only ever looked right because the old 1.5%-of-the-timeline
+ * minimum pill width inflated it in the RENDERING — the lie removed in #233.)
+ *
+ * This lives outside the timeline component because BOTH ways of creating a
+ * region must agree: the toolbar buttons in V4Timeline and the keyboard
+ * shortcuts in NewEditorShell, which the empty lanes advertise ("Press Z to add
+ * zoom") and which have no other access to the zoom — `nav` is local state
+ * inside V4Timeline. Paths that are not a user placing a pill by hand (the
+ * agent, auto-zooms) don't call this and keep useTimeline's flat default.
+ */
+
+/** On-screen width a freshly created pill aims for. Clears PILL_CONTENT_MIN_PX,
+ *  so it shows its icon and label at once with room to grab either handle. */
+export const PILL_CREATE_PX = 40;
+/** Floor on the duration. Only bites past ~30x zoom, where 40px is worth a few
+ *  hundredths of a second and the region would be born unusable. */
+export const PILL_CREATE_MIN_SEC = 0.25;
+
+/**
+ * The timeline's current scale, in px per timeline-second.
+ *
+ * Module state, written by the one timeline that exists and read IMPERATIVELY at
+ * the instant a region is created — deliberately not a store subscription. The
+ * value changes on every zoom notch and nothing renders it, so subscribing would
+ * re-render the whole editor shell for a number only a click ever reads. Same
+ * reasoning as `playheadSec()` in useTimeline.
+ */
+let pxPerSec = 0;
+
+export function setTimelineScale(value: number): void {
+	pxPerSec = Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * Duration to create a region with, or `undefined` while the timeline has not
+ * been measured yet (first paint, or no timeline mounted) — callers then fall
+ * back to their own default rather than inventing a length from a width of zero.
+ */
+export function newRegionDurationSec(): number | undefined {
+	return pxPerSec > 0 ? Math.max(PILL_CREATE_MIN_SEC, PILL_CREATE_PX / pxPerSec) : undefined;
+}