@hyperframes/studio-server 0.8.57 → 0.8.59

package/dist/index.js

@@ -3,14 +3,17 @@ import {
   findUnsafeMutationValues
 } from "./chunk-X62ASOGO.js";
 import {
+  dedupeClonedCompositionId,
+  findTargetElement,
   isHTMLElement,
+  parseSourceDocument,
   patchElementInHtml,
   probeElementInSource,
   removeElementFromHtml,
   splitElementInHtml,
   unwrapElementsFromHtml,
   wrapElementsInHtml
-} from "./chunk-MMVFN2BI.js";
+} from "./chunk-KFPWE4Q7.js";
 import {
   getElementScreenshotClip
 } from "./chunk-W2SBTCO2.js";
@@ -19,12 +22,12 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "./chunk-QN7UPP3B.js";
+} from "./chunk-PGL4S2ZU.js";
 import {
   ProxyCapacityError,
   ProxyTranscodeError,
   resolveProxy
-} from "./chunk-BVSPLTYT.js";
+} from "./chunk-45POWYFS.js";
 import {
   PROXY_VARIANT_CONFIG,
   decideMediaProxyEligibility,
@@ -33,7 +36,7 @@ import {
   probeMediaMetadata,
   recordProxyRequest,
   resolveProxyVariantRequest
-} from "./chunk-QJ73CZFQ.js";
+} from "./chunk-4MNTZVVZ.js";
 import {
   STUDIO_MANUAL_EDITS_PATH,
   createStudioManualEditsRenderBodyScript,
@@ -297,8 +300,8 @@ import {
   existsSync as existsSync3,
   ftruncateSync,
   openSync,
-  readFileSync as readFileSync4,
-  writeFileSync as writeFileSync4,
+  readFileSync as readFileSync5,
+  writeFileSync as writeFileSync5,
   writeSync,
   mkdirSync as mkdirSync3,
   unlinkSync as unlinkSync2,
@@ -607,6 +610,13 @@ function recordFileWriteReceipt(absPath, receipt) {
   current.push({ ...receipt, recordedAt: now });
   receipts.set(absPath, current);
 }
+function clearFileWriteReceipt(absPath, version, writeToken) {
+  const current = (receipts.get(absPath) ?? []).filter(
+    (entry) => entry.version !== version || entry.writeToken !== writeToken
+  );
+  if (current.length > 0) receipts.set(absPath, current);
+  else receipts.delete(absPath);
+}
 function identifyFileWrite(absPath, expectedVersion) {
   const now = Date.now();
   const current = (receipts.get(absPath) ?? []).filter(
@@ -624,6 +634,79 @@ function identifyFileWrite(absPath, expectedVersion) {
 }
 var consumeFileWriteReceipt = identifyFileWrite;
 
+// src/helpers/applyFileMutations.ts
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
+function applyFileMutations(projectDir, mutations, requestToken, writeFile = writeFileSync4) {
+  const prepared = mutations.map((mutation) => ({
+    ...mutation,
+    before: mutation.before ?? readFileSync3(mutation.absPath, "utf-8")
+  }));
+  const results = [];
+  const attempted = [];
+  try {
+    for (const mutation of prepared) {
+      results.push(applyOneMutation(projectDir, mutation, requestToken, writeFile, attempted));
+    }
+    return results;
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const mutation of attempted.reverse()) {
+      try {
+        writeFile(mutation.absPath, mutation.before, "utf-8");
+        clearFileWriteReceipt(mutation.absPath, mutation.version, mutation.writeToken);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [error, ...rollbackErrors],
+        "File mutation failed and rollback did not complete"
+      );
+    }
+    throw error;
+  }
+}
+function applyOneMutation(projectDir, mutation, requestToken, writeFile, attempted) {
+  const current = readFileSync3(mutation.absPath, "utf-8");
+  assertExpectedVersion(mutation.expectedVersion, current);
+  if (mutation.after === mutation.before) {
+    return {
+      ...mutation,
+      before: current,
+      changed: false,
+      backupPath: null,
+      version: fileContentVersion(mutation.before),
+      writeToken: null
+    };
+  }
+  const backup = snapshotBeforeWrite(projectDir, mutation.absPath);
+  if (backup.error) throw new Error(`backup failed: ${backup.error}`);
+  const before = current;
+  const version = fileContentVersion(mutation.after);
+  const writeToken = createWriteToken(requestToken);
+  attempted.push({ ...mutation, before, version, writeToken });
+  writeFile(mutation.absPath, mutation.after, "utf-8");
+  recordFileWriteReceipt(mutation.absPath, {
+    path: mutation.sourceFile,
+    version,
+    writeToken
+  });
+  return {
+    ...mutation,
+    before,
+    changed: true,
+    backupPath: backupPathForResponse(projectDir, backup.backupPath),
+    version,
+    writeToken
+  };
+}
+function assertExpectedVersion(expectedVersion, current) {
+  if (expectedVersion !== void 0 && fileContentVersion(current) !== expectedVersion) {
+    throw new Error("file changed since the timeline was read");
+  }
+}
+
 // src/routes/files.ts
 import { classifyPropertyGroup } from "@hyperframes/parsers/gsap-constants";
 import { parseGsapScriptAcorn } from "@hyperframes/parsers/gsap-parser-acorn";
@@ -659,7 +742,7 @@ import {
 import { parseHTML as parseHTML2 } from "linkedom";
 
 // src/helpers/compositionInsertion.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3, realpathSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync4, realpathSync } from "fs";
 import { randomUUID as randomUUID2 } from "crypto";
 import { dirname as dirname2, relative as relative3, resolve as resolve2, sep as sep2 } from "path";
 import { parseHTML } from "linkedom";
@@ -731,7 +814,7 @@ function validateDependencyGraph(projectDir, targetAbs, sourceAbs) {
     }
     if (visited.has(file)) return;
     visiting.add(file);
-    const source = readFileSync3(file, "utf-8");
+    const source = readFileSync4(file, "utf-8");
     const { document } = compositionRoot(source);
     for (const host of descendants(document, "[data-composition-src]")) {
       const dependency = host.getAttribute("data-composition-src");
@@ -795,7 +878,7 @@ function insertCompositionIntoSource(input) {
   const targetAbs = canonicalProjectFile(input.projectDir, input.targetPath);
   const sourceAbs = canonicalProjectFile(input.projectDir, input.sourcePath);
   validateDependencyGraph(input.projectDir, targetAbs, sourceAbs);
-  const source = readFileSync3(sourceAbs, "utf-8");
+  const source = readFileSync4(sourceAbs, "utf-8");
   const sourceComposition = compositionRoot(source).root;
   const duration = positiveAttribute(
     sourceComposition,
@@ -983,7 +1066,7 @@ function foldElementPatches(originalContent, patches) {
   }
   return { content, matched };
 }
-function commitElementPatchBatches(projectDir, batches, writeFile = writeFileSync4) {
+function commitElementPatchBatches(projectDir, batches, writeFile = writeFileSync5, requestToken) {
   const resolvedPaths = /* @__PURE__ */ new Set();
   const prepared = [];
   for (const batch of batches) {
@@ -993,7 +1076,7 @@ function commitElementPatchBatches(projectDir, batches, writeFile = writeFileSyn
     resolvedPaths.add(absPath);
     let before;
     try {
-      before = readFileSync4(absPath, "utf-8");
+      before = readFileSync5(absPath, "utf-8");
     } catch {
       return { error: "not-found", sourceFile: batch.sourceFile };
     }
@@ -1019,64 +1102,34 @@ function commitElementPatchBatches(projectDir, batches, writeFile = writeFileSyn
       }))
     };
   }
-  const files = [];
-  const attemptedWrites = [];
-  try {
-    for (const file of prepared) {
-      if (file.after === file.before) {
-        files.push({
-          sourceFile: file.sourceFile,
-          changed: false,
-          matched: file.matched,
-          before: file.before,
-          after: file.before
-        });
-        continue;
-      }
-      const backup = snapshotBeforeWrite(projectDir, file.absPath);
-      if (backup.error) {
-        throw new Error(`Failed to create backup for ${file.sourceFile}: ${backup.error}`);
-      }
-      attemptedWrites.push(file);
-      writeFile(file.absPath, file.after, "utf-8");
-      files.push({
-        sourceFile: file.sourceFile,
-        changed: true,
-        matched: file.matched,
-        before: file.before,
-        after: file.after,
-        backupPath: backupPathForResponse(projectDir, backup.backupPath)
-      });
-    }
-  } catch (error) {
-    const rollbackErrors = [];
-    for (const file of attemptedWrites.reverse()) {
-      try {
-        writeFile(file.absPath, file.before, "utf-8");
-      } catch (rollbackError) {
-        rollbackErrors.push(rollbackError);
-      }
-    }
-    if (rollbackErrors.length > 0) {
-      throw new AggregateError(
-        [error, ...rollbackErrors],
-        "Element patch batch failed and rollback did not complete"
-      );
-    }
-    throw error;
-  }
+  const applied = applyFileMutations(
+    projectDir,
+    prepared.map(({ sourceFile, absPath, before, after }) => ({
+      sourceFile,
+      absPath,
+      before,
+      after
+    })),
+    requestToken,
+    writeFile
+  );
+  const files = applied.map((file, index) => ({
+    sourceFile: file.sourceFile,
+    changed: file.changed,
+    matched: prepared[index]?.matched ?? [],
+    before: file.before,
+    after: file.after,
+    backupPath: file.backupPath ?? void 0
+  }));
   return { durable: true, files };
 }
 function commitElementPatchBatchesWithReceipts(c, projectDir, batches) {
-  const result = commitElementPatchBatches(projectDir, batches);
-  if ("error" in result || !result.durable) return result;
-  for (const file of result.files) {
-    if (!file.changed) continue;
-    const absPath = resolveWithinProject(projectDir, file.sourceFile);
-    if (!absPath) throw new Error(`Committed element patch escaped project: ${file.sourceFile}`);
-    recordMutationReceipt(c, file.sourceFile, absPath, file.after);
-  }
-  return result;
+  return commitElementPatchBatches(
+    projectDir,
+    batches,
+    writeFileSync5,
+    c.req.header("X-Hyperframes-Write-Token")
+  );
 }
 function recordMutationReceipt(c, filePath, absPath, html) {
   const version = fileContentVersion(html);
@@ -1085,7 +1138,7 @@ function recordMutationReceipt(c, filePath, absPath, html) {
   return { version, writeToken };
 }
 function writeFileWithReceipt(c, filePath, absPath, html) {
-  writeFileSync4(absPath, html, "utf-8");
+  writeFileSync5(absPath, html, "utf-8");
   return recordMutationReceipt(c, filePath, absPath, html);
 }
 function writeMutationResult(c, projectDir, filePath, absPath, html) {
@@ -1170,11 +1223,11 @@ function updateReferences(projectDir, oldPath, newPath) {
   let updatedCount = 0;
   for (const file of textFiles) {
     if (!isSafePath(projectDir, file)) continue;
-    const content = readFileSync4(file, "utf-8");
+    const content = readFileSync5(file, "utf-8");
     if (!content.includes(oldPath)) continue;
     const updated = content.split(oldPath).join(newPath);
     if (updated !== content) {
-      writeFileSync4(file, updated, "utf-8");
+      writeFileSync5(file, updated, "utf-8");
       updatedCount++;
     }
   }
@@ -1444,7 +1497,7 @@ function containsRawGsapExpression(value) {
   return Object.values(value).some(containsRawGsapExpression);
 }
 async function prepareGsapMutationScript(c, res, firstMutation) {
-  const beforeHtml = readFileSync4(res.absPath, "utf-8");
+  const beforeHtml = readFileSync5(res.absPath, "utf-8");
   let html = beforeHtml;
   let block = extractGsapScriptBlock(html);
   if (!block && (firstMutation.type === "add" || firstMutation.type === "add-with-keyframes")) {
@@ -1511,7 +1564,7 @@ async function applyGsapMutations(c, res, mutations) {
   const changed = block.scriptText !== initialScript;
   const newHtml = changed ? block.replaceScript(block.scriptText) : html;
   let backupPath = null;
-  if (readFileSync4(res.absPath, "utf-8") !== beforeHtml) {
+  if (readFileSync5(res.absPath, "utf-8") !== beforeHtml) {
     return c.json({ error: "file changed during GSAP mutation", conflict: true }, 409);
   }
   if (changed) {
@@ -2294,7 +2347,7 @@ async function processUploadedFiles(formData, targetDir, projectDir) {
       try {
         const fd = openSync(finalPath, "wx");
         try {
-          writeFileSync4(fd, buffer);
+          writeFileSync5(fd, buffer);
         } finally {
           closeSync(fd);
         }
@@ -2332,7 +2385,7 @@ function registerFileRoutes(api, adapter) {
       }
       return c.json({ error: "not found" }, 404);
     }
-    const content = readFileSync4(res.absPath);
+    const content = readFileSync5(res.absPath);
     const version = fileContentVersion(content);
     c.header("ETag", version);
     return c.json({ filename: res.filePath, content: content.toString("utf-8"), version });
@@ -2346,7 +2399,7 @@ function registerFileRoutes(api, adapter) {
     if (expectedVersion === null && !createOnly) {
       let currentContent = null;
       try {
-        currentContent = readFileSync4(res.absPath);
+        currentContent = readFileSync5(res.absPath);
       } catch (error) {
         if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
           throw error;
@@ -2372,7 +2425,7 @@ function registerFileRoutes(api, adapter) {
         if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
           throw error;
         }
-        const currentContent = readFileSync4(res.absPath);
+        const currentContent = readFileSync5(res.absPath);
         return c.json(
           {
             error: "file conflict",
@@ -2407,7 +2460,7 @@ function registerFileRoutes(api, adapter) {
         );
       }
       try {
-        const currentContent = readFileSync4(fd);
+        const currentContent = readFileSync5(fd);
         const currentVersion = fileContentVersion(currentContent);
         if (expectedVersion !== currentVersion) {
           return c.json(
@@ -2446,7 +2499,7 @@ function registerFileRoutes(api, adapter) {
     ensureDir(res.absPath);
     const body = Buffer.from(await c.req.arrayBuffer());
     try {
-      writeFileSync4(res.absPath, body, { flag: "wx" });
+      writeFileSync5(res.absPath, body, { flag: "wx" });
     } catch (error) {
       if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
         throw error;
@@ -2480,7 +2533,7 @@ function registerFileRoutes(api, adapter) {
     }
     let before;
     try {
-      before = readFileSync4(ctx.absPath, "utf-8");
+      before = readFileSync5(ctx.absPath, "utf-8");
     } catch (error) {
       if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
         throw error;
@@ -2537,7 +2590,7 @@ function registerFileRoutes(api, adapter) {
     }
     const parsed = await parseMutationBody(c);
     if ("error" in parsed) return parsed.error;
-    const originalContent = readFileSync4(ctx.absPath, "utf-8");
+    const originalContent = readFileSync5(ctx.absPath, "utf-8");
     return writeIfChanged(
       c,
       ctx.project.dir,
@@ -2558,7 +2611,7 @@ function registerFileRoutes(api, adapter) {
     if (!Array.isArray(targets) || targets.length === 0) {
       return c.json({ error: "targets required" }, 400);
     }
-    const originalContent = readFileSync4(ctx.absPath, "utf-8");
+    const originalContent = readFileSync5(ctx.absPath, "utf-8");
     let next = originalContent;
     for (const target of targets) {
       next = removeElementFromHtml(next, target);
@@ -2591,7 +2644,7 @@ function registerFileRoutes(api, adapter) {
         seen.add(absPath);
         let before;
         try {
-          before = readFileSync4(absPath, "utf-8");
+          before = readFileSync5(absPath, "utf-8");
         } catch {
           return c.json({ error: `not found: ${file.path}` }, 404);
         }
@@ -2618,7 +2671,7 @@ function registerFileRoutes(api, adapter) {
         prepared.push(folded);
       }
       for (const file of prepared) {
-        const current = readFileSync4(file.absPath, "utf-8");
+        const current = readFileSync5(file.absPath, "utf-8");
         if (current !== file.before) {
           return c.json(
             {
@@ -2648,7 +2701,7 @@ function registerFileRoutes(api, adapter) {
       const written = [];
       try {
         for (const file of prepared) {
-          writeFileSync4(file.absPath, file.after, "utf-8");
+          writeFileSync5(file.absPath, file.after, "utf-8");
           written.push(file);
           recordFileWriteReceipt(file.absPath, {
             path: file.path,
@@ -2660,12 +2713,12 @@ function registerFileRoutes(api, adapter) {
         const conflicts = [];
         for (const file of written.reverse()) {
           try {
-            const current = readFileSync4(file.absPath, "utf-8");
+            const current = readFileSync5(file.absPath, "utf-8");
             if (current !== file.after) {
               conflicts.push(file.path);
               continue;
             }
-            writeFileSync4(file.absPath, file.before, "utf-8");
+            writeFileSync5(file.absPath, file.before, "utf-8");
             recordFileWriteReceipt(file.absPath, {
               path: file.path,
               version: fileContentVersion(file.before),
@@ -2708,7 +2761,7 @@ function registerFileRoutes(api, adapter) {
     const fallbackTiming = typeof parsed.body.elementStart === "number" && typeof parsed.body.elementDuration === "number" ? { start: parsed.body.elementStart, duration: parsed.body.elementDuration } : void 0;
     let originalContent;
     try {
-      originalContent = readFileSync4(ctx.absPath, "utf-8");
+      originalContent = readFileSync5(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2764,7 +2817,7 @@ function registerFileRoutes(api, adapter) {
     }
     let originalContent;
     try {
-      originalContent = readFileSync4(ctx.absPath, "utf-8");
+      originalContent = readFileSync5(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2865,7 +2918,7 @@ function registerFileRoutes(api, adapter) {
     }
     let originalContent;
     try {
-      originalContent = readFileSync4(ctx.absPath, "utf-8");
+      originalContent = readFileSync5(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2920,7 +2973,7 @@ function registerFileRoutes(api, adapter) {
     ).map((entry) => ({ target: entry.target, track: entry.track }));
     let originalContent;
     try {
-      originalContent = readFileSync4(ctx.absPath, "utf-8");
+      originalContent = readFileSync5(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2949,7 +3002,7 @@ function registerFileRoutes(api, adapter) {
     if ("error" in parsed) return parsed.error;
     let content;
     try {
-      content = readFileSync4(ctx.absPath, "utf-8");
+      content = readFileSync5(ctx.absPath, "utf-8");
     } catch {
       return c.json({ exists: false });
     }
@@ -2992,7 +3045,7 @@ function registerFileRoutes(api, adapter) {
       return c.json({ error: "forbidden" }, 403);
     }
     ensureDir(destAbs);
-    writeFileSync4(destAbs, readFileSync4(srcAbs));
+    writeFileSync5(destAbs, readFileSync5(srcAbs));
     return c.json({ ok: true, path: copyPath }, 201);
   });
   const MAX_UPLOAD_BYTES = 500 * 1024 * 1024;
@@ -3022,7 +3075,7 @@ function registerFileRoutes(api, adapter) {
       mustExist: true
     });
     if ("error" in res) return res.error;
-    const html = readFileSync4(res.absPath, "utf-8");
+    const html = readFileSync5(res.absPath, "utf-8");
     const block = extractGsapScriptBlock(html);
     if (!block) {
       return c.json({
@@ -3081,17 +3134,17 @@ function registerFileRoutes(api, adapter) {
     if (!body || typeof body.expected !== "string" || typeof body.restore !== "string") {
       return c.json({ error: "expected and restore contents required" }, 400);
     }
-    const current = readFileSync4(res.absPath, "utf-8");
+    const current = readFileSync5(res.absPath, "utf-8");
     if (current !== body.expected) {
       return c.json({ ok: true, restored: false, conflict: true });
     }
-    writeFileSync4(res.absPath, body.restore, "utf-8");
+    writeFileSync5(res.absPath, body.restore, "utf-8");
     return c.json({ ok: true, restored: true, conflict: false });
   });
 }
 
 // src/routes/preview.ts
-import { createReadStream, existsSync as existsSync5, readFileSync as readFileSync7, statSync as statSync3 } from "fs";
+import { createReadStream, existsSync as existsSync5, readFileSync as readFileSync8, statSync as statSync3 } from "fs";
 import { Readable } from "stream";
 import { join as join8, resolve as resolve4 } from "path";
 import { createHash as createHash3 } from "crypto";
@@ -3099,7 +3152,7 @@ import { injectScriptsIntoHtml, stripEmbeddedRuntimeScripts as stripEmbeddedRunt
 import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
 
 // src/helpers/subComposition.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
 import { join as join7 } from "path";
 import { parseHTML as parseHTML3 } from "linkedom";
 import {
@@ -3211,7 +3264,7 @@ function tagRootCompositionFile(bodyHtml, compPath) {
 function buildSubCompositionHtml(projectDir, compPath, runtimeUrl, baseHref, rawOverride) {
   const compFile = join7(projectDir, compPath);
   if (!existsSync4(compFile)) return null;
-  const rawComp = rawOverride ?? readFileSync5(compFile, "utf-8");
+  const rawComp = rawOverride ?? readFileSync6(compFile, "utf-8");
   let compHeadContent = "";
   let rewrittenContent;
   let htmlAttrs = "";
@@ -3244,7 +3297,7 @@ function buildSubCompositionHtml(projectDir, compPath, runtimeUrl, baseHref, raw
   const indexPath = join7(projectDir, "index.html");
   let headContent = "";
   if (existsSync4(indexPath)) {
-    const indexHtml = readFileSync5(indexPath, "utf-8");
+    const indexHtml = readFileSync6(indexPath, "utf-8");
     const headMatch = indexHtml.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
     headContent = headMatch?.[1] ?? "";
   }
@@ -3288,8 +3341,8 @@ import {
   fstatSync,
   ftruncateSync as ftruncateSync2,
   openSync as openSync2,
-  readFileSync as readFileSync6,
-  writeFileSync as writeFileSync5,
+  readFileSync as readFileSync7,
+  writeFileSync as writeFileSync6,
   writeSync as writeSync2
 } from "fs";
 function persistHfIdsIfNeeded(filePath, html) {
@@ -3298,9 +3351,9 @@ function persistHfIdsIfNeeded(filePath, html) {
   const idsAfter = (normalized.match(/\bdata-hf-id=/g) ?? []).length;
   if (idsAfter > idsBefore) {
     try {
-      const current = readFileSync6(filePath, "utf-8");
+      const current = readFileSync7(filePath, "utf-8");
       if (current === html) {
-        writeFileSync5(filePath, normalized, "utf-8");
+        writeFileSync6(filePath, normalized, "utf-8");
       }
     } catch (err) {
       console.warn("[hyperframes] persistHfIdsIfNeeded: failed to write ids to disk:", err);
@@ -3326,7 +3379,7 @@ function stampFileHfIds(filePath) {
   if (fd === null) return null;
   try {
     if (!fstatSync(fd).isFile()) return null;
-    const html = readFileSync6(fd, "utf-8");
+    const html = readFileSync7(fd, "utf-8");
     const normalized = ensureHfIds(html);
     const idsBefore = (html.match(/\bdata-hf-id=/g) ?? []).length;
     const idsAfter = (normalized.match(/\bdata-hf-id=/g) ?? []).length;
@@ -3388,7 +3441,7 @@ function readStudioMotionManifestContent(projectDir) {
   const manifestPath = join8(projectDir, STUDIO_MOTION_PATH);
   if (!existsSync5(manifestPath)) return "";
   try {
-    return readFileSync7(manifestPath, "utf-8");
+    return readFileSync8(manifestPath, "utf-8");
   } catch {
     return "";
   }
@@ -3534,14 +3587,14 @@ function resolveProjectMainHtml(projectDir, projectId) {
   const indexPath = join8(projectDir, "index.html");
   if (existsSync5(indexPath)) {
     return {
-      html: readFileSync7(indexPath, "utf-8"),
+      html: readFileSync8(indexPath, "utf-8"),
       compositionPath: "index.html"
     };
   }
   const blockHtmlPath = join8(projectDir, `${projectId}.html`);
   if (existsSync5(blockHtmlPath)) {
     return {
-      html: readFileSync7(blockHtmlPath, "utf-8"),
+      html: readFileSync8(blockHtmlPath, "utf-8"),
       compositionPath: `${projectId}.html`
     };
   }
@@ -3735,7 +3788,7 @@ ${runtimeTag}`;
       }
       servedContentType = PROXY_VARIANT_CONFIG[proxyVariant].contentType;
     }
-    const textBuffer = isText ? Buffer.from(readFileSync7(file, "utf-8"), "utf-8") : null;
+    const textBuffer = isText ? Buffer.from(readFileSync8(file, "utf-8"), "utf-8") : null;
     const totalSize = textBuffer ? textBuffer.length : statSync3(servedPath).size;
     const bodyFor = (start, end) => textBuffer ? new Uint8Array(textBuffer.subarray(start, end + 1)) : (
       // Node's web stream type and the DOM one do not overlap for tsc on
@@ -3779,7 +3832,7 @@ ${runtimeTag}`;
 }
 
 // src/routes/lint.ts
-import { readFileSync as readFileSync8 } from "fs";
+import { readFileSync as readFileSync9 } from "fs";
 import { join as join9 } from "path";
 async function collectProjectFindings(adapter, projectDir) {
   const findings = [];
@@ -3798,7 +3851,7 @@ async function lintUncoveredHtml(adapter, projectDir, htmlFiles, coveredFiles) {
   const findings = [];
   for (const file of htmlFiles) {
     if (coveredFiles.has(file)) continue;
-    const content = readFileSync8(join9(projectDir, file), "utf-8");
+    const content = readFileSync9(join9(projectDir, file), "utf-8");
     const result = await adapter.lint(content, { filePath: file, isSubComposition: true });
     for (const finding of result?.findings ?? []) {
       findings.push({ ...finding, file });
@@ -3831,7 +3884,7 @@ function registerLintRoutes(api, adapter) {
 
 // src/routes/render.ts
 import { streamSSE } from "hono/streaming";
-import { existsSync as existsSync6, readFileSync as readFileSync9, mkdirSync as mkdirSync4, unlinkSync as unlinkSync3, readdirSync as readdirSync5, statSync as statSync4 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync10, mkdirSync as mkdirSync4, unlinkSync as unlinkSync3, readdirSync as readdirSync5, statSync as statSync4 } from "fs";
 import { join as join10 } from "path";
 import { VALID_CANVAS_RESOLUTIONS } from "@hyperframes/parsers";
 import { formatRenderOutputTimestamp, parseFps } from "@hyperframes/core";
@@ -3969,7 +4022,7 @@ function registerRenderRoutes(api, adapter) {
     }
     const contentType = renderContentType(job.outputPath);
     const filename = job.outputPath.split("/").pop() ?? `render.mp4`;
-    const content = readFileSync9(job.outputPath);
+    const content = readFileSync10(job.outputPath);
     return new Response(content, {
       headers: {
         "Content-Type": contentType,
@@ -3987,7 +4040,7 @@ function registerRenderRoutes(api, adapter) {
     }
     const contentType = renderContentType(job.outputPath);
     const filename = job.outputPath.split("/").pop() ?? `render.mp4`;
-    const content = readFileSync9(job.outputPath);
+    const content = readFileSync10(job.outputPath);
     return new Response(content, {
       headers: {
         "Content-Type": contentType,
@@ -4020,7 +4073,7 @@ function registerRenderRoutes(api, adapter) {
     if (!fp) return c.json({ error: "forbidden" }, 403);
     if (!existsSync6(fp)) return c.json({ error: "not found" }, 404);
     const contentType = renderContentType(fp);
-    const content = readFileSync9(fp);
+    const content = readFileSync10(fp);
     return new Response(content, {
       headers: {
         "Content-Type": contentType,
@@ -4044,7 +4097,7 @@ function registerRenderRoutes(api, adapter) {
       let durationMs;
       if (existsSync6(metaPath)) {
         try {
-          const meta = JSON.parse(readFileSync9(metaPath, "utf-8"));
+          const meta = JSON.parse(readFileSync10(metaPath, "utf-8"));
           if (meta.status === "failed" && !existsSync6(fp)) status = "failed";
           if (meta.durationMs) durationMs = meta.durationMs;
         } catch {
@@ -4078,13 +4131,13 @@ function registerRenderRoutes(api, adapter) {
 import {
   existsSync as existsSync7,
   mkdirSync as mkdirSync5,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   readdirSync as readdirSync6,
   renameSync as renameSync3,
   rmSync as rmSync4,
   statSync as statSync5,
   unlinkSync as unlinkSync4,
-  writeFileSync as writeFileSync6
+  writeFileSync as writeFileSync7
 } from "fs";
 import { join as join11 } from "path";
 import { createHash as createHash4, randomUUID as randomUUID3 } from "crypto";
@@ -4233,7 +4286,7 @@ function pruneThumbnailCache(cacheDir, protectedPaths, now = Date.now()) {
 function writeThumbnailAtomically(path, buffer) {
   const temporaryPath = `${path}.${process.pid}.${randomUUID3()}.tmp`;
   try {
-    writeFileSync6(temporaryPath, buffer, { flag: "wx" });
+    writeFileSync7(temporaryPath, buffer, { flag: "wx" });
     renameSync3(temporaryPath, path);
   } finally {
     rmSync4(temporaryPath, { force: true });
@@ -4271,7 +4324,7 @@ function registerThumbnailRoutes(api, adapter) {
     let sourceKey = "";
     const htmlFile = join11(project.dir, compPath);
     if (existsSync7(htmlFile)) {
-      const html = readFileSync10(htmlFile, "utf-8");
+      const html = readFileSync11(htmlFile, "utf-8");
       sourceKey = `_${createHash4("sha1").update(html).digest("hex").slice(0, 16)}`;
       sourceMtime = Math.round(statSync5(htmlFile).mtimeMs);
       if (!vpWidth) {
@@ -4284,14 +4337,14 @@ function registerThumbnailRoutes(api, adapter) {
     const manualEditsFile = join11(project.dir, STUDIO_MANUAL_EDITS_PATH);
     let manualEditsKey = "";
     if (existsSync7(manualEditsFile)) {
-      const manualEditsContent = readFileSync10(manualEditsFile, "utf-8");
+      const manualEditsContent = readFileSync11(manualEditsFile, "utf-8");
       manualEditsKey = `_${createHash4("sha1").update(manualEditsContent).digest("hex").slice(0, 16)}`;
       sourceMtime = Math.max(sourceMtime, Math.round(statSync5(manualEditsFile).mtimeMs));
     }
     const motionFile = join11(project.dir, STUDIO_MOTION_PATH);
     let motionKey = "";
     if (existsSync7(motionFile)) {
-      const motionContent = readFileSync10(motionFile, "utf-8");
+      const motionContent = readFileSync11(motionFile, "utf-8");
       motionKey = `_${createHash4("sha1").update(motionContent).digest("hex").slice(0, 16)}`;
       sourceMtime = Math.max(sourceMtime, Math.round(statSync5(motionFile).mtimeMs));
     }
@@ -4313,7 +4366,7 @@ function registerThumbnailRoutes(api, adapter) {
       );
     }
     if (existsSync7(cachePath)) {
-      return new Response(new Uint8Array(readFileSync10(cachePath)), {
+      return new Response(new Uint8Array(readFileSync11(cachePath)), {
         headers: { "Content-Type": contentType, "Cache-Control": "no-cache" }
       });
     }
@@ -4368,7 +4421,7 @@ function registerThumbnailRoutes(api, adapter) {
 }
 
 // src/routes/waveform.ts
-import { existsSync as existsSync8, readFileSync as readFileSync11, statSync as statSync6 } from "fs";
+import { existsSync as existsSync8, readFileSync as readFileSync12, statSync as statSync6 } from "fs";
 import { join as join12 } from "path";
 function registerWaveformRoutes(api, adapter) {
   api.get("/projects/:id/waveform/*", async (c) => {
@@ -4384,7 +4437,7 @@ function registerWaveformRoutes(api, adapter) {
     const cachePath = join12(cacheDir, buildWaveformCacheKey(assetPath, stats));
     try {
       if (isWaveformCacheDirectory(cacheDir) && existsSync8(cachePath)) {
-        const peaks2 = JSON.parse(readFileSync11(cachePath, "utf-8"));
+        const peaks2 = JSON.parse(readFileSync12(cachePath, "utf-8"));
         return c.json({ peaks: peaks2 });
       }
     } catch {
@@ -4870,14 +4923,14 @@ function registerMediaRoutes(api, adapter, options = {}) {
 }
 
 // src/routes/globalAssets.ts
-import { existsSync as existsSync10, readFileSync as readFileSync12 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync13 } from "fs";
 import { homedir } from "os";
 import { join as join14 } from "path";
 function readGlobalAssets(home = homedir()) {
   const manifestPath = join14(home, ".media", "manifest.jsonl");
   if (!existsSync10(manifestPath)) return [];
   const out = [];
-  for (const line of readFileSync12(manifestPath, "utf8").split("\n")) {
+  for (const line of readFileSync13(manifestPath, "utf8").split("\n")) {
     if (!line.trim()) continue;
     try {
       const rec = JSON.parse(line);
@@ -4912,6 +4965,57 @@ function createStudioApi(adapter) {
   return api;
 }
 
+// src/helpers/duplicateElement.ts
+import { ensureHfIds as ensureHfIds3 } from "@hyperframes/parsers/hf-ids";
+function duplicateElementInHtml(source, target, newId, at) {
+  const { document, wrappedFragment } = parseSourceDocument(source);
+  const element = findTargetElement(document, target);
+  if (!element || !element.parentElement) return { html: source, matched: false, newId: null };
+  const duration = numericAttribute(element, "data-duration");
+  const track = numericAttribute(element, "data-track-index") ?? 0;
+  if (duration === null || numericAttribute(element, "data-start") === null) {
+    return { html: source, matched: false, newId: null };
+  }
+  const uniqueId = nextUniqueId(document, newId);
+  rippleElements(document, element, at, duration, track);
+  const clone = element.cloneNode(true);
+  if (!isHTMLElement(clone)) return { html: source, matched: false, newId: null };
+  clone.setAttribute("id", uniqueId);
+  dedupeClonedCompositionId(document, clone);
+  stripStableIds(clone);
+  clone.setAttribute("data-start", String(at));
+  element.parentElement.insertBefore(clone, element.nextSibling);
+  const html = wrappedFragment ? document.body.innerHTML || "" : document.toString();
+  return { html: ensureHfIds3(html), matched: true, newId: uniqueId };
+}
+function nextUniqueId(document, newId) {
+  let uniqueId = newId;
+  let suffix = 2;
+  while (document.getElementById(uniqueId)) uniqueId = `${newId}-${suffix++}`;
+  return uniqueId;
+}
+function rippleElements(document, element, at, duration, track) {
+  for (const candidate of Array.from(document.querySelectorAll("[data-start][data-duration]"))) {
+    if (candidate === element || candidate.getAttribute("data-track-index") !== String(track)) {
+      continue;
+    }
+    const start = numericAttribute(candidate, "data-start");
+    if (start !== null && start >= at) {
+      candidate.setAttribute("data-start", String(start + duration));
+    }
+  }
+}
+function stripStableIds(element) {
+  element.removeAttribute("data-hf-id");
+  for (const child of Array.from(element.querySelectorAll("[data-hf-id]"))) {
+    child.removeAttribute("data-hf-id");
+  }
+}
+function numericAttribute(element, name) {
+  const value = Number(element.getAttribute(name));
+  return Number.isFinite(value) ? value : null;
+}
+
 // src/helpers/thumbnailOutput.ts
 function thumbnailDeviceScaleFactor({
   width,
@@ -4984,6 +5088,7 @@ export {
   STUDIO_MANUAL_EDITS_PATH,
   STUDIO_MOTION_PATH,
   affectsProjectSignature,
+  applyFileMutations,
   buildSubCompositionHtml,
   consumeFileWriteReceipt,
   createBackgroundRemovalJob,
@@ -4992,11 +5097,18 @@ export {
   createStudioManualEditsRenderBodyScript,
   createStudioMotionRenderBodyScript,
   createStudioPositionSeekReapplyScript,
+  dedupeClonedCompositionId,
+  duplicateElementInHtml,
   fileContentVersion,
+  findTargetElement,
   getElementScreenshotClip,
   getMimeType,
   identifyFileWrite,
   isSafePath,
+  parseSourceDocument,
+  patchElementInHtml,
+  removeElementFromHtml,
+  splitElementInHtml,
   thumbnailDeviceScaleFactor,
   walkDir
 };