@hyperframes/studio 0.8.23 → 0.8.25

package/src/webmcp/handles.test.ts

@@ -5,23 +5,15 @@ import {
   mintElementHandle,
   parseElementHandle,
   resolveElementHandle,
+  resolveLiveHandleSelection,
   timelineElementAddress,
 } from "./handles";
+import { previewDoc } from "./webmcpTestUtils";
 
 function timelineElement(overrides: Partial<TimelineElement>): TimelineElement {
   return { id: "synthetic-id", tag: "div", start: 0, duration: 1, track: 0, ...overrides };
 }
 
-/** A separate document, standing in for the preview iframe's realm. */
-function previewDoc(html: string): Document {
-  const iframe = document.createElement("iframe");
-  document.body.append(iframe);
-  const doc = iframe.contentDocument;
-  if (!doc) throw new Error("expected iframe document");
-  doc.body.innerHTML = html;
-  return doc;
-}
-
 describe("mintElementHandle", () => {
   it("prefers data-hf-id, the stable patch target", () => {
     const handle = mintElementHandle(
@@ -29,7 +21,7 @@ describe("mintElementHandle", () => {
         timelineElement({ hfId: "abc123", domId: "headline", selector: ".title" }),
       ),
     );
-    expect(handle).toBe("hf:abc123");
+    expect(handle).toBe("hf:v1:index.html:index.html:abc123");
   });
 
   it("falls back to the DOM id when there is no hf id", () => {
@@ -37,7 +29,7 @@ describe("mintElementHandle", () => {
       mintElementHandle(
         timelineElementAddress(timelineElement({ domId: "headline", selector: ".title" })),
       ),
-    ).toBe("dom:headline");
+    ).toBe("dom:v1:index.html:index.html:headline");
   });
 
   it("falls back to a selector with its occurrence index", () => {
@@ -45,12 +37,12 @@ describe("mintElementHandle", () => {
       mintElementHandle(
         timelineElementAddress(timelineElement({ selector: ".card", selectorIndex: 2 })),
       ),
-    ).toBe("sel:.card#2");
+    ).toBe("sel:v1:index.html:index.html:.card#2");
   });
 
   it("defaults a missing occurrence index to the first match", () => {
     expect(mintElementHandle(timelineElementAddress(timelineElement({ selector: ".card" })))).toBe(
-      "sel:.card#0",
+      "sel:v1:index.html:index.html:.card#0",
     );
   });
 
@@ -60,17 +52,110 @@ describe("mintElementHandle", () => {
   });
 });
 
+describe("resolveLiveHandleSelection", () => {
+  it("reports a transient change when the replacement preview has not rebuilt the target", async () => {
+    const firstDoc = previewDoc('<div id="headline">before</div>');
+    const replacementDoc = previewDoc("<main>reloading</main>");
+    let currentDoc = firstDoc;
+
+    const result = await resolveLiveHandleSelection(
+      () => currentDoc,
+      "dom:headline",
+      async (element) => {
+        currentDoc = replacementDoc;
+        return { element };
+      },
+    );
+
+    expect(result).toEqual({ status: "changed" });
+  });
+
+  it("reports a stable missing target as not found", async () => {
+    const doc = previewDoc("<main>settled</main>");
+
+    const result = await resolveLiveHandleSelection(
+      () => doc,
+      "dom:headline",
+      async (element) => ({ element }),
+    );
+
+    expect(result).toEqual({ status: "not-found" });
+  });
+});
+
 describe("parseElementHandle", () => {
+  it("round-trips source ownership and the active composition", () => {
+    expect(
+      parseElementHandle(
+        mintElementHandle({
+          domId: "headline:hero",
+          sourceFile: "compositions/hero.html",
+          activeCompositionPath: "index.html",
+        })!,
+      ),
+    ).toEqual({
+      scheme: "dom",
+      version: 1,
+      value: "headline:hero",
+      index: 0,
+      sourceFile: "compositions/hero.html",
+      activeCompositionPath: "index.html",
+    });
+  });
+
+  it("encodes path, selector, colon, and hash delimiters without ambiguity", () => {
+    const handle = mintElementHandle({
+      selector: '#hero[data-label="a:b"] > .card:nth-child(2)',
+      selectorIndex: 3,
+      sourceFile: "compositions/a:b#hero.html",
+      activeCompositionPath: "scenes/root:wide.html",
+    });
+
+    expect(parseElementHandle(handle!)).toEqual({
+      scheme: "sel",
+      version: 1,
+      value: '#hero[data-label="a:b"] > .card:nth-child(2)',
+      index: 3,
+      sourceFile: "compositions/a:b#hero.html",
+      activeCompositionPath: "scenes/root:wide.html",
+    });
+  });
+
   it("splits the index off the LAST hash, so id selectors survive", () => {
     expect(parseElementHandle("sel:#card > .title#3")).toEqual({
       scheme: "sel",
+      version: 0,
       value: "#card > .title",
       index: 3,
     });
   });
 
   it("treats a selector with no index as the first match", () => {
-    expect(parseElementHandle("sel:.card")).toEqual({ scheme: "sel", value: ".card", index: 0 });
+    expect(parseElementHandle("sel:.card")).toEqual({
+      scheme: "sel",
+      version: 0,
+      value: ".card",
+      index: 0,
+    });
+  });
+
+  it("round-trips the project identity in a writable v2 handle", () => {
+    const handle = mintElementHandle({
+      projectId: "project:demo",
+      domId: "headline",
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+    });
+
+    expect(parseElementHandle(handle!)).toEqual({
+      scheme: "dom",
+      version: 2,
+      projectId: "project:demo",
+      value: "headline",
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+      index: 0,
+    });
   });
 
   it("rejects an unknown scheme", () => {
@@ -106,6 +191,78 @@ describe("resolveElementHandle", () => {
     expect(resolved instanceof HTMLElement).toBe(false);
   });
 
+  it("distinguishes duplicate authored ids by source file", () => {
+    const doc = previewDoc(
+      `<main data-composition-id="root" data-composition-file="index.html">
+         <div id="duplicate">root</div>
+         <section data-composition-id="nested" data-composition-file="compositions/nested.html">
+           <div id="duplicate">nested</div>
+         </section>
+       </main>`,
+    );
+    const rootHandle = mintElementHandle({
+      domId: "duplicate",
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+    });
+    const nestedHandle = mintElementHandle({
+      domId: "duplicate",
+      sourceFile: "compositions/nested.html",
+      activeCompositionPath: "index.html",
+    });
+
+    expect(rootHandle).not.toBe(nestedHandle);
+    expect(resolveElementHandle(doc, rootHandle!)?.textContent).toBe("root");
+    expect(resolveElementHandle(doc, nestedHandle!)?.textContent).toBe("nested");
+  });
+
+  it("keeps selector occurrence indexes scoped to their source file", () => {
+    const doc = previewDoc(
+      `<main data-composition-id="root" data-composition-file="index.html">
+         <div class="card">root first</div><div class="card">root second</div>
+         <section data-composition-id="nested" data-composition-file="compositions/nested.html">
+           <div class="card">nested first</div><div class="card">nested second</div>
+         </section>
+       </main>`,
+    );
+    const rootSecond = mintElementHandle({
+      selector: ".card",
+      selectorIndex: 1,
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+    });
+    const nestedSecond = mintElementHandle({
+      selector: ".card",
+      selectorIndex: 1,
+      sourceFile: "compositions/nested.html",
+      activeCompositionPath: "index.html",
+    });
+
+    expect(resolveElementHandle(doc, rootSecond!)?.textContent).toBe("root second");
+    expect(resolveElementHandle(doc, nestedSecond!)?.textContent).toBe("nested second");
+  });
+
+  it("re-resolves a scoped handle against the live document after reload", () => {
+    const handle = mintElementHandle({
+      domId: "headline",
+      sourceFile: "index.html",
+      activeCompositionPath: "index.html",
+    });
+    const firstDoc = previewDoc(
+      '<main data-composition-id="root" data-composition-file="index.html"><div id="headline">before</div></main>',
+    );
+    const first = resolveElementHandle(firstDoc, handle!);
+    const reloadedDoc = previewDoc(
+      '<main data-composition-id="root" data-composition-file="index.html"><div id="headline">after</div></main>',
+    );
+    const reloaded = resolveElementHandle(reloadedDoc, handle!);
+
+    expect(first?.textContent).toBe("before");
+    expect(reloaded?.textContent).toBe("after");
+    expect(reloaded).not.toBe(first);
+    expect(reloaded?.ownerDocument).toBe(reloadedDoc);
+  });
+
   it("returns null for a handle that no longer matches", () => {
     const doc = previewDoc('<div id="headline">A</div>');
     expect(resolveElementHandle(doc, "dom:deleted")).toBeNull();

package/src/webmcp/handles.ts

@@ -13,6 +13,7 @@
  */
 
 import type { TimelineElement } from "../player/store/timelineElement";
+import { findElementForSelection } from "../components/editor/domEditingElement";
 import type { PatchTarget } from "../utils/sourcePatcher";
 
 const SEPARATOR = ":";
@@ -24,10 +25,13 @@ const INDEX_SEPARATOR = "#";
  * knowing about either.
  */
 export interface ElementAddress {
+  projectId?: string | null;
   hfId?: string;
   domId?: string | null;
   selector?: string;
   selectorIndex?: number;
+  sourceFile?: string;
+  activeCompositionPath?: string | null;
 }
 
 /**
@@ -35,37 +39,108 @@ export interface ElementAddress {
  * `data-hf-id` survives edits that renumber or reorder; a bare selector does not.
  */
 export function mintElementHandle(address: ElementAddress): string | null {
-  if (address.hfId) return `hf${SEPARATOR}${address.hfId}`;
-  if (address.domId) return `dom${SEPARATOR}${address.domId}`;
+  const scoped = (value: string) => {
+    if (!address.sourceFile || !address.activeCompositionPath) return value;
+    if (address.projectId) {
+      return [
+        "v2",
+        encodeURIComponent(address.projectId),
+        encodeURIComponent(address.activeCompositionPath),
+        encodeURIComponent(address.sourceFile),
+        encodeURIComponent(value),
+      ].join(SEPARATOR);
+    }
+    return [
+      "v1",
+      encodeURIComponent(address.activeCompositionPath),
+      encodeURIComponent(address.sourceFile),
+      encodeURIComponent(value),
+    ].join(SEPARATOR);
+  };
+
+  if (address.hfId) return `hf${SEPARATOR}${scoped(address.hfId)}`;
+  if (address.domId) return `dom${SEPARATOR}${scoped(address.domId)}`;
   if (address.selector) {
     const index = address.selectorIndex ?? 0;
-    return `sel${SEPARATOR}${address.selector}${INDEX_SEPARATOR}${index}`;
+    return `sel${SEPARATOR}${scoped(address.selector)}${INDEX_SEPARATOR}${index}`;
   }
   return null;
 }
 
-export function timelineElementAddress(element: TimelineElement): ElementAddress {
+export function timelineElementAddress(
+  element: TimelineElement,
+  activeCompositionPath: string | null = "index.html",
+  projectId?: string | null,
+): ElementAddress {
+  const rootFile = activeCompositionPath ?? "index.html";
   return {
+    projectId,
     hfId: element.hfId,
     domId: element.domId,
     selector: element.selector,
     selectorIndex: element.selectorIndex,
+    sourceFile: element.sourceFile ?? rootFile,
+    activeCompositionPath: rootFile,
   };
 }
 
-export function patchTargetAddress(target: PatchTarget): ElementAddress {
+export function patchTargetAddress(
+  target: PatchTarget & { sourceFile?: string },
+  activeCompositionPath?: string | null,
+  projectId?: string | null,
+): ElementAddress {
   return {
+    projectId,
     hfId: target.hfId,
     domId: target.id,
     selector: target.selector,
     selectorIndex: target.selectorIndex,
+    sourceFile: target.sourceFile,
+    activeCompositionPath,
   };
 }
 
-interface ParsedHandle {
+export interface ParsedHandle {
   scheme: "hf" | "dom" | "sel";
+  version: 0 | 1 | 2;
   value: string;
   index: number;
+  projectId?: string;
+  sourceFile?: string;
+  activeCompositionPath?: string;
+}
+
+function decodeScopedParts(rest: string, version: "v1" | "v2", count: number) {
+  const parts = rest.split(SEPARATOR);
+  if (parts[0] !== version || parts.length !== count + 1) return null;
+  return parts.slice(1).map(decodeHandlePart);
+}
+
+function parseV1ScopedValue(rest: string): Omit<ParsedHandle, "scheme" | "index"> | null {
+  const [activeCompositionPath, sourceFile, value] = decodeScopedParts(rest, "v1", 3) ?? [];
+  if (!activeCompositionPath || !sourceFile || !value) return null;
+  return { version: 1, value, sourceFile, activeCompositionPath };
+}
+
+function parseV2ScopedValue(rest: string): Omit<ParsedHandle, "scheme" | "index"> | null {
+  const [projectId, activeCompositionPath, sourceFile, value] =
+    decodeScopedParts(rest, "v2", 4) ?? [];
+  if (!projectId || !activeCompositionPath || !sourceFile || !value) return null;
+  return { version: 2, projectId, value, sourceFile, activeCompositionPath };
+}
+
+function parseScopedValue(rest: string): Omit<ParsedHandle, "scheme" | "index"> | null {
+  if (rest.startsWith(`v1${SEPARATOR}`)) return parseV1ScopedValue(rest);
+  if (rest.startsWith(`v2${SEPARATOR}`)) return parseV2ScopedValue(rest);
+  return { value: rest, version: 0 };
+}
+
+function decodeHandlePart(value: string): string | null {
+  try {
+    return decodeURIComponent(value) || null;
+  } catch {
+    return null;
+  }
 }
 
 export function parseElementHandle(handle: string): ParsedHandle | null {
@@ -74,15 +149,25 @@ export function parseElementHandle(handle: string): ParsedHandle | null {
   const scheme = handle.slice(0, separatorAt);
   const rest = handle.slice(separatorAt + 1);
   if (!rest) return null;
-  if (scheme === "hf" || scheme === "dom") return { scheme, value: rest, index: 0 };
+  if (scheme === "hf" || scheme === "dom") {
+    const scoped = parseScopedValue(rest);
+    return scoped ? { scheme, ...scoped, index: 0 } : null;
+  }
   if (scheme !== "sel") return null;
 
   // Only the LAST `#` splits the index off: CSS selectors contain `#` themselves.
   const indexAt = rest.lastIndexOf(INDEX_SEPARATOR);
-  if (indexAt <= 0) return { scheme, value: rest, index: 0 };
+  if (indexAt <= 0) {
+    const scoped = parseScopedValue(rest);
+    return scoped ? { scheme, ...scoped, index: 0 } : null;
+  }
   const index = Number(rest.slice(indexAt + 1));
-  if (!Number.isInteger(index) || index < 0) return { scheme, value: rest, index: 0 };
-  return { scheme, value: rest.slice(0, indexAt), index };
+  if (!Number.isInteger(index) || index < 0) {
+    const scoped = parseScopedValue(rest);
+    return scoped ? { scheme, ...scoped, index: 0 } : null;
+  }
+  const scoped = parseScopedValue(rest.slice(0, indexAt));
+  return scoped ? { scheme, ...scoped, index } : null;
 }
 
 /**
@@ -95,35 +180,67 @@ export function parseElementHandle(handle: string): ParsedHandle | null {
 export function resolveElementHandle(doc: Document, handle: string): HTMLElement | null {
   const parsed = parseElementHandle(handle);
   if (!parsed) return null;
-
-  if (parsed.scheme === "dom") return asHtmlElement(doc, doc.getElementById(parsed.value));
-  if (parsed.scheme === "hf") {
-    return asHtmlElement(doc, doc.querySelector(`[data-hf-id="${cssEscape(parsed.value)}"]`));
-  }
-
-  let matches: NodeListOf<Element>;
-  try {
-    matches = doc.querySelectorAll(parsed.value);
-  } catch {
-    // A selector minted from a previous document can be invalid in this one.
-    return null;
-  }
-  return asHtmlElement(doc, matches.item(parsed.index));
+  return findElementForSelection(
+    doc,
+    {
+      hfId: parsed.scheme === "hf" ? parsed.value : undefined,
+      id: parsed.scheme === "dom" ? parsed.value : undefined,
+      selector: parsed.scheme === "sel" ? parsed.value : undefined,
+      selectorIndex: parsed.scheme === "sel" ? parsed.index : undefined,
+      sourceFile: parsed.sourceFile,
+    },
+    parsed.activeCompositionPath ?? null,
+  );
 }
 
-function cssEscape(value: string): string {
-  // ponytail: happy-dom and jsdom don't always ship CSS.escape; quoting the two
-  // characters that can break out of an attribute selector covers this use.
-  return typeof CSS?.escape === "function" ? CSS.escape(value) : value.replace(/["\\]/g, "\\$&");
+/** Legacy read handles remain valid, but a scoped handle must name the active project. */
+export function elementHandleMatchesProject(handle: string, projectId: string | null): boolean {
+  const parsed = parseElementHandle(handle);
+  if (!parsed) return false;
+  return parsed.version !== 2 || (!!projectId && parsed.projectId === projectId);
 }
 
+export type LiveHandleResolution<T extends { element: HTMLElement }> =
+  | { status: "ready"; selection: T }
+  | { status: "preview-unavailable" }
+  | { status: "not-found" }
+  | { status: "unsupported" }
+  | { status: "changed" };
+
 /**
- * `instanceof HTMLElement` is checked against the OWNING document's realm.
- * The preview lives in an iframe, so Studio's own `HTMLElement` is a different
- * constructor and the naive check fails on every real preview element.
+ * Resolve and build a selection across one possible preview reload.
+ *
+ * Building a selection can await a source probe. A thumbnail refresh may
+ * replace the preview document during that await, leaving an otherwise valid
+ * selection attached to the old document with a truthful-looking 0x0 box.
+ * Reacquire once from the current document, then refuse if it moves again.
  */
-function asHtmlElement(doc: Document, node: Element | null): HTMLElement | null {
-  if (!node) return null;
-  const ctor = doc.defaultView?.HTMLElement;
-  return ctor && node instanceof ctor ? node : null;
+export async function resolveLiveHandleSelection<T extends { element: HTMLElement }>(
+  getPreviewDocument: () => Document | null,
+  handle: string,
+  buildSelection: (element: HTMLElement) => Promise<T | null>,
+): Promise<LiveHandleResolution<T>> {
+  let reloadObserved = false;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const doc = getPreviewDocument();
+    if (!doc) return { status: "preview-unavailable" };
+    const element = resolveElementHandle(doc, handle);
+    if (!element) return { status: reloadObserved ? "changed" : "not-found" };
+
+    const selection = await buildSelection(element);
+    const currentDoc = getPreviewDocument();
+    const previewChanged =
+      currentDoc !== doc ||
+      element.ownerDocument !== doc ||
+      !element.isConnected ||
+      (selection !== null &&
+        (selection.element.ownerDocument !== doc || !selection.element.isConnected));
+    if (previewChanged) {
+      reloadObserved = true;
+      continue;
+    }
+    if (!selection) return { status: "unsupported" };
+    return { status: "ready", selection };
+  }
+  return { status: "changed" };
 }