1+ import {
2+ parseSnapshotRange ,
3+ sampleSnapshotRange ,
4+ resolveSnapshotCompositionRange ,
5+ type SnapshotRange ,
6+ } from "./snapshotSampling.js" ;
17import { failCommand } from "../utils/commandResult.js" ;
28// fallow-ignore-file complexity
39import { defineCommand } from "citty" ;
@@ -436,6 +442,8 @@ async function captureSnapshots(
436442 projectDir : string ,
437443 opts : {
438444 frames ?: number ;
445+ range ?: SnapshotRange ;
446+ composition ?: string ;
439447 timeout ?: number ;
440448 at ?: number [ ] ;
441449 outputDir ?: string ;
@@ -517,13 +525,38 @@ async function captureSnapshots(
517525 return [ ] ;
518526 }
519527
520- // Calculate seek positions — explicit timestamps or evenly spaced, always
521- // including a readable end-of-timeline frame (FINDING [7]).
522- const { times : positions , appendedTail } = computeSnapshotTimes ( duration , {
523- frames : numFrames ,
524- at : opts . at ,
525- includeEnd : opts . includeEnd ,
526- } ) ;
528+ let range = opts . range ;
529+ if ( opts . composition ) {
530+ const timing = await page . evaluate ( ( ) => ( {
531+ html : document . documentElement . outerHTML ,
532+ durations : Object . fromEntries (
533+ Object . entries ( ( window as any ) . __timelines ?? { } ) . map ( ( [ id , timeline ] ) => [
534+ id ,
535+ Number ( ( timeline as any ) . duration ?.( ) ) ,
536+ ] ) ,
537+ ) ,
538+ } ) ) ;
539+ range = resolveSnapshotCompositionRange (
540+ timing . html ,
541+ timing . durations ,
542+ opts . composition ,
543+ duration ,
544+ ) ;
545+ }
546+ const { times : positions , appendedTail } = range
547+ ? {
548+ times : sampleSnapshotRange ( range , numFrames , duration , ! ! opts . composition ) ,
549+ appendedTail : false ,
550+ }
551+ : computeSnapshotTimes ( duration , {
552+ frames : numFrames ,
553+ at : opts . at ,
554+ includeEnd : opts . includeEnd ,
555+ } ) ;
556+ if ( range )
557+ console . log (
558+ ` Sampling ${ positions . length } frames within ${ range [ 0 ] } –${ range [ 1 ] } s${ opts . composition ? ` (composition ${ opts . composition } )` : "" } ` ,
559+ ) ;
527560 if ( appendedTail ) {
528561 console . log (
529562 ` ${ c . dim ( `Note: added an end-of-timeline frame at ${ positions [ positions . length - 1 ] ! . toFixed ( 2 ) } s. Short beats between your --at times may still be skipped — pass them explicitly.` ) } ` ,
@@ -842,6 +875,16 @@ export default defineCommand({
842875 description :
843876 "Comma-separated timestamps in seconds (e.g., --at 3.0,10.5,18.0). Each is captured at that exact instant, not snapped to a frame." ,
844877 } ,
878+ range : {
879+ type : "string" ,
880+ description :
881+ "Root-timeline range START,END in seconds; sample --frames evenly within it, without adding the full-video tail" ,
882+ } ,
883+ composition : {
884+ type : "string" ,
885+ description :
886+ "data-composition-id to sample; take --frames within its effective root-timeline interval, without adding the full-video tail" ,
887+ } ,
845888 timeout : {
846889 type : "string" ,
847890 description : "Ms to wait for runtime to initialize (default: 5000)" ,
@@ -892,6 +935,13 @@ export default defineCommand({
892935 } ,
893936 } ,
894937 async run ( { args } ) {
938+ if ( [ args . at , args . range , args . composition ] . filter ( ( value ) => value !== undefined ) . length > 1 )
939+ throw new Error ( "Use only one of --at, --range, or --composition" ) ;
940+ const frames = parseInt ( args . frames as string , 10 ) || 5 ;
941+ const range = args . range === undefined ? undefined : parseSnapshotRange ( String ( args . range ) ) ;
942+ const composition =
943+ args . composition === undefined ? undefined : String ( args . composition ) . trim ( ) ;
944+ if ( composition === "" ) throw new Error ( "--composition requires a composition ID" ) ;
895945 const project = resolveProject ( args . dir ) ;
896946 const lintResult = await lintProject ( project . dir ) ;
897947 if ( hasDefinitiveEntryMismatch ( lintResult ) ) {
@@ -920,7 +970,6 @@ export default defineCommand({
920970 console . log ( "" ) ;
921971 failCommand ( ) ;
922972 }
923- const frames = parseInt ( args . frames as string , 10 ) || 5 ;
924973 const timeout = parseInt ( args . timeout as string , 10 ) || 5000 ;
925974 const atTimestamps = args . at
926975 ? String ( args . at )
@@ -963,6 +1012,8 @@ export default defineCommand({
9631012 : join ( project . dir , "snapshots" ) ;
9641013 const paths = await captureSnapshots ( project . dir , {
9651014 frames,
1015+ range,
1016+ composition,
9661017 timeout,
9671018 at : atTimestamps ,
9681019 outputDir : snapshotDir ,
@@ -1001,10 +1052,8 @@ export default defineCommand({
10011052 snapshotDir ,
10021053 join ( snapshotDir , "contact-sheet.jpg" ) ,
10031054 ) ;
1004- if ( sheets . length > 0 ) {
1005- const label =
1006- sheets . length === 1 ? "contact-sheet.jpg" : `contact-sheet-1..${ sheets . length } .jpg` ;
1007- console . log ( ` ${ c . dim ( label ) } (grid view for AI review)` ) ;
1055+ for ( const sheet of sheets ) {
1056+ console . log ( ` ${ resolve ( sheet ) } (grid view for AI review)` ) ;
10081057 }
10091058 } catch ( err ) {
10101059 console . warn (
@@ -1019,7 +1068,8 @@ export default defineCommand({
10191068 try {
10201069 const geminiKey = process . env . GEMINI_API_KEY || process . env . GOOGLE_API_KEY ;
10211070 if ( ! geminiKey ) {
1022- console . log ( ` ${ c . dim ( "--describe: GEMINI_API_KEY not set, skipping" ) } ` ) ;
1071+ if ( args . describe !== undefined )
1072+ console . log ( ` ${ c . dim ( "--describe: GEMINI_API_KEY not set, skipping" ) } ` ) ;
10231073 } else if ( paths . length > 0 ) {
10241074 console . log ( ` ${ c . dim ( "Describing frames with Gemini vision..." ) } ` ) ;
10251075 const { GoogleGenAI } = await loadOptionalPackage ( "@google/genai" , "--describe" ) ;
0 commit comments