Skip to content

Commit 34613df

Browse files
fix(skills): transient-init retry for standalone animation-map and contrast-report
The standalone helpers called initializeSession exactly once, so a valid modular project — whose sub-composition timelines register asynchronously — could hit the readiness deadline and die with the transient "zero duration / Runtime ready: false" diagnostic the render pipeline retries (probeStage). Add initializeSessionWithRetry to the shared package-loader (both byte-identical copies): close the crashed session and retry once with a fresh browser, gated by the engine's canonical isTransientBrowserError — now re-exported from @hyperframes/producer, with a frozen fallback pattern list for older published packages. The "Runtime ready: true" fast-fail (a genuine authoring bug) still fails without a retry. Co-Authored-By: Claude Opus 4.8 <[email protected]>
1 parent fcbfb95 commit 34613df

7 files changed

Lines changed: 318 additions & 20 deletions

File tree

‎packages/producer/src/index.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,10 @@ export {
5050
captureFrameToBuffer,
5151
getCompositionDuration,
5252
getCapturePerfSummary,
53+
// Transient-vs-genuine init failure classifier — re-exported so standalone
54+
// skill helpers (animation-map, contrast-report) can reuse the render
55+
// pipeline's canonical retry gating instead of re-deriving it.
56+
isTransientBrowserError,
5357
prepareCaptureSessionForReuse,
5458
type CaptureOptions,
5559
type CaptureSession,

‎packages/producer/src/services/frameCapture.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ export {
1010
captureFrameToBuffer,
1111
getCompositionDuration,
1212
getCapturePerfSummary,
13+
isTransientBrowserError,
1314
prepareCaptureSessionForReuse,
1415
type CaptureOptions,
1516
type CaptureResult,

‎skills/hyperframes-animation/scripts/animation-map.mjs‎

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import {
2121
bundleCompositionForCapture,
2222
hyperframesPackageSpec,
2323
importPackagesOrBootstrap,
24+
initializeSessionWithRetry,
2425
} from "./package-loader.mjs";
2526

2627
const packages = await importPackagesOrBootstrap(
@@ -32,13 +33,8 @@ const packages = await importPackagesOrBootstrap(
3233
],
3334
},
3435
);
35-
const {
36-
createFileServer,
37-
createCaptureSession,
38-
initializeSession,
39-
closeCaptureSession,
40-
getCompositionDuration,
41-
} = packages["@hyperframes/producer"];
36+
const { createFileServer, createCaptureSession, closeCaptureSession, getCompositionDuration } =
37+
packages["@hyperframes/producer"];
4238
const { parseFps } = packages["@hyperframes/core"];
4339

4440
// ─── CLI ─────────────────────────────────────────────────────────────────────
@@ -71,13 +67,22 @@ try {
7167
compiledDir: bundle.compiledDir,
7268
port: 0,
7369
});
74-
session = await createCaptureSession(
75-
server.url,
76-
OUT_DIR,
77-
{ width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
78-
null,
70+
// Canonical transient-init retry/cleanup (mirrors the render pipeline's
71+
// probeStage): a valid modular project's sub-composition timelines register
72+
// asynchronously, so the first attempt can time out as transient
73+
// "zero duration / Runtime ready: false" — retry once with a fresh browser
74+
// instead of false-failing the project.
75+
session = await initializeSessionWithRetry(
76+
packages["@hyperframes/producer"],
77+
() =>
78+
createCaptureSession(
79+
server.url,
80+
OUT_DIR,
81+
{ width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
82+
null,
83+
),
84+
{ log: (message) => console.error(`animation-map: ${message}`) },
7985
);
80-
await initializeSession(session);
8186

8287
const duration = await getCompositionDuration(session);
8388
const tweens = await enumerateTweens(session);

‎skills/hyperframes-animation/scripts/animation-map.test.mjs‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,3 +116,154 @@ describe("HyperFrames skill helpers", () => {
116116
}
117117
});
118118
});
119+
120+
// ── Transient-init retry (the zero-duration false-fail fix) ─────────────────
121+
// A valid modular project's sub-composition timelines register asynchronously;
122+
// the first initializeSession can time out with the transient "zero duration /
123+
// Runtime ready: false" diagnostic. The render pipeline closes the crashed
124+
// session and retries once with a fresh browser (probeStage) — the standalone
125+
// helpers must do the same instead of reporting the project as zero-duration.
126+
127+
/** Write a fake node_modules with the given producer index.mjs source. */
128+
function writeFakeEnv(root, producerIndexSource) {
129+
const packageDir = join(root, "node_modules", "@hyperframes", "producer");
130+
const corePackageDir = join(root, "node_modules", "@hyperframes", "core");
131+
const sharpPackageDir = join(root, "node_modules", "sharp");
132+
const compositionDir = join(root, "composition");
133+
mkdirSync(packageDir, { recursive: true });
134+
mkdirSync(corePackageDir, { recursive: true });
135+
mkdirSync(sharpPackageDir, { recursive: true });
136+
mkdirSync(compositionDir, { recursive: true });
137+
writeFileSync(
138+
join(packageDir, "package.json"),
139+
JSON.stringify({ name: "@hyperframes/producer", type: "module", exports: "./index.mjs" }),
140+
);
141+
writeFileSync(join(packageDir, "index.mjs"), producerIndexSource);
142+
writeFileSync(
143+
join(corePackageDir, "package.json"),
144+
JSON.stringify({
145+
name: "@hyperframes/core",
146+
type: "module",
147+
exports: { ".": "./index.mjs", "./compiler": "./compiler.mjs" },
148+
}),
149+
);
150+
writeFileSync(
151+
join(corePackageDir, "index.mjs"),
152+
"export function parseFps(input) { return { ok: true, value: { num: Number(input), den: 1 } }; }",
153+
);
154+
writeFileSync(
155+
join(corePackageDir, "compiler.mjs"),
156+
'export async function bundleToSingleHtml() { return "<!doctype html><main>x</main>"; }',
157+
);
158+
writeFileSync(
159+
join(sharpPackageDir, "package.json"),
160+
JSON.stringify({ name: "sharp", type: "module", exports: "./index.mjs" }),
161+
);
162+
writeFileSync(join(sharpPackageDir, "index.mjs"), "export default function sharp() {}\n");
163+
return compositionDir;
164+
}
165+
166+
function runHelper(helper, root, compositionDir) {
167+
const result = spawnSync(process.execPath, [helper, compositionDir, "--out", join(root, "out")], {
168+
encoding: "utf8",
169+
env: { ...process.env, HYPERFRAMES_SKILL_NODE_MODULES: join(root, "node_modules") },
170+
});
171+
return `${result.stdout}\n${result.stderr}`;
172+
}
173+
174+
const FAKE_PRODUCER_COMMON = [
175+
'export async function createFileServer() { return { url: "http://test", close() {} }; }',
176+
'export async function createCaptureSession() { console.error("SESSION_CREATED"); return {}; }',
177+
'export async function closeCaptureSession() { console.error("SESSION_CLOSED"); }',
178+
"export async function getCompositionDuration() { return 0; }",
179+
].join("\n");
180+
181+
describe("transient-init retry", () => {
182+
for (const helper of HELPERS) {
183+
it(`${helper.split("/").at(-1)} retries a transient zero-duration init once with a fresh session`, () => {
184+
const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-retry-test-"));
185+
try {
186+
const compositionDir = writeFakeEnv(
187+
root,
188+
[
189+
FAKE_PRODUCER_COMMON,
190+
"let initCalls = 0;",
191+
"export async function initializeSession() {",
192+
" initCalls++;",
193+
" if (initCalls === 1) {",
194+
// The transient shape: readiness deadline hit before async
195+
// sub-composition timelines landed (Runtime ready: false).
196+
' throw new Error("Composition has zero duration after initialization.\\nRuntime ready: false");',
197+
" }",
198+
' throw new Error("INIT_ATTEMPT_2_REACHED");',
199+
"}",
200+
].join("\n"),
201+
);
202+
203+
const output = runHelper(helper, root, compositionDir);
204+
205+
// Retried: fresh session created for attempt 2, crashed one closed.
206+
assert.match(output, /retrying with a fresh browser session/);
207+
assert.equal((output.match(/SESSION_CREATED/g) ?? []).length, 2);
208+
assert.equal((output.match(/SESSION_CLOSED/g) ?? []).length, 2);
209+
// ...and the retry genuinely re-ran init (bounded: no third attempt).
210+
assert.match(output, /INIT_ATTEMPT_2_REACHED/);
211+
} finally {
212+
rmSync(root, { recursive: true, force: true });
213+
}
214+
});
215+
216+
it(`${helper.split("/").at(-1)} does NOT retry a genuine authoring failure (Runtime ready: true)`, () => {
217+
const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-retry-test-"));
218+
try {
219+
const compositionDir = writeFakeEnv(
220+
root,
221+
[
222+
FAKE_PRODUCER_COMMON,
223+
"export async function initializeSession() {",
224+
// The fast-fail shape: runtime IS ready, there is genuinely no
225+
// timeline/duration — an authoring bug retries can't fix.
226+
' throw new Error("Composition has zero duration after initialization.\\nRuntime ready: true");',
227+
"}",
228+
].join("\n"),
229+
);
230+
231+
const output = runHelper(helper, root, compositionDir);
232+
233+
assert.doesNotMatch(output, /retrying with a fresh browser session/);
234+
assert.equal((output.match(/SESSION_CREATED/g) ?? []).length, 1);
235+
assert.match(output, /Composition has zero duration/);
236+
} finally {
237+
rmSync(root, { recursive: true, force: true });
238+
}
239+
});
240+
}
241+
242+
it("prefers the producer's own isTransientBrowserError classifier when exported", () => {
243+
const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-retry-test-"));
244+
try {
245+
const compositionDir = writeFakeEnv(
246+
root,
247+
[
248+
FAKE_PRODUCER_COMMON,
249+
// A message the frozen fallback patterns would NOT match — only the
250+
// producer-provided classifier can mark it transient.
251+
"export function isTransientBrowserError(err) { return String(err && err.message).includes('CUSTOM_TRANSIENT'); }",
252+
"let initCalls = 0;",
253+
"export async function initializeSession() {",
254+
" initCalls++;",
255+
' if (initCalls === 1) throw new Error("CUSTOM_TRANSIENT flake");',
256+
' throw new Error("INIT_ATTEMPT_2_REACHED");',
257+
"}",
258+
].join("\n"),
259+
);
260+
261+
const output = runHelper(HELPERS[0], root, compositionDir);
262+
263+
assert.match(output, /retrying with a fresh browser session/);
264+
assert.match(output, /INIT_ATTEMPT_2_REACHED/);
265+
} finally {
266+
rmSync(root, { recursive: true, force: true });
267+
}
268+
});
269+
});

‎skills/hyperframes-animation/scripts/package-loader.mjs‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,71 @@ export async function bundleCompositionForCapture(compiler, projectDir) {
7373
}
7474
}
7575

76+
// ── Transient-init retry ─────────────────────────────────────────────────────
77+
// Frozen snapshot of the engine's TRANSIENT_BROWSER_ERROR_PATTERNS (see
78+
// packages/engine frameCapture.ts), used only when the imported
79+
// @hyperframes/producer predates the isTransientBrowserError re-export. The
80+
// last pattern is the load-bearing one for modular projects: sub-composition
81+
// timelines register asynchronously, so a first init attempt can time out as
82+
// "zero duration / Runtime ready: false" on a valid project.
83+
const FALLBACK_TRANSIENT_PATTERNS = [
84+
/Navigating frame was detached/i,
85+
/Target closed/i,
86+
/Session closed/i,
87+
/browser has disconnected/i,
88+
/Page crashed/i,
89+
/Execution context was destroyed/i,
90+
/Cannot find context with specified id/i,
91+
/Failed to launch the browser process/i,
92+
/Navigation timeout of \d+ ms exceeded/i,
93+
/ECONNREFUSED/i,
94+
/net::ERR_NETWORK_CHANGED/i,
95+
/Composition has zero duration[\s\S]*Runtime ready: false/,
96+
];
97+
98+
/**
99+
* Create + initialize a capture session with the canonical transient-init
100+
* retry/cleanup the render pipeline uses (see probeStage in
101+
* @hyperframes/producer): on a transient failure, close the crashed session
102+
* and retry ONCE with a fresh browser. Without this, a standalone helper
103+
* false-fails valid modular projects whose sub-composition timelines land a
104+
* beat after the first readiness deadline ("zero duration" with
105+
* "Runtime ready: false").
106+
*
107+
* `producer` is the imported @hyperframes/producer namespace;
108+
* `createSession` is a factory returning a fresh (uninitialized) session.
109+
* Non-transient init failures (e.g. the "Runtime ready: true" zero-duration
110+
* fast-fail — a genuine authoring bug) still throw on the first attempt.
111+
*/
112+
export async function initializeSessionWithRetry(producer, createSession, options = {}) {
113+
const maxAttempts = options.maxAttempts ?? 2;
114+
const log = options.log ?? ((message) => console.error(message));
115+
const isTransient =
116+
typeof producer.isTransientBrowserError === "function"
117+
? producer.isTransientBrowserError
118+
: (err) => {
119+
const message = err instanceof Error ? err.message : String(err);
120+
return FALLBACK_TRANSIENT_PATTERNS.some((pattern) => pattern.test(message));
121+
};
122+
123+
for (let attempt = 1; ; attempt++) {
124+
const session = await createSession();
125+
try {
126+
await producer.initializeSession(session);
127+
return session;
128+
} catch (error) {
129+
await producer.closeCaptureSession(session).catch(() => {});
130+
if (attempt >= maxAttempts || !isTransient(error)) throw error;
131+
log(
132+
`transient browser-init failure (attempt ${attempt}/${maxAttempts}): ${
133+
error instanceof Error ? error.message : String(error)
134+
}`,
135+
);
136+
log("retrying with a fresh browser session...");
137+
}
138+
}
139+
}
140+
76141
export function hyperframesPackageSpec(packageName) {
77142
const override = process.env[VERSION_OVERRIDE_ENV]?.trim();
78143
if (override) return `${packageName}@${override}`;

‎skills/hyperframes-creative/scripts/contrast-report.mjs‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ import {
4949
bundleCompositionForCapture,
5050
hyperframesPackageSpec,
5151
importPackagesOrBootstrap,
52+
initializeSessionWithRetry,
5253
} from "./package-loader.mjs";
5354

5455
// Bundle first so mounted sub-compositions are inlined before the producer's
@@ -68,7 +69,6 @@ const { parseFps } = packages["@hyperframes/core"];
6869
const {
6970
createFileServer,
7071
createCaptureSession,
71-
initializeSession,
7272
closeCaptureSession,
7373
captureFrameToBuffer,
7474
getCompositionDuration,
@@ -101,13 +101,20 @@ try {
101101
compiledDir: bundle.compiledDir,
102102
port: 0,
103103
});
104-
session = await createCaptureSession(
105-
server.url,
106-
OUT_DIR,
107-
{ width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
108-
null,
104+
// Canonical transient-init retry/cleanup (mirrors the render pipeline's
105+
// probeStage) — same reasoning as animation-map.mjs: don't false-fail a
106+
// valid modular project whose sub-composition timelines land a beat late.
107+
session = await initializeSessionWithRetry(
108+
packages["@hyperframes/producer"],
109+
() =>
110+
createCaptureSession(
111+
server.url,
112+
OUT_DIR,
113+
{ width: WIDTH, height: HEIGHT, fps: FPS, format: "png" },
114+
null,
115+
),
116+
{ log: (message) => console.error(`contrast-report: ${message}`) },
109117
);
110-
await initializeSession(session);
111118

112119
const duration = await getCompositionDuration(session);
113120
const times = Array.from(

0 commit comments

Comments
 (0)