mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
fix(studio): stop a Studio edit from reloading the preview as if it were external
Every mutation route wrote the file without leaving a write receipt, so the watcher's broadcast of Studio's own edit arrived with no identity on it. The external-change coordinator could not tell that echo from an agent or an editor writing the file behind Studio's back, so it took the safe branch and did a full iframe reload. That reload hides the stage for the length of the reload, which is what the flash after a text edit was. Every mutation write now goes through one helper that records the receipt, and the client claims the write before the request goes out rather than after it: the server writes and the watcher fires while the request is still in flight, so a token marked from the response can arrive after the echo it was meant to match. Reproduced in the browser before and after, with the reload path traced end to end. Before, a patch-element write logged `token: null` then a reload from the coordinator; after, the same write logs the token and `suppressed: own write token`, with no reload. Adds `hf-reload-debug` (localStorage, off by default) alongside the existing `hf-resize-debug`: it records each file-change decision and its reason, plus the stack of whoever asked for a full reload.
This commit is contained in:
@@ -425,6 +425,38 @@ describe("registerFileRoutes", () => {
|
||||
expect(readFileSync(join(projectDir, "index.html"), "utf-8")).toContain("After");
|
||||
});
|
||||
|
||||
// Without the receipt the client cannot recognise its own edit in the watcher
|
||||
// broadcast, so it treats it as someone else's write and does a full preview
|
||||
// reload — a visible blank on the stage right after the user typed.
|
||||
it("leaves a write receipt so the patch's own file-change echo is identifiable", async () => {
|
||||
const projectDir = createProjectDir();
|
||||
writeFileSync(projectDir + "/index.html", '<div id="title">Before</div>');
|
||||
const app = new Hono();
|
||||
registerFileRoutes(app, createAdapter(projectDir));
|
||||
|
||||
const response = await app.request(
|
||||
"http://localhost/projects/demo/file-mutations/patch-element/index.html",
|
||||
{
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"X-Hyperframes-Write-Token": "studio-patch-1",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
target: { id: "title" },
|
||||
operations: [{ type: "text-content", property: "textContent", value: "After" }],
|
||||
}),
|
||||
},
|
||||
);
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
expect(consumeFileWriteReceipt(join(projectDir, "index.html"))).toEqual({
|
||||
path: "index.html",
|
||||
version: fileContentVersion(readFileSync(join(projectDir, "index.html"), "utf-8")),
|
||||
writeToken: "studio-patch-1",
|
||||
});
|
||||
});
|
||||
|
||||
it("applies an ordered element patch batch with one file write", async () => {
|
||||
const projectDir = createProjectDir();
|
||||
const original =
|
||||
|
||||
@@ -112,6 +112,7 @@ interface RouteContext {
|
||||
param: (name: string) => string;
|
||||
path: string;
|
||||
query: (name: string) => string | undefined;
|
||||
header: (name: string) => string | undefined;
|
||||
};
|
||||
header: (name: string, value: string) => void;
|
||||
json: (data: unknown, status?: number) => Response;
|
||||
@@ -399,6 +400,35 @@ export function commitElementPatchBatches(
|
||||
return { durable: true, files };
|
||||
}
|
||||
|
||||
/**
|
||||
* Write a mutation result, and leave behind the receipt that claims it.
|
||||
*
|
||||
* The file watcher broadcasts every write, including the ones Studio itself just
|
||||
* asked for. The receipt is what lets the client tell its own echo from an agent
|
||||
* or an editor writing the file behind its back: without one, the client treats
|
||||
* its own edit as an external change and does a full preview reload, which blanks
|
||||
* the stage for a few hundred milliseconds right after the user typed. Every
|
||||
* mutation route writes through here so no route can forget.
|
||||
*/
|
||||
function writeMutationResult(
|
||||
c: RouteContext,
|
||||
projectDir: string,
|
||||
filePath: string,
|
||||
absPath: string,
|
||||
html: string,
|
||||
): { backupPath: string | null; version: string } {
|
||||
const backup = snapshotBeforeWrite(projectDir, absPath);
|
||||
if (backup.error) console.warn(`Failed to create backup for ${filePath}: ${backup.error}`);
|
||||
writeFileSync(absPath, html, "utf-8");
|
||||
const version = fileContentVersion(html);
|
||||
recordFileWriteReceipt(absPath, {
|
||||
path: filePath,
|
||||
version,
|
||||
writeToken: createWriteToken(c.req.header("X-Hyperframes-Write-Token")),
|
||||
});
|
||||
return { backupPath: backupPathForResponse(projectDir, backup.backupPath), version };
|
||||
}
|
||||
|
||||
/** Write `next` to `absPath` only if it differs from `original`, returning a standardized change response. */
|
||||
function writeIfChanged(
|
||||
c: RouteContext,
|
||||
@@ -411,15 +441,13 @@ function writeIfChanged(
|
||||
if (next === original) {
|
||||
return c.json({ ok: true, changed: false, content: original, path: filePath });
|
||||
}
|
||||
const backup = snapshotBeforeWrite(projectDir, absPath);
|
||||
if (backup.error) console.warn(`Failed to create backup for ${filePath}: ${backup.error}`);
|
||||
writeFileSync(absPath, next, "utf-8");
|
||||
const { backupPath } = writeMutationResult(c, projectDir, filePath, absPath, next);
|
||||
return c.json({
|
||||
ok: true,
|
||||
changed: true,
|
||||
content: next,
|
||||
path: filePath,
|
||||
backupPath: backupPathForResponse(projectDir, backup.backupPath),
|
||||
backupPath,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -1238,10 +1266,13 @@ async function applyGsapMutations(
|
||||
return c.json({ error: "file changed during GSAP mutation", conflict: true }, 409);
|
||||
}
|
||||
if (changed) {
|
||||
const backup = snapshotBeforeWrite(res.project.dir, res.absPath);
|
||||
if (backup.error) console.warn(`Failed to create backup for ${res.filePath}: ${backup.error}`);
|
||||
backupPath = backupPathForResponse(res.project.dir, backup.backupPath);
|
||||
writeFileSync(res.absPath, newHtml, "utf-8");
|
||||
backupPath = writeMutationResult(
|
||||
c,
|
||||
res.project.dir,
|
||||
res.filePath,
|
||||
res.absPath,
|
||||
newHtml,
|
||||
).backupPath;
|
||||
}
|
||||
|
||||
const responsePayload: Record<string, unknown> = {
|
||||
@@ -2623,10 +2654,13 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
|
||||
version,
|
||||
});
|
||||
}
|
||||
const backup = snapshotBeforeWrite(ctx.project.dir, ctx.absPath);
|
||||
if (backup.error) console.warn(`Failed to create backup for ${ctx.filePath}: ${backup.error}`);
|
||||
writeFileSync(ctx.absPath, result.html, "utf-8");
|
||||
const version = fileContentVersion(result.html);
|
||||
const { version, backupPath } = writeMutationResult(
|
||||
c,
|
||||
ctx.project.dir,
|
||||
ctx.filePath,
|
||||
ctx.absPath,
|
||||
result.html,
|
||||
);
|
||||
c.header("ETag", version);
|
||||
return c.json({
|
||||
ok: true,
|
||||
@@ -2635,7 +2669,7 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
|
||||
newId: result.newId,
|
||||
path: ctx.filePath,
|
||||
version,
|
||||
backupPath: backupPathForResponse(ctx.project.dir, backup.backupPath),
|
||||
backupPath,
|
||||
});
|
||||
});
|
||||
|
||||
@@ -2676,16 +2710,20 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
|
||||
path: ctx.filePath,
|
||||
});
|
||||
}
|
||||
const backup = snapshotBeforeWrite(ctx.project.dir, ctx.absPath);
|
||||
if (backup.error) console.warn(`Failed to create backup for ${ctx.filePath}: ${backup.error}`);
|
||||
writeFileSync(ctx.absPath, patched, "utf-8");
|
||||
const { backupPath } = writeMutationResult(
|
||||
c,
|
||||
ctx.project.dir,
|
||||
ctx.filePath,
|
||||
ctx.absPath,
|
||||
patched,
|
||||
);
|
||||
return c.json({
|
||||
ok: true,
|
||||
changed: true,
|
||||
matched,
|
||||
content: patched,
|
||||
path: ctx.filePath,
|
||||
backupPath: backupPathForResponse(ctx.project.dir, backup.backupPath),
|
||||
backupPath,
|
||||
});
|
||||
});
|
||||
|
||||
@@ -2807,16 +2845,20 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
|
||||
result.error === "grouped elements must share a single parent" ? 422 : 400,
|
||||
);
|
||||
}
|
||||
const backup = snapshotBeforeWrite(ctx.project.dir, ctx.absPath);
|
||||
if (backup.error) console.warn(`Failed to create backup for ${ctx.filePath}: ${backup.error}`);
|
||||
writeFileSync(ctx.absPath, result.html, "utf-8");
|
||||
const { backupPath } = writeMutationResult(
|
||||
c,
|
||||
ctx.project.dir,
|
||||
ctx.filePath,
|
||||
ctx.absPath,
|
||||
result.html,
|
||||
);
|
||||
return c.json({
|
||||
ok: true,
|
||||
changed: true,
|
||||
groupId: result.groupId,
|
||||
content: result.html,
|
||||
path: ctx.filePath,
|
||||
backupPath: backupPathForResponse(ctx.project.dir, backup.backupPath),
|
||||
backupPath,
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
@@ -3,6 +3,7 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
|
||||
|
||||
export { PROPERTY_DEFAULTS } from "./gsapShared";
|
||||
import { idSelector, matchesExactlyOne } from "./gsapShared";
|
||||
import { studioWriteHeaders } from "../utils/studioFileVersion";
|
||||
|
||||
/**
|
||||
* The selector to author a NEW tween against, minting an id on the element when
|
||||
@@ -119,7 +120,7 @@ export async function assignGsapTargetAutoIdIfNeeded({
|
||||
`/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-element/${encodeURIComponent(targetPath)}`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
|
||||
body: JSON.stringify(patchBody),
|
||||
},
|
||||
);
|
||||
|
||||
@@ -33,6 +33,7 @@ import {
|
||||
readErrorResponseBody,
|
||||
} from "./useDomEditCommitsHelpers";
|
||||
import { cutoverCommittedOrThrow, type CutoverResult } from "../utils/sdkCutover";
|
||||
import { studioWriteHeaders } from "../utils/studioFileVersion";
|
||||
interface RecordEditInput {
|
||||
label: string;
|
||||
kind: EditHistoryKind;
|
||||
@@ -201,7 +202,7 @@ export function useDomEditCommits({
|
||||
`/api/projects/${pid}/file-mutations/patch-element/${encodeURIComponent(targetPath)}`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
|
||||
body: JSON.stringify(patchBody),
|
||||
},
|
||||
);
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { StudioSaveHttpError, trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
|
||||
import type { DomEditPatchBatch } from "./domEditCommitTypes";
|
||||
import { formatFieldsSuffix } from "./gsapScriptCommitHelpers";
|
||||
import { studioWriteHeaders } from "../utils/studioFileVersion";
|
||||
|
||||
export function formatUnsafeFieldList(fields: Array<{ path: string }>): string {
|
||||
return fields.map((field) => field.path).join(", ");
|
||||
@@ -99,7 +100,7 @@ export async function patchElementBatches(projectId: string, batches: DomEditPat
|
||||
`/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-element-batches`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
|
||||
body,
|
||||
},
|
||||
);
|
||||
|
||||
@@ -21,6 +21,7 @@ import {
|
||||
} from "../components/editor/useLayerRevealOverride";
|
||||
import type { CommitDomEditPatchBatches, DomEditPatchBatch } from "./domEditCommitTypes";
|
||||
import { cutoverCommittedOrThrow, type CutoverResult } from "../utils/sdkCutover";
|
||||
import { studioWriteHeaders } from "../utils/studioFileVersion";
|
||||
|
||||
interface UseElementLifecycleOpsParams extends DomEditCommitBaseParams {
|
||||
/** Route delete through SDK when session resolves the hf-id. */
|
||||
@@ -115,7 +116,7 @@ export function useElementLifecycleOps({
|
||||
`/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
|
||||
body: JSON.stringify({ target: patchTarget }),
|
||||
},
|
||||
);
|
||||
|
||||
@@ -4,6 +4,7 @@ import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
|
||||
import type { ExternalConflictSnapshot } from "../utils/externalConflictStorage";
|
||||
import { isSelfWriteEcho } from "./sdkSelfWriteRegistry";
|
||||
import { consumeStudioWriteToken } from "../utils/studioFileVersion";
|
||||
import { logReload } from "../utils/reloadDebug";
|
||||
|
||||
type ExternalChangeDrainResult =
|
||||
| { status: "clean" }
|
||||
@@ -194,6 +195,7 @@ export function useExternalFileChangeCoordinator({
|
||||
|
||||
const reloadAcceptedGeneration = useCallback(
|
||||
(path: string) => {
|
||||
logReload("reload", { path, by: "external-change coordinator" });
|
||||
reloadPreview();
|
||||
reloadSdkSession(path);
|
||||
},
|
||||
@@ -221,11 +223,22 @@ export function useExternalFileChangeCoordinator({
|
||||
pendingTimelinePaths.delete(path);
|
||||
|
||||
const content = readFileChangeContent(payload);
|
||||
if (consumeStudioWriteToken(readFileChangeWriteToken(payload))) return;
|
||||
if (content != null && isSelfWriteEcho(path, content)) return;
|
||||
const token = readFileChangeWriteToken(payload);
|
||||
logReload("file-change", { path, token: token ?? null, hasContent: content != null });
|
||||
if (consumeStudioWriteToken(token)) {
|
||||
logReload("suppressed", { path, why: "own write token" });
|
||||
return;
|
||||
}
|
||||
if (content != null && isSelfWriteEcho(path, content)) {
|
||||
logReload("suppressed", { path, why: "own content echo" });
|
||||
return;
|
||||
}
|
||||
|
||||
const identity = eventIdentity(path, payload);
|
||||
if (!allowDuplicate && identity != null && identity === lastEventIdentityRef.current) return;
|
||||
if (!allowDuplicate && identity != null && identity === lastEventIdentityRef.current) {
|
||||
logReload("suppressed", { path, why: "duplicate event" });
|
||||
return;
|
||||
}
|
||||
lastEventIdentityRef.current = identity;
|
||||
const generation = ++generationRef.current;
|
||||
const result = await drainPendingChanges();
|
||||
|
||||
@@ -5,6 +5,7 @@ import {
|
||||
type DomEditCommitBaseParams,
|
||||
} from "../utils/studioFileHistory";
|
||||
import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
|
||||
import { studioWriteHeaders } from "../utils/studioFileVersion";
|
||||
|
||||
interface UseGroupCommitsParams extends DomEditCommitBaseParams {
|
||||
/** Resync the SDK session after a server-side write (the wrapper/unwrap changes
|
||||
@@ -75,7 +76,7 @@ async function commitStructuralMutation(
|
||||
`/api/projects/${pid}/file-mutations/${route}/${encodeURIComponent(targetPath)}`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
|
||||
body: JSON.stringify(body),
|
||||
},
|
||||
);
|
||||
|
||||
@@ -36,6 +36,7 @@ import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
|
||||
import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
|
||||
import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
|
||||
import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
|
||||
import { studioWriteHeaders } from "../utils/studioFileVersion";
|
||||
|
||||
type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
|
||||
stackingReorder?: TimelineStackingReorderIntent | null;
|
||||
@@ -412,7 +413,7 @@ export function useTimelineEditing({
|
||||
`/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
|
||||
body: JSON.stringify({ target: patchTarget }),
|
||||
},
|
||||
);
|
||||
|
||||
@@ -4,6 +4,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
|
||||
import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
|
||||
import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
|
||||
import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
|
||||
import { logReload } from "../../utils/reloadDebug";
|
||||
|
||||
export type { ClipManifestClip } from "../lib/playbackTypes";
|
||||
export { createStaticSeekPlaybackAdapter } from "../lib/playbackAdapter";
|
||||
@@ -445,6 +446,7 @@ export function useTimelinePlayer() {
|
||||
const refreshPlayer = useCallback(() => {
|
||||
const iframe = iframeRef.current;
|
||||
if (!iframe) return;
|
||||
logReload("refreshPlayer", { stack: new Error("refreshPlayer").stack });
|
||||
saveSeekPosition();
|
||||
// Hide the iframe across the full reload so the user never sees the reloading
|
||||
// document's RAW DOM (every clip stacked and visible) in the window between the
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
// Preview full-reload diagnostics — grep [hf-reload]. Off by default; opt in per
|
||||
// session with `localStorage.setItem("hf-reload-debug", "1")` (then reload).
|
||||
//
|
||||
// A full reload blanks the stage for ~100-300ms, so any reload the user did not
|
||||
// ask for reads as a flash. These lines answer the only question that matters
|
||||
// when one appears: who asked for it, and why the write that triggered it was
|
||||
// not recognised as Studio's own.
|
||||
let enabled: boolean | null = null;
|
||||
|
||||
function isEnabled(): boolean {
|
||||
if (enabled === null) {
|
||||
try {
|
||||
enabled = localStorage.getItem("hf-reload-debug") === "1";
|
||||
} catch {
|
||||
enabled = false;
|
||||
}
|
||||
}
|
||||
return enabled;
|
||||
}
|
||||
|
||||
export function logReload(stage: string, data: Record<string, unknown> = {}): void {
|
||||
if (!isEnabled()) return;
|
||||
console.log(
|
||||
`[hf-reload] ${JSON.stringify({ stage, t: Math.round(performance.now()), ...data })}`,
|
||||
);
|
||||
}
|
||||
@@ -51,3 +51,18 @@ export async function studioExpectedFileVersion(
|
||||
export function createStudioWriteToken(): string {
|
||||
return globalThis.crypto.randomUUID();
|
||||
}
|
||||
|
||||
/**
|
||||
* Headers that claim the write a mutation request is about to make as our own.
|
||||
*
|
||||
* The token is marked BEFORE the request goes out on purpose: the server writes
|
||||
* the file and the watcher broadcasts it while the request is still in flight, so
|
||||
* a token marked from the response can arrive after the echo it was meant to
|
||||
* match. An unmatched echo reads as an external change and costs a full preview
|
||||
* reload, which the user sees as a flash right after their own edit.
|
||||
*/
|
||||
export function studioWriteHeaders(): Record<string, string> {
|
||||
const token = createStudioWriteToken();
|
||||
markStudioWriteToken(token);
|
||||
return { "X-Hyperframes-Write-Token": token };
|
||||
}
|
||||
|
||||
@@ -2,6 +2,7 @@ import { createStudioSaveHttpError } from "./studioSaveDiagnostics";
|
||||
import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
|
||||
import type { RecordEditInput } from "./studioFileHistory";
|
||||
import { buildProjectApiPath } from "./projectRouting";
|
||||
import { studioWriteHeaders } from "./studioFileVersion";
|
||||
|
||||
interface TimelineCompositionInsertionResult {
|
||||
path: string;
|
||||
@@ -34,7 +35,7 @@ async function insertTimelineComposition(input: {
|
||||
),
|
||||
{
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
|
||||
body: JSON.stringify({
|
||||
sourcePath: input.sourcePath,
|
||||
start: input.start,
|
||||
|
||||
Reference in New Issue
Block a user