@hypit/hypit 0.0.1 → 0.1.1

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

@@ -0,0 +1,178 @@
+import type { Clip, StudioSnapshot } from "../shared.js";
+
+/**
+ * Which pane the user acted in. Panes ignore events they originated, which is
+ * the only thing keeping timeline, code and picture from driving each other in
+ * a loop.
+ */
+export type Origin = "timeline" | "code" | "video";
+
+export type Selection =
+  | { readonly kind: "none" }
+  | { readonly kind: "clip"; readonly clipId: string; readonly origin: Origin }
+  | { readonly kind: "semantic-segment"; readonly segmentId: string; readonly origin: Origin }
+  | { readonly kind: "semantic-selection"; readonly selectionId: string; readonly origin: Origin }
+  | { readonly kind: "semantic-moment"; readonly momentId: string; readonly origin: Origin };
+
+export type Playhead = { readonly frame: number; readonly origin: Origin | "play" };
+
+export type State = {
+  readonly snapshot: StudioSnapshot;
+  readonly selection: Selection;
+  readonly playhead: Playhead;
+};
+
+export type Store = {
+  /** Undefined until the first snapshot arrives. */
+  current(): State | undefined;
+  clip(clipId: string): Clip | undefined;
+  /** Clips covering a frame, topmost track first. */
+  clipsAt(frame: number): readonly Clip[];
+  load(snapshot: StudioSnapshot): void;
+  /** Select without moving the playhead; timeline inspection must not destroy position. */
+  select(clipId: string, origin: Origin): void;
+  /** Select one authored SemanticTake without moving the playhead. */
+  selectSemanticSegment(segmentId: string, origin: Origin): void;
+  /** Select one authored Selection marker without moving the playhead. */
+  selectSemanticSelection(selectionId: string, origin: Origin): void;
+  /** Select one authored Moment marker without moving the playhead. */
+  selectSemanticMoment(momentId: string, origin: Origin): void;
+  /** Select and seek to the clip start, used by source navigation. */
+  selectClip(clipId: string, origin: Origin): void;
+  /**
+   * Look at one instant, optionally selecting a clip there. Used when the thing
+   * an author pointed at is a Script range rather than a clip, which has no
+   * first frame of its own to jump to.
+   */
+  focus(frame: number, clipId: string | undefined, origin: Origin): void;
+  clearSelection(): void;
+  seek(frame: number, origin: Origin | "play"): void;
+  subscribe(listener: (state: State) => void): void;
+};
+
+/**
+ * The clip an author is pointing at in the source text.
+ *
+ * A Script intent wins over the element that binds it: `@claim … @/claim` sits
+ * inside the `<script>` element, so without that preference every click in the
+ * prose would select the Speech Take instead of the B-roll. Ties break toward
+ * the tightest range, which is the most specific thing under the cursor.
+ */
+export function clipAtOffset(snapshot: StudioSnapshot, offset: number): Clip | undefined {
+  const clips = snapshot.tracks.flatMap((track) => track.clips);
+  const within = (range: { readonly start: number; readonly end: number } | undefined): number =>
+    range === undefined || offset < range.start || offset > range.end
+      ? Number.POSITIVE_INFINITY
+      : range.end - range.start;
+
+  let best: Clip | undefined;
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const clip of clips) {
+    const score = within(clip.elementRange);
+    if (score < bestScore) {
+      bestScore = score;
+      best = clip;
+    }
+  }
+  return best;
+}
+
+export function createStore(): Store {
+  let snapshot: StudioSnapshot | undefined;
+  let selection: Selection = { kind: "none" };
+  let playhead: Playhead = { frame: 0, origin: "timeline" };
+  const listeners: ((state: State) => void)[] = [];
+
+  const clips = (): readonly Clip[] => snapshot?.tracks.flatMap((track) => track.clips) ?? [];
+
+  const emit = (): void => {
+    if (snapshot === undefined) return;
+    const state: State = { snapshot, selection, playhead };
+    for (const listener of listeners) listener(state);
+  };
+
+  const clamp = (frame: number): number =>
+    Math.max(0, Math.min(Math.round(frame), (snapshot?.space.frameCount ?? 1) - 1));
+
+  return {
+    current: () => snapshot === undefined ? undefined : { snapshot, selection, playhead },
+    clip: (clipId) => clips().find((clip) => clip.id === clipId),
+    clipsAt(frame) {
+      return clips()
+        .filter((clip) => frame >= clip.startFrame && frame < clip.endFrameExclusive)
+        .sort((left, right) => right.stackOrder - left.stackOrder);
+    },
+    load(value) {
+      snapshot = value;
+      // A recompiled Source may have dropped the selected clip, and its frame
+      // count may have moved under the playhead.
+      const held = selection;
+      if (held.kind === "clip" && !clips().some((clip) => clip.id === held.clipId)) {
+        selection = { kind: "none" };
+      }
+      if (held.kind === "semantic-segment"
+        && !snapshot.semantic?.segments.some((segment) => segment.id === held.segmentId)) {
+        selection = { kind: "none" };
+      }
+      if (held.kind === "semantic-selection"
+        && !snapshot.semantic?.selections.some((item) => item.id === held.selectionId)) {
+        selection = { kind: "none" };
+      }
+      if (held.kind === "semantic-moment"
+        && !snapshot.semantic?.moments.some((item) => item.id === held.momentId)) {
+        selection = { kind: "none" };
+      }
+      playhead = { frame: clamp(playhead.frame), origin: playhead.origin };
+      emit();
+    },
+    select(clipId, origin) {
+      const clip = clips().find((item) => item.id === clipId);
+      if (clip === undefined) return;
+      selection = { kind: "clip", clipId, origin };
+      emit();
+    },
+    selectSemanticSegment(segmentId, origin) {
+      if (snapshot?.semantic?.segments.some((segment) => segment.id === segmentId) !== true) return;
+      selection = { kind: "semantic-segment", segmentId, origin };
+      emit();
+    },
+    selectSemanticSelection(selectionId, origin) {
+      if (snapshot?.semantic?.selections.some((item) => item.id === selectionId) !== true) return;
+      selection = { kind: "semantic-selection", selectionId, origin };
+      emit();
+    },
+    selectSemanticMoment(momentId, origin) {
+      if (snapshot?.semantic?.moments.some((item) => item.id === momentId) !== true) return;
+      selection = { kind: "semantic-moment", momentId, origin };
+      emit();
+    },
+    selectClip(clipId, origin) {
+      const clip = clips().find((item) => item.id === clipId);
+      if (clip === undefined) return;
+      selection = { kind: "clip", clipId, origin };
+      playhead = { frame: clamp(clip.startFrame), origin };
+      emit();
+    },
+    focus(frame, clipId, origin) {
+      const clip = clipId === undefined ? undefined : clips().find((item) => item.id === clipId);
+      selection = clip === undefined ? { kind: "none" } : { kind: "clip", clipId: clip.id, origin };
+      playhead = { frame: clamp(frame), origin };
+      emit();
+    },
+    clearSelection() {
+      if (selection.kind === "none") return;
+      selection = { kind: "none" };
+      emit();
+    },
+    seek(frame, origin) {
+      const next = clamp(frame);
+      if (next === playhead.frame && origin === playhead.origin) return;
+      playhead = { frame: next, origin };
+      emit();
+    },
+    subscribe(listener) {
+      listeners.push(listener);
+      if (snapshot !== undefined) listener({ snapshot, selection, playhead });
+    },
+  };
+}

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

@@ -0,0 +1,231 @@
+import type { StudioSnapshot } from "../shared.js";
+import { createOverlay } from "./overlay.js";
+import { icon, setIcon } from "./icons.js";
+import type { State, Store } from "./selection.js";
+
+export type Stage = {
+  readonly element: HTMLElement;
+  /** Start or stop playback, however the request arrived. */
+  toggle(): void;
+};
+
+/**
+ * The picture.
+ *
+ * The synthetic preview is the real HyperFrames document in an iframe, scrubbed
+ * by pausing its animations and setting their time. The transport therefore
+ * drives frames, not seconds, and lands on exactly the frame the renderer would
+ * photograph.
+ */
+export function createStage(store: Store): 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>
+    </div>
+    <div class="stage-viewport">
+      <div class="stage-scaler">
+        <iframe title="Preview" sandbox="allow-scripts allow-same-origin" allow="autoplay"></iframe>
+      </div>
+    </div>
+    <div class="stage-bar">
+      <button type="button" data-previous aria-label="Previous frame" title="Previous frame">
+        ${icon("previous")}
+      </button>
+      <button type="button" data-play aria-label="Play">
+        <span data-icon>${icon("play")}</span>
+      </button>
+      <button type="button" data-next aria-label="Next frame" title="Next frame">
+        ${icon("next")}
+      </button>
+      <button type="button" data-mute aria-label="Mute" class="stage-mute">
+        <span data-mute-icon>${icon("volume")}</span>
+      </button>
+    </div>`;
+
+  const viewport = element.querySelector<HTMLElement>(".stage-viewport")!;
+  const scaler = element.querySelector<HTMLElement>(".stage-scaler")!;
+  const iframe = element.querySelector<HTMLIFrameElement>("iframe")!;
+  /**
+   * Measure a clip in the rendered picture.
+   *
+   * The iframe is sized to the canvas, so coordinates inside its document are
+   * canvas pixels already and need no conversion. `getBoundingClientRect`
+   * reflects the paused animation's transform, which is the whole point:
+   * lifecycle motion displaces a clip from its Placement Frame for the length
+   * 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 document_ = iframe.contentDocument;
+    if (document_ === null) return undefined;
+    const present = document_.querySelector(`[data-hypit-present-id="${CSS.escape(clipId)}"]`);
+    // 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;
+    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 };
+  };
+
+  // The overlay is a sibling of the iframe inside the scaler, so it inherits the
+  // letterboxed content box and needs no transform of its own.
+  const overlay = createOverlay(store, measure);
+  scaler.append(overlay.element);
+
+  // Clicking the picture selects whatever is drawn under the pointer, which is
+  // the third way into the same selection.
+  scaler.addEventListener("click", (event) => {
+    const clip = overlay.hitTest(event.clientX, event.clientY);
+    if (clip !== undefined) store.select(clip.id, "video");
+    else store.clearSelection();
+  });
+  // The room around the picture is empty in the plainest sense.
+  viewport.addEventListener("click", (event) => {
+    if (event.target === viewport) store.clearSelection();
+  });
+  const play = element.querySelector<HTMLButtonElement>("[data-play]")!;
+  const previous = element.querySelector<HTMLButtonElement>("[data-previous]")!;
+  const next = element.querySelector<HTMLButtonElement>("[data-next]")!;
+  const playIcon = element.querySelector<HTMLElement>("[data-icon]")!;
+  const mute = element.querySelector<HTMLButtonElement>("[data-mute]")!;
+  const muteIcon = element.querySelector<HTMLElement>("[data-mute-icon]")!;
+
+  type SeekWindow = Window & {
+    __hypitSeekFrame?: (frame: number) => Promise<boolean>;
+    __hypitPlayFrame?: (frame: number) => Promise<boolean>;
+    __hypitSetMuted?: (muted: boolean) => Promise<boolean>;
+  };
+  let state: State | undefined;
+  let mounted = -1;
+  let ready = false;
+  let playing = false;
+  let muted = false;
+  let raf = 0;
+  // The transport counts frames from where it was last told to be. Jumping to a
+  // clip mid-playback moves that origin rather than stopping, so playback
+  // carries on from the frame the author asked for.
+  let fromFrame = 0;
+  let began = 0;
+  let placed = 0;
+
+  const seekPicture = (frame: number): void => {
+    const request = ++placed;
+    void (iframe.contentWindow as SeekWindow | null)?.__hypitSeekFrame?.(frame).then((current) => {
+      if (current && request === placed) overlay.refresh();
+    });
+  };
+
+  const fps = (snapshot: StudioSnapshot): number =>
+    snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
+
+  const fit = (): void => {
+    if (state === undefined) return;
+    const { canvasWidth, canvasHeight } = state.snapshot.space;
+    const room = viewport.getBoundingClientRect();
+    const scale = Math.min(
+      (room.width - 28) / canvasWidth,
+      (room.height - 28) / canvasHeight,
+    );
+    // A zero-sized viewport during layout would otherwise produce NaN.
+    const valid = Number.isFinite(scale) && scale > 0 ? scale : 1;
+    scaler.style.width = `${canvasWidth * valid}px`;
+    scaler.style.height = `${canvasHeight * valid}px`;
+    iframe.style.width = `${canvasWidth}px`;
+    iframe.style.height = `${canvasHeight}px`;
+    iframe.style.transform = `scale(${valid})`;
+  };
+
+  const stop = (): void => {
+    const wasPlaying = playing;
+    playing = false;
+    setIcon(playIcon, "play");
+    play.setAttribute("aria-label", "Play");
+    if (raf !== 0) cancelAnimationFrame(raf);
+    raf = 0;
+    // Settle the picture on the frame the transport stopped at.
+    if (wasPlaying && state !== undefined && ready) {
+      seekPicture(state.playhead.frame);
+    }
+  };
+
+  const toggle = (): void => {
+    if (state === undefined) return;
+    if (playing) { stop(); return; }
+    playing = true;
+    setIcon(playIcon, "pause");
+    play.setAttribute("aria-label", "Pause");
+    const total = state.snapshot.space.frameCount;
+    const rate = fps(state.snapshot);
+    fromFrame = state.playhead.frame >= total - 1 ? 0 : state.playhead.frame;
+    if (ready) (iframe.contentWindow as SeekWindow | null)?.__hypitPlayFrame?.(fromFrame);
+    began = performance.now();
+    const step = (now: number): void => {
+      const at = fromFrame + Math.round((now - began) / 1000 * rate);
+      if (!playing || at >= total) { store.seek(total - 1, "play"); stop(); return; }
+      store.seek(at, "play");
+      raf = requestAnimationFrame(step);
+    };
+    raf = requestAnimationFrame(step);
+  };
+  play.addEventListener("click", toggle);
+  previous.addEventListener("click", () => {
+    if (state !== undefined) store.seek(state.playhead.frame - 1, "video");
+  });
+  next.addEventListener("click", () => {
+    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");
+    (iframe.contentWindow as SeekWindow | null)?.__hypitSetMuted?.(muted);
+  };
+  mute.addEventListener("click", () => { muted = !muted; applyMuted(); });
+
+  iframe.addEventListener("load", () => {
+    ready = true;
+    if (state !== undefined) seekPicture(state.playhead.frame);
+    applyMuted();
+    // The box could not be measured until now.
+    overlay.refresh();
+  });
+
+  new ResizeObserver(fit).observe(viewport);
+
+  store.subscribe((value) => {
+    const first = state === undefined;
+    state = value;
+    if (value.snapshot.revision !== mounted) {
+      mounted = value.snapshot.revision;
+      stop();
+      ready = false;
+      const preview = value.snapshot.preview;
+      iframe.srcdoc = preview.srcdoc;
+      fit();
+    }
+    if (first) fit();
+
+    // 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
+    // every frame is what makes a picture fall behind its own transport.
+    // A jump that arrives while the transport runs is both: the picture moves
+    // now, and playback continues from there.
+    const jumped = value.playhead.origin !== "play";
+    if (jumped && playing) {
+      fromFrame = value.playhead.frame;
+      began = performance.now();
+    }
+    if (!ready) return;
+    const frame = (iframe.contentWindow as SeekWindow | null);
+    if (playing) frame?.__hypitPlayFrame?.(value.playhead.frame);
+    else seekPicture(value.playhead.frame);
+    // The overlay subscribed first, so it measured the picture as it was before
+    // this seek. Redraw now that the picture has moved.
+    if (playing) overlay.refresh();
+  });
+
+  return { element, toggle };
+}

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

@@ -0,0 +1,195 @@
+/**
+ * A tokenizer for SVML's own surface syntax.
+ *
+ * SVML has a small, closed grammar — tags, quoted strings, whole-value
+ * references, and Script prose with markers — so it is tokenized directly rather
+ * than through a general highlighter that has no grammar for it. The Script
+ * markers are the point: `@claim … @/claim` is what a Media Item binds to, so it
+ * has to read as a distinct thing from an ordinary attribute.
+ *
+ * Tokens are non-overlapping and in source order. Gaps between them are plain
+ * text; the renderer emits those verbatim, so the concatenation of everything is
+ * always byte-identical to the source.
+ */
+
+export type TokenKind =
+  | "header"
+  | "comment"
+  | "punct"
+  | "tag"
+  | "attr"
+  | "string"
+  | "reference"
+  | "marker"
+  | "role";
+
+export type Token = {
+  readonly start: number;
+  readonly end: number;
+  readonly kind: TokenKind;
+  /** For `marker` tokens, the Selection or Moment the marker names. */
+  readonly id?: string;
+};
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_.:-]*/u;
+const ATTRIBUTE = /^[A-Za-z_][A-Za-z0-9_.:-]*/u;
+/**
+ * The Script's own marker grammar: `@id` opens a Selection, `@/id` closes one,
+ * `@id!` marks a Moment, and a leading `~` or trailing `~` chooses which side of
+ * the neighbouring word the marker binds to.
+ */
+const MARKER = /^~?@\/?[a-z][a-z0-9_-]*[!~]?/u;
+
+function localName(tag: string): string {
+  const colon = tag.indexOf(":");
+  return colon < 0 ? tag : tag.slice(colon + 1);
+}
+
+function isSpace(value: string | undefined): boolean {
+  return value === " " || value === "\t" || value === "\n" || value === "\r";
+}
+
+export function tokenizeSvml(source: string): readonly Token[] {
+  const tokens: Token[] = [];
+  const push = (start: number, end: number, kind: TokenKind, id?: string): void => {
+    if (end > start) tokens.push({ start, end, kind, ...(id === undefined ? {} : { id }) });
+  };
+
+  let cursor = 0;
+  while (cursor < source.length) {
+    if (source.startsWith("<?", cursor)) {
+      const end = source.indexOf("?>", cursor + 2);
+      const stop = end < 0 ? source.length : end + 2;
+      push(cursor, stop, "header");
+      cursor = stop;
+      continue;
+    }
+
+    if (source.startsWith("<!--", cursor)) {
+      const end = source.indexOf("-->", cursor + 4);
+      const stop = end < 0 ? source.length : end + 3;
+      push(cursor, stop, "comment");
+      cursor = stop;
+      continue;
+    }
+
+    if (source[cursor] === "<") {
+      const closing = source[cursor + 1] === "/";
+      const nameStart = cursor + (closing ? 2 : 1);
+      const name = NAME.exec(source.slice(nameStart));
+      if (name === null) {
+        // A bare `<` in prose. Leave it as plain text so offsets never drift.
+        cursor += 1;
+        continue;
+      }
+      push(cursor, nameStart, "punct");
+      push(nameStart, nameStart + name[0].length, "tag");
+      cursor = nameStart + name[0].length;
+      cursor = tokenizeAttributes(source, cursor, push);
+
+      // Script is the language's one Raw Surface: its body is prose with
+      // markers, not markup, and must be scanned by different rules.
+      if (!closing && localName(name[0]) === "script" && source[cursor - 2] !== "/") {
+        cursor = tokenizeScriptBody(source, cursor, name[0], push);
+      }
+      continue;
+    }
+
+    cursor += 1;
+  }
+  return tokens;
+}
+
+type Push = (start: number, end: number, kind: TokenKind, id?: string) => void;
+
+/** Consume attributes through the tag's `>` or `/>`, whichever closes it. */
+function tokenizeAttributes(source: string, from: number, push: Push): number {
+  let cursor = from;
+  while (cursor < source.length) {
+    while (isSpace(source[cursor])) cursor += 1;
+    if (source.startsWith("/>", cursor)) {
+      push(cursor, cursor + 2, "punct");
+      return cursor + 2;
+    }
+    if (source[cursor] === ">") {
+      push(cursor, cursor + 1, "punct");
+      return cursor + 1;
+    }
+    const name = ATTRIBUTE.exec(source.slice(cursor));
+    if (name === null) return cursor + 1;
+    push(cursor, cursor + name[0].length, "attr");
+    cursor += name[0].length;
+
+    while (isSpace(source[cursor])) cursor += 1;
+    if (source[cursor] !== "=") continue;
+    push(cursor, cursor + 1, "punct");
+    cursor += 1;
+    while (isSpace(source[cursor])) cursor += 1;
+
+    const quote = source[cursor];
+    if (quote === "\"" || quote === "'") {
+      const close = source.indexOf(quote, cursor + 1);
+      const stop = close < 0 ? source.length : close + 1;
+      push(cursor, stop, "string");
+      cursor = stop;
+      continue;
+    }
+    if (quote === "{") {
+      const close = source.indexOf("}", cursor + 1);
+      const stop = close < 0 ? source.length : close + 1;
+      push(cursor, stop, "reference");
+      cursor = stop;
+      continue;
+    }
+  }
+  return cursor;
+}
+
+/** Script prose: Segment and Role Cue tags stay tags; `@id` markers stand out. */
+function tokenizeScriptBody(source: string, from: number, tag: string, push: Push): number {
+  const close = `</${tag}>`;
+  let cursor = from;
+  while (cursor < source.length) {
+    if (source.startsWith(close, cursor)) {
+      push(cursor, cursor + 2, "punct");
+      push(cursor + 2, cursor + 2 + tag.length, "tag");
+      push(cursor + 2 + tag.length, cursor + close.length, "punct");
+      return cursor + close.length;
+    }
+    if (source.startsWith("<!--", cursor)) {
+      const end = source.indexOf("-->", cursor + 4);
+      const stop = end < 0 ? source.length : end + 3;
+      push(cursor, stop, "comment");
+      cursor = stop;
+      continue;
+    }
+    if (source[cursor] === "<") {
+      const closing = source[cursor + 1] === "/";
+      const nameStart = cursor + (closing ? 2 : 1);
+      const name = NAME.exec(source.slice(nameStart));
+      if (name === null) { cursor += 1; continue; }
+      const end = source.indexOf(">", nameStart);
+      const stop = end < 0 ? source.length : end + 1;
+      push(cursor, nameStart, "punct");
+      // An upper-case tag inside Script is a Role Cue, not a Segment.
+      push(nameStart, nameStart + name[0].length, /^[A-Z]/u.test(name[0]) ? "role" : "tag");
+      push(nameStart + name[0].length, stop, "punct");
+      cursor = stop;
+      continue;
+    }
+    // A leading `~` binds the marker to the word on its left, and is part of it.
+    if (source[cursor] === "@" || (source[cursor] === "~" && source[cursor + 1] === "@")) {
+      const marker = MARKER.exec(source.slice(cursor));
+      if (marker !== null) {
+        // Strip the affinity sigils, the `@` and the closing `/` so an opening
+        // marker, its closing marker and a Moment all report the same name.
+        const id = marker[0].replace(/^~?@\/?/u, "").replace(/[!~]$/u, "");
+        push(cursor, cursor + marker[0].length, "marker", id);
+        cursor += marker[0].length;
+        continue;
+      }
+    }
+    cursor += 1;
+  }
+  return cursor;
+}