Skip to content

Commit 045b3a4

Browse files
feat(cli): report which catalog items a render actually used (#3470)
`registry_item_added` fires when a catalog block is installed and `render_complete` fires when a video is produced, but nothing joined them, so "did this video use the catalog?" had no answer. `hyperframes add` now records each installed item in `hyperframes.json` (installed files are plain composition HTML with no provenance marker, so this manifest is the only record that a file came from the registry), and `render_complete` reports both the items the project installed and the blocks the rendered composition actually reaches. An item installed and then never mounted was tried and dropped, which no add-time event can express. The scan answering "which sub-compositions does this file mount" now has one owner, `collectSubCompositionSrcs` in `@hyperframes/parsers`, shared with lint's `lintMissingOrEmptySubComposition`. It holds two invariants that were previously restated per call site and got re-derived wrongly: it is a text scan rather than a DOM query, because `<template>` content is inert and every sub-composition except the render entry is wrapped in one; and references resolve root-relative at every nesting level, matching `parseSubCompositions`. It walks tag by tag rather than running open-ended spans across the whole file, so a malformed composition cannot stall the render plan. Also: `registryItems` is declared in the config schema, which closes with `additionalProperties: false`, with an ajv-backed test pinning every key the CLI writes; counts are never truncated by the name cap, and the reported used blocks stay a subset of the reported installed ones, with `registry_items_truncated` marking a windowed list; and an unreadable manifest reports itself rather than posing as a project that never used the catalog.
1 parent b2fc18b commit 045b3a4

18 files changed

Lines changed: 1127 additions & 38 deletions

‎bun.lock‎

Lines changed: 14 additions & 13 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/schema/hyperframes.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,29 @@
5656
"type": "string",
5757
"pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
5858
"description": "Owning authoring-workflow skill slug (e.g. product-launch-video). Set by `hyperframes init --skill` or seeded from the first `hyperframes render --skill`; every render of this project is then attributed to it on anonymous telemetry, without re-passing the flag."
59+
},
60+
"registryItems": {
61+
"type": "array",
62+
"description": "Catalog items installed by `hyperframes add`, in install order. Installed files are plain composition HTML with no provenance marker, so this is the only record that a file came from the registry; a render reads it back to report which catalog items the finished video actually used. Append-only, deduped by name.",
63+
"items": {
64+
"type": "object",
65+
"required": ["name", "type", "target"],
66+
"additionalProperties": false,
67+
"properties": {
68+
"name": {
69+
"type": "string",
70+
"description": "Registry item name, e.g. data-chart."
71+
},
72+
"type": {
73+
"type": "string",
74+
"description": "Registry item type, e.g. hyperframes:block."
75+
},
76+
"target": {
77+
"type": "string",
78+
"description": "Primary installed file, relative to the project root."
79+
}
80+
}
81+
}
5982
}
6083
}
6184
}

‎packages/cli/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
"@types/fontkit": "^2.0.9",
6262
"@types/mime-types": "^3.0.1",
6363
"@types/node": "^25.0.10",
64+
"ajv": "^8.20.0",
6465
"linkedom": "^0.18.12",
6566
"picocolors": "^1.1.1",
6667
"tsup": "^8.0.0",

‎packages/cli/src/commands/add.ts‎

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ import {
2525
DEFAULT_PROJECT_CONFIG,
2626
loadProjectConfig,
2727
projectConfigPath,
28+
recordProjectRegistryItems,
2829
writeProjectConfig,
2930
} from "../utils/projectConfig.js";
3031
import { copyToClipboard } from "../utils/clipboard.js";
@@ -78,6 +79,23 @@ function variableValuesAttribute(values: Record<string, unknown> | null): string
7879
return ` data-variable-values='${json}'`;
7980
}
8081

82+
/**
83+
* The file a consumer points at for this item: the snippet if it has one, else
84+
* its composition, else whatever landed first. Project-relative, empty when the
85+
* item installed no files.
86+
*
87+
* One owner for this choice. The paste snippet's `data-composition-src` and the
88+
* recorded manifest target must name the same file, or a render would look for
89+
* a block at a path the composition never mounts and report it as dropped.
90+
*/
91+
function primaryInstalledTarget(item: RegistryItem): string {
92+
const primary =
93+
item.files.find((f) => f.type === "hyperframes:snippet") ??
94+
item.files.find((f) => f.type === "hyperframes:composition") ??
95+
item.files[0];
96+
return primary?.target ?? "";
97+
}
98+
8199
export function buildSnippet(
82100
item: RegistryItem,
83101
relativeTarget: string,
@@ -321,13 +339,22 @@ export async function runAdd(opts: RunAddArgs): Promise<RunAddResult> {
321339
});
322340
}
323341

342+
// Persist what came from the registry. Installed files are plain composition
343+
// HTML with no provenance marker, so without this a later render cannot tell
344+
// a catalog block from one the user wrote — and "did the catalog item survive
345+
// into the video?" stays unanswerable.
346+
recordProjectRegistryItems(
347+
projectDir,
348+
installPlan.map((planItem) => ({
349+
name: planItem.name,
350+
type: planItem.type,
351+
target: primaryInstalledTarget(planItem),
352+
})),
353+
);
354+
324355
// 6. Build include snippet + clipboard copy for the requested item.
325356
const itemForInstall = installPlan[installPlan.length - 1]!;
326-
const primaryFile =
327-
itemForInstall.files.find((f) => f.type === "hyperframes:snippet") ??
328-
itemForInstall.files.find((f) => f.type === "hyperframes:composition") ??
329-
itemForInstall.files[0];
330-
const snippetTargetRel = primaryFile?.target ?? "";
357+
const snippetTargetRel = primaryInstalledTarget(itemForInstall);
331358
const snippet = buildSnippet(item, snippetTargetRel, variableValues);
332359
const clipboardCopied = !opts.skipClipboard && snippet ? copyToClipboard(snippet) : false;
333360

‎packages/cli/src/commands/render.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import type { Example } from "./_examples.js";
44
import { mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
55
import { createRenderPlan, resolveBrowserGpuForCli, type RenderFormat } from "./render/plan.js";
66
import { seedProjectAuthoringSkill } from "../utils/projectConfig.js";
7+
import type { CatalogUsage } from "../utils/catalogUsage.js";
78
import { presentRenderPlan } from "./render/present.js";
89
import { executeRenderPlan, renderLintContinuationHint, runRenderLint } from "./render/execute.js";
910
// Test-only seams retained at the command boundary for render behavior tests.
@@ -377,6 +378,12 @@ export interface RenderOptions {
377378
quality: "draft" | "standard" | "high";
378379
/** Authoring workflow skill that drove this render (telemetry attribution). */
379380
authoringSkill?: string;
381+
/**
382+
* Catalog items installed in this project and those the rendered composition
383+
* reaches. Resolved once in the render plan; absent on programmatic callers
384+
* that build options by hand, which simply omit the catalog properties.
385+
*/
386+
catalogUsage?: CatalogUsage;
380387
format: RenderFormat;
381388
gifLoop?: number;
382389
workers?: number;
@@ -763,6 +770,7 @@ async function renderDocker(
763770
docker: true,
764771
gpu: options.gpu,
765772
authoringSkill: options.authoringSkill,
773+
catalogUsage: options.catalogUsage,
766774
...getMemorySnapshot(),
767775
}),
768776
);
@@ -1498,6 +1506,7 @@ function trackRenderMetrics(
14981506
docker,
14991507
gpu: options.gpu,
15001508
authoringSkill: options.authoringSkill,
1509+
catalogUsage: options.catalogUsage,
15011510
staticDedupEnabled: perf?.staticDedup?.enabled,
15021511
staticDedupArmed: perf?.staticDedup?.armed,
15031512
staticDedupSkipReason: perf?.staticDedup?.skipReason,

‎packages/cli/src/commands/render/execute.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ export async function executeRenderPlan(
101101
fps: plan.fps,
102102
quality: plan.quality,
103103
authoringSkill: plan.authoringSkill,
104+
catalogUsage: plan.catalogUsage,
104105
format: plan.format,
105106
gifLoop: plan.gifLoop,
106107
workers: plan.workers,
@@ -254,6 +255,7 @@ async function executeBatchRender(
254255
fps: plan.fps,
255256
quality: plan.quality,
256257
authoringSkill: plan.authoringSkill,
258+
catalogUsage: plan.catalogUsage,
257259
format: plan.format,
258260
workers: plan.workers,
259261
gpu: plan.useGpu,

‎packages/cli/src/commands/render/plan.test.ts‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
2-
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
2+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { join, resolve } from "node:path";
55
import { CliUsageError } from "../../utils/commandResult.js";
@@ -37,6 +37,42 @@ describe("createRenderPlan", () => {
3737
expect(Object.isFrozen(plan.environment)).toBe(true);
3838
});
3939

40+
// The catalog join reaches the render event through the plan, so a plan that
41+
// silently drops it would leave every render reporting no catalog items.
42+
it("resolves catalog usage from the project manifest and the render entry", () => {
43+
writeFileSync(
44+
join(projectDir, "index.html"),
45+
'<main data-composition-id="main" data-width="1920" data-height="1080" data-fps="24">' +
46+
'<div data-composition-src="compositions/kept.html" data-duration="2"></div></main>',
47+
);
48+
mkdirSync(join(projectDir, "compositions"), { recursive: true });
49+
// `<template>`-wrapped, as sub-compositions are actually authored: template
50+
// content is inert, so a DOM scan of these files would find nothing.
51+
for (const name of ["kept", "dropped"]) {
52+
writeFileSync(
53+
join(projectDir, "compositions", `${name}.html`),
54+
`<template id="${name}-template"><div data-composition-id="${name}" data-width="1920" data-height="1080"></div></template>`,
55+
);
56+
}
57+
writeFileSync(
58+
join(projectDir, "hyperframes.json"),
59+
JSON.stringify({
60+
registry: "https://example.test",
61+
registryItems: [
62+
{ name: "kept", type: "hyperframes:block", target: "compositions/kept.html" },
63+
{ name: "dropped", type: "hyperframes:block", target: "compositions/dropped.html" },
64+
],
65+
}),
66+
);
67+
68+
const plan = createRenderPlan({ dir: projectDir, output: "result.mp4" });
69+
expect(plan.catalogUsage).toEqual({
70+
installed: ["dropped", "kept"],
71+
usedBlocks: ["kept"],
72+
manifestUnreadable: false,
73+
});
74+
});
75+
4076
it("preserves an explicit strict-readiness opt-in", () => {
4177
const plan = createRenderPlan({ dir: projectDir, "best-effort": false });
4278
expect(plan.bestEffort).toBe(false);

‎packages/cli/src/commands/render/plan.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import {
2929
} from "../../utils/renderArgs.js";
3030
import { normalizeSkillSlug } from "../../telemetry/skill.js";
3131
import { loadProjectConfig } from "../../utils/projectConfig.js";
32+
import { type CatalogUsage, summarizeCatalogUsage } from "../../utils/catalogUsage.js";
3233

3334
const VALID_QUALITY = new Set(["draft", "standard", "high"]);
3435
const RENDER_FORMATS = ["mp4", "webm", "mov", "png-sequence", "gif"] as const;
@@ -99,6 +100,8 @@ export interface RenderPlan {
99100
quality: RenderQuality;
100101
authoringSkill?: string;
101102
invalidAuthoringSkill?: string;
103+
/** Catalog items installed in this project, and those the entry reaches. */
104+
catalogUsage: CatalogUsage;
102105
format: RenderFormat;
103106
gifLoop?: number;
104107
gifFpsCapped: boolean;
@@ -204,6 +207,10 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
204207
? args.skill
205208
: undefined;
206209

210+
// Resolved here, once, from the same entry the render will use: batch rows
211+
// vary only their variables, so every row shares this composition tree.
212+
const catalogUsage = summarizeCatalogUsage(project.dir, renderTarget);
213+
207214
const formatRaw = args.format ?? "mp4";
208215
const format = parseRenderFormat(formatRaw);
209216
if (!format) {
@@ -412,6 +419,7 @@ export function createRenderPlan(args: RenderCommandArgs, now = new Date()): Ren
412419
quality,
413420
authoringSkill,
414421
invalidAuthoringSkill,
422+
catalogUsage,
415423
format,
416424
gifLoop,
417425
gifFpsCapped,
@@ -461,7 +469,6 @@ export function renderOutputDirectory(plan: RenderPlan): string {
461469

462470
/** Resolve browser GPU mode from Docker, CLI, env, then the auto default. */
463471
// Re-exported by render.ts to preserve its tested public seam.
464-
// fallow-ignore-next-line unused-export
465472
export function resolveBrowserGpuForCli(
466473
useDocker: boolean,
467474
browserGpuArg: boolean | undefined,

0 commit comments

Comments
 (0)