| 1 | # @html-video/content-graph |
| 2 | |
| 3 | Structured intermediate representation produced by the agent's first round and consumed by the second round to render HTML frame sequences. |
| 4 | |
| 5 | See `research/2026-05-28-understand-anything-takeaways.md` (#1 content-graph, #4 graph-then-sort) for the design rationale, and the upcoming RFC-06 draft for the full spec. |
| 6 | |
| 7 | ## Schema |
| 8 | |
| 9 | ```ts |
| 10 | interface ContentGraph { |
| 11 | schemaVersion: 1; |
| 12 | intent: 'single-frame' | 'explainer' | 'data-viz' | 'promo' | 'comparison' | 'other'; |
| 13 | synopsis?: string; |
| 14 | nodes: Array<EntityNode | DataNode | TextNode>; |
| 15 | edges: Array<{ from: string; to: string; kind: 'sequence' | 'contrast' | 'dependency'; reason?: string }>; |
| 16 | } |
| 17 | ``` |
| 18 | |
| 19 | - **dependency edges** are hard constraints (topo sort). |
| 20 | - **sequence edges** are soft preferences (tie-break order between independent nodes). |
| 21 | - **contrast edges** carry semantics for the frame composer (does not affect order). |
| 22 | |
| 23 | ## API |
| 24 | |
| 25 | ```ts |
| 26 | import { validate, topoSort, totalDurationSec } from '@html-video/content-graph'; |
| 27 | |
| 28 | const result = validate(graph); |
| 29 | if (!result.ok) throw new Error(result.errors[0].message); |
| 30 | |
| 31 | const playOrder = topoSort(graph); // string[] of node ids |
| 32 | const totalSec = totalDurationSec(graph); |
| 33 | ``` |
| 34 |