@hypit/hypit 0.1.2 → 0.1.4

package/packages/studio/src/ui/stage.ts

@@ -1,4 +1,5 @@
-import type { StudioSnapshot } from "../shared.js";
+import { createArtifactPreview } from "./artifact-preview.js";
+import type { StudioArtifactView, StudioSnapshot } from "../shared.js";
 import { createOverlay } from "./overlay.js";
 import { icon, setIcon } from "./icons.js";
 import type { State, Store } from "./selection.js";
@@ -7,6 +8,8 @@ export type Stage = {
   readonly element: HTMLElement;
   /** Start or stop playback, however the request arrived. */
   toggle(): void;
+  openArtifact(artifact: StudioArtifactView): void;
+  renameArtifact(artifact: StudioArtifactView): void;
 };
 
 /**
@@ -17,19 +20,23 @@ export type Stage = {
  * drives frames, not seconds, and lands on exactly the frame the renderer would
  * photograph.
  */
-export function createStage(store: Store): Stage {
+export function createStage(store: Store, selectedArtifact: (id: string | undefined) => void): Stage {
   const element = document.createElement("section");
   element.className = "stage";
   element.innerHTML = `
     <div class="stage-heading">
       <div class="stage-title">${icon("preview")}<strong>Preview</strong></div>
+      <button type="button" class="stage-return" hidden>Back to composition</button>
     </div>
     <div class="stage-viewport">
       <div class="stage-scaler">
         <iframe title="Preview" sandbox="allow-scripts allow-same-origin" allow="autoplay"></iframe>
       </div>
     </div>
+    <input class="stage-scrubber" type="range" min="0" max="0" value="0" step="0.01" aria-label="Media time" hidden>
     <div class="stage-bar">
+      <span class="stage-time" hidden></span>
+      <div class="stage-transport">
       <button type="button" data-previous aria-label="Previous frame" title="Previous frame">
         ${icon("previous")}
       </button>
@@ -39,6 +46,7 @@ export function createStage(store: Store): Stage {
       <button type="button" data-next aria-label="Next frame" title="Next frame">
         ${icon("next")}
       </button>
+      </div>
       <button type="button" data-mute aria-label="Mute" class="stage-mute">
         <span data-mute-icon>${icon("volume")}</span>
       </button>
@@ -57,17 +65,30 @@ export function createStage(store: Store): Stage {
    * of its enter and exit, and selecting a clip lands the playhead on exactly
    * the frame where that displacement is largest.
    */
-  const measure = (clipId: string): { xPx: number; yPx: number; widthPx: number; heightPx: number } | undefined => {
+  const measure = (clipId: string): { xPx: number; yPx: number; widthPx: number; heightPx: number; stackOrder: number } | undefined => {
     const document_ = iframe.contentDocument;
     if (document_ === null) return undefined;
     const present = document_.querySelector(`[data-hypit-present-id="${CSS.escape(clipId)}"]`);
+    if (present === null) return undefined;
+    const current = store.current();
+    if (current === undefined) return undefined;
+    const frameRate = fps(current.snapshot);
+    const start = Number(present.getAttribute("data-start"));
+    const end = start + Number(present.getAttribute("data-duration"));
+    if (current.playhead.frame < Math.round(start * frameRate)
+      || current.playhead.frame >= Math.round(end * frameRate)) return undefined;
     // The present spans the whole canvas; the drawn box is its frame element.
     const drawn = present?.querySelector(`[data-hypit-element-id="${CSS.escape(`${clipId}:frame`)}"]`)
       ?? present?.querySelector("[data-hypit-element-id]");
     if (drawn === null || drawn === undefined) return undefined;
+    for (let ancestor: Element | null = drawn; ancestor !== null; ancestor = ancestor.parentElement) {
+      const style = document_.defaultView!.getComputedStyle(ancestor);
+      if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return undefined;
+    }
     const box = drawn.getBoundingClientRect();
     if (box.width === 0 && box.height === 0) return undefined;
-    return { xPx: box.left, yPx: box.top, widthPx: box.width, heightPx: box.height };
+    return { xPx: box.left, yPx: box.top, widthPx: box.width, heightPx: box.height,
+      stackOrder: Number(document_.defaultView!.getComputedStyle(present).zIndex) || 0 };
   };
 
   // The overlay is a sibling of the iframe inside the scaler, so it inherits the
@@ -152,6 +173,7 @@ export function createStage(store: Store): Stage {
   };
 
   const toggle = (): void => {
+    if (artifactPreview.selected !== undefined) { artifactPreview.toggle(); return; }
     if (state === undefined) return;
     if (playing) { stop(); return; }
     playing = true;
@@ -172,21 +194,107 @@ export function createStage(store: Store): Stage {
   };
   play.addEventListener("click", toggle);
   previous.addEventListener("click", () => {
-    if (state !== undefined) store.seek(state.playhead.frame - 1, "video");
+    if (artifactPreview.selected !== undefined) artifactPreview.seek((artifactPreview.media?.currentTime ?? 0) - 5);
+    else if (state !== undefined) store.seek(state.playhead.frame - 1, "video");
   });
   next.addEventListener("click", () => {
-    if (state !== undefined) store.seek(state.playhead.frame + 1, "video");
+    if (artifactPreview.selected !== undefined) artifactPreview.seek((artifactPreview.media?.currentTime ?? 0) + 5);
+    else if (state !== undefined) store.seek(state.playhead.frame + 1, "video");
   });
 
   const applyMuted = (): void => {
     setIcon(muteIcon, muted ? "muted" : "volume");
     mute.setAttribute("aria-label", muted ? "Unmute" : "Mute");
+    if (artifactPreview.media !== undefined) artifactPreview.media.muted = muted;
     (iframe.contentWindow as SeekWindow | null)?.__hypitSetMuted?.(muted);
   };
   mute.addEventListener("click", () => { muted = !muted; applyMuted(); });
 
+  const title = element.querySelector<HTMLElement>(".stage-title strong")!;
+  const back = element.querySelector<HTMLButtonElement>(".stage-return")!;
+  const scrubber = element.querySelector<HTMLInputElement>(".stage-scrubber")!;
+  const time = element.querySelector<HTMLElement>(".stage-time")!;
+  const transport = element.querySelector<HTMLElement>(".stage-transport")!;
+  const clock = (seconds: number): string => {
+    const ticks = Math.max(0, Math.round(seconds * 100));
+    const whole = Math.floor(ticks / 100);
+    return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}.${String(ticks % 100).padStart(2, "0")}`;
+  };
+  const artifactPreview = createArtifactPreview(() => {
+    if (artifactPreview.selected === undefined) return;
+    const media = artifactPreview.media;
+    const timed = media !== undefined;
+    const duration = media !== undefined && Number.isFinite(media.duration) ? media.duration : 0;
+    transport.hidden = !timed;
+    mute.hidden = !timed;
+    scrubber.hidden = !timed;
+    time.hidden = !timed;
+    play.disabled = duration <= 0 || media?.error != null;
+    previous.disabled = next.disabled = play.disabled;
+    scrubber.disabled = duration <= 0;
+    scrubber.step = "0.01";
+    scrubber.setAttribute("aria-label", "Media time");
+    scrubber.max = String(duration);
+    scrubber.value = String(media?.currentTime ?? 0);
+    time.textContent = `${clock(media?.currentTime ?? 0)} / ${clock(duration)}`;
+    setIcon(playIcon, media !== undefined && !media.paused ? "pause" : "play");
+    play.setAttribute("aria-label", media !== undefined && !media.paused ? "Pause" : "Play");
+  });
+  viewport.append(artifactPreview.element);
+  const compositionTime = (): void => {
+    if (state === undefined || artifactPreview.selected !== undefined) return;
+    const rate = fps(state.snapshot);
+    scrubber.hidden = time.hidden = false;
+    scrubber.disabled = !ready;
+    scrubber.step = String(1 / rate);
+    scrubber.max = String(Math.max(0, state.snapshot.space.frameCount - 1) / rate);
+    scrubber.value = String(state.playhead.frame / rate);
+    scrubber.setAttribute("aria-label", "Composition time");
+    time.textContent = `${clock(state.playhead.frame / rate)} / ${clock(state.snapshot.space.frameCount / rate)}`;
+  };
+  scrubber.addEventListener("input", () => {
+    if (artifactPreview.selected !== undefined) artifactPreview.seek(Number(scrubber.value));
+    else if (state !== undefined) store.seek(Math.round(Number(scrubber.value) * fps(state.snapshot)), "video");
+  });
+
+  const returnToComposition = (): void => {
+    artifactPreview.close();
+    selectedArtifact(undefined);
+    scaler.hidden = false;
+    back.hidden = true;
+    compositionTime();
+    transport.hidden = mute.hidden = false;
+    play.disabled = previous.disabled = next.disabled = false;
+    previous.title = "Previous frame";
+    previous.setAttribute("aria-label", previous.title);
+    next.title = "Next frame";
+    next.setAttribute("aria-label", next.title);
+    title.textContent = "Preview";
+    title.removeAttribute("title");
+    setIcon(playIcon, "play");
+    play.setAttribute("aria-label", "Play");
+    fit();
+    if (state !== undefined && ready) seekPicture(state.playhead.frame);
+  };
+  back.addEventListener("click", returnToComposition);
+
+  const openArtifact = (artifact: StudioArtifactView): void => {
+    stop();
+    scaler.hidden = true;
+    back.hidden = false;
+    title.textContent = artifact.displayName ?? artifact.output;
+    title.title = artifact.output;
+    previous.title = "Back 5 seconds";
+    next.title = "Forward 5 seconds";
+    previous.setAttribute("aria-label", previous.title);
+    next.setAttribute("aria-label", next.title);
+    artifactPreview.open(artifact, muted);
+    selectedArtifact(artifact.id);
+  };
+
   iframe.addEventListener("load", () => {
     ready = true;
+    compositionTime();
     if (state !== undefined) seekPicture(state.playhead.frame);
     applyMuted();
     // The box could not be measured until now.
@@ -197,16 +305,19 @@ export function createStage(store: Store): Stage {
 
   store.subscribe((value) => {
     const first = state === undefined;
+    const moved = state !== undefined && (state.playhead.frame !== value.playhead.frame || state.selection !== value.selection);
     state = value;
+    if (moved && value.playhead.origin !== "play" && artifactPreview.selected !== undefined) returnToComposition();
     if (value.snapshot.revision !== mounted) {
       mounted = value.snapshot.revision;
-      stop();
+      if (artifactPreview.selected === undefined) stop();
       ready = false;
       const preview = value.snapshot.preview;
       iframe.srcdoc = preview.srcdoc;
       fit();
     }
     if (first) fit();
+    compositionTime();
 
     // Playing and scrubbing are different requests: one lets material run on
     // its own clock, the other moves it. Asking a decoder for a fresh seek
@@ -227,5 +338,10 @@ export function createStage(store: Store): Stage {
     if (playing) overlay.refresh();
   });
 
-  return { element, toggle };
+  return { element, toggle, openArtifact,
+    renameArtifact(artifact) {
+      const selected = artifactPreview.selected;
+      if (selected?.build === artifact.build && selected.output === artifact.output) title.textContent = artifact.displayName ?? artifact.output;
+    },
+  };
 }

package/packages/studio/src/ui/timeline.ts

@@ -8,6 +8,7 @@ import { mountMaterialPreview } from "./material-preview.js";
 import type { State, Store } from "./selection.js";
 import { createHandle } from "./resize.js";
 import { createZoom } from "./zoom.js";
+import { chooseSemanticGesture, semanticGestureSpan } from "../temporal-edit.js";
 import { applyStudioMutation } from "./writeback.js";
 
 export type Timeline = {
@@ -17,7 +18,6 @@ export type Timeline = {
   readonly fit: () => void;
 };
 
-const opened = new Set<string>();
 const itemMetrics = {
   // Ordinary items fill their rows. Only the semantic lane owns compact word cells.
   insetYPx: 1,
@@ -221,107 +221,17 @@ export function createTimeline(store: Store): Timeline {
     readonly clip: StudioSnapshot["tracks"][number]["clips"][number];
     readonly handle: StudioEditHandle;
     readonly startFrame: number;
-    readonly pointerAnchorIndex?: number;
     readonly pointerId: number;
     readonly node: HTMLElement;
     readonly originalLeft: string;
     readonly originalWidth: string;
   } | undefined;
 
-  const nearestAnchorIndex = (
-    frame: number,
-    indices: readonly number[],
-    preferredIndex?: number,
-  ): number | undefined => {
-    if (state === undefined) return undefined;
-    const anchors = state.snapshot.semantic?.anchors ?? [];
-    const preferredKind = preferredIndex === undefined ? undefined : anchors[preferredIndex]?.kind;
-    return [...indices].sort((left, right) => {
-      const leftAnchor = anchors[left]!;
-      const rightAnchor = anchors[right]!;
-      return Math.abs(leftAnchor.frame - frame) - Math.abs(rightAnchor.frame - frame)
-        || Number(leftAnchor.kind !== preferredKind) - Number(rightAnchor.kind !== preferredKind)
-        || Math.abs(left - (preferredIndex ?? left)) - Math.abs(right - (preferredIndex ?? right))
-        || left - right;
-    })[0];
-  };
-
-  const semanticTarget = (
-    edit: NonNullable<typeof activeEdit>,
-    nextFrame: number,
-  ): { readonly kind: "selection"; readonly startAnchorId: string; readonly endAnchorId: string }
-    | { readonly kind: "moment"; readonly anchorId: string }
-    | undefined => {
-    if (state === undefined || edit.handle.semantic === undefined) return undefined;
-    const semantic = edit.handle.semantic;
-    const anchors = state.snapshot.semantic?.anchors ?? [];
-    if (semantic.kind === "moment") {
-      const currentIndex = anchors.findIndex((anchor) => anchor.id === semantic.anchorId);
-      const anchorIndex = nearestAnchorIndex(
-        nextFrame,
-        anchors.map((_, index) => index),
-        currentIndex < 0 ? undefined : currentIndex,
-      );
-      return anchorIndex === undefined ? undefined : { kind: "moment", anchorId: anchors[anchorIndex]!.id };
-    }
-    const startIndex = anchors.findIndex((anchor) => anchor.id === semantic.startAnchorId);
-    const endIndex = anchors.findIndex((anchor) => anchor.id === semantic.endAnchorId);
-    if (startIndex < 0 || endIndex < 0 || startIndex >= endIndex) return undefined;
-    let nextStart = startIndex;
-    let nextEnd = endIndex;
-    if (edit.handle.gesture === "trim-start") {
-      const allowed = anchors.flatMap((anchor, index) =>
-        index < endIndex && anchor.frame < anchors[endIndex]!.frame ? [index] : []);
-      nextStart = nearestAnchorIndex(nextFrame, allowed, startIndex) ?? startIndex;
-    } else if (edit.handle.gesture === "trim-end") {
-      const allowed = anchors.flatMap((anchor, index) =>
-        index > startIndex && anchor.frame > anchors[startIndex]!.frame ? [index] : []);
-      nextEnd = nearestAnchorIndex(nextFrame, allowed, endIndex) ?? endIndex;
-    } else if (edit.handle.gesture === "move") {
-      const instantBoundary = edit.handle.temporal?.kind === "instant"
-        && edit.handle.temporal.authority.kind === "semantic"
-        && edit.handle.temporal.authority.source.kind === "selection"
-        ? edit.handle.temporal.authority.boundary
-        : undefined;
-      if (instantBoundary === "start") {
-        const allowed = anchors.flatMap((anchor, index) =>
-          index < endIndex && anchor.frame < anchors[endIndex]!.frame ? [index] : []);
-        nextStart = nearestAnchorIndex(nextFrame, allowed, startIndex) ?? startIndex;
-        return { kind: "selection", startAnchorId: anchors[nextStart]!.id, endAnchorId: anchors[nextEnd]!.id };
-      }
-      if (instantBoundary === "end") {
-        const allowed = anchors.flatMap((anchor, index) =>
-          index > startIndex && anchor.frame > anchors[startIndex]!.frame ? [index] : []);
-        nextEnd = nearestAnchorIndex(nextFrame, allowed, endIndex) ?? endIndex;
-        return { kind: "selection", startAnchorId: anchors[nextStart]!.id, endAnchorId: anchors[nextEnd]!.id };
-      }
-      const pointerIndex = edit.pointerAnchorIndex ?? startIndex;
-      const deltas = anchors.flatMap((_, index) => {
-        const delta = index - pointerIndex;
-        const movedStart = startIndex + delta;
-        const movedEnd = endIndex + delta;
-        return movedStart >= 0 && movedEnd < anchors.length
-          && anchors[movedStart]!.frame < anchors[movedEnd]!.frame
-          ? [delta]
-          : [];
-      });
-      const targetPointer = nearestAnchorIndex(
-        nextFrame,
-        deltas.map((delta) => pointerIndex + delta),
-        pointerIndex,
-      );
-      const delta = targetPointer === undefined ? 0 : targetPointer - pointerIndex;
-      nextStart += delta;
-      nextEnd += delta;
-    } else {
-      return undefined;
-    }
-    return {
-      kind: "selection",
-      startAnchorId: anchors[nextStart]!.id,
-      endAnchorId: anchors[nextEnd]!.id,
-    };
-  };
+  const semanticTarget = (edit: NonNullable<typeof activeEdit>, nextFrame: number) =>
+    state === undefined ? undefined : chooseSemanticGesture({
+      anchors: state.snapshot.semantic?.anchors ?? [], handle: edit.handle,
+      pointerStart: edit.startFrame, pointerNow: nextFrame, frameCount: state.snapshot.space.frameCount,
+    });
 
   const absoluteWindowTarget = (
     edit: NonNullable<typeof activeEdit>,
@@ -354,40 +264,8 @@ export function createTimeline(store: Store): Timeline {
   ): { readonly startFrame: number; readonly endFrameExclusive: number } | undefined => {
     if (state === undefined) return undefined;
     const target = semanticTarget(edit, nextFrame);
-    if (target?.kind === "selection" && edit.handle.semantic?.kind === "selection") {
-      const current = state.snapshot.semantic?.selections.find((selection) => selection.id === edit.handle.semantic!.id);
-      const nextStart = state.snapshot.semantic?.anchors.find((anchor) => anchor.id === target.startAnchorId)?.frame;
-      const nextEnd = state.snapshot.semantic?.anchors.find((anchor) => anchor.id === target.endAnchorId)?.frame;
-      if (current === undefined || nextStart === undefined || nextEnd === undefined) return undefined;
-      const instantBoundary = edit.handle.temporal?.kind === "instant"
-        && edit.handle.temporal.authority.kind === "semantic"
-        && edit.handle.temporal.authority.source.kind === "selection"
-        ? edit.handle.temporal.authority.boundary
-        : undefined;
-      if (instantBoundary === "start" || instantBoundary === "end") {
-        const frame = instantBoundary === "start" ? nextStart : nextEnd;
-        return { startFrame: frame, endFrameExclusive: frame + 1 };
-      }
-      return {
-        startFrame: nextStart + edit.clip.startFrame - current.startFrame,
-        endFrameExclusive: nextEnd + edit.clip.endFrameExclusive - current.endFrameExclusive,
-      };
-    }
-    if (target?.kind === "moment" && edit.handle.semantic?.kind === "moment") {
-      const current = state.snapshot.semantic?.moments.find((moment) => moment.id === edit.handle.semantic!.id);
-      const next = state.snapshot.semantic?.anchors.find((anchor) => anchor.id === target.anchorId)?.frame;
-      if (current === undefined || next === undefined) return undefined;
-      const delta = next - current.frame;
-      if (edit.handle.gesture === "trim-start") {
-        return { startFrame: next, endFrameExclusive: edit.clip.endFrameExclusive };
-      }
-      if (edit.handle.gesture === "trim-end") {
-        return { startFrame: edit.clip.startFrame, endFrameExclusive: next };
-      }
-      return edit.handle.moveEffect === "move-start"
-        ? { startFrame: edit.clip.startFrame + delta, endFrameExclusive: edit.clip.endFrameExclusive }
-        : { startFrame: edit.clip.startFrame + delta, endFrameExclusive: edit.clip.endFrameExclusive + delta };
-    }
+    if (target !== undefined) return semanticGestureSpan(state.snapshot.semantic?.anchors ?? [], edit.handle, target);
+    if (edit.handle.semantic !== undefined) return undefined;
     return edit.handle.temporal === undefined ? undefined : absoluteWindowTarget(edit, nextFrame);
   };
   lanes.addEventListener("pointerdown", (event) => {
@@ -577,18 +455,15 @@ export function createTimeline(store: Store): Timeline {
     detail: string,
     height: number,
     attached = false,
-    hasState = false,
   ): HTMLElement => {
     const label = document.createElement("div");
-    label.className = `track-label track-${kind}${hasState ? " track-label-has-state" : ""}`;
+    label.className = `track-label track-${kind}`;
     if (attached) label.classList.add("track-label-attached");
     label.style.height = `${height}px`;
     label.title = `${name} · ${detail}`;
     label.innerHTML = `${attached
       ? '<span class="track-attachment-mark" aria-hidden="true"></span>'
-      : '<span class="track-icon"></span>'}<span class="track-copy"><strong></strong></span>${hasState
-        ? '<span class="track-state"></span>'
-        : ""}`;
+      : '<span class="track-icon"></span>'}<span class="track-copy"><strong></strong></span>`;
     if (!attached) setIcon(label.querySelector(".track-icon")!, iconName);
     label.querySelector("strong")!.textContent = name;
     return label;
@@ -604,7 +479,7 @@ export function createTimeline(store: Store): Timeline {
     .sort((left, right) => (left.binding.lane.order ?? 0) - (right.binding.lane.order ?? 0));
 
   const buildSemanticLane = (snapshot: StudioSnapshot): void => {
-    if (snapshot.semantic === undefined || snapshot.semantic.segments.length === 0) {
+    if (snapshot.semantic === undefined) {
       return;
     }
     const presentation = snapshot.semantic.presentation;
@@ -781,17 +656,6 @@ export function createTimeline(store: Store): Timeline {
     attached = false,
   ): void => {
     const tone = track.binding.tone;
-    const freeFrom: number[] = [];
-    const rowOf = new Map<string, number>();
-    for (const clip of [...track.clips].sort((a, b) => b.stackOrder - a.stackOrder || a.startFrame - b.startFrame)) {
-      let row = freeFrom.findIndex((free) => free <= clip.startFrame);
-      if (row < 0) { row = freeFrom.length; freeFrom.push(0); }
-      freeFrom[row] = clip.endFrameExclusive;
-      rowOf.set(clip.id, row);
-    }
-    const depth = Math.max(1, freeFrom.length);
-    const folded = depth > 1 && !opened.has(track.id);
-    const shownRows = folded ? 1 : depth;
     const laneHeight = track.binding.lane.heightPx;
     const displayedItems = track.clips.length;
     const label = createTrackLabel(
@@ -799,44 +663,26 @@ export function createTimeline(store: Store): Timeline {
       tone,
       track.binding.icon,
       `${displayedItems} item${displayedItems === 1 ? "" : "s"}`,
-      shownRows * laneHeight,
+      laneHeight,
       attached,
-      depth > 1,
     );
     label.classList.add(`track-facet-${track.binding.facet}`);
-    if (depth > 1) {
-      const fold = document.createElement("button");
-      fold.type = "button";
-      fold.className = "track-fold";
-      fold.textContent = folded ? `+${depth - 1}` : "−";
-      fold.title = folded ? `Show ${depth} rows` : "Collapse rows";
-      fold.setAttribute("aria-expanded", String(!folded));
-      fold.addEventListener("click", (event) => {
-        event.stopPropagation();
-        if (opened.has(track.id)) opened.delete(track.id);
-        else opened.add(track.id);
-        build(snapshot);
-        paint();
-      });
-      label.querySelector(".track-state")!.append(fold);
-    }
     labels.append(label);
 
     const lane = document.createElement("div");
     lane.className = `lane track-tone-${tone} track-facet-${track.binding.facet}${attached ? " lane-attached" : ""}`;
-    lane.style.height = `${shownRows * laneHeight}px`;
+    lane.style.height = `${laneHeight}px`;
     lane.style.setProperty("--lane-height", `${laneHeight}px`);
     const laneWidth = lanes.clientWidth;
     const materialMounts: {
       readonly target: HTMLElement;
       readonly preview: Extract<StudioSnapshot["tracks"][number]["clips"][number]["display"]["layers"][number], { readonly kind: "preview" }>["preview"];
     }[] = [];
-    for (const clip of track.clips) {
+    // Stable order preserves Companion projection order when stack levels tie.
+    for (const clip of [...track.clips].sort((a, b) => a.stackOrder - b.stackOrder)) {
       const from = place(clip.startFrame, snapshot.space.frameCount, zoom.window());
       const to = place(clip.endFrameExclusive, snapshot.space.frameCount, zoom.window());
       if (to <= 0 || from >= 1) continue;
-      const row = rowOf.get(clip.id) ?? 0;
-      if (folded && row > 0) continue;
       const node = document.createElement("button");
       node.type = "button";
       node.className = `clip clip-tone-${tone} clip-facet-${track.binding.facet} clip-chrome-${clip.presentation.chrome}`;
@@ -847,7 +693,6 @@ export function createTimeline(store: Store): Timeline {
       node.style.width = `max(2px, calc(${Math.max(0, to - from) * 100}% - ${itemMetrics.gapPx}px))`;
       const visibleWidthPx = visibleItemWidth(from, to, laneWidth);
       node.classList.toggle("clip-preview-wide", visibleWidthPx >= 92);
-      node.style.top = `${row * laneHeight}px`;
       node.title = `${clip.display.title} · ${clip.startFrame}-${clip.endFrameExclusive}f`;
       node.innerHTML = `<span class="clip-head"><span class="clip-name"></span><span class="clip-meta"></span></span><span class="clip-body"><span class="clip-layers" aria-hidden="true"></span><span class="clip-phases"></span></span><span class="clip-selection" aria-hidden="true"></span>`;
       const layers = node.querySelector<HTMLElement>(".clip-layers")!;
@@ -894,17 +739,10 @@ export function createTimeline(store: Store): Timeline {
           const pointerFrame = handle.coordinate === "semantic-anchor"
             ? rawFrameAt(event.clientX)
             : frameAt(event.clientX);
-          const pointerAnchorIndex = handle.semantic !== undefined
-            ? nearestAnchorIndex(
-                pointerFrame,
-                state?.snapshot.semantic?.anchors.map((_, index) => index) ?? [],
-              )
-            : undefined;
           activeEdit = {
             clip,
             handle,
             startFrame: pointerFrame,
-            ...(pointerAnchorIndex === undefined ? {} : { pointerAnchorIndex }),
             pointerId: event.pointerId,
             node,
             originalLeft: node.style.left,
@@ -940,8 +778,7 @@ export function createTimeline(store: Store): Timeline {
       const attachedTo = track.binding.lane.attachedTo;
       if (attachedTo !== undefined) continue;
       buildTrack(snapshot, track, nextClipNodes);
-      const slot = track.binding.lane.groupId;
-      if (slot === undefined) continue;
+      const slot = track.binding.lane.groupId ?? track.binding.groupId;
       const attachments = attachedTracks(snapshot, slot, track.binding.groupId);
       for (const attachment of attachments) {
         buildTrack(snapshot, attachment, nextClipNodes, true);

package/packages/studio/start.ts

@@ -11,9 +11,12 @@ Open a Run in the browser to inspect its composition, Sources and Results.
   hypit studio --run <build.svrun> [--runtime <hypit.runtime.json>]
     [--port <number>] [--workspace <directory>] [--package-root <directory>]
 
-Paths are relative to the invoking project. Without --runtime, Studio uses
-that project's selected Runtime Profile. The server prints its browser URL;
-press Ctrl+C to stop it.
+Relative command-line paths start at the current directory; --workspace selects
+the project, without rebasing those paths. Otherwise the nearest package.json
+above the current directory defines the project (or the current directory if none).
+Without --runtime, Studio uses that project's .hypit/runtime selection.
+The server prints its project, Run, Runtime selection and browser URL.
+Press Ctrl+C to stop it.
 `);
 }
 
@@ -76,6 +79,15 @@ export async function runStudio(argv: readonly string[], io: Pick<CliIo, "write"
   const runtimePath = runtimeArgument === undefined
     ? selectedRuntime?.profile
     : resolve(invokedFrom, runtimeArgument);
+  console.info([
+    `  Project            ${workspaceRoot}`,
+    `  Run                ${runPath}`,
+    `  Runtime Profile    ${runtimePath ?? "not selected"}`,
+    `  Runtime selection  ${runtimeArgument !== undefined
+      ? "command argument (this session only)" : selectedRuntime?.selectionFile ?? "none"}`,
+    ...(packageRoot === workspaceRoot ? [] : [`  Package root       ${packageRoot}`]),
+    "",
+  ].join("\n"));
   const port = Number(values.get("port") ?? "5179");
   if (!Number.isSafeInteger(port) || port <= 0) invalidArguments("--port must be a positive integer");
 

package/packages/studio-adapter/README.md

@@ -48,6 +48,22 @@ nominal output Type and authored input names of the component. A Companion does
 author attribute. Omitting `project` uses generic terminal entities; `poster` adds the declared
 Surface preview when one exists, without changing the component's rendered video.
 
+Each lane occupies one timeline row. Entities overlap in ascending `stackOrder`,
+with later projected entities above earlier ones when orders tie. Studio keeps
+overlapping entities mounted and raises the selected entity within its lane;
+selection does not change the rendered composition or write stacking back to Source.
+Expose `presentId` or `renderIds` for visual entities so picture selection can
+address the same entity shown in the timeline. Attached lanes represent distinct
+Companion projections, not extra rows allocated to avoid temporal overlap.
+
+An entity's timeline interval describes the operation being edited; its rendered
+parts may remain visible afterward. Associate every relevant phase through
+`renderIds` (for example, an entrance and the settled object). Studio picks the
+currently visible part in rendered stacking order and selects the same entity,
+without extending its editable interval. Give the parent the board or background
+parts and its children their own parts when they should be independently selectable.
+The component decides this granularity. A composite can remain one selectable entity.
+
 Merge the facet into the package's existing activation. In this example `authorContribution`
 exports its existing modules, deterministic component and Markup facets:
 
@@ -168,6 +184,11 @@ silently becoming one policy. Studio resolves the declarations against the
 current Source closure, publishes only real writable fields, renders all DOM
 and CSS itself, and commits changes through `parameter.adjust`.
 
+Fields can declare `number` display scaling, supported suffixes, limits and step; `unit` alone is
+only a label. Select options can carry separate scalar values, labels, descriptions and color/font
+preview hints. Text may be multiline; colors may offer package-chosen swatches. See
+[Inspector presentation and conversion](../studio/INSPECTOR.md) for examples and ownership.
+
 Structured controls keep a local draft and commit one complete canonical value.
 Their codec is the author language (`@hypit/svs` for Recipe values), not a
 Companion callback. Companions cannot inject DOM, CSS, parsing code or filesystem

package/packages/studio-adapter/src/index.ts

@@ -122,6 +122,24 @@ export const studioParameterControls = [
 export type StudioParameterControl = typeof studioParameterControls[number];
 export type StudioParameterLanguage = "svml" | "svs" | "svrun";
 
+/** Data-only choices. Packages supply meaning; Studio owns all option rendering. */
+export type StudioParameterOption = string | {
+  readonly value: string | number | boolean;
+  readonly label: string;
+  readonly description?: string;
+  readonly preview?: { readonly kind: "color"; readonly color: string }
+    | { readonly kind: "font"; readonly family: string; readonly sample?: string };
+};
+
+/** Displayed number = authored number × scale. Suffixes are retained, never converted. */
+export type StudioNumberPresentation = {
+  readonly scale?: number;
+  readonly suffixes?: readonly string[];
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly step?: number;
+};
+
 /** A real author endpoint. Its existence never implies Inspector visibility. */
 export type StudioSourceBinding = {
   readonly id: string;
@@ -170,8 +188,12 @@ export type StudioInspectorFieldDeclaration = {
   readonly summary?: string;
   /** Omit when the binding's public schema selects the finite Studio control. */
   readonly control?: StudioParameterControl;
-  readonly options?: readonly string[];
+  readonly options?: readonly StudioParameterOption[];
   readonly unit?: string;
+  readonly number?: StudioNumberPresentation;
+  readonly multiline?: boolean;
+  /** Optional suggested colors, independent of the accepted color value. */
+  readonly swatches?: readonly string[];
 };
 
 /** Resolved Inspector DTO. Studio renders it and executes its exact source write. */
@@ -308,6 +330,7 @@ export type StudioEntityDisplay = {
 };
 
 export type StudioLaneDescription = {
+  /** Height of this single timeline lane; overlapping entities share it. */
   readonly heightPx: number;
   readonly groupId?: string;
   readonly attachedTo?: string;
@@ -482,10 +505,12 @@ export type StudioEntityDraft = {
   readonly display: StudioEntityDisplay;
   readonly startFrame: number;
   readonly endFrameExclusive: number;
+  /** Back-to-front timeline order. Ties preserve projection order. Selection raises only the timeline item. */
   readonly stackOrder: number;
   readonly elementRange?: Range;
   readonly markerId?: string;
   readonly presentId?: string;
+  /** Rendered parts belonging to this entity, including phases beyond its editable timeline interval. */
   readonly renderIds?: readonly string[];
   /** Resolved author references that differ per derived entity, such as one Cue's actual Style. */
   readonly parameterReferences?: Readonly<Record<string, string>>;