Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
refactor: preserve semantic identity through video time
kashorina4c290b032f3
diff --git a/packages/audio-track/package.json b/packages/audio-track/package.jsonindex cc6c9805..1de78800 100644--- a/packages/audio-track/package.json+++ b/packages/audio-track/package.json@@ -20,6 +20,7 @@"@hypit/protocol": "workspace:*","@hypit/semantic-track": "workspace:*","@hypit/temporal": "workspace:*",+ "@hypit/temporal-markup": "workspace:*","@hypit/markup": "workspace:*"},"devDependencies": {diff --git a/packages/audio-track/src/component.ts b/packages/audio-track/src/component.tsindex e74e9c46..75b3e707 100644--- a/packages/audio-track/src/component.ts+++ b/packages/audio-track/src/component.ts@@ -2,8 +2,7 @@ import type { ComponentPackage } from "@hypit/component-kit";import type { SynchronizedMedia } from "@hypit/media";import { canonicalize } from "@hypit/protocol";import type { StoredValue } from "@hypit/protocol";-import type { SemanticTrack } from "@hypit/semantic-track";-import { projectSemanticProgramSpace } from "@hypit/semantic-track";+import type { ProgramSpace } from "@hypit/program-space";import { audioTrackProducers, audioTrackTypes } from "./manifest.js";import { appendProjectedAudioItem, assertAudioTrackProgram, createAudioTrackSet, finalizeAudioTrack, renderAudioTrack } from "./program.js";@@ -16,14 +15,14 @@ function inline<T>(value: StoredValue | undefined, label: string): T {}const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });-const base = (inputs: [AudioTrackSet, AudioTrackHeader, SemanticTrack, SynchronizedMedia, AudioClipSpec, TemporalWindow]) => output(appendProjectedAudioItem(...inputs));+const base = (inputs: [AudioTrackSet, AudioTrackHeader, ProgramSpace, SynchronizedMedia, AudioClipSpec, TemporalWindow]) => output(appendProjectedAudioItem(...inputs));export const audioTrackComponent = {producers: [{ producer: audioTrackProducers.createSet, handler: () => ({ outputs: { set: output(createAudioTrackSet()) }, needs: {} }) },{ producer: audioTrackProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: base([inline<AudioTrackSet>(inputs.set?.value, "AudioTrackSet"), inline<AudioTrackHeader>(inputs.header?.value, "AudioTrackHeader"),- inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"), inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),inline<AudioClipSpec>(inputs.spec?.value, "AudioClipSpec"),inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),]) }, needs: {} }) },@@ -31,7 +30,7 @@ export const audioTrackComponent = {inline<AudioTrackSet>(inputs.set?.value, "AudioTrackSet"), inline<AudioTrackHeader>(inputs.header?.value, "AudioTrackHeader"),)) }, needs: {} }) },{ producer: audioTrackProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderAudioTrack(- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")), inline<AudioTrackProgram>(inputs.program?.value, "AudioTrackProgram"),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<AudioTrackProgram>(inputs.program?.value, "AudioTrackProgram"),)) }, needs: {} }) },],validators: [{diff --git a/packages/audio-track/src/fragment.ts b/packages/audio-track/src/fragment.tsindex 93318944..ae0c8696 100644--- a/packages/audio-track/src/fragment.ts+++ b/packages/audio-track/src/fragment.ts@@ -2,52 +2,40 @@ import { compositionTypes } from "@hypit/composition";import { sealGraphFragment } from "@hypit/elaborator";import type { FragmentOperation } from "@hypit/elaborator";import { mediaTypes } from "@hypit/media";-import { narrativeTypes } from "@hypit/narrative";-import { semanticTrackTypes } from "@hypit/semantic-track";-import { temporalProducers, temporalTypes } from "@hypit/temporal";+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";+import { temporalTypes } from "@hypit/temporal";import { audioTrackProducers, audioTrackTypes } from "./manifest.js";-export type AudioTrackFragmentItem =- | { readonly kind: "program"; readonly mediaName: string; readonly specName: string; readonly windowSpecName: string }- | { readonly kind: "selection"; readonly mediaName: string; readonly specName: string; readonly windowSpecName: string; readonly sourceName: string }- | { readonly kind: "moment"; readonly mediaName: string; readonly specName: string; readonly windowSpecName: string; readonly sourceName: string };+export type AudioTrackFragmentItem = {+ readonly mediaName: string;+ readonly specName: string;+ readonly windowName: string;+};const input = (name: string) => ({ kind: "fragment-input" as const, name });const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });export function createAudioTrackFragment(items: readonly AudioTrackFragmentItem[]) {if (items.length === 0) throw new Error("Audio Track Fragment requires at least one Item.");- const inputTypes = new Map<string, (typeof audioTrackTypes.clipSpec | typeof mediaTypes.synchronized | typeof narrativeTypes.selection | typeof narrativeTypes.moment | typeof temporalTypes.windowSpec)>();+ const inputTypes = new Map<string, (typeof audioTrackTypes.clipSpec | typeof mediaTypes.synchronized | typeof temporalTypes.window)>();const operations: FragmentOperation[] = [+ { id: "audio:space", producer: semanticTrackProducers.projectProgramSpace, inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },{ id: "audio:set:empty", producer: audioTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },];let current = "audio:set:empty";items.forEach((item, index) => {inputTypes.set(item.mediaName, mediaTypes.synchronized);inputTypes.set(item.specName, audioTrackTypes.clipSpec);- inputTypes.set(item.windowSpecName, temporalTypes.windowSpec);- if (item.kind !== "program") {- inputTypes.set(item.sourceName, item.kind === "selection" ? narrativeTypes.selection : narrativeTypes.moment);- }+ inputTypes.set(item.windowName, temporalTypes.window);const id = `audio:set:append:${String(index + 1).padStart(4, "0")}`;- const windowId = `audio:window:${String(index + 1).padStart(4, "0")}`;- const windowProducer = item.kind === "program" ? temporalProducers.projectProgram- : item.kind === "selection" ? temporalProducers.projectSelection : temporalProducers.projectMoment;- operations.push({- id: windowId,- producer: windowProducer,- inputs: { semantic: input("semantic"), spec: input(item.windowSpecName),- ...(item.kind === "program" ? {} : { [item.kind]: input(item.sourceName) }) },- result: { kind: "output", name: "window" },- });operations.push({id,producer: audioTrackProducers.appendItem,inputs: {- set: operation(current), header: input("header"), semantic: input("semantic"),+ set: operation(current), header: input("header"), space: operation("audio:space"),media: input(item.mediaName), spec: input(item.specName),- window: operation(windowId),+ window: input(item.windowName),},result: { kind: "output", name: "set" },});@@ -55,7 +43,7 @@ export function createAudioTrackFragment(items: readonly AudioTrackFragmentItem[});operations.push({ id: "audio:program", producer: audioTrackProducers.finalize, inputs: { set: operation(current), header: input("header") }, result: { kind: "output", name: "program" } },- { id: "audio:track", producer: audioTrackProducers.render, inputs: { semantic: input("semantic"), program: operation("audio:program") }, result: { kind: "output", name: "track" } },+ { id: "audio:track", producer: audioTrackProducers.render, inputs: { space: operation("audio:space"), program: operation("audio:program") }, result: { kind: "output", name: "track" } },);return sealGraphFragment({inputs: [@@ -72,5 +60,5 @@ export function createAudioTrackFragment(items: readonly AudioTrackFragmentItem[}export const programAudioTrackFragment = createAudioTrackFragment([- { kind: "program", mediaName: "media", specName: "spec", windowSpecName: "window-spec" },+ { mediaName: "media", specName: "spec", windowName: "window" },]);diff --git a/packages/audio-track/src/manifest.ts b/packages/audio-track/src/manifest.tsindex 5962ae23..7edbd604 100644--- a/packages/audio-track/src/manifest.ts+++ b/packages/audio-track/src/manifest.ts@@ -1,10 +1,12 @@import { compositionDependency, compositionTypes } from "@hypit/composition";import { mediaDependency, mediaTypes } from "@hypit/media";-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";+import { narrativeDependency } from "@hypit/narrative";+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";import { blobRefObjectSchema } from "@hypit/protocol";import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";import { temporalDependency, temporalTypes } from "@hypit/temporal";+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";export const audioTrackModuleRef = { name: "@hypit/audio-track", version: "1" } as const;export const audioTrackTypes = {@@ -65,13 +67,13 @@ export const audioTrackProgramSchema: ValueSchema = object({const baseInputs = [{ name: "set", type: audioTrackTypes.set }, { name: "header", type: audioTrackTypes.header },- { name: "semantic", type: semanticTrackTypes.track }, { name: "media", type: mediaTypes.synchronized },+ { name: "space", type: programSpaceTypes.programSpace }, { name: "media", type: mediaTypes.synchronized },{ name: "spec", type: audioTrackTypes.clipSpec }, { name: "window", type: temporalTypes.window },] as const;export const audioTrackMarkupSurfaces = [{name: "track", tag: "Track", mode: "structured",- outputs: [audioTrackTypes.header, audioTrackTypes.clipSpec, temporalTypes.windowSpec, audioTrackTypes.program, compositionTypes.audioTrack],+ outputs: [audioTrackTypes.header, audioTrackTypes.clipSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, audioTrackTypes.program, compositionTypes.audioTrack],vocabulary: {summary: "One Audio Track: explicitly prepared audio Clips placed on a shared SemanticTrack and lowered to one ordinary peer AudioTrack.",attributes: [@@ -87,24 +89,7 @@ export const audioTrackMarkupSurfaces = [{{ name: "source", kind: "reference", required: true,accepts: [mediaTypes.synchronized],summary: "Selects the explicitly prepared audio this Clip plays." },- { name: "during", kind: "expression", required: false, values: ["program"],- accepts: [narrativeTypes.selection],- summary: "Spans the whole program when written as `program`, or the window of the referenced Selection." },- { name: "at", kind: "reference", required: false,- accepts: [narrativeTypes.moment],- summary: "Starts the window at the cue of the referenced Moment." },- { name: "for", kind: "literal", required: false,- summary: "Fixes the exact length of a Moment window, such as `12f`, `250ms` or `1.5s`." },- { name: "start", kind: "literal", required: false,- summary: "Places the window start at a point expression." },- { name: "end", kind: "literal", required: false,- summary: "Places the window end at a point expression." },- { name: "selection", kind: "reference", required: false,- accepts: [narrativeTypes.selection],- summary: "Binds the Selection that resolves `selection.start` and `selection.end` in a start/end window." },- { name: "moment", kind: "reference", required: false,- accepts: [narrativeTypes.moment],- summary: "Binds the Moment that resolves `moment.cue` in a start/end window." },+ ...temporalWindowAttributeVocabulary,{ name: "trim-start", kind: "literal", required: false,summary: "Removes an exact duration from the head of the source." },{ name: "trim-end", kind: "literal", required: false,@@ -134,7 +119,7 @@ export const audioTrackMarkupSurfaces = [{</audio:Track>`,notes: ["A Track requires at least one Clip, and neither a Track nor a Clip accepts text content.",- "A Clip states exactly one window form: `during`, `at` with `for`, or `start` with `end`.",+ "A Clip states exactly one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`.","A point expression is `program.start`, `program.end`, `selection.start`, `selection.end` or `moment.cue`, each optionally offset by `+` or `-` and a duration, or a bare duration read as an absolute position.","`selection` and `moment` cannot be written together.","`min-rate` and `max-rate` are rejected unless `playback` is `stretch`.",@@ -147,7 +132,7 @@ export const audioTrackManifest: ModuleManifest = {format: "hypit.module@1",name: audioTrackModuleRef.name,version: audioTrackModuleRef.version,- dependencies: [mediaDependency, narrativeDependency, semanticTrackDependency, temporalDependency, compositionDependency],+ dependencies: [mediaDependency, narrativeDependency, programSpaceDependency, semanticTrackDependency, temporalDependency, compositionDependency],types: [{ name: audioTrackTypes.header.name },{ name: audioTrackTypes.clipSpec.name },@@ -159,7 +144,7 @@ export const audioTrackManifest: ModuleManifest = {{ name: audioTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: audioTrackTypes.set }], needs: [] },{ name: audioTrackProducers.appendItem.name, inputs: [...baseInputs], outputs: [{ name: "set", type: audioTrackTypes.set }], needs: [] },{ name: audioTrackProducers.finalize.name, inputs: [{ name: "set", type: audioTrackTypes.set }, { name: "header", type: audioTrackTypes.header }], outputs: [{ name: "program", type: audioTrackTypes.program }], needs: [] },- { name: audioTrackProducers.render.name, inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: audioTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },+ { name: audioTrackProducers.render.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: audioTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },],};export const audioTrackDependency = { module: audioTrackModuleRef } as const;diff --git a/packages/audio-track/src/program.ts b/packages/audio-track/src/program.tsindex 8530d243..fba3830f 100644--- a/packages/audio-track/src/program.ts+++ b/packages/audio-track/src/program.ts@@ -9,9 +9,7 @@ import {} from "@hypit/program-space";import type { ProgramSpace } from "@hypit/program-space";import { canonicalize, isDigest } from "@hypit/protocol";-import { projectSemanticProgramSpace } from "@hypit/semantic-track";-import type { SemanticTrack } from "@hypit/semantic-track";-import { temporalDurationInSamples } from "@hypit/temporal";+import { assertTemporalWindowFor, temporalDurationInSamples } from "@hypit/temporal";import type { ProjectedWindow, TemporalDuration } from "@hypit/temporal";import type {@@ -96,16 +94,16 @@ function sourceFacts(media: SynchronizedMedia): AudioItemProgram["source"] {function realizedItems(set: AudioTrackSet,header: AudioTrackHeader,- semantic: SemanticTrack,+ space: ProgramSpace,media: SynchronizedMedia,spec: AudioClipSpec,window: ProjectedWindow,): AudioTrackSet {- const space = projectSemanticProgramSpace(semantic);assertAudioTrackSet(set);assertAudioTrackHeader(header);assertProgramSpaceIdentity(space);assertAudioClipSpec(spec);+ assertTemporalWindowFor(window, { subjectId: spec.id, space });const source = sourceFacts(media);const trimStart = spec.trim.start === undefined ? 0 : temporalDurationInSamples(spec.trim.start, space);const trimEnd = spec.trim.end === undefined ? source.sampleFrames : temporalDurationInSamples(spec.trim.end, space);@@ -131,12 +129,12 @@ function realizedItems(export function appendProjectedAudioItem(set: AudioTrackSet,header: AudioTrackHeader,- semantic: SemanticTrack,+ space: ProgramSpace,media: SynchronizedMedia,spec: AudioClipSpec,window: ProjectedWindow,): AudioTrackSet {- return realizedItems(set, header, semantic, media, spec, window);+ return realizedItems(set, header, space, media, spec, window);}function normalizeProgram(value: AudioTrackProgram): AudioTrackProgram {@@ -244,6 +242,7 @@ export function renderAudioTrack(space: ProgramSpace, program: AudioTrackProgramassertAudioTrackProgram(program);const totalSamples = programSpaceSampleFrames(space, 48_000);const track = sealAudioTrack({+ programSpaceId: space.id,id: program.id,clips: program.items.map((item) => terminalClip(item, space)),});diff --git a/packages/audio-track/src/surface.ts b/packages/audio-track/src/surface.tsindex 58700ce4..37e8b1dc 100644--- a/packages/audio-track/src/surface.ts+++ b/packages/audio-track/src/surface.ts@@ -1,15 +1,15 @@import { mediaTypes } from "@hypit/media";-import { narrativeTypes } from "@hypit/narrative";import { semanticTrackTypes } from "@hypit/semantic-track";import type {StructuredElement,StructuredSurfaceHandler,+ SurfaceComponentDraft,SurfaceRecordDraft,SurfaceResolvedReference,MarkupAttributeValue,} from "@hypit/markup";-import type { TemporalDuration, TemporalPointExpression, TemporalWindowProjection } from "@hypit/temporal";-import { temporalTypes } from "@hypit/temporal";+import type { TemporalDuration } from "@hypit/temporal";+import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";import { createAudioTrackFragment } from "./fragment.js";import { audioTrackTypes } from "./manifest.js";@@ -77,27 +77,6 @@ function duration(value: string, label: string): TemporalDuration {return { unit: "seconds", numerator: numerator / gcd, denominator: scale / gcd };}-function negate(value: TemporalDuration): TemporalDuration {- return value.unit === "seconds"- ? { ...value, numerator: -value.numerator }- : { ...value, value: -value.value };-}--function point(value: string, label: string): TemporalPointExpression {- const trimmed = value.trim();- const refs = ["program.start", "program.end", "selection.start", "selection.end", "moment.cue"] as const;- for (const ref of refs) {- if (trimmed === ref) return { ref };- const escaped = ref.replace(".", "\\.");- const match = new RegExp(`^${escaped}\\s*([+-])\\s*(.+)$`, "u").exec(trimmed);- if (match !== null) {- const offset = duration(match[2]!, `${label} offset`);- return { ref, offset: match[1] === "-" ? negate(offset) : offset };- }- }- return { ref: "absolute", at: duration(trimmed, label) };-}-function numeric(element: StructuredElement, name: string, fallback?: number): number {const raw = optionalText(element, name);if (raw === undefined && fallback !== undefined) return fallback;@@ -124,57 +103,6 @@ function occupancy(element: StructuredElement): AudioOccupancy {}}-type TemporalBinding = {- readonly kind: "program" | "selection" | "moment";- readonly projection: TemporalWindowProjection;- readonly source?: SurfaceResolvedReference;-};--function temporalBinding(- element: StructuredElement,- resolve: (path: string) => SurfaceResolvedReference | undefined,-): TemporalBinding {- const during = element.attributes.during;- const at = element.attributes.at;- const explicitStart = optionalText(element, "start");- const explicitEnd = optionalText(element, "end");- const selection = element.attributes.selection;- const moment = element.attributes.moment;- const forms = Number(during !== undefined) + Number(at !== undefined) + Number(explicitStart !== undefined || explicitEnd !== undefined);- if (forms !== 1) throw new Error(`${element.name} requires exactly one of during, at/for, or start/end.`);- if (during !== undefined) {- if (typeof during === "string") {- if (during.trim() !== "program") throw new Error(`${element.name}.during text must be program.`);- return { kind: "program", projection: { start: { ref: "program.start" }, end: { ref: "program.end" } } };- }- const source = resolved(during, `${element.name}.during`, narrativeTypes.selection, resolve);- return { kind: "selection", source, projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } } };- }- if (at !== undefined) {- const source = resolved(at, `${element.name}.at`, narrativeTypes.moment, resolve);- const forDuration = duration(text(element, "for"), `${element.name}.for`);- return { kind: "moment", source, projection: {- start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: forDuration },- } };- }- if (explicitStart === undefined || explicitEnd === undefined) throw new Error(`${element.name} explicit timing requires start and end.`);- if (selection !== undefined && moment !== undefined) throw new Error(`${element.name} cannot bind Selection and Moment together.`);- if (selection !== undefined) return {- kind: "selection",- source: resolved(selection, `${element.name}.selection`, narrativeTypes.selection, resolve),- projection: { start: point(explicitStart, `${element.name}.start`), end: point(explicitEnd, `${element.name}.end`) },- };- if (moment !== undefined) return {- kind: "moment",- source: resolved(moment, `${element.name}.moment`, narrativeTypes.moment, resolve),- projection: { start: point(explicitStart, `${element.name}.start`), end: point(explicitEnd, `${element.name}.end`) },- };- return {- kind: "program",- projection: { start: point(explicitStart, `${element.name}.start`), end: point(explicitEnd, `${element.name}.end`) },- };-}-export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {allowed(element, ["id", "semantic"]);const id = text(element, "id");@@ -186,6 +114,8 @@ export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, resvalue: { kind: "inline", value: sealAudioTrackHeader({ id }) },range: element.range,}];+ const temporalComponents: SurfaceComponentDraft[] = [];+ const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];const fragmentItems: Parameters<typeof createAudioTrackFragment>[0][number][] = [];const inputs: Record<string, { kind: "record"; id: string } | { kind: "component-output"; component: string; output: string }> = {header: { kind: "record", id: headerId },@@ -200,14 +130,17 @@ export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, resif (!child.name.endsWith(":Clip") && child.name !== "Clip") throw new Error(`${element.name} accepts only Clip children.`);if (child.children.some((node) => node.kind === "element" || node.value.trim())) throw new Error(`${child.name} must be empty.`);allowed(child, [- "id", "source", "during", "at", "for", "start", "end", "selection", "moment",+ "id", "source", ...temporalWindowAttributeNames,"trim-start", "trim-end", "playback", "min-rate", "max-rate", "gain", "fade-in", "fade-out",]);itemIndex += 1;const suffix = String(itemIndex).padStart(4, "0");const clipId = optionalText(child, "id") ?? `${id}.clip.${suffix}`;const source = resolved(child.attributes.source, `${child.name}.source`, mediaTypes.synchronized, resolveReference);- const binding = temporalBinding(child, resolveReference);+ const temporal = createTemporalWindowProjection({ id: clipId, element: child, semantic, resolveReference });+ records.push(...temporal.records);+ temporalComponents.push(...temporal.components);+ temporalFragments.push(...temporal.fragments);const playback = occupancy(child);if (playback.mode !== "stretch" && (child.attributes["min-rate"] !== undefined || child.attributes["max-rate"] !== undefined)) {throw new Error(`${child.name} rate bounds require stretch playback.`);@@ -226,35 +159,28 @@ export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, resfadeOut: duration(text(child, "fade-out", "0f"), `${child.name}.fade-out`),},});- const windowSpecName = `item-${suffix}-window-spec`;- records.push({ id: `${id}.clip.${suffix}.window`, type: temporalTypes.windowSpec,- value: { kind: "inline", value: { id: clipId, projection: binding.projection } }, range: child.range });- inputs[windowSpecName] = { kind: "record", id: `${id}.clip.${suffix}.window` };+ const windowName = `item-${suffix}-window`;+ inputs[windowName] = temporal.ref;const mediaName = `item-${suffix}-media`;const specName = `item-${suffix}-spec`;const specId = `${id}.clip.${suffix}.spec`;records.push({ id: specId, type: audioTrackTypes.clipSpec, value: { kind: "inline", value: clipSpec }, range: child.range });inputs[mediaName] = source.ref;inputs[specName] = { kind: "record", id: specId };- if (binding.kind === "program") {- fragmentItems.push({ kind: "program", mediaName, specName, windowSpecName });- } else {- const sourceName = `item-${suffix}-${binding.kind}`;- inputs[sourceName] = binding.source!.ref;- fragmentItems.push({ kind: binding.kind, mediaName, specName, sourceName, windowSpecName });- }+ fragmentItems.push({ mediaName, specName, windowName });}if (fragmentItems.length === 0) throw new Error(`${element.name} requires at least one Clip.`);const fragment = createAudioTrackFragment(fragmentItems);return {records,- components: [{+ components: [...temporalComponents, {id,fragment: fragment.id,inputs,outputs: { program: `${id}.program`, track: `${id}.track` },range: element.range,}],- fragments: [fragment],+ fragments: [...temporalFragments, fragment],+ exports: [`${id}.program`, `${id}.track`],};};diff --git a/packages/audio-track/test/audio-track.test.ts b/packages/audio-track/test/audio-track.test.tsindex c377bc01..fc01f2ad 100644--- a/packages/audio-track/test/audio-track.test.ts+++ b/packages/audio-track/test/audio-track.test.ts@@ -2,6 +2,8 @@ import assert from "node:assert/strict";import test from "node:test";import { fixtureDigest } from "../../../test/fixture-digest.js";import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";+import { projectMomentWindow, projectProgramWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";+import type { TemporalWindowProjection } from "../../../test/temporal-fixture.js";import {audioTrackManifest,@@ -30,9 +32,8 @@ import { narrativeManifest } from "@hypit/narrative";import { compileAudioProgramPlan } from "@hypit/media-pipeline";import { programSpaceDependency, programSpaceManifest, programSpaceTypes, sealProgramSpace } from "@hypit/program-space";import type { ModuleManifest } from "@hypit/protocol";-import { semanticTrackDependency, semanticTrackManifest, semanticTrackTypes } from "@hypit/semantic-track";-import { projectMomentWindow, projectProgramWindow, projectSelectionWindow, temporalProducers } from "@hypit/temporal";-import type { TemporalWindowProjection } from "@hypit/temporal";+import { projectSemanticProgramSpace, semanticTrackDependency, semanticTrackManifest, semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";+import { temporalProducers } from "@hypit/temporal";import { speechEvidenceManifest } from "@hypit/speech-evidence";import { speechManifest } from "@hypit/speech";import { spatialManifest } from "@hypit/spatial";@@ -41,7 +42,7 @@ import { MarkupSurfaceRegistry, createMarkupAuthorFrontend } from "@hypit/markupimport { createRecordAdmitter, TypeValidatorRegistry } from "@hypit/validation";import { visualIrManifest } from "@hypit/visual-ir";-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 10,frameRate: { numerator: 30, denominator: 1 },});@@ -90,7 +91,7 @@ function appendProgramAudioItem(source: SynchronizedMedia, authored: TestAudioClipSpec,): AudioTrackSet {const { projection, ...clip } = authored;- return appendProjectedAudioItem(set, trackHeader, semanticTrack, source, clip, projectProgramWindow({+ return appendProjectedAudioItem(set, trackHeader, projectSemanticProgramSpace(semanticTrack), source, clip, projectProgramWindow({itemId: clip.id, semantic: semanticTrack, projection,}));}@@ -100,7 +101,7 @@ function appendSelectionAudioItem(source: SynchronizedMedia, selection: NarrativeSelectionRef, authored: TestAudioClipSpec,): AudioTrackSet {const { projection, ...clip } = authored;- return appendProjectedAudioItem(set, trackHeader, semanticTrack, source, clip, projectSelectionWindow({+ return appendProjectedAudioItem(set, trackHeader, projectSemanticProgramSpace(semanticTrack), source, clip, projectSelectionWindow({itemId: clip.id, semantic: semanticTrack, selection, projection,}));}@@ -110,7 +111,7 @@ function appendMomentAudioItem(source: SynchronizedMedia, moment: NarrativeMomentRef, authored: TestAudioClipSpec,): AudioTrackSet {const { projection, ...clip } = authored;- return appendProjectedAudioItem(set, trackHeader, semanticTrack, source, clip, projectMomentWindow({+ return appendProjectedAudioItem(set, trackHeader, projectSemanticProgramSpace(semanticTrack), source, clip, projectMomentWindow({itemId: clip.id, semantic: semanticTrack, moment, projection,}));}@@ -188,11 +189,13 @@ test("trim and fades quantize once into the same sample domain", () => {test("Selection and Moment each place one independent item", () => {const selection: NarrativeSelectionRef = {+ narrativeId: "test-narrative",id: "mentions",startAnchorId: "a",endAnchorId: "b",};const moment: NarrativeMomentRef = {+ narrativeId: "test-narrative",id: "hits",anchorId: "c",};@@ -218,6 +221,7 @@ test("one Track with overlaps and two peer Tracks compile to the same determinisconst combined = {kind: "audio" as const,id: "combined",+ programSpaceId: space.id,clips: [{ ...first.clips[0]!, id: "a" },{ ...second.clips[0]!, id: "b" },@@ -242,12 +246,12 @@ test("one Track with overlaps and two peer Tracks compile to the same deterministest("dynamic Fragment keeps every material and temporal dependency as an explicit input", () => {const fragment = createAudioTrackFragment([- { kind: "program", mediaName: "music", specName: "music-spec", windowSpecName: "music-window-spec" },- { kind: "selection", mediaName: "voice", specName: "voice-spec", sourceName: "selection", windowSpecName: "voice-window-spec" },- { kind: "moment", mediaName: "impact", specName: "impact-spec", sourceName: "moment", windowSpecName: "impact-window-spec" },+ { mediaName: "music", specName: "music-spec", windowName: "music-window" },+ { mediaName: "voice", specName: "voice-spec", windowName: "voice-window" },+ { mediaName: "impact", specName: "impact-spec", windowName: "impact-window" },]);assert.deepEqual(fragment.inputs.map((input) => input.name), [- "header", "impact", "impact-spec", "impact-window-spec", "moment", "music", "music-spec", "music-window-spec", "selection", "semantic", "voice", "voice-spec", "voice-window-spec",+ "header", "impact", "impact-spec", "impact-window", "music", "music-spec", "music-window", "semantic", "voice", "voice-spec", "voice-window",]);assert.equal(fragment.exports[1]?.name, "track");});@@ -332,7 +336,10 @@ test("the self-described Audio Surface parses into the same finite Producer grapaudioTrackProducers.createSet.name,audioTrackProducers.appendItem.name,audioTrackProducers.finalize.name,- temporalProducers.projectProgram.name,+ temporalProducers.projectProgramInstant.name,+ temporalProducers.projectProgramInstant.name,+ temporalProducers.composeWindow.name,+ semanticTrackProducers.projectProgramSpace.name,audioTrackProducers.render.name,].sort());});diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.mdindex e4403206..6a3ada39 100644--- a/packages/caption-fine/README.md+++ b/packages/caption-fine/README.md@@ -21,6 +21,10 @@ Caption first projects authored Script units onto semantic Word timing. Fine theexplicit visible Schedule and renders that Schedule. Lead and tail never change the semantic Wordtimes used by Karaoke.+The Fine Schedule preserves the Caption projection's ProgramSpace, Narrative and document identities.+The renderer rejects any mismatched Space or document. Studio may expose lead, tail and handoff as+ordinary parameter edits, but Cue rectangles remain read-only semantic evidence.+Cue grouping is authored by Script segments, turns, Style changes and `||`; it is not delegated toan LLM. Fine rejects word-specific Style runs. A caption whose Cue contains structural roles orrelationships—an emphasis group with another font and layout, alternating full-frame inversion, ordiff --git a/packages/caption-fine/src/component.ts b/packages/caption-fine/src/component.tsindex a2aca67e..538f6ed7 100644--- a/packages/caption-fine/src/component.ts+++ b/packages/caption-fine/src/component.ts@@ -1,8 +1,7 @@import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";import type { ComponentPackage } from "@hypit/component-kit";import type { CaptionDocument } from "@hypit/narrative";-import { projectSemanticProgramSpace } from "@hypit/semantic-track";-import type { SemanticTrack } from "@hypit/semantic-track";+import type { ProgramSpace } from "@hypit/program-space";import type { StoredValue } from "@hypit/protocol";import { canonicalize } from "@hypit/protocol";@@ -36,7 +35,7 @@ export const captionFineComponent = {inline<FineCaptionSchedule>(inputs.schedule?.value, "FineCaptionSchedule"),inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),)) } },needs: {},}),diff --git a/packages/caption-fine/src/fragment.ts b/packages/caption-fine/src/fragment.tsindex 6dc48cc9..a0c11ad6 100644--- a/packages/caption-fine/src/fragment.ts+++ b/packages/caption-fine/src/fragment.ts@@ -2,7 +2,7 @@ import { captionProducers, captionTypes } from "@hypit/caption";import { compositionTypes } from "@hypit/composition";import { sealGraphFragment } from "@hypit/elaborator";import { narrativeTypes } from "@hypit/narrative";-import { semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { captionFineProducers, captionFineTypes } from "./manifest.js";@@ -17,6 +17,12 @@ export const fineCaptionTrackFragment = sealGraphFragment({{ name: "program", type: captionTypes.program },],operations: [+ {+ id: "caption:space",+ producer: semanticTrackProducers.projectProgramSpace,+ inputs: { track: input("semantic") },+ result: { kind: "output", name: "space" },+ },{id: "caption:temporalize-document",producer: captionProducers.temporalizeDocument,@@ -38,7 +44,7 @@ export const fineCaptionTrackFragment = sealGraphFragment({producer: captionFineProducers.render,inputs: {schedule: operation("caption-fine:schedule"), program: input("program"),- document: input("document"), semantic: input("semantic"),+ document: input("document"), space: operation("caption:space"),},result: { kind: "output", name: "track" },},diff --git a/packages/caption-fine/src/manifest.ts b/packages/caption-fine/src/manifest.tsindex 78e46725..22bd91e4 100644--- a/packages/caption-fine/src/manifest.ts+++ b/packages/caption-fine/src/manifest.ts@@ -4,6 +4,7 @@ import { captionManifest, captionModuleRef, captionTypes } from "@hypit/caption"import { compositionDependency, compositionTypes } from "@hypit/composition";import { mediaDependency, mediaTypes } from "@hypit/media";import { narrativeDependency, narrativeTypes } from "@hypit/narrative";+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";import type { ModuleManifest, ProducerRef } from "@hypit/protocol";import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";import { svsRecipeType } from "@hypit/svs";@@ -332,6 +333,7 @@ export const captionFineManifest: ModuleManifest = {compositionDependency,mediaDependency,narrativeDependency,+ programSpaceDependency,semanticTrackDependency,],types: [{ name: captionFineTypes.schedule.name }],@@ -353,7 +355,7 @@ export const captionFineManifest: ModuleManifest = {{ name: "schedule", type: captionFineTypes.schedule },{ name: "program", type: captionTypes.program },{ name: "document", type: narrativeTypes.captionDocument },- { name: "semantic", type: semanticTrackTypes.track },+ { name: "space", type: programSpaceTypes.programSpace },],outputs: [{ name: "track", type: compositionTypes.visualTrack }],needs: [],diff --git a/packages/caption-fine/src/render.ts b/packages/caption-fine/src/render.tsindex 366d6fc2..31e94f7a 100644--- a/packages/caption-fine/src/render.ts+++ b/packages/caption-fine/src/render.ts@@ -877,6 +877,10 @@ export function renderFineCaption(throw new Error("Fine Caption accepts one uniform token rule and cannot consume word-specific Style runs");}assertProgramSpaceIdentity(space);+ if (schedule.spaceId !== space.id || schedule.narrativeId !== space.narrativeId+ || document.narrativeId !== space.narrativeId) {+ throw new Error("Fine Caption inputs belong to different ProgramSpaces or Narratives");+ }const styles = new Map(program.styles.map((style) => [style.id, style]));const wordText = new Map(document.words.map((word) => [word.id, word.text]));const atomById = new Map(document.units.map((atom) => [atom.id, atom]));@@ -911,6 +915,7 @@ export function renderFineCaption(}];});const track = sealVisualTrack({+ programSpaceId: space.id,visualIr: "hypit.visual-ir@1",id: program.id,presents,diff --git a/packages/caption-fine/src/schedule.ts b/packages/caption-fine/src/schedule.tsindex 900b0c89..4d5f207f 100644--- a/packages/caption-fine/src/schedule.ts+++ b/packages/caption-fine/src/schedule.ts@@ -24,6 +24,9 @@ export function scheduleFineCaption(assertTimedCaptionProjection(projection);assertCaptionProgramForDocument(program, document);if (projection.documentId !== document.id) throw new Error("Fine Caption Schedule received another CaptionDocument");+ if (projection.narrativeId !== document.narrativeId) {+ throw new Error("Fine Caption Schedule received a CaptionDocument from another Narrative");+ }if (program.wordRuns.length !== 0) {throw new Error("Fine Caption accepts one uniform token rule and cannot consume word-specific Style runs");}@@ -89,11 +92,18 @@ export function scheduleFineCaption(throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);}}- return { documentId: document.id, cues };+ return {+ spaceId: projection.spaceId,+ narrativeId: projection.narrativeId,+ documentId: document.id,+ cues,+ };}export function assertFineCaptionSchedule(value: FineCaptionSchedule): void {- if (!value.documentId) throw new Error("Fine Caption Schedule document identity is empty");+ if (!value.spaceId || !value.narrativeId || !value.documentId) {+ throw new Error("Fine Caption Schedule provenance is empty");+ }const ids = new Set<string>();for (const cue of value.cues) {if (!cue.id || !cue.styleId || ids.has(cue.id) || cue.units.length === 0) {diff --git a/packages/caption-fine/src/types.ts b/packages/caption-fine/src/types.tsindex 2d4b87de..c1cd3104 100644--- a/packages/caption-fine/src/types.ts+++ b/packages/caption-fine/src/types.ts@@ -184,6 +184,8 @@ export type FineCaptionScheduledCue = {/** Explicit projection consumed by the Fine renderer. */export type FineCaptionSchedule = {+ readonly spaceId: string;+ readonly narrativeId: string;readonly documentId: string;readonly cues: readonly FineCaptionScheduledCue[];};diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.tsindex fb0601f1..72deaf6f 100644--- a/packages/caption-fine/test/caption-fine.test.ts+++ b/packages/caption-fine/test/caption-fine.test.ts@@ -65,7 +65,7 @@ const recipe: SvsRecipe = {function fixture() {const parsed = parseScript("caption-fine.svml", "<line>one two || three four</line>");- const document = captionDocument(parsed, "story.caption");+ const document = captionDocument(parsed, "story.caption", "story");const style = fineCaptionStyle("plain", recipe, [font]);const program: CaptionProgram = {id: "captions",@@ -78,6 +78,8 @@ function fixture() {const [first, second, third, fourth] = document.units;assert.ok(first && second && third && fourth);const projection: TimedCaptionProjection = {+ spaceId: "test-space",+ narrativeId: "story",documentId: document.id,cues: [{@@ -124,7 +126,7 @@ test("Fine Caption schedules visibility outside semantic Word timing and cuts on]);const track = renderFineCaption(schedule, program, document,- sealProgramSpace({ durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));+ sealProgramSpace({ id: "test-space", narrativeId: "story", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));assert.deepEqual(track.presents.map((present) => present.span), [{ startFrame: 6, endFrameExclusive: 36 },{ startFrame: 36, endFrameExclusive: 62 },diff --git a/packages/caption/README.md b/packages/caption/README.mdindex 2467be14..f8859e1a 100644--- a/packages/caption/README.md+++ b/packages/caption/README.md@@ -17,3 +17,8 @@ to complete alignment units before timing; a Selection that cuts through an N:MScript-native word attributes are resolved separately as local word Style runs and do not createanother timing source. They are part of the common Caption contract for structural Caption families;`@hypit/caption-fine` deliberately rejects them because Fine requires one uniform token rule per Cue.++`TimedCaptionProjection` is intentionally not a `TemporalWindow` collection. Cue timing is a+read-only projection of token evidence, not an author-controlled placement window. It nevertheless+carries the exact `spaceId`, `narrativeId` and `documentId`, so another SemanticTrack or Script cannot+be substituted silently.diff --git a/packages/caption/src/manifest.ts b/packages/caption/src/manifest.tsindex 270b63f2..f6e41408 100644--- a/packages/caption/src/manifest.ts+++ b/packages/caption/src/manifest.ts@@ -35,6 +35,8 @@ export const captionProgramSchema: ValueSchema = object({});const timedUnit = object({ unitId: { schema: string }, startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });export const timedCaptionProjectionSchema: ValueSchema = object({+ spaceId: { schema: string },+ narrativeId: { schema: string },documentId: { schema: string },cues: { schema: { kind: "array", items: object({id: { schema: string }, styleId: { schema: string }, startFrame: { schema: integer }, endFrameExclusive: { schema: integer },diff --git a/packages/caption/src/temporalize.ts b/packages/caption/src/temporalize.tsindex e0ecc24a..05befba6 100644--- a/packages/caption/src/temporalize.ts+++ b/packages/caption/src/temporalize.ts@@ -1,5 +1,5 @@import type { CaptionDocument } from "@hypit/narrative";-import { tokenFrameSpan } from "@hypit/semantic-track";+import { projectSemanticProgramSpace, tokenFrameSpan } from "@hypit/semantic-track";import type { SemanticTrack } from "@hypit/semantic-track";import { CaptionTimingError } from "./error.js";@@ -14,6 +14,10 @@ export function temporalizeCaptionDocument(): TimedCaptionProjection {assertCaptionDocument(document);assertCaptionProgramForDocument(program, document);+ const space = projectSemanticProgramSpace(semantic);+ if (document.narrativeId !== space.narrativeId) {+ throw new CaptionTimingError("CAPTION_NARRATIVE", "CaptionDocument and SemanticTrack belong to different Narratives.");+ }const styleByUnit = new Map(program.runs.flatMap((run) => run.unitIds.map((unitId) => [unitId, run.styleId] as const)));const muted = new Set(program.mutedUnitIds);const breaks = new Set(document.cueBreaks.map((cueBreak) => cueBreak.afterUnitId));@@ -24,8 +28,11 @@ export function temporalizeCaptionDocument(if (styleId === undefined) throw new CaptionTimingError("CAPTION_UNIT", `Caption unit ${unit.id} has no Style.`);const window = tokenFrameSpan(semantic, unit.sourceTokenIds);if (window === undefined) throw new CaptionTimingError("CAPTION_SPEECH_COVERAGE", `Caption unit ${unit.id} is absent from the SemanticTrack.`);- const startFrame = Math.min(window.startFrame, window.endFrameExclusive);- const endFrameExclusive = Math.max(startFrame + 1, window.startFrame, window.endFrameExclusive);+ if (window.endFrameExclusive < window.startFrame) {+ throw new CaptionTimingError("CAPTION_SPEECH_ORDER", `Caption unit ${unit.id} references speech Tokens in reverse order.`);+ }+ const startFrame = window.startFrame;+ const endFrameExclusive = Math.max(startFrame + 1, window.endFrameExclusive);timed.push({ unit, styleId, timing: { unitId: unit.id, startFrame, endFrameExclusive } });}const cues: TimedCaptionCue[] = [];@@ -59,7 +66,12 @@ export function temporalizeCaptionDocument(current.units.push(entry.timing);}flush();- const result: TimedCaptionProjection = { documentId: document.id, cues };+ const result: TimedCaptionProjection = {+ spaceId: space.id,+ narrativeId: space.narrativeId,+ documentId: document.id,+ cues,+ };assertTimedCaptionProjection(result);return result;}@@ -71,20 +83,29 @@ export function applyCaptionMute(): TimedCaptionProjection {assertCaptionDocument(document);assertCaptionProgramForDocument(program, document);- if (projection.documentId !== document.id) throw new Error("Caption Mute received another CaptionDocument");+ if (projection.documentId !== document.id || projection.narrativeId !== document.narrativeId) {+ throw new Error("Caption Mute received another CaptionDocument or Narrative");+ }const muted = new Set(program.mutedUnitIds);const cues = projection.cues.flatMap((cue) => {const units = cue.units.filter((unit) => !muted.has(unit.unitId));if (units.length === 0) return [];return [{ ...cue, units, startFrame: units[0]!.startFrame, endFrameExclusive: units.at(-1)!.endFrameExclusive }];});- const result = { documentId: projection.documentId, cues };+ const result = {+ spaceId: projection.spaceId,+ narrativeId: projection.narrativeId,+ documentId: projection.documentId,+ cues,+ };assertTimedCaptionProjection(result);return result;}export function assertTimedCaptionProjection(projection: TimedCaptionProjection): void {- if (projection.documentId.length === 0) throw new Error("TimedCaptionProjection document identity is invalid");+ if (projection.spaceId.length === 0 || projection.narrativeId.length === 0 || projection.documentId.length === 0) {+ throw new Error("TimedCaptionProjection provenance is invalid");+ }const cueIds = new Set<string>();const unitIds = new Set<string>();for (const cue of projection.cues) {diff --git a/packages/caption/src/types.ts b/packages/caption/src/types.tsindex 719d9b82..5af696ae 100644--- a/packages/caption/src/types.ts+++ b/packages/caption/src/types.ts@@ -63,6 +63,9 @@ export type TimedCaptionCue = {};export type TimedCaptionProjection = {+ /** Semantic ProgramSpace from which every unit frame was measured. */+ readonly spaceId: string;+ readonly narrativeId: string;readonly documentId: string;readonly cues: readonly TimedCaptionCue[];};diff --git a/packages/caption/test/caption.test.ts b/packages/caption/test/caption.test.tsindex 2f79a73f..0672b9db 100644--- a/packages/caption/test/caption.test.ts+++ b/packages/caption/test/caption.test.ts@@ -13,8 +13,8 @@ import type { Narrative } from "@hypit/narrative";test("Caption uses complete semantic selections and authored cue breaks", () => {const parsed = parseScript("caption.svml", "<line>one @focus two three @/focus || four</line>");- const narrative = narrativeValue(parsed) as unknown as Narrative;- const document = captionDocument(parsed, "story.caption");+ const narrative = narrativeValue(parsed, "story") as unknown as Narrative;+ const document = captionDocument(parsed, "story.caption", "story");const selection = narrative.selections[0]!;const subset = captionUnitsForSelection(document, narrative, selection);assert.equal(subset.unitIds.length, 2);@@ -26,8 +26,8 @@ test("Caption uses complete semantic selections and authored cue breaks", () =>test("Caption keeps Selection styles and adds flat word-attribute styles separately", () => {const parsed = parseScript("caption-attributes.svml", "<line>@focus really{emphasis} matters @/focus</line>");- const narrative = narrativeValue(parsed) as unknown as Narrative;- const document = captionDocument(parsed, "story.caption");+ const narrative = narrativeValue(parsed, "story") as unknown as Narrative;+ const document = captionDocument(parsed, "story.caption", "story");const plain = sealCaptionStyle({ id: "plain", rendering: { family: "test", parameters: canonicalize({ level: "plain" }) } });const emphasis = sealCaptionStyle({ id: "emphasis", rendering: { family: "test", parameters: canonicalize({ level: "emphasis" }) } });const selection = narrative.selections[0]!;diff --git a/packages/comment-sticker/package.json b/packages/comment-sticker/package.jsonindex 9692d8bd..22263cec 100644--- a/packages/comment-sticker/package.json+++ b/packages/comment-sticker/package.json@@ -19,6 +19,7 @@"@hypit/spatial": "workspace:*","@hypit/svs": "workspace:*","@hypit/temporal": "workspace:*",+ "@hypit/temporal-markup": "workspace:*","@hypit/text": "workspace:*","@hypit/markup": "workspace:*"},diff --git a/packages/comment-sticker/src/component.ts b/packages/comment-sticker/src/component.tsindex 7866cb2d..75388761 100644--- a/packages/comment-sticker/src/component.ts+++ b/packages/comment-sticker/src/component.ts@@ -1,8 +1,7 @@import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";import { canonicalize } from "@hypit/protocol";import type { BlobRef, StoredValue } from "@hypit/protocol";-import type { SemanticTrack } from "@hypit/semantic-track";-import { projectSemanticProgramSpace } from "@hypit/semantic-track";+import type { ProgramSpace } from "@hypit/program-space";import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";import type { Text } from "@hypit/text";@@ -29,9 +28,9 @@ function common(inputs: Record<string, { readonly value: StoredValue } | undefinreturn {set: inline<CommentStickerSet>(inputs.set?.value, "CommentStickerSet"),header: inline<CommentStickerHeader>(inputs.header?.value, "CommentStickerHeader"),+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),style: inline<CommentStickerStyle>(inputs.style?.value, "CommentStickerStyle"),- semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),spec: inline<CommentStickerItemSpec>(inputs.spec?.value, "CommentStickerItemSpec"),content: inline<CommentStickerContent>(inputs.content?.value, "CommentStickerContent"),window: inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),@@ -70,8 +69,8 @@ export const commentStickerComponent = {handler: ({ inputs }: ProducerHandlerContext) => {const values = common(inputs);return { outputs: { set: output(appendProjectedCommentSticker(- values.set, values.header, values.frame, values.style, values.spec, values.content, values.window,- ...(avatar ? [inline<BlobRef>(inputs.avatar?.value, "Comment Sticker avatar")] : []),+ values.set, values.header, values.space, values.frame, values.style, values.spec, values.content, values.window,+ avatar ? inline<BlobRef>(inputs.avatar?.value, "Comment Sticker avatar") : undefined,)) }, needs: {} };},})),@@ -86,7 +85,7 @@ export const commentStickerComponent = {producer: commentStickerProducers.render,handler: ({ inputs }) => ({ outputs: { track: output(renderCommentSticker(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),inline<CommentStickerProgram>(inputs.program?.value, "CommentStickerProgram"),)) }, needs: {} }),},diff --git a/packages/comment-sticker/src/fragment.ts b/packages/comment-sticker/src/fragment.tsindex 383ba6a0..452b4a8f 100644--- a/packages/comment-sticker/src/fragment.ts+++ b/packages/comment-sticker/src/fragment.ts@@ -2,22 +2,16 @@ import { artifactTypes } from "@hypit/artifact";import { compositionTypes } from "@hypit/composition";import { sealGraphFragment } from "@hypit/elaborator";import type { FragmentOperation } from "@hypit/elaborator";-import { narrativeTypes } from "@hypit/narrative";import type { TypeRef } from "@hypit/protocol";-import { semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { textTypes } from "@hypit/text";-import { temporalProducers, temporalTypes } from "@hypit/temporal";+import { temporalTypes } from "@hypit/temporal";import { commentStickerProducers, commentStickerTypes } from "./manifest.js";-type TimedItem =- | { readonly kind: "program" }- | { readonly kind: "selection"; readonly sourceName: string }- | { readonly kind: "moment"; readonly sourceName: string };--export type CommentStickerFragmentItem = TimedItem & {- readonly windowSpecName: string;+export type CommentStickerFragmentItem = {+ readonly windowName: string;readonly specName: string;readonly frameName: string;readonly styleName: string;@@ -38,16 +32,24 @@ function appendProducer(item: CommentStickerFragmentItem) {export function createCommentStickerFragment(items: readonly CommentStickerFragmentItem[]) {if (items.length === 0) throw new Error("Comment Sticker Fragment requires at least one Item.");const types = new Map<string, TypeRef>();- const operations: FragmentOperation[] = [{- id: "comment:set:empty",- producer: commentStickerProducers.createSet,- inputs: {},- result: { kind: "output", name: "set" },- }];+ const operations: FragmentOperation[] = [+ {+ id: "comment:space",+ producer: semanticTrackProducers.projectProgramSpace,+ inputs: { track: input("semantic") },+ result: { kind: "output", name: "space" },+ },+ {+ id: "comment:set:empty",+ producer: commentStickerProducers.createSet,+ inputs: {},+ result: { kind: "output", name: "set" },+ },+ ];let current = "comment:set:empty";items.forEach((item, index) => {types.set(item.specName, commentStickerTypes.itemSpec);- types.set(item.windowSpecName, temporalTypes.windowSpec);+ types.set(item.windowName, temporalTypes.window);types.set(item.frameName, spatialTypes.frame);types.set(item.styleName, commentStickerTypes.style);types.set(item.commentName, textTypes.text);@@ -55,9 +57,6 @@ export function createCommentStickerFragment(items: readonly CommentStickerFragmif (item.headerTextName !== undefined) types.set(item.headerTextName, textTypes.text);if (item.metaName !== undefined) types.set(item.metaName, textTypes.text);if (item.avatarName !== undefined) types.set(item.avatarName, artifactTypes.blob);- if (item.kind !== "program") {- types.set(item.sourceName, item.kind === "selection" ? narrativeTypes.selection : narrativeTypes.moment);- }const suffix = String(index + 1).padStart(4, "0");const createContentId = `comment:content:${suffix}:create`;operations.push({@@ -83,22 +82,16 @@ export function createCommentStickerFragment(items: readonly CommentStickerFragmcontent = operation(fieldId);}const id = `comment:set:append:${suffix}`;- const windowId = `comment:window:${suffix}`;- const windowProducer = item.kind === "program" ? temporalProducers.projectProgram- : item.kind === "selection" ? temporalProducers.projectSelection : temporalProducers.projectMoment;- operations.push({ id: windowId, producer: windowProducer, inputs: {- semantic: input("semantic"), spec: input(item.windowSpecName),- ...(item.kind === "program" ? {} : { [item.kind]: input(item.sourceName) }),- }, result: { kind: "output", name: "window" } });operations.push({id,producer: appendProducer(item),inputs: {set: operation(current),header: input("header"),+ space: operation("comment:space"),frame: input(item.frameName),style: input(item.styleName),- semantic: input("semantic"), window: operation(windowId),+ window: input(item.windowName),spec: input(item.specName),content,...(item.avatarName === undefined ? {} : { avatar: input(item.avatarName) }),@@ -117,7 +110,7 @@ export function createCommentStickerFragment(items: readonly CommentStickerFragm{id: "comment:track",producer: commentStickerProducers.render,- inputs: { canvas: input("canvas"), semantic: input("semantic"), program: operation("comment:program") },+ inputs: { canvas: input("canvas"), space: operation("comment:space"), program: operation("comment:program") },result: { kind: "output", name: "track" },},);diff --git a/packages/comment-sticker/src/manifest.ts b/packages/comment-sticker/src/manifest.tsindex e9e4f04f..911b9d7d 100644--- a/packages/comment-sticker/src/manifest.ts+++ b/packages/comment-sticker/src/manifest.ts@@ -3,12 +3,14 @@ import { readFile } from "node:fs/promises";import { artifactDependency, artifactTypes } from "@hypit/artifact";import { compositionDependency, compositionTypes } from "@hypit/composition";import { fontArtifactSchema, mediaDependency, mediaTypes } from "@hypit/media";-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";+import { narrativeDependency } from "@hypit/narrative";+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";import { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import { temporalDependency, temporalTypes } from "@hypit/temporal";+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";import { textDependency, textTypes } from "@hypit/text";const previewImage = (file: string) => ({@@ -131,8 +133,9 @@ export const commentStickerProgramSchema: ValueSchema = object({});const appendInputs = [{ name: "set", type: commentStickerTypes.set }, { name: "header", type: commentStickerTypes.header },+ { name: "space", type: programSpaceTypes.programSpace },{ name: "frame", type: spatialTypes.frame }, { name: "style", type: commentStickerTypes.style },- { name: "semantic", type: semanticTrackTypes.track }, { name: "spec", type: commentStickerTypes.itemSpec },+ { name: "spec", type: commentStickerTypes.itemSpec },{ name: "content", type: commentStickerTypes.content }, { name: "window", type: temporalTypes.window },] as const;@@ -263,7 +266,7 @@ export const commentStickerMarkupSurfaces = [],},},- { name: "track", tag: "Track", mode: "structured", outputs: [textTypes.text, commentStickerTypes.header, commentStickerTypes.itemSpec, temporalTypes.windowSpec, commentStickerTypes.program, compositionTypes.visualTrack],+ { name: "track", tag: "Track", mode: "structured", outputs: [textTypes.text, commentStickerTypes.header, commentStickerTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, commentStickerTypes.program, compositionTypes.visualTrack],vocabulary: {summary: "Places social comment cards over the Program and renders them as one self-contained VisualTrack.",appearance: "One rounded card per Sticker, tilted a couple of degrees and lifted on a soft drop shadow, drawn at the place and size its Frame gives it on the Canvas, with a small triangular speech tail hanging from the card's lower edge. Inside the card a circular avatar sits at the left — the supplied image Artifact, or a filled disc bearing the author's initial — and a text column runs beside it from top to bottom: a small faint header line such as `Reply to @viewer's comment`, then the comment copy in large heavy type wrapped to a few lines and ellipsized, then a small faint metadata row pinned to the card's bottom edge when one is supplied. Each card keeps its own window rather than a shared one: it pops in scaling up and unwinding its tilt, rises and rocks gently while it holds, then fades upward as it leaves. Cards are placed by their Frames alone, so several stand on screen at once and none reflows around another.",@@ -296,20 +299,7 @@ export const commentStickerMarkupSurfaces = [summary: "Supplies the card's metadata row, which is not rendered when it is absent." },{ name: "avatar", kind: "reference", required: false, accepts: [artifactTypes.blob],summary: "Supplies the image Artifact drawn as the commenter's avatar." },- { name: "during", kind: "expression", required: false, values: ["program"], accepts: [narrativeTypes.selection],- summary: "Spans the whole Program when written as `program`, or the referenced Selection." },- { name: "at", kind: "reference", required: false, accepts: [narrativeTypes.moment],- summary: "Opens the card's window at the referenced Moment's cue." },- { name: "for", kind: "literal", required: false,- summary: "Sets the length of a Moment window as an exact duration such as `48f`, `240ms` or `2.5s`." },- { name: "start", kind: "literal", required: false,- summary: "Opens the window at `program.start`, `program.end`, `selection.start`, `selection.end` or `moment.cue` with an optional `+` or `-` duration offset, or at a bare duration measured from the start of the Program." },- { name: "end", kind: "literal", required: false,- summary: "Closes the window at `program.start`, `program.end`, `selection.start`, `selection.end` or `moment.cue` with an optional `+` or `-` duration offset, or at a bare duration measured from the start of the Program." },- { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection],- summary: "Resolves `selection.start` and `selection.end` in an explicit start and end window." },- { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment],- summary: "Resolves `moment.cue` in an explicit start and end window." },+ ...temporalWindowAttributeVocabulary,],text: "The card's comment copy, read when `comment` is absent.",},@@ -344,7 +334,7 @@ export const commentStickerManifest: ModuleManifest = {format: "hypit.module@1",name: commentStickerModuleRef.name,version: commentStickerModuleRef.version,- dependencies: [artifactDependency, narrativeDependency, semanticTrackDependency, spatialDependency, temporalDependency, mediaDependency, compositionDependency, textDependency],+ dependencies: [artifactDependency, narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, mediaDependency, compositionDependency, textDependency],types: [{ name: commentStickerTypes.header.name },{ name: commentStickerTypes.style.name },@@ -376,7 +366,7 @@ export const commentStickerManifest: ModuleManifest = {needs: [],})),{ name: commentStickerProducers.finalize.name, inputs: [{ name: "set", type: commentStickerTypes.set }, { name: "header", type: commentStickerTypes.header }], outputs: [{ name: "program", type: commentStickerTypes.program }], needs: [] },- { name: commentStickerProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: commentStickerTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },+ { name: commentStickerProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: commentStickerTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },],};diff --git a/packages/comment-sticker/src/program.ts b/packages/comment-sticker/src/program.tsindex 9b753ad4..f26cd570 100644--- a/packages/comment-sticker/src/program.ts+++ b/packages/comment-sticker/src/program.ts@@ -17,6 +17,7 @@ import { canonicalize, isDigest } from "@hypit/protocol";import type { BlobRef } from "@hypit/protocol";import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";+import { assertTemporalWindowFor } from "@hypit/temporal";import type { ProjectedWindow } from "@hypit/temporal";import { verifyText } from "@hypit/text";import type { Text } from "@hypit/text";@@ -194,6 +195,7 @@ export function assertCommentStickerSet(value: CommentStickerSet): void {function realized(set: CommentStickerSet,header: CommentStickerHeader,+ space: ProgramSpace,frame: SpatialFrame,style: CommentStickerStyle,spec: CommentStickerItemSpec,@@ -227,6 +229,7 @@ function realized(export function appendProjectedCommentSticker(set: CommentStickerSet,header: CommentStickerHeader,+ space: ProgramSpace,frame: SpatialFrame,style: CommentStickerStyle,spec: CommentStickerItemSpec,@@ -234,7 +237,8 @@ export function appendProjectedCommentSticker(window: ProjectedWindow,avatar?: BlobRef,): CommentStickerSet {- return realized(set, header, frame, style, spec, content, window, avatar);+ assertTemporalWindowFor(window, { subjectId: spec.id, space });+ return realized(set, header, space, frame, style, spec, content, window, avatar);}export function assertCommentStickerProgram(value: CommentStickerProgram): void {@@ -590,6 +594,7 @@ export function renderCommentSticker(canvas: CanvasSpace, space: ProgramSpace, passertProgramSpaceIdentity(space);assertCommentStickerProgram(program);const track = sealVisualTrack({+ programSpaceId: space.id,visualIr: "hypit.visual-ir@1",id: program.id,presents: program.items.map((item) => ({diff --git a/packages/comment-sticker/src/surface.ts b/packages/comment-sticker/src/surface.tsindex 87866e8b..2cc2e31d 100644--- a/packages/comment-sticker/src/surface.ts+++ b/packages/comment-sticker/src/surface.ts@@ -1,7 +1,6 @@import { artifactTypes } from "@hypit/artifact";import { mediaTypes } from "@hypit/media";import type { FontStackRef } from "@hypit/media";-import { narrativeTypes } from "@hypit/narrative";import { semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";@@ -10,19 +9,19 @@ import { sealText, textTypes } from "@hypit/text";import type {StructuredElement,StructuredSurfaceHandler,+ SurfaceComponentDraft,SurfaceRecordDraft,SurfaceResolvedReference,MarkupAttributeValue,} from "@hypit/markup";-import type { TemporalDuration, TemporalPointExpression, TemporalWindowProjection } from "@hypit/temporal";-import { temporalTypes } from "@hypit/temporal";+import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";import { decodeCommentStickerStyle } from "./author.js";import { createCommentStickerFragment } from "./fragment.js";import { commentStickerTypes } from "./manifest.js";import { sealCommentStickerHeader, sealCommentStickerItemSpec } from "./program.js";-const TIMING = ["during", "at", "for", "start", "end", "selection", "moment"] as const;+const TIMING = temporalWindowAttributeNames;function localName(name: string): string { return name.slice(name.lastIndexOf(":") + 1); }function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {@@ -61,80 +60,6 @@ function inline<T>(value: SurfaceResolvedReference, label: string): T {if (value.record?.value.kind !== "inline") throw new Error(`${label} must reference authored inline data.`);return value.record.value.value as unknown as T;}-function gcd(left: number, right: number): number {- let a = Math.abs(left); let b = Math.abs(right);- while (b !== 0) [a, b] = [b, a % b];- return a;-}-function duration(value: string, label: string): TemporalDuration {- const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());- if (!match) throw new Error(`${label} must be an exact duration.`);- const whole = Number(match[1]); const fraction = match[2] ?? ""; const unit = match[3];- if (unit === "f" || unit === "ms") {- if (fraction) throw new Error(`${label} ${unit} duration must be integral.`);- return { unit: unit === "f" ? "frames" : "milliseconds", value: whole };- }- const scale = 10 ** fraction.length;- const numerator = whole * scale + (fraction ? Number(fraction) : 0);- const divisor = gcd(numerator, scale);- return { unit: "seconds", numerator: numerator / divisor, denominator: scale / divisor };-}-function negate(value: TemporalDuration): TemporalDuration {- return value.unit === "seconds" ? { ...value, numerator: -value.numerator } : { ...value, value: -value.value };-}-function point(value: string, label: string): TemporalPointExpression {- const trimmed = value.trim();- const refs = ["program.start", "program.end", "selection.start", "selection.end", "moment.cue"] as const;- for (const target of refs) {- if (trimmed === target) return { ref: target };- const match = new RegExp(`^${target.replace(".", "\\.")}\\s*([+-])\\s*(.+)$`, "u").exec(trimmed);- if (match) {- const offset = duration(match[2]!, `${label} offset`);- return { ref: target, offset: match[1] === "-" ? negate(offset) : offset };- }- }- return { ref: "absolute", at: duration(trimmed, label) };-}--type Binding = {- readonly kind: "program" | "selection" | "moment";- readonly projection: TemporalWindowProjection;- readonly source?: SurfaceResolvedReference;-};--function binding(element: StructuredElement, resolve: (path: string) => SurfaceResolvedReference | undefined): Binding {- const during = element.attributes.during; const at = element.attributes.at;- const start = optionalText(element, "start"); const end = optionalText(element, "end");- const forms = Number(during !== undefined) + Number(at !== undefined) + Number(start !== undefined || end !== undefined);- if (forms !== 1) throw new Error(`${element.name} requires exactly one temporal form.`);- if (during !== undefined) {- if (typeof during === "string") {- if (during.trim() !== "program") throw new Error(`${element.name}.during text must be program.`);- return { kind: "program", projection: { start: { ref: "program.start" }, end: { ref: "program.end" } } };- }- return {- kind: "selection",- source: reference(during, `${element.name}.during`, narrativeTypes.selection, resolve),- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },- };- }- if (at !== undefined) return {- kind: "moment",- source: reference(at, `${element.name}.at`, narrativeTypes.moment, resolve),- projection: {- start: { ref: "moment.cue" },- end: { ref: "moment.cue", offset: duration(text(element, "for"), `${element.name}.for`) },- },- };- if (start === undefined || end === undefined) throw new Error(`${element.name} explicit timing requires start and end.`);- const selection = element.attributes.selection; const moment = element.attributes.moment;- if (selection !== undefined && moment !== undefined) throw new Error(`${element.name} cannot bind Selection and Moment together.`);- const projection = { start: point(start, `${element.name}.start`), end: point(end, `${element.name}.end`) };- if (selection !== undefined) return { kind: "selection", source: reference(selection, `${element.name}.selection`, narrativeTypes.selection, resolve), projection };- if (moment !== undefined) return { kind: "moment", source: reference(moment, `${element.name}.moment`, narrativeTypes.moment, resolve), projection };- return { kind: "program", projection };-}-function dedent(value: string): string {const lines = value.replace(/^\n/u, "").replace(/\n\s*$/u, "").split("\n");const indentation = lines.filter((line) => line.trim()).reduce(@@ -174,6 +99,8 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ elevalue: { kind: "inline", value: sealCommentStickerHeader({ id }) },range: element.range,}];+ const temporalComponents: SurfaceComponentDraft[] = [];+ const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, semantic: semantic.ref };const items: Parameters<typeof createCommentStickerFragment>[0][number][] = [];for (const child of element.children) {@@ -184,7 +111,9 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ eleif (localName(child.name) !== "Sticker") throw new Error(`${element.name} accepts only Sticker children.`);if (child.children.some((node) => node.kind === "element")) throw new Error(`${child.name} accepts plain comment text only.`);allowed(child, ["id", "comment", "frame", "style", "avatar", "author", "header", "meta", ...TIMING], ["id", "frame", "style"]);- const temporal = binding(child, resolveReference);+ const itemId = text(child, "id");+ const temporal = createTemporalWindowProjection({ id: itemId, element: child, semantic, resolveReference });+ records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);const suffix = String(items.length + 1).padStart(4, "0");const frame = reference(child.attributes.frame, `${child.name}.frame`, spatialTypes.frame, resolveReference);const style = reference(child.attributes.style, `${child.name}.style`, commentStickerTypes.style, resolveReference);@@ -200,21 +129,18 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ eleconst displayHeader = child.attributes.header === undefined ? undefined : graphText(child.attributes.header, `${child.name}.header`, resolveReference);const meta = child.attributes.meta === undefined ? undefined : graphText(child.attributes.meta, `${child.name}.meta`, resolveReference);const specId = `${id}.item.${suffix}.spec`;- const windowSpecId = `${id}.item.${suffix}.window`;- const windowSpecName = `item-${suffix}-window-spec`;records.push({id: specId,type: commentStickerTypes.itemSpec,value: { kind: "inline", value: sealCommentStickerItemSpec({- id: text(child, "id"),+ id: itemId,}) },range: child.range,});- records.push({ id: windowSpecId, type: temporalTypes.windowSpec,- value: { kind: "inline", value: { id: text(child, "id"), projection: temporal.projection } }, range: child.range });+ const windowName = `item-${suffix}-window`;const specName = `item-${suffix}-spec`; const frameName = `item-${suffix}-frame`; const styleName = `item-${suffix}-style`;- inputs[specName] = { kind: "record", id: specId }; inputs[windowSpecName] = { kind: "record", id: windowSpecId };+ inputs[specName] = { kind: "record", id: specId }; inputs[windowName] = temporal.ref;inputs[frameName] = frame.ref; inputs[styleName] = style.ref;const attachText = (field: string, value: string | SurfaceResolvedReference): string => {const name = `item-${suffix}-${field}`;@@ -232,18 +158,14 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ eleconst avatarName = avatar === undefined ? undefined : `item-${suffix}-avatar`;if (avatar !== undefined) inputs[avatarName!] = avatar.ref;const copy = { commentName, ...(authorName === undefined ? {} : { authorName }), ...(headerTextName === undefined ? {} : { headerTextName }), ...(metaName === undefined ? {} : { metaName }) };- if (temporal.kind === "program") items.push({ kind: "program", windowSpecName, specName, frameName, styleName, ...copy, ...(avatarName === undefined ? {} : { avatarName }) });- else {- const sourceName = `item-${suffix}-${temporal.kind}`;- inputs[sourceName] = temporal.source!.ref;- items.push({ kind: temporal.kind, windowSpecName, specName, frameName, styleName, ...copy, sourceName, ...(avatarName === undefined ? {} : { avatarName }) });- }+ items.push({ windowName, specName, frameName, styleName, ...copy, ...(avatarName === undefined ? {} : { avatarName }) });}if (items.length === 0) throw new Error(`${element.name} requires at least one Sticker.`);const fragment = createCommentStickerFragment(items);return {records,- components: [{ id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],- fragments: [fragment],+ components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],+ fragments: [...temporalFragments, fragment],+ exports: [`${id}.program`, `${id}.track`],};};diff --git a/packages/comment-sticker/test/comment-sticker.test.ts b/packages/comment-sticker/test/comment-sticker.test.tsindex 2dbcc6d3..08343d2c 100644--- a/packages/comment-sticker/test/comment-sticker.test.ts+++ b/packages/comment-sticker/test/comment-sticker.test.ts@@ -2,13 +2,14 @@ import assert from "node:assert/strict";import test from "node:test";import { fixtureDigest } from "../../../test/fixture-digest.js";import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";+import { projectProgramWindow } from "../../../test/temporal-fixture.js";import { artifactTypes } from "@hypit/artifact";import { compileHyperframesDocument } from "@hypit/hyperframes";import type { FontArtifactRef, FontStackRef } from "@hypit/media";import { mediaTypes } from "@hypit/media";import { sealProgramSpace } from "@hypit/program-space";-import { semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import type { SvsRecipe } from "@hypit/svs";@@ -17,7 +18,6 @@ import type { SurfaceResolvedReference } from "@hypit/markup";import { sealText } from "@hypit/text";import { textTypes } from "@hypit/text";import { temporalProducers } from "@hypit/temporal";-import { projectProgramWindow } from "@hypit/temporal";import {appendProjectedCommentSticker,@@ -50,7 +50,7 @@ const style = decodeCommentStickerStyle(recipe, fonts, "social-comment");const frame = { xPx: 80, yPx: 140, widthPx: 920, heightPx: 360 };const canvas = { widthPx: 1080, heightPx: 1920,origin: "top-left" as const, xDirection: "right" as const, yDirection: "down" as const, pixelAspect: "square" as const };-const space = sealProgramSpace({ durationSec: 3, frameRate: { numerator: 30, denominator: 1 } });+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } });const header = sealCommentStickerHeader({ id: "comments" });const semantic = semanticTrackFixture(space);@@ -70,7 +70,7 @@ function content(meta?: string) {function track(meta?: string) {const spec = item("opening");- const set = appendProjectedCommentSticker(createCommentStickerSet(), header, frame, style, spec, content(meta), projectProgramWindow({+ const set = appendProjectedCommentSticker(createCommentStickerSet(), header, space, frame, style, spec, content(meta), projectProgramWindow({itemId: spec.id, semantic, projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },}));return renderCommentSticker(canvas, space, finalizeCommentSticker(set, header));@@ -121,7 +121,7 @@ test("short Sticker windows compose overlapping enter and exit motion instead of}, fonts, "compressed");const spec = item("compressed");const set = appendProjectedCommentSticker(- createCommentStickerSet(), header, frame, compressed, spec, content(), projectProgramWindow({+ createCommentStickerSet(), header, space, frame, compressed, spec, content(), projectProgramWindow({itemId: spec.id, semantic, projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },}),);@@ -184,16 +184,19 @@ test("Track Surface lowers mixed program and semantic Stickers to a finite expliresolveReference: (path) => refs.get(path),resolveAsset: noAsset,});- assert.equal(result.components.length, 1);- assert.deepEqual(result.fragments[0]?.operations.map((operation) => operation.producer.name).sort(), [+ assert.equal(result.components.filter((component) => component.outputs.track !== undefined).length, 1);+ assert.deepEqual(result.fragments.flatMap((fragment) => fragment.operations.map((operation) => operation.producer.name)).sort(), [commentStickerProducers.createSet.name,commentStickerProducers.createContent.name,commentStickerProducers.setContentAuthor.name,commentStickerProducers.setContentMeta.name,commentStickerProducers.appendItemAvatar.name,commentStickerProducers.finalize.name,- temporalProducers.projectProgram.name,+ temporalProducers.projectProgramInstant.name,+ temporalProducers.projectProgramInstant.name,+ temporalProducers.composeWindow.name,+ semanticTrackProducers.projectProgramSpace.name,commentStickerProducers.render.name,].sort());- assert.equal(result.components[0]?.outputs.track, "comments.track");+ assert.equal(result.components.find((component) => component.outputs.track !== undefined)?.outputs.track, "comments.track");});diff --git a/packages/composition/src/schema.ts b/packages/composition/src/schema.tsindex 84e4eef1..46c41959 100644--- a/packages/composition/src/schema.ts+++ b/packages/composition/src/schema.ts@@ -169,7 +169,7 @@ const surface = object({ ...base, kind: { schema: { kind: "literal", value: "surconst element: ValueSchema = { kind: "oneOf", variants: [box, mask, text, textFlowElement, pathTextElement, media("image"), media("video"), surface] };const span = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });const present = object({ id: { schema: string }, span: { schema: span }, stacking: { schema: object({ order: { schema: signedInteger }, tieBreak: { schema: string } }) }, elements: { schema: { kind: "array", minItems: 1, items: element } } });-export const visualTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "visual" } }, visualIr: { schema: { kind: "literal", value: VISUAL_IR_V1 } }, id: { schema: string }, presents: { schema: { kind: "array", items: present } } });+export const visualTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "visual" } }, programSpaceId: { schema: string }, visualIr: { schema: { kind: "literal", value: VISUAL_IR_V1 } }, id: { schema: string }, presents: { schema: { kind: "array", items: present } } });const audioSampleSpan = object({ startSample: { schema: integer }, endSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } } });const audioClip = object({id: { schema: string },@@ -188,5 +188,5 @@ const audioClip = object({fadeInSamples: { schema: integer },fadeOutSamples: { schema: integer },});-export const audioTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "audio" } }, id: { schema: string }, clips: { schema: { kind: "array", items: audioClip } } });+export const audioTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "audio" } }, programSpaceId: { schema: string }, id: { schema: string }, clips: { schema: { kind: "array", items: audioClip } } });export const compositionSchema: ValueSchema = object({ id: { schema: string }, canvas: { schema: object({ width: { schema: integer }, height: { schema: integer }, clearColor: { schema: string } }) }, tracks: { schema: { kind: "array", items: { kind: "oneOf", variants: [visualTrackSchema, audioTrackSchema] } } } });diff --git a/packages/composition/src/track.ts b/packages/composition/src/track.tsindex f4fd5c2b..7ecbd2d5 100644--- a/packages/composition/src/track.ts+++ b/packages/composition/src/track.ts@@ -358,6 +358,8 @@ export type VisualPresent = {export type VisualTrack = {readonly kind: "visual";+ /** ProgramSpace identity this terminal placement was rendered against. */+ readonly programSpaceId: string;/** The one terminal visual language shared by official video components. */readonly visualIr: typeof VISUAL_IR_V1;readonly id: string;@@ -394,6 +396,8 @@ export type AudioClip = {export type AudioTrack = {readonly kind: "audio";+ /** ProgramSpace identity this terminal placement was rendered against. */+ readonly programSpaceId: string;readonly id: string;readonly clips: readonly AudioClip[];};@@ -1195,6 +1199,7 @@ function normalizeElement(element: VisualElement): VisualElement {function visualTrackContent(value: Omit<VisualTrack, "kind">): VisualTrack {return {kind: "visual",+ programSpaceId: value.programSpaceId,visualIr: value.visualIr,id: value.id,presents: [...value.presents]@@ -1215,6 +1220,7 @@ function visualTrackContent(value: Omit<VisualTrack, "kind">): VisualTrack {function audioTrackContent(value: Omit<AudioTrack, "kind">): AudioTrack {return {kind: "audio",+ programSpaceId: value.programSpaceId,id: value.id,clips: [...value.clips].map((clip) => ({@@ -1245,6 +1251,10 @@ export function assertVisualTrackIdentity(track: VisualTrack, programSpace?: Proif (programSpace !== undefined) assertProgramSpaceIdentity(programSpace);if (track.kind !== "visual") throw new Error("VisualTrack kind is invalid.");if (track.visualIr !== VISUAL_IR_V1) throw new Error("Unsupported VisualTrack visual IR.");+ assertNonEmpty(track.programSpaceId, "VisualTrack programSpaceId");+ if (programSpace !== undefined && track.programSpaceId !== programSpace.id) {+ throw new Error(`VisualTrack ${track.id} belongs to ProgramSpace ${track.programSpaceId}, not ${programSpace.id}.`);+ }assertNonEmpty(track.id, "VisualTrack id");const presentIds = new Set<string>();for (const present of track.presents) {@@ -1257,6 +1267,10 @@ export function assertVisualTrackIdentity(track: VisualTrack, programSpace?: Proexport function assertAudioTrackIdentity(track: AudioTrack, programSpace?: ProgramSpace): void {if (programSpace !== undefined) assertProgramSpaceIdentity(programSpace);if (track.kind !== "audio") throw new Error("AudioTrack kind is invalid.");+ assertNonEmpty(track.programSpaceId, "AudioTrack programSpaceId");+ if (programSpace !== undefined && track.programSpaceId !== programSpace.id) {+ throw new Error(`AudioTrack ${track.id} belongs to ProgramSpace ${track.programSpaceId}, not ${programSpace.id}.`);+ }assertNonEmpty(track.id, "AudioTrack id");const totalSamples = programSpace === undefined? Number.MAX_SAFE_INTEGERdiff --git a/packages/composition/test/render.test.ts b/packages/composition/test/render.test.tsindex 77a7ff89..512df152 100644--- a/packages/composition/test/render.test.ts+++ b/packages/composition/test/render.test.ts@@ -15,7 +15,7 @@ import {} from "../src/index.js";import type { VisualTrack } from "../src/index.js";-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 2,frameRate: { numerator: 30, denominator: 1 },});@@ -80,7 +80,7 @@ test("CompositableSurfaceRef distinguishes a typed alpha surface from an ordinar});test("exact fonts own font selection and cannot conflict with raw CSS font facts", () => {- const invalid = sealVisualTrack({+ const invalid = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "invalid-font-track",presents: [{@@ -108,7 +108,7 @@ test("exact fonts own font selection and cannot conflict with raw CSS font facts});test("animated materialized Surfaces must exactly share the Present frame domain", () => {- const valid = sealVisualTrack({+ const valid = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "surface-track",presents: [{@@ -127,8 +127,7 @@ test("animated materialized Surfaces must exactly share the Present frame domainconst content = structuredClone(valid) as VisualTrack;const surface = content.presents[0]!.elements[0]!;assert(surface.kind === "surface");- const invalid = sealVisualTrack({- ...content,+ const invalid = sealVisualTrack({...content,presents: [{...content.presents[0]!,span: { startFrame: 0, endFrameExclusive: 30 },@@ -149,7 +148,7 @@ test("animated materialized Surfaces must exactly share the Present frame domain});test("a local mask owns exactly one mask root and one content root inside its Present", () => {- const track = sealVisualTrack({+ const track = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "masked-text",presents: [{@@ -182,8 +181,7 @@ test("a local mask owns exactly one mask root and one content root inside its Prconst invalid = structuredClone(track) as VisualTrack;const root = invalid.presents[0]!.elements[0]!;assert(root.kind === "mask");- const broken = sealVisualTrack({- ...invalid,+ const broken = sealVisualTrack({...invalid,presents: [{...invalid.presents[0]!,elements: [{ ...root, contentElement: "foreign" }, ...invalid.presents[0]!.elements.slice(1)],@@ -194,8 +192,7 @@ test("a local mask owns exactly one mask root and one content root inside its Prcanvas: { width: 1080, height: 1920, clearColor: "#000000" }, tracks: [broken],}), space), /declared mask and content roots/u);- const nested = sealVisualTrack({- ...track,+ const nested = sealVisualTrack({...track,presents: [{...track.presents[0]!,elements: [diff --git a/packages/composition/test/track.test.ts b/packages/composition/test/track.test.tsindex 74cbbb9c..29f551de 100644--- a/packages/composition/test/track.test.ts+++ b/packages/composition/test/track.test.ts@@ -45,11 +45,11 @@ const audio: BlobRef = {};function fixture() {- const programSpace = sealProgramSpace({+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 4,frameRate: { numerator: 30, denominator: 1 },});- const visual = sealVisualTrack({+ const visual = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "caption",presents: [{@@ -62,7 +62,7 @@ function fixture() {],}],});- const sound = sealAudioTrack({+ const sound = sealAudioTrack({ programSpaceId: "test-space",id: "speech",clips: [{id: "speech",@@ -105,8 +105,7 @@ test("VisualTrack rejects cross-Track pixel sampling styles", () => {const { programSpace, visual, sound } = fixture();const content = structuredClone(visual) as VisualTrack;const first = content.presents[0]!.elements[0]!;- const invasive = sealVisualTrack({- ...content,+ const invasive = sealVisualTrack({...content,presents: [{...content.presents[0]!,elements: [{ ...first, style: [{ name: "backdrop-filter", value: "blur(20px)" }] }],@@ -124,8 +123,7 @@ test("VisualTrack style values cannot smuggle a second declaration", () => {const { programSpace, visual } = fixture();const content = structuredClone(visual) as VisualTrack;const first = content.presents[0]!.elements[0]!;- const smuggled = sealVisualTrack({- ...content,+ const smuggled = sealVisualTrack({...content,presents: [{...content.presents[0]!,elements: [{ ...first, style: [{ name: "color", value: "red;backdrop-filter:blur(20px)" }] }],@@ -144,8 +142,7 @@ test("VisualTrack style values cannot smuggle a second declaration", () => {test("VisualTrack cannot silently extend the versioned public Visual IR", () => {const { programSpace, visual } = fixture();const first = visual.presents[0]!.elements[0]!;- const unknownStyle = sealVisualTrack({- ...visual,+ const unknownStyle = sealVisualTrack({...visual,presents: [{...visual.presents[0]!,elements: [{ ...first, style: [{ name: "mask-image", value: "linear-gradient(black, transparent)" }] }],@@ -160,8 +157,7 @@ test("VisualTrack cannot silently extend the versioned public Visual IR", () =>/outside hypit\.visual-ir@1/u,);- const fixedPosition = sealVisualTrack({- ...visual,+ const fixedPosition = sealVisualTrack({...visual,presents: [{...visual.presents[0]!,elements: [{ ...first, style: [{ name: "position", value: "fixed" }] }],@@ -172,8 +168,7 @@ test("VisualTrack cannot silently extend the versioned public Visual IR", () =>/position has unsupported value fixed/u,);- const environmentBound = sealVisualTrack({- ...visual,+ const environmentBound = sealVisualTrack({...visual,presents: [{...visual.presents[0]!,elements: [{ ...first, style: [{ name: "color", value: "var(--host-color)" }] }],@@ -199,8 +194,7 @@ test("VisualTrack explicitly binds the visual IR instead of trusting the Runtimetest("the Type owner rejects an invalid VisualTrack at the shared admission gate", async () => {const { visual } = fixture();const present = visual.presents[0]!;- const invalid = sealVisualTrack({- ...visual,+ const invalid = sealVisualTrack({...visual,presents: [{...present,elements: [@@ -225,7 +219,7 @@ test("the Type owner rejects an invalid VisualTrack at the shared admission gatetest("Composition validates Track frame ranges against the explicitly connected ProgramSpace", () => {const { programSpace, visual } = fixture();- const foreign = sealProgramSpace({+ const foreign = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 1,frameRate: { numerator: 24, denominator: 1 },});@@ -246,8 +240,7 @@ test("one authoring Track may contribute independently stacked Presents", () =>id: "cue-2",stacking: { order: 30, tieBreak: "board" },};- const interleaved = sealVisualTrack({- ...content,+ const interleaved = sealVisualTrack({...content,presents: [{ ...content.presents[0]!, stacking: { order: 80, tieBreak: "icon" } },second,@@ -266,8 +259,7 @@ test("Visual Present animations may finish before or after their visibility windconst { programSpace, visual } = fixture();const present = visual.presents[0]!;const root = present.elements[0]!;- const animated = sealVisualTrack({- ...visual,+ const animated = sealVisualTrack({...visual,presents: [{...present,elements: [{@@ -286,8 +278,7 @@ test("Visual Present animations may finish before or after their visibility windcanvas: { width: 1080, height: 1920, clearColor: "#000000" },tracks: [animated],}), programSpace));- const clipped = sealVisualTrack({- ...visual,+ const clipped = sealVisualTrack({...visual,presents: [{...present,elements: [{@@ -306,8 +297,7 @@ test("Visual Present animations may finish before or after their visibility windcanvas: { width: 1080, height: 1920, clearColor: "#000000" },tracks: [clipped],}), programSpace));- const invasive = sealVisualTrack({- ...visual,+ const invasive = sealVisualTrack({...visual,presents: [{...present,elements: [{diff --git a/packages/deck-track/README.md b/packages/deck-track/README.mdindex a67f79bf..bde629ad 100644--- a/packages/deck-track/README.md+++ b/packages/deck-track/README.md@@ -35,8 +35,8 @@ silently depend on renderer playback history.Optional labels are separate exact-font values and are referenced by Cards. Filenames, URLs andmedia metadata are never treated as label truth.-The Surface projects every Card `at` and the deck terminal to `TemporalPoint` values before the-Deck component runs. Card append and finalization consume those Points directly; they never locate+The Surface projects every Card `at` and the deck terminal to `TemporalInstant` values before the+Deck component runs. Card append and finalization consume those Instants directly; they never locatea Moment/Selection or manufacture a one-frame terminal Window internally.`deck:Label` accepts either literal body copy or `content={Text}`. It binds that copy to exact fontdiff --git a/packages/deck-track/package.json b/packages/deck-track/package.jsonindex ba43df66..2b1d5eb2 100644--- a/packages/deck-track/package.json+++ b/packages/deck-track/package.json@@ -24,6 +24,7 @@"@hypit/spatial": "workspace:*","@hypit/svs": "workspace:*","@hypit/temporal": "workspace:*",+ "@hypit/temporal-markup": "workspace:*","@hypit/text": "workspace:*","@hypit/markup": "workspace:*"},diff --git a/packages/deck-track/src/component.ts b/packages/deck-track/src/component.tsindex 380f0439..587bffe3 100644--- a/packages/deck-track/src/component.ts+++ b/packages/deck-track/src/component.ts@@ -3,7 +3,7 @@ import { canonicalize } from "@hypit/protocol";import type { StoredValue } from "@hypit/protocol";import type { ProgramSpace } from "@hypit/program-space";import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";-import type { TemporalPoint } from "@hypit/temporal";+import type { TemporalInstant } from "@hypit/temporal";import type { MediaLayerSet } from "@hypit/media-track";import type { Text } from "@hypit/text";@@ -53,10 +53,11 @@ export const depthStackComponent = {producer: depthStackProducers.appendCard,handler: ({ inputs }) => ({ outputs: { set: output(appendDepthStackCard(inline<DepthStackCardSet>(inputs.set?.value, "DepthStackCardSet"),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),inline<MediaLayerSet>(inputs.material?.value, "MediaLayerSet"),inline<DepthStackCardLabel>(inputs.label?.value, "DepthStackCardLabel"),inline<DepthStackCardSpec>(inputs.spec?.value, "DepthStackCardSpec"),- inline<TemporalPoint>(inputs.activation?.value, "TemporalPoint"),+ inline<TemporalInstant>(inputs.activation?.value, "TemporalInstant"),)) }, needs: {} }),},{@@ -65,7 +66,7 @@ export const depthStackComponent = {const value = finalizeInputs(inputs);return { outputs: { program: output(finalizeDepthStack(value.set, value.header, value.frame, value.spec,- inline<TemporalPoint>(inputs.terminal?.value, "TemporalPoint"), value.space,+ inline<TemporalInstant>(inputs.terminal?.value, "TemporalInstant"), value.space,)) }, needs: {} };},},diff --git a/packages/deck-track/src/fragment.ts b/packages/deck-track/src/fragment.tsindex c333de06..8e318df1 100644--- a/packages/deck-track/src/fragment.ts+++ b/packages/deck-track/src/fragment.ts@@ -4,10 +4,9 @@ import { sealGraphFragment } from "@hypit/elaborator";import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";import { mediaTypes } from "@hypit/media";import { mediaTrackProducers, mediaTrackTypes } from "@hypit/media-track";-import { narrativeTypes } from "@hypit/narrative";import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";-import { temporalProducers, temporalTypes } from "@hypit/temporal";+import { temporalTypes } from "@hypit/temporal";import { depthStackProducers, depthStackTypes } from "./manifest.js";@@ -24,14 +23,9 @@ export type DepthStackFragmentCard = {readonly framePaintSpecName?: string;readonly labelName: string;readonly cardSpecName: string;- readonly momentName: string;- readonly pointSpecName: string;+ readonly activationName: string;};-export type DepthStackFragmentTerminal =- | { readonly kind: "program-end" }- | { readonly kind: "moment" | "selection-start" | "selection-end"; readonly inputName: string; readonly specName: string };-function sourceInput(card: DepthStackFragmentCard): GraphFragment["inputs"][number] {const type = card.sourceKind === "still"? artifactTypes.blob@@ -41,7 +35,7 @@ function sourceInput(card: DepthStackFragmentCard): GraphFragment["inputs"][numbexport function createDepthStackFragment(cards: readonly DepthStackFragmentCard[],- terminal: DepthStackFragmentTerminal,+ terminalName: string,) {if (cards.length === 0) throw new Error("DepthStack Fragment requires Cards.");const inputs: Array<GraphFragment["inputs"][number]> = [@@ -51,12 +45,20 @@ export function createDepthStackFragment({ name: "semantic", type: semanticTrackTypes.track },{ name: "spec", type: depthStackTypes.spec },];- const operations: FragmentOperation[] = [{- id: "cards",- producer: depthStackProducers.createCards,- inputs: {},- result: { kind: "output", name: "set" },- }];+ const operations: FragmentOperation[] = [+ {+ id: "space",+ producer: semanticTrackProducers.projectProgramSpace,+ inputs: { track: input("semantic") },+ result: { kind: "output", name: "space" },+ },+ {+ id: "cards",+ producer: depthStackProducers.createCards,+ inputs: {},+ result: { kind: "output", name: "set" },+ },+ ];let cardSet = operation("cards");for (const card of cards) {inputs.push(sourceInput(card));@@ -66,8 +68,7 @@ export function createDepthStackFragment({ name: card.sampleSpecName, type: mediaTrackTypes.sampleLayerSpec },{ name: card.labelName, type: depthStackTypes.cardLabel },{ name: card.cardSpecName, type: depthStackTypes.cardSpec },- { name: card.momentName, type: narrativeTypes.moment },- { name: card.pointSpecName, type: temporalTypes.pointSpec },+ { name: card.activationName, type: temporalTypes.instant },);if (card.framePaintSpecName !== undefined) {inputs.push({ name: card.framePaintSpecName, type: mediaTrackTypes.paintLayerSpec });@@ -107,53 +108,22 @@ export function createDepthStackFragment(result: { kind: "output", name: "layers" },});const appendId = `append-${card.suffix}`;- const pointId = `point-${card.suffix}`;- operations.push({- id: pointId,- producer: temporalProducers.projectMomentPoint,- inputs: { semantic: input("semantic"), moment: input(card.momentName), spec: input(card.pointSpecName) },- result: { kind: "output", name: "point" },- });operations.push({id: appendId,producer: depthStackProducers.appendCard,inputs: {set: cardSet,+ space: operation("space"),material: operation(sampleId),label: input(card.labelName),spec: input(card.cardSpecName),- activation: operation(pointId),+ activation: input(card.activationName),},result: { kind: "output", name: "set" },});cardSet = operation(appendId);}- if (terminal.kind !== "program-end") {- inputs.push({- name: terminal.inputName,- type: terminal.kind === "moment" ? narrativeTypes.moment : narrativeTypes.selection,- });- inputs.push({ name: terminal.specName, type: temporalTypes.pointSpec });- }- const terminalPoint = terminal.kind === "program-end" ? "program-point" : "terminal-point";- if (terminal.kind === "program-end") {- inputs.push({ name: "program-spec", type: temporalTypes.pointSpec });- operations.push({ id: terminalPoint, producer: temporalProducers.projectProgramPoint,- inputs: { semantic: input("semantic"), spec: input("program-spec") }, result: { kind: "output", name: "point" } });- } else {- operations.push({ id: terminalPoint,- producer: terminal.kind === "moment" ? temporalProducers.projectMomentPoint : temporalProducers.projectSelectionPoint,- inputs: {- semantic: input("semantic"), spec: input(terminal.specName),- [terminal.kind === "moment" ? "moment" : "selection"]: input(terminal.inputName),- }, result: { kind: "output", name: "point" } });- }- operations.push({- id: "space",- producer: semanticTrackProducers.projectProgramSpace,- inputs: { track: input("semantic") },- result: { kind: "output", name: "space" },- });+ inputs.push({ name: terminalName, type: temporalTypes.instant });operations.push({id: "program",producer: depthStackProducers.finalize,@@ -163,7 +133,7 @@ export function createDepthStackFragment(frame: input("frame"),spec: input("spec"),space: operation("space"),- terminal: operation(terminalPoint),+ terminal: input(terminalName),},result: { kind: "output", name: "program" },});diff --git a/packages/deck-track/src/index.ts b/packages/deck-track/src/index.tsindex 1794f603..4a62e568 100644--- a/packages/deck-track/src/index.ts+++ b/packages/deck-track/src/index.ts@@ -5,7 +5,7 @@ export {} from "./author.js";export { depthStackComponent } from "./component.js";export { createDepthStackFragment } from "./fragment.js";-export type { DepthStackFragmentCard, DepthStackFragmentTerminal } from "./fragment.js";+export type { DepthStackFragmentCard } from "./fragment.js";export {decodeDepthStackLabelSurface,decodeDepthStackSurface,diff --git a/packages/deck-track/src/lower.ts b/packages/deck-track/src/lower.tsindex 9fa54e2d..bfa4c38c 100644--- a/packages/deck-track/src/lower.ts+++ b/packages/deck-track/src/lower.ts@@ -360,6 +360,7 @@ export function renderDepthStack(}}const track = sealVisualTrack({+ programSpaceId: space.id,visualIr: "hypit.visual-ir@1",id: program.id,presents,diff --git a/packages/deck-track/src/manifest.ts b/packages/deck-track/src/manifest.tsindex 2ebdd894..4d8af303 100644--- a/packages/deck-track/src/manifest.ts+++ b/packages/deck-track/src/manifest.ts@@ -24,6 +24,7 @@ import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-traimport { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import { temporalDependency, temporalTypes } from "@hypit/temporal";+import { temporalInstantAttributeVocabulary } from "@hypit/temporal-markup";import { textDependency, textTypes } from "@hypit/text";const previewImage = (file: string) => ({@@ -157,7 +158,7 @@ export const depthStackMarkupSurfaces = [depthStackTypes.header, depthStackTypes.spec, depthStackTypes.cardSpec,spatialTypes.fit, mediaTrackTypes.sampleLayerSpec, mediaTrackTypes.paintLayerSpec,depthStackTypes.cardLabel, depthStackTypes.cardLabelStyle, textTypes.text,- temporalTypes.pointSpec,+ temporalTypes.instantSpec, temporalTypes.instant,depthStackTypes.program, compositionTypes.visualTrack,],vocabulary: {@@ -330,8 +331,7 @@ export const depthStackMarkupSurfaces = [summary: "Chooses the picture the Card shows, as a still image Artifact, a Synchronized Medium or a Compositable Surface." },{ name: "extent", kind: "reference", required: false, accepts: [spatialTypes.extent],summary: "Gives a still image its pixel Extent, which timed and surface sources already carry." },- { name: "at", kind: "reference", required: true, accepts: [narrativeTypes.moment],- summary: "Chooses the Moment the Card is dealt on." },+ ...temporalInstantAttributeVocabulary,{ name: "appearance", kind: "reference", required: false, accepts: [svsRecipeType],summary: "Chooses this Card's own Recipe in place of the deck's, adding explicit future and past playback.",recipe: [@@ -422,12 +422,12 @@ export const depthStackManifest: ModuleManifest = {{ name: depthStackProducers.bindLabelText.name, inputs: [{ name: "style", type: depthStackTypes.cardLabelStyle }, { name: "content", type: textTypes.text }], outputs: [{ name: "label", type: depthStackTypes.cardLabel }], needs: [] },{ name: depthStackProducers.createCards.name, inputs: [], outputs: [{ name: "set", type: depthStackTypes.cardSet }], needs: [] },{ name: depthStackProducers.appendCard.name, inputs: [- { name: "set", type: depthStackTypes.cardSet }, { name: "material", type: mediaTrackTypes.layerSet },+ { name: "set", type: depthStackTypes.cardSet }, { name: "space", type: programSpaceTypes.programSpace }, { name: "material", type: mediaTrackTypes.layerSet },{ name: "label", type: depthStackTypes.cardLabel }, { name: "spec", type: depthStackTypes.cardSpec },- { name: "activation", type: temporalTypes.point },+ { name: "activation", type: temporalTypes.instant },], outputs: [{ name: "set", type: depthStackTypes.cardSet }], needs: [] },{ name: depthStackProducers.finalize.name,- inputs: [...finalizeInputs, { name: "terminal", type: temporalTypes.point }],+ inputs: [...finalizeInputs, { name: "terminal", type: temporalTypes.instant }],outputs: [{ name: "program", type: depthStackTypes.program }], needs: [] },{ name: depthStackProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace },diff --git a/packages/deck-track/src/program.ts b/packages/deck-track/src/program.tsindex e745185a..281e80fd 100644--- a/packages/deck-track/src/program.ts+++ b/packages/deck-track/src/program.ts@@ -16,7 +16,8 @@ import { verifyText } from "@hypit/text";import type { Text } from "@hypit/text";import { assertSpatialFrame } from "@hypit/spatial";import type { SpatialFrame } from "@hypit/spatial";-import type { TemporalPoint } from "@hypit/temporal";+import { assertTemporalInstantFor } from "@hypit/temporal";+import type { TemporalInstant } from "@hypit/temporal";import type {DeckCardTone,@@ -228,11 +229,13 @@ function appendDepthStackCardAtFrame(export function appendDepthStackCard(set: DepthStackCardSet,+ space: ProgramSpace,material: DepthStackCardSet["cards"][number]["material"],label: DepthStackCardLabel,spec: DepthStackCardSpec,- activation: TemporalPoint,+ activation: TemporalInstant,): DepthStackCardSet {+ assertTemporalInstantFor(activation, { subjectId: spec.id, space });return appendDepthStackCardAtFrame(set, material, label, spec, activation.frame);}@@ -269,9 +272,10 @@ export function finalizeDepthStack(header: DepthStackHeader,frame: SpatialFrame,spec: DepthStackSpec,- terminal: TemporalPoint,+ terminal: TemporalInstant,space: ProgramSpace,): DepthStackProgram {+ assertTemporalInstantFor(terminal, { subjectId: header.id, space });return finalizeDepthStackAtFrame(set, header, frame, spec, terminal.frame, space);}diff --git a/packages/deck-track/src/surface.ts b/packages/deck-track/src/surface.tsindex 6f4b42bb..7e864903 100644--- a/packages/deck-track/src/surface.ts+++ b/packages/deck-track/src/surface.ts@@ -2,12 +2,11 @@ import { artifactTypes } from "@hypit/artifact";import { mediaTypes } from "@hypit/media";import type { FontStackRef } from "@hypit/media";import { mediaTrackTypes } from "@hypit/media-track";-import { narrativeTypes } from "@hypit/narrative";import type { TypeRef } from "@hypit/protocol";import { semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";-import { temporalTypes } from "@hypit/temporal";+import { createTemporalInstantProjection, temporalInstantAttributeNames } from "@hypit/temporal-markup";import type { SvsRecipe } from "@hypit/svs";import { sealText, textTypes } from "@hypit/text";import { sealGraphFragment } from "@hypit/elaborator";@@ -15,6 +14,7 @@ import type { AuthorValueRef } from "@hypit/elaborator";import type {StructuredElement,StructuredSurfaceHandler,+ SurfaceComponentDraft,SurfaceRecordDraft,SurfaceResolvedReference,MarkupAttributeValue,@@ -28,10 +28,7 @@ import {import {createDepthStackFragment,} from "./fragment.js";-import type {- DepthStackFragmentCard,- DepthStackFragmentTerminal,-} from "./fragment.js";+import type { DepthStackFragmentCard } from "./fragment.js";import { depthStackProducers, depthStackTypes } from "./manifest.js";import {noDepthStackCardLabel,@@ -183,26 +180,6 @@ export const decodeDepthStackLabelSurface: StructuredSurfaceHandler = ({ element};};-function terminal(- element: StructuredElement,- resolve: (path: string) => SurfaceResolvedReference | undefined,-): { readonly terminal: DepthStackFragmentTerminal; readonly reference?: SurfaceResolvedReference } {- const raw = element.attributes.until;- if (typeof raw === "string") {- if (raw.trim() !== "program.end") throw new Error(`${element.name}.until text must be program.end.`);- if (element.attributes["until-boundary"] !== undefined) throw new Error(`${element.name}.until-boundary requires a Selection.`);- return { terminal: { kind: "program-end" } };- }- const value = oneOfReference(raw, `${element.name}.until`, [narrativeTypes.moment, narrativeTypes.selection], resolve);- if (sameType(value.type, narrativeTypes.moment)) {- if (element.attributes["until-boundary"] !== undefined) throw new Error(`${element.name}.until-boundary requires a Selection.`);- return { terminal: { kind: "moment", inputName: "terminal", specName: "terminal-spec" }, reference: value };- }- const boundary = text(element, "until-boundary", "end");- if (boundary !== "start" && boundary !== "end") throw new Error(`${element.name}.until-boundary is invalid.`);- return { terminal: { kind: boundary === "start" ? "selection-start" : "selection-end", inputName: "terminal", specName: "terminal-spec" }, reference: value };-}-export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {allowed(element, ["id", "semantic", "canvas", "frame", "appearance", "until", "until-boundary"]);const id = text(element, "id");@@ -210,8 +187,13 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, resconst canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);const appearance = recipe(element.attributes.appearance, `${element.name}.appearance`, resolveReference);- const terminalValue = terminal(element, resolveReference);- const records: SurfaceRecordDraft[] = [];+ const terminal = createTemporalInstantProjection({+ id: `${id}.terminal`, subjectId: id, element, semantic, resolveReference,+ semanticAttribute: "until", boundaryAttribute: "until-boundary", boundaryFallback: "end", projectedAttribute: false,+ });+ const records: SurfaceRecordDraft[] = [...terminal.records];+ const temporalComponents: SurfaceComponentDraft[] = [...terminal.components];+ const temporalFragments = [...terminal.fragments];const headerId = `${id}.header`;const specId = `${id}.spec`;records.push(@@ -220,22 +202,8 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res);const inputs: Record<string, typeof semantic.ref> = {canvas: canvas.ref, frame: frame.ref, header: { kind: "record", id: headerId }, semantic: semantic.ref,- spec: { kind: "record", id: specId },+ spec: { kind: "record", id: specId }, terminal: terminal.ref,};- const terminalSpecId = `${id}.terminal.point`;- const terminalSpecName = terminalValue.terminal.kind === "program-end" ? "program-spec" : terminalValue.terminal.specName;- records.push({ id: terminalSpecId, type: temporalTypes.pointSpec, value: { kind: "inline", value: {- id: `${id}.terminal`,- projection: terminalValue.terminal.kind === "program-end"- ? { ref: "program.end" }- : terminalValue.terminal.kind === "moment"- ? { ref: "moment.cue" }- : terminalValue.terminal.kind === "selection-start"- ? { ref: "selection.start" }- : { ref: "selection.end" },- } }, range: element.range });- if (terminalValue.reference !== undefined) inputs.terminal = terminalValue.reference.ref;- inputs[terminalSpecName] = { kind: "record", id: terminalSpecId };const cards: DepthStackFragmentCard[] = [];let cardIndex = 0;for (const child of element.children) {@@ -244,7 +212,7 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, rescontinue;}if (child.name.split(":").at(-1) !== "Card") throw new Error(`${element.name} accepts Card children only.`);- allowed(child, ["id", "source", "extent", "at", "appearance", "label"]);+ allowed(child, ["id", "source", "extent", ...temporalInstantAttributeNames, "appearance", "label"]);empty(child);cardIndex += 1;const suffix = String(cardIndex).padStart(4, "0");@@ -256,7 +224,8 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res: reference(child.attributes.extent, `${child.name}.extent`, spatialTypes.extent, resolveReference);if (sourceKind === "still" && extent === undefined) throw new Error(`${child.name}.extent is required for a still image.`);if (sourceKind !== "still" && extent !== undefined) throw new Error(`${child.name}.extent belongs only to a still image.`);- const moment = reference(child.attributes.at, `${child.name}.at`, narrativeTypes.moment, resolveReference);+ const activation = createTemporalInstantProjection({ id: `${id}.${cardId}`, subjectId: cardId, element: child, semantic, resolveReference });+ records.push(...activation.records); temporalComponents.push(...activation.components); temporalFragments.push(...activation.fragments);const cardAppearance = child.attributes.appearance === undefined? appearance : recipe(child.attributes.appearance, `${child.name}.appearance`, resolveReference);const material = decodeDepthStackMaterial(cardAppearance, `${id}.${cardId}`, sourceKind);@@ -272,20 +241,13 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, resconst fitName = `card-${suffix}-fit`;const sampleSpecName = `card-${suffix}-sample-spec`;const cardSpecName = `card-${suffix}-spec`;- const momentName = `card-${suffix}-moment`;- const pointSpecName = `card-${suffix}-point-spec`;+ const activationName = `card-${suffix}-activation`;const labelName = `card-${suffix}-label`;inputs[sourceName] = source.ref;inputs[fitName] = { kind: "record", id: fitId };inputs[sampleSpecName] = { kind: "record", id: sampleId };inputs[cardSpecName] = { kind: "record", id: cardSpecId };- inputs[momentName] = moment.ref;- const pointSpecId = `${id}.card.${suffix}.point`;- records.push({ id: pointSpecId, type: temporalTypes.pointSpec, value: { kind: "inline", value: {- id: `${id}.${cardId}`,- projection: { ref: "moment.cue" },- } }, range: child.range });- inputs[pointSpecName] = { kind: "record", id: pointSpecId };+ inputs[activationName] = activation.ref;let labelRef: typeof semantic.ref;if (child.attributes.label === undefined) {const labelId = `${id}.card.${suffix}.label-none`;@@ -309,14 +271,15 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res}cards.push({suffix, sourceKind, sourceName, ...(extentName === undefined ? {} : { extentName }), fitName, sampleSpecName,- ...(framePaintSpecName === undefined ? {} : { framePaintSpecName }), labelName, cardSpecName, momentName, pointSpecName,+ ...(framePaintSpecName === undefined ? {} : { framePaintSpecName }), labelName, cardSpecName, activationName,});}if (cards.length === 0) throw new Error(`${element.name} requires at least one Card.`);- const fragment = createDepthStackFragment(cards, terminalValue.terminal);+ const fragment = createDepthStackFragment(cards, "terminal");return {records,- components: [{ id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],- fragments: [fragment],+ components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],+ fragments: [...temporalFragments, fragment],+ exports: [`${id}.program`, `${id}.track`],};};diff --git a/packages/deck-track/test/deck-track.test.ts b/packages/deck-track/test/deck-track.test.tsindex a566ab00..eee345f0 100644--- a/packages/deck-track/test/deck-track.test.ts+++ b/packages/deck-track/test/deck-track.test.ts@@ -41,7 +41,7 @@ import { sealProgramSpace } from "@hypit/program-space";import type { ModuleManifest } from "@hypit/protocol";import { semanticTrackTypes } from "@hypit/semantic-track";import { temporalTypes } from "@hypit/temporal";-import type { TemporalPoint } from "@hypit/temporal";+import type { TemporalInstant } from "@hypit/temporal";import { sealCanvasSpace, sealSpatialFrame, spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import { sealText, textManifest, textTypes } from "@hypit/text";@@ -55,7 +55,7 @@ import type {import { artifactTypes } from "@hypit/artifact";import { mediaTrackManifest, mediaTrackTypes } from "@hypit/media-track";-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 2,frameRate: { numerator: 30, denominator: 1 },});@@ -102,7 +102,7 @@ test("DepthStack Surface declares every sealed Record it may emit", () => {depthStackTypes.cardLabel,depthStackTypes.cardLabelStyle,textTypes.text,- temporalTypes.pointSpec,+ temporalTypes.instantSpec,depthStackTypes.program,compositionTypes.visualTrack,]) {@@ -204,21 +204,25 @@ function cardSpec(id: string, past: "hold-tail" | "continue" | "hide" = "hold-ta});}-function momentPoint(id: string, frameValue: number): TemporalPoint {+function momentPoint(id: string, frameValue: number): TemporalInstant {return {id: `${id}::moment`,- source: { kind: "moment", id },+ subjectId: id,+ source: { spaceId: space.id, narrativeId: space.narrativeId, kind: "moment", id },projection: { ref: "moment.cue" },frame: frameValue,+ authority: { kind: "fixed" },};}-function programPoint(endFrame: number): TemporalPoint {+function programPoint(subjectId: string, endFrame: number): TemporalInstant {return {id: "program::program",- source: { kind: "program", id: "program" },+ subjectId,+ source: { spaceId: space.id, narrativeId: space.narrativeId, kind: "program", id: "program" },projection: { ref: "program.end" },frame: endFrame,+ authority: { kind: "fixed" },};}@@ -236,6 +240,7 @@ function program(input: {const id = `card-${index + 1}`;set = appendDepthStackCard(set,+ space,input.materials?.[index] ?? stillMaterial(id),input.labels?.[index] ?? noDepthStackCardLabel(),input.playbacks?.[index] ?? cardSpec(id),@@ -247,7 +252,7 @@ function program(input: {sealDepthStackHeader({ id: "proof-stack" }),frame,input.spec ?? baseSpec(),- programPoint(input.terminal ?? 60),+ programPoint("proof-stack", input.terminal ?? 60),space,);}@@ -282,7 +287,7 @@ test("explicit wrapping never aliases one Card into several relative depths", ()test("missing, equal, reversed and terminal-crossing triggers fail in authored order", () => {assert.throws(() => finalizeDepthStack(createDepthStackCardSet(), sealDepthStackHeader({ id: "empty" }),- frame, baseSpec(), programPoint(60), space,+ frame, baseSpec(), programPoint("empty", 60), space,), /at least one Card/u);assert.throws(() => program({ triggers: [0, 20, 20] }), /strictly increasing/u);assert.throws(() => program({ triggers: [0, 30, 20] }), /strictly increasing/u);@@ -436,15 +441,24 @@ test("the author Surface keeps every source, trigger, terminal, Frame and optionresolveReference: (path) => references.get(path),resolveAsset: async () => { throw new Error("no asset resolution expected"); },});- assert.equal(result.components.length, 1);- assert.deepEqual(Object.keys(result.components[0]!.outputs).sort(), ["program", "track"]);- const fragment = result.fragments[0]!;+ const component = result.components.find((candidate) => candidate.outputs.track !== undefined);+ assert.ok(component !== undefined);+ assert.deepEqual(Object.keys(component.outputs).sort(), ["program", "track"]);+ const fragment = result.fragments.find((candidate) => candidate.exports.some((output) => output.name === "track"))!;assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-still-media-layer"));assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-timed-media-layer"));assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-depth-stack-card"));assert.ok(fragment.operations.some((operation) => operation.producer.name === "finalize-depth-stack"));- assert.ok(fragment.operations.some((operation) => operation.producer.name === "project-selection-point"));- assert.equal(fragment.inputs.filter((input) => input.type.name === narrativeTypes.moment.name).length, 2);+ assert.ok(result.fragments.some((candidate) => candidate.operations.some((operation) =>+ operation.producer.name === "project-selection-instant")));+ const temporalSubjects = new Set(result.records.flatMap((record) =>+ record.value.kind === "inline"+ && typeof record.value.value === "object"+ && record.value.value !== null+ && "subjectId" in record.value.value+ ? [String((record.value.value as { readonly subjectId: unknown }).subjectId)]+ : []));+ assert.deepEqual([...temporalSubjects].sort(), ["one", "proof", "two"]);assert.ok(fragment.inputs.some((input) => input.name === "frame"));assert.ok(fragment.inputs.some((input) => input.name === "terminal"));});diff --git a/packages/film/src/component.ts b/packages/film/src/component.tsindex 01344806..68368e20 100644--- a/packages/film/src/component.ts+++ b/packages/film/src/component.ts@@ -1,6 +1,5 @@import type { ComponentPackage } from "@hypit/component-kit";-import { projectSemanticProgramSpace } from "@hypit/semantic-track";-import type { SemanticTrack } from "@hypit/semantic-track";+import type { ProgramSpace } from "@hypit/program-space";import type { CanvasSpace } from "@hypit/spatial";import type { AudioTrack, VisualTrack } from "@hypit/composition";import type { StoredValue } from "@hypit/protocol";@@ -29,7 +28,7 @@ export const filmComponent = {handler: ({ inputs }) => ({outputs: { set: { kind: "inline", value: canonicalize(appendFilmVisualTrack(inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),inline<VisualTrack>(inputs.track?.value, "VisualTrack"),)) } },needs: {},@@ -40,7 +39,7 @@ export const filmComponent = {handler: ({ inputs }) => ({outputs: { set: { kind: "inline", value: canonicalize(appendFilmAudioTrack(inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),inline<AudioTrack>(inputs.track?.value, "AudioTrack"),)) } },needs: {},@@ -52,7 +51,7 @@ export const filmComponent = {outputs: { composition: { kind: "inline", value: canonicalize(compileFilmComposition(inline<FilmProgram>(inputs.program?.value, "FilmProgram"),inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),)) } },needs: {},diff --git a/packages/film/src/fragment.ts b/packages/film/src/fragment.tsindex e3920a91..f3e26c20 100644--- a/packages/film/src/fragment.ts+++ b/packages/film/src/fragment.ts@@ -1,4 +1,4 @@-import { semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { compositionTypes } from "@hypit/composition";import type { Track } from "@hypit/composition";@@ -31,19 +31,27 @@ function assertTrackInputs(tracks: readonly FilmTrackInput[]): FilmTrackInput[]*/export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions) {const tracks = assertTrackInputs(options.tracks);- const operations: FragmentOperation[] = [{- id: "track-set:empty",- producer: filmProducers.createTrackSet,- inputs: {},- result: { kind: "output" as const, name: "set" },- }];+ const operations: FragmentOperation[] = [+ {+ id: "film:space",+ producer: semanticTrackProducers.projectProgramSpace,+ inputs: { track: input("semantic") },+ result: { kind: "output" as const, name: "space" },+ },+ {+ id: "track-set:empty",+ producer: filmProducers.createTrackSet,+ inputs: {},+ result: { kind: "output" as const, name: "set" },+ },+ ];let current = "track-set:empty";tracks.forEach((track, index) => {const id = `track-set:append:${String(index).padStart(4, "0")}`;operations.push({id,producer: track.kind === "visual" ? filmProducers.appendVisualTrack : filmProducers.appendAudioTrack,- inputs: { set: operation(current), semantic: input("semantic"), track: input(track.name) },+ inputs: { set: operation(current), space: operation("film:space"), track: input(track.name) },result: { kind: "output" as const, name: "set" },});current = id;@@ -54,7 +62,7 @@ export function createFilmAssemblyFragment(options: FilmAssemblyFragmentOptions)inputs: {program: input("program"),canvas: input("canvas"),- semantic: input("semantic"),+ space: operation("film:space"),set: operation(current),},result: { kind: "output" as const, name: "composition" },diff --git a/packages/film/src/manifest.ts b/packages/film/src/manifest.tsindex 5cf9ba44..c0304c96 100644--- a/packages/film/src/manifest.ts+++ b/packages/film/src/manifest.ts@@ -1,4 +1,5 @@import { audioTrackSchema, compositionDependency, compositionTypes, visualTrackSchema } from "@hypit/composition";+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";import { spatialDependency, spatialTypes } from "@hypit/spatial";@@ -99,6 +100,7 @@ export const filmManifest: ModuleManifest = {name: filmModuleRef.name,version: filmModuleRef.version,dependencies: [+ programSpaceDependency,semanticTrackDependency,spatialDependency,compositionDependency,@@ -120,7 +122,7 @@ export const filmManifest: ModuleManifest = {name: filmProducers.appendVisualTrack.name,inputs: [{ name: "set", type: filmTypes.trackSet },- { name: "semantic", type: semanticTrackTypes.track },+ { name: "space", type: programSpaceTypes.programSpace },{ name: "track", type: compositionTypes.visualTrack },],outputs: [{ name: "set", type: filmTypes.trackSet }],@@ -130,7 +132,7 @@ export const filmManifest: ModuleManifest = {name: filmProducers.appendAudioTrack.name,inputs: [{ name: "set", type: filmTypes.trackSet },- { name: "semantic", type: semanticTrackTypes.track },+ { name: "space", type: programSpaceTypes.programSpace },{ name: "track", type: compositionTypes.audioTrack },],outputs: [{ name: "set", type: filmTypes.trackSet }],@@ -141,7 +143,7 @@ export const filmManifest: ModuleManifest = {inputs: [{ name: "program", type: filmTypes.program },{ name: "canvas", type: spatialTypes.canvas },- { name: "semantic", type: semanticTrackTypes.track },+ { name: "space", type: programSpaceTypes.programSpace },{ name: "set", type: filmTypes.trackSet },],outputs: [{ name: "composition", type: compositionTypes.composition }],diff --git a/packages/film/test/film.test.ts b/packages/film/test/film.test.tsindex 41665ec7..61fcedad 100644--- a/packages/film/test/film.test.ts+++ b/packages/film/test/film.test.ts@@ -1,7 +1,7 @@import { compositionComponent, spatialComponent, videoContractManifests } from "../../../test/support/video-domain.js";import { registerTypeValidatorFacets } from "@hypit/component-kit";import { programSpaceTypes, sealProgramSpace } from "@hypit/program-space";-import { projectSemanticProgramSpace, semanticTrackTypes } from "@hypit/semantic-track";+import { projectSemanticProgramSpace, semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import type { SemanticTrack } from "@hypit/semantic-track";import { compositionTypes, sealAudioTrack, sealVisualTrack } from "@hypit/composition";import type { Composition, Track } from "@hypit/composition";@@ -35,7 +35,7 @@ import { renderTypographyTrack, sealTypographyTrackProgram, stillTextMotion, typimport type { TextStyle } from "@hypit/typography-track";import { admitRecord, TypeValidatorRegistry } from "@hypit/validation";-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 4,frameRate: { numerator: 30, denominator: 1 },});@@ -102,7 +102,7 @@ const textProgram = sealTypographyTrackProgram({motion: stillTextMotion(),}],});-const background = sealVisualTrack({+const background = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "background-track",presents: [{@@ -112,7 +112,7 @@ const background = sealVisualTrack({elements: [{ id: "root", kind: "box", order: 0, style: [{ name: "background-color", value: "#223344" }] }],}],});-const audio = sealAudioTrack({+const audio = sealAudioTrack({ programSpaceId: "test-space",id: "empty-audio-track",clips: [],});@@ -213,7 +213,10 @@ function producerModules(target: string): string[] {}test("Film stops at Composition and Hyperframes remains an ordinary downstream Fragment", () => {- assert.deepEqual(producerNames("title.track"), [typographyTrackProducers.render.name]);+ assert.deepEqual(producerNames("title.track"), [+ typographyTrackProducers.render.name,+ semanticTrackProducers.projectProgramSpace.name,+ ]);assert.equal(producerModules("main.composition").includes(hyperframesProducers.compile.module.name), false);assert.deepEqual(producerNames("main.composition").filter((name) => name.startsWith("append-")).sort(), [filmProducers.appendAudioTrack.name,@@ -228,9 +231,13 @@ test("Film stops at Composition and Hyperframes remains an ordinary downstream Ftest("the Driver folds peer Tracks, then independently compiles the Composition", async () => {const registry = new ProducerRegistry();+ registry.registerProducer(semanticTrackProducers.projectProgramSpace, ({ inputs }) => ({+ outputs: { space: stored(projectSemanticProgramSpace(inline(inputs.track) as SemanticTrack)) },+ needs: {},+ }));registry.registerProducer(typographyTrackProducers.render, ({ inputs }) => ({outputs: { track: stored(renderTypographyTrack(- projectSemanticProgramSpace(inline(inputs.semantic) as SemanticTrack),+ inline(inputs.space) as typeof space,inline(inputs.program) as typeof textProgram,)) },needs: {},@@ -242,7 +249,7 @@ test("the Driver folds peer Tracks, then independently compiles the Composition"registry.registerProducer(filmProducers.appendVisualTrack, ({ inputs }) => ({outputs: { set: stored(appendFilmVisualTrack(inline(inputs.set) as never,- projectSemanticProgramSpace(inline(inputs.semantic) as SemanticTrack),+ inline(inputs.space) as typeof space,inline(inputs.track) as never,)) },needs: {},@@ -250,7 +257,7 @@ test("the Driver folds peer Tracks, then independently compiles the Composition"registry.registerProducer(filmProducers.appendAudioTrack, ({ inputs }) => ({outputs: { set: stored(appendFilmAudioTrack(inline(inputs.set) as never,- projectSemanticProgramSpace(inline(inputs.semantic) as SemanticTrack),+ inline(inputs.space) as typeof space,inline(inputs.track) as never,)) },needs: {},@@ -259,7 +266,7 @@ test("the Driver folds peer Tracks, then independently compiles the Composition"outputs: { composition: stored(compileFilmComposition(inline(inputs.program) as never,inline(inputs.canvas) as typeof canvas,- projectSemanticProgramSpace(inline(inputs.semantic) as SemanticTrack),+ inline(inputs.space) as typeof space,inline(inputs.set) as never,)) },needs: {},@@ -284,6 +291,6 @@ test("the Driver folds peer Tracks, then independently compiles the Composition"test("Film rejects duplicate Track ids before Composition", () => {const set = appendFilmVisualTrack(createFilmTrackSet(), space, background);- const duplicate = sealVisualTrack({ ...background });+ const duplicate = sealVisualTrack({...background });assert.throws(() => appendFilmVisualTrack(set, space, duplicate), /already contains Track id/u);});diff --git a/packages/film/test/surface.test.ts b/packages/film/test/surface.test.tsindex 0253b7be..f36f22a8 100644--- a/packages/film/test/surface.test.ts+++ b/packages/film/test/surface.test.ts@@ -1,7 +1,7 @@import { compositionComponent, spatialComponent, videoContractManifests } from "../../../test/support/video-domain.js";import { registerTypeValidatorFacets } from "@hypit/component-kit";import { programSpaceDependency, programSpaceTypes, sealProgramSpace } from "@hypit/program-space";-import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackDependency, semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { compositionDependency, compositionTypes, sealAudioTrack, sealVisualTrack } from "@hypit/composition";import type { Track } from "@hypit/composition";import assert from "node:assert/strict";@@ -57,17 +57,17 @@ const fixtureManifest: ModuleManifest = {producers: [],};-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 2,frameRate: { numerator: 30, denominator: 1 },});const semantic = semanticTrackFixture(space);-const visual = sealVisualTrack({+const visual = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "visual",presents: [],});-const audio = sealAudioTrack({+const audio = sealAudioTrack({ programSpaceId: "test-space",id: "audio",clips: [],});@@ -172,6 +172,7 @@ test("the official Film Surface validates SVS and lowers dynamic peer Tracks", afilmProducers.appendAudioTrack.name,filmProducers.appendVisualTrack.name,filmProducers.compileComposition.name,+ semanticTrackProducers.projectProgramSpace.name,].sort());});diff --git a/packages/hyperframes/test/document.test.ts b/packages/hyperframes/test/document.test.tsindex aecdaa3d..8aeae4bf 100644--- a/packages/hyperframes/test/document.test.ts+++ b/packages/hyperframes/test/document.test.ts@@ -22,7 +22,7 @@ const fixtureFont: FontArtifactRef = {};function fixture() {- const programSpace = sealProgramSpace({+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 1001 / 1000,frameRate: { numerator: 30_000, denominator: 1_001 },});@@ -38,7 +38,7 @@ function fixture() {size: 20,mediaType: "audio/wav",};- const lower = sealVisualTrack({+ const lower = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "lower",presents: [{@@ -54,7 +54,7 @@ function fixture() {}],}],});- const upper = sealVisualTrack({+ const upper = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "upper",presents: [{@@ -67,7 +67,7 @@ function fixture() {],}],});- const audio = sealAudioTrack({+ const audio = sealAudioTrack({ programSpaceId: "test-space",id: "sound",clips: [{id: "main",@@ -162,8 +162,7 @@ test("HyperFrames emits frame-bound local animation without creating a Track staassert(lower?.kind === "visual");const present = lower.presents[0]!;const media = present.elements[0]!;- const animated = sealVisualTrack({- ...lower,+ const animated = sealVisualTrack({...lower,presents: [{...present,elements: [{@@ -195,8 +194,7 @@ test("HyperFrames clips a long animation by Present visibility instead of rejectassert(lower?.kind === "visual");const present = lower.presents[0]!;const media = present.elements[0]!;- const animated = sealVisualTrack({- ...lower,+ const animated = sealVisualTrack({...lower,presents: [{ ...present, elements: [{ ...media, animation: { keyframes: [{ atFrame: 0, style: [{ name: "opacity", value: 0 }] },{ atFrame: 45, style: [{ name: "opacity", value: 1 }] },@@ -212,7 +210,7 @@ test("HyperFrames clips a long animation by Present visibility instead of reject});test("content-bound fonts and typed compositable Surfaces cross the same Artifact boundary", () => {- const space = sealProgramSpace({+ const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 1,frameRate: { numerator: 30, denominator: 1 },});@@ -227,7 +225,7 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifacstyle: "normal",};const surfaceDigest = fixtureDigest("hyperframes:alpha-surface");- const track = sealVisualTrack({+ const track = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "bound-render-dependencies",presents: [{@@ -287,7 +285,7 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac});test("exact timed sampling lowers loop boundaries and held frames without zero-rate browser media", () => {- const programSpace = sealProgramSpace({+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 8 / 30,frameRate: { numerator: 30, denominator: 1 },});@@ -297,7 +295,7 @@ test("exact timed sampling lowers loop boundaries and held frames without zero-rsize: 1_000,mediaType: "video/mp4",};- const track = sealVisualTrack({+ const track = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "sampled",presents: [{@@ -352,11 +350,11 @@ test("a Track naming five takes still lowers to DOM identities a Windows path caconst trackId = "speech-visual:opening-monologue-take-1+opening-monologue-take-2"+ "+opening-monologue-take-3+opening-monologue-take-4+opening-monologue-take-5";const presentId = `${trackId}:clip-1`;- const programSpace = sealProgramSpace({+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 8 / 30,frameRate: { numerator: 30, denominator: 1 },});- const track = sealVisualTrack({+ const track = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: trackId,presents: [{diff --git a/packages/media-execution/src/execute.ts b/packages/media-execution/src/execute.tsindex 0ce2e771..0128c4af 100644--- a/packages/media-execution/src/execute.ts+++ b/packages/media-execution/src/execute.ts@@ -22,7 +22,9 @@ import {type NormalizeMediaNeed,type ProjectSpeechEvidenceAudioNeed,type RenderAudioNeed,+ type RenderStillVideoNeed,type TransformMediaNeed,+ verifyStillVideoRequest,} from "@hypit/media-pipeline";import type { AudioProgramClip, AudioProgramPlan, MediaTransformOperation } from "@hypit/media-pipeline";import {@@ -483,6 +485,14 @@ function extractFrameNeed(value: CanonicalValue): ExtractFrameNeed {return item;}+function renderStillVideoNeed(value: CanonicalValue): RenderStillVideoNeed {+ const item = object(value, "RenderStillVideoNeed") as unknown as RenderStillVideoNeed;+ assert(item.source?.kind === "blob" && item.source.mediaType.startsWith("image/"),+ "RenderStillVideoNeed source must be an image Artifact");+ verifyStillVideoRequest(item.request);+ return item;+}+function evidenceAudioNeed(value: CanonicalValue): ProjectSpeechEvidenceAudioNeed {const item = object(value, "ProjectSpeechEvidenceAudioNeed") as unknown as ProjectSpeechEvidenceAudioNeed;assert(item.source?.kind === "blob", "ProjectSpeechEvidenceAudioNeed is invalid");@@ -723,6 +733,64 @@ export async function executeNormalizeMedia(}}+/** Encode one authored image into an exact silent CFR video. */+export async function executeRenderStillVideo(+ env: MediaExecutionEnvironment,+ constraints: CanonicalValue,+): Promise<MediaOperationResult> {+ const need = renderStillVideoNeed(constraints);+ const work = await mkdtemp(join(tmpdir(), "hypit-media-still-"));+ try {+ const input = join(work, "source.image");+ const output = join(work, "still.mp4");+ await stageArtifact(env, need.source, input);+ const fps = `${need.request.frameRate.numerator}/${need.request.frameRate.denominator}`;+ const filter = [+ "select=eq(n\\,0)",+ "loop=loop=-1:size=1:start=0",+ `trim=start_frame=0:end_frame=${need.request.frameCount}`,+ `setpts=N*${need.request.frameRate.denominator}/(${need.request.frameRate.numerator}*TB)`,+ "pad=ceil(iw/2)*2:ceil(ih/2)*2:(ow-iw)/2:(oh-ih)/2:color=black",+ "setsar=1",+ ].join(",");+ await runProcess({+ executable: env.ffmpegPath,+ argv: [+ "-y", "-i", input, "-map", "0:v:0", "-an", "-vf", filter,+ "-frames:v", String(need.request.frameCount), "-r", fps, "-fps_mode", "cfr",+ "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p",+ "-movflags", "+faststart", output,+ ],+ timeoutMs: env.processTimeoutMs,+ maxStdoutBytes: 64 * 1024,+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),+ });+ const inspected = await outputInspection({+ path: output,+ mediaType: "video/mp4",+ ffprobePath: env.ffprobePath,+ timeoutMs: env.processTimeoutMs,+ maxProbeOutputBytes: env.maxProbeOutputBytes,+ ...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),+ });+ const videos = inspected.streams.filter((item): item is MediaVideoStream => item.kind === "video");+ assert(videos.length === 1 && inspected.streams.length === 1+ && videos[0]!.decodedUnitCount === need.request.frameCount,+ "Still media output differs from its requested frame domain");+ const visual = videos[0]!;+ assert(visual.sampleAspectRatio.numerator === 1 && visual.sampleAspectRatio.denominator === 1+ && visual.rotationDegrees === 0,+ "Still media output retains non-square samples or display rotation");+ assert(visual.averageFrameRate !== undefined+ && visual.averageFrameRate.numerator * need.request.frameRate.denominator+ === need.request.frameRate.numerator * visual.averageFrameRate.denominator,+ "Still media output differs from its requested frame rate");+ return artifactResult(await env.artifacts.putFile(output, "video/mp4"));+ } finally {+ await rm(work, { recursive: true, force: true }).catch(() => {});+ }+}+type TransformPlan = {readonly videoFilters: readonly string[];readonly audioFilters: readonly string[];diff --git a/packages/media-execution/src/index.ts b/packages/media-execution/src/index.tsindex 274a4a0c..fcc10457 100644--- a/packages/media-execution/src/index.ts+++ b/packages/media-execution/src/index.ts@@ -6,6 +6,7 @@ export {executeNormalizeMedia,executeProjectSpeechEvidenceAudio,executeRenderTimelineAudio,+ executeRenderStillVideo,executeTransformMedia,} from "./execute.js";export { parseMediaInspection } from "./probe.js";diff --git a/packages/media-execution/src/toolchain.ts b/packages/media-execution/src/toolchain.tsindex f2ceea2d..5e76f6d2 100644--- a/packages/media-execution/src/toolchain.ts+++ b/packages/media-execution/src/toolchain.ts@@ -5,7 +5,10 @@ export type MediaToolchainState =| { readonly state: "down" | "mismatch"; readonly detail: string };const REQUIRED_ENCODERS = ["aac", "libx264", "pcm_s16le"] as const;-const REQUIRED_FILTERS = ["aformat", "amix", "aresample", "asetpts", "atempo", "atrim", "scale", "setsar"] as const;+const REQUIRED_FILTERS = [+ "aformat", "amix", "aresample", "asetpts", "atempo", "atrim",+ "loop", "pad", "scale", "select", "setpts", "setsar", "trim",+] as const;function run(executable: string, args: readonly string[]): Promise<{ ok: boolean; output: string }> {return new Promise((resolve) => {diff --git a/packages/media-pipeline/README.md b/packages/media-pipeline/README.mdindex b6871300..e8fde4be 100644--- a/packages/media-pipeline/README.md+++ b/packages/media-pipeline/README.md@@ -43,7 +43,21 @@ The frame clock is a separate program fact and can be shared by every NormalizeAn SVS recipe may centralize the stream policy (`video`, `audio` and `span-authority`); it does nothide the Normalize graph node or turn multiple sources into one opaque batch operation.-Three ordinary author operations reuse that same inspection/execution boundary:+A still image becomes ordinary video before it enters that waist:++```svml+<media:StillVideo id="opening-still" source={opening-head}+ duration={opening-duration.duration} clock={clock}/>+<pipeline:Normalize id="opening-media" source={opening-still.video}+ video="primary-moving" audio="none" span-authority="video" clock={clock}/>+```++`StillVideo` returns a silent MP4 `BlobArtifact`, not `SynchronizedMedia`. Encoding its first decoded+image frame is a `render-still-video` Need; inspection and normalization remain the same explicit+steps used by imported or generated moving video. The Blob can therefore serve B-roll through+Normalize, or continue into either estimated or measured A-roll semantics afterward.++Four ordinary author operations reuse that same inspection/execution boundary:```xml<pipeline:Normalize id="shot-media" source={shot.video}diff --git a/packages/media-pipeline/src/activation.ts b/packages/media-pipeline/src/activation.tsindex e20e3be4..631664c4 100644--- a/packages/media-pipeline/src/activation.ts+++ b/packages/media-pipeline/src/activation.ts@@ -1,6 +1,7 @@import { createMarkupSurfaceHostFacet } from "@hypit/markup";import {decodeSynchronizedMediaSurface,+ decodeStillVideoSurface,decodeExtractAudioSurface,decodeExtractFrameSurface,decodeTransformMediaSurface,@@ -18,6 +19,10 @@ export const hypitPackage = {module: mediaPipelineModuleRef,declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "synchronized-media")!,handler: decodeSynchronizedMediaSurface,+ }), createMarkupSurfaceHostFacet({+ module: mediaPipelineModuleRef,+ declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "still-video")!,+ handler: decodeStillVideoSurface,}), createMarkupSurfaceHostFacet({module: mediaPipelineModuleRef,declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "transform-media")!,diff --git a/packages/media-pipeline/src/audio-plan.ts b/packages/media-pipeline/src/audio-plan.tsindex db47d1c0..918379a1 100644--- a/packages/media-pipeline/src/audio-plan.ts+++ b/packages/media-pipeline/src/audio-plan.ts@@ -23,6 +23,8 @@ export function verifyAudioProgramPlan(value: unknown): asserts value is AudioPrassert(Number.isSafeInteger(item.frameCount) && item.frameCount > 0, "AudioProgramPlan frame count is invalid");assert(item.sampleRate === 48_000, "AudioProgramPlan sample rate must be 48000");const planSpace = {+ id: "audio-program-plan",+ narrativeId: "audio-program-plan",durationSec: item.frameCount * item.frameRate.denominator / item.frameRate.numerator,frameRate: item.frameRate,};diff --git a/packages/media-pipeline/src/component.ts b/packages/media-pipeline/src/component.tsindex 1d2d1083..2d8bab94 100644--- a/packages/media-pipeline/src/component.ts+++ b/packages/media-pipeline/src/component.ts@@ -2,8 +2,10 @@ import { mediaComponent } from "@hypit/media";import type { ComponentPackage } from "@hypit/component-kit";import { synchronizedMediaSampleFrames, verifyMediaInspection, verifyMediaStreamSelection, verifyMuxedMedia, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "@hypit/media";import type { MediaInspection, MediaStreamSelection, MuxedMedia, RenderedVisual, SynchronizedMedia, TimelineAudio } from "@hypit/media";-import type { ProgramSpace } from "@hypit/program-space";-import { speechEvidenceSampleBoundary } from "@hypit/speech";+import { assertProgramClockIdentity } from "@hypit/program-space";+import type { ProgramClock, ProgramSpace } from "@hypit/program-space";+import { assertSpeechDurationIdentity, speechEvidenceSampleBoundary } from "@hypit/speech";+import type { SpeechDuration } from "@hypit/speech";import type { Composition } from "@hypit/composition";import type { BlobRef, CanonicalValue, StoredValue } from "@hypit/protocol";import { canonicalize } from "@hypit/protocol";@@ -20,9 +22,11 @@ import {import {selectAudioStream,selectVideoStream,+ sealStillVideoRequest,verifyAudioExtractionRequest,verifyFrameExtractionRequest,verifyMediaTransformProgram,+ verifyStillVideoRequest,} from "./operations.js";import type {AudioExtractionRequest,@@ -35,6 +39,8 @@ import type {NormalizeMediaNeed,ProjectSpeechEvidenceAudioNeed,RenderAudioNeed,+ RenderStillVideoNeed,+ StillVideoRequest,TransformMediaNeed,} from "./types.js";@@ -80,6 +86,12 @@ export const mediaPipelineComponent = {verifyFrameExtractionRequest(inline(value, "FrameExtractionRequest"));},},+ {+ type: mediaPipelineTypes.stillVideoRequest,+ handler: ({ value }) => {+ verifyStillVideoRequest(inline(value, "StillVideoRequest"));+ },+ },],producers: [{@@ -179,6 +191,36 @@ export const mediaPipelineComponent = {return { outputs: {}, needs: { image: canonicalize(need) } };},},+ {+ producer: mediaPipelineProducers.planStill,+ handler: ({ inputs }) => {+ const duration = inline(inputs.duration!.value, "SpeechDuration") as unknown as SpeechDuration;+ const clock = inline(inputs.clock!.value, "ProgramClock") as unknown as ProgramClock;+ assertSpeechDurationIdentity(duration);+ assertProgramClockIdentity(clock);+ const frames = Math.round(duration * clock.frameRate.numerator / clock.frameRate.denominator);+ if (!Number.isSafeInteger(frames) || frames < 1) {+ throw new Error("Still video duration does not produce a positive safe frame count");+ }+ const request = sealStillVideoRequest({+ frameRate: clock.frameRate,+ frameCount: frames,+ output: { container: "mp4", codec: "h264", pixelFormat: "yuv420p" },+ });+ return { outputs: { request: { kind: "inline", value: canonicalize(request) } }, needs: {} };+ },+ },+ {+ producer: mediaPipelineProducers.renderStill,+ handler: ({ inputs }) => {+ const source = blob(inputs.source!.value, "Still video source");+ const request = inline(inputs.request!.value, "StillVideoRequest") as unknown as StillVideoRequest;+ if (!source.mediaType.startsWith("image/")) throw new Error("Still video source must be an image Artifact");+ verifyStillVideoRequest(request);+ const need: RenderStillVideoNeed = { source, request };+ return { outputs: {}, needs: { video: canonicalize(need) } };+ },+ },{producer: mediaPipelineProducers.projectSpeechEvidenceAudio,handler: ({ inputs }) => {diff --git a/packages/media-pipeline/src/fragment.ts b/packages/media-pipeline/src/fragment.tsindex 2acd5735..c4a927b1 100644--- a/packages/media-pipeline/src/fragment.ts+++ b/packages/media-pipeline/src/fragment.ts@@ -1,5 +1,7 @@import { mediaTypes } from "@hypit/media";import { artifactTypes } from "@hypit/artifact";+import { programSpaceTypes } from "@hypit/program-space";+import { speechTypes } from "@hypit/speech";import { sealGraphFragment } from "@hypit/elaborator";import {@@ -118,3 +120,30 @@ export const extractFrameFragment = sealGraphFragment({root: operation("extract"),}],});++export const stillVideoFragment = sealGraphFragment({+ inputs: [+ { name: "source", type: artifactTypes.blob },+ { name: "duration", type: speechTypes.duration },+ { name: "clock", type: programSpaceTypes.clock },+ ],+ operations: [+ {+ id: "plan",+ producer: mediaPipelineProducers.planStill,+ inputs: { duration: input("duration"), clock: input("clock") },+ result: { kind: "output", name: "request" },+ },+ {+ id: "render",+ producer: mediaPipelineProducers.renderStill,+ inputs: { source: input("source"), request: operation("plan") },+ result: { kind: "need", name: "video" },+ },+ ],+ exports: [{+ name: "video",+ type: artifactTypes.blob,+ root: operation("render"),+ }],+});diff --git a/packages/media-pipeline/src/index.ts b/packages/media-pipeline/src/index.tsindex 5c9b50bd..bc1d13ba 100644--- a/packages/media-pipeline/src/index.ts+++ b/packages/media-pipeline/src/index.ts@@ -6,6 +6,7 @@ export {extractAudioFragment,extractFrameFragment,synchronizedMediaFragment,+ stillVideoFragment,transformMediaFragment,} from "./fragment.js";export {@@ -13,13 +14,13 @@ export {sealAudioProgramPlan,verifyAudioProgramPlan,} from "./audio-plan.js";-export { mediaPipelineCapabilities, mediaPipelineManifest, mediaPipelineMarkupSurfaces, mediaPipelineModuleRef, mediaPipelineProducers, mediaPipelineTypes, audioProgramPlanSchema, mediaSelectionRequestSchema, audioExtractionRequestSchema, frameExtractionRequestSchema, mediaTransformProgramSchema } from "./manifest.js";+export { mediaPipelineCapabilities, mediaPipelineManifest, mediaPipelineMarkupSurfaces, mediaPipelineModuleRef, mediaPipelineProducers, mediaPipelineTypes, audioProgramPlanSchema, mediaSelectionRequestSchema, audioExtractionRequestSchema, frameExtractionRequestSchema, stillVideoRequestSchema, mediaTransformProgramSchema } from "./manifest.js";export {sealMediaSelectionRequest,selectMediaStreams,verifyMediaSelectionRequest,} from "./selection.js";-export { decodeSynchronizedMediaSurface } from "./surface.js";+export { decodeSynchronizedMediaSurface, decodeStillVideoSurface } from "./surface.js";export {decodeExtractAudioSurface,decodeExtractFrameSurface,@@ -29,10 +30,12 @@ export {sealAudioExtractionRequest,sealFrameExtractionRequest,sealMediaTransformProgram,+ sealStillVideoRequest,selectAudioStream,selectVideoStream,verifyAudioExtractionRequest,verifyFrameExtractionRequest,verifyMediaTransformProgram,+ verifyStillVideoRequest,} from "./operations.js";export type * from "./types.js";diff --git a/packages/media-pipeline/src/manifest.ts b/packages/media-pipeline/src/manifest.tsindex 6391f956..e0809025 100644--- a/packages/media-pipeline/src/manifest.ts+++ b/packages/media-pipeline/src/manifest.ts@@ -20,6 +20,7 @@ export const mediaPipelineTypes = {transformProgram: { module: mediaPipelineModuleRef, name: "MediaTransformProgram" },audioExtractionRequest: { module: mediaPipelineModuleRef, name: "AudioExtractionRequest" },frameExtractionRequest: { module: mediaPipelineModuleRef, name: "FrameExtractionRequest" },+ stillVideoRequest: { module: mediaPipelineModuleRef, name: "StillVideoRequest" },} satisfies Record<string, TypeRef>;export const mediaPipelineCapabilities = {inspect: { module: mediaPipelineModuleRef, name: "inspect-media" },@@ -27,6 +28,7 @@ export const mediaPipelineCapabilities = {transform: { module: mediaPipelineModuleRef, name: "transform-media" },extractAudio: { module: mediaPipelineModuleRef, name: "extract-media-audio" },extractFrame: { module: mediaPipelineModuleRef, name: "extract-media-frame" },+ renderStill: { module: mediaPipelineModuleRef, name: "render-still-video" },projectSpeechEvidenceAudio: { module: mediaPipelineModuleRef, name: "project-speech-evidence-audio" },renderAudio: { module: mediaPipelineModuleRef, name: "render-timeline-audio" },mux: { module: mediaPipelineModuleRef, name: "mux-program-media" },@@ -38,6 +40,8 @@ export const mediaPipelineProducers = {transform: { module: mediaPipelineModuleRef, name: "request-media-transform" },extractAudio: { module: mediaPipelineModuleRef, name: "request-audio-extraction" },extractFrame: { module: mediaPipelineModuleRef, name: "request-frame-extraction" },+ planStill: { module: mediaPipelineModuleRef, name: "plan-still-video" },+ renderStill: { module: mediaPipelineModuleRef, name: "request-still-video" },projectSpeechEvidenceAudio: { module: mediaPipelineModuleRef, name: "request-speech-evidence-audio" },planAudio: { module: mediaPipelineModuleRef, name: "compile-audio-program" },renderAudio: { module: mediaPipelineModuleRef, name: "request-audio-render" },@@ -145,6 +149,28 @@ export const frameExtractionRequestSchema: ValueSchema = {},};+export const stillVideoRequestSchema: ValueSchema = {+ kind: "object",+ fields: {+ frameRate: { schema: {+ kind: "object",+ fields: {+ numerator: { schema: { kind: "number", integer: true, minimum: 1 } },+ denominator: { schema: { kind: "number", integer: true, minimum: 1 } },+ },+ } },+ frameCount: { schema: { kind: "number", integer: true, minimum: 1 } },+ output: { schema: {+ kind: "object",+ fields: {+ container: { schema: { kind: "literal", value: "mp4" } },+ codec: { schema: { kind: "literal", value: "h264" } },+ pixelFormat: { schema: { kind: "literal", value: "yuv420p" } },+ },+ } },+ },+};+const blobRefSchema: ValueSchema = {kind: "object",fields: {@@ -237,6 +263,32 @@ export const mediaPipelineMarkupSurfaces = [],},},+ {+ name: "still-video", tag: "StillVideo", mode: "structured",+ outputs: [mediaPipelineTypes.stillVideoRequest, artifactTypes.blob],+ vocabulary: {+ summary: "Encodes one authored image as an ordinary silent MP4 Blob on an explicit duration and frame clock.",+ attributes: [+ { name: "id", kind: "identifier", required: true,+ summary: "Names the still-video operation and the MP4 Artifact it publishes." },+ { name: "source", kind: "reference", required: true, accepts: [artifactTypes.blob],+ summary: "Selects the authored image whose first decoded frame is held for the full video." },+ { name: "duration", kind: "reference", required: true, accepts: [speechTypes.duration],+ summary: "Selects the positive duration used to establish the video's finite frame count." },+ { name: "clock", kind: "reference", required: true, accepts: [programSpaceTypes.clock],+ summary: "Selects the frame clock used by the generated MP4." },+ ],+ ports: [{ name: "video", type: artifactTypes.blob,+ summary: "The ordinary silent MP4 Artifact, addressed as `<id>.video`." }],+ example: `<media:StillVideo id="opening-still" source={opening-head}+ duration={opening-duration.duration} clock={clock}/>`,+ notes: [+ "The result is a normal video Blob, not SynchronizedMedia and not a SemanticTake.",+ "Use Normalize afterward exactly as for generated or imported moving video.",+ "Encoding is a render-still-video Need fulfilled by the selected media Provider; this Surface never invokes FFmpeg itself.",+ ],+ },+ },{name: "transform-media", tag: "Transform", mode: "structured",outputs: [mediaPipelineTypes.transformProgram, artifactTypes.blob],@@ -370,6 +422,9 @@ export const mediaPipelineManifest: ModuleManifest = {{name: mediaPipelineTypes.frameExtractionRequest.name,},+ {+ name: mediaPipelineTypes.stillVideoRequest.name,+ },],capabilities: [{ name: mediaPipelineCapabilities.inspect.name, returns: mediaTypes.inspection },@@ -377,6 +432,7 @@ export const mediaPipelineManifest: ModuleManifest = {{ name: mediaPipelineCapabilities.transform.name, returns: artifactTypes.blob },{ name: mediaPipelineCapabilities.extractAudio.name, returns: artifactTypes.blob },{ name: mediaPipelineCapabilities.extractFrame.name, returns: artifactTypes.blob },+ { name: mediaPipelineCapabilities.renderStill.name, returns: artifactTypes.blob },{ name: mediaPipelineCapabilities.projectSpeechEvidenceAudio.name, returns: speechTypes.evidenceAudio },{ name: mediaPipelineCapabilities.renderAudio.name, returns: mediaTypes.timelineAudio },{ name: mediaPipelineCapabilities.mux.name, returns: mediaTypes.muxed },@@ -460,6 +516,28 @@ export const mediaPipelineManifest: ModuleManifest = {returns: artifactTypes.blob,}],},+ {+ name: mediaPipelineProducers.planStill.name,+ inputs: [+ { name: "duration", type: speechTypes.duration },+ { name: "clock", type: programSpaceTypes.clock },+ ],+ outputs: [{ name: "request", type: mediaPipelineTypes.stillVideoRequest }],+ needs: [],+ },+ {+ name: mediaPipelineProducers.renderStill.name,+ inputs: [+ { name: "source", type: artifactTypes.blob },+ { name: "request", type: mediaPipelineTypes.stillVideoRequest },+ ],+ outputs: [],+ needs: [{+ name: "video",+ capability: mediaPipelineCapabilities.renderStill,+ returns: artifactTypes.blob,+ }],+ },{name: mediaPipelineProducers.projectSpeechEvidenceAudio.name,inputs: [{ name: "media", type: mediaTypes.synchronized }],diff --git a/packages/media-pipeline/src/operations.ts b/packages/media-pipeline/src/operations.tsindex 183b572e..ae8d6554 100644--- a/packages/media-pipeline/src/operations.ts+++ b/packages/media-pipeline/src/operations.ts@@ -8,6 +8,7 @@ import type {MediaAudioSelector,MediaTransformProgram,MediaVideoSelector,+ StillVideoRequest,} from "./types.js";function assert(condition: unknown, message: string): asserts condition {@@ -113,6 +114,25 @@ export function sealFrameExtractionRequest(value: FrameExtractionRequest): Framereturn result;}+export function verifyStillVideoRequest(value: unknown): asserts value is StillVideoRequest {+ const request = object(value, "StillVideoRequest");+ const frameRate = object(request.frameRate, "StillVideoRequest.frameRate");+ assert(Number.isSafeInteger(frameRate.numerator) && (frameRate.numerator as number) > 0+ && Number.isSafeInteger(frameRate.denominator) && (frameRate.denominator as number) > 0,+ "StillVideoRequest.frameRate must be a positive rational");+ assert(Number.isSafeInteger(request.frameCount) && (request.frameCount as number) > 0,+ "StillVideoRequest.frameCount must be positive");+ const output = object(request.output, "StillVideoRequest.output");+ assert(output.container === "mp4" && output.codec === "h264" && output.pixelFormat === "yuv420p",+ "StillVideoRequest output profile is unsupported");+}++export function sealStillVideoRequest(value: StillVideoRequest): StillVideoRequest {+ const result = canonicalize(value) as unknown as StillVideoRequest;+ verifyStillVideoRequest(result);+ return result;+}+function uniqueDefault<T extends { readonly disposition: { readonly default: boolean }; readonly index: number }>(values: readonly T[],subject: string,diff --git a/packages/media-pipeline/src/surface.ts b/packages/media-pipeline/src/surface.tsindex 6eb9b9d3..7a6de16a 100644--- a/packages/media-pipeline/src/surface.ts+++ b/packages/media-pipeline/src/surface.ts@@ -10,12 +10,14 @@ import {import { sameType, type CanonicalValue } from "@hypit/protocol";import { artifactTypes } from "@hypit/artifact";import { mediaTypes } from "@hypit/media";+import { speechTypes } from "@hypit/speech";import { programSpaceTypes, type ProgramClock } from "@hypit/program-space";import { svsRecipeType, type SvsRecipe } from "@hypit/svs";import {extractAudioFragment,extractFrameFragment,+ stillVideoFragment,synchronizedMediaFragment,transformMediaFragment,} from "./fragment.js";@@ -226,6 +228,36 @@ export const decodeSynchronizedMediaSurface: StructuredSurfaceHandler = ({ eleme};};+export const decodeStillVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {+ exactAttributes(element, ["id", "source", "duration", "clock"]);+ empty(element);+ const id = text(element, "id");+ const source = ref(element.attributes.source, `${element.name}.source`, resolveReference);+ const duration = typedReference(+ element.attributes.duration,+ `${element.name}.duration`,+ speechTypes.duration,+ resolveReference,+ );+ const clock = typedReference(+ element.attributes.clock,+ `${element.name}.clock`,+ programSpaceTypes.clock,+ resolveReference,+ );+ return {+ records: [],+ components: [{+ id,+ fragment: stillVideoFragment.id,+ inputs: { source: source.ref, duration: duration.ref, clock: clock.ref },+ outputs: { video: `${id}.video` },+ range: element.range,+ }],+ fragments: [stillVideoFragment],+ };+};+export const decodeTransformMediaSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {exactAttributes(element, ["id", "source"]);const id = text(element, "id");diff --git a/packages/media-pipeline/src/types.ts b/packages/media-pipeline/src/types.tsindex 49918200..8c9c0acd 100644--- a/packages/media-pipeline/src/types.ts+++ b/packages/media-pipeline/src/types.ts@@ -67,6 +67,17 @@ export type FrameExtractionRequest = {readonly output: { readonly format: "png" };};+/** Exact silent video requested from one authored still image. */+export type StillVideoRequest = {+ readonly frameRate: MediaRational;+ readonly frameCount: number;+ readonly output: {+ readonly container: "mp4";+ readonly codec: "h264";+ readonly pixelFormat: "yuv420p";+ };+};+export type TransformMediaNeed = {readonly media: import("@hypit/media").SynchronizedMedia;readonly program: MediaTransformProgram;@@ -86,6 +97,11 @@ export type ExtractFrameNeed = {readonly output: FrameExtractionRequest["output"];};+export type RenderStillVideoNeed = {+ readonly source: BlobRef;+ readonly request: StillVideoRequest;+};+export type NormalizeMediaNeed = {readonly source: BlobRef;readonly inspection: MediaInspection;diff --git a/packages/media-pipeline/test/manifest.test.ts b/packages/media-pipeline/test/manifest.test.tsindex d77cb8c3..92861a83 100644--- a/packages/media-pipeline/test/manifest.test.ts+++ b/packages/media-pipeline/test/manifest.test.ts@@ -1,6 +1,7 @@import { artifactTypes } from "@hypit/artifact";import { mediaTypes } from "@hypit/media";import { programSpaceTypes } from "@hypit/program-space";+import { speechTypes } from "@hypit/speech";import { svsRecipeType } from "@hypit/svs";import assert from "node:assert/strict";import test from "node:test";@@ -11,10 +12,12 @@ import {decodeExtractAudioSurface,decodeExtractFrameSurface,decodeTransformMediaSurface,+ decodeStillVideoSurface,extractAudioFragment,extractFrameFragment,synchronizedMediaFragment,transformMediaFragment,+ stillVideoFragment,} from "../src/index.js";test("the Normalize Surface makes inspection and normalization an explicit author graph branch", async () => {@@ -112,3 +115,33 @@ test("media operations are ordinary graph branches over BlobArtifact", async ()assert.equal(frame.fragments[0]?.id, extractFrameFragment.id);assert.deepEqual(frame.components[0]?.outputs, { image: "continuity.image" });});++test("StillVideo stops at an ordinary MP4 branch before Normalize", async () => {+ const range = { source: "still.svml", start: 0, end: 1 };+ const output = await decodeStillVideoSurface({+ sourceName: range.source,+ element: {+ kind: "element",+ name: "media:StillVideo",+ attributes: {+ id: "opening-still",+ source: { kind: "reference", path: "opening-head" },+ duration: { kind: "reference", path: "opening-duration.duration" },+ clock: { kind: "reference", path: "clock" },+ },+ children: [],+ range,+ },+ resolveReference: (path) => path === "opening-head"+ ? { path, ref: { kind: "record", id: path }, type: artifactTypes.blob }+ : path === "opening-duration.duration"+ ? { path, ref: { kind: "record", id: path }, type: speechTypes.duration }+ : path === "clock"+ ? { path, ref: { kind: "record", id: path }, type: programSpaceTypes.clock }+ : undefined,+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },+ });+ assert.equal(output.fragments[0]?.id, stillVideoFragment.id);+ assert.deepEqual(output.components[0]?.outputs, { video: "opening-still.video" });+ assert.equal(stillVideoFragment.exports[0]?.type.name, artifactTypes.blob.name);+});diff --git a/packages/media-track/README.md b/packages/media-track/README.mdindex 89f13726..13de6ed9 100644--- a/packages/media-track/README.md+++ b/packages/media-track/README.md@@ -12,7 +12,7 @@ activation points and pairwise Handoffs. Package-owned Recipes cover fitting, soframe Paint, clipping, borders, shadows, lifecycle motion and sampling motion.Ordinary Items consume projected `TemporalWindow` values. Sequence Member activations and the-Sequence terminal consume projected `TemporalPoint` values instead; the Sequence component owns+Sequence terminal consume projected `TemporalInstant` values instead; the Sequence component ownsonly the schedule and handoff consumption that follows those points. All domain Producers receiveProgramSpace explicitly and do not locate semantic sources themselves.diff --git a/packages/media-track/package.json b/packages/media-track/package.jsonindex 12d07fcc..89a87631 100644--- a/packages/media-track/package.json+++ b/packages/media-track/package.json@@ -24,5 +24,6 @@"@hypit/svs": "workspace:*","@hypit/markup": "workspace:*","@hypit/temporal": "workspace:*"+ ,"@hypit/temporal-markup": "workspace:*"}}diff --git a/packages/media-track/src/component.ts b/packages/media-track/src/component.tsindex 7b0ae521..1bfbd01a 100644--- a/packages/media-track/src/component.ts+++ b/packages/media-track/src/component.ts@@ -4,7 +4,7 @@ import { canonicalize } from "@hypit/protocol";import type { BlobRef, StoredValue } from "@hypit/protocol";import type { ProgramSpace } from "@hypit/program-space";import type { CanvasSpace, ContentFit, IntrinsicExtent, SpatialFrame, SpatialPath } from "@hypit/spatial";-import type { TemporalPoint, TemporalWindow } from "@hypit/temporal";+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";import {appendMediaPaintLayer,@@ -65,9 +65,10 @@ function itemInputs(inputs: ProducerHandlerContext["inputs"]) {function memberInputs(inputs: ProducerHandlerContext["inputs"]) {return {members: inline<MediaSequenceMemberSet>(inputs.members?.value, "MediaSequenceMemberSet"),+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),layers: inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),spec: inline<MediaSequenceMemberSpec>(inputs.spec?.value, "MediaSequenceMemberSpec"),- activation: inline<TemporalPoint>(inputs.activation?.value, "TemporalPoint"),+ activation: inline<TemporalInstant>(inputs.activation?.value, "TemporalInstant"),};}@@ -81,7 +82,7 @@ function sequenceInputs(inputs: ProducerHandlerContext["inputs"]) {frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),spec: inline<MediaSequenceSpec>(inputs.spec?.value, "MediaSequenceSpec"),sounds: inline<MediaSoundSet>(inputs.sounds?.value, "MediaSoundSet"),- terminal: inline<TemporalPoint>(inputs.terminal?.value, "TemporalPoint"),+ terminal: inline<TemporalInstant>(inputs.terminal?.value, "TemporalInstant"),};}@@ -128,7 +129,7 @@ export const mediaTrackComponent = {{ producer: mediaTrackProducers.appendMember, handler: ({ inputs }) => {const value = memberInputs(inputs);return { outputs: { members: output(appendMediaSequenceMember(- value.members, value.layers, value.spec, value.activation,+ value.members, value.space, value.layers, value.spec, value.activation,)) }, needs: {} };} },{ producer: mediaTrackProducers.appendSequence, handler: ({ inputs }) => {diff --git a/packages/media-track/src/fragment.ts b/packages/media-track/src/fragment.tsindex 7f4610a0..a935bb1a 100644--- a/packages/media-track/src/fragment.ts+++ b/packages/media-track/src/fragment.ts@@ -3,7 +3,7 @@ import { compositionTypes } from "@hypit/composition";import { sealGraphFragment } from "@hypit/elaborator";import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";-import { temporalProducers, temporalTypes } from "@hypit/temporal";+import { temporalTypes } from "@hypit/temporal";import { mediaTrackProducers, mediaTrackTypes } from "./manifest.js";@@ -22,7 +22,7 @@ export const stillMediaTrackFragment = sealGraphFragment({{ name: "fit", type: spatialTypes.fit },{ name: "sample-spec", type: mediaTrackTypes.sampleLayerSpec },{ name: "item-spec", type: mediaTrackTypes.itemSpec },- { name: "window-spec", type: temporalTypes.windowSpec },+ { name: "window", type: temporalTypes.window },],operations: [{ id: "layers", producer: mediaTrackProducers.createLayers, inputs: {}, result: { kind: "output", name: "layers" } },@@ -31,15 +31,12 @@ export const stillMediaTrackFragment = sealGraphFragment({}, result: { kind: "output", name: "layers" } },{ id: "set", producer: mediaTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },{ id: "sounds", producer: mediaTrackProducers.createSounds, inputs: {}, result: { kind: "output", name: "sounds" } },- { id: "window", producer: temporalProducers.projectProgram, inputs: {- semantic: input("semantic"), spec: input("window-spec"),- }, result: { kind: "output", name: "window" } },{ id: "space", producer: semanticTrackProducers.projectProgramSpace, inputs: {track: input("semantic"),}, result: { kind: "output", name: "space" } },{ id: "append", producer: mediaTrackProducers.appendItem, inputs: {set: operation("set"), header: input("header"), space: operation("space"), canvas: input("canvas"), layers: operation("sample"),- frame: input("frame"), spec: input("item-spec"), sounds: operation("sounds"), window: operation("window"),+ frame: input("frame"), spec: input("item-spec"), sounds: operation("sounds"), window: input("window"),}, result: { kind: "output", name: "set" } },{ id: "finalize", producer: mediaTrackProducers.finalize, inputs: {set: operation("append"), header: input("header"), space: operation("space"),diff --git a/packages/media-track/src/manifest.ts b/packages/media-track/src/manifest.tsindex 647f3fdf..1f01d447 100644--- a/packages/media-track/src/manifest.ts+++ b/packages/media-track/src/manifest.ts@@ -20,6 +20,7 @@ import {} from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import { temporalDependency, temporalTypes } from "@hypit/temporal";+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";const previewImage = (file: string) => ({mediaType: "image/png",@@ -255,15 +256,15 @@ const itemInputs = [{ name: "sounds", type: mediaTrackTypes.soundSet }, { name: "window", type: temporalTypes.window },] as const;const memberInputs = [- { name: "members", type: mediaTrackTypes.memberSet }, { name: "layers", type: mediaTrackTypes.layerSet },- { name: "spec", type: mediaTrackTypes.memberSpec }, { name: "activation", type: temporalTypes.point },+ { name: "members", type: mediaTrackTypes.memberSet }, { name: "space", type: programSpaceTypes.programSpace }, { name: "layers", type: mediaTrackTypes.layerSet },+ { name: "spec", type: mediaTrackTypes.memberSpec }, { name: "activation", type: temporalTypes.instant },] as const;const sequenceInputs = [{ name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header },{ name: "space", type: programSpaceTypes.programSpace }, { name: "canvas", type: spatialTypes.canvas },{ name: "members", type: mediaTrackTypes.memberSet },{ name: "frame", type: spatialTypes.frame }, { name: "spec", type: mediaTrackTypes.sequenceSpec },- { name: "sounds", type: mediaTrackTypes.soundSet }, { name: "terminal", type: temporalTypes.point },+ { name: "sounds", type: mediaTrackTypes.soundSet }, { name: "terminal", type: temporalTypes.instant },] as const;const appearanceRecipeProperties = [@@ -358,7 +359,7 @@ export const mediaTrackMarkupSurfaces = [{mediaTrackTypes.layerSet, mediaTrackTypes.soundSpec, mediaTrackTypes.soundSet,mediaTrackTypes.itemSpec, mediaTrackTypes.memberSpec, mediaTrackTypes.memberSet,mediaTrackTypes.handoffSpec, mediaTrackTypes.sequenceSpec, mediaTrackTypes.set,- temporalTypes.pointSpec, temporalTypes.windowSpec, mediaTrackTypes.program,+ temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, mediaTrackTypes.program,compositionTypes.visualTrack, compositionTypes.audioTrack],vocabulary: {summary: "One Media Track: independently timed Items and replacement Sequences placed on a shared SemanticTrack and Canvas, lowered to one peer VisualTrack and, when audio is authored, one peer AudioTrack.",@@ -404,23 +405,7 @@ export const mediaTrackMarkupSurfaces = [{summary: "Names the layer whose source audio this Item emits." },{ name: "audio-gain", kind: "literal", required: false,summary: "Scales the selected source audio by a linear gain; defaults to `1`." },- { name: "during", kind: "expression", required: false, values: ["program"],- accepts: [narrativeTypes.selection, narrativeTypes.excerpt],- summary: "Spans the whole program when written as `program`, or the window of the referenced Selection or Segment." },- { name: "at", kind: "reference", required: false, accepts: [narrativeTypes.moment],- summary: "Starts the window at the cue of the referenced Moment." },- { name: "for", kind: "literal", required: false,- summary: "Fixes the exact length of a Moment window, such as `12f`, `250ms` or `1.5s`." },- { name: "start", kind: "literal", required: false,- summary: "Places the window start at a point expression." },- { name: "end", kind: "literal", required: false,- summary: "Places the window end at a point expression." },- { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection],- summary: "Binds the Selection that resolves `selection.start` and `selection.end` in a start/end window." },- { name: "segment", kind: "reference", required: false, accepts: [narrativeTypes.excerpt],- summary: "Binds the Segment that resolves `segment.start` and `segment.end` in a start/end window." },- { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment],- summary: "Binds the Moment that resolves `moment.cue` in a start/end window." },+ ...temporalWindowAttributeVocabulary,] },{ tag: "Sequence", cardinality: "many",summary: "One Frame whose Members replace each other at explicit activation points, written as ordered Member, Handoff and Sound children.",@@ -458,7 +443,7 @@ export const mediaTrackMarkupSurfaces = [{</media-track:Track>`,notes: ["A Track requires at least one Item or Sequence and accepts no text content.",- "An Item states exactly one window form: `during`, `at` with `for`, or `start` with `end`; `selection`, `segment` and `moment` bind a start/end window and cannot be written together.",+ "An Item states exactly one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`; `selection`, `segment` and `moment` bind a start/end window and cannot be written together.","A point expression is `program.start`, `program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end` or `moment.cue`, each optionally offset by `+` or `-` and a duration, or a bare duration read as an absolute position.","A unit that names a direct source names exactly one of `image`, `video`, `media` or `surface`; `extent` is required with `image` and refused otherwise, and `audio` is only valid with `video`.","`audio-gain` is refused without selected source audio.",diff --git a/packages/media-track/src/program.ts b/packages/media-track/src/program.tsindex 69f96864..e891f710 100644--- a/packages/media-track/src/program.ts+++ b/packages/media-track/src/program.ts@@ -17,7 +17,8 @@ import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";import type { CanvasSpace } from "@hypit/spatial";import { assertSpatialPath } from "@hypit/spatial";import type { SpatialPath } from "@hypit/spatial";-import type { ProjectedWindow, TemporalPoint } from "@hypit/temporal";+import { assertTemporalInstantFor, assertTemporalWindowFor } from "@hypit/temporal";+import type { ProjectedWindow, TemporalInstant } from "@hypit/temporal";import {assertMediaIdentity,@@ -140,6 +141,7 @@ function realizedItems(assert(layers.layers.length > 0, `Media Item ${spec.id} requires at least one layer.`);assertSpatialFrame(frame);assertMediaItemSpec(spec);+ assertTemporalWindowFor(window, { subjectId: spec.id, space });assertMediaSoundSet(sounds);assert(!sounds.sounds.some((sound) => sound.trigger.kind === "handoff"),`Media Item ${spec.id} cannot own a Handoff sound.`);@@ -255,8 +257,9 @@ export function appendMediaSequence(frame: MediaSequenceProgram["frame"],spec: MediaSequenceSpec,sounds: MediaSoundSet,- terminal: TemporalPoint,+ terminal: TemporalInstant,): MediaTrackSet {+ assertTemporalInstantFor(terminal, { subjectId: spec.id, space });return appendMediaSequenceAtFrame(set, header, space, canvas, members, frame, spec, sounds, terminal.frame);}@@ -363,6 +366,7 @@ export function assertMediaTrackProgramIdentity(value: MediaTrackProgram, space:export function projectMediaVisualTrack(space: ProgramSpace, program: MediaTrackProgram): VisualTrack {assertMediaTrackProgramIdentity(program, space);const track = sealVisualTrack({+ programSpaceId: space.id,visualIr: "hypit.visual-ir@1",id: program.id,presents: [@@ -554,7 +558,7 @@ export function projectMediaAudioTrack(space: ProgramSpace, program: MediaTrackPreturn [...(source === undefined ? [] : [source]), ...edgeSoundClips(item, space)];}).concat(program.sequences.flatMap((sequence) => sequenceAudioClips(sequence, space)));assert(clips.length > 0, `Media Program ${program.id} has no explicitly authored audio projection.`);- const track = sealAudioTrack({ id: `${program.id}:audio`, clips });+ const track = sealAudioTrack({ programSpaceId: space.id, id: `${program.id}:audio`, clips });assertAudioTrackIdentity(track, space);return track;}diff --git a/packages/media-track/src/sequence.ts b/packages/media-track/src/sequence.tsindex 99340537..532ea6f9 100644--- a/packages/media-track/src/sequence.ts+++ b/packages/media-track/src/sequence.ts@@ -9,8 +9,8 @@ import type { ProgramSpace } from "@hypit/program-space";import { canonicalize } from "@hypit/protocol";import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";import type { CanvasSpace } from "@hypit/spatial";-import { resolveTriggeredSchedule } from "@hypit/temporal";-import type { TemporalPoint } from "@hypit/temporal";+import { assertTemporalInstantFor, resolveTriggeredSchedule } from "@hypit/temporal";+import type { TemporalInstant } from "@hypit/temporal";import { assertMediaIdentity, assertMediaLayerSet } from "./layers.js";import { lowerMediaItemElements } from "./lower.js";@@ -109,10 +109,12 @@ function appendMediaSequenceMemberAtFrame(export function appendMediaSequenceMember(set: MediaSequenceMemberSet,+ space: ProgramSpace,layers: MediaLayerSet,spec: MediaSequenceMemberSpec,- activation: TemporalPoint,+ activation: TemporalInstant,): MediaSequenceMemberSet {+ assertTemporalInstantFor(activation, { subjectId: spec.id, space });return appendMediaSequenceMemberAtFrame(set, layers, spec, activation.frame);}diff --git a/packages/media-track/src/surface.ts b/packages/media-track/src/surface.tsindex 24d1c618..6b9a33a7 100644--- a/packages/media-track/src/surface.ts+++ b/packages/media-track/src/surface.ts@@ -5,6 +5,7 @@ import {optionalTextAttribute as optionalText,type StructuredElement,type StructuredSurfaceHandler,+ type SurfaceComponentDraft,type SurfaceRecordDraft,type SurfaceResolvedReference,type MarkupAttributeValue,@@ -15,17 +16,12 @@ import { compositionTypes } from "@hypit/composition";import { sealGraphFragment } from "@hypit/elaborator";import type { FragmentOperation } from "@hypit/elaborator";import { mediaTypes } from "@hypit/media";-import { narrativeTypes } from "@hypit/narrative";import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import type { SvsRecipe } from "@hypit/svs";-import type {- TemporalDuration,- TemporalPointExpression,- TemporalWindowProjection,-} from "@hypit/temporal";-import { temporalProducers, temporalTypes } from "@hypit/temporal";+import { temporalTypes } from "@hypit/temporal";+import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames, temporalWindowAttributeNames } from "@hypit/temporal-markup";import {decodeMediaFit,@@ -74,20 +70,6 @@ function reference(return value;}-function oneOfReferences(- raw: MarkupAttributeValue | undefined,- label: string,- expected: readonly TypeRef[],- resolve: (path: string) => SurfaceResolvedReference | undefined,-): SurfaceResolvedReference {- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);- const value = resolve(raw.path);- if (value === undefined || !expected.some((type) => sameType(value.type, type))) {- throw new Error(`${label} has the wrong Type.`);- }- return value;-}-function recipe(value: SurfaceResolvedReference, label: string): SvsRecipe {if (!sameType(value.type, svsRecipeType) || value.record?.value.kind !== "inline") {throw new Error(`${label} must be an authored SVS Recipe.`);@@ -95,114 +77,6 @@ function recipe(value: SurfaceResolvedReference, label: string): SvsRecipe {return value.record.value.value as unknown as SvsRecipe;}-function divisor(left: number, right: number): number {- let a = Math.abs(left);- let b = Math.abs(right);- while (b !== 0) [a, b] = [b, a % b];- return a;-}--function duration(value: string, label: string): TemporalDuration {- const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());- if (match === null) throw new Error(`${label} must be an exact duration such as 12f, 250ms or 1.5s.`);- const whole = Number(match[1]);- const fraction = match[2] ?? "";- const unit = match[3];- if (!Number.isSafeInteger(whole)) throw new Error(`${label} is outside safe arithmetic.`);- if (unit === "f" || unit === "ms") {- if (fraction.length > 0) throw new Error(`${label} ${unit} duration must be an integer.`);- return { unit: unit === "f" ? "frames" : "milliseconds", value: whole };- }- const scale = 10 ** fraction.length;- const numerator = whole * scale + (fraction.length === 0 ? 0 : Number(fraction));- if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(scale)) throw new Error(`${label} is outside safe arithmetic.`);- const gcd = divisor(numerator, scale);- return { unit: "seconds", numerator: numerator / gcd, denominator: scale / gcd };-}--function negate(value: TemporalDuration): TemporalDuration {- return value.unit === "seconds" ? { ...value, numerator: -value.numerator } : { ...value, value: -value.value };-}--function point(value: string, label: string): TemporalPointExpression {- const trimmed = value.trim();- const refs = ["program.start", "program.end", "selection.start", "selection.end", "segment.start", "segment.end", "moment.cue"] as const;- for (const ref of refs) {- if (trimmed === ref) return { ref };- const match = new RegExp(`^${ref.replace(".", "\\.")}\\s*([+-])\\s*(.+)$`, "u").exec(trimmed);- if (match !== null) {- const offset = duration(match[2]!, `${label} offset`);- return { ref, offset: match[1] === "-" ? negate(offset) : offset };- }- }- return { ref: "absolute", at: duration(trimmed, label) };-}--type TemporalBinding = {- readonly kind: "program" | "selection" | "segment" | "moment";- readonly projection: TemporalWindowProjection;- readonly source?: SurfaceResolvedReference;-};--function temporalBinding(- element: StructuredElement,- resolve: (path: string) => SurfaceResolvedReference | undefined,-): TemporalBinding {- const during = element.attributes.during;- const at = element.attributes.at;- const start = optionalText(element, "start");- const end = optionalText(element, "end");- const selection = element.attributes.selection;- const segment = element.attributes.segment;- const moment = element.attributes.moment;- const forms = Number(during !== undefined) + Number(at !== undefined) + Number(start !== undefined || end !== undefined);- if (forms !== 1) throw new Error(`${element.name} requires exactly one of during, at/for, or start/end.`);- if (during !== undefined) {- if (typeof during === "string") {- if (during.trim() !== "program") throw new Error(`${element.name}.during text must be program.`);- return { kind: "program", projection: { start: { ref: "program.start" }, end: { ref: "program.end" } } };- }- const source = oneOfReferences(during, `${element.name}.during`, [narrativeTypes.selection, narrativeTypes.excerpt], resolve);- return sameType(source.type, narrativeTypes.selection) ? {- kind: "selection",- source,- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },- } : {- kind: "segment",- source,- projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },- };- }- if (at !== undefined) {- const forDuration = duration(text(element, "for"), `${element.name}.for`);- return {- kind: "moment",- source: reference(at, `${element.name}.at`, narrativeTypes.moment, resolve),- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: forDuration } },- };- }- if (start === undefined || end === undefined) throw new Error(`${element.name} explicit timing requires start and end.`);- if (Number(selection !== undefined) + Number(segment !== undefined) + Number(moment !== undefined) > 1) {- throw new Error(`${element.name} cannot bind Selection, Segment and Moment together.`);- }- if (selection !== undefined) return {- kind: "selection",- source: reference(selection, `${element.name}.selection`, narrativeTypes.selection, resolve),- projection: { start: point(start, `${element.name}.start`), end: point(end, `${element.name}.end`) },- };- if (moment !== undefined) return {- kind: "moment",- source: reference(moment, `${element.name}.moment`, narrativeTypes.moment, resolve),- projection: { start: point(start, `${element.name}.start`), end: point(end, `${element.name}.end`) },- };- if (segment !== undefined) return {- kind: "segment",- source: reference(segment, `${element.name}.segment`, narrativeTypes.excerpt, resolve),- projection: { start: point(start, `${element.name}.start`), end: point(end, `${element.name}.end`) },- };- return { kind: "program", projection: { start: point(start, `${element.name}.start`), end: point(end, `${element.name}.end`) } };-}-type FragmentLayer =| { readonly kind: "paint"; readonly specName: string }| { readonly kind: "still"; readonly sourceName: string; readonly extentName: string; readonly fitName: string; readonly specName: string }@@ -212,9 +86,7 @@ type FragmentSound = { readonly sourceName: string; readonly specName: string };type FragmentItem = {readonly suffix: string;- readonly binding: TemporalBinding["kind"];- readonly sourceName?: string;- readonly windowSpecName: string;+ readonly windowName: string;readonly frameName: string;readonly specName: string;readonly clipPathName?: string;@@ -224,18 +96,14 @@ type FragmentItem = {type FragmentMember = {readonly suffix: string;- readonly binding: "moment" | "selection-start" | "selection-end";- readonly sourceName: string;- readonly pointSpecName: string;+ readonly instantName: string;readonly specName: string;readonly layers: readonly FragmentLayer[];};type FragmentSequence = {readonly suffix: string;- readonly terminal: "program-end" | "moment" | "selection-start" | "selection-end";- readonly terminalSourceName?: string;- readonly terminalSpecName: string;+ readonly terminalName: string;readonly frameName: string;readonly specName: string;readonly clipPathName?: string;@@ -289,14 +157,6 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: sconst prefix = `item:${item.suffix}`;const layers = appendLayers(operations, prefix, item.layers);const sounds = appendSounds(operations, prefix, item.sounds);- const windowId = `${prefix}:window`;- const windowProducer = item.binding === "program" ? temporalProducers.projectProgram- : item.binding === "selection" ? temporalProducers.projectSelection- : item.binding === "segment" ? temporalProducers.projectSegment : temporalProducers.projectMoment;- operations.push({ id: windowId, producer: windowProducer, inputs: {- semantic: input("semantic"), spec: input(item.windowSpecName),- ...(item.binding === "program" ? {} : { [item.binding]: input(item.sourceName!) }),- }, result: { kind: "output", name: "window" } });const appendId = `${prefix}:append`;let spec: FragmentOperation["inputs"][string] = input(item.specName);if (item.clipPathName !== undefined) {@@ -308,7 +168,7 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: s}const common = {set: operation(set), header: input("header"), space: operation("track:space"), canvas: input("canvas"),- layers: operation(layers), frame: input(item.frameName), spec, sounds: operation(sounds), window: operation(windowId),+ layers: operation(layers), frame: input(item.frameName), spec, sounds: operation(sounds), window: input(item.windowName),};operations.push({ id: appendId, producer: mediaTrackProducers.appendItem, inputs: common, result: { kind: "output", name: "set" } });set = appendId;@@ -322,14 +182,8 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: sconst memberPrefix = `${prefix}:member:${member.suffix}`;const layers = appendLayers(operations, memberPrefix, member.layers);const appendId = `${memberPrefix}:append`;- const pointId = `${memberPrefix}:point`;- const pointProducer = member.binding === "moment" ? temporalProducers.projectMomentPoint : temporalProducers.projectSelectionPoint;- operations.push({ id: pointId, producer: pointProducer, inputs: {- semantic: input("semantic"), spec: input(member.pointSpecName),- [member.binding === "moment" ? "moment" : "selection"]: input(member.sourceName),- }, result: { kind: "output", name: "point" } });operations.push({ id: appendId, producer: mediaTrackProducers.appendMember, inputs: {- members: operation(members), layers: operation(layers), spec: input(member.specName), activation: operation(pointId),+ members: operation(members), space: operation("track:space"), layers: operation(layers), spec: input(member.specName), activation: input(member.instantName),}, result: { kind: "output", name: "members" } });members = appendId;}@@ -347,17 +201,8 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: sset: operation(set), header: input("header"), space: operation("track:space"), canvas: input("canvas"),members: operation(members), frame: input(sequence.frameName), spec, sounds: operation(sounds),};- const terminalPointId = `${prefix}:terminal`;- const terminalProducer = sequence.terminal === "program-end" ? temporalProducers.projectProgramPoint- : sequence.terminal === "moment" ? temporalProducers.projectMomentPoint : temporalProducers.projectSelectionPoint;- operations.push({ id: terminalPointId, producer: terminalProducer, inputs: {- semantic: input("semantic"), spec: input(sequence.terminalSpecName),- ...(sequence.terminal === "program-end" ? {} : {- [sequence.terminal === "moment" ? "moment" : "selection"]: input(sequence.terminalSourceName!),- }),- }, result: { kind: "output", name: "point" } });operations.push({ id: appendId, producer: mediaTrackProducers.appendSequence,- inputs: { ...common, terminal: operation(terminalPointId) }, result: { kind: "output", name: "set" } });+ inputs: { ...common, terminal: input(sequence.terminalName) }, result: { kind: "output", name: "set" } });set = appendId;}operations.push(@@ -382,6 +227,7 @@ type SurfaceBuilder = {readonly inputTypes: { name: string; type: TypeRef }[];addReference(name: string, value: SurfaceResolvedReference): void;addRecord(name: string, id: string, type: TypeRef, value: unknown, range: StructuredElement["range"]): void;+ addValue(name: string, value: SurfaceResolvedReference["ref"], type: TypeRef): void;};function builder(): SurfaceBuilder {@@ -403,6 +249,11 @@ function builder(): SurfaceBuilder {inputs[name] = { kind: "record", id };inputTypes.push({ name, type });},+ addValue(name, value, type) {+ if (inputs[name] !== undefined) throw new Error(`Media Surface repeats input ${name}.`);+ inputs[name] = value;+ inputTypes.push({ name, type });+ },};}@@ -641,13 +492,16 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, resallowed(element, ["id", "semantic", "canvas"]);const trackId = text(element, "id");const state = builder();- state.addReference("semantic", reference(element.attributes.semantic, `${element.name}.semantic`, semanticTrackTypes.track, resolveReference));+ const semantic = reference(element.attributes.semantic, `${element.name}.semantic`, semanticTrackTypes.track, resolveReference);+ state.addReference("semantic", semantic);state.addReference("canvas", reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference));const headerId = `${trackId}.header`;state.addRecord("header", headerId, mediaTrackTypes.header,sealMediaTrackHeader({ id: trackId }), element.range);const items: FragmentItem[] = [];const sequences: FragmentSequence[] = [];+ const temporalComponents: SurfaceComponentDraft[] = [];+ const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];let itemIndex = 0;let sequenceIndex = 0;let hasAudio = false;@@ -661,7 +515,7 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, resconst itemSuffix = suffix(itemIndex);allowed(child, ["id", "image", "media", "surface", "extent", "frame", "appearance", "motion", "source-audio", "audio-gain",- "clip", "during", "at", "for", "start", "end", "selection", "segment", "moment",+ "clip", ...temporalWindowAttributeNames,]);const id = optionalText(child, "id") ?? `${trackId}.item.${itemSuffix}`;const appearance = recipe(reference(child.attributes.appearance, `${child.name}.appearance`, svsRecipeType, resolveReference), `${child.name}.appearance`);@@ -672,16 +526,16 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res}const motionRecipe = child.attributes.motion === undefined ? undefined: recipe(reference(child.attributes.motion, `${child.name}.motion`, svsRecipeType, resolveReference), `${child.name}.motion`);- const binding = temporalBinding(child, resolveReference);+ const temporal = createTemporalWindowProjection({ id, element: child, semantic, resolveReference });+ state.records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);const directSource = declaredVisualSource(child, resolveReference);validateUnitChildren(child, directSource !== undefined, true);const layers = unitLayers(state, { trackId, unitSuffix: `item-${itemSuffix}`, element: child, appearance,...(directSource === undefined ? {} : { directSource }), allowFramePaint: true }, resolveReference);const selectedAudio = sourceAudio(child);const specName = `item-${itemSuffix}-spec`;- const windowSpecName = `item-${itemSuffix}-window-spec`;- state.addRecord(windowSpecName, `${trackId}.item.${itemSuffix}.window`, temporalTypes.windowSpec,- { id, projection: binding.projection }, child.range);+ const windowName = `item-${itemSuffix}-window`;+ state.addValue(windowName, temporal.ref, temporalTypes.window);state.addRecord(specName, `${trackId}.item.${itemSuffix}.spec`, mediaTrackTypes.itemSpec,decodeMediaItemSpec(appearance, { id,motion: decodeMediaMotion(motionRecipe), ...(selectedAudio === undefined ? {} : { sourceAudio: selectedAudio }) }), child.range);@@ -694,9 +548,7 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res}}if (selectedAudio !== undefined || fragmentSounds.length > 0) hasAudio = true;- const sourceName = binding.kind === "program" ? undefined : `item-${itemSuffix}-${binding.kind}`;- if (binding.source !== undefined) state.addReference(sourceName!, binding.source);- items.push({ suffix: itemSuffix, binding: binding.kind, ...(sourceName === undefined ? {} : { sourceName }), windowSpecName, frameName, specName,+ items.push({ suffix: itemSuffix, windowName, frameName, specName,...(clipPathName === undefined ? {} : { clipPathName }), layers, sounds: fragmentSounds });continue;}@@ -734,13 +586,9 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, resconst members: FragmentMember[] = [];for (const [index, member] of memberElements.entries()) {const memberSuffix = suffix(index + 1);- allowed(member, ["id", "image", "media", "surface", "extent", "appearance", "at", "boundary", "source-audio", "audio-gain"]);- const at = oneOfReferences(member.attributes.at, `${member.name}.at`, [narrativeTypes.moment, narrativeTypes.selection], resolveReference);- const boundary = optionalText(member, "boundary");- const binding = sameType(at.type, narrativeTypes.moment) ? "moment"- : boundary === "start" ? "selection-start" : boundary === "end" ? "selection-end" : undefined;- if (binding === undefined) throw new Error(`${member.name}.boundary must be start or end for a Selection activation.`);- if (sameType(at.type, narrativeTypes.moment) && boundary !== undefined) throw new Error(`${member.name}.boundary is invalid for a Moment activation.`);+ allowed(member, ["id", "image", "media", "surface", "extent", "appearance", ...temporalInstantAttributeNames, "source-audio", "audio-gain"]);+ const temporal = createTemporalInstantProjection({ id: `${id}.${memberIds[index]}`, subjectId: memberIds[index]!, element: member, semantic, resolveReference });+ state.records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);const memberAppearance = member.attributes.appearance === undefined ? appearance: recipe(reference(member.attributes.appearance, `${member.name}.appearance`, svsRecipeType, resolveReference), `${member.name}.appearance`);const directSource = declaredVisualSource(member, resolveReference);@@ -751,21 +599,12 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, resconst selectedAudio = sourceAudio(member);if (selectedAudio !== undefined) hasAudio = true;const specName = `${unitSuffix}-spec`;- const pointSpecName = `${unitSuffix}-point-spec`;state.addRecord(specName, `${trackId}.${unitSuffix}.spec`, mediaTrackTypes.memberSpec,sealMediaSequenceMemberSpec({ id: memberIds[index]!,...(selectedAudio === undefined ? {} : { sourceAudio: selectedAudio }) }), member.range);- state.addRecord(pointSpecName, `${trackId}.${unitSuffix}.point`, temporalTypes.pointSpec, {- id: `${id}.${memberIds[index]}`,- projection: binding === "moment"- ? { ref: "moment.cue" }- : boundary === "start"- ? { ref: "selection.start" }- : { ref: "selection.end" },- }, member.range);- const sourceName = `${unitSuffix}-${binding === "moment" ? "moment" : "selection"}`;- state.addReference(sourceName, at);- members.push({ suffix: memberSuffix, binding, sourceName, specName, pointSpecName, layers });+ const instantName = `${unitSuffix}-instant`;+ state.addValue(instantName, temporal.ref, temporalTypes.instant);+ members.push({ suffix: memberSuffix, instantName, specName, layers });}const sequenceSounds: FragmentSound[] = [];for (const soundChild of child.children) {@@ -777,52 +616,29 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res)) throw new Error(`${child.name} accepts only Member, Handoff and Sound children.`);}if (sequenceSounds.length > 0) hasAudio = true;- const until = child.attributes.until;- let terminal: FragmentSequence["terminal"];- let terminalReference: SurfaceResolvedReference | undefined;- if (typeof until === "string") {- if (until.trim() !== "program.end") throw new Error(`${child.name}.until text must be program.end.`);- terminal = "program-end";- if (child.attributes["until-boundary"] !== undefined) throw new Error(`${child.name}.until-boundary is invalid for program.end.`);- } else {- terminalReference = oneOfReferences(until, `${child.name}.until`, [narrativeTypes.moment, narrativeTypes.selection], resolveReference);- if (sameType(terminalReference.type, narrativeTypes.moment)) {- if (child.attributes["until-boundary"] !== undefined) throw new Error(`${child.name}.until-boundary is invalid for a Moment.`);- terminal = "moment";- } else {- const boundary = text(child, "until-boundary", "end");- if (boundary !== "start" && boundary !== "end") throw new Error(`${child.name}.until-boundary must be start or end.`);- terminal = boundary === "start" ? "selection-start" : "selection-end";- }- }+ const terminalTemporal = createTemporalInstantProjection({+ id: `${id}.terminal`, subjectId: id, element: child, semantic, resolveReference,+ semanticAttribute: "until", boundaryAttribute: "until-boundary", projectedAttribute: false,+ boundaryFallback: "end",+ });+ state.records.push(...terminalTemporal.records); temporalComponents.push(...terminalTemporal.components); temporalFragments.push(...terminalTemporal.fragments);const frameName = `sequence-${sequenceSuffix}-frame`;state.addReference(frameName, reference(child.attributes.frame, `${child.name}.frame`, spatialTypes.frame, resolveReference));const specName = `sequence-${sequenceSuffix}-spec`;state.addRecord(specName, `${trackId}.sequence.${sequenceSuffix}.spec`, mediaTrackTypes.sequenceSpec,decodeMediaSequenceSpec(appearance, id, decodeMediaMotion(motionRecipe), handoffs), child.range);- const terminalSourceName = terminalReference === undefined ? undefined : `sequence-${sequenceSuffix}-terminal`;- if (terminalReference !== undefined) state.addReference(terminalSourceName!, terminalReference);- const terminalSpecName = `sequence-${sequenceSuffix}-terminal-point-spec`;- state.addRecord(terminalSpecName, `${trackId}.sequence.${sequenceSuffix}.terminal-point`, temporalTypes.pointSpec, {- id: `${id}.terminal`,- projection: terminal === "program-end"- ? { ref: "program.end" }- : terminal === "moment"- ? { ref: "moment.cue" }- : terminal === "selection-start"- ? { ref: "selection.start" }- : { ref: "selection.end" },- }, child.range);- sequences.push({ suffix: sequenceSuffix, terminal, ...(terminalSourceName === undefined ? {} : { terminalSourceName }), terminalSpecName, frameName, specName,+ const terminalName = `sequence-${sequenceSuffix}-terminal`;+ state.addValue(terminalName, terminalTemporal.ref, temporalTypes.instant);+ sequences.push({ suffix: sequenceSuffix, terminalName, frameName, specName,...(clipPathName === undefined ? {} : { clipPathName }), members, sounds: sequenceSounds });}if (items.length === 0 && sequences.length === 0) throw new Error(`${element.name} requires at least one Item or Sequence.`);const fragment = createMediaTrackSurfaceFragment(state.inputTypes, items, sequences, hasAudio);return {records: state.records,- components: [{ id: trackId, fragment: fragment.id, inputs: state.inputs,+ components: [...temporalComponents, { id: trackId, fragment: fragment.id, inputs: state.inputs,outputs: { program: `${trackId}.program`, visual: `${trackId}.visual`, ...(hasAudio ? { audio: `${trackId}.audio` } : {}) }, range: element.range }],- fragments: [fragment],+ fragments: [...temporalFragments, fragment],exports: [`${trackId}.program`, `${trackId}.visual`, ...(hasAudio ? [`${trackId}.audio`] : [])],};};diff --git a/packages/media-track/test/media-track.test.ts b/packages/media-track/test/media-track.test.tsindex 58cd2e3a..f59635ae 100644--- a/packages/media-track/test/media-track.test.ts+++ b/packages/media-track/test/media-track.test.ts@@ -2,6 +2,8 @@ import assert from "node:assert/strict";import test from "node:test";import { fixtureDigest } from "../../../test/fixture-digest.js";import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";+import { projectMomentWindow, projectProgramWindow, projectSegmentWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";+import type { TemporalWindowProjection } from "../../../test/temporal-fixture.js";import { sealComposition } from "@hypit/composition";import type { AudioTrack } from "@hypit/composition";@@ -59,10 +61,9 @@ import { spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import type { SvsRecipe } from "@hypit/svs";import type { StructuredElement, StructuredNode, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";-import { projectMomentWindow, projectProgramWindow, projectSegmentWindow, projectSelectionWindow } from "@hypit/temporal";-import type { TemporalWindow, TemporalWindowProjection } from "@hypit/temporal";+import type { TemporalWindow } from "@hypit/temporal";-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 4,frameRate: { numerator: 30, denominator: 1 },});@@ -154,7 +155,7 @@ function appendSelectionMediaItem(function appendSegmentMediaItem(set: ReturnType<typeof createMediaTrackSet>, trackHeader: typeof header, semanticTrack: typeof semantic,- canvasSpace: typeof canvas, layers: MediaLayerSet, frameValue: typeof frame, segment: { kind: "segment"; id: string; tokenStart: number; tokenEndExclusive: number },+ canvasSpace: typeof canvas, layers: MediaLayerSet, frameValue: typeof frame, segment: { narrativeId: string; kind: "segment"; id: string; tokenStart: number; tokenEndExclusive: number },authored: TestMediaItemSpec, sounds: ReturnType<typeof createMediaSoundSet>,) {const { projection, ...spec } = authored;@@ -228,11 +229,13 @@ function sequenceMembers(id: `member-${index + 1}`,sourceAudio: { fromLayer: "video", gain: 1 - (index * 0.1) },});- members = appendProjectedMediaSequenceMember(members, layerFactory(index), spec, {+ members = appendProjectedMediaSequenceMember(members, space, layerFactory(index), spec, {id: `${spec.id}::test`,- source: { kind: "program", id: "program" },+ subjectId: spec.id,+ source: { spaceId: space.id, narrativeId: space.narrativeId, kind: "program", id: "program" },projection: { ref: "program.start" },frame: activationFrame,+ authority: { kind: "fixed" },});}return members;@@ -241,8 +244,9 @@ function sequenceMembers(function testProgramWindow(endFrameExclusive: number): TemporalWindow {return {id: "program::test",- source: { kind: "program", id: "program" },- projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },+ subjectId: "program",+ start: { id: "program::test.start", subjectId: "program", source: { spaceId: space.id, narrativeId: space.narrativeId, kind: "program", id: "program" }, projection: { ref: "program.start" }, frame: 0, authority: { kind: "fixed" } },+ end: { id: "program::test.end", subjectId: "program", source: { spaceId: space.id, narrativeId: space.narrativeId, kind: "program", id: "program" }, projection: { ref: "program.end" }, frame: endFrameExclusive, authority: { kind: "fixed" } },span: { startFrame: 0, endFrameExclusive },};}@@ -253,19 +257,21 @@ function appendMediaSequence(sounds: ReturnType<typeof createMediaSoundSet>, terminalFrame: number,) {return appendProjectedMediaSequence(set, trackHeader, spaceValue, canvasValue, members, frameValue, spec, sounds, {- id: `${spec.id}::terminal`, source: { kind: "program", id: "program" },- projection: { ref: "program.end" }, frame: terminalFrame,+ id: `${spec.id}::terminal`, subjectId: spec.id, source: { spaceId: space.id, narrativeId: space.narrativeId, kind: "program", id: "program" },+ projection: { ref: "program.end" }, frame: terminalFrame, authority: { kind: "fixed" },});}function appendMediaSequenceMember(set: ReturnType<typeof createMediaSequenceMemberSet>, layers: MediaLayerSet, spec: ReturnType<typeof sealMediaSequenceMemberSpec>, activationFrame: number,) {- return appendProjectedMediaSequenceMember(set, layers, spec, {+ return appendProjectedMediaSequenceMember(set, space, layers, spec, {id: `${spec.id}::test`,- source: { kind: "program", id: "program" },+ subjectId: spec.id,+ source: { spaceId: space.id, narrativeId: space.narrativeId, kind: "program", id: "program" },projection: { ref: "program.start" },frame: activationFrame,+ authority: { kind: "fixed" },});}@@ -316,10 +322,10 @@ test("an Item keeps ordered Paint/sample layers, two-frame fit and frame presentassert.deepEqual(program.items[0]?.span, { startFrame: 0, endFrameExclusive: 120 });assert.deepEqual(program.items[0]?.layers.map((layer) => layer.id), ["backing", "content"]);const track = projectMediaVisualTrack(space, program);- assert.deepEqual(track.presents[0]?.stacking, { order: 40, tieBreak: "proof:product::program" });+ assert.deepEqual(track.presents[0]?.stacking, { order: 40, tieBreak: "proof:product" });const elements = track.presents[0]!.elements;assert.deepEqual(elements.slice(0, 3).map((element) => element.id), [- "product::program:placement", "product::program:lifecycle", "product::program:frame",+ "product:placement", "product:lifecycle", "product:frame",]);const media = elements.find((element) => element.id === "content");assert.equal(media?.kind, "image");@@ -464,6 +470,7 @@ test("source audio and edge SFX project separately from the visual Track", () =>const bgm: AudioTrack = {kind: "audio",id: "independent-bgm",+ programSpaceId: space.id,clips: [{id: "bed",artifact: timed("bgm").audio!.artifact,@@ -527,6 +534,7 @@ test("still and animated typed Surfaces use the same layer law without browser ftest("Media Items consume singular Selection and Moment sources without becoming an exclusive lane", () => {const selection: NarrativeSelectionRef = {+ narrativeId: space.narrativeId,id: "mentions",startAnchorId: "a",endAnchorId: "b",@@ -538,6 +546,7 @@ test("Media Items consume singular Selection and Moment sources without becoming}), createMediaSoundSet());assert.deepEqual(selected.items.map((item) => item.span), [{ startFrame: 15, endFrameExclusive: 45 }]);const moment: NarrativeMomentRef = {+ narrativeId: space.narrativeId,id: "cue", anchorId: "b",};const overlapping = appendMomentMediaItem(selected, header, semantic, canvas, stillLayers(), frame,@@ -566,7 +575,7 @@ test("Media Items consume singular Selection and Moment sources without becomingtest("a Media Item can consume one whole Narrative Segment without a synthetic Selection", () => {const result = appendSegmentMediaItem(createMediaTrackSet(), header, semantic, canvas, stillLayers(), frame,- { kind: "segment", id: "answer", tokenStart: 0, tokenEndExclusive: 1 },+ { narrativeId: space.narrativeId, kind: "segment", id: "answer", tokenStart: 0, tokenEndExclusive: 1 },itemSpec({id: "whole-answer",projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },@@ -691,7 +700,7 @@ test("timed visual occupancy resolves every alignment into exact source-frame setest("the graph keeps every source, extent, fit, frame, time and appearance input explicit", () => {assert.deepEqual(stillMediaTrackFragment.inputs.map((input) => input.name), [- "canvas", "extent", "fit", "frame", "header", "item-spec", "sample-spec", "semantic", "source", "window-spec",+ "canvas", "extent", "fit", "frame", "header", "item-spec", "sample-spec", "semantic", "source", "window",]);});@@ -758,9 +767,10 @@ test("the Media author Surface emits explicit graph edges for layers, semantic tresolveReference: (path) => references.get(path),resolveAsset: async () => { throw new Error("no asset resolution expected"); },});- assert.equal(result.components.length, 1);- assert.deepEqual(Object.keys(result.components[0]!.outputs).sort(), ["audio", "program", "visual"]);- const fragment = result.fragments[0]!;+ const component = result.components.find((candidate) => candidate.outputs.visual !== undefined);+ assert.ok(component !== undefined);+ assert.deepEqual(Object.keys(component.outputs).sort(), ["audio", "program", "visual"]);+ const fragment = result.fragments.find((candidate) => candidate.exports.some((output) => output.name === "visual"))!;const producers = fragment.operations.map((entry) => entry.producer.name);assert.ok(producers.includes("append-still-media-layer"));assert.ok(producers.includes("append-media-item"));@@ -770,11 +780,19 @@ test("the Media author Surface emits explicit graph edges for layers, semantic tassert.ok(producers.includes("bind-media-item-clip-path"));assert.ok(producers.includes("append-media-sequence-member"));assert.ok(producers.includes("append-media-sequence"));- assert.ok(producers.includes("project-selection-point"));+ assert.ok(result.fragments.some((candidate) => candidate.operations.some((operation) =>+ operation.producer.name === "project-selection-instant")));+ const temporalSubjects = new Set(result.records.flatMap((record) =>+ record.value.kind === "inline"+ && typeof record.value.value === "object"+ && record.value.value !== null+ && "subjectId" in record.value.value+ ? [String((record.value.value as { readonly subjectId: unknown }).subjectId)]+ : []));+ assert.deepEqual([...temporalSubjects].sort(), ["one", "proof", "segment-card", "steps", "still-card", "two"]);assert.ok(producers.includes("append-media-sound"));assert.ok(fragment.inputs.some((entry) => entry.type.name === artifactTypes.blob.name));assert.ok(fragment.inputs.some((entry) => entry.type.name === mediaTypes.synchronized.name));- assert.ok(fragment.inputs.some((entry) => entry.type.name === narrativeTypes.selection.name));assert.ok(fragment.inputs.some((entry) => entry.type.name === spatialTypes.path.name));const itemSpecs = result.records.filter((entry) => entry.type.name === "MediaItemSpec");assert.equal(itemSpecs.length, 3);diff --git a/packages/narrative/package.json b/packages/narrative/package.jsonindex c3a8bf11..780751e5 100644--- a/packages/narrative/package.json+++ b/packages/narrative/package.json@@ -11,6 +11,7 @@"activation": "./src/activation.ts"},"dependencies": {+ "@hypit/component-kit": "workspace:*","@hypit/protocol": "workspace:*"}}diff --git a/packages/narrative/src/activation.ts b/packages/narrative/src/activation.tsindex 82d62acb..7a1b37e4 100644--- a/packages/narrative/src/activation.ts+++ b/packages/narrative/src/activation.ts@@ -1,6 +1,7 @@-import { narrativeManifest } from "./index.js";+import { narrativeComponent, narrativeManifest } from "./index.js";export const hypitPackage = {format: "hypit.node-package@1" as const,modules: [{ manifest: narrativeManifest }],+ components: [narrativeComponent],};export default hypitPackage;diff --git a/packages/narrative/src/component.ts b/packages/narrative/src/component.tsnew file mode 100644index 00000000..8964a756--- /dev/null+++ b/packages/narrative/src/component.ts@@ -0,0 +1,33 @@+import type { ComponentPackage } from "@hypit/component-kit";+import type { StoredValue } from "@hypit/protocol";++import {+ assertCaptionDocumentIdentity,+ assertNarrativeExcerptIdentity,+ assertNarrativeIdentity,+ assertNarrativeMomentRefIdentity,+ assertNarrativeSelectionRefIdentity,+} from "./identity.js";+import { narrativeTypes } from "./manifest.js";+import type {+ CaptionDocument,+ Narrative,+ NarrativeExcerpt,+ NarrativeMomentRef,+ NarrativeSelectionRef,+} from "./types.js";++function inline<T>(value: StoredValue, subject: string): T {+ if (value.kind !== "inline") throw new Error(`${subject} must be inline.`);+ return value.value as T;+}++export const narrativeComponent = {+ validators: [+ { type: narrativeTypes.narrative, handler: ({ value }) => assertNarrativeIdentity(inline<Narrative>(value, "Narrative")) },+ { type: narrativeTypes.excerpt, handler: ({ value }) => assertNarrativeExcerptIdentity(inline<NarrativeExcerpt>(value, "NarrativeExcerpt")) },+ { type: narrativeTypes.selection, handler: ({ value }) => assertNarrativeSelectionRefIdentity(inline<NarrativeSelectionRef>(value, "NarrativeSelection")) },+ { type: narrativeTypes.moment, handler: ({ value }) => assertNarrativeMomentRefIdentity(inline<NarrativeMomentRef>(value, "NarrativeMoment")) },+ { type: narrativeTypes.captionDocument, handler: ({ value }) => assertCaptionDocumentIdentity(inline<CaptionDocument>(value, "CaptionDocument")) },+ ],+} satisfies ComponentPackage;diff --git a/packages/narrative/src/identity.ts b/packages/narrative/src/identity.tsnew file mode 100644index 00000000..583ef29a--- /dev/null+++ b/packages/narrative/src/identity.ts@@ -0,0 +1,129 @@+import type {+ CaptionDocument,+ Narrative,+ NarrativeExcerpt,+ NarrativeMomentRef,+ NarrativeSelectionRef,+} from "./types.js";++function nonempty(value: string, subject: string): void {+ if (value.trim().length === 0) throw new Error(`${subject} must not be empty.`);+}++function unique(values: readonly string[], subject: string): Set<string> {+ const found = new Set<string>();+ for (const value of values) {+ nonempty(value, subject);+ if (found.has(value)) throw new Error(`${subject} repeats ${value}.`);+ found.add(value);+ }+ return found;+}++export function assertNarrativeIdentity(value: Narrative): void {+ nonempty(value.id, "Narrative id");+ if (value.segments.length === 0) throw new Error("Narrative must contain at least one Segment.");+ const segmentIds = unique(value.segments.map((item) => item.id), "Narrative Segment id");+ const tokenIds = unique(value.tokens.map((item) => item.id), "Narrative Token id");+ unique(value.turns.map((item) => item.id), "Narrative Turn id");+ unique(value.selections.map((item) => item.id), "Narrative Selection id");+ unique(value.moments.map((item) => item.id), "Narrative Moment id");+ const anchorIds = unique(value.semanticIndex.anchors.map((item) => item.id), "Narrative Anchor id");+ const anchors = value.semanticIndex.anchors;+ if (anchors[0]?.id !== "program:start" || anchors[0].kind !== "program-start"+ || anchors.at(-1)?.id !== "program:end" || anchors.at(-1)?.kind !== "program-end") {+ throw new Error("Narrative semantic anchors must begin and end with the Program boundaries.");+ }+ const anchorOrder = new Map(anchors.map((anchor, index) => [anchor.id, index] as const));+ let tokenCursor = 0;+ for (const segment of value.segments) {+ if (!Number.isSafeInteger(segment.tokenStart) || !Number.isSafeInteger(segment.tokenEndExclusive)+ || segment.tokenStart !== tokenCursor || segment.tokenEndExclusive <= segment.tokenStart+ || segment.tokenEndExclusive > value.tokens.length+ || !anchorIds.has(segment.startAnchorId) || !anchorIds.has(segment.endAnchorId)) {+ throw new Error(`Narrative Segment ${segment.id} has invalid token or Anchor boundaries.`);+ }+ for (let index = segment.tokenStart; index < segment.tokenEndExclusive; index += 1) {+ const token = value.tokens[index]!;+ if (token.segmentId !== segment.id || !tokenIds.has(token.id)+ || !anchorIds.has(token.startAnchorId) || !anchorIds.has(token.endAnchorId)+ || token.text.length === 0 || token.normalized.length === 0) {+ throw new Error(`Narrative Token ${token.id} disagrees with Segment ${segment.id}.`);+ }+ }+ tokenCursor = segment.tokenEndExclusive;+ }+ if (tokenCursor !== value.tokens.length) throw new Error("Narrative Segments must partition Tokens in order.");+ for (const turn of value.turns) {+ if (!segmentIds.has(turn.segmentId) || !Number.isSafeInteger(turn.tokenStart)+ || !Number.isSafeInteger(turn.tokenEndExclusive) || turn.tokenEndExclusive <= turn.tokenStart+ || turn.tokenStart < 0 || turn.tokenEndExclusive > value.tokens.length+ || value.tokens.slice(turn.tokenStart, turn.tokenEndExclusive).some((token) => token.segmentId !== turn.segmentId)) {+ throw new Error(`Narrative Turn ${turn.id} has invalid Token coverage.`);+ }+ }+ for (const selection of value.selections) {+ const start = anchorOrder.get(selection.startAnchorId);+ const end = anchorOrder.get(selection.endAnchorId);+ if (start === undefined || end === undefined || end < start) {+ throw new Error(`Narrative Selection ${selection.id} has invalid Anchor order.`);+ }+ }+ for (const moment of value.moments) {+ if (!anchorIds.has(moment.anchorId)) throw new Error(`Narrative Moment ${moment.id} names an unknown Anchor.`);+ }+}++export function assertNarrativeExcerptIdentity(value: NarrativeExcerpt): void {+ if (value.kind !== "segment") throw new Error("NarrativeExcerpt must be a Segment.");+ nonempty(value.narrativeId, "NarrativeExcerpt narrativeId");+ nonempty(value.id, "NarrativeExcerpt id");+ if (!Number.isSafeInteger(value.tokenStart) || !Number.isSafeInteger(value.tokenEndExclusive)+ || value.tokenStart < 0 || value.tokenEndExclusive <= value.tokenStart) {+ throw new Error("NarrativeExcerpt Token coverage is invalid.");+ }+}++export function assertNarrativeSelectionRefIdentity(value: NarrativeSelectionRef): void {+ nonempty(value.narrativeId, "NarrativeSelection narrativeId");+ nonempty(value.id, "NarrativeSelection id");+ nonempty(value.startAnchorId, "NarrativeSelection startAnchorId");+ nonempty(value.endAnchorId, "NarrativeSelection endAnchorId");+}++export function assertNarrativeMomentRefIdentity(value: NarrativeMomentRef): void {+ nonempty(value.narrativeId, "NarrativeMoment narrativeId");+ nonempty(value.id, "NarrativeMoment id");+ nonempty(value.anchorId, "NarrativeMoment anchorId");+}++export function assertCaptionDocumentIdentity(value: CaptionDocument): void {+ nonempty(value.narrativeId, "CaptionDocument narrativeId");+ nonempty(value.id, "CaptionDocument id");+ if (value.units.length === 0 || value.words.length === 0) throw new Error("CaptionDocument is empty.");+ const unitIds = unique(value.units.map((item) => item.id), "CaptionDocument unit id");+ const wordIds = unique(value.words.map((item) => item.id), "CaptionDocument word id");+ const words = new Map(value.words.map((word) => [word.id, word] as const));+ const orderedWords: string[] = [];+ for (const unit of value.units) {+ if (unit.wordIds.length === 0 || unit.sourceTokenIds.length === 0) {+ throw new Error(`Caption unit ${unit.id} is empty.`);+ }+ for (const wordId of unit.wordIds) {+ const word = words.get(wordId);+ if (word === undefined || word.unitId !== unit.id || word.segmentId !== unit.segmentId+ || word.turnId !== unit.turnId || word.role !== unit.role) {+ throw new Error(`Caption unit ${unit.id} references a foreign word.`);+ }+ orderedWords.push(wordId);+ }+ }+ if (orderedWords.length !== wordIds.size+ || orderedWords.some((id, index) => id !== value.words[index]?.id)) {+ throw new Error("CaptionDocument units must partition words in order.");+ }+ unique(value.cueBreaks.map((item) => item.afterUnitId), "CaptionDocument Cue Break");+ if (value.cueBreaks.some((item) => !unitIds.has(item.afterUnitId))) {+ throw new Error("CaptionDocument Cue Break names an unknown unit.");+ }+}diff --git a/packages/narrative/src/index.ts b/packages/narrative/src/index.tsindex b4bf0b59..8621493e 100644--- a/packages/narrative/src/index.ts+++ b/packages/narrative/src/index.ts@@ -1,3 +1,11 @@export { narrativeDependency, narrativeManifest, narrativeModuleRef, narrativeTypes } from "./manifest.js";+export { narrativeComponent } from "./component.js";+export {+ assertCaptionDocumentIdentity,+ assertNarrativeExcerptIdentity,+ assertNarrativeIdentity,+ assertNarrativeMomentRefIdentity,+ assertNarrativeSelectionRefIdentity,+} from "./identity.js";export { captionDocumentSchema, narrativeExcerptSchema, narrativeMomentSchema, narrativeSchema, narrativeSelectionSchema } from "./schema.js";export type * from "./types.js";diff --git a/packages/narrative/src/schema.ts b/packages/narrative/src/schema.tsindex d29c67a2..b86f8b14 100644--- a/packages/narrative/src/schema.ts+++ b/packages/narrative/src/schema.ts@@ -5,8 +5,26 @@ const integer = { kind: "number", integer: true, minimum: 0 } as const;const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>,): ValueSchema => ({ kind: "object", fields });+const semanticAnchor: ValueSchema = { kind: "oneOf", variants: [+ object({+ id: { schema: { kind: "literal", value: "program:start" } },+ kind: { schema: { kind: "literal", value: "program-start" } },+ }),+ object({+ id: { schema: string }, kind: { schema: { kind: "string", enum: ["segment-start", "segment-end"] } },+ segmentId: { schema: string },+ }),+ object({+ id: { schema: string }, kind: { schema: { kind: "string", enum: ["token-start", "token-end"] } },+ segmentId: { schema: string }, tokenId: { schema: string },+ }),+ object({+ id: { schema: { kind: "literal", value: "program:end" } },+ kind: { schema: { kind: "literal", value: "program-end" } },+ }),+] };export const narrativeSchema: ValueSchema = object({-+ id: { schema: string },segments: { schema: { kind: "array", minItems: 1, items: object({id: { schema: string }, startAnchorId: { schema: string },endAnchorId: { schema: string }, tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },@@ -28,16 +46,12 @@ export const narrativeSchema: ValueSchema = object({}) } },semanticIndex: { schema: object({- anchors: { schema: { kind: "array", minItems: 2, items: object({- id: { schema: string },- kind: { schema: { kind: "string", enum: ["segment-start", "token-start", "token-end", "segment-end"] } },- segmentId: { schema: string }, tokenId: { schema: string, optional: true },- }) } },+ anchors: { schema: { kind: "array", minItems: 2, items: semanticAnchor } },}) },});export const narrativeExcerptSchema: ValueSchema = object({-+ narrativeId: { schema: string },kind: { schema: { kind: "literal", value: "segment" } }, id: { schema: string },tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },});@@ -57,17 +71,19 @@ const captionAlignmentUnit = object({});const captionCueBreak = object({ afterUnitId: { schema: string } });export const captionDocumentSchema: ValueSchema = object({-+ narrativeId: { schema: string },id: { schema: string },units: { schema: { kind: "array", minItems: 1, items: captionAlignmentUnit } },words: { schema: { kind: "array", minItems: 1, items: captionDisplayWord } },cueBreaks: { schema: { kind: "array", items: captionCueBreak } },});export const narrativeMomentSchema: ValueSchema = object({+ narrativeId: { schema: string },id: { schema: string },anchorId: { schema: string },});export const narrativeSelectionSchema: ValueSchema = object({+ narrativeId: { schema: string },id: { schema: string },startAnchorId: { schema: string }, endAnchorId: { schema: string },});diff --git a/packages/narrative/src/types.ts b/packages/narrative/src/types.tsindex 49a3c069..9878a3b9 100644--- a/packages/narrative/src/types.ts+++ b/packages/narrative/src/types.ts@@ -31,7 +31,10 @@ export type NarrativeSelection = {};/** One explicitly authored semantic window, independently referenceable by graph edges. */-export type NarrativeSelectionRef = NarrativeSelection;+export type NarrativeSelectionRef = NarrativeSelection & {+ /** Author-visible `<script id>` that owns this independently exported Selection. */+ readonly narrativeId: string;+};export type NarrativeMoment = {readonly id: string;@@ -40,7 +43,10 @@ export type NarrativeMoment = {};/** One explicitly authored semantic instant, independently referenceable by graph edges. */-export type NarrativeMomentRef = NarrativeMoment;+export type NarrativeMomentRef = NarrativeMoment & {+ /** Author-visible `<script id>` that owns this independently exported Moment. */+ readonly narrativeId: string;+};/** One author-visible word surface. Punctuation owned by the surface is preserved. */export type CaptionDisplayWord = {@@ -79,20 +85,37 @@ export type CaptionCueBreak = {/** Complete Script-owned Caption truth. It contains no frame or measured timing facts. */export type CaptionDocument = {+ /** Author-visible `<script id>` that owns this caption projection. */+ readonly narrativeId: string;readonly id: string;readonly units: readonly CaptionAlignmentUnit[];readonly words: readonly CaptionDisplayWord[];readonly cueBreaks: readonly CaptionCueBreak[];};-export type SemanticAnchor = {- readonly id: string;- readonly kind: "segment-start" | "token-start" | "token-end" | "segment-end";- readonly segmentId: string;- readonly tokenId?: string;-};+export type SemanticAnchor =+ | {+ readonly id: "program:start";+ readonly kind: "program-start";+ readonly segmentId?: never;+ readonly tokenId?: never;+ }+ | {+ readonly id: "program:end";+ readonly kind: "program-end";+ readonly segmentId?: never;+ readonly tokenId?: never;+ }+ | {+ readonly id: string;+ readonly kind: "segment-start" | "token-start" | "token-end" | "segment-end";+ readonly segmentId: string;+ readonly tokenId?: string;+ };export type Narrative = {+ /** Author-visible `<script id>`; every exported semantic view retains it. */+ readonly id: string;readonly segments: readonly NarrativeSegment[];readonly tokens: readonly NarrativeToken[];readonly turns: readonly NarrativeTurn[];@@ -110,6 +133,8 @@ export type Narrative = {*/export type NarrativeExcerpt = {readonly kind: "segment";+ /** Author-visible `<script id>` that owns this Segment. */+ readonly narrativeId: string;readonly id: string;readonly tokenStart: number;readonly tokenEndExclusive: number;diff --git a/packages/program-space/src/index.ts b/packages/program-space/src/index.tsindex 542d98a6..ba773ef7 100644--- a/packages/program-space/src/index.ts+++ b/packages/program-space/src/index.ts@@ -5,6 +5,10 @@ export type ProgramClock = {};export type ProgramSpace = {+ /** Author-visible identity of the SemanticTrack defining this time axis. */+ readonly id: string;+ /** Author-visible Script identity behind the semantic time axis. */+ readonly narrativeId: string;readonly durationSec: number;readonly frameRate: { readonly numerator: number; readonly denominator: number };};@@ -16,9 +20,12 @@ export const programSpaceTypes = {} satisfies Record<string, TypeRef>;const number = { kind: "number", minimum: 0 } as const;const integer = { kind: "number", integer: true, minimum: 0 } as const;+const string = { kind: "string", minLength: 1 } as const;export const programSpaceSchema: ValueSchema = {kind: "object",fields: {+ id: { schema: string },+ narrativeId: { schema: string },durationSec: { schema: number },frameRate: { schema: { kind: "object", fields: {numerator: { schema: integer }, denominator: { schema: integer },@@ -83,7 +90,8 @@ export function programFrameSampleBoundary(}export function assertProgramSpaceIdentity(programSpace: ProgramSpace): void {const { numerator, denominator } = programSpace.frameRate;- if (!Number.isSafeInteger(numerator) || numerator <= 0 || !Number.isSafeInteger(denominator)+ if (!programSpace.id.trim() || !programSpace.narrativeId.trim()+ || !Number.isSafeInteger(numerator) || numerator <= 0 || !Number.isSafeInteger(denominator)|| denominator <= 0 || !Number.isFinite(programSpace.durationSec) || programSpace.durationSec <= 0) {throw new Error("ProgramSpace is invalid.");}diff --git a/packages/provider-media-aws-lambda/README.md b/packages/provider-media-aws-lambda/README.mdindex c88a40d1..246e9dde 100644--- a/packages/provider-media-aws-lambda/README.md+++ b/packages/provider-media-aws-lambda/README.md@@ -1,6 +1,6 @@# `@hypit/provider-media-aws-lambda`-AWS Lambda Endpoint package for the eight exact capabilities declared by+AWS Lambda Endpoint package for the nine exact capabilities declared by`@hypit/media-pipeline` and implemented by `@hypit/media-execution`.The Provider invokes one versioned or aliased Lambda ARN synchronously. Source and result bytes staydiff --git a/packages/provider-media-aws-lambda/src/contract.ts b/packages/provider-media-aws-lambda/src/contract.tsindex e03700e6..bbf89425 100644--- a/packages/provider-media-aws-lambda/src/contract.ts+++ b/packages/provider-media-aws-lambda/src/contract.ts@@ -18,6 +18,7 @@ export const mediaLambdaOperations = ["transform","extract-audio","extract-frame",+ "render-still","project-speech-evidence-audio","render-audio","mux",diff --git a/packages/provider-media-aws-lambda/src/provider.ts b/packages/provider-media-aws-lambda/src/provider.tsindex f183f74d..869dd925 100644--- a/packages/provider-media-aws-lambda/src/provider.ts+++ b/packages/provider-media-aws-lambda/src/provider.ts@@ -145,6 +145,12 @@ export function createAwsLambdaMediaProvider(config: CreateAwsLambdaMediaProvidereturns: artifactTypes.blob,handler: operation("extract-frame"),},+ {+ lifecycle: "immediate" as const,+ capability: mediaPipelineCapabilities.renderStill,+ returns: artifactTypes.blob,+ handler: operation("render-still"),+ },{lifecycle: "immediate" as const,capability: mediaPipelineCapabilities.projectSpeechEvidenceAudio,diff --git a/packages/provider-media-local/README.md b/packages/provider-media-local/README.mdindex 8dcf0687..5a109414 100644--- a/packages/provider-media-local/README.md+++ b/packages/provider-media-local/README.md@@ -1,6 +1,6 @@# `@hypit/provider-media-local`-Trusted local ffprobe/ffmpeg implementation of `@hypit/media-pipeline`'s eight exact byte-operation+Trusted local ffprobe/ffmpeg implementation of `@hypit/media-pipeline`'s nine exact byte-operationcapabilities. It is Runtime configuration and is never imported by author `.svml`.```ts@@ -22,6 +22,7 @@ The Endpoint:- preserves source A/V offset through deterministic trim, delay, pad and crop operations;- emits a silent CFR H.264 visual and, when selected, an exact-length 48 kHz stereo PCM WAV.- transforms synchronized A/V, extracts generic reference audio and extracts exact source frames;+- encodes one authored image frame as an ordinary finite silent MP4 before normalization;- renders an explicit `AudioProgramPlan` into one exact-length 48 kHz stereo PCM `TimelineAudio`;- muxes exactly one verified silent visual stream and one verified program-audio stream into MP4;- distinguishes AAC coding-frame padding from the authoritative packet presentation span.diff --git a/packages/provider-media-local/src/provider.ts b/packages/provider-media-local/src/provider.tsindex bd278f46..ce15ea57 100644--- a/packages/provider-media-local/src/provider.ts+++ b/packages/provider-media-local/src/provider.ts@@ -8,6 +8,7 @@ import {executeNormalizeMedia,executeProjectSpeechEvidenceAudio,executeRenderTimelineAudio,+ executeRenderStillVideo,executeTransformMedia,} from "@hypit/media-execution";import type { MediaExecutionEnvironment, MediaOperationResult } from "@hypit/media-execution";@@ -112,6 +113,12 @@ export function createLocalMediaProvider(config: CreateLocalMediaProviderOptionsreturns: artifactTypes.blob,handler: operation(executeExtractFrame),},+ {+ lifecycle: "immediate" as const,+ capability: mediaPipelineCapabilities.renderStill,+ returns: artifactTypes.blob,+ handler: operation(executeRenderStillVideo),+ },{lifecycle: "immediate" as const,capability: mediaPipelineCapabilities.projectSpeechEvidenceAudio,diff --git a/packages/provider-media-local/test/provider.test.ts b/packages/provider-media-local/test/provider.test.tsindex 72826e8e..4da3d5af 100644--- a/packages/provider-media-local/test/provider.test.ts+++ b/packages/provider-media-local/test/provider.test.ts@@ -611,6 +611,40 @@ test("local media Provider transforms A/V and extracts ordinary audio and frameassert.equal(extractedFrame.mediaType, "image/png");const frameInspection = await inspectArtifact(artifacts, extractedFrame);assert.equal(frameInspection.streams.find((item) => item.kind === "video")?.decodedUnitCount, 1);++ const stillVideo = await executeArtifact(need(+ "need:render-still-video",+ mediaPipelineCapabilities.renderStill,+ artifactTypes.blob,+ canonicalize({+ source: extractedFrame,+ request: {+ frameRate: { numerator: 30, denominator: 1 },+ frameCount: 15,+ output: { container: "mp4", codec: "h264", pixelFormat: "yuv420p" },+ },+ }),+ ));+ assert.equal(stillVideo.mediaType, "video/mp4");+ const stillInspection = await inspectArtifact(artifacts, stillVideo);+ assert.equal(stillInspection.streams.length, 1);+ assert.equal(stillInspection.streams[0]?.kind, "video");+ assert.equal(stillInspection.streams[0]?.decodedUnitCount, 15);+ const stillSelection = selectMediaStreams(stillInspection, sealMediaSelectionRequest({+ video: { mode: "primary-moving" },+ audio: { mode: "none" },+ spanAuthority: "video",+ frameRate: { numerator: 30, denominator: 1 },+ }));+ const stillNormalized = await normalizeArtifact({+ artifacts,+ source: stillVideo,+ inspection: stillInspection,+ selection: stillSelection,+ frameRate: { numerator: 30, denominator: 1 },+ });+ assert.equal(stillNormalized.timeline.frameCount, 15);+ assert.equal(stillNormalized.audio, undefined);} finally {await rm(root, { recursive: true, force: true }).catch(() => {});}diff --git a/packages/ranking/README.md b/packages/ranking/README.mdindex 50a4cfe7..eab167d7 100644--- a/packages/ranking/README.md+++ b/packages/ranking/README.md@@ -6,8 +6,8 @@ Three independent progressive-ranking author components over one private schedul- `Column`- `TopThree`-The package owns variant-specific Programs and Styles. It consumes explicit Segment/Selection/Moment,-SemanticTrack, SpatialFrame, font, image and optional sound edges, then lowers to peer+The package owns variant-specific Programs and Styles. It consumes explicit Program/Segment/Selection/Moment,+SemanticTrack, Canvas, SpatialFrame, font, image and optional sound edges, then lowers to peer`VisualTrack` and optional `AudioTrack` values. It adds no Ranking field to Core, Composition orVisual IR.@@ -43,17 +43,43 @@ copy.```Column separates placement from reveal time. `rank` determines the numbered row only. Every-non-preset Item owns one Selection whose projected window is its reveal interval. Every sibling-window must already be disjoint and contained by the container's Segment/Selection `during` span;+non-preset Item owns one Segment or Selection whose projected window is its reveal interval. Every sibling+window must already be disjoint and contained by the container's Program/Segment/Selection `during` span;invalid input is refused instead of clamped or rearranged. Reveal time, child order and rank may all differ. A preset Itemhas no child `during` and is settled from the beginning of the outer window.-TierBoard and TopThree triggers and terminals are explicit `TemporalPoint` values. Column outer and-reveal inputs remain `TemporalWindow` values. Ranking consumes those projections plus-ProgramSpace and owns only the subsequent visual schedule; it does not locate-Moment/Selection frames internally.+TierBoard follows the same window contract. A preset Item is settled from the start and has no+`during` or `entry`. Every other Item owns one Segment or Selection and explicitly chooses `entry="direct"` or+`entry="drop"`. The windows must be contained, non-empty and mutually disjoint. Presets take the+innermost cells in author order; non-preset Items then take cells from inside to outside in strict+window order, regardless of child order. Its board and explanation stage are independent: `frame`+is only the continuous colored-label/dark-content tier table, while `canvas` supplies the coordinate+space for the stage. A direct Item appears in place at its target cell with a quick scale overshoot+and soft settle. A drop Item uses the same in-place entrance on the stage, holds perfectly still+while that Item is discussed, and only follows an eased curved glide into its target cell during the+final `move-frames` ending exactly at the window boundary. It then remains settled.-The Column's `frame` is the fixed left ranking rail; `canvas` supplies the independent coordinate-space for the large reveal stage. `stage-x` and `stage-y` are normalized Canvas coordinates. Each-normal reveal rises from below the Canvas, holds on that stage, then shrinks and moves into its-ranked content slot.+TierBoard and Column accept `during="program"` when their outer lifetime is the complete+SemanticTrack domain. The author Surface projects that Program source to the same `TemporalWindow`+consumed by the Ranking schedule; the component does not learn a separate Program timing mode.++```svml+<ranking:TierBoard id="tiers" semantic={speech.semantic} canvas={vertical}+ frame={layout.tiers} during={story.segment.tiers} style={tier-style}>+ <ranking:TierItem tier="s" preset="true" icon={brand}/>+ <ranking:TierItem tier="a" entry="direct" icon={first}+ during={story.selection.first}/>+ <ranking:TierItem tier="a" entry="drop" icon={second}+ during={story.selection.second}/>+</ranking:TierBoard>+```++TopThree triggers and its terminal remain explicit `TemporalInstant` values. TierBoard and Column+outer/reveal inputs are `TemporalWindow` values. Ranking consumes those projections plus+ProgramSpace and owns only the subsequent visual schedule; it never locates Moment/Selection+frames internally.++TierBoard and Column both separate their compact `frame` from an independent Canvas stage.+`stage-x` and `stage-y` are normalized Canvas coordinates, and `stage-size` is independent from the+settled cell size. Column reveals rise from below the Canvas; Tier entries appear in place, and only+`drop` entries later move from the stage into the board.diff --git a/packages/ranking/package.json b/packages/ranking/package.jsonindex 771e74f1..9cc4bc49 100644--- a/packages/ranking/package.json+++ b/packages/ranking/package.json@@ -23,6 +23,7 @@"@hypit/spatial": "workspace:*","@hypit/svs": "workspace:*","@hypit/temporal": "workspace:*",+ "@hypit/temporal-markup": "workspace:*","@hypit/text": "workspace:*","@hypit/markup": "workspace:*"},diff --git a/packages/ranking/preview/TierBoard.svg b/packages/ranking/preview/TierBoard.svgnew file mode 100644index 00000000..52fcbbe2--- /dev/null+++ b/packages/ranking/preview/TierBoard.svg@@ -0,0 +1,36 @@+<svg xmlns="http://www.w3.org/2000/svg" width="274" height="392" viewBox="0 0 274 392" fill="none">+ <!-- A compact crop of the real TierBoard: one continuous square-edged+ table, original row paint and typography, and icons inside its dark+ content column. The 24px side gutters remain visible when repeated. -->+ <g>+ <path d="M24 16H137V136H24Z" fill="#EE5F52"/>+ <path d="M24 136H137V256H24Z" fill="#F0A04C"/>+ <path d="M24 256H137V376H24Z" fill="#F0C84D"/>+ <path d="M137 16H250V376H137Z" fill="#2B2B30"/>++ <g fill="#2C2C2C" font-family="Inter,Arial,sans-serif" font-size="36" font-weight="400" text-anchor="middle">+ <text x="80.5" y="88">S</text>+ <text x="80.5" y="208">A</text>+ <text x="80.5" y="328">B</text>+ </g>++ <g>+ <rect x="145" y="28" width="96" height="96" rx="12" fill="#5B65C9"/>+ <circle cx="193" cy="76" r="26" fill="#FFFFFF" fill-opacity=".16"/>+ <path d="M186 59L210 76L186 93Z" fill="#FFFFFF"/>++ <rect x="145" y="148" width="96" height="96" rx="12" fill="#279CA8"/>+ <path d="M164 176H208V185H164ZM164 191H197V200H164ZM164 206H208V215H164Z" fill="#FFFFFF"/>+ <path d="M201 190L217 196L201 202Z" fill="#FFFFFF"/>++ <rect x="145" y="268" width="96" height="96" rx="12" fill="#C96254"/>+ <circle cx="185" cy="316" r="19" fill="none" stroke="#FFFFFF" stroke-width="8"/>+ <circle cx="207" cy="316" r="19" fill="none" stroke="#FFFFFF" stroke-width="8"/>+ </g>++ <g stroke="#111315" stroke-width="3">+ <path d="M24 136H250M24 256H250M137 16V376"/>+ <rect x="24" y="16" width="226" height="360"/>+ </g>+ </g>+</svg>diff --git a/packages/ranking/src/component.ts b/packages/ranking/src/component.tsindex e2ac1900..3be13405 100644--- a/packages/ranking/src/component.ts+++ b/packages/ranking/src/component.ts@@ -3,12 +3,12 @@ import type { SynchronizedMedia } from "@hypit/media";import type { ProgramSpace } from "@hypit/program-space";import { canonicalize } from "@hypit/protocol";import type { BlobRef, StoredValue } from "@hypit/protocol";-import type { TemporalPoint, TemporalWindow } from "@hypit/temporal";+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";import type { Text } from "@hypit/text";import { rankingProducers, rankingTypes } from "./manifest.js";-import { appendColumnItem, appendColumnWindow, appendRankingItemSpec, appendRankingSound, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertRankingSchedule, assertRankingSoundEventPlan, assertTierBoardProgram, assertTopThreeProgram, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, materializeRankingTextItem } from "./schedule.js";+import { appendColumnItem, appendColumnWindow, appendRankingItemSpec, appendRankingSound, appendTierBoardItem, appendTierBoardWindow, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertRankingSchedule, assertRankingSoundEventPlan, assertTierBoardProgram, assertTopThreeProgram, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSchedule, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTierBoardWindowSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, materializeRankingTextItem } from "./schedule.js";import {renderColumn,renderRankingAudio,@@ -33,6 +33,7 @@ import type {TierBoardItemSpec,TierBoardProgram,TierBoardStyle,+ TierBoardWindowSet,TopThreeItemSet,TopThreeItemSpec,TopThreeProgram,@@ -88,7 +89,7 @@ export const rankingComponent = {handler: ({ inputs }) => ({ outputs: { set: output(appendTriggeredRankingCandidate(inline<TriggeredRankingCandidateSet>(inputs.set?.value, "TriggeredRankingCandidateSet"),inline<RankingItemSpec>(inputs.spec?.value, "RankingItemSpec"),- inline<TemporalPoint>(inputs.activation?.value, "TemporalPoint"),+ inline<TemporalInstant>(inputs.activation?.value, "TemporalInstant"),)) }, needs: {} }),},{@@ -98,7 +99,29 @@ export const rankingComponent = {space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),outer: inline<TemporalWindow>(inputs.outer?.value, "TemporalWindow"),candidates: inline(inputs.candidates?.value, "TriggeredRankingCandidateSet"),- terminal: inline<TemporalPoint>(inputs.terminal?.value, "TemporalPoint"),+ terminal: inline<TemporalInstant>(inputs.terminal?.value, "TemporalInstant"),+ })) }, needs: {} }),+ },+ {+ producer: rankingProducers.createTierWindows,+ handler: () => ({ outputs: { set: output(createTierBoardWindowSet()) }, needs: {} }),+ },+ {+ producer: rankingProducers.appendTierWindow,+ handler: ({ inputs }) => ({ outputs: { set: output(appendTierBoardWindow(+ inline<TierBoardWindowSet>(inputs.set?.value, "TierBoardWindowSet"),+ inline<TierBoardItemSpec>(inputs.spec?.value, "TierBoardItemSpec"),+ inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),+ )) }, needs: {} }),+ },+ {+ producer: rankingProducers.tierSchedule,+ handler: ({ inputs }) => ({ outputs: { schedule: output(buildTierBoardSchedule({+ header: inline<RankingHeader>(inputs.header?.value, "RankingHeader"),+ items: inline<RankingItemSpecSet>(inputs.items?.value, "RankingItemSpecSet"),+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),+ outer: inline<TemporalWindow>(inputs.outer?.value, "TemporalWindow"),+ windows: inline<TierBoardWindowSet>(inputs.windows?.value, "TierBoardWindowSet"),})) }, needs: {} }),},{@@ -118,6 +141,7 @@ export const rankingComponent = {handler: ({ inputs }) => ({ outputs: { schedule: output(buildColumnSchedule({header: inline<RankingHeader>(inputs.header?.value, "RankingHeader"),items: inline<RankingItemSpecSet>(inputs.items?.value, "RankingItemSpecSet"),+ space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),outer: inline<TemporalWindow>(inputs.outer?.value, "TemporalWindow"),windows: inline<ColumnWindowSet>(inputs.windows?.value, "ColumnWindowSet"),})) }, needs: {} }),@@ -164,7 +188,8 @@ export const rankingComponent = {producer: rankingProducers.tierProgram,handler: ({ inputs }) => {const common = programInputs(inputs);- return { outputs: { program: output(buildTierBoardProgram(common.header, common.frame, common.schedule,+ return { outputs: { program: output(buildTierBoardProgram(common.header,+ inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), common.frame, common.schedule,inline<TierBoardStyle>(inputs.style?.value, "TierBoardStyle"), inline<TierBoardItemSet>(inputs.set?.value, "TierBoardItemSet"))) }, needs: {} };},},diff --git a/packages/ranking/src/fragment.ts b/packages/ranking/src/fragment.tsindex de96e102..790e75cd 100644--- a/packages/ranking/src/fragment.ts+++ b/packages/ranking/src/fragment.ts@@ -2,11 +2,10 @@ import { compositionTypes } from "@hypit/composition";import { sealGraphFragment } from "@hypit/elaborator";import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";import { mediaTypes } from "@hypit/media";-import { narrativeTypes } from "@hypit/narrative";import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { textTypes } from "@hypit/text";-import { temporalProducers, temporalTypes } from "@hypit/temporal";+import { temporalTypes } from "@hypit/temporal";import { rankingProducers, rankingTypes } from "./manifest.js";import type { RankingVariant } from "./types.js";@@ -20,7 +19,6 @@ export type RankingFragmentItem = {readonly iconName?: string;readonly contentName?: string;readonly timingName?: string;- readonly timingSpecName?: string;};export type RankingFragmentSound = {@@ -53,20 +51,17 @@ export function createRankingFragment(variant: RankingVariant,items: readonly RankingFragmentItem[],sound: RankingFragmentSound,- outerKind: "selection" | "segment" = "selection",) {if (items.length === 0) throw new Error("Ranking Fragment requires at least one Item.");const selected = definition(variant);const inputs: Array<GraphFragment["inputs"][number]> = [{ name: "header", type: rankingTypes.header },{ name: "semantic", type: semanticTrackTypes.track },- { name: "outer", type: outerKind === "selection" ? narrativeTypes.selection : narrativeTypes.excerpt },- { name: "outer-spec", type: temporalTypes.windowSpec },- ...(variant === "column" ? [] : [- { name: "terminal", type: narrativeTypes.moment },- { name: "terminal-spec", type: temporalTypes.pointSpec },- ]),- ...(variant === "column" ? [{ name: "canvas", type: spatialTypes.canvas }] : []),+ { name: "outer", type: temporalTypes.window },+ ...(variant === "top-three" ? [+ { name: "terminal", type: temporalTypes.instant },+ ] : []),+ ...(variant === "column" || variant === "tier-board" ? [{ name: "canvas", type: spatialTypes.canvas }] : []),{ name: "frame", type: spatialTypes.frame },{ name: "style", type: selected.style },];@@ -77,7 +72,8 @@ export function createRankingFragment({ id: "resolved", producer: selected.create, inputs: {}, result: { kind: "output", name: "set" } },{ id: "candidates", producer: variant === "column"? rankingProducers.createColumnWindows- : rankingProducers.createTriggeredCandidates, inputs: {}, result: { kind: "output" as const, name: "set" } },+ : variant === "tier-board" ? rankingProducers.createTierWindows+ : rankingProducers.createTriggeredCandidates, inputs: {}, result: { kind: "output" as const, name: "set" } },];let specs = operation("specs");let resolved = operation("resolved");@@ -88,10 +84,8 @@ export function createRankingFragment(if (item.iconName !== undefined) inputs.push({ name: item.iconName, type: mediaTypes.blobArtifact });if (item.timingName !== undefined) inputs.push({name: item.timingName,- type: variant === "column" ? narrativeTypes.selection : narrativeTypes.moment,+ type: variant === "top-three" ? temporalTypes.instant : temporalTypes.window,});- if (item.timingSpecName !== undefined) inputs.push({ name: item.timingSpecName,- type: variant === "column" ? temporalTypes.windowSpec : temporalTypes.pointSpec });const materializedId = `materialize-${item.suffix}`;if (item.contentName !== undefined) operations.push({id: materializedId,@@ -121,66 +115,36 @@ export function createRankingFragment(});resolved = operation(visualId);if (item.timingName !== undefined) {- const projectionId = `${variant === "column" ? "window" : "point"}-${item.suffix}`;- operations.push({- id: projectionId,- producer: variant === "column" ? temporalProducers.projectSelection : temporalProducers.projectMomentPoint,- inputs: {- semantic: input("semantic"), spec: input(item.timingSpecName!),- [variant === "column" ? "selection" : "moment"]: input(item.timingName),- },- result: { kind: "output", name: variant === "column" ? "window" : "point" },- });const timingId = `timing-${item.suffix}`;operations.push({id: timingId,producer: variant === "column"? rankingProducers.appendColumnWindow- : rankingProducers.appendTriggeredCandidate,+ : variant === "tier-board" ? rankingProducers.appendTierWindow+ : rankingProducers.appendTriggeredCandidate,inputs: {set: candidates, spec: resolvedSpec,- [variant === "column" ? "window" : "activation"]: operation(projectionId),+ [variant === "top-three" ? "activation" : "window"]: input(item.timingName),},result: { kind: "output", name: "set" },});candidates = operation(timingId);}}- if (variant === "column") {- operations.push({- id: "outer-window",- producer: outerKind === "selection" ? temporalProducers.projectSelection : temporalProducers.projectSegment,- inputs: {- semantic: input("semantic"), spec: input("outer-spec"),- [outerKind === "selection" ? "selection" : "segment"]: input("outer"),- },- result: { kind: "output", name: "window" },- });+ if (variant === "column" || variant === "tier-board") {operations.push({id: "schedule",- producer: rankingProducers.columnSchedule,- inputs: { header: input("header"), items: specs, outer: operation("outer-window"), windows: candidates },+ producer: variant === "column" ? rankingProducers.columnSchedule : rankingProducers.tierSchedule,+ inputs: { header: input("header"), items: specs, space: operation("space"), outer: input("outer"), windows: candidates },result: { kind: "output", name: "schedule" },});} else {- operations.push({- id: "outer-window",- producer: temporalProducers.projectSelection,- inputs: { semantic: input("semantic"), selection: input("outer"), spec: input("outer-spec") },- result: { kind: "output", name: "window" },- });- operations.push({- id: "terminal-point",- producer: temporalProducers.projectMomentPoint,- inputs: { semantic: input("semantic"), moment: input("terminal"), spec: input("terminal-spec") },- result: { kind: "output", name: "point" },- });operations.push({id: "schedule",producer: rankingProducers.schedule,inputs: {header: input("header"), items: specs, space: operation("space"),- outer: operation("outer-window"), candidates, terminal: operation("terminal-point"),+ outer: input("outer"), candidates, terminal: input("terminal"),},result: { kind: "output", name: "schedule" },});@@ -190,7 +154,7 @@ export function createRankingFragment(producer: selected.build,inputs: {header: input("header"),- ...(variant === "column" ? { canvas: input("canvas") } : {}),+ ...(variant === "column" || variant === "tier-board" ? { canvas: input("canvas") } : {}),frame: input("frame"), schedule: operation("schedule"), style: input("style"), set: resolved,},result: { kind: "output", name: "program" },diff --git a/packages/ranking/src/index.ts b/packages/ranking/src/index.tsindex 6bbb20a6..1e29b20b 100644--- a/packages/ranking/src/index.ts+++ b/packages/ranking/src/index.ts@@ -1,4 +1,5 @@-export { appendColumnWindow, appendRankingItemSpec, appendRankingSound, appendColumnItem, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertColumnStyle, assertColumnWindowSet, assertRankingHeader, assertRankingItemSpec, assertRankingItemSpecSet, assertRankingTextItemShell, assertRankingSchedule, assertRankingSoundEventPlan, assertRankingSoundStyle, assertTierBoardProgram, assertTierBoardStyle, assertTopThreeProgram, assertTopThreeStyle, assertTriggeredRankingCandidateSet, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, sealRankingHeader, sealRankingTextItemShell, materializeRankingTextItem } from "./schedule.js";+export { appendColumnWindow, appendTierBoardWindow, appendRankingItemSpec, appendRankingSound, appendColumnItem, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertColumnStyle, assertColumnWindowSet, assertTierBoardWindowSet, assertRankingHeader, assertRankingItemSpec, assertRankingItemSpecSet, assertRankingTextItemShell, assertRankingSchedule, assertRankingSoundEventPlan, assertRankingSoundStyle, assertTierBoardProgram, assertTierBoardStyle, assertTopThreeProgram, assertTopThreeStyle, assertTriggeredRankingCandidateSet, buildColumnProgram, buildColumnSchedule, buildTierBoardSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowSet, createTierBoardWindowSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, resolveTierBoardMotion, sealRankingHeader, sealRankingTextItemShell, materializeRankingTextItem } from "./schedule.js";+export { directTierItemPose, fromHighTierItemPose, tierBoardGeometry, tierCell, tierStageGeometry } from "./tier.js";export {decodeColumnStyle,decodeTierBoardStyle,@@ -13,7 +14,7 @@ export {export { rankingComponent } from "./component.js";export { createRankingFragment } from "./fragment.js";export type { RankingFragmentItem, RankingFragmentSound } from "./fragment.js";-export { columnWindowSetSchema, triggeredRankingCandidateSetSchema, rankingDependency, rankingHeaderSchema, rankingItemSpecSchema, rankingTextItemShellSchema, rankingItemSpecSetSchema, rankingManifest, rankingMarkupSurfaces, rankingModuleRef, rankingProducers, rankingScheduleSchema, rankingSoundEventsSchema, rankingSoundSetSchema, rankingSoundStyleSchema, rankingTypes } from "./manifest.js";+export { rankingWindowSetSchema, tierBoardWindowSetSchema, columnWindowSetSchema, triggeredRankingCandidateSetSchema, rankingDependency, rankingHeaderSchema, rankingItemSpecSchema, rankingTextItemShellSchema, rankingItemSpecSetSchema, rankingManifest, rankingMarkupSurfaces, rankingModuleRef, rankingProducers, rankingScheduleSchema, rankingSoundEventsSchema, rankingSoundSetSchema, rankingSoundStyleSchema, rankingTypes } from "./manifest.js";export {decodeColumnStyleSurface,decodeColumnSurface,diff --git a/packages/ranking/src/manifest.ts b/packages/ranking/src/manifest.tsindex 9c56acfd..0987319e 100644--- a/packages/ranking/src/manifest.ts+++ b/packages/ranking/src/manifest.ts@@ -9,7 +9,8 @@ import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/pimport { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";import { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";-import { temporalDependency, temporalTypes } from "@hypit/temporal";+import { temporalDependency, temporalInstantSchema, temporalTypes, temporalWindowSchema } from "@hypit/temporal";+import { temporalInstantAttributeVocabulary } from "@hypit/temporal-markup";import { textDependency, textTypes } from "@hypit/text";const previewImage = (file: string, mediaType = "image/png") => ({@@ -25,6 +26,7 @@ export const rankingTypes = {textItemShell: { module: rankingModuleRef, name: "RankingTextItemShell" },itemSpecs: { module: rankingModuleRef, name: "RankingItemSpecSet" },triggeredCandidates: { module: rankingModuleRef, name: "TriggeredRankingCandidateSet" },+ tierWindows: { module: rankingModuleRef, name: "TierBoardWindowSet" },columnWindows: { module: rankingModuleRef, name: "ColumnWindowSet" },schedule: { module: rankingModuleRef, name: "RankingSchedule" },soundStyle: { module: rankingModuleRef, name: "RankingSoundStyle" },@@ -47,6 +49,9 @@ export const rankingProducers = {createTriggeredCandidates: { module: rankingModuleRef, name: "create-triggered-ranking-candidates" },appendTriggeredCandidate: { module: rankingModuleRef, name: "append-triggered-ranking-candidate" },schedule: { module: rankingModuleRef, name: "build-ranking-schedule" },+ createTierWindows: { module: rankingModuleRef, name: "create-tier-board-windows" },+ appendTierWindow: { module: rankingModuleRef, name: "append-tier-board-window" },+ tierSchedule: { module: rankingModuleRef, name: "build-tier-board-schedule" },createColumnWindows: { module: rankingModuleRef, name: "create-column-windows" },appendColumnWindow: { module: rankingModuleRef, name: "append-column-window" },columnSchedule: { module: rankingModuleRef, name: "build-column-schedule" },@@ -92,6 +97,8 @@ const rankingRecipeSchemas = {"font-size": { kind: "number", minimum: 0 },"font-weight": { kind: "number", integer: true, minimum: 1 },"text-color": recipeColor,+ "label-text-color": recipeColor,+ "label-size": { kind: "number", minimum: 0 },"line-height": { kind: "number", minimum: 0 },"board-background": recipeColor,"board-border-color": recipeColor,@@ -102,10 +109,11 @@ const rankingRecipeSchemas = {"board-shadow-blur": { kind: "number", minimum: 0 },"board-shadow-spread": { kind: "number" },"board-shadow-color": recipeColor,- "appear-frames": { kind: "number", integer: true, minimum: 0 },- "move-frames": { kind: "number", integer: true, minimum: 0 },+ "appear-frames": { kind: "number", integer: true, minimum: 1 },+ "move-frames": { kind: "number", integer: true, minimum: 1 },"motion-easing": { kind: "string", enum: ["linear", "ease-in", "ease-out", "ease-in-out"] },- "label-width": { kind: "number", minimum: 0 },+ "label-width": { kind: "number", minimum: 0.08, maximum: 0.3 },+ "icon-radius-ratio": { kind: "number", minimum: 0 },padding: { kind: "number", minimum: 0 },"row-height": { kind: "number", minimum: 0 },"row-gap": { kind: "number", minimum: 0 },@@ -113,8 +121,8 @@ const rankingRecipeSchemas = {"icon-size": { kind: "number", minimum: 0 },"icon-radius": { kind: "number", minimum: 0 },"icon-fit": { kind: "string", enum: ["contain", "cover"] },- "stage-x": { kind: "number" },- "stage-y": { kind: "number" },+ "stage-x": { kind: "number", minimum: 0, maximum: 1 },+ "stage-y": { kind: "number", minimum: 0, maximum: 1 },"stage-size": { kind: "number", minimum: 0 },"center-x": { kind: "number" },"baseline-y": { kind: "number" },@@ -158,7 +166,12 @@ export const rankingHeaderSchema: ValueSchema = object({id: { schema: string }, variant: { schema: variants },});export const rankingItemSpecSchema: ValueSchema = { kind: "oneOf", variants: [- object({ variant: { schema: { kind: "literal", value: "tier-board" } }, ...itemBase, tier: { schema: string }, entry: { schema: { kind: "string", enum: ["direct", "stage"] } } }),+ object({ variant: { schema: { kind: "literal", value: "tier-board" } }, ...itemBase,+ tier: { schema: string }, preset: { schema: { kind: "literal", value: true } },+ }),+ object({ variant: { schema: { kind: "literal", value: "tier-board" } }, ...itemBase,+ tier: { schema: string }, preset: { schema: { kind: "literal", value: false } }, entry: { schema: { kind: "string", enum: ["direct", "drop"] } },+ }),object({ variant: { schema: { kind: "literal", value: "column" } }, ...itemBase,label: { schema: string }, rank: { schema: { kind: "number", integer: true, minimum: 1 } }, preset: { schema: { kind: "boolean" } },}),@@ -177,32 +190,27 @@ export const rankingItemSpecSetSchema: ValueSchema = object({const frameSpan = object({ startFrame: { schema: unsigned }, endFrameExclusive: { schema: unsigned } });export const triggeredRankingCandidateSetSchema: ValueSchema = object({entries: { schema: { kind: "array", items: object({- itemId: { schema: string }, activation: { schema: object({- id: { schema: string }, source: { schema: object({ kind: { schema: string }, id: { schema: string } }) },- projection: { schema: object({}, true) }, frame: { schema: unsigned },- }) },+ itemId: { schema: string }, activation: { schema: temporalInstantSchema },}) } },});-export const columnWindowSetSchema: ValueSchema = object({+export const rankingWindowSetSchema: ValueSchema = object({entries: { schema: { kind: "array", items: object({- itemId: { schema: string }, window: { schema: object({- id: { schema: string }, source: { schema: object({ kind: { schema: string }, id: { schema: string } }) },- projection: { schema: object({ start: { schema: object({}, true) }, end: { schema: object({}, true) } }) },- span: { schema: frameSpan },- }) },+ itemId: { schema: string }, window: { schema: temporalWindowSchema },}) } },});+export const tierBoardWindowSetSchema = rankingWindowSetSchema;+export const columnWindowSetSchema = rankingWindowSetSchema;const triggeredScheduleSchema: ValueSchema = object({id: { schema: string },- variant: { schema: { kind: "string", enum: ["tier-board", "top-three"] } },+ variant: { schema: { kind: "literal", value: "top-three" } },outer: { schema: frameSpan }, terminalFrame: { schema: unsigned },entries: { schema: { kind: "array", minItems: 1, items: object({itemId: { schema: string }, triggerFrame: { schema: unsigned },stage: { schema: frameSpan }, cumulative: { schema: frameSpan }, settled: { schema: frameSpan },}) } },});-const columnScheduleSchema: ValueSchema = object({- id: { schema: string }, variant: { schema: { kind: "literal", value: "column" } }, outer: { schema: frameSpan },+const windowedScheduleSchema = (variant: "tier-board" | "column"): ValueSchema => object({+ id: { schema: string }, variant: { schema: { kind: "literal", value: variant } }, outer: { schema: frameSpan },entries: { schema: { kind: "array", minItems: 1, items: { kind: "oneOf", variants: [object({ itemId: { schema: string }, mode: { schema: { kind: "literal", value: "preset" } }, settled: { schema: frameSpan } }),object({ itemId: { schema: string }, mode: { schema: { kind: "literal", value: "reveal" } },@@ -210,7 +218,9 @@ const columnScheduleSchema: ValueSchema = object({}),] } } },});-export const rankingScheduleSchema: ValueSchema = { kind: "oneOf", variants: [triggeredScheduleSchema, columnScheduleSchema] };+export const rankingScheduleSchema: ValueSchema = { kind: "oneOf", variants: [+ triggeredScheduleSchema, windowedScheduleSchema("tier-board"), windowedScheduleSchema("column"),+] };const styleSchema = (): ValueSchema => object({}, true);const setSchema = (): ValueSchema => object({items: { schema: { kind: "array", items: object({}, true) } },@@ -242,74 +252,48 @@ export const rankingMarkupSurfaces = [{ name: "id", kind: "identifier", required: true,summary: "Names this Style so a TierBoard can reference it." },{ name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],- summary: "Chooses the Recipe carrying the tier rows, board Paint, row and cell geometry, icon treatment, staging pose and motion.",+ summary: "Chooses the Recipe carrying the tier rows, board Paint, row and cell geometry, icon treatment and entrance motion.",recipe: typedRecipeProperties([{ name: "rows", required: false, fallback: [- { id: "s", label: "S", color: "#ef4444" },- { id: "a", label: "A", color: "#f59e0b" },- { id: "b", label: "B", color: "#22c55e" },- { id: "c", label: "C", color: "#3b82f6" },+ { id: "s", label: "S", color: "#EE5F52" },+ { id: "a", label: "A", color: "#F0A04C" },+ { id: "b", label: "B", color: "#F0C84D" },+ { id: "c", label: "C", color: "#EDE356" },+ { id: "d", label: "D", color: "#A6DA7B" },], summary: "Defines the ordered tier rows the board draws, each with an id, label and color." },- { name: "font-size", required: false, fallback: "28",- summary: "Sets the size in pixels the Item copy is set at." },- { name: "font-weight", required: false, fallback: "700",- summary: "Sets the weight the Item copy is set at." },- { name: "text-color", required: false, fallback: "#ffffff",- summary: "Sets the color the Item copy is drawn in." },- { name: "line-height", required: false, fallback: "1.15",- summary: "Sets the line height the Item copy is set on, as a multiple of its size." },- { name: "board-background", required: false, fallback: "#151821",- summary: "Sets the color the board fills with." },- { name: "board-border-color", required: false, fallback: "#ffffff33",- summary: "Sets the color of the board's border." },- { name: "board-border-width", required: false, fallback: "1",- summary: "Sets the width in pixels of the board's border." },- { name: "board-radius", required: false, fallback: "18",- summary: "Sets the corner radius in pixels of the board." },- { name: "board-shadow-x", required: false, fallback: "0",- summary: "Offsets the board's shadow horizontally in pixels." },- { name: "board-shadow-y", required: false, fallback: "10",- summary: "Offsets the board's shadow vertically in pixels." },- { name: "board-shadow-blur", required: false, fallback: "24",- summary: "Sets the blur radius in pixels of the board's shadow." },- { name: "board-shadow-spread", required: false, fallback: "0",- summary: "Sets the spread in pixels of the board's shadow." },- { name: "board-shadow-color", required: false, fallback: "#00000066",- summary: "Sets the color of the board's shadow." },- { name: "appear-frames", required: false, fallback: "6",- summary: "Sets how many frames an Item takes to appear." },- { name: "move-frames", required: false, fallback: "8",- summary: "Sets how many frames a staged Item takes to move into its row." },- { name: "motion-easing", required: false, fallback: "ease-in-out",- values: ["linear", "ease-in", "ease-out", "ease-in-out"],- summary: "Selects the easing both the appearance and the move are timed with." },- { name: "label-width", required: false, fallback: "72",- summary: "Sets the width in pixels of the column the row labels are set in." },- { name: "padding", required: false, fallback: "18",- summary: "Sets the inset in pixels between the board's edge and its rows." },- { name: "row-height", required: false, fallback: "92",- summary: "Sets the height in pixels of one tier row." },- { name: "row-gap", required: false, fallback: "10",- summary: "Sets the gap in pixels between tier rows." },- { name: "cell-gap", required: false, fallback: "12",- summary: "Sets the gap in pixels between the Items within one row." },- { name: "icon-size", required: false, fallback: "72",- summary: "Sets the size in pixels an Item's icon is drawn at." },- { name: "icon-radius", required: false, fallback: "12",- summary: "Sets the corner radius in pixels of an Item's icon." },+ { name: "label-text-color", required: false, fallback: "#2c2c2c",+ summary: "Sets the color of the row letters." },+ { name: "label-size", required: false, fallback: "0.3",+ summary: "Sets each row letter's size as a fraction of the row height." },+ { name: "line-height", required: false, fallback: "1",+ summary: "Sets the row letter line height as a multiple of its size." },+ { name: "board-background", required: false, fallback: "#2b2b30",+ summary: "Sets the grey content area behind the placed icons." },+ { name: "board-border-color", required: false, fallback: "#111315",+ summary: "Sets the continuous grid-line color around and between the tier rows." },+ { name: "board-border-width", required: false, fallback: "3",+ summary: "Sets the grid-line width in pixels." },+ { name: "label-width", required: false,+ summary: "Overrides the label column width as a fraction of the board Frame width; when absent it is derived from row height." },+ { name: "stage-x", required: false, fallback: "0.2",+ summary: "Places the independent explanation stage horizontally as a fraction of the Canvas width." },+ { name: "stage-y", required: false, fallback: "0.3",+ summary: "Places the independent explanation stage vertically as a fraction of the Canvas height." },+ { name: "stage-size", required: false, fallback: "168",+ summary: "Sets the staged Item size in Canvas pixels independently from its settled tier cell." },+ { name: "icon-radius-ratio", required: false, fallback: "0.12",+ summary: "Sets icon corner radius as a fraction of one tier row's height." },{ name: "icon-fit", required: false, fallback: "cover",values: ["contain", "cover"],summary: "Decides whether an Item's icon fits inside its box or fills it." },- { name: "stage-x", required: false, fallback: "0.5",- summary: "Places the staging point horizontally, as a fraction of the Frame's width." },- { name: "stage-y", required: false, fallback: "0.23",- summary: "Places the staging point vertically, as a fraction of the Frame's height." },- { name: "stage-size", required: false, fallback: "108",- summary: "Sets the size in pixels a staged Item is drawn at before it moves in." },+ { name: "appear-frames", required: false, fallback: "8",+ summary: "Sets the quick in-place scale-and-fade entrance duration for both entry modes." },+ { name: "move-frames", required: false, fallback: "14",+ summary: "Sets the final eased curved glide duration of a staged Item; it always ends at the Item window's end." },{ name: "board-stack", required: false, fallback: "20",summary: "Sets the draw order the board itself is placed at." },{ name: "stage-stack", required: false, fallback: "25",- summary: "Sets the draw order the staging area is placed at." },+ summary: "Sets the draw order a drop Item uses while it occupies the independent stage." },{ name: "item-stack", required: false, fallback: "30",summary: "Sets the draw order every Item is placed at, unless the Item overrides it." },{ name: "appear-gain", required: false, fallback: "1",@@ -499,54 +483,56 @@ export const rankingMarkupSurfaces = ["The element is empty; it accepts no children and no text.","The Recipe is validated against the variant, so a Recipe holding another board's keys is refused by name.","The Recipe carries one color per podium slot, so a TopThree Style always resolves three of them.",- "Every other property is refused by name, except the board Paint and `stage-stack` keys, which a podium accepts and never reads.",+ "Every other property is refused by name.",],} },- { name: "tier", tag: "TierBoard", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, temporalTypes.pointSpec, temporalTypes.windowSpec, rankingTypes.schedule, rankingTypes.tierProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],+ { name: "tier", tag: "TierBoard", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.tierProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],vocabulary: {- summary: "Places ordered Items into tier rows at the Moment owned by each Item, and publishes the board and the Tracks it renders to.",+ summary: "Places Items into tier rows from preset state or explicit reveal Selections, and publishes the board and the Tracks it renders to.",appearance:- "One rounded, bordered, shadowed board filling its Frame, with the Style's tier rows stacked down it from the top: each row is a full-width bar in that tier's own color, its short label set in a fixed-width column at the row's left edge. Items are square rounded icon tiles with no copy of their own; each lands in the row its `tier` names and packs left to right after the label column in chronological order of the Items' Moments. A tile written `direct` fades and rises into its cell over the appear frames; a tile written `stage` appears first inside a dashed square floating near the top of the Frame, holds there at stage size, then shrinks and travels into its cell. Every tile already placed stays exactly where it landed while the later ones arrive.",- preview: previewImage("TierBoard.png"),+ "The board occupies only its Frame: one continuous tier table with colored label cells, a dark content field and dark grid lines. An independent explanation stage is positioned in Canvas space. Preset tiles occupy the innermost cells from the first frame. Every other tile takes one explicit Segment or Selection window; sorting those disjoint windows gives the strict reveal order and fills each tier from inside to outside. Both entry modes appear in place with a quick overshoot and soft settle. A direct tile appears in its final cell. A drop tile appears on the stage, remains still while that Item is discussed, then follows an eased curved glide into its final cell during the window's last move interval. Every placed tile remains settled while later ones arrive.",+ preview: previewImage("TierBoard.svg", "image/svg+xml"),attributes: [{ name: "id", kind: "identifier", required: true,summary: "Names this board so its Schedule, Program and Tracks can be referenced elsewhere in the Source." },{ name: "semantic", kind: "reference", required: true, accepts: [semanticTrackTypes.track],- summary: "Chooses the SemanticTrack that owns the frame domain and resolves every Item Moment." },+ summary: "Chooses the SemanticTrack that owns the frame domain and resolves the board and Item windows." },+ { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],+ summary: "Chooses the Canvas coordinate space used by the independent explanation stage." },{ name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],- summary: "Chooses the Frame the whole board occupies." },- { name: "during", kind: "reference", required: true, accepts: [narrativeTypes.selection],- summary: "Chooses the Selection the board is on screen for." },- { name: "terminal", kind: "reference", required: true, accepts: [narrativeTypes.moment],- summary: "Chooses the Moment the board settles on and ends after." },+ summary: "Chooses the compact Frame occupied only by the tier table." },+ { name: "during", kind: "expression", required: true, values: ["program"], accepts: [narrativeTypes.selection, narrativeTypes.excerpt],+ summary: "Spans the complete SemanticTrack when written as program, or projects the referenced Segment or Selection into the board lifetime." },{ name: "style", kind: "reference", required: true, accepts: [rankingTypes.tierStyle],summary: "Chooses the TierBoardStyle this board is drawn in, and only that variant's." },{ name: "appear-sound", kind: "reference", required: false, accepts: [mediaTypes.synchronized],summary: "Chooses the Synchronized Medium played as each Item appears." },{ name: "move-sound", kind: "reference", required: false, accepts: [mediaTypes.synchronized],- summary: "Chooses the Synchronized Medium played as a staged Item moves into its row." },+ summary: "Chooses the Synchronized Medium played when a drop Item leaves the independent stage near the end of its window." },],children: [{ tag: "TierItem", cardinality: "many",- summary: "One Item of the board, placed at its own Moment; it is empty.",+ summary: "One icon tile of the board; it is either preset or owns one Segment or Selection reveal window and is empty.",attributes: [{ name: "id", kind: "identifier", required: false,summary: "Names this Item within the board; an omitted id is generated from the Item's position." },{ name: "tier", kind: "literal", required: true,summary: "Chooses the row of the Style Recipe this Item is placed into." },- { name: "entry", kind: "literal", required: false, values: ["direct", "stage"],- summary: "Decides whether the Item lands in its row directly or stages first and moves in, and defaults to direct." },+ { name: "preset", kind: "literal", required: false, values: ["true", "false"],+ summary: "Makes the Item occupy its tier from the start; a preset Item has no during or entry." },+ { name: "entry", kind: "literal", required: false, values: ["direct", "drop"],+ summary: "Chooses an in-place entrance in the final cell or on the independent stage; a staged Item holds for the explanation, then glides into the tier at the window end. It is required for non-preset Items and forbidden for preset Items." },{ name: "icon", kind: "reference", required: true, accepts: [mediaTypes.blobArtifact],summary: "Chooses the image drawn beside the Item." },- { name: "at", kind: "reference", required: true, accepts: [narrativeTypes.moment],- summary: "Chooses the Moment when this Item appears; chronological order is derived from these item-owned Moments." },+ { name: "during", kind: "reference", required: false, accepts: [narrativeTypes.selection, narrativeTypes.excerpt],+ summary: "Chooses this non-preset Item's exact Segment or Selection interval; all sibling intervals must be disjoint." },{ name: "stack", kind: "literal", required: false,summary: "Overrides the Style's draw order for this Item alone." },] },],ports: [{ name: "schedule", type: rankingTypes.schedule,- summary: "The resolved Schedule: each Item's trigger frame and its staged, cumulative and settled spans." },+ summary: "The resolved Schedule: preset occupancy plus each revealed Item's exact window and settled span." },{ name: "program", type: rankingTypes.tierProgram,summary: "The resolved board: its Frame, Style, Schedule and ordered Items." },{ name: "visual", type: compositionTypes.visualTrack,@@ -555,35 +541,37 @@ export const rankingMarkupSurfaces = [summary: "The rendered board sound, published only when a sound is authored." },],example: `<ranking:TierBoardStyle id="tier-style" recipe={recipes.ranking.tier} font={ui-font}/>-<ranking:TierBoard id="tiers" semantic={speech.semantic} frame={board-frame}- during={story.selection.board} terminal={story.moment.done}+<ranking:TierBoard id="tiers" semantic={speech.semantic} canvas={vertical} frame={board-frame}+ during="program"style={tier-style}>- <ranking:TierItem id="row-regen" tier="s" icon={icon-regen} at={story.moment.regen}/>- <ranking:TierItem id="row-remini" tier="a" entry="stage" icon={icon-remini} at={story.moment.remini}/>+ <ranking:TierItem id="row-regen" tier="s" preset="true" icon={icon-regen}/>+ <ranking:TierItem id="row-remini" tier="a" entry="drop" icon={icon-remini} during={story.selection.remini}/></ranking:TierBoard>`,notes: ["The board requires at least one TierItem, accepts no other child and no text of its own, and Item ids must be unique within it.",- "`move-sound` requires at least one TierItem written `entry=\"stage\"`; a sound with nothing to sound on is refused.",+ "Every non-preset Item consumes a non-empty Segment or Selection of at least two frames; windows must be inside the board and non-overlapping.",+ "Preset Items occupy the inner cells in author order. Revealed Items follow in strict window order, independent of child order.",+ "`move-sound` requires at least one TierItem written `entry=\"drop\"`; a sound with nothing to sound on is refused.","Authoring either sound also connects the Style's `.sound` output, so `style` must name a TierBoardStyle written in this Source.",],} },- { name: "column", tag: "Column", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.windowSpec, rankingTypes.schedule, rankingTypes.columnProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],+ { name: "column", tag: "Column", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.columnProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],vocabulary: {- summary: "Places rows by explicit rank, reveals each non-preset row in its own Selection, and publishes the board and the Tracks it renders to.",+ summary: "Places rows by explicit rank, reveals each non-preset row in its own Segment or Selection, and publishes the board and the Tracks it renders to.",appearance:- "A narrow vertical rank rail occupies its Frame while a large reveal stage is positioned independently in Canvas space. Preset rows are settled from the first frame. Each other row rises into the stage during its own projected Selection, then shrinks and moves into the content slot beside its numbered rank. Rank, child order and reveal time are independent.",+ "A narrow vertical rank rail occupies its Frame while a large reveal stage is positioned independently in Canvas space. Preset rows are settled from the first frame. Each other row rises into the stage during its own projected Segment or Selection, then shrinks and moves into the content slot beside its numbered rank. Rank, child order and reveal time are independent.",preview: previewImage("Column.svg", "image/svg+xml"),attributes: [{ name: "id", kind: "identifier", required: true,summary: "Names this board so its Schedule, Program and Tracks can be referenced elsewhere in the Source." },{ name: "semantic", kind: "reference", required: true, accepts: [semanticTrackTypes.track],- summary: "Chooses the SemanticTrack that owns the frame domain and resolves every reveal Selection." },+ summary: "Chooses the SemanticTrack that owns the frame domain and resolves every reveal window." },{ name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],summary: "Chooses the Canvas coordinate space used by the independent reveal stage." },{ name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],summary: "Chooses the fixed Frame occupied by the vertical rank rail." },- { name: "during", kind: "reference", required: true, accepts: [narrativeTypes.selection, narrativeTypes.excerpt],- summary: "Chooses the Segment or Selection that contains the complete Column lifetime." },+ { name: "during", kind: "expression", required: true, values: ["program"], accepts: [narrativeTypes.selection, narrativeTypes.excerpt],+ summary: "Spans the complete SemanticTrack when written as program, or projects the referenced Segment or Selection into the Column lifetime." },{ name: "style", kind: "reference", required: true, accepts: [rankingTypes.columnStyle],summary: "Chooses the ColumnStyle this board is drawn in, and only that variant's." },{ name: "appear-sound", kind: "reference", required: false, accepts: [mediaTypes.synchronized],@@ -593,7 +581,7 @@ export const rankingMarkupSurfaces = [],children: [{ tag: "ColumnItem", cardinality: "many",- summary: "One explicitly ranked row; it is either preset or owns one reveal Selection.",+ summary: "One explicitly ranked row; it is either preset or owns one Segment or Selection reveal window.",attributes: [{ name: "id", kind: "identifier", required: false,summary: "Names this row within the board; an omitted id is generated from the row's position." },@@ -603,8 +591,8 @@ export const rankingMarkupSurfaces = [summary: "Sets the positive rank number and final row position independently from reveal order." },{ name: "preset", kind: "literal", required: false, values: ["true", "false"],summary: "Settles the row from the start of the outer window; defaults to false." },- { name: "during", kind: "reference", required: false, accepts: [narrativeTypes.selection],- summary: "Chooses this row's reveal Selection; required unless preset is true." },+ { name: "during", kind: "reference", required: false, accepts: [narrativeTypes.selection, narrativeTypes.excerpt],+ summary: "Chooses this row's Segment or Selection reveal window; required unless preset is true." },{ name: "icon", kind: "reference", required: false, accepts: [mediaTypes.blobArtifact],summary: "Chooses the image drawn beside the row." },{ name: "stack", kind: "literal", required: false,@@ -637,7 +625,7 @@ export const rankingMarkupSurfaces = ["Authoring either sound also connects the Style's `.sound` output, so `style` must name a ColumnStyle written in this Source.",],} },- { name: "top-three", tag: "TopThree", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.pointSpec, temporalTypes.windowSpec, rankingTypes.schedule, rankingTypes.topThreeProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],+ { name: "top-three", tag: "TopThree", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.topThreeProgram, compositionTypes.visualTrack, compositionTypes.audioTrack],vocabulary: {summary: "Fills a podium one slot at a time at the Moment owned by each Item, and publishes the board and the Tracks it renders to.",appearance:@@ -669,8 +657,7 @@ export const rankingMarkupSurfaces = [summary: "Sets the slot's copy, written literally or chosen from an existing Text." },{ name: "icon", kind: "reference", required: false, accepts: [mediaTypes.blobArtifact],summary: "Chooses the image drawn beside the slot." },- { name: "at", kind: "reference", required: true, accepts: [narrativeTypes.moment],- summary: "Chooses the Moment when this slot appears; chronological order is derived from these item-owned Moments." },+ ...temporalInstantAttributeVocabulary,{ name: "stack", kind: "literal", required: false,summary: "Overrides the Style's draw order for this slot alone." },] },@@ -713,6 +700,7 @@ export const rankingManifest: ModuleManifest = {{ name: rankingTypes.textItemShell.name },{ name: rankingTypes.itemSpecs.name },{ name: rankingTypes.triggeredCandidates.name },+ { name: rankingTypes.tierWindows.name },{ name: rankingTypes.columnWindows.name },{ name: rankingTypes.schedule.name },{ name: rankingTypes.soundStyle.name },@@ -738,13 +726,25 @@ export const rankingManifest: ModuleManifest = {], needs: [] },{ name: rankingProducers.appendTriggeredCandidate.name, inputs: [{ name: "set", type: rankingTypes.triggeredCandidates }, { name: "spec", type: rankingTypes.itemSpec },- { name: "activation", type: temporalTypes.point },+ { name: "activation", type: temporalTypes.instant },], outputs: [{ name: "set", type: rankingTypes.triggeredCandidates }], needs: [] },{ name: rankingProducers.schedule.name, inputs: [{ name: "header", type: rankingTypes.header }, { name: "items", type: rankingTypes.itemSpecs },{ name: "space", type: programSpaceTypes.programSpace },{ name: "outer", type: temporalTypes.window }, { name: "candidates", type: rankingTypes.triggeredCandidates },- { name: "terminal", type: temporalTypes.point },+ { name: "terminal", type: temporalTypes.instant },+ ], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [] },+ { name: rankingProducers.createTierWindows.name, inputs: [], outputs: [+ { name: "set", type: rankingTypes.tierWindows },+ ], needs: [] },+ { name: rankingProducers.appendTierWindow.name, inputs: [+ { name: "set", type: rankingTypes.tierWindows }, { name: "spec", type: rankingTypes.itemSpec },+ { name: "window", type: temporalTypes.window },+ ], outputs: [{ name: "set", type: rankingTypes.tierWindows }], needs: [] },+ { name: rankingProducers.tierSchedule.name, inputs: [+ { name: "header", type: rankingTypes.header }, { name: "items", type: rankingTypes.itemSpecs },+ { name: "space", type: programSpaceTypes.programSpace },+ { name: "outer", type: temporalTypes.window }, { name: "windows", type: rankingTypes.tierWindows },], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [] },{ name: rankingProducers.createColumnWindows.name, inputs: [], outputs: [{ name: "set", type: rankingTypes.columnWindows },@@ -755,6 +755,7 @@ export const rankingManifest: ModuleManifest = {], outputs: [{ name: "set", type: rankingTypes.columnWindows }], needs: [] },{ name: rankingProducers.columnSchedule.name, inputs: [{ name: "header", type: rankingTypes.header }, { name: "items", type: rankingTypes.itemSpecs },+ { name: "space", type: programSpaceTypes.programSpace },{ name: "outer", type: temporalTypes.window }, { name: "windows", type: rankingTypes.columnWindows },], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [] },...([@@ -780,7 +781,8 @@ export const rankingManifest: ModuleManifest = {...programDefinitions.flatMap(([programType, styleType, setType, programProducer, eventProducer, renderProducer]) => [{ name: programProducer.name, inputs: [{ name: "header", type: rankingTypes.header },- ...(programType === rankingTypes.columnProgram ? [{ name: "canvas", type: spatialTypes.canvas }] : []),+ ...(programType === rankingTypes.columnProgram || programType === rankingTypes.tierProgram+ ? [{ name: "canvas", type: spatialTypes.canvas }] : []),{ name: "frame", type: spatialTypes.frame }, { name: "schedule", type: rankingTypes.schedule },{ name: "style", type: styleType }, { name: "set", type: setType },], outputs: [{ name: "program", type: programType }], needs: [] },diff --git a/packages/ranking/src/render.ts b/packages/ranking/src/render.tsindex a2eff832..fbfd4177 100644--- a/packages/ranking/src/render.ts+++ b/packages/ranking/src/render.ts@@ -28,8 +28,16 @@ import {assertTierBoardProgram,assertTopThreeProgram,fitColumnRevealMotion,- fitRankingStageMotion,+ fitRankingEntranceMotion,} from "./schedule.js";+import {+ directTierItemPose,+ fromHighTierItemPose,+ tierBoardGeometry,+ tierCell,+ tierStageGeometry,+} from "./tier.js";+import type { TierCell, TierItemPose } from "./tier.js";import type {ColumnItem,ColumnProgram,@@ -212,35 +220,39 @@ function finalTransform(): string {return "translate(0px,0px) scale(1)";}-function stageTransform(finalX: number, finalY: number, stageX: number, stageY: number, scale: number): string {- return `translate(${px(stageX - finalX)},${px(stageY - finalY)}) scale(${scale})`;+function directItemAnimation(+ duration: number,+ appearFrames: number,+ easing: "linear" | "ease-in" | "ease-out" | "ease-in-out" = "ease-out",+): VisualAnimation {+ return animation(duration, [+ { atFrame: 0, style: transformStyle("translate(0px,8px) scale(0.82)", 0), easing },+ { atFrame: appearFrames, style: transformStyle(finalTransform(), 1) },+ ]);}-function settledItemAnimation(input: {- readonly duration: number;- readonly appearFrames: number;- readonly moveStart: number;- readonly moveEnd: number;- readonly stageTransform: string;- readonly easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";-}): VisualAnimation {- return animation(input.duration, [- { atFrame: 0, style: transformStyle(`${input.stageTransform} scale(0.82)`, 0), easing: "ease-out" },- { atFrame: input.appearFrames, style: transformStyle(input.stageTransform, 1) },- { atFrame: input.moveStart, style: transformStyle(input.stageTransform, 1), easing: input.easing },- { atFrame: input.moveEnd, style: transformStyle(finalTransform(), 1) },- ]);+function tierItemStyle(pose: TierItemPose, cell: TierCell): VisualStyleDeclaration[] {+ return [+ { name: "filter", value: `blur(${px(pose.blurPx)}) drop-shadow(0 ${px(pose.shadowY)} ${px(pose.shadowBlur)} rgba(0,0,0,${Math.round(pose.shadowOpacity * 1_000_000) / 1_000_000}))` },+ { name: "opacity", value: Math.round(pose.opacity * 1_000_000) / 1_000_000 },+ { name: "transform", value: `translate(${px(pose.x - cell.x)},${px(pose.y - cell.y)}) scale(${Math.round(pose.scale * 1_000_000) / 1_000_000}) rotate(${Math.round(pose.rotateDeg * 1_000_000) / 1_000_000}deg)` },+ ];}-function directItemAnimation(duration: number, appearFrames: number): VisualAnimation {- return animation(duration, [- { atFrame: 0, style: transformStyle("translate(0px,8px) scale(0.82)", 0), easing: "ease-out" },- { atFrame: appearFrames, style: transformStyle(finalTransform(), 1) },- ]);+function tierItemAnimation(+ duration: number,+ cell: TierCell,+ poseAt: (frame: number) => TierItemPose,+): VisualAnimation {+ return animation(duration, Array.from({ length: duration + 1 }, (_, frame) => ({+ atFrame: frame,+ easing: "linear" as const,+ style: tierItemStyle(poseAt(frame), cell),+ })));}function sealTrack(space: ProgramSpace, id: string, presents: readonly VisualPresent[]): VisualTrack {- const value = sealVisualTrack({ visualIr: "hypit.visual-ir@1", id, presents });+ const value = sealVisualTrack({ programSpaceId: space.id, visualIr: "hypit.visual-ir@1", id, presents });assertVisualTrackIdentity(value, space);return value;}@@ -248,87 +260,105 @@ function sealTrack(space: ProgramSpace, id: string, presents: readonly VisualPreexport function renderTierBoard(space: ProgramSpace, program: TierBoardProgram): VisualTrack {assertProgramSpaceIdentity(space);assertTierBoardProgram(program);- const { frame, style, schedule } = program;+ const { canvas, frame, style, schedule } = program;+ const geometry = tierBoardGeometry(frame.widthPx, frame.heightPx, style);+ const stage = tierStageGeometry(canvas.widthPx, canvas.heightPx, style);const presents: VisualPresent[] = [];const boardElements: VisualElement[] = [absoluteBox({- id: "tier-board", order: 0, x: frame.xPx, y: frame.yPx, width: frame.widthPx, height: frame.heightPx,- style: boardStyle(style.board),+ id: "tier-board-root", order: 0,+ x: frame.xPx, y: frame.yPx, width: frame.widthPx, height: frame.heightPx,})];+ const labelTypography: RankingTextStyle = {+ fonts: structuredClone(style.fonts),+ sizePx: geometry.rowHeight * style.labelSizeRatio,+ weight: style.fonts[0]!.weight,+ color: style.labelTextColor,+ lineHeight: style.labelLineHeight,+ };for (const [index, row] of style.rows.entries()) {- const y = style.paddingPx + index * (style.rowHeightPx + style.rowGapPx);+ const root = `tier-row-${row.id}`;+ const y = index * geometry.rowHeight;+ const last = index === style.rows.length - 1;boardElements.push(absoluteBox({- id: `tier-row-${row.id}`, parent: "tier-board", order: boardElements.length,- x: style.paddingPx, y, width: frame.widthPx - style.paddingPx * 2, height: style.rowHeightPx,- style: [{ name: "background", value: row.color }, { name: "border-radius", value: px(Math.min(12, style.iconRadiusPx)) }],+ id: root, parent: "tier-board-root", order: boardElements.length,+ x: 0, y, width: frame.widthPx, height: geometry.rowHeight,+ style: [+ { name: "border-top", value: `${px(style.borderWidthPx)} solid ${style.borderColor}` },+ { name: "border-left", value: `${px(style.borderWidthPx)} solid ${style.borderColor}` },+ { name: "border-right", value: `${px(style.borderWidthPx)} solid ${style.borderColor}` },+ ...(last ? [{ name: "border-bottom", value: `${px(style.borderWidthPx)} solid ${style.borderColor}` } satisfies VisualStyleDeclaration] : []),+ { name: "box-sizing", value: "border-box" },+ ],+ }));+ boardElements.push(absoluteBox({+ id: `${root}-content`, parent: root, order: boardElements.length,+ x: geometry.labelWidth, y: 0, width: frame.widthPx - geometry.labelWidth, height: geometry.rowHeight,+ style: [{ name: "background", value: style.boardColor }],}));boardElements.push(simpleText({- id: `tier-label-${row.id}`, parent: `tier-row-${row.id}`, order: boardElements.length,- text: row.label, typography: style.text, x: 0, y: 0, width: style.labelWidthPx, height: style.rowHeightPx,+ id: `${root}-label`, parent: root, order: boardElements.length,+ text: row.label, typography: labelTypography, x: 0, y: 0,+ width: geometry.labelWidth, height: geometry.rowHeight,+ style: [+ { name: "background", value: row.color },+ { name: "border-right", value: `${px(style.borderWidthPx)} solid ${style.borderColor}` },+ { name: "box-sizing", value: "border-box" },+ ],}));}presents.push(present({id: `${program.id}:board`, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:board`, elements: boardElements,}));- if (program.items.some((item) => item.entry === "stage")) {- const size = style.stageSizePx;- presents.push(present({- id: `${program.id}:stage`, start: schedule.entries[0]!.triggerFrame, end: schedule.terminalFrame,- stacking: style.stageStackingOrder, tieBreak: `${program.id}:0001:stage`, elements: [absoluteBox({- id: "tier-stage", order: 0,- x: frame.xPx + frame.widthPx * style.stagePoint.x - size / 2,- y: frame.yPx + frame.heightPx * style.stagePoint.y - size / 2,- width: size, height: size,- style: [- { name: "border", value: `${px(2)} dashed ${style.text.color}` },- { name: "border-radius", value: px(style.iconRadiusPx) },- { name: "opacity", value: 0.45 },- ],- })],- }));- }+ const entries = new Map(schedule.entries.map((entry) => [entry.itemId, entry]));const rowCounts = new Map<string, number>();for (const [index, item] of program.items.entries()) {- const entry = schedule.entries[index]!;+ const entry = entries.get(item.id)!;const rowIndex = style.rows.findIndex((row) => row.id === item.tier);- const cell = rowCounts.get(item.tier) ?? 0;- rowCounts.set(item.tier, cell + 1);- const x = frame.xPx + style.paddingPx + style.labelWidthPx + cell * (style.iconSizePx + style.cellGapPx);- const y = frame.yPx + style.paddingPx + rowIndex * (style.rowHeightPx + style.rowGapPx)- + (style.rowHeightPx - style.iconSizePx) / 2;- assert(x + style.iconSizePx <= frame.xPx + frame.widthPx - style.paddingPx,+ const column = rowCounts.get(item.tier) ?? 0;+ rowCounts.set(item.tier, column + 1);+ const cell = tierCell(geometry, rowIndex, column);+ assert(cell.x + cell.size <= frame.widthPx,`TierBoard row ${item.tier} cannot fit Item ${item.id}.`);- const duration = entry.stage.endFrameExclusive - entry.stage.startFrame;- const fitted = fitRankingStageMotion(duration, style.motion.appearFrames, style.motion.moveFrames, item.entry === "stage");- const rootAnimation = item.entry === "direct"- ? directItemAnimation(duration, fitted.appearFrames)- : settledItemAnimation({- duration,- appearFrames: fitted.appearFrames,- moveStart: entry.stage.endFrameExclusive - fitted.moveFrames - entry.triggerFrame,- moveEnd: entry.stage.endFrameExclusive - entry.triggerFrame,- stageTransform: stageTransform(- x, y,- frame.xPx + frame.widthPx * style.stagePoint.x - style.iconSizePx / 2,- frame.yPx + frame.heightPx * style.stagePoint.y - style.iconSizePx / 2,- style.stageSizePx / style.iconSizePx,- ),- easing: style.motion.easing,- });+ const radius = Math.round(geometry.rowHeight * style.iconRadiusRatio);+ const absoluteCell: TierCell = {+ x: frame.xPx + cell.x,+ y: frame.yPx + cell.y,+ size: cell.size,+ };const root = `tier-item-${item.id}`;const itemElements = (animationValue?: VisualAnimation): VisualElement[] => [- absoluteBox({ id: root, order: 0, x, y, width: style.iconSizePx, height: style.iconSizePx,- ...(animationValue === undefined ? {} : { animation: animationValue }) }),- iconElement({ id: "icon", parent: root, order: 1, artifact: item.icon, x: 0, y: 0, size: style.iconSizePx, radius: style.iconRadiusPx, fit: style.iconFit }),+ absoluteBox({+ id: root, order: 0,+ x: absoluteCell.x, y: absoluteCell.y, width: cell.size, height: cell.size,+ style: [+ { name: "border-radius", value: px(radius) },+ { name: "filter", value: "blur(0px) drop-shadow(0 7px 10px rgba(0,0,0,0.2))" },+ ...(style.iconFit === "contain" ? [{ name: "background", value: "rgba(255,255,255,0.96)" } satisfies VisualStyleDeclaration] : []),+ { name: "overflow", value: "hidden" },+ { name: "transform-origin", value: "center center" },+ ],+ ...(animationValue === undefined ? {} : { animation: animationValue }),+ }),+ iconElement({ id: "icon", parent: root, order: 1, artifact: item.icon, x: 0, y: 0,+ size: cell.size, radius, fit: style.iconFit }),];- presents.push(present({- id: `${program.id}:item:${item.id}:stage`,- start: entry.stage.startFrame,- end: entry.stage.endFrameExclusive,- stacking: item.stackingOrder ?? style.itemStackingOrder,- tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:stage`,- elements: itemElements(rootAnimation),- }));+ if (entry.mode === "reveal") {+ assert(!item.preset, `TierBoard reveal ${item.id} cannot be preset.`);+ const duration = entry.window.endFrameExclusive - entry.window.startFrame;+ const rootAnimation = tierItemAnimation(duration, absoluteCell, item.entry === "direct"+ ? (localFrame) => directTierItemPose(localFrame, absoluteCell, style.motion.appearFrames)+ : (localFrame) => fromHighTierItemPose(+ localFrame, duration, stage, absoluteCell, style.motion.appearFrames, style.motion.moveFrames));+ presents.push(present({+ id: `${program.id}:item:${item.id}:reveal`,+ start: entry.window.startFrame,+ end: entry.window.endFrameExclusive,+ stacking: item.stackingOrder ?? (item.entry === "drop" ? style.stageStackingOrder : style.itemStackingOrder),+ tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:reveal`,+ elements: itemElements(rootAnimation),+ }));+ }if (entry.settled.endFrameExclusive > entry.settled.startFrame) presents.push(present({id: `${program.id}:item:${item.id}:settled`,start: entry.settled.startFrame,@@ -585,7 +615,7 @@ export function renderTopThree(space: ProgramSpace, program: TopThreeProgram): Vid: root, order: 0, x, y, width: style.iconSizePx,height: style.iconSizePx + style.labelGapPx + style.text.sizePx * style.text.lineHeight,...(active ? { animation: directItemAnimation(duration,- fitRankingStageMotion(duration, style.motion.appearFrames, style.motion.moveFrames, false).appearFrames) } : {}),+ fitRankingEntranceMotion(duration, style.motion.appearFrames, style.motion.moveFrames, false).appearFrames) } : {}),})];if (active) elements.push(absoluteBox({ id: accent, parent: root, order: 1, x: 0, y: 0, width: style.iconSizePx, height: style.iconSizePx,style: [@@ -656,7 +686,7 @@ export function renderRankingAudio(if (sounds[kind] !== undefined) assert(clips.some((clip) => clip.id.endsWith(`:${kind}`)),`Ranking ${kind} sound has no matching visual event.`);}- const track = sealAudioTrack({ id: `${plan.id}.audio`, clips });+ const track = sealAudioTrack({ programSpaceId: space.id, id: `${plan.id}.audio`, clips });assertAudioTrackIdentity(track, space);return track;}diff --git a/packages/ranking/src/schedule.ts b/packages/ranking/src/schedule.tsindex c99e74b3..c4dc5d2d 100644--- a/packages/ranking/src/schedule.ts+++ b/packages/ranking/src/schedule.ts@@ -13,8 +13,12 @@ import { verifyText } from "@hypit/text";import type { Text } from "@hypit/text";import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";import type { CanvasSpace } from "@hypit/spatial";-import { resolveTriggeredSchedule } from "@hypit/temporal";-import type { TemporalPoint, TemporalWindow } from "@hypit/temporal";+import {+ assertTemporalInstantFor,+ assertTemporalWindowFor,+ resolveTriggeredSchedule,+} from "@hypit/temporal";+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";import type {ColumnItem,@@ -37,6 +41,9 @@ import type {RankingSoundStyle,RankingTextStyle,RankingVariant,+ RankingWindowSet,+ TierBoardSchedule,+ TierBoardWindowSet,TriggeredRankingCandidateSet,TriggeredRankingSchedule,TierBoardItem,@@ -160,8 +167,30 @@ function assertCommonStyle(input: {}export function assertTierBoardStyle(value: TierBoardStyle): void {- assertCommonStyle(value, "TierBoardStyle");- assertRankingBoardPaint(value.board, "TierBoardStyle.board");+ assert(value.fonts.length > 0, "TierBoardStyle.fonts is empty.");+ value.fonts.forEach((fontValue, index) => assertFontArtifactRef(fontValue, `TierBoardStyle.fonts.${index}`));+ color(value.labelTextColor, "TierBoardStyle.labelTextColor");+ positive(value.labelSizeRatio, "TierBoardStyle.labelSizeRatio");+ positive(value.labelLineHeight, "TierBoardStyle.labelLineHeight");+ color(value.boardColor, "TierBoardStyle.boardColor");+ color(value.borderColor, "TierBoardStyle.borderColor");+ nonNegative(value.borderWidthPx, "TierBoardStyle.borderWidthPx");+ if (value.labelWidthRatio !== undefined) {+ assert(Number.isFinite(value.labelWidthRatio) && value.labelWidthRatio >= 0.08 && value.labelWidthRatio <= 0.3,+ "TierBoardStyle.labelWidthRatio must be between 0.08 and 0.3.");+ }+ for (const [name, coordinate] of Object.entries(value.stagePoint)) {+ assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1,+ `TierBoardStyle.stagePoint.${name} must be between 0 and 1.`);+ }+ positive(value.stageSizePx, "TierBoardStyle.stageSizePx");+ nonNegative(value.iconRadiusRatio, "TierBoardStyle.iconRadiusRatio");+ assert(value.iconFit === "contain" || value.iconFit === "cover", "TierBoardStyle.iconFit is invalid.");+ integer(value.motion.appearFrames, "TierBoardStyle.motion.appearFrames", 1);+ integer(value.motion.moveFrames, "TierBoardStyle.motion.moveFrames", 1);+ stacking(value.boardStackingOrder, "TierBoardStyle.boardStackingOrder");+ stacking(value.stageStackingOrder, "TierBoardStyle.stageStackingOrder");+ stacking(value.itemStackingOrder, "TierBoardStyle.itemStackingOrder");assert(value.rows.length > 0, "TierBoardStyle.rows is empty.");const rows = new Set<string>();for (const [index, row] of value.rows.entries()) {@@ -171,16 +200,6 @@ export function assertTierBoardStyle(value: TierBoardStyle): void {assert(row.label.trim().length > 0, `TierBoardStyle.rows.${index}.label is empty.`);color(row.color, `TierBoardStyle.rows.${index}.color`);}- for (const [name, numberValue] of Object.entries({- labelWidthPx: value.labelWidthPx, paddingPx: value.paddingPx, rowHeightPx: value.rowHeightPx,- rowGapPx: value.rowGapPx, cellGapPx: value.cellGapPx, stageSizePx: value.stageSizePx,- })) nonNegative(numberValue, `TierBoardStyle.${name}`);- assert(value.labelWidthPx > 0 && value.rowHeightPx > 0 && value.stageSizePx > 0,- "TierBoardStyle positive geometry is invalid.");- for (const [name, coordinate] of Object.entries(value.stagePoint)) {- assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1, `TierBoardStyle.stagePoint.${name} is invalid.`);- }- stacking(value.stageStackingOrder, "TierBoardStyle.stageStackingOrder");}export function assertColumnStyle(value: ColumnStyle): void {@@ -214,7 +233,9 @@ export function assertRankingItemSpec(value: RankingItemSpec): void {identity(value.id, "RankingItemSpec.id");if (value.variant === "tier-board") {identity(value.tier, `TierBoardItemSpec.${value.id}.tier`);- assert(value.entry === "direct" || value.entry === "stage", `TierBoardItemSpec.${value.id}.entry is invalid.`);+ assert(typeof value.preset === "boolean", `TierBoardItemSpec.${value.id}.preset is invalid.`);+ if (value.preset) assert(!("entry" in value), `Preset TierBoardItemSpec.${value.id} cannot have an entry.`);+ else assert(value.entry === "direct" || value.entry === "drop", `TierBoardItemSpec.${value.id}.entry is invalid.`);} else if (value.variant === "column") {assert(value.label.trim().length > 0, `ColumnItemSpec.${value.id}.label is empty.`);integer(value.rank, `ColumnItemSpec.${value.id}.rank`, 1);@@ -290,17 +311,18 @@ export function assertTriggeredRankingCandidateSet(value: TriggeredRankingCandidassert(!itemIds.has(entry.itemId), `TriggeredRankingCandidateSet repeats ${entry.itemId}.`);itemIds.add(entry.itemId);frame(entry.activation.frame, `TriggeredRankingCandidateSet.entries.${index}.activation.frame`);+ assertTemporalInstantFor(entry.activation, { subjectId: entry.itemId });}}export function appendTriggeredRankingCandidate(set: TriggeredRankingCandidateSet,spec: RankingItemSpec,- activation: TemporalPoint,+ activation: TemporalInstant,): TriggeredRankingCandidateSet {assertTriggeredRankingCandidateSet(set);assertRankingItemSpec(spec);- assert(spec.variant !== "column", `Column Item ${spec.id} consumes a Selection window, not a Moment.`);+ assert(spec.variant === "top-three", `Ranking Item ${spec.id} consumes a Selection window, not a Moment.`);assert(!set.entries.some((entry) => entry.itemId === spec.id), `Ranking Item ${spec.id} already has a Moment.`);const result: TriggeredRankingCandidateSet = {entries: [...set.entries, { itemId: spec.id, activation: structuredClone(activation) }],@@ -315,14 +337,19 @@ export function buildTriggeredRankingSchedule(input: {readonly space: ProgramSpace;readonly outer: TemporalWindow;readonly candidates: TriggeredRankingCandidateSet;- readonly terminal: TemporalPoint;+ readonly terminal: TemporalInstant;}): TriggeredRankingSchedule {assertRankingHeader(input.header);assertRankingItemSpecSet(input.items);assert(input.items.variant === input.header.variant, "Ranking schedule variant disagrees with its item set.");- assert(input.header.variant !== "column", "Column uses item-owned Selection windows, not the triggered Ranking schedule.");+ assert(input.header.variant === "top-three", "Only TopThree uses the triggered Ranking schedule.");assert(input.items.items.length > 0, "Ranking requires at least one Item.");assertTriggeredRankingCandidateSet(input.candidates);+ assertTemporalWindowFor(input.outer, { subjectId: input.header.id, space: input.space });+ assertTemporalInstantFor(input.terminal, { subjectId: input.header.id, space: input.space });+ for (const candidate of input.candidates.entries) {+ assertTemporalInstantFor(candidate.activation, { subjectId: candidate.itemId, space: input.space });+ }const expected = new Set(input.items.items.map((item) => item.id));const received = new Set(input.candidates.entries.map((entry) => entry.itemId));assert(expected.size === received.size && [...expected].every((id) => received.has(id)),@@ -356,80 +383,124 @@ export function buildTriggeredRankingSchedule(input: {return canonicalize(result) as unknown as TriggeredRankingSchedule;}-export function createColumnWindowSet(): ColumnWindowSet {+function createRankingWindowSet(): RankingWindowSet {return { entries: [] };}-export function assertColumnWindowSet(value: ColumnWindowSet): void {- assert(Array.isArray(value.entries), "ColumnWindowSet.entries is invalid.");+function assertRankingWindowSet(value: RankingWindowSet, label: string): void {+ assert(Array.isArray(value.entries), `${label}.entries is invalid.`);const ids = new Set<string>();for (const [index, entry] of value.entries.entries()) {- identity(entry.itemId, `ColumnWindowSet.entries.${index}.itemId`);- assert(!ids.has(entry.itemId), `ColumnWindowSet repeats ${entry.itemId}.`);+ identity(entry.itemId, `${label}.entries.${index}.itemId`);+ assert(!ids.has(entry.itemId), `${label} repeats ${entry.itemId}.`);ids.add(entry.itemId);- frame(entry.window.span.startFrame, `ColumnWindowSet.entries.${index}.window.span.startFrame`);- frame(entry.window.span.endFrameExclusive, `ColumnWindowSet.entries.${index}.window.span.endFrameExclusive`);+ frame(entry.window.span.startFrame, `${label}.entries.${index}.window.span.startFrame`);+ frame(entry.window.span.endFrameExclusive, `${label}.entries.${index}.window.span.endFrameExclusive`);assert(entry.window.span.endFrameExclusive > entry.window.span.startFrame,- `ColumnWindowSet.entries.${index}.window is empty.`);+ `${label}.entries.${index}.window is empty.`);+ assertTemporalWindowFor(entry.window, { subjectId: entry.itemId });}}-export function appendColumnWindow(- set: ColumnWindowSet,- spec: ColumnItemSpec,+export const createTierBoardWindowSet = (): TierBoardWindowSet => createRankingWindowSet();+export const createColumnWindowSet = (): ColumnWindowSet => createRankingWindowSet();++export const assertTierBoardWindowSet = (value: TierBoardWindowSet): void => assertRankingWindowSet(value, "TierBoardWindowSet");+export const assertColumnWindowSet = (value: ColumnWindowSet): void => assertRankingWindowSet(value, "ColumnWindowSet");++function appendRankingWindow<T extends TierBoardItemSpec | ColumnItemSpec>(+ set: RankingWindowSet,+ spec: T,window: TemporalWindow,-): ColumnWindowSet {- assertColumnWindowSet(set);+ variant: T["variant"],+ label: string,+): RankingWindowSet {+ assertRankingWindowSet(set, `${label}WindowSet`);assertRankingItemSpec(spec);- assert(!spec.preset, `Preset Column Item ${spec.id} cannot consume a Selection window.`);- assert(!set.entries.some((entry) => entry.itemId === spec.id), `Column Item ${spec.id} already has a Selection window.`);- const result: ColumnWindowSet = {+ assert(spec.variant === variant, `${label} window requires a ${label} Item.`);+ assert(!spec.preset, `Preset ${label} Item ${spec.id} cannot consume a Selection window.`);+ assert(!set.entries.some((entry) => entry.itemId === spec.id), `${label} Item ${spec.id} already has a Selection window.`);+ assertTemporalWindowFor(window, { subjectId: spec.id });+ const result: RankingWindowSet = {entries: [...set.entries, { itemId: spec.id, window: structuredClone(window) }].sort((left, right) => left.itemId.localeCompare(right.itemId)),};- assertColumnWindowSet(result);- return canonicalize(result) as unknown as ColumnWindowSet;+ assertRankingWindowSet(result, `${label}WindowSet`);+ return canonicalize(result) as unknown as RankingWindowSet;}-export function buildColumnSchedule(input: {+export function appendTierBoardWindow(+ set: TierBoardWindowSet,+ spec: TierBoardItemSpec,+ window: TemporalWindow,+): TierBoardWindowSet {+ return appendRankingWindow(set, spec, window, "tier-board", "TierBoard");+}++export function appendColumnWindow(+ set: ColumnWindowSet,+ spec: ColumnItemSpec,+ window: TemporalWindow,+): ColumnWindowSet {+ return appendRankingWindow(set, spec, window, "column", "Column");+}++function buildWindowedRankingSchedule(input: {readonly header: RankingHeader;readonly items: RankingItemSpecSet;+ readonly space: ProgramSpace;readonly outer: TemporalWindow;- readonly windows: ColumnWindowSet;-}): ColumnSchedule {+ readonly windows: RankingWindowSet;+ readonly variant: "tier-board" | "column";+}): TierBoardSchedule | ColumnSchedule {assertRankingHeader(input.header);- assert(input.header.variant === "column", "Column Schedule requires a Column header.");+ const label = input.variant === "tier-board" ? "TierBoard" : "Column";+ assert(input.header.variant === input.variant, `${label} Schedule requires a ${label} header.`);assertRankingItemSpecSet(input.items);- assert(input.items.variant === "column", "Column Schedule requires Column Items.");- assert(input.items.items.length > 0, "Column requires at least one Item.");- assertColumnWindowSet(input.windows);- frame(input.outer.span.startFrame, "Column outer window start");- frame(input.outer.span.endFrameExclusive, "Column outer window end");- assert(input.outer.span.endFrameExclusive > input.outer.span.startFrame, "Column outer window is empty.");- const items = [...input.items.items as readonly ColumnItemSpec[]]- .sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));- const expected = new Set(items.filter((item) => !item.preset).map((item) => item.id));+ assert(input.items.variant === input.variant, `${label} Schedule requires ${label} Items.`);+ assert(input.items.items.length > 0, `${label} requires at least one Item.`);+ assertRankingWindowSet(input.windows, `${label}WindowSet`);+ assertTemporalWindowFor(input.outer, { subjectId: input.header.id, space: input.space });+ frame(input.outer.span.startFrame, `${label} outer window start`);+ frame(input.outer.span.endFrameExclusive, `${label} outer window end`);+ assert(input.outer.span.endFrameExclusive > input.outer.span.startFrame, `${label} outer window is empty.`);+ const authoredItems = [...input.items.items] as readonly (TierBoardItemSpec | ColumnItemSpec)[];+ const expected = new Set(authoredItems.filter((item) => !item.preset).map((item) => item.id));const received = new Set(input.windows.entries.map((entry) => entry.itemId));assert(expected.size === received.size && [...expected].every((id) => received.has(id)),- "Column non-preset Items and Selection windows differ.");+ `${label} non-preset Items and Selection windows differ.`);const orderedWindows = [...input.windows.entries].sort((left, right) =>left.window.span.startFrame - right.window.span.startFrame|| left.window.span.endFrameExclusive - right.window.span.endFrameExclusive|| left.itemId.localeCompare(right.itemId));for (const entry of orderedWindows) {+ assertTemporalWindowFor(entry.window, { subjectId: entry.itemId, space: input.space });assert(entry.window.span.startFrame >= input.outer.span.startFrame&& entry.window.span.endFrameExclusive <= input.outer.span.endFrameExclusive,- `Column Item ${entry.itemId} window is outside the outer window.`);+ `${label} Item ${entry.itemId} window is outside the outer window.`);+ if (input.variant === "tier-board") assert(+ entry.window.span.endFrameExclusive - entry.window.span.startFrame >= 2,+ `TierBoard Item ${entry.itemId} window must span at least two frames so its entrance can be animated.`,+ );}for (let index = 1; index < orderedWindows.length; index += 1) {const previous = orderedWindows[index - 1]!;const current = orderedWindows[index]!;assert(current.window.span.startFrame >= previous.window.span.endFrameExclusive,- `Column Item windows ${previous.itemId} and ${current.itemId} overlap.`);+ `${label} Item windows ${previous.itemId} and ${current.itemId} overlap.`);}- const result: ColumnSchedule = {+ const windowOrder = new Map(orderedWindows.map((entry, index) => [entry.itemId, index]));+ const authorOrder = new Map(authoredItems.map((item, index) => [item.id, index]));+ const items = input.variant === "column"+ ? [...authoredItems].sort((left, right) => (left as ColumnItemSpec).rank - (right as ColumnItemSpec).rank || left.id.localeCompare(right.id))+ : [...authoredItems].sort((left, right) => {+ if (left.preset !== right.preset) return left.preset ? -1 : 1;+ if (left.preset) return authorOrder.get(left.id)! - authorOrder.get(right.id)!;+ return windowOrder.get(left.id)! - windowOrder.get(right.id)!;+ });+ const result: TierBoardSchedule | ColumnSchedule = {id: input.header.id,- variant: "column",+ variant: input.variant,outer: { ...input.outer.span },entries: items.map((item) => {if (item.preset) return {@@ -447,13 +518,32 @@ export function buildColumnSchedule(input: {}),};assertRankingSchedule(result);- return canonicalize(result) as unknown as ColumnSchedule;+ return canonicalize(result) as unknown as TierBoardSchedule | ColumnSchedule;+}++export function buildTierBoardSchedule(input: {+ readonly header: RankingHeader;+ readonly items: RankingItemSpecSet;+ readonly space: ProgramSpace;+ readonly outer: TemporalWindow;+ readonly windows: TierBoardWindowSet;+}): TierBoardSchedule {+ return buildWindowedRankingSchedule({ ...input, variant: "tier-board" }) as TierBoardSchedule;+}++export function buildColumnSchedule(input: {+ readonly header: RankingHeader;+ readonly items: RankingItemSpecSet;+ readonly space: ProgramSpace;+ readonly outer: TemporalWindow;+ readonly windows: ColumnWindowSet;+}): ColumnSchedule {+ return buildWindowedRankingSchedule({ ...input, variant: "column" }) as ColumnSchedule;}function assertTriggeredRankingSchedule(value: TriggeredRankingSchedule): void {identity(value.id, "RankingSchedule.id");- assert(["tier-board", "top-three"].includes(value.variant),- "Triggered RankingSchedule.variant is invalid.");+ assert(value.variant === "top-three", "Triggered RankingSchedule.variant is invalid.");frame(value.outer.startFrame, "RankingSchedule.outer.startFrame");frame(value.outer.endFrameExclusive, "RankingSchedule.outer.endFrameExclusive");assert(value.outer.endFrameExclusive > value.outer.startFrame, "RankingSchedule.outer is empty.");@@ -484,46 +574,61 @@ function assertTriggeredRankingSchedule(value: TriggeredRankingSchedule): void {"RankingSchedule final stage does not end at terminal.");}-function assertColumnSchedule(value: ColumnSchedule): void {- identity(value.id, "ColumnSchedule.id");- frame(value.outer.startFrame, "ColumnSchedule.outer.startFrame");- frame(value.outer.endFrameExclusive, "ColumnSchedule.outer.endFrameExclusive");- assert(value.outer.endFrameExclusive > value.outer.startFrame, "ColumnSchedule.outer is empty.");- assert(value.entries.length > 0, "ColumnSchedule.entries is empty.");+function assertWindowedRankingSchedule(value: TierBoardSchedule | ColumnSchedule): void {+ const label = value.variant === "tier-board" ? "TierBoardSchedule" : "ColumnSchedule";+ identity(value.id, `${label}.id`);+ frame(value.outer.startFrame, `${label}.outer.startFrame`);+ frame(value.outer.endFrameExclusive, `${label}.outer.endFrameExclusive`);+ assert(value.outer.endFrameExclusive > value.outer.startFrame, `${label}.outer is empty.`);+ assert(value.entries.length > 0, `${label}.entries is empty.`);const ids = new Set<string>();const windows: Array<{ readonly itemId: string; readonly startFrame: number; readonly endFrameExclusive: number }> = [];+ let tierRevealStarted = false;for (const [index, entry] of value.entries.entries()) {- identity(entry.itemId, `ColumnSchedule.entries.${index}.itemId`);- assert(!ids.has(entry.itemId), `ColumnSchedule repeats ${entry.itemId}.`);+ identity(entry.itemId, `${label}.entries.${index}.itemId`);+ assert(!ids.has(entry.itemId), `${label} repeats ${entry.itemId}.`);ids.add(entry.itemId);if (entry.mode === "preset") {+ assert(value.variant !== "tier-board" || !tierRevealStarted,+ `TierBoardSchedule preset ${entry.itemId} appears after a reveal Item.`);assert(entry.settled.startFrame === value.outer.startFrame&& entry.settled.endFrameExclusive === value.outer.endFrameExclusive,- `ColumnSchedule preset ${entry.itemId} does not occupy the outer window.`);+ `${label} preset ${entry.itemId} does not occupy the outer window.`);continue;}- frame(entry.window.startFrame, `ColumnSchedule.entries.${index}.window.startFrame`);- frame(entry.window.endFrameExclusive, `ColumnSchedule.entries.${index}.window.endFrameExclusive`);+ tierRevealStarted = true;+ frame(entry.window.startFrame, `${label}.entries.${index}.window.startFrame`);+ frame(entry.window.endFrameExclusive, `${label}.entries.${index}.window.endFrameExclusive`);assert(entry.window.startFrame >= value.outer.startFrame&& entry.window.endFrameExclusive <= value.outer.endFrameExclusive&& entry.window.endFrameExclusive > entry.window.startFrame,- `ColumnSchedule.entries.${index}.window is outside the outer window.`);+ `${label}.entries.${index}.window is outside the outer window.`);assert(entry.settled.startFrame === entry.window.endFrameExclusive&& entry.settled.endFrameExclusive === value.outer.endFrameExclusive,- `ColumnSchedule.entries.${index}.settled is inconsistent.`);+ `${label}.entries.${index}.settled is inconsistent.`);windows.push({ itemId: entry.itemId, ...entry.window });}windows.sort((left, right) => left.startFrame - right.startFrame|| left.endFrameExclusive - right.endFrameExclusive || left.itemId.localeCompare(right.itemId));for (let index = 1; index < windows.length; index += 1) {assert(windows[index]!.startFrame >= windows[index - 1]!.endFrameExclusive,- `ColumnSchedule windows ${windows[index - 1]!.itemId} and ${windows[index]!.itemId} overlap.`);+ `${label} windows ${windows[index - 1]!.itemId} and ${windows[index]!.itemId} overlap.`);+ }+ if (value.variant === "tier-board") {+ const revealOrder = value.entries.filter((entry) => entry.mode === "reveal");+ for (let index = 1; index < revealOrder.length; index += 1) {+ const previous = revealOrder[index - 1]!;+ const current = revealOrder[index]!;+ assert(previous.mode === "reveal" && current.mode === "reveal"+ && current.window.startFrame >= previous.window.endFrameExclusive,+ `TierBoardSchedule reveal order is not chronological at ${current.itemId}.`);+ }}}export function assertRankingSchedule(value: RankingSchedule, space?: ProgramSpace): void {- if (value.variant === "column") assertColumnSchedule(value);- else assertTriggeredRankingSchedule(value);+ if (value.variant === "top-three") assertTriggeredRankingSchedule(value);+ else assertWindowedRankingSchedule(value);if (space !== undefined) {assertProgramSpaceIdentity(space);assert(value.outer.endFrameExclusive <= programSpaceFrameCount(space), "RankingSchedule exceeds ProgramSpace.");@@ -587,25 +692,41 @@ function orderForSchedule<T extends { readonly id: string }>(});}-function columnIdsEqual(schedule: ColumnSchedule, items: readonly { readonly id: string }[]): void {- assert(schedule.entries.length === items.length, "Column Program item count differs from its Schedule.");+function windowedIdsEqual(schedule: TierBoardSchedule | ColumnSchedule, items: readonly { readonly id: string }[]): void {+ assert(schedule.entries.length === items.length, "Windowed Ranking Program item count differs from its Schedule.");const scheduled = new Set(schedule.entries.map((entry) => entry.itemId));assert(scheduled.size === items.length && items.every((item) => scheduled.has(item.id)),- "Column Program Items differ from its Schedule.");+ "Windowed Ranking Program Items differ from its Schedule.");}-export function fitRankingStageMotion(+export function fitRankingEntranceMotion(durationFrames: number,preferredAppearFrames: number,preferredMoveFrames: number,needsMove: boolean,): { readonly appearFrames: number; readonly moveFrames: number } {- assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "Ranking stage duration is invalid.");+ assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "Ranking entrance duration is invalid.");if (!needsMove) return { appearFrames: Math.min(preferredAppearFrames, durationFrames), moveFrames: 0 };- const moveFrames = Math.min(preferredMoveFrames, durationFrames);+ const moveFrames = Math.min(preferredMoveFrames, Math.max(1, durationFrames - 1));return { appearFrames: Math.min(preferredAppearFrames, durationFrames - moveFrames), moveFrames };}+export function resolveTierBoardMotion(+ durationFrames: number,+ appearFrames: number,+ moveFrames: number,+): { readonly appearEndFrame: number; readonly moveStartFrame: number; readonly moveEndFrame?: number } {+ assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "TierBoard Item duration is invalid.");+ assert(Number.isSafeInteger(appearFrames) && appearFrames > 0, "TierBoard appear duration is invalid.");+ assert(Number.isSafeInteger(moveFrames) && moveFrames > 0, "TierBoard move duration is invalid.");+ const moveStartFrame = Math.max(appearFrames, durationFrames - moveFrames);+ return {+ appearEndFrame: appearFrames,+ moveStartFrame,+ ...(durationFrames > moveStartFrame ? { moveEndFrame: durationFrames } : {}),+ };+}+export function fitColumnRevealMotion(durationFrames: number,preferredAppearFrames: number,@@ -624,14 +745,17 @@ export function fitColumnRevealMotion(return { mode: "stage", appearFrames, moveFrames: durationFrames - appearFrames };}-export function buildTierBoardProgram(header: RankingHeader, frameValue: import("@hypit/spatial").SpatialFrame, schedule: RankingSchedule, style: TierBoardStyle, set: TierBoardItemSet): TierBoardProgram {+export function buildTierBoardProgram(header: RankingHeader, canvasValue: CanvasSpace, frameValue: import("@hypit/spatial").SpatialFrame, schedule: RankingSchedule, style: TierBoardStyle, set: TierBoardItemSet): TierBoardProgram {assert(header.variant === "tier-board" && schedule.variant === "tier-board", "TierBoard variant is inconsistent.");+ assertCanvasSpace(canvasValue);assertSpatialFrame(frameValue);assertTierBoardStyle(style);- const items = orderForSchedule(schedule, set.items).map((item) => structuredClone(item));+ windowedIdsEqual(schedule, set.items);+ const byId = new Map(set.items.map((item) => [item.id, item]));+ const items = schedule.entries.map((entry) => structuredClone(byId.get(entry.itemId)!));const rows = new Set(style.rows.map((row) => row.id));for (const item of items) assert(rows.has(item.tier), `TierBoard Item ${item.id} references unknown tier ${item.tier}.`);- const result: TierBoardProgram = { id: header.id, frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };+ const result: TierBoardProgram = { id: header.id, canvas: structuredClone(canvasValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };assertTierBoardProgram(result);return canonicalize(result) as unknown as TierBoardProgram;}@@ -641,7 +765,7 @@ export function buildColumnProgram(header: RankingHeader, canvasValue: CanvasSpaassertCanvasSpace(canvasValue);assertSpatialFrame(frameValue);assertColumnStyle(style);- columnIdsEqual(schedule, set.items);+ windowedIdsEqual(schedule, set.items);const items = [...set.items].map((item) => structuredClone(item)).sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));const result: ColumnProgram = { id: header.id, canvas: structuredClone(canvasValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };assertColumnProgram(result);@@ -662,9 +786,10 @@ export function buildTopThreeProgram(header: RankingHeader, frameValue: import("export function assertTierBoardProgram(value: TierBoardProgram): void {assertRankingSchedule(value.schedule);assert(value.schedule.variant === "tier-board", "TierBoardProgram Schedule variant is invalid.");+ assertCanvasSpace(value.canvas);assertSpatialFrame(value.frame);assertTierBoardStyle(value.style);- idsEqual(value.schedule, value.items);+ windowedIdsEqual(value.schedule, value.items);value.items.forEach((item) => { assertRankingItemSpec(item); assertBlobImage(item.icon, `TierBoardItem.${item.id}.icon`); });}@@ -674,7 +799,7 @@ export function assertColumnProgram(value: ColumnProgram): void {assertCanvasSpace(value.canvas);assertSpatialFrame(value.frame);assertColumnStyle(value.style);- columnIdsEqual(value.schedule, value.items);+ windowedIdsEqual(value.schedule, value.items);value.items.forEach((item) => { assertRankingItemSpec(item); if (item.icon !== undefined) assertBlobImage(item.icon, `ColumnItem.${item.id}.icon`); });for (let index = 1; index < value.items.length; index += 1) {assert(value.items[index - 1]!.rank < value.items[index]!.rank, "ColumnProgram Items are not ordered by unique rank.");@@ -704,21 +829,26 @@ function sealEvents(id: string, variant: RankingVariant, events: readonly Rankinexport function buildTierBoardSoundEvents(schedule: RankingSchedule, style: TierBoardStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {assert(schedule.variant === "tier-board" && specs.variant === "tier-board", "TierBoard event inputs disagree.");assertTierBoardStyle(style);- const ordered = orderForSchedule(schedule, specs.items);- const events = schedule.entries.flatMap((entry, index) => {- const spec = ordered[index] as TierBoardItemSpec;- const duration = entry.stage.endFrameExclusive - entry.triggerFrame;- const fitted = fitRankingStageMotion(duration, style.motion.appearFrames, style.motion.moveFrames, spec.entry === "stage");- return [event(schedule.id, entry.itemId, "appear", entry.triggerFrame),- ...(spec.entry === "stage" ? [event(schedule.id, entry.itemId, "move", entry.stage.endFrameExclusive - fitted.moveFrames)] : [])];- });+ windowedIdsEqual(schedule, specs.items);+ const byId = new Map(specs.items.map((spec) => [spec.id, spec as TierBoardItemSpec]));+ const events = schedule.entries.flatMap((entry) => {+ if (entry.mode === "preset") return [];+ const spec = byId.get(entry.itemId)!;+ assert(!spec.preset, `TierBoard reveal ${entry.itemId} cannot be preset.`);+ const duration = entry.window.endFrameExclusive - entry.window.startFrame;+ const phases = resolveTierBoardMotion(duration, style.motion.appearFrames, style.motion.moveFrames);+ return [event(schedule.id, entry.itemId, "appear", entry.window.startFrame),+ ...(spec.entry === "drop" && phases.moveEndFrame !== undefined+ ? [event(schedule.id, entry.itemId, "move", entry.window.startFrame + phases.moveStartFrame)]+ : [])];+ }).sort((left, right) => left.frame - right.frame || left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id));return sealEvents(schedule.id, schedule.variant, events);}export function buildColumnSoundEvents(schedule: RankingSchedule, style: ColumnStyle, specs: RankingItemSpecSet): RankingSoundEventPlan {assert(schedule.variant === "column" && specs.variant === "column", "Column event inputs disagree.");assertColumnStyle(style);- columnIdsEqual(schedule, specs.items);+ windowedIdsEqual(schedule, specs.items);const events = schedule.entries.flatMap((entry) => {if (entry.mode === "preset") return [];const duration = entry.window.endFrameExclusive - entry.window.startFrame;diff --git a/packages/ranking/src/style.ts b/packages/ranking/src/style.tsindex b1a783c5..bb594b87 100644--- a/packages/ranking/src/style.ts+++ b/packages/ranking/src/style.ts@@ -31,20 +31,22 @@ const COMMON_KEYS = ["appear-frames", "move-frames", "motion-easing","board-background", "board-border-color", "board-border-width", "board-radius","board-shadow-x", "board-shadow-y", "board-shadow-blur", "board-shadow-spread", "board-shadow-color",- "board-stack", "item-stack", "stage-stack",+ "board-stack", "item-stack","appear-gain", "move-gain", "sound-fade-frames",] as const;const TIER_KEYS = [- ...COMMON_KEYS,- "rows", "label-width", "padding", "row-height", "row-gap", "cell-gap",- "icon-size", "icon-radius", "icon-fit", "stage-x", "stage-y", "stage-size",+ "rows", "label-text-color", "label-size", "line-height",+ "board-background", "board-border-color", "board-border-width",+ "label-width", "stage-x", "stage-y", "stage-size", "icon-radius-ratio", "icon-fit",+ "appear-frames", "move-frames", "board-stack", "stage-stack", "item-stack",+ "appear-gain", "move-gain", "sound-fade-frames",] as const;const COLUMN_KEYS = [...COMMON_KEYS,"rank-colors", "padding", "row-height", "row-gap", "icon-size", "icon-radius", "icon-fit",- "stage-x", "stage-y", "stage-size",+ "stage-x", "stage-y", "stage-size", "stage-stack",] as const;const TOP_KEYS = [@@ -76,6 +78,13 @@ function integer(recipe: SvsRecipe, name: string, fallback: number): number {return value;}+function optionalNumber(recipe: SvsRecipe, name: string): number | undefined {+ const value = recipe.properties[name];+ if (value === undefined) return undefined;+ if (typeof value !== "number" || !Number.isFinite(value)) fail(recipe, `${name} must be a finite number.`);+ return value;+}+function text(recipe: SvsRecipe, name: string, fallback: string): string {const value = recipe.properties[name];if (value === undefined) return fallback;@@ -145,10 +154,11 @@ function sound(recipe: SvsRecipe): RankingSoundStyle {function rowList(recipe: SvsRecipe): TierRowStyle[] {const value = recipe.properties.rows ?? [- { id: "s", label: "S", color: "#ef4444" },- { id: "a", label: "A", color: "#f59e0b" },- { id: "b", label: "B", color: "#22c55e" },- { id: "c", label: "C", color: "#3b82f6" },+ { id: "s", label: "S", color: "#EE5F52" },+ { id: "a", label: "A", color: "#F0A04C" },+ { id: "b", label: "B", color: "#F0C84D" },+ { id: "c", label: "C", color: "#EDE356" },+ { id: "d", label: "D", color: "#A6DA7B" },];if (!Array.isArray(value) || value.length === 0) fail(recipe, "rows must be a non-empty array.");return value.map((item, index) => {@@ -180,22 +190,25 @@ export function decodeTierBoardStyle(): { readonly style: TierBoardStyle; readonly sound: RankingSoundStyle } {known(recipe, TIER_KEYS);const fonts = exactFonts(font);+ const labelWidthRatio = optionalNumber(recipe, "label-width");const style: TierBoardStyle = {-rows: rowList(recipe),- board: board(recipe),- text: typography(recipe, fonts),- labelWidthPx: number(recipe, "label-width", 72),- paddingPx: number(recipe, "padding", 18),- rowHeightPx: number(recipe, "row-height", 92),- rowGapPx: number(recipe, "row-gap", 10),- cellGapPx: number(recipe, "cell-gap", 12),- iconSizePx: number(recipe, "icon-size", 72),- iconRadiusPx: number(recipe, "icon-radius", 12),+ fonts,+ labelTextColor: text(recipe, "label-text-color", "#2c2c2c"),+ labelSizeRatio: number(recipe, "label-size", 0.3),+ labelLineHeight: number(recipe, "line-height", 1),+ boardColor: text(recipe, "board-background", "#2b2b30"),+ borderColor: text(recipe, "board-border-color", "#111315"),+ borderWidthPx: number(recipe, "board-border-width", 3),+ ...(labelWidthRatio === undefined ? {} : { labelWidthRatio }),+ stagePoint: { x: number(recipe, "stage-x", 0.2), y: number(recipe, "stage-y", 0.3) },+ stageSizePx: number(recipe, "stage-size", 168),+ iconRadiusRatio: number(recipe, "icon-radius-ratio", 0.12),iconFit: oneOf(recipe, "icon-fit", ["contain", "cover"] as const, "cover"),- stagePoint: { x: number(recipe, "stage-x", 0.5), y: number(recipe, "stage-y", 0.23) },- stageSizePx: number(recipe, "stage-size", 108),- motion: motion(recipe),+ motion: {+ appearFrames: integer(recipe, "appear-frames", 8),+ moveFrames: integer(recipe, "move-frames", 14),+ },boardStackingOrder: integer(recipe, "board-stack", 20),stageStackingOrder: integer(recipe, "stage-stack", 25),itemStackingOrder: integer(recipe, "item-stack", 30),diff --git a/packages/ranking/src/surface.ts b/packages/ranking/src/surface.tsindex aa90d1f9..4ac2b85e 100644--- a/packages/ranking/src/surface.ts+++ b/packages/ranking/src/surface.ts@@ -6,6 +6,7 @@ import {optionalTextAttribute as optionalText,type StructuredElement,type StructuredSurfaceHandler,+ type SurfaceComponentDraft,type SurfaceRecordDraft,type SurfaceResolvedReference,type MarkupAttributeValue,@@ -13,13 +14,12 @@ import {import { sameType, type CanonicalValue, type TypeRef } from "@hypit/protocol";import { mediaTypes } from "@hypit/media";import type { FontArtifactRef, FontStackRef } from "@hypit/media";-import { narrativeTypes } from "@hypit/narrative";import { semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import type { SvsRecipe } from "@hypit/svs";import { textTypes } from "@hypit/text";-import { temporalTypes } from "@hypit/temporal";+import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames } from "@hypit/temporal-markup";import { createRankingFragment } from "./fragment.js";import type { RankingFragmentItem, RankingFragmentSound } from "./fragment.js";@@ -131,32 +131,37 @@ function itemSpec(variant: RankingVariant,suffix: string,resolve: (path: string) => SurfaceResolvedReference | undefined,-): { readonly spec: RankingItemSpec | RankingTextItemShell; readonly content?: SurfaceResolvedReference; readonly timing?: SurfaceResolvedReference } {+): { readonly spec: RankingItemSpec | RankingTextItemShell; readonly content?: SurfaceResolvedReference; readonly timed: boolean } {const id = itemIdentity(element, suffix);const stackingOrder = integer(element, "stack");let value: RankingItemSpec;if (variant === "tier-board") {- allowed(element, ["id", "tier", "entry", "icon", "at", "stack"]);+ allowed(element, ["id", "tier", "entry", "icon", "preset", "during", "stack"]);empty(element);- const entry = text(element, "entry", "direct");- if (entry !== "direct" && entry !== "stage") throw new Error(`${element.name}.entry must be direct or stage.`);- const timing = reference(element.attributes.at, `${element.name}.at`, narrativeTypes.moment, resolve);- value = {- variant, id, tier: text(element, "tier"), entry,- ...(stackingOrder === undefined ? {} : { stackingOrder }),- } satisfies TierBoardItemSpec;+ const preset = boolean(element, "preset", false);+ const timed = element.attributes.during !== undefined;+ if (preset && timed) throw new Error(`${element.name} cannot combine preset=true with during.`);+ if (preset && element.attributes.entry !== undefined) throw new Error(`${element.name} preset Items do not have an entry mode.`);+ if (!preset && !timed) throw new Error(`${element.name} requires during unless preset=true.`);+ const common = { variant, id, tier: text(element, "tier"),+ ...(stackingOrder === undefined ? {} : { stackingOrder }) } as const;+ if (preset) value = { ...common, preset: true } satisfies TierBoardItemSpec;+ else {+ const entry = text(element, "entry");+ if (entry !== "direct" && entry !== "drop") throw new Error(`${element.name}.entry must be direct or drop.`);+ value = { ...common, preset: false, entry } satisfies TierBoardItemSpec;+ }assertRankingItemSpec(value);- return { spec: value, timing };+ return { spec: value, timed };} else if (variant === "column") {allowed(element, ["id", "label", "icon", "rank", "preset", "during", "stack"]);empty(element);const rank = integer(element, "rank");if (rank === undefined || rank < 1) throw new Error(`${element.name}.rank must be a positive integer.`);const preset = boolean(element, "preset", false);- const timing = element.attributes.during === undefined ? undefined- : reference(element.attributes.during, `${element.name}.during`, narrativeTypes.selection, resolve);- if (preset && timing !== undefined) throw new Error(`${element.name} cannot combine preset=true with during.`);- if (!preset && timing === undefined) throw new Error(`${element.name} requires during unless preset=true.`);+ const timed = element.attributes.during !== undefined;+ if (preset && timed) throw new Error(`${element.name} cannot combine preset=true with during.`);+ if (!preset && !timed) throw new Error(`${element.name} requires during unless preset=true.`);const label = textValue(element.attributes.label, `${element.name}.label`, resolve);if (typeof label === "string") value = {variant, id, label, rank, preset,@@ -165,13 +170,12 @@ function itemSpec(else return { spec: sealRankingTextItemShell({variant, id, rank, preset,...(stackingOrder === undefined ? {} : { stackingOrder }),- }), content: label, ...(timing === undefined ? {} : { timing }) };+ }), content: label, timed };assertRankingItemSpec(value);- return { spec: value, ...(timing === undefined ? {} : { timing }) };+ return { spec: value, timed };} else if (variant === "top-three") {- allowed(element, ["id", "label", "icon", "at", "stack"]);+ allowed(element, ["id", "label", "icon", ...temporalInstantAttributeNames, "stack"]);empty(element);- const timing = reference(element.attributes.at, `${element.name}.at`, narrativeTypes.moment, resolve);const label = textValue(element.attributes.label, `${element.name}.label`, resolve);if (typeof label === "string") value = {variant, id, label,@@ -180,9 +184,9 @@ function itemSpec(else return { spec: sealRankingTextItemShell({variant, id,...(stackingOrder === undefined ? {} : { stackingOrder }),- }), content: label, timing };+ }), content: label, timed: true };assertRankingItemSpec(value);- return { spec: value, timing };+ return { spec: value, timed: true };}throw new Error(`${element.name} belongs to an unknown Ranking variant.`);}@@ -196,65 +200,45 @@ const variantDefinition = {function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {return ({ element, resolveReference }) => {const common = ["id", "semantic", "frame", "during", "terminal", "style", "appear-sound", "move-sound"];- const attributes = variant === "column"+ const attributes = variant === "column" || variant === "tier-board"? [...common.filter((name) => name !== "terminal"), "canvas"]: common;allowed(element, attributes);const id = text(element, "id");const selected = variantDefinition[variant];const semantic = reference(element.attributes.semantic, `${element.name}.semantic`, semanticTrackTypes.track, resolveReference);- const canvas = variant === "column"+ const canvas = variant === "column" || variant === "tier-board"? reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference): undefined;const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);- const outer = variant === "column"- ? oneOfReference(element.attributes.during, `${element.name}.during`, [narrativeTypes.selection, narrativeTypes.excerpt], resolveReference)- : reference(element.attributes.during, `${element.name}.during`, narrativeTypes.selection, resolveReference);- const outerKind = sameType(outer.type, narrativeTypes.excerpt) ? "segment" : "selection";- const terminal = variant === "column" ? undefined- : reference(element.attributes.terminal, `${element.name}.terminal`, narrativeTypes.moment, resolveReference);+ const outerTemporal = createTemporalWindowProjection({ id: `${id}.outer`, subjectId: id, element, semantic, resolveReference });+ const terminalTemporal = variant === "top-three"+ ? createTemporalInstantProjection({+ id: `${id}.terminal`, subjectId: id, element, semantic, resolveReference,+ semanticAttribute: "terminal", projectedAttribute: false,+ })+ : undefined;const styleRaw = element.attributes.style;const style = reference(styleRaw, `${element.name}.style`, selected.style, resolveReference);- const records: SurfaceRecordDraft[] = [];+ const records: SurfaceRecordDraft[] = [...outerTemporal.records, ...(terminalTemporal?.records ?? [])];+ const temporalComponents: SurfaceComponentDraft[] = [...outerTemporal.components, ...(terminalTemporal?.components ?? [])];+ const temporalFragments = [...outerTemporal.fragments, ...(terminalTemporal?.fragments ?? [])];const headerId = `${id}.header`;records.push({id: headerId, type: rankingTypes.header,value: { kind: "inline", value: sealRankingHeader({ id, variant }) as unknown as CanonicalValue },range: element.range,});- const outerSpecId = `${id}.outer.window`;- const outerSpecName = "outer-spec";- records.push({- id: outerSpecId,- type: temporalTypes.windowSpec,- value: { kind: "inline", value: {- id: `${id}.outer`,- projection: outerKind === "selection"- ? { start: { ref: "selection.start" }, end: { ref: "selection.end" } }- : { start: { ref: "segment.start" }, end: { ref: "segment.end" } },- } as unknown as CanonicalValue },- range: element.range,- });- const terminalSpecId = `${id}.terminal.point`;- if (terminal !== undefined) records.push({- id: terminalSpecId,- type: temporalTypes.pointSpec,- value: { kind: "inline", value: {- id: `${id}.terminal`,- projection: { ref: "moment.cue" },- } as unknown as CanonicalValue },- range: element.range,- });const inputs: Record<string, typeof semantic.ref> = {header: { kind: "record", id: headerId }, semantic: semantic.ref, frame: frame.ref,- outer: outer.ref, [outerSpecName]: { kind: "record", id: outerSpecId }, style: style.ref,+ outer: outerTemporal.ref, style: style.ref,...(canvas === undefined ? {} : { canvas: canvas.ref }),- ...(terminal === undefined ? {} : { terminal: terminal.ref, "terminal-spec": { kind: "record", id: terminalSpecId } }),+ ...(terminalTemporal === undefined ? {} : { terminal: terminalTemporal.ref }),};const items: RankingFragmentItem[] = [];const itemIds = new Set<string>();let index = 0;- let hasStage = false;+ let hasDrop = false;for (const child of element.children) {if (child.kind === "text") {if (child.value.trim().length > 0) throw new Error(`${element.name} accepts ${selected.tag} children only.`);@@ -267,32 +251,23 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {const spec = authored.spec;if (itemIds.has(spec.id)) throw new Error(`${element.name} has duplicate Item id ${spec.id}.`);itemIds.add(spec.id);- hasStage ||= spec.variant === "tier-board" && spec.entry === "stage";+ hasDrop ||= spec.variant === "tier-board" && !spec.preset && spec.entry === "drop";const specId = `${id}.item.${suffix}.spec`;const specName = `item-${suffix}-spec`;records.push({ id: specId, type: authored.content === undefined ? rankingTypes.itemSpec : rankingTypes.textItemShell, value: { kind: "inline", value: spec as unknown as CanonicalValue }, range: child.range });inputs[specName] = { kind: "record", id: specId };const contentName = authored.content === undefined ? undefined : `item-${suffix}-content`;if (authored.content !== undefined) inputs[contentName!] = authored.content.ref;- const timingName = authored.timing === undefined ? undefined : `item-${suffix}-timing`;- if (authored.timing !== undefined) inputs[timingName!] = authored.timing.ref;- const timingSpecName = authored.timing === undefined ? undefined- : `item-${suffix}-${variant === "column" ? "window" : "point"}-spec`;- if (authored.timing !== undefined) {- const timingSpecId = `${id}.item.${suffix}.${variant === "column" ? "window" : "point"}`;- records.push({- id: timingSpecId,- type: variant === "column" ? temporalTypes.windowSpec : temporalTypes.pointSpec,- value: { kind: "inline", value: {- id: `${id}.item.${suffix}`,- projection: variant === "column"- ? { start: { ref: "selection.start" }, end: { ref: "selection.end" } }- : { ref: "moment.cue" },- } as unknown as CanonicalValue },- range: child.range,- });- inputs[timingSpecName!] = { kind: "record", id: timingSpecId };+ const itemTemporal = !authored.timed ? undefined : variant === "top-three"+ ? createTemporalInstantProjection({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, semantic, resolveReference })+ : createTemporalWindowProjection({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, semantic, resolveReference });+ if (itemTemporal !== undefined) {+ records.push(...itemTemporal.records);+ temporalComponents.push(...itemTemporal.components);+ temporalFragments.push(...itemTemporal.fragments);}+ const timingName = itemTemporal === undefined ? undefined : `item-${suffix}-timing`;+ if (itemTemporal !== undefined) inputs[timingName!] = itemTemporal.ref;let iconName: string | undefined;if (variant === "tier-board" || child.attributes.icon !== undefined) {const icon = reference(child.attributes.icon, `${child.name}.icon`, mediaTypes.blobArtifact, resolveReference);@@ -303,7 +278,6 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {...(contentName === undefined ? {} : { contentName }),...(iconName === undefined ? {} : { iconName }),...(timingName === undefined ? {} : { timingName }),- ...(timingSpecName === undefined ? {} : { timingSpecName }),});}if (items.length === 0) throw new Error(`${element.name} requires at least one ${selected.tag}.`);@@ -312,7 +286,7 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {...(element.attributes["move-sound"] === undefined ? {} : { moveName: "move-sound" }),};if (sound.moveName !== undefined && variant === "top-three") throw new Error(`${element.name} has no move sound phase.`);- if (sound.moveName !== undefined && variant === "tier-board" && !hasStage) throw new Error(`${element.name}.move-sound requires one staged TierItem.`);+ if (sound.moveName !== undefined && variant === "tier-board" && !hasDrop) throw new Error(`${element.name}.move-sound requires one drop TierItem.`);for (const [attribute, inputName] of [["appear-sound", sound.appearName], ["move-sound", sound.moveName]] as const) {if (inputName === undefined) continue;inputs[inputName] = reference(element.attributes[attribute], `${element.name}.${attribute}`, mediaTypes.synchronized, resolveReference).ref;@@ -325,10 +299,10 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {}inputs["sound-style"] = soundStyle.ref;}- const fragment = createRankingFragment(variant, items, sound, outerKind);+ const fragment = createRankingFragment(variant, items, sound);return {records,- components: [{+ components: [...temporalComponents, {id, fragment: fragment.id, inputs,outputs: {schedule: `${id}.schedule`, program: `${id}.program`, visual: `${id}.visual`,@@ -336,7 +310,8 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {},range: element.range,}],- fragments: [fragment],+ fragments: [...temporalFragments, fragment],+ exports: [`${id}.schedule`, `${id}.program`, `${id}.visual`, ...(sound.appearName === undefined && sound.moveName === undefined ? [] : [`${id}.audio`])],};};}diff --git a/packages/ranking/src/tier.ts b/packages/ranking/src/tier.tsnew file mode 100644index 00000000..6d888bdf--- /dev/null+++ b/packages/ranking/src/tier.ts@@ -0,0 +1,176 @@+import { resolveTierBoardMotion } from "./schedule.js";+import type { TierBoardStyle } from "./types.js";++export type TierBoardGeometry = {+ readonly width: number;+ readonly height: number;+ readonly rowHeight: number;+ readonly labelWidth: number;+ readonly gap: number;+ readonly iconSize: number;+};++export type TierStageGeometry = {+ readonly centerX: number;+ readonly centerY: number;+ readonly size: number;+};++export type TierCell = {+ readonly x: number;+ readonly y: number;+ readonly size: number;+};++export type TierItemPose = {+ readonly x: number;+ readonly y: number;+ readonly scale: number;+ readonly opacity: number;+ readonly rotateDeg: number;+ readonly blurPx: number;+ readonly shadowY: number;+ readonly shadowBlur: number;+ readonly shadowOpacity: number;+};++function clamp01(value: number): number {+ return Math.max(0, Math.min(1, value));+}++function outCubic(value: number): number {+ return 1 - Math.pow(1 - value, 3);+}++function smootherStep(value: number): number {+ return value * value * value * (value * (value * 6 - 15) + 10);+}++export function tierBoardGeometry(width: number, height: number, style: TierBoardStyle): TierBoardGeometry {+ const rowHeight = height / style.rows.length;+ const labelWidth = Math.round(style.labelWidthRatio === undefined+ ? rowHeight * 1.5+ : width * style.labelWidthRatio);+ const gap = Math.max(4, Math.round(rowHeight * 0.03));+ return {+ width,+ height,+ rowHeight,+ labelWidth,+ gap,+ iconSize: rowHeight - gap * 2,+ };+}++export function tierStageGeometry(width: number, height: number, style: TierBoardStyle): TierStageGeometry {+ return {+ centerX: Math.round(width * style.stagePoint.x),+ centerY: Math.round(height * style.stagePoint.y),+ size: style.stageSizePx,+ };+}++export function tierCell(geometry: TierBoardGeometry, rowIndex: number, column: number): TierCell {+ return {+ x: geometry.labelWidth + geometry.gap + column * (geometry.iconSize + geometry.gap),+ y: Math.round(rowIndex * geometry.rowHeight+ + (geometry.rowHeight - geometry.iconSize) / 2),+ size: geometry.iconSize,+ };+}++function settled(cell: TierCell): TierItemPose {+ return {+ x: cell.x,+ y: cell.y,+ scale: 1,+ opacity: 1,+ rotateDeg: 0,+ blurPx: 0,+ shadowY: 7,+ shadowBlur: 10,+ shadowOpacity: 0.2,+ };+}++export function directTierItemPose(+ localFrame: number,+ cell: TierCell,+ appearFrames: number,+): TierItemPose {+ if (localFrame >= appearFrames) return settled(cell);+ const progress = clamp01(localFrame / appearFrames);+ const eased = outCubic(progress);+ const overshoot = Math.sin(Math.PI * progress) * 0.075;+ return {+ x: cell.x,+ y: cell.y,+ scale: 0.76 + 0.24 * eased + overshoot,+ opacity: Math.min(1, progress * 4),+ rotateDeg: 0,+ blurPx: (1 - eased) * 1.2,+ shadowY: 12 - 5 * eased,+ shadowBlur: 18 - 8 * eased,+ shadowOpacity: 0.28 - 0.08 * eased,+ };+}++export function fromHighTierItemPose(+ localFrame: number,+ durationFrames: number,+ stage: TierStageGeometry,+ cell: TierCell,+ appearFrames: number,+ moveFrames: number,+): TierItemPose {+ const phases = resolveTierBoardMotion(durationFrames, appearFrames, moveFrames);+ const stageX = stage.centerX - cell.size / 2;+ const stageY = stage.centerY - cell.size / 2;+ const stageScale = stage.size / cell.size;+ if (localFrame < phases.appearEndFrame) {+ const progress = clamp01(localFrame / appearFrames);+ const eased = outCubic(progress);+ const overshoot = Math.sin(Math.PI * progress) * 0.06;+ return {+ x: stageX,+ y: stageY,+ scale: stageScale * (0.76 + 0.24 * eased + overshoot),+ opacity: Math.min(1, progress * 4),+ rotateDeg: 0,+ blurPx: (1 - eased) * 1.6,+ shadowY: 18 - 2 * eased,+ shadowBlur: 28 - 4 * eased,+ shadowOpacity: 0.3,+ };+ }+ if (localFrame < phases.moveStartFrame) return {+ x: stageX,+ y: stageY,+ scale: stageScale,+ opacity: 1,+ rotateDeg: 0,+ blurPx: 0,+ shadowY: 16,+ shadowBlur: 24,+ shadowOpacity: 0.3,+ };+ if (localFrame < durationFrames) {+ const actualMoveFrames = (phases.moveEndFrame ?? durationFrames) - phases.moveStartFrame;+ const progress = clamp01((localFrame - phases.moveStartFrame) / actualMoveFrames);+ const eased = smootherStep(progress);+ const arc = Math.sin(Math.PI * eased);+ const arcHeight = Math.min(48, Math.max(20, Math.abs(cell.y - stageY) * 0.09));+ return {+ x: stageX + (cell.x - stageX) * eased,+ y: stageY + (cell.y - stageY) * eased - arcHeight * arc,+ scale: stageScale + (1 - stageScale) * eased + 0.025 * arc,+ opacity: 1,+ rotateDeg: 0,+ blurPx: 0,+ shadowY: 16 - 8 * eased,+ shadowBlur: 24 - 12 * eased,+ shadowOpacity: 0.3 - 0.1 * eased,+ };+ }+ return settled(cell);+}diff --git a/packages/ranking/src/types.ts b/packages/ranking/src/types.tsindex 32083817..f29a53e9 100644--- a/packages/ranking/src/types.ts+++ b/packages/ranking/src/types.ts@@ -5,7 +5,7 @@ import type {} from "@hypit/media";import type { BlobRef } from "@hypit/protocol";import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";-import type { TemporalPoint, TemporalWindow } from "@hypit/temporal";+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";export type RankingVariant = "tier-board" | "column" | "top-three";@@ -24,7 +24,7 @@ export type TriggeredRankingScheduleEntry = {export type TriggeredRankingSchedule = {readonly id: string;- readonly variant: Exclude<RankingVariant, "column">;+ readonly variant: "top-three";readonly outer: FrameSpan;readonly terminalFrame: number;readonly entries: readonly TriggeredRankingScheduleEntry[];@@ -32,23 +32,26 @@ export type TriggeredRankingSchedule = {export type TriggeredRankingCandidate = {readonly itemId: string;- readonly activation: TemporalPoint;+ readonly activation: TemporalInstant;};export type TriggeredRankingCandidateSet = {readonly entries: readonly TriggeredRankingCandidate[];};-export type ColumnWindowInput = {+export type RankingWindowInput = {readonly itemId: string;readonly window: TemporalWindow;};-export type ColumnWindowSet = {- readonly entries: readonly ColumnWindowInput[];+export type RankingWindowSet = {+ readonly entries: readonly RankingWindowInput[];};-export type ColumnScheduleEntry =+export type TierBoardWindowSet = RankingWindowSet;+export type ColumnWindowSet = RankingWindowSet;++export type WindowedRankingScheduleEntry =| {readonly itemId: string;readonly mode: "preset";@@ -61,14 +64,21 @@ export type ColumnScheduleEntry =readonly settled: FrameSpan;};+export type TierBoardSchedule = {+ readonly id: string;+ readonly variant: "tier-board";+ readonly outer: FrameSpan;+ readonly entries: readonly WindowedRankingScheduleEntry[];+};+export type ColumnSchedule = {readonly id: string;readonly variant: "column";readonly outer: FrameSpan;- readonly entries: readonly ColumnScheduleEntry[];+ readonly entries: readonly WindowedRankingScheduleEntry[];};-export type RankingSchedule = TriggeredRankingSchedule | ColumnSchedule;+export type RankingSchedule = TriggeredRankingSchedule | TierBoardSchedule | ColumnSchedule;export type RankingTextStyle = {readonly fonts: readonly FontArtifactRef[];@@ -98,6 +108,11 @@ export type RankingMotionStyle = {readonly easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";};+export type TierBoardMotionStyle = {+ readonly appearFrames: number;+ readonly moveFrames: number;+};+export type RankingSoundStyle = {readonly appearGain: number;readonly moveGain: number;@@ -112,19 +127,19 @@ export type TierRowStyle = {export type TierBoardStyle = {readonly rows: readonly TierRowStyle[];- readonly board: RankingBoardPaint;- readonly text: RankingTextStyle;- readonly labelWidthPx: number;- readonly paddingPx: number;- readonly rowHeightPx: number;- readonly rowGapPx: number;- readonly cellGapPx: number;- readonly iconSizePx: number;- readonly iconRadiusPx: number;- readonly iconFit: "contain" | "cover";+ readonly fonts: readonly FontArtifactRef[];+ readonly labelTextColor: string;+ readonly labelSizeRatio: number;+ readonly labelLineHeight: number;+ readonly boardColor: string;+ readonly borderColor: string;+ readonly borderWidthPx: number;+ readonly labelWidthRatio?: number;readonly stagePoint: { readonly x: number; readonly y: number };readonly stageSizePx: number;- readonly motion: RankingMotionStyle;+ readonly iconRadiusRatio: number;+ readonly iconFit: "contain" | "cover";+ readonly motion: TierBoardMotionStyle;readonly boardStackingOrder: number;readonly stageStackingOrder: number;readonly itemStackingOrder: number;@@ -164,14 +179,18 @@ export type TopThreeStyle = {readonly itemStackingOrder: number;};-export type TierBoardItemSpec = {+type TierBoardItemBase = {readonly variant: "tier-board";readonly id: string;readonly tier: string;- readonly entry: "direct" | "stage";readonly stackingOrder?: number;};+export type TierBoardItemSpec = TierBoardItemBase & (+ | { readonly preset: true }+ | { readonly preset: false; readonly entry: "direct" | "drop" }+);+export type ColumnItemSpec = {readonly variant: "column";readonly id: string;@@ -216,8 +235,9 @@ export type TopThreeItemSet = {export type TierBoardProgram = {readonly id: string;+ readonly canvas: CanvasSpace;readonly frame: SpatialFrame;- readonly schedule: TriggeredRankingSchedule;+ readonly schedule: TierBoardSchedule;readonly style: TierBoardStyle;readonly items: readonly TierBoardItem[];};diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.tsindex 101cdb9b..7529e8c2 100644--- a/packages/ranking/test/ranking.test.ts+++ b/packages/ranking/test/ranking.test.ts@@ -3,6 +3,7 @@ import test from "node:test";import { videoContractManifests } from "../../../test/support/video-domain.js";import { fixtureDigest } from "../../../test/fixture-digest.js";import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";+import { projectMomentInstantFixture, projectSegmentWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";import { createResolvedClosure } from "@hypit/core";import type { FontArtifactRef, SynchronizedMedia } from "@hypit/media";@@ -18,6 +19,7 @@ import {appendRankingItemSpec,appendRankingSound,appendTierBoardItem,+ appendTierBoardWindow,appendTopThreeItem,appendTriggeredRankingCandidate as appendProjectedTriggeredRankingCandidate,buildColumnProgram,@@ -25,6 +27,7 @@ import {buildColumnSoundEvents,buildTriggeredRankingSchedule,buildTierBoardProgram,+ buildTierBoardSchedule,buildTierBoardSoundEvents,buildTopThreeProgram,buildTopThreeSoundEvents,@@ -33,17 +36,20 @@ import {createRankingItemSpecSet,createRankingSoundSet,createTierBoardItemSet,+ createTierBoardWindowSet,createTopThreeItemSet,createTriggeredRankingCandidateSet,decodeColumnStyle,decodeColumnStyleSurface,decodeColumnSurface,+ directTierItemPose,decodeTierBoardStyle,decodeTierBoardStyleSurface,decodeTierBoardSurface,decodeTopThreeStyle,decodeTopThreeStyleSurface,decodeTopThreeSurface,+ fromHighTierItemPose,renderColumn,renderRankingAudio,renderTierBoard,@@ -53,7 +59,11 @@ import {rankingMarkupSurfaces,rankingProducers,rankingTypes,+ resolveTierBoardMotion,sealRankingHeader,+ tierBoardGeometry,+ tierCell,+ tierStageGeometry,} from "@hypit/ranking";import type {ColumnItemSpec,@@ -63,6 +73,7 @@ import type {RankingItemSpecSet,TriggeredRankingSchedule,TriggeredRankingCandidateSet,+ TierBoardSchedule,TierBoardItemSpec,TopThreeItemSpec,} from "@hypit/ranking";@@ -71,7 +82,7 @@ import { semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";import { svsRecipeType } from "@hypit/svs";import { sealText, textManifest, textTypes } from "@hypit/text";-import { projectMomentPoint, projectSegmentWindow, projectSelectionWindow } from "@hypit/temporal";+import { temporalProducers } from "@hypit/temporal";import type { TemporalWindow } from "@hypit/temporal";import type {StructuredElement,@@ -80,7 +91,7 @@ import type {MarkupAttributeValue,} from "@hypit/markup";-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 8,frameRate: { numerator: 30, denominator: 1 },});@@ -91,6 +102,9 @@ const canvas = sealCanvasSpace({const frame = sealSpatialFrame({xPx: 40, yPx: 80, widthPx: 720, heightPx: 560,});+const tierFrame = sealSpatialFrame({+ xPx: 40, yPx: 360, widthPx: 720, heightPx: 280,+});const semanticTrack = semanticTrackFixture(space, {segments: [{ id: "opening", frameCount: 10 },@@ -114,17 +128,19 @@ const semanticTrack = semanticTrackFixture(space, {],});const outer: NarrativeSelectionRef = {+ narrativeId: space.narrativeId,id: "ranking-window",startAnchorId: "outer-start",endAnchorId: "outer-end",};const terminal: NarrativeMomentRef = {+ narrativeId: space.narrativeId,id: "ranking-complete",anchorId: "terminal",};-const rankingSegment: NarrativeExcerpt = { kind: "segment", id: "ranking", tokenStart: 0, tokenEndExclusive: 1 };+const rankingSegment: NarrativeExcerpt = { narrativeId: space.narrativeId, kind: "segment", id: "ranking", tokenStart: 0, tokenEndExclusive: 1 };const selection = (id: string, startAnchorId: string, endAnchorId: string): NarrativeSelectionRef => ({- id, startAnchorId, endAnchorId,+ narrativeId: space.narrativeId, id, startAnchorId, endAnchorId,});const early = selection("early", "early-start", "early-end");const overlapping = selection("overlapping", "overlap-start", "overlap-end");@@ -158,6 +174,7 @@ function schedule(let candidates = createTriggeredRankingCandidateSet();for (const [index, value] of values.entries()) {candidates = appendTriggeredRankingCandidate(candidates, value, semanticTrack, {+ narrativeId: space.narrativeId,id: `${value.id}-moment`,anchorId: anchors[index]!,});@@ -169,7 +186,7 @@ function appendTriggeredRankingCandidate(set: ReturnType<typeof createTriggeredRankingCandidateSet>, spec: RankingItemSpec,semantic: typeof semanticTrack, moment: NarrativeMomentRef,) {- return appendProjectedTriggeredRankingCandidate(set, spec, projectMomentPoint({+ return appendProjectedTriggeredRankingCandidate(set, spec, projectMomentInstantFixture({itemId: spec.id, semantic, moment,projection: { ref: "moment.cue" },}));@@ -188,12 +205,12 @@ function buildRankingSchedule(input: {items: input.items,space,outer: projectSelectionWindow({- itemId: input.outer.id, semantic: input.semantic, selection: input.outer,+ itemId: input.outer.id, subjectId: input.header.id, semantic: input.semantic, selection: input.outer,projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },}),candidates: input.candidates,- terminal: projectMomentPoint({- itemId: input.terminal.id, semantic: input.semantic, moment: input.terminal,+ terminal: projectMomentInstantFixture({+ itemId: input.terminal.id, subjectId: input.header.id, semantic: input.semantic, moment: input.terminal,projection: { ref: "moment.cue" },}),});@@ -209,16 +226,26 @@ function appendProjectedColumnWindow(}));}-function projectColumnSegmentOuterWindow(semantic: typeof semanticTrack, segment: NarrativeExcerpt): TemporalWindow {+function appendProjectedTierWindow(+ set: ReturnType<typeof createTierBoardWindowSet>, spec: TierBoardItemSpec,+ semantic: typeof semanticTrack, selectionValue: NarrativeSelectionRef,+) {+ return appendTierBoardWindow(set, spec, projectSelectionWindow({+ itemId: spec.id, semantic, selection: selectionValue,+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },+ }));+}++function projectColumnSegmentOuterWindow(semantic: typeof semanticTrack, segment: NarrativeExcerpt, subjectId: string): TemporalWindow {return projectSegmentWindow({- itemId: `${segment.id}:outer`, semantic, segment,+ itemId: `${segment.id}:outer`, subjectId, semantic, segment,projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },});}-const tierSpec = (id: string, tier: string, entry: "direct" | "stage" = "direct"): TierBoardItemSpec => ({- variant: "tier-board", id, tier, entry,-});+const tierSpec = (id: string, tier: string, entry: "direct" | "drop" = "direct", preset = false): TierBoardItemSpec => ({+ variant: "tier-board", id, tier, ...(preset ? { preset: true } : { preset: false, entry }),+} as TierBoardItemSpec);const columnSpec = (id: string, rank: number, preset = false): ColumnItemSpec => ({variant: "column", id, label: id.toUpperCase(), rank, preset,});@@ -230,7 +257,7 @@ function columnSchedule(owner: RankingHeader,values: readonly ColumnItemSpec[],windows: Readonly<Record<string, NarrativeSelectionRef>>,- outerWindow = projectColumnSegmentOuterWindow(semanticTrack, rankingSegment),+ outerWindow = projectColumnSegmentOuterWindow(semanticTrack, rankingSegment, owner.id),): ColumnSchedule {let set = createColumnWindowSet();for (const value of values) {@@ -239,7 +266,26 @@ function columnSchedule(if (timing === undefined) throw new Error(`Missing test Selection for ${value.id}.`);set = appendProjectedColumnWindow(set, value, semanticTrack, timing);}- return buildColumnSchedule({ header: owner, items: specs(owner, values), outer: outerWindow, windows: set });+ return buildColumnSchedule({ header: owner, items: specs(owner, values), space, outer: outerWindow, windows: set });+}++function tierSchedule(+ owner: RankingHeader,+ values: readonly TierBoardItemSpec[],+ windows: Readonly<Record<string, NarrativeSelectionRef>>,+ outerWindow = projectSelectionWindow({+ itemId: outer.id, subjectId: owner.id, semantic: semanticTrack, selection: outer,+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },+ }),+): TierBoardSchedule {+ let set = createTierBoardWindowSet();+ for (const value of values) {+ if (value.preset) continue;+ const timing = windows[value.id];+ if (timing === undefined) throw new Error(`Missing test Selection for ${value.id}.`);+ set = appendProjectedTierWindow(set, value, semanticTrack, timing);+ }+ return buildTierBoardSchedule({ header: owner, items: specs(owner, values), space, outer: outerWindow, windows: set });}test("RankingSchedule derives chronological Item order from item-owned Moments and preserves a settled suffix", () => {@@ -254,10 +300,10 @@ test("RankingSchedule derives chronological Item order from item-owned Moments a});test("RankingSchedule requires one item-owned Moment per Item and distinct chronological frames", () => {- const owner = header("tier-board");- const values = [tierSpec("a", "s"), tierSpec("b", "a")];+ const owner = header("top-three");+ const values = [topSpec("a"), topSpec("b")];let missing = createTriggeredRankingCandidateSet();- missing = appendTriggeredRankingCandidate(missing, values[0]!, semanticTrack, { id: "a-at", anchorId: "one" });+ missing = appendTriggeredRankingCandidate(missing, values[0]!, semanticTrack, { narrativeId: space.narrativeId, id: "a-at", anchorId: "one" });assert.throws(() => buildRankingSchedule({header: owner, items: specs(owner, values), semantic: semanticTrack, outer, candidates: missing, terminal,}), /item-owned Moments differ/u);@@ -266,11 +312,12 @@ test("RankingSchedule requires one item-owned Moment per Item and distinct chrontest("variant Style decoders reject unknown Recipes and keep exact fonts and independent stacks", () => {const tier = decodeTierBoardStyle(recipe("ranking.tier", {- rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }], "board-stack": 8, "stage-stack": 20, "item-stack": 31,+ rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }], "board-stack": 8, "item-stack": 31,}), font);assert.deepEqual(tier.style.rows.map((row) => row.id), ["s", "a"]);- assert.equal(tier.style.text.fonts[0]?.sources[0]?.artifact.digest, font.sources[0]!.artifact.digest);- assert.deepEqual([tier.style.boardStackingOrder, tier.style.stageStackingOrder, tier.style.itemStackingOrder], [8, 20, 31]);+ assert.equal(tier.style.fonts[0]?.sources[0]?.artifact.digest, font.sources[0]!.artifact.digest);+ assert.deepEqual([tier.style.boardStackingOrder, tier.style.itemStackingOrder], [8, 31]);+ assert.throws(() => decodeTierBoardStyle(recipe("ranking.tier", { padding: 18 }), font), /does not accept padding/u);assert.throws(() => decodeColumnStyle(recipe("ranking.column", { "tier-only": 1 }), font), /does not accept/u);assert.equal(decodeTopThreeStyle(recipe("ranking.top"), font).style.slotColors.length, 3);assert.throws(() => decodeTopThreeStyle(recipe("ranking.top", {@@ -278,27 +325,65 @@ test("variant Style decoders reject unknown Recipes and keep exact fonts and ind}), font), /exactly three/u);});-test("TierBoard owns cumulative direct/stage placement and rejects invalid schedule boundaries", () => {+test("TierBoard separates its board Frame from the Canvas stage and holds drop Items until the final curved glide", () => {const owner = header("tier-board", "tiers");- const semantic = [tierSpec("alpha", "s", "stage"), tierSpec("beta", "a")];+ const semantic = [+ tierSpec("late", "s", "drop"),+ tierSpec("preset", "s", "direct", true),+ tierSpec("early", "s"),+ ];const style = decodeTierBoardStyle(recipe("ranking.tier", {rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }], "appear-frames": 5, "move-frames": 8,}), font).style;let set = createTierBoardItemSet();- set = appendTierBoardItem(set, semantic[0]!, image("alpha"));- set = appendTierBoardItem(set, semantic[1]!, image("beta"));- const program = buildTierBoardProgram(owner, frame, schedule(owner, semantic), style, set);+ for (const item of semantic) set = appendTierBoardItem(set, item, image(item.id));+ const value = tierSchedule(owner, semantic, { early, late });+ const program = buildTierBoardProgram(owner, canvas, tierFrame, value, style, set);const track = renderTierBoard(space, program);- assert.deepEqual(track.presents.map((item) => item.stacking.order).sort((a, b) => a - b), [20, 25, 30, 30, 30, 30]);- assert.equal(track.presents.find((item) => item.id.endsWith(":item:alpha:settled"))?.span.endFrameExclusive, 230);- const tightTerminal = { ...terminal, anchorId: "two" };- let candidates = createTriggeredRankingCandidateSet();- for (const [index, item] of semantic.entries()) {- candidates = appendTriggeredRankingCandidate(candidates, item, semanticTrack, { id: `${item.id}-at`, anchorId: triggerAnchors[index]! });- }- assert.throws(() => buildRankingSchedule({- header: owner, items: specs(owner, semantic), semantic: semanticTrack, outer, candidates, terminal: tightTerminal,- }), /outside|strictly increasing/u);+ assert.deepEqual(value.entries.map((entry) => entry.itemId), ["preset", "early", "late"]);+ assert.deepEqual(program.items.map((item) => item.id), ["preset", "early", "late"]);+ assert.equal(track.presents.some((item) => item.id.endsWith(":item:preset:reveal")), false);+ assert.equal(track.presents.find((item) => item.id.endsWith(":item:preset:settled"))?.span.startFrame, 10);+ const direct = track.presents.find((item) => item.id.endsWith(":item:early:reveal"))!;+ const drop = track.presents.find((item) => item.id.endsWith(":item:late:reveal"))!;+ assert.ok(direct.elements[0]?.animation);+ const geometry = tierBoardGeometry(tierFrame.widthPx, tierFrame.heightPx, style);+ const stage = tierStageGeometry(canvas.widthPx, canvas.heightPx, style);+ assert.deepEqual({+ rowHeight: geometry.rowHeight, labelWidth: geometry.labelWidth,+ gap: geometry.gap, iconSize: geometry.iconSize,+ }, { rowHeight: 140, labelWidth: 210, gap: 4, iconSize: 132 });+ assert.deepEqual(stage, { centerX: 216, centerY: 576, size: 168 });+ const boardRow = track.presents.find((item) => item.id.endsWith(":board"))?.elements+ .find((item) => item.id === "tier-row-s");+ assert.equal(boardRow?.style.find((item) => item.name === "top")?.value, "0px");+ const relativeCell = tierCell(geometry, 0, 2);+ const cell = { x: tierFrame.xPx + relativeCell.x, y: tierFrame.yPx + relativeCell.y, size: relativeCell.size };+ const duration = 40;+ const phases = resolveTierBoardMotion(duration, style.motion.appearFrames, style.motion.moveFrames);+ assert.deepEqual(phases, { appearEndFrame: 5, moveStartFrame: 32, moveEndFrame: 40 });+ const directMiddle = directTierItemPose(4, cell, 8);+ assert.deepEqual([directMiddle.x, directMiddle.y], [cell.x, cell.y]);+ assert.ok(directMiddle.scale > 1, "direct entrance overshoots in place before settling");+ const stageMiddle = fromHighTierItemPose(4, duration, stage, cell, 8, 8);+ assert.deepEqual([stageMiddle.x, stageMiddle.y], [stage.centerX - cell.size / 2, stage.centerY - cell.size / 2]);+ assert.ok(stageMiddle.scale > stage.size / cell.size, "stage entrance overshoots in place before settling");+ assert.deepEqual(fromHighTierItemPose(20, duration, stage, cell, 5, 8), {+ x: stage.centerX - cell.size / 2, y: stage.centerY - cell.size / 2, scale: stage.size / cell.size,+ opacity: 1, rotateDeg: 0, blurPx: 0,+ shadowY: 16, shadowBlur: 24, shadowOpacity: 0.3,+ });+ const curvedMiddle = fromHighTierItemPose(36, duration, stage, cell, 5, 8);+ assert.notEqual(curvedMiddle.x, stage.centerX - cell.size / 2);+ assert.ok(curvedMiddle.y < ((stage.centerY - cell.size / 2) + cell.y) / 2,+ "drop motion follows an arc above the linear midpoint");+ assert.equal(fromHighTierItemPose(40, duration, stage, cell, 5, 8).x, cell.x);+ assert.equal(drop.elements[0]?.animation?.keyframes.find((item) => item.atFrame === 20)+ ?.style.find((item) => item.name === "transform")?.value,+ "translate(-376px,146px) scale(1.272727) rotate(0deg)");+ assert.deepEqual(buildTierBoardSoundEvents(value, style, specs(owner, semantic)).events+ .map((item) => [item.kind, item.frame]), [["appear", 25], ["appear", 120], ["move", 152]]);+ assert.throws(() => tierSchedule(owner, [semantic[0]!, semantic[2]!], { late: overlapping, early }), /overlap/u);});test("Column consumes explicit disjoint reveal windows without changing them", () => {@@ -315,7 +400,7 @@ test("Column consumes explicit disjoint reveal windows without changing them", (set = appendColumnItem(set, semantic[1]!, image("preset"));set = appendColumnItem(set, semantic[2]!);set = appendColumnItem(set, semantic[3]!, image("overlap"));- const outerWindow = projectColumnSegmentOuterWindow(semanticTrack, rankingSegment);+ const outerWindow = projectColumnSegmentOuterWindow(semanticTrack, rankingSegment, owner.id);assert.deepEqual(outerWindow.span, { startFrame: 10, endFrameExclusive: 230 });const value = columnSchedule(owner, semantic, {"late-rank-one": late,@@ -349,7 +434,7 @@ test("Column rejects overlapping or out-of-bounds reveal windows", () => {assert.throws(() => columnSchedule(owner, values, { one: early, two: overlapping }),/windows one and two overlap/u);- const outerWindow = projectColumnSegmentOuterWindow(semanticTrack, rankingSegment);+ const outerWindow = projectColumnSegmentOuterWindow(semanticTrack, rankingSegment, owner.id);let windows = createColumnWindowSet();const projected = projectSelectionWindow({itemId: "one", semantic: semanticTrack, selection: early,@@ -357,10 +442,11 @@ test("Column rejects overlapping or out-of-bounds reveal windows", () => {});windows = appendColumnWindow(windows, values[0]!, {...projected,+ start: { ...projected.start, frame: outerWindow.span.startFrame - 1 },span: { startFrame: outerWindow.span.startFrame - 1, endFrameExclusive: projected.span.endFrameExclusive },});assert.throws(() => buildColumnSchedule({- header: owner, items: specs(owner, [values[0]!]), outer: outerWindow, windows,+ header: owner, items: specs(owner, [values[0]!]), space, outer: outerWindow, windows,}), /one window is outside/u);});@@ -414,9 +500,9 @@ test("visual and sound event plans share exact phase frames while absent sound stest("each component owns a distinct event law and repeated lowering is canonical", () => {const tierOwner = header("tier-board", "tier-events");- const tierItems = [tierSpec("direct", "s"), tierSpec("stage", "a", "stage")];+ const tierItems = [tierSpec("direct", "s"), tierSpec("drop", "a", "drop")];const tier = decodeTierBoardStyle(recipe("ranking.tier", { rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }] }), font).style;- assert.deepEqual(buildTierBoardSoundEvents(schedule(tierOwner, tierItems), tier, specs(tierOwner, tierItems)).events.map((item) => item.kind),+ assert.deepEqual(buildTierBoardSoundEvents(tierSchedule(tierOwner, tierItems, { direct: early, drop: late }), tier, specs(tierOwner, tierItems)).events.map((item) => item.kind),["appear", "appear", "move"]);const topOwner = header("top-three", "top-events");@@ -448,6 +534,7 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image["frame", plain("frame", spatialTypes.frame)],["outer", plain("outer", narrativeTypes.selection)],["ranking-segment", plain("ranking-segment", narrativeTypes.excerpt)],+ ["tier-reveal", plain("tier-reveal", narrativeTypes.selection)],["column-reveal", plain("column-reveal", narrativeTypes.selection)],["moment-one", plain("moment-one", narrativeTypes.moment)],["moment-two", plain("moment-two", narrativeTypes.moment)],@@ -480,9 +567,9 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image}const cases = [[decodeTierBoardSurface, node("ranking:TierBoard", {- id: "tier", semantic: ref("semantic"), frame: ref("frame"), during: ref("outer"),- terminal: ref("terminal"), style: ref("tier-style"),- }, [node("ranking:TierItem", { id: "tier-one", tier: "s", entry: "stage", icon: ref("icon-1"), at: ref("moment-one") })])],+ id: "tier", semantic: ref("semantic"), canvas: ref("canvas"), frame: ref("frame"), during: "program",+ style: ref("tier-style"),+ }, [node("ranking:TierItem", { id: "tier-one", tier: "s", entry: "drop", icon: ref("icon-1"), during: ref("ranking-segment") })])],[decodeColumnSurface, node("ranking:Column", {id: "column", semantic: ref("semantic"), canvas: ref("canvas"), frame: ref("frame"), during: ref("ranking-segment"),style: ref("column-style"),@@ -502,23 +589,47 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, imageresolveReference: (path) => references.get(path),resolveAsset: async () => { throw new Error("no asset resolution expected"); },});- assert.equal(result.components.length, 1);- assert.equal(result.fragments.length, 1);- const fragment = result.fragments[0]!;+ assert.equal(result.components.filter((component) => component.outputs.visual !== undefined).length, 1);+ const fragment = result.fragments.find((candidate) => candidate.exports.some((output) => output.name === "visual"))!;assert.ok(fragment.exports.some((output) => output.name === "schedule"));assert.ok(fragment.exports.some((output) => output.name === "program"));assert.ok(fragment.exports.some((output) => output.name === "visual"));assert.ok(fragment.inputs.some((input) => input.name === "frame"));+ const temporalSubjects = new Set(result.records.flatMap((record) =>+ record.value.kind === "inline"+ && typeof record.value.value === "object"+ && record.value.value !== null+ && "subjectId" in record.value.value+ ? [String((record.value.value as { readonly subjectId: unknown }).subjectId)]+ : []));+ assert.ok(temporalSubjects.has(String(element.attributes.id)));+ for (const child of element.children) {+ if (child.kind === "element" && child.attributes.id !== undefined && child.attributes.preset !== "true") {+ assert.ok(temporalSubjects.has(String(child.attributes.id)));+ }+ }}+ const programTier = await decodeTierBoardSurface({+ sourceName: "ranking.svml", element: cases[0][1],+ resolveReference: (path) => references.get(path),+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },+ });+ const tierFragment = programTier.fragments.find((candidate) => candidate.exports.some((output) => output.name === "visual"))!;+ assert.equal(tierFragment.inputs.find((input) => input.name === "outer")?.type.name, "TemporalWindow");+ assert.ok(programTier.fragments.some((fragment) => fragment.operations.some((operation) =>+ operation.producer.name === temporalProducers.projectProgramInstant.name)));+ assert.ok(programTier.fragments.some((fragment) => fragment.operations.some((operation) =>+ operation.producer.name === temporalProducers.projectSegmentInstant.name)));const column = await decodeColumnSurface({sourceName: "ranking.svml", element: cases[1][1],resolveReference: (path) => references.get(path),resolveAsset: async () => { throw new Error("no asset resolution expected"); },});- const audio = column.fragments[0]!.exports.find((output) => output.name === "audio");- assert.ok(column.fragments[0]!.operations.some((operation) => operation.producer.name === rankingProducers.materializeTextItem.name));+ const columnFragment = column.fragments.find((candidate) => candidate.exports.some((output) => output.name === "visual"))!;+ const audio = columnFragment.exports.find((output) => output.name === "audio");+ assert.ok(columnFragment.operations.some((operation) => operation.producer.name === rankingProducers.materializeTextItem.name));assert(audio !== undefined);- assert.deepEqual(Object.keys(column.components[0]!.outputs).sort(), ["audio", "program", "schedule", "visual"]);+ assert.deepEqual(Object.keys(column.components.find((component) => component.outputs.visual !== undefined)!.outputs).sort(), ["audio", "program", "schedule", "visual"]);});test("Ranking Surfaces declare their sealed Records and icon Producers consume Blob values", async () => {@@ -550,22 +661,23 @@ test("Ranking author Surfaces fail closed on impossible image and sound combinatconst plain = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({ path, ref: { kind: "record", id: path }, type });const references = new Map<string, SurfaceResolvedReference>([["semantic", plain("semantic", semanticTrackTypes.track)],+ ["canvas", plain("canvas", spatialTypes.canvas)],["frame", plain("frame", spatialTypes.frame)], ["outer", plain("outer", narrativeTypes.selection)],- ["moment", plain("moment", narrativeTypes.moment)], ["terminal", plain("terminal", narrativeTypes.moment)],+ ["icon", plain("icon", mediaTypes.blobArtifact)],["style", plain("style", rankingTypes.tierStyle)], ["style.sound", plain("style.sound", rankingTypes.soundStyle)],["move", plain("move", mediaTypes.synchronized)],]);- const common = { id: "bad", semantic: ref("semantic"), frame: ref("frame"), during: ref("outer"), terminal: ref("terminal"), style: ref("style") };+ const common = { id: "bad", semantic: ref("semantic"), canvas: ref("canvas"), frame: ref("frame"), during: ref("outer"), style: ref("style") };const context = (element: StructuredElement) => ({sourceName: "ranking.svml", element, resolveReference: (path: string) => references.get(path),resolveAsset: async () => { throw new Error("no asset resolution expected"); },});assert.throws(() => decodeTierBoardSurface(context({kind: "element", name: "ranking:TierBoard", attributes: common,- children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", at: ref("moment") }, children: [], range }], range,+ children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", entry: "direct", during: ref("outer") }, children: [], range }], range,})), /icon/u);assert.throws(() => decodeTierBoardSurface(context({kind: "element", name: "ranking:TierBoard", attributes: { ...common, "move-sound": ref("move") },- children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", icon: ref("missing"), at: ref("moment") }, children: [], range }], range,- })), /wrong Type|move-sound/u);+ children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", entry: "direct", icon: ref("icon"), during: ref("outer") }, children: [], range }], range,+ })), /move-sound/u);});diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 476b0d68..a3c59d63 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -1,8 +1,7 @@import type { Part } from "@google/genai";import { access, readdir, stat, writeFile } from "node:fs/promises";-import { dirname, join, resolve } from "node:path";-import { createRequire } from "node:module";-import { loadNodePackageSelection } from "@hypit/package-loader-node";+import { join, resolve } from "node:path";+import { loadNodePackageSelection, locateNodePackage } from "@hypit/package-loader-node";import { markupSurfaceHostFacetAbi } from "@hypit/markup";import type { RegisteredSurface, SurfaceVocabulary } from "@hypit/markup";import { exactModelHostAbi } from "@hypit/model-kit";@@ -762,17 +761,10 @@ function withoutPreview(value: SurfaceVocabulary | undefined): SurfaceVocabularyfunction readmePath(specifier: string, root: string): string | undefined {try {- const require = createRequire(join(root, "__hypit_reference_tools__.cjs"));- const entry = require.resolve(specifier) as string;- let cursor = dirname(entry);- while (cursor !== dirname(cursor)) {- try {- const candidate = join(cursor, "package.json");- const packageJson = require(candidate) as { name?: string };- if (packageJson.name === specifier) return join(cursor, "README.md");- } catch { /* keep walking */ }- cursor = dirname(cursor);- }- return undefined;+ const located = locateNodePackage(specifier, {+ from: join(root, "__hypit_reference_tools__.mjs"),+ workspaceRoots: [root],+ });+ return join(located.root, "README.md");} catch { return undefined; }}diff --git a/packages/render-hyperframes/test/render.test.ts b/packages/render-hyperframes/test/render.test.tsindex 10b4a796..49317442 100644--- a/packages/render-hyperframes/test/render.test.ts+++ b/packages/render-hyperframes/test/render.test.ts@@ -84,7 +84,7 @@ import {} from "@hypit/semantic-track";import { svsManifest } from "@hypit/svs";-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 2,frameRate: { numerator: 30, denominator: 1 },});diff --git a/packages/screen-overlay/package.json b/packages/screen-overlay/package.jsonindex 295e45c5..efb9570f 100644--- a/packages/screen-overlay/package.json+++ b/packages/screen-overlay/package.json@@ -16,6 +16,7 @@"@hypit/semantic-track": "workspace:*","@hypit/spatial": "workspace:*","@hypit/temporal": "workspace:*",+ "@hypit/temporal-markup": "workspace:*","@hypit/markup": "workspace:*"},"devDependencies": {diff --git a/packages/screen-overlay/src/component.ts b/packages/screen-overlay/src/component.tsindex 9fb838ea..3e44cb7b 100644--- a/packages/screen-overlay/src/component.ts+++ b/packages/screen-overlay/src/component.ts@@ -1,8 +1,7 @@import type { ComponentPackage } from "@hypit/component-kit";import { canonicalize } from "@hypit/protocol";import type { StoredValue } from "@hypit/protocol";-import type { SemanticTrack } from "@hypit/semantic-track";-import { projectSemanticProgramSpace } from "@hypit/semantic-track";+import type { ProgramSpace } from "@hypit/program-space";import type { CanvasSpace } from "@hypit/spatial";import { screenOverlayProducers, screenOverlayTypes } from "./manifest.js";import { appendProjectedScreenOverlay, assertScreenOverlayProgram, createScreenOverlaySet, finalizeScreenOverlay, renderScreenOverlay } from "./program.js";@@ -13,9 +12,9 @@ const output = (value: unknown) => ({ kind: "inline" as const, value: canonicaliexport const screenOverlayComponent = {producers: [{ producer: screenOverlayProducers.createSet, handler: () => ({ outputs: { set: output(createScreenOverlaySet()) }, needs: {} }) },- { producer: screenOverlayProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: output(appendProjectedScreenOverlay(inline<ScreenOverlaySet>(inputs.set?.value, "ScreenOverlaySet"), inline<ScreenOverlayHeader>(inputs.header?.value, "ScreenOverlayHeader"), inline<ScreenOverlayItemSpec>(inputs.spec?.value, "ScreenOverlayItemSpec"), inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"))) }, needs: {} }) },+ { producer: screenOverlayProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: output(appendProjectedScreenOverlay(inline<ScreenOverlaySet>(inputs.set?.value, "ScreenOverlaySet"), inline<ScreenOverlayHeader>(inputs.header?.value, "ScreenOverlayHeader"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<ScreenOverlayItemSpec>(inputs.spec?.value, "ScreenOverlayItemSpec"), inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"))) }, needs: {} }) },{ producer: screenOverlayProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeScreenOverlay(inline<ScreenOverlaySet>(inputs.set?.value, "ScreenOverlaySet"), inline<ScreenOverlayHeader>(inputs.header?.value, "ScreenOverlayHeader"))) }, needs: {} }) },- { producer: screenOverlayProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderScreenOverlay(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")), inline<ScreenOverlayProgram>(inputs.program?.value, "ScreenOverlayProgram"))) }, needs: {} }) },+ { producer: screenOverlayProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderScreenOverlay(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<ScreenOverlayProgram>(inputs.program?.value, "ScreenOverlayProgram"))) }, needs: {} }) },],validators: [{ type: screenOverlayTypes.program, handler: ({ value }) => assertScreenOverlayProgram(inline<ScreenOverlayProgram>(value, "ScreenOverlayProgram")) }],} satisfies ComponentPackage;diff --git a/packages/screen-overlay/src/fragment.ts b/packages/screen-overlay/src/fragment.tsindex 9301dec8..fd9ac05c 100644--- a/packages/screen-overlay/src/fragment.ts+++ b/packages/screen-overlay/src/fragment.ts@@ -1,45 +1,34 @@import { compositionTypes } from "@hypit/composition";import { sealGraphFragment } from "@hypit/elaborator";import type { FragmentOperation } from "@hypit/elaborator";-import { narrativeTypes } from "@hypit/narrative";-import { semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";-import { temporalProducers, temporalTypes } from "@hypit/temporal";+import { temporalTypes } from "@hypit/temporal";import { screenOverlayProducers, screenOverlayTypes } from "./manifest.js";-export type ScreenOverlayFragmentItem =- | { readonly kind: "program"; readonly specName: string; readonly windowSpecName: string }- | { readonly kind: "selection"; readonly specName: string; readonly sourceName: string; readonly windowSpecName: string }- | { readonly kind: "moment"; readonly specName: string; readonly sourceName: string; readonly windowSpecName: string };+export type ScreenOverlayFragmentItem = { readonly specName: string; readonly windowName: string };const input = (name: string) => ({ kind: "fragment-input" as const, name });const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });export function createScreenOverlayFragment(items: readonly ScreenOverlayFragmentItem[]) {if (items.length === 0) throw new Error("Screen Overlay Fragment requires at least one Item.");- const types = new Map<string, typeof screenOverlayTypes.itemSpec | typeof semanticTrackTypes.track | typeof narrativeTypes.selection | typeof narrativeTypes.moment | typeof temporalTypes.windowSpec>();- const operations: FragmentOperation[] = [{ id: "overlay:set:empty", producer: screenOverlayProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } }];+ const types = new Map<string, typeof screenOverlayTypes.itemSpec | typeof temporalTypes.window>();+ const operations: FragmentOperation[] = [+ { id: "overlay:space", producer: semanticTrackProducers.projectProgramSpace, inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },+ { id: "overlay:set:empty", producer: screenOverlayProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },+ ];let current = "overlay:set:empty";items.forEach((item, index) => {types.set(item.specName, screenOverlayTypes.itemSpec);- types.set(item.windowSpecName, temporalTypes.windowSpec);- if (item.kind !== "program") {- types.set(item.sourceName, item.kind === "selection" ? narrativeTypes.selection : narrativeTypes.moment);- }+ types.set(item.windowName, temporalTypes.window);const id = `overlay:set:append:${String(index + 1).padStart(4, "0")}`;- const windowId = `overlay:window:${String(index + 1).padStart(4, "0")}`;- const windowProducer = item.kind === "program" ? temporalProducers.projectProgram- : item.kind === "selection" ? temporalProducers.projectSelection : temporalProducers.projectMoment;- operations.push({ id: windowId, producer: windowProducer, inputs: {- semantic: input("semantic"), spec: input(item.windowSpecName),- ...(item.kind === "program" ? {} : { [item.kind]: input(item.sourceName) }),- }, result: { kind: "output", name: "window" } });operations.push({ id, producer: screenOverlayProducers.appendItem,- inputs: { set: operation(current), header: input("header"), semantic: input("semantic"), spec: input(item.specName),- window: operation(windowId) }, result: { kind: "output", name: "set" } });+ inputs: { set: operation(current), header: input("header"), spec: input(item.specName),+ space: operation("overlay:space"), window: input(item.windowName) }, result: { kind: "output", name: "set" } });current = id;});operations.push({ id: "overlay:program", producer: screenOverlayProducers.finalize, inputs: { set: operation(current), header: input("header") }, result: { kind: "output", name: "program" } },- { id: "overlay:track", producer: screenOverlayProducers.render, inputs: { canvas: input("canvas"), semantic: input("semantic"), program: operation("overlay:program") }, result: { kind: "output", name: "track" } },+ { id: "overlay:track", producer: screenOverlayProducers.render, inputs: { canvas: input("canvas"), space: operation("overlay:space"), program: operation("overlay:program") }, result: { kind: "output", name: "track" } },);return sealGraphFragment({ inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "header", type: screenOverlayTypes.header },@@ -49,4 +38,4 @@ export function createScreenOverlayFragment(items: readonly ScreenOverlayFragmen{ name: "track", type: compositionTypes.visualTrack, root: operation("overlay:track") },] });}-export const programScreenOverlayFragment = createScreenOverlayFragment([{ kind: "program", specName: "spec", windowSpecName: "window-spec" }]);+export const programScreenOverlayFragment = createScreenOverlayFragment([{ specName: "spec", windowName: "window" }]);diff --git a/packages/screen-overlay/src/manifest.ts b/packages/screen-overlay/src/manifest.tsindex c284d89e..9307b704 100644--- a/packages/screen-overlay/src/manifest.ts+++ b/packages/screen-overlay/src/manifest.ts@@ -1,11 +1,13 @@import { readFile } from "node:fs/promises";import { compositionDependency, compositionTypes } from "@hypit/composition";-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";+import { narrativeDependency } from "@hypit/narrative";+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";import { spatialDependency, spatialTypes } from "@hypit/spatial";import { temporalDependency, temporalTypes } from "@hypit/temporal";+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";const previewImage = (file: string) => ({mediaType: "image/png",@@ -62,31 +64,18 @@ export const screenOverlayHeaderSchema: ValueSchema = object({ id: { schema: strexport const screenOverlayItemSpecSchema: ValueSchema = itemSpec;export const screenOverlaySetSchema: ValueSchema = object({ items: { schema: { kind: "array", items: item } } });export const screenOverlayProgramSchema: ValueSchema = object({ id: { schema: string }, items: { schema: { kind: "array", minItems: 1, items: item } } });-const appendInputs = [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }, { name: "semantic", type: semanticTrackTypes.track }, { name: "spec", type: screenOverlayTypes.itemSpec }, { name: "window", type: temporalTypes.window }] as const;+const appendInputs = [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }, { name: "space", type: programSpaceTypes.programSpace }, { name: "spec", type: screenOverlayTypes.itemSpec }, { name: "window", type: temporalTypes.window }] as const;const itemAttributes = [{ name: "id", kind: "identifier", required: false,summary: "Names this item; the overlay numbers the item after its kind when it is omitted." },{ name: "z", kind: "literal", required: true,summary: "Sets the stacking order this item is painted in against its siblings." },- { name: "during", kind: "expression", required: false, values: ["program"], accepts: [narrativeTypes.selection],- summary: "Holds the item across the whole programme, or across the Selection it names." },- { name: "at", kind: "reference", required: false, accepts: [narrativeTypes.moment],- summary: "Starts the item at the cue of the Moment it names." },- { name: "for", kind: "literal", required: false,- summary: "Sets the exact duration the item holds past the Moment cue." },- { name: "start", kind: "literal", required: false,- summary: "Sets the point the item begins at, as a named edge with an optional offset or as an absolute duration." },- { name: "end", kind: "literal", required: false,- summary: "Sets the point the item ends at, as a named edge with an optional offset or as an absolute duration." },- { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection],- summary: "Binds explicit `start` and `end` timing to a Selection." },- { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment],- summary: "Binds explicit `start` and `end` timing to a Moment." },+ ...temporalWindowAttributeVocabulary,] as const;export const screenOverlayMarkupSurfaces = [- { name: "track", tag: "Track", mode: "structured", outputs: [screenOverlayTypes.header, screenOverlayTypes.itemSpec, temporalTypes.windowSpec, screenOverlayTypes.program, compositionTypes.visualTrack],+ { name: "track", tag: "Track", mode: "structured", outputs: [screenOverlayTypes.header, screenOverlayTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, screenOverlayTypes.program, compositionTypes.visualTrack],vocabulary: {summary: "Paints self-contained screen treatments across the whole Canvas and publishes the overlay Program and the VisualTrack it renders to.",appearance: "Treatments laid edge to edge over the whole Canvas, never a panel, a card or text, each item covering the frame for its own span only and painted over its siblings in `z` order. Flash pulses one color up to full and back down across the frame, ColorWash holds that same flat color still, and Vignette leaves the middle clear and darkens outwards to one color in an ellipse around a chosen centre. Four items cross the frame as travelling geometry: ScanLines rule it with evenly spaced white stripes at an angle, DirectionalMatte sweeps a feathered wall of color over it, WhipVeil slides a single soft-edged white band left, right, up or down, and LightLeak drags a heavily blurred angled gradient of colors from one side to the other. The remaining four scatter many small shapes from a seed: GlitchVeil throws wide colored horizontal bars that jump sideways, Grain sprinkles fine specks that crawl diagonally, Bokeh floats blurred round discs of one color that drift apart, and TVStatic fills the frame with grey noise cells beneath fine horizontal scan lines.",@@ -299,7 +288,7 @@ export const screenOverlayMarkupSurfaces = [export const screenOverlayManifest: ModuleManifest = {format: "hypit.module@1", name: screenOverlayModuleRef.name, version: screenOverlayModuleRef.version,- dependencies: [narrativeDependency, semanticTrackDependency, spatialDependency, temporalDependency, compositionDependency],+ dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, compositionDependency],types: [{ name: screenOverlayTypes.header.name },{ name: screenOverlayTypes.itemSpec.name },@@ -310,7 +299,7 @@ export const screenOverlayManifest: ModuleManifest = {{ name: screenOverlayProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: screenOverlayTypes.set }], needs: [] },{ name: screenOverlayProducers.appendItem.name, inputs: [...appendInputs], outputs: [{ name: "set", type: screenOverlayTypes.set }], needs: [] },{ name: screenOverlayProducers.finalize.name, inputs: [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }], outputs: [{ name: "program", type: screenOverlayTypes.program }], needs: [] },- { name: screenOverlayProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: screenOverlayTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },+ { name: screenOverlayProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: screenOverlayTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },],};export const screenOverlayDependency = { module: screenOverlayModuleRef } as const;diff --git a/packages/screen-overlay/src/program.ts b/packages/screen-overlay/src/program.tsindex 9a52599a..46721b52 100644--- a/packages/screen-overlay/src/program.ts+++ b/packages/screen-overlay/src/program.ts@@ -5,6 +5,7 @@ import type { ProgramSpace } from "@hypit/program-space";import { canonicalize } from "@hypit/protocol";import { assertCanvasSpace } from "@hypit/spatial";import type { CanvasSpace } from "@hypit/spatial";+import { assertTemporalWindowFor } from "@hypit/temporal";import type { ProjectedWindow } from "@hypit/temporal";import type {@@ -106,10 +107,11 @@ export function assertScreenOverlaySet(value: ScreenOverlaySet): void {}function realized(- set: ScreenOverlaySet, header: ScreenOverlayHeader, spec: ScreenOverlayItemSpec,+ set: ScreenOverlaySet, header: ScreenOverlayHeader, space: ProgramSpace, spec: ScreenOverlayItemSpec,window: ProjectedWindow,): ScreenOverlaySet {assertScreenOverlaySet(set); assertScreenOverlayHeader(header); assertScreenOverlayItemSpec(spec);+ assertTemporalWindowFor(window, { subjectId: spec.id, space });const addition = {id: window.id,subjectId: spec.id,@@ -126,10 +128,11 @@ function realized(export function appendProjectedScreenOverlay(set: ScreenOverlaySet,header: ScreenOverlayHeader,+ space: ProgramSpace,spec: ScreenOverlayItemSpec,window: ProjectedWindow,): ScreenOverlaySet {- return realized(set, header, spec, window);+ return realized(set, header, space, spec, window);}export function sealScreenOverlayProgram(value: ScreenOverlayProgram): ScreenOverlayProgram {const normalized = { id: value.id,@@ -307,7 +310,7 @@ function overlayElements(content: ScreenOverlayComponent, canvas: CanvasSpace, dexport function renderScreenOverlay(canvas: CanvasSpace, space: ProgramSpace, program: ScreenOverlayProgram): VisualTrack {assertCanvasSpace(canvas); assertProgramSpaceIdentity(space); assertScreenOverlayProgram(program);const track = sealVisualTrack({- visualIr: "hypit.visual-ir@1", id: program.id,+ programSpaceId: space.id, visualIr: "hypit.visual-ir@1", id: program.id,presents: program.items.map((item) => ({id: item.id, subjectId: item.subjectId, span: { ...item.span }, stacking: { ...item.stacking },elements: overlayElements(item.content, canvas, item.span.endFrameExclusive - item.span.startFrame),diff --git a/packages/screen-overlay/src/surface.ts b/packages/screen-overlay/src/surface.tsindex 81f7fcf1..457488c1 100644--- a/packages/screen-overlay/src/surface.ts+++ b/packages/screen-overlay/src/surface.ts@@ -1,15 +1,13 @@-import { narrativeTypes } from "@hypit/narrative";import { semanticTrackTypes } from "@hypit/semantic-track";import { spatialTypes } from "@hypit/spatial";-import type { StructuredElement, StructuredSurfaceHandler, SurfaceRecordDraft, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";-import type { TemporalDuration, TemporalPointExpression, TemporalWindowProjection } from "@hypit/temporal";-import { temporalTypes } from "@hypit/temporal";+import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";+import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";import { createScreenOverlayFragment } from "./fragment.js";import { screenOverlayTypes } from "./manifest.js";import { sealScreenOverlayHeader, sealScreenOverlayItemSpec } from "./program.js";import type { ScreenOverlayComponent } from "./types.js";-const TIMING = ["during", "at", "for", "start", "end", "selection", "moment"] as const;+const TIMING = temporalWindowAttributeNames;function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;}@@ -29,28 +27,6 @@ function ref(raw: MarkupAttributeValue | undefined, label: string, expected: Surif (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);const value = resolve(raw.path); if (value === undefined || !sameType(value.type, expected)) throw new Error(`${label} has the wrong Type.`); return value;}-function gcd(left: number, right: number): number { let a = Math.abs(left); let b = Math.abs(right); while (b !== 0) [a, b] = [b, a % b]; return a; }-function duration(value: string, label: string): TemporalDuration {- const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());- if (!match) throw new Error(`${label} must be an exact duration.`);- const whole = Number(match[1]); const fraction = match[2] ?? ""; const unit = match[3];- if (unit === "f" || unit === "ms") {- if (fraction) throw new Error(`${label} ${unit} duration must be integral.`);- return { unit: unit === "f" ? "frames" : "milliseconds", value: whole };- }- const scale = 10 ** fraction.length; const numerator = whole * scale + (fraction ? Number(fraction) : 0); const divisor = gcd(numerator, scale);- return { unit: "seconds", numerator: numerator / divisor, denominator: scale / divisor };-}-function negate(value: TemporalDuration): TemporalDuration { return value.unit === "seconds" ? { ...value, numerator: -value.numerator } : { ...value, value: -value.value }; }-function point(value: string, label: string): TemporalPointExpression {- const trimmed = value.trim(); const refs = ["program.start", "program.end", "selection.start", "selection.end", "moment.cue"] as const;- for (const reference of refs) {- if (trimmed === reference) return { ref: reference };- const match = new RegExp(`^${reference.replace(".", "\\.")}\\s*([+-])\\s*(.+)$`, "u").exec(trimmed);- if (match) { const offset = duration(match[2]!, `${label} offset`); return { ref: reference, offset: match[1] === "-" ? negate(offset) : offset }; }- }- return { ref: "absolute", at: duration(trimmed, label) };-}function numeric(element: StructuredElement, name: string, fallback?: number): number {const raw = optionalText(element, name); if (raw === undefined && fallback !== undefined) return fallback;const value = Number(raw); if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be numeric.`); return value;@@ -62,31 +38,6 @@ function colors(element: StructuredElement, name: string): string[] {const values = text(element, name).split(",").map((value) => value.trim()).filter(Boolean);if (values.length === 0) throw new Error(`${element.name}.${name} requires colors.`); return values;}-type Binding = { readonly kind: "program" | "selection" | "moment"; readonly projection: TemporalWindowProjection; readonly source?: SurfaceResolvedReference };-function binding(element: StructuredElement, resolve: (path: string) => SurfaceResolvedReference | undefined): Binding {- const during = element.attributes.during; const at = element.attributes.at;- const start = optionalText(element, "start"); const end = optionalText(element, "end");- const forms = Number(during !== undefined) + Number(at !== undefined) + Number(start !== undefined || end !== undefined);- if (forms !== 1) throw new Error(`${element.name} requires exactly one temporal form.`);- if (during !== undefined) {- if (typeof during === "string") {- if (during.trim() !== "program") throw new Error(`${element.name}.during text must be program.`);- return { kind: "program", projection: { start: { ref: "program.start" }, end: { ref: "program.end" } } };- }- return { kind: "selection", source: ref(during, `${element.name}.during`, narrativeTypes.selection, resolve),- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } } };- }- if (at !== undefined) return { kind: "moment", source: ref(at, `${element.name}.at`, narrativeTypes.moment, resolve),- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: duration(text(element, "for"), `${element.name}.for`) } } };- if (start === undefined || end === undefined) throw new Error(`${element.name} explicit timing requires start and end.`);- const selection = element.attributes.selection; const moment = element.attributes.moment;- if (selection !== undefined && moment !== undefined) throw new Error(`${element.name} cannot bind Selection and Moment together.`);- const projection = { start: point(start, `${element.name}.start`), end: point(end, `${element.name}.end`) };- if (selection !== undefined) return { kind: "selection", source: ref(selection, `${element.name}.selection`, narrativeTypes.selection, resolve), projection };- if (moment !== undefined) return { kind: "moment", source: ref(moment, `${element.name}.moment`, narrativeTypes.moment, resolve), projection };- return { kind: "program", projection };-}-function content(element: StructuredElement): { readonly value: ScreenOverlayComponent; readonly attributes: readonly string[] } {const name = element.name.split(":").at(-1);switch (name) {@@ -111,6 +62,8 @@ export const decodeScreenOverlaySurface: StructuredSurfaceHandler = ({ element,const semantic = ref(element.attributes.semantic, `${element.name}.semantic`, semanticTrackTypes.track, resolveReference);const headerId = `${id}.header`; const records: SurfaceRecordDraft[] = [{ id: headerId, type: screenOverlayTypes.header,value: { kind: "inline", value: sealScreenOverlayHeader({ id }) }, range: element.range }];+ const temporalComponents: SurfaceComponentDraft[] = [];+ const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];const fragmentItems: Parameters<typeof createScreenOverlayFragment>[0][number][] = [];const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, semantic: semantic.ref };let index = 0;@@ -118,24 +71,19 @@ export const decodeScreenOverlaySurface: StructuredSurfaceHandler = ({ element,if (child.kind === "text") { if (child.value.trim()) throw new Error(`${element.name} accepts only component children.`); continue; }if (child.children.some((node) => node.kind === "element" || node.value.trim())) throw new Error(`${child.name} must be empty.`);index += 1; const suffix = String(index).padStart(4, "0"); const decoded = content(child);- allowed(child, ["id", "z", ...TIMING, ...decoded.attributes]); const temporal = binding(child, resolveReference);+ allowed(child, ["id", "z", ...TIMING, ...decoded.attributes]);const itemSpec = sealScreenOverlayItemSpec({id: optionalText(child, "id") ?? `${id}.${decoded.value.kind}.${suffix}`, content: decoded.value,stackingOrder: integer(child, "z") });+ const temporal = createTemporalWindowProjection({ id: itemSpec.id, element: child, semantic, resolveReference });+ records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);const specId = `${id}.item.${suffix}.spec`; const specName = `item-${suffix}-spec`;- const windowSpecId = `${id}.item.${suffix}.window`; const windowSpecName = `item-${suffix}-window-spec`;- records.push({ id: windowSpecId, type: temporalTypes.windowSpec,- value: { kind: "inline", value: { id: itemSpec.id, projection: temporal.projection } }, range: child.range });records.push({ id: specId, type: screenOverlayTypes.itemSpec, value: { kind: "inline", value: itemSpec }, range: child.range });- inputs[specName] = { kind: "record", id: specId }; inputs[windowSpecName] = { kind: "record", id: windowSpecId };- if (temporal.kind === "program") fragmentItems.push({ kind: "program", specName, windowSpecName });- else {- const sourceName = `item-${suffix}-${temporal.kind}`;- inputs[sourceName] = temporal.source!.ref;- fragmentItems.push({ kind: temporal.kind, specName, sourceName, windowSpecName });- }+ const windowName = `item-${suffix}-window`;+ inputs[specName] = { kind: "record", id: specId }; inputs[windowName] = temporal.ref;+ fragmentItems.push({ specName, windowName });}if (fragmentItems.length === 0) throw new Error(`${element.name} requires at least one component.`);const fragment = createScreenOverlayFragment(fragmentItems);- return { records, components: [{ id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }], fragments: [fragment] };+ return { records, components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }], fragments: [...temporalFragments, fragment], exports: [`${id}.program`, `${id}.track`] };};diff --git a/packages/screen-overlay/test/screen-overlay.test.ts b/packages/screen-overlay/test/screen-overlay.test.tsindex a7cee8ea..afaf5160 100644--- a/packages/screen-overlay/test/screen-overlay.test.ts+++ b/packages/screen-overlay/test/screen-overlay.test.ts@@ -2,6 +2,7 @@ import assert from "node:assert/strict";import test from "node:test";import { fixtureDigest } from "../../../test/fixture-digest.js";import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";+import { projectProgramWindow } from "../../../test/temporal-fixture.js";import { artifactManifest } from "@hypit/artifact";import { registerTypeValidatorFacets } from "@hypit/component-kit";@@ -28,11 +29,11 @@ import {sealScreenOverlayItemSpec,} from "@hypit/screen-overlay";import type { ScreenOverlayComponent } from "@hypit/screen-overlay";-import { semanticTrackDependency, semanticTrackManifest, semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackDependency, semanticTrackManifest, semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { speechEvidenceManifest } from "@hypit/speech-evidence";import { speechManifest } from "@hypit/speech";import { sealCanvasSpace, spatialComponent, spatialDependency, spatialManifest, spatialTypes } from "@hypit/spatial";-import { projectProgramWindow, temporalManifest, temporalProducers } from "@hypit/temporal";+import { temporalManifest, temporalProducers } from "@hypit/temporal";import { MarkupSurfaceRegistry, createMarkupAuthorFrontend } from "@hypit/markup";import { createRecordAdmitter, TypeValidatorRegistry } from "@hypit/validation";import { visualIrManifest } from "@hypit/visual-ir";@@ -41,7 +42,7 @@ const canvas = sealCanvasSpace({widthPx: 1080, heightPx: 1920,origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",});-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 2, frameRate: { numerator: 30, denominator: 1 },});const header = sealScreenOverlayHeader({ id: "screen" });@@ -71,7 +72,7 @@ function trackFor(content: ScreenOverlayComponent, stackingOrder = 50) {projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },});return renderScreenOverlay(canvas, space, finalizeScreenOverlay(- appendProjectedScreenOverlay(createScreenOverlaySet(), header, spec, window), header,+ appendProjectedScreenOverlay(createScreenOverlaySet(), header, space, spec, window), header,));}@@ -106,7 +107,7 @@ test("explicit seeds control stochastic component identity", () => {test("overlay Tracks interleave with peer Tracks only through absolute stacking", () => {const below = trackFor(components[1]!, 20);const above = { ...trackFor(components[0]!, 80), id: "screen-above" };- const middle = sealVisualTrack({+ const middle = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1", id: "middle",presents: [{ id: "middle", span: { startFrame: 0, endFrameExclusive: 60 }, stacking: { order: 50, tieBreak: "middle" },elements: [{ id: "root", order: 0, kind: "box", style: [{ name: "background-color", value: "#112233" }] }] }],@@ -122,8 +123,8 @@ test("overlay Tracks interleave with peer Tracks only through absolute stacking"});test("the package has no lower-composite, sibling Track, backdrop-filter or hidden audio port", () => {- const fragment = createScreenOverlayFragment([{ kind: "program", specName: "spec", windowSpecName: "window-spec" }]);- assert.deepEqual(fragment.inputs.map((input) => input.name), ["canvas", "header", "semantic", "spec", "window-spec"]);+ const fragment = createScreenOverlayFragment([{ specName: "spec", windowName: "window" }]);+ assert.deepEqual(fragment.inputs.map((input) => input.name), ["canvas", "header", "semantic", "spec", "window"]);assert.equal(fragment.exports.some((output) => output.type.name === "AudioTrack"), false);assert.throws(() => sealScreenOverlayItemSpec({id: "blur",@@ -212,7 +213,10 @@ test("the self-described Screen Surface parses into a finite peer-Track graph",screenOverlayProducers.createSet.name,screenOverlayProducers.appendItem.name,screenOverlayProducers.finalize.name,- temporalProducers.projectProgram.name,+ temporalProducers.projectProgramInstant.name,+ temporalProducers.projectProgramInstant.name,+ temporalProducers.composeWindow.name,+ semanticTrackProducers.projectProgramSpace.name,screenOverlayProducers.render.name,].sort());});diff --git a/packages/script/README.md b/packages/script/README.mdindex 13522728..d41f55d3 100644--- a/packages/script/README.md+++ b/packages/script/README.md@@ -2,7 +2,8 @@Official raw Script Surface for the Markup Frontend. It parses prose-first named Segment blocks,newline-independent Role Cues, Dual Text, Selection and Moment syntax, and lowers them to a-canonical authored Narrative value with exactly `2M + 2N` semantic anchor identities.+canonical authored Narrative value with exactly `2M + 2N + 2` semantic anchor identities: both+ends of every Token and Segment, plus the Script Program's own start and end.The package is an ordinary statically declared Surface module. Core does not import it and does notknow that Script, Segment or Narrative exist.diff --git a/packages/script/src/edit.ts b/packages/script/src/edit.tsindex dffeac40..563d0a9d 100644--- a/packages/script/src/edit.ts+++ b/packages/script/src/edit.ts@@ -7,7 +7,7 @@ import type { Affinity, ParsedNarrative, SemanticAnchor } from "./types.js";export type ScriptAnchorEditSite = {readonly anchorId: string;readonly kind: SemanticAnchor["kind"];- readonly segmentId: string;+ readonly segmentId?: string;readonly offset: number;readonly affinity: Affinity;readonly placement: "before" | "after";@@ -26,17 +26,30 @@ export type ScriptMomentAdjustment = {type Edit = { readonly range: SourceRange; readonly replacement: string };-/** Script owns the exact source inverse of every one of its 2M + 2N anchors. */+/** Script owns the exact source inverse of every one of its 2M + 2N + 2 anchors. */export function scriptAnchorEditSites(parsed: ParsedNarrative): readonly ScriptAnchorEditSite[] {const segments = new Map(parsed.segments.map((segment) => [segment.id, segment] as const));const tokens = new Map(parsed.tokens.map((token) => [token.id, token] as const));return parsed.semanticIndex.anchors.map((anchor): ScriptAnchorEditSite => {- const segment = segments.get(anchor.segmentId);- if (segment === undefined) throw new Error(`Semantic Anchor ${anchor.id} names unknown Segment ${anchor.segmentId}.`);+ if (anchor.kind === "program-start") {+ return {+ anchorId: anchor.id, kind: anchor.kind, offset: parsed.sourceRange.start,+ affinity: "left", placement: "before",+ };+ }+ if (anchor.kind === "program-end") {+ return {+ anchorId: anchor.id, kind: anchor.kind, offset: parsed.sourceRange.end,+ affinity: "right", placement: "after",+ };+ }+ const segmentId = anchor.segmentId;+ const segment = segments.get(segmentId);+ if (segment === undefined) throw new Error(`Semantic Anchor ${anchor.id} names unknown Segment ${segmentId}.`);if (anchor.kind === "segment-start") {const first = parsed.tokens[segment.tokenStart];return {- anchorId: anchor.id, kind: anchor.kind, segmentId: anchor.segmentId,+ anchorId: anchor.id, kind: anchor.kind, segmentId,offset: first?.range.start ?? segment.contentRange.start,affinity: "left", placement: "before",};@@ -44,7 +57,7 @@ export function scriptAnchorEditSites(parsed: ParsedNarrative): readonly ScriptAif (anchor.kind === "segment-end") {const last = parsed.tokens[segment.tokenEndExclusive - 1];return {- anchorId: anchor.id, kind: anchor.kind, segmentId: anchor.segmentId,+ anchorId: anchor.id, kind: anchor.kind, segmentId,offset: last?.range.end ?? segment.contentRange.end,affinity: "right", placement: "after",};@@ -52,10 +65,10 @@ export function scriptAnchorEditSites(parsed: ParsedNarrative): readonly ScriptAconst token = anchor.tokenId === undefined ? undefined : tokens.get(anchor.tokenId);if (token === undefined) throw new Error(`Semantic Anchor ${anchor.id} names no Script Token.`);return anchor.kind === "token-start" ? {- anchorId: anchor.id, kind: anchor.kind, segmentId: anchor.segmentId,+ anchorId: anchor.id, kind: anchor.kind, segmentId,offset: token.range.start, affinity: "right", placement: "before",} : {- anchorId: anchor.id, kind: anchor.kind, segmentId: anchor.segmentId,+ anchorId: anchor.id, kind: anchor.kind, segmentId,offset: token.range.end, affinity: "left", placement: "after",};});@@ -123,8 +136,8 @@ export function adjustScriptSelection(input: {if (rewritten?.startAnchorId !== start.anchorId || rewritten.endAnchorId !== end.anchorId) {throw new Error(`Script refused to move Selection ${selection.id} to the requested Anchors.`);}- const before = narrativeValue(input.parsed) as unknown as { readonly selections: readonly { readonly id: string }[] };- const after = narrativeValue(reparsed) as unknown as { readonly selections: readonly { readonly id: string }[] };+ const before = narrativeValue(input.parsed, "comparison") as unknown as { readonly selections: readonly { readonly id: string }[] };+ const after = narrativeValue(reparsed, "comparison") as unknown as { readonly selections: readonly { readonly id: string }[] };if (before.selections.length !== after.selections.length|| before.selections.some((item) => !after.selections.some((candidate) => candidate.id === item.id))) {throw new Error("Script Selection adjustment changed authored identities.");diff --git a/packages/script/src/format.ts b/packages/script/src/format.tsindex f77366b6..41a420f0 100644--- a/packages/script/src/format.ts+++ b/packages/script/src/format.ts@@ -72,7 +72,7 @@ export function formatScript(sourceName: string, source: string): string {while (output.at(-1) === "") output.pop();const formatted = `${output.join("\n")}\n`;const reparsed = parseScript(sourceName, formatted);- if (canonicalStringify(narrativeValue(parsed)) !== canonicalStringify(narrativeValue(reparsed))) {+ if (canonicalStringify(narrativeValue(parsed, "comparison")) !== canonicalStringify(narrativeValue(reparsed, "comparison"))) {throw new ScriptSyntaxError("SCRIPT_FORMAT_SEMANTICS","Formatter refused to change Script semantics.",diff --git a/packages/script/src/narrative.ts b/packages/script/src/narrative.tsindex b4ecebf0..dca3fa93 100644--- a/packages/script/src/narrative.ts+++ b/packages/script/src/narrative.ts@@ -15,7 +15,7 @@ function turnForRegion(parsed: ParsedNarrative, region: ParsedCaptionRegion): Pareturn turn;}-function projectCaption(parsed: ParsedNarrative, id: string): CaptionDocument {+function projectCaption(parsed: ParsedNarrative, id: string, narrativeId: string): CaptionDocument {const units: CaptionAlignmentUnit[] = [];const words: CaptionDisplayWord[] = [];for (const region of parsed.captionProjection.regions) {@@ -89,15 +89,15 @@ function projectCaption(parsed: ParsedNarrative, id: string): CaptionDocument {}return { afterUnitId: previous.id };});- return { id, units, words, cueBreaks };+ return { narrativeId, id, units, words, cueBreaks };}-export function captionDocument(parsed: ParsedNarrative, id: string): CaptionDocument {- return projectCaption(parsed, id);+export function captionDocument(parsed: ParsedNarrative, id: string, narrativeId: string): CaptionDocument {+ return projectCaption(parsed, id, narrativeId);}-export function captionDocumentValue(parsed: ParsedNarrative, id: string): CanonicalValue {- return canonicalize(captionDocument(parsed, id));+export function captionDocumentValue(parsed: ParsedNarrative, id: string, narrativeId: string): CanonicalValue {+ return canonicalize(captionDocument(parsed, id, narrativeId));}function segmentSerializations(segment: ParsedNarrative["segments"][number]): {@@ -131,9 +131,11 @@ function segmentSerializations(segment: ParsedNarrative["segments"][number]): {export function narrativeSegmentExcerptValue(parsed: ParsedNarrative,segment: ParsedNarrative["segments"][number],+ narrativeId: string,): CanonicalValue {return canonicalize({kind: "segment",+ narrativeId,id: segment.id,tokenStart: segment.tokenStart,tokenEndExclusive: segment.tokenEndExclusive,@@ -148,20 +150,22 @@ export function narrativeSpeechTextValue(segment: ParsedNarrative["segments"][nureturn sealText(segmentSerializations(segment).speech) as unknown as CanonicalValue;}-export function narrativeSelectionValue(selection: ParsedNarrative["selections"][number]): CanonicalValue {+export function narrativeSelectionValue(selection: ParsedNarrative["selections"][number], narrativeId: string): CanonicalValue {return canonicalize({+ narrativeId,id: selection.id,startAnchorId: selection.open.boundary.anchorId,endAnchorId: selection.close.boundary.anchorId,});}-export function narrativeMomentValue(moment: ParsedNarrative["moments"][number]): CanonicalValue {- return canonicalize({ id: moment.id, anchorId: moment.boundary.anchorId });+export function narrativeMomentValue(moment: ParsedNarrative["moments"][number], narrativeId: string): CanonicalValue {+ return canonicalize({ narrativeId, id: moment.id, anchorId: moment.boundary.anchorId });}-export function narrativeValue(parsed: ParsedNarrative): CanonicalValue {+export function narrativeValue(parsed: ParsedNarrative, id: string): CanonicalValue {return canonicalize({+ id,segments: parsed.segments.map((segment) => ({id: segment.id,startAnchorId: segment.startAnchorId,@@ -194,8 +198,8 @@ export function narrativeValue(parsed: ParsedNarrative): CanonicalValue {anchors: parsed.semanticIndex.anchors.map((anchor) => ({id: anchor.id,kind: anchor.kind,- segmentId: anchor.segmentId,- ...(anchor.tokenId === undefined ? {} : { tokenId: anchor.tokenId }),+ ...("segmentId" in anchor ? { segmentId: anchor.segmentId } : {}),+ ...("tokenId" in anchor && anchor.tokenId !== undefined ? { tokenId: anchor.tokenId } : {}),})),},});diff --git a/packages/script/src/parser.ts b/packages/script/src/parser.tsindex 0e18ef53..3375c36f 100644--- a/packages/script/src/parser.ts+++ b/packages/script/src/parser.ts@@ -751,10 +751,11 @@ export function parseScript(const segmentById = new Map(segments.map((segment) => [segment.id, segment]));/**- * Resolve one marker to the exact `2m + 2n` anchor its affinity names. Token and+ * Resolve one marker to the exact `2m + 2n + 2` anchor its affinity names. Token and* Segment cuts are equal citizens: a marker with nothing to its left inside a* Segment snaps to that Segment's own start, never across into the previous- * Segment, whose end may sit at a different time.+ * Segment, whose end may sit at a different time. At the Script body's outer+ * cuts, affinity distinguishes the Program boundary from its first/last Segment.*/const anchorForBoundary = (boundary: RawMarkerBoundary, affinity: Affinity): string => {if (segments.length === 0) fail("SCRIPT_ANCHOR_UNRESOLVED", "Script declares no Segment to anchor markers to.");@@ -769,13 +770,13 @@ export function parseScript(? tokens[boundary.tokenIndex]!.startAnchorId: inside.endAnchorId;}- // Between Segments: structuralPosition counts the Segments already closed.+ // Outside or between Segments: structuralPosition counts the Segments already closed.if (affinity === "left") {const previous = segments[boundary.structuralPosition - 1];- return previous ? previous.endAnchorId : segments[0]!.startAnchorId;+ return previous ? previous.endAnchorId : "program:start";}const next = segments[boundary.structuralPosition];- return next ? next.startAnchorId : segments.at(-1)!.endAnchorId;+ return next ? next.startAnchorId : "program:end";};const anchored = <T extends { readonly affinity: Affinity; readonly boundary: RawMarkerBoundary }>(edge: T,@@ -784,31 +785,36 @@ export function parseScript(boundary: { ...edge.boundary, anchorId: anchorForBoundary(edge.boundary, edge.affinity) },});- const anchors: SemanticAnchor[] = segments.flatMap((segment) => [- { id: segment.startAnchorId, kind: "segment-start" as const, segmentId: segment.id },- ...tokens.slice(segment.tokenStart, segment.tokenEndExclusive).flatMap((token) => [- {- id: token.startAnchorId,- kind: "token-start" as const,- segmentId: segment.id,- tokenId: token.id,- segmentTokenIndex: token.segmentTokenIndex,- },- {- id: token.endAnchorId,- kind: "token-end" as const,- segmentId: segment.id,- tokenId: token.id,- segmentTokenIndex: token.segmentTokenIndex,- },+ const anchors: SemanticAnchor[] = [+ { id: "program:start", kind: "program-start" },+ ...segments.flatMap((segment) => [+ { id: segment.startAnchorId, kind: "segment-start" as const, segmentId: segment.id },+ ...tokens.slice(segment.tokenStart, segment.tokenEndExclusive).flatMap((token) => [+ {+ id: token.startAnchorId,+ kind: "token-start" as const,+ segmentId: segment.id,+ tokenId: token.id,+ segmentTokenIndex: token.segmentTokenIndex,+ },+ {+ id: token.endAnchorId,+ kind: "token-end" as const,+ segmentId: segment.id,+ tokenId: token.id,+ segmentTokenIndex: token.segmentTokenIndex,+ },+ ]),+ { id: segment.endAnchorId, kind: "segment-end" as const, segmentId: segment.id },]),- { id: segment.endAnchorId, kind: "segment-end" as const, segmentId: segment.id },- ]);- if (anchors.length !== 2 * tokens.length + 2 * segments.length) {- fail("SCRIPT_ANCHOR_CARDINALITY", "Semantic anchor cardinality is not 2M + 2N.");+ { id: "program:end", kind: "program-end" },+ ];+ if (anchors.length !== 2 * tokens.length + 2 * segments.length + 2) {+ fail("SCRIPT_ANCHOR_CARDINALITY", "Semantic anchor cardinality is not 2M + 2N + 2.");}return {+ sourceRange: { start: sourceOffset, end: sourceOffset + source.length },segments,tokens,turns,diff --git a/packages/script/src/surface.ts b/packages/script/src/surface.tsindex e755140d..096cdca8 100644--- a/packages/script/src/surface.ts+++ b/packages/script/src/surface.ts@@ -80,13 +80,13 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut{id: rawId,type: narrativeType,- value: { kind: "inline", value: narrativeValue(parsed) },+ value: { kind: "inline", value: narrativeValue(parsed, rawId) },range: { start: input.openingStart, end: close.end },},...parsed.segments.map((segment) => ({id: `${rawId}.segment.${segment.id}`,type: narrativeExcerptType,- value: { kind: "inline" as const, value: narrativeSegmentExcerptValue(parsed, segment) },+ value: { kind: "inline" as const, value: narrativeSegmentExcerptValue(parsed, segment, rawId) },range: segment.range,})),...parsed.segments.flatMap((segment) => [@@ -106,13 +106,13 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut{id: captionId,type: captionDocumentType,- value: { kind: "inline" as const, value: captionDocumentValue(parsed, captionId) },+ value: { kind: "inline" as const, value: captionDocumentValue(parsed, captionId, rawId) },range: { start: input.openingStart, end: close.end },},...parsed.selections.map((selection) => ({id: `${rawId}.selection.${selection.id}`,type: narrativeSelectionType,- value: { kind: "inline" as const, value: narrativeSelectionValue(selection) },+ value: { kind: "inline" as const, value: narrativeSelectionValue(selection, rawId) },range: {start: selection.open.range.start,end: selection.close.range.end,@@ -121,11 +121,12 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut...parsed.moments.map((moment) => ({id: `${rawId}.moment.${moment.id}`,type: narrativeMomentType,- value: { kind: "inline" as const, value: narrativeMomentValue(moment) },+ value: { kind: "inline" as const, value: narrativeMomentValue(moment, rawId) },range: moment.range,})),],components: [],fragments: [],+ identities: [{ namespace: narrativeType, id: rawId }],};}diff --git a/packages/script/src/types.ts b/packages/script/src/types.tsindex ac5a7675..cc6c4e66 100644--- a/packages/script/src/types.ts+++ b/packages/script/src/types.ts@@ -48,11 +48,11 @@ export type ParsedToken = NarrativeToken & {};export type ParsedTurn = NarrativeTurn & { readonly range: SourceRange };-export type ParsedSelection = NarrativeSelection & {+export type ParsedSelection = Omit<NarrativeSelection, "narrativeId"> & {readonly open: { readonly affinity: Affinity; readonly boundary: MarkerBoundary; readonly range: SourceRange };readonly close: { readonly affinity: Affinity; readonly boundary: MarkerBoundary; readonly range: SourceRange };};-export type ParsedMoment = NarrativeMoment & {+export type ParsedMoment = Omit<NarrativeMoment, "narrativeId"> & {readonly affinity: Affinity;readonly boundary: MarkerBoundary;readonly range: SourceRange;@@ -75,8 +75,10 @@ export type ParsedCaptionRegion = {export type ParsedNarrative = Omit<Narrative,- "segments" | "tokens" | "turns" | "selections" | "moments"+ "id" | "segments" | "tokens" | "turns" | "selections" | "moments"> & {+ /** Exact Script body range, used only for source-preserving Program-boundary edits. */+ readonly sourceRange: SourceRange;readonly segments: readonly ParsedSegment[];readonly tokens: readonly ParsedToken[];readonly turns: readonly ParsedTurn[];@@ -116,4 +118,8 @@ export type ScriptSurfaceOutput = {/** Script is a record-only Surface; it cannot smuggle executable graph declarations. */readonly components: readonly never[];readonly fragments: readonly never[];+ readonly identities: readonly {+ readonly namespace: TypeRef;+ readonly id: string;+ }[];};diff --git a/packages/script/test/markup-integration.test.ts b/packages/script/test/markup-integration.test.tsindex edb32c05..a2a3815b 100644--- a/packages/script/test/markup-integration.test.ts+++ b/packages/script/test/markup-integration.test.ts@@ -8,6 +8,7 @@ import { createResolvedClosure } from "@hypit/core";import type { ModuleManifest } from "@hypit/protocol";import {decodeScriptSurface,+ narrativeType,scriptManifest,scriptMarkupSurfaces,scriptModuleRef,@@ -63,6 +64,7 @@ test("Script teaches Markup <script> only through its imported Manifest", asyncrecord.id === "story.segment.opening.speech" && record.type.name === "Text"), true);assert.equal(result.records.some((record) =>record.id === "story.caption" && record.type.name === "CaptionDocument"), true);+ assert.deepEqual(result.identities, [{ namespace: narrativeType, id: "story" }]);});test("the same Script meaning has the same authored Record digest across reflow", async () => {diff --git a/packages/script/test/script.test.ts b/packages/script/test/script.test.tsindex 7f649d3d..3873dc65 100644--- a/packages/script/test/script.test.ts+++ b/packages/script/test/script.test.ts@@ -13,7 +13,7 @@ import {serializeSpeech,} from "@hypit/script";-test("Selection source edits relocate markers by 2M + 2N Anchor identity", () => {+test("Selection source edits relocate markers by 2M + 2N + 2 Anchor identity", () => {const source = "<one><HOST>@focus alpha beta @/focus gamma</one>\r\n<two><HOST>delta epsilon</two>";const parsed = parseScript("selection-adjust.svml", source);const movedWords = adjustScriptSelection({@@ -48,6 +48,32 @@ test("Selection source edits relocate markers by 2M + 2N Anchor identity", () =>]);});+test("Program boundaries are distinct writable semantic Anchors", () => {+ const source = "<one>alpha</one>\n<two>beta</two>";+ const withSelection = adjustScriptSelection({+ sourceName: "program-boundaries.svml",+ source: "@focus <one>alpha</one>\n<two>beta @/focus</two>",+ parsed: parseScript("program-boundaries.svml", "@focus <one>alpha</one>\n<two>beta @/focus</two>"),+ adjustment: { id: "focus", startAnchorId: "program:start", endAnchorId: "program:end" },+ });+ const selection = parseScript("program-boundaries.svml", withSelection).selections[0]!;+ assert.deepEqual([selection.startAnchorId, selection.endAnchorId], ["program:start", "program:end"]);+ assert.match(withSelection, /^~@focus /u);+ assert.match(withSelection, / @\/focus~$/u);++ const withMoment = adjustScriptMoment({+ sourceName: "program-boundaries.svml",+ source: `${source.slice(0, source.indexOf("beta"))}@cue! ${source.slice(source.indexOf("beta"))}`,+ parsed: parseScript(+ "program-boundaries.svml",+ `${source.slice(0, source.indexOf("beta"))}@cue! ${source.slice(source.indexOf("beta"))}`,+ ),+ adjustment: { id: "cue", anchorId: "program:end" },+ });+ assert.equal(parseScript("program-boundaries.svml", withMoment).moments[0]!.anchorId, "program:end");+ assert.match(withMoment, / @cue!$/u);+});+test("Moment source edits relocate one marker to an exact semantic Anchor", () => {const source = "<one><HOST>alpha @cue! beta</one><two><HOST>gamma</two>";const moved = adjustScriptMoment({@@ -66,25 +92,25 @@ test("Script keeps speech, dialogue and CaptionDocument as separate projections"assert.equal(serializeSpeech(parsed), "I laughed my ass off there.");assert.equal(serializeDialogue(parsed), "BOB: I laughed my ass off there.");assert.equal(serializeCaption(parsed), "I laughed there.");- const document = captionDocument(parsed, "story.caption");+ const document = captionDocument(parsed, "story.caption", "story");assert.equal(document.units.length, 3);assert.equal(document.units[1]!.wordIds.length, 1);assert.equal(document.units[1]!.sourceTokenIds.length, 4);assert.deepEqual(document.cueBreaks, []);- assert.equal((narrativeValue(parsed) as { semanticIndex: { anchors: unknown[] } }).semanticIndex.anchors.length,- 2 * parsed.tokens.length + 2 * parsed.segments.length);+ assert.equal((narrativeValue(parsed, "story") as { semanticIndex: { anchors: unknown[] } }).semanticIndex.anchors.length,+ 2 * parsed.tokens.length + 2 * parsed.segments.length + 2);});test("Cue breaks are authored between complete units", () => {const parsed = parseScript("break.svml", "<line>one two || three four</line>");- const document = captionDocument(parsed, "story.caption");+ const document = captionDocument(parsed, "story.caption", "story");assert.equal(document.cueBreaks.length, 1);assert.equal(document.cueBreaks[0]!.afterUnitId, document.units[1]!.id);});test("Caption punctuation is display-only and CJK uses lexical character units", () => {const parsed = parseScript("punctuation-cjk.svml", "<line><test | now>. here 你好,世界!</line>");- const document = captionDocument(parsed, "story.caption");+ const document = captionDocument(parsed, "story.caption", "story");assert.deepEqual(parsed.tokens.map((token) => token.text), ["now", "here", "你", "好", "世", "界"]);assert.deepEqual(document.words.slice(0, 2).map((word) => word.text), ["test.", "here"]);assert.deepEqual(document.words.slice(-4).map((word) => word.text), ["你", "好,", "世", "界!"]);@@ -95,7 +121,7 @@ test("Caption punctuation assigns ASCII quotes to the enclosed display words", ("punctuation-quotes.svml","<line>He said <\"hello world\" | hello world>. 他说 <“你好” | 你好>。</line>",);- const document = captionDocument(parsed, "story.caption");+ const document = captionDocument(parsed, "story.caption", "story");assert.deepEqual(parsed.tokens.map((token) => token.text), ["He", "said", "hello", "world", "他", "说", "你", "好",]);@@ -109,7 +135,7 @@ test("Script keeps ordinary compounds and formatted numbers lexical", () => {"punctuation-compounds.svml","<line>rock ’n’ roll costs 1,234.56 dollars.</line>",);- const document = captionDocument(parsed, "story.caption");+ const document = captionDocument(parsed, "story.caption", "story");assert.deepEqual(parsed.tokens.map((token) => token.text), ["rock", "n", "roll", "costs", "1,234.56", "dollars",]);@@ -120,7 +146,7 @@ test("Script keeps ordinary compounds and formatted numbers lexical", () => {test("A single pipe is literal and a double pipe is an authored Cue Break", () => {const parsed = parseScript("pipes.svml", "<line>one | two || three \\|\\| four</line>");- const document = captionDocument(parsed, "story.caption");+ const document = captionDocument(parsed, "story.caption", "story");assert.equal(document.cueBreaks.length, 1);assert.equal(serializeCaption(parsed), "one | two three || four");assert.deepEqual(document.words.map((word) => word.text), ["one|", "two", "three||", "four"]);@@ -141,7 +167,7 @@ test("Script projects flat token attributes onto display words without changing"word-attributes.svml","<line>This is really{emphasis,keyword} <hypit{brand} | hype it> now.</line>",);- const document = captionDocument(parsed, "story.caption");+ const document = captionDocument(parsed, "story.caption", "story");assert.deepEqual(document.words.map((word) => [word.text, word.attributes]), [["This", []],["is", []],diff --git a/packages/semantic-take-estimate/README.md b/packages/semantic-take-estimate/README.mdnew file mode 100644index 00000000..1a2d2763--- /dev/null+++ b/packages/semantic-take-estimate/README.md@@ -0,0 +1,38 @@+# `@hypit/semantic-take-estimate`++An explicit, provider-free alternative to measured speech alignment for preview Builds.++```text+Narrative + Segment + normalized SynchronizedMedia + SpeechEstimatePolicy+ -> syllable-weighted Token windows with real gaps+ -> SemanticTake+```++The package consumes an existing normalized media value. It knows nothing about how the video was+generated and does not run FFmpeg, OpenCV, WhisperX or any other external process. It preserves the+Script's exact Segment, Token and Anchor identities and estimates only their local frame positions.+The normalized media's complete frame count is the allocation budget: after short edge and word+gaps, every remaining frame is distributed across Tokens by pronunciation-unit weight. A longer+normalized video therefore stretches the whole Script across that longer interval instead of+leaving a fixed-length estimate at the beginning.++```svml+<estimated:SemanticTake id="opening-estimated" narrative={story}+ segment={story.segment.opening} media={opening-media.media}+ policy={opening-duration.policy}/>+```++The result has the ordinary `@hypit/speech@1#SemanticTake` type. A Run can therefore choose this+Build output while real A-roll is unavailable, then later choose the corresponding WhisperX output+without changing Speech Track, Caption, Selection or Studio protocols.++For example, a later Studio Run may satisfy its ordinary measured-take output with the earlier+estimated Build product:++```svrun+<build-record id="opening-preview" build="bld_..." output="opening-estimated.take"/>+<satisfy output="opening-semantic.take" candidate="opening-preview"/>+```++This is ordinary Run candidate selection. There is no preview-specific `SemanticTake` subtype and+Studio still opens only after every required output has an actual candidate with no unresolved Need.diff --git a/packages/semantic-take-estimate/package.json b/packages/semantic-take-estimate/package.jsonnew file mode 100644index 00000000..5e2f6fba--- /dev/null+++ b/packages/semantic-take-estimate/package.json@@ -0,0 +1,26 @@+{+ "name": "@hypit/semantic-take-estimate",+ "version": "0.0.0-dev",+ "license": "SEE LICENSE IN LICENSE",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "hypit": {+ "activation": "./src/activation.ts"+ },+ "dependencies": {+ "@hypit/component-kit": "workspace:*",+ "@hypit/elaborator": "workspace:*",+ "@hypit/estimate": "workspace:*",+ "@hypit/markup": "workspace:*",+ "@hypit/media": "workspace:*",+ "@hypit/narrative": "workspace:*",+ "@hypit/protocol": "workspace:*",+ "@hypit/speech": "workspace:*"+ },+ "devDependencies": {+ "@hypit/script": "workspace:*"+ }+}diff --git a/packages/semantic-take-estimate/src/activation.ts b/packages/semantic-take-estimate/src/activation.tsnew file mode 100644index 00000000..6aa56e0f--- /dev/null+++ b/packages/semantic-take-estimate/src/activation.ts@@ -0,0 +1,22 @@+import { createMarkupSurfaceHostFacet } from "@hypit/markup";++import {+ decodeSemanticTakeEstimateSurface,+ semanticTakeEstimateComponent,+ semanticTakeEstimateManifest,+ semanticTakeEstimateMarkupSurfaces,+ semanticTakeEstimateModuleRef,+} from "./index.js";++export const hypitPackage = {+ format: "hypit.node-package@1" as const,+ modules: [{ manifest: semanticTakeEstimateManifest }],+ components: [semanticTakeEstimateComponent],+ hostFacets: [createMarkupSurfaceHostFacet({+ module: semanticTakeEstimateModuleRef,+ declaration: semanticTakeEstimateMarkupSurfaces.find((item) => item.name === "semantic-take")!,+ handler: decodeSemanticTakeEstimateSurface,+ })],+};++export default hypitPackage;diff --git a/packages/semantic-take-estimate/src/component.ts b/packages/semantic-take-estimate/src/component.tsnew file mode 100644index 00000000..4770d434--- /dev/null+++ b/packages/semantic-take-estimate/src/component.ts@@ -0,0 +1,34 @@+import type { ComponentPackage } from "@hypit/component-kit";+import type { SpeechEstimatePolicy } from "@hypit/estimate";+import type { SynchronizedMedia } from "@hypit/media";+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";+import { canonicalize } from "@hypit/protocol";+import type { StoredValue } from "@hypit/protocol";++import { semanticTakeEstimateProducers } from "./manifest.js";+import { materializeEstimatedSemanticTake } from "./program.js";++function inline<T>(value: StoredValue | undefined, subject: string): T {+ if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);+ return value.value as unknown as T;+}++export const semanticTakeEstimateComponent = {+ producers: [{+ producer: semanticTakeEstimateProducers.materialize,+ handler: ({ inputs }) => ({+ outputs: {+ take: {+ kind: "inline",+ value: canonicalize(materializeEstimatedSemanticTake(+ inline<Narrative>(inputs.narrative?.value, "Narrative"),+ inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),+ inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),+ inline<SpeechEstimatePolicy>(inputs.policy?.value, "SpeechEstimatePolicy"),+ )),+ },+ },+ needs: {},+ }),+ }],+} satisfies ComponentPackage;diff --git a/packages/semantic-take-estimate/src/fragment.ts b/packages/semantic-take-estimate/src/fragment.tsnew file mode 100644index 00000000..5d13955c--- /dev/null+++ b/packages/semantic-take-estimate/src/fragment.ts@@ -0,0 +1,31 @@+import { estimateTypes } from "@hypit/estimate";+import { sealGraphFragment } from "@hypit/elaborator";+import { mediaTypes } from "@hypit/media";+import { narrativeTypes } from "@hypit/narrative";+import { speechTypes } from "@hypit/speech";++import { semanticTakeEstimateProducers } from "./manifest.js";++const input = (name: string) => ({ kind: "fragment-input" as const, name });+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });++export const semanticTakeEstimateFragment = sealGraphFragment({+ inputs: [+ { name: "narrative", type: narrativeTypes.narrative },+ { name: "segment", type: narrativeTypes.excerpt },+ { name: "media", type: mediaTypes.synchronized },+ { name: "policy", type: estimateTypes.speechPolicy },+ ],+ operations: [{+ id: "materialize",+ producer: semanticTakeEstimateProducers.materialize,+ inputs: {+ narrative: input("narrative"),+ segment: input("segment"),+ media: input("media"),+ policy: input("policy"),+ },+ result: { kind: "output", name: "take" },+ }],+ exports: [{ name: "take", type: speechTypes.semanticTake, root: operation("materialize") }],+});diff --git a/packages/semantic-take-estimate/src/index.ts b/packages/semantic-take-estimate/src/index.tsnew file mode 100644index 00000000..fc100ee5--- /dev/null+++ b/packages/semantic-take-estimate/src/index.ts@@ -0,0 +1,13 @@+export { semanticTakeEstimateComponent } from "./component.js";+export { semanticTakeEstimateFragment } from "./fragment.js";+export {+ semanticTakeEstimateManifest,+ semanticTakeEstimateMarkupSurfaces,+ semanticTakeEstimateModuleRef,+ semanticTakeEstimateProducers,+} from "./manifest.js";+export {+ estimateSemanticTakeTiming,+ materializeEstimatedSemanticTake,+} from "./program.js";+export { decodeSemanticTakeEstimateSurface } from "./surface.js";diff --git a/packages/semantic-take-estimate/src/manifest.ts b/packages/semantic-take-estimate/src/manifest.tsnew file mode 100644index 00000000..6b077fa8--- /dev/null+++ b/packages/semantic-take-estimate/src/manifest.ts@@ -0,0 +1,70 @@+import { estimateModuleRef, estimateTypes } from "@hypit/estimate";+import { mediaDependency, mediaTypes } from "@hypit/media";+import { narrativeDependency, narrativeTypes } from "@hypit/narrative";+import type { ModuleManifest, ProducerRef } from "@hypit/protocol";+import { speechDependency, speechTypes } from "@hypit/speech";++export const semanticTakeEstimateModuleRef = { name: "@hypit/semantic-take-estimate", version: "1" } as const;++export const semanticTakeEstimateProducers = {+ materialize: { module: semanticTakeEstimateModuleRef, name: "materialize-estimated-semantic-take" },+} satisfies Record<string, ProducerRef>;++export const semanticTakeEstimateMarkupSurfaces = [{+ name: "semantic-take",+ tag: "SemanticTake",+ mode: "structured",+ outputs: [speechTypes.semanticTake],+ vocabulary: {+ summary:+ "Projects syllable-weighted estimated word windows onto one already normalized video and publishes a SemanticTake.",+ attributes: [+ { name: "id", kind: "identifier", required: true,+ summary: "Names this estimated alignment and the SemanticTake it publishes." },+ { name: "narrative", kind: "reference", required: true, accepts: [narrativeTypes.narrative],+ summary: "Selects the authored Narrative that owns every Token and Anchor identity." },+ { name: "segment", kind: "reference", required: true, accepts: [narrativeTypes.excerpt],+ summary: "Selects the single authored Segment represented by the normalized video." },+ { name: "media", kind: "reference", required: true, accepts: [mediaTypes.synchronized],+ summary: "Selects the already normalized SynchronizedMedia whose exact frame domain receives the estimate." },+ { name: "policy", kind: "reference", required: true, accepts: [estimateTypes.speechPolicy],+ summary: "Selects the speech-estimate policy whose explicit language rules weight each authored Token." },+ ],+ ports: [{ name: "take", type: speechTypes.semanticTake,+ summary: "The estimated SemanticTake, addressed as `<id>.take`." }],+ example: `<estimated:SemanticTake id="opening-estimated" narrative={story}+ segment={story.segment.opening} media={opening-media.media}+ policy={opening-duration.policy}/>`,+ notes: [+ "This package does not measure audio and never claims WhisperX or other acoustic evidence.",+ "Every Token uses its original Script identity. Only its local frame window is estimated.",+ "Pronunciation-unit weights determine relative word lengths; adjacent words and both media edges retain non-zero frame gaps.",+ "The result has the same SemanticTake Type as a measured alignment, so Run chooses between ordinary candidates without a preview-specific downstream protocol.",+ ],+ },+}] as const;++export const semanticTakeEstimateManifest: ModuleManifest = {+ format: "hypit.module@1",+ name: semanticTakeEstimateModuleRef.name,+ version: semanticTakeEstimateModuleRef.version,+ dependencies: [+ mediaDependency,+ narrativeDependency,+ speechDependency,+ { module: estimateModuleRef },+ ],+ types: [],+ capabilities: [],+ producers: [{+ name: semanticTakeEstimateProducers.materialize.name,+ inputs: [+ { name: "narrative", type: narrativeTypes.narrative },+ { name: "segment", type: narrativeTypes.excerpt },+ { name: "media", type: mediaTypes.synchronized },+ { name: "policy", type: estimateTypes.speechPolicy },+ ],+ outputs: [{ name: "take", type: speechTypes.semanticTake }],+ needs: [],+ }],+};diff --git a/packages/semantic-take-estimate/src/program.ts b/packages/semantic-take-estimate/src/program.tsnew file mode 100644index 00000000..dd557ae7--- /dev/null+++ b/packages/semantic-take-estimate/src/program.ts@@ -0,0 +1,115 @@+import {+ assertSpeechEstimatePolicy,+ countSpeechEstimateUnits,+ resolveSpeechEstimateLanguage,+} from "@hypit/estimate";+import type { SpeechEstimatePolicy } from "@hypit/estimate";+import { verifySynchronizedMedia } from "@hypit/media";+import type { SynchronizedMedia } from "@hypit/media";+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";+import { materializeSemanticTake } from "@hypit/speech";+import type { SemanticTake, SemanticTakeTimedToken, SemanticTakeTiming } from "@hypit/speech";++const EDGE_GAP_SECONDS = 0.12;+const WORD_GAP_SECONDS = 0.06;++function segmentTokens(narrative: Narrative, excerpt: NarrativeExcerpt): readonly Narrative["tokens"][number][] {+ if (excerpt.kind !== "segment") throw new Error("Estimated SemanticTake requires a Segment excerpt.");+ const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id);+ if (segment === undefined+ || segment.tokenStart !== excerpt.tokenStart+ || segment.tokenEndExclusive !== excerpt.tokenEndExclusive) {+ throw new Error(`NarrativeExcerpt ${excerpt.id} does not describe its authored Segment.`);+ }+ const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive);+ if (tokens.length === 0) throw new Error(`Estimated SemanticTake Segment ${excerpt.id} contains no speech Tokens.`);+ return tokens;+}++function weightedFrames(total: number, weights: readonly number[]): number[] {+ if (total < weights.length) throw new Error("Estimated SemanticTake has fewer articulation frames than Tokens.");+ const remaining = total - weights.length;+ const weightTotal = weights.reduce((sum, weight) => sum + weight, 0);+ const allocations = weights.map((weight) => 1 + Math.floor(remaining * weight / weightTotal));+ const left = total - allocations.reduce((sum, value) => sum + value, 0);+ const order = weights+ .map((weight, index) => ({ index, remainder: remaining * weight % weightTotal }))+ .sort((leftItem, rightItem) => rightItem.remainder - leftItem.remainder || leftItem.index - rightItem.index);+ for (let index = 0; index < left; index += 1) allocations[order[index]!.index]! += 1;+ return allocations;+}++/** Deterministic, explicitly estimated timing; it consumes no acoustic evidence. */+export function estimateSemanticTakeTiming(+ narrative: Narrative,+ excerpt: NarrativeExcerpt,+ media: SynchronizedMedia,+ policy: SpeechEstimatePolicy,+): SemanticTakeTiming {+ verifySynchronizedMedia(media);+ assertSpeechEstimatePolicy(policy);+ const tokens = segmentTokens(narrative, excerpt);+ const rate = media.timeline.frameRate.numerator / media.timeline.frameRate.denominator;+ const edgeGap = Math.max(1, Math.round(EDGE_GAP_SECONDS * rate));+ const wordGap = Math.max(1, Math.round(WORD_GAP_SECONDS * rate));+ const reserved = edgeGap * 2 + wordGap * (tokens.length - 1);+ const articulationFrames = media.timeline.frameCount - reserved;+ if (articulationFrames < tokens.length) {+ throw new Error(+ `Estimated SemanticTake needs at least ${reserved + tokens.length} frames to keep every Token visible and separated; got ${media.timeline.frameCount}.`,+ );+ }++ const language = resolveSpeechEstimateLanguage(tokens.map((token) => token.text).join(" "), policy.language);+ const weights = tokens.map((token) => Math.max(1, countSpeechEstimateUnits(token.text, language)));+ const durations = weightedFrames(articulationFrames, weights);+ let cursor = edgeGap;+ const timed = tokens.map((token, index): SemanticTakeTimedToken => {+ const startFrame = cursor;+ const endFrameExclusive = startFrame + durations[index]!;+ cursor = endFrameExclusive + (index === tokens.length - 1 ? 0 : wordGap);+ return {+ tokenId: token.id,+ segmentId: excerpt.id,+ startFrame,+ endFrameExclusive,+ };+ });+ if (cursor !== media.timeline.frameCount - edgeGap) {+ throw new Error("Estimated SemanticTake timing allocation did not close over its frame domain.");+ }++ const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id)!;+ const frameByAnchor = new Map<string, number>([+ [segment.startAnchorId, 0],+ [segment.endAnchorId, media.timeline.frameCount],+ ]);+ for (const [index, token] of tokens.entries()) {+ frameByAnchor.set(token.startAnchorId, timed[index]!.startFrame);+ frameByAnchor.set(token.endAnchorId, timed[index]!.endFrameExclusive);+ }+ const anchors = narrative.semanticIndex.anchors+ .filter((anchor) => anchor.segmentId === excerpt.id)+ .map((anchor) => {+ const frame = frameByAnchor.get(anchor.id);+ if (frame === undefined) throw new Error(`Estimated timing cannot locate authored Anchor ${anchor.id}.`);+ return { identity: anchor.id, frame };+ });+ return { tokens: timed, anchors };+}++export function materializeEstimatedSemanticTake(+ narrative: Narrative,+ excerpt: NarrativeExcerpt,+ media: SynchronizedMedia,+ policy: SpeechEstimatePolicy,+): SemanticTake {+ verifySynchronizedMedia(media);+ if (media.visual === undefined) throw new Error("Estimated SemanticTake requires normalized visual media.");+ return materializeSemanticTake(+ narrative,+ excerpt,+ media,+ estimateSemanticTakeTiming(narrative, excerpt, media, policy),+ );+}diff --git a/packages/semantic-take-estimate/src/surface.ts b/packages/semantic-take-estimate/src/surface.tsnew file mode 100644index 00000000..6ac0d470--- /dev/null+++ b/packages/semantic-take-estimate/src/surface.ts@@ -0,0 +1,56 @@+import { estimateTypes } from "@hypit/estimate";+import {+ assertExactAttributes,+ textAttribute,+} from "@hypit/markup";+import type {+ MarkupAttributeValue,+ StructuredElement,+ StructuredSurfaceHandler,+ SurfaceResolvedReference,+} from "@hypit/markup";+import { mediaTypes } from "@hypit/media";+import { narrativeTypes } from "@hypit/narrative";+import { sameType } from "@hypit/protocol";++import { semanticTakeEstimateFragment } from "./fragment.js";++function reference(+ element: StructuredElement,+ name: string,+ expected: SurfaceResolvedReference["type"],+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,+): SurfaceResolvedReference {+ const raw: MarkupAttributeValue | undefined = element.attributes[name];+ if (typeof raw !== "object" || raw.kind !== "reference") {+ throw new Error(`${element.name}.${name} must be a whole-value reference`);+ }+ const resolved = resolveReference(raw.path);+ if (resolved === undefined) throw new Error(`${element.name}.${name} cannot resolve ${raw.path}`);+ if (!sameType(resolved.type, expected)) throw new Error(`${element.name}.${name} has the wrong type`);+ return resolved;+}++export const decodeSemanticTakeEstimateSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {+ assertExactAttributes(element, ["id", "narrative", "segment", "media", "policy"]);+ if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {+ throw new Error(`${element.name} must be empty`);+ }+ const id = textAttribute(element, "id");+ return {+ records: [],+ components: [{+ id,+ fragment: semanticTakeEstimateFragment.id,+ inputs: {+ narrative: reference(element, "narrative", narrativeTypes.narrative, resolveReference).ref,+ segment: reference(element, "segment", narrativeTypes.excerpt, resolveReference).ref,+ media: reference(element, "media", mediaTypes.synchronized, resolveReference).ref,+ policy: reference(element, "policy", estimateTypes.speechPolicy, resolveReference).ref,+ },+ outputs: { take: `${id}.take` },+ range: element.range,+ }],+ fragments: [semanticTakeEstimateFragment],+ };+};diff --git a/packages/semantic-take-estimate/test/semantic-take-estimate.test.ts b/packages/semantic-take-estimate/test/semantic-take-estimate.test.tsnew file mode 100644index 00000000..819eecc6--- /dev/null+++ b/packages/semantic-take-estimate/test/semantic-take-estimate.test.ts@@ -0,0 +1,110 @@+import assert from "node:assert/strict";+import test from "node:test";++import { sealSpeechEstimatePolicy } from "@hypit/estimate";+import { sealSynchronizedMedia } from "@hypit/media";+import type { Narrative } from "@hypit/narrative";+import { fixtureDigest } from "../../../test/fixture-digest.js";++import {+ estimateSemanticTakeTiming,+ materializeEstimatedSemanticTake,+} from "@hypit/semantic-take-estimate";++const narrative: Narrative = {+ id: "test-narrative",+ segments: [{+ id: "opening",+ startAnchorId: "opening:start",+ endAnchorId: "opening:end",+ tokenStart: 0,+ tokenEndExclusive: 3,+ }],+ tokens: [+ { id: "a", segmentId: "opening", startAnchorId: "a:start", endAnchorId: "a:end", text: "A", normalized: "a" },+ { id: "wonderful", segmentId: "opening", startAnchorId: "wonderful:start", endAnchorId: "wonderful:end", text: "wonderful", normalized: "wonderful" },+ { id: "cat", segmentId: "opening", startAnchorId: "cat:start", endAnchorId: "cat:end", text: "cat.", normalized: "cat" },+ ],+ turns: [],+ selections: [],+ moments: [],+ semanticIndex: {+ anchors: [+ { id: "opening:start", kind: "segment-start", segmentId: "opening" },+ { id: "a:start", kind: "token-start", segmentId: "opening", tokenId: "a" },+ { id: "a:end", kind: "token-end", segmentId: "opening", tokenId: "a" },+ { id: "wonderful:start", kind: "token-start", segmentId: "opening", tokenId: "wonderful" },+ { id: "wonderful:end", kind: "token-end", segmentId: "opening", tokenId: "wonderful" },+ { id: "cat:start", kind: "token-start", segmentId: "opening", tokenId: "cat" },+ { id: "cat:end", kind: "token-end", segmentId: "opening", tokenId: "cat" },+ { id: "opening:end", kind: "segment-end", segmentId: "opening" },+ ],+ },+};++const excerpt = { narrativeId: narrative.id, kind: "segment" as const, id: "opening", tokenStart: 0, tokenEndExclusive: 3 };+const media = sealSynchronizedMedia({+ timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 120 },+ visual: {+ artifact: { kind: "blob", digest: fixtureDigest("estimated-take-video"), size: 1_024, mediaType: "video/mp4" },+ width: 1_080,+ height: 1_920,+ },+});+const policy = sealSpeechEstimatePolicy({+ language: "en",+ pace: "normal",+ minimumSec: 1,+ maximumSec: 30,+ rounding: "none",+});++test("estimated timing weights articulation by syllables and leaves visible gaps", () => {+ const timing = estimateSemanticTakeTiming(narrative, excerpt, media, policy);+ assert.equal(timing.tokens[0]!.startFrame, 4);+ assert.equal(timing.tokens[1]!.startFrame - timing.tokens[0]!.endFrameExclusive, 2);+ assert.equal(timing.tokens[2]!.startFrame - timing.tokens[1]!.endFrameExclusive, 2);+ assert.equal(media.timeline.frameCount - timing.tokens[2]!.endFrameExclusive, 4);+ const durations = timing.tokens.map((token) => token.endFrameExclusive - token.startFrame);+ assert.ok(durations[1]! > durations[0]!);+ assert.ok(durations[1]! > durations[2]!);+});++test("estimated timing fills the normalized media instead of stopping at a fixed speech length", () => {+ const frameCounts = [7 * 30, 10 * 30];+ const timings = frameCounts.map((frameCount) => estimateSemanticTakeTiming(+ narrative,+ excerpt,+ sealSynchronizedMedia({ ...media, timeline: { ...media.timeline, frameCount } }),+ policy,+ ));++ for (const [index, timing] of timings.entries()) {+ const frameCount = frameCounts[index]!;+ assert.ok(timing.tokens[0]!.startFrame <= 0.2 * 30);+ assert.ok(timing.tokens.at(-1)!.endFrameExclusive >= frameCount - 0.2 * 30);+ }+ assert.ok(+ timings[1]!.tokens[1]!.endFrameExclusive - timings[1]!.tokens[1]!.startFrame+ > timings[0]!.tokens[1]!.endFrameExclusive - timings[0]!.tokens[1]!.startFrame,+ );+});++test("estimated and measured alignment share the ordinary SemanticTake waist", () => {+ const take = materializeEstimatedSemanticTake(narrative, excerpt, media, policy);+ assert.equal(take.segment.segmentId, "opening");+ assert.deepEqual(take.tokens.map((token) => token.tokenId), ["a", "wonderful", "cat"]);+ assert.deepEqual(take.media, media);+ assert.equal(take.media.audio, undefined);+});++test("an implausibly short frame domain is refused instead of squeezing words together", () => {+ const short = sealSynchronizedMedia({+ ...media,+ timeline: { ...media.timeline, frameCount: 8 },+ });+ assert.throws(+ () => estimateSemanticTakeTiming(narrative, excerpt, short, policy),+ /keep every Token visible and separated/u,+ );+});diff --git a/packages/semantic-track/README.md b/packages/semantic-track/README.mdindex 1dedad05..9438af0d 100644--- a/packages/semantic-track/README.md+++ b/packages/semantic-track/README.md@@ -6,6 +6,6 @@ their normalized local frame counts. There are no gap items or empty items. A Taaudio or only visual media; only its word array may be empty. Visual placement is deliberately notpart of this semantic truth.-The package exposes pure projections to `ProgramSpace`, `VisualTrack` and `AudioTrack`, plus the+The package exposes pure projections to `ProgramSpace` and `AudioTrack`, plus theselection/segment/moment lookup functions used by semantic components. It performs no media I/O,mixing, transcription or rendering.diff --git a/packages/semantic-track/src/component.ts b/packages/semantic-track/src/component.tsindex 8428b413..65c1319b 100644--- a/packages/semantic-track/src/component.ts+++ b/packages/semantic-track/src/component.ts@@ -2,7 +2,8 @@ import type { ComponentPackage } from "@hypit/component-kit";import type { StoredValue } from "@hypit/protocol";import { canonicalize } from "@hypit/protocol";-import { semanticTrackProducers } from "./manifest.js";+import { semanticTrackProducers, semanticTrackTypes } from "./manifest.js";+import { assertSemanticTrackIdentity } from "./identity.js";import { projectSemanticAudioTrack, projectSemanticProgramSpace } from "./projection.js";import type { SemanticTrack } from "./types.js";@@ -16,4 +17,8 @@ export const semanticTrackComponent = {{ producer: semanticTrackProducers.projectProgramSpace, handler: ({ inputs }) => ({ outputs: { space: { kind: "inline", value: canonicalize(projectSemanticProgramSpace(track(inputs.track?.value))) } }, needs: {} }) },{ producer: semanticTrackProducers.projectAudio, handler: ({ inputs }) => ({ outputs: { audio: { kind: "inline", value: canonicalize(projectSemanticAudioTrack(track(inputs.track?.value))) } }, needs: {} }) },],+ validators: [{+ type: semanticTrackTypes.track,+ handler: ({ value }) => assertSemanticTrackIdentity(track(value)),+ }],} satisfies ComponentPackage;diff --git a/packages/semantic-track/src/identity.ts b/packages/semantic-track/src/identity.tsindex 41c6562b..05b01055 100644--- a/packages/semantic-track/src/identity.ts+++ b/packages/semantic-track/src/identity.ts@@ -9,13 +9,18 @@ export function sealSemanticTrack(value: SemanticTrack): SemanticTrack {}export function assertSemanticTrackIdentity(track: SemanticTrack): void {- if (!track.id.trim() || track.items.length === 0) throw new Error("SemanticTrack must contain at least one item.");+ if (!track.id.trim() || !track.narrativeId.trim() || track.items.length === 0) {+ throw new Error("SemanticTrack must have identities and contain at least one item.");+ }const segmentIds = new Set<string>();const tokenIds = new Set<string>();const anchorIds = new Set<string>();let frameRate: SemanticTrack["items"][number]["take"]["media"]["timeline"]["frameRate"] | undefined;for (const item of track.items) {assertSemanticTakeIdentity(item.take);+ if (item.take.narrativeId !== track.narrativeId) {+ throw new Error(`SemanticTrack ${track.id} mixes Narrative ${item.take.narrativeId} into ${track.narrativeId}.`);+ }const rate = item.take.media.timeline.frameRate;if (frameRate === undefined) frameRate = rate;else if (frameRate.numerator !== rate.numerator || frameRate.denominator !== rate.denominator) {@@ -29,6 +34,9 @@ export function assertSemanticTrackIdentity(track: SemanticTrack): void {tokenIds.add(token.tokenId);}for (const anchor of item.take.anchors) {+ if (anchor.identity === "program:start" || anchor.identity === "program:end") {+ throw new Error(`SemanticTake cannot declare reserved Program Anchor ${anchor.identity}.`);+ }if (anchorIds.has(anchor.identity)) throw new Error(`SemanticTrack repeats Anchor ${anchor.identity}.`);anchorIds.add(anchor.identity);}diff --git a/packages/semantic-track/src/index.ts b/packages/semantic-track/src/index.tsindex 64c1bdf3..adb93675 100644--- a/packages/semantic-track/src/index.ts+++ b/packages/semantic-track/src/index.ts@@ -1,6 +1,6 @@export { semanticTrackComponent } from "./component.js";export { assertSemanticTrackIdentity, sealSemanticTrack, semanticTrackFrameCount, semanticTrackSpans } from "./identity.js";-export { assertNarrativeMomentIdentity, assertNarrativeSelectionIdentity, momentFrame, segmentFrameSpan, selectionFrameSpan, tokenFrameSpan } from "./location.js";+export { assertNarrativeMomentIdentity, assertNarrativeSelectionIdentity, momentFrame, segmentFrameSpan, selectionFrameSpan, semanticAnchorFrames, tokenFrameSpan } from "./location.js";export { semanticTrackDependency, semanticTrackManifest, semanticTrackModuleRef, semanticTrackProducers, semanticTrackSchema, semanticTrackTypes } from "./manifest.js";export { projectSemanticAudioTrack, projectSemanticProgramSpace } from "./projection.js";export type * from "./types.js";diff --git a/packages/semantic-track/src/location.ts b/packages/semantic-track/src/location.tsindex 0658e328..6bfd633f 100644--- a/packages/semantic-track/src/location.ts+++ b/packages/semantic-track/src/location.ts@@ -1,19 +1,30 @@import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";-import { assertSemanticTrackIdentity, semanticTrackSpans } from "./identity.js";+import { assertSemanticTrackIdentity, semanticTrackFrameCount, semanticTrackSpans } from "./identity.js";import type { LocatedFrameSpan, SemanticTrack } from "./types.js";export function assertNarrativeSelectionIdentity(selection: NarrativeSelectionRef): void {- if (!selection.id || !selection.startAnchorId || !selection.endAnchorId) throw new Error("NarrativeSelection is invalid");+ if (!selection.narrativeId || !selection.id || !selection.startAnchorId || !selection.endAnchorId) throw new Error("NarrativeSelection is invalid");}export function assertNarrativeMomentIdentity(moment: NarrativeMomentRef): void {- if (!moment.id || !moment.anchorId) throw new Error("NarrativeMoment is invalid");+ if (!moment.narrativeId || !moment.id || !moment.anchorId) throw new Error("NarrativeMoment is invalid");}-function anchorFrames(track: SemanticTrack): ReadonlyMap<string, number> {- return new Map(semanticTrackSpans(track).flatMap(({ item, startFrame }) =>- item.take.anchors.map((anchor) => [anchor.identity, startFrame + anchor.frame] as const)));+function assertNarrativeOwner(track: SemanticTrack, narrativeId: string, label: string): void {+ if (narrativeId !== track.narrativeId) {+ throw new Error(`${label} belongs to Narrative ${narrativeId}, not SemanticTrack ${track.id}.`);+ }+}++export function semanticAnchorFrames(track: SemanticTrack): ReadonlyMap<string, number> {+ assertSemanticTrackIdentity(track);+ return new Map([+ ["program:start", 0] as const,+ ...semanticTrackSpans(track).flatMap(({ item, startFrame }) =>+ item.take.anchors.map((anchor) => [anchor.identity, startFrame + anchor.frame] as const)),+ ["program:end", semanticTrackFrameCount(track)] as const,+ ]);}function frameFor(frames: ReadonlyMap<string, number>, anchorId: string, owner: string): number {@@ -28,7 +39,8 @@ export function selectionFrameSpan(): LocatedFrameSpan {assertSemanticTrackIdentity(track);assertNarrativeSelectionIdentity(selection);- const frames = anchorFrames(track);+ assertNarrativeOwner(track, selection.narrativeId, `NarrativeSelection ${selection.id}`);+ const frames = semanticAnchorFrames(track);return {startFrame: frameFor(frames, selection.startAnchorId, `NarrativeSelection ${selection.id}`),endFrameExclusive: frameFor(frames, selection.endAnchorId, `NarrativeSelection ${selection.id}`),@@ -38,6 +50,7 @@ export function selectionFrameSpan(export function segmentFrameSpan(track: SemanticTrack, segment: NarrativeExcerpt): LocatedFrameSpan {assertSemanticTrackIdentity(track);if (segment.kind !== "segment" || !segment.id) throw new Error("Narrative Segment excerpt is invalid");+ assertNarrativeOwner(track, segment.narrativeId, `Narrative Segment ${segment.id}`);const found = semanticTrackSpans(track).find(({ item }) => item.take.segment.segmentId === segment.id);if (found === undefined) throw new Error(`SemanticTrack does not contain Segment ${segment.id}.`);return { startFrame: found.startFrame, endFrameExclusive: found.endFrameExclusive };@@ -62,6 +75,7 @@ export function tokenFrameSpan(track: SemanticTrack, tokenIds: readonly string[]export function momentFrame(track: SemanticTrack, moment: NarrativeMomentRef): number {assertSemanticTrackIdentity(track);assertNarrativeMomentIdentity(moment);- const frames = anchorFrames(track);+ assertNarrativeOwner(track, moment.narrativeId, `NarrativeMoment ${moment.id}`);+ const frames = semanticAnchorFrames(track);return frameFor(frames, moment.anchorId, `NarrativeMoment ${moment.id}`);}diff --git a/packages/semantic-track/src/manifest.ts b/packages/semantic-track/src/manifest.tsindex 6dd81b6c..a47eceb0 100644--- a/packages/semantic-track/src/manifest.ts+++ b/packages/semantic-track/src/manifest.ts@@ -17,6 +17,7 @@ const string = { kind: "string", minLength: 1 } as const;const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });export const semanticTrackSchema: ValueSchema = object({id: { schema: string },+ narrativeId: { schema: string },items: { schema: { kind: "array", minItems: 1, items: object({take: { schema: semanticTakeSchema },}) } },diff --git a/packages/semantic-track/src/projection.ts b/packages/semantic-track/src/projection.tsindex 32813082..1fac68de 100644--- a/packages/semantic-track/src/projection.ts+++ b/packages/semantic-track/src/projection.ts@@ -14,6 +14,8 @@ export function projectSemanticProgramSpace(track: SemanticTrack): ProgramSpaceassertSemanticTrackIdentity(track);const frameRate = track.items[0]!.take.media.timeline.frameRate;return sealProgramSpace({+ id: track.id,+ narrativeId: track.narrativeId,durationSec: semanticTrackFrameCount(track) * frameRate.denominator / frameRate.numerator,frameRate,});@@ -46,5 +48,5 @@ export function projectSemanticAudioTrack(track: SemanticTrack): AudioTrack {fadeOutSamples: 0,}];});- return sealAudioTrack({ id: `${track.id}:audio`, clips });+ return sealAudioTrack({ programSpaceId: space.id, id: `${track.id}:audio`, clips });}diff --git a/packages/semantic-track/src/types.ts b/packages/semantic-track/src/types.tsindex 8398a3e4..e3ccf79d 100644--- a/packages/semantic-track/src/types.ts+++ b/packages/semantic-track/src/types.ts@@ -10,6 +10,7 @@ export type SemanticTrackItem = {*/export type SemanticTrack = {readonly id: string;+ readonly narrativeId: string;readonly items: readonly SemanticTrackItem[];};diff --git a/packages/speech-alignment/src/local.ts b/packages/speech-alignment/src/local.tsindex f40a839f..7ad62e3e 100644--- a/packages/speech-alignment/src/local.ts+++ b/packages/speech-alignment/src/local.ts@@ -1,12 +1,12 @@import type { SynchronizedMedia } from "@hypit/media";import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";import { sealProgramSpace } from "@hypit/program-space";+import { materializeSemanticTake } from "@hypit/speech";import type { SemanticTake } from "@hypit/speech";import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";import { locateAlignedSegmentTiming } from "./locate.js";import type { AlignmentBasis } from "./locate.js";-import { materializeSemanticTake } from "./materialize.js";function segmentNarrative(narrative: Narrative, excerpt: NarrativeExcerpt): Narrative {if (excerpt.kind !== "segment") throw new Error("SemanticTake alignment requires a Segment excerpt.");@@ -17,6 +17,7 @@ function segmentNarrative(narrative: Narrative, excerpt: NarrativeExcerpt): Narr}const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive);return {+ id: narrative.id,segments: [{ ...segment, tokenStart: 0, tokenEndExclusive: tokens.length }],tokens,turns: narrative.turns@@ -44,6 +45,8 @@ export function alignSemanticTake(if (media.audio === undefined) throw new Error(`SemanticTake ${excerpt.id} has no normalized audio.`);const localNarrative = segmentNarrative(narrative, excerpt);const programSpace = sealProgramSpace({+ id: `${excerpt.narrativeId}.segment.${excerpt.id}`,+ narrativeId: excerpt.narrativeId,durationSec: media.timeline.frameCount * media.timeline.frameRate.denominator/ media.timeline.frameRate.numerator,frameRate: media.timeline.frameRate,diff --git a/packages/speech-alignment/src/locate.ts b/packages/speech-alignment/src/locate.tsindex d9c3e5fc..027fd3ed 100644--- a/packages/speech-alignment/src/locate.ts+++ b/packages/speech-alignment/src/locate.ts@@ -3,6 +3,7 @@ import type { BlobRef } from "@hypit/protocol";import type { Narrative, NarrativeToken } from "@hypit/narrative";import { programFrameSampleBoundary, programSpaceFrameCount } from "@hypit/program-space";import type { ProgramSpace } from "@hypit/program-space";+import type { SemanticTakeTimedToken, SemanticTakeTiming } from "@hypit/speech";import type {AlignedTranscriptEvidence,SpeechActivitySpan,@@ -16,20 +17,9 @@ import { SpeechAlignmentError } from "./error.js";import { alignCharacters, alignmentCharacters } from "./normalize.js";import type { AlignmentGroup, TimedSpeechSegment } from "./types.js";-export type LocalTimedSpeechToken = {- readonly tokenId: string;- readonly segmentId: string;- readonly startFrame: number;- readonly endFrameExclusive: number;-};--export type LocalSemanticTimePoint = { readonly identity: string; readonly frame: number };--/** Private alignment result used only to materialize one SemanticTake. */-export type LocalSemanticTiming = {- readonly tokens: readonly LocalTimedSpeechToken[];- readonly anchors: readonly LocalSemanticTimePoint[];-};+export type LocalTimedSpeechToken = SemanticTakeTimedToken;+export type LocalSemanticTimePoint = SemanticTakeTiming["anchors"][number];+export type LocalSemanticTiming = SemanticTakeTiming;/** Package-private clock used while aligning exactly one normalized Segment Take. */export type AlignmentBasis = {@@ -465,17 +455,19 @@ export function locateAlignedSegmentTiming(const tokensById = new Map(timedTokens.map((token) => [token.tokenId, token]));const segmentsById = new Map(timedSegments.map((segment) => [segment.segmentId, segment]));- const anchors: LocalSemanticTimePoint[] = narrative.semanticIndex.anchors.map((anchor) => {+ const anchors: LocalSemanticTimePoint[] = narrative.semanticIndex.anchors.flatMap((anchor): LocalSemanticTimePoint[] => {+ // Program boundaries belong to the assembled SemanticTrack, never to one Segment-local Take.+ if (anchor.kind === "program-start" || anchor.kind === "program-end") return [];if (anchor.kind === "segment-start" || anchor.kind === "segment-end") {const segment = segmentsById.get(anchor.segmentId)!;- return anchor.kind === "segment-start"+ return [anchor.kind === "segment-start"? { identity: anchor.id, frame: segment.startFrame }- : { identity: anchor.id, frame: segment.endFrameExclusive };+ : { identity: anchor.id, frame: segment.endFrameExclusive }];}const token = tokensById.get(anchor.tokenId!)!;- return anchor.kind === "token-start"+ return [anchor.kind === "token-start"? { identity: anchor.id, frame: token.startFrame }- : { identity: anchor.id, frame: token.endFrameExclusive };+ : { identity: anchor.id, frame: token.endFrameExclusive }];});return { tokens: timedTokens, anchors };}diff --git a/packages/speech-alignment/test/speech-align.test.ts b/packages/speech-alignment/test/speech-align.test.tsindex 0b68a538..c307dc41 100644--- a/packages/speech-alignment/test/speech-align.test.ts+++ b/packages/speech-alignment/test/speech-align.test.ts@@ -1,13 +1,13 @@import type { Narrative } from "@hypit/narrative";import { sealProgramSpace } from "@hypit/program-space";-import { materializeSemanticTake } from "../src/materialize.js";+import { materializeSemanticTake } from "@hypit/speech";import { sealAlignedTranscriptEvidence } from "@hypit/speech-evidence";import type { AlignedTranscriptEvidence, SpeechCharacterEvidence, SpeechWordEvidence } from "@hypit/speech-evidence";import assert from "node:assert/strict";import test from "node:test";import { fixtureDigest } from "../../../test/fixture-digest.js";-import { parseScript } from "@hypit/script";+import { narrativeValue, parseScript as parseScriptSource } from "@hypit/script";import {SpeechAlignmentError,alignWordGroups,@@ -22,6 +22,10 @@ type WordFixture = {readonly score?: number;};+function parseScript(sourceName: string, source: string): Narrative {+ return narrativeValue(parseScriptSource(sourceName, source), "test-narrative") as unknown as Narrative;+}+function wordEvidence(word: WordFixture): SpeechWordEvidence {return {text: word.text,@@ -77,7 +81,7 @@ function speechBasis(durationSec = 2,): AlignmentBasis {if (narrative.segments.length !== 1) throw new Error("Test alignment requires one Segment.");- const programSpace = sealProgramSpace({+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec,frameRate: { numerator: 1_000, denominator: 1 },});@@ -150,7 +154,7 @@ test("a measured Segment-local map becomes a self-contained SemanticTake", () =>const segment = narrative.segments[0]!;const take = materializeSemanticTake(narrative,- { kind: "segment", id: segment.id, tokenStart: segment.tokenStart, tokenEndExclusive: segment.tokenEndExclusive },+ { narrativeId: narrative.id, kind: "segment", id: segment.id, tokenStart: segment.tokenStart, tokenEndExclusive: segment.tokenEndExclusive },{timeline: { frameRate: { numerator: 1_000, denominator: 1 }, frameCount: 2_000 },visual: { artifact: { kind: "blob", digest: fixtureDigest("materialize:video"), size: 1, mediaType: "video/mp4" }, width: 720, height: 1280 },@@ -323,7 +327,7 @@ test("a collapsed WhisperX word is assigned the available interval between its ntest("three Script words may share the two video frames covered by one evidence word", () => {const narrative = parseScript("pigeonhole.svml", "<line>alpha beta gamma</line>");const original = speechBasis(narrative, 1);- const programSpace = sealProgramSpace({+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 1,frameRate: { numerator: 32, denominator: 1 },});@@ -350,7 +354,7 @@ test("Evidence is interpreted only through the explicitly connected alignment clbasis,words: [{ text: "Hello", startSec: 0.1, endSec: 0.4 }, { text: "world", startSec: 0.5, endSec: 0.9 }],});- const anotherSpace = sealProgramSpace({+ const anotherSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 2,frameRate: { numerator: 30, denominator: 1 },});@@ -366,7 +370,7 @@ test("Evidence is interpreted only through the explicitly connected alignment cltest("the final map is quantized once into the selected ProgramSpace", () => {const narrative = parseScript("frames.svml", "<line>Hello.</line>");const original = speechBasis(narrative, 1);- const programSpace = sealProgramSpace({+ const programSpace = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 1,frameRate: { numerator: 30, denominator: 1 },});diff --git a/packages/speech-track/src/program.ts b/packages/speech-track/src/program.tsindex 17d3d970..1f624e91 100644--- a/packages/speech-track/src/program.ts+++ b/packages/speech-track/src/program.ts@@ -121,8 +121,12 @@ export function assembleSpeechTrack(assertSpeechTrackSet(set);assert(set.takes.length > 0, "Speech Track must contain at least one Take");for (const take of set.takes) assertTake(take);+ const narrativeId = set.takes[0]!.semantic.narrativeId;+ assert(set.takes.every((take) => take.semantic.narrativeId === narrativeId),+ "Speech Track cannot mix Takes from different Narratives");return sealSemanticTrack({id: header.id,+ narrativeId,items: set.takes.map((item) => ({ take: item.semantic })),});}diff --git a/packages/speech-track/src/projection.ts b/packages/speech-track/src/projection.tsindex 31edfba3..9d2ef9e1 100644--- a/packages/speech-track/src/projection.ts+++ b/packages/speech-track/src/projection.ts@@ -14,6 +14,7 @@ export function projectSpeechTrackVisual(track: SemanticTrack, set: SpeechTrackS? []: [[item.semantic.segment.segmentId, item.visual] as const]));return sealVisualTrack({+ programSpaceId: space.id,visualIr: "hypit.visual-ir@1",id: trackId,presents: lowerRestrictedSpeechVisualPresents(diff --git a/packages/speech-track/test/program.test.ts b/packages/speech-track/test/program.test.tsindex d3860f26..e08e8410 100644--- a/packages/speech-track/test/program.test.ts+++ b/packages/speech-track/test/program.test.ts@@ -33,6 +33,7 @@ function semantic(id: string, visual: boolean): SemanticTake {audio: { artifact: { kind: "blob", digest: fixtureDigest(`${id}:audio`), size: 1, mediaType: "audio/wav" } },};return {+ narrativeId: "test-narrative",media,segment: {segmentId: id,diff --git a/packages/speech-track/test/surface.test.ts b/packages/speech-track/test/surface.test.tsindex ebdc002d..8d6ca9e3 100644--- a/packages/speech-track/test/surface.test.ts+++ b/packages/speech-track/test/surface.test.ts@@ -10,6 +10,7 @@ import { svsRecipeType } from "@hypit/svs";import { decodeSpeechTrackSurface } from "@hypit/speech-track";const take: SemanticTake = {+ narrativeId: "test-narrative",media: {timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },visual: {diff --git a/packages/speech/package.json b/packages/speech/package.jsonindex 92a8cc29..e6576251 100644--- a/packages/speech/package.json+++ b/packages/speech/package.json@@ -11,7 +11,9 @@"activation": "./src/activation.ts"},"dependencies": {+ "@hypit/component-kit": "workspace:*","@hypit/media": "workspace:*",+ "@hypit/narrative": "workspace:*","@hypit/protocol": "workspace:*"}}diff --git a/packages/speech/src/activation.ts b/packages/speech/src/activation.tsindex a98b2e6b..9ef49130 100644--- a/packages/speech/src/activation.ts+++ b/packages/speech/src/activation.ts@@ -1,3 +1,7 @@-import { speechManifest } from "./index.js";-export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: speechManifest }] };+import { speechComponent, speechManifest } from "./index.js";+export const hypitPackage = {+ format: "hypit.node-package@1" as const,+ modules: [{ manifest: speechManifest }],+ components: [speechComponent],+};export default hypitPackage;diff --git a/packages/speech/src/component.ts b/packages/speech/src/component.tsnew file mode 100644index 00000000..ccfa13bf--- /dev/null+++ b/packages/speech/src/component.ts@@ -0,0 +1,23 @@+import type { ComponentPackage } from "@hypit/component-kit";+import type { StoredValue } from "@hypit/protocol";++import {+ assertSemanticTakeIdentity,+ assertSpeechDurationIdentity,+ assertSpeechEvidenceAudioIdentity,+} from "./identity.js";+import { speechTypes } from "./manifest.js";+import type { SemanticTake, SpeechDuration, SpeechEvidenceAudio } from "./types.js";++function inline<T>(value: StoredValue, subject: string): T {+ if (value.kind !== "inline") throw new Error(`${subject} must be inline.`);+ return value.value as T;+}++export const speechComponent = {+ validators: [+ { type: speechTypes.duration, handler: ({ value }) => assertSpeechDurationIdentity(inline<SpeechDuration>(value, "SpeechDuration")) },+ { type: speechTypes.evidenceAudio, handler: ({ value }) => assertSpeechEvidenceAudioIdentity(inline<SpeechEvidenceAudio>(value, "SpeechEvidenceAudio")) },+ { type: speechTypes.semanticTake, handler: ({ value }) => assertSemanticTakeIdentity(inline<SemanticTake>(value, "SemanticTake")) },+ ],+} satisfies ComponentPackage;diff --git a/packages/speech/src/identity.ts b/packages/speech/src/identity.tsindex c581dc12..a83365f2 100644--- a/packages/speech/src/identity.ts+++ b/packages/speech/src/identity.ts@@ -13,9 +13,14 @@ export function speechEvidenceSampleBoundary(masterSampleBoundary: number): numb}export function sealSpeechEvidenceAudio(value: SpeechEvidenceAudio): SpeechEvidenceAudio { return structuredClone(value); }-export function sealSemanticTake(value: SemanticTake): SemanticTake { return structuredClone(value); }+export function sealSemanticTake(value: SemanticTake): SemanticTake {+ const take = structuredClone(value);+ assertSemanticTakeIdentity(take);+ return take;+}export function assertSemanticTakeIdentity(take: SemanticTake): void {+ if (!take.narrativeId.trim()) throw new Error("SemanticTake narrativeId must not be empty.");verifySynchronizedMedia(take.media);const frameCount = take.media.timeline.frameCount;const { segment } = take;@@ -23,30 +28,40 @@ export function assertSemanticTakeIdentity(take: SemanticTake): void {|| segment.startFrame !== 0 || segment.endFrameExclusive !== frameCount) {throw new Error("SemanticTake Segment must cover its local media frame domain.");}+ const anchorIds = new Set<string>();+ const anchorFrames = new Map<string, number>();+ for (const anchor of take.anchors) {+ if (!anchor.identity || anchorIds.has(anchor.identity) || !Number.isSafeInteger(anchor.frame)+ || anchor.frame < 0 || anchor.frame > frameCount) {+ throw new Error(`SemanticTake anchor ${anchor.identity || "<unnamed>"} is invalid.`);+ }+ anchorIds.add(anchor.identity);+ anchorFrames.set(anchor.identity, anchor.frame);+ }+ if (anchorFrames.get(segment.startAnchorId) !== 0+ || anchorFrames.get(segment.endAnchorId) !== frameCount) {+ throw new Error("SemanticTake Segment Anchors must equal its media boundaries.");+ }const tokenIds = new Set<string>();- const referencedAnchorIds = new Set<string>([segment.startAnchorId, segment.endAnchorId]);+ let previousStart = 0;+ let previousEnd = 0;for (const token of take.tokens) {if (!token.tokenId || !token.segmentId || token.segmentId !== segment.segmentId || !token.text|| !token.startAnchorId || !token.endAnchorId || tokenIds.has(token.tokenId)|| !Number.isSafeInteger(token.startFrame) || !Number.isSafeInteger(token.endFrameExclusive)|| token.startFrame < 0 || token.endFrameExclusive < 0- || token.startFrame > frameCount || token.endFrameExclusive > frameCount) {+ || token.startFrame > token.endFrameExclusive+ || token.startFrame > frameCount || token.endFrameExclusive > frameCount+ || token.startFrame < previousStart || token.endFrameExclusive < previousEnd) {throw new Error(`SemanticTake token ${token.tokenId || "<unnamed>"} is invalid.`);}- referencedAnchorIds.add(token.startAnchorId);- referencedAnchorIds.add(token.endAnchorId);- tokenIds.add(token.tokenId);- }- const anchorIds = new Set<string>();- for (const anchor of take.anchors) {- if (!anchor.identity || anchorIds.has(anchor.identity) || !Number.isSafeInteger(anchor.frame)- || anchor.frame < 0 || anchor.frame > frameCount) {- throw new Error(`SemanticTake anchor ${anchor.identity || "<unnamed>"} is invalid.`);+ if (anchorFrames.get(token.startAnchorId) !== token.startFrame+ || anchorFrames.get(token.endAnchorId) !== token.endFrameExclusive) {+ throw new Error(`SemanticTake token ${token.tokenId} disagrees with its Anchors.`);}- anchorIds.add(anchor.identity);- }- for (const anchorId of referencedAnchorIds) {- if (!anchorIds.has(anchorId)) throw new Error(`SemanticTake is missing referenced Anchor ${anchorId}.`);+ tokenIds.add(token.tokenId);+ previousStart = token.startFrame;+ previousEnd = token.endFrameExclusive;}}export function assertSpeechEvidenceAudioIdentity(value: SpeechEvidenceAudio): void {diff --git a/packages/speech/src/index.ts b/packages/speech/src/index.tsindex c48d94fa..aead4563 100644--- a/packages/speech/src/index.ts+++ b/packages/speech/src/index.ts@@ -1,4 +1,6 @@export { assertSemanticTakeIdentity, assertSpeechDurationIdentity, assertSpeechEvidenceAudioIdentity, sealSemanticTake, sealSpeechDuration, sealSpeechEvidenceAudio, speechEvidenceSampleBoundary } from "./identity.js";+export { speechComponent } from "./component.js";+export { materializeSemanticTake } from "./materialize.js";export { speechDependency, speechManifest, speechModuleRef, speechTypes } from "./manifest.js";export { semanticTakeSchema, speechDurationSchema, speechEvidenceAudioSchema } from "./schema.js";export type * from "./types.js";diff --git a/packages/speech-alignment/src/materialize.ts b/packages/speech/src/materialize.tssimilarity index 69%rename from packages/speech-alignment/src/materialize.tsrename to packages/speech/src/materialize.tsindex 330cee83..afb3b834 100644--- a/packages/speech-alignment/src/materialize.ts+++ b/packages/speech/src/materialize.ts@@ -1,11 +1,13 @@-import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";import type { SynchronizedMedia } from "@hypit/media";-import type { SemanticTake } from "@hypit/speech";-import { assertSemanticTakeIdentity, sealSemanticTake } from "@hypit/speech";+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";-import type { LocalSemanticTiming } from "./locate.js";+import { assertSemanticTakeIdentity, sealSemanticTake } from "./identity.js";+import type { SemanticTake, SemanticTakeTiming } from "./types.js";function authoredSegment(narrative: Narrative, excerpt: NarrativeExcerpt): Narrative["segments"][number] {+ if (narrative.id !== excerpt.narrativeId) {+ throw new Error(`NarrativeExcerpt ${excerpt.id} belongs to Narrative ${excerpt.narrativeId}, not ${narrative.id}.`);+ }if (excerpt.kind !== "segment") throw new Error("SemanticTake materialization requires a Segment excerpt.");const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id);if (segment === undefined) throw new Error(`Narrative does not contain Segment ${excerpt.id}.`);@@ -23,13 +25,14 @@ function localFrame(frame: number, frameCount: number, label: string): number {}/**- * Copy one Segment-local alignment into a self-contained semantic Take.+ * Copy one Segment-local timing result into a self-contained semantic Take.+ * How the timing was obtained remains the caller's explicit package meaning.*/export function materializeSemanticTake(narrative: Narrative,excerpt: NarrativeExcerpt,media: SynchronizedMedia,- timing: LocalSemanticTiming,+ timing: SemanticTakeTiming,): SemanticTake {const segment = authoredSegment(narrative, excerpt);const localFrameCount = media.timeline.frameCount;@@ -37,16 +40,19 @@ export function materializeSemanticTake(const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive).map((token) => {const timed = timedById.get(token.id);if (timed === undefined || timed.segmentId !== segment.id) {- throw new Error(`Semantic map does not locate authored Token ${token.id}.`);+ throw new Error(`Semantic timing does not locate authored Token ${token.id}.`);}+ const startFrame = localFrame(timed.startFrame, localFrameCount, `Token ${token.id}`);+ const endFrameExclusive = localFrame(timed.endFrameExclusive, localFrameCount, `Token ${token.id}`);+ if (endFrameExclusive <= startFrame) throw new Error(`Token ${token.id} has an empty or reversed frame window.`);return {tokenId: token.id,segmentId: segment.id,text: token.text,startAnchorId: token.startAnchorId,endAnchorId: token.endAnchorId,- startFrame: localFrame(timed.startFrame, localFrameCount, `Token ${token.id}`),- endFrameExclusive: localFrame(timed.endFrameExclusive, localFrameCount, `Token ${token.id}`),+ startFrame,+ endFrameExclusive,};});const anchorsById = new Map(timing.anchors.map((anchor) => [anchor.identity, anchor]));@@ -54,13 +60,14 @@ export function materializeSemanticTake(.filter((anchor) => anchor.segmentId === segment.id).map((anchor) => {const measured = anchorsById.get(anchor.id);- if (measured === undefined) throw new Error(`Semantic map does not locate authored Anchor ${anchor.id}.`);+ if (measured === undefined) throw new Error(`Semantic timing does not locate authored Anchor ${anchor.id}.`);return {identity: anchor.id,frame: localFrame(measured.frame, localFrameCount, `Anchor ${anchor.id}`),};});const take = sealSemanticTake({+ narrativeId: narrative.id,media,segment: {segmentId: segment.id,diff --git a/packages/speech/src/schema.ts b/packages/speech/src/schema.tsindex ca48a0c0..c8a1731f 100644--- a/packages/speech/src/schema.ts+++ b/packages/speech/src/schema.ts@@ -34,6 +34,7 @@ export const speechEvidenceAudioSchema: ValueSchema = object({sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } },});export const semanticTakeSchema: ValueSchema = object({+ narrativeId: { schema: string },media: { schema: synchronizedMediaSchema },segment: { schema: semanticTakeSegment },tokens: { schema: { kind: "array", items: semanticTakeToken } },diff --git a/packages/speech/src/types.ts b/packages/speech/src/types.tsindex 0394fc91..d55d8a0b 100644--- a/packages/speech/src/types.ts+++ b/packages/speech/src/types.ts@@ -25,6 +25,8 @@ export type SemanticTakeToken = {* coordinates travel with this Take instead of requiring a second Script edge.*/export type SemanticTake = {+ /** Author-visible Script identity carried through every semantic projection. */+ readonly narrativeId: string;readonly media: SynchronizedMedia;readonly segment: {readonly segmentId: string;@@ -36,3 +38,17 @@ export type SemanticTake = {readonly tokens: readonly SemanticTakeToken[];readonly anchors: readonly { readonly identity: string; readonly frame: number }[];};++/** One authored Token located in a Segment-local frame domain. */+export type SemanticTakeTimedToken = {+ readonly tokenId: string;+ readonly segmentId: string;+ readonly startFrame: number;+ readonly endFrameExclusive: number;+};++/** Provider measurement and preview estimation both materialize through this narrow timing waist. */+export type SemanticTakeTiming = {+ readonly tokens: readonly SemanticTakeTimedToken[];+ readonly anchors: readonly { readonly identity: string; readonly frame: number }[];+};diff --git a/packages/speech/test/evidence.test.ts b/packages/speech/test/evidence.test.tsindex 0df20619..fa991a5c 100644--- a/packages/speech/test/evidence.test.ts+++ b/packages/speech/test/evidence.test.ts@@ -11,7 +11,7 @@ test("speech evidence uses integer rational boundary projection rather than floaassert.equal(speechEvidenceSampleBoundary(480_000), 160_000);assert.equal(speechEvidenceSampleBoundary(480_001), 160_000);assert.equal(speechEvidenceSampleBoundary(480_002), 160_001);- const ntsc = sealProgramSpace({+ const ntsc = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 1.001,frameRate: { numerator: 30_000, denominator: 1_001 },});diff --git a/packages/speech/test/identity.test.ts b/packages/speech/test/identity.test.tsnew file mode 100644index 00000000..118f3b08--- /dev/null+++ b/packages/speech/test/identity.test.ts@@ -0,0 +1,36 @@+import assert from "node:assert/strict";+import test from "node:test";++import { assertSemanticTakeIdentity } from "@hypit/speech";++test("SemanticTake rejects Token frames that disagree with authored Anchors", () => {+ assert.throws(() => assertSemanticTakeIdentity({+ narrativeId: "story",+ media: {+ timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },+ audio: {+ artifact: {+ kind: "blob",+ digest: `sha256:${"0".repeat(64)}`,+ size: 1,+ mediaType: "audio/wav",+ },+ },+ },+ segment: {+ segmentId: "intro", startAnchorId: "intro:start", endAnchorId: "intro:end",+ startFrame: 0, endFrameExclusive: 30,+ },+ tokens: [{+ tokenId: "hello", segmentId: "intro", text: "hello",+ startAnchorId: "hello:start", endAnchorId: "hello:end",+ startFrame: 4, endFrameExclusive: 10,+ }],+ anchors: [+ { identity: "intro:start", frame: 0 },+ { identity: "hello:start", frame: 3 },+ { identity: "hello:end", frame: 10 },+ { identity: "intro:end", frame: 30 },+ ],+ }), /disagrees with its Anchors/u);+});diff --git a/packages/temporal-markup/package.json b/packages/temporal-markup/package.jsonnew file mode 100644index 00000000..dc7a2bb4--- /dev/null+++ b/packages/temporal-markup/package.json@@ -0,0 +1,17 @@+{+ "name": "@hypit/temporal-markup",+ "version": "0.0.0-dev",+ "license": "SEE LICENSE IN LICENSE",+ "private": true,+ "type": "module",+ "exports": {+ ".": "./src/index.ts"+ },+ "dependencies": {+ "@hypit/elaborator": "workspace:*",+ "@hypit/markup": "workspace:*",+ "@hypit/narrative": "workspace:*",+ "@hypit/semantic-track": "workspace:*",+ "@hypit/temporal": "workspace:*"+ }+}diff --git a/packages/temporal-markup/src/index.ts b/packages/temporal-markup/src/index.tsnew file mode 100644index 00000000..b606e8f3--- /dev/null+++ b/packages/temporal-markup/src/index.ts@@ -0,0 +1,523 @@+import { sealGraphFragment } from "@hypit/elaborator";+import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";+import type {+ MarkupAttributeValue,+ StructuredElement,+ SurfaceComponentDraft,+ SurfaceAttributeVocabulary,+ SurfaceRecordDraft,+ SurfaceResolvedReference,+} from "@hypit/markup";+import { narrativeTypes } from "@hypit/narrative";+import { semanticTrackTypes } from "@hypit/semantic-track";+import {+ temporalProducers,+ temporalTypes,+} from "@hypit/temporal";+import type {+ TemporalDuration,+ TemporalInstantAuthority,+ TemporalInstantExpression,+} from "@hypit/temporal";++type ResolveReference = (path: string) => SurfaceResolvedReference | undefined;+type SourceKind = "program" | "selection" | "segment" | "moment";++/** Complete author vocabulary for one Window consumer. Domain packages may only add non-time fields. */+export const temporalWindowAttributeVocabulary: readonly SurfaceAttributeVocabulary[] = [+ { name: "during", kind: "expression", required: false, values: ["program"],+ accepts: [narrativeTypes.selection, narrativeTypes.excerpt],+ summary: "Uses the whole Program, or the exact window of a referenced Selection or Segment." },+ { name: "at", kind: "reference", required: false, accepts: [narrativeTypes.moment],+ summary: "Uses a semantic Moment as the start authority; write it together with for." },+ { name: "until", kind: "reference", required: false, accepts: [narrativeTypes.moment],+ summary: "Uses a semantic Moment as the end authority; write it together with for." },+ { name: "for", kind: "literal", required: false,+ summary: "Sets the projected duration paired with at or until, such as 12f, 250ms or 1.5s." },+ { name: "start", kind: "literal", required: false,+ summary: "Sets a projected start expression; write it together with end." },+ { name: "end", kind: "literal", required: false,+ summary: "Sets a projected end expression; write it together with start." },+ { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection],+ summary: "Resolves selection.start or selection.end used by a projected start/end expression." },+ { name: "segment", kind: "reference", required: false, accepts: [narrativeTypes.excerpt],+ summary: "Resolves segment.start or segment.end used by a projected start/end expression." },+ { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment],+ summary: "Resolves moment.cue used by a projected start/end expression." },+];+export const temporalWindowAttributeNames = temporalWindowAttributeVocabulary.map(({ name }) => name);++/** Complete author vocabulary for a semantic or explicitly projected Instant. */+export const temporalInstantAttributeVocabulary: readonly SurfaceAttributeVocabulary[] = [+ { name: "at", kind: "reference", required: false,+ accepts: [narrativeTypes.moment, narrativeTypes.selection, narrativeTypes.excerpt],+ summary: "Uses a semantic Moment or a chosen Selection or Segment boundary as the Instant authority." },+ { name: "instant", kind: "literal", required: false,+ summary: "Uses an explicitly projected point expression when no semantic point owns the timing." },+ { name: "boundary", kind: "literal", required: false, values: ["start", "end"],+ summary: "Chooses the start or end boundary when at references a Selection or Segment." },+ { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection],+ summary: "Resolves selection.start or selection.end used by an instant expression." },+ { name: "segment", kind: "reference", required: false, accepts: [narrativeTypes.excerpt],+ summary: "Resolves segment.start or segment.end used by an instant expression." },+ { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment],+ summary: "Resolves moment.cue used by an instant expression." },+];+export const temporalInstantAttributeNames = temporalInstantAttributeVocabulary.map(({ name }) => name);++function rejectUnusedTemporalAttributes(+ element: StructuredElement,+ universe: readonly string[],+ allowed: readonly string[],+): void {+ const accepted = new Set(allowed);+ const unused = universe.filter((name) => element.attributes[name] !== undefined && !accepted.has(name));+ if (unused.length > 0) {+ throw new Error(`${element.name} timing form does not accept ${unused.join(", ")}.`);+ }+}++type InstantDraft = {+ readonly expression: TemporalInstantExpression;+ readonly authority: TemporalInstantAuthority;+ readonly source: SourceKind;+ readonly reference?: SurfaceResolvedReference;+};++export type TemporalMarkupProjection = {+ readonly records: readonly SurfaceRecordDraft[];+ readonly components: readonly SurfaceComponentDraft[];+ readonly fragments: readonly GraphFragment[];+ readonly ref: { readonly kind: "component-output"; readonly component: string; readonly output: string };+};++function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {+ return left.module.name === right.module.name+ && left.module.version === right.module.version+ && left.name === right.name;+}++function resolve(+ raw: MarkupAttributeValue | undefined,+ label: string,+ expected: SurfaceResolvedReference["type"],+ resolveReference: ResolveReference,+): SurfaceResolvedReference {+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);+ const found = resolveReference(raw.path);+ if (found === undefined || !sameType(found.type, expected)) throw new Error(`${label} has the wrong Type.`);+ return found;+}++function resolveDuring(+ raw: MarkupAttributeValue,+ label: string,+ resolveReference: ResolveReference,+): { readonly kind: "selection" | "segment"; readonly reference: SurfaceResolvedReference } {+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be program or a reference.`);+ const found = resolveReference(raw.path);+ if (found !== undefined && sameType(found.type, narrativeTypes.selection)) {+ return { kind: "selection", reference: found };+ }+ if (found !== undefined && sameType(found.type, narrativeTypes.excerpt)) {+ return { kind: "segment", reference: found };+ }+ throw new Error(`${label} must reference a Selection or Segment.`);+}++function optionalText(element: StructuredElement, name: string): string | undefined {+ const value = element.attributes[name];+ if (value === undefined) return undefined;+ if (typeof value !== "string" || value.trim().length === 0) {+ throw new Error(`${element.name}.${name} must be text.`);+ }+ return value.trim();+}++function text(element: StructuredElement, name: string): string {+ const found = optionalText(element, name);+ if (found === undefined) throw new Error(`${element.name}.${name} is required.`);+ return found;+}++function divisor(left: number, right: number): number {+ let a = Math.abs(left);+ let b = Math.abs(right);+ while (b !== 0) [a, b] = [b, a % b];+ return a;+}++export function parseTemporalDuration(value: string, label: string): TemporalDuration {+ const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());+ if (match === null) throw new Error(`${label} must be an exact duration such as 12f, 250ms or 1.5s.`);+ const whole = Number(match[1]);+ const fraction = match[2] ?? "";+ const unit = match[3];+ if (!Number.isSafeInteger(whole)) throw new Error(`${label} is outside safe arithmetic.`);+ if (unit === "f" || unit === "ms") {+ if (fraction.length > 0) throw new Error(`${label} ${unit} duration must be an integer.`);+ return { unit: unit === "f" ? "frames" : "milliseconds", value: whole };+ }+ const scale = 10 ** fraction.length;+ const numerator = whole * scale + (fraction.length === 0 ? 0 : Number(fraction));+ if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(scale)) {+ throw new Error(`${label} is outside safe arithmetic.`);+ }+ const gcd = divisor(numerator, scale);+ return { unit: "seconds", numerator: numerator / gcd, denominator: scale / gcd };+}++function negate(value: TemporalDuration): TemporalDuration {+ return value.unit === "seconds"+ ? { ...value, numerator: -value.numerator }+ : { ...value, value: -value.value };+}++export function parseTemporalInstant(value: string, label: string): TemporalInstantExpression {+ const trimmed = value.trim();+ const refs = [+ "program.start", "program.end", "selection.start", "selection.end",+ "segment.start", "segment.end", "moment.cue",+ ] as const;+ for (const ref of refs) {+ if (trimmed === ref) return { ref };+ const escaped = ref.replace(".", "\\.");+ const match = new RegExp(`^${escaped}\\s*([+-])\\s*(.+)$`, "u").exec(trimmed);+ if (match !== null) {+ const offset = parseTemporalDuration(match[2]!, `${label} offset`);+ return { ref, offset: match[1] === "-" ? negate(offset) : offset };+ }+ }+ return { ref: "absolute", at: parseTemporalDuration(trimmed, label) };+}++function expressionSource(expression: TemporalInstantExpression): SourceKind {+ if (expression.ref.startsWith("selection.")) return "selection";+ if (expression.ref.startsWith("segment.")) return "segment";+ if (expression.ref === "moment.cue") return "moment";+ return "program";+}++function sourceReference(+ element: StructuredElement,+ kind: SourceKind,+ resolveReference: ResolveReference,+): SurfaceResolvedReference | undefined {+ if (kind === "program") return undefined;+ const expected = kind === "selection"+ ? narrativeTypes.selection+ : kind === "segment" ? narrativeTypes.excerpt : narrativeTypes.moment;+ return resolve(element.attributes[kind], `${element.name}.${kind}`, expected, resolveReference);+}++function projectionFragment(input: {+ readonly output: "instant" | "window";+ readonly start: InstantDraft;+ readonly end?: InstantDraft;+}): GraphFragment {+ const fragmentInput = (name: string) => ({ kind: "fragment-input" as const, name });+ const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });+ const endpoints = input.end === undefined+ ? [["instant", input.start] as const]+ : [["start", input.start] as const, ["end", input.end] as const];+ const inputs = [+ { name: "semantic", type: semanticTrackTypes.track },+ ...endpoints.map(([name]) => ({ name: `${name}-spec`, type: temporalTypes.instantSpec })),+ ...endpoints.flatMap(([name, endpoint]) => endpoint.source === "program" ? [] : [{+ name: `${name}-${endpoint.source}`,+ type: endpoint.source === "selection" ? narrativeTypes.selection+ : endpoint.source === "segment" ? narrativeTypes.excerpt : narrativeTypes.moment,+ }]),+ ...(input.end === undefined ? [] : [{ name: "window-spec", type: temporalTypes.windowSpec }]),+ ];+ const operations: FragmentOperation[] = endpoints.map(([name, endpoint]) => ({+ id: `temporal:${name}`,+ producer: endpoint.source === "program" ? temporalProducers.projectProgramInstant+ : endpoint.source === "selection" ? temporalProducers.projectSelectionInstant+ : endpoint.source === "segment" ? temporalProducers.projectSegmentInstant+ : temporalProducers.projectMomentInstant,+ inputs: {+ semantic: fragmentInput("semantic"),+ spec: fragmentInput(`${name}-spec`),+ ...(endpoint.source === "program" ? {} : {+ [endpoint.source]: fragmentInput(`${name}-${endpoint.source}`),+ }),+ },+ result: { kind: "output" as const, name: "instant" },+ }));+ if (input.end !== undefined) operations.push({+ id: "temporal:window",+ producer: temporalProducers.composeWindow,+ inputs: {+ spec: fragmentInput("window-spec"),+ start: operation("temporal:start"),+ end: operation("temporal:end"),+ },+ result: { kind: "output" as const, name: "window" },+ });+ return sealGraphFragment({+ inputs,+ operations,+ exports: [{+ name: input.output,+ type: input.output === "window" ? temporalTypes.window : temporalTypes.instant,+ root: operation(input.output === "window" ? "temporal:window" : "temporal:instant"),+ }],+ });+}++function projectionDraft(input: {+ readonly id: string;+ readonly subjectId?: string;+ readonly element: StructuredElement;+ readonly semantic: SurfaceResolvedReference;+ readonly start: InstantDraft;+ readonly end?: InstantDraft;+}): TemporalMarkupProjection {+ if (!sameType(input.semantic.type, semanticTrackTypes.track)) {+ throw new Error(`${input.element.name}.semantic has the wrong Type.`);+ }+ const output = input.end === undefined ? "instant" : "window";+ const subjectId = input.subjectId ?? input.id;+ if (subjectId.length === 0) throw new Error("Temporal projection subjectId must not be empty.");+ const fragment = projectionFragment({ output, start: input.start, ...(input.end === undefined ? {} : { end: input.end }) });+ const componentId = `${input.id}.__temporal`;+ const records: SurfaceRecordDraft[] = [];+ const componentInputs: SurfaceComponentDraft["inputs"] extends infer _T+ ? Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }>+ : never = { semantic: input.semantic.ref };+ const endpoints = input.end === undefined+ ? [["instant", input.start] as const]+ : [["start", input.start] as const, ["end", input.end] as const];+ for (const [name, endpoint] of endpoints) {+ const recordId = `${input.id}.__temporal.${name}`;+ records.push({+ id: recordId,+ type: temporalTypes.instantSpec,+ value: { kind: "inline", value: {+ id: `${input.id}.${name}`,+ subjectId,+ projection: endpoint.expression,+ authority: endpoint.authority,+ } },+ range: input.element.range,+ });+ componentInputs[`${name}-spec`] = { kind: "record", id: recordId };+ if (endpoint.source !== "program") {+ if (endpoint.reference === undefined) throw new Error(`${input.id}.${name} has no ${endpoint.source} source.`);+ componentInputs[`${name}-${endpoint.source}`] = endpoint.reference.ref;+ }+ }+ if (input.end !== undefined) {+ const windowSpecId = `${input.id}.__temporal.window`;+ records.push({+ id: windowSpecId,+ type: temporalTypes.windowSpec,+ value: { kind: "inline", value: { id: input.id, subjectId } },+ range: input.element.range,+ });+ componentInputs["window-spec"] = { kind: "record", id: windowSpecId };+ }+ return {+ records,+ components: [{+ id: componentId,+ fragment: fragment.id,+ inputs: componentInputs,+ outputs: { [output]: `${input.id}.__temporal.${output}` },+ range: input.element.range,+ }],+ fragments: [fragment],+ ref: { kind: "component-output", component: componentId, output },+ };+}++/** Decode exactly one of during, at/for, until/for, or start/end. */+export function createTemporalWindowProjection(input: {+ readonly id: string;+ readonly subjectId?: string;+ readonly element: StructuredElement;+ readonly semantic: SurfaceResolvedReference;+ readonly resolveReference: ResolveReference;+}): TemporalMarkupProjection {+ const { element, resolveReference } = input;+ const during = element.attributes.during;+ const at = element.attributes.at;+ const until = element.attributes.until;+ const start = optionalText(element, "start");+ const end = optionalText(element, "end");+ const forms = Number(during !== undefined) + Number(at !== undefined)+ + Number(until !== undefined) + Number(start !== undefined || end !== undefined);+ if (forms !== 1) {+ throw new Error(`${element.name} requires exactly one of during, at/for, until/for, or start/end.`);+ }+ if (during !== undefined) {+ rejectUnusedTemporalAttributes(element, temporalWindowAttributeNames, ["during"]);+ if (typeof during === "string") {+ if (during.trim() !== "program") throw new Error(`${element.name}.during text must be program.`);+ return projectionDraft({+ ...input,+ start: { expression: { ref: "program.start" }, authority: { kind: "fixed" }, source: "program" },+ end: { expression: { ref: "program.end" }, authority: { kind: "fixed" }, source: "program" },+ });+ }+ const bound = resolveDuring(during, `${element.name}.during`, resolveReference);+ const semantic = bound.kind === "selection";+ return projectionDraft({+ ...input,+ start: {+ expression: { ref: `${bound.kind}.start` },+ authority: semantic ? { kind: "semantic", boundary: "start" } : { kind: "fixed" },+ source: bound.kind,+ reference: bound.reference,+ },+ end: {+ expression: { ref: `${bound.kind}.end` },+ authority: semantic ? { kind: "semantic", boundary: "end" } : { kind: "fixed" },+ source: bound.kind,+ reference: bound.reference,+ },+ });+ }+ if (at !== undefined || until !== undefined) {+ const name = at !== undefined ? "at" : "until";+ rejectUnusedTemporalAttributes(element, temporalWindowAttributeNames, [name, "for"]);+ const moment = resolve(at ?? until, `${element.name}.${name}`, narrativeTypes.moment, resolveReference);+ const length = parseTemporalDuration(text(element, "for"), `${element.name}.for`);+ const cue: InstantDraft = {+ expression: { ref: "moment.cue" },+ authority: { kind: "semantic", boundary: "cue" },+ source: "moment",+ reference: moment,+ };+ const derived: InstantDraft = {+ expression: { ref: "moment.cue", offset: at !== undefined ? length : negate(length) },+ authority: {+ kind: "parameter",+ binding: "for",+ relation: at !== undefined ? "after-start" : "before-end",+ },+ source: "moment",+ reference: moment,+ };+ return projectionDraft({+ ...input,+ start: at !== undefined ? cue : derived,+ end: at !== undefined ? derived : cue,+ });+ }+ if (start === undefined || end === undefined) {+ throw new Error(`${element.name} explicit timing requires both start and end.`);+ }+ const startExpression = parseTemporalInstant(start, `${element.name}.start`);+ const endExpression = parseTemporalInstant(end, `${element.name}.end`);+ const startSource = expressionSource(startExpression);+ const endSource = expressionSource(endExpression);+ rejectUnusedTemporalAttributes(element, temporalWindowAttributeNames, [+ "start", "end",+ ...(startSource === "program" ? [] : [startSource]),+ ...(endSource === "program" ? [] : [endSource]),+ ]);+ const startReference = startSource === "program" ? undefined : sourceReference(element, startSource, resolveReference);+ const endReference = endSource === "program" ? undefined : sourceReference(element, endSource, resolveReference);+ return projectionDraft({+ ...input,+ start: {+ expression: startExpression,+ authority: { kind: "parameter", binding: "start", relation: "direct" },+ source: startSource,+ ...(startReference === undefined ? {} : { reference: startReference }),+ },+ end: {+ expression: endExpression,+ authority: { kind: "parameter", binding: "end", relation: "direct" },+ source: endSource,+ ...(endReference === undefined ? {} : { reference: endReference }),+ },+ });+}++/** Decode exactly one semantic at={Moment} or projected instant="...". */+export function createTemporalInstantProjection(input: {+ readonly id: string;+ readonly subjectId?: string;+ readonly element: StructuredElement;+ readonly semantic: SurfaceResolvedReference;+ readonly resolveReference: ResolveReference;+ readonly semanticAttribute?: string;+ readonly boundaryAttribute?: string;+ readonly boundaryFallback?: "start" | "end";+ readonly projectedAttribute?: string | false;+}): TemporalMarkupProjection {+ const semanticAttribute = input.semanticAttribute ?? "at";+ const boundaryAttribute = input.boundaryAttribute ?? "boundary";+ const projectedAttribute = input.projectedAttribute === undefined ? "instant" : input.projectedAttribute;+ const at = input.element.attributes[semanticAttribute];+ const explicit = projectedAttribute === false ? undefined : optionalText(input.element, projectedAttribute);+ const universe = [...new Set([+ ...temporalInstantAttributeNames,+ semanticAttribute,+ boundaryAttribute,+ ...(projectedAttribute === false ? [] : [projectedAttribute]),+ ])];+ if (Number(at !== undefined) + Number(explicit !== undefined) !== 1) {+ throw new Error(`${input.element.name} requires exactly one of ${semanticAttribute}${projectedAttribute === false ? "" : ` or ${projectedAttribute}`}.`);+ }+ if (at !== undefined) {+ if (typeof at === "string") {+ throw new Error(`${input.element.name}.${semanticAttribute} must be a semantic reference; use ${projectedAttribute || "instant"} for a projected point.`);+ }+ const found = input.resolveReference(at.path);+ if (found === undefined) throw new Error(`${input.element.name}.${semanticAttribute} is unresolved.`);+ if (sameType(found.type, narrativeTypes.moment)) {+ if (input.element.attributes[boundaryAttribute] !== undefined) {+ throw new Error(`${input.element.name}.${boundaryAttribute} is invalid for a Moment.`);+ }+ rejectUnusedTemporalAttributes(input.element, universe, [semanticAttribute]);+ return projectionDraft({+ ...input,+ start: {+ expression: { ref: "moment.cue" },+ authority: { kind: "semantic", boundary: "cue" },+ source: "moment",+ reference: found,+ },+ });+ }+ const source = sameType(found.type, narrativeTypes.selection) ? "selection"+ : sameType(found.type, narrativeTypes.excerpt) ? "segment" : undefined;+ if (source === undefined) {+ throw new Error(`${input.element.name}.${semanticAttribute} must reference a Moment, Selection or Segment.`);+ }+ const boundary = optionalText(input.element, boundaryAttribute) ?? input.boundaryFallback;+ if (boundary !== "start" && boundary !== "end") {+ throw new Error(`${input.element.name}.${boundaryAttribute} must be start or end.`);+ }+ rejectUnusedTemporalAttributes(input.element, universe, [semanticAttribute, boundaryAttribute]);+ return projectionDraft({+ ...input,+ start: {+ expression: { ref: `${source}.${boundary}` },+ authority: source === "selection" ? { kind: "semantic", boundary } : { kind: "fixed" },+ source,+ reference: found,+ },+ });+ }+ const expression = parseTemporalInstant(explicit!, `${input.element.name}.${projectedAttribute || "instant"}`);+ const source = expressionSource(expression);+ rejectUnusedTemporalAttributes(input.element, universe, [+ projectedAttribute || "instant",+ ...(source === "program" ? [] : [source]),+ ]);+ const reference = source === "program" ? undefined : sourceReference(input.element, source, input.resolveReference);+ return projectionDraft({+ ...input,+ start: {+ expression,+ authority: { kind: "parameter", binding: projectedAttribute || "instant", relation: "direct" },+ source,+ ...(reference === undefined ? {} : { reference }),+ },+ });+}diff --git a/packages/temporal-markup/test/temporal-markup.test.ts b/packages/temporal-markup/test/temporal-markup.test.tsnew file mode 100644index 00000000..2ce514ef--- /dev/null+++ b/packages/temporal-markup/test/temporal-markup.test.ts@@ -0,0 +1,70 @@+import assert from "node:assert/strict";+import test from "node:test";++import type { MarkupAttributeValue, StructuredElement, SurfaceResolvedReference } from "@hypit/markup";+import { narrativeTypes } from "@hypit/narrative";+import { semanticTrackTypes } from "@hypit/semantic-track";+import type { TemporalInstantSpec } from "@hypit/temporal";++import { createTemporalInstantProjection, createTemporalWindowProjection } from "../src/index.js";++const range = { source: "main.svml", start: 0, end: 1 };+const reference = (path: string): MarkupAttributeValue => ({ kind: "reference", path });+const resolved = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({+ path, type, ref: { kind: "record", id: path },+});+const semantic = resolved("semantic", semanticTrackTypes.track);+const references = new Map([+ ["selection", resolved("selection", narrativeTypes.selection)],+ ["segment", resolved("segment", narrativeTypes.excerpt)],+ ["moment", resolved("moment", narrativeTypes.moment)],+]);+const resolveReference = (path: string) => references.get(path);+const element = (attributes: Record<string, MarkupAttributeValue>): StructuredElement => ({+ kind: "element", name: "example:Item", attributes, children: [], range,+});+const specs = (projection: ReturnType<typeof createTemporalWindowProjection>) => projection.records+ .filter((record) => record.type.name === "TemporalInstantSpec")+ .map((record) => record.value.kind === "inline" ? record.value.value as unknown as TemporalInstantSpec : undefined);++test("the author bridge owns the four Window forms and the explicit Instant fallback", () => {+ assert.deepEqual(specs(createTemporalWindowProjection({+ id: "during", element: element({ during: reference("selection") }), semantic, resolveReference,+ })).map((spec) => spec?.authority), [+ { kind: "semantic", boundary: "start" },+ { kind: "semantic", boundary: "end" },+ ]);++ assert.deepEqual(specs(createTemporalWindowProjection({+ id: "at", element: element({ at: reference("moment"), for: "8f" }), semantic, resolveReference,+ })).map((spec) => spec?.authority), [+ { kind: "semantic", boundary: "cue" },+ { kind: "parameter", binding: "for", relation: "after-start" },+ ]);++ assert.deepEqual(specs(createTemporalWindowProjection({+ id: "until", element: element({ until: reference("moment"), for: "8f" }), semantic, resolveReference,+ })).map((spec) => spec?.authority), [+ { kind: "parameter", binding: "for", relation: "before-end" },+ { kind: "semantic", boundary: "cue" },+ ]);++ assert.deepEqual(specs(createTemporalWindowProjection({+ id: "explicit",+ element: element({ start: "moment.cue+3f", end: "program.end", moment: reference("moment") }),+ semantic, resolveReference,+ })).map((spec) => spec?.authority), [+ { kind: "parameter", binding: "start", relation: "direct" },+ { kind: "parameter", binding: "end", relation: "direct" },+ ]);++ const instant = createTemporalInstantProjection({+ id: "fallback", element: element({ instant: "moment.cue+3f", moment: reference("moment") }),+ semantic, resolveReference,+ });+ assert.deepEqual(specs(instant as ReturnType<typeof createTemporalWindowProjection>)[0]?.authority,+ { kind: "parameter", binding: "instant", relation: "direct" });+ assert.throws(() => createTemporalInstantProjection({+ id: "ambiguous", element: element({ at: "moment.cue+3f" }), semantic, resolveReference,+ }), /semantic reference.*projected point/u);+});diff --git a/packages/temporal/README.md b/packages/temporal/README.mdindex 79caf385..d8fcd25a 100644--- a/packages/temporal/README.md+++ b/packages/temporal/README.md@@ -1,18 +1,26 @@# `@hypit/temporal`-Focused video-domain temporal projection. It locates one authored Program, Selection, Segment or-Moment through `@hypit/semantic-track`, evaluates exact rational point expressions and projects-them into ProgramSpace.+Runtime protocol for projected video time.-The graph-facing protocol has two distinct results. `TemporalPointSpec -> TemporalPoint` preserves-one frame boundary, including `program.end`; `TemporalWindowSpec -> TemporalWindow` preserves a-non-empty half-open frame span. Author Surfaces emit the appropriate Spec and one `project-*-point`-or `project-*` operation. Downstream components consume the projected value and ProgramSpace; they-do not receive a Selection or Moment to locate internally.+The public values are `TemporalInstant` and `TemporalWindow`. An Instant retains its runtime source,+exact projection expression, resolved ProgramSpace frame and author authority. A Window is composed+from two independently traced Instants; it has no synthetic single source.-Both results retain source identity and the authored projection expression. Studio reads those-executed records and their real consumer edges, so Point values are never disguised as one-frame-Windows and no second timing truth is reconstructed from source attribute names.+Every source names its exact `ProgramSpace` and `Narrative`, and every projection retains the+consumer's public domain identity as `subjectId`. These are public provenance fields, not generated hashes+or editor metadata. A graph-qualified projection `id` and its author-facing `subjectId` are separate+on purpose.-The package also provides pure sibling-window validation and triggered-stage scheduling. It defines-no Core branch, renderer behavior, media playback policy, Provider or authoring super-program.+Author syntax does not live here. `@hypit/temporal-markup` lowers SVML timing forms into ordinary+Instant projection and Window composition operations. The graph supplies ProgramSpace separately;+domain components receive only ProgramSpace plus the resulting Instant or Window and never locate a+Selection, Segment or Moment themselves.++Every official consumer verifies the projection at its public boundary: `subjectId` must name the+domain object being built, both endpoints must retain one ProgramSpace/Narrative, and that identity+must equal the explicitly supplied ProgramSpace. ProgramSpace is therefore an ordinary graph input+to the consumer, not ambient renderer state.++Temporal rejects Instants outside ProgramSpace and Windows that are reversed or empty. It does not+clip or repair author time. The package also provides sibling-window validation and triggered-stage+scheduling, but no renderer, Provider, media policy or Studio behavior.diff --git a/packages/temporal/src/component.ts b/packages/temporal/src/component.tsindex cb702da2..50405e67 100644--- a/packages/temporal/src/component.ts+++ b/packages/temporal/src/component.ts@@ -5,17 +5,14 @@ import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } fromimport type { SemanticTrack } from "@hypit/semantic-track";import {- projectMomentPoint,- projectMomentWindow,- projectProgramPoint,- projectProgramWindow,- projectSegmentPoint,- projectSegmentWindow,- projectSelectionPoint,- projectSelectionWindow,+ composeTemporalWindow,+ projectMomentInstant,+ projectProgramInstant,+ projectSegmentInstant,+ projectSelectionInstant,} from "./projection.js";-import { temporalProducers, temporalTypes } from "./index.js";-import type { TemporalPointSpec, TemporalWindowSpec } from "./types.js";+import { temporalProducers } from "./index.js";+import type { ProjectedInstant, TemporalInstantSpec, TemporalWindowSpec } from "./types.js";function inline<T>(value: StoredValue | undefined, label: string): T {if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);@@ -24,61 +21,47 @@ function inline<T>(value: StoredValue | undefined, label: string): T {const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });-function windowSpec(inputs: ProducerHandlerContext["inputs"]): TemporalWindowSpec {- return inline<TemporalWindowSpec>(inputs.spec?.value, "TemporalWindowSpec");-}--function pointSpec(inputs: ProducerHandlerContext["inputs"]): TemporalPointSpec {- return inline<TemporalPointSpec>(inputs.spec?.value, "TemporalPointSpec");+function instantSpec(inputs: ProducerHandlerContext["inputs"]): TemporalInstantSpec {+ return inline<TemporalInstantSpec>(inputs.spec?.value, "TemporalInstantSpec");}export const temporalComponent = {producers: [- { producer: temporalProducers.projectProgramPoint, handler: ({ inputs }) => ({ outputs: { point: output(projectProgramPoint({- itemId: pointSpec(inputs).id,- semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),- projection: pointSpec(inputs).projection,- })) }, needs: {} }) },- { producer: temporalProducers.projectSelectionPoint, handler: ({ inputs }) => ({ outputs: { point: output(projectSelectionPoint({- itemId: pointSpec(inputs).id,- semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),- selection: inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),- projection: pointSpec(inputs).projection,- })) }, needs: {} }) },- { producer: temporalProducers.projectSegmentPoint, handler: ({ inputs }) => ({ outputs: { point: output(projectSegmentPoint({- itemId: pointSpec(inputs).id,- semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),- segment: inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),- projection: pointSpec(inputs).projection,- })) }, needs: {} }) },- { producer: temporalProducers.projectMomentPoint, handler: ({ inputs }) => ({ outputs: { point: output(projectMomentPoint({- itemId: pointSpec(inputs).id,- semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),- moment: inline<NarrativeMomentRef>(inputs.moment?.value, "NarrativeMoment"),- projection: pointSpec(inputs).projection,- })) }, needs: {} }) },- { producer: temporalProducers.projectProgram, handler: ({ inputs }) => ({ outputs: { window: output(projectProgramWindow({- itemId: windowSpec(inputs).id,+ { producer: temporalProducers.projectProgramInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectProgramInstant({+ itemId: instantSpec(inputs).id,+ subjectId: instantSpec(inputs).subjectId,semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),- projection: windowSpec(inputs).projection,+ projection: instantSpec(inputs).projection,+ authority: instantSpec(inputs).authority,})) }, needs: {} }) },- { producer: temporalProducers.projectSelection, handler: ({ inputs }) => ({ outputs: { window: output(projectSelectionWindow({- itemId: windowSpec(inputs).id,+ { producer: temporalProducers.projectSelectionInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectSelectionInstant({+ itemId: instantSpec(inputs).id,+ subjectId: instantSpec(inputs).subjectId,semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),selection: inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),- projection: windowSpec(inputs).projection,+ projection: instantSpec(inputs).projection,+ authority: instantSpec(inputs).authority,})) }, needs: {} }) },- { producer: temporalProducers.projectSegment, handler: ({ inputs }) => ({ outputs: { window: output(projectSegmentWindow({- itemId: windowSpec(inputs).id,+ { producer: temporalProducers.projectSegmentInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectSegmentInstant({+ itemId: instantSpec(inputs).id,+ subjectId: instantSpec(inputs).subjectId,semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),segment: inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),- projection: windowSpec(inputs).projection,+ projection: instantSpec(inputs).projection,+ authority: instantSpec(inputs).authority,})) }, needs: {} }) },- { producer: temporalProducers.projectMoment, handler: ({ inputs }) => ({ outputs: { window: output(projectMomentWindow({- itemId: windowSpec(inputs).id,+ { producer: temporalProducers.projectMomentInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectMomentInstant({+ itemId: instantSpec(inputs).id,+ subjectId: instantSpec(inputs).subjectId,semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),moment: inline<NarrativeMomentRef>(inputs.moment?.value, "NarrativeMoment"),- projection: windowSpec(inputs).projection,+ projection: instantSpec(inputs).projection,+ authority: instantSpec(inputs).authority,})) }, needs: {} }) },+ { producer: temporalProducers.composeWindow, handler: ({ inputs }) => ({ outputs: { window: output(composeTemporalWindow(+ inline<TemporalWindowSpec>(inputs.spec?.value, "TemporalWindowSpec"),+ inline<ProjectedInstant>(inputs.start?.value, "TemporalInstant start"),+ inline<ProjectedInstant>(inputs.end?.value, "TemporalInstant end"),+ )) }, needs: {} }) },],} satisfies ComponentPackage;diff --git a/packages/temporal/src/index.ts b/packages/temporal/src/index.tsindex a79a1339..968c3b07 100644--- a/packages/temporal/src/index.ts+++ b/packages/temporal/src/index.ts@@ -1,5 +1,5 @@import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";-import { narrativeTypes, narrativeDependency } from "@hypit/narrative";+import { narrativeDependency, narrativeTypes } from "@hypit/narrative";import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";import { programSpaceDependency } from "@hypit/program-space";@@ -12,18 +12,30 @@ const duration: ValueSchema = { kind: "oneOf", variants: [object({ unit: { schema: { kind: "literal", value: "milliseconds" } }, value: { schema: integer } }),object({ unit: { schema: { kind: "literal", value: "seconds" } }, numerator: { schema: integer }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } }),] };-const point: ValueSchema = { kind: "oneOf", variants: [+const instant: ValueSchema = { kind: "oneOf", variants: [...["program.start", "program.end", "selection.start", "selection.end", "segment.start", "segment.end", "moment.cue"].map((ref) => object({ref: { schema: { kind: "literal", value: ref } }, offset: { schema: duration, optional: true },})),object({ ref: { schema: { kind: "literal", value: "absolute" } }, at: { schema: duration } }),] };-const projectionSchema: ValueSchema = object({ start: { schema: point }, end: { schema: point } });const sourceSchema: ValueSchema = { kind: "oneOf", variants: [...["program", "selection", "segment", "moment"].map((kind) => object({+ spaceId: { schema: string }, narrativeId: { schema: string },kind: { schema: { kind: "literal", value: kind } }, id: { schema: string },})),] };+const authoritySchema: ValueSchema = { kind: "oneOf", variants: [+ object({+ kind: { schema: { kind: "literal", value: "semantic" } },+ boundary: { schema: { kind: "string", enum: ["start", "end", "cue"] } },+ }),+ object({+ kind: { schema: { kind: "literal", value: "parameter" } },+ binding: { schema: string },+ relation: { schema: { kind: "string", enum: ["direct", "after-start", "before-end"] } },+ }),+ object({ kind: { schema: { kind: "literal", value: "fixed" } } }),+] };const frameSpanSchema: ValueSchema = object({startFrame: { schema: unsignedInteger },endFrameExclusive: { schema: { kind: "number", integer: true, minimum: 1 } },@@ -37,20 +49,17 @@ export type * from "./types.js";export const temporalModuleRef = { name: "@hypit/temporal", version: "1" } as const;export const temporalTypes = {- pointSpec: { module: temporalModuleRef, name: "TemporalPointSpec" },- point: { module: temporalModuleRef, name: "TemporalPoint" },+ instantSpec: { module: temporalModuleRef, name: "TemporalInstantSpec" },+ instant: { module: temporalModuleRef, name: "TemporalInstant" },windowSpec: { module: temporalModuleRef, name: "TemporalWindowSpec" },window: { module: temporalModuleRef, name: "TemporalWindow" },} satisfies Record<string, TypeRef>;export const temporalProducers = {- projectProgramPoint: { module: temporalModuleRef, name: "project-program-point" },- projectSelectionPoint: { module: temporalModuleRef, name: "project-selection-point" },- projectSegmentPoint: { module: temporalModuleRef, name: "project-segment-point" },- projectMomentPoint: { module: temporalModuleRef, name: "project-moment-point" },- projectProgram: { module: temporalModuleRef, name: "project-program-window" },- projectSelection: { module: temporalModuleRef, name: "project-selection-window" },- projectSegment: { module: temporalModuleRef, name: "project-segment-window" },- projectMoment: { module: temporalModuleRef, name: "project-moment-window" },+ projectProgramInstant: { module: temporalModuleRef, name: "project-program-instant" },+ projectSelectionInstant: { module: temporalModuleRef, name: "project-selection-instant" },+ projectSegmentInstant: { module: temporalModuleRef, name: "project-segment-instant" },+ projectMomentInstant: { module: temporalModuleRef, name: "project-moment-instant" },+ composeWindow: { module: temporalModuleRef, name: "compose-window" },} satisfies Record<string, ProducerRef>;export const temporalManifest: ModuleManifest = {format: "hypit.module@1",@@ -58,50 +67,44 @@ export const temporalManifest: ModuleManifest = {version: temporalModuleRef.version,dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency],types: [- { name: temporalTypes.pointSpec.name },- { name: temporalTypes.point.name },+ { name: temporalTypes.instantSpec.name },+ { name: temporalTypes.instant.name },{ name: temporalTypes.windowSpec.name },{ name: temporalTypes.window.name },],capabilities: [],producers: [- { name: temporalProducers.projectProgramPoint.name,- inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "spec", type: temporalTypes.pointSpec }],- outputs: [{ name: "point", type: temporalTypes.point }], needs: [] },- { name: temporalProducers.projectSelectionPoint.name,- inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: temporalTypes.pointSpec }],- outputs: [{ name: "point", type: temporalTypes.point }], needs: [] },- { name: temporalProducers.projectSegmentPoint.name,- inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: temporalTypes.pointSpec }],- outputs: [{ name: "point", type: temporalTypes.point }], needs: [] },- { name: temporalProducers.projectMomentPoint.name,- inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: temporalTypes.pointSpec }],- outputs: [{ name: "point", type: temporalTypes.point }], needs: [] },- { name: temporalProducers.projectProgram.name,- inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "spec", type: temporalTypes.windowSpec }],- outputs: [{ name: "window", type: temporalTypes.window }], needs: [] },- { name: temporalProducers.projectSelection.name,- inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: temporalTypes.windowSpec }],- outputs: [{ name: "window", type: temporalTypes.window }], needs: [] },- { name: temporalProducers.projectSegment.name,- inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: temporalTypes.windowSpec }],- outputs: [{ name: "window", type: temporalTypes.window }], needs: [] },- { name: temporalProducers.projectMoment.name,- inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: temporalTypes.windowSpec }],+ { name: temporalProducers.projectProgramInstant.name,+ inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "spec", type: temporalTypes.instantSpec }],+ outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },+ { name: temporalProducers.projectSelectionInstant.name,+ inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: temporalTypes.instantSpec }],+ outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },+ { name: temporalProducers.projectSegmentInstant.name,+ inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: temporalTypes.instantSpec }],+ outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },+ { name: temporalProducers.projectMomentInstant.name,+ inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: temporalTypes.instantSpec }],+ outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },+ { name: temporalProducers.composeWindow.name,+ inputs: [{ name: "spec", type: temporalTypes.windowSpec }, { name: "start", type: temporalTypes.instant }, { name: "end", type: temporalTypes.instant }],outputs: [{ name: "window", type: temporalTypes.window }], needs: [] },],};export const temporalDependency = { module: temporalModuleRef } as const;-export const temporalPointSpecSchema: ValueSchema = object({- id: { schema: string }, projection: { schema: point },-});-export const temporalPointSchema: ValueSchema = object({- id: { schema: string }, source: { schema: sourceSchema }, projection: { schema: point }, frame: { schema: unsignedInteger },+export const temporalInstantSpecSchema: ValueSchema = object({+ id: { schema: string }, subjectId: { schema: string }, projection: { schema: instant }, authority: { schema: authoritySchema },});-export const temporalWindowSpecSchema: ValueSchema = object({- id: { schema: string }, projection: { schema: projectionSchema },+export const temporalInstantSchema: ValueSchema = object({+ id: { schema: string }, subjectId: { schema: string }, source: { schema: sourceSchema }, projection: { schema: instant },+ authority: { schema: authoritySchema }, frame: { schema: unsignedInteger },});+export const temporalWindowSpecSchema: ValueSchema = object({ id: { schema: string }, subjectId: { schema: string } });export const temporalWindowSchema: ValueSchema = object({- id: { schema: string }, source: { schema: sourceSchema }, projection: { schema: projectionSchema }, span: { schema: frameSpanSchema },+ id: { schema: string },+ subjectId: { schema: string },+ start: { schema: temporalInstantSchema },+ end: { schema: temporalInstantSchema },+ span: { schema: frameSpanSchema },});diff --git a/packages/temporal/src/projection.ts b/packages/temporal/src/projection.tsindex 6b6b4ab9..32746ba1 100644--- a/packages/temporal/src/projection.ts+++ b/packages/temporal/src/projection.ts@@ -5,42 +5,88 @@ import { projectSemanticProgramSpace } from "@hypit/semantic-track";import type { SemanticTrack } from "@hypit/semantic-track";import { locateMoment, locateProgram, locateSegment, locateSelection } from "./location.js";-import {- add,- compare,- durationInFrames,- maximum,- minimum,- quantizeBoundary,- rational,-} from "./rational.js";+import { add, compare, durationInFrames, quantizeBoundary, rational } from "./rational.js";import type { Rational } from "./rational.js";import type {- FrameSpan,LocatedMoment,LocatedProgram,LocatedSegment,LocatedSelection,- ProjectedPoint,+ ProjectedInstant,ProjectedWindow,+ TemporalInstantExpression,+ TemporalInstant,+ TemporalInstantSpec,TemporalSource,- TemporalPointSpec,+ TemporalWindow,TemporalWindowSpec,- TemporalPointExpression,- TemporalWindowProjection,WindowRelation,} from "./types.js";-type PointEnvironment = {+export type TemporalConsumption = {+ readonly subjectId: string;+ readonly space?: ProgramSpace;+};++/** Verify the public identity carried across a Temporal consumer boundary. */+export function assertTemporalInstantFor(+ instant: TemporalInstant,+ expected: TemporalConsumption,+): void {+ if (!expected.subjectId || instant.subjectId !== expected.subjectId) {+ throw new Error(`Temporal Instant subject ${instant.subjectId} does not match ${expected.subjectId}.`);+ }+ if (!instant.source.spaceId || !instant.source.narrativeId) {+ throw new Error("Temporal Instant has no ProgramSpace identity.");+ }+ if (!Number.isSafeInteger(instant.frame) || instant.frame < 0) {+ throw new Error("Temporal Instant frame is invalid.");+ }+ if (expected.space !== undefined) {+ assertProgramSpaceIdentity(expected.space);+ if (instant.source.spaceId !== expected.space.id+ || instant.source.narrativeId !== expected.space.narrativeId) {+ throw new Error("Temporal Instant belongs to a different ProgramSpace or Narrative.");+ }+ if (instant.frame > programSpaceFrameCount(expected.space)) {+ throw new Error("Temporal Instant falls outside its ProgramSpace.");+ }+ }+}++/** Verify both endpoint provenance and the materialized span consumed by a domain program. */+export function assertTemporalWindowFor(+ window: TemporalWindow,+ expected: TemporalConsumption,+): void {+ if (window.subjectId !== expected.subjectId+ || window.start.subjectId !== expected.subjectId+ || window.end.subjectId !== expected.subjectId) {+ throw new Error(`Temporal Window subject ${window.subjectId} does not match ${expected.subjectId}.`);+ }+ assertTemporalInstantFor(window.start, expected);+ assertTemporalInstantFor(window.end, expected);+ if (window.start.source.spaceId !== window.end.source.spaceId+ || window.start.source.narrativeId !== window.end.source.narrativeId) {+ throw new Error("Temporal Window endpoints belong to different ProgramSpaces or Narratives.");+ }+ if (window.span.startFrame !== window.start.frame+ || window.span.endFrameExclusive !== window.end.frame+ || window.span.endFrameExclusive <= window.span.startFrame) {+ throw new Error("Temporal Window span disagrees with its endpoints.");+ }+}++type InstantEnvironment = {readonly program: LocatedProgram;readonly selection?: LocatedSelection;readonly moment?: LocatedMoment;readonly segment?: LocatedSegment;};-function evaluatePoint(- expression: TemporalPointExpression,- environment: PointEnvironment,+function evaluateInstant(+ expression: TemporalInstantExpression,+ environment: InstantEnvironment,space: ProgramSpace,): Rational {if (expression.ref === "absolute") return durationInFrames(expression.at, space);@@ -79,48 +125,22 @@ function evaluatePoint(: add(rational(BigInt(base)), durationInFrames(expression.offset, space));}-export function projectTemporalWindow(- projection: TemporalWindowProjection,- environment: PointEnvironment,- space: ProgramSpace,-): FrameSpan {- assertProgramSpaceIdentity(space);- const totalFrames = programSpaceFrameCount(space);- const rawStart = evaluatePoint(projection.start, environment, space);- const rawEnd = evaluatePoint(projection.end, environment, space);- if (compare(rawEnd, rawStart) < 0) throw new Error("Temporal projection produces a reversed raw window.");- if (compare(rawEnd, rawStart) === 0) throw new Error("Temporal projection produces a zero raw window.");- const lower = rational(0n);- const upper = rational(BigInt(totalFrames));- const clippedStart = maximum(rawStart, lower);- const clippedEnd = minimum(rawEnd, upper);- if (compare(clippedEnd, clippedStart) <= 0) {- throw new Error("Temporal projection does not intersect ProgramSpace.");- }- const startFrame = quantizeBoundary(clippedStart);- const endFrameExclusive = quantizeBoundary(clippedEnd);- if (startFrame < 0 || endFrameExclusive > totalFrames || endFrameExclusive <= startFrame) {- throw new Error("Temporal projection is shorter than one frame after quantization.");- }- return { startFrame, endFrameExclusive };-}--export function projectTemporalPoint(- projection: TemporalPointExpression,- environment: PointEnvironment,+export function projectTemporalInstant(+ projection: TemporalInstantExpression,+ environment: InstantEnvironment,space: ProgramSpace,): number {assertProgramSpaceIdentity(space);const totalFrames = programSpaceFrameCount(space);- const raw = evaluatePoint(projection, environment, space);+ const raw = evaluateInstant(projection, environment, space);const lower = rational(0n);const upper = rational(BigInt(totalFrames));if (compare(raw, lower) < 0 || compare(raw, upper) > 0) {- throw new Error("Temporal point projection falls outside ProgramSpace.");+ throw new Error("Temporal Instant projection falls outside ProgramSpace.");}const frame = quantizeBoundary(raw);if (frame < 0 || frame > totalFrames) {- throw new Error("Temporal point projection quantizes outside ProgramSpace.");+ throw new Error("Temporal Instant projection quantizes outside ProgramSpace.");}return frame;}@@ -130,154 +150,112 @@ function projectedId(itemId: string, sourceId: string): string {return `${itemId}::${sourceId}`;}-function projectedWindow(- spec: TemporalWindowSpec,- source: TemporalSource,- span: FrameSpan,-): ProjectedWindow {- return {- id: projectedId(spec.id, source.id),- source: { ...source },- projection: structuredClone(spec.projection),- span: { ...span },- };-}--function projectedPoint(- spec: TemporalPointSpec,+function projectedInstant(+ spec: TemporalInstantSpec,source: TemporalSource,frame: number,-): ProjectedPoint {+): ProjectedInstant {return {id: projectedId(spec.id, source.id),+ subjectId: spec.subjectId,source: { ...source },projection: structuredClone(spec.projection),+ authority: structuredClone(spec.authority),frame,};}-export function projectSelectionPoint(input: {+export function projectSelectionInstant(input: {readonly itemId: string;+ readonly subjectId: string;readonly semantic: SemanticTrack;readonly selection: NarrativeSelectionRef;- readonly projection: TemporalPointExpression;-}): ProjectedPoint {+ readonly projection: TemporalInstantExpression;+ readonly authority: TemporalInstantSpec["authority"];+}): ProjectedInstant {const space = projectSemanticProgramSpace(input.semantic);const program = locateProgram(input.semantic);const selection = locateSelection(input.semantic, input.selection);- return projectedPoint(- { id: input.itemId, projection: input.projection },- { kind: "selection", id: selection.id },- projectTemporalPoint(input.projection, { program, selection }, space),+ return projectedInstant(+ { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },+ { spaceId: space.id, narrativeId: space.narrativeId, kind: "selection", id: selection.id },+ projectTemporalInstant(input.projection, { program, selection }, space),);}-export function projectMomentPoint(input: {+export function projectMomentInstant(input: {readonly itemId: string;+ readonly subjectId: string;readonly semantic: SemanticTrack;readonly moment: NarrativeMomentRef;- readonly projection: TemporalPointExpression;-}): ProjectedPoint {+ readonly projection: TemporalInstantExpression;+ readonly authority: TemporalInstantSpec["authority"];+}): ProjectedInstant {const space = projectSemanticProgramSpace(input.semantic);const program = locateProgram(input.semantic);const moment = locateMoment(input.semantic, input.moment);- return projectedPoint(- { id: input.itemId, projection: input.projection },- { kind: "moment", id: moment.id },- projectTemporalPoint(input.projection, { program, moment }, space),+ return projectedInstant(+ { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },+ { spaceId: space.id, narrativeId: space.narrativeId, kind: "moment", id: moment.id },+ projectTemporalInstant(input.projection, { program, moment }, space),);}-export function projectProgramPoint(input: {+export function projectProgramInstant(input: {readonly itemId: string;+ readonly subjectId: string;readonly semantic: SemanticTrack;- readonly projection: TemporalPointExpression;-}): ProjectedPoint {+ readonly projection: TemporalInstantExpression;+ readonly authority: TemporalInstantSpec["authority"];+}): ProjectedInstant {const space = projectSemanticProgramSpace(input.semantic);const program = locateProgram(input.semantic);- return projectedPoint(- { id: input.itemId, projection: input.projection },- { kind: "program", id: program.id },- projectTemporalPoint(input.projection, { program }, space),+ return projectedInstant(+ { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },+ { spaceId: space.id, narrativeId: space.narrativeId, kind: "program", id: program.id },+ projectTemporalInstant(input.projection, { program }, space),);}-export function projectSegmentPoint(input: {+export function projectSegmentInstant(input: {readonly itemId: string;+ readonly subjectId: string;readonly semantic: SemanticTrack;readonly segment: NarrativeExcerpt;- readonly projection: TemporalPointExpression;-}): ProjectedPoint {+ readonly projection: TemporalInstantExpression;+ readonly authority: TemporalInstantSpec["authority"];+}): ProjectedInstant {const space = projectSemanticProgramSpace(input.semantic);const program = locateProgram(input.semantic);const segment = locateSegment(input.semantic, input.segment);- return projectedPoint(- { id: input.itemId, projection: input.projection },- { kind: "segment", id: segment.id },- projectTemporalPoint(input.projection, { program, segment }, space),- );-}--export function projectSelectionWindow(input: {- readonly itemId: string;- readonly semantic: SemanticTrack;- readonly selection: NarrativeSelectionRef;- readonly projection: TemporalWindowProjection;-}): ProjectedWindow {- const space = projectSemanticProgramSpace(input.semantic);- const program = locateProgram(input.semantic);- const selection = locateSelection(input.semantic, input.selection);- return projectedWindow(- { id: input.itemId, projection: input.projection },- { kind: "selection", id: selection.id },- projectTemporalWindow(input.projection, { program, selection }, space),- );-}--export function projectMomentWindow(input: {- readonly itemId: string;- readonly semantic: SemanticTrack;- readonly moment: NarrativeMomentRef;- readonly projection: TemporalWindowProjection;-}): ProjectedWindow {- const space = projectSemanticProgramSpace(input.semantic);- const program = locateProgram(input.semantic);- const moment = locateMoment(input.semantic, input.moment);- return projectedWindow(- { id: input.itemId, projection: input.projection },- { kind: "moment", id: moment.id },- projectTemporalWindow(input.projection, { program, moment }, space),- );-}--export function projectProgramWindow(input: {- readonly itemId: string;- readonly semantic: SemanticTrack;- readonly projection: TemporalWindowProjection;-}): ProjectedWindow {- const space = projectSemanticProgramSpace(input.semantic);- const program = locateProgram(input.semantic);- return projectedWindow(- { id: input.itemId, projection: input.projection },- { kind: "program", id: program.id },- projectTemporalWindow(input.projection, { program }, space),+ return projectedInstant(+ { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },+ { spaceId: space.id, narrativeId: space.narrativeId, kind: "segment", id: segment.id },+ projectTemporalInstant(input.projection, { program, segment }, space),);}-export function projectSegmentWindow(input: {- readonly itemId: string;- readonly semantic: SemanticTrack;- readonly segment: NarrativeExcerpt;- readonly projection: TemporalWindowProjection;-}): ProjectedWindow {- const space = projectSemanticProgramSpace(input.semantic);- const program = locateProgram(input.semantic);- const segment = locateSegment(input.semantic, input.segment);- return projectedWindow(- { id: input.itemId, projection: input.projection },- { kind: "segment", id: segment.id },- projectTemporalWindow(input.projection, { program, segment }, space),- );+export function composeTemporalWindow(+ spec: TemporalWindowSpec,+ start: ProjectedInstant,+ end: ProjectedInstant,+): ProjectedWindow {+ if (spec.id.length === 0) throw new Error("Temporal Window id must not be empty.");+ if (!spec.subjectId || start.subjectId !== spec.subjectId || end.subjectId !== spec.subjectId) {+ throw new Error("Temporal Window endpoints must explicitly name the Window subject.");+ }+ if (start.source.spaceId !== end.source.spaceId || start.source.narrativeId !== end.source.narrativeId) {+ throw new Error("Temporal Window endpoints must belong to one ProgramSpace and Narrative.");+ }+ if (end.frame < start.frame) throw new Error("Temporal Window endpoints are reversed.");+ if (end.frame === start.frame) throw new Error("Temporal Window endpoints produce a zero window.");+ return {+ id: spec.id,+ subjectId: spec.subjectId,+ start: structuredClone(start),+ end: structuredClone(end),+ span: { startFrame: start.frame, endFrameExclusive: end.frame },+ };}export function assertWindowRelation(diff --git a/packages/temporal/src/types.ts b/packages/temporal/src/types.tsindex c3866c0b..c8cba2fa 100644--- a/packages/temporal/src/types.ts+++ b/packages/temporal/src/types.ts@@ -31,7 +31,8 @@ export type TemporalDuration =| { readonly unit: "milliseconds"; readonly value: number }| { readonly unit: "seconds"; readonly numerator: number; readonly denominator: number };-export type TemporalPointExpression =+/** A single projected boundary before it is resolved into ProgramSpace. */+export type TemporalInstantExpression =| { readonly ref: "program.start"; readonly offset?: TemporalDuration }| { readonly ref: "program.end"; readonly offset?: TemporalDuration }| { readonly ref: "selection.start"; readonly offset?: TemporalDuration }@@ -41,27 +42,42 @@ export type TemporalPointExpression =| { readonly ref: "moment.cue"; readonly offset?: TemporalDuration }| { readonly ref: "absolute"; readonly at: TemporalDuration };-export type TemporalWindowProjection = {- readonly start: TemporalPointExpression;- readonly end: TemporalPointExpression;-};--/** Authored semantic source used by a temporal projection. */+/** Runtime dependency used to resolve an Instant. This is not its authoring authority. */export type TemporalSource = {+ readonly spaceId: string;+ readonly narrativeId: string;readonly kind: "program" | "selection" | "segment" | "moment";readonly id: string;};-/** Input value for the Temporal projection producer. */-export type TemporalWindowSpec = {+/**+ * The author-owned inverse of one projected Instant. Runtime dependencies and+ * author authority are deliberately separate: an expression may read an+ * anchor while remaining writable only at its author parameter.+ */+export type TemporalInstantAuthority =+ | { readonly kind: "semantic"; readonly boundary: "start" | "end" | "cue" }+ | {+ readonly kind: "parameter";+ readonly binding: string;+ readonly relation: "direct" | "after-start" | "before-end";+ }+ | { readonly kind: "fixed" };++/** Input value for an Instant projection producer. */+export type TemporalInstantSpec = {readonly id: string;- readonly projection: TemporalWindowProjection;+ /** Author/domain entity whose timing this projection controls. */+ readonly subjectId: string;+ readonly projection: TemporalInstantExpression;+ readonly authority: TemporalInstantAuthority;};-/** Input value for a Temporal point projection producer. */-export type TemporalPointSpec = {+/** Input value for composing two resolved Instants into a Window. */+export type TemporalWindowSpec = {readonly id: string;- readonly projection: TemporalPointExpression;+ /** Author/domain entity whose timing this projection controls. */+ readonly subjectId: string;};export type FrameSpan = {@@ -69,25 +85,28 @@ export type FrameSpan = {readonly endFrameExclusive: number;};-export type ProjectedWindow = {+export type ProjectedInstant = {readonly id: string;+ readonly subjectId: string;readonly source: TemporalSource;- readonly projection: TemporalWindowProjection;- readonly span: FrameSpan;+ readonly projection: TemporalInstantExpression;+ readonly authority: TemporalInstantAuthority;+ readonly frame: number;};-export type ProjectedPoint = {+export type ProjectedWindow = {readonly id: string;- readonly source: TemporalSource;- readonly projection: TemporalPointExpression;- readonly frame: number;+ readonly subjectId: string;+ readonly start: ProjectedInstant;+ readonly end: ProjectedInstant;+ readonly span: FrameSpan;};-/** Public protocol name for the resolved window consumed by domain programs. */-export type TemporalWindow = ProjectedWindow;+/** Public projection protocol consumed by domain programs. */+export type TemporalInstant = ProjectedInstant;-/** Public protocol name for the resolved boundary consumed by domain programs. */-export type TemporalPoint = ProjectedPoint;+/** Public projection protocol composed from two independently traced Instants. */+export type TemporalWindow = ProjectedWindow;export type WindowRelation = "independent" | "disjoint";diff --git a/packages/temporal/test/temporal.test.ts b/packages/temporal/test/temporal.test.tsindex 19d6b30a..1008b694 100644--- a/packages/temporal/test/temporal.test.ts+++ b/packages/temporal/test/temporal.test.ts@@ -8,19 +8,19 @@ import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";import {assertWindowRelation,+ composeTemporalWindow,locateSelection,- projectMomentPoint,- projectMomentWindow,- projectProgramPoint,- projectProgramWindow,- projectSelectionPoint,- projectSegmentWindow,- projectSelectionWindow,+ projectMomentInstant,+ projectProgramInstant,+ projectSelectionInstant,+ projectSegmentInstant,resolveTriggeredSchedule,temporalDurationInSamples,} from "../src/index.js";const space: ProgramSpace = {+ id: "test-space",+ narrativeId: "test-narrative",durationSec: 10,frameRate: { numerator: 30, denominator: 1 },};@@ -44,11 +44,44 @@ const semantic = semanticTrackFixture(space, {});const selection = (id: string, startAnchorId: string, endAnchorId: string): NarrativeSelectionRef => ({- id, startAnchorId, endAnchorId,+ narrativeId: "test-narrative", id, startAnchorId, endAnchorId,});-const moment = (id: string, anchorId: string): NarrativeMomentRef => ({ id, anchorId });+const moment = (id: string, anchorId: string): NarrativeMomentRef => ({ narrativeId: "test-narrative", id, anchorId });const frames = (value: number) => ({ unit: "frames" as const, value });const seconds = (numerator: number, denominator = 1) => ({ unit: "seconds" as const, numerator, denominator });+const fixed = { kind: "fixed" as const };+type Projection = import("../src/index.js").TemporalInstantExpression;+const projectProgramInstantFixture = (input: { itemId: string; semantic: typeof semantic; projection: Projection }) =>+ projectProgramInstant({ ...input, subjectId: input.itemId, authority: fixed });+const projectMomentInstantFixture = (input: { itemId: string; semantic: typeof semantic; moment: NarrativeMomentRef; projection: Projection }) =>+ projectMomentInstant({ ...input, subjectId: input.itemId, authority: fixed });+const projectSelectionInstantFixture = (input: { itemId: string; semantic: typeof semantic; selection: NarrativeSelectionRef; projection: Projection }) =>+ projectSelectionInstant({ ...input, subjectId: input.itemId, authority: fixed });+const projectSelectionWindow = (input: {+ itemId: string; semantic: typeof semantic; selection: NarrativeSelectionRef;+ projection: { start: Projection; end: Projection };+}) => composeTemporalWindow({ id: input.itemId, subjectId: input.itemId },+ projectSelectionInstant({ itemId: `${input.itemId}.start`, subjectId: input.itemId, semantic: input.semantic, selection: input.selection, projection: input.projection.start, authority: fixed }),+ input.projection.end.ref.startsWith("program.") || input.projection.end.ref === "absolute"+ ? projectProgramInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, semantic: input.semantic, projection: input.projection.end, authority: fixed })+ : projectSelectionInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, semantic: input.semantic, selection: input.selection, projection: input.projection.end, authority: fixed }));+const projectMomentWindow = (input: {+ itemId: string; semantic: typeof semantic; moment: NarrativeMomentRef;+ projection: { start: Projection; end: Projection };+}) => composeTemporalWindow({ id: input.itemId, subjectId: input.itemId },+ projectMomentInstant({ itemId: `${input.itemId}.start`, subjectId: input.itemId, semantic: input.semantic, moment: input.moment, projection: input.projection.start, authority: fixed }),+ projectMomentInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, semantic: input.semantic, moment: input.moment, projection: input.projection.end, authority: fixed }));+const projectSegmentWindow = (input: {+ itemId: string; semantic: typeof semantic; segment: import("@hypit/narrative").NarrativeExcerpt;+ projection: { start: Projection; end: Projection };+}) => composeTemporalWindow({ id: input.itemId, subjectId: input.itemId },+ projectSegmentInstant({ itemId: `${input.itemId}.start`, subjectId: input.itemId, semantic: input.semantic, segment: input.segment, projection: input.projection.start, authority: fixed }),+ projectSegmentInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, semantic: input.semantic, segment: input.segment, projection: input.projection.end, authority: fixed }));+const projectProgramWindow = (input: {+ itemId: string; semantic: typeof semantic; projection: { start: Projection; end: Projection };+}) => composeTemporalWindow({ id: input.itemId, subjectId: input.itemId },+ projectProgramInstant({ itemId: `${input.itemId}.start`, subjectId: input.itemId, semantic: input.semantic, projection: input.projection.start, authority: fixed }),+ projectProgramInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, semantic: input.semantic, projection: input.projection.end, authority: fixed }));test("one Selection projects exact local points and stable source identity", () => {const result = projectSelectionWindow({@@ -57,46 +90,60 @@ test("one Selection projects exact local points and stable source identity", ()selection: selection("proof", "a", "b"),projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },});- assert.deepEqual(result, {- id: "card::proof",- source: { kind: "selection", id: "proof" },- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },- span: { startFrame: 30, endFrameExclusive: 60 },- });+ assert.equal(result.id, "card");+ assert.equal(result.start.source.id, "proof");+ assert.equal(result.end.source.id, "proof");+ assert.deepEqual(result.span, { startFrame: 30, endFrameExclusive: 60 });});test("points preserve source identity and admit both ProgramSpace boundaries", () => {- assert.deepEqual(projectProgramPoint({+ assert.deepEqual(projectProgramInstantFixture({itemId: "terminal",semantic,projection: { ref: "program.end" },}), {id: "terminal::program",- source: { kind: "program", id: "program" },+ subjectId: "terminal",+ source: { spaceId: "test-space", narrativeId: "test-narrative", kind: "program", id: "program" },projection: { ref: "program.end" },+ authority: fixed,frame: 300,});- assert.deepEqual(projectMomentPoint({+ assert.deepEqual(projectMomentInstantFixture({itemId: "terminal",semantic,moment: moment("done", "end"),projection: { ref: "moment.cue" },}), {id: "terminal::done",- source: { kind: "moment", id: "done" },+ subjectId: "terminal",+ source: { spaceId: "test-space", narrativeId: "test-narrative", kind: "moment", id: "done" },projection: { ref: "moment.cue" },+ authority: fixed,frame: 300,});- assert.equal(projectProgramPoint({+ assert.equal(projectProgramInstantFixture({itemId: "start",semantic,projection: { ref: "program.start" },}).frame, 0);});+test("Script Program Anchors resolve through the SemanticTrack without entering a SemanticTake", () => {+ assert.deepEqual(locateSelection(semantic, selection("whole", "program:start", "program:end")), {+ id: "whole", start: { frame: 0 }, end: { frame: 300 },+ });+ assert.equal(projectMomentInstantFixture({+ itemId: "outro",+ semantic,+ moment: moment("outro", "program:end"),+ projection: { ref: "moment.cue" },+ }).frame, 300);+});+test("a point may consume one boundary of a crossed Selection", () => {const crossed = selection("crossed", "d", "a");- assert.equal(projectSelectionPoint({+ assert.equal(projectSelectionInstantFixture({itemId: "boundary",semantic,selection: crossed,@@ -105,12 +152,12 @@ test("a point may consume one boundary of a crossed Selection", () => {});test("points reject exact coordinates outside ProgramSpace", () => {- assert.throws(() => projectProgramPoint({+ assert.throws(() => projectProgramInstantFixture({itemId: "before",semantic,projection: { ref: "program.start", offset: frames(-1) },}), /falls outside ProgramSpace/u);- assert.throws(() => projectProgramPoint({+ assert.throws(() => projectProgramInstantFixture({itemId: "after",semantic,projection: { ref: "program.end", offset: frames(1) },@@ -121,19 +168,17 @@ test("one Segment projects from its own structural start and end anchors", () =>const result = projectSegmentWindow({itemId: "answer-card",semantic,- segment: { kind: "segment", id: "answer", tokenStart: 0, tokenEndExclusive: 1 },- projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },- });- assert.deepEqual(result, {- id: "answer-card::answer",- source: { kind: "segment", id: "answer" },+ segment: { kind: "segment", narrativeId: "test-narrative", id: "answer", tokenStart: 0, tokenEndExclusive: 1 },projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },- span: { startFrame: 60, endFrameExclusive: 120 },});+ assert.equal(result.id, "answer-card");+ assert.equal(result.start.source.id, "answer");+ assert.equal(result.end.source.id, "answer");+ assert.deepEqual(result.span, { startFrame: 60, endFrameExclusive: 120 });});-test("negative intermediate points clip before nearest half-later frame quantization", () => {- const result = projectMomentWindow({+test("Instant endpoints outside ProgramSpace are rejected before Window composition", () => {+ assert.throws(() => projectMomentWindow({itemId: "lead",semantic,moment: moment("cue", "a"),@@ -141,12 +186,12 @@ test("negative intermediate points clip before nearest half-later frame quantizastart: { ref: "moment.cue", offset: seconds(-2) },end: { ref: "moment.cue", offset: { unit: "milliseconds", value: 550 } },},- });- assert.deepEqual(result.span, { startFrame: 0, endFrameExclusive: 47 });+ }), /falls outside ProgramSpace/u);});test("program and absolute projections use exact rational frame-rate arithmetic", () => {const ntsc: ProgramSpace = {+ id: "test-space", narrativeId: "test-narrative",durationSec: 1.001,frameRate: { numerator: 30_000, denominator: 1_001 },};@@ -163,6 +208,7 @@ test("program and absolute projections use exact rational frame-rate arithmetic"test("frame and authored durations enter one exact sample-boundary rule", () => {const ntsc: ProgramSpace = {+ id: "test-space", narrativeId: "test-narrative",durationSec: 1.001,frameRate: { numerator: 30_000, denominator: 1_001 },};@@ -172,6 +218,7 @@ test("frame and authored durations enter one exact sample-boundary rule", () =>assert.equal(temporalDurationInSamples({ unit: "milliseconds", value: 125 }, ntsc), 6_000);assert.equal(temporalDurationInSamples(seconds(1, 3), ntsc), 16_000);const twentyFour: ProgramSpace = {+ id: "test-space", narrativeId: "test-narrative",durationSec: 1,frameRate: { numerator: 24, denominator: 1 },};@@ -187,7 +234,7 @@ test("crossed source anchors are allowed until a projection actually consumes thassert.throws(() => projectSelectionWindow({itemId: "identity", semantic, selection: crossed,projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },- }), /reversed raw window/u);+ }), /endpoints are reversed/u);assert.deepEqual(projectSelectionWindow({itemId: "persist", semantic, selection: crossed,projection: { start: { ref: "selection.start" }, end: { ref: "program.end" } },@@ -198,18 +245,18 @@ test("zero, fully outside and sub-frame windows fail atomically", () => {assert.throws(() => projectProgramWindow({itemId: "zero", semantic,projection: { start: { ref: "program.start" }, end: { ref: "program.start" } },- }), /zero raw window/u);+ }), /zero window/u);assert.throws(() => projectProgramWindow({itemId: "outside", semantic,projection: { start: { ref: "program.end", offset: frames(1) }, end: { ref: "program.end", offset: frames(2) } },- }), /does not intersect/u);+ }), /falls outside ProgramSpace/u);assert.throws(() => projectProgramWindow({itemId: "tiny", semantic,projection: {start: { ref: "absolute", at: seconds(1, 100) },end: { ref: "absolute", at: seconds(7, 500) },},- }), /shorter than one frame/u);+ }), /zero window/u);});test("disjoint validation checks physical overlap without reordering the input", () => {diff --git a/packages/typography-track/package.json b/packages/typography-track/package.jsonindex 1a25cf61..fc7d9056 100644--- a/packages/typography-track/package.json+++ b/packages/typography-track/package.json@@ -22,6 +22,7 @@"@hypit/spatial": "workspace:*","@hypit/svs": "workspace:*","@hypit/temporal": "workspace:*",+ "@hypit/temporal-markup": "workspace:*","@hypit/text": "workspace:*","@hypit/visual-ir": "workspace:*","@hypit/markup": "workspace:*"diff --git a/packages/typography-track/src/component.ts b/packages/typography-track/src/component.tsindex b535a617..a8062631 100644--- a/packages/typography-track/src/component.ts+++ b/packages/typography-track/src/component.ts@@ -1,6 +1,5 @@import type { ComponentPackage } from "@hypit/component-kit";-import type { SemanticTrack } from "@hypit/semantic-track";-import { projectSemanticProgramSpace } from "@hypit/semantic-track";+import type { ProgramSpace } from "@hypit/program-space";import type { CompositableSurfaceRef } from "@hypit/media";import type { SpatialFrame, SpatialPath, SpatialPoint } from "@hypit/spatial";import type { StoredValue } from "@hypit/protocol";@@ -59,6 +58,7 @@ export const typographyTrackComponent = {handler: ({ inputs }) => ({ outputs: { set: output(appendProjectedTextItem(inline<TypographyTrackSet>(inputs.set?.value, "TypographyTrackSet"),inline<TypographyTrackHeader>(inputs.header?.value, "TypographyTrackHeader"),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),inline<TextPlacement>(inputs.placement?.value, "TextPlacement"),inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),inline<TextStyle>(inputs.style?.value, "TextStyle"),@@ -76,14 +76,14 @@ export const typographyTrackComponent = {{producer: typographyTrackProducers.render,handler: ({ inputs }) => ({ outputs: { track: output(renderTypographyTrack(- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),inline<TypographyTrackProgram>(inputs.program?.value, "TypographyTrackProgram"),)) }, needs: {} }),},{producer: typographyTrackProducers.renderMask,handler: ({ inputs }) => ({ outputs: { track: output(renderTextMaskTrack(- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),inline<TypographyTrackProgram>(inputs.program?.value, "TypographyTrackProgram"),inline<CompositableSurfaceRef>(inputs.material?.value, "CompositableSurfaceRef"),inline<TextMaskSpec>(inputs.spec?.value, "TextMaskSpec"),diff --git a/packages/typography-track/src/fragment.ts b/packages/typography-track/src/fragment.tsindex feea28f9..54a6e304 100644--- a/packages/typography-track/src/fragment.ts+++ b/packages/typography-track/src/fragment.ts@@ -1,7 +1,7 @@import { compositionTypes } from "@hypit/composition";import type { VisualTrack } from "@hypit/composition";import { sealGraphFragment } from "@hypit/elaborator";-import { semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { typographyTrackProducers, typographyTrackTypes } from "./manifest.js";@@ -14,12 +14,20 @@ export const typographyTrackFragment = sealGraphFragment({{ name: "semantic", type: semanticTrackTypes.track },{ name: "program", type: typographyTrackTypes.program },],- operations: [{- id: "render",- producer: typographyTrackProducers.render,- inputs: { semantic: input("semantic"), program: input("program") },- result: { kind: "output", name: "track" },- }],+ operations: [+ {+ id: "space",+ producer: semanticTrackProducers.projectProgramSpace,+ inputs: { track: input("semantic") },+ result: { kind: "output", name: "space" },+ },+ {+ id: "render",+ producer: typographyTrackProducers.render,+ inputs: { space: operation("space"), program: input("program") },+ result: { kind: "output", name: "track" },+ },+ ],exports: [{name: "track",type: compositionTypes.visualTrack,diff --git a/packages/typography-track/src/manifest.ts b/packages/typography-track/src/manifest.tsindex 99be24e4..6303c9bf 100644--- a/packages/typography-track/src/manifest.ts+++ b/packages/typography-track/src/manifest.ts@@ -1,6 +1,7 @@import { readFile } from "node:fs/promises";-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";+import { narrativeDependency } from "@hypit/narrative";+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";import {compositionDependency,@@ -24,6 +25,7 @@ import { svsRecipeType } from "@hypit/svs";import { textDependency, textTypes } from "@hypit/text";import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";import { temporalDependency, temporalTypes } from "@hypit/temporal";+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";const previewImage = (file: string) => ({mediaType: "image/png",@@ -418,7 +420,7 @@ export const typographyTrackMarkupSurfaces = [],},},- { name: "track", tag: "Track", mode: "structured", outputs: [typographyTrackTypes.header, typographyTrackTypes.itemSpec, typographyTrackTypes.plainItemSpec, typographyTrackTypes.motion, typographyTrackTypes.set, typographyTrackTypes.placement, temporalTypes.windowSpec, typographyTrackTypes.program, compositionTypes.visualTrack],+ { name: "track", tag: "Track", mode: "structured", outputs: [typographyTrackTypes.header, typographyTrackTypes.itemSpec, typographyTrackTypes.plainItemSpec, typographyTrackTypes.motion, typographyTrackTypes.set, typographyTrackTypes.placement, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, typographyTrackTypes.program, compositionTypes.visualTrack],vocabulary: {summary: "One Typography Track: independently placed and timed text items on a shared ProgramSpace, lowered to one addressable TypographyTrackProgram and one peer VisualTrack.",appearance: "Text alone on an otherwise empty Canvas: the glyphs, plus whatever Paint the Style puts around them — fills, outlines, glows, shadows and rounded, bordered, optionally tailed boxes drawn behind the frame, paragraph, line, run, word or grapheme. Each item holds its own region of the Canvas: a Point item is one unwrapped block that hugs its text and hangs off a single coordinate by its inline and block anchors, an Area item flows and wraps inside a rectangle under its own alignment, columns, clipping and overflow, and a Path item strings the glyphs along a curve, on one side of it, turning with it or standing upright. Items switch on and off at their own frame windows and overlap in the stacking order their Styles declare, so titles, labels and captions can occupy different corners at once and outlast or outlive one another. While an item is on screen it plays its Motion: the whole block translating, scaling, rotating, skewing, fading, blurring, recoloring or wiping open from an edge, and its paragraphs, lines, runs, words or graphemes arriving one behind another in a staggered run.",@@ -438,13 +440,7 @@ export const typographyTrackMarkupSurfaces = [{ name: "style", kind: "reference", required: true, accepts: [typographyTrackTypes.style], summary: "Chooses the compiled Style the item is drawn in." },{ name: "motion", kind: "reference", required: false, accepts: [typographyTrackTypes.motion], summary: "Chooses the Motion the item plays; the Track supplies a still Motion otherwise." },{ name: "content", kind: "reference", required: false, accepts: [textTypes.text], summary: "Reads an ordinary graph Text as one plain run, which requires the item to be written empty." },- { name: "during", kind: "expression", required: false, accepts: [narrativeTypes.selection], summary: "Spans the whole program when written as `program`, or the window of the referenced Selection." },- { name: "at", kind: "reference", required: false, accepts: [narrativeTypes.moment], summary: "Starts the window at the cue of the referenced Moment." },- { name: "for", kind: "literal", required: false, summary: "Fixes the exact length of a Moment window, such as `12f`, `250ms` or `1.5s`." },- { name: "start", kind: "literal", required: false, summary: "Places the window start at a point expression." },- { name: "end", kind: "literal", required: false, summary: "Places the window end at a point expression." },- { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection], summary: "Binds the Selection that resolves `selection.start` and `selection.end` in a start/end window." },- { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment], summary: "Binds the Moment that resolves `moment.cue` in a start/end window." },+ ...temporalWindowAttributeVocabulary,],children: documentChildren,text: "Direct text is the item's whole document, read as one paragraph." },@@ -456,13 +452,7 @@ export const typographyTrackMarkupSurfaces = [{ name: "style", kind: "reference", required: true, accepts: [typographyTrackTypes.style], summary: "Chooses the compiled Style the item is drawn in." },{ name: "motion", kind: "reference", required: false, accepts: [typographyTrackTypes.motion], summary: "Chooses the Motion the item plays; the Track supplies a still Motion otherwise." },{ name: "content", kind: "reference", required: false, accepts: [textTypes.text], summary: "Reads an ordinary graph Text as one plain run, which requires the item to be written empty." },- { name: "during", kind: "expression", required: false, accepts: [narrativeTypes.selection], summary: "Spans the whole program when written as `program`, or the window of the referenced Selection." },- { name: "at", kind: "reference", required: false, accepts: [narrativeTypes.moment], summary: "Starts the window at the cue of the referenced Moment." },- { name: "for", kind: "literal", required: false, summary: "Fixes the exact length of a Moment window, such as `12f`, `250ms` or `1.5s`." },- { name: "start", kind: "literal", required: false, summary: "Places the window start at a point expression." },- { name: "end", kind: "literal", required: false, summary: "Places the window end at a point expression." },- { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection], summary: "Binds the Selection that resolves `selection.start` and `selection.end` in a start/end window." },- { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment], summary: "Binds the Moment that resolves `moment.cue` in a start/end window." },+ ...temporalWindowAttributeVocabulary,],children: documentChildren,text: "Direct text is the item's whole document, read as one paragraph." },@@ -474,13 +464,7 @@ export const typographyTrackMarkupSurfaces = [{ name: "style", kind: "reference", required: true, accepts: [typographyTrackTypes.style], summary: "Chooses the compiled Style the item is drawn in." },{ name: "motion", kind: "reference", required: false, accepts: [typographyTrackTypes.motion], summary: "Chooses the Motion the item plays; the Track supplies a still Motion otherwise." },{ name: "content", kind: "reference", required: false, accepts: [textTypes.text], summary: "Reads an ordinary graph Text as one plain run, which requires the item to be written empty." },- { name: "during", kind: "expression", required: false, accepts: [narrativeTypes.selection], summary: "Spans the whole program when written as `program`, or the window of the referenced Selection." },- { name: "at", kind: "reference", required: false, accepts: [narrativeTypes.moment], summary: "Starts the window at the cue of the referenced Moment." },- { name: "for", kind: "literal", required: false, summary: "Fixes the exact length of a Moment window, such as `12f`, `250ms` or `1.5s`." },- { name: "start", kind: "literal", required: false, summary: "Places the window start at a point expression." },- { name: "end", kind: "literal", required: false, summary: "Places the window end at a point expression." },- { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection], summary: "Binds the Selection that resolves `selection.start` and `selection.end` in a start/end window." },- { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment], summary: "Binds the Moment that resolves `moment.cue` in a start/end window." },+ ...temporalWindowAttributeVocabulary,],children: documentChildren,text: "Direct text is the item's whole document, read as one paragraph." },@@ -501,7 +485,7 @@ export const typographyTrackMarkupSurfaces = [</text:Track>`,notes: ["A Track requires at least one `<Point>`, `<Area>` or `<Path>` and accepts no text content of its own.",- "An item states exactly one window form: `during`, `at` with `for`, or `start` with `end`; `selection` and `moment` bind a start/end window and cannot be written together.",+ "An item states exactly one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`; `selection`, `segment` and `moment` bind a start/end window and cannot be written together.","A point expression is `program.start`, `program.end`, `selection.start`, `selection.end` or `moment.cue`, each optionally offset by `+` or `-` and a duration, or a bare duration read as an absolute position.","An item written without `content` owns its own document: direct text becomes one paragraph, and `<P>` children carry rich runs instead; a document mixes neither `<P>` children with direct text nor direct text with nested elements.","Neither a `<P>` nor a `<Span>` may be empty, and a `style` on either must name a Style Record authored in this Source or imported from another, because its typography and Paint are copied into the document as the item is decoded.",@@ -546,7 +530,7 @@ export const typographyTrackManifest: ModuleManifest = {format: "hypit.module@1",name: typographyTrackModuleRef.name,version: typographyTrackModuleRef.version,- dependencies: [narrativeDependency, semanticTrackDependency, spatialDependency, mediaDependency, compositionDependency, textDependency, temporalDependency],+ dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, mediaDependency, compositionDependency, textDependency, temporalDependency],types: [{ name: typographyTrackTypes.style.name },{ name: typographyTrackTypes.motion.name },@@ -565,9 +549,9 @@ export const typographyTrackManifest: ModuleManifest = {{ name: typographyTrackProducers.bindArea.name, inputs: [{ name: "frame", type: spatialTypes.frame }], outputs: [{ name: "placement", type: typographyTrackTypes.placement }], needs: [] },{ name: typographyTrackProducers.bindPath.name, inputs: [{ name: "path", type: spatialTypes.path }], outputs: [{ name: "placement", type: typographyTrackTypes.placement }], needs: [] },{ name: typographyTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: typographyTrackTypes.set }], needs: [] },- { name: typographyTrackProducers.appendItem.name, inputs: [{ name: "set", type: typographyTrackTypes.set }, { name: "header", type: typographyTrackTypes.header }, { name: "semantic", type: semanticTrackTypes.track }, { name: "placement", type: typographyTrackTypes.placement }, { name: "spec", type: typographyTrackTypes.itemSpec }, { name: "style", type: typographyTrackTypes.style }, { name: "motion", type: typographyTrackTypes.motion }, { name: "window", type: temporalTypes.window }], outputs: [{ name: "set", type: typographyTrackTypes.set }], needs: [] },+ { name: typographyTrackProducers.appendItem.name, inputs: [{ name: "set", type: typographyTrackTypes.set }, { name: "header", type: typographyTrackTypes.header }, { name: "space", type: programSpaceTypes.programSpace }, { name: "placement", type: typographyTrackTypes.placement }, { name: "spec", type: typographyTrackTypes.itemSpec }, { name: "style", type: typographyTrackTypes.style }, { name: "motion", type: typographyTrackTypes.motion }, { name: "window", type: temporalTypes.window }], outputs: [{ name: "set", type: typographyTrackTypes.set }], needs: [] },{ name: typographyTrackProducers.finalize.name, inputs: [{ name: "header", type: typographyTrackTypes.header }, { name: "set", type: typographyTrackTypes.set }], outputs: [{ name: "program", type: typographyTrackTypes.program }], needs: [] },- { name: typographyTrackProducers.render.name, inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: typographyTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },- { name: typographyTrackProducers.renderMask.name, inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "program", type: typographyTrackTypes.program }, { name: "material", type: mediaTypes.compositableSurface }, { name: "spec", type: typographyTrackTypes.maskSpec }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },+ { name: typographyTrackProducers.render.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: typographyTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },+ { name: typographyTrackProducers.renderMask.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: typographyTrackTypes.program }, { name: "material", type: mediaTypes.compositableSurface }, { name: "spec", type: typographyTrackTypes.maskSpec }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },],};diff --git a/packages/typography-track/src/program.ts b/packages/typography-track/src/program.tsindex cf773cc4..ae6e300b 100644--- a/packages/typography-track/src/program.ts+++ b/packages/typography-track/src/program.ts@@ -6,6 +6,7 @@ import {assertSpatialPoint,} from "@hypit/spatial";import type { SpatialFrame, SpatialPath, SpatialPoint } from "@hypit/spatial";+import { assertTemporalWindowFor } from "@hypit/temporal";import type { ProjectedWindow } from "@hypit/temporal";import {assertVisualTrackIdentity,@@ -100,6 +101,7 @@ export function assertTextStyle(style: TextStyle): void {}assertVisualTrackIdentity({kind: "visual",+ programSpaceId: "text-style-validation",visualIr: "hypit.visual-ir@1",id: "text-style-validation",presents: [{@@ -302,6 +304,7 @@ function append(export function appendProjectedTextItem(set: TypographyTrackSet,header: TypographyTrackHeader,+ space: ProgramSpace,placement: TextPlacement,spec: TextItemSpec,style: TextStyle,@@ -309,6 +312,7 @@ export function appendProjectedTextItem(window: ProjectedWindow,): TypographyTrackSet {assertTextPlacement(placement);+ assertTemporalWindowFor(window, { subjectId: spec.id, space });return append(set, header, spec, style, motion, placement.geometry, window);}@@ -555,6 +559,7 @@ function elements(item: TextItem): VisualElement[] {export function renderTypographyTrack(space: ProgramSpace, program: TypographyTrackProgram): VisualTrack {assertTypographyTrackProgramIdentity(program, space);const track = sealVisualTrack({+ programSpaceId: space.id,visualIr: "hypit.visual-ir@1",id: program.id,presents: program.items.map((item) => ({@@ -581,6 +586,7 @@ export function renderTextMaskTrack(throw new Error("Official Text Mask requires one explicit still material Surface; timed materials use an independent package.");}const track = sealVisualTrack({+ programSpaceId: space.id,visualIr: "hypit.visual-ir@1",id: spec.id,presents: program.items.map((item) => {diff --git a/packages/typography-track/src/surface.ts b/packages/typography-track/src/surface.tsindex 350b38c6..ecd55a58 100644--- a/packages/typography-track/src/surface.ts+++ b/packages/typography-track/src/surface.ts@@ -1,5 +1,4 @@-import { narrativeTypes } from "@hypit/narrative";-import { semanticTrackTypes } from "@hypit/semantic-track";+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";import { compositionTypes } from "@hypit/composition";import type {VisualColorPaint,@@ -25,16 +24,13 @@ import { textTypes } from "@hypit/text";import type {StructuredElement,StructuredSurfaceHandler,+ SurfaceComponentDraft,SurfaceRecordDraft,SurfaceResolvedReference,MarkupAttributeValue,} from "@hypit/markup";-import type {- TemporalDuration,- TemporalPointExpression,- TemporalWindowProjection,-} from "@hypit/temporal";-import { temporalProducers, temporalTypes } from "@hypit/temporal";+import { temporalTypes } from "@hypit/temporal";+import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";import { typographyTrackProducers, typographyTrackTypes } from "./manifest.js";import {@@ -536,77 +532,6 @@ export const decodeTypographyMotionSurface: StructuredSurfaceHandler = ({ elemenreturn { records: [{ id, type: typographyTrackTypes.motion, value: { kind: "inline", value: motion }, range: element.range }], components: [], fragments: [] };};-function divisor(left: number, right: number): number {- let a = Math.abs(left); let b = Math.abs(right);- while (b !== 0) [a, b] = [b, a % b];- return a;-}--function duration(value: string, label: string): TemporalDuration {- const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());- if (match === null) throw new Error(`${label} must be an exact duration such as 12f, 250ms or 1.5s.`);- const whole = Number(match[1]); const fraction = match[2] ?? ""; const unit = match[3];- if (!Number.isSafeInteger(whole)) throw new Error(`${label} is outside safe arithmetic.`);- if (unit === "f" || unit === "ms") {- if (fraction.length > 0) throw new Error(`${label} ${unit} duration must be an integer.`);- return { unit: unit === "f" ? "frames" : "milliseconds", value: whole };- }- const scale = 10 ** fraction.length;- const numerator = whole * scale + (fraction.length === 0 ? 0 : Number(fraction));- const gcd = divisor(numerator, scale);- return { unit: "seconds", numerator: numerator / gcd, denominator: scale / gcd };-}--function negate(value: TemporalDuration): TemporalDuration {- return value.unit === "seconds" ? { ...value, numerator: -value.numerator } : { ...value, value: -value.value };-}--function pointExpression(value: string, label: string): TemporalPointExpression {- const trimmed = value.trim();- const refs = ["program.start", "program.end", "selection.start", "selection.end", "moment.cue"] as const;- for (const ref of refs) {- if (trimmed === ref) return { ref };- const match = new RegExp(`^${ref.replace(".", "\\.")}\\s*([+-])\\s*(.+)$`, "u").exec(trimmed);- if (match !== null) {- const offset = duration(match[2]!, `${label} offset`);- return { ref, offset: match[1] === "-" ? negate(offset) : offset };- }- }- return { ref: "absolute", at: duration(trimmed, label) };-}--type TemporalBinding = {- readonly kind: "program" | "selection" | "moment";- readonly projection: TemporalWindowProjection;- readonly source?: SurfaceResolvedReference;-};--function temporalBinding(element: StructuredElement, resolve: (path: string) => SurfaceResolvedReference | undefined): TemporalBinding {- const during = element.attributes.during;- const at = element.attributes.at;- const start = optionalText(element, "start");- const end = optionalText(element, "end");- const selection = element.attributes.selection;- const moment = element.attributes.moment;- const forms = Number(during !== undefined) + Number(at !== undefined) + Number(start !== undefined || end !== undefined);- if (forms !== 1) throw new Error(`${element.name} requires exactly one of during, at/for, or start/end.`);- if (during !== undefined) {- if (typeof during === "string") {- if (during.trim() !== "program") throw new Error(`${element.name}.during text must be program.`);- return { kind: "program", projection: { start: { ref: "program.start" }, end: { ref: "program.end" } } };- }- return { kind: "selection", source: reference(during, `${element.name}.during`, narrativeTypes.selection, resolve), projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } } };- }- if (at !== undefined) {- return { kind: "moment", source: reference(at, `${element.name}.at`, narrativeTypes.moment, resolve), projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: duration(text(element, "for"), `${element.name}.for`) } } };- }- if (start === undefined || end === undefined) throw new Error(`${element.name} explicit timing requires start and end.`);- if (selection !== undefined && moment !== undefined) throw new Error(`${element.name} cannot bind Selection and Moment together.`);- if (selection !== undefined) return { kind: "selection", source: reference(selection, `${element.name}.selection`, narrativeTypes.selection, resolve), projection: { start: pointExpression(start, `${element.name}.start`), end: pointExpression(end, `${element.name}.end`) } };- if (moment !== undefined) return { kind: "moment", source: reference(moment, `${element.name}.moment`, narrativeTypes.moment, resolve), projection: { start: pointExpression(start, `${element.name}.start`), end: pointExpression(end, `${element.name}.end`) } };- return { kind: "program", projection: { start: pointExpression(start, `${element.name}.start`), end: pointExpression(end, `${element.name}.end`) } };-}-function dedent(value: string): string {const lines = value.replace(/^\n/u, "").replace(/\n\s*$/u, "").split("\n");const indentation = lines.filter((line) => line.trim()).reduce((min, line) => Math.min(min, /^\s*/u.exec(line)?.[0].length ?? 0), Number.POSITIVE_INFINITY);@@ -690,9 +615,7 @@ function document(element: StructuredElement, resolve: (path: string) => Surfacetype FragmentItem = {readonly suffix: string;- readonly binding: TemporalBinding["kind"];- readonly sourceName?: string;- readonly windowSpecName: string;+ readonly windowName: string;readonly placementKind: "point" | "area" | "path";readonly geometryName: string;readonly specName: string;@@ -702,7 +625,10 @@ type FragmentItem = {};function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphFragment {- const operations: FragmentOperation[] = [{ id: "text:set:empty", producer: typographyTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } }];+ const operations: FragmentOperation[] = [+ { id: "text:space", producer: semanticTrackProducers.projectProgramSpace, inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },+ { id: "text:set:empty", producer: typographyTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },+ ];let current = "text:set:empty";for (const [index, item] of items.entries()) {const bind = `text:placement:${String(index + 1).padStart(4, "0")}`;@@ -721,25 +647,18 @@ function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphFresult: { kind: "output", name: "spec" },});}- const windowId = `text:window:${String(index + 1).padStart(4, "0")}`;- const windowProducer = item.binding === "program" ? temporalProducers.projectProgram- : item.binding === "selection" ? temporalProducers.projectSelection : temporalProducers.projectMoment;- operations.push({ id: windowId, producer: windowProducer, inputs: {- semantic: input("semantic"), spec: input(item.windowSpecName),- ...(item.binding === "program" ? {} : { [item.binding]: input(item.sourceName!) }),- }, result: { kind: "output", name: "window" } });const append = `text:set:append:${String(index + 1).padStart(4, "0")}`;const common = {- set: operation(current), header: input("header"), semantic: input("semantic"), placement: operation(bind),+ set: operation(current), header: input("header"), space: operation("text:space"), placement: operation(bind),spec: item.contentName === undefined ? input(item.specName) : operation(materialized),- style: input(item.styleName), motion: input(item.motionName), window: operation(windowId),+ style: input(item.styleName), motion: input(item.motionName), window: input(item.windowName),};operations.push({ id: append, producer: typographyTrackProducers.appendItem, inputs: common, result: { kind: "output", name: "set" } });current = append;}operations.push({ id: "text:finalize", producer: typographyTrackProducers.finalize, inputs: { header: input("header"), set: operation(current) }, result: { kind: "output", name: "program" } },- { id: "text:render", producer: typographyTrackProducers.render, inputs: { semantic: input("semantic"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },+ { id: "text:render", producer: typographyTrackProducers.render, inputs: { space: operation("text:space"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },);const inputEntries = [{ name: "semantic", type: semanticTrackTypes.track },@@ -750,8 +669,7 @@ function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphF...(item.contentName === undefined ? [] : [{ name: item.contentName, type: textTypes.text }]),{ name: item.styleName, type: typographyTrackTypes.style },{ name: item.motionName, type: typographyTrackTypes.motion },- { name: item.windowSpecName, type: temporalTypes.windowSpec },- ...(item.sourceName === undefined ? [] : [{ name: item.sourceName, type: item.binding === "selection" ? narrativeTypes.selection : narrativeTypes.moment }]),+ { name: item.windowName, type: temporalTypes.window },]),];const inputs = [...new Map(inputEntries.map((value) => [value.name, value])).values()];@@ -780,11 +698,13 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element}];const defaultMotionId = `${id}.__still-motion`;records.push({ id: defaultMotionId, type: typographyTrackTypes.motion, value: { kind: "inline", value: stillTextMotion(defaultMotionId) }, range: element.range });+ const temporalComponents: SurfaceComponentDraft[] = [];+ const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];const items: Array<FragmentItem & {readonly geometry: SurfaceResolvedReference;readonly style: SurfaceResolvedReference;readonly motion: AuthorValueRef;- readonly source?: SurfaceResolvedReference;+ readonly window: ReturnType<typeof createTemporalWindowProjection>["ref"];readonly content?: SurfaceResolvedReference;readonly specId: string;}> = [];@@ -807,10 +727,11 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ elementconst index = items.length + 1;const suffix = String(index).padStart(4, "0");allowed(child, [- "id", "content", "placement", "style", "motion", "during", "at", "for", "start", "end", "selection", "moment",+ "id", "content", "placement", "style", "motion", ...temporalWindowAttributeNames,], ["id", "placement", "style"]);const itemId = text(child, "id");- const binding = temporalBinding(child, resolveReference);+ const temporal = createTemporalWindowProjection({ id: itemId, element: child, semantic, resolveReference });+ records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);const placementKind = form.toLowerCase() as "point" | "area" | "path";const geometry = reference(child.attributes.placement, `${child.name}.placement`, placementKind === "point" ? spatialTypes.point : placementKind === "area" ? spatialTypes.frame : spatialTypes.path, resolveReference);const style = reference(child.attributes.style, `${child.name}.style`, typographyTrackTypes.style, resolveReference);@@ -818,8 +739,7 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element? ({ kind: "record", id: defaultMotionId } as const): reference(child.attributes.motion, `${child.name}.motion`, typographyTrackTypes.motion, resolveReference).ref;const specId = `${id}.item.${suffix}.spec`;- const windowSpecId = `${id}.item.${suffix}.window`;- const windowSpecName = `item-${suffix}-window-spec`;+ const windowName = `item-${suffix}-window`;const content = child.attributes.content === undefined? undefined: reference(child.attributes.content, `${child.name}.content`, textTypes.text, resolveReference);@@ -837,43 +757,36 @@ export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ elementtype: content === undefined ? typographyTrackTypes.itemSpec : typographyTrackTypes.plainItemSpec,value: { kind: "inline", value: spec }, range: child.range,});- records.push({- id: windowSpecId,- type: temporalTypes.windowSpec,- value: { kind: "inline", value: { id: itemId, projection: binding.projection } }, range: child.range,- });items.push({- suffix, binding: binding.kind, placementKind, windowSpecName,+ suffix, placementKind, windowName,geometryName: sharedInputName("geometry", geometry.ref, suffix), specName: `item-${suffix}-spec`,styleName: sharedInputName("style", style.ref, suffix), motionName: sharedInputName("motion", motionRef, suffix),...(content === undefined ? {} : { contentName: sharedInputName("content", content.ref, suffix), content }),- ...(binding.source === undefined ? {} : { sourceName: sharedInputName("source", binding.source.ref, suffix), source: binding.source }),- geometry, style, motion: motionRef, specId,+ geometry, style, motion: motionRef, specId, window: temporal.ref,});}if (items.length === 0) throw new Error(`${element.name} requires at least one Point, Area or Path.`);- const fragmentItems: FragmentItem[] = items.map(({ suffix, binding, sourceName, placementKind, geometryName, specName, styleName, motionName, contentName, windowSpecName }) => ({- suffix, binding, placementKind, geometryName, specName, styleName, motionName, windowSpecName,- ...(contentName === undefined ? {} : { contentName }), ...(sourceName === undefined ? {} : { sourceName }),+ const fragmentItems: FragmentItem[] = items.map(({ suffix, placementKind, geometryName, specName, styleName, motionName, contentName, windowName }) => ({+ suffix, placementKind, geometryName, specName, styleName, motionName, windowName,+ ...(contentName === undefined ? {} : { contentName }),}));const fragment = createTrackFragment(id, fragmentItems);return {records,- components: [{+ components: [...temporalComponents, {id, fragment: fragment.id,inputs: {semantic: semantic.ref, header: { kind: "record", id: headerId },...Object.fromEntries(items.flatMap((item) => [[item.geometryName, item.geometry.ref], [item.specName, { kind: "record" as const, id: item.specId }],- [item.windowSpecName, { kind: "record" as const, id: `${id}.item.${item.suffix}.window` }],+ [item.windowName, item.window],[item.styleName, item.style.ref], [item.motionName, item.motion],...(item.content === undefined ? [] : [[item.contentName!, item.content.ref] as const]),- ...(item.source === undefined ? [] : [[item.sourceName!, item.source.ref] as const]),])),},outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range,}],- fragments: [fragment],+ fragments: [...temporalFragments, fragment],exports: [`${id}.program`, `${id}.track`],};};@@ -887,11 +800,17 @@ function createMaskFragment(id: string): GraphFragment {];return sealGraphFragment({inputs,- operations: [{- id: "text-mask:render", producer: typographyTrackProducers.renderMask,- inputs: { semantic: input("semantic"), program: input("program"), material: input("material"), spec: input("spec") },- result: { kind: "output", name: "track" },- }],+ operations: [+ {+ id: "text-mask:space", producer: semanticTrackProducers.projectProgramSpace,+ inputs: { track: input("semantic") }, result: { kind: "output", name: "space" },+ },+ {+ id: "text-mask:render", producer: typographyTrackProducers.renderMask,+ inputs: { space: operation("text-mask:space"), program: input("program"), material: input("material"), spec: input("spec") },+ result: { kind: "output", name: "track" },+ },+ ],exports: [{name: "track", type: compositionTypes.visualTrack, root: operation("text-mask:render"),}],diff --git a/packages/typography-track/test/typography-track.test.ts b/packages/typography-track/test/typography-track.test.tsindex d8561b6e..f7cefd8f 100644--- a/packages/typography-track/test/typography-track.test.ts+++ b/packages/typography-track/test/typography-track.test.ts@@ -2,6 +2,7 @@ import assert from "node:assert/strict";import test from "node:test";import { fixtureDigest } from "../../../test/fixture-digest.js";import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";+import { projectSelectionWindow } from "../../../test/temporal-fixture.js";import { spatialComponent, videoContractManifests } from "../../../test/support/video-domain.js";import { registerTypeValidatorFacets } from "@hypit/component-kit";@@ -47,9 +48,8 @@ import { svsManifest, svsRecipeType } from "@hypit/svs";import { sealText, textComponent, textDependency, textManifest, textTypes } from "@hypit/text";import { MarkupSurfaceRegistry, createMarkupAuthorFrontend } from "@hypit/markup";import { createRecordAdmitter, TypeValidatorRegistry } from "@hypit/validation";-import { projectSelectionWindow } from "@hypit/temporal";-const space = sealProgramSpace({+const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative",durationSec: 5,frameRate: { numerator: 30, denominator: 1 },});@@ -189,7 +189,7 @@ test("persistent and timed Text Items lower to ordinary VisualTrack Presents", (assert.deepEqual(track.presents.map((present) => present.id), ["watermark", "callout"]);assert.equal(track.presents[0]?.elements[2]?.kind, "text-flow");- const lower = sealVisualTrack({+ const lower = sealVisualTrack({ programSpaceId: "test-space",visualIr: "hypit.visual-ir@1",id: "lower",presents: [{@@ -278,6 +278,7 @@ test("TypographyTrackProgram rejects a frame span outside ProgramSpace", () => {test("Selection Text consumes explicit Selection, SemanticTrack, Style, Motion and Placement edges", () => {const selection: NarrativeSelectionRef = {+ narrativeId: space.narrativeId,id: "callout",startAnchorId: "selection:start",endAnchorId: "selection:end",@@ -291,6 +292,7 @@ test("Selection Text consumes explicit Selection, SemanticTrack, Style, Motion aconst program = finalizeTypographyTrack(header, appendProjectedTextItem(createTypographyTrackSet(),header,+ space,bindAreaTextPlacement({ xPx: 108, yPx: 192, widthPx: 864, heightPx: 192 }),spec,textStyle("meaning", 80),diff --git a/services/media-lambda/README.md b/services/media-lambda/README.mdindex 3aebbe00..9eb2d563 100644--- a/services/media-lambda/README.md+++ b/services/media-lambda/README.md@@ -1,7 +1,7 @@# Hypit media execution service-This service answers eight media Needs in AWS Lambda: inspect, normalize, transform, extract audio,-extract frame, speech-evidence projection, timeline audio and mux. It is deployment state, not an+This service answers nine media Needs in AWS Lambda: inspect, normalize, transform, extract audio,+extract frame, still-video rendering, speech-evidence projection, timeline audio and mux. It is deployment state, not anauthor-importable SVML package.It owns no media semantics. `@hypit/media-execution` contains the FFmpeg commands anddiff --git a/services/media-lambda/src/handler.ts b/services/media-lambda/src/handler.tsindex 10089fca..f05387c2 100644--- a/services/media-lambda/src/handler.ts+++ b/services/media-lambda/src/handler.ts@@ -8,6 +8,7 @@ import {executeNormalizeMedia,executeProjectSpeechEvidenceAudio,executeRenderTimelineAudio,+ executeRenderStillVideo,executeTransformMedia,} from "@hypit/media-execution";import type { MediaExecutionEnvironment, MediaOperationResult } from "@hypit/media-execution";@@ -39,6 +40,7 @@ const OPERATIONS: Record<"transform": executeTransformMedia,"extract-audio": executeExtractAudio,"extract-frame": executeExtractFrame,+ "render-still": executeRenderStillVideo,"project-speech-evidence-audio": executeProjectSpeechEvidenceAudio,"render-audio": executeRenderTimelineAudio,"mux": executeMuxProgramMedia,diff --git a/test/semantic-track-fixture.ts b/test/semantic-track-fixture.tsindex 56ff604e..31858c6e 100644--- a/test/semantic-track-fixture.ts+++ b/test/semantic-track-fixture.ts@@ -39,7 +39,9 @@ export function semanticTrackFixture(]));let startFrame = 0;return {- id: options.id ?? "semantic",+ // A SemanticTrack is the author-visible identity of the ProgramSpace it projects.+ id: options.id ?? space.id,+ narrativeId: space.narrativeId,items: segments.map((segment, index) => {const endFrameExclusive = startFrame + segment.frameCount;const startAnchorId = `segment:${segment.id}:start`;@@ -50,6 +52,7 @@ export function semanticTrackFixture(&& (index === segments.length - 1 ? anchor.frame <= endFrameExclusive : anchor.frame < endFrameExclusive)).map((anchor) => ({ identity: anchor.identity, frame: anchor.frame - startFrame }));const take = {+ narrativeId: space.narrativeId,media: {timeline: { frameRate: space.frameRate, frameCount: segment.frameCount },audio: { artifact: audioArtifact },diff --git a/test/temporal-fixture.ts b/test/temporal-fixture.tsnew file mode 100644index 00000000..bf471ace--- /dev/null+++ b/test/temporal-fixture.ts@@ -0,0 +1,87 @@+import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";+import type { SemanticTrack } from "@hypit/semantic-track";+import {+ composeTemporalWindow,+ projectMomentInstant,+ projectProgramInstant,+ projectSegmentInstant,+ projectSelectionInstant,+} from "@hypit/temporal";+import type { TemporalInstantExpression } from "@hypit/temporal";++export type TemporalWindowProjection = {+ readonly start: TemporalInstantExpression;+ readonly end: TemporalInstantExpression;+};++const fixed = { kind: "fixed" as const };++export function projectProgramInstantFixture(input: {+ readonly itemId: string;+ readonly subjectId?: string;+ readonly semantic: SemanticTrack;+ readonly projection: TemporalInstantExpression;+}) {+ return projectProgramInstant({ ...input, subjectId: input.subjectId ?? input.itemId, authority: fixed });+}++export function projectMomentInstantFixture(input: {+ readonly itemId: string;+ readonly subjectId?: string;+ readonly semantic: SemanticTrack;+ readonly moment: NarrativeMomentRef;+ readonly projection: TemporalInstantExpression;+}) {+ return projectMomentInstant({ ...input, subjectId: input.subjectId ?? input.itemId, authority: fixed });+}++export function projectProgramWindow(input: {+ readonly itemId: string;+ readonly subjectId?: string;+ readonly semantic: SemanticTrack;+ readonly projection: TemporalWindowProjection;+}) {+ const subjectId = input.subjectId ?? input.itemId;+ return composeTemporalWindow({ id: input.itemId, subjectId },+ projectProgramInstant({ itemId: `${input.itemId}.start`, subjectId, semantic: input.semantic, projection: input.projection.start, authority: fixed }),+ projectProgramInstant({ itemId: `${input.itemId}.end`, subjectId, semantic: input.semantic, projection: input.projection.end, authority: fixed }));+}++export function projectSelectionWindow(input: {+ readonly itemId: string;+ readonly subjectId?: string;+ readonly semantic: SemanticTrack;+ readonly selection: NarrativeSelectionRef;+ readonly projection: TemporalWindowProjection;+}) {+ const subjectId = input.subjectId ?? input.itemId;+ return composeTemporalWindow({ id: input.itemId, subjectId },+ projectSelectionInstant({ itemId: `${input.itemId}.start`, subjectId, semantic: input.semantic, selection: input.selection, projection: input.projection.start, authority: fixed }),+ projectSelectionInstant({ itemId: `${input.itemId}.end`, subjectId, semantic: input.semantic, selection: input.selection, projection: input.projection.end, authority: fixed }));+}++export function projectSegmentWindow(input: {+ readonly itemId: string;+ readonly subjectId?: string;+ readonly semantic: SemanticTrack;+ readonly segment: NarrativeExcerpt;+ readonly projection: TemporalWindowProjection;+}) {+ const subjectId = input.subjectId ?? input.itemId;+ return composeTemporalWindow({ id: input.itemId, subjectId },+ projectSegmentInstant({ itemId: `${input.itemId}.start`, subjectId, semantic: input.semantic, segment: input.segment, projection: input.projection.start, authority: fixed }),+ projectSegmentInstant({ itemId: `${input.itemId}.end`, subjectId, semantic: input.semantic, segment: input.segment, projection: input.projection.end, authority: fixed }));+}++export function projectMomentWindow(input: {+ readonly itemId: string;+ readonly subjectId?: string;+ readonly semantic: SemanticTrack;+ readonly moment: NarrativeMomentRef;+ readonly projection: TemporalWindowProjection;+}) {+ const subjectId = input.subjectId ?? input.itemId;+ return composeTemporalWindow({ id: input.itemId, subjectId },+ projectMomentInstant({ itemId: `${input.itemId}.start`, subjectId, semantic: input.semantic, moment: input.moment, projection: input.projection.start, authority: fixed }),+ projectMomentInstant({ itemId: `${input.itemId}.end`, subjectId, semantic: input.semantic, moment: input.moment, projection: input.projection.end, authority: fixed }));+}