Setting the file. One moment.
Frame Packets Core · Faceless Explainer · heygen-com/hyperframes · Skills Docs
Back to the top of the page This file
Number 15.18
Position 18 of 26
Type JavaScript
Size 7 KB
Lines 194 scripts/lib/ frame-packets-core.mjs
JavaScript · 194 lines · 7 KB
14 import { pathToFileURL } from "node:url" ;
15
16 export function field ( block , name ) {
17 const match = block. match ( new RegExp ( `^- \\ s+${ name }: \\ s*(.+)$` , "im" ));
18 return match?.[ 1 ]?. trim () ?? null ;
19 }
20
21 export function splitFrames ( storyboard ) {
22 const matches = [ ... storyboard. matchAll ( / ^ ## Frame \s + ( [ ^ \n] + ) $ / gm )];
23 return matches. map (( match , index ) => {
24 const start = match.index;
25 const end = matches[index + 1 ]?.index ?? storyboard. length ;
26 return {
27 heading: match[ 1 ]. trim (),
28 block: storyboard. slice (start, end). trim (),
29 };
30 });
31 }
32
33 export function frameId ( frame ) {
34 const src = field (frame.block, "src" );
35 if ( ! src) throw new Error ( `${ frame . heading }: missing src` );
36 return basename (src). replace ( / \. html ?$ / i , "" );
37 }
38
39 export function selectedFile ( path , heading ) {
40 if ( ! path || ! existsSync (path)) return "" ;
41 return ` \n ## ${ heading } \n\n ${ readFileSync ( path , "utf8" ). trim () } \n ` ;
42 }
43
44 function escapeRegExp ( id ) {
45 return id. replace ( / [.*+?^${}()|[ \]\\ ] / g , " \\ $&" );
46 }
47
48 export function knownRuleIds ( animationDir ) {
49 const rulesDir = join (animationDir, "rules" );
50 if ( ! existsSync (rulesDir)) {
51 console. warn (
52 `frame-packets: no rules dir at ${ rulesDir } — packets will inline no motion recipes` ,
53 );
54 return [];
55 }
56 return readdirSync (rulesDir)
57 . filter (( name ) => name. endsWith ( ".md" ))
58 . map (( name ) => name. replace ( / \. md $ / , "" ));
59 }
60
61 export function citedRules ( block , ruleIds ) {
62 const explicit = ( field (block, "rules" ) ?? "" )
63 . split ( / [,\s] + / )
64 . map (( rule ) => rule. trim ())
65 . filter (Boolean);
66 const mentioned = ruleIds. filter (( id ) =>
67 new RegExp ( `(?<![ \\ w-])${ escapeRegExp ( id ) }(?![ \\ w-])` , "i" ). test (block),
68 );
69 return [ ...new Set ([ ... explicit, ... mentioned])]. filter (( id ) => ruleIds. includes (id));
70 }
71
72 // visual-design.md tells the author to write the blueprint as `<id> (Reproduce)`
73 // or `<id> (Adapt)` — the qualifier is direction for the frame worker, not part of
74 // the filename. Parse the field into the id it names (or null for `compose`), so
75 // no caller ever resolves a raw field value against the blueprints directory.
76 export function blueprintId ( block ) {
77 const raw = field (block, "blueprint" );
78 if ( ! raw) return null ;
79 const id = raw. replace ( / \s * \( [ ^ )] * \) \s *$ / , "" ). trim ();
80 return id && id. toLowerCase () !== "compose" ? id : null ;
81 }
82
83 export function resourceSections ( block , { animationDir , ruleIds , frameId }) {
84 let sections = "" ;
85 const blueprint = blueprintId (block);
86 if (blueprint) {
87 const blueprintsDir = join (animationDir, "blueprints" );
88 const path = join (blueprintsDir, `${ blueprint }.md` );
89 // An installed library must contain the named blueprint.
90 // An absent on-demand library warns, like missing motion rules.
91 if ( ! existsSync (blueprintsDir)) {
92 console. warn (
93 `frame-packets: no blueprints dir at ${ blueprintsDir } — packets will inline no blueprint` ,
94 );
95 } else if ( ! existsSync (path)) {
96 throw new Error ( `${ frameId ?? "frame"}: blueprint "${ blueprint }" has no file at ${ path }` );
97 } else {
98 sections += selectedFile (path, `Selected blueprint: ${ blueprint }` );
99 }
100 }
101 for ( const rule of citedRules (block, ruleIds)) {
102 sections += selectedFile (
103 join (animationDir, "rules" , `${ rule }.md` ),
104 `Selected motion rule: ${ rule }` ,
105 );
106 }
107 return sections;
108 }
109
110 export function buildRolePayload ({ corePath , deltaPath , outDir }) {
111 const core = readFileSync (corePath, "utf8" ). trim ();
112 const delta = readFileSync (deltaPath, "utf8" ). trim ();
113 const role = `${ core } \n\n --- \n\n ${ delta } \n ` ;
114 mkdirSync (outDir, { recursive: true });
115 const path = join (outDir, "_role.md" );
116 writeFileSync (path, role);
117 return { path, bytes: Buffer. byteLength (role) };
118 }
119
120 export function buildFramePackets ({
121 projectDir ,
122 storyboardPath = join (projectDir, "STORYBOARD.md" ),
123 outDir = join (projectDir, ".hyperframes" , "frame-packets" ),
124 maxPacketBytes = 48_000 ,
125 animationDir ,
126 corePath ,
127 deltaPath ,
128 // Per-workflow hooks (all optional):
129 // designTruthLine(projectDir) -> the packet's design-truth input line
130 // validateFrame(frame, id) -> throw to reject a frame before packing
131 // extraSections(block) -> extra packet sections appended after the rule recipes
132 designTruthLine = ( dir ) => `- Design tokens: ${ join ( resolve ( dir ), "frame.md" ) }` ,
133 validateFrame ,
134 extraSections ,
135 }) {
136 const storyboard = readFileSync (storyboardPath, "utf8" );
137 const frames = splitFrames (storyboard);
138 if (frames. length === 0 ) throw new Error ( "STORYBOARD.md has no frame blocks" );
139 const ruleIds = knownRuleIds (animationDir);
140
141 const packets = frames. map (( frame ) => {
142 const id = frameId (frame);
143 if (validateFrame) validateFrame (frame, id);
144 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 ) : ""}` ;
145 const bytes = Buffer. byteLength (packet);
146 if (bytes > maxPacketBytes) {
147 throw new Error ( `${ id }: frame packet is ${ bytes } bytes (limit ${ maxPacketBytes })` );
148 }
149 return { frameId: id, path: join (outDir, `${ id }.md` ), bytes, packet };
150 });
151
152 mkdirSync (outDir, { recursive: true });
153 for ( const { path , packet } of packets) writeFileSync (path, packet);
154 buildRolePayload ({ corePath, deltaPath, outDir });
155 return packets. map (({ packet : _packet , ... result }) => result);
156 }
157
158 export function flag ( argv , name , fallback ) {
159 const index = argv. indexOf ( `--${ name }` );
160 return index >= 0 && argv[index + 1 ] ? argv[index + 1 ] : fallback;
161 }
162
163 // realpath both sides: on macOS /tmp → /private/tmp, and node resolves the main
164 // module's symlinks in import.meta.url while argv[1] keeps the invoked spelling —
165 // a raw compare silently skips main() when invoked through any symlinked path.
166 export function isMainModule ( importMetaUrl ) {
167 if ( ! process.argv[ 1 ]) return false ;
168 try {
169 return pathToFileURL ( realpathSync (process.argv[ 1 ])).href === importMetaUrl;
170 } catch {
171 return false ;
172 }
173 }
174
175 export function runCli ({ buildFramePackets : build , buildRolePayload : buildRole }) {
176 const argv = process.argv. slice ( 2 );
177 const projectDir = resolve ( flag (argv, "project" , "." ));
178 const outDir = resolve ( flag (argv, "out-dir" , join (projectDir, ".hyperframes" , "frame-packets" )));
179 try {
180 const packets = build ({
181 projectDir,
182 storyboardPath: resolve ( flag (argv, "storyboard" , join (projectDir, "STORYBOARD.md" ))),
183 outDir,
184 });
185 const role = buildRole ({ outDir });
186 console. log ( `✓ frame packets: ${ packets . length } bounded packet(s)` );
187 for ( const packet of packets)
188 console. log ( ` ${ packet . frameId }: ${ packet . bytes } bytes → ${ packet . path }` );
189 console. log ( ` worker role: ${ role . bytes } bytes → ${ role . path }` );
190 } catch (error) {
191 console. error ( `✗ frame packets: ${ error . message }` );
192 process. exit ( 1 );
193 }
194 }