@hyperframes/studio 0.8.49 → 0.8.51

package/src/player/lib/describeClips.ts

@@ -0,0 +1,52 @@
+/** Plain-field clip facts from the player store; feeds the Ask-agent prompt and `studio_look`. */
+import type { TimelineElement } from "../store/playerStore";
+import { elementAutomationLanes } from "../components/automationLaneData";
+import { byStart, formatClipLine, type ClipFact } from "@hyperframes/core/clip-facts";
+export { byStart } from "@hyperframes/core/clip-facts";
+export type { ClipFact } from "@hyperframes/core/clip-facts";
+
+/** The store holds preview URLs; the agent edits project files, so drop the origin and preview prefix. */
+function projectRelativeSrc(src: string): string {
+  return src.replace(/^https?:\/\/[^/]+/, "").replace(/^\/api\/projects\/[^/]+\/preview\//, "");
+}
+
+export function describeClip(element: TimelineElement): ClipFact {
+  return {
+    id: element.domId ?? element.id,
+    label: element.label ?? null,
+    kind: element.kind ?? element.tag.toLowerCase(),
+    start: element.start,
+    duration: element.duration,
+    end: element.start + element.duration,
+    trackIndex: element.authoredTrack ?? element.track,
+    src: element.src ? projectRelativeSrc(element.src) : null,
+    sourceFile: element.sourceFile ?? null,
+    volume: element.volume ?? null,
+    lanes: elementAutomationLanes(element).map((lane) => ({
+      target: lane.target,
+      points: lane.points.map(({ t, v }) => ({ t, v })),
+    })),
+    playbackRate: element.playbackRate === 1 ? null : (element.playbackRate ?? null),
+    audioGroup: element.audioGroup ?? null,
+    role: element.timelineRole ?? null,
+  };
+}
+
+export function describeClips(elements: readonly TimelineElement[]): ClipFact[] {
+  return elements.map(describeClip).sort(byStart);
+}
+
+const PROMPT_CLIP_CAP = 200;
+
+/** The Ask-agent prompt's Timeline block; empty when the timeline has no clips. */
+export function formatTimelineBlock(elements: readonly TimelineElement[]): string {
+  const clips = describeClips(elements);
+  if (clips.length === 0) return "";
+  const shown = clips.slice(0, PROMPT_CLIP_CAP).map(formatClipLine);
+  const more = clips.length - shown.length;
+  return [
+    "Timeline (composition seconds; lane points are seconds from the clip start):",
+    ...shown,
+    ...(more > 0 ? [`(${more} more clips not listed)`] : []),
+  ].join("\n");
+}

package/src/player/lib/timelineDOM.test.ts

@@ -3,7 +3,6 @@ import { describe, expect, it } from "vitest";
 import {
   createTimelineElementFromManifestClip,
   parseTimelineFromDOM,
-  createImplicitTimelineLayersFromDOM,
   mergeTimelineElementsPreservingDowngrades,
 } from "./timelineDOM";
 import { isTimelineIgnoredElement } from "./timelineElementHelpers";
@@ -302,19 +301,6 @@ describe("createTimelineElementFromManifestClip — source-scoped selector ident
 // implicit-layer fallback happily gave it a track. Draggable and trimmable, and
 // writing timing onto a bus means nothing.
 describe("<hf-audio-group> is not a timeline layer", () => {
-  it("gets no implicit row of its own", () => {
-    const doc = makeDoc(`
-      <div data-composition-id="root">
-        <audio id="voice-1" data-start="0" data-duration="6" data-audio-group="voiceover"></audio>
-        <hf-audio-group id="voiceover" data-label="Voiceover"></hf-audio-group>
-      </div>
-    `);
-
-    const implicit = createImplicitTimelineLayersFromDOM(doc, 12, []);
-
-    expect(implicit.map((el) => el.domId)).not.toContain("voiceover");
-  });
-
   it("is excluded by the shared ignore predicate", () => {
     const doc = makeDoc(`<hf-audio-group id="vo"></hf-audio-group><div id="panel"></div>`);
     expect(isTimelineIgnoredElement(doc.getElementById("vo") as Element)).toBe(true);
@@ -322,72 +308,6 @@ describe("<hf-audio-group> is not a timeline layer", () => {
   });
 });
 
-describe("createImplicitTimelineLayersFromDOM — hfId from data-hf-id", () => {
-  it("uses the runtime root paint scope for implicit siblings of manifest clips", () => {
-    const doc = makeDoc(`
-      <div data-composition-id="root">
-        <div id="timed" data-start="0" data-duration="5"></div>
-        <div id="implicit"></div>
-      </div>
-    `);
-    const timedHost = doc.getElementById("timed");
-    const timed = createTimelineElementFromManifestClip({
-      clip: {
-        id: "timed",
-        label: "Timed",
-        start: 0,
-        duration: 5,
-        track: 0,
-        stackingContextId: "css:root",
-        kind: "element",
-        tagName: "div",
-        compositionId: null,
-        parentCompositionId: null,
-        compositionSrc: null,
-        assetUrl: null,
-      },
-      fallbackIndex: 0,
-      doc,
-      hostEl: timedHost,
-    });
-    const implicit = createImplicitTimelineLayersFromDOM(doc, 5, [timed])[0];
-
-    expect(implicit?.stackingContextId).toBe("css:root");
-    expect(implicit?.stackingContextId).toBe(timed.stackingContextId);
-  });
-
-  it("harvests hfId from an implicit layer child that has data-hf-id", () => {
-    const doc = makeDoc(`
-      <div data-composition-id="root">
-        <div id="layer" class="clip" data-hf-id="hf-xyz789"></div>
-      </div>
-    `);
-
-    const layers = createImplicitTimelineLayersFromDOM(doc, 10);
-    const layer = layers.find((el) => el.domId === "layer");
-
-    expect(layer).toBeDefined();
-    expect(layer?.hfId).toBe("hf-xyz789");
-  });
-
-  it("ignores runtime-owned color grading canvases as implicit layers", () => {
-    const doc = makeDoc(`
-      <div data-composition-id="root" data-duration="5">
-        <img id="photo" class="clip" data-start="0" data-duration="5" />
-        <canvas
-          class="__hf_color_grading_canvas__"
-          data-hf-color-grading-canvas="true"
-          data-hyperframes-ignore
-        ></canvas>
-      </div>
-    `);
-
-    const layers = createImplicitTimelineLayersFromDOM(doc, 5);
-
-    expect(layers).toEqual([]);
-  });
-});
-
 describe("mergeTimelineElementsPreservingDowngrades — genuine removal vs transient downgrade", () => {
   it("drops a removed TOP-LEVEL element (undo of a split) instead of ghosting it", () => {
     const current = [el("a"), el("a-split")]; // post-split store: original + clone

package/src/player/lib/timelineDOM.ts

@@ -17,8 +17,6 @@ import {
   resolveMediaElement,
   applyMediaMetadataFromElement,
   getTimelineElementDisplayLabel,
-  getImplicitTimelineLayerLabel,
-  isImplicitTimelineLayerCandidate,
   getTimelineElementSelector,
   getTimelineElementSourceFile,
   getTimelineElementSelectorIndex,
@@ -203,63 +201,6 @@ export function createTimelineElementFromManifestClip(params: {
   return entry;
 }
 
-export function createImplicitTimelineLayersFromDOM(
-  doc: Document,
-  rootDuration: number,
-  existingElements: readonly TimelineElement[] = [],
-): TimelineElement[] {
-  if (!Number.isFinite(rootDuration) || rootDuration <= 0) return [];
-  const rootComp = doc.querySelector("[data-composition-id]");
-  if (!rootComp) return [];
-
-  const existingKeys = new Set(existingElements.map(getTimelineElementIdentity));
-  const maxTrack = existingElements.reduce(
-    (max, element) => Math.max(max, Number.isFinite(element.track) ? element.track : 0),
-    -1,
-  );
-  const layers: TimelineElement[] = [];
-
-  for (const child of Array.from(rootComp.children)) {
-    if (!isImplicitTimelineLayerCandidate(rootComp, child)) continue;
-
-    const selector = getTimelineElementSelector(child);
-    if (!selector) continue;
-    const selectorIndex = getTimelineElementSelectorIndex(doc, child, selector);
-    const sourceFile = getTimelineElementSourceFile(child);
-    const label = getImplicitTimelineLayerLabel(child);
-    const identity = buildTimelineElementIdentity({
-      preferredId: child.id || null,
-      label,
-      fallbackIndex: existingElements.length + layers.length,
-      domId: child.id || undefined,
-      selector,
-      selectorIndex,
-      sourceFile,
-    });
-    if (existingKeys.has(identity.key) || existingKeys.has(identity.id)) continue;
-
-    layers.push({
-      domId: child.id || undefined,
-      hfId: child.getAttribute("data-hf-id") || undefined,
-      zIndex: readTimelineElementZIndex(child),
-      duration: rootDuration,
-      id: identity.id,
-      key: identity.key,
-      label,
-      selector,
-      selectorIndex,
-      sourceFile,
-      stackingContextId: resolveCssStackingContextId(child),
-      start: 0,
-      tag: child.tagName.toLowerCase(),
-      timingSource: "implicit",
-      track: maxTrack + 1 + layers.length,
-    });
-  }
-
-  return layers;
-}
-
 /**
  * Parse [data-start] elements from a Document into TimelineElement[].
  * Shared helper — used by onIframeLoad fallback, handleMessage, and enrichMissingCompositions.
@@ -330,7 +271,6 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
       selectorIndex,
       sourceFile,
       stackingContextId: resolveCssStackingContextId(el),
-      timingSource: "authored",
       zIndex: readTimelineElementZIndex(el),
     };
 
@@ -399,7 +339,7 @@ export function parseTimelineFromDOM(doc: Document, rootDuration: number): Timel
     els.push(entry);
   });
 
-  return [...els, ...createImplicitTimelineLayersFromDOM(doc, rootDuration, els)];
+  return els;
 }
 
 // ---------------------------------------------------------------------------

package/src/player/lib/timelineElementHelpers.ts

@@ -2,7 +2,7 @@
  * Low-level helpers for building and identifying TimelineElement objects.
  *
  * Covers: duration reading, media-element metadata extraction, selector/key/
- * identity builders, DOM node lookup, and implicit layer detection. These are
+ * identity builders, and DOM node lookup. These are
  * intentionally dependency-free (no store, no hooks) so they can be used in
  * both the React hook and test environments.
  */
@@ -82,13 +82,7 @@ function normalizePlaybackRate(raw: number): number {
 }
 
 export function isTimelineIgnoredElement(el: Element): boolean {
-  // An `<hf-audio-group>` is a mixer bus, not a clip: it carries the group's
-  // label, fader, mute and FX chain, has no timing of its own, and is drawn as
-  // a GROUP ROW by the group derivation. Left in, the implicit-layer fallback
-  // also gave it an ordinary full-duration track — so a grouped composition
-  // showed "Voiceover • 0.0s – 12.0s" as a phantom clip directly above the real
-  // group header. Harmless-looking, but that row is draggable and trimmable,
-  // and writing timing onto the bus is meaningless.
+  // An `<hf-audio-group>` is a mixer bus with no timing of its own, drawn as a group row, never a clip.
   if (el.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG) return true;
   return Boolean(
     el.closest(
@@ -223,37 +217,6 @@ export function getTimelineElementDisplayLabel(input: {
   return tag ? `${tag} clip` : "Timeline clip";
 }
 
-const IMPLICIT_TIMELINE_LAYER_SKIP_TAGS = new Set([
-  "base",
-  "link",
-  "meta",
-  "noscript",
-  "script",
-  "style",
-  "template",
-]);
-
-function humanizeTimelineIdentifier(value: string): string {
-  return value
-    .trim()
-    .replace(/[_-]+/g, " ")
-    .replace(/\s+/g, " ")
-    .replace(/\b\w/g, (match) => match.toUpperCase());
-}
-
-export function getImplicitTimelineLayerLabel(el: HTMLElement): string {
-  const explicitLabel =
-    el.getAttribute("data-timeline-label") ??
-    el.getAttribute("data-label") ??
-    el.getAttribute("aria-label");
-  if (explicitLabel?.trim()) return explicitLabel.trim();
-  if (el.id.trim()) return humanizeTimelineIdentifier(el.id);
-  const classes = el.className.split(/\s+/).filter(Boolean);
-  const className = classes.find((value) => value !== "clip") ?? classes[0];
-  if (className) return humanizeTimelineIdentifier(className);
-  return getTimelineElementDisplayLabel({ tag: el.tagName });
-}
-
 // ---------------------------------------------------------------------------
 // Selector / identity / key builders
 // ---------------------------------------------------------------------------
@@ -475,17 +438,3 @@ export function createTimelineDomNodeResolver(doc: Document) {
     return node;
   };
 }
-
-// ---------------------------------------------------------------------------
-// Implicit layer detection
-// ---------------------------------------------------------------------------
-
-export function isImplicitTimelineLayerCandidate(root: Element, el: Element): el is HTMLElement {
-  if (!isHtmlElement(el)) return false;
-  if (isTimelineIgnoredElement(el)) return false;
-  if (el.parentElement !== root) return false;
-  const tagName = el.tagName.toLowerCase();
-  if (IMPLICIT_TIMELINE_LAYER_SKIP_TAGS.has(tagName)) return false;
-  if (el.hasAttribute("data-start") || el.hasAttribute("data-track-index")) return false;
-  return Boolean(getTimelineElementSelector(el));
-}

package/src/player/store/playerStore.ts

@@ -200,6 +200,8 @@ interface PlayerState extends PlayerStoreSlices {
   clipManifest: ClipManifestClip[] | null;
   setClipManifest: (clips: ClipManifestClip[] | null) => void;
   clipParentMap: Map<string, string>;
+  topLevelIds: ReadonlySet<string> | null;
+  setTopLevelIds: (ids: ReadonlySet<string> | null) => void;
   setClipParentMap: (map: Map<string, string>) => void;
   /**
    * Sub-composition DOM descendants (groups + their children) that have no
@@ -288,6 +290,7 @@ export function createTimelineResetState() {
     beatPersist: null,
     clipManifest: null,
     clipParentMap: new Map<string, string>(),
+    topLevelIds: null,
     domClipChildren: [],
     subCompositionHostState: new Map<string, SubCompositionHostState>(),
   };
@@ -434,6 +437,8 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setClipManifest: (clips) => set({ clipManifest: clips }),
   clipParentMap: new Map(),
   setClipParentMap: (map) => set({ clipParentMap: map }),
+  topLevelIds: null,
+  setTopLevelIds: (ids) => set({ topLevelIds: ids }),
   domClipChildren: [],
   setDomClipChildren: (children) => set({ domClipChildren: children }),
   subCompositionHostState: new Map(),

package/src/player/store/timelineElement.ts

@@ -59,8 +59,6 @@ export interface TimelineElement {
   automation?: string;
   /** Path from data-composition-src — identifies sub-composition elements */
   compositionSrc?: string;
-  /** Whether this row came from authored clip timing or Studio's full-duration layer fallback. */
-  timingSource?: "authored" | "implicit";
   /** Set by data-timeline-locked on the host element — disables move and trim in Studio. */
   timelineLocked?: boolean;
   /** Set by data-hidden on the host element — hides the clip in preview and render. */
@@ -79,7 +77,7 @@ export interface TimelineElement {
   audioGroupFxChain?: string;
   audioGroupAutomation?: string;
   /**
-   * Set by useExpandedTimelineElements on an inline-expanded sub-composition
+   * Set by useTimelineRowElements on an inline-expanded sub-composition
    * child: the absolute master-timeline start of the sub-comp host the child
    * lives in. Presence marks the element as expanded; edits subtract it to get
    * the child's local (sourceFile-relative) time. Works at any nesting depth.

package/src/shims/canvasBrowserStub.js

@@ -0,0 +1,50 @@
+/**
+ * Browser stub for the Node-only `canvas` package.
+ *
+ * linkedom's `HTMLCanvasElement` constructor calls `createCanvas(300, 150)`
+ * (300x150 being the HTML canvas default size). linkedom guards that import in
+ * a try/catch: the try requires the native `canvas` package, and the catch
+ * falls back to linkedom's own bundled canvas shim.
+ *
+ * That guard only works with a *runtime* require. Vite resolves the specifier
+ * statically, so the bundled form is a plain assignment that cannot throw, the
+ * catch never runs, and `createCanvas` lands `undefined`. Parsing any `<canvas>`
+ * tag then throws inside `openComposition`, Studio loses its SDK session for the
+ * whole composition, and every edit silently falls back to the server path — the
+ * resolver shadow does not run either, so it was invisible until
+ * `studio:sdk_session_unavailable` shipped in v0.8.47.
+ *
+ * Production telemetry over the 72h after the flip: 1065 of 1544 session-open
+ * failures were this crash, across a large share of 197 users. Canvas is common
+ * in compositions (Three.js, shaders, particle effects, charts).
+ *
+ * Aliasing `canvas` to this file makes the browser build resolve to a
+ * measurement-only canvas, which is all linkedom's static parse needs — nothing
+ * in the SDK rasterizes through it. It mirrors linkedom's own
+ * `commonjs/canvas-shim.cjs`, reimplemented here because linkedom's `exports`
+ * map does not expose that file.
+ */
+
+class BrowserCanvasStub {
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+  }
+  /** linkedom only ever needs the element to exist; nothing draws through it. */
+  getContext() {
+    return null;
+  }
+  toDataURL() {
+    return "";
+  }
+}
+
+export function createCanvas(width, height) {
+  return new BrowserCanvasStub(width, height);
+}
+
+// linkedom consumes this as a DEFAULT import — `import Canvas from
+// '../../commonjs/canvas.cjs'` then `const {createCanvas} = Canvas` — so the
+// default export is the load-bearing one; the named export above is interop
+// belt-and-braces.
+export default { createCanvas };

package/src/styles/iconTokens.ts

@@ -0,0 +1,20 @@
+import type { IconWeight } from "@phosphor-icons/react";
+
+const WEIGHTS = ["thin", "light", "regular", "bold", "fill", "duotone"] as const;
+
+function asWeight(value: string): IconWeight | null {
+  return (WEIGHTS as readonly string[]).includes(value) ? (value as IconWeight) : null;
+}
+
+/** Studio's Phosphor defaults, read off `theme.css` so size and weight have one
+ * owner instead of a CSS variable and a JS constant that drift. A missing or
+ * unrecognized value falls back to Phosphor's own default. */
+export function readIconTokens(root: Element = document.documentElement): {
+  size: string;
+  weight: IconWeight;
+} {
+  const styles = getComputedStyle(root);
+  const size = styles.getPropertyValue("--icon-size").trim();
+  const weight = asWeight(styles.getPropertyValue("--icon-weight").trim());
+  return { size: size || "1em", weight: weight ?? "regular" };
+}

package/src/styles/palette-reset.css

@@ -0,0 +1,6 @@
+/* Studio's own app clears Tailwind's stock palette so only Studio tokens are
+ * reachable from markup. Kept out of theme.css so a host importing the tokens
+ * keeps its own colours. Must be imported before theme.css. */
+@theme static {
+  --color-*: initial;
+}

package/src/styles/studio.css

@@ -1,6 +1,19 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import "tailwindcss" source(none);
+@import "./palette-reset.css";
+@import "./theme.css";
+
+/* Explicit sources: Studio's own TypeScript and its shell HTML. Automatic
+ * detection would walk up to the repo root and scan `data/projects`, gitignored user content. */
+@source "../**/*.{ts,tsx}";
+@source "../../index.html";
+
+/* Tailwind v4 preflight no longer gives enabled buttons a pointer cursor. */
+@layer base {
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
+}
 
 /*
  * Studio is a dark-only UI — pin the user-agent color scheme to dark so that
@@ -14,9 +27,9 @@
 body {
   margin: 0;
   padding: 0;
-  background: #0a0a0a;
-  color: #e5e5e5;
-  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  background: var(--color-bg-0);
+  color: var(--color-text-body);
+  font-family: var(--font-sans);
   overflow: hidden;
 }
 
@@ -290,7 +303,7 @@ body {
   left: 12px;
   overflow: hidden;
   color: rgba(255, 255, 255, 0.34);
-  font-family: "SF Mono", "Fira Code", monospace;
+  font-family: var(--font-mono);
   font-size: 9px;
   font-variant-numeric: tabular-nums;
   line-height: 1;
@@ -328,7 +341,7 @@ body {
 }
 
 .cm-editor .cm-scroller {
-  font-family: "JetBrains Mono", "Fira Code", "SF Mono", monospace;
+  font-family: var(--font-mono);
 }
 
 .cm-editor.cm-focused {
@@ -385,12 +398,7 @@ body {
 }
 
 .hf-loader-title {
-  font-family:
-    Inter,
-    -apple-system,
-    BlinkMacSystemFont,
-    "Segoe UI",
-    sans-serif;
+  font-family: var(--font-sans);
   font-size: 1rem;
   font-weight: 600;
   letter-spacing: 0;
@@ -406,12 +414,7 @@ body {
   min-height: 2.5rem;
   overflow: hidden;
   color: var(--hf-text-secondary, rgba(244, 244, 245, 0.68));
-  font-family:
-    Inter,
-    -apple-system,
-    BlinkMacSystemFont,
-    "Segoe UI",
-    sans-serif;
+  font-family: var(--font-sans);
   font-size: 0.82rem;
   line-height: 1.6;
 }
@@ -423,7 +426,7 @@ body {
   text-overflow: ellipsis;
   white-space: nowrap;
   color: var(--hf-text-tertiary, rgba(244, 244, 245, 0.46));
-  font-family: "IBM Plex Mono", "SF Mono", "Fira Code", monospace;
+  font-family: var(--font-mono);
   font-size: 0.75rem;
   letter-spacing: 0;
   font-variant-numeric: tabular-nums;

package/src/styles/tailwind-preset.shared.js

@@ -1,3 +1,6 @@
+/** @deprecated Superseded by `src/styles/theme.css` (published as
+ * `@hyperframes/studio/theme.css`); kept one more major for Tailwind v3
+ * consumers. Values are byte-identical; theme.test.ts fails if they drift. */
 const studioPreset = {
   theme: {
     extend: {