Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

40.1 KB
Raw Blame
import { userText, uiAttribute, uiText, uiAttr } from "./i18n.js";
import type { StudioSnapshot } from "../shared.js";
import type { StudioEditHandle } from "@hypit/studio-companion";
import { icon, setIcon } from "./icons.js";
import { mountMaterialPreview } from "./material-preview.js";
import type { State, Store } from "./selection.js";
import { createHandle } from "./resize.js";
import { createZoom } from "./zoom.js";
import { chooseDomainGesture, domainGestureSpan } from "../temporal-edit.js";
import { applyStudioMutation } from "./writeback.js";

export type Timeline = {
  readonly element: HTMLElement;
  readonly zoomIn: () => void;
  readonly zoomOut: () => void;
  readonly fit: () => void;
};

const itemMetrics = {
  // Ordinary items fill their rows. Temporal-domain lanes may own compact cells.
  insetYPx: 1,
  headerPx: 15,
  contentCellPx: 18,
  gapPx: 1,
} as const;

const labelFont = '500 11px -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif';
const textMeasure = document.createElement("canvas").getContext("2d");
const textWidths = new Map<string, number>();
const wordLabelPaddingPx = 5;
const wordLabelEnterBufferPx = 1;

function measuredText(value: string, font = labelFont): number {
  const key = `${font}\u0000${value}`;
  const cached = textWidths.get(key);
  if (cached !== undefined) return cached;
  if (textMeasure === null) return Array.from(value).length * 7;
  textMeasure.font = font;
  const width = textMeasure.measureText(value).width;
  textWidths.set(key, width);
  return width;
}

function timecode(seconds: number): string {
  const whole = Math.floor(seconds);
  return `${String(Math.floor(whole / 60)).padStart(2, "0")}:${String(whole % 60).padStart(2, "0")}`;
}

function frameTickLabel(frame: number): string {
  return `${frame}f`;
}

function frameSteps(frameRate: number): readonly number[] {
  const result: number[] = [];
  for (let candidate = 1; candidate <= frameRate; candidate += 1) {
    if (frameRate % candidate === 0) result.push(candidate);
  }
  return result;
}

function place(frame: number, frameCount: number, shown: { start: number; end: number }): number {
  const span = Math.max(1e-6, shown.end - shown.start);
  return (frame / Math.max(1, frameCount) - shown.start) / span;
}

function displayTrackName(track: StudioSnapshot["tracks"][number]): string {
  if (track.binding.label !== undefined) return track.binding.label;
  return track.label;
}

function visibleItemWidth(
  from: number,
  to: number,
  laneWidth: number,
): number {
  const visibleFrom = Math.max(0, from);
  const visibleTo = Math.min(1, to);
  return Math.max(0, visibleTo - visibleFrom) * laneWidth;
}

export function createTimeline(store: Store): Timeline {
  const element = document.createElement("section");
  element.className = "timeline";
  element.style.setProperty("--timeline-item-inset-y", `${itemMetrics.insetYPx}px`);
  element.style.setProperty("--timeline-item-header-height", `${itemMetrics.headerPx}px`);
  element.style.setProperty("--timeline-content-cell-height", `${itemMetrics.contentCellPx}px`);
  element.innerHTML = `
    <div class="timeline-toolbar">
      <div class="timeline-tools">
        <button type="button" class="tool-button active" ${uiAttribute("aria-label", "timeline.select")} ${uiAttribute("title", "timeline.select")}>${icon("select")}</button>
      </div>
      <div class="timeline-time" data-timeline-time>00:00:00</div>
      <div class="timeline-view-actions">
        <button type="button" class="icon-button" data-zoom-out ${uiAttribute("aria-label", "timeline.zoom-out")} ${uiAttribute("title", "timeline.zoom-out")}>${icon("minus")}</button>
        <button type="button" class="icon-button" data-zoom-fit ${uiAttribute("aria-label", "timeline.fit-timeline")} ${uiAttribute("title", "timeline.fit-timeline")}>${icon("fit")}</button>
        <button type="button" class="icon-button" data-zoom-in ${uiAttribute("aria-label", "timeline.zoom-in")} ${uiAttribute("title", "timeline.zoom-in")}>${icon("plus")}</button>
      </div>
    </div>
    <div class="timeline-body" data-timeline-body>
      <div class="timeline-labels" data-labels></div>
      <div class="timeline-lanes" data-lanes>
        <div class="ruler" data-ruler><div class="playhead-grip" data-playhead-grip></div></div>
        <div class="lanes" data-rows></div>
        <div class="timeline-hover" data-hover aria-hidden="true"><span data-hover-time></span></div>
        <div class="playhead" data-playhead></div>
      </div>
    </div>
    <div class="timeline-zoom" data-zoom></div>`;

  const labels = element.querySelector<HTMLElement>("[data-labels]")!;
  const body = element.querySelector<HTMLElement>("[data-timeline-body]")!;
  const lanes = element.querySelector<HTMLElement>("[data-lanes]")!;
  const ruler = element.querySelector<HTMLElement>("[data-ruler]")!;
  const rows = element.querySelector<HTMLElement>("[data-rows]")!;
  const hover = element.querySelector<HTMLElement>("[data-hover]")!;
  const hoverTime = element.querySelector<HTMLElement>("[data-hover-time]")!;
  const playhead = element.querySelector<HTMLElement>("[data-playhead]")!;
  const playheadGrip = element.querySelector<HTMLElement>("[data-playhead-grip]")!;
  const timelineTime = element.querySelector<HTMLElement>("[data-timeline-time]")!;
  const zoom = createZoom();
  element.querySelector<HTMLElement>("[data-zoom]")!.append(zoom.element);

  // The label column is part of the timeline's reading surface, not a fixed
  // application chrome width.  Keep enough room for the longest built-in
  // facet name while leaving a usable canvas, and remember the author's choice.
  const labelHandle = createHandle({
    axis: "column",
    initial: 188,
    minimum: 156,
    // createTimeline is constructed before it is attached to the document, so
    // clientWidth is initially zero. Keep the preferred default valid during
    // that first pass; on a real viewport the canvas-aware ceiling applies,
    // with 260px as the hard visual cap on a wide timeline.
    maximum: () => Math.min(260, Math.max(188, body.clientWidth - 360)),
    apply: (size) => { element.style.setProperty("--timeline-label-width", `${size}px`); },
    remember: "hypit-studio.v4.timeline-label-width",
  });
  labelHandle.classList.add("timeline-label-handle");
  uiAttr(labelHandle, "aria-label", "timeline.resize-timeline-track-labels");
  uiAttr(labelHandle, "title", "timeline.resize-track-labels");
  body.insertBefore(labelHandle, lanes);

  let state: State | undefined;
  let built = -1;
  let paintFrame = 0;
  let rebuildFrame = 0;
  let selectedWord: string | undefined;
  let overlapMenu: HTMLElement | undefined;
  const closeOverlapMenu = () => { overlapMenu?.remove(); overlapMenu = undefined; };
  element.addEventListener("pointerdown", event => {
    if (!overlapMenu?.contains(event.target as Node)) closeOverlapMenu();
  });
  element.addEventListener("keydown", event => { if (event.key === "Escape") closeOverlapMenu(); });
  body.addEventListener("scroll", closeOverlapMenu);
  let itemNodes: readonly {
    readonly node: HTMLElement;
    readonly start: number;
    readonly end: number;
    readonly id: string;
    readonly selectionGroup?: string;
  }[] = [];
  let domainNodes: readonly {
    readonly node: HTMLElement;
    readonly companion: string;
    readonly domainId: string;
    readonly id: string;
    readonly start: number;
    readonly end: number;
    readonly kind: "span" | "point";
    readonly appearance: "block" | "compact" | "marker";
  }[] = [];
  const readableWordLabels = new Set<string>();

  const playheadFraction = (): number => {
    if (state === undefined) return 0.5;
    const shown = zoom.window();
    const at = state.playhead.frame / Math.max(1, state.snapshot.timeline.frameCount);
    return Math.max(0, Math.min(1, (at - shown.start) / Math.max(1e-6, shown.end - shown.start)));
  };
  const zoomOut = (): void => zoom.pinch(playheadFraction(), 1.25);
  const zoomIn = (): void => zoom.pinch(playheadFraction(), 0.8);
  const fit = (): void => zoom.fit();
  element.querySelector<HTMLButtonElement>("[data-zoom-out]")!.addEventListener("click", zoomOut);
  element.querySelector<HTMLButtonElement>("[data-zoom-in]")!.addEventListener("click", zoomIn);
  element.querySelector<HTMLButtonElement>("[data-zoom-fit]")!.addEventListener("click", fit);

  const fps = (snapshot: StudioSnapshot): number =>
    snapshot.timeline.frameRate.numerator / snapshot.timeline.frameRate.denominator;

  const snapFrame = (frame: number): number => {
    if (state === undefined || lanes.clientWidth <= 0) return frame;
    const shown = zoom.window();
    const threshold = Math.max(1, Math.ceil(
      (shown.end - shown.start) * state.snapshot.timeline.frameCount / lanes.clientWidth * 6,
    ));
    let nearest = frame;
    let distance = threshold + 1;
    const consider = (candidate: number): void => {
      const next = Math.abs(candidate - frame);
      if (next < distance) { nearest = candidate; distance = next; }
    };
    for (const anchor of state.snapshot.temporalDomains.flatMap((domain) => domain.anchors)) consider(anchor.frame);
    for (const item of state.snapshot.tracks.flatMap((track) => track.items)) {
      consider(item.startFrame);
      consider(item.endFrameExclusive);
    }
    return distance <= threshold ? nearest : frame;
  };

  const rawFrameAt = (clientX: number): number => {
    const box = lanes.getBoundingClientRect();
    if (box.width === 0 || state === undefined) return 0;
    const across = Math.max(0, Math.min(1, (clientX - box.left) / box.width));
    const shown = zoom.window();
    return Math.floor(
      (shown.start + across * (shown.end - shown.start)) * state.snapshot.timeline.frameCount,
    );
  };
  const frameAt = (clientX: number): number => snapFrame(rawFrameAt(clientX));

  const frameTimecode = (snapshot: StudioSnapshot, frame: number): string => {
    const rate = Math.max(1, Math.round(fps(snapshot)));
    const seconds = Math.floor(frame / fps(snapshot));
    return `${String(Math.floor(seconds / 60)).padStart(2, "0")}:${String(seconds % 60).padStart(2, "0")}:${String(frame % rate).padStart(2, "0")}`;
  };

  let pointerArmed = false;
  let pointerDownX = 0;
  let pointerDownOnItem = false;
  let activeEdit: {
    readonly item: StudioSnapshot["tracks"][number]["items"][number];
    readonly handle: StudioEditHandle;
    readonly startFrame: number;
    readonly pointerId: number;
    readonly node: HTMLElement;
    readonly originalLeft: string;
    readonly originalWidth: string;
  } | undefined;

  const editDomain = (snapshot: StudioSnapshot, handle: StudioEditHandle) => handle.domain === undefined
    ? undefined
    : snapshot.temporalDomains.find((domain) => domain.companion === handle.domain!.companion
      && domain.id === handle.domain!.domainId);

  const domainTarget = (edit: NonNullable<typeof activeEdit>, nextFrame: number) =>
    state === undefined ? undefined : chooseDomainGesture({
      anchors: editDomain(state.snapshot, edit.handle)?.anchors ?? [], handle: edit.handle,
      pointerStart: edit.startFrame, pointerNow: nextFrame, frameCount: state.snapshot.timeline.frameCount,
    });

  const absoluteWindowTarget = (
    edit: NonNullable<typeof activeEdit>,
    nextFrame: number,
  ): { readonly startFrame: number; readonly endFrameExclusive: number } => {
    if (state === undefined) return {
      startFrame: edit.item.startFrame,
      endFrameExclusive: edit.item.endFrameExclusive,
    };
    const rawDelta = nextFrame - edit.startFrame;
    const delta = Math.max(-edit.item.startFrame,
      Math.min(state.snapshot.timeline.frameCount - edit.item.endFrameExclusive, rawDelta));
    if (edit.handle.gesture === "move") return {
      startFrame: edit.item.startFrame + delta,
      endFrameExclusive: edit.item.endFrameExclusive + delta,
    };
    if (edit.handle.gesture === "trim-start") return {
      startFrame: Math.min(edit.item.endFrameExclusive - 1, nextFrame),
      endFrameExclusive: edit.item.endFrameExclusive,
    };
    return {
      startFrame: edit.item.startFrame,
      endFrameExclusive: Math.max(edit.item.startFrame + 1, nextFrame),
    };
  };

  const previewWindow = (
    edit: NonNullable<typeof activeEdit>,
    nextFrame: number,
  ): { readonly startFrame: number; readonly endFrameExclusive: number } | undefined => {
    if (state === undefined) return undefined;
    const target = domainTarget(edit, nextFrame);
    if (target !== undefined) return domainGestureSpan(editDomain(state.snapshot, edit.handle)?.anchors ?? [], edit.handle, target);
    if (edit.handle.domain !== undefined) return undefined;
    return edit.handle.temporal === undefined ? undefined : absoluteWindowTarget(edit, nextFrame);
  };
  lanes.addEventListener("pointerdown", (event) => {
    pointerDownOnItem = (event.target as HTMLElement).closest(
      ".studio-item, .temporal-domain-block, .temporal-domain-compact, .temporal-domain-point",
    ) !== null;
    pointerDownX = event.clientX;
    pointerArmed = true;
    // Let temporal-domain children receive their native click. Capturing every
    // pointer here retargets the later click to `.lanes`, which made segment
    // and selection buttons appear to be dead zones. Blank-space scrubbing
    // still uses capture so it can continue outside the lane.
    if (!pointerDownOnItem) {
      try { lanes.setPointerCapture(event.pointerId); } catch { /* pointer remains local */ }
    }
    if (!pointerDownOnItem) {
      store.clearSelection();
      store.seek(frameAt(event.clientX), "timeline");
    }
  });
  lanes.addEventListener("pointermove", (event) => {
    const frame = frameAt(event.clientX);
    const at = place(frame, state?.snapshot.timeline.frameCount ?? 1, zoom.window()) * lanes.clientWidth;
    hover.style.transform = `translate3d(${at}px,0,0)`;
    hoverTime.textContent = state === undefined ? "" : frameTimecode(state.snapshot, frame);
    hover.classList.add("visible");
    if (activeEdit !== undefined && state !== undefined) {
      const nextFrame = activeEdit.handle.coordinate === "domain-anchor"
        ? rawFrameAt(event.clientX)
        : frameAt(event.clientX);
      const preview = previewWindow(activeEdit, nextFrame);
      if (preview !== undefined) {
        const from = place(preview.startFrame, state.snapshot.timeline.frameCount, zoom.window());
        const to = place(preview.endFrameExclusive, state.snapshot.timeline.frameCount, zoom.window());
        activeEdit.node.style.left = `${from * 100}%`;
        activeEdit.node.style.width = `max(2px, ${Math.max(0, to - from) * 100}%)`;
      }
      return;
    }
    if (!pointerArmed || event.buttons !== 1) return;
    if (pointerDownOnItem && Math.abs(event.clientX - pointerDownX) < 3) return;
    store.seek(frame, "timeline");
  });
  const finishPointer = (event: PointerEvent): void => {
    const edit = activeEdit;
    activeEdit = undefined;
    edit?.node.classList.remove("editing");
    if (edit !== undefined) {
      edit.node.style.left = edit.originalLeft;
      edit.node.style.width = edit.originalWidth;
    }
    pointerArmed = false;
    try { lanes.releasePointerCapture(event.pointerId); } catch { /* already released */ }
    if (edit === undefined || state === undefined || event.type === "pointercancel") return;
    const nextFrame = edit.handle.coordinate === "domain-anchor"
      ? rawFrameAt(event.clientX)
      : frameAt(event.clientX);
    const resolvedDomainTarget = domainTarget(edit, nextFrame);
    const resolvedWindow = previewWindow(edit, nextFrame);
    if (resolvedWindow === undefined || edit.handle.temporal === undefined) return;
    const target = edit.handle.temporal.kind === "instant"
      ? {
          kind: "instant" as const,
          frame: resolvedWindow.startFrame,
          ...(resolvedDomainTarget === undefined ? {} : { domain: resolvedDomainTarget }),
        }
      : {
          kind: "window" as const,
          ...resolvedWindow,
          ...(resolvedDomainTarget === undefined ? {} : { domain: resolvedDomainTarget }),
        };
    if (resolvedDomainTarget?.kind === "span"
      && edit.handle.domain?.kind === "span"
      && resolvedDomainTarget.startAnchorId === edit.handle.domain.startAnchorId
      && resolvedDomainTarget.endAnchorId === edit.handle.domain.endAnchorId
      && (target.kind === "instant"
        ? target.frame === edit.item.startFrame
        : target.startFrame === edit.item.startFrame && target.endFrameExclusive === edit.item.endFrameExclusive)) return;
    if (resolvedDomainTarget?.kind === "point"
      && edit.handle.domain?.kind === "point"
      && resolvedDomainTarget.anchorId === edit.handle.domain.anchorId
      && (target.kind === "instant"
        ? target.frame === edit.item.startFrame
        : target.startFrame === edit.item.startFrame && target.endFrameExclusive === edit.item.endFrameExclusive)) return;
    if (resolvedDomainTarget === undefined
      && (target.kind === "instant"
        ? target.frame === edit.item.startFrame
        : target.startFrame === edit.item.startFrame && target.endFrameExclusive === edit.item.endFrameExclusive)) return;
    element.dispatchEvent(new CustomEvent("studio:write", { detail: { state: "saving" } }));
    void applyStudioMutation({
      type: "timeline.adjust",
      revision: state.snapshot.revision,
      itemId: edit.item.id,
      gesture: edit.handle.gesture,
      target,
    }).then(() => {
      element.dispatchEvent(new CustomEvent("studio:write", { detail: { state: "saved" } }));
    }).catch((error: unknown) => {
      // The next snapshot/error event is the source of truth; a failed gesture
      // must never be represented by a local optimistic rectangle.
      console.error(error);
      element.dispatchEvent(new CustomEvent("studio:write", { detail: { state: "error" } }));
    });
  };
  lanes.addEventListener("pointerup", finishPointer);
  lanes.addEventListener("pointercancel", finishPointer);
  lanes.addEventListener("pointerleave", () => {
    if (!pointerArmed) hover.classList.remove("visible");
  });

  const drawRuler = (snapshot: StudioSnapshot): void => {
    ruler.replaceChildren();
    const frameCount = Math.max(1, snapshot.timeline.frameCount);
    const shown = zoom.window();
    const visibleFrames = Math.max(1, (shown.end - shown.start) * frameCount);
    const widthPx = Math.max(1, lanes.clientWidth);
    const exactRate = Math.max(1, fps(snapshot));
    const rate = Math.max(1, Math.round(exactRate));
    const pxPerFrame = widthPx / visibleFrames;
    const pxPerSecond = pxPerFrame * exactRate;
    const startFrame = shown.start * frameCount;
    const endFrame = shown.end * frameCount;
    const startSecond = startFrame / exactRate;
    const endSecond = endFrame / exactRate;

    const context = document.createElement("span");
    context.className = "ruler-context";
    context.textContent = timecode(startSecond);
    ruler.append(context);

    const secondCandidates = [1, 2, 5, 10, 15, 30, 60, 120];
    const majorSeconds = secondCandidates.find((candidate) => candidate * pxPerSecond >= 112)
      ?? secondCandidates.at(-1)!;
    const firstSecond = Math.max(0, Math.ceil(startSecond - 1e-6));
    const lastSecond = Math.min(Math.floor(snapshot.timeline.durationSec), Math.floor(endSecond + 1e-6));
    for (let seconds = firstSecond; seconds <= lastSecond; seconds += 1) {
      const frame = Math.min(frameCount, Math.round(seconds * exactRate));
      const at = place(frame, frameCount, shown);
      if (at < 0 || at > 1) continue;
      const major = Math.abs(seconds / majorSeconds - Math.round(seconds / majorSeconds)) < 1e-6;
      const tick = document.createElement("span");
      tick.className = `tick tick-second ${major ? "tick-major" : "tick-minor"}${at > 0.94 ? " tick-last" : ""}`;
      tick.style.left = `${at * 100}%`;
      tick.textContent = major && at * widthPx >= 52 ? timecode(seconds) : "";
      ruler.append(tick);
    }

    const steps = frameSteps(rate);
    // A full-project ruler stays quiet. Once a second occupies enough screen
    // space, minor frame marks enter before their labels. Both densities are
    // selected from the same frame lattice, only with different pixel budgets.
    const tickStep = pxPerSecond < 120
      ? rate
      : steps.find((candidate) => candidate * pxPerFrame >= 18) ?? rate;
    const labelStep = steps.find((candidate) => candidate * pxPerFrame >= 68) ?? rate;
    const firstFrame = Math.max(0, Math.ceil(startFrame));
    const lastFrame = Math.min(frameCount, Math.floor(endFrame));
    for (let frame = firstFrame; frame <= lastFrame; frame += 1) {
      const withinSecond = ((frame % rate) + rate) % rate;
      if (withinSecond === 0) continue;
      const at = place(frame, frameCount, shown);
      if (at < 0 || at > 1) continue;
      if (withinSecond % tickStep === 0) {
        const tick = document.createElement("span");
        tick.className = `tick tick-subdivision${tickStep === 1 ? " tick-frame" : ""}`;
        tick.style.left = `${at * 100}%`;
        ruler.append(tick);
      }
      if (labelStep < rate && withinSecond % labelStep === 0 && at * widthPx >= 52) {
        const label = document.createElement("span");
        label.className = "tick-frame-label";
        label.style.left = `${at * 100}%`;
        label.textContent = frameTickLabel(withinSecond);
        ruler.append(label);
      }
    }
    // The ruler is sticky while tracks scroll. Keeping the grip inside it makes
    // the current-time marker remain attached to the scale instead of leaving
    // its head behind at the top of the scrolled track stack.
    ruler.append(playheadGrip);
  };

  const createTrackLabel = (
    name: string,
    kind: string,
    iconName: string,
    detail: string,
    height: number,
    attached = false,
  ): HTMLElement => {
    const label = document.createElement("div");
    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>`;
    if (!attached) setIcon(label.querySelector(".track-icon")!, iconName);
    label.querySelector("strong")!.textContent = name;
    return label;
  };

  const attachedTracks = (
    snapshot: StudioSnapshot,
    slot: string,
    groupId?: string,
  ): readonly StudioSnapshot["tracks"][number][] => snapshot.tracks
    .filter((track) => track.binding.lane.attachedTo === slot
      && (groupId === undefined || track.binding.groupId === groupId))
    .sort((left, right) => (left.binding.lane.order ?? 0) - (right.binding.lane.order ?? 0));


  const buildTemporalDomainLane = (
    snapshot: StudioSnapshot,
    domain: StudioSnapshot["temporalDomains"][number],
    group: HTMLElement,
    insetTop: number,
    insetBottom: number,
  ): void => {
    if (domain.lanes.length === 0) return;
    const laneHeight = domain.lanes.reduce((height, lane) => height + lane.heightPx, insetTop + insetBottom);
    const lane = document.createElement("div");
    lane.className = `lane temporal-domain-lane track-tone-${domain.presentation.tone}`;
    lane.style.height = `${laneHeight}px`;
    const bands = new Map<string, HTMLElement>();
    let bandTop = insetTop;
    for (const description of domain.lanes) {
      const band = document.createElement("div");
      band.className = "temporal-domain-band";
      band.style.top = `${bandTop}px`;
      band.style.setProperty("--temporal-domain-band-height", `${description.heightPx}px`);
      band.setAttribute("aria-label", description.label ?? description.id);
      bands.set(description.id, band);
      lane.append(band);
      bandTop += description.heightPx;
    }
    const nextNodes: typeof domainNodes[number][] = [];
    for (const item of domain.items) {
      const band = bands.get(item.laneId);
      if (band === undefined) continue;
      const start = item.kind === "point" ? item.frame : item.startFrame;
      const end = item.kind === "point" ? item.frame + 1 : item.endFrameExclusive;
      const from = place(start, snapshot.timeline.frameCount, zoom.window());
      const to = place(end, snapshot.timeline.frameCount, zoom.window());
      if (to <= 0 || from >= 1) continue;
      const node = item.appearance === "compact" ? document.createElement("span") : document.createElement("button");
      if (node instanceof HTMLButtonElement) node.type = "button";
      node.className = item.kind === "point" ? "temporal-domain-point"
        : item.appearance === "compact" ? "temporal-domain-cell temporal-domain-compact"
        : "temporal-domain-cell temporal-domain-block";
      node.style.left = `${from * 100}%`;
      if (item.kind === "span") node.style.width = `max(${item.appearance === "compact" ? 1 : 2}px, ${Math.max(0, to - from) * 100}%)`;
      node.title = item.label;
      node.setAttribute("aria-label", item.label);
      if (item.kind === "span") {
        const content = document.createElement("span");
        content.className = "temporal-domain-cell-content";
        const text = document.createElement("span");
        text.className = item.appearance === "compact" ? "temporal-domain-compact-label" : "temporal-domain-block-label";
        text.textContent = item.label;
        content.append(text);
        node.append(content);
        if (item.appearance === "compact") {
          const widthPx = Math.max(1, (to - from) * lanes.clientWidth);
          const textWidthPx = measuredText(item.label);
          const identity = `${domain.companion}:${domain.id}:${item.id}`;
          const fitsCell = widthPx - wordLabelPaddingPx * 2 >= textWidthPx
            + (readableWordLabels.has(identity) ? 0 : wordLabelEnterBufferPx);
          if (fitsCell) readableWordLabels.add(identity);
          else readableWordLabels.delete(identity);
          const fitsViewport = from >= 0
            && from * lanes.clientWidth + wordLabelPaddingPx * 2 + textWidthPx <= lanes.clientWidth;
          node.classList.toggle("word-label-visible", fitsCell && fitsViewport);
        }
      }
      node.addEventListener("click", (event) => {
        event.stopPropagation();
        if (item.appearance === "compact") {
          store.clearSelection();
          selectedWord = `${domain.companion}:${domain.id}:${item.id}`;
        } else {
          store.selectTemporalDomainItem(domain.companion, domain.id, item.id, "timeline");
        }
        store.seek(start, "timeline");
      });
      if (item.kind === "span" && item.appearance !== "compact") node.addEventListener("dblclick", (event) => {
        event.stopPropagation();
        zoom.focus(item.startFrame / Math.max(1, snapshot.timeline.frameCount),
          item.endFrameExclusive / Math.max(1, snapshot.timeline.frameCount));
      });
      band.append(node);
      nextNodes.push({ node, companion: domain.companion, domainId: domain.id, id: item.id,
        start, end, kind: item.kind, appearance: item.appearance });
    }
    lane.addEventListener("contextmenu", (event) => {
      const hits = nextNodes.filter(({ node }) => {
        const rect = node.getBoundingClientRect();
        return event.clientX >= rect.left && event.clientX < rect.right
          && event.clientY >= rect.top && event.clientY < rect.bottom;
      });
      if (hits.length < 2) return;
      event.preventDefault();
      closeOverlapMenu();
      const menu = document.createElement("div");
      menu.className = "timeline-overlap-menu";
      menu.setAttribute("role", "menu");
      uiAttr(menu, "aria-label", "timeline.overlapping-timeline-objects");
      for (const hit of [...hits].reverse()) {
        const option = document.createElement("button");
        option.type = "button";
        option.setAttribute("role", "menuitem");
        option.textContent = hit.node.getAttribute("aria-label") ?? hit.id;
        option.addEventListener("click", () => { closeOverlapMenu(); hit.node.click(); });
        menu.append(option);
      }
      element.append(menu);
      menu.style.left = `${Math.max(0, Math.min(event.clientX, window.innerWidth - menu.offsetWidth - 8))}px`;
      menu.style.top = `${Math.max(0, Math.min(event.clientY, window.innerHeight - menu.offsetHeight - 8))}px`;
      overlapMenu = menu;
      menu.querySelector("button")?.focus();
    });
    group.append(lane);
    domainNodes = [...domainNodes, ...nextNodes];
  };

  const buildTrack = (
    snapshot: StudioSnapshot,
    track: StudioSnapshot["tracks"][number],
    nextItemNodes: { node: HTMLElement; start: number; end: number; id: string; selectionGroup?: string }[],
    attached = false,
  ): void => {
    const totalHeight = track.binding.lane.heightPx;
    const tone = track.binding.tone;
    const displayedItems = track.items.length;
    const label = createTrackLabel(
      displayTrackName(track),
      tone,
      track.binding.icon,
      `${displayedItems} item${displayedItems === 1 ? "" : "s"}`,
      totalHeight,
      attached,
    );
    label.classList.add(`track-facet-${track.binding.facet}`);
    labels.append(label);

    const trackBody = document.createElement("div");
    trackBody.className = "timeline-track";
    trackBody.dataset.track = track.id;
    trackBody.style.height = `${totalHeight}px`;
    const materialMounts: {
      readonly target: HTMLElement;
      readonly preview: Extract<StudioSnapshot["tracks"][number]["items"][number]["display"]["layers"][number], { readonly kind: "preview" }>["preview"];
    }[] = [];
    const lane = document.createElement("div");
    lane.className = `lane track-tone-${tone} track-facet-${track.binding.facet}${attached ? " lane-attached" : ""}`;
    lane.style.height = `${totalHeight}px`;
    lane.style.setProperty("--lane-height", `${totalHeight}px`);
    const laneWidth = lanes.clientWidth;
    // Stable order preserves Companion projection order when stack levels tie.
    for (const item of [...track.items].sort((a, b) => a.stackOrder - b.stackOrder)) {
        const from = place(item.startFrame, snapshot.timeline.frameCount, zoom.window());
        const to = place(item.endFrameExclusive, snapshot.timeline.frameCount, zoom.window());
        if (to <= 0 || from >= 1) continue;
        const node = document.createElement("button");
        node.type = "button";
        node.className = `studio-item studio-item-tone-${tone} studio-item-facet-${track.binding.facet} studio-item-chrome-${item.presentation.chrome}`;
        node.classList.toggle("studio-item-editable", item.editHandles.some((handle) => handle.enabled));
        node.dataset.item = item.id;
        node.setAttribute("aria-label", item.display.title);
        node.style.left = `${from * 100}%`;
        node.style.width = `max(2px, ${Math.max(0, to - from) * 100}%)`;
        const visibleWidthPx = visibleItemWidth(from, to, laneWidth);
        node.classList.toggle("studio-item-preview-wide", visibleWidthPx >= 92);
        node.title = `${item.display.title} · ${item.startFrame}-${item.endFrameExclusive}f`;
        node.innerHTML = `<span class="studio-item-head"><span class="studio-item-name"></span><span class="studio-item-meta"></span></span><span class="studio-item-body"><span class="studio-item-layers" aria-hidden="true"></span></span><span class="studio-item-boundary" aria-hidden="true"></span><span class="studio-item-selection" aria-hidden="true"></span>`;
        const layers = node.querySelector<HTMLElement>(".studio-item-layers")!;
        item.display.layers.forEach((layer, index) => {
          const layerNode = document.createElement("span");
          layerNode.className = `studio-item-layer studio-item-layer-${layer.kind} studio-item-layer-role-${layer.role}`;
          layerNode.style.zIndex = String(index + 1);
          if (layer.kind === "text") {
            layerNode.textContent = layer.text;
          } else {
            layerNode.classList.add(`studio-item-layer-layout-${layer.layout}`);
            materialMounts.push({ target: layerNode, preview: layer.preview });
          }
          layers.append(layerNode);
        });
        const metaText = item.presentation.chrome === "point"
          ? `${(item.startFrame / fps(snapshot)).toFixed(2)}s`
          : `${((item.endFrameExclusive - item.startFrame) / fps(snapshot)).toFixed(2)}s`;
        const headerLabel = node.querySelector<HTMLElement>(".studio-item-name")!;
        node.querySelector(".studio-item-meta")!.textContent = metaText;
        headerLabel.textContent = item.display.title;
        node.addEventListener("pointerdown", (event) => {
          const rect = node.getBoundingClientRect();
          const edge = Math.min(8, Math.max(4, rect.width / 3));
          const nearStart = event.clientX - rect.left <= edge;
          const nearEnd = rect.right - event.clientX <= edge;
          const handle = item.editHandles.find((candidate) =>
            candidate.enabled
            && ((candidate.gesture === "trim-start" && nearStart)
              || (candidate.gesture === "trim-end" && nearEnd)
              || (candidate.gesture === "move" && !nearStart && !nearEnd)));
          if (handle !== undefined
            && (handle.gesture === "move" || handle.gesture === "trim-start" || handle.gesture === "trim-end")) {
            event.stopPropagation();
            const pointerFrame = handle.coordinate === "domain-anchor"
              ? rawFrameAt(event.clientX)
              : frameAt(event.clientX);
            activeEdit = {
              item,
              handle,
              startFrame: pointerFrame,
              pointerId: event.pointerId,
              node,
              originalLeft: node.style.left,
              originalWidth: node.style.width,
            };
            node.classList.add("editing");
            try { lanes.setPointerCapture(event.pointerId); } catch { /* local pointer */ }
            store.select(item.id, "timeline");
            return;
          }
          store.select(item.id, "timeline");
        });
        node.addEventListener("dblclick", () => store.seek(item.startFrame, "timeline"));
        nextItemNodes.push({ node, start: item.startFrame, end: item.endFrameExclusive, id: item.id, ...(item.selectionGroup === undefined ? {} : { selectionGroup: item.selectionGroup }) });
      lane.append(node);
    }
    trackBody.append(lane);
    rows.append(trackBody);
    // Cached storyboards render synchronously and need connected, measurable targets.
    for (const item of materialMounts) mountMaterialPreview(item.target, item.preview);
  };

  const build = (snapshot: StudioSnapshot): void => {
    closeOverlapMenu();
    const scrollTop = body.scrollTop;
    labels.replaceChildren();
    rows.replaceChildren();
    domainNodes = [];
    const temporalDomains = snapshot.temporalDomains.filter((domain) => domain.lanes.length > 0);
    if (temporalDomains.length > 0) {
      const temporalHeight = temporalDomains.reduce((height, domain) => height
        + domain.lanes.reduce((domainHeight, lane) => domainHeight + lane.heightPx, 0), itemMetrics.insetYPx * 2);
      const temporalLabel = createTrackLabel("", "teal", "brand", "", temporalHeight);
      userText(temporalLabel.querySelector("strong")!, "Timeline");
      temporalLabel.title = `${temporalDomains.reduce((count, domain) => count + domain.items.length, 0)} temporal items`;
      temporalLabel.classList.add("track-label-temporal-domain");
      temporalLabel.style.height = `calc(var(--timeline-ruler-height) + ${temporalHeight}px)`;
      labels.append(temporalLabel);
    } else {
      const corner = document.createElement("div");
      corner.className = "label-corner";
      userText(corner, "");
      labels.append(corner);
    }
    if (temporalDomains.length > 0) {
      const group = document.createElement("div");
      group.className = "temporal-domain-group";
      temporalDomains.forEach((domain, index) => buildTemporalDomainLane(
        snapshot,
        domain,
        group,
        index === 0 ? itemMetrics.insetYPx : 0,
        index === temporalDomains.length - 1 ? itemMetrics.insetYPx : 0,
      ));
      rows.append(group);
    }
    const nextItemNodes: { node: HTMLElement; start: number; end: number; id: string; selectionGroup?: string }[] = [];
    for (const track of snapshot.tracks) {
      const attachedTo = track.binding.lane.attachedTo;
      if (attachedTo !== undefined) continue;
      buildTrack(snapshot, track, nextItemNodes);
      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, nextItemNodes, true);
      }
    }
    itemNodes = nextItemNodes;
    drawRuler(snapshot);
    // Replacing every row briefly collapses the scroll surface. Preserve the
    // vertical reading position when a horizontal pan rebuilds the window.
    body.scrollTop = scrollTop;
  };

  const paint = (): void => {
    if (state === undefined) return;
    const { snapshot, selection, playhead: head } = state;
    const position = place(head.frame, snapshot.timeline.frameCount, zoom.window()) * lanes.clientWidth;
    if (head.origin === "play" && position > lanes.clientWidth * 0.88 && zoom.window().end < 0.9999) {
      zoom.slide(Math.max(0.25, position / Math.max(1, lanes.clientWidth) - 0.18));
      return;
    }
    playhead.style.transform = `translate3d(${position}px,0,0)`;
    playheadGrip.style.transform = `translate3d(${position - 5}px,0,0)`;
    playhead.classList.toggle("outside", position < 0 || position > lanes.clientWidth);
    playheadGrip.classList.toggle("outside", position < 0 || position > lanes.clientWidth);
    timelineTime.textContent = frameTimecode(snapshot, head.frame);
    const chosen = selection.kind === "item" ? store.item(selection.itemId) : undefined;
    for (const item of itemNodes) {
      const selected = chosen !== undefined && (chosen.id === item.id
        || (chosen.selectionGroup !== undefined && chosen.selectionGroup === item.selectionGroup));
      item.node.classList.toggle("selected", selected);
      item.node.setAttribute("aria-pressed", String(selected));
      item.node.classList.toggle("live", head.frame >= item.start && head.frame < item.end);
    }
    for (const item of domainNodes) {
      const inside = item.kind === "span" && head.frame >= item.start && head.frame < item.end;
      item.node.classList.toggle("live", inside && item.appearance !== "compact");
      item.node.classList.toggle("current", inside && item.appearance === "compact");
      const identity = `${item.companion}:${item.domainId}:${item.id}`;
      const selected = (item.appearance === "compact" && selectedWord === identity && selection.kind === "none")
        || (selection.kind === "temporal-domain" && selection.companion === item.companion
          && selection.domainId === item.domainId && selection.itemId === item.id);
      item.node.classList.toggle("selected", selected);
      if (item.appearance !== "compact") item.node.setAttribute("aria-pressed", String(selected));
    }
  };

  const schedulePaint = (): void => {
    if (paintFrame !== 0) return;
    paintFrame = requestAnimationFrame(() => {
      paintFrame = 0;
      paint();
    });
  };

  const scheduleBuild = (): void => {
    if (rebuildFrame !== 0 || state === undefined) return;
    rebuildFrame = requestAnimationFrame(() => {
      rebuildFrame = 0;
      if (state === undefined) return;
      build(state.snapshot);
      paint();
    });
  };

  lanes.addEventListener("wheel", (event) => {
    if (event.ctrlKey || event.metaKey || event.altKey) {
      event.preventDefault();
      const box = lanes.getBoundingClientRect();
      const at = box.width === 0 ? 0.5 : (event.clientX - box.left) / box.width;
      zoom.pinch(at, Math.exp(event.deltaY * 0.004));
      return;
    }
    if (event.shiftKey || Math.abs(event.deltaX) > Math.abs(event.deltaY)) {
      event.preventDefault();
      const delta = event.shiftKey ? event.deltaY : event.deltaX;
      zoom.slide(delta / Math.max(1, lanes.clientWidth));
    }
  }, { passive: false });

  zoom.subscribe(scheduleBuild);
  store.subscribe((value) => {
    state = value;
    if (value.selection.kind !== "none") selectedWord = undefined;
    if (value.snapshot.revision !== built) {
      built = value.snapshot.revision;
      build(value.snapshot);
    }
    schedulePaint();
  });
  const resizeObserver = new ResizeObserver(() => {
    if (state !== undefined) scheduleBuild();
  });
  resizeObserver.observe(element);
  resizeObserver.observe(lanes);

  return { element, zoomIn, zoomOut, fit };
}