From 5b98f4f36719bde95b642e89bfb5409e41e39365 Mon Sep 17 00:00:00 2001 From: Archi Date: Mon, 26 Oct 2026 19:42:24 +0100 Subject: [PATCH 1/3] feat(core): trim and cuts in edits.json RunEditsSchema takes a trim and up to 100 ordered, non-touching cuts in timeline ms. checkRunEdits now takes the run's result and reports a cut outside the trimmed range, a trim or cut hiding the failed step, and less than 500 ms of page left (spec 354). --- packages/core/schemas/edits.schema.json | 37 ++++++ packages/core/src/edits.ts | 145 ++++++++++++++++++++++++ packages/core/test/edits.spec.ts | 138 +++++++++++++++++++++- packages/renderer/src/plan/plan.ts | 6 +- 4 files changed, 323 insertions(+), 3 deletions(-) diff --git a/packages/core/schemas/edits.schema.json b/packages/core/schemas/edits.schema.json index d943b5b..299db32 100644 --- a/packages/core/schemas/edits.schema.json +++ b/packages/core/schemas/edits.schema.json @@ -59,6 +59,43 @@ "additionalProperties": false } }, + "trim": { + "type": "object", + "properties": { + "startMs": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "endMs": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "additionalProperties": false + }, + "cuts": { + "maxItems": 100, + "type": "array", + "items": { + "type": "object", + "properties": { + "startMs": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "endMs": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "required": ["startMs", "endMs"], + "additionalProperties": false + } + }, "cards": { "type": "object", "properties": { diff --git a/packages/core/src/edits.ts b/packages/core/src/edits.ts index ba9f5a3..85e49dd 100644 --- a/packages/core/src/edits.ts +++ b/packages/core/src/edits.ts @@ -5,6 +5,7 @@ import { CardTextSchema, FrameConfigSchema, } from './project-config.ts'; +import type { RunResult } from './run-result.ts'; import { ZoomSchema } from './step.ts'; import type { Timeline } from './timeline.ts'; @@ -48,6 +49,47 @@ const EditedCaptionsSchema = z } }); +const MAX_CUTS = 100; + +/** The least page a trim and cuts may leave (spec 354). */ +const MIN_PAGE_MS = 500; + +/** A new start and a new end of the page, either optional. */ +const TrimSchema = z + .strictObject({ startMs: msSchema.optional(), endMs: msSchema.optional() }) + .refine( + (trim) => + trim.startMs === undefined || + trim.endMs === undefined || + trim.startMs < trim.endMs, + { message: 'expected endMs to be after startMs', path: ['endMs'] }, + ); + +const CutSchema = z + .strictObject({ startMs: msSchema, endMs: msSchema }) + .refine((cut) => cut.endMs > cut.startMs, { + message: 'expected endMs to be after startMs', + path: ['endMs'], + }); + +/** Ordered by `startMs`, at least 1 ms apart: two touching cuts are one cut. */ +const CutsSchema = z + .array(CutSchema) + .max(MAX_CUTS) + .superRefine((cuts, ctx) => { + for (const [index, cut] of cuts.entries()) { + const previous = cuts[index - 1]; + if (previous !== undefined && cut.startMs <= previous.endMs) { + ctx.addIssue({ + code: 'custom', + message: + 'expected cuts ordered by startMs, neither overlapping nor touching', + path: [index, 'startMs'], + }); + } + } + }); + /** At most one entry per step. */ const ZoomEditsSchema = z .array( @@ -84,6 +126,10 @@ export const RunEditsSchema = z.strictObject({ captions: EditedCaptionsSchema.optional(), // A step not listed keeps its timeline `zoom`. zoom: ZoomEditsSchema.optional(), + // Timeline ms (spec 354): the page plays from `startMs` to `endMs`, less + // every cut. The source stays as recorded. + trim: TrimSchema.optional(), + cuts: CutsSchema.optional(), cards: z .strictObject({ intro: z @@ -121,10 +167,16 @@ export type RunEdits = z.infer; * step whose event has a target box (ADR-0012 §2), and no caption past the * end of the video. `tailMs` is the end hold the renderer keeps after the * last event and its hold (`render.endHoldMs`). + * + * The trim and the cuts (spec 354) are checked against the run's range — to + * the failed step's end on a failed run, as the renderer ends it: every cut + * inside the trimmed range, nothing hiding the failure (ADR-0004 §4, + * ADR-0020 §2), and at least 500 ms of page left. */ export function checkRunEdits( edits: RunEdits, timeline: Timeline, + result: RunResult, { tailMs = DEFAULT_TAIL_MS }: { tailMs?: number } = {}, ): Issue[] { const issues: Issue[] = []; @@ -156,5 +208,98 @@ export function checkRunEdits( }); } } + issues.push(...checkTrim(edits, timeline, result, endMs)); + return issues; +} + +/** `passedEndMs`: where the video of a passed run ends, in timeline ms. */ +function checkTrim( + { trim, cuts = [] }: RunEdits, + timeline: Timeline, + result: RunResult, + passedEndMs: number, +): Issue[] { + if (trim === undefined && cuts.length === 0) return []; + const issues: Issue[] = []; + const failure = failureOf(result); + const failedEvent = + failure?.stepIndex === undefined + ? undefined + : timeline.events.find((event) => event.stepIndex === failure.stepIndex); + const lastEvent = timeline.events.at(-1); + // The renderer's range: to the failure, or the end hold after the last event. + const runEndMs = + lastEvent === undefined + ? Infinity + : failure === undefined + ? passedEndMs + : (failedEvent ?? lastEvent).endMs; + const fromMs = trim?.startMs ?? 0; + const toMs = Math.min(trim?.endMs ?? Infinity, runEndMs); + for (const [index, cut] of cuts.entries()) { + if (cut.startMs < fromMs || cut.endMs > toMs) { + issues.push({ + path: `cuts[${index}]`, + code: 'cut-outside-trim', + message: `expected the cut inside the page, ${fromMs}–${toMs} ms`, + }); + } + } + if (failedEvent !== undefined) { + if (trim?.endMs !== undefined && trim.endMs < failedEvent.endMs) { + issues.push({ + path: 'trim.endMs', + code: 'trim-hides-failure', + message: `expected the trim to end at or after ${failedEvent.endMs} ms, where step ${failedEvent.stepIndex} failed`, + }); + } + // A step with no length still shows for the instant it starts. + const failedUntil = Math.max(failedEvent.endMs, failedEvent.startMs + 1); + for (const [index, cut] of cuts.entries()) { + if (cut.startMs < failedUntil && cut.endMs > failedEvent.startMs) { + issues.push({ + path: `cuts[${index}]`, + code: 'trim-hides-failure', + message: `expected the cut to leave step ${failedEvent.stepIndex}, which failed, on screen`, + }); + } + } + } + if (Number.isFinite(toMs)) { + const cutMs = cuts.reduce( + (sum, cut) => + sum + + Math.max(0, Math.min(cut.endMs, toMs) - Math.max(cut.startMs, fromMs)), + 0, + ); + if (toMs - fromMs - cutMs < MIN_PAGE_MS) { + issues.push({ + path: trim === undefined ? 'cuts' : 'trim', + code: 'too-short', + message: `expected at least ${MIN_PAGE_MS} ms of page after the trim and the cuts`, + }); + } + } return issues; } + +/** The failure of a capture stage, as the renderer reads it; `undefined` on a passed run. */ +function failureOf(result: RunResult): { stepIndex?: number } | undefined { + for (const stage of CAPTURE_STAGES) { + const state = result.stages[stage]; + if (state.status === 'failed') { + return state.error?.stepIndex === undefined + ? {} + : { stepIndex: state.error.stepIndex }; + } + } + return undefined; +} + +/** The stages that decide whether the run failed; `rendering` and `storage` do not. */ +const CAPTURE_STAGES = [ + 'readiness', + 'execution', + 'verification', + 'recording', +] as const; diff --git a/packages/core/test/edits.spec.ts b/packages/core/test/edits.spec.ts index 9c6bac2..99844c4 100644 --- a/packages/core/test/edits.spec.ts +++ b/packages/core/test/edits.spec.ts @@ -1,8 +1,11 @@ import { describe, expect, it } from 'vitest'; import { checkRunEdits, + deriveRunStatus, type RunEdits, RunEditsSchema, + type RunResult, + type Stages, type Timeline, TimelineSchema, } from '../src/index.ts'; @@ -25,12 +28,44 @@ const timeline: Timeline = TimelineSchema.parse({ ], }); +function result(failedAt?: number): RunResult { + const passed = { status: 'passed' as const }; + const stages: Stages = { + readiness: passed, + execution: + failedAt === undefined + ? passed + : { + status: 'failed', + error: { message: 'boom', stepIndex: failedAt }, + }, + verification: passed, + recording: passed, + rendering: { status: 'pending' }, + storage: { status: 'pending' }, + }; + return { + schemaVersion: 1, + runId: 'run', + scenarioId: 'inline', + scenarioName: 'Sign up', + startedAt: '2026-10-26T10:00:00.000Z', + finishedAt: '2026-10-26T10:00:10.000Z', + status: deriveRunStatus(stages), + stages, + renders: [], + warnings: [], + }; +} + const caption = (startMs: number, endMs: number, text = 'Hello') => ({ startMs, endMs, text, }); +const cut = (startMs: number, endMs: number) => ({ startMs, endMs }); + describe('RunEditsSchema', () => { it('parses a minimal file', () => { expect(RunEditsSchema.parse({ schemaVersion: 1 })).toEqual({ @@ -53,6 +88,8 @@ describe('RunEditsSchema', () => { }, background: { color: '#112233' }, frame: { enabled: true, radius: 0, shadow: false }, + trim: { startMs: 200, endMs: 2_000 }, + cuts: [cut(300, 400), cut(401, 900)], }; expect(RunEditsSchema.parse(edits)).toEqual(edits); }); @@ -66,7 +103,7 @@ describe('RunEditsSchema', () => { }); it.each([ - ['an unknown key', { schemaVersion: 1, trim: { startMs: 0 } }], + ['an unknown key', { schemaVersion: 1, speed: 2 }], ['schemaVersion 2', { schemaVersion: 2 }], ['an empty caption span', { captions: [caption(100, 100)] }], ['a caption ending before it starts', { captions: [caption(100, 50)] }], @@ -107,12 +144,42 @@ describe('RunEditsSchema', () => { ['a negative frame radius', { frame: { radius: -1 } }], ['a frame margin', { frame: { marginRatio: 0.1 } }], ['an image background', { background: { image: 'a.png' } }], + ['a trim ending at its start', { trim: { startMs: 500, endMs: 500 } }], + ['a trim ending before its start', { trim: { startMs: 500, endMs: 400 } }], + ['an empty cut', { cuts: [cut(100, 100)] }], + ['unordered cuts', { cuts: [cut(500, 600), cut(0, 100)] }], + ['overlapping cuts', { cuts: [cut(0, 200), cut(100, 300)] }], + ['touching cuts', { cuts: [cut(0, 200), cut(200, 300)] }], + [ + '101 cuts', + { + cuts: Array.from({ length: 101 }, (_, index) => + cut(index * 10, index * 10 + 5), + ), + }, + ], ])('rejects %s', (_, edits) => { expect( RunEditsSchema.safeParse({ schemaVersion: 1, ...edits }).success, ).toBe(false); }); + it('accepts a trim with one end, and 100 cuts', () => { + const cuts = Array.from({ length: 100 }, (_, index) => + cut(index * 10, index * 10 + 5), + ); + for (const edits of [ + { trim: { startMs: 500 } }, + { trim: { endMs: 500 } }, + { trim: {} }, + { cuts }, + ]) { + expect( + RunEditsSchema.safeParse({ schemaVersion: 1, ...edits }).success, + ).toBe(true); + } + }); + it('accepts 200 captions', () => { const captions = Array.from({ length: 200 }, (_, index) => caption(index * 10, index * 10 + 5), @@ -124,10 +191,15 @@ describe('RunEditsSchema', () => { }); describe('checkRunEdits', () => { - const check = (edits: Omit, tailMs?: number) => + const check = ( + edits: Omit, + tailMs?: number, + failedAt?: number, + ) => checkRunEdits( RunEditsSchema.parse({ schemaVersion: 1, ...edits }), timeline, + result(failedAt), tailMs === undefined ? {} : { tailMs }, ); @@ -173,4 +245,66 @@ describe('checkRunEdits', () => { ]); expect(check({ captions: [caption(0, 2_900)] }, 0)).toEqual([]); }); + + describe('trim and cuts', () => { + // The run's range: 0 to 5400 (the last event ends at 2400, holds 500, + // and the default tail is 2500); to 1400 when the click at step 1 fails. + it('accepts a cut over the last step of a passed run', () => { + expect(check({ cuts: [cut(1_400, 2_900)] })).toEqual([]); + expect(check({ trim: { startMs: 100, endMs: 5_400 } })).toEqual([]); + }); + + it('reports cut-outside-trim for a cut past either end of the trim, or of the run', () => { + expect( + check({ + trim: { startMs: 500, endMs: 3_000 }, + cuts: [cut(400, 600), cut(1_000, 1_200), cut(2_900, 3_100)], + }), + ).toEqual([ + expect.objectContaining({ path: 'cuts[0]', code: 'cut-outside-trim' }), + expect.objectContaining({ path: 'cuts[2]', code: 'cut-outside-trim' }), + ]); + expect(check({ cuts: [cut(5_000, 5_401)] })).toEqual([ + expect.objectContaining({ path: 'cuts[0]', code: 'cut-outside-trim' }), + ]); + }); + + it('reports trim-hides-failure for a trim ending before the failed step ends', () => { + expect(check({ trim: { endMs: 1_399 } }, undefined, 1)).toEqual([ + expect.objectContaining({ + path: 'trim.endMs', + code: 'trim-hides-failure', + }), + ]); + expect(check({ trim: { endMs: 1_400 } }, undefined, 1)).toEqual([]); + }); + + it('reports trim-hides-failure for a cut over the failed step', () => { + expect(check({ cuts: [cut(1_300, 1_350)] }, undefined, 1)).toEqual([ + expect.objectContaining({ path: 'cuts[0]', code: 'trim-hides-failure' }), + ]); + // Touching the step is not over it. + expect(check({ cuts: [cut(100, 800)] }, undefined, 1)).toEqual([]); + }); + + it('ends the range of a failed run at the failed step', () => { + expect(check({ cuts: [cut(1_400, 1_500)] }, undefined, 1)).toEqual([ + expect.objectContaining({ code: 'cut-outside-trim' }), + ]); + }); + + it('reports too-short when less than 500 ms of page is left', () => { + expect(check({ trim: { startMs: 1_000, endMs: 1_499 } })).toEqual([ + expect.objectContaining({ path: 'trim', code: 'too-short' }), + ]); + expect(check({ trim: { startMs: 1_000, endMs: 1_500 } })).toEqual([]); + expect(check({ cuts: [cut(0, 4_901)] })).toEqual([ + expect.objectContaining({ path: 'cuts', code: 'too-short' }), + ]); + // A trim past the end of the run leaves nothing. + expect(check({ trim: { startMs: 6_000 } })).toEqual([ + expect.objectContaining({ code: 'too-short' }), + ]); + }); + }); }); diff --git a/packages/renderer/src/plan/plan.ts b/packages/renderer/src/plan/plan.ts index 40af886..61ecba4 100644 --- a/packages/renderer/src/plan/plan.ts +++ b/packages/renderer/src/plan/plan.ts @@ -151,6 +151,7 @@ export async function buildRenderPlan( const edits = await readEdits( path.join(runDir, PLAN_INPUTS.edits), timeline, + result, options.endHoldMs ?? DEFAULTS.endHoldMs, ); const videoFile = path.join(runDir, timeline.videoFile); @@ -179,6 +180,7 @@ export async function buildRenderPlan( async function readEdits( file: string, timeline: Timeline, + result: RunResult, tailMs: number, ): Promise { let text: string; @@ -202,7 +204,9 @@ async function readEdits( `${name} is invalid at ${formatPath(issue.path) || '(root)'}: ${issue.message}`, ); } - const [issue] = checkRunEdits(parsed.data, timeline, { tailMs }); + const [issue] = checkRunEdits(parsed.data, timeline, result, { + tailMs, + }); if (issue !== undefined) { throw new Error( `${name} does not fit the run at ${issue.path}: ${issue.message}`, From b70cfe999c85b45b1f2a0e19e88c1611d0e85160 Mon Sep 17 00:00:00 2001 From: Archi Date: Mon, 26 Oct 2026 19:59:54 +0100 Subject: [PATCH 2/3] feat(renderer): trim and cut segments from edits.json The trim sets the page's source range and each cut is a segment of the time map with no output span (spec 354). Captions, click rings, key badges and scene cards inside a cut or outside the trim are dropped; the cursor jumps across a cut; the camera and the crop follow are planned with the cuts played and held across each join. Mask spans get keys at the cut edges inside a scroll, and with transitions on every cut dissolves from the last source frame before it, carrying that frame's masks. --- packages/renderer/src/plan/cards.ts | 6 +- packages/renderer/src/plan/cuts.ts | 106 ++++++ packages/renderer/src/plan/masks.ts | 55 ++- packages/renderer/src/plan/plan.ts | 208 ++++++++--- packages/renderer/src/plan/time-map.ts | 30 +- packages/renderer/src/plan/transitions.ts | 84 ++++- packages/renderer/src/plan/types.ts | 7 +- packages/renderer/test/plan/cuts.spec.ts | 420 ++++++++++++++++++++++ 8 files changed, 860 insertions(+), 56 deletions(-) create mode 100644 packages/renderer/src/plan/cuts.ts create mode 100644 packages/renderer/test/plan/cuts.spec.ts diff --git a/packages/renderer/src/plan/cards.ts b/packages/renderer/src/plan/cards.ts index 44d1dd4..b687b10 100644 --- a/packages/renderer/src/plan/cards.ts +++ b/packages/renderer/src/plan/cards.ts @@ -26,7 +26,8 @@ export type PlacedCard = CardSpec & CardSlot; * card on every `scene` marker before the page ends, and — on a successful * run with a title — the outro after it. `out` maps timeline ms to page ms. * `edits` (spec 353) switch cards and replace their text; without a config - * there are no cards, edited or not. + * there are no cards, edited or not. A scene the page never shows — inside a + * cut or outside the trim (spec 354) — places no card. */ export function placeCards(input: { config?: CardsConfig; @@ -39,6 +40,8 @@ export function placeCards(input: { description?: string; failed: boolean; edits?: RunEdits['cards']; + /** Whether the page never shows this timeline instant. */ + hidden?: (timelineMs: number) => boolean; }): PlacedCard[] { const { config, events, out, pageEndMs, edits } = input; const annotations = input.annotations ?? []; @@ -74,6 +77,7 @@ export function placeCards(input: { ), ].sort((a, b) => a.timelineMs - b.timelineMs); for (const scene of scenes) { + if (input.hidden?.(scene.timelineMs) === true) continue; const atMs = out(scene.timelineMs); // After a failure the page has ended; the scene never showed. if (atMs >= pageEndMs) continue; diff --git a/packages/renderer/src/plan/cuts.ts b/packages/renderer/src/plan/cuts.ts new file mode 100644 index 0000000..c5a0548 --- /dev/null +++ b/packages/renderer/src/plan/cuts.ts @@ -0,0 +1,106 @@ +import { cursorAt } from './frame.ts'; +import type { CursorMove, Interval } from './types.ts'; + +/** + * A cut where it joins the page (spec 354): `fromMs` and `toMs` in the page + * ms of the map that plays the cut, `atMs` in page ms, where it plays in 0. + */ +export interface CutJoin { + fromMs: number; + toMs: number; + atMs: number; +} + +/** + * Whether `[fromMs, toMs]` of the timeline lies inside one of `removed` — + * the trim's head and tail and the cuts — so the page never shows it. An + * instant on a cut's end shows: the page resumes there. + */ +export function hiddenBy( + removed: readonly Interval[], + fromMs: number, + toMs = fromMs, +): boolean { + return removed.some( + (span) => + span.startMs <= fromMs && toMs <= span.endMs && fromMs < span.endMs, + ); +} + +/** + * Cursor moves in timeline ms cut at every removed span inside them (spec + * 354, Decision 3): the cursor glides up to the span, then jumps to where it + * is after it — to the move's end when the span outlasts the move, as a move + * with no length on the span's end. + */ +export function splitMovesAt( + moves: readonly CursorMove[], + removed: readonly Interval[], +): CursorMove[] { + return moves.flatMap((move) => { + const pieces: CursorMove[] = []; + let piece = move; + for (const span of removed) { + if (span.endMs <= piece.startMs || span.startMs >= piece.endMs) continue; + if (span.startMs > piece.startMs) { + const point = cursorAt([move], span.startMs) ?? move.from; + pieces.push({ ...piece, endMs: span.startMs, to: point }); + } + if (span.endMs >= move.endMs) { + // The tail of the trim: nothing after it plays. + if (span.endMs === Infinity) return pieces; + piece = { + startMs: span.endMs, + endMs: span.endMs, + from: move.to, + to: move.to, + }; + break; + } + const point = cursorAt([move], span.endMs) ?? move.to; + piece = { ...piece, startMs: span.endMs, from: point }; + } + pieces.push(piece); + return pieces; + }); +} + +/** + * Keyframes planned on the map that plays the cuts, moved onto the page + * (spec 354, Decision 3): the keys inside a cut go, and the camera holds its + * state on the cut across the join — like across a card — then settles over + * `settleMs` on where the cut left it, unless a key after the cut comes + * sooner. So a zoom that starts inside a cut starts at the cut's end. + */ +export function holdAcrossCuts( + keys: readonly K[], + joins: readonly CutJoin[], + toPage: (ms: number) => number, + hold: (ms: number, atMs: number) => K, + settleMs: number, +): K[] { + const first = keys[0]; + const last = keys.at(-1); + if (joins.length === 0 || first === undefined || last === undefined) { + return [...keys]; + } + const inside = (ms: number): boolean => + joins.some((join) => ms > join.fromMs && ms <= join.toMs); + const out = keys + .filter((key) => !inside(key.atMs)) + .map((key) => ({ ...key, atMs: toPage(key.atMs) })); + for (const [index, join] of joins.entries()) { + if (join.toMs <= first.atMs || join.fromMs >= last.atMs) continue; + out.push(hold(join.fromMs, join.atMs)); + const after = keys.find((key) => key.atMs > join.toMs); + const settleAt = Math.min( + join.atMs + settleMs, + joins[index + 1]?.atMs ?? Infinity, + ); + if (after === undefined || toPage(after.atMs) > settleAt) { + out.push(hold(join.toMs, settleAt)); + } + } + // Stable: a hold comes after a key on the same instant. + return out.sort((a, b) => a.atMs - b.atMs); +} diff --git a/packages/renderer/src/plan/masks.ts b/packages/renderer/src/plan/masks.ts index 14c9be5..b2ae9ad 100644 --- a/packages/renderer/src/plan/masks.ts +++ b/packages/renderer/src/plan/masks.ts @@ -6,7 +6,7 @@ import type { TimelineEvent, } from '@demoflow/core'; import { showsHeldPage } from './transitions.ts'; -import type { MaskSpan } from './types.ts'; +import type { Interval, MaskSpan } from './types.ts'; /** Masks overhang the field's box by this much on every side. */ const MASK_MARGIN_PX = 4; @@ -38,6 +38,10 @@ const MASK_MARGIN_PX = 4; * the engine measured it in viewport space on every frame, and a move starts * a new interval, so a page scroll does not move it. A document navigation * may lengthen its span, never shorten it (#221). + * + * A scroll that crosses a span of `removed` — the trim and the cuts (spec + * 354), in timeline ms — gets a key on each edge of it, the box where the + * scroll had it then: the page jumps there at the join, and so does the box. */ export function maskSpans( events: readonly TimelineEvent[], @@ -48,6 +52,7 @@ export function maskSpans( leadMs, trailMs, maskedElements, + removed = [], ...leaving }: { leadMs: number; @@ -56,6 +61,7 @@ export function maskSpans( navigations: readonly Navigation[]; transitions: boolean; sourceFrameMs: number; + removed?: readonly Interval[]; }, ): MaskSpan[] { const documentEnd = (fromMs: number, endMs: number): number => @@ -81,13 +87,18 @@ export function maskSpans( ) { continue; } - keys.push({ atMs: Math.min(out(later.startMs), endMs), box }); + const before = box; box = { ...box, x: box.x - (scroll.after.x - scroll.before.x), y: box.y - (scroll.after.y - scroll.before.y), }; - keys.push({ atMs: Math.min(out(later.endMs), endMs), box }); + keys.push( + ...scrollKeys(later, before, box, removed, out).map((key) => ({ + ...key, + atMs: Math.min(key.atMs, endMs), + })), + ); } // The keys stay as measured: a hold reads the box at its start from them. spans.push({ @@ -117,13 +128,13 @@ export function maskSpans( const scroll = later.scroll; // A container scroll moves what is inside it; the masked field is not assumed to be. if (scroll === undefined || scroll.container !== undefined) continue; - keys.push({ atMs: out(later.startMs), box }); + const before = box; box = { ...box, x: box.x - (scroll.after.x - scroll.before.x), y: box.y - (scroll.after.y - scroll.before.y), }; - keys.push({ atMs: out(later.endMs), box }); + keys.push(...scrollKeys(later, before, box, removed, out)); if (!overlaps(box, viewport)) { endMs = out(later.endMs) + trailMs; break; @@ -158,6 +169,40 @@ export function maskSpans( return spans; } +/** + * A box's keys over a page scroll, `from → to` in page ms: one at each end, + * and one on each edge of a removed span inside it, the box lerped there. + */ +function scrollKeys( + scroll: { startMs: number; endMs: number }, + from: Box, + to: Box, + removed: readonly Interval[], + out: (timelineMs: number) => number, +): MaskSpan['keys'] { + const at = (timelineMs: number): MaskSpan['keys'][number] => { + const t = (timelineMs - scroll.startMs) / (scroll.endMs - scroll.startMs); + return { + atMs: out(timelineMs), + box: { + ...from, + x: from.x + (to.x - from.x) * t, + y: from.y + (to.y - from.y) * t, + }, + }; + }; + const inside = (ms: number): boolean => + ms > scroll.startMs && ms < scroll.endMs; + return [ + { atMs: out(scroll.startMs), box: from }, + ...removed.flatMap((span) => [ + ...(inside(span.startMs) ? [at(span.startMs)] : []), + ...(inside(span.endMs) ? [at(span.endMs)] : []), + ]), + { atMs: out(scroll.endMs), box: to }, + ]; +} + /** * When the document a mask's field was measured on leaves the screen (spec * 146), given the span's start in timeline ms and its end in page ms. The diff --git a/packages/renderer/src/plan/plan.ts b/packages/renderer/src/plan/plan.ts index 61ecba4..1aa6103 100644 --- a/packages/renderer/src/plan/plan.ts +++ b/packages/renderer/src/plan/plan.ts @@ -21,8 +21,14 @@ import { } from '@demoflow/core'; import { resolveBackground } from './background.ts'; import { placeCards, shiftOverlays } from './cards.ts'; +import { + type CutJoin, + hiddenBy, + holdAcrossCuts, + splitMovesAt, +} from './cuts.ts'; import { probeVideo } from './ffmpeg.ts'; -import { cropSize } from './frame.ts'; +import { cameraStateAt, cropSize, followAt } from './frame.ts'; import { measuredMaskMarginMs } from './mask-margin.ts'; import { maskSpans } from './masks.ts'; import { findSyncClear, syncOffset } from './sync-mark.ts'; @@ -30,9 +36,11 @@ import { buildTimeMap, idleStretches, insertCards, + subtractIntervals, toOutputMs, + toSourceMs, } from './time-map.ts'; -import { planHolds, shiftHolds } from './transitions.ts'; +import { planHolds, shiftHolds, withCutHolds } from './transitions.ts'; import type { CameraKeyframe, Caption, @@ -317,13 +325,94 @@ export function planRender( ? [{ startMs: toSource(event.endMs), endMs: toSource(shownUntil(event)) }] : []), ]); - const idle = idleStretches(source.freezes, active, thresholdMs, sourceEndMs); + // The trim sets the page's range, within the recording's (spec 354, + // Decision 1); the cuts play in 0 ms (Decision 2). + const trim = edits?.trim; + const pageStartMs = + trim?.startMs === undefined + ? startMs + : Math.max(startMs, toSource(trim.startMs)); + const pageStopMs = + trim?.endMs === undefined + ? sourceEndMs + : Math.max(pageStartMs, Math.min(sourceEndMs, toSource(trim.endMs))); + const cuts = edits?.cuts ?? []; + const sourceCuts: Interval[] = cuts.map((cut) => ({ + startMs: toSource(cut.startMs), + endMs: toSource(cut.endMs), + })); + // Timeline ms the page never shows. + const removed: Interval[] = [ + ...(trim?.startMs === undefined + ? [] + : [{ startMs: -Infinity, endMs: trim.startMs }]), + ...cuts, + ...(trim?.endMs === undefined + ? [] + : [{ startMs: trim.endMs, endMs: Infinity }]), + ]; + const hidden = (fromMs: number, toMs = fromMs): boolean => + hiddenBy(removed, fromMs, toMs); + + const idle = idleStretches(source.freezes, active, thresholdMs, pageStopMs); // Page time: the map before cards. Overlays are planned in it, then moved // past the cards, so no lead or trail is ever measured across a card. - const pageMap = buildTimeMap(idle, sourceEndMs, compressToMs, startMs); + const pageMap = buildTimeMap( + idle, + pageStopMs, + compressToMs, + pageStartMs, + sourceCuts, + ); const out = (timelineMs: number): number => toOutputMs(pageMap, toSource(timelineMs)); const pageEndMs = pageMap.at(-1)?.outputEndMs ?? 0; + // The same map with every cut played: what moves is planned on it, then + // held across each join, so no move is squeezed into a cut's instant. + const playedMap = buildTimeMap( + subtractIntervals(idle, sourceCuts), + pageStopMs, + compressToMs, + pageStartMs, + ); + const outPlayed = (timelineMs: number): number => + toOutputMs(playedMap, toSource(timelineMs)); + const playedToPage = (ms: number): number => + toOutputMs(pageMap, toSourceMs(playedMap, ms)); + const joins: CutJoin[] = sourceCuts.flatMap((cut) => { + const fromMs = toOutputMs(playedMap, cut.startMs); + const toMs = toOutputMs(playedMap, cut.endMs); + return toMs > fromMs + ? [{ fromMs, toMs, atMs: toOutputMs(pageMap, cut.startMs) }] + : []; + }); + const playedCamera = cameraKeyframes( + events, + outPlayed, + viewport, + defaultZoom, + shownUntil, + ); + const camera = holdAcrossCuts( + playedCamera, + joins, + playedToPage, + (ms, atMs) => ({ atMs, ...cameraStateAt(playedCamera, ms) }), + TIMING.zoomInMs, + ); + const followAcross = ( + crop: { width: number; height: number }, + config: { followMs: number; deadZone: number }, + ): FollowKey[] => { + const keys = followKeys(events, outPlayed, viewport, crop, config); + return holdAcrossCuts( + keys, + joins, + playedToPage, + (ms, atMs) => ({ atMs, ...(followAt(keys, ms) ?? { x: 0, y: 0 }) }), + config.followMs, + ); + }; const cards = placeCards({ ...(options.cards === undefined ? {} : { config: options.cards }), @@ -337,6 +426,7 @@ export function planRender( : { description: options.scenario.description }), failed: failure !== undefined, ...(edits?.cards === undefined ? {} : { edits: edits.cards }), + ...(removed.length === 0 ? {} : { hidden }), }); const masks = maskSpans(events, out, viewport, pageEndMs, { leadMs: maskLeadMs, @@ -345,6 +435,7 @@ export function planRender( navigations: timeline.navigations ?? [], transitions: options.transitions?.enabled === true, sourceFrameMs: 1000 / source.fps, + removed, }); const cardBackground = frame?.background ?? resolveBackground(background); const verticalConfig = VerticalConfigSchema.parse(options.vertical ?? {}); @@ -352,8 +443,9 @@ export function planRender( const { follow, squareFollow, ...overlays } = shiftOverlays( { // A phone has no mouse pointer: the click ring is the tap (spec 307). - cursor: timeline.device === 'phone' ? [] : cursorMoves(events, out), - clicks: clickRings(events, out), + cursor: + timeline.device === 'phone' ? [] : cursorMoves(events, out, removed), + clicks: clickRings(events, out, hidden), highlights: highlights( events, out, @@ -361,27 +453,15 @@ export function planRender( pageEndMs, cardBackground.to, ), - camera: cameraKeyframes(events, out, viewport, defaultZoom, shownUntil), - follow: followKeys( - events, - out, - viewport, - cropSize(viewport, VERTICAL), - verticalConfig, - ), - squareFollow: followKeys( - events, - out, - viewport, - cropSize(viewport, SQUARE), - squareConfig, - ), + camera, + follow: followAcross(cropSize(viewport, VERTICAL), verticalConfig), + squareFollow: followAcross(cropSize(viewport, SQUARE), squareConfig), masks, captions: edits?.captions === undefined - ? captions(events, timeline.annotations ?? [], out, pageEndMs) + ? captions(events, timeline.annotations ?? [], out, pageEndMs, hidden) : editedCaptions(edits.captions, out, pageEndMs), - keys: keyBadges(events, out, pageEndMs, viewport), + keys: keyBadges(events, out, pageEndMs, viewport, hidden), }, cards, ); @@ -390,18 +470,45 @@ export function planRender( ? { durationMs: options.transitions.durationMs, holds: shiftHolds( - planHolds({ - navigations: timeline.navigations ?? [], - events, - out, - toSource, - sourceStartMs: pageMap[0]?.sourceStartMs ?? 0, - pageEndMs, - masks, - sourceFrameMs: 1000 / source.fps, - maskLeadMs, - durationMs: options.transitions.durationMs, - }), + withCutHolds( + planHolds({ + navigations: timeline.navigations ?? [], + events, + out, + toSource, + sourceStartMs: pageMap[0]?.sourceStartMs ?? 0, + pageEndMs, + masks, + sourceFrameMs: 1000 / source.fps, + maskLeadMs, + durationMs: options.transitions.durationMs, + removed, + }), + { + // The last source frame before each cut dissolves into the + // first after it (spec 354, Decision 4). + joins: sourceCuts.flatMap((cut) => { + const sourceMs = Math.max( + pageStartMs, + cut.startMs - 1000 / source.fps, + ); + // A cut on the page's start is a trim: nothing before it to hold. + return cut.endMs > cut.startMs && cut.startMs > pageStartMs + ? [ + { + atMs: toOutputMs(pageMap, cut.startMs), + sourceMs, + heldAtMs: toOutputMs(pageMap, sourceMs), + }, + ] + : []; + }), + masks, + pageEndMs, + sourceFrameMs: 1000 / source.fps, + durationMs: options.transitions.durationMs, + }, + ), cards, ), } @@ -734,30 +841,41 @@ function pressMs(event: TimelineEvent): number { : event.endMs; } +/** Each step's pointer move, cut at every span the page never shows (spec 354). */ function cursorMoves( events: readonly TimelineEvent[], out: (timelineMs: number) => number, + removed: readonly Interval[], ): CursorMove[] { - return events.flatMap((event) => + const moves = events.flatMap((event) => event.pointer === undefined ? [] : [ { - startMs: out(event.startMs), - endMs: out(pressMs(event)), + startMs: event.startMs, + endMs: pressMs(event), from: event.pointer.from, to: event.pointer.to, }, ], ); + return splitMovesAt(moves, removed).map((move) => ({ + ...move, + startMs: out(move.startMs), + endMs: out(move.endMs), + })); } +/** A ring on every click the page shows the press of. */ function clickRings( events: readonly TimelineEvent[], out: (timelineMs: number) => number, + hidden: (timelineMs: number) => boolean, ): ClickRing[] { return events.flatMap((event) => - event.action !== 'click' || event.pointer === undefined + event.action !== 'click' || + event.pointer === undefined || + hidden(pressMs(event)) ? [] : [ { @@ -939,19 +1057,22 @@ function distance(a: Point, b: Point): number { * A badge naming the key of every `press`, hanging below its target — or, for * a press on the focused element, below where the pointer last rested (the * middle of the viewport before the first move). It shows from the step's - * start until 600 ms after its end; a later badge cuts an earlier one. + * start until 600 ms after its end; a later badge cuts an earlier one. A + * press the page never shows (spec 354) has none. */ function keyBadges( events: readonly TimelineEvent[], out: (timelineMs: number) => number, videoEndMs: number, viewport: { width: number; height: number }, + hidden: (fromMs: number, toMs: number) => boolean, ): KeyBadge[] { let rest: Point = { x: viewport.width / 2, y: viewport.height / 2 }; const list: KeyBadge[] = []; for (const event of events) { if (event.pointer !== undefined) rest = event.pointer.to; if (event.action !== 'press' || event.key === undefined) continue; + if (hidden(event.startMs, event.endMs)) continue; const anchor = event.target === undefined ? rest @@ -977,16 +1098,18 @@ function keyBadges( * A lower-third for every step `caption` and `caption` marker, from the * step's start until 800 ms after its end, and for every `caption` the page * set (#201), for 3 s from the call. A later caption cuts an earlier one, - * whichever source it came from. + * whichever source it came from. A step or call the page never shows (spec + * 354) has none: its tail would show past the cut. */ function captions( events: readonly TimelineEvent[], annotations: readonly Annotation[], out: (timelineMs: number) => number, videoEndMs: number, + hidden: (fromMs: number, toMs?: number) => boolean, ): Caption[] { const fromPage: Caption[] = annotations.flatMap((annotation) => - annotation.kind === 'caption' + annotation.kind === 'caption' && !hidden(annotation.atMs) ? [ { startMs: out(annotation.atMs), @@ -1003,6 +1126,7 @@ function captions( const text = event.marker?.kind === 'caption' ? event.marker.title : event.caption; if (text === undefined || text.trim() === '') return []; + if (hidden(event.startMs, event.endMs)) return []; return [ { startMs: out(event.startMs), diff --git a/packages/renderer/src/plan/time-map.ts b/packages/renderer/src/plan/time-map.ts index 0ed543b..b0e1437 100644 --- a/packages/renderer/src/plan/time-map.ts +++ b/packages/renderer/src/plan/time-map.ts @@ -29,6 +29,18 @@ export function idleStretches( return mergeSorted(idle); } +/** `intervals` less every one of `removed`. */ +export function subtractIntervals( + intervals: readonly Interval[], + removed: readonly Interval[], +): Interval[] { + let pieces = intervals.map((interval) => ({ ...interval })); + for (const window of removed) { + pieces = pieces.flatMap((piece) => subtract(piece, window)); + } + return pieces; +} + function subtract(piece: Interval, cut: Interval): Interval[] { if (cut.endMs <= piece.startMs || cut.startMs >= piece.endMs) return [piece]; const out: Interval[] = []; @@ -57,13 +69,18 @@ function mergeSorted(intervals: Interval[]): Interval[] { /** * The time map: source `[startMs, endMs]` in order, real time except the idle - * stretches, which each play in `compressToMs`. Output 0 is source `startMs`. + * stretches, which each play in `compressToMs`, and the cuts (spec 354, + * Decision 2), which play in 0 ms: a segment with a source span and no + * output, so every instant inside a cut maps to the join. A cut is taken out + * of the idle stretches first; what is left of a stretch still plays in + * `compressToMs`. Output 0 is source `startMs`. */ export function buildTimeMap( idle: readonly Interval[], endMs: number, compressToMs: number, startMs = 0, + cuts: readonly Interval[] = [], ): TimeSegment[] { const segments: TimeSegment[] = []; let source = startMs; @@ -79,12 +96,19 @@ export function buildTimeMap( source = sourceEndMs; output += outputLength; }; - for (const stretch of idle) { + const stretches = [ + ...subtractIntervals(idle, cuts).map((piece) => ({ ...piece, cut: false })), + ...cuts.map((cut) => ({ ...cut, cut: true })), + ].sort((a, b) => a.startMs - b.startMs); + for (const stretch of stretches) { if (stretch.startMs >= endMs) break; const stretchStart = Math.max(stretch.startMs, source); push(stretchStart, stretchStart - source); const stretchEnd = Math.min(stretch.endMs, endMs); - push(stretchEnd, Math.min(compressToMs, stretchEnd - stretchStart)); + push( + stretchEnd, + stretch.cut ? 0 : Math.min(compressToMs, stretchEnd - stretchStart), + ); } push(endMs, endMs - source); return segments; diff --git a/packages/renderer/src/plan/transitions.ts b/packages/renderer/src/plan/transitions.ts index 15abe32..55182fb 100644 --- a/packages/renderer/src/plan/transitions.ts +++ b/packages/renderer/src/plan/transitions.ts @@ -2,7 +2,7 @@ import type { Navigation, TimelineEvent } from '@demoflow/core'; import type { PlacedCard } from './cards.ts'; import { maskBoxAt } from './frame.ts'; import { shiftPastCards } from './time-map.ts'; -import type { MaskSpan, NavigationHold } from './types.ts'; +import type { Interval, MaskSpan, NavigationHold } from './types.ts'; /** * The holds of a run's page loads, in page ms (spec 114). Each navigation @@ -29,6 +29,9 @@ import type { MaskSpan, NavigationHold } from './types.ts'; * A hold carries every mask active from the frame held — or one source frame * before it — to its navigation's start, at its box on the frame held: that * frame shows that page, whatever the live page's masks do meanwhile. + * + * A frame held inside a cut (spec 354) never showed: the hold takes the frame + * a lead before the cut instead. */ export function planHolds(input: { navigations: readonly Navigation[]; @@ -46,8 +49,11 @@ export function planHolds(input: { /** The plan's mask lead: the same sync uncertainty, budgeted for masks. */ maskLeadMs: number; durationMs: number; + /** The trim and the cuts, timeline ms. */ + removed?: readonly Interval[]; }): NavigationHold[] { const { navigations, events, out, pageEndMs } = input; + const removed = input.removed ?? []; const leadMs = Math.max(input.maskLeadMs, 2 * input.sourceFrameMs); // Steps that take time: a marker is no action of its own. const steps = events.filter((event) => event.endMs > event.startMs); @@ -56,8 +62,21 @@ export function planHolds(input: { const first = index === 0; // After a failure the page has ended: this load never showed. if (!first && out(navigation.startMs) >= pageEndMs) break; + // The timeline ms of the frame held, before every cut it falls in. + let heldMs = navigation.startMs - leadMs; + let beforeCut = false; + for (const span of [...removed].reverse()) { + if ( + Number.isFinite(span.startMs) && + span.startMs <= heldMs && + heldMs < span.endMs + ) { + heldMs = span.startMs - leadMs; + beforeCut = true; + } + } // The page ms of the frame held. - const heldAtMs = out(navigation.startMs - leadMs); + const heldAtMs = out(heldMs); const startMs = first ? 0 : Math.max( @@ -95,7 +114,9 @@ export function planHolds(input: { // later than the frame's own time. sourceMs: Math.max( input.sourceStartMs, - input.toSource(navigation.startMs) - leadMs, + beforeCut + ? input.toSource(heldMs) + : input.toSource(navigation.startMs) - leadMs, ), }), masks: first @@ -117,6 +138,63 @@ export function planHolds(input: { return holds; } +/** + * `holds` with a dissolve at every cut (spec 354, Decision 4), in page ms: at + * the join the frame held — the last source frame before the cut — dissolves + * into the page after it over `durationMs`, never past the next hold, the + * next join or the end of the page. A join inside a page load's hold or + * dissolve has none: the load already hides it. Like a load's, the hold + * carries every mask on the frame held, at its box there. + */ +export function withCutHolds( + holds: readonly NavigationHold[], + input: { + /** In page order: the join, the source frame held, and its page ms. */ + joins: readonly { atMs: number; sourceMs: number; heldAtMs: number }[]; + /** In page ms, before the cards are inserted. */ + masks: readonly MaskSpan[]; + pageEndMs: number; + sourceFrameMs: number; + durationMs: number; + }, +): NavigationHold[] { + const { joins, pageEndMs } = input; + if (joins.length === 0) return [...holds]; + const all = [...holds]; + for (const [index, join] of joins.entries()) { + const { atMs, heldAtMs } = join; + if (holds.some((hold) => hold.startMs <= atMs && atMs < hold.fadeEndMs)) { + continue; + } + const fadeEndMs = Math.min( + atMs + input.durationMs, + holds.find((hold) => hold.startMs > atMs)?.startMs ?? Infinity, + joins[index + 1]?.atMs ?? Infinity, + pageEndMs, + ); + if (fadeEndMs <= atMs) continue; + all.push({ + startMs: atMs, + endMs: atMs, + fadeEndMs, + fadeMs: fadeEndMs - atMs, + sourceMs: join.sourceMs, + masks: input.masks + .filter( + (mask) => + mask.startMs <= atMs && mask.endMs > heldAtMs - input.sourceFrameMs, + ) + .map((mask) => + maskBoxAt( + mask, + Math.min(Math.max(heldAtMs, mask.startMs), mask.endMs), + ), + ), + }); + } + return all.sort((a, b) => a.startMs - b.startMs); +} + /** * The step before the one a navigation started in: a hold may freeze the * tail of it, never more. Not the triggering step itself — a `navigate` step diff --git a/packages/renderer/src/plan/types.ts b/packages/renderer/src/plan/types.ts index 620833e..4eb49b4 100644 --- a/packages/renderer/src/plan/types.ts +++ b/packages/renderer/src/plan/types.ts @@ -169,8 +169,9 @@ export interface SourceSpec { /** * One piece of the time map. Output time maps linearly onto source time: a - * piece whose spans differ is an idle stretch played fast, and one with no - * source span is a card, the page held on that frame behind it. + * piece whose spans differ is an idle stretch played fast, one with no + * source span is a card, the page held on that frame behind it, and one with + * no output span is a cut (spec 354), source that never plays. */ export interface TimeSegment { outputStartMs: number; @@ -254,6 +255,8 @@ export interface CardSpec { * instead — with `masks` drawn on it; at `endMs` the page is ready and the * held frame dissolves into it over `fadeMs` of page time, until `fadeEndMs`. * Cursor, rings, captions and badges keep following page time throughout. + * A cut (spec 354, Decision 4) is a hold with `startMs` at `endMs`: the last + * frame before the cut dissolves into the first after it. */ export interface NavigationHold { startMs: number; diff --git a/packages/renderer/test/plan/cuts.spec.ts b/packages/renderer/test/plan/cuts.spec.ts new file mode 100644 index 0000000..5ef45ab --- /dev/null +++ b/packages/renderer/test/plan/cuts.spec.ts @@ -0,0 +1,420 @@ +import { + type Annotation, + type CardsConfig, + deriveRunStatus, + type RunEdits, + type RunResult, + type Stages, + type Timeline, + type TimelineEvent, +} from '@demoflow/core'; +import { describe, expect, it } from 'vitest'; +import { + buildTimeMap, + frameAt, + planRender, + type RenderPlan, + type RenderPlanOptions, + toOutputMs, + toSourceMs, +} from '../../src/index.ts'; + +const VIEWPORT = { width: 1280, height: 720 }; +const SOURCE_FRAME_MS = 1000 / 25; +const FADE = { enabled: true, durationMs: 300 }; + +function result(): RunResult { + const passed = { status: 'passed' as const }; + const stages: Stages = { + readiness: passed, + execution: passed, + verification: passed, + recording: passed, + rendering: { status: 'pending' }, + storage: { status: 'pending' }, + }; + return { + schemaVersion: 1, + runId: 'run', + scenarioId: 'inline', + scenarioName: 'Create a customer', + startedAt: '2026-10-26T10:00:00.000Z', + finishedAt: '2026-10-26T10:00:10.000Z', + status: deriveRunStatus(stages), + stages, + renders: [], + warnings: [], + }; +} + +function timeline( + events: Omit[], + annotations?: Annotation[], +): Timeline { + return { + schemaVersion: 1, + viewport: VIEWPORT, + deviceScaleFactor: 2, + videoFile: 'source.webm', + events: events.map((event, stepIndex) => ({ ...event, stepIndex })), + ...(annotations === undefined ? {} : { annotations }), + }; +} + +/** No freezes and no offset: page time is timeline time until a cut. */ +function plan( + events: Omit[], + edits: Omit | undefined, + options: RenderPlanOptions & { annotations?: Annotation[] } = {}, +): RenderPlan { + const { annotations, ...rest } = options; + return planRender( + { + timeline: timeline(events, annotations), + result: result(), + source: { + width: 2560, + height: 1440, + fps: 25, + durationMs: 20_000, + codec: 'vp9', + freezes: [], + }, + ...(edits === undefined ? {} : { edits: { schemaVersion: 1, ...edits } }), + }, + { offsetMs: 0, frame: {}, ...rest }, + ); +} + +function click( + startMs: number, + endMs: number, + extra: Partial = {}, +): Omit { + return { + action: 'click', + startMs, + endMs, + target: { box: { x: 580, y: 346, width: 120, height: 28 } }, + pointer: { from: { x: 640, y: 360 }, to: { x: 640, y: 360 } }, + ...extra, + }; +} + +const wait = (startMs: number, endMs: number) => ({ + action: 'wait' as const, + startMs, + endMs, +}); + +const scene = (atMs: number, title: string) => ({ + action: 'marker' as const, + startMs: atMs, + endMs: atMs, + marker: { title, kind: 'scene' as const }, +}); + +/** Every card off unless a test turns it on. */ +function cards(overrides: Partial = {}): CardsConfig { + return { + intro: { enabled: false, durationMs: 2000 }, + scenes: { enabled: false, durationMs: 1500 }, + outro: { durationMs: 2500 }, + ...overrides, + }; +} + +/** Output ms of every output frame of the plan. */ +function frameTimes(rendered: RenderPlan): number[] { + const { fps } = rendered.output; + const count = Math.ceil((rendered.durationMs * fps) / 1000); + return Array.from({ length: count }, (_, index) => (index * 1000) / fps); +} + +const frameOf = (rendered: RenderPlan, outputMs: number): number => + Math.round((outputMs * rendered.output.fps) / 1000); + +const CUT = { startMs: 3000, endMs: 5000 }; + +describe('buildTimeMap with cuts', () => { + it('skips a cut: it plays in 0 ms and the page resumes on its end', () => { + const map = buildTimeMap([], 10_000, 400, 0, [CUT]); + expect(map).toEqual([ + { + outputStartMs: 0, + outputEndMs: 3000, + sourceStartMs: 0, + sourceEndMs: 3000, + }, + { + outputStartMs: 3000, + outputEndMs: 3000, + sourceStartMs: 3000, + sourceEndMs: 5000, + }, + { + outputStartMs: 3000, + outputEndMs: 8000, + sourceStartMs: 5000, + sourceEndMs: 10_000, + }, + ]); + expect(toOutputMs(map, 4000)).toBe(3000); + expect(toSourceMs(map, 3000)).toBe(5000); + expect(toSourceMs(map, 2999)).toBe(2999); + }); + + it('compresses only the half of an idle stretch a cut leaves', () => { + const map = buildTimeMap([{ startMs: 2000, endMs: 6000 }], 10_000, 400, 0, [ + { startMs: 2000, endMs: 4000 }, + ]); + expect(map).toEqual([ + { + outputStartMs: 0, + outputEndMs: 2000, + sourceStartMs: 0, + sourceEndMs: 2000, + }, + { + outputStartMs: 2000, + outputEndMs: 2000, + sourceStartMs: 2000, + sourceEndMs: 4000, + }, + { + outputStartMs: 2000, + outputEndMs: 2400, + sourceStartMs: 4000, + sourceEndMs: 6000, + }, + { + outputStartMs: 2400, + outputEndMs: 6400, + sourceStartMs: 6000, + sourceEndMs: 10_000, + }, + ]); + }); +}); + +describe('trim', () => { + const events = [click(1000, 2000), wait(2000, 6000)]; + + it('starts the page on the source frame of the trim’s start', () => { + const rendered = plan(events, { trim: { startMs: 2000 } }); + expect(rendered.timeMap[0]).toMatchObject({ + outputStartMs: 0, + sourceStartMs: 2000, + }); + const first = frameAt(rendered, 0).sourceMs; + expect(first).not.toBeNull(); + expect(Math.abs((first ?? 0) - 2000)).toBeLessThanOrEqual(SOURCE_FRAME_MS); + }); + + it('ends the page on the trim’s end, then plays the outro', () => { + const rendered = plan( + events, + { trim: { endMs: 5000 } }, + { cards: cards({ outro: { title: 'Thanks', durationMs: 2500 } }) }, + ); + const page = rendered.timeMap.filter( + (segment) => segment.sourceEndMs > segment.sourceStartMs, + ); + expect(page.at(-1)).toMatchObject({ outputEndMs: 5000, sourceEndMs: 5000 }); + expect(rendered.cards).toEqual([ + expect.objectContaining({ + kind: 'outro', + startMs: 5000, + durationMs: 2500, + }), + ]); + expect(rendered.durationMs).toBe(7500); + const last = frameAt(rendered, frameOf(rendered, 5000) - 1).sourceMs; + expect(Math.abs((last ?? 0) - 5000)).toBeLessThanOrEqual(SOURCE_FRAME_MS); + }); +}); + +describe('overlays across a cut', () => { + it('drops a caption inside a cut and keeps one across it on both sides', () => { + const events = [click(1000, 2000), wait(2000, 8000)]; + const rendered = plan(events, { + cuts: [CUT, { startMs: 6000, endMs: 6500 }], + captions: [ + { startMs: 2000, endMs: 5500, text: 'Across' }, + { startMs: 6100, endMs: 6400, text: 'Inside' }, + ], + }); + expect(rendered.captions).toEqual([ + { startMs: 2000, endMs: 3500, text: 'Across' }, + ]); + const shown = (ms: number) => + frameAt(rendered, frameOf(rendered, ms)).caption; + expect(shown(2900)).toBe('Across'); + expect(shown(3100)).toBe('Across'); + }); + + it('drops a step caption inside a cut and keeps one across it', () => { + const events = [ + click(2000, 3500, { caption: 'Across' }), + click(3500, 4500, { caption: 'Inside' }), + wait(4500, 8000), + ]; + const rendered = plan(events, undefined); + expect(rendered.captions.map((caption) => caption.text)).toEqual([ + 'Across', + 'Inside', + ]); + const cut = plan(events, { cuts: [CUT] }); + expect(cut.captions.map((caption) => caption.text)).toEqual(['Across']); + }); + + it('drops a click ring inside a cut', () => { + const events = [click(1000, 2000), click(3500, 4500), wait(4500, 8000)]; + expect(plan(events, undefined).clicks).toHaveLength(2); + const rendered = plan(events, { cuts: [CUT] }); + expect(rendered.clicks).toHaveLength(1); + expect(rendered.clicks[0].atMs).toBeLessThan(CUT.startMs); + }); + + it('places no scene card whose marker is inside a cut', () => { + const events = [ + scene(0, 'Start'), + click(1000, 2000), + scene(4000, 'Hidden'), + click(4000, 4500), + wait(4500, 8000), + ]; + const options = { + cards: cards({ scenes: { enabled: true, durationMs: 1500 } }), + }; + const titles = (rendered: RenderPlan) => + rendered.cards.map((card) => card.title); + expect(titles(plan(events, undefined, options))).toEqual([ + 'Start', + 'Hidden', + ]); + expect(titles(plan(events, { cuts: [CUT] }, options))).toEqual(['Start']); + }); + + it('jumps the cursor across a cut instead of gliding through it', () => { + const events = [ + click(2000, 4000, { + pointer: { from: { x: 0, y: 0 }, to: { x: 1000, y: 0 } }, + }), + wait(4000, 8000), + ]; + const rendered = plan(events, { cuts: [{ startMs: 2500, endMs: 3500 }] }); + for (const move of rendered.cursor) { + // No move is squeezed into the join's instant with a length. + expect(move.endMs).toBeGreaterThanOrEqual(move.startMs); + if (move.endMs === move.startMs) continue; + expect(move.endMs <= 2500 || move.startMs >= 2500).toBe(true); + } + }); +}); + +describe('transitions at a cut', () => { + const events = [click(1000, 2000), wait(2000, 8000)]; + + it('dissolves from the last frame before a cut with transitions on', () => { + const rendered = plan(events, { cuts: [CUT] }, { transitions: FADE }); + expect(rendered.transitions?.holds).toEqual([ + { + startMs: 3000, + endMs: 3000, + fadeEndMs: 3300, + fadeMs: 300, + sourceMs: 3000 - SOURCE_FRAME_MS, + masks: [], + }, + ]); + const state = frameAt(rendered, frameOf(rendered, 3100)); + expect(state.sourceMs).toBeGreaterThanOrEqual(CUT.endMs); + expect(state.fade?.from.sourceMs).toBe(3000 - SOURCE_FRAME_MS); + }); + + it('joins hard with transitions off', () => { + const rendered = plan( + events, + { cuts: [CUT] }, + { transitions: { enabled: false, durationMs: 300 } }, + ); + expect(rendered.transitions).toBeUndefined(); + expect(frameAt(rendered, frameOf(rendered, 3100)).fade).toBeUndefined(); + }); + + it('adds no dissolve for a trim', () => { + const rendered = plan( + events, + { trim: { startMs: 1500, endMs: 7000 } }, + { transitions: FADE }, + ); + expect(rendered.transitions?.holds).toEqual([]); + }); +}); + +describe('masks at a cut', () => { + const password = { x: 264, y: 230, width: 384, height: 28 }; + const VISIBLE = { startMs: 2000, endMs: 4000 }; + const events: Omit[] = [ + click(500, 1000), + { + action: 'fill', + startMs: 1000, + endMs: VISIBLE.startMs, + target: { box: password }, + masked: true, + value: '***', + maskVisibility: [{ ...VISIBLE, box: password }], + }, + wait(VISIBLE.startMs, 7000), + ]; + const visible = (rendered: RenderPlan, sourceMs: number): boolean => { + const timelineMs = sourceMs - rendered.offsetMs; + return timelineMs >= VISIBLE.startMs && timelineMs < VISIBLE.endMs; + }; + + /** Every cut with an edge within 300 ms of a visibility edge, 10 ms apart. */ + const cuts = [VISIBLE.startMs, VISIBLE.endMs].flatMap((edgeMs) => + Array.from({ length: 61 }, (_, index) => edgeMs - 300 + index * 10).flatMap( + (atMs) => [ + { startMs: atMs, endMs: atMs + 500 }, + { startMs: atMs - 500, endMs: atMs }, + ], + ), + ); + + it.each([ + ['off', { enabled: false, durationMs: 300 }], + ['on', FADE], + ])('leaves no visible field unmasked on any output frame, transitions %s', (_, transitions) => { + let liveChecked = 0; + let heldChecked = 0; + for (const cut of cuts) { + const rendered = plan(events, { cuts: [cut] }, { transitions }); + for (const atMs of frameTimes(rendered)) { + const where = `cut ${cut.startMs}–${cut.endMs}, frame at ${atMs}`; + const live = toSourceMs(rendered.timeMap, atMs); + if (visible(rendered, live)) { + liveChecked++; + expect( + rendered.masks.some( + (mask) => mask.startMs <= atMs && atMs < mask.endMs, + ), + where, + ).toBe(true); + } + const hold = rendered.transitions?.holds.find( + (entry) => entry.startMs <= atMs && atMs < entry.fadeEndMs, + ); + if (hold?.sourceMs !== undefined && visible(rendered, hold.sourceMs)) { + heldChecked++; + expect(hold.masks.length, where).toBeGreaterThan(0); + } + } + } + // The sweep reaches visible frames, and with transitions held ones. + expect(liveChecked).toBeGreaterThan(0); + expect(heldChecked > 0).toBe(transitions.enabled); + }); +}); From 572a92c8972d6759725380eac9a4ff2c09e82704 Mon Sep 17 00:00:00 2001 From: Archi Date: Mon, 26 Oct 2026 19:59:56 +0100 Subject: [PATCH 3/3] style(core): format the edits spec --- packages/core/test/edits.spec.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/core/test/edits.spec.ts b/packages/core/test/edits.spec.ts index 99844c4..08f51d7 100644 --- a/packages/core/test/edits.spec.ts +++ b/packages/core/test/edits.spec.ts @@ -281,7 +281,10 @@ describe('checkRunEdits', () => { it('reports trim-hides-failure for a cut over the failed step', () => { expect(check({ cuts: [cut(1_300, 1_350)] }, undefined, 1)).toEqual([ - expect.objectContaining({ path: 'cuts[0]', code: 'trim-hides-failure' }), + expect.objectContaining({ + path: 'cuts[0]', + code: 'trim-hides-failure', + }), ]); // Touching the step is not over it. expect(check({ cuts: [cut(100, 800)] }, undefined, 1)).toEqual([]);