Skip to content

Commit d1482b0

Browse files
fix(skills): resolve the blueprint id from a qualified blueprint: field (#3337)
* fix(skills): resolve the blueprint id from a qualified `blueprint:` field visual-design.md documents `blueprint:` as the id plus a `(Reproduce)` / `(Adapt)` qualifier, and prints `dataviz-countup (Adapt)` as its worked example. The packet builder used that raw field as a filename, so a qualified blueprint looked for `<id> (Adapt).md`, found nothing, and inlined an empty string: `selectedFile()` returns "" for a missing path. Every packet shipped without the one document the frame was designed against, and the run still exited 0 with nothing on stderr. `compose (Adapt)` missed the `compose` check the same way. Parse the field into the id it names, once, so no caller resolves a raw field value against the blueprints directory. A blueprint that resolves to no file is now a named error rather than an empty section, matching how the builder already treats a missing `src` and an oversize packet. The existing tests only used bare ids, which is how the qualified form escaped; they now cover both, and the missing-file case. One owner: product-launch-video, faceless-explainer, pr-to-video and general-video all delegate to frame-packets-core.mjs. Co-Authored-By: anikam13 <[email protected]> * fix(skills): degrade, not fail, when the blueprints library is absent Self-review catch on the previous commit. hyperframes-animation installs on demand, so its blueprints/ directory can legitimately be missing — that is a skill that isn't installed yet, not a frame naming a bad id. Throwing there turned a silent degrade into a hard failure for a valid setup. Distinguish the two: an absent blueprints/ warns and inlines nothing, exactly as an absent rules/ already does in knownRuleIds; a present library that has no file for this id still throws, because that is a typo or an unstripped qualifier. Co-Authored-By: anikam13 <[email protected]> * fix(skills): point two dead blueprint references at real shapes CI surfaced these once an unresolvable blueprint stopped being silent. Both named ids that have never existed in hyperframes-animation/blueprints/: - faceless-explainer's frame template taught `messaging-multi-phase`, so an agent copying the template verbatim tagged a blueprint that resolves to nothing. dataviz-countup is what the same skill already uses in its own visual-design template and tests. - pr-to-video's diff-excerpt guardrail fixture used `number-lockup`. The test is about diff excerpting and the id was incidental; the frame's own `counting-dynamic-scale` rule makes dataviz-countup the natural real shape. A sweep of every `blueprint:` value across skills/ finds no others. Co-Authored-By: anikam13 <[email protected]> --------- Co-authored-by: anikam13 <[email protected]>
1 parent c66c9a4 commit d1482b0

5 files changed

Lines changed: 116 additions & 14 deletions

File tree

‎skills-manifest.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"files": 138
77
},
88
"faceless-explainer": {
9-
"hash": "7d587ff36c975d9a",
9+
"hash": "81423e16a3e2806d",
1010
"files": 24
1111
},
1212
"figma": {
@@ -34,7 +34,7 @@
3434
"files": 11
3535
},
3636
"hyperframes-core": {
37-
"hash": "f6516b74cb6e5d58",
37+
"hash": "74b9841f63c8f405",
3838
"files": 20
3939
},
4040
"hyperframes-creative": {
@@ -62,11 +62,11 @@
6262
"files": 132
6363
},
6464
"pr-to-video": {
65-
"hash": "14250b018114d26d",
65+
"hash": "bacdbbd868cd84a1",
6666
"files": 30
6767
},
6868
"product-launch-video": {
69-
"hash": "12c0895d4963aa90",
69+
"hash": "ff7c30295b67fc2e",
7070
"files": 29
7171
},
7272
"remotion-to-hyperframes": {

‎skills/faceless-explainer/references/story-design.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -233,7 +233,7 @@ Use the exact fields required by the core storyboard format. This is the narrati
233233
- type: feature_showcase
234234
- persuasion: Progressive disclosure
235235
- beat: comprehension
236-
- blueprint: messaging-multi-phase — candidate shape from the role→blueprint menu; omit when none fits
236+
- blueprint: dataviz-countup — candidate shape from the role→blueprint menu; omit when none fits
237237

238238
narrativeRole: What this frame does in the viewer's understanding.
239239
keyMessage: The one idea the viewer should remember.

‎skills/hyperframes-core/scripts/lib/frame-packets-core.mjs‎

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -83,14 +83,38 @@ export function citedRules(block, ruleIds) {
8383
return [...new Set([...explicit, ...mentioned])].filter((id) => ruleIds.includes(id));
8484
}
8585

86-
export function resourceSections(block, { animationDir, ruleIds }) {
86+
// visual-design.md tells the author to write the blueprint as `<id> (Reproduce)`
87+
// or `<id> (Adapt)` — the qualifier is direction for the frame worker, not part of
88+
// the filename. Parse the field into the id it names (or null for `compose`), so
89+
// no caller ever resolves a raw field value against the blueprints directory.
90+
export function blueprintId(block) {
91+
const raw = field(block, "blueprint");
92+
if (!raw) return null;
93+
const id = raw.replace(/\s*\([^)]*\)\s*$/, "").trim();
94+
return id && id.toLowerCase() !== "compose" ? id : null;
95+
}
96+
97+
export function resourceSections(block, { animationDir, ruleIds, frameId }) {
8798
let sections = "";
88-
const blueprint = field(block, "blueprint");
89-
if (blueprint && blueprint.toLowerCase() !== "compose") {
90-
sections += selectedFile(
91-
join(animationDir, "blueprints", `${blueprint}.md`),
92-
`Selected blueprint: ${blueprint}`,
93-
);
99+
const blueprint = blueprintId(block);
100+
if (blueprint) {
101+
const blueprintsDir = join(animationDir, "blueprints");
102+
const path = join(blueprintsDir, `${blueprint}.md`);
103+
// A blueprint that resolved to nothing used to inline an empty string, so the
104+
// packet shipped without the one document the frame was designed against and
105+
// the run still reported success. Name it instead — but only when the library
106+
// is actually there to be named against. The animation skill installs on
107+
// demand, so an absent blueprints/ is a missing install, not a bad id, and it
108+
// degrades with a warning exactly like an absent rules/ (see knownRuleIds).
109+
if (!existsSync(blueprintsDir)) {
110+
console.warn(
111+
`frame-packets: no blueprints dir at ${blueprintsDir} — packets will inline no blueprint`,
112+
);
113+
} else if (!existsSync(path)) {
114+
throw new Error(`${frameId ?? "frame"}: blueprint "${blueprint}" has no file at ${path}`);
115+
} else {
116+
sections += selectedFile(path, `Selected blueprint: ${blueprint}`);
117+
}
94118
}
95119
for (const rule of citedRules(block, ruleIds)) {
96120
sections += selectedFile(
@@ -135,7 +159,7 @@ export function buildFramePackets({
135159
const packets = frames.map((frame) => {
136160
const id = frameId(frame);
137161
if (validateFrame) validateFrame(frame, id);
138-
const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds })}${extraSections ? extraSections(frame.block) : ""}`;
162+
const packet = `# Frame packet: ${id}\n\n## Project inputs\n\n- Project: ${resolve(projectDir)}\n${designTruthLine(projectDir)}\n- RULES_DIR: ${join(animationDir, "rules")}\n\n## Assigned storyboard block\n\n${frame.block}\n${resourceSections(frame.block, { animationDir, ruleIds, frameId: id })}${extraSections ? extraSections(frame.block) : ""}`;
139163
const bytes = Buffer.byteLength(packet);
140164
if (bytes > maxPacketBytes) {
141165
throw new Error(`${id}: frame packet is ${bytes} bytes (limit ${maxPacketBytes})`);

‎skills/pr-to-video/scripts/workflow-guardrails.test.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ test("#1092 packets contain selected excerpts but never the full diff", () => {
8383
write(join(project, "frame.md"), "# compact frame tokens\n");
8484
write(
8585
join(project, "STORYBOARD.md"),
86-
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-diff\n- blueprint: compose\n- rules: text-reveal\n\n### Source excerpt\n\n\`\`\`diff\n-oldCall()\n+newCall({ attested: true })\n\`\`\`\n\n## Frame 2 — Impact\n\n- duration: 3s\n- src: compositions/frames/02-impact.html\n- blueprint: number-lockup\n- rules: counting-dynamic-scale\n`,
86+
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Diff\n\n- duration: 4s\n- src: compositions/frames/01-diff.html\n- focal: code-diff\n- blueprint: compose\n- rules: text-reveal\n\n### Source excerpt\n\n\`\`\`diff\n-oldCall()\n+newCall({ attested: true })\n\`\`\`\n\n## Frame 2 — Impact\n\n- duration: 3s\n- src: compositions/frames/02-impact.html\n- blueprint: dataviz-countup\n- rules: counting-dynamic-scale\n`,
8787
);
8888

8989
const result = buildFramePackets({

‎skills/product-launch-video/scripts/frame-packets.test.mjs‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,81 @@ test("packet validation is atomic and leaves no partial output on overflow", ()
6464
);
6565
assert.equal(existsSync(outDir), false);
6666
});
67+
68+
// ── the blueprint qualifier ──────────────────────────────────────────────────
69+
// Regression: visual-design.md documents `blueprint:` as the id plus a
70+
// `(Reproduce)` / `(Adapt)` qualifier, and prints `dataviz-countup (Adapt)` as
71+
// its worked example. The resolver used the raw field as the filename, so every
72+
// qualified blueprint looked for a file that cannot exist and inlined "" —
73+
// packets shipped without the document the frame was designed against, and the
74+
// run still reported success. The cases above only ever used bare ids.
75+
76+
test("a qualified blueprint resolves to the same body as the bare id", () => {
77+
const project = mkdtempSync(join(tmpdir(), "plv-blueprint-qualified-"));
78+
write(join(project, "frame.md"), "# tokens\n");
79+
write(
80+
join(project, "STORYBOARD.md"),
81+
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Adapted\n\n- duration: 3s\n- src: compositions/frames/01-adapted.html\n- blueprint: device-surface-showcase (Adapt)\n\n## Frame 2 — Reproduced\n\n- duration: 3s\n- src: compositions/frames/02-reproduced.html\n- blueprint: device-surface-showcase (Reproduce)\n\n## Frame 3 — Bare\n\n- duration: 3s\n- src: compositions/frames/03-bare.html\n- blueprint: device-surface-showcase\n`,
82+
);
83+
84+
const packets = buildFramePackets({ projectDir: project });
85+
const blueprintSections = packets.map((packet) => {
86+
const body = readFileSync(packet.path, "utf8");
87+
const start = body.indexOf("## Selected blueprint:");
88+
assert.notEqual(start, -1, `${packet.frameId} inlined no blueprint`);
89+
return body.slice(start);
90+
});
91+
92+
assert.match(blueprintSections[0], /## Selected blueprint: device-surface-showcase\n/);
93+
// The qualifier is direction for the worker, not a different document: all
94+
// three frames must inline byte-identical blueprint bodies.
95+
assert.equal(new Set(blueprintSections).size, 1);
96+
});
97+
98+
test("a qualified `compose` still selects no blueprint", () => {
99+
const project = mkdtempSync(join(tmpdir(), "plv-blueprint-compose-"));
100+
write(join(project, "frame.md"), "# tokens\n");
101+
write(
102+
join(project, "STORYBOARD.md"),
103+
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Freeform\n\n- duration: 3s\n- src: compositions/frames/01-freeform.html\n- blueprint: compose (Adapt)\n`,
104+
);
105+
106+
const [packet] = buildFramePackets({ projectDir: project });
107+
108+
assert.doesNotMatch(readFileSync(packet.path, "utf8"), /## Selected blueprint/);
109+
});
110+
111+
test("a blueprint with no file fails the run instead of shipping an empty section", () => {
112+
const project = mkdtempSync(join(tmpdir(), "plv-blueprint-missing-"));
113+
const outDir = join(project, ".hyperframes", "frame-packets");
114+
write(join(project, "frame.md"), "# tokens\n");
115+
write(
116+
join(project, "STORYBOARD.md"),
117+
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Typo\n\n- duration: 3s\n- src: compositions/frames/01-typo.html\n- blueprint: device-surface-showcses\n`,
118+
);
119+
120+
assert.throws(
121+
() => buildFramePackets({ projectDir: project, outDir }),
122+
/01-typo: blueprint "device-surface-showcses" has no file/,
123+
);
124+
assert.equal(existsSync(outDir), false);
125+
});
126+
127+
test("an uninstalled animation skill degrades with a warning, it does not fail the run", () => {
128+
// hyperframes-animation installs on demand, so an absent blueprints/ means the
129+
// library isn't there yet — not that the frame named a bad id. Matches how an
130+
// absent rules/ already behaves.
131+
const project = mkdtempSync(join(tmpdir(), "plv-blueprint-uninstalled-"));
132+
write(join(project, "frame.md"), "# tokens\n");
133+
write(
134+
join(project, "STORYBOARD.md"),
135+
`---\nformat: 1920x1080\n---\n\n## Frame 1 — Hook\n\n- duration: 3s\n- src: compositions/frames/01-hook.html\n- blueprint: dataviz-countup (Adapt)\n`,
136+
);
137+
138+
const [packet] = buildFramePackets({
139+
projectDir: project,
140+
animationDir: join(project, "absent-animation-skill"),
141+
});
142+
143+
assert.doesNotMatch(readFileSync(packet.path, "utf8"), /## Selected blueprint/);
144+
});

0 commit comments

Comments
 (0)