Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

refactor: unify Studio items and temporal inverses

kashorin91d98a1b2d75
diff --git a/packages/audio-track/src/studio.ts b/packages/audio-track/src/studio.ts
index 8b26d0cd..126d16de 100644
--- a/packages/audio-track/src/studio.ts
+++ b/packages/audio-track/src/studio.ts
@@ -3,7 +3,7 @@ import type { StudioTrackCompanion, StudioTrackCompanionContext } from "@hypit/s
import {
artifactPreview,
authoredItemTitle,
- childEntities,
+ childItems,
previewLayer,
requiredSurfaceValue,
temporalLineageFor,
@@ -24,14 +24,14 @@ function projectAudio(context: StudioTrackCompanionContext) {
sourceTypes: [audioTrackTypes.clipSpec],
preview: artifactPreview("audio", clip.source.artifact.resource),
}));
- return childEntities(context, clips, "audio-clip", "standard").map((entity, index) => {
+ return childItems(context, clips, "audio-clip", "standard").map((item, index) => {
const clip = clips[index]!;
const temporal = temporalLineageFor(context, clip.id, "window");
const semanticSource = temporalDomainSource(temporal);
return {
- ...entity,
+ ...item,
display: {
- title: authoredItemTitle(context, entity.authoredId, clip.sourceTypes, ["source"]),
+ title: authoredItemTitle(context, item.authoredId, clip.sourceTypes, ["source"]),
layers: [previewLayer(clip.preview, "waveform")],
},
...(semanticSource?.id === undefined ? {} : { markerId: semanticSource.id }),
diff --git a/packages/caption-fine/src/studio.ts b/packages/caption-fine/src/studio.ts
index 02094bf7..e29fb051 100644
--- a/packages/caption-fine/src/studio.ts
+++ b/packages/caption-fine/src/studio.ts
@@ -7,10 +7,11 @@ import type { FineCaptionSchedule } from "./types.js";
import type {
StudioTrackCompanion,
StudioTrackCompanionContext,
- StudioEntityDraft,
+ StudioItemDraft,
+ StudioInspectorObjectDraft,
StudioInspectorFieldDeclaration,
} from "@hypit/studio-companion";
-import { authoredChildFor, temporalLineageFor, temporalDomainSource, requiredReferencedValue, requiredSurfaceValue } from "@hypit/studio-companion";
+import { authoredChildFor, requiredReferencedValue, requiredSurfaceValue } from "@hypit/studio-companion";
const styleSurface = captionFineMarkupSurfaces.find((surface) => surface.name === "style");
@@ -114,41 +115,57 @@ function cueText(document: CaptionDocument | undefined, unitIds: readonly string
.join("");
}
-export function projectCaptionContents(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
- const content = requiredReferencedValue(context, "timing", captionTypes.timing) as CaptionTiming;
+export function projectCaptionContents(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
+ const timing = requiredReferencedValue(context, "timing", captionTypes.timing) as CaptionTiming;
const schedule = requiredSurfaceValue(context, "schedule") as FineCaptionSchedule;
const document = requiredReferencedValue(context, "document", captionTypes.document) as CaptionDocument;
- if (document.id !== content.documentId) throw new Error("Caption content belongs to another CaptionDocument.");
- const cues = new Map<string, FineCaptionSchedule["cues"][number]>();
- for (const cue of schedule.cues) if (!cues.has(cue.cueId)) cues.set(cue.cueId, cue);
- return [...cues.values()].map((cue, index): StudioEntityDraft => ({
- id: `${context.track.outputRef}:cue:${cue.cueId}`, authoredId: cue.cueId,
- display: { title: `#${index + 1}`, layers: [{ kind: "text", role: "content", text: cueText(document, cue.units.map(unit => unit.unitId)) }] },
- startFrame: cue.timedStartFrame, endFrameExclusive: cue.timedEndFrameExclusive, stackOrder: 0,
- renderIds: schedule.cues.filter(item => item.cueId === cue.cueId).map(item => item.id),
- presentation: { entity: "caption-cue", chrome: "standard" },
- inspector: [{ id: "range", label: "Range", domain: "when", section: { id: "cue", label: "Cue" }, value: `${cue.timedStartFrame}–${cue.timedEndFrameExclusive}`, unit: "f" }],
- }));
+ if (document.id !== timing.documentId) throw new Error("Caption timing belongs to another CaptionDocument.");
+ const units = new Map(timing.units.map((unit) => [unit.unitId, unit]));
+ return document.cues.map((cue, index): StudioItemDraft => {
+ const timed = cue.unitIds.map((unitId) => {
+ const unit = units.get(unitId);
+ if (unit === undefined) throw new Error(`Caption Cue ${cue.id} has no timing for Unit ${unitId}.`);
+ return unit;
+ });
+ if (timed.length === 0) throw new Error(`Caption Cue ${cue.id} contains no Units.`);
+ const startFrame = Math.min(...timed.map((unit) => unit.startFrame));
+ const endFrameExclusive = Math.max(...timed.map((unit) => unit.endFrameExclusive));
+ return {
+ id: `${context.track.outputRef}:cue:${cue.id}`, authoredId: cue.id,
+ display: { title: `#${index + 1}`, layers: [{ kind: "text", role: "content", text: cueText(document, cue.unitIds) }] },
+ startFrame, endFrameExclusive, stackOrder: 0,
+ renderIds: schedule.cues.filter(item => item.cueId === cue.id).map(item => item.id),
+ presentation: { kind: "caption-cue", chrome: "standard" },
+ inspector: [
+ { id: "range", label: "Range", domain: "when", section: { id: "cue", label: "Cue" }, value: `${startFrame}–${endFrameExclusive}`, unit: "f" },
+ ...(cue.role === undefined ? [] : [{ id: "role", label: "Role", domain: "how" as const, section: { id: "cue", label: "Cue" }, value: cue.role }]),
+ ],
+ };
+ });
+}
+
+export function projectCaption(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
+ return projectCaptionContents(context);
}
-export function projectCaption(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+export function projectCaptionUses(context: StudioTrackCompanionContext): readonly StudioInspectorObjectDraft[] {
const program = requiredSurfaceValue(context, "program") as CaptionProgram;
- const uses: StudioEntityDraft[] = program.uses.flatMap((use, index) => {
- if (use.window === undefined) return [];
+ return program.uses.map((use, index) => {
const child = authoredChildFor(context, use.id, []);
- const temporal = temporalLineageFor(context, use.window.subjectId, "window");
- const semantic = temporalDomainSource(temporal);
- return [{
- id: `${context.track.outputRef}:use:${use.id}`, authoredId: use.id,
- display: { title: use.styleId, layers: [] },
- ...use.window.span, stackOrder: index, ...(child === undefined ? {} : { elementRange: child.range }),
- ...(temporal === undefined ? {} : { temporal }),
- ...(semantic === undefined ? {} : { markerId: semantic.id }),
- presentation: { entity: "caption-use", chrome: "standard" }, band: "uses",
- inspector: [{ id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${use.window.span.startFrame}–${use.window.span.endFrameExclusive}`, unit: "f" }],
- }];
+ return {
+ id: `use:${use.id}`,
+ authoredId: use.id,
+ title: use.styleId,
+ ...(child === undefined ? {} : { elementRange: child.range }),
+ parameterReferences: { style: use.styleId },
+ inspector: [
+ { id: "order", label: "Order", domain: "how", section: { id: "rule", label: "Rule" }, value: index + 1 },
+ { id: "scope", label: "Scope", domain: "when", section: { id: "rule", label: "Rule" },
+ value: use.window === undefined ? "All matching cues" : use.window.subjectId },
+ { id: "role", label: "Role", domain: "how", section: { id: "rule", label: "Rule" }, value: use.role ?? "Any" },
+ ],
+ };
});
- return [...projectCaptionContents(context), ...uses];
}
export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] = [
@@ -157,10 +174,11 @@ export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] =
output: { type: compositionTypes.visualTrack, surface: "caption", modules: [captionFineModuleRef] },
family: "caption", tone: "magenta", icon: "captions",
lane: { heightPx: 36 },
- bands: [{
- id: "uses", placement: "after", heightPx: 15, display: "label",
+ inspectorObjects: [{
+ id: "uses", label: "Presentation Rules",
bindings: [{ name: "style", companion: true }],
inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "style", label: "Style" }, control: "text" }],
+ project: projectCaptionUses,
}],
requiredValues: ["schedule", "program"], project: projectCaption,
diff --git a/packages/caption-fine/test/studio-companion.test.ts b/packages/caption-fine/test/studio-companion.test.ts
index 6d06c6bb..f12a93b1 100644
--- a/packages/caption-fine/test/studio-companion.test.ts
+++ b/packages/caption-fine/test/studio-companion.test.ts
@@ -5,9 +5,9 @@ import type { FineCaptionSchedule } from "../src/index.js";
import { captionTypes } from "@hypit/caption";
import type { CaptionDocument } from "@hypit/caption";
import { compositionTypes } from "@hypit/composition";
-import type { StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-companion";
+import type { StudioTrackCompanionContext, StudioItemDraft } from "@hypit/studio-companion";
-import { captionFineInspectorFields, projectCaptionContents } from "../src/studio.js";
+import { captionFineInspectorFields, projectCaptionContents, projectCaptionUses } from "../src/studio.js";
test("Caption Companion owns Inspector grouping", () => {
const declared = (name: string) => captionFineInspectorFields.find((field) => field.binding === `style.${name}`);
@@ -34,14 +34,14 @@ test("Caption Companion projects Cue text and Style from public domain values",
};
const document: CaptionDocument = {
id: "story.caption",
- units: [{ id: "unit-1", groupId: "segment-1:turn-1", wordIds: ["word-1", "word-2"] }],
+ units: [{ id: "unit-1", wordIds: ["word-1", "word-2"] }],
words: [
{ id: "word-1", unitId: "unit-1", text: "真实", separatorBefore: "", attributes: [] },
{ id: "word-2", unitId: "unit-1", text: "字幕", separatorBefore: "", attributes: [] },
],
- cueBreaks: [],
+ cues: [{ id: "cue-1", unitIds: ["unit-1"] }],
};
- const base: StudioEntityDraft = {
+ const base: StudioItemDraft = {
id: "captions.track:cue-1", authoredId: "captions", display: { title: "cue-1", layers: [] },
startFrame: 8, endFrameExclusive: 24, stackOrder: 70, presentId: "cue-1",
elementRange: { start: 0, end: 80 },
@@ -94,22 +94,25 @@ test("Caption Companion projects Cue text and Style from public domain values",
assert.deepEqual([cue?.startFrame, cue?.endFrameExclusive], [10, 20]);
});
-test("Caption Uses keep authored windows and child ownership even with no rendered content", async () => {
+test("Caption Uses stay in Inspector while Cues remain independent of rendered content", async () => {
const { projectCaption } = await import("../src/studio.js");
- const { temporalTypes } = await import("@hypit/temporal");
const { timelineFixture } = await import("../../../test/timeline-fixture.js");
const { projectProgramWindow } = await import("../../../test/temporal-fixture.js");
const timeline = timelineFixture({id:"film",frameCount: 180, frameRate: { numerator: 30, denominator: 1 }}, {segments:[{id:"a",frameCount:90},{id:"b",frameCount:90}]});
- const uses = ["base", "hidden"].map(id=>({id,styleId:id,window:projectProgramWindow({itemId:id,semantic:timeline,projection:{start:{ref:"timeline.start"},end:{ref:"timeline.end"}}})}));
+ const uses = [
+ { id: "base", styleId: "base" },
+ { id: "hidden", styleId: "hidden", window: projectProgramWindow({itemId:"hidden",semantic:timeline,projection:{start:{ref:"timeline.start"},end:{ref:"timeline.end"}}}) },
+ ];
const context = {
track:{outputRef:"captions.track",trace:{references:[{input:"document",typeRef:captionTypes.document,ref:"document"},{input:"timing",typeRef:captionTypes.timing,ref:"timing"}],outputPorts:[{name:"schedule",ref:"schedule"},{name:"program",ref:"program"}]}},
placement:{children:uses.map((use,i)=>({id:use.id,range:{start:i*10,end:i*10+8},referenceAttributes:{style:use.styleId},values:[]}))},
- values:new Map<string,unknown>([["document",{id:"document",units:[],words:[]}],["timing",{timelineId:"film",documentId:"document",units:[]}],["schedule",{cues:[]}],["program",{uses}]]),
+ values:new Map<string,unknown>([["document",{id:"document",units:[],words:[],cues:[]}],["timing",{timelineId:"film",documentId:"document",units:[]}],["schedule",{cues:[]}],["program",{uses}]]),
spans:[],temporalBindings:[],
} as unknown as StudioTrackCompanionContext;
- const entities=projectCaption(context);
- assert.deepEqual(entities.map(item=>[item.display.title,item.startFrame,item.endFrameExclusive,item.elementRange]),[
- ["base",0,180,{start:0,end:8}],["hidden",0,180,{start:10,end:18}],
+ assert.deepEqual(projectCaption(context), []);
+ const objects=projectCaptionUses(context);
+ assert.deepEqual(objects.map(item=>[item.title,item.elementRange,item.inspector?.find(field=>field.id==="scope")?.value]),[
+ ["base",{start:0,end:8},"All matching cues"],["hidden",{start:10,end:18},"hidden"],
]);
- assert.ok(entities.every(item=>item.band==="uses" && item.presentation?.chrome==="standard"));
+ assert.ok(objects.every(item=>item.parameterReferences?.style===item.title));
});
diff --git a/packages/comment-sticker/src/studio.ts b/packages/comment-sticker/src/studio.ts
index a8aaba9f..1d70f9ca 100644
--- a/packages/comment-sticker/src/studio.ts
+++ b/packages/comment-sticker/src/studio.ts
@@ -1,8 +1,8 @@
import { commentStickerMarkupSurfaces, commentStickerModuleRef, commentStickerTypes } from "./index.js";
import type { CommentStickerProgram } from "./index.js";
import { compositionTypes } from "@hypit/hypit/composition";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-companion";
-import { artifactPreview, childEntities, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalDomainSource, textLayer } from "@hypit/studio-companion";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioItemDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-companion";
+import { artifactPreview, childItems, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalDomainSource, textLayer } from "@hypit/studio-companion";
const frameParameters: readonly StudioSourceBindingDeclaration[] = [
{ name: "within" },
@@ -68,7 +68,7 @@ const commentInspector: readonly StudioInspectorFieldDeclaration[] = commentProp
};
});
-function projectComments(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectComments(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const program = requiredSurfaceValue(context, "program") as CommentStickerProgram;
const items = program.items.map((item) => ({
id: item.id,
@@ -78,15 +78,15 @@ function projectComments(context: StudioTrackCompanionContext): readonly StudioE
stackOrder: item.style.stackingOrder,
sourceTypes: [commentStickerTypes.itemSpec],
}));
- return childEntities(context, items, "comment-sticker", "standard").map((entity, index) => {
+ return childItems(context, items, "comment-sticker", "standard").map((projected, index) => {
const item = program.items[index];
- if (item === undefined) return entity;
+ if (item === undefined) return projected;
const temporal = temporalLineageFor(context, item.id, "window");
const semanticSource = temporalDomainSource(temporal);
return {
- ...entity,
+ ...projected,
display: {
- title: entity.display.title,
+ title: projected.display.title,
layers: [
...(item.avatar === undefined ? [] : [previewLayer(artifactPreview("image", item.avatar.resource), "contain", "decoration")]),
textLayer(item.content.comment),
diff --git a/packages/depth-stack/src/studio.ts b/packages/depth-stack/src/studio.ts
index 7692996c..fb90fe96 100644
--- a/packages/depth-stack/src/studio.ts
+++ b/packages/depth-stack/src/studio.ts
@@ -1,7 +1,7 @@
import { depthStackMarkupSurfaces, depthStackModuleRef } from "./index.js";
import type { DepthStackProgram } from "./index.js";
import { compositionTypes } from "@hypit/hypit/composition";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-companion";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioItemDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-companion";
import { requiredSurfaceValue, temporalLineageFor, temporalDomainSource } from "@hypit/studio-companion";
const deckProperties = (depthStackMarkupSurfaces
@@ -76,12 +76,12 @@ function cardTitle(card: DepthStackProgram["cards"][number]): string {
return text || card.id;
}
-function projectDeck(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectDeck(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const program = requiredSurfaceValue(context, "program") as DepthStackProgram;
if (context.placement === undefined) return context.generic();
const children = new Map(context.placement.children.flatMap((child) =>
child.id === undefined ? [] : [[child.id, child] as const]));
- return program.cards.map((card, index): StudioEntityDraft => {
+ return program.cards.map((card, index): StudioItemDraft => {
const child = children.get(card.id);
const temporal = temporalLineageFor(context, card.id, "activation");
const markerId = temporalDomainSource(temporal)?.id;
@@ -91,7 +91,7 @@ function projectDeck(context: StudioTrackCompanionContext): readonly StudioEntit
const appearance = child?.referenceAttributes.appearance
?? context.placement?.referenceAttributes.appearance;
return {
- id: `${context.track.outputRef}:entity:${card.id}`,
+ id: `${context.track.outputRef}:item:${card.id}`,
authoredId: card.id,
...(markerId === undefined ? {} : { markerId }),
display: { title: cardTitle(card), layers: [] },
@@ -101,7 +101,7 @@ function projectDeck(context: StudioTrackCompanionContext): readonly StudioEntit
...(child === undefined ? {} : { elementRange: child.range }),
...(render === undefined ? {} : { presentId: render.id, renderIds: renders.map((span) => span.id) }),
...(appearance === undefined ? {} : { parameterReferences: { appearance } }),
- presentation: { entity: "deck-card", chrome: "standard" },
+ presentation: { kind: "deck-card", chrome: "standard" },
...(temporal === undefined ? {} : { temporal }),
};
});
diff --git a/packages/narrative-temporal/package.json b/packages/narrative-temporal/package.json
index 27196f52..43ee8e2a 100644
--- a/packages/narrative-temporal/package.json
+++ b/packages/narrative-temporal/package.json
@@ -18,6 +18,7 @@
"@hypit/protocol": "workspace:*",
"@hypit/temporal": "workspace:*",
"@hypit/timeline": "workspace:*",
- "@hypit/admission": "workspace:*"
+ "@hypit/admission": "workspace:*",
+ "@hypit/studio-companion": "workspace:*"
}
}
diff --git a/packages/narrative-temporal/src/activation.ts b/packages/narrative-temporal/src/activation.ts
index a0bb3ec9..f5274b00 100644
--- a/packages/narrative-temporal/src/activation.ts
+++ b/packages/narrative-temporal/src/activation.ts
@@ -1,14 +1,20 @@
import { createAdmissionPackageFacet } from "@hypit/admission";
import { createProducerPackageFacet } from "@hypit/producer";
import { createMarkupSurfaceFacet } from "@hypit/markup";
+import { createStudioCompanionFacet } from "@hypit/studio-companion";
import { decodeNarrativeInstantSurface, decodeNarrativeProjectionSurface, decodeNarrativeWindowSurface,
narrativeProjectionMarkupSurfaces, narrativeTemporalComponent,
narrativeTemporalManifest, narrativeTemporalModuleRef } from "./index.js";
+import { narrativeStudioTemporalDeclarations, narrativeStudioTemporalRelations } from "./studio.js";
export const hypitPackage = {
format: "hypit.package@1" as const,
modules: [{ manifest: narrativeTemporalManifest }],
facets: [
+ createStudioCompanionFacet({
+ temporalDeclarations: narrativeStudioTemporalDeclarations,
+ temporalRelations: narrativeStudioTemporalRelations,
+ }),
...[narrativeTemporalComponent].flatMap((component) => [createProducerPackageFacet(component), createAdmissionPackageFacet(component)]),
createMarkupSurfaceFacet({ module: narrativeTemporalModuleRef,
declaration: narrativeProjectionMarkupSurfaces.find((item) => item.name === "narrative-projection")!, handler: decodeNarrativeProjectionSurface }),
diff --git a/packages/narrative-temporal/src/studio.ts b/packages/narrative-temporal/src/studio.ts
new file mode 100644
index 00000000..419aa4e3
--- /dev/null
+++ b/packages/narrative-temporal/src/studio.ts
@@ -0,0 +1,82 @@
+import type {
+ StudioPlacement,
+ StudioTemporalDeclarationCompanion,
+ StudioTemporalDeclarationDraft,
+ StudioTemporalRelationCompanion,
+} from "@hypit/studio-companion";
+
+import { narrativeTemporalModuleRef, narrativeTemporalProducers } from "./manifest.js";
+
+function output(
+ placement: StudioPlacement,
+ name: string,
+): StudioTemporalDeclarationDraft | undefined {
+ if (placement.id === undefined) return undefined;
+ const found = placement.outputPorts.find((candidate) => candidate.name === name);
+ return found === undefined ? undefined : {
+ id: placement.id,
+ label: placement.id,
+ output: found.ref,
+ range: placement.range,
+ };
+}
+
+export const narrativeStudioTemporalDeclarations: readonly StudioTemporalDeclarationCompanion[] = [{
+ id: "window-declaration",
+ match: { module: narrativeTemporalModuleRef, surface: "narrative-window" },
+ project: ({ placement }) => {
+ const found = output(placement, "window");
+ return found === undefined ? [] : [found];
+ },
+}, {
+ id: "instant-declaration",
+ match: { module: narrativeTemporalModuleRef, surface: "narrative-instant" },
+ project: ({ placement }) => {
+ const found = output(placement, "instant");
+ return found === undefined ? [] : [found];
+ },
+}];
+
+function projectedInstant(
+ producer: (typeof narrativeTemporalProducers)["projectSelectionInstant" | "projectSegmentInstant" | "projectMomentInstant"],
+ sourceInput: "selection" | "segment" | "moment",
+): StudioTemporalRelationCompanion {
+ return {
+ id: producer.name,
+ match: { producer, output: "instant" },
+ invert: () => [],
+ trace({ output, inputs, identify }) {
+ const held = output.value as { readonly id?: unknown; readonly timelineId?: unknown; readonly frame?: unknown };
+ const spec = inputs.spec?.value as { readonly boundary?: unknown } | undefined;
+ const source = inputs[sourceInput];
+ const projection = inputs.projection?.value as { readonly id?: unknown } | undefined;
+ const recognized = identify(sourceInput);
+ if (source === undefined || recognized === undefined || typeof held.id !== "string"
+ || typeof held.timelineId !== "string" || !Number.isSafeInteger(held.frame)
+ || typeof projection?.id !== "string") return undefined;
+ const boundary = typeof spec?.boundary === "string" ? spec.boundary : "point";
+ const temporalSource = {
+ timelineId: held.timelineId,
+ type: source.type,
+ kind: recognized.kind,
+ id: recognized.itemId,
+ domain: { companion: recognized.companion, id: projection.id },
+ };
+ const reference = `${sourceInput}.${boundary === "cue" ? "cue" : boundary}`;
+ return {
+ kind: "instant",
+ expression: reference,
+ reference,
+ frame: held.frame as number,
+ source: temporalSource,
+ authority: { kind: "domain", source: temporalSource, boundary },
+ };
+ },
+ };
+}
+
+export const narrativeStudioTemporalRelations: readonly StudioTemporalRelationCompanion[] = [
+ projectedInstant(narrativeTemporalProducers.projectSelectionInstant, "selection"),
+ projectedInstant(narrativeTemporalProducers.projectSegmentInstant, "segment"),
+ projectedInstant(narrativeTemporalProducers.projectMomentInstant, "moment"),
+];
diff --git a/packages/narrative-temporal/test/studio.test.ts b/packages/narrative-temporal/test/studio.test.ts
new file mode 100644
index 00000000..1fd9f389
--- /dev/null
+++ b/packages/narrative-temporal/test/studio.test.ts
@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { StudioPlacement } from "@hypit/studio-companion";
+
+import { narrativeTemporalModuleRef } from "../src/manifest.js";
+import { narrativeStudioTemporalDeclarations } from "../src/studio.js";
+
+const placement = (surface: string, port: string): StudioPlacement => ({
+ tag: `semantic:${surface}`,
+ module: narrativeTemporalModuleRef,
+ sourcePath: "main.svml",
+ surface,
+ id: "claim",
+ range: { start: 4, end: 24 },
+ records: [], values: [], outputs: ["claim"], outputPorts: [{ name: port, ref: "claim" }],
+ children: [], attributes: {}, attributeValueRanges: {}, referenceAttributes: {}, referenceTypes: {}, references: [],
+});
+
+test("Narrative temporal companions expose semantic Window and Instant as the same declaration shape", () => {
+ const window = narrativeStudioTemporalDeclarations.find((item) => item.match.surface === "narrative-window")!;
+ const instant = narrativeStudioTemporalDeclarations.find((item) => item.match.surface === "narrative-instant")!;
+ assert.deepEqual(window.project({ placement: placement("Window", "window") }),
+ [{ id: "claim", label: "claim", output: "claim", range: { start: 4, end: 24 } }]);
+ assert.deepEqual(instant.project({ placement: placement("Instant", "instant") }),
+ [{ id: "claim", label: "claim", output: "claim", range: { start: 4, end: 24 } }]);
+});
diff --git a/packages/ranking/src/studio.ts b/packages/ranking/src/studio.ts
index bd7aa3f8..ef93f13f 100644
--- a/packages/ranking/src/studio.ts
+++ b/packages/ranking/src/studio.ts
@@ -2,7 +2,7 @@ import { rankingMarkupSurfaces, rankingModuleRef, rankingTypes } from "./index.j
import type { RankingProgram, RankingSchedule, RankingSoundEventPlan } from "./index.js";
import { compositionTypes } from "@hypit/hypit/composition";
import type { AudioTrack } from "@hypit/hypit/composition";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-companion";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioItemDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-companion";
import { artifactPreview, authoredChildFor, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalDomainSource } from "@hypit/studio-companion";
@@ -118,7 +118,7 @@ function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style"
};
}
-function projectRanking(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectRanking(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const placement = context.placement;
const schedule = requiredSurfaceValue(context, "schedule") as RankingSchedule;
const program = requiredSurfaceValue(context, "program") as RankingProgram;
@@ -126,8 +126,8 @@ function projectRanking(context: StudioTrackCompanionContext): readonly StudioEn
const boardId = placement.id ?? context.track.outputRef;
const outerTemporal = temporalLineageFor(context, boardId, "outer");
const outerSemanticSource = temporalDomainSource(outerTemporal);
- const group: StudioEntityDraft = {
- id: `${context.track.outputRef}:entity:${boardId}`,
+ const group: StudioItemDraft = {
+ id: `${context.track.outputRef}:item:${boardId}`,
authoredId: boardId,
...(outerSemanticSource?.id === undefined ? {} : { markerId: outerSemanticSource.id }),
display: { title: boardId, layers: [] },
@@ -136,11 +136,11 @@ function projectRanking(context: StudioTrackCompanionContext): readonly StudioEn
stackOrder: Math.max(...context.spans.map((span) => span.stackOrder), 0),
elementRange: placement.range,
renderIds: context.spans.map((span) => span.id),
- presentation: { entity: "ranking", chrome: "group" },
+ presentation: { kind: "ranking", chrome: "group" },
...(outerTemporal === undefined ? {} : { temporal: outerTemporal }),
};
const programItems = new Map(program?.items.map((item) => [item.id, item] as const) ?? []);
- const reveals = schedule.entries.flatMap((entry): readonly StudioEntityDraft[] => {
+ const reveals = schedule.entries.flatMap((entry): readonly StudioItemDraft[] => {
if ("mode" in entry && entry.mode !== "reveal") return [];
const child = authoredChildFor(context, entry.itemId, [rankingTypes.itemSpec, rankingTypes.textItemShell]);
const item = programItems.get(entry.itemId);
@@ -150,7 +150,7 @@ function projectRanking(context: StudioTrackCompanionContext): readonly StudioEn
const icon = item?.icon;
const label = item !== undefined && "label" in item ? item.label : child?.attributes.label ?? entry.itemId;
return [{
- id: `${context.track.outputRef}:entity:${entry.itemId}`,
+ id: `${context.track.outputRef}:item:${entry.itemId}`,
authoredId: entry.itemId,
renderIds: context.spans.filter((span) => span.subjectId === entry.itemId).map((span) => span.id),
...(semanticSource?.id === undefined ? {} : { markerId: semanticSource.id }),
@@ -163,11 +163,11 @@ function projectRanking(context: StudioTrackCompanionContext): readonly StudioEn
stackOrder: group.stackOrder + 1,
...(child === undefined ? {} : { elementRange: child.range }),
lane: "mode" in entry ? "reveal" : "activation",
- presentation: { entity: "ranking-reveal", chrome: "standard" },
+ presentation: { kind: "ranking-reveal", chrome: "standard" },
...(temporal === undefined ? {} : { temporal }),
}];
}).sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id));
- const childRenderIds = new Set(reveals.flatMap((entity) => entity.renderIds ?? []));
+ const childRenderIds = new Set(reveals.flatMap((item) => item.renderIds ?? []));
return [{ ...group, renderIds: group.renderIds!.filter((id) => !childRenderIds.has(id)) }, ...reveals];
}
@@ -175,12 +175,12 @@ const commonBindings: readonly StudioSourceBindingDeclaration[] = [
{ name: "frame", referenced: frameParameters },
];
-function projectRankingAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectRankingAudio(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const events = requiredSurfaceValue(context, "events") as RankingSoundEventPlan;
const byId = new Map(events.events.map((event) => [event.id, event]));
const clips = new Map((context.track.value as AudioTrack).clips.map((clip) => [clip.id, clip]));
const boardId = context.placement?.id ?? context.track.outputRef;
- return context.spans.map((span): StudioEntityDraft => {
+ return context.spans.map((span): StudioItemDraft => {
const event = byId.get(span.id);
const clip = clips.get(span.id);
if (event === undefined || clip === undefined) throw new Error(`Ranking sound ${span.id} has no event or audio clip.`);
@@ -188,12 +188,12 @@ function projectRankingAudio(context: StudioTrackCompanionContext): readonly Stu
const label = child?.attributes.label ?? event.itemId;
const phase = event.kind === "appear" ? "Appear" : "Move";
return {
- id: `${context.track.outputRef}:entity:${event.id}`,
+ id: `${context.track.outputRef}:item:${event.id}`,
authoredId: boardId,
display: { title: `${label} · ${phase}`, layers: [previewLayer(artifactPreview("audio", clip.artifact.resource), "waveform")] },
startFrame: span.startFrame, endFrameExclusive: span.endFrameExclusive, stackOrder: span.stackOrder,
...(context.placement === undefined ? {} : { elementRange: context.placement.range }),
- presentation: { entity: "ranking-sound", chrome: "standard" },
+ presentation: { kind: "ranking-sound", chrome: "standard" },
inspector: [{
id: "trigger", label: "Trigger", domain: "when", page: { id: "sound", label: "Sound" }, section: { id: "event", label: "Event" },
value: `${label} · ${phase} · ${event.frame}f`,
diff --git a/packages/ranking/test/companion.test.ts b/packages/ranking/test/companion.test.ts
index 2ea97891..8d31c2ed 100644
--- a/packages/ranking/test/companion.test.ts
+++ b/packages/ranking/test/companion.test.ts
@@ -31,12 +31,12 @@ test("audio uses exact event identities and emitted clips, with shared recipe ow
] }]]),
spans: [{ id: "opaque-event-id", startFrame: 90, endFrameExclusive: 99, stackOrder: 0 }],
} as unknown as StudioTrackCompanionContext;
- const entities = audio.project!(context);
- assert.equal(entities.length, 1);
- assert.equal(entities[0]!.display.title, "Player One · Move");
- assert.equal(entities[0]!.authoredId, "board");
- assert.deepEqual(entities[0]!.elementRange, context.placement!.range);
- assert.equal(entities[0]!.temporal, undefined);
- assert.equal(entities[0]!.inspector![0]!.value, "Player One · Move · 90f");
- assert.deepEqual([entities[0]!.startFrame, entities[0]!.endFrameExclusive], [90, 99]);
+ const items = audio.project!(context);
+ assert.equal(items.length, 1);
+ assert.equal(items[0]!.display.title, "Player One · Move");
+ assert.equal(items[0]!.authoredId, "board");
+ assert.deepEqual(items[0]!.elementRange, context.placement!.range);
+ assert.equal(items[0]!.temporal, undefined);
+ assert.equal(items[0]!.inspector![0]!.value, "Player One · Move · 90f");
+ assert.deepEqual([items[0]!.startFrame, items[0]!.endFrameExclusive], [90, 99]);
});
diff --git a/packages/script/src/studio.ts b/packages/script/src/studio.ts
index 3836d5c4..a196999e 100644
--- a/packages/script/src/studio.ts
+++ b/packages/script/src/studio.ts
@@ -34,65 +34,72 @@ function one<T>(values: readonly T[], subject: string): T | undefined {
return values[0];
}
-export function projectScriptTemporalDomain(input: StudioTemporalDomainProjectionInput): StudioTemporalDomainProjection | undefined {
+export function projectScriptTemporalDomain(input: StudioTemporalDomainProjectionInput): readonly StudioTemporalDomainProjection[] {
const narrative = one(input.values.filter((item) => sameType(item.type, narrativeTypes.narrative)
&& (item.value as NarrativeValue).id === input.source.domainId), `Studio Narrative id ${input.source.domainId}`)?.value as NarrativeValue | undefined;
- if (narrative === undefined) return undefined;
- const projection = one(input.values.filter((item) => sameType(item.type, narrativeTemporalTypes.narrativeProjection)
+ if (narrative === undefined) return [];
+ const projections = input.values.filter((item) => sameType(item.type, narrativeTemporalTypes.narrativeProjection)
&& (item.value as NarrativeProjection).narrativeId === input.source.domainId
- && (item.value as NarrativeProjection).timelineId === input.timeline.id), `Studio Narrative projection ${input.source.domainId}`)?.value as NarrativeProjection | undefined;
- if (projection === undefined) return undefined;
+ && (item.value as NarrativeProjection).timelineId === input.timeline.id)
+ .map((item) => item.value as NarrativeProjection);
const source = input.source.data as ScriptStudioObservation;
const segmentRanges = new Map(source.segments.map((item) => [item.id, item.range]));
const tokenRanges = new Map(source.tokens.map((item) => [item.id, item.range]));
const selectionRanges = new Map(source.selections.map((item) => [item.id, { start: item.open.start, end: item.close.end }]));
const momentRanges = new Map(source.moments.map((item) => [item.id, item.range]));
- const frame = new Map(projection.boundaries.map((boundary) => [boundary.id, boundary.frame]));
+ const narrativeSegments = new Map((narrative.segments ?? []).map((segment) => [segment.id, segment]));
+ const narrativeTokens = new Map((narrative.tokens ?? []).map((token) => [token.id, token]));
const tokenText = new Map((narrative.tokens ?? []).map((token) => [token.id, token.text]));
- const anchors = (narrative.anchors ?? []).flatMap((anchor) => {
- const at = frame.get(anchor.id);
- if (at === undefined) return [];
- const detail = [anchor.tokenId === undefined ? undefined : tokenText.get(anchor.tokenId), anchor.segmentId]
- .filter((part): part is string => part !== undefined).join(" · ");
- return [{ id: anchor.id, kind: anchor.kind, frame: at,
- ...(anchor.tokenId === undefined ? {} : { label: tokenText.get(anchor.tokenId) ?? anchor.tokenId }),
- ...(detail.length === 0 ? {} : { detail }) }];
+ return projections.map((projection) => {
+ const frame = new Map(projection.boundaries.map((boundary) => [boundary.id, boundary.frame]));
+ const anchors = (narrative.anchors ?? []).flatMap((anchor) => {
+ const at = frame.get(anchor.id);
+ if (at === undefined) return [];
+ const detail = [anchor.tokenId === undefined ? undefined : tokenText.get(anchor.tokenId), anchor.segmentId]
+ .filter((part): part is string => part !== undefined).join(" · ");
+ return [{ id: anchor.id, kind: anchor.kind, frame: at,
+ ...(anchor.tokenId === undefined ? {} : { label: tokenText.get(anchor.tokenId) ?? anchor.tokenId }),
+ ...(detail.length === 0 ? {} : { detail }) }];
+ });
+ const segments = projection.segments.flatMap((projected) => {
+ const segment = narrativeSegments.get(projected.segmentId);
+ if (segment === undefined) return [];
+ const startFrame = frame.get(segment.startAnchorId); const endFrame = frame.get(segment.endAnchorId);
+ if (startFrame === undefined || endFrame === undefined) return [];
+ return [{ kind: "span" as const, appearance: "block" as const, id: segment.id, laneId: "maps", label: segment.id,
+ source: { type: narrativeTypes.segmentRef, kind: "segment", id: segment.id }, startAnchorId: segment.startAnchorId,
+ endAnchorId: segment.endAnchorId, startFrame, endFrameExclusive: Math.max(startFrame + 1, endFrame),
+ ...(segmentRanges.has(segment.id) ? { range: segmentRanges.get(segment.id)! } : {}) }];
+ });
+ const tokens = projection.tokens.flatMap((projected) => {
+ const token = narrativeTokens.get(projected.tokenId);
+ if (token === undefined) return [];
+ const startFrame = frame.get(token.startAnchorId); const endFrame = frame.get(token.endAnchorId);
+ if (startFrame === undefined || endFrame === undefined) return [];
+ return [{ kind: "span" as const, appearance: "compact" as const, id: token.id, laneId: "evidence", label: token.text,
+ startAnchorId: token.startAnchorId, endAnchorId: token.endAnchorId, startFrame,
+ endFrameExclusive: Math.max(startFrame + 1, endFrame), followPlayhead: true,
+ ...(tokenRanges.has(token.id) ? { range: tokenRanges.get(token.id)! } : {}) }];
+ });
+ const selections = (narrative.selections ?? []).flatMap((selection) => {
+ const startFrame = frame.get(selection.startAnchorId); const endFrameExclusive = frame.get(selection.endAnchorId);
+ if (startFrame === undefined || endFrameExclusive === undefined || endFrameExclusive <= startFrame) return [];
+ return [{ kind: "span" as const, appearance: "block" as const, id: selection.id, laneId: "intent", label: selection.id,
+ source: { type: narrativeTypes.selection, kind: "selection", id: selection.id }, editable: true,
+ startAnchorId: selection.startAnchorId, endAnchorId: selection.endAnchorId, startFrame, endFrameExclusive,
+ ...(selectionRanges.has(selection.id) ? { range: selectionRanges.get(selection.id)! } : {}) }];
+ });
+ const moments = (narrative.moments ?? []).flatMap((moment) => {
+ const at = frame.get(moment.anchorId); if (at === undefined) return [];
+ return [{ kind: "point" as const, appearance: "marker" as const, id: moment.id, laneId: "intent", label: moment.id,
+ source: { type: narrativeTypes.moment, kind: "moment", id: moment.id }, editable: true,
+ anchorId: moment.anchorId, frame: at, ...(momentRanges.has(moment.id) ? { range: momentRanges.get(moment.id)! } : {}) }];
+ });
+ return { id: projection.id, timelineId: input.timeline.id,
+ lanes: [{ id: "maps", label: "Map", heightPx: 26 },
+ { id: "evidence", label: "Evidence", heightPx: 26 }],
+ anchors, items: [...segments, ...tokens], editItems: [...selections, ...moments] };
});
- const segments = (narrative.segments ?? []).flatMap((segment) => {
- const startFrame = frame.get(segment.startAnchorId); const endFrame = frame.get(segment.endAnchorId);
- if (startFrame === undefined || endFrame === undefined) return [];
- return [{ kind: "span" as const, appearance: "block" as const, id: segment.id, laneId: "segments", label: segment.id,
- source: { type: narrativeTypes.segmentRef, kind: "segment", id: segment.id }, startAnchorId: segment.startAnchorId,
- endAnchorId: segment.endAnchorId, startFrame, endFrameExclusive: Math.max(startFrame + 1, endFrame),
- ...(segmentRanges.has(segment.id) ? { range: segmentRanges.get(segment.id)! } : {}) }];
- });
- const tokens = (narrative.tokens ?? []).flatMap((token) => {
- const startFrame = frame.get(token.startAnchorId); const endFrame = frame.get(token.endAnchorId);
- if (startFrame === undefined || endFrame === undefined) return [];
- return [{ kind: "span" as const, appearance: "compact" as const, id: token.id, laneId: "tokens", label: token.text,
- startAnchorId: token.startAnchorId, endAnchorId: token.endAnchorId, startFrame,
- endFrameExclusive: Math.max(startFrame + 1, endFrame), followPlayhead: true,
- ...(tokenRanges.has(token.id) ? { range: tokenRanges.get(token.id)! } : {}) }];
- });
- const selections = (narrative.selections ?? []).flatMap((selection) => {
- const startFrame = frame.get(selection.startAnchorId); const endFrameExclusive = frame.get(selection.endAnchorId);
- if (startFrame === undefined || endFrameExclusive === undefined || endFrameExclusive <= startFrame) return [];
- return [{ kind: "span" as const, appearance: "block" as const, id: selection.id, laneId: "intent", label: selection.id,
- source: { type: narrativeTypes.selection, kind: "selection", id: selection.id }, editable: true,
- startAnchorId: selection.startAnchorId, endAnchorId: selection.endAnchorId, startFrame, endFrameExclusive,
- ...(selectionRanges.has(selection.id) ? { range: selectionRanges.get(selection.id)! } : {}) }];
- });
- const moments = (narrative.moments ?? []).flatMap((moment) => {
- const at = frame.get(moment.anchorId); if (at === undefined) return [];
- return [{ kind: "point" as const, appearance: "marker" as const, id: moment.id, laneId: "intent", label: moment.id,
- source: { type: narrativeTypes.moment, kind: "moment", id: moment.id }, editable: true,
- anchorId: moment.anchorId, frame: at, ...(momentRanges.has(moment.id) ? { range: momentRanges.get(moment.id)! } : {}) }];
- });
- return { id: input.source.domainId, timelineId: input.timeline.id,
- lanes: [{ id: "segments", label: "Segments", heightPx: 26 },
- ...(tokens.length === 0 ? [] : [{ id: "tokens", label: "Words", heightPx: 26 }]),
- ...(selections.length + moments.length === 0 ? [] : [{ id: "intent", label: "Intent", heightPx: 26 }])],
- anchors, items: [...segments, ...tokens, ...selections, ...moments] };
}
const scriptTemporalSourceTypes = [narrativeTypes.segmentRef, narrativeTypes.selection, narrativeTypes.moment] as const;
@@ -102,7 +109,7 @@ export const scriptStudioTemporalDomains: readonly StudioTemporalDomainCompanion
match: { module: scriptModuleRef, surface: "script" },
valueTypes: [narrativeTypes.narrative, narrativeTemporalTypes.narrativeProjection],
sourceTypes: scriptTemporalSourceTypes,
- presentation: { family: "narrative", tone: "teal", label: "Narrative", icon: "brand" },
+ presentation: { family: "narrative", tone: "teal", icon: "brand" },
identify({ type, value }) {
if (!scriptTemporalSourceTypes.some((candidate) => sameType(candidate, type))) return undefined;
const held = value as { readonly narrativeId?: unknown; readonly id?: unknown; readonly kind?: unknown };
diff --git a/packages/script/test/studio-companion.test.ts b/packages/script/test/studio-companion.test.ts
index 36339abe..1daafc91 100644
--- a/packages/script/test/studio-companion.test.ts
+++ b/packages/script/test/studio-companion.test.ts
@@ -32,14 +32,50 @@ test("Studio observes and edits the compiler's Script body without changing its
const values = decoded.records.flatMap(record => record.value.kind === "inline"
? [{ id: record.id, type: record.type, value: record.value.value }] : []);
values.push({ id: "story.projection", type: narrativeTemporalTypes.narrativeProjection, value: {
- id: "story.projection", narrativeId: "story", timelineId: "film", segments: [], tokens: [],
+ id: "story.projection", narrativeId: "story", timelineId: "film",
+ segments: parsed.segments.map((segment) => ({ segmentId: segment.id,
+ startBoundaryId: segment.startAnchorId, endBoundaryId: segment.endAnchorId })),
+ tokens: parsed.tokens.map((token) => ({ tokenId: token.id, segmentId: token.segmentId, text: token.text,
+ startBoundaryId: token.startAnchorId, endBoundaryId: token.endAnchorId })),
boundaries: parsed.anchors.map((anchor, index) => ({ id: anchor.id, frame: index * 3 })),
} });
- const projection = companion.project({ source: { ...observed, companion: companion.id }, values,
+ const [projection] = companion.project({ source: { ...observed, companion: companion.id }, values,
timeline: { id: "film", frameCount: 100, frameRate: { numerator: 30, denominator: 1 } },
});
assert.ok(projection);
+ assert.deepEqual(projection.lanes.map((lane) => lane.id), ["maps", "evidence"]);
+ assert.equal(projection.items.some((item) => item.laneId === "intent"), false);
+ assert.equal(projection.editItems.some((item) => item.id === "beat"), true);
const tokens = projection.items.filter((item) => item.kind === "span" && item.appearance === "compact");
assert.deepEqual(tokens.map(token => token.label), parsed.tokens.map(token => token.text));
assert.deepEqual(tokens.map(token => token.range), observation.tokens.map(token => token.range));
});
+
+test("Studio projects every exact Narrative Projection instead of choosing one per Script and Timeline", () => {
+ const body = '<line><host>one two</line>';
+ const prefix = '<script id="story">';
+ const source = `${prefix}${body}</script>`;
+ const companion = scriptStudioTemporalDomains[0]!;
+ const decoded = decodeScriptSurface({ sourceName: "studio.svml", source, tag: "script", attributes: { id: "story" },
+ openingStart: 0, contentStart: prefix.length });
+ const observed = companion.observe({ sourceName: "studio.svml", source, tag: "script", attributes: { id: "story" },
+ range: { start: 0, end: source.length }, contentStart: prefix.length, nextOffset: decoded.nextOffset })!;
+ const parsed = parseScript("body", body);
+ const values = decoded.records.flatMap(record => record.value.kind === "inline"
+ ? [{ id: record.id, type: record.type, value: record.value.value }] : []);
+ for (const [id, offset] of [["story.primary", 0], ["story.alternate", 40]] as const) {
+ values.push({ id, type: narrativeTemporalTypes.narrativeProjection, value: {
+ id, narrativeId: "story", timelineId: "film",
+ segments: parsed.segments.map((segment) => ({ segmentId: segment.id,
+ startBoundaryId: segment.startAnchorId, endBoundaryId: segment.endAnchorId })),
+ tokens: parsed.tokens.map((token) => ({ tokenId: token.id, segmentId: token.segmentId, text: token.text,
+ startBoundaryId: token.startAnchorId, endBoundaryId: token.endAnchorId })),
+ boundaries: parsed.anchors.map((anchor, index) => ({ id: anchor.id, frame: offset + index * 3 })),
+ } });
+ }
+ const projected = companion.project({ source: { ...observed, companion: companion.id }, values,
+ timeline: { id: "film", frameCount: 100, frameRate: { numerator: 30, denominator: 1 } } });
+ assert.deepEqual(projected.map((item) => item.id), ["story.primary", "story.alternate"]);
+ assert.deepEqual(projected.map((item) => item.lanes.map((lane) => lane.id)),
+ [["maps", "evidence"], ["maps", "evidence"]]);
+});
diff --git a/packages/studio-companion/README.md b/packages/studio-companion/README.md
index 5178088e..1e91b178 100644
--- a/packages/studio-companion/README.md
+++ b/packages/studio-companion/README.md
@@ -12,7 +12,7 @@ component.
## A minimal project Track Companion
Suppose `@studio/score-strip@1` already owns a `track` Surface that emits a public VisualTrack and
-accepts a literal string `label` attribute. The Companion can reuse generic terminal entities while
+accepts a literal string `label` attribute. The Companion can reuse generic terminal Items while
adding package-specific presentation and one Inspector field:
```ts
@@ -46,24 +46,24 @@ export const companions: readonly StudioTrackCompanion[] = [{
The names and lane height are this example's choices. Use the real Module ABI, Surface name,
nominal output Type and authored input names of the component. A Companion does not create a new
-author attribute. Omitting `project` uses generic terminal entities; `poster` adds the declared
+author attribute. Omitting `project` uses generic terminal Items; `poster` adds the declared
Surface preview when one exists, without changing the component's rendered video.
-Each lane occupies one timeline row. Entities overlap in ascending `stackOrder`,
-with later projected entities above earlier ones when orders tie. Studio keeps
-overlapping entities mounted and raises the selected entity within its lane;
+Each lane occupies one timeline row. Items overlap in ascending `stackOrder`,
+with later projected Items above earlier ones when orders tie. Studio keeps
+overlapping Items mounted and raises the selected Item within its lane;
selection does not change the rendered composition or write stacking back to Source.
-Expose `presentId` or `renderIds` for visual entities so picture selection can
-address the same entity shown in the timeline. Attached lanes represent distinct
+Expose `presentId` or `renderIds` for visual Items so picture selection can
+address the same Item shown in the timeline. Attached lanes represent distinct
Companion projections, not extra rows allocated to avoid temporal overlap.
-An entity's timeline interval describes the operation being edited; its rendered
+An Item's timeline interval describes the operation being edited; its rendered
parts may remain visible afterward. Associate every relevant phase through
`renderIds` (for example, an entrance and the settled object). Studio picks the
-currently visible part in rendered stacking order and selects the same entity,
+currently visible part in rendered stacking order and selects the same Item,
without extending its editable interval. Give the parent the board or background
parts and its children their own parts when they should be independently selectable.
-The component decides this granularity. A composite can remain one selectable entity.
+The component decides this granularity. A composite can remain one selectable Item.
Merge the facet into the package's existing activation. In this example `authorContribution`
exports its existing modules, deterministic component and Markup facets:
@@ -93,7 +93,7 @@ explicit official Companion selection. It qualifies this local id as
`@studio/score-strip#score-strip`. There is no extra Studio Profile, plugin scan or Core registration.
Restart the Studio process after changing activation or package code.
-## Project domain entities and material
+## Project domain Items and material
A terminal VisualTrack is enough for generic display. When it loses meaningful domain structure,
publish a deterministic schedule/program output from the same Surface and name its port in
@@ -102,20 +102,20 @@ The port must exist in the Surface's public output mappings; inventing a port na
does not make an internal Producer value observable. `requiredReferencedValue(context, input, type)`
instead follows one exact typed author reference, such as a CaptionDocument.
-`project` returns `StudioEntityDraft[]`. Each entity has an id, authored identity, display title and
+`project` returns `StudioItemDraft[]`. Each Item has an id, authored identity, display title and
ordered layers, `startFrame`, `endFrameExclusive` and `stackOrder`. Useful optional fields include:
| Field/helper | Purpose |
| --- | --- |
-| `selectionGroup` | Link disjoint displayed intervals of one author entity; selection highlights them together without changing their independent timing |
-| `presentation` | Name the entity's role and choose `standard`, `group`, `point` or `compact` chrome (a single-line primary label) |
+| `selectionGroup` | Link disjoint displayed intervals of one author Item; selection highlights them together without changing their independent timing |
+| `presentation` | Name the Item kind and choose `standard`, `group`, `point` or `compact` chrome (a single-line primary label) |
| `textLayer(text)` | Put explicit domain text in the timeline body |
| `previewLayer(artifactPreview(kind, resource), layout)` | Show a declared image/video/audio Resource with a finite layout; Studio resolves transport |
-| `renderIds` | Relate an entity to its actual rendered elements |
-| `parameterReferences` | Select exact per-entity authored references, such as the Style really used by this Cue |
+| `renderIds` | Relate an Item to its actual rendered elements |
+| `parameterReferences` | Select exact per-Item authored references, such as the Style really used by this Cue |
| `temporal` | Carry the executed Instant/Window lineage and its edit authority |
-| `lane` and Companion `attachments` | Put child entities on a declared additional lane, with its own bindings and Inspector |
-| `childEntities` / `authoredChildFor` | Resolve children from public identity and exact Spec Types rather than source order guesses |
+| `lane` and Companion `attachments` | Put child Items on a declared additional lane, with its own bindings and Inspector |
+| `childItems` / `authoredChildFor` | Resolve children from public identity and exact Spec Types rather than source order guesses |
| `authoredItemTitle` | Prefer an explicit author id, then a source reference from the attributes chosen by the Companion; presentation leaves editing identity unchanged |
Use the program's frame space and half-open intervals. Persistent visibility and its activation are
@@ -132,7 +132,7 @@ Caption Fine's `@hypit/caption-fine/studio` facet for Cue text and Style selecti
`StudioTrackCompanionContext.temporalBindings` exposes the executed Instant/Window records in the selected
Track closure, including projection expressions, source identity and direct consumer inputs.
-`temporalLineageFor()` joins a domain entity to those edges through the identity of a value consumed
+`temporalLineageFor()` joins a domain Item to those edges through the identity of a value consumed
beside the projection. No match is read-only, one match is used, and several matches are an error rather
than a first-result guess. Endpoint authority is already part of that executed lineage: an author syntax
may declare a parameter inverse on the Spec it creates, while a domain projector declares its own source
@@ -147,7 +147,7 @@ allowed to interpret a value.
Trace references retain the exact author input name and resolved TypeRef. A Companion that needs a
CaptionDocument or another referenced domain value selects that declared edge; it never scans all
-values for a familiar object shape. Child entities follow the same rule: when an optional Source id
+values for a familiar object shape. Child Items follow the same rule: when an optional Source id
was omitted, a Companion may name the exact domain Spec Type whose public `id` owns that child.
Studio then recovers the Source range from the typed observed Record, without ordinal matching.
@@ -157,17 +157,71 @@ physical package identity, so executable package code cannot impersonate an
official Companion. The Source closure selects project packages; Studio does not
scan `node_modules` for plugins or use Runtime Profiles to select Companions.
-The same Studio Companion facet can contribute Film, temporal-domain and parameter Companions. A Film Companion
+The same Studio Companion facet can contribute Film, temporal-domain, temporal-declaration and parameter Companions. A Film Companion
identifies its Timeline and terminal Tracks. The Timeline supplies only the program range. A
-temporal-domain Companion owns source observation, requests the domain values it needs, projects
-generic anchors plus point/span items onto that Timeline, and receives inverse point/span edits.
+temporal-domain Companion owns source observation, requests the domain values it needs, and returns
+one view for every exact Projection instance. Each view projects package-owned lanes, anchors and
+visible point/span Items onto the absolute Timeline. Domain objects needed only to invert a Track/Item
+edit belong in `editItems`; Studio does not draw them as another lane.
Script Studio uses this protocol for Narrative, but common Studio neither imports Narrative nor
reserves segment, word, Selection or Moment slots. Another package can contribute beat, shot or
motion-event domains through the same protocol.
+A temporal-declaration Companion instead matches one author Surface and names only the output ports
+whose primary values are author-visible absolute Windows or Instants. It does not choose their color,
+row or editing behavior. Studio resolves those exact outputs and puts every package's declarations in
+one read-only `Windows & Instants` row. This keeps Surface port knowledge in the owning package while
+letting common Studio understand only the shared absolute temporal types. Do not export a Timeline's
+root range, automatically derived Window boundaries or internal helper values as separate declarations.
+
+```ts
+createStudioCompanionFacet({
+ temporalDeclarations: [{
+ id: "window",
+ match: { module: myModule, surface: "window" },
+ project: ({ placement }) => placement.id === undefined ? [] : [{
+ id: placement.id,
+ output: placement.outputPorts.find((port) => port.name === "window")!.ref,
+ range: placement.range,
+ }],
+ }],
+})
+```
+
+A temporal-relation Companion owns the inverse meaning of one package-private Producer output. It
+receives only the executed input/output values and one desired Point, Extent or Span constraint. It
+may return input constraints and exact author-Spec replacements. Common Studio recursively composes
+those local plans, removes conflicting branches, merges candidates that reach the same exact author
+writes, and commits the sole remaining plan in one transaction. Distinct surviving plans are a real
+ambiguity. The package never receives mutable Studio state or file access through this API.
+
+The same relation may expose `trace` to reconstruct the meaning of its output from exact input
+records. Trace is how a private materialization, offset or domain projection preserves lineage and
+edit authority without making Studio recognize the package's Producer names or input vocabulary.
+
+This is how an author package keeps private construction values private. For example,
+`@hypit/timeline-author` explains how its materialized Window leads to a construction Span, and how
+that Span leads to its Point and Extent inputs. Studio does not import or enumerate those Producer
+names. A relation with no unique inverse returns no plan; a relation with several genuine author
+choices returns several plans. Studio evaluates them through the remaining graph and rejects the
+gesture only if they still produce different valid author decisions.
+
+```ts
+createStudioCompanionFacet({
+ temporalRelations: [{
+ id: "span-between",
+ match: { producer: mySpanProducer, output: "span" },
+ invert: ({ target }) => target.kind !== "span" ? [] : [{ constraints: [
+ { input: "start", target: { kind: "instant", frame: target.startFrame } },
+ { input: "end", target: { kind: "instant", frame: target.endFrameExclusive } },
+ ] }],
+ }],
+})
+```
+
For a domain item whose Spec is consumed beside a Window or Instant, call
`temporalLineageFor(context, item.id, "window")` using the actual projection input name. Attach the
-returned lineage to that entity; the input may instead be `activation`, `outer` or another declared
+returned lineage to that Item; the input may instead be `activation`, `outer` or another declared
port. Studio derives common timeline gestures from endpoint authority. No matching lineage means
no inferred domain edit; several matching edges require resolving the ambiguity in the component
projection. Visible frame coincidence is not a source relationship.
@@ -188,7 +242,7 @@ Inspector editing deliberately has two declarations:
This keeps source traversal, timeline inverses and editor presentation from
silently becoming one policy. Studio resolves the declarations against the
current Source closure. Visible read-only bindings render as text alongside editable fields.
-A projected entity can also supply `inspector` values with an `id`, `label`, `domain`, `section`
+A projected Item can also supply `inspector` values with an `id`, `label`, `domain`, `section`
and `value`, such as its resolved interval. These facts need no Source endpoint.
Only resolved fields with an `edit` endpoint accept `parameter.adjust`. Studio renders all DOM
and CSS itself; grouping does not grant edit authority.
@@ -207,60 +261,56 @@ new domain property fails Companion loading instead of inheriting UI from its na
`referenced` follows declared authored-element references; `recipe` names an explicit path through
authored references to one SVS Recipe and its admitted properties. These paths are independent of
the `inspector` field table. Keep shared values shared: editing a Recipe affects its consumers, while
-an entity-specific `parameterReferences` override must identify the actual authored value it uses.
+an Item-specific `parameterReferences` override must identify the actual authored value it uses.
-Verify the integration in an ordinary Run: the intended Module/Surface matches, the expected entity
+Verify the integration in an ordinary Run: the intended Module/Surface matches, the expected Item
is selected, its field reaches the correct Source or Recipe, and changing it recomputes the preview.
For domain handles, verify the exact point/span identity and its other consumers too. Read-only derived timing
is preferable to an invented inverse. The Companion explains the component; its Producers remain
responsible for identical video behavior in Studio, seeking and encoded rendering.
Compact chrome uses `display.title` as its complete single-line content: a Cue can put its subtitle
-text there and a Use can put its Style name there. It has no separate thumbnail/body region or
+text there. It has no separate thumbnail/body region or
inline duration. Time remains in the tooltip and Companion-selected Inspector facts. Tone and lane
height are independent declarations; compact does not recognize Caption or Use names.
Choose lane tones explicitly. The `blue-muted`, `green-muted`, `magenta-muted`
and `orange-muted` palette entries provide quieter rows within the same color
-family. For example, content and its presentation Uses can share a hue while
-the Uses take the muted tone. Studio does not derive tone from attachment depth
-or the entity name.
+family. Studio does not derive tone from attachment depth or the Item kind.
-### Internal bands and child Tracks
+### Inspector objects and child Tracks
-A Track can place independently timed entities in internal `bands`. These strips share its label
-and meet without gaps. Use them for aspects of the same content, such as a bottom strip of
-presentation rules. Keep `attachments` for independently represented child objects with their own
-labels, such as a ranking board's reveals. These declarations affect Studio presentation only.
+A Track can project authored rules or other non-occurrence objects through `inspectorObjects`.
+They stay out of the Timeline and appear in that Track's Inspector. Keep `attachments` for
+independently represented child content with its own time identity and label, such as a ranking
+board's reveals. Neither form changes the compiled video model.
```ts
{
lane: { heightPx: 60 },
- bands: [{
+ inspectorObjects: [{
id: "rules",
- placement: "after",
- heightPx: 15,
- display: "label",
+ label: "Presentation Rules",
bindings: [{ name: "style" }],
inspector: [{
binding: "style", label: "Style", domain: "how", control: "text",
section: { id: "presentation", label: "Presentation" },
}],
+ project: (context) => context.placement?.children.flatMap((child) => child.id === undefined ? [] : [{
+ id: `rule:${child.id}`,
+ authoredId: child.id,
+ title: child.id,
+ elementRange: child.range,
+ }]) ?? [],
}],
}
```
-The projection puts `band: "rules"` on the corresponding entity drafts. Other entities remain in
-the main content area. A band can be `before` or `after` that area; declarations retain their order
-within each placement. `display: "label"` fills the strip with entity titles, while `"content"`
-retains the entity's normal chrome and body. An optional `tone` selects another palette entry;
-omission inherits the Track tone. Heights are independent, so a label band can match the 15px
-standard item header.
-
-An entity selects either an internal `band` or a child `lane`. Bands retain their own intervals,
-overlap ordering, selection, Inspector declarations and temporal writeback. A rule spanning three
-content blocks stays one entity; Studio does not split it at content boundaries. Band entities stay
-in the Track's `clips` collection, so ordinary selection and editing use the same identities.
+The projected object has its own source identity and fields but no timeline rectangle. Studio shows
+these objects when an Item on the owning Track is selected. Their fields use the same binding and
+parameter-Companion machinery as Item fields. An independently timed child still uses a declared
+`attachment` and selects that attachment's `lane` in its Item draft; attachments remain ordinary
+Tracks with their own Items, selection and temporal writeback.
### Parameters owned by referenced objects
diff --git a/packages/studio-companion/src/index.ts b/packages/studio-companion/src/index.ts
index 468acbad..89baff82 100644
--- a/packages/studio-companion/src/index.ts
+++ b/packages/studio-companion/src/index.ts
@@ -1,6 +1,6 @@
import type { Facet } from "@hypit/hypit/facet";
import { sameType } from "@hypit/hypit/protocol";
-import type { CanonicalValue, ModuleRef, TypeRef, ValueSchema } from "@hypit/hypit/protocol";
+import type { CanonicalValue, ModuleRef, ProducerRef, TypeRef, ValueSchema } from "@hypit/hypit/protocol";
export const studioCompanionFacetAbi = "hypit.studio-companion@1";
@@ -33,7 +33,8 @@ export type StudioTimelineTone =
| "neutral";
export type StudioTimelinePresentation = {
- readonly entity: string;
+ /** Package-owned item kind used only for presentation and diagnostics. */
+ readonly kind: string;
/** Studio-owned shell. Compact presents the primary label in one line, with time in details. */
readonly chrome: "standard" | "group" | "point" | "compact";
};
@@ -57,6 +58,8 @@ export type StudioTemporalAuthority =
| {
readonly kind: "parameter";
readonly binding: string;
+ /** Exact executed Spec that owns this author parameter. */
+ readonly owner?: string;
readonly relation: "direct" | "after-start" | "before-end";
}
| { readonly kind: "fixed" };
@@ -82,6 +85,8 @@ export type StudioTemporalWindowProjection = {
export type StudioTemporalProjection = StudioTemporalInstantProjection | StudioTemporalWindowProjection;
export type StudioTemporalLineage = {
+ /** Exact executed Temporal value. Studio keeps this identity for inverse traversal. */
+ readonly record: string;
readonly projection: StudioTemporalProjection;
};
@@ -143,7 +148,7 @@ export type StudioAttributeGroupEdit = {
/** A real author endpoint. Its existence never implies Inspector visibility. */
export type StudioSourceBinding = {
readonly id: string;
- /** Companion-owned path, stable across source files and projected entities. */
+ /** Companion-owned path, stable across source files and projected Items. */
readonly binding: string;
/** Author vocabulary name at the terminal source element. */
readonly name: string;
@@ -197,7 +202,7 @@ export type StudioInspectorFieldDeclaration = {
readonly swatches?: readonly string[];
};
-/** A selected entity's package-owned fact, with no author write endpoint. */
+/** A selected Item's package-owned fact, with no author write endpoint. */
export type StudioInspectorValue = Pick<StudioInspectorFieldDeclaration,
"label" | "domain" | "page" | "section" | "summary" | "unit"> & {
readonly id: string;
@@ -301,7 +306,7 @@ export type StudioEditHandle = {
readonly enabled: boolean;
/** Coordinate space in which the central gesture resolver measures intent. */
readonly coordinate?: StudioEditCoordinate;
- /** How moving a domain Point changes the visible entity before recompilation. */
+ /** How moving a domain Point changes the visible Item before recompilation. */
readonly moveEffect?: "translate-window" | "move-start";
/** Snap policy is data, not a timeline-wide guess. */
readonly snapTo?: readonly StudioSnapTarget[];
@@ -310,6 +315,8 @@ export type StudioEditHandle = {
readonly domain?: StudioTemporalDomainEditTarget;
/** Exact endpoint authority used to validate and execute this inverse. */
readonly temporal?: StudioTemporalProjection;
+ /** Exact executed Temporal value traversed by the server-side inverse planner. */
+ readonly temporalRecord?: string;
readonly disabledReason?: string;
};
@@ -342,7 +349,7 @@ export type StudioDisplayLayer =
readonly layout: "repeat-x" | "cover" | "contain" | "storyboard" | "waveform";
};
-export type StudioEntityDisplay = {
+export type StudioItemDisplay = {
/** Primary label: a header in standard chrome, the complete single-line content in compact chrome. */
readonly title: string;
/** Ordered back-to-front body layers. */
@@ -350,7 +357,7 @@ export type StudioEntityDisplay = {
};
export type StudioLaneDescription = {
- /** Height of this single timeline lane; overlapping entities share it. */
+ /** Height of this single timeline lane; overlapping Items share it. */
readonly heightPx: number;
readonly groupId?: string;
readonly attachedTo?: string;
@@ -408,7 +415,7 @@ export type StudioTemporalDomainItem = {
});
export type StudioTemporalDomainView = {
- /** Domain identity supplied by its package, such as one Narrative id. */
+ /** Exact projected-view identity supplied by its package, such as one Projection id. */
readonly id: string;
/** Qualified Companion identity; together with id this is globally unambiguous. */
readonly companion: string;
@@ -421,7 +428,10 @@ export type StudioTemporalDomainView = {
};
readonly lanes: readonly StudioTemporalDomainLane[];
readonly anchors: readonly StudioTemporalDomainAnchor[];
+ /** Items visible on the shared Timeline. */
readonly items: readonly StudioTemporalDomainItem[];
+ /** Domain-owned inverse targets retained for Track/Item editing but not drawn as Timeline rows. */
+ readonly editItems: readonly StudioTemporalDomainItem[];
readonly provenance: StudioCandidateProvenance;
/** Exact package-owned author source used only for inverse dispatch. */
readonly source: {
@@ -531,10 +541,10 @@ export type StudioSpan = {
readonly stackOrder: number;
};
-export type StudioEntityDraft = {
+export type StudioItemDraft = {
readonly id: string;
readonly authoredId: string;
- readonly display: StudioEntityDisplay;
+ readonly display: StudioItemDisplay;
readonly startFrame: number;
readonly endFrameExclusive: number;
/** Back-to-front timeline order. Ties preserve projection order. Selection raises only the timeline item. */
@@ -542,11 +552,11 @@ export type StudioEntityDraft = {
readonly elementRange?: Range;
readonly markerId?: string;
readonly presentId?: string;
- /** Rendered parts belonging to this entity. */
+ /** Rendered parts belonging to this Item. */
readonly renderIds?: readonly string[];
- /** Resolved author references that differ per derived entity, such as one Cue's actual Style. */
+ /** Resolved author references that differ per derived Item, such as one Cue's actual Style. */
readonly parameterReferences?: Readonly<Record<string, string>>;
- /** Disjoint displayed intervals belonging to one selectable author entity. */
+ /** Disjoint displayed intervals belonging to one selectable author Item. */
readonly selectionGroup?: string;
/** Deliberately selected facts, presented beside bound Inspector fields. */
readonly inspector?: readonly StudioInspectorValue[];
@@ -554,8 +564,16 @@ export type StudioEntityDraft = {
readonly temporal?: StudioTemporalLineage;
/** Independent child Track partition; omitted means this Track. */
readonly lane?: string;
- /** Internal band of this Track; mutually exclusive with lane. */
- readonly band?: string;
+};
+
+/** One non-timeline author object owned by a Track and presented in Inspector. */
+export type StudioInspectorObjectDraft = {
+ readonly id: string;
+ readonly authoredId: string;
+ readonly title: string;
+ readonly elementRange?: Range;
+ readonly parameterReferences?: Readonly<Record<string, string>>;
+ readonly inspector?: readonly StudioInspectorValue[];
};
export type StudioTrackCompanionContext = {
@@ -568,7 +586,16 @@ export type StudioTrackCompanionContext = {
/** Temporal values in this Track's actual executed dependency closure. */
readonly temporalBindings: readonly StudioTemporalBinding[];
readonly temporalDomains: readonly StudioTemporalDomainView[];
- readonly generic: () => readonly StudioEntityDraft[];
+ readonly generic: () => readonly StudioItemDraft[];
+};
+
+/** Package-owned projection of Track rules or other author objects that are not timeline occurrences. */
+export type StudioInspectorObjectCompanion = {
+ readonly id: string;
+ readonly label: string;
+ readonly bindings?: readonly StudioSourceBindingDeclaration[];
+ readonly inspector?: readonly StudioInspectorFieldDeclaration[];
+ readonly project: (context: StudioTrackCompanionContext) => readonly StudioInspectorObjectDraft[];
};
export type StudioTrackCompanion = {
@@ -585,11 +612,11 @@ export type StudioTrackCompanion = {
readonly tone?: StudioTimelineTone;
readonly label?: string;
readonly icon?: StudioIcon;
- /** Opts root timeline entities into the component's package-owned Surface preview. */
+ /** Opts root timeline Items into the component's package-owned Surface preview. */
readonly poster?: { readonly source: "surface-preview" };
readonly attachments?: readonly StudioLaneAttachment[];
- /** Internal bands share this Track’s label and contain independently timed entities. */
- readonly bands?: readonly StudioTrackBand[];
+ /** Non-timeline author objects shown only in this Track's Inspector. */
+ readonly inspectorObjects?: readonly StudioInspectorObjectCompanion[];
/** Same-Surface output values required to project this Track for Studio. */
readonly requiredValues?: readonly string[];
readonly lane?: StudioLaneDescription;
@@ -597,7 +624,7 @@ export type StudioTrackCompanion = {
readonly bindings?: readonly StudioSourceBindingDeclaration[];
/** Visible field table. Undeclared bindings remain invisible. */
readonly inspector?: readonly StudioInspectorFieldDeclaration[];
- readonly project?: (context: StudioTrackCompanionContext) => readonly StudioEntityDraft[];
+ readonly project?: (context: StudioTrackCompanionContext) => readonly StudioItemDraft[];
};
/** Parameters owned by an authored object, independently of its consumers. */
@@ -613,6 +640,8 @@ export type StudioCompanionContribution = {
readonly tracks: readonly StudioTrackCompanion[];
readonly films?: readonly StudioFilmCompanion[];
readonly temporalDomains?: readonly StudioTemporalDomainCompanion[];
+ readonly temporalDeclarations?: readonly StudioTemporalDeclarationCompanion[];
+ readonly temporalRelations?: readonly StudioTemporalRelationCompanion[];
readonly parameters?: readonly StudioParameterCompanion[];
};
@@ -646,7 +675,8 @@ export type StudioTemporalDomainAdjustment =
| { readonly kind: "span"; readonly itemId: string; readonly startAnchorId: string; readonly endAnchorId: string }
| { readonly kind: "point"; readonly itemId: string; readonly anchorId: string };
-export type StudioTemporalDomainProjection = Pick<StudioTemporalDomainView, "id" | "timelineId" | "lanes" | "anchors" | "items">;
+export type StudioTemporalDomainProjection = Pick<StudioTemporalDomainView,
+ "id" | "timelineId" | "lanes" | "anchors" | "items" | "editItems">;
export type StudioTemporalDomainProjectionInput = {
readonly source: StudioTemporalDomainSourceMap;
readonly values: readonly StudioObservedValue[];
@@ -689,7 +719,7 @@ export type StudioTemporalDomainCompanion = {
readonly nextOffset?: number;
readonly attributes: Readonly<Record<string, unknown>>;
}) => Omit<StudioTemporalDomainSourceMap, "companion"> | undefined;
- readonly project: (input: StudioTemporalDomainProjectionInput) => StudioTemporalDomainProjection | undefined;
+ readonly project: (input: StudioTemporalDomainProjectionInput) => readonly StudioTemporalDomainProjection[];
readonly adjust: (input: {
readonly sourceName: string;
readonly source: string;
@@ -697,6 +727,76 @@ export type StudioTemporalDomainCompanion = {
}) => string;
};
+/** One package-owned author declaration whose primary result is an absolute Window or Instant. */
+export type StudioTemporalDeclarationDraft = {
+ readonly id: string;
+ readonly label?: string;
+ /** Exact qualified output record selected by the owning Surface Companion. */
+ readonly output: string;
+ readonly range?: Range;
+};
+
+/** Declares author-visible temporal outputs without choosing their common Studio presentation. */
+export type StudioTemporalDeclarationCompanion = {
+ readonly id: string;
+ readonly match: { readonly module: ModuleRef; readonly surface: string };
+ readonly project: (input: { readonly placement: StudioPlacement }) => readonly StudioTemporalDeclarationDraft[];
+};
+
+/** A desired value propagated while Studio reverses one executed temporal author graph. */
+export type StudioTemporalConstraint =
+ | { readonly kind: "instant"; readonly frame: number }
+ | { readonly kind: "extent"; readonly frameCount: number }
+ | { readonly kind: "span"; readonly startFrame: number; readonly endFrameExclusive: number };
+
+export type StudioTemporalRelationValue = {
+ readonly record: string;
+ readonly type: TypeRef;
+ readonly value: unknown;
+};
+
+export type StudioTemporalRelationInversePlan = {
+ readonly constraints?: readonly { readonly input: string; readonly target: StudioTemporalConstraint }[];
+ readonly writes?: readonly {
+ readonly input: string;
+ readonly binding: string;
+ readonly replacement: string;
+ }[];
+};
+
+export type StudioTemporalExtentTrace = {
+ readonly kind: "extent";
+ readonly frameCount: number;
+ readonly authority?: Extract<StudioTemporalAuthority, { readonly kind: "parameter" }>;
+};
+
+export type StudioTemporalRelationTrace = StudioTemporalProjection | StudioTemporalExtentTrace;
+
+/** Package-owned inverse semantics for one Producer relation. */
+export type StudioTemporalRelationCompanion = {
+ readonly id: string;
+ readonly match: { readonly producer: ProducerRef; readonly output: string };
+ readonly invert: (input: {
+ readonly target: StudioTemporalConstraint;
+ readonly output: StudioTemporalRelationValue;
+ readonly inputs: Readonly<Record<string, StudioTemporalRelationValue>>;
+ /** Constraint already imposed on a shared input by another output path. */
+ readonly desired: (input: string) => StudioTemporalConstraint | undefined;
+ }) => readonly StudioTemporalRelationInversePlan[];
+ /** Reconstruct package-owned lineage without exposing its private Producer vocabulary to Studio. */
+ readonly trace?: (input: {
+ readonly output: StudioTemporalRelationValue;
+ readonly inputs: Readonly<Record<string, StudioTemporalRelationValue>>;
+ readonly trace: (input: string) => StudioTemporalRelationTrace | undefined;
+ readonly identify: (input: string) => {
+ readonly companion: string;
+ readonly domainId: string;
+ readonly kind: string;
+ readonly itemId: string;
+ } | undefined;
+ }) => StudioTemporalRelationTrace | undefined;
+};
+
export type StudioCompanionFacet = Facet & {
readonly abi: typeof studioCompanionFacetAbi;
readonly implementation: StudioCompanionContribution;
@@ -713,6 +813,8 @@ export function createStudioCompanionFacet(input: {
readonly tracks?: readonly StudioTrackCompanion[];
readonly films?: readonly StudioFilmCompanion[];
readonly temporalDomains?: readonly StudioTemporalDomainCompanion[];
+ readonly temporalDeclarations?: readonly StudioTemporalDeclarationCompanion[];
+ readonly temporalRelations?: readonly StudioTemporalRelationCompanion[];
readonly parameters?: readonly StudioParameterCompanion[];
}): StudioCompanionFacet {
return {
@@ -722,6 +824,8 @@ export function createStudioCompanionFacet(input: {
tracks: input.tracks ?? [],
...(input.films === undefined ? {} : { films: input.films }),
...(input.temporalDomains === undefined ? {} : { temporalDomains: input.temporalDomains }),
+ ...(input.temporalDeclarations === undefined ? {} : { temporalDeclarations: input.temporalDeclarations }),
+ ...(input.temporalRelations === undefined ? {} : { temporalRelations: input.temporalRelations }),
...(input.parameters === undefined ? {} : { parameters: input.parameters }),
},
};
@@ -731,6 +835,8 @@ export type StudioPackageContribution = {
readonly tracks: readonly StudioTrackCompanion[];
readonly films: readonly StudioFilmCompanion[];
readonly temporalDomains: readonly StudioTemporalDomainCompanion[];
+ readonly temporalDeclarations: readonly StudioTemporalDeclarationCompanion[];
+ readonly temporalRelations: readonly StudioTemporalRelationCompanion[];
readonly parameters: readonly StudioParameterCompanion[];
};
@@ -749,6 +855,8 @@ export function studioContributionFromPackage(
const tracks: StudioTrackCompanion[] = [];
const films: StudioFilmCompanion[] = [];
const temporalDomains: StudioTemporalDomainCompanion[] = [];
+ const temporalDeclarations: StudioTemporalDeclarationCompanion[] = [];
+ const temporalRelations: StudioTemporalRelationCompanion[] = [];
const parameters: StudioParameterCompanion[] = [];
for (const facet of facets) {
if (facet.abi !== studioCompanionFacetAbi) continue;
@@ -771,8 +879,16 @@ export function studioContributionFromPackage(
...domain,
id: qualify(owner, domain.id, "Studio Temporal Domain companion"),
})));
+ temporalDeclarations.push(...(contribution.temporalDeclarations ?? []).map((declaration) => ({
+ ...declaration,
+ id: qualify(owner, declaration.id, "Studio Temporal Declaration companion"),
+ })));
+ temporalRelations.push(...(contribution.temporalRelations ?? []).map((relation) => ({
+ ...relation,
+ id: qualify(owner, relation.id, "Studio Temporal Relation companion"),
+ })));
}
- return { tracks, films, temporalDomains, parameters };
+ return { tracks, films, temporalDomains, temporalDeclarations, temporalRelations, parameters };
}
/**
@@ -786,18 +902,6 @@ export function studioTrackCompanionsFromPackage(
return studioContributionFromPackage(owner, facets).tracks;
}
-/** A contiguous internal strip, not a child Track. Declaration order is visual order. */
-export type StudioTrackBand = {
- readonly id: string;
- readonly placement: "before" | "after";
- readonly heightPx: number;
- /** Label bands use the whole strip for each entity's title; content bands retain its chrome. */
- readonly display: "label" | "content";
- readonly tone?: StudioTimelineTone;
- readonly bindings?: readonly StudioSourceBindingDeclaration[];
- readonly inspector?: readonly StudioInspectorFieldDeclaration[];
-};
-
export type StudioLaneAttachment = {
readonly id: string;
readonly family: StudioTrackFamily;
@@ -860,7 +964,7 @@ export function textLayer(text: string): StudioDisplayLayer {
return { kind: "text", role: "content", text };
}
-/** Find the executed projection that explicitly names this domain entity as its subject. */
+/** Find the executed projection that explicitly names this domain Item as its subject. */
export function temporalBindingsFor(
context: StudioTrackCompanionContext,
subjectId: string,
@@ -902,7 +1006,7 @@ export function temporalLineageFor(
throw new Error(`Studio Temporal lineage is ambiguous for ${subjectId}${input === undefined ? "" : ` at ${input}`}.`);
}
const binding = found[0];
- return binding === undefined ? undefined : { projection: binding.projection };
+ return binding === undefined ? undefined : { record: binding.record, projection: binding.projection };
}
/** Unique domain-owned author identity carried by one projection, when there is one. */
@@ -940,12 +1044,12 @@ export function authoredItemTitle(
return authoredId;
}
-export function childEntities(
+export function childItems(
context: StudioTrackCompanionContext,
items: readonly {
/** Exact identity of the projected domain item consumed by Temporal/renderer bindings. */
readonly id: string;
- /** Exact author-owned entity realized by this projected item, when the identities differ. */
+ /** Exact author-owned Item realized by this projected item, when the identities differ. */
readonly subjectId?: string;
readonly startFrame: number;
readonly endFrameExclusive: number;
@@ -953,9 +1057,9 @@ export function childEntities(
/** Exact domain Spec types that may carry an omitted Source id. */
readonly sourceTypes?: readonly TypeRef[];
}[],
- entity: StudioTimelinePresentation["entity"],
+ kind: StudioTimelinePresentation["kind"],
chrome: StudioTimelinePresentation["chrome"],
-): readonly StudioEntityDraft[] {
+): readonly StudioItemDraft[] {
return items.map((item) => {
const authoredId = item.subjectId ?? item.id;
const child = authoredChildFor(context, authoredId, item.sourceTypes ?? []);
@@ -965,7 +1069,7 @@ export function childEntities(
const renders = context.spans.filter((span) => span.id === item.id || span.subjectId === authoredId);
const render = renders[0];
return {
- id: `${context.track.outputRef}:entity:${item.id}`,
+ id: `${context.track.outputRef}:item:${item.id}`,
authoredId,
display: { title: authoredId, layers: [] },
startFrame: item.startFrame,
@@ -973,7 +1077,7 @@ export function childEntities(
stackOrder: item.stackOrder,
...(child === undefined ? {} : { elementRange: child.range }),
...(render === undefined ? {} : { presentId: render.id, renderIds: renders.map((span) => span.id) }),
- presentation: { entity, chrome },
+ presentation: { kind, chrome },
};
});
}
diff --git a/packages/studio-companion/test/identity.test.ts b/packages/studio-companion/test/identity.test.ts
index 2c1c055c..f880786d 100644
--- a/packages/studio-companion/test/identity.test.ts
+++ b/packages/studio-companion/test/identity.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { authoredChildFor } from "../src/index.js";
+import { authoredChildFor, createStudioCompanionFacet, studioContributionFromPackage } from "../src/index.js";
import type { StudioTrackCompanionContext } from "../src/index.js";
const itemType = { module: { name: "@example/media", version: "1" }, name: "ItemSpec" } as const;
@@ -22,3 +22,12 @@ test("typed child values recover an omitted authored id without ordinal guessing
assert.equal(authoredChildFor(context, "track.item.0001", [itemType]), child);
assert.equal(authoredChildFor(context, "track.item.0001", [{ ...itemType, module: { ...itemType.module, version: "2" } }]), undefined);
});
+
+test("temporal relation identities are qualified by the selected physical package", () => {
+ const producer = { module: { name: "@example/author", version: "1" }, name: "point" } as const;
+ const contribution = studioContributionFromPackage("@project/author", [createStudioCompanionFacet({
+ temporalRelations: [{ id: "point", match: { producer, output: "point" }, invert: () => [] }],
+ })]);
+ assert.equal(contribution.temporalRelations[0]?.id, "@project/author#point");
+ assert.deepEqual(contribution.temporalRelations[0]?.match, { producer, output: "point" });
+});
diff --git a/packages/studio/INSPECTOR.md b/packages/studio/INSPECTOR.md
index fe9d3e31..7a25a0c9 100644
--- a/packages/studio/INSPECTOR.md
+++ b/packages/studio/INSPECTOR.md
@@ -21,7 +21,7 @@ its color is How, and the object's frame is Where. One field has one owner and o
shown when selected by the Companion, including read-only bindings. The interface orders available
domains as Where, When, How. Read-only values and editable controls share the same sections.
-A projected entity may supply a few computed `inspector` facts without binding them to Source:
+A projected Item may supply a few computed `inspector` facts without binding them to Source:
```ts
inspector: [{ id: "range", label: "Range", domain: "when",
@@ -31,7 +31,7 @@ inspector: [{ id: "range", label: "Range", domain: "when",
The resolved DTO carries an `edit: { language, source }` only for writable author fields.
The UI uses plain selectable text otherwise; the server requires that endpoint for writes.
Choose facts that explain the selected object or its controls. Component headers organize lanes;
-the selected entities own their details. The finite controls are independent of the three domains:
+the selected Items own their details. The finite controls are independent of the three domains:
| Control | Use |
| --- | --- |
diff --git a/packages/studio/README.md b/packages/studio/README.md
index a8838200..40ed74a0 100644
--- a/packages/studio/README.md
+++ b/packages/studio/README.md
@@ -93,7 +93,7 @@ to play or pause; the wider progress control seeks, with a hovered-frame preview
main playhead alone. The hover picture uses one lazy, muted instance of the current preview document,
released when leaving Comments. It needs no Build or thumbnail files.
-Studio retains picture selection and its right-click menu for overlapping Companion entities.
+Studio retains picture selection and its right-click menu for overlapping Companion Items.
Comments uses viewing controls without selecting objects. Switching views preserves the composition
time and Studio's selection; comments themselves only refer to a time and the user's words.
@@ -145,12 +145,19 @@ a separate, planned connection; **Send comment** currently saves the note only.
The selected targets must reach one Film and its resolved time source. Studio rejects several
distinct Films in one view; use separate Runs/sessions for those. A Timeline supplies the complete
-program range and the ruler always shows program time. Independently installed temporal-domain
-Companions may add labelled lanes of anchors, points and spans. Script Studio projects Narrative
-Segments, words, Selections and Moments this way; common Studio has no Narrative slot or
-Narrative-shaped fallback. A beat or shot package can use the same surface without changing Studio.
-Empty domain lanes are omitted based on the whole work, not the visible window or playhead. The
-complete ruler area stays pinned while component tracks scroll.
+program range and the ruler always shows program time. Each package-owned temporal-domain Companion
+may add an exact Projection view. Script Studio gives every Narrative Projection two rows: mapped
+Segments and projected word evidence. Selection and Moment objects that exist only to invert a
+Track/Item edit remain hidden rather than becoming a third semantic-content row. Common Studio has
+no Narrative slot or Narrative-shaped fallback; a beat or shot package can contribute its own two
+or more lanes without changing Studio.
+
+All package-declared primary Window and Instant outputs share one read-only declaration row. Their
+owning Surface Companions select the exact output ports; common Studio only resolves the absolute
+temporal values. Automatically derived Window boundaries, the Timeline's root range and internal
+helpers are not repeated as Items. The resulting time header is one ruler row, the lanes contributed
+by each exact Projection, and one common declaration row. Only the ruler is pinned while all rows
+scroll together with component Tracks.
Domain items retain Companion projection order within each lane. Their fine borders distinguish
adjacent and overlapping intervals without inventing time gaps. Selection raises an object above
@@ -166,8 +173,8 @@ package code or imports that introduce new packages. Browser refresh does not re
server-side package modules.
The Source pane can edit the selected `.svml`, `.svs` or `.svrun` file. The Inspector
-shows project facts when no entity is selected and declared facts and author fields for
-the selected entity. A reference can resolve to a shared Frame or Recipe, so one edit
+shows project facts when no Item is selected and declared facts and author fields for
+the selected Item. A reference can resolve to a shared Frame or Recipe, so one edit
may affect several consumers. Structured fields save together when editing ends and the value is complete; missing required values stay in the editor with a completion hint.
Check save status; source conflicts reject stale edits rather than overwrite newer files.
@@ -182,16 +189,20 @@ their complete extents are reference information in Studio.
Timeline gestures use explicit temporal authority. Moving a shared Selection or
Moment edits Script and moves its consumers after recompilation. A parameter-based
handle edits its exact authored parameter. Fixed or derived values with no supported
-inverse remain read-only. Seeing an entity does not promise every drag gesture.
+inverse remain read-only. Seeing an Item does not promise every drag gesture.
-A direct `during={selection}` move advances both endpoints by the same number of domain
-stops (distinct frame positions), so its duration may change. `at/for` moves its event and
-offers a trailing duration trim; `until/for` offers the corresponding leading trim.
+A direct `during={selection}` move is available only where both semantic endpoints can move by the
+same absolute frame delta, so a move always preserves the Window duration. Trimming one edge keeps
+the opposite absolute edge fixed. For example, trimming the leading edge of `at/for` atomically
+changes the event and duration; trimming the trailing edge of `until/for` does the corresponding
+two-source edit. If the executed author relations cannot satisfy the whole gesture, it stays read-only.
An Instant reference expression edits only its offset; a bare reference has an implicit zero offset.
`start/end` trims edit the corresponding expression; moving the window shifts both by the same
frame delta. Edited clock values and offsets are written in frames at the current Timeline rate.
The domain-item Inspector exposes exact anchor identities and, where a declared handle supports it,
offers choices among coincident anchors. Their meaning and writeback remain package-owned.
+Dragging to a new frame with several distinct valid Anchor identities does not silently select one;
+the author must make that identity choice explicitly.
See [temporal author forms](../temporal/EDITING.md) for the complete behavior.
Tasks and Artifacts are inspection surfaces; selecting an Artifact does not write a
@@ -202,6 +213,12 @@ Run Candidate. Use `build-record`/`satisfy` in the Run for explicit Output reuse
[Inspector fields](INSPECTOR.md) describes Where/When/How grouping, numeric unit conversion,
rich choices, fonts, color suggestions and exact Source writeback.
+The common author surface is `Track -> Item`. `Item` is only Studio's shared selection and
+presentation envelope: Visual and Audio packages retain their own Clip models, Typography retains
+its occurrence model, and project components retain their own domain names. Their Companions decide
+which domain objects become Items and declare each Item's title, interval, layers, Inspector facts,
+bindings and temporal lineage. Studio does not enumerate those domain families.
+
Studio is an application boundary. Core and domain computation do not import it or
register UI metadata. The installed Distribution explicitly selects one independent
Studio Companion per supported official domain. Packages actually selected by the
@@ -219,7 +236,7 @@ subpaths, with `@hypit/hypit` as a development dependency. The active Distributi
at runtime. Ship the Companion's compiled JavaScript with its component package.
The companion owns what its Track means: matching, required same-Surface values,
-entities, lane range, finite chrome, title and ordered text/material layers,
+Items, lane range, finite chrome, title and ordered text/material layers,
source bindings, Inspector fields and executed temporal lineage. Inspector fields
select real bindings or package-owned facts and organize them under the Studio-owned
`Where / When / How` domains, optional companion-owned pages and sections. A
@@ -245,9 +262,18 @@ explicit change through the normal revisioned mutation path.
Temporal lineage comes from the exact executed graph selected by the Run. Studio indexes the
`TemporalInstant` and `TemporalWindow` records in each Track's dependency closure, including each
-endpoint's author authority and direct consumer edge. Common timeline inverses come from that
-authority rather than Companion declarations. Track Companions never infer semantic sources from SVML
-attribute names, runtime id prefixes or coincident frame spans.
+endpoint's author authority and direct consumer edge. Common Temporal relations are handled by the
+shared planner; author packages contribute inverses for their own private construction Producers.
+Studio recursively composes those local relations, merges graph paths that produce the same exact
+author writes and applies only one distinct conflict-free author plan. The graph reader uses the
+same package-owned relations to reconstruct lineage; it does not recognize concrete Temporal or
+domain Producer names.
+Track Companions never infer semantic sources from SVML attribute names, runtime id prefixes or
+coincident frame spans.
+
+Temporal writes remain one Source transaction. After recompilation, Studio checks the rebuilt Item
+against the complete requested absolute-frame constraint; a compiling plan that resolves elsewhere
+is rejected and the original files are restored just like a compilation failure.
Opening Studio never spends and never creates a Build. Its display closure contains
the Candidates selected by the Run, deterministic Producers and exact Needs that
@@ -274,7 +300,7 @@ The preview consumes generic AudioClips: source sampling, fixed gain, program-sa
audibility regions and target-relative fades. Web Audio gain nodes schedule the independent factors
on the same clock, including silence and amplification above unity. Visual video elements stay muted;
the Film's selected AudioTracks own composition sound. Seeking is silent. This path is independent of
-which component emitted a clip.
+which component emitted an audio contribution.
### Interface language
diff --git a/packages/studio/src/common-temporal-relations.ts b/packages/studio/src/common-temporal-relations.ts
new file mode 100644
index 00000000..e8db312e
--- /dev/null
+++ b/packages/studio/src/common-temporal-relations.ts
@@ -0,0 +1,145 @@
+import { temporalProducers, temporalTypes } from "@hypit/hypit/temporal";
+import type {
+ StudioTemporalAuthority,
+ StudioTemporalRelationCompanion,
+ StudioTemporalRelationValue,
+} from "@hypit/studio-companion";
+
+import { formatTemporalPointEdit } from "./temporal-edit.js";
+
+type Instant = { readonly id: string; readonly timelineId: string; readonly frame: number };
+type Timeline = { readonly id: string; readonly frameCount: number };
+type Extent = { readonly frameCount: number };
+type AuthorSpec = {
+ readonly projection?: { readonly ref?: string; readonly at?: unknown; readonly offset?: unknown };
+ readonly direction?: 1 | -1;
+ readonly author?: { readonly binding?: string; readonly relation?: "direct" | "after-start" | "before-end" };
+};
+
+function value<T>(input: StudioTemporalRelationValue | undefined, label: string): T {
+ if (input === undefined) throw new Error(`Common Temporal relation requires ${label}.`);
+ return input.value as T;
+}
+
+function duration(raw: unknown): string {
+ const held = raw as { readonly unit?: string; readonly value?: number; readonly numerator?: number; readonly denominator?: number };
+ if (held.unit === "frames") return `${held.value ?? 0}f`;
+ if (held.unit === "milliseconds") return `${held.value ?? 0}ms`;
+ if (held.unit === "seconds") return held.denominator === 1
+ ? `${held.numerator ?? 0}s` : `${held.numerator ?? 0}/${held.denominator ?? 1}s`;
+ return "?";
+}
+
+function signed(raw: unknown): string {
+ const held = raw as { readonly unit?: string; readonly value?: number; readonly numerator?: number };
+ const negative = held.unit === "seconds" ? (held.numerator ?? 0) < 0 : (held.value ?? 0) < 0;
+ if (!negative) return `+${duration(raw)}`;
+ return held.unit === "seconds"
+ ? `-${duration({ ...held, numerator: Math.abs(held.numerator ?? 0) })}`
+ : `-${duration({ ...held, value: Math.abs(held.value ?? 0) })}`;
+}
+
+function pointExpression(spec: AuthorSpec): string {
+ const projection = spec.projection;
+ if (projection?.ref === "absolute") return `${duration(projection.at)}${projection.offset === undefined ? "" : signed(projection.offset)}`;
+ return typeof projection?.ref !== "string" ? "?"
+ : `${projection.ref}${projection.offset === undefined ? "" : signed(projection.offset)}`;
+}
+
+function parameterAuthority(spec: AuthorSpec, record: string): Extract<StudioTemporalAuthority, { readonly kind: "parameter" }> | undefined {
+ const author = spec.author;
+ return typeof author?.binding === "string" && author.relation !== undefined
+ ? { kind: "parameter", binding: author.binding, owner: `${record}:${author.binding}`, relation: author.relation }
+ : undefined;
+}
+
+export const commonTemporalStudioRelations: readonly StudioTemporalRelationCompanion[] = [{
+ id: "common-compose-window", match: { producer: temporalProducers.composeWindow, output: "window" },
+ invert({ target }) {
+ return target.kind !== "span" ? [] : [{ constraints: [
+ { input: "start", target: { kind: "instant", frame: target.startFrame } },
+ { input: "end", target: { kind: "instant", frame: target.endFrameExclusive } },
+ ] }];
+ },
+ trace({ output, trace }) {
+ const held = output.value as { readonly span?: { readonly startFrame?: number; readonly endFrameExclusive?: number } };
+ const start = trace("start"); const end = trace("end");
+ return start?.kind !== "instant" || end?.kind !== "instant"
+ || !Number.isSafeInteger(held.span?.startFrame) || !Number.isSafeInteger(held.span?.endFrameExclusive)
+ ? undefined : { kind: "window", start, end,
+ startFrame: held.span!.startFrame!, endFrameExclusive: held.span!.endFrameExclusive! };
+ },
+}, {
+ id: "common-reuse-instant", match: { producer: temporalProducers.reuseInstant, output: "instant" },
+ invert({ target }) { return target.kind === "instant" ? [{ constraints: [{ input: "instant", target }] }] : []; },
+ trace({ output, trace }) {
+ const upstream = trace("instant"); const held = value<Instant>(output, "Instant");
+ return upstream?.kind !== "instant" ? undefined : { ...upstream, frame: held.frame };
+ },
+}, {
+ id: "common-project-program-instant", match: { producer: temporalProducers.projectProgramInstant, output: "instant" },
+ invert({ target, inputs }) {
+ if (target.kind !== "instant") return [];
+ const spec = value<AuthorSpec>(inputs.spec, "Instant Spec");
+ const binding = spec.author?.binding;
+ if (typeof binding !== "string") return [];
+ const timeline = value<Timeline>(inputs.timeline, "Timeline");
+ const reference = spec.projection?.ref;
+ const base = reference === "timeline.start" ? 0 : reference === "timeline.end" ? timeline.frameCount : undefined;
+ return [{ writes: [{ input: "spec", binding,
+ replacement: formatTemporalPointEdit(reference === "timeline.start" || reference === "timeline.end" ? reference : "absolute", target.frame, base) }] }];
+ },
+ trace({ output, inputs }) {
+ const specInput = inputs.spec;
+ const timeline = inputs.timeline;
+ if (specInput === undefined || timeline === undefined) return undefined;
+ const point = value<Instant>(output, "Instant");
+ const spec = value<AuthorSpec>(specInput, "Instant Spec");
+ const clock = value<Timeline>(timeline, "Timeline");
+ const authority = parameterAuthority(spec, specInput.record);
+ const reference = spec.projection?.ref;
+ return { kind: "instant", expression: pointExpression(spec),
+ reference: typeof reference === "string" ? reference : "absolute", frame: point.frame,
+ source: { timelineId: point.timelineId, type: timeline.type, kind: "timeline", id: clock.id },
+ authority: authority ?? { kind: "fixed" } };
+ },
+}, {
+ id: "common-shift-instant", match: { producer: temporalProducers.shiftInstant, output: "instant" },
+ invert({ target, inputs, desired }) {
+ if (target.kind !== "instant") return [];
+ const specInput = inputs.spec;
+ const baseInput = inputs.instant;
+ if (specInput === undefined || baseInput === undefined) return [];
+ const spec = value<AuthorSpec>(specInput, "Shift Spec");
+ const base = desired("instant");
+ const baseFrame = base?.kind === "instant" ? base.frame : value<Instant>(baseInput, "base Instant").frame;
+ const direction = spec.direction;
+ if (direction !== 1 && direction !== -1) return [];
+ const count = direction * (target.frame - baseFrame);
+ if (!Number.isSafeInteger(count) || count < 0) return [];
+ if (typeof spec.author?.binding === "string") return [{
+ ...(base === undefined ? { constraints: [{ input: "instant", target: { kind: "instant" as const, frame: baseFrame } }] } : {}),
+ writes: [{ input: "spec", binding: spec.author.binding, replacement: `${count}f` }],
+ }];
+ const held = value<Extent>(inputs.extent, "Extent").frameCount;
+ return [{ constraints: [{ input: "instant", target: { kind: "instant", frame: target.frame - direction * held } }] }];
+ },
+ trace({ output, inputs, trace }) {
+ const held = value<Instant>(output, "Instant");
+ const specInput = inputs.spec;
+ if (specInput === undefined) return undefined;
+ const spec = value<AuthorSpec>(specInput, "Shift Spec");
+ const authority = parameterAuthority(spec, specInput.record);
+ if (authority !== undefined) return { kind: "instant", expression: `${held.frame}f`, reference: "absolute",
+ frame: held.frame, source: { timelineId: held.timelineId, type: output.type, kind: "resolved", id: held.id }, authority };
+ const upstream = trace("instant");
+ return upstream?.kind !== "instant" ? undefined : { ...upstream, frame: held.frame };
+ },
+}, ...[temporalProducers.extentFromDomain, temporalProducers.extentFromDuration].map((producer): StudioTemporalRelationCompanion => ({
+ id: `common-${producer.name}`, match: { producer, output: "extent" },
+ invert({ target, output }) {
+ const current = value<Extent>(output, "Extent");
+ return target.kind === "extent" && target.frameCount === current.frameCount ? [{}] : [];
+ },
+ trace({ output }) { return { kind: "extent", frameCount: value<Extent>(output, "Extent").frameCount }; },
+}))];
diff --git a/packages/studio/src/companion-assembly.ts b/packages/studio/src/companion-assembly.ts
index d9640ca4..359d20ad 100644
--- a/packages/studio/src/companion-assembly.ts
+++ b/packages/studio/src/companion-assembly.ts
@@ -4,6 +4,7 @@ import { studioContributionFromPackage } from "@hypit/studio-companion";
import { fallbackStudioTrackCompanions } from "./fallback-companions.js";
import { StudioCompanionRegistry } from "./studio-registry.js";
+import { commonTemporalStudioRelations } from "./common-temporal-relations.js";
/**
* Assemble the immutable Companion Registry for one Source closure.
@@ -28,6 +29,8 @@ export async function loadStudioCompanionRegistry(input: {
{
films: contributions.flatMap((item) => item.films),
temporalDomains: contributions.flatMap((item) => item.temporalDomains),
+ temporalDeclarations: contributions.flatMap((item) => item.temporalDeclarations),
+ temporalRelations: [...commonTemporalStudioRelations, ...contributions.flatMap((item) => item.temporalRelations)],
parameters: contributions.flatMap((item) => item.parameters),
},
);
diff --git a/packages/studio/src/fallback-companions.ts b/packages/studio/src/fallback-companions.ts
index 0ceda5a9..59dab2d6 100644
--- a/packages/studio/src/fallback-companions.ts
+++ b/packages/studio/src/fallback-companions.ts
@@ -1,4 +1,4 @@
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-companion";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioItemDraft } from "@hypit/studio-companion";
import { artifactPreview, previewLayer, temporalLineageFor, temporalDomainSource } from "@hypit/studio-companion";
import { compositionTypes } from "@hypit/hypit/composition";
import { timelineTypes } from "@hypit/hypit/timeline";
@@ -24,13 +24,13 @@ type TerminalAudioTrack = {
function withTemporalLineage(
context: StudioTrackCompanionContext,
- entity: StudioEntityDraft,
-): StudioEntityDraft {
- const temporal = temporalLineageFor(context, entity.authoredId);
- if (temporal === undefined) return entity;
+ item: StudioItemDraft,
+): StudioItemDraft {
+ const temporal = temporalLineageFor(context, item.authoredId);
+ if (temporal === undefined) return item;
const domainSource = temporalDomainSource(temporal);
return {
- ...entity,
+ ...item,
...(domainSource?.id === undefined
? {}
: { markerId: domainSource.id }),
@@ -38,40 +38,40 @@ function withTemporalLineage(
};
}
-function projectTerminalVisual(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectTerminalVisual(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const presents = new Map(((context.track.value as TerminalVisualTrack).presents ?? [])
.map((present) => [present.id, present] as const));
- return context.generic().map((entity) => {
- const present = entity.presentId === undefined ? undefined : presents.get(entity.presentId);
+ return context.generic().map((item) => {
+ const present = item.presentId === undefined ? undefined : presents.get(item.presentId);
const material = present?.elements?.find((element) =>
(element.kind === "image" || element.kind === "video") && element.artifact?.resource !== undefined);
const resource = material?.artifact?.resource;
return withTemporalLineage(context, {
- ...entity,
+ ...item,
...(present?.subjectId === undefined ? {} : { authoredId: present.subjectId }),
display: {
- title: present?.subjectId ?? entity.display.title,
+ title: present?.subjectId ?? item.display.title,
layers: resource === undefined ? [] : [previewLayer(artifactPreview(material?.kind === "image" ? "image" : "video", resource), material?.kind === "image" ? "repeat-x" : "storyboard")],
},
- presentation: { entity: "media-item", chrome: "standard" },
+ presentation: { kind: "media-item", chrome: "standard" },
});
});
}
-function projectTerminalAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectTerminalAudio(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const clips = new Map(((context.track.value as TerminalAudioTrack).clips ?? [])
.map((clip) => [clip.id, clip] as const));
- return context.generic().map((entity, index) => {
+ return context.generic().map((item, index) => {
const clip = clips.get(context.spans[index]?.id ?? "");
const resource = clip?.artifact?.resource;
return withTemporalLineage(context, {
- ...entity,
+ ...item,
...(clip?.subjectId === undefined ? {} : { authoredId: clip.subjectId }),
display: {
- title: clip?.subjectId ?? entity.display.title,
+ title: clip?.subjectId ?? item.display.title,
layers: resource === undefined ? [] : [previewLayer(artifactPreview("audio", resource), "waveform")],
},
- presentation: { entity: "audio-clip", chrome: "standard" },
+ presentation: { kind: "audio-clip", chrome: "standard" },
});
});
}
@@ -91,7 +91,7 @@ export const fallbackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
},
{
id: "@hypit/studio#visual-track", role: "track", output: { type: compositionTypes.visualTrack },
- family: "media", tone: "blue", icon: "video",
+ family: "visual", tone: "blue", icon: "video",
project: projectTerminalVisual,
lane: { heightPx: 76 },
},
diff --git a/packages/studio/src/parameters.ts b/packages/studio/src/parameters.ts
index e260f517..8c844dda 100644
--- a/packages/studio/src/parameters.ts
+++ b/packages/studio/src/parameters.ts
@@ -6,7 +6,8 @@ import type {
StudioSourceBinding,
StudioSourceBindingDeclaration,
StudioRecipeReferenceBindingDeclaration,
- StudioEntityDraft,
+ StudioItemDraft,
+ StudioInspectorObjectDraft,
StudioEditSource,
StudioPlacement,
StudioEditHandle,
@@ -27,6 +28,8 @@ import type { StudioCompanionRegistry } from "./studio-registry.js";
import type { Range } from "./shared.js";
import type { Placement } from "./observe.js";
+type StudioParameterDraft = StudioItemDraft | StudioInspectorObjectDraft;
+
export type StudioSourceFile = {
readonly path: string;
readonly text: string;
@@ -84,7 +87,7 @@ function sameRange(left: Range | undefined, right: Range | undefined): boolean {
return left !== undefined && right !== undefined && left.start === right.start && left.end === right.end;
}
-function elementFor(placement: StudioPlacement, draft: StudioEntityDraft): AuthorElement | undefined {
+function elementFor(placement: StudioPlacement, draft: StudioParameterDraft): AuthorElement | undefined {
const candidates: readonly (AuthorElement & { readonly id?: string; readonly range: Range })[] = [
{
...(placement.authorElement === undefined ? {} : { authorElement: placement.authorElement }),
@@ -138,7 +141,7 @@ function recipeParameters(input: {
readonly root: string;
readonly files: readonly StudioSourceFile[];
readonly current: StudioSourceFile;
- readonly draft: StudioEntityDraft;
+ readonly draft: StudioParameterDraft;
readonly referenceName: string;
readonly referencePath: string;
readonly referenceRef?: string;
@@ -225,7 +228,7 @@ function recipeParameters(input: {
});
}
-function attributeGroup(file: StudioSourceFile, target: AuthorElement, draft: StudioEntityDraft,
+function attributeGroup(file: StudioSourceFile, target: AuthorElement, draft: StudioParameterDraft,
declaration: StudioSourceBindingDeclaration, binding: string, root: string): readonly StudioSourceBinding[] {
if (declaration.schema === undefined) throw new Error(`Attribute group ${binding} needs a schema.`);
const tag = parseOpeningTag({ name: file.path, text: file.text }, target.range.start);
@@ -261,7 +264,7 @@ function attributeGroup(file: StudioSourceFile, target: AuthorElement, draft: St
range: sourceRange, preimage }, attributes: { insertionOffset: opening[0].length, ranges } }];
}
-function omittedAttribute(file: StudioSourceFile, target: AuthorElement, draft: StudioEntityDraft,
+function omittedAttribute(file: StudioSourceFile, target: AuthorElement, draft: StudioParameterDraft,
declaration: StudioSourceBindingDeclaration, binding: string, root: string): readonly StudioSourceBinding[] {
const value = typeof declaration.fallback === "function" ? declaration.fallback(target.attributes) : declaration.fallback;
if (value === undefined) return [];
@@ -279,7 +282,7 @@ function omittedAttribute(file: StudioSourceFile, target: AuthorElement, draft:
function referencedParameters(input: {
readonly root: string;
readonly files: readonly StudioSourceFile[];
- readonly draft: StudioEntityDraft;
+ readonly draft: StudioParameterDraft;
readonly referenceName: string;
readonly referencePath: string;
readonly referenceRef?: string;
@@ -342,7 +345,7 @@ function referencedParameters(input: {
function parameterReference(
element: AuthorElement,
- draft: StudioEntityDraft,
+ draft: StudioParameterDraft,
name: string,
): { readonly path: string; readonly ref?: string } | undefined {
const projected = draft.parameterReferences?.[name];
@@ -356,7 +359,7 @@ function parameterReference(
/** Resolve only references opted into by the consuming Companion. */
export function composeParameterDeclarations(input: {
readonly placement: StudioPlacement | undefined;
- readonly draft: StudioEntityDraft;
+ readonly draft: StudioParameterDraft;
readonly placements: readonly Placement[];
readonly registry: StudioCompanionRegistry;
readonly bindings: readonly StudioSourceBindingDeclaration[];
@@ -393,7 +396,7 @@ export function sourceBindingsForDraft(input: {
readonly root: string;
readonly files: readonly StudioSourceFile[];
readonly placement: StudioPlacement | undefined;
- readonly draft: StudioEntityDraft;
+ readonly draft: StudioParameterDraft;
readonly declarations: readonly StudioSourceBindingDeclaration[];
readonly placements?: readonly Placement[];
}): readonly StudioSourceBinding[] {
@@ -469,9 +472,9 @@ export function sourceBindingsForDraft(input: {
return [...direct, ...recipes];
}
-/** Resolve the Companion's visible field table against real bindings and entity facts. */
+/** Resolve the Companion's visible field table against real bindings and Item facts. */
export function inspectorFieldsForBindings(
- draft: StudioEntityDraft,
+ draft: StudioParameterDraft,
bindings: readonly StudioSourceBinding[],
declarations: readonly StudioInspectorFieldDeclaration[],
): readonly StudioInspectorField[] {
@@ -501,19 +504,6 @@ export function inspectorFieldsForBindings(
}))];
}
-/** Runtime authority, rather than a Companion allowlist, makes timing fields writable. */
-export function temporalBindingDeclarations(
- temporal?: StudioTemporalLineage,
-): readonly StudioSourceBindingDeclaration[] {
- if (temporal === undefined) return [];
- const endpoints = temporal.projection.kind === "instant"
- ? [temporal.projection]
- : [temporal.projection.start, temporal.projection.end];
- return [...new Set(endpoints.flatMap((endpoint) => endpoint.authority.kind === "parameter"
- ? [endpoint.authority.binding]
- : []))].map((name) => ({ name, writable: true }));
-}
-
/** Resolve finite timeline gestures from the exact endpoint authorities in the executed graph. */
export function resolveTimelineEditHandles(
bindings: readonly StudioSourceBinding[],
@@ -524,7 +514,7 @@ export function resolveTimelineEditHandles(
for (const binding of bindings) {
// Timing source attributes live in SVML. A nested Recipe may legitimately
// also have a property named `start`; it must never shadow the author
- // window when a clip is being dragged.
+ // window when a Studio Item is being dragged.
if (binding.language === "svml" && !byName.has(binding.binding)) byName.set(binding.binding, binding);
}
const writable = (binding: StudioSourceBinding | undefined): binding is StudioSourceBinding =>
@@ -552,7 +542,7 @@ export function resolveTimelineEditHandles(
&& candidate.domain?.id === first.domain?.id)) return undefined;
const view = domains.find((candidate) => candidate.timelineId === first.timelineId
&& candidate.companion === first.domain!.companion && candidate.id === first.domain!.id);
- const item = view?.items.find((candidate) => candidate.editable === true
+ const item = view?.editItems.find((candidate) => candidate.editable === true
&& candidate.source !== undefined
&& sameType(candidate.source.type, first.type)
&& candidate.source.kind === first.kind && candidate.source.id === first.id);
@@ -568,15 +558,18 @@ export function resolveTimelineEditHandles(
const handle = (
gesture: StudioTimelineGesture,
- affected: readonly { readonly endpoint: StudioTemporalInstantProjection; readonly role: "start" | "end" }[],
+ changed: readonly { readonly endpoint: StudioTemporalInstantProjection; readonly role: "start" | "end" }[],
+ constrained: readonly { readonly endpoint: StudioTemporalInstantProjection; readonly role: "start" | "end" }[],
moveEffect?: "translate-window" | "move-start",
): StudioEditHandle => {
- const unavailable = affected.find(({ endpoint }) => endpoint.authority.kind === "fixed");
+ const unavailable = changed.find(({ endpoint }) => endpoint.authority.kind === "fixed");
if (unavailable !== undefined) return disabled(gesture, "该时间表达未开放时间轴回写。");
const projected: ({ readonly missing: string } | StudioEditSource)[] = [];
- for (const { endpoint, role } of affected) {
+ for (const { endpoint, role } of constrained) {
if (endpoint.authority.kind !== "parameter") continue;
- const binding = byName.get(endpoint.authority.binding);
+ if (endpoint.authority.relation === "direct"
+ && !changed.some((candidate) => candidate.endpoint === endpoint)) continue;
+ const binding = byName.get(endpoint.authority.owner ?? endpoint.authority.binding);
if (!writable(binding)) {
projected.push({ missing: endpoint.authority.binding });
continue;
@@ -590,7 +583,7 @@ export function resolveTimelineEditHandles(
if (missing !== undefined && "missing" in missing) {
return disabled(gesture, `投影参数 ${missing.missing} 在当前作者源码中不可写。`);
}
- const domainEndpoints = affected.filter(({ endpoint }) => endpoint.authority.kind === "domain").map(({ endpoint }) => endpoint);
+ const domainEndpoints = changed.filter(({ endpoint }) => endpoint.authority.kind === "domain").map(({ endpoint }) => endpoint);
const target = domainTarget(domainEndpoints);
if (domainEndpoints.length > 0 && target === undefined) {
return disabled(gesture, "时间域端点在当前 Candidate 中没有可写的作者身份。");
@@ -607,23 +600,19 @@ export function resolveTimelineEditHandles(
...(sources.length === 0 ? {} : { sources }),
...(target === undefined ? {} : { domain: target }),
temporal: projection,
+ temporalRecord: temporal.record,
};
};
if (projection.kind === "instant") {
- return [handle("move", [{ endpoint: projection, role: "start" }], "move-start")];
+ const point = [{ endpoint: projection, role: "start" as const }];
+ return [handle("move", point, point, "move-start")];
}
const start = { endpoint: projection.start, role: "start" as const };
const end = { endpoint: projection.end, role: "end" as const };
- if (projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start") {
- return [handle("move", [start], "translate-window"), handle("trim-end", [end])];
- }
- if (projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end") {
- return [handle("move", [end], "translate-window"), handle("trim-start", [start])];
- }
return [
- handle("move", [start, end], "translate-window"),
- handle("trim-start", [start]),
- handle("trim-end", [end]),
+ handle("move", [start, end], [start, end], "translate-window"),
+ handle("trim-start", [start], [start, end]),
+ handle("trim-end", [end], [start, end]),
];
}
diff --git a/packages/studio/src/projection.ts b/packages/studio/src/projection.ts
index 7157c220..bca5ea5c 100644
--- a/packages/studio/src/projection.ts
+++ b/packages/studio/src/projection.ts
@@ -5,6 +5,7 @@ import type { Composition } from "@hypit/hypit/composition";
import { compositionTypes } from "@hypit/hypit/composition";
import { timelineTypes, assertTimelineIdentity } from "@hypit/hypit/timeline";
import type { Timeline } from "@hypit/hypit/timeline";
+import { temporalTypes } from "@hypit/hypit/temporal";
import type { StudioObservedValue, StudioResolvedTrack, StudioTemporalBinding } from "@hypit/studio-companion";
import type { CliTransientExecution as RuntimeHostTransientExecution } from "@hypit/hypit/cli";
@@ -24,11 +25,14 @@ function playable(type: import("@hypit/hypit/protocol").TypeRef): boolean {
export type BuiltTrack = StudioResolvedTrack;
export type StudioProjection = {
+ /** Server-only executed graph retained for exact Studio inverse traversal. */
+ readonly state: ExecutionState;
readonly source: CompiledSource;
readonly tracks: readonly BuiltTrack[];
/** Resolved Companion realizations keyed by exact graph output ref. */
readonly values: ReadonlyMap<string, unknown>;
readonly temporalDomainValues: readonly StudioObservedValue[];
+ readonly temporalValues: readonly StudioObservedValue[];
readonly temporalBindings: ReadonlyMap<string, readonly StudioTemporalBinding[]>;
readonly composition: Composition;
readonly timingOutput?: { readonly name: string; readonly ref: string };
@@ -205,7 +209,12 @@ export async function resolveStudioProjection(input: {
});
const temporalBindings = new Map(tracks.map((track) => [
track.outputRef,
- executedTemporalBindings(executed.state, track.outputRef, (type, value) => input.registry.identifyTemporalSource(type, value)),
+ executedTemporalBindings(
+ executed.state,
+ track.outputRef,
+ (type, value) => input.registry.identifyTemporalSource(type, value),
+ (producer, output) => input.registry.temporalRelationFor(producer, output),
+ ),
] as const));
const values = new Map<string, unknown>();
for (const target of targets) {
@@ -223,19 +232,31 @@ export async function resolveStudioProjection(input: {
}
const temporalValueTypes = input.registry.temporalDomainValueTypes();
const temporalDomainValues: StudioObservedValue[] = [];
+ const temporalValues: StudioObservedValue[] = [];
+ const temporalDomainValueIds = new Set<string>();
+ const temporalValueIds = new Set<string>();
for (const record of [...executed.state.program.records, ...executed.state.records]) {
- if (!temporalValueTypes.some((type) => sameType(type, record.type)) || record.value.kind !== "inline") continue;
+ if (record.value.kind !== "inline") continue;
+ if ((sameType(record.type, temporalTypes.instant) || sameType(record.type, temporalTypes.window))
+ && !temporalValueIds.has(record.id)) {
+ temporalValues.push({ id: record.id, type: record.type, value: record.value.value });
+ temporalValueIds.add(record.id);
+ }
+ if (!temporalValueTypes.some((type) => sameType(type, record.type))) continue;
values.set(record.id, record.value.value);
- if (!temporalDomainValues.some((item) => item.id === record.id)) {
+ if (!temporalDomainValueIds.has(record.id)) {
temporalDomainValues.push({ id: record.id, type: record.type, value: record.value.value });
+ temporalDomainValueIds.add(record.id);
}
}
const timingCandidateId = satisfactions.get(input.timeRef);
return {
+ state: executed.state,
source: input.source,
tracks,
values,
temporalDomainValues,
+ temporalValues,
temporalBindings,
composition,
timingOutput: { name: timingOutput?.name ?? timeline.id, ref: input.timeRef },
diff --git a/packages/studio/src/server.ts b/packages/studio/src/server.ts
index 183aa13d..c0ff6fcb 100644
--- a/packages/studio/src/server.ts
+++ b/packages/studio/src/server.ts
@@ -9,7 +9,6 @@ import { pipeline } from "node:stream/promises";
import type { Plugin, ViteDevServer } from "vite";
import type { BuildResultFileRange } from "@hypit/hypit/result";
import type { StudioTemporalInstantProjection } from "@hypit/studio-companion";
-import { sameType } from "@hypit/hypit/protocol";
import type { StudioBuildLibrary } from "./build-library.js";
import type { ServedFile } from "./compile.js";
@@ -19,11 +18,13 @@ import { loadStudioRun } from "./run.js";
import { allowsStudioMutation } from "./mutation-origin.js";
import { parameterAuthorValue, parameterOption, serializeParameterValue, serializeAttributeGroup, validateParameterValue } from "./parameter-values.js";
import { readStudioSession } from "./session.js";
+import type { StudioSession } from "./session.js";
import type { Range, StudioFailure, StudioLibraryRequest, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
import { createStudioStoryboard } from "./storyboard.js";
import type { StudioStoryboard } from "./storyboard.js";
import { findSurfacePreview } from "./surface-preview.js";
-import { formatTemporalPointEdit, domainGestureSpan } from "./temporal-edit.js";
+import { domainGestureSpan } from "./temporal-edit.js";
+import { planTemporalInverse, temporalAuthorBindings } from "./temporal-inverse.js";
import { replaceSourceFiles } from "./source-transaction.js";
export type StudioPluginOptions = {
@@ -86,6 +87,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
let visualDocument: import("@hypit/hypit/html-program").HtmlProgram | undefined;
let failure: StudioFailure | undefined;
let material: ReadonlyMap<string, ServedFile> = new Map();
+ let temporalEdit: StudioSession["temporalEdit"] | undefined;
let revision = 0;
let server: ViteDevServer | undefined;
let timer: ReturnType<typeof setTimeout> | undefined;
@@ -165,6 +167,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
visualHtml = result.visualHtml;
visualDocument = result.document;
material = result.material;
+ temporalEdit = result.temporalEdit;
failure = undefined;
if (notify) server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
} catch (error) {
@@ -250,26 +253,39 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
return new Map([...previousFiles].filter(([absolute]) => nextFiles.has(absolute)));
};
- const currentClip = (entityId: string): StudioSnapshot["tracks"][number]["clips"][number] => {
- const found = snapshot?.tracks.flatMap((track) => track.clips).find((clip) => clip.id === entityId);
- if (found === undefined) throw new Error(`Studio entity ${entityId} no longer exists.`);
+ const currentItem = (itemId: string): StudioSnapshot["tracks"][number]["items"][number] => {
+ const found = snapshot?.tracks.flatMap((track) => track.items).find((item) => item.id === itemId);
+ if (found === undefined) throw new Error(`Studio Item ${itemId} no longer exists.`);
return found;
};
+ const currentParameterOwner = (
+ owner: Extract<StudioMutation, { readonly type: "parameter.adjust" }>["owner"],
+ ): { readonly label: string; readonly inspector: StudioSnapshot["tracks"][number]["items"][number]["inspector"] } => {
+ if (owner.kind === "item") {
+ const item = currentItem(owner.itemId);
+ return { label: `Item ${owner.itemId}`, inspector: item.inspector };
+ }
+ const track = snapshot?.tracks.find((candidate) => candidate.id === owner.trackId);
+ const object = track?.inspectorObjects.find((candidate) => candidate.id === owner.objectId);
+ if (object === undefined) throw new Error(`Studio Inspector object ${owner.objectId} no longer exists.`);
+ return { label: `Inspector object ${owner.objectId}`, inspector: object.inspector };
+ };
+
const timelinePatches = async (
mutation: Extract<StudioMutation, { readonly type: "timeline.adjust" }>,
): Promise<readonly Patch[]> => {
- const clip = currentClip(mutation.entityId);
- const handle = clip.editHandles.find((candidate) =>
+ const item = currentItem(mutation.itemId);
+ const handle = item.editHandles.find((candidate) =>
candidate.operation === "timeline.adjust"
&& candidate.gesture === mutation.gesture
&& candidate.enabled);
- if (handle === undefined) throw new Error(`Entity ${mutation.entityId} does not allow ${mutation.gesture}.`);
+ if (handle === undefined) throw new Error(`Item ${mutation.itemId} does not allow ${mutation.gesture}.`);
const temporal = handle.temporal;
- if (temporal === undefined) throw new Error("This timeline entity has no authoring authority.");
+ if (temporal === undefined) throw new Error("This timeline Item has no authoring authority.");
if (temporal.kind !== mutation.target.kind) {
- throw new Error(`This timeline entity requires a ${temporal.kind} mutation target.`);
+ throw new Error(`This timeline Item requires a ${temporal.kind} mutation target.`);
}
const startFrame = mutation.target.kind === "instant" ? mutation.target.frame : mutation.target.startFrame;
const endFrameExclusive = mutation.target.kind === "instant" ? mutation.target.frame + 1 : mutation.target.endFrameExclusive;
@@ -280,13 +296,13 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
}
if (temporal.kind === "window") {
if (mutation.gesture === "move" && handle.domain?.kind !== "span"
- && endFrameExclusive - startFrame !== clip.endFrameExclusive - clip.startFrame) {
+ && endFrameExclusive - startFrame !== item.endFrameExclusive - item.startFrame) {
throw new Error("Move must preserve the Window duration.");
}
- if (mutation.gesture === "trim-start" && endFrameExclusive !== clip.endFrameExclusive) {
+ if (mutation.gesture === "trim-start" && endFrameExclusive !== item.endFrameExclusive) {
throw new Error("Trim start cannot change the Window end.");
}
- if (mutation.gesture === "trim-end" && startFrame !== clip.startFrame) {
+ if (mutation.gesture === "trim-end" && startFrame !== item.startFrame) {
throw new Error("Trim end cannot change the Window start.");
}
} else if (mutation.gesture !== "move") {
@@ -301,7 +317,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
|| handle.domain.companion !== domainTarget.companion
|| handle.domain.domainId !== domainTarget.domainId
|| handle.domain.itemId !== domainTarget.itemId) {
- throw new Error(`Entity ${mutation.entityId} is not bound to the requested temporal-domain item.`);
+ throw new Error(`Item ${mutation.itemId} is not bound to the requested temporal-domain item.`);
}
const current = snapshot;
const domain = current?.temporalDomains.find((candidate) => candidate.companion === domainTarget.companion
@@ -335,9 +351,6 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
});
}
- const source = (role: "start" | "end" | "duration") =>
- handle.sources?.find((candidate) => candidate.role === role)?.source;
- const frame = (value: number): string => `${value}f`;
const domainFrame = (endpoint: StudioTemporalInstantProjection): number | undefined => {
if (endpoint.authority.kind !== "domain" || domainTarget === undefined || handle.domain === undefined) return undefined;
const domain = snapshot?.temporalDomains.find((candidate) => candidate.companion === domainTarget.companion
@@ -353,62 +366,37 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
}
return undefined;
};
- const projectionBaseFrame = (endpoint: StudioTemporalInstantProjection): number | undefined => {
- if (endpoint.reference === "absolute") return undefined;
- if (endpoint.reference === "timeline.start") return 0;
- if (endpoint.reference === "timeline.end") return snapshot?.timeline.frameCount;
- const domain = endpoint.source.domain;
- const view = domain === undefined ? undefined : snapshot?.temporalDomains.find((candidate) =>
- candidate.companion === domain.companion && candidate.id === domain.id);
- const item = view?.items.find((candidate) => candidate.source !== undefined
- && sameType(candidate.source.type, endpoint.source.type)
- && candidate.source.kind === endpoint.source.kind && candidate.source.id === endpoint.source.id);
- if (item === undefined) return undefined;
- if (item.kind === "point") return item.frame;
- return endpoint.authority.kind === "domain" && endpoint.authority.boundary === "start"
- ? item.startFrame : item.endFrameExclusive;
- };
- const projectedPointValue = (endpoint: StudioTemporalInstantProjection, desired: number): string =>
- formatTemporalPointEdit(endpoint.reference, desired, projectionBaseFrame(endpoint));
- const writeEndpoint = (
- endpoint: StudioTemporalInstantProjection,
- desired: number,
- role: "start" | "end",
- ): void => {
- if (desired === endpoint.frame) return;
- if (endpoint.authority.kind === "fixed") throw new Error(`The ${role} endpoint has no timeline write target.`);
- if (endpoint.authority.kind === "domain") {
- if (domainFrame(endpoint) !== desired) throw new Error(`The ${role} endpoint does not match its temporal-domain Anchor.`);
- return;
- }
- if (endpoint.authority.relation !== "direct") return;
- const author = source(role);
- if (author === undefined) throw new Error(`The ${role} projection has no writable Source binding.`);
- patches.push({ ...author, replacement: projectedPointValue(endpoint, desired) });
- };
- if (temporal.kind === "instant") {
- writeEndpoint(temporal, startFrame, "start");
- } else {
- writeEndpoint(temporal.start, startFrame, "start");
- writeEndpoint(temporal.end, endFrameExclusive, "end");
- const derived = [temporal.start, temporal.end].find((endpoint) =>
- endpoint.authority.kind === "parameter" && endpoint.authority.relation !== "direct");
- if (derived !== undefined
- && endFrameExclusive - startFrame !== temporal.endFrameExclusive - temporal.startFrame) {
- const author = source("duration");
- if (author === undefined) throw new Error("The projected duration has no writable Source binding.");
- patches.push({ ...author, replacement: frame(endFrameExclusive - startFrame) });
- }
+ if (temporalEdit === undefined || handle.temporalRecord === undefined) {
+ throw new Error("This timeline Item has no executed Temporal edit graph.");
}
+ const bindings = temporalAuthorBindings({
+ state: temporalEdit.state,
+ rootRecord: handle.temporalRecord,
+ workspaceRoot: options.workspaceRoot,
+ placements: temporalEdit.placements,
+ files: temporalEdit.files,
+ });
+ const writes = planTemporalInverse({
+ state: temporalEdit.state,
+ rootRecord: handle.temporalRecord,
+ target: temporal.kind === "instant"
+ ? { kind: "instant", frame: startFrame }
+ : { kind: "window", startFrame, endFrameExclusive },
+ bindings,
+ domainFrame,
+ registry: options.registry,
+ identify: (type, value) => options.registry.identifyTemporalSource(type, value),
+ });
+ patches.push(...writes.map((write) => ({ ...write.source, replacement: write.replacement })));
return patches.filter((patch) => patch.replacement !== patch.preimage);
};
const mutationPatches = async (mutation: StudioMutation): Promise<readonly Patch[]> => {
if (mutation.type === "timeline.adjust") return timelinePatches(mutation);
- const clip = currentClip(mutation.entityId);
- const parameter = clip.inspector.find((candidate) => candidate.id === mutation.parameterId);
+ const owner = currentParameterOwner(mutation.owner);
+ const parameter = owner.inspector.find((candidate) => candidate.id === mutation.parameterId);
if (parameter?.edit === undefined) {
- throw new Error(`Entity ${mutation.entityId} has no writable parameter ${mutation.parameterId}.`);
+ throw new Error(`${owner.label} has no writable parameter ${mutation.parameterId}.`);
}
const authorValue = parameterAuthorValue(parameter, mutation.value);
if (parameter.schema !== undefined) {
@@ -455,11 +443,24 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
const previous = await applyTransaction(patches, mutation.revision);
const attempt = ++requestedRevision;
await publish(attempt, false);
- if (failure?.revision !== attempt) {
+ const temporalMismatch = mutation.type !== "timeline.adjust" || failure?.revision === attempt
+ ? undefined
+ : (() => {
+ const item = snapshot?.tracks.flatMap((track) => track.items)
+ .find((candidate) => candidate.id === mutation.itemId);
+ if (item === undefined) return `Item ${mutation.itemId} disappeared after recompilation.`;
+ return mutation.target.kind === "instant"
+ ? item.startFrame === mutation.target.frame ? undefined
+ : `Item ${mutation.itemId} resolved to frame ${item.startFrame}, not ${mutation.target.frame}.`
+ : item.startFrame === mutation.target.startFrame
+ && item.endFrameExclusive === mutation.target.endFrameExclusive ? undefined
+ : `Item ${mutation.itemId} resolved to [${item.startFrame}, ${item.endFrameExclusive}), not [${mutation.target.startFrame}, ${mutation.target.endFrameExclusive}).`;
+ })();
+ if (failure?.revision !== attempt && temporalMismatch === undefined) {
server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
return attempt;
}
- const rejected = failure.error;
+ const rejected = temporalMismatch ?? failure!.error;
await replaceSourceFiles(previous);
await publish(++requestedRevision, false);
server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
@@ -569,18 +570,23 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
for await (const chunk of request) chunks.push(Buffer.from(chunk));
const body = JSON.parse(Buffer.concat(chunks).toString("utf8")) as Partial<StudioMutation>;
if ((body.type !== "timeline.adjust" && body.type !== "parameter.adjust")
- || typeof body.revision !== "number"
- || typeof body.entityId !== "string") {
+ || typeof body.revision !== "number") {
json(response, 400, { error: "Expected a Studio author mutation." });
return;
}
if (body.type === "timeline.adjust"
- && (typeof body.gesture !== "string" || typeof body.target !== "object" || body.target === null)) {
+ && (typeof body.itemId !== "string" || typeof body.gesture !== "string"
+ || typeof body.target !== "object" || body.target === null)) {
json(response, 400, { error: "Expected a timeline gesture and target." });
return;
}
if (body.type === "parameter.adjust"
- && (typeof body.parameterId !== "string" || body.value === undefined)) {
+ && (typeof body.parameterId !== "string" || body.value === undefined
+ || typeof body.owner !== "object" || body.owner === null
+ || (body.owner.kind === "item" && typeof body.owner.itemId !== "string")
+ || (body.owner.kind === "track-object"
+ && (typeof body.owner.trackId !== "string" || typeof body.owner.objectId !== "string"))
+ || (body.owner.kind !== "item" && body.owner.kind !== "track-object"))) {
json(response, 400, { error: "Expected a parameter identity and value." });
return;
}
diff --git a/packages/studio/src/session.ts b/packages/studio/src/session.ts
index db6031e9..e4172af0 100644
--- a/packages/studio/src/session.ts
+++ b/packages/studio/src/session.ts
@@ -17,6 +17,8 @@ import { snapshot } from "./snapshot.js";
import { inspectStudioRun } from "./studio-preflight.js";
import type { StudioViewRequirement } from "./studio-preflight.js";
import type { StudioSourceFile } from "./parameters.js";
+import type { BuildState } from "@hypit/hypit/protocol";
+import type { Placement } from "./observe.js";
function sourceFiles(run: RunPlan): readonly StudioSourceFile[] {
const paths = [run.runPath, run.authorSource, ...run.source.compiled.closure.units.map((unit) => unit.id)];
@@ -52,6 +54,11 @@ export type StudioSession = {
readonly material: ReadonlyMap<string, ServedFile>;
readonly observations: Observations;
readonly projections: readonly StudioViewRequirement[];
+ readonly temporalEdit: {
+ readonly state: BuildState;
+ readonly files: readonly StudioSourceFile[];
+ readonly placements: readonly Placement[];
+ };
};
export async function readStudioSession(input: {
@@ -112,5 +119,10 @@ export async function readStudioSession(input: {
material: built.served,
observations: source.observations,
projections: inspection.projections,
+ temporalEdit: {
+ state: built.state,
+ files,
+ placements: built.source.observations.placements,
+ },
};
}
diff --git a/packages/studio/src/shared.ts b/packages/studio/src/shared.ts
index c4375984..9f20b3a0 100644
--- a/packages/studio/src/shared.ts
+++ b/packages/studio/src/shared.ts
@@ -5,11 +5,10 @@
import type {
Range,
- StudioEntityDisplay,
+ StudioItemDisplay,
StudioIcon,
StudioEditHandle,
StudioLaneDescription,
- StudioTrackBand,
StudioMaterialPreview,
StudioInspectorField,
StudioInspectorDomain,
@@ -28,7 +27,7 @@ import type { CanonicalValue } from "@hypit/hypit/protocol";
export type {
Range,
- StudioEntityDisplay,
+ StudioItemDisplay,
StudioIcon,
StudioEditHandle,
StudioLaneDescription,
@@ -61,7 +60,6 @@ export type StudioTrackBinding = {
readonly companion: string;
/** Studio-local partition key for an attached projection. */
readonly attachmentId?: string;
- readonly bands?: readonly Omit<StudioTrackBand, "bindings" | "inspector">[];
readonly lane: StudioLaneDescription;
readonly authoredTag?: string;
readonly references: readonly { readonly name: string; readonly type: string }[];
@@ -87,18 +85,17 @@ export type CandidateProvenance = {
* measured from the rendered picture rather than restated here, because motion
* moves it and only the picture knows where it ended up.
*/
-export type Clip = {
- /** Studio identity. Output-qualified so sibling Track clips cannot collide. */
+export type StudioItem = {
+ /** Studio identity. Output-qualified so sibling Track Items cannot collide. */
readonly id: string;
- /** Renderer identity, present only when this clip paints a Visual Present. */
+ /** Renderer identity, present only when this Item paints a Visual Present. */
readonly presentId?: string;
/** The authored id this Present is named after, when it names one. */
readonly authoredId: string;
readonly selectionGroup?: string;
- readonly band?: string;
/** The Script marker that placed it, when something said put it there. */
readonly markerId?: string;
- readonly display: StudioEntityDisplay;
+ readonly display: StudioItemDisplay;
readonly startFrame: number;
readonly endFrameExclusive: number;
/** Where that authored tag was written. */
@@ -106,20 +103,31 @@ export type Clip = {
readonly stackOrder: number;
readonly presentation: StudioTimelinePresentation;
readonly temporal?: StudioTemporalLineage;
- /** Rendering identities implementing this author entity; optional for non-visual entities. */
+ /** Rendering identities implementing this author Item; optional for non-visual Items. */
readonly renderIds: readonly string[];
/** Companion-selected writable fields; hidden source bindings never cross into this surface. */
readonly inspector: readonly StudioInspectorField[];
readonly editHandles: readonly StudioEditHandle[];
};
-export type Track = {
+export type StudioInspectorObject = {
+ readonly id: string;
+ /** Package-owned grouping label, such as Presentation Rules. */
+ readonly group: string;
+ readonly title: string;
+ readonly elementRange?: Range;
+ readonly inspector: readonly StudioInspectorField[];
+};
+
+export type StudioTrack = {
/** Exact LogicalOutput ref; labels are not identities. */
readonly id: string;
readonly label: string;
/** Render order in the timeline; 0 is the top row. */
readonly row: number;
- readonly clips: readonly Clip[];
+ readonly items: readonly StudioItem[];
+ /** Track-owned author objects that are rules or parameters, not timeline occurrences. */
+ readonly inspectorObjects: readonly StudioInspectorObject[];
readonly binding: StudioTrackBinding;
/** Which resolved Run candidate produced this Track, or why it did not. */
readonly provenance: CandidateProvenance;
@@ -229,7 +237,7 @@ export type StudioSnapshot = {
readonly frameCount: number;
readonly durationSec: number;
};
- readonly tracks: readonly Track[];
+ readonly tracks: readonly StudioTrack[];
/** Package-contributed temporal views projected onto the same absolute ruler. */
readonly temporalDomains: readonly TemporalDomainView[];
/** The Tracks, compiled into the document the renderer photographs. */
@@ -246,7 +254,7 @@ export type StudioMutation =
| {
readonly type: "timeline.adjust";
readonly revision: number;
- readonly entityId: string;
+ readonly itemId: string;
readonly gesture: StudioTimelineGesture;
readonly target:
| {
@@ -264,7 +272,9 @@ export type StudioMutation =
| {
readonly type: "parameter.adjust";
readonly revision: number;
- readonly entityId: string;
+ readonly owner:
+ | { readonly kind: "item"; readonly itemId: string }
+ | { readonly kind: "track-object"; readonly trackId: string; readonly objectId: string };
readonly parameterId: string;
readonly value: CanonicalValue;
};
diff --git a/packages/studio/src/snapshot.ts b/packages/studio/src/snapshot.ts
index 3884ddcb..98803945 100644
--- a/packages/studio/src/snapshot.ts
+++ b/packages/studio/src/snapshot.ts
@@ -2,7 +2,7 @@ import { composeParameterDeclarations } from "./parameters.js";
/**
* Turn the resolved Studio projection into what the panels read.
*
- * The Timeline owns the work range. Companions project selectable entities onto
+ * The Timeline owns the work range. Companions project selectable Items onto
* that range without extending it or requiring component-specific editor code.
*/
import { relative } from "node:path";
@@ -10,25 +10,28 @@ import { relative } from "node:path";
import type { MarkupSurfaceRegistryLike } from "@hypit/hypit/markup";
import { compositionTypes } from "@hypit/hypit/composition";
import { timelineFrameCount } from "@hypit/hypit/timeline";
+import { temporalTypes } from "@hypit/hypit/temporal";
+import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
import { sameModule, sameType } from "@hypit/hypit/protocol";
import type {
CandidateProvenance,
- Clip,
+ StudioItem,
StudioSnapshot,
Range,
TemporalDomainView,
- Track,
+ StudioTrack,
} from "./shared.js";
import type { Placement } from "./observe.js";
import type { StudioProjection } from "./projection.js";
import {
- sealStudioClip,
+ sealStudioItem,
} from "./studio-registry.js";
import type { StudioCompanionRegistry } from "./studio-registry.js";
-import type { StudioEntityDraft } from "./studio-registry.js";
-import { inspectorFieldsForBindings, resolveTimelineEditHandles, sourceBindingsForDraft, temporalBindingDeclarations } from "./parameters.js";
+import type { StudioItemDraft } from "./studio-registry.js";
+import { inspectorFieldsForBindings, resolveTimelineEditHandles, sourceBindingsForDraft } from "./parameters.js";
import type { StudioSourceFile } from "./parameters.js";
+import { temporalAuthorBindings } from "./temporal-inverse.js";
type Present = {
readonly id: string;
@@ -108,13 +111,75 @@ function temporalDomains(
};
return built.source.observations.temporalDomains.flatMap((source) => {
const projected = registry.projectTemporalDomain({ source, values: built.temporalDomainValues, timeline: built.timeline });
- if (projected === undefined || projected.timelineId !== built.timeline.id) return [];
- return [{ ...projected, companion: source.companion,
+ return projected.filter((view) => view.timelineId === built.timeline.id).map((view) => ({ ...view, companion: source.companion,
presentation: registry.temporalDomainPresentation(source.companion), provenance,
- source: { path: source.sourcePath, content: source.content } }];
+ source: { path: source.sourcePath, content: source.content } }));
});
}
+/** All package-declared absolute author values share one read-only Timeline row. */
+function temporalDeclarationDomain(
+ registry: StudioCompanionRegistry,
+ built: StudioProjection,
+ source: { readonly path: string; readonly text: string },
+): TemporalDomainView {
+ const values = new Map(built.temporalValues.map((item) => [item.id, item] as const));
+ const declarations = built.source.observations.placements.flatMap((placement) =>
+ registry.projectTemporalDeclarations(placement).map((draft) => ({ placement, draft })));
+ const anchors: TemporalDomainView["anchors"][number][] = [];
+ const items: TemporalDomainView["items"][number][] = [];
+ const seen = new Set<string>();
+ for (const { placement, draft } of declarations) {
+ if (seen.has(draft.output)) continue;
+ const found = values.get(draft.output);
+ if (found === undefined) continue;
+ const range = placement.sourcePath === source.path ? draft.range : undefined;
+ if (sameType(found.type, temporalTypes.window)) {
+ const value = found.value as TemporalWindow;
+ if (value.start.timelineId !== built.timeline.id || value.end.timelineId !== built.timeline.id) continue;
+ const startAnchorId = `${draft.output}:start`;
+ const endAnchorId = `${draft.output}:end`;
+ anchors.push({ id: startAnchorId, kind: "window-start", frame: value.span.startFrame },
+ { id: endAnchorId, kind: "window-end", frame: value.span.endFrameExclusive });
+ items.push({ kind: "span", appearance: "block", id: draft.output, laneId: "declarations",
+ label: draft.label ?? draft.id, startAnchorId, endAnchorId,
+ startFrame: value.span.startFrame, endFrameExclusive: value.span.endFrameExclusive,
+ ...(range === undefined ? {} : { range }) });
+ seen.add(draft.output);
+ continue;
+ }
+ if (!sameType(found.type, temporalTypes.instant)) continue;
+ const value = found.value as TemporalInstant;
+ if (value.timelineId !== built.timeline.id) continue;
+ const anchorId = `${draft.output}:point`;
+ anchors.push({ id: anchorId, kind: "instant", frame: value.frame });
+ items.push({ kind: "point", appearance: "marker", id: draft.output, laneId: "declarations",
+ label: draft.label ?? draft.id, anchorId, frame: value.frame,
+ ...(range === undefined ? {} : { range }) });
+ seen.add(draft.output);
+ }
+ const provenance: CandidateProvenance = {
+ output: built.timingOutput?.name ?? "Timeline",
+ ...(built.timingOutput?.ref === undefined ? {} : { outputRef: built.timingOutput.ref }),
+ ...(built.timingCandidateId === undefined ? {} : { candidateId: built.timingCandidateId }),
+ origin: built.timingCandidateOrigin,
+ status: "resolved",
+ errors: [],
+ };
+ return {
+ id: "absolute-declarations",
+ companion: "studio#absolute-declarations",
+ timelineId: built.timeline.id,
+ presentation: { family: "temporal", tone: "teal", label: "Windows & Instants", icon: "timeline" },
+ lanes: [{ id: "declarations", label: "Windows & Instants", heightPx: 26 }],
+ anchors,
+ items,
+ editItems: [],
+ provenance,
+ source: { path: source.path, content: { start: 0, end: source.text.length } },
+ };
+}
+
export function snapshot(registry: StudioCompanionRegistry, built: StudioProjection, input: {
readonly revision: number;
readonly path: string;
@@ -128,8 +193,8 @@ export function snapshot(registry: StudioCompanionRegistry, built: StudioProject
readonly surfaces: MarkupSurfaceRegistryLike;
}): StudioSnapshot {
const located = authored(built.source.observations.placements);
- const domains = temporalDomains(registry, built);
- const tracks: Track[] = [];
+ const domains = [...temporalDomains(registry, built), temporalDeclarationDomain(registry, built, input)];
+ const tracks: StudioTrack[] = [];
for (const item of built.tracks) {
const projectedSpans = spans(item.value, input.frameRate);
const binding = registry.bindTrack(item);
@@ -138,7 +203,7 @@ export function snapshot(registry: StudioCompanionRegistry, built: StudioProject
candidate.id === item.trace.authoredId
&& sameModule(candidate.module, item.trace.module!)
&& candidate.surface === item.trace.surface);
- const generic = (): readonly StudioEntityDraft[] => projectedSpans.map((span) => {
+ const generic = (): readonly StudioItemDraft[] => projectedSpans.map((span) => {
const identity = span.subjectId ?? span.id;
const where = located.find((candidate) => candidate.id === identity);
return {
@@ -152,7 +217,7 @@ export function snapshot(registry: StudioCompanionRegistry, built: StudioProject
stackOrder: span.stackOrder,
};
});
- const drafts = registry.projectTrack({
+ const companionContext = {
track: item,
...(placement === undefined ? {} : { placement }),
...(item.surfacePreview === undefined ? {} : { surfacePreview: item.surfacePreview }),
@@ -161,23 +226,29 @@ export function snapshot(registry: StudioCompanionRegistry, built: StudioProject
temporalBindings: built.temporalBindings.get(item.outputRef) ?? [],
temporalDomains: domains,
generic,
- }).map((draft) => {
+ };
+ const drafts = registry.projectTrack(companionContext).map((draft) => {
const declarations = composeParameterDeclarations({
placement, draft, placements: built.source.observations.placements, registry,
- bindings: registry.bindingDeclarations(item, placement, draft.lane, draft.band),
- inspector: registry.inspectorDeclarations(item, placement, draft.lane, draft.band),
+ bindings: registry.bindingDeclarations(item, draft.lane),
+ inspector: registry.inspectorDeclarations(item, draft.lane),
});
- const bindings = sourceBindingsForDraft({
+ const ordinaryBindings = sourceBindingsForDraft({
root: input.workspaceRoot,
files: input.sourceFiles,
placement,
draft,
- declarations: [
- ...declarations.bindings,
- ...temporalBindingDeclarations(draft.temporal),
- ],
+ declarations: declarations.bindings,
placements: built.source.observations.placements,
});
+ const temporalBindings = draft.temporal === undefined ? [] : temporalAuthorBindings({
+ state: built.state,
+ rootRecord: draft.temporal.record,
+ workspaceRoot: input.workspaceRoot,
+ placements: built.source.observations.placements,
+ files: input.sourceFiles,
+ });
+ const bindings = [...ordinaryBindings, ...temporalBindings];
const inspector = inspectorFieldsForBindings(
draft,
bindings,
@@ -194,9 +265,34 @@ export function snapshot(registry: StudioCompanionRegistry, built: StudioProject
editHandles,
};
});
- const clips: Clip[] = drafts
+ const inspectorObjects = registry.projectInspectorObjects(companionContext).map(({ label, draft, bindings: declaredBindings, inspector: declaredInspector }) => {
+ const declarations = composeParameterDeclarations({
+ placement,
+ draft,
+ placements: built.source.observations.placements,
+ registry,
+ bindings: declaredBindings,
+ inspector: declaredInspector,
+ });
+ const bindings = sourceBindingsForDraft({
+ root: input.workspaceRoot,
+ files: input.sourceFiles,
+ placement,
+ draft,
+ declarations: declarations.bindings,
+ placements: built.source.observations.placements,
+ });
+ return {
+ id: draft.id.startsWith(`${item.outputRef}:`) ? draft.id : `${item.outputRef}:inspector:${draft.id}`,
+ group: label,
+ title: draft.title,
+ ...(draft.elementRange === undefined ? {} : { elementRange: draft.elementRange }),
+ inspector: inspectorFieldsForBindings(draft, bindings, declarations.inspector),
+ };
+ });
+ const items: StudioItem[] = drafts
.filter(({ draft }) => draft.lane === undefined)
- .map(({ draft, inspector, editHandles }) => sealStudioClip(item.outputRef, draft, binding, editHandles, inspector));
+ .map(({ draft, inspector, editHandles }) => sealStudioItem(item.outputRef, draft, binding, editHandles, inspector));
const provenance: CandidateProvenance = {
output: item.name,
outputRef: item.outputRef,
@@ -209,7 +305,8 @@ export function snapshot(registry: StudioCompanionRegistry, built: StudioProject
id: item.outputRef,
label: item.name,
row: 0,
- clips,
+ items,
+ inspectorObjects,
binding,
provenance,
});
@@ -220,8 +317,9 @@ export function snapshot(registry: StudioCompanionRegistry, built: StudioProject
id: `${item.outputRef}::studio::${attachment.attachmentId}`,
label: attachment.label ?? attachment.attachmentId ?? item.name,
row: 0,
- clips: attachedDrafts.map(({ draft, inspector, editHandles }) =>
- sealStudioClip(item.outputRef, draft, attachment, editHandles, inspector)),
+ items: attachedDrafts.map(({ draft, inspector, editHandles }) =>
+ sealStudioItem(item.outputRef, draft, attachment, editHandles, inspector)),
+ inspectorObjects: [],
binding: attachment,
provenance,
});
@@ -229,8 +327,8 @@ export function snapshot(registry: StudioCompanionRegistry, built: StudioProject
}
// Root lanes retain Film's authored organizational order. A Present's z is
// local compositing data and cannot define the order of a Track containing
- // independently stacked items. Studio-only detail lanes stay beside the
- // root that produced them in this list.
+ // independently stacked items. Companion-declared Attachment Tracks stay
+ // beside the root Track that produced them in this list.
const rows = tracks.map((track, row) => ({ ...track, row }));
const frameCount = timelineFrameCount(built.timeline);
diff --git a/packages/studio/src/studio-registry.ts b/packages/studio/src/studio-registry.ts
index 61647bf8..bfa82f3d 100644
--- a/packages/studio/src/studio-registry.ts
+++ b/packages/studio/src/studio-registry.ts
@@ -3,7 +3,8 @@ import type {
StudioParameterCompanion,
StudioTrackCompanionContext,
StudioEditHandle,
- StudioEntityDraft,
+ StudioItemDraft,
+ StudioInspectorObjectDraft,
StudioFilmCompanion,
StudioLaneAttachment,
StudioViewRole,
@@ -11,6 +12,9 @@ import type {
StudioTemporalDomainAdjustment,
StudioTemporalDomainProjectionInput,
StudioTemporalDomainCompanion,
+ StudioTemporalDeclarationCompanion,
+ StudioTemporalDeclarationDraft,
+ StudioTemporalRelationCompanion,
StudioTemporalDomainSourceMap,
StudioSourceBindingDeclaration,
StudioSpan,
@@ -19,12 +23,12 @@ import { studioParameterControls } from "@hypit/studio-companion";
import { parameterOption } from "./parameter-values.js";
import { compositionTypes } from "@hypit/hypit/composition";
import { sameModule, sameType } from "@hypit/hypit/protocol";
-import type { ModuleRef, TypeRef } from "@hypit/hypit/protocol";
+import type { ModuleRef, ProducerRef, TypeRef } from "@hypit/hypit/protocol";
import type { Placement } from "./observe.js";
-import type { Clip, StudioTrackBinding } from "./shared.js";
+import type { StudioItem, StudioTrackBinding } from "./shared.js";
-export type { StudioEntityDraft, StudioViewRole, StudioSpan } from "@hypit/studio-companion";
+export type { StudioItemDraft, StudioViewRole, StudioSpan } from "@hypit/studio-companion";
const flatLane = {
heightPx: 52,
@@ -101,16 +105,14 @@ function validateCompanionVocabulary(companion: StudioTrackCompanion): void {
throw new Error(`Studio Track Companion ${companion.id} selects unsupported icon ${companion.icon}`);
}
validateInspector(`Studio Track Companion ${companion.id}`, companion.bindings, companion.inspector);
- const bandIds = new Set<string>();
- for (const band of companion.bands ?? []) {
- if (!band.id.trim() || bandIds.has(band.id)) throw new Error(`Studio Companion ${companion.id} has a duplicate or empty band id`);
- bandIds.add(band.id);
- if (!Number.isFinite(band.heightPx) || band.heightPx <= 0
- || !["before", "after"].includes(band.placement) || !["label", "content"].includes(band.display)) {
- throw new Error(`Studio Companion ${companion.id} band ${band.id} has invalid layout`);
+ const inspectorObjectIds = new Set<string>();
+ for (const object of companion.inspectorObjects ?? []) {
+ if (!object.id.trim() || inspectorObjectIds.has(object.id)) {
+ throw new Error(`Studio Companion ${companion.id} has a duplicate or empty Inspector object id`);
}
- if (band.tone !== undefined && !tones.has(band.tone)) throw new Error(`Studio Companion ${companion.id} band ${band.id} has unsupported tone`);
- validateInspector(`Studio Companion ${companion.id} band ${band.id}`, band.bindings, band.inspector);
+ inspectorObjectIds.add(object.id);
+ if (!object.label.trim()) throw new Error(`Studio Companion ${companion.id} Inspector object ${object.id} has no label`);
+ validateInspector(`Studio Companion ${companion.id} Inspector object ${object.id}`, object.bindings, object.inspector);
}
for (const attachment of companion.attachments ?? []) {
if (attachment.tone !== undefined && !tones.has(attachment.tone)) {
@@ -123,40 +125,37 @@ function validateCompanionVocabulary(companion: StudioTrackCompanion): void {
}
}
-function validateDraftVocabulary(companion: StudioTrackCompanion, draft: StudioEntityDraft): void {
- if (draft.band !== undefined && (draft.lane !== undefined || !companion.bands?.some(band => band.id === draft.band))) {
- throw new Error(`Studio Companion ${companion.id} entity ${draft.id} must select one declared band within its own Track`);
- }
-
+function validateItemDraftVocabulary(companion: StudioTrackCompanion, draft: StudioItemDraft): void {
if (draft.display === undefined || typeof draft.display.title !== "string" || draft.display.title.trim().length === 0) {
- throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} has no display title`);
+ throw new Error(`Studio Track Companion ${companion.id} Item ${draft.id} has no display title`);
}
if (!Array.isArray(draft.display.layers)) {
- throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} has invalid display layers`);
+ throw new Error(`Studio Track Companion ${companion.id} Item ${draft.id} has invalid display layers`);
}
- if (draft.presentation !== undefined && !chromes.has(draft.presentation.chrome)) {
- throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} selects unsupported chrome ${draft.presentation.chrome}`);
+ if (draft.presentation !== undefined
+ && (!draft.presentation.kind.trim() || !chromes.has(draft.presentation.chrome))) {
+ throw new Error(`Studio Track Companion ${companion.id} Item ${draft.id} has invalid presentation`);
}
for (const [index, layer] of draft.display.layers.entries()) {
if (layer.kind === "text") {
if (layer.role !== "content" || typeof layer.text !== "string") {
- throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} has invalid text layer ${index}`);
+ throw new Error(`Studio Track Companion ${companion.id} Item ${draft.id} has invalid text layer ${index}`);
}
continue;
}
if (layer.kind !== "preview" || (layer.role !== "content" && layer.role !== "decoration")
|| !layouts.has(layer.layout)
|| !(["image", "video", "audio"] as const).includes(layer.preview.kind)) {
- throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} has invalid preview layer ${index}`);
+ throw new Error(`Studio Track Companion ${companion.id} Item ${draft.id} has invalid preview layer ${index}`);
}
const source = layer.preview.source;
if (source.kind === "artifact") {
if (typeof source.resource !== "string" || source.resource.length === 0) {
- throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} has invalid Artifact source`);
+ throw new Error(`Studio Track Companion ${companion.id} Item ${draft.id} has invalid Artifact source`);
}
} else if (source.kind !== "surface-preview"
|| source.module.length === 0 || source.version.length === 0 || source.surface.length === 0) {
- throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} has invalid Surface preview source`);
+ throw new Error(`Studio Track Companion ${companion.id} Item ${draft.id} has invalid Surface preview source`);
}
}
}
@@ -188,12 +187,16 @@ export class StudioCompanionRegistry {
readonly #tracks: readonly StudioTrackCompanion[];
readonly #films: readonly StudioFilmCompanion[];
readonly #temporalDomains: readonly StudioTemporalDomainCompanion[];
+ readonly #temporalDeclarations: readonly StudioTemporalDeclarationCompanion[];
+ readonly #temporalRelations: readonly StudioTemporalRelationCompanion[];
constructor(
tracks: readonly StudioTrackCompanion[],
options: {
readonly films?: readonly StudioFilmCompanion[];
readonly temporalDomains?: readonly StudioTemporalDomainCompanion[];
+ readonly temporalDeclarations?: readonly StudioTemporalDeclarationCompanion[];
+ readonly temporalRelations?: readonly StudioTemporalRelationCompanion[];
readonly parameters?: readonly StudioParameterCompanion[];
} = {},
) {
@@ -205,7 +208,10 @@ export class StudioCompanionRegistry {
}
const films = [...(options.films ?? [])];
const temporalDomains = [...(options.temporalDomains ?? [])];
- for (const [label, companions] of [["Film", films], ["Temporal Domain", temporalDomains]] as const) {
+ const temporalDeclarations = [...(options.temporalDeclarations ?? [])];
+ const temporalRelations = [...(options.temporalRelations ?? [])];
+ for (const [label, companions] of [["Film", films], ["Temporal Domain", temporalDomains],
+ ["Temporal Declaration", temporalDeclarations], ["Temporal Relation", temporalRelations]] as const) {
const companionIds = new Set<string>();
for (const companion of companions) {
if (companionIds.has(companion.id) || ids.has(companion.id)) {
@@ -224,6 +230,19 @@ export class StudioCompanionRegistry {
this.#tracks = Object.freeze([...tracks]);
this.#films = Object.freeze(films);
this.#temporalDomains = Object.freeze(temporalDomains);
+ this.#temporalDeclarations = Object.freeze(temporalDeclarations);
+ this.#temporalRelations = Object.freeze(temporalRelations);
+ }
+
+ temporalRelationFor(producer: ProducerRef, output: string): StudioTemporalRelationCompanion | undefined {
+ const found = this.#temporalRelations.filter((companion) =>
+ sameModule(companion.match.producer.module, producer.module)
+ && companion.match.producer.name === producer.name
+ && companion.match.output === output);
+ if (found.length > 1) {
+ throw new Error(`Studio Temporal Relation companions are ambiguous for ${producer.module.name}@${producer.module.version}#${producer.name}.${output}.`);
+ }
+ return found[0];
}
parameterCompanionFor(module: ModuleRef, surface: string): StudioParameterCompanion | undefined {
@@ -270,6 +289,15 @@ export class StudioCompanionRegistry {
return companion.project(input);
}
+ projectTemporalDeclarations(placement: Placement): readonly StudioTemporalDeclarationDraft[] {
+ const found = this.#temporalDeclarations.filter((companion) =>
+ sameModule(companion.match.module, placement.module) && companion.match.surface === placement.surface);
+ if (found.length > 1) {
+ throw new Error(`Studio Temporal Declaration companions are ambiguous for ${placement.module.name}@${placement.module.version}#${placement.surface}.`);
+ }
+ return found[0]?.project({ placement }) ?? [];
+ }
+
adjustTemporalDomain(input: {
readonly companion: string;
readonly sourceName: string;
@@ -383,22 +411,21 @@ export class StudioCompanionRegistry {
icon: companion.icon ?? (sameType(track.typeRef, compositionTypes.audioTrack) ? "waveform" : "layers"),
companion: companion.id,
lane: companion.lane ?? flatLane,
- ...(companion.bands === undefined ? {} : { bands: companion.bands.map(({ bindings: _bindings, inspector: _inspector, ...band }) => band) }),
...(track.trace.placement === undefined ? {} : { authoredTag: track.trace.placement }),
references: track.trace.references.map(({ name, type }) => ({ name, type })),
};
}
- projectTrack(input: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+ projectTrack(input: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const companion = this.#trackCompanion(input.track);
const drafts = companion.project?.(input) ?? input.generic();
const preview = input.surfacePreview;
- const surfaceLayer: StudioEntityDraft["display"]["layers"][number] | undefined = preview === undefined
+ const surfaceLayer: StudioItemDraft["display"]["layers"][number] | undefined = preview === undefined
? undefined
: { kind: "preview", role: "decoration", preview, layout: "repeat-x" };
- const projected: readonly StudioEntityDraft[] = companion.poster?.source !== "surface-preview" || surfaceLayer === undefined
+ const projected: readonly StudioItemDraft[] = companion.poster?.source !== "surface-preview" || surfaceLayer === undefined
? drafts
- : drafts.map((draft) => draft.lane !== undefined || draft.band !== undefined
+ : drafts.map((draft) => draft.lane !== undefined
? draft
: {
...draft,
@@ -407,18 +434,39 @@ export class StudioCompanionRegistry {
layers: [surfaceLayer, ...draft.display.layers],
},
});
- for (const draft of projected) validateDraftVocabulary(companion, draft);
+ for (const draft of projected) validateItemDraftVocabulary(companion, draft);
return projected;
}
+ projectInspectorObjects(input: StudioTrackCompanionContext): readonly {
+ readonly companionId: string;
+ readonly label: string;
+ readonly draft: StudioInspectorObjectDraft;
+ readonly bindings: readonly StudioSourceBindingDeclaration[];
+ readonly inspector: NonNullable<StudioTrackCompanion["inspector"]>;
+ }[] {
+ const companion = this.#trackCompanion(input.track);
+ const result = (companion.inspectorObjects ?? []).flatMap((object) => object.project(input).map((draft) => ({
+ companionId: object.id,
+ label: object.label,
+ draft,
+ bindings: object.bindings ?? [],
+ inspector: object.inspector ?? [],
+ })));
+ const ids = new Set<string>();
+ for (const { draft } of result) {
+ if (!draft.id.trim() || ids.has(draft.id)) throw new Error(`Studio Companion ${companion.id} repeats Inspector object ${draft.id}`);
+ if (!draft.authoredId.trim() || !draft.title.trim()) throw new Error(`Studio Companion ${companion.id} Inspector object ${draft.id} is incomplete`);
+ ids.add(draft.id);
+ }
+ return result;
+ }
+
bindingDeclarations(
track: StudioResolvedTrack,
- placement: Placement | undefined,
lane?: string,
- band?: string,
) {
const companion = this.#trackCompanion(track);
- if (band !== undefined) return companion.bands?.find(item => item.id === band)?.bindings ?? [];
if (lane !== undefined) {
return companion.attachments?.find((attachment) => attachment.id === lane)?.bindings ?? [];
}
@@ -427,12 +475,9 @@ export class StudioCompanionRegistry {
inspectorDeclarations(
track: StudioResolvedTrack,
- placement: Placement | undefined,
lane?: string,
- band?: string,
) {
const companion = this.#trackCompanion(track);
- if (band !== undefined) return companion.bands?.find(item => item.id === band)?.inspector ?? [];
if (lane !== undefined) {
return companion.attachments?.find((attachment) => attachment.id === lane)?.inspector ?? [];
}
@@ -441,18 +486,17 @@ export class StudioCompanionRegistry {
}
-export function sealStudioClip(
+export function sealStudioItem(
outputRef: string,
- draft: StudioEntityDraft,
+ draft: StudioItemDraft,
fallback: StudioTrackBinding,
editHandles: readonly StudioEditHandle[] = [],
- inspector: Clip["inspector"] = [],
-): Clip {
+ inspector: StudioItem["inspector"] = [],
+): StudioItem {
return {
id: draft.id.startsWith(`${outputRef}:`) ? draft.id : `${outputRef}:${draft.id}`,
...(draft.presentId === undefined ? {} : { presentId: draft.presentId }),
authoredId: draft.authoredId,
- ...(draft.band === undefined ? {} : { band: draft.band }),
...(draft.selectionGroup === undefined ? {} : { selectionGroup: draft.selectionGroup }),
...(draft.markerId === undefined ? {} : { markerId: draft.markerId }),
display: draft.display,
@@ -461,7 +505,7 @@ export function sealStudioClip(
...(draft.elementRange === undefined ? {} : { elementRange: draft.elementRange }),
stackOrder: draft.stackOrder,
presentation: draft.presentation ?? {
- entity: fallback.facet === "audio" ? "audio-clip" : "present",
+ kind: fallback.facet === "audio" ? "audio-clip" : "present",
chrome: "standard",
},
...(draft.temporal === undefined ? {} : { temporal: draft.temporal }),
diff --git a/packages/studio/src/style.css b/packages/studio/src/style.css
index fa27ce23..42767cb2 100644
--- a/packages/studio/src/style.css
+++ b/packages/studio/src/style.css
@@ -769,6 +769,22 @@ button:focus-visible, textarea:focus-visible {
.property-code > strong { font: 11px/18px var(--font-mono); }
.property-number > strong { font-family: var(--font-mono); font-variant-numeric: tabular-nums; }
.parameter-group .property-grid { display: flex; flex-direction: column; gap: 7px; }
+.inspector-object-group > .property-grid { display: flex; flex-direction: column; gap: 7px; }
+.inspector-object {
+ min-width: 0;
+ border: 1px solid light-dark(#e5e2dd, #2b2e34);
+ border-radius: 4px;
+ background: light-dark(#faf9f7, #191a1e);
+}
+.inspector-object > summary {
+ padding: 8px 10px;
+ color: var(--text-2);
+ font-size: 11px;
+ font-weight: 500;
+ cursor: pointer;
+}
+.inspector-object-fields { border-top: 1px solid var(--line); }
+.inspector-object-fields > .property-group:last-child { border-bottom: 0; }
.parameter-row {
min-width: 0;
min-height: 30px;
@@ -1171,7 +1187,7 @@ button:focus-visible, textarea:focus-visible {
.tick-last { padding-right: 4px; padding-left: 0; border-right: 1px solid light-dark(#c4c0b9, #45484e); border-left: 0; transform: translateX(-100%); }
.lanes { min-height: 0; cursor: default; }
.lane { position: relative; isolation: isolate; min-height: 0; overflow: hidden; border-bottom: 1px solid light-dark(#ebe8e4, #191b1f); background: var(--lane); }
-.temporal-domain-lane { position: sticky; top: var(--timeline-ruler-height); z-index: 8; min-height: 0; border-bottom: 1px solid var(--line); background: var(--lane); }
+.temporal-domain-lane { position: relative; min-height: 0; border-bottom: 1px solid var(--line); background: var(--lane); }
.temporal-domain-band {
position: absolute;
right: 0;
@@ -1280,7 +1296,7 @@ button:focus-visible, textarea:focus-visible {
background: var(--temporal-domain-point);
}
.temporal-domain-point:focus-visible { outline: 0; }
-.track-label-temporal-domain { position: sticky; top: 0; z-index: 8; border-bottom: 1px solid var(--line); background: light-dark(#faf9f7, #111216); }
+.track-label-temporal-domain { position: relative; border-bottom: 1px solid var(--line); background: light-dark(#faf9f7, #111216); }
.track-label-temporal-domain::before { display: none; }
.track-label-attached {
/* The branch marker occupies the same 18px prefix as a root icon;
@@ -1289,7 +1305,7 @@ button:focus-visible, textarea:focus-visible {
background: transparent;
}
.track-label-attached::before { inset: var(--timeline-item-inset-y) 6px; background: light-dark(#f0eeea, #181a1f); }
-.clip {
+.studio-item {
z-index: 0;
--track: var(--visual);
--item-head: color-mix(in srgb, var(--track) 58%, var(--lane));
@@ -1313,13 +1329,13 @@ button:focus-visible, textarea:focus-visible {
cursor: default;
}
/* On light surfaces an item is a tint of its track hue; its text is a deep shade of the same hue. */
-:root[data-theme="light"] .clip {
+:root[data-theme="light"] .studio-item {
--item-head: color-mix(in srgb, var(--track) 42%, #fff);
--item-body: color-mix(in srgb, var(--track) 20%, #fff);
}
/* Only Companion-declared editable intervals enable edge gestures. */
-#app .clip::before,
-#app .clip::after {
+#app .studio-item::before,
+#app .studio-item::after {
content: "";
position: absolute;
z-index: 8;
@@ -1330,23 +1346,23 @@ button:focus-visible, textarea:focus-visible {
background: transparent;
cursor: default !important;
}
-#app .clip::before { left: 0; }
-#app .clip::after { right: 0; }
-#app .clip-editable::before,
-#app .clip-editable::after {
+#app .studio-item::before { left: 0; }
+#app .studio-item::after { right: 0; }
+#app .studio-item-editable::before,
+#app .studio-item-editable::after {
pointer-events: auto;
cursor: ew-resize !important;
}
-.clip.selected {
+.studio-item.selected {
z-index: 1;
overflow: visible;
box-shadow: none;
color: var(--item-ink);
}
-.clip.editing { box-shadow: 0 0 0 1px var(--item-ink); }
-.clip:focus-visible { outline: 0; }
+.studio-item.editing { box-shadow: 0 0 0 1px var(--item-ink); }
+.studio-item:focus-visible { outline: 0; }
/* Draw above thumbnails and text without changing interval geometry. */
-.clip-boundary {
+.studio-item-boundary {
position: absolute;
z-index: 5;
inset: 0;
@@ -1354,7 +1370,7 @@ button:focus-visible, textarea:focus-visible {
border-radius: inherit;
pointer-events: none;
}
-.clip-selection {
+.studio-item-selection {
position: absolute;
z-index: 6;
inset: 0;
@@ -1363,7 +1379,7 @@ button:focus-visible, textarea:focus-visible {
border-radius: var(--timeline-selection-radius);
pointer-events: none;
}
-.clip-selection::before, .clip-selection::after {
+.studio-item-selection::before, .studio-item-selection::after {
content: "";
position: absolute;
top: 0;
@@ -1371,17 +1387,17 @@ button:focus-visible, textarea:focus-visible {
width: var(--timeline-selection-edge);
background: var(--timeline-selection-color);
}
-.clip-selection::before {
+.studio-item-selection::before {
left: 0;
border-radius: var(--timeline-selection-radius) 0 0 var(--timeline-selection-radius);
}
-.clip-selection::after {
+.studio-item-selection::after {
right: 0;
border-radius: 0 var(--timeline-selection-radius) var(--timeline-selection-radius) 0;
}
-.clip.selected > .clip-selection { display: block; }
-.clip.selected > .clip-boundary { border-color: var(--timeline-selection-color); }
-.clip-head {
+.studio-item.selected > .studio-item-selection { display: block; }
+.studio-item.selected > .studio-item-boundary { border-color: var(--timeline-selection-color); }
+.studio-item-head {
position: absolute;
z-index: 3;
top: 0;
@@ -1397,7 +1413,7 @@ button:focus-visible, textarea:focus-visible {
background: var(--item-head);
border-radius: var(--timeline-item-radius) var(--timeline-item-radius) 0 0;
}
-.clip-body {
+.studio-item-body {
position: absolute;
z-index: 1;
top: var(--timeline-item-header-height);
@@ -1408,36 +1424,36 @@ button:focus-visible, textarea:focus-visible {
background: var(--item-body);
border-radius: 0 0 var(--timeline-item-radius) var(--timeline-item-radius);
}
-.clip-layers { position: absolute; inset: 0; overflow: hidden; pointer-events: none; }
-.clip-layer { position: absolute; inset: 0; display: block; overflow: hidden; pointer-events: none; }
-.clip-material-image, .clip-material-video {
+.studio-item-layers { position: absolute; inset: 0; overflow: hidden; pointer-events: none; }
+.studio-item-layer { position: absolute; inset: 0; display: block; overflow: hidden; pointer-events: none; }
+.studio-item-material-image, .studio-item-material-video {
background-position: left center;
background-size: auto 100%;
opacity: 1;
}
-.clip-layer-layout-repeat-x { background-repeat: repeat-x; background-position: left center; background-size: auto 100%; }
-.clip-layer-layout-cover { background-repeat: no-repeat; background-position: center; background-size: cover; }
-.clip-layer-layout-contain { background-repeat: no-repeat; background-position: left center; background-size: contain; }
-.clip-material-video { background: none; }
-.clip-video-frame {
+.studio-item-layer-layout-repeat-x { background-repeat: repeat-x; background-position: left center; background-size: auto 100%; }
+.studio-item-layer-layout-cover { background-repeat: no-repeat; background-position: center; background-size: cover; }
+.studio-item-layer-layout-contain { background-repeat: no-repeat; background-position: left center; background-size: contain; }
+.studio-item-material-video { background: none; }
+.studio-item-video-frame {
position: absolute;
top: 0;
bottom: 0;
background-repeat: no-repeat;
}
-.clip-layer-layout-waveform {
+.studio-item-layer-layout-waveform {
inset: 2px 5px;
background-repeat: no-repeat;
background-position: center;
background-size: 100% 100%;
opacity: .9;
}
-.clip-material-audio { background-image: var(--waveform); }
-:root[data-theme="light"] .clip-material-audio {
+.studio-item-material-audio { background-image: var(--waveform); }
+:root[data-theme="light"] .studio-item-material-audio {
background: color-mix(in srgb, var(--track) 70%, #000);
mask: var(--waveform) center / 100% 100% no-repeat;
}
-.clip-layer-text {
+.studio-item-layer-text {
display: flex;
height: 100%;
align-items: center;
@@ -1450,34 +1466,34 @@ button:focus-visible, textarea:focus-visible {
text-overflow: clip;
white-space: nowrap;
}
-.clip-phase { position: absolute; bottom: 0; height: 3px; border-left: 1px solid light-dark(rgba(0, 0, 0, .14), rgba(255, 255, 255, .17)); }
-.clip-phase-active, .clip-phase-enter, .clip-phase-exit { background: light-dark(rgba(0, 0, 0, .2), rgba(255, 255, 255, .24)); }
-.clip-phase-settled, .clip-phase-body { background: light-dark(rgba(0, 0, 0, .08), rgba(255, 255, 255, .10)); }
-.clip-phase-preferred { border-top: 1px dashed light-dark(rgba(0, 0, 0, .4), rgba(255, 255, 255, .48)); background: transparent; }
-.clip-name, .clip-meta { display: block; flex: 0 0 auto; white-space: nowrap; }
-.clip-name { color: light-dark(var(--item-ink), #eef0f3); font-size: 11px; font-weight: 500; }
-.clip-meta {
+.studio-item-phase { position: absolute; bottom: 0; height: 3px; border-left: 1px solid light-dark(rgba(0, 0, 0, .14), rgba(255, 255, 255, .17)); }
+.studio-item-phase-active, .studio-item-phase-enter, .studio-item-phase-exit { background: light-dark(rgba(0, 0, 0, .2), rgba(255, 255, 255, .24)); }
+.studio-item-phase-settled, .studio-item-phase-body { background: light-dark(rgba(0, 0, 0, .08), rgba(255, 255, 255, .10)); }
+.studio-item-phase-preferred { border-top: 1px dashed light-dark(rgba(0, 0, 0, .4), rgba(255, 255, 255, .48)); background: transparent; }
+.studio-item-name, .studio-item-meta { display: block; flex: 0 0 auto; white-space: nowrap; }
+.studio-item-name { color: light-dark(var(--item-ink), #eef0f3); font-size: 11px; font-weight: 500; }
+.studio-item-meta {
color: light-dark(color-mix(in srgb, var(--item-ink) 72%, transparent), rgba(255, 255, 255, .75));
font: 500 11px/1 var(--font-mono);
font-variant-numeric: tabular-nums;
}
-.clip-tone-blue { --track: var(--tone-blue); }
-.clip-tone-blue-muted { --track: var(--tone-blue-muted); }
-.clip-tone-green { --track: var(--tone-green); }
-.clip-tone-green-muted { --track: var(--tone-green-muted); }
-.clip-tone-teal { --track: var(--tone-teal); }
-.clip-tone-violet { --track: var(--tone-violet); }
-.clip-tone-magenta { --track: var(--tone-magenta); }
-.clip-tone-magenta-muted { --track: var(--tone-magenta-muted); }
-.clip-tone-orange { --track: var(--tone-orange); }
-.clip-tone-orange-muted { --track: var(--tone-orange-muted); }
-.clip-tone-neutral { --track: var(--tone-neutral); }
-.clip-chrome-group {
+.studio-item-tone-blue { --track: var(--tone-blue); }
+.studio-item-tone-blue-muted { --track: var(--tone-blue-muted); }
+.studio-item-tone-green { --track: var(--tone-green); }
+.studio-item-tone-green-muted { --track: var(--tone-green-muted); }
+.studio-item-tone-teal { --track: var(--tone-teal); }
+.studio-item-tone-violet { --track: var(--tone-violet); }
+.studio-item-tone-magenta { --track: var(--tone-magenta); }
+.studio-item-tone-magenta-muted { --track: var(--tone-magenta-muted); }
+.studio-item-tone-orange { --track: var(--tone-orange); }
+.studio-item-tone-orange-muted { --track: var(--tone-orange-muted); }
+.studio-item-tone-neutral { --track: var(--tone-neutral); }
+.studio-item-chrome-group {
border: 0;
background: var(--item-body);
box-shadow: none;
}
-.clip-chrome-group > .clip-body { background: var(--item-body); }
+.studio-item-chrome-group > .studio-item-body { background: var(--item-body); }
.timeline-hover {
position: absolute;
top: 0;
@@ -1682,36 +1698,12 @@ button:focus-visible, textarea:focus-visible {
.selection-menu button:focus-visible { background: var(--field); outline: none; }
/* Compact authored rules keep interval geometry without a thumbnail body. */
-.clip-chrome-compact > .clip-head {
+.studio-item-chrome-compact > .studio-item-head {
height: 100%;
border-bottom: 0;
border-radius: var(--timeline-item-radius);
background: var(--item-head);
}
-.clip-chrome-compact > .clip-body,
-.clip-chrome-compact .clip-meta { display: none; }
-.clip-chrome-compact .clip-name { font-size: 11px; font-weight: 500; }
-
-/* Track-internal bands share one label and meet without child-track gutters. */
-.timeline-track-banded { padding: var(--timeline-item-inset-y) 0; }
-.timeline-track-banded > .track-band { border-bottom: 0; }
-.timeline-track-banded > .track-band > .clip {
- height: 100%;
- margin-top: 0;
- border-radius: 0;
-}
-.timeline-track-banded > .track-band:first-child > .clip {
- border-top-left-radius: var(--timeline-item-radius);
- border-top-right-radius: var(--timeline-item-radius);
-}
-.timeline-track-banded > .track-band:last-child > .clip {
- border-bottom-left-radius: var(--timeline-item-radius);
- border-bottom-right-radius: var(--timeline-item-radius);
-}
-.track-band .clip-head, .track-band .clip-body { border-radius: inherit; }
-.track-band-label .clip-head {
- height: 100%;
- border-bottom: 0;
- background: var(--item-head);
-}
-.track-band-label .clip-body, .track-band-label .clip-meta { display: none; }
+.studio-item-chrome-compact > .studio-item-body,
+.studio-item-chrome-compact .studio-item-meta { display: none; }
+.studio-item-chrome-compact .studio-item-name { font-size: 11px; font-weight: 500; }
diff --git a/packages/studio/src/temporal-edit.ts b/packages/studio/src/temporal-edit.ts
index 4a14a252..e5012815 100644
--- a/packages/studio/src/temporal-edit.ts
+++ b/packages/studio/src/temporal-edit.ts
@@ -20,13 +20,19 @@ export function domainGestureSpan(
const next = byId.get(target.anchorId);
if (!previous || !next) return undefined;
const delta = next.frame - previous.frame;
- span = temporal.kind === "instant"
- ? { startFrame: temporal.frame + delta, endFrameExclusive: temporal.frame + delta + 1 }
- : { startFrame: temporal.startFrame + delta, endFrameExclusive: temporal.endFrameExclusive + delta };
+ if (temporal.kind === "instant") {
+ span = { startFrame: temporal.frame + delta, endFrameExclusive: temporal.frame + delta + 1 };
+ } else if (handle.gesture === "trim-start") {
+ span = { startFrame: temporal.startFrame + delta, endFrameExclusive: temporal.endFrameExclusive };
+ } else if (handle.gesture === "trim-end") {
+ span = { startFrame: temporal.startFrame, endFrameExclusive: temporal.endFrameExclusive + delta };
+ } else {
+ span = { startFrame: temporal.startFrame + delta, endFrameExclusive: temporal.endFrameExclusive + delta };
+ }
} else if (domain.kind === "span" && target.kind === "span") {
const start = byId.get(target.startAnchorId);
const end = byId.get(target.endAnchorId);
- if (!start || !end || start.order > end.order) return undefined;
+ if (!start || !end) return undefined;
if (temporal.kind === "instant") {
if (temporal.authority.kind !== "domain") return undefined;
if (temporal.authority.boundary === "start" && target.endAnchorId !== domain.endAnchorId
@@ -37,12 +43,10 @@ export function domainGestureSpan(
if (handle.gesture === "trim-start" && target.endAnchorId !== domain.endAnchorId
|| handle.gesture === "trim-end" && target.startAnchorId !== domain.startAnchorId) return undefined;
if (handle.gesture === "move") {
- const stops = [...new Set(anchors.map((anchor) => anchor.frame))].sort((a, b) => a - b);
const previousStart = byId.get(domain.startAnchorId);
const previousEnd = byId.get(domain.endAnchorId);
if (!previousStart || !previousEnd
- || stops.indexOf(start.frame) - stops.indexOf(previousStart.frame)
- !== stops.indexOf(end.frame) - stops.indexOf(previousEnd.frame)) return undefined;
+ || start.frame - previousStart.frame !== end.frame - previousEnd.frame) return undefined;
}
span = { startFrame: start.frame, endFrameExclusive: end.frame };
}
@@ -76,6 +80,10 @@ export function chooseDomainGesture(input: {
Number(a.id !== preferred.id) - Number(b.id !== preferred.id)
|| Number(a.kind !== preferred.kind) - Number(b.kind !== preferred.kind)
|| order.get(a.id)! - order.get(b.id)!);
+ const identified = (choices: readonly StudioTemporalDomainAnchor[], preferred: StudioTemporalDomainAnchor) => {
+ const current = choices.find((candidate) => candidate.id === preferred.id);
+ return current === undefined ? [...choices] : [current];
+ };
const valid = (target: DomainTarget) => {
const span = domainGestureSpan(anchors, handle, target);
return span !== undefined && (temporal.kind === "instant" ? span.startFrame : span.endFrameExclusive) <= input.frameCount;
@@ -84,10 +92,16 @@ export function chooseDomainGesture(input: {
if (domain.kind === "point") {
const current = byId.get(domain.anchorId);
if (!current) return undefined;
- const candidates = ranked(anchors, current).sort((a, b) =>
- Math.abs(a.frame - current.frame - delta) - Math.abs(b.frame - current.frame - delta));
- return candidates.map((anchor): DomainTarget => ({ kind: "point", companion: domain.companion,
- domainId: domain.domainId, itemId: domain.itemId, anchorId: anchor.id })).find(valid);
+ const frames = stops.sort((a, b) => Math.abs(a - current.frame - delta) - Math.abs(b - current.frame - delta));
+ for (const frame of frames) {
+ const candidates = identified(ranked(at.get(frame)!, current), current)
+ .map((anchor): DomainTarget => ({ kind: "point", companion: domain.companion,
+ domainId: domain.domainId, itemId: domain.itemId, anchorId: anchor.id }))
+ .filter(valid);
+ if (candidates.length > 1) return undefined;
+ if (candidates.length === 1) return candidates[0];
+ }
+ return undefined;
}
const start = byId.get(domain.startAnchorId);
const end = byId.get(domain.endAnchorId);
@@ -97,28 +111,31 @@ export function chooseDomainGesture(input: {
startAnchorId: a.id, endAnchorId: b.id,
});
if (handle.gesture === "move" && temporal.kind === "window") {
- const first = stops.indexOf(start.frame);
- const last = stops.indexOf(end.frame);
- const shifts = stops.map((_, index) => index - first)
- .filter((shift) => last + shift >= 0 && last + shift < stops.length)
- .sort((a, b) => Math.abs(stops[first + a]! - start.frame - delta)
- - Math.abs(stops[first + b]! - start.frame - delta) || Math.abs(a) - Math.abs(b));
+ const available = new Set(stops);
+ const shifts = stops.map((frame) => frame - start.frame)
+ .filter((shift) => available.has(end.frame + shift))
+ .sort((a, b) => Math.abs(a - delta) - Math.abs(b - delta) || Math.abs(a) - Math.abs(b));
for (const shift of shifts) {
- for (const a of ranked(at.get(stops[first + shift]!)!, start)) {
- for (const b of ranked(at.get(stops[last + shift]!)!, end)) {
- const candidate = target(a, b);
- if (valid(candidate)) return candidate;
- }
- }
+ const starts = identified(ranked(at.get(start.frame + shift)!, start), start);
+ const ends = identified(ranked(at.get(end.frame + shift)!, end), end);
+ if (starts.length * ends.length > 1) return undefined;
+ const a = starts[0], b = ends[0];
+ if (a !== undefined && b !== undefined && valid(target(a, b))) return target(a, b);
}
return undefined;
}
const boundary = temporal.kind === "instant" && temporal.authority.kind === "domain"
? temporal.authority.boundary : handle.gesture === "trim-start" ? "start" : "end";
const current = boundary === "start" ? start : end;
- const candidates = ranked(anchors, current).sort((a, b) =>
- Math.abs(a.frame - current.frame - delta) - Math.abs(b.frame - current.frame - delta));
- return candidates.map((anchor) => boundary === "start" ? target(anchor, end) : target(start, anchor)).find(valid);
+ const frames = stops.sort((a, b) => Math.abs(a - current.frame - delta) - Math.abs(b - current.frame - delta));
+ for (const frame of frames) {
+ const candidates = identified(ranked(at.get(frame)!, current), current)
+ .map((anchor) => boundary === "start" ? target(anchor, end) : target(start, anchor))
+ .filter(valid);
+ if (candidates.length > 1) return undefined;
+ if (candidates.length === 1) return candidates[0];
+ }
+ return undefined;
}
diff --git a/packages/studio/src/temporal-graph.ts b/packages/studio/src/temporal-graph.ts
index 90420fac..9be7b868 100644
--- a/packages/studio/src/temporal-graph.ts
+++ b/packages/studio/src/temporal-graph.ts
@@ -1,210 +1,141 @@
import { sameType } from "@hypit/hypit/protocol";
-import type { BuildState, ProducerStep, StoredValue, TypeRef, TypedRecord } from "@hypit/hypit/protocol";
-import { temporalModuleRef, temporalTypes } from "@hypit/hypit/temporal";
+import type { BuildState, ProducerRef, ProducerStep, StoredValue, TypeRef, TypedRecord } from "@hypit/hypit/protocol";
+import { temporalTypes } from "@hypit/hypit/temporal";
import type {
StudioTemporalBinding,
StudioTemporalInstantProjection,
StudioTemporalProjection,
+ StudioTemporalRelationCompanion,
+ StudioTemporalRelationTrace,
+ StudioTemporalRelationValue,
} from "@hypit/studio-companion";
-type PointExpression = {
- readonly ref?: string;
- readonly offset?: unknown;
- readonly at?: unknown;
-};
-
-type IdentifyTemporalSource = (type: TypeRef, value: unknown) => {
+export type IdentifyTemporalSource = (type: TypeRef, value: unknown) => {
readonly companion: string;
readonly id: string;
readonly kind: string;
readonly itemId: string;
} | undefined;
+export type FindTemporalRelation = (
+ producer: ProducerRef,
+ output: string,
+) => StudioTemporalRelationCompanion | undefined;
+
function inline(value: StoredValue): unknown | undefined {
return value.kind === "inline" ? value.value : undefined;
}
-function duration(value: unknown): string {
- const item = value as {
- readonly unit?: string;
- readonly value?: number;
- readonly numerator?: number;
- readonly denominator?: number;
- } | undefined;
- if (item?.unit === "frames") return `${item.value ?? 0}f`;
- if (item?.unit === "milliseconds") return `${item.value ?? 0}ms`;
- if (item?.unit === "seconds") return item.denominator === 1
- ? `${item.numerator ?? 0}s`
- : `${item.numerator ?? 0}/${item.denominator ?? 1}s`;
- return "?";
+function recordIndex(state: BuildState): ReadonlyMap<string, TypedRecord> {
+ return new Map([...state.program.records, ...state.records].map((record) => [record.id, record] as const));
}
-function signed(value: unknown): string {
- const item = value as { readonly unit?: string; readonly value?: number; readonly numerator?: number } | undefined;
- if (item === undefined) return "+?";
- const negative = item.unit === "seconds" ? (item.numerator ?? 0) < 0 : (item.value ?? 0) < 0;
- if (!negative) return `+${duration(value)}`;
- return item.unit === "seconds"
- ? `-${duration({ ...item, numerator: Math.abs(item.numerator ?? 0) })}`
- : `-${duration({ ...item, value: Math.abs(item.value ?? 0) })}`;
+function producingSteps(state: BuildState): ReadonlyMap<string, ProducerStep> {
+ return new Map(state.plan.steps.flatMap((step) =>
+ Object.values(step.outputs).map((record) => [record, step] as const)));
}
-function expression(value: unknown): string {
- const point = value as PointExpression;
- if (point.ref === "absolute") return `${duration(point.at)}${point.offset === undefined ? "" : signed(point.offset)}`;
- if (typeof point.ref !== "string") return "?";
- return point.offset === undefined ? point.ref : `${point.ref}${signed(point.offset)}`;
+function relationValue(records: ReadonlyMap<string, TypedRecord>, id: string): StudioTemporalRelationValue | undefined {
+ const found = records.get(id);
+ return found === undefined ? undefined : { record: id, type: found.type, value: inline(found.value) };
}
-function instant(
- record: TypedRecord | undefined,
- records: ReadonlyMap<string, TypedRecord>,
- producers: ReadonlyMap<string, ProducerStep>,
- identify?: IdentifyTemporalSource,
- fallback?: unknown,
-): StudioTemporalInstantProjection | undefined {
- const value = record === undefined ? fallback : inline(record.value);
- const held = value as {
+function fixedInstant(record: TypedRecord): StudioTemporalInstantProjection | undefined {
+ const held = inline(record.value) as {
readonly id?: unknown;
readonly timelineId?: unknown;
readonly frame?: unknown;
} | undefined;
- if (typeof held?.id !== "string" || typeof held.timelineId !== "string" || !Number.isSafeInteger(held.frame)) return undefined;
- const step = record === undefined ? undefined : producers.get(record.id);
- const specRecord = step?.inputs.spec === undefined ? undefined : records.get(step.inputs.spec);
- const spec = specRecord === undefined ? undefined : inline(specRecord.value) as {
- readonly projection?: PointExpression;
- readonly reference?: unknown;
- readonly boundary?: unknown;
- readonly offset?: unknown;
- readonly author?: { readonly binding?: unknown; readonly relation?: unknown };
- } | undefined;
- const parameterAuthority = spec?.author !== undefined
- && typeof spec.author.binding === "string"
- && ["direct", "after-start", "before-end"].includes(String(spec.author.relation))
- ? { kind: "parameter" as const, binding: spec.author.binding,
- relation: spec.author.relation as "direct" | "after-start" | "before-end" }
- : undefined;
- if (step?.producer.module.name === temporalModuleRef.name
- && step.producer.module.version === temporalModuleRef.version
- && step.producer.name === "project-program-instant"
- && spec?.projection !== undefined) {
- const timelineRecord = step.inputs.timeline === undefined ? undefined : records.get(step.inputs.timeline);
- const timeline = timelineRecord === undefined ? undefined : inline(timelineRecord.value) as { readonly id?: unknown } | undefined;
- const reference = spec.projection.ref;
- if (typeof reference !== "string") return undefined;
- return {
- kind: "instant",
- expression: expression(spec.projection),
- reference,
- frame: held.frame as number,
- source: { timelineId: held.timelineId, type: timelineRecord?.type ?? record!.type,
- kind: "timeline", id: typeof timeline?.id === "string" ? timeline.id : held.timelineId },
- authority: parameterAuthority ?? { kind: "fixed" },
- };
- }
- if (step?.producer.module.name === temporalModuleRef.name
- && step.producer.module.version === temporalModuleRef.version
- && step.producer.name === "shift-instant"
- && parameterAuthority !== undefined) {
- return {
- kind: "instant",
- expression: `${held.frame as number}f`,
- reference: "absolute",
- frame: held.frame as number,
- source: { timelineId: held.timelineId, type: record?.type ?? temporalTypes.instant,
- kind: "resolved", id: held.id },
- authority: parameterAuthority,
- };
- }
- if (step !== undefined) {
- const domainInput = Object.entries(step.inputs).find(([name]) =>
- name !== "timeline" && name !== "projection" && name !== "spec");
- if (domainInput !== undefined) {
- const [kind, sourceId] = domainInput;
- const sourceRecord = records.get(sourceId);
- const sourceValue = sourceRecord === undefined ? undefined : inline(sourceRecord.value) as { readonly id?: unknown } | undefined;
- const boundary = typeof spec?.boundary === "string" ? spec.boundary : "point";
- const reference = typeof spec?.reference === "string"
- ? spec.reference
- : `${kind}.${boundary === "cue" ? "cue" : boundary}`;
- const point = { ref: reference };
- if (sourceRecord !== undefined && typeof sourceValue?.id === "string") {
- const identified = identify?.(sourceRecord.type, sourceValue);
- const source = { timelineId: held.timelineId, type: sourceRecord.type,
- kind: identified?.kind ?? kind, id: identified?.itemId ?? sourceValue.id,
- ...(identified === undefined ? {} : { domain: { companion: identified.companion, id: identified.id } }) };
- return {
+ return typeof held?.id !== "string" || typeof held.timelineId !== "string" || !Number.isSafeInteger(held.frame)
+ ? undefined
+ : {
kind: "instant",
- expression: expression(point),
- reference,
+ expression: `${held.frame as number}f`,
+ reference: "absolute",
frame: held.frame as number,
- source,
- authority: { kind: "domain", source, boundary },
+ source: { timelineId: held.timelineId, type: record.type, kind: "resolved", id: held.id },
+ authority: { kind: "fixed" },
};
- }
- }
- }
- const type = record?.type ?? temporalTypes.instant;
- return {
- kind: "instant",
- expression: `${held.frame as number}f`,
- reference: "absolute",
- frame: held.frame as number,
- source: { timelineId: held.timelineId, type, kind: "resolved", id: held.id },
- authority: { kind: "fixed" },
- };
}
-function projection(
- record: TypedRecord,
- records: ReadonlyMap<string, TypedRecord>,
- producers: ReadonlyMap<string, ProducerStep>,
- identify?: IdentifyTemporalSource,
-): {
- readonly id: string;
- readonly subjectId: string;
- readonly projection: StudioTemporalProjection;
-} | undefined {
+function fixedWindow(record: TypedRecord): StudioTemporalProjection | undefined {
const held = inline(record.value) as {
- readonly id?: unknown;
- readonly subjectId?: unknown;
readonly start?: unknown;
readonly end?: unknown;
readonly span?: { readonly startFrame?: unknown; readonly endFrameExclusive?: unknown };
} | undefined;
- if (typeof held?.id !== "string" || typeof held.subjectId !== "string") return undefined;
- if (sameType(record.type, temporalTypes.instant)) {
- const projected = instant(record, records, producers, identify);
- return projected === undefined ? undefined : { id: held.id, subjectId: held.subjectId, projection: projected };
- }
- const step = producers.get(record.id);
- const startRecord = step?.inputs.start === undefined ? undefined : records.get(step.inputs.start);
- const endRecord = step?.inputs.end === undefined ? undefined : records.get(step.inputs.end);
- const start = instant(startRecord, records, producers, identify, held.start);
- const end = instant(endRecord, records, producers, identify, held.end);
- if (start === undefined || end === undefined) return undefined;
- if (!Number.isSafeInteger(held.span?.startFrame) || !Number.isSafeInteger(held.span?.endFrameExclusive)) return undefined;
- return {
- id: held.id,
- subjectId: held.subjectId,
- projection: {
- kind: "window",
- start,
- end,
- startFrame: held.span!.startFrame as number,
- endFrameExclusive: held.span!.endFrameExclusive as number,
- },
- };
+ const startRecord: TypedRecord = { ...record, id: `${record.id}:start`,
+ value: { kind: "inline", value: held?.start as import("@hypit/hypit/protocol").CanonicalValue } };
+ const endRecord: TypedRecord = { ...record, id: `${record.id}:end`,
+ value: { kind: "inline", value: held?.end as import("@hypit/hypit/protocol").CanonicalValue } };
+ const start = fixedInstant(startRecord);
+ const end = fixedInstant(endRecord);
+ return start === undefined || end === undefined || !Number.isSafeInteger(held?.span?.startFrame)
+ || !Number.isSafeInteger(held?.span?.endFrameExclusive)
+ ? undefined
+ : {
+ kind: "window",
+ start,
+ end,
+ startFrame: held!.span!.startFrame as number,
+ endFrameExclusive: held!.span!.endFrameExclusive as number,
+ };
}
-function recordIndex(state: BuildState): ReadonlyMap<string, TypedRecord> {
- return new Map([...state.program.records, ...state.records].map((record) => [record.id, record] as const));
+function traceRecord(input: {
+ readonly record: string;
+ readonly records: ReadonlyMap<string, TypedRecord>;
+ readonly producers: ReadonlyMap<string, ProducerStep>;
+ readonly identify?: IdentifyTemporalSource;
+ readonly relationFor?: FindTemporalRelation;
+ readonly active: ReadonlySet<string>;
+}): StudioTemporalRelationTrace | undefined {
+ const record = input.records.get(input.record);
+ if (record === undefined || input.active.has(input.record)) return undefined;
+ const step = input.producers.get(input.record);
+ if (step !== undefined && input.relationFor !== undefined) {
+ const outputName = Object.entries(step.outputs).find(([, id]) => id === input.record)?.[0];
+ const relation = outputName === undefined ? undefined : input.relationFor(step.producer, outputName);
+ if (relation?.trace !== undefined) {
+ const output = relationValue(input.records, input.record);
+ if (output === undefined) return undefined;
+ const inputs = Object.fromEntries(Object.entries(step.inputs).flatMap(([name, id]) => {
+ const value = relationValue(input.records, id);
+ return value === undefined ? [] : [[name, value]];
+ }));
+ const active = new Set(input.active).add(input.record);
+ return relation.trace({
+ output,
+ inputs,
+ trace: (name) => {
+ const child = step.inputs[name];
+ return child === undefined ? undefined : traceRecord({ ...input, record: child, active });
+ },
+ identify: (name) => {
+ const child = step.inputs[name];
+ const value = child === undefined ? undefined : relationValue(input.records, child);
+ const found = value === undefined ? undefined : input.identify?.(value.type, value.value);
+ return found === undefined ? undefined : { ...found, domainId: found.id };
+ },
+ });
+ }
+ }
+ if (sameType(record.type, temporalTypes.instant)) return fixedInstant(record);
+ if (sameType(record.type, temporalTypes.window)) return fixedWindow(record);
+ return undefined;
}
-function producingSteps(state: BuildState): ReadonlyMap<string, ProducerStep> {
- return new Map(state.plan.steps.flatMap((step) =>
- Object.values(step.outputs).map((record) => [record, step] as const)));
+/** Read one exact executed Temporal record through package-owned relation semantics. */
+export function executedTemporalProjection(
+ state: BuildState,
+ record: string,
+ identify?: IdentifyTemporalSource,
+ relationFor?: FindTemporalRelation,
+): StudioTemporalProjection | undefined {
+ const records = recordIndex(state);
+ const traced = traceRecord({ record, records, producers: producingSteps(state), active: new Set(),
+ ...(identify === undefined ? {} : { identify }), ...(relationFor === undefined ? {} : { relationFor }) });
+ return traced?.kind === "instant" || traced?.kind === "window" ? traced : undefined;
}
function closure(state: BuildState, output: string): ReadonlySet<string> {
@@ -219,21 +150,21 @@ function closure(state: BuildState, output: string): ReadonlySet<string> {
const step = producers.get(record);
if (step === undefined || steps.has(step.id)) return;
steps.add(step.id);
- for (const input of Object.values(step.inputs)) visit(input);
+ for (const child of Object.values(step.inputs)) visit(child);
};
visit(selected.record);
return steps;
}
/**
- * Read Temporal lineage from the exact executed dependency closure of one
- * logical output. Projection and consumption are graph facts; source markup is
- * deliberately not consulted here.
+ * Read Temporal lineage from one executed output closure. Studio follows graph
+ * identity; packages explain relation meaning through their Companions.
*/
export function executedTemporalBindings(
state: BuildState,
output: string,
identify?: IdentifyTemporalSource,
+ relationFor?: FindTemporalRelation,
): readonly StudioTemporalBinding[] {
const records = recordIndex(state);
const producers = producingSteps(state);
@@ -242,37 +173,35 @@ export function executedTemporalBindings(
return [...records.values()]
.filter((record) => sameType(record.type, temporalTypes.instant) || sameType(record.type, temporalTypes.window))
.flatMap((record): readonly StudioTemporalBinding[] => {
- const projected = projection(record, records, producers, identify);
- if (projected === undefined) return [];
+ const held = inline(record.value) as { readonly id?: unknown; readonly subjectId?: unknown } | undefined;
+ if (typeof held?.id !== "string" || typeof held.subjectId !== "string") return [];
+ const projection = executedTemporalProjection(state, record.id, identify, relationFor);
+ if (projection === undefined) return [];
const consumers = steps.flatMap((step) => Object.entries(step.inputs)
- .filter(([, input]) => input === record.id)
- .map(([input]) => ({
- step: step.id,
- producer: { module: { ...step.producer.module }, name: step.producer.name },
- input,
- role: step.producer.module.name === temporalModuleRef.name
- && step.producer.module.version === temporalModuleRef.version
- ? "projection" as const
- : "domain" as const,
- inputs: Object.entries(step.inputs).flatMap(([name, id]) => {
+ .filter(([, child]) => child === record.id)
+ .map(([name]) => {
+ const producesTemporal = Object.values(step.outputs).some((id) => {
const found = records.get(id);
- if (found === undefined) return [];
- const value = inline(found.value);
- return [{
- name,
- record: id,
- type: { module: { ...found.type.module }, name: found.type.name },
- ...(value === undefined ? {} : { value: structuredClone(value) }),
- }];
- }).sort((left, right) => left.name.localeCompare(right.name)),
- })));
+ return found !== undefined && (sameType(found.type, temporalTypes.instant) || sameType(found.type, temporalTypes.window));
+ });
+ return {
+ step: step.id,
+ producer: { module: { ...step.producer.module }, name: step.producer.name },
+ input: name,
+ role: producesTemporal ? "projection" as const : "domain" as const,
+ inputs: Object.entries(step.inputs).flatMap(([inputName, id]) => {
+ const found = records.get(id);
+ if (found === undefined) return [];
+ const value = inline(found.value);
+ return [{ name: inputName, record: id, type: { module: { ...found.type.module }, name: found.type.name },
+ ...(value === undefined ? {} : { value: structuredClone(value) }) }];
+ }).sort((left, right) => left.name.localeCompare(right.name)),
+ };
+ }));
if (consumers.length === 0) return [];
- return [{
- record: record.id,
- ...projected,
+ return [{ record: record.id, id: held.id, subjectId: held.subjectId, projection,
consumers: consumers.sort((left, right) => left.step.localeCompare(right.step)
- || left.input.localeCompare(right.input)),
- }];
+ || left.input.localeCompare(right.input)) }];
})
.sort((left, right) => left.record.localeCompare(right.record));
}
diff --git a/packages/studio/src/temporal-inverse.ts b/packages/studio/src/temporal-inverse.ts
new file mode 100644
index 00000000..aa635e9d
--- /dev/null
+++ b/packages/studio/src/temporal-inverse.ts
@@ -0,0 +1,276 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+import type { BuildState, ProducerStep, StoredValue, TypedRecord } from "@hypit/hypit/protocol";
+import { sameType } from "@hypit/hypit/protocol";
+import { temporalTypes } from "@hypit/hypit/temporal";
+import type {
+ StudioSourceBinding,
+ StudioTemporalConstraint,
+ StudioTemporalInstantProjection,
+ StudioTemporalRelationValue,
+} from "@hypit/studio-companion";
+
+import type { Placement } from "./observe.js";
+import type { StudioSourceFile } from "./parameters.js";
+import { executedTemporalProjection } from "./temporal-graph.js";
+import type { StudioCompanionRegistry } from "./studio-registry.js";
+
+type TemporalAuthor = {
+ readonly binding?: unknown;
+ readonly relation?: unknown;
+};
+
+export type TemporalSourceWrite = {
+ readonly source: StudioSourceBinding["source"];
+ readonly replacement: string;
+};
+
+function inline(value: StoredValue): unknown | undefined {
+ return value.kind === "inline" ? value.value : undefined;
+}
+
+function recordIndex(state: BuildState): ReadonlyMap<string, TypedRecord> {
+ return new Map([...state.program.records, ...state.records].map((record) => [record.id, record] as const));
+}
+
+function producerIndex(state: BuildState): ReadonlyMap<string, ProducerStep> {
+ return new Map(state.plan.steps.flatMap((step) =>
+ Object.values(step.outputs).map((record) => [record, step] as const)));
+}
+
+type AuthorElement = {
+ readonly sourcePath: string;
+ readonly authorEndpoints: Readonly<Record<string, string>>;
+ readonly records: readonly string[];
+ readonly attributes: Readonly<Record<string, unknown>>;
+ readonly references: Readonly<Record<string, string>>;
+ readonly attributeValueRanges: Readonly<Record<string, { readonly start: number; readonly end: number }>>;
+};
+
+function authorElements(placements: readonly Placement[]): readonly AuthorElement[] {
+ return placements.flatMap((placement): readonly AuthorElement[] => [{
+ sourcePath: placement.sourcePath,
+ authorEndpoints: placement.authorEndpoints ?? {},
+ records: placement.records,
+ attributes: placement.attributes,
+ references: placement.referenceAttributes,
+ attributeValueRanges: placement.attributeValueRanges,
+ }, ...placement.children.map((child) => ({
+ sourcePath: child.sourcePath,
+ authorEndpoints: child.authorEndpoints ?? {},
+ records: child.records ?? [],
+ attributes: child.attributes,
+ references: child.referenceAttributes,
+ attributeValueRanges: child.attributeValueRanges,
+ }))]);
+}
+
+function absolute(root: string, path: string): string {
+ return isAbsolute(path) ? resolve(path) : resolve(root, path);
+}
+
+/**
+ * Resolve author parameters by the exact executed Spec record that owns them.
+ * A consumer and a referenced declaration may use the same vocabulary word;
+ * the Spec identity keeps those writes distinct.
+ */
+export function temporalAuthorBindings(input: {
+ readonly state: BuildState;
+ readonly rootRecord: string;
+ readonly workspaceRoot: string;
+ readonly placements: readonly Placement[];
+ readonly files: readonly StudioSourceFile[];
+}): readonly StudioSourceBinding[] {
+ const records = recordIndex(input.state);
+ const producers = producerIndex(input.state);
+ const elements = authorElements(input.placements);
+ const files = new Map(input.files.map((file) => [absolute(input.workspaceRoot, file.path), file] as const));
+ const reached = new Set<string>();
+ const bindings = new Map<string, StudioSourceBinding>();
+ const collect = (recordId: string): void => {
+ const held = records.get(recordId);
+ const spec = held === undefined ? undefined : inline(held.value) as { readonly author?: TemporalAuthor } | undefined;
+ const binding = typeof spec?.author?.binding === "string" ? spec.author.binding : undefined;
+ if (binding === undefined) return;
+ const owner = `${recordId}:${binding}`;
+ const candidates = elements.filter((element) => element.records.includes(recordId)
+ && element.authorEndpoints[binding] !== undefined);
+ if (candidates.length !== 1) return;
+ const element = candidates[0]!;
+ const range = element.attributeValueRanges[binding];
+ const endpoint = element.authorEndpoints[binding];
+ const file = files.get(absolute(input.workspaceRoot, element.sourcePath));
+ if (range === undefined || endpoint === undefined || file === undefined || element.references[binding] !== undefined) return;
+ bindings.set(owner, {
+ id: owner,
+ binding: owner,
+ name: binding,
+ value: element.attributes[binding] as import("@hypit/hypit/protocol").CanonicalValue,
+ language: file.language,
+ writable: true,
+ source: {
+ endpoint,
+ path: relative(input.workspaceRoot, absolute(input.workspaceRoot, element.sourcePath)),
+ range,
+ preimage: file.text.slice(range.start, range.end),
+ },
+ });
+ };
+ const visit = (recordId: string): void => {
+ if (reached.has(recordId)) return;
+ reached.add(recordId);
+ collect(recordId);
+ const step = producers.get(recordId);
+ if (step === undefined) return;
+ for (const upstream of Object.values(step.inputs)) visit(upstream);
+ };
+ visit(input.rootRecord);
+ return [...bindings.values()];
+}
+
+/**
+ * Deterministically invert the executed Temporal relations used by an Item.
+ * The returned writes are one atomic author decision. Non-injective or opaque
+ * relations deliberately produce no plan instead of guessing an owner.
+ */
+export function planTemporalInverse(input: {
+ readonly state: BuildState;
+ readonly rootRecord: string;
+ readonly target: { readonly kind: "instant"; readonly frame: number }
+ | { readonly kind: "window"; readonly startFrame: number; readonly endFrameExclusive: number };
+ readonly bindings: readonly StudioSourceBinding[];
+ readonly domainFrame: (projection: StudioTemporalInstantProjection) => number | undefined;
+ readonly identify?: Parameters<typeof executedTemporalProjection>[2];
+ readonly registry?: StudioCompanionRegistry;
+}): readonly TemporalSourceWrite[] {
+ const records = recordIndex(input.state);
+ const producers = producerIndex(input.state);
+ const sources = new Map(input.bindings.map((binding) => [binding.binding, binding.source] as const));
+ const sameConstraint = (left: StudioTemporalConstraint, right: StudioTemporalConstraint): boolean =>
+ left.kind === right.kind && (left.kind === "instant" && right.kind === "instant"
+ ? left.frame === right.frame
+ : left.kind === "extent" && right.kind === "extent"
+ ? left.frameCount === right.frameCount
+ : left.kind === "span" && right.kind === "span"
+ ? left.startFrame === right.startFrame && left.endFrameExclusive === right.endFrameExclusive
+ : false);
+ const root = records.get(input.rootRecord);
+ if (root === undefined) throw new Error(`Temporal inverse cannot find ${input.rootRecord}.`);
+ type Candidate = {
+ readonly desired: Map<string, StudioTemporalConstraint>;
+ readonly queue: string[];
+ readonly writes: Map<string, TemporalSourceWrite>;
+ };
+ const constrain = (candidate: Candidate, record: string, target: StudioTemporalConstraint): boolean => {
+ const previous = candidate.desired.get(record);
+ if (previous !== undefined) return sameConstraint(previous, target);
+ candidate.desired.set(record, target);
+ candidate.queue.push(record);
+ return true;
+ };
+ const initial: Candidate = { desired: new Map(), queue: [], writes: new Map() };
+ if (input.target.kind === "instant") {
+ if (!sameType(root.type, temporalTypes.instant)) throw new Error("Temporal inverse expected an Instant record.");
+ constrain(initial, root.id, input.target);
+ } else {
+ if (!sameType(root.type, temporalTypes.window)) throw new Error("Temporal inverse expected a Window record.");
+ constrain(initial, root.id, { kind: "span", startFrame: input.target.startFrame,
+ endFrameExclusive: input.target.endFrameExclusive });
+ }
+
+ const write = (candidate: Candidate, owner: string, replacement: string): boolean => {
+ const source = sources.get(owner);
+ if (source === undefined) return false;
+ const key = source.endpoint ?? `${source.path}:${source.range.start}:${source.range.end}`;
+ const previous = candidate.writes.get(key);
+ if (previous !== undefined) return previous.replacement === replacement;
+ candidate.writes.set(key, { source, replacement });
+ return true;
+ };
+
+ const clone = (candidate: Candidate): Candidate => ({
+ desired: new Map(candidate.desired), queue: [...candidate.queue], writes: new Map(candidate.writes),
+ });
+ const solve = (candidate: Candidate): readonly Candidate[] => {
+ if (candidate.queue.length === 0) return [candidate];
+ const recordId = candidate.queue.shift()!;
+ const target = candidate.desired.get(recordId)!;
+ const record = records.get(recordId);
+ const step = producers.get(recordId);
+ if (record === undefined) throw new Error(`Temporal inverse cannot read ${recordId}.`);
+ const raw = inline(record.value) as {
+ readonly frame?: unknown; readonly frameCount?: unknown;
+ readonly startFrame?: unknown; readonly endFrameExclusive?: unknown;
+ readonly span?: { readonly startFrame?: unknown; readonly endFrameExclusive?: unknown };
+ } | undefined;
+ const current = (): StudioTemporalConstraint | undefined => {
+ if (Number.isSafeInteger(raw?.frame)) return { kind: "instant", frame: raw!.frame as number };
+ const heldSpan = Number.isSafeInteger(raw?.startFrame) && Number.isSafeInteger(raw?.endFrameExclusive)
+ ? raw : raw?.span;
+ if (Number.isSafeInteger(heldSpan?.startFrame) && Number.isSafeInteger(heldSpan?.endFrameExclusive)) {
+ return { kind: "span", startFrame: heldSpan!.startFrame as number,
+ endFrameExclusive: heldSpan!.endFrameExclusive as number };
+ }
+ if (Number.isSafeInteger(raw?.frameCount)) return { kind: "extent", frameCount: raw!.frameCount as number };
+ return undefined;
+ };
+ if (step === undefined) {
+ const held = current();
+ return held === undefined || !sameConstraint(held, target) ? [] : solve(candidate);
+ }
+ const outputName = Object.entries(step.outputs).find(([, output]) => output === recordId)?.[0];
+ const relation = outputName === undefined ? undefined : input.registry?.temporalRelationFor(step.producer, outputName);
+ if (relation !== undefined) {
+ const relationValue = (id: string): StudioTemporalRelationValue => {
+ const found = records.get(id);
+ if (found === undefined) throw new Error(`Temporal relation ${relation.id} cannot read ${id}.`);
+ return { record: id, type: found.type, value: inline(found.value) };
+ };
+ const plans = relation.invert({
+ target,
+ output: relationValue(recordId),
+ inputs: Object.fromEntries(Object.entries(step.inputs).map(([name, id]) => [name, relationValue(id)])),
+ desired: (name) => {
+ const id = step.inputs[name];
+ return id === undefined ? undefined : candidate.desired.get(id);
+ },
+ });
+ if (plans.length > 0) {
+ return plans.flatMap((plan): readonly Candidate[] => {
+ const branch = clone(candidate);
+ for (const child of plan.constraints ?? []) {
+ const record = step.inputs[child.input];
+ if (record === undefined) throw new Error(`Temporal relation ${relation.id} names missing input ${child.input}.`);
+ if (!constrain(branch, record, child.target)) return [];
+ }
+ for (const change of plan.writes ?? []) {
+ const record = step.inputs[change.input];
+ if (record === undefined) throw new Error(`Temporal relation ${relation.id} names missing input ${change.input}.`);
+ if (!write(branch, `${record}:${change.binding}`, change.replacement)) return [];
+ }
+ return solve(branch);
+ });
+ }
+ }
+ const projection = target.kind === "instant"
+ ? executedTemporalProjection(input.state, recordId, input.identify,
+ (producer, output) => input.registry?.temporalRelationFor(producer, output)) : undefined;
+ if (target.kind === "instant" && projection?.kind === "instant" && projection.authority.kind === "domain") {
+ return input.domainFrame(projection) !== target.frame ? [] : solve(candidate);
+ }
+ const held = current();
+ return held === undefined || !sameConstraint(held, target) ? [] : solve(candidate);
+ };
+ const key = (candidate: Candidate): string => [...candidate.writes.entries()]
+ .sort(([left], [right]) => left.localeCompare(right))
+ .map(([source, write]) => `${JSON.stringify(source)}:${JSON.stringify(write.replacement)}`).join("\n");
+ const solutions = new Map<string, Candidate>();
+ for (const candidate of solve(initial)) solutions.set(key(candidate), candidate);
+ if (solutions.size === 0) throw new Error("Temporal relation graph has no author inverse for the requested edit.");
+ if (solutions.size > 1) throw new Error("Temporal relation graph has multiple distinct author inverses for the requested edit.");
+ return [...[...solutions.values()][0]!.writes.values()]
+ .filter((candidate) => candidate.replacement !== candidate.source.preimage)
+ .sort((left, right) => left.source.path.localeCompare(right.source.path)
+ || left.source.range.start - right.source.range.start
+ || left.source.range.end - right.source.range.end);
+}
diff --git a/packages/studio/src/ui/code.ts b/packages/studio/src/ui/code.ts
index d0959e95..19bf0cd7 100644
--- a/packages/studio/src/ui/code.ts
+++ b/packages/studio/src/ui/code.ts
@@ -353,7 +353,7 @@ export function createCodePane(): CodePane {
if (token === undefined) code.append(node);
else {
const span = document.createElement("span");
- // A marker pair shares a tone with the clip it binds, so the two
+ // A marker pair shares a tone with the Item it binds, so the two
// ends of `@{claim} … @{/claim}` read as one thing.
const tone = token.id === undefined ? undefined : tones.get(token.id);
span.className = `tok tok-${token.kind}${tone === undefined ? "" : ` tone-${tone}`}`;
diff --git a/packages/studio/src/ui/main.ts b/packages/studio/src/ui/main.ts
index 019b7c4e..c5e68eac 100644
--- a/packages/studio/src/ui/main.ts
+++ b/packages/studio/src/ui/main.ts
@@ -1,6 +1,6 @@
import { bindDropdown } from "./dropdown.js";
import { uiLabel, uiAttribute, uiText, uiAttr, userText, languageMenu, initializeI18n, type Message } from "./i18n.js";
-import type { Clip, StudioFailure, StudioInspectorDomain, StudioSnapshot } from "../shared.js";
+import type { StudioItem, StudioFailure, StudioInspectorDomain, StudioMutation, StudioSnapshot } from "../shared.js";
import type { CanonicalValue, ValueSchema } from "@hypit/hypit/protocol";
import { parameterAuthorValue, parameterControlForSchema, parameterNumber, parameterOption, parameterRecordSchema, parameterRecordVariants, validateParameterValue } from "../parameter-values.js";
import { createCodePane } from "./code.js";
@@ -9,7 +9,7 @@ import { createLibraryPane } from "./library.js";
import { createHandle } from "./resize.js";
import type { Highlight } from "./code.js";
import { domainItemAtOffset, spanAtOffset } from "./markers.js";
-import { clipAtOffset, createStore } from "./selection.js";
+import { itemAtOffset, createStore } from "./selection.js";
import { createStage } from "./stage.js";
import { domainGestureSpan } from "../temporal-edit.js";
import type { DomainTarget } from "../temporal-edit.js";
@@ -208,8 +208,8 @@ const domainPresentation: Readonly<Record<StudioInspectorDomain, { readonly labe
when: { label: "inspector.when", icon: "when" },
};
const domainOrder: readonly StudioInspectorDomain[] = ["where", "when", "how"];
-const inspectorDomainByEntity = new Map<string, StudioInspectorDomain>();
-const inspectorPageByEntity = new Map<string, string>();
+const inspectorDomainByItem = new Map<string, StudioInspectorDomain>();
+const inspectorPageByItem = new Map<string, string>();
function defaultWorkspaceHeading(): void {
workspaceHeading.className = "pane-heading workspace-heading";
@@ -217,7 +217,7 @@ function defaultWorkspaceHeading(): void {
}
function inspectorHeading(
- entityId: string,
+ itemId: string,
domains: readonly StudioInspectorDomain[],
active: StudioInspectorDomain,
select: (domain: StudioInspectorDomain) => void,
@@ -232,7 +232,7 @@ function inspectorHeading(
button.innerHTML = `${icon(presentation.icon)}<strong>${uiLabel(presentation.label)}</strong>`;
button.setAttribute("aria-pressed", String(domain === active));
button.addEventListener("click", () => {
- inspectorDomainByEntity.set(entityId, domain);
+ inspectorDomainByItem.set(itemId, domain);
select(domain);
});
return button;
@@ -247,19 +247,21 @@ function textValue(value: CanonicalValue): string {
return typeof value === "string" ? value : value === null ? "" : String(value);
}
-function restoreParameterControls(entityId: string): void {
+type ParameterOwner = Extract<StudioMutation, { readonly type: "parameter.adjust" }>["owner"];
+
+function restoreParameterControls(): void {
const current = store.current();
- if (current?.selection.kind === "clip" && current.selection.clipId === entityId) {
- renderInspector(current.snapshot, entityId);
+ if (current?.selection.kind === "item") {
+ renderInspector(current.snapshot, current.selection.itemId);
}
}
-function commitControl(entityId: string, parameter: Clip["inspector"][number], replacement: CanonicalValue): void {
+function commitControl(owner: ParameterOwner, parameter: StudioItem["inspector"][number], replacement: CanonicalValue): void {
try {
if (sameValue(parameterAuthorValue(parameter, replacement), parameter.value)) return;
- void writeParameter(entityId, parameter, replacement);
+ void writeParameter(owner, parameter, replacement);
} catch (error) {
- restoreParameterControls(entityId);
+ restoreParameterControls();
uiText(status, "common.invalid-value"); status.className = "status error";
status.title = error instanceof Error ? error.message : String(error);
}
@@ -283,7 +285,7 @@ document.addEventListener("keydown", (event) => {
}, true);
function selectControl(
- parameter: Clip["inspector"][number],
+ parameter: StudioItem["inspector"][number],
change: (value: CanonicalValue) => void,
): HTMLElement {
const control = document.createElement("div");
@@ -443,7 +445,7 @@ function scalarDraftControl(
held: CanonicalValue | undefined,
change: (value: CanonicalValue) => void,
): HTMLElement {
- return parameterControl("", {
+ return parameterControl({ kind: "item", itemId: "" }, {
id: label, label, domain: "how", section: { id: "record", label: "" },
control: parameterControlForSchema(schema) ?? "text",
...(schema.kind === "string" && schema.enum !== undefined ? { options: schema.enum } : {}),
@@ -471,7 +473,7 @@ function recordDraftControl(
return fields;
}
-function structuredControl(entityId: string, parameter: Clip["inspector"][number], change: (value: CanonicalValue) => void): HTMLElement {
+function structuredControl(owner: ParameterOwner, parameter: StudioItem["inspector"][number], change: (value: CanonicalValue) => void): HTMLElement {
const declaredSchema = parameter.schema;
const shell = document.createElement("div");
shell.className = "parameter-structured";
@@ -503,7 +505,7 @@ function structuredControl(entityId: string, parameter: Clip["inspector"][number
if (schema === undefined) return;
if (variants.length) {
const active = variants.find(variant => variant.schema === schema)!;
- shell.append(parameterControl(entityId, {
+ shell.append(parameterControl(owner, {
...parameter, control: "select", value: variants.indexOf(active),
options: variants.map((variant, index) => ({ value: index, label: textValue(variant.value) })),
}, (next) => {
@@ -610,14 +612,14 @@ function structuredControl(entityId: string, parameter: Clip["inspector"][number
}
function parameterControl(
- entityId: string,
- parameter: Clip["inspector"][number],
+ owner: ParameterOwner,
+ parameter: StudioItem["inspector"][number],
change?: (value: CanonicalValue) => void,
): HTMLElement {
const editable = parameter.edit !== undefined || change !== undefined;
- const commit = change ?? ((value: CanonicalValue) => commitControl(entityId, parameter, value));
+ const commit = change ?? ((value: CanonicalValue) => commitControl(owner, parameter, value));
if (editable && parameter.control === "record" && parameter.schema !== undefined && parameterRecordVariants(parameter.schema).length) {
- return structuredControl(entityId, parameter, commit);
+ return structuredControl(owner, parameter, commit);
}
const row = document.createElement("div");
row.className = `parameter-row ${!editable ? "parameter-readonly" : "parameter-editable"} control-${parameter.control}`;
@@ -666,7 +668,7 @@ function parameterControl(
right.append(palette);
}
} else if (parameter.control === "list" || parameter.control === "record") {
- right.append(structuredControl(entityId, parameter, commit));
+ right.append(structuredControl(owner, parameter, commit));
} else {
if (parameter.multiline && parameter.control === "text") {
const value = document.createElement("textarea"); value.className = "parameter-value parameter-multiline";
@@ -722,8 +724,8 @@ function parameterControl(
return row;
}
-function parameterGroups(entityId: string, fields: readonly Clip["inspector"][number][]): readonly HTMLElement[] {
- const groups = new Map<string, Clip["inspector"][number][]>();
+function parameterGroups(owner: ParameterOwner, fields: readonly StudioItem["inspector"][number][]): readonly HTMLElement[] {
+ const groups = new Map<string, StudioItem["inspector"][number][]>();
for (const field of fields) {
const key = `${field.section.id}\u0000${field.section.label}`;
const held = groups.get(key) ?? [];
@@ -732,12 +734,12 @@ function parameterGroups(entityId: string, fields: readonly Clip["inspector"][nu
}
return [...groups].map(([key, values]) => {
const [, label = ""] = key.split("\u0000");
- return group(label, values.map((parameter) => parameterControl(entityId, parameter)), "parameter-group inspector-field-group");
+ return group(label, values.map((parameter) => parameterControl(owner, parameter)), "parameter-group inspector-field-group");
});
}
let parameterWriteState: "" | "common.saving" | "common.saved" | "common.failed" = "";
-async function writeParameter(entityId: string, parameter: Clip["inspector"][number], replacement: CanonicalValue): Promise<void> {
+async function writeParameter(owner: ParameterOwner, parameter: StudioItem["inspector"][number], replacement: CanonicalValue): Promise<void> {
const state = store.current();
if (state === undefined) return;
parameterWriteState = "common.saving";
@@ -748,7 +750,7 @@ async function writeParameter(entityId: string, parameter: Clip["inspector"][num
await applyStudioMutation({
type: "parameter.adjust",
revision: state.snapshot.revision,
- entityId,
+ owner,
parameterId: parameter.id,
value: replacement,
});
@@ -758,7 +760,7 @@ async function writeParameter(entityId: string, parameter: Clip["inspector"][num
} catch (error) {
// Validation and stale-revision rejections do not publish a new snapshot.
// Restore the accepted value just as a rejected compilation does.
- restoreParameterControls(entityId);
+ restoreParameterControls();
parameterWriteState = "common.failed";
uiText(status, error instanceof Error ? "common.save-failed" : parameterWriteState);
status.className = "status error";
@@ -766,15 +768,42 @@ async function writeParameter(entityId: string, parameter: Clip["inspector"][num
}
}
+function trackInspectorGroups(
+ track: StudioSnapshot["tracks"][number],
+ domain: StudioInspectorDomain,
+): readonly HTMLElement[] {
+ const grouped = new Map<string, typeof track.inspectorObjects>();
+ for (const object of track.inspectorObjects) {
+ if (!object.inspector.some((field) => field.domain === domain)) continue;
+ grouped.set(object.group, [...(grouped.get(object.group) ?? []), object]);
+ }
+ return [...grouped].map(([label, objects]) => group(label, objects.map((object) => {
+ const details = document.createElement("details");
+ details.className = "inspector-object";
+ const summary = document.createElement("summary");
+ summary.textContent = object.title;
+ const fields = document.createElement("div");
+ fields.className = "inspector-object-fields";
+ fields.append(...parameterGroups(
+ { kind: "track-object", trackId: track.id, objectId: object.id },
+ object.inspector.filter((field) => field.domain === domain),
+ ));
+ details.append(summary, fields);
+ return details;
+ }), "inspector-object-group"));
+}
+
/**
* A single strip between the picture and the timeline. It is a row of the
* layout rather than a floating card, so it can never cover the frame being
* inspected or the transport used to reach it.
*/
-function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined): void {
- const clip = clipId === undefined ? undefined : store.clip(clipId);
+function renderInspector(snapshot: StudioSnapshot, itemId: string | undefined): void {
+ const item = itemId === undefined ? undefined : store.item(itemId);
+ const track = item === undefined ? undefined : snapshot.tracks.find((candidate) =>
+ candidate.items.some((candidateItem) => candidateItem.id === item.id));
- if (clip === undefined) {
+ if (item === undefined) {
defaultWorkspaceHeading();
const fps = snapshot.timeline.frameRate.numerator / snapshot.timeline.frameRate.denominator;
inspector.replaceChildren(
@@ -802,7 +831,8 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
);
return;
}
- const domains = domainOrder.filter((domain) => clip.inspector.some((field) => field.domain === domain));
+ const domains = domainOrder.filter((domain) => item.inspector.some((field) => field.domain === domain)
+ || track?.inspectorObjects.some((object) => object.inspector.some((field) => field.domain === domain)) === true);
if (domains.length === 0) {
defaultWorkspaceHeading();
const empty = document.createElement("div");
@@ -811,12 +841,12 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
inspector.replaceChildren(empty);
return;
}
- const remembered = inspectorDomainByEntity.get(clip.id);
+ const remembered = inspectorDomainByItem.get(item.id);
const activeDomain = remembered !== undefined && domains.includes(remembered) ? remembered : domains[0]!;
- inspectorDomainByEntity.set(clip.id, activeDomain);
- inspectorHeading(clip.id, domains, activeDomain, () => renderInspector(snapshot, clip.id));
+ inspectorDomainByItem.set(item.id, activeDomain);
+ inspectorHeading(item.id, domains, activeDomain, () => renderInspector(snapshot, item.id));
- const domainFields = clip.inspector.filter((field) => field.domain === activeDomain);
+ const domainFields = item.inspector.filter((field) => field.domain === activeDomain);
const pages = new Map<string, { readonly label: string; readonly fields: typeof domainFields }>();
const commonFields = domainFields.filter(field => field.page === undefined);
for (const field of domainFields.filter(field => field.page !== undefined)) {
@@ -826,13 +856,16 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
}
const pageIds = [...pages.keys()];
if (pageIds.length === 0) {
- inspector.replaceChildren(...parameterGroups(clip.id, commonFields));
+ inspector.replaceChildren(
+ ...parameterGroups({ kind: "item", itemId: item.id }, commonFields),
+ ...(track === undefined ? [] : trackInspectorGroups(track, activeDomain)),
+ );
return;
}
- const memoryKey = `${clip.id}:${activeDomain}`;
- const rememberedPage = inspectorPageByEntity.get(memoryKey);
+ const memoryKey = `${item.id}:${activeDomain}`;
+ const rememberedPage = inspectorPageByItem.get(memoryKey);
const activePage = rememberedPage !== undefined && pages.has(rememberedPage) ? rememberedPage : pageIds[0]!;
- inspectorPageByEntity.set(memoryKey, activePage);
+ inspectorPageByItem.set(memoryKey, activePage);
const page = pages.get(activePage);
const subtabs = document.createElement("div");
subtabs.className = "inspector-subtabs";
@@ -845,13 +878,17 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
label.textContent = pages.get(id)?.label ?? id;
button.append(label);
button.addEventListener("click", () => {
- inspectorPageByEntity.set(memoryKey, id);
- renderInspector(snapshot, clip.id);
+ inspectorPageByItem.set(memoryKey, id);
+ renderInspector(snapshot, item.id);
});
return button;
}));
}
- inspector.replaceChildren(...(pageIds.length > 1 ? [subtabs] : []), ...parameterGroups(clip.id, [...commonFields, ...(page?.fields ?? [])]));
+ inspector.replaceChildren(
+ ...(pageIds.length > 1 ? [subtabs] : []),
+ ...parameterGroups({ kind: "item", itemId: item.id }, [...commonFields, ...(page?.fields ?? [])]),
+ ...(track === undefined ? [] : trackInspectorGroups(track, activeDomain)),
+ );
}
/** Exact identity choice for coincident anchors, through package-declared domain handles. */
@@ -860,10 +897,10 @@ function renderTemporalDomainInspector(snapshot: StudioSnapshot, companion: stri
const item = domain?.items.find((candidate) => candidate.id === itemId);
if (domain === undefined || item === undefined) { inspector.replaceChildren(); return; }
defaultWorkspaceHeading();
- const consumers = snapshot.tracks.flatMap((track) => track.clips).flatMap((clip) => clip.editHandles
+ const consumers = snapshot.tracks.flatMap((track) => track.items).flatMap((studioItem) => studioItem.editHandles
.filter((handle) => handle.enabled && handle.domain?.companion === companion
&& handle.domain.domainId === domainId && handle.domain.itemId === itemId)
- .map((handle) => ({ clip, handle })));
+ .map((handle) => ({ studioItem, handle })));
if (item.editable !== true || consumers.length === 0) {
const empty = document.createElement("div");
empty.className = "inspector-empty";
@@ -912,7 +949,7 @@ function renderTemporalDomainInspector(snapshot: StudioSnapshot, companion: stri
control.disabled = true;
uiText(status, "common.saving"); status.className = "status saving";
void applyStudioMutation({ type: "timeline.adjust", revision: snapshot.revision,
- entityId: choice.clip.id, gesture: choice.handle.gesture,
+ itemId: choice.studioItem.id, gesture: choice.handle.gesture,
target: temporal.kind === "instant" ? { kind: "instant", frame: span.startFrame, domain: choice.target }
: { kind: "window", ...span, domain: choice.target },
}).then(() => { uiText(status, "common.saved"); status.className = "status saved"; })
@@ -941,7 +978,7 @@ let scrolledTo = "";
store.subscribe(({ snapshot, selection, playhead }) => {
const origin = selection.kind === "none" ? undefined : selection.origin;
- const chosen = selection.kind === "clip" ? store.clip(selection.clipId) : undefined;
+ const chosen = selection.kind === "item" ? store.item(selection.itemId) : undefined;
const chosenDomain = selection.kind === "temporal-domain"
? snapshot.temporalDomains.find((domain) => domain.companion === selection.companion
&& domain.id === selection.domainId)?.items.find((item) => item.id === selection.itemId)
@@ -1000,26 +1037,26 @@ code.element.addEventListener("click", (event) => {
store.selectTemporalDomainItem(domainItem.companion, domainItem.domainId, domainItem.itemId, "code");
return;
}
- const clip = clipAtOffset(state.snapshot, offset);
+ const item = itemAtOffset(state.snapshot, offset);
// A click inside marked prose lands inside the innermost marker written there,
// not at the start of whatever encloses it. `@{amount}` places nothing, so
- // resolving through clips alone would throw the playhead out to `@{fee}`.
+ // resolving through Items alone would throw the playhead out to `@{fee}`.
const span = spanAtOffset(state.snapshot, offset);
- // Prose is anywhere a marker was written; whether a clip also covers that
- // offset only decides which clip to select, not whether the click counts.
+ // Prose is anywhere a marker was written; whether an Item also covers that
+ // offset only decides which Item to select, not whether the click counts.
const inProse = span !== undefined
- && (clip?.elementRange === undefined
- || !(offset >= clip.elementRange.start && offset <= clip.elementRange.end));
+ && (item?.elementRange === undefined
+ || !(offset >= item.elementRange.start && offset <= item.elementRange.end));
if (inProse) {
- // A clip is named after itself and remembers what placed it, so a marker
- // finds the clips it put there through the second, not the first.
+ // An Item is named after itself and remembers what placed it, so a marker
+ // finds the Items it put there through the second, not the first.
const bound = state.snapshot.tracks
- .flatMap((track) => track.clips)
+ .flatMap((track) => track.items)
.find((item) => item.markerId === span.itemId || item.authoredId === span.itemId);
// A marker that places nothing still sits inside one that does, so the
- // enclosing clip stays selected rather than leaving the inspector blank.
- const target = bound?.id ?? clip?.id;
+ // enclosing Item stays selected rather than leaving the inspector blank.
+ const target = bound?.id ?? item?.id;
if (target === undefined) {
store.selectTemporalDomainItem(span.companion, span.domainId, span.itemId, "code");
store.seek(span.startFrame, "code");
@@ -1027,8 +1064,8 @@ code.element.addEventListener("click", (event) => {
else store.focus(span.startFrame, target, "code");
return;
}
- if (clip === undefined) store.clearSelection();
- else store.selectClip(clip.id, "code");
+ if (item === undefined) store.clearSelection();
+ else store.selectItem(item.id, "code");
});
window.addEventListener("keydown", (event) => {
@@ -1090,7 +1127,7 @@ function applyFailure(failure: StudioFailure): void {
// value visible in the field.
const current = store.current();
if (current === undefined) return;
- if (current.selection.kind === "clip") renderInspector(current.snapshot, current.selection.clipId);
+ if (current.selection.kind === "item") renderInspector(current.snapshot, current.selection.itemId);
else if (current.selection.kind === "temporal-domain") renderTemporalDomainInspector(current.snapshot,
current.selection.companion, current.selection.domainId, current.selection.itemId);
}
diff --git a/packages/studio/src/ui/markers.ts b/packages/studio/src/ui/markers.ts
index c20cf932..2d559cb1 100644
--- a/packages/studio/src/ui/markers.ts
+++ b/packages/studio/src/ui/markers.ts
@@ -7,7 +7,7 @@ function depthOf(range: Range, all: readonly Range[]): number {
return 1 + all.filter((other) => other.start < range.start && other.end > range.end).length;
}
-/** Stable tones derived from package-contributed source nesting, then reused by clips. */
+/** Stable tones derived from package-contributed source nesting, then reused by Items. */
export function intentTones(snapshot: StudioSnapshot): ReadonlyMap<string, number> {
const tones = new Map<string, number>();
for (const domain of snapshot.temporalDomains) {
@@ -19,17 +19,17 @@ export function intentTones(snapshot: StudioSnapshot): ReadonlyMap<string, numbe
const seen = new Map<string, number>();
let spare = 0;
for (const track of snapshot.tracks) {
- for (const clip of track.clips) {
- if (tones.has(clip.authoredId)) continue;
- const intent = clip.markerId === undefined ? undefined : tones.get(clip.markerId);
+ for (const item of track.items) {
+ if (tones.has(item.authoredId)) continue;
+ const intent = item.markerId === undefined ? undefined : tones.get(item.markerId);
if (intent === undefined) {
- tones.set(clip.authoredId, spare % INTENT_TONES);
+ tones.set(item.authoredId, spare % INTENT_TONES);
spare += 1;
continue;
}
- const index = seen.get(clip.markerId!) ?? 0;
- seen.set(clip.markerId!, index + 1);
- tones.set(clip.authoredId, (intent + index) % INTENT_TONES);
+ const index = seen.get(item.markerId!) ?? 0;
+ seen.set(item.markerId!, index + 1);
+ tones.set(item.authoredId, (intent + index) % INTENT_TONES);
}
}
return tones;
diff --git a/packages/studio/src/ui/material-preview.ts b/packages/studio/src/ui/material-preview.ts
index 9e3278c0..0f28c9cf 100644
--- a/packages/studio/src/ui/material-preview.ts
+++ b/packages/studio/src/ui/material-preview.ts
@@ -83,7 +83,7 @@ function renderStoryboard(target: HTMLElement, storyboard: Storyboard): void {
const column = index % storyboard.columns;
const row = Math.floor(index / storyboard.columns);
const frame = document.createElement("span");
- frame.className = "clip-video-frame";
+ frame.className = "studio-item-video-frame";
frame.style.left = `${left}px`;
// Adjacent frames share the same fractional boundary. Adding a full CSS
// pixel here lets the next frame overpaint roughly 3% of a 9:16 thumbnail,
@@ -143,7 +143,7 @@ export function audioPreview(url: string): Promise<string | undefined> {
/** Mount only a real selected artifact; failed decoding deliberately leaves the item plain. */
export function mountMaterialPreview(target: HTMLElement, preview: StudioMaterialPreview): void {
const url = previewUrl(preview);
- target.classList.add(`clip-material-${preview.kind}`);
+ target.classList.add(`studio-item-material-${preview.kind}`);
if (preview.kind === "video") {
if (resolvedStoryboards.has(url)) {
const storyboard = resolvedStoryboards.get(url);
diff --git a/packages/studio/src/ui/overlay.ts b/packages/studio/src/ui/overlay.ts
index 16f82f39..0b369c4a 100644
--- a/packages/studio/src/ui/overlay.ts
+++ b/packages/studio/src/ui/overlay.ts
@@ -1,11 +1,11 @@
-import type { Clip, StudioSnapshot } from "../shared.js";
+import type { StudioItem, StudioSnapshot } from "../shared.js";
import { intentTones } from "./markers.js";
import type { Store } from "./selection.js";
const SVG_NS = "http://www.w3.org/2000/svg";
/**
- * Where a clip is actually drawn, in canvas pixels, or undefined when the
+ * Where an Item is actually drawn, in canvas pixels, or undefined when the
* picture has not mounted yet.
*/
/** A box on the canvas, in canvas pixels. */
@@ -14,13 +14,13 @@ export type Box = {
readonly widthPx: number; readonly heightPx: number;
};
-export type Measure = (clipId: string) => (Box & { readonly stackOrder: number }) | undefined;
+export type Measure = (renderId: string) => (Box & { readonly stackOrder: number }) | undefined;
export type Overlay = {
readonly element: SVGSVGElement;
- /** The topmost clip drawn at a point, in client coordinates. */
- hitTest(clientX: number, clientY: number): Clip | undefined;
- hitsAt(clientX: number, clientY: number): readonly Clip[];
+ /** The topmost Item drawn at a point, in client coordinates. */
+ hitTest(clientX: number, clientY: number): StudioItem | undefined;
+ hitsAt(clientX: number, clientY: number): readonly StudioItem[];
/** Redraw against the picture, once it has mounted or moved. */
refresh(): void;
};
@@ -44,14 +44,14 @@ function inside(box: Box, x: number, y: number): boolean {
}
/**
- * The box drawn over the picture for the selected clip.
+ * The box drawn over the picture for the selected Item.
*
* The overlay shares the composition's own coordinate system through its
* viewBox, so a box is written in canvas pixels with no transform to keep in
* step with the iframe's scale.
*
* The box itself is measured from the rendered picture rather than recomputed
- * from the Placement Frame. Two things move a clip away from that Frame:
+ * from the Placement Frame. Two things move an Item away from that Frame:
* lifecycle motion displaces it for the length of its enter and exit, and the
* frame paint fills the Frame while padded material does not. Measuring what
* was drawn is exact for both, and stays exact for whatever the renderer does
@@ -63,24 +63,24 @@ export function createOverlay(store: Store, measure: Measure): Overlay {
element.setAttribute("class", "stage-overlay");
element.setAttribute("preserveAspectRatio", "none");
- let entities: readonly Clip[] = [];
+ let items: readonly StudioItem[] = [];
let canvas = { width: 1, height: 1 };
- let last: { snapshot: StudioSnapshot; selected: Clip | undefined } | undefined;
+ let last: { snapshot: StudioSnapshot; selected: StudioItem | undefined } | undefined;
/**
* The box is measured off the picture rather than restated from the Source:
* motion moves an element across its span, so only what was drawn knows where
* it ended up. A Present that has not mounted has no box to draw.
*/
- const drawnParts = (clip: Clip) => {
- const ids = clip.renderIds.length > 0 ? clip.renderIds : clip.presentId === undefined ? [] : [clip.presentId];
+ const drawnParts = (item: StudioItem) => {
+ const ids = item.renderIds.length > 0 ? item.renderIds : item.presentId === undefined ? [] : [item.presentId];
return ids.flatMap((id) => {
const found = measure(id);
return found === undefined ? [] : [found];
});
};
- const drawnBox = (clip: Clip): Box | undefined => {
- const boxes = drawnParts(clip);
+ const drawnBox = (item: StudioItem): Box | undefined => {
+ const boxes = drawnParts(item);
if (boxes.length === 0) return undefined;
const left = Math.min(...boxes.map((box) => box.xPx));
const top = Math.min(...boxes.map((box) => box.yPx));
@@ -97,7 +97,7 @@ export function createOverlay(store: Store, measure: Measure): Overlay {
element.replaceChildren();
// An editing interval can end before its visual representation disappears.
// The renderer decides which associated parts are visible at this frame.
- entities = snapshot.tracks.flatMap((track) => track.clips);
+ items = snapshot.tracks.flatMap((track) => track.items);
if (selected === undefined) return;
const tones = intentTones(snapshot);
@@ -123,22 +123,22 @@ export function createOverlay(store: Store, measure: Measure): Overlay {
store.subscribe(({ snapshot, selection }) => {
last = {
snapshot,
- selected: selection.kind === "clip" ? store.clip(selection.clipId) : undefined,
+ selected: selection.kind === "item" ? store.item(selection.itemId) : undefined,
};
draw();
});
- const hitsAt = (clientX: number, clientY: number): readonly Clip[] => {
+ const hitsAt = (clientX: number, clientY: number): readonly StudioItem[] => {
const box = element.getBoundingClientRect();
if (box.width === 0 || box.height === 0) return [];
const x = (clientX - box.left) / box.width * canvas.width;
const y = (clientY - box.top) / box.height * canvas.height;
// Hit individual parts, not the empty space inside a group's union box.
- const hits = entities.flatMap((clip) => drawnParts(clip)
+ const hits = items.flatMap((item) => drawnParts(item)
.filter((part) => inside(part, x, y))
- .map((part) => ({ clip, order: part.stackOrder })))
+ .map((part) => ({ item, order: part.stackOrder })))
.sort((left, right) => right.order - left.order);
- return [...new Map(hits.map(({ clip }) => [clip.id, clip])).values()];
+ return [...new Map(hits.map(({ item }) => [item.id, item])).values()];
};
return {
element,
diff --git a/packages/studio/src/ui/selection.ts b/packages/studio/src/ui/selection.ts
index 179abefd..3dffb4cf 100644
--- a/packages/studio/src/ui/selection.ts
+++ b/packages/studio/src/ui/selection.ts
@@ -1,4 +1,4 @@
-import type { Clip, StudioSnapshot } from "../shared.js";
+import type { StudioItem, StudioSnapshot } from "../shared.js";
/**
* Which pane the user acted in. Panes ignore events they originated, which is
@@ -9,7 +9,7 @@ export type Origin = "timeline" | "code" | "video";
export type Selection =
| { readonly kind: "none" }
- | { readonly kind: "clip"; readonly clipId: string; readonly origin: Origin }
+ | { readonly kind: "item"; readonly itemId: string; readonly origin: Origin }
| { readonly kind: "temporal-domain"; readonly companion: string; readonly domainId: string; readonly itemId: string; readonly origin: Origin };
export type Playhead = { readonly frame: number; readonly origin: Origin | "play" };
@@ -23,49 +23,49 @@ export type State = {
export type Store = {
/** Undefined until the first snapshot arrives. */
current(): State | undefined;
- clip(clipId: string): Clip | undefined;
- /** Clips covering a frame, topmost track first. */
- clipsAt(frame: number): readonly Clip[];
+ item(itemId: string): StudioItem | undefined;
+ /** Items covering a frame, topmost track first. */
+ itemsAt(frame: number): readonly StudioItem[];
load(snapshot: StudioSnapshot): void;
/** Select without moving the playhead; timeline inspection must not destroy position. */
- select(clipId: string, origin: Origin): void;
+ select(itemId: string, origin: Origin): void;
/** Select one package-contributed temporal-domain item without moving the playhead. */
selectTemporalDomainItem(companion: string, domainId: string, itemId: string, origin: Origin): void;
- /** Select and seek to the clip start, used by source navigation. */
- selectClip(clipId: string, origin: Origin): void;
+ /** Select and seek to the Item start, used by source navigation. */
+ selectItem(itemId: string, origin: Origin): void;
/**
- * Look at one instant, optionally selecting a clip there. Used when the thing
- * an author pointed at is a Script range rather than a clip, which has no
+ * Look at one instant, optionally selecting an Item there. Used when the thing
+ * an author pointed at is a Script range rather than an Item, which has no
* first frame of its own to jump to.
*/
- focus(frame: number, clipId: string | undefined, origin: Origin): void;
+ focus(frame: number, itemId: string | undefined, origin: Origin): void;
clearSelection(): void;
seek(frame: number, origin: Origin | "play"): void;
subscribe(listener: (state: State) => void): void;
};
/**
- * The clip an author is pointing at in the source text.
+ * The Item an author is pointing at in the source text.
*
* A Script intent wins over the element that binds it: `@{claim} … @{/claim}` sits
* inside the `<script>` element, so without that preference every click in the
* prose would select the speech performance instead of the B-roll. Ties break toward
* the tightest range, which is the most specific thing under the cursor.
*/
-export function clipAtOffset(snapshot: StudioSnapshot, offset: number): Clip | undefined {
- const clips = snapshot.tracks.flatMap((track) => track.clips);
+export function itemAtOffset(snapshot: StudioSnapshot, offset: number): StudioItem | undefined {
+ const items = snapshot.tracks.flatMap((track) => track.items);
const within = (range: { readonly start: number; readonly end: number } | undefined): number =>
range === undefined || offset < range.start || offset > range.end
? Number.POSITIVE_INFINITY
: range.end - range.start;
- let best: Clip | undefined;
+ let best: StudioItem | undefined;
let bestScore = Number.POSITIVE_INFINITY;
- for (const clip of clips) {
- const score = within(clip.elementRange);
+ for (const item of items) {
+ const score = within(item.elementRange);
if (score < bestScore) {
bestScore = score;
- best = clip;
+ best = item;
}
}
return best;
@@ -77,7 +77,7 @@ export function createStore(): Store {
let playhead: Playhead = { frame: 0, origin: "timeline" };
const listeners: ((state: State) => void)[] = [];
- const clips = (): readonly Clip[] => snapshot?.tracks.flatMap((track) => track.clips) ?? [];
+ const items = (): readonly StudioItem[] => snapshot?.tracks.flatMap((track) => track.items) ?? [];
const emit = (): void => {
if (snapshot === undefined) return;
@@ -90,18 +90,18 @@ export function createStore(): Store {
return {
current: () => snapshot === undefined ? undefined : { snapshot, selection, playhead },
- clip: (clipId) => clips().find((clip) => clip.id === clipId),
- clipsAt(frame) {
- return clips()
- .filter((clip) => frame >= clip.startFrame && frame < clip.endFrameExclusive)
+ item: (itemId) => items().find((item) => item.id === itemId),
+ itemsAt(frame) {
+ return items()
+ .filter((item) => frame >= item.startFrame && frame < item.endFrameExclusive)
.sort((left, right) => right.stackOrder - left.stackOrder);
},
load(value) {
snapshot = value;
- // A recompiled Source may have dropped the selected clip, and its frame
+ // A recompiled Source may have dropped the selected Item, and its frame
// count may have moved under the playhead.
const held = selection;
- if (held.kind === "clip" && !clips().some((clip) => clip.id === held.clipId)) {
+ if (held.kind === "item" && !items().some((item) => item.id === held.itemId)) {
selection = { kind: "none" };
}
if (held.kind === "temporal-domain"
@@ -112,10 +112,10 @@ export function createStore(): Store {
playhead = { frame: clamp(playhead.frame), origin: playhead.origin };
emit();
},
- select(clipId, origin) {
- const clip = clips().find((item) => item.id === clipId);
- if (clip === undefined) return;
- selection = { kind: "clip", clipId, origin };
+ select(itemId, origin) {
+ const item = items().find((candidate) => candidate.id === itemId);
+ if (item === undefined) return;
+ selection = { kind: "item", itemId, origin };
emit();
},
selectTemporalDomainItem(companion, domainId, itemId, origin) {
@@ -124,16 +124,16 @@ export function createStore(): Store {
selection = { kind: "temporal-domain", companion, domainId, itemId, origin };
emit();
},
- selectClip(clipId, origin) {
- const clip = clips().find((item) => item.id === clipId);
- if (clip === undefined) return;
- selection = { kind: "clip", clipId, origin };
- playhead = { frame: clamp(clip.startFrame), origin };
+ selectItem(itemId, origin) {
+ const item = items().find((candidate) => candidate.id === itemId);
+ if (item === undefined) return;
+ selection = { kind: "item", itemId, origin };
+ playhead = { frame: clamp(item.startFrame), origin };
emit();
},
- focus(frame, clipId, origin) {
- const clip = clipId === undefined ? undefined : clips().find((item) => item.id === clipId);
- selection = clip === undefined ? { kind: "none" } : { kind: "clip", clipId: clip.id, origin };
+ focus(frame, itemId, origin) {
+ const item = itemId === undefined ? undefined : items().find((candidate) => candidate.id === itemId);
+ selection = item === undefined ? { kind: "none" } : { kind: "item", itemId: item.id, origin };
playhead = { frame: clamp(frame), origin };
emit();
},
diff --git a/packages/studio/src/ui/stage.ts b/packages/studio/src/ui/stage.ts
index 57c12ed2..a225d62c 100644
--- a/packages/studio/src/ui/stage.ts
+++ b/packages/studio/src/ui/stage.ts
@@ -66,19 +66,19 @@ export function createStage(store: Store, selectedArtifact: (id: string | undefi
const iframe = element.querySelector<HTMLIFrameElement>("iframe")!;
let reviewMode = false;
/**
- * Measure a clip in the rendered picture.
+ * Measure an Item in the rendered picture.
*
* The iframe is sized to the canvas, so coordinates inside its document are
* canvas pixels already and need no conversion. `getBoundingClientRect`
* reflects the paused animation's transform, which is the whole point:
- * lifecycle motion displaces a clip from its Placement Frame for the length
- * of its enter and exit, and selecting a clip lands the playhead on exactly
+ * lifecycle motion displaces an Item from its Placement Frame for the length
+ * of its enter and exit, and selecting an Item lands the playhead on exactly
* the frame where that displacement is largest.
*/
- const measure = (clipId: string): { xPx: number; yPx: number; widthPx: number; heightPx: number; stackOrder: number } | undefined => {
+ const measure = (renderId: string): { xPx: number; yPx: number; widthPx: number; heightPx: number; stackOrder: number } | undefined => {
const document_ = iframe.contentDocument;
if (document_ === null) return undefined;
- const present = document_.querySelector(`[data-hypit-present-id="${CSS.escape(clipId)}"]`);
+ const present = document_.querySelector(`[data-hypit-present-id="${CSS.escape(renderId)}"]`);
if (present === null) return undefined;
const current = store.current();
if (current === undefined) return undefined;
@@ -88,7 +88,7 @@ export function createStage(store: Store, selectedArtifact: (id: string | undefi
if (current.playhead.frame < Math.round(start * frameRate)
|| current.playhead.frame >= Math.round(end * frameRate)) return undefined;
// The present spans the whole canvas; the drawn box is its frame element.
- const drawn = present?.querySelector(`[data-hypit-element-id="${CSS.escape(`${clipId}:frame`)}"]`)
+ const drawn = present?.querySelector(`[data-hypit-element-id="${CSS.escape(`${renderId}:frame`)}"]`)
?? present?.querySelector("[data-hypit-element-id]");
if (drawn === null || drawn === undefined) return undefined;
for (let ancestor: Element | null = drawn; ancestor !== null; ancestor = ancestor.parentElement) {
@@ -110,8 +110,8 @@ export function createStage(store: Store, selectedArtifact: (id: string | undefi
// the third way into the same selection.
scaler.addEventListener("click", (event) => {
if (reviewMode) { toggle(); return; }
- const clip = overlay.hitTest(event.clientX, event.clientY);
- if (clip !== undefined) store.select(clip.id, "video");
+ const item = overlay.hitTest(event.clientX, event.clientY);
+ if (item !== undefined) store.select(item.id, "video");
else store.clearSelection();
});
// A broad component frame can cover smaller elements. Offer all actual
@@ -168,7 +168,7 @@ export function createStage(store: Store, selectedArtifact: (id: string | undefi
let muted = false;
let raf = 0;
// The transport counts frames from where it was last told to be. Jumping to a
- // clip mid-playback moves that origin rather than stopping, so playback
+ // Item mid-playback moves that origin rather than stopping, so playback
// carries on from the frame the author asked for.
let fromFrame = 0;
let began = 0;
diff --git a/packages/studio/src/ui/timeline.ts b/packages/studio/src/ui/timeline.ts
index ca01972f..1e6bfb24 100644
--- a/packages/studio/src/ui/timeline.ts
+++ b/packages/studio/src/ui/timeline.ts
@@ -151,7 +151,7 @@ export function createTimeline(store: Store): Timeline {
});
element.addEventListener("keydown", event => { if (event.key === "Escape") closeOverlapMenu(); });
body.addEventListener("scroll", closeOverlapMenu);
- let clipNodes: readonly {
+ let itemNodes: readonly {
readonly node: HTMLElement;
readonly start: number;
readonly end: number;
@@ -198,9 +198,9 @@ export function createTimeline(store: Store): Timeline {
if (next < distance) { nearest = candidate; distance = next; }
};
for (const anchor of state.snapshot.temporalDomains.flatMap((domain) => domain.anchors)) consider(anchor.frame);
- for (const clip of state.snapshot.tracks.flatMap((track) => track.clips)) {
- consider(clip.startFrame);
- consider(clip.endFrameExclusive);
+ for (const item of state.snapshot.tracks.flatMap((track) => track.items)) {
+ consider(item.startFrame);
+ consider(item.endFrameExclusive);
}
return distance <= threshold ? nearest : frame;
};
@@ -226,7 +226,7 @@ export function createTimeline(store: Store): Timeline {
let pointerDownX = 0;
let pointerDownOnItem = false;
let activeEdit: {
- readonly clip: StudioSnapshot["tracks"][number]["clips"][number];
+ readonly item: StudioSnapshot["tracks"][number]["items"][number];
readonly handle: StudioEditHandle;
readonly startFrame: number;
readonly pointerId: number;
@@ -251,23 +251,23 @@ export function createTimeline(store: Store): Timeline {
nextFrame: number,
): { readonly startFrame: number; readonly endFrameExclusive: number } => {
if (state === undefined) return {
- startFrame: edit.clip.startFrame,
- endFrameExclusive: edit.clip.endFrameExclusive,
+ startFrame: edit.item.startFrame,
+ endFrameExclusive: edit.item.endFrameExclusive,
};
const rawDelta = nextFrame - edit.startFrame;
- const delta = Math.max(-edit.clip.startFrame,
- Math.min(state.snapshot.timeline.frameCount - edit.clip.endFrameExclusive, rawDelta));
+ const delta = Math.max(-edit.item.startFrame,
+ Math.min(state.snapshot.timeline.frameCount - edit.item.endFrameExclusive, rawDelta));
if (edit.handle.gesture === "move") return {
- startFrame: edit.clip.startFrame + delta,
- endFrameExclusive: edit.clip.endFrameExclusive + delta,
+ startFrame: edit.item.startFrame + delta,
+ endFrameExclusive: edit.item.endFrameExclusive + delta,
};
if (edit.handle.gesture === "trim-start") return {
- startFrame: Math.min(edit.clip.endFrameExclusive - 1, nextFrame),
- endFrameExclusive: edit.clip.endFrameExclusive,
+ startFrame: Math.min(edit.item.endFrameExclusive - 1, nextFrame),
+ endFrameExclusive: edit.item.endFrameExclusive,
};
return {
- startFrame: edit.clip.startFrame,
- endFrameExclusive: Math.max(edit.clip.startFrame + 1, nextFrame),
+ startFrame: edit.item.startFrame,
+ endFrameExclusive: Math.max(edit.item.startFrame + 1, nextFrame),
};
};
@@ -283,7 +283,7 @@ export function createTimeline(store: Store): Timeline {
};
lanes.addEventListener("pointerdown", (event) => {
pointerDownOnItem = (event.target as HTMLElement).closest(
- ".clip, .temporal-domain-block, .temporal-domain-compact, .temporal-domain-span, .temporal-domain-point",
+ ".studio-item, .temporal-domain-block, .temporal-domain-compact, .temporal-domain-span, .temporal-domain-point",
) !== null;
pointerDownX = event.clientX;
pointerArmed = true;
@@ -355,23 +355,23 @@ export function createTimeline(store: Store): Timeline {
&& resolvedDomainTarget.startAnchorId === edit.handle.domain.startAnchorId
&& resolvedDomainTarget.endAnchorId === edit.handle.domain.endAnchorId
&& (target.kind === "instant"
- ? target.frame === edit.clip.startFrame
- : target.startFrame === edit.clip.startFrame && target.endFrameExclusive === edit.clip.endFrameExclusive)) return;
+ ? target.frame === edit.item.startFrame
+ : target.startFrame === edit.item.startFrame && target.endFrameExclusive === edit.item.endFrameExclusive)) return;
if (resolvedDomainTarget?.kind === "point"
&& edit.handle.domain?.kind === "point"
&& resolvedDomainTarget.anchorId === edit.handle.domain.anchorId
&& (target.kind === "instant"
- ? target.frame === edit.clip.startFrame
- : target.startFrame === edit.clip.startFrame && target.endFrameExclusive === edit.clip.endFrameExclusive)) return;
+ ? target.frame === edit.item.startFrame
+ : target.startFrame === edit.item.startFrame && target.endFrameExclusive === edit.item.endFrameExclusive)) return;
if (resolvedDomainTarget === undefined
&& (target.kind === "instant"
- ? target.frame === edit.clip.startFrame
- : target.startFrame === edit.clip.startFrame && target.endFrameExclusive === edit.clip.endFrameExclusive)) return;
+ ? target.frame === edit.item.startFrame
+ : target.startFrame === edit.item.startFrame && target.endFrameExclusive === edit.item.endFrameExclusive)) return;
element.dispatchEvent(new CustomEvent("studio:write", { detail: { state: "saving" } }));
void applyStudioMutation({
type: "timeline.adjust",
revision: state.snapshot.revision,
- entityId: edit.clip.id,
+ itemId: edit.item.id,
gesture: edit.handle.gesture,
target,
}).then(() => {
@@ -496,13 +496,13 @@ export function createTimeline(store: Store): Timeline {
snapshot: StudioSnapshot,
domain: StudioSnapshot["temporalDomains"][number],
): void => {
- if (domain.items.length === 0 || domain.lanes.length === 0) return;
+ if (domain.lanes.length === 0) return;
const laneHeight = domain.lanes.reduce((height, lane) => height + lane.heightPx, itemMetrics.insetYPx * 2);
const label = createTrackLabel(domain.presentation.label ?? domain.id, domain.presentation.tone,
domain.presentation.icon, "", laneHeight);
label.title = `${domain.items.length} temporal items`;
label.classList.add("track-label-temporal-domain");
- label.style.height = `calc(var(--timeline-ruler-height) + ${laneHeight}px)`;
+ label.style.height = `${laneHeight}px`;
labels.append(label);
const lane = document.createElement("div");
@@ -604,20 +604,12 @@ export function createTimeline(store: Store): Timeline {
const buildTrack = (
snapshot: StudioSnapshot,
track: StudioSnapshot["tracks"][number],
- nextClipNodes: { node: HTMLElement; start: number; end: number; id: string; selectionGroup?: string }[],
+ nextItemNodes: { node: HTMLElement; start: number; end: number; id: string; selectionGroup?: string }[],
attached = false,
): void => {
- const trackBands = track.binding.bands ?? [];
- const banded = trackBands.length > 0;
- const layout = [
- ...trackBands.filter(band => band.placement === "before"),
- { id: undefined, heightPx: track.binding.lane.heightPx, display: "content" as const, tone: track.binding.tone },
- ...trackBands.filter(band => band.placement === "after"),
- ];
- const totalHeight = layout.reduce((sum, band) => sum + band.heightPx, 0)
- + (banded ? 2 * itemMetrics.insetYPx : 0);
+ const totalHeight = track.binding.lane.heightPx;
const tone = track.binding.tone;
- const displayedItems = track.clips.length;
+ const displayedItems = track.items.length;
const label = createTrackLabel(
displayTrackName(track),
tone,
@@ -630,65 +622,60 @@ export function createTimeline(store: Store): Timeline {
labels.append(label);
const trackBody = document.createElement("div");
- trackBody.className = banded ? "timeline-track timeline-track-banded" : "timeline-track";
+ trackBody.className = "timeline-track";
trackBody.dataset.track = track.id;
trackBody.style.height = `${totalHeight}px`;
const materialMounts: {
readonly target: HTMLElement;
- readonly preview: Extract<StudioSnapshot["tracks"][number]["clips"][number]["display"]["layers"][number], { readonly kind: "preview" }>["preview"];
+ readonly preview: Extract<StudioSnapshot["tracks"][number]["items"][number]["display"]["layers"][number], { readonly kind: "preview" }>["preview"];
}[] = [];
- for (const band of layout) {
- const tone = band.tone ?? track.binding.tone;
- const laneHeight = band.heightPx;
- const lane = document.createElement("div");
- lane.className = `lane track-tone-${tone} track-facet-${track.binding.facet}${attached ? " lane-attached" : ""}`;
- lane.style.height = `${laneHeight}px`;
- if (banded) lane.classList.add("track-band", `track-band-${band.display}`);
- if (band.id !== undefined) lane.dataset.band = band.id;
- lane.style.setProperty("--lane-height", `${laneHeight}px`);
- const laneWidth = lanes.clientWidth;
- // Stable order preserves Companion projection order when stack levels tie.
- for (const clip of track.clips.filter(clip => clip.band === band.id).sort((a, b) => a.stackOrder - b.stackOrder)) {
- const from = place(clip.startFrame, snapshot.timeline.frameCount, zoom.window());
- const to = place(clip.endFrameExclusive, snapshot.timeline.frameCount, zoom.window());
+ const lane = document.createElement("div");
+ lane.className = `lane track-tone-${tone} track-facet-${track.binding.facet}${attached ? " lane-attached" : ""}`;
+ lane.style.height = `${totalHeight}px`;
+ lane.style.setProperty("--lane-height", `${totalHeight}px`);
+ const laneWidth = lanes.clientWidth;
+ // Stable order preserves Companion projection order when stack levels tie.
+ for (const item of [...track.items].sort((a, b) => a.stackOrder - b.stackOrder)) {
+ const from = place(item.startFrame, snapshot.timeline.frameCount, zoom.window());
+ const to = place(item.endFrameExclusive, snapshot.timeline.frameCount, zoom.window());
if (to <= 0 || from >= 1) continue;
const node = document.createElement("button");
node.type = "button";
- node.className = `clip clip-tone-${tone} clip-facet-${track.binding.facet} clip-chrome-${clip.presentation.chrome}`;
- node.classList.toggle("clip-editable", clip.editHandles.some((handle) => handle.enabled));
- node.dataset.clip = clip.id;
- node.setAttribute("aria-label", clip.display.title);
+ node.className = `studio-item studio-item-tone-${tone} studio-item-facet-${track.binding.facet} studio-item-chrome-${item.presentation.chrome}`;
+ node.classList.toggle("studio-item-editable", item.editHandles.some((handle) => handle.enabled));
+ node.dataset.item = item.id;
+ node.setAttribute("aria-label", item.display.title);
node.style.left = `${from * 100}%`;
node.style.width = `max(2px, ${Math.max(0, to - from) * 100}%)`;
const visibleWidthPx = visibleItemWidth(from, to, laneWidth);
- node.classList.toggle("clip-preview-wide", visibleWidthPx >= 92);
- node.title = `${clip.display.title} · ${clip.startFrame}-${clip.endFrameExclusive}f`;
- node.innerHTML = `<span class="clip-head"><span class="clip-name"></span><span class="clip-meta"></span></span><span class="clip-body"><span class="clip-layers" aria-hidden="true"></span></span><span class="clip-boundary" aria-hidden="true"></span><span class="clip-selection" aria-hidden="true"></span>`;
- const layers = node.querySelector<HTMLElement>(".clip-layers")!;
- clip.display.layers.forEach((layer, index) => {
+ node.classList.toggle("studio-item-preview-wide", visibleWidthPx >= 92);
+ node.title = `${item.display.title} · ${item.startFrame}-${item.endFrameExclusive}f`;
+ node.innerHTML = `<span class="studio-item-head"><span class="studio-item-name"></span><span class="studio-item-meta"></span></span><span class="studio-item-body"><span class="studio-item-layers" aria-hidden="true"></span></span><span class="studio-item-boundary" aria-hidden="true"></span><span class="studio-item-selection" aria-hidden="true"></span>`;
+ const layers = node.querySelector<HTMLElement>(".studio-item-layers")!;
+ item.display.layers.forEach((layer, index) => {
const layerNode = document.createElement("span");
- layerNode.className = `clip-layer clip-layer-${layer.kind} clip-layer-role-${layer.role}`;
+ layerNode.className = `studio-item-layer studio-item-layer-${layer.kind} studio-item-layer-role-${layer.role}`;
layerNode.style.zIndex = String(index + 1);
if (layer.kind === "text") {
layerNode.textContent = layer.text;
} else {
- layerNode.classList.add(`clip-layer-layout-${layer.layout}`);
+ layerNode.classList.add(`studio-item-layer-layout-${layer.layout}`);
materialMounts.push({ target: layerNode, preview: layer.preview });
}
layers.append(layerNode);
});
- const metaText = clip.presentation.chrome === "point"
- ? `${(clip.startFrame / fps(snapshot)).toFixed(2)}s`
- : `${((clip.endFrameExclusive - clip.startFrame) / fps(snapshot)).toFixed(2)}s`;
- const headerLabel = node.querySelector<HTMLElement>(".clip-name")!;
- node.querySelector(".clip-meta")!.textContent = metaText;
- headerLabel.textContent = clip.display.title;
+ const metaText = item.presentation.chrome === "point"
+ ? `${(item.startFrame / fps(snapshot)).toFixed(2)}s`
+ : `${((item.endFrameExclusive - item.startFrame) / fps(snapshot)).toFixed(2)}s`;
+ const headerLabel = node.querySelector<HTMLElement>(".studio-item-name")!;
+ node.querySelector(".studio-item-meta")!.textContent = metaText;
+ headerLabel.textContent = item.display.title;
node.addEventListener("pointerdown", (event) => {
const rect = node.getBoundingClientRect();
const edge = Math.min(8, Math.max(4, rect.width / 3));
const nearStart = event.clientX - rect.left <= edge;
const nearEnd = rect.right - event.clientX <= edge;
- const handle = clip.editHandles.find((candidate) =>
+ const handle = item.editHandles.find((candidate) =>
candidate.enabled
&& ((candidate.gesture === "trim-start" && nearStart)
|| (candidate.gesture === "trim-end" && nearEnd)
@@ -700,7 +687,7 @@ export function createTimeline(store: Store): Timeline {
? rawFrameAt(event.clientX)
: frameAt(event.clientX);
activeEdit = {
- clip,
+ item,
handle,
startFrame: pointerFrame,
pointerId: event.pointerId,
@@ -710,17 +697,16 @@ export function createTimeline(store: Store): Timeline {
};
node.classList.add("editing");
try { lanes.setPointerCapture(event.pointerId); } catch { /* local pointer */ }
- store.select(clip.id, "timeline");
+ store.select(item.id, "timeline");
return;
}
- store.select(clip.id, "timeline");
+ store.select(item.id, "timeline");
});
- node.addEventListener("dblclick", () => store.seek(clip.startFrame, "timeline"));
- nextClipNodes.push({ node, start: clip.startFrame, end: clip.endFrameExclusive, id: clip.id, ...(clip.selectionGroup === undefined ? {} : { selectionGroup: clip.selectionGroup }) });
- lane.append(node);
- }
- trackBody.append(lane);
+ node.addEventListener("dblclick", () => store.seek(item.startFrame, "timeline"));
+ nextItemNodes.push({ node, start: item.startFrame, end: item.endFrameExclusive, id: item.id, ...(item.selectionGroup === undefined ? {} : { selectionGroup: item.selectionGroup }) });
+ lane.append(node);
}
+ trackBody.append(lane);
rows.append(trackBody);
// Cached storyboards render synchronously and need connected, measurable targets.
for (const item of materialMounts) mountMaterialPreview(item.target, item.preview);
@@ -735,20 +721,20 @@ export function createTimeline(store: Store): Timeline {
const corner = document.createElement("div");
corner.className = "label-corner";
userText(corner, "");
- if (snapshot.temporalDomains.every((domain) => domain.items.length === 0)) labels.append(corner);
+ labels.append(corner);
for (const domain of snapshot.temporalDomains) buildTemporalDomainLane(snapshot, domain);
- const nextClipNodes: { node: HTMLElement; start: number; end: number; id: string; selectionGroup?: string }[] = [];
+ const nextItemNodes: { node: HTMLElement; start: number; end: number; id: string; selectionGroup?: string }[] = [];
for (const track of snapshot.tracks) {
const attachedTo = track.binding.lane.attachedTo;
if (attachedTo !== undefined) continue;
- buildTrack(snapshot, track, nextClipNodes);
+ buildTrack(snapshot, track, nextItemNodes);
const slot = track.binding.lane.groupId ?? track.binding.groupId;
const attachments = attachedTracks(snapshot, slot, track.binding.groupId);
for (const attachment of attachments) {
- buildTrack(snapshot, attachment, nextClipNodes, true);
+ buildTrack(snapshot, attachment, nextItemNodes, true);
}
}
- clipNodes = nextClipNodes;
+ itemNodes = nextItemNodes;
drawRuler(snapshot);
// Replacing every row briefly collapses the scroll surface. Preserve the
// vertical reading position when a horizontal pan rebuilds the window.
@@ -768,8 +754,8 @@ export function createTimeline(store: Store): Timeline {
playhead.classList.toggle("outside", position < 0 || position > lanes.clientWidth);
playheadGrip.classList.toggle("outside", position < 0 || position > lanes.clientWidth);
timelineTime.textContent = frameTimecode(snapshot, head.frame);
- const chosen = selection.kind === "clip" ? store.clip(selection.clipId) : undefined;
- for (const item of clipNodes) {
+ const chosen = selection.kind === "item" ? store.item(selection.itemId) : undefined;
+ for (const item of itemNodes) {
const selected = chosen !== undefined && (chosen.id === item.id
|| (chosen.selectionGroup !== undefined && chosen.selectionGroup === item.selectionGroup));
item.node.classList.toggle("selected", selected);
diff --git a/packages/studio/src/ui/zoom.ts b/packages/studio/src/ui/zoom.ts
index 52fcddbf..bdd1a0a8 100644
--- a/packages/studio/src/ui/zoom.ts
+++ b/packages/studio/src/ui/zoom.ts
@@ -109,7 +109,7 @@ export function createZoom(): Zoom {
subscribe(listen) { listeners.push(listen); listen(window_); },
/**
* Pinching over the strip zooms about the point under the fingers, which is
- * how every other timeline behaves and the only gesture that keeps the clip
+ * how every other timeline behaves and the only gesture that keeps the Item
* being read where it was.
*/
pinch(at: number, factor: number) {
diff --git a/packages/studio/test/attribute-groups.test.ts b/packages/studio/test/attribute-groups.test.ts
index 1d283b4e..fa8b79b7 100644
--- a/packages/studio/test/attribute-groups.test.ts
+++ b/packages/studio/test/attribute-groups.test.ts
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import test from "node:test";
import { parseStructuredElement } from "@hypit/markup";
import { audioTrackModuleRef } from "@hypit/audio-track";
-import type { StudioPlacement, StudioEntityDraft, StudioTrackCompanion } from "@hypit/studio-companion";
+import type { StudioPlacement, StudioItemDraft, StudioTrackCompanion } from "@hypit/studio-companion";
import { audioTrackStudioTrackCompanions } from "../../audio-track/src/studio.js";
import { sourceBindingsForDraft, inspectorFieldsForBindings } from "../src/parameters.js";
import { serializeAttributeGroup, validateParameterValue } from "../src/parameter-values.js";
@@ -12,7 +12,7 @@ function fields(text: string, companion: Pick<StudioTrackCompanion, "bindings" |
const placement = { ...element, id: "music", tag: element.name, surface: "item", module: audioTrackModuleRef,
sourcePath: "main.svml", references: [], referenceAttributes: {}, records: [], outputs: [], outputPorts: [], values: [], children: [],
} as unknown as StudioPlacement;
- const draft: StudioEntityDraft = { id: "music", authoredId: "music", display: { title: "Music", layers: [] }, startFrame: 0, endFrameExclusive: 90, stackOrder: 0 };
+ const draft: StudioItemDraft = { id: "music", authoredId: "music", display: { title: "Music", layers: [] }, startFrame: 0, endFrameExclusive: 90, stackOrder: 0 };
return inspectorFieldsForBindings(draft, sourceBindingsForDraft({ root: "/project", files: [{ path: "main.svml", text, language: "svml" }],
placement, draft, declarations: companion.bindings! }), companion.inspector!);
}
diff --git a/packages/studio/test/material-companions.test.ts b/packages/studio/test/material-companions.test.ts
index 92f6a532..c02737f6 100644
--- a/packages/studio/test/material-companions.test.ts
+++ b/packages/studio/test/material-companions.test.ts
@@ -5,6 +5,7 @@ import { audioTrackTypes } from "@hypit/audio-track";
import { visualTrackTypes } from "@hypit/visual-track";
import type { StudioTrackCompanionContext } from "@hypit/studio-companion";
import { audioTrackStudioTrackCompanions } from "../../audio-track/src/studio.js";
+import { textFineStudioTrackCompanions } from "../../text-fine/src/studio.js";
import { visualTrackStudioTrackCompanions } from "../../visual-track/src/studio.js";
for (const kind of ["audio", "visual"] as const) {
@@ -35,12 +36,12 @@ for (const kind of ["audio", "visual"] as const) {
} as unknown as StudioTrackCompanionContext;
const companion = kind === "audio" ? audioTrackStudioTrackCompanions[0]!
: visualTrackStudioTrackCompanions.find((entry) => entry.id === "visual")!;
- const entities = companion.project!(context);
- assert.deepEqual(entities.map((entry) => entry.display.title), ["my-chosen-name", "assets.shared.material", "assets.shared.material"]);
- assert.deepEqual(entities.map((entry) => entry.authoredId), subjects);
- assert.equal(new Set(entities.map((entry) => entry.id)).size, 3);
- assert.deepEqual(entities.map((entry) => entry.elementRange), subjects.map(child).map((entry) => entry.range));
- assert.deepEqual(entities.map((entry) => [entry.startFrame, entry.endFrameExclusive]), [[0, 20], [10, 30], [20, 40]]);
+ const items = companion.project!(context);
+ assert.deepEqual(items.map((entry) => entry.display.title), ["my-chosen-name", "assets.shared.material", "assets.shared.material"]);
+ assert.deepEqual(items.map((entry) => entry.authoredId), subjects);
+ assert.equal(new Set(items.map((entry) => entry.id)).size, 3);
+ assert.deepEqual(items.map((entry) => entry.elementRange), subjects.map(child).map((entry) => entry.range));
+ assert.deepEqual(items.map((entry) => [entry.startFrame, entry.endFrameExclusive]), [[0, 20], [10, 30], [20, 40]]);
});
}
@@ -52,3 +53,11 @@ test("audio source time stays explicit and gain remains a bounded mixing control
const gain = companion.inspector!.find(field => field.binding === "gain")!;
assert.equal(gain.domain, "how"); assert.equal(gain.number?.scale, 100); assert.equal(gain.number?.maximum, 6400);
});
+
+test("official Companions expose author families without changing terminal facets", () => {
+ assert.equal(visualTrackStudioTrackCompanions[0]?.family, "visual");
+ assert.equal(audioTrackStudioTrackCompanions[0]?.family, "audio");
+ assert.deepEqual(textFineStudioTrackCompanions.map((companion) => companion.family), [
+ "typography", "typography", "typography",
+ ]);
+});
diff --git a/packages/studio/test/parameter-companions.test.ts b/packages/studio/test/parameter-companions.test.ts
index 0b62005c..d6c272fa 100644
--- a/packages/studio/test/parameter-companions.test.ts
+++ b/packages/studio/test/parameter-companions.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import type { StudioPlacement, StudioEntityDraft, StudioParameterCompanion } from "@hypit/studio-companion";
+import type { StudioPlacement, StudioItemDraft, StudioParameterCompanion } from "@hypit/studio-companion";
import { studioContributionFromPackage, createStudioCompanionFacet } from "@hypit/studio-companion";
import { composeParameterDeclarations, sourceBindingsForDraft, inspectorFieldsForBindings } from "../src/parameters.js";
import { StudioCompanionRegistry } from "../src/studio-registry.js";
@@ -25,7 +25,7 @@ test("a project object contributes its own parameters to a consumer and inserts
const split = text.indexOf('<p:Pan');
const owner = { ...placement("view", 0, split), referenceAttributes: { style: "pan" }, resolvedReferenceAttributes: { style: "pan" } };
const style = placement("pan", split, text.length);
- const draft: StudioEntityDraft = { id: "use", authoredId: "view", display: { title: "Pan", layers: [] }, startFrame: 0, endFrameExclusive: 30, stackOrder: 0 };
+ const draft: StudioItemDraft = { id: "use", authoredId: "view", display: { title: "Pan", layers: [] }, startFrame: 0, endFrameExclusive: 30, stackOrder: 0 };
const declarations = composeParameterDeclarations({ registry, placement: owner, placements: [owner, style], draft,
bindings: [{ name: "style", companion: true }], inspector: [] });
const fields = inspectorFieldsForBindings(draft, sourceBindingsForDraft({ root: "/workspace", files: [{ path: "main.svml", text, language: "svml" }],
diff --git a/packages/studio/test/parameters.test.ts b/packages/studio/test/parameters.test.ts
index 001bb690..7b41c53a 100644
--- a/packages/studio/test/parameters.test.ts
+++ b/packages/studio/test/parameters.test.ts
@@ -27,7 +27,8 @@ const temporalDomain: StudioTemporalDomainView = {
{ id: "segment:a:token:1:end", kind: "token-end", frame: 12 },
{ id: "segment:a:end", kind: "segment-end", frame: 12 },
],
- items: [{ kind: "span", appearance: "block", id: "claim", laneId: "intent", label: "claim",
+ items: [],
+ editItems: [{ kind: "span", appearance: "block", id: "claim", laneId: "intent", label: "claim",
source: { type: narrativeSourceIdentity.type, kind: "selection", id: "claim" }, editable: true,
startAnchorId: "segment:a:token:1:start",
endAnchorId: "segment:a:token:1:end",
@@ -38,7 +39,7 @@ const temporalDomain: StudioTemporalDomainView = {
source: { path: "main.svml", content: { start: 0, end: 100 } },
};
-const withMoment: StudioTemporalDomainView = { ...temporalDomain, items: [...temporalDomain.items, {
+const withMoment: StudioTemporalDomainView = { ...temporalDomain, editItems: [...temporalDomain.editItems, {
kind: "point", appearance: "marker", id: "beat", laneId: "intent", label: "beat",
source: { type: narrativeSourceIdentity.type, kind: "moment", id: "beat" }, editable: true,
anchorId: "segment:a:token:1:end", frame: 12,
@@ -53,6 +54,7 @@ test("structured parameter values validate and serialize through the generic SVS
test("timeline gestures resolve through the shared Selection identity", () => {
const temporal: StudioTemporalLineage = {
+ record: "claim.window",
projection: {
kind: "window",
start: {
@@ -85,6 +87,7 @@ test("timeline gestures resolve through the shared Selection identity", () => {
test("moving a Moment projection resolves to the shared Moment identity", () => {
const handles = resolveTimelineEditHandles([], {
+ record: "beat.instant",
projection: {
kind: "instant", expression: "moment.cue", reference: "moment.cue", frame: 12,
source: { ...narrativeSourceIdentity, kind: "moment", id: "beat" },
@@ -120,19 +123,23 @@ test("at/for and until/for derive complementary semantic and duration inverses",
authority: { kind: "parameter" as const, binding: "for", relation: "before-end" as const },
};
const atFor = resolveTimelineEditHandles([duration], {
+ record: "beat.after",
projection: { kind: "window", start: moment, end: after, startFrame: 12, endFrameExclusive: 20 },
}, [withMoment]);
assert.deepEqual(atFor.map((handle) => [handle.gesture, handle.domain?.kind, handle.sources?.map((source) => source.role)]), [
- ["move", "point", undefined],
+ ["move", "point", ["duration"]],
+ ["trim-start", "point", ["duration"]],
["trim-end", undefined, ["duration"]],
]);
const untilFor = resolveTimelineEditHandles([duration], {
+ record: "beat.before",
projection: { kind: "window", start: before, end: moment, startFrame: 4, endFrameExclusive: 12 },
}, [withMoment]);
assert.deepEqual(untilFor.map((handle) => [handle.gesture, handle.domain?.kind, handle.sources?.map((source) => source.role)]), [
- ["move", "point", undefined],
+ ["move", "point", ["duration"]],
["trim-start", undefined, ["duration"]],
+ ["trim-end", "point", ["duration"]],
]);
});
@@ -156,6 +163,7 @@ test("absolute Window edits work without a semantic lane and use the Companion's
const handles = resolveTimelineEditHandles(
parameters,
{
+ record: "absolute.window",
projection: {
kind: "window",
start: {
@@ -199,7 +207,7 @@ test("independent reference endpoints expose local edits without claiming their
}));
const handles = resolveTimelineEditHandles(bindings, { projection: {
kind: "window", start: endpoints[0]!, end: endpoints[1]!, startFrame: 2, endFrameExclusive: 20,
- } }, [temporalDomain]);
+ }, record: "references.window" }, [temporalDomain]);
assert.deepEqual(handles.map(({ gesture, enabled, domain, sources }) => ({ gesture, enabled, domain, roles: sources?.map(source => source.role) })), [
{ gesture: "move", enabled: true, domain: undefined, roles: ["start", "end"] },
{ gesture: "trim-start", enabled: true, domain: undefined, roles: ["start"] },
@@ -225,7 +233,7 @@ test("parameter Source paths stay relative to the author workspace", () => {
referenceAttributes: {}, referenceTypes: {}, references: [],
},
draft: {
- id: "entity:item", authoredId: "item", display: { title: "item", layers: [] },
+ id: "item:item", authoredId: "item", display: { title: "item", layers: [] },
startFrame: 1, endFrameExclusive: 2, stackOrder: 0,
elementRange: { start: 0, end: text.length },
},
@@ -257,7 +265,7 @@ test("nested declared references reach the font attribute, not the referring Sty
const parameters = sourceBindingsForDraft({
root: "/workspace", files: [{ path: "main.svml", text, language: "svml" }],
placement: track, placements: [track, style, font],
- draft: { id: "track:entity", authoredId: "track", display: { title: "track", layers: [] },
+ draft: { id: "track:item", authoredId: "track", display: { title: "track", layers: [] },
startFrame: 0, endFrameExclusive: 10, stackOrder: 0, elementRange: track.range },
declarations: [{ name: "style", referenced: [{ name: "font", referenced: [{ name: "family", writable: true }] }] }],
});
@@ -267,7 +275,7 @@ test("nested declared references reach the font attribute, not the referring Sty
assert.equal(family?.writable, true);
});
-test("a derived entity follows its actual Style and Companion-owned Recipe presentation", () => {
+test("a derived Item follows its actual Style and Companion-owned Recipe presentation", () => {
const main = "<scene:Track id=\"captions\" layout={baseline-layout}/>";
const sheet = `<?svml using="@hypit/recipe@1"?>
<sheet version="1">
diff --git a/packages/studio/test/registry.test.ts b/packages/studio/test/registry.test.ts
index 7426f924..6e7013ba 100644
--- a/packages/studio/test/registry.test.ts
+++ b/packages/studio/test/registry.test.ts
@@ -21,31 +21,34 @@ test("Companion origin matching includes the exact module version", () => {
), undefined);
});
-test("internal bands keep entities in their Track and own their Inspector bindings", () => {
+test("Inspector objects stay out of the Timeline while child Tracks remain available", () => {
const companion: StudioTrackCompanion = {
id: "cards", role: "track", family: "cards", tone: "blue",
output: { type: compositionTypes.visualTrack },
- bands: [{ id: "rules", placement: "after", heightPx: 15, display: "label",
+ inspectorObjects: [{
+ id: "rules", label: "Presentation Rules",
bindings: [{ name: "style" }],
inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "style", label: "Style" }, control: "text" }],
+ project: () => [{ id: "rule", authoredId: "rule", title: "Layout" }],
}],
attachments: [{ id: "objects", family: "objects", icon: "layers", facet: "visual", lane: { heightPx: 40 } }],
- project: () => [{ id: "rule", authoredId: "rule", band: "rules",
- display: { title: "Layout", layers: [] }, startFrame: 0, endFrameExclusive: 120, stackOrder: 0 }],
+ project: () => [{ id: "card", authoredId: "card",
+ display: { title: "Card", layers: [] }, startFrame: 0, endFrameExclusive: 120, stackOrder: 0 }],
};
const registry = new StudioCompanionRegistry([companion]);
const track = { typeRef: compositionTypes.visualTrack, outputRef: "cards.visual", name: "cards", type: "VisualTrack",
candidateOrigin: "source", role: "track", value: {}, trace: { references: [], outputPorts: [] } } as const;
assert.deepEqual(registry.trackAttachments(track).map(item => item.attachmentId), ["objects"]);
- assert.deepEqual(registry.bindTrack(track).bands, [{ id: "rules", placement: "after", heightPx: 15, display: "label" }]);
- assert.deepEqual(registry.bindingDeclarations(track, undefined, undefined, "rules"), [{ name: "style" }]);
- assert.equal(registry.inspectorDeclarations(track, undefined, undefined, "rules")[0]?.label, "Style");
const context = { track, values: new Map(), spans: [], temporalBindings: [], temporalDomains: [], generic: () => [] };
const [draft] = registry.projectTrack(context);
- assert.equal(draft?.lane, undefined);
- assert.equal(draft?.band, "rules");
- const invalid = new StudioCompanionRegistry([{ ...companion, project: () => [{ ...draft!, band: "missing" }] }]);
- assert.throws(() => invalid.projectTrack(context), /declared band/);
- const ambiguous = new StudioCompanionRegistry([{ ...companion, project: () => [{ ...draft!, lane: "objects" }] }]);
- assert.throws(() => ambiguous.projectTrack(context), /declared band/);
+ assert.equal(draft?.display.title, "Card");
+ const [rule] = registry.projectInspectorObjects(context);
+ assert.equal(rule?.label, "Presentation Rules");
+ assert.deepEqual(rule?.bindings, [{ name: "style" }]);
+ assert.equal(rule?.inspector[0]?.label, "Style");
+ assert.equal(rule?.draft.title, "Layout");
+ const invalid = new StudioCompanionRegistry([{ ...companion,
+ inspectorObjects: [{ ...companion.inspectorObjects![0]!, project: () => [rule!.draft, rule!.draft] }],
+ }]);
+ assert.throws(() => invalid.projectInspectorObjects(context), /repeats Inspector object/);
});
diff --git a/packages/studio/test/semantic-gesture.test.ts b/packages/studio/test/semantic-gesture.test.ts
index 434c48d0..b7d3166c 100644
--- a/packages/studio/test/semantic-gesture.test.ts
+++ b/packages/studio/test/semantic-gesture.test.ts
@@ -29,20 +29,25 @@ const choose = (h: StudioEditHandle, from: number, to: number, list = anchors) =
anchors: list, handle: h, pointerStart: from, pointerNow: to, frameCount: 100,
});
-test("Selection move advances both ends one stop, changes duration, and writes back through Script", () => {
- const target = choose(handle, 0, 5)!;
+test("Selection move requires one exact frame delta at both semantic endpoints", () => {
+ const movingAnchors = anchors.filter((anchor, index) =>
+ ![0, 20, 40].includes(anchor.frame)
+ || (anchor.frame === 0 && anchor.id === selection.startAnchorId)
+ || (anchor.frame === 20 && anchor.id === selection.endAnchorId)
+ || (anchor.frame === 40 && index === anchors.findIndex((candidate) => candidate.frame === 40)));
+ const target = choose(handle, 0, 20, movingAnchors)!;
assert.equal(target.kind, "span");
if (target.kind !== "span") return;
- assert.deepEqual(domainGestureSpan(anchors, handle, target), { startFrame: 5, endFrameExclusive: 40 });
+ assert.deepEqual(domainGestureSpan(movingAnchors, handle, target), { startFrame: 20, endFrameExclusive: 40 });
const rewritten = adjustScriptSelection({ sourceName: "gesture", source, parsed: narrative, adjustment: { id: "proof", ...target } });
const next = parseScript("gesture", rewritten).selections[0]!;
assert.equal(next.startAnchorId, target.startAnchorId);
assert.equal(next.endAnchorId, target.endAnchorId);
const moved: StudioEditHandle = { ...handle, domain: target, temporal: {
- kind: "window", start: endpoint("start", 5), end: endpoint("end", 40), startFrame: 5, endFrameExclusive: 40,
+ kind: "window", start: endpoint("start", 20), end: endpoint("end", 40), startFrame: 20, endFrameExclusive: 40,
} };
- const back = choose(moved, 5, 0)!;
- assert.deepEqual(domainGestureSpan(anchors, moved, back), { startFrame: 0, endFrameExclusive: 20 });
+ const back = choose(moved, 20, 0, movingAnchors)!;
+ assert.deepEqual(domainGestureSpan(movingAnchors, moved, back), { startFrame: 0, endFrameExclusive: 20 });
});
test("coincident anchors preserve the current identity without preferring starts to ends", () => {
@@ -52,6 +57,12 @@ test("coincident anchors preserve the current identity without preferring starts
assert.equal(choose(point, 20, 40)?.kind, "span");
});
+test("a drag does not silently choose between distinct identities at a new coincident stop", () => {
+ const duplicate = { ...anchors[0]!, id: "another-anchor", frame: 40 };
+ const point: StudioEditHandle = { ...handle, temporal: endpoint("end", 20) };
+ assert.equal(choose(point, 20, 40, [...anchors, duplicate]), undefined);
+});
+
test("a directly selected boundary remains editable even when the raw range reverses in time", () => {
const overlapping = anchors.map((anchor) => anchor.id === selection.startAnchorId ? { ...anchor, frame: 30 } : anchor);
const point: StudioEditHandle = { ...handle, temporal: endpoint("start", 30) };
@@ -75,6 +86,19 @@ test("dragging a bound Moment keeps an event-and-duration Window intact", () =>
assert.deepEqual(domainGestureSpan(anchors, timed, target), { startFrame: 40, endFrameExclusive: 48 });
});
+test("trimming a point-anchored Window moves only the selected boundary", () => {
+ const momentSource = { ...temporalSource, kind: "moment", id: "beat" } as const;
+ const moment: StudioTemporalInstantProjection = { kind: "instant", frame: 20, expression: "moment.cue", reference: "moment.cue", source: momentSource,
+ authority: { kind: "domain", source: momentSource, boundary: "cue" } };
+ const timed: StudioEditHandle = { ...handle, gesture: "trim-start", domain: { kind: "point", companion: "script", domainId: "story",
+ itemId: "beat", anchorId: selection.endAnchorId }, temporal: {
+ kind: "window", start: moment, end: { ...moment, frame: 28, authority: { kind: "parameter", binding: "for", relation: "after-start" } },
+ startFrame: 20, endFrameExclusive: 28,
+ } };
+ const target = choose(timed, 20, 5)!;
+ assert.deepEqual(domainGestureSpan(anchors, timed, target), { startFrame: 5, endFrameExclusive: 28 });
+});
+
test("offset edits cross zero without losing the explicit editable parameter", () => {
assert.equal(formatTemporalPointEdit("moment.cue", 12, 10), "moment.cue+2f");
diff --git a/packages/studio/test/snapshot-range.test.ts b/packages/studio/test/snapshot-range.test.ts
index e2bc1aa1..ac67d126 100644
--- a/packages/studio/test/snapshot-range.test.ts
+++ b/packages/studio/test/snapshot-range.test.ts
@@ -1,17 +1,19 @@
import assert from "node:assert/strict";
import test from "node:test";
import { compositionTypes } from "@hypit/composition";
+import { temporalTypes } from "@hypit/temporal";
+import type { StudioPlacement, StudioTemporalDeclarationCompanion } from "@hypit/studio-companion";
import { snapshot } from "../src/snapshot.js";
import type { StudioProjection } from "../src/projection.js";
import { StudioCompanionRegistry } from "../src/studio-registry.js";
import { fallbackStudioTrackCompanions } from "../src/fallback-companions.js";
-test("a pure-MG work keeps its declared extent even when an editor entity extends beyond it", () => {
+test("a pure-MG work keeps its declared extent even when a Studio Item extends beyond it", () => {
const built = { source: { observations: { placements: [], temporalDomains: [] } },
tracks: [{ outputRef: "art.visual", name: "art.visual", typeRef: compositionTypes.visualTrack,
trace: { outputPorts: [], references: [] }, candidateOrigin: "source", value: { presents: [{ id: "scene", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 150 } }] } }],
timeline: { id: "work", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } },
- values: new Map(), temporalBindings: new Map(),
+ values: new Map(), temporalDomainValues: [], temporalValues: [], temporalBindings: new Map(),
} as unknown as StudioProjection;
const result = snapshot(new StudioCompanionRegistry(fallbackStudioTrackCompanions), built, {
revision: 1, path: "main.svml", text: "", run: { path: "main.svrun", targets: [], satisfactions: [] },
@@ -19,7 +21,53 @@ test("a pure-MG work keeps its declared extent even when an editor entity extend
preview: { kind: "html-program", srcdoc: "" }, workspaceRoot: "/project", sourceFiles: [], surfaces: {} as never,
});
assert.equal(result.timeline.frameCount, 90); assert.equal(result.timeline.durationSec, 3);
- assert.equal(result.tracks[0]!.clips[0]!.endFrameExclusive, 150);
- assert.deepEqual(result.temporalDomains, []);
+ assert.equal(result.tracks[0]!.items[0]!.endFrameExclusive, 150);
+ assert.equal("clips" in result.tracks[0]!, false);
+ assert.equal(result.temporalDomains.length, 1);
+ assert.equal(result.temporalDomains[0]!.id, "absolute-declarations");
+ assert.deepEqual(result.temporalDomains[0]!.items, []);
assert.equal("timing" in result.provenance, false);
});
+
+test("direct and projected author time share one read-only declaration row", () => {
+ const directModule = { name: "example/direct", version: "1" };
+ const projectedModule = { name: "example/projected", version: "1" };
+ const placement = (module: typeof directModule, surface: string, id: string, output: string) => ({
+ tag: surface, module, sourcePath: "main.svml", surface, id, range: { start: 0, end: 10 },
+ records: [], values: [], outputs: [output], outputPorts: [{ name: "value", ref: output }], children: [],
+ attributes: {}, attributeValueRanges: {}, referenceAttributes: {}, referenceTypes: {}, references: [],
+ });
+ const placements = [placement(directModule, "window", "direct", "direct.value"),
+ placement(projectedModule, "instant", "projected", "projected.value")];
+ const built = { source: { observations: { placements, temporalDomains: [] } }, tracks: [],
+ timeline: { id: "work", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } },
+ values: new Map(), temporalDomainValues: [], temporalBindings: new Map(), temporalValues: [
+ { id: "direct.value", type: temporalTypes.window, value: {
+ id: "direct", subjectId: "direct",
+ start: { id: "direct.start", subjectId: "direct", timelineId: "work", frame: 3 },
+ end: { id: "direct.end", subjectId: "direct", timelineId: "work", frame: 30 },
+ span: { startFrame: 3, endFrameExclusive: 30 },
+ } },
+ { id: "projected.value", type: temporalTypes.instant, value: {
+ id: "projected", subjectId: "projected", timelineId: "work", frame: 18,
+ } },
+ ],
+ } as unknown as StudioProjection;
+ const declaration = (id: string, module: typeof directModule, surface: string): StudioTemporalDeclarationCompanion => ({
+ id, match: { module, surface }, project: ({ placement: found }: { placement: StudioPlacement }) => found.id === undefined
+ ? [] : [{ id: found.id, label: found.id, output: found.outputPorts[0]!.ref, range: found.range }],
+ });
+ const registry = new StudioCompanionRegistry(fallbackStudioTrackCompanions, { temporalDeclarations: [
+ declaration("direct", directModule, "window"), declaration("projected", projectedModule, "instant"),
+ ] });
+ const result = snapshot(registry, built, {
+ revision: 1, path: "main.svml", text: "", run: { path: "main.svrun", targets: [], satisfactions: [] },
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" }, frameRate: built.timeline.frameRate,
+ preview: { kind: "html-program", srcdoc: "" }, workspaceRoot: "/project", sourceFiles: [], surfaces: {} as never,
+ });
+ assert.equal(result.temporalDomains.length, 1);
+ assert.deepEqual(result.temporalDomains[0]!.items.map((item) => [item.label, item.kind, item.laneId]), [
+ ["direct", "span", "declarations"], ["projected", "point", "declarations"],
+ ]);
+ assert.deepEqual(result.temporalDomains[0]!.editItems, []);
+});
diff --git a/packages/studio/test/temporal-graph.test.ts b/packages/studio/test/temporal-graph.test.ts
index 512bbbb7..9f728d2e 100644
--- a/packages/studio/test/temporal-graph.test.ts
+++ b/packages/studio/test/temporal-graph.test.ts
@@ -4,6 +4,8 @@ import test from "node:test";
import type { BuildState, ProducerStep, TypeRef, TypedRecord } from "@hypit/protocol";
import { executedTemporalBindings } from "../src/temporal-graph.js";
+import { commonTemporalStudioRelations } from "../src/common-temporal-relations.js";
+import { narrativeStudioTemporalRelations } from "../../narrative-temporal/src/studio.js";
const module = (name: string) => ({ name, version: "1" });
const type = (owner: string, name: string): TypeRef => ({ module: module(owner), name });
@@ -14,6 +16,12 @@ const producer = (owner: string, name: string) => ({ module: module(owner), name
const step = (id: string, owner: string, name: string, inputs: ProducerStep["inputs"], outputs: ProducerStep["outputs"]): ProducerStep => ({
id, producer: producer(owner, name), inputs, outputs, needs: {},
});
+const relationFor = (relations: typeof commonTemporalStudioRelations) =>
+ (candidate: ProducerStep["producer"], output: string) => relations.find((relation) =>
+ relation.match.producer.module.name === candidate.module.name
+ && relation.match.producer.module.version === candidate.module.version
+ && relation.match.producer.name === candidate.name
+ && relation.match.output === output);
test("Studio reads Instant lineage and author authority from executed graph edges", () => {
const program = [
@@ -52,7 +60,18 @@ test("Studio reads Instant lineage and author authority from executed graph edge
needs: [], outstanding: [], diagnostics: [],
} as unknown as BuildState;
- const bindings = executedTemporalBindings(state, "visual");
+ const opaque = executedTemporalBindings(state, "visual");
+ assert.deepEqual(opaque[0]?.projection, {
+ kind: "instant", expression: "42f", reference: "absolute", frame: 42,
+ source: { timelineId: "speech", type: type("@hypit/temporal", "TemporalInstant"), kind: "resolved", id: "deck.card::cue" },
+ authority: { kind: "fixed" },
+ });
+ const bindings = executedTemporalBindings(state, "visual", (sourceType, value) => {
+ const held = value as { readonly id?: unknown };
+ return sourceType.module.name === "@hypit/narrative" && typeof held.id === "string"
+ ? { companion: "narrative", id: "story-on-speech", kind: sourceType.name === "NarrativeMoment" ? "moment" : "source", itemId: held.id }
+ : undefined;
+ }, relationFor(narrativeStudioTemporalRelations));
assert.equal(bindings.length, 1);
assert.deepEqual(bindings[0], {
record: "point",
@@ -60,8 +79,10 @@ test("Studio reads Instant lineage and author authority from executed graph edge
id: "deck.card::cue",
projection: {
kind: "instant", expression: "moment.cue", reference: "moment.cue", frame: 42,
- source: { timelineId: "speech", type: type("@hypit/narrative", "NarrativeMoment"), kind: "moment", id: "cue" },
- authority: { kind: "domain", source: { timelineId: "speech", type: type("@hypit/narrative", "NarrativeMoment"), kind: "moment", id: "cue" }, boundary: "cue" },
+ source: { timelineId: "speech", type: type("@hypit/narrative", "NarrativeMoment"), kind: "moment", id: "cue",
+ domain: { companion: "narrative", id: "story-on-speech" } },
+ authority: { kind: "domain", source: { timelineId: "speech", type: type("@hypit/narrative", "NarrativeMoment"), kind: "moment", id: "cue",
+ domain: { companion: "narrative", id: "story-on-speech" } }, boundary: "cue" },
},
consumers: [{
step: "append",
@@ -113,7 +134,7 @@ test("Studio reads author parameter authority declared by the Temporal Spec", ()
needs: [], outstanding: [], diagnostics: [],
} as unknown as BuildState;
- const bindings = executedTemporalBindings(state, "visual");
+ const bindings = executedTemporalBindings(state, "visual", undefined, relationFor(commonTemporalStudioRelations));
assert.equal(bindings.length, 1);
assert.deepEqual(bindings[0]?.projection, {
kind: "instant",
@@ -126,6 +147,6 @@ test("Studio reads author parameter authority declared by the Temporal Spec", ()
kind: "timeline",
id: "main",
},
- authority: { kind: "parameter", binding: "at", relation: "direct" },
+ authority: { kind: "parameter", binding: "at", owner: "point-spec:at", relation: "direct" },
});
});
diff --git a/packages/studio/test/temporal-inverse.test.ts b/packages/studio/test/temporal-inverse.test.ts
new file mode 100644
index 00000000..841e1c44
--- /dev/null
+++ b/packages/studio/test/temporal-inverse.test.ts
@@ -0,0 +1,229 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { BuildState, ProducerStep, TypeRef, TypedRecord } from "@hypit/protocol";
+
+import { planTemporalInverse, temporalAuthorBindings } from "../src/temporal-inverse.js";
+import { StudioCompanionRegistry } from "../src/studio-registry.js";
+import { commonTemporalStudioRelations } from "../src/common-temporal-relations.js";
+import { timelineAuthorProducers } from "../../timeline-author/src/manifest.js";
+import { timelineAuthorStudioTemporalRelations } from "../../timeline-author/src/studio.js";
+
+const module = (name: string) => ({ name, version: "1" });
+const type = (owner: string, name: string): TypeRef => ({ module: module(owner), name });
+const record = (id: string, owner: string, name: string, value: unknown): TypedRecord => ({
+ id, type: type(owner, name), value: { kind: "inline", value: value as never },
+});
+const step = (id: string, name: string, inputs: ProducerStep["inputs"], outputs: ProducerStep["outputs"]): ProducerStep => ({
+ id, producer: { module: module("@hypit/temporal"), name }, inputs, outputs, needs: {},
+});
+
+function fixture(): BuildState {
+ const program = [
+ record("timeline", "@hypit/timeline", "Timeline", {
+ id: "main", frameRate: { numerator: 30, denominator: 1 }, frameCount: 100,
+ }),
+ record("start-spec", "@hypit/temporal", "TemporalInstantSpec", {
+ id: "clip.start", subjectId: "clip", projection: { ref: "absolute", at: { unit: "frames", value: 10 } },
+ author: { binding: "from", relation: "direct" },
+ }),
+ record("duration", "@hypit/temporal", "TemporalDuration", { unit: "frames", value: 20 }),
+ record("shift-spec", "@hypit/temporal", "TemporalShiftSpec", {
+ id: "clip.end", subjectId: "clip", direction: 1,
+ author: { binding: "for", relation: "after-start" },
+ }),
+ record("window-spec", "@hypit/temporal", "TemporalWindowSpec", { id: "clip", subjectId: "clip" }),
+ ];
+ const executed = [
+ record("upstream-start", "@hypit/temporal", "TemporalInstant", {
+ id: "clip.start", subjectId: "clip", timelineId: "main", frame: 10,
+ }),
+ record("start", "@hypit/temporal", "TemporalInstant", {
+ id: "clip.start", subjectId: "clip", timelineId: "main", frame: 10,
+ }),
+ record("extent", "@hypit/temporal", "TemporalExtent", {
+ frameRate: { numerator: 30, denominator: 1 }, frameCount: 20,
+ }),
+ record("end", "@hypit/temporal", "TemporalInstant", {
+ id: "clip.end", subjectId: "clip", timelineId: "main", frame: 30,
+ }),
+ record("window", "@hypit/temporal", "TemporalWindow", {
+ id: "clip", subjectId: "clip",
+ start: { id: "clip.start", subjectId: "clip", timelineId: "main", frame: 10 },
+ end: { id: "clip.end", subjectId: "clip", timelineId: "main", frame: 30 },
+ span: { startFrame: 10, endFrameExclusive: 30 },
+ }),
+ ];
+ const steps = [
+ step("project", "project-program-instant", { timeline: "timeline", spec: "start-spec" }, { instant: "upstream-start" }),
+ step("reuse", "reuse-instant", { instant: "upstream-start" }, { instant: "start" }),
+ step("extent", "extent-from-duration", { timeline: "timeline", duration: "duration" }, { extent: "extent" }),
+ step("shift", "shift-instant", { timeline: "timeline", instant: "start", extent: "extent", spec: "shift-spec" }, { instant: "end" }),
+ step("compose", "compose-window", { spec: "window-spec", start: "start", end: "end" }, { window: "window" }),
+ ];
+ return {
+ format: "hypit.build@1",
+ program: { closure: { modules: [] }, records: program },
+ targets: [],
+ plan: { format: "hypit.plan@1", steps, goals: [], outputBindings: [] },
+ status: "complete", records: executed,
+ steps: steps.map(({ id }) => ({ id, status: "complete" as const })),
+ needs: [], outstanding: [], diagnostics: [],
+ } as unknown as BuildState;
+}
+
+const source = '<Clip from="10f" for="20f"/>';
+const fromStart = source.indexOf("10f");
+const forStart = source.indexOf("20f");
+const placement = {
+ sourcePath: "/project/main.svml",
+ authorEndpoints: { from: "author:from", for: "author:for" },
+ records: ["start-spec", "duration", "shift-spec", "window-spec"],
+ attributes: { from: "10f", for: "20f" },
+ referenceAttributes: {},
+ attributeValueRanges: {
+ from: { start: fromStart, end: fromStart + 3 },
+ for: { start: forStart, end: forStart + 3 },
+ },
+ children: [],
+} as unknown as import("../src/observe.js").Placement;
+
+function bindings(state: BuildState) {
+ return temporalAuthorBindings({
+ state,
+ rootRecord: "window",
+ workspaceRoot: "/project",
+ placements: [placement],
+ files: [{ path: "/project/main.svml", text: source, language: "svml" }],
+ });
+}
+
+const plan = (state: BuildState, startFrame: number, endFrameExclusive: number) => planTemporalInverse({
+ state,
+ rootRecord: "window",
+ target: { kind: "window", startFrame, endFrameExclusive },
+ bindings: bindings(state),
+ domainFrame: () => undefined,
+ registry: new StudioCompanionRegistry([], { temporalRelations: commonTemporalStudioRelations }),
+});
+
+test("recursive Temporal inverse crosses reuse and atomically compensates from/for", () => {
+ const state = fixture();
+ assert.deepEqual(bindings(state).map((binding) => [binding.binding, binding.source.endpoint]), [
+ ["start-spec:from", "author:from"],
+ ["shift-spec:for", "author:for"],
+ ]);
+ assert.deepEqual(plan(state, 15, 30).map((write) => [write.source.endpoint, write.replacement]), [
+ ["author:from", "15f"],
+ ["author:for", "15f"],
+ ]);
+});
+
+test("move preserves duration while trim-end changes only the owned extent", () => {
+ const state = fixture();
+ assert.deepEqual(plan(state, 15, 35).map((write) => [write.source.endpoint, write.replacement]), [
+ ["author:from", "15f"],
+ ]);
+ assert.deepEqual(plan(state, 10, 40).map((write) => [write.source.endpoint, write.replacement]), [
+ ["author:for", "30f"],
+ ]);
+});
+
+test("Timeline Author Companion reverses its private Point, Extent and Span graph", () => {
+ const timelineModule = module("@hypit/timeline-author");
+ const authorType = (name: string) => ({ module: timelineModule, name });
+ const program = [
+ record("clock", "@hypit/timeline", "Clock", { frameRate: { numerator: 30, denominator: 1 } }),
+ record("from-duration", "@hypit/timeline-author", "ConstructionDurationSpec", {
+ duration: { unit: "frames", value: 10 },
+ }),
+ record("from-spec", "@hypit/timeline-author", "ConstructionOffsetSpec", {
+ direction: 1, author: { binding: "from", declarationId: "clip", expression: { kind: "absolute" } },
+ }),
+ record("for-spec", "@hypit/timeline-author", "ConstructionDurationSpec", {
+ duration: { unit: "frames", value: 20 }, author: { binding: "for", declarationId: "clip" },
+ }),
+ record("timeline", "@hypit/timeline", "Timeline", {
+ id: "main", frameRate: { numerator: 30, denominator: 1 }, frameCount: 100,
+ }),
+ record("identity", "@hypit/timeline-author", "ConstructionIdentitySpec", { id: "main.clip" }),
+ ];
+ const executed = [
+ { id: "origin", type: authorType("ConstructionPoint"), value: { kind: "inline", value: { frame: 0 } } },
+ { id: "from-extent", type: authorType("ConstructionExtent"), value: { kind: "inline", value: { frameCount: 10 } } },
+ { id: "start-point", type: authorType("ConstructionPoint"), value: { kind: "inline", value: { frame: 10 } } },
+ { id: "clip-extent", type: authorType("ConstructionExtent"), value: { kind: "inline", value: { frameCount: 20 } } },
+ { id: "clip-span", type: authorType("ConstructionSpan"), value: { kind: "inline", value: { startFrame: 10, endFrameExclusive: 30 } } },
+ record("author-window", "@hypit/temporal", "TemporalWindow", {
+ id: "main.clip", subjectId: "main.clip",
+ start: { id: "main.clip.start", subjectId: "main.clip", timelineId: "main", frame: 10 },
+ end: { id: "main.clip.end", subjectId: "main.clip", timelineId: "main", frame: 30 },
+ span: { startFrame: 10, endFrameExclusive: 30 },
+ }),
+ ] as TypedRecord[];
+ const authorStep = (id: string, producer: keyof typeof timelineAuthorProducers,
+ inputs: ProducerStep["inputs"], outputName: string, output: string): ProducerStep => ({
+ id, producer: timelineAuthorProducers[producer], inputs, outputs: { [outputName]: output }, needs: {},
+ });
+ const steps = [
+ authorStep("origin", "origin", { clock: "clock" }, "point", "origin"),
+ authorStep("from-duration", "duration", { clock: "clock", duration: "from-duration" }, "extent", "from-extent"),
+ authorStep("offset", "offset", { point: "origin", extent: "from-extent", spec: "from-spec" }, "point", "start-point"),
+ authorStep("for-duration", "duration", { clock: "clock", duration: "for-spec" }, "extent", "clip-extent"),
+ authorStep("span", "span", { start: "start-point", extent: "clip-extent" }, "span", "clip-span"),
+ authorStep("window", "window", { timeline: "timeline", span: "clip-span", spec: "identity" }, "window", "author-window"),
+ ];
+ const state = {
+ format: "hypit.build@1", program: { closure: { modules: [] }, records: program }, targets: [],
+ plan: { format: "hypit.plan@1", steps, goals: [], outputBindings: [] }, status: "complete",
+ records: executed, steps: steps.map(({ id }) => ({ id, status: "complete" as const })),
+ needs: [], outstanding: [], diagnostics: [],
+ } as unknown as BuildState;
+ const text = '<time:Window id="clip" from="10f" for="20f"/>';
+ const child = {
+ sourcePath: "/project/main.svml", authorEndpoints: { from: "child:from", for: "child:for" },
+ records: ["from-spec", "for-spec"], attributes: { from: "10f", for: "20f" }, referenceAttributes: {},
+ attributeValueRanges: {
+ from: { start: text.indexOf("10f"), end: text.indexOf("10f") + 3 },
+ for: { start: text.indexOf("20f"), end: text.indexOf("20f") + 3 },
+ }, children: [],
+ } as unknown as import("../src/observe.js").Placement;
+ const owned = temporalAuthorBindings({ state, rootRecord: "author-window", workspaceRoot: "/project",
+ placements: [child], files: [{ path: "/project/main.svml", text, language: "svml" }] });
+ const registry = new StudioCompanionRegistry([], { temporalRelations: timelineAuthorStudioTemporalRelations });
+ const writes = planTemporalInverse({ state, rootRecord: "author-window",
+ target: { kind: "window", startFrame: 15, endFrameExclusive: 30 }, bindings: owned,
+ domainFrame: () => undefined, registry });
+ assert.deepEqual(writes.map((write) => [write.source.endpoint, write.replacement]), [
+ ["child:from", "15f"], ["child:for", "15f"],
+ ]);
+});
+
+test("relation candidates are solved by their final author writes", () => {
+ const spec = record("spec", "@example/time", "Spec", { author: { binding: "at" } });
+ const point = record("point", "@hypit/temporal", "TemporalInstant", {
+ id: "point", subjectId: "point", timelineId: "main", frame: 10,
+ });
+ const producer = { module: module("@example/time"), name: "choose-point" };
+ const operation: ProducerStep = { id: "choose", producer, inputs: { spec: "spec" }, outputs: { point: "point" }, needs: {} };
+ const state = {
+ format: "hypit.build@1", program: { closure: { modules: [] }, records: [spec] }, targets: [],
+ plan: { format: "hypit.plan@1", steps: [operation], goals: [], outputBindings: [] }, status: "complete",
+ records: [point], steps: [{ id: "choose", status: "complete" as const }],
+ needs: [], outstanding: [], diagnostics: [],
+ } as unknown as BuildState;
+ const binding = {
+ id: "spec:at", binding: "spec:at", name: "at", value: "10f", language: "svml" as const, writable: true,
+ source: { endpoint: "author:at", path: "main.svml", range: { start: 0, end: 3 }, preimage: "10f" },
+ };
+ const candidates = (replacements: readonly string[]) => new StudioCompanionRegistry([], { temporalRelations: [{
+ id: "choose-point", match: { producer, output: "point" },
+ invert: () => replacements.map((replacement) => ({ writes: [{ input: "spec", binding: "at", replacement }] })),
+ }] });
+ const planWith = (registry: StudioCompanionRegistry) => planTemporalInverse({
+ state, rootRecord: "point", target: { kind: "instant", frame: 12 }, bindings: [binding],
+ domainFrame: () => undefined, registry,
+ });
+ assert.deepEqual(planWith(candidates(["12f", "12f"])).map((write) => write.replacement), ["12f"]);
+ assert.throws(() => planWith(candidates(["12f", "13f"])), /multiple distinct author inverses/u);
+});
diff --git a/packages/temporal/EDITING.md b/packages/temporal/EDITING.md
index 1395d3cb..d7c21d63 100644
--- a/packages/temporal/EDITING.md
+++ b/packages/temporal/EDITING.md
@@ -13,8 +13,8 @@ that may declare an inverse.
| Author form | Move | Leading edge | Trailing edge |
| --- | --- | --- | --- |
-| `from="2s" for="8f"` | Rewrite `from`; retain `for`. | Rewrite `from`. | Rewrite `for`. |
-| `until="3s" for="8f"` | Rewrite `until`; retain `for`. | Rewrite `for`. | Rewrite `until`. |
+| `from="2s" for="8f"` | Rewrite `from`; retain `for`. | Rewrite `from` and `for` atomically so the end stays fixed. | Rewrite `for`. |
+| `until="3s" for="8f"` | Rewrite `until`; retain `for`. | Rewrite `for`. | Rewrite `until` and `for` atomically so the start stays fixed. |
| `from="1s" until="3s"` | Shift both values. | Rewrite `from`. | Rewrite `until`. |
| named Window declared with `from`/`until`/`for` | Rewrite the declaration. | Rewrite its leading relation. | Rewrite its trailing relation. |
| component `during={named-window}` | Follow the referenced value. | Edit its producer. | Edit its producer. |
@@ -46,4 +46,6 @@ This division is intentional:
- the component owns only what the value means for its behavior.
There is no automatic inverse, hidden compatibility fallback, or central registry of temporal
-lineage. Unsupported edits remain unavailable instead of mutating a guessed source.
+lineage. An author package may contribute local inverse relations for the private Producers it puts
+in the executed graph; Studio only composes their typed Point, Extent and Span constraints. Unsupported
+or ambiguous edits remain unavailable instead of mutating a guessed source.
diff --git a/packages/text-fine/src/studio.ts b/packages/text-fine/src/studio.ts
index 8e3e1fa9..2eb194b6 100644
--- a/packages/text-fine/src/studio.ts
+++ b/packages/text-fine/src/studio.ts
@@ -1,8 +1,8 @@
import { textFineMarkupSurfaces, textFineModuleRef, textFineTypes } from "./manifest.js";
import type { FineTextOccurrence, TextItem } from "./types.js";
import { compositionTypes } from "@hypit/hypit/composition";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-companion";
-import { childEntities, requiredSurfaceValue, temporalLineageFor, textLayer } from "@hypit/studio-companion";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioItemDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-companion";
+import { childItems, requiredSurfaceValue, temporalLineageFor, textLayer } from "@hypit/studio-companion";
const typographyProperties = (textFineMarkupSurfaces
.find((surface) => surface.name === "style")?.vocabulary.attributes
@@ -60,22 +60,22 @@ function textOf(item: Pick<TextItem, "document">): string {
.trim();
}
-function projectFineText(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectFineText(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const occurrence = requiredSurfaceValue(context, "occurrence") as FineTextOccurrence;
- const entity = childEntities(context, [{
+ const item = childItems(context, [{
id: occurrence.id,
startFrame: occurrence.span.startFrame,
endFrameExclusive: occurrence.span.endFrameExclusive,
stackOrder: occurrence.placement.z,
sourceTypes: [textFineTypes.itemSpec, textFineTypes.plainItemSpec],
}], "typography-item", "standard")[0];
- if (entity === undefined) return [];
+ if (item === undefined) return [];
const label = textOf(occurrence);
const temporal = temporalLineageFor(context, occurrence.id, "window");
return [{
- ...entity,
+ ...item,
authoredId: context.placement?.id ?? occurrence.id,
- display: { ...entity.display, title: context.placement?.id ?? occurrence.id, layers: label.length === 0 ? [] : [textLayer(label)] },
+ display: { ...item.display, title: context.placement?.id ?? occurrence.id, layers: label.length === 0 ? [] : [textLayer(label)] },
...(context.placement === undefined ? {} : { elementRange: context.placement.range }),
...(temporal === undefined ? {} : { temporal }),
}];
@@ -114,7 +114,7 @@ function fineTextCompanion(form: "flow" | "point" | "path"): StudioTrackCompanio
return {
id: form, role: "track",
output: { type: compositionTypes.visualTrack, surface: form, modules: [textFineModuleRef] },
- family: "text", tone: "violet", icon: "text",
+ family: "typography", tone: "violet", icon: "text",
bindings: [
{ name: geometry },
{ name: "content" },
diff --git a/packages/timeline-author/README.md b/packages/timeline-author/README.md
index de11bbbe..282f2030 100644
--- a/packages/timeline-author/README.md
+++ b/packages/timeline-author/README.md
@@ -81,6 +81,22 @@ range are errors.
The graph may have several roots, branches and leaves. It needs no clip ordering or single content
root; it needs one resolvable `end`.
+## Studio inverse
+
+Timeline Author retains the exact child declaration and binding on private literal Duration and
+Offset Specs. Its Studio Companion owns the inverse relations for private construction Points,
+Extents and Spans. Studio can therefore follow a consumed Window back through the executed author
+graph without learning Timeline Author's Producer vocabulary.
+
+For `from + for`, moving keeps `for` unchanged; trimming the leading edge rewrites `from` and `for`
+atomically so the old end remains fixed. `until + for` is the corresponding end-anchored relation,
+while `from + until` exposes both boundaries. A bare reference follows its upstream producer. An
+explicit offset owns only that offset expression. `earliest` and `latest` remain read-only when a
+change would require choosing among inputs; Studio does not guess which branch the author intended.
+
+These inverse facts are package-local Studio support. They do not change the Timeline value, add an
+editing concern to Core, or create a second author graph.
+
## Unknown generated duration
`TemporalExtent` is an unpositioned frame count on one frame rate. Normalization publishes it only
diff --git a/packages/timeline-author/package.json b/packages/timeline-author/package.json
index 03a033bc..d69a7cca 100644
--- a/packages/timeline-author/package.json
+++ b/packages/timeline-author/package.json
@@ -15,7 +15,8 @@
"activation": "./src/activation.ts"
},
"peerDependencies": {
- "@hypit/hypit": "workspace:^"
+ "@hypit/hypit": "workspace:^",
+ "@hypit/studio-companion": "workspace:^"
},
"devDependencies": {
"@hypit/hypit": "workspace:*",
@@ -23,6 +24,7 @@
"@hypit/author": "workspace:*",
"@hypit/markup": "workspace:*",
"@hypit/script": "workspace:*",
+ "@hypit/studio-companion": "workspace:*",
"@hypit/temporal": "workspace:*",
"@hypit/text": "workspace:*",
"@hypit/timeline": "workspace:*",
diff --git a/packages/timeline-author/src/activation.ts b/packages/timeline-author/src/activation.ts
index a752c1e2..e4f5f182 100644
--- a/packages/timeline-author/src/activation.ts
+++ b/packages/timeline-author/src/activation.ts
@@ -1,11 +1,13 @@
import { createAdmissionPackageFacet } from "@hypit/hypit/admission";
import { createProducerPackageFacet } from "@hypit/hypit/producer";
import { createMarkupSurfaceFacet } from "@hypit/hypit/markup";
+import { createStudioCompanionFacet } from "@hypit/studio-companion";
import {
decodeAbsoluteInstantSurface, decodeAbsoluteWindowSurface, decodeClockSurface, decodeTimelineAuthorSurface, timelineAuthorComponent, timelineAuthorManifest,
timelineAuthorModuleRef,
timelineAuthorMarkupSurfaces,
} from "./index.js";
+import { timelineAuthorStudioTemporalDeclarations, timelineAuthorStudioTemporalRelations } from "./studio.js";
export const hypitPackage = {
format: "hypit.package@1" as const,
@@ -13,6 +15,10 @@ export const hypitPackage = {
manifest: timelineAuthorManifest,
}],
facets: [
+ createStudioCompanionFacet({
+ temporalDeclarations: timelineAuthorStudioTemporalDeclarations,
+ temporalRelations: timelineAuthorStudioTemporalRelations,
+ }),
...[timelineAuthorComponent].flatMap((component) => [createProducerPackageFacet(component), createAdmissionPackageFacet(component)]),createMarkupSurfaceFacet({
module: timelineAuthorModuleRef,
declaration: timelineAuthorMarkupSurfaces.find((item) => item.name === "timeline")!, handler: decodeTimelineAuthorSurface,
diff --git a/packages/timeline-author/src/component.ts b/packages/timeline-author/src/component.ts
index bf7cb973..f6697256 100644
--- a/packages/timeline-author/src/component.ts
+++ b/packages/timeline-author/src/component.ts
@@ -2,7 +2,7 @@ import { canonicalize } from "@hypit/hypit/protocol";
import type { ProducerPackage } from "@hypit/hypit/producer";
import type { AdmissionPackage } from "@hypit/hypit/admission";
import type { StoredValue } from "@hypit/hypit/protocol";
-import type { LocalTemporalDomain, TemporalDuration, TemporalExtent, TemporalWindow } from "@hypit/hypit/temporal";
+import type { LocalTemporalDomain, TemporalExtent, TemporalWindow } from "@hypit/hypit/temporal";
import type { Clock, Timeline } from "@hypit/hypit/timeline";
import { timelineAuthorProducers } from "./manifest.js";
@@ -13,7 +13,7 @@ import {
finalizeTimeline, materializeInstant, materializeWindow,
} from "./program.js";
import type {
- ConstructionExtent, ConstructionIdentitySpec, ConstructionOffsetSpec,
+ ConstructionDurationSpec, ConstructionExtent, ConstructionIdentitySpec, ConstructionOffsetSpec,
ConstructionPoint, ConstructionSpan, TimelineAuthorHeader,
} from "./types.js";
@@ -26,7 +26,7 @@ const output = (value: unknown) => ({ kind: "inline" as const, value: canonicali
export const timelineAuthorComponent = {
producers: [
{ producer: timelineAuthorProducers.origin, handler: ({ inputs }) => ({ outputs: { point: output(constructionOrigin(inline<Clock>(inputs.clock?.value, "Clock"))) }, needs: {} }) },
- { producer: timelineAuthorProducers.duration, handler: ({ inputs }) => ({ outputs: { extent: output(constructionDuration(inline<Clock>(inputs.clock?.value, "Clock"), inline<TemporalDuration>(inputs.duration?.value, "ConstructionDurationSpec"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.duration, handler: ({ inputs }) => ({ outputs: { extent: output(constructionDuration(inline<Clock>(inputs.clock?.value, "Clock"), inline<ConstructionDurationSpec>(inputs.duration?.value, "ConstructionDurationSpec").duration)) }, needs: {} }) },
{ producer: timelineAuthorProducers.resolvedExtent, handler: ({ inputs }) => ({ outputs: { extent: output(constructionResolvedExtent(inline<Clock>(inputs.clock?.value, "Clock"), inline<TemporalExtent>(inputs.extent?.value, "TemporalExtent"))) }, needs: {} }) },
{ producer: timelineAuthorProducers.offset, handler: ({ inputs }) => ({ outputs: { point: output(constructionOffset(inline<ConstructionPoint>(inputs.point?.value, "ConstructionPoint"), inline<ConstructionExtent>(inputs.extent?.value, "ConstructionExtent"), inline<ConstructionOffsetSpec>(inputs.spec?.value, "ConstructionOffsetSpec"))) }, needs: {} }) },
{ producer: timelineAuthorProducers.earliest, handler: ({ inputs }) => ({ outputs: { point: output(constructionEarliest(inline<ConstructionPoint>(inputs.left?.value, "ConstructionPoint"), inline<ConstructionPoint>(inputs.right?.value, "ConstructionPoint"))) }, needs: {} }) },
diff --git a/packages/timeline-author/src/fragment.ts b/packages/timeline-author/src/fragment.ts
index 16042aad..c2310114 100644
--- a/packages/timeline-author/src/fragment.ts
+++ b/packages/timeline-author/src/fragment.ts
@@ -6,7 +6,7 @@ import type { TemporalDuration } from "@hypit/hypit/temporal";
import { timelineTypes } from "@hypit/hypit/timeline";
import { timelineAuthorProducers, timelineAuthorTypes } from "./manifest.js";
-import type { TimelineAuthorDeclaration, TimelineAuthorFragmentOptions } from "./types.js";
+import type { TimelineAuthorBinding, TimelineAuthorDeclaration, TimelineAuthorFragmentOptions } from "./types.js";
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string): FragmentOperationRef => ({ kind: "fragment-operation", operation: id });
@@ -15,6 +15,7 @@ export type TimelineAuthorInlineInput = {
readonly name: string;
readonly type: TypeRef;
readonly value: unknown;
+ readonly author?: TimelineAuthorBinding;
};
export type TimelineAuthorFragmentPlan = {
@@ -117,10 +118,10 @@ export function compileTimelineAuthorFragment(options: TimelineAuthorFragmentOpt
}
return operation(value.id);
};
- const addInline = (type: TypeRef, value: unknown, stem: string): ReturnType<typeof input> => {
+ const addInline = (type: TypeRef, value: unknown, stem: string, author?: TimelineAuthorBinding): ReturnType<typeof input> => {
const name = `${stem}-${++generated}`;
inputs.push({ name, type });
- inlineInputs.push({ name, type, value });
+ inlineInputs.push({ name, type, value, ...(author === undefined ? {} : { author }) });
return input(name);
};
const identitySpec = (id: string, subjectId = id) =>
@@ -129,9 +130,10 @@ export function compileTimelineAuthorFragment(options: TimelineAuthorFragmentOpt
id: "point:start", producer: timelineAuthorProducers.origin,
inputs: { clock: input("clock") }, result: { kind: "output", name: "point" },
});
- const durationExtent = (raw: string): FragmentOperationRef => {
+ const durationExtent = (raw: string, author?: TimelineAuthorBinding): FragmentOperationRef => {
const duration = parseDuration(raw, "Timeline construction duration");
- const durationInput = addInline(timelineAuthorTypes.duration, duration, "duration");
+ const durationInput = addInline(timelineAuthorTypes.duration,
+ { duration, ...(author === undefined ? {} : { author }) }, "duration", author);
return addOperation({ id: `extent:duration:${generated}`, producer: timelineAuthorProducers.duration,
inputs: { clock: input("clock"), duration: durationInput }, result: { kind: "output", name: "extent" } });
};
@@ -144,7 +146,8 @@ export function compileTimelineAuthorFragment(options: TimelineAuthorFragmentOpt
inputs: { clock: input("clock"), extent: input(name) }, result: { kind: "output", name: "extent" } });
};
const declarationExtent = (declaration: Extract<TimelineAuthorDeclaration, { readonly kind: "window" }>): FragmentOperationRef => {
- if (declaration.duration !== undefined) return durationExtent(declaration.duration);
+ if (declaration.duration !== undefined) return durationExtent(declaration.duration,
+ { binding: "for", declarationId: declaration.id });
assert(declaration.extentInput !== undefined, `Timeline Window ${declaration.id} requires for.`);
return resolvedExtent(declaration.id, declaration.extentInput);
};
@@ -158,14 +161,16 @@ export function compileTimelineAuthorFragment(options: TimelineAuthorFragmentOpt
producer: boundary === "start" ? timelineAuthorProducers.spanStart : timelineAuthorProducers.spanEnd,
inputs: { span: spanRef(id) }, result: { kind: "output", name: "point" } });
};
- const pointExpression = (source: string): FragmentOperationRef => {
+ const pointExpression = (source: string, author?: TimelineAuthorBinding): FragmentOperationRef => {
const { base, direction, duration } = splitOffset(source);
let ref: FragmentOperationRef;
if (base === "start") ref = originRef();
else if (base === "end") ref = operation("point:end");
else if (/^\d+(?:\.\d+)?(?:f|ms|s)$/u.test(base)) {
const extent = durationExtent(base);
- const spec = addInline(timelineAuthorTypes.offset, { direction: 1 }, "offset");
+ const owned = author === undefined ? undefined : { ...author, expression: { kind: "absolute" as const } };
+ const spec = addInline(timelineAuthorTypes.offset,
+ { direction: 1, ...(owned === undefined ? {} : { author: owned }) }, "offset", owned);
ref = addOperation({ id: `point:absolute:${generated}`, producer: timelineAuthorProducers.offset,
inputs: { point: originRef(), extent, spec }, result: { kind: "output", name: "point" } });
} else {
@@ -192,7 +197,9 @@ export function compileTimelineAuthorFragment(options: TimelineAuthorFragmentOpt
if (direction === undefined) return ref;
assert(duration !== undefined && duration.length > 0, `Timeline expression ${source} has no offset duration.`);
const extent = durationExtent(duration);
- const spec = addInline(timelineAuthorTypes.offset, { direction }, "offset");
+ const owned = author === undefined ? undefined : { ...author, expression: { kind: "offset" as const, base } };
+ const spec = addInline(timelineAuthorTypes.offset,
+ { direction, ...(owned === undefined ? {} : { author: owned }) }, "offset", owned);
return addOperation({ id: `point:offset:${++generated}`, producer: timelineAuthorProducers.offset,
inputs: { point: ref, extent, spec }, result: { kind: "output", name: "point" } });
};
@@ -200,7 +207,7 @@ export function compileTimelineAuthorFragment(options: TimelineAuthorFragmentOpt
for (const declaration of options.declarations) {
if (declaration.kind === "instant") {
addOperation({ id: `decl:${declaration.id}:point`, producer: timelineAuthorProducers.aliasPoint,
- inputs: { point: pointExpression(declaration.at) }, result: { kind: "output", name: "point" } });
+ inputs: { point: pointExpression(declaration.at, { binding: "at", declarationId: declaration.id }) }, result: { kind: "output", name: "point" } });
continue;
}
const hasFrom = declaration.from !== undefined;
@@ -210,21 +217,24 @@ export function compileTimelineAuthorFragment(options: TimelineAuthorFragmentOpt
`Timeline Window ${declaration.id} requires exactly two of from, until and for.`);
if (hasFrom && hasUntil) {
addOperation({ id: `decl:${declaration.id}:span`, producer: timelineAuthorProducers.spanBetween,
- inputs: { start: pointExpression(declaration.from!), end: pointExpression(declaration.until!) },
+ inputs: {
+ start: pointExpression(declaration.from!, { binding: "from", declarationId: declaration.id }),
+ end: pointExpression(declaration.until!, { binding: "until", declarationId: declaration.id }),
+ },
result: { kind: "output", name: "span" } });
} else if (hasFrom) {
addOperation({ id: `decl:${declaration.id}:span`, producer: timelineAuthorProducers.span,
- inputs: { start: pointExpression(declaration.from!), extent: declarationExtent(declaration) },
+ inputs: { start: pointExpression(declaration.from!, { binding: "from", declarationId: declaration.id }), extent: declarationExtent(declaration) },
result: { kind: "output", name: "span" } });
} else {
addOperation({ id: `decl:${declaration.id}:span`, producer: timelineAuthorProducers.spanEnding,
- inputs: { end: pointExpression(declaration.until!), extent: declarationExtent(declaration) },
+ inputs: { end: pointExpression(declaration.until!, { binding: "until", declarationId: declaration.id }), extent: declarationExtent(declaration) },
result: { kind: "output", name: "span" } });
}
}
addOperation({ id: "point:end", producer: timelineAuthorProducers.aliasPoint,
- inputs: { point: pointExpression(options.end) }, result: { kind: "output", name: "point" } });
+ inputs: { point: pointExpression(options.end, { binding: "end" }) }, result: { kind: "output", name: "point" } });
addOperation({ id: "timeline", producer: timelineAuthorProducers.finalize,
inputs: { header: input("header"), clock: input("clock"), end: operation("point:end") },
result: { kind: "output", name: "timeline" } });
diff --git a/packages/timeline-author/src/studio.ts b/packages/timeline-author/src/studio.ts
new file mode 100644
index 00000000..75ddf10e
--- /dev/null
+++ b/packages/timeline-author/src/studio.ts
@@ -0,0 +1,317 @@
+import type {
+ StudioPlacement,
+ StudioTemporalConstraint,
+ StudioTemporalDeclarationCompanion,
+ StudioTemporalDeclarationDraft,
+ StudioTemporalRelationCompanion,
+ StudioTemporalInstantProjection,
+ StudioTemporalRelationTrace,
+ StudioTemporalRelationValue,
+} from "@hypit/studio-companion";
+
+import { timelineAuthorModuleRef, timelineAuthorProducers } from "./manifest.js";
+import type {
+ ConstructionDurationSpec,
+ ConstructionExtent,
+ ConstructionOffsetSpec,
+ ConstructionPoint,
+ ConstructionSpan,
+} from "./types.js";
+
+function output(
+ placement: StudioPlacement,
+ name: string,
+ id: string,
+ range = placement.range,
+): StudioTemporalDeclarationDraft | undefined {
+ const found = placement.outputPorts.find((candidate) => candidate.name === name);
+ return found === undefined ? undefined : { id, label: id, output: found.ref, range };
+}
+
+const localName = (tag: string) => tag.slice(tag.lastIndexOf(":") + 1);
+
+export const timelineAuthorStudioTemporalDeclarations: readonly StudioTemporalDeclarationCompanion[] = [{
+ id: "timeline-declarations",
+ match: { module: timelineAuthorModuleRef, surface: "timeline" },
+ project({ placement }) {
+ return placement.children.flatMap((child) => {
+ if (child.id === undefined || (localName(child.tag) !== "Window" && localName(child.tag) !== "Instant")) return [];
+ const found = output(placement, `anchor-${child.id}`, child.id, child.range);
+ return found === undefined ? [] : [found];
+ });
+ },
+}, {
+ id: "window-declaration",
+ match: { module: timelineAuthorModuleRef, surface: "window" },
+ project({ placement }) {
+ if (placement.id === undefined) return [];
+ const found = output(placement, "window", placement.id);
+ return found === undefined ? [] : [found];
+ },
+}, {
+ id: "instant-declaration",
+ match: { module: timelineAuthorModuleRef, surface: "instant" },
+ project({ placement }) {
+ if (placement.id === undefined) return [];
+ const found = output(placement, "instant", placement.id);
+ return found === undefined ? [] : [found];
+ },
+}];
+
+function value<T>(input: StudioTemporalRelationValue | undefined, label: string): T {
+ if (input === undefined) throw new Error(`Timeline Author inverse requires ${label}.`);
+ return input.value as T;
+}
+
+const instant = (target: StudioTemporalConstraint): Extract<StudioTemporalConstraint, { readonly kind: "instant" }> | undefined =>
+ target.kind === "instant" ? target : undefined;
+const extent = (target: StudioTemporalConstraint): Extract<StudioTemporalConstraint, { readonly kind: "extent" }> | undefined =>
+ target.kind === "extent" ? target : undefined;
+const span = (target: StudioTemporalConstraint): Extract<StudioTemporalConstraint, { readonly kind: "span" }> | undefined =>
+ target.kind === "span" ? target : undefined;
+
+function pointTrace(trace: StudioTemporalRelationTrace | undefined): StudioTemporalInstantProjection | undefined {
+ return trace?.kind === "instant" ? trace : undefined;
+}
+
+function withFrame(point: StudioTemporalInstantProjection, frame: number): StudioTemporalInstantProjection {
+ return { ...point, frame };
+}
+
+function parameterFromExtent(
+ trace: StudioTemporalRelationTrace | undefined,
+ relation: "after-start" | "before-end",
+): Extract<StudioTemporalInstantProjection["authority"], { readonly kind: "parameter" }> | undefined {
+ return trace?.kind === "extent" && trace.authority !== undefined
+ ? { ...trace.authority, relation } : undefined;
+}
+
+/** Timeline Author owns the inverse meaning of its private construction Producers. */
+export const timelineAuthorStudioTemporalRelations: readonly StudioTemporalRelationCompanion[] = [
+ {
+ id: "materialize-instant", match: { producer: timelineAuthorProducers.instant, output: "instant" },
+ invert({ target }) {
+ const desired = instant(target);
+ return desired === undefined ? [] : [{ constraints: [{ input: "point", target: desired }] }];
+ },
+ trace({ output, trace }) {
+ const held = output.value as { readonly timelineId?: unknown; readonly frame?: unknown };
+ const point = pointTrace(trace("point"));
+ return point === undefined || typeof held.timelineId !== "string" || !Number.isSafeInteger(held.frame)
+ ? undefined : { ...point, frame: held.frame as number,
+ source: { ...point.source, timelineId: held.timelineId } };
+ },
+ }, {
+ id: "materialize-window", match: { producer: timelineAuthorProducers.window, output: "window" },
+ invert({ target }) {
+ const desired = span(target);
+ return desired === undefined ? [] : [{ constraints: [{ input: "span", target: desired }] }];
+ },
+ trace({ output, trace }) {
+ const held = output.value as {
+ readonly start?: { readonly timelineId?: unknown };
+ readonly end?: { readonly timelineId?: unknown };
+ readonly span?: { readonly startFrame?: unknown; readonly endFrameExclusive?: unknown };
+ };
+ const source = trace("span");
+ return source?.kind !== "window" || !Number.isSafeInteger(held.span?.startFrame)
+ || !Number.isSafeInteger(held.span?.endFrameExclusive) ? undefined : {
+ ...source,
+ start: { ...withFrame(source.start, held.span!.startFrame as number),
+ source: { ...source.start.source,
+ ...(typeof held.start?.timelineId === "string" ? { timelineId: held.start.timelineId } : {}) } },
+ end: { ...withFrame(source.end, held.span!.endFrameExclusive as number),
+ source: { ...source.end.source,
+ ...(typeof held.end?.timelineId === "string" ? { timelineId: held.end.timelineId } : {}) } },
+ startFrame: held.span!.startFrame as number,
+ endFrameExclusive: held.span!.endFrameExclusive as number,
+ };
+ },
+ }, {
+ id: "alias-point", match: { producer: timelineAuthorProducers.aliasPoint, output: "point" },
+ invert({ target }) {
+ const desired = instant(target);
+ return desired === undefined ? [] : [{ constraints: [{ input: "point", target: desired }] }];
+ },
+ trace({ output, trace }) {
+ const held = value<ConstructionPoint>(output, "Point");
+ const source = pointTrace(trace("point"));
+ return source === undefined ? undefined : withFrame(source, held.frame);
+ },
+ }, {
+ id: "span-start", match: { producer: timelineAuthorProducers.spanStart, output: "point" },
+ invert({ target, inputs }) {
+ const desired = instant(target);
+ const current = value<ConstructionSpan>(inputs.span, "Span");
+ return desired === undefined ? [] : [{ constraints: [{ input: "span", target: {
+ kind: "span", startFrame: desired.frame, endFrameExclusive: current.endFrameExclusive,
+ } }] }];
+ },
+ trace({ trace }) {
+ const held = trace("span");
+ return held?.kind === "window" ? held.start : undefined;
+ },
+ }, {
+ id: "span-end", match: { producer: timelineAuthorProducers.spanEnd, output: "point" },
+ invert({ target, inputs }) {
+ const desired = instant(target);
+ const current = value<ConstructionSpan>(inputs.span, "Span");
+ return desired === undefined ? [] : [{ constraints: [{ input: "span", target: {
+ kind: "span", startFrame: current.startFrame, endFrameExclusive: desired.frame,
+ } }] }];
+ },
+ trace({ trace }) {
+ const held = trace("span");
+ return held?.kind === "window" ? held.end : undefined;
+ },
+ }, {
+ id: "span-between", match: { producer: timelineAuthorProducers.spanBetween, output: "span" },
+ invert({ target }) {
+ const desired = span(target);
+ return desired === undefined ? [] : [{ constraints: [
+ { input: "start", target: { kind: "instant", frame: desired.startFrame } },
+ { input: "end", target: { kind: "instant", frame: desired.endFrameExclusive } },
+ ] }];
+ },
+ trace({ output, trace }) {
+ const held = value<ConstructionSpan>(output, "Span");
+ const start = pointTrace(trace("start")); const end = pointTrace(trace("end"));
+ return start === undefined || end === undefined ? undefined : {
+ kind: "window", start: withFrame(start, held.startFrame), end: withFrame(end, held.endFrameExclusive),
+ startFrame: held.startFrame, endFrameExclusive: held.endFrameExclusive,
+ };
+ },
+ }, {
+ id: "span-from", match: { producer: timelineAuthorProducers.span, output: "span" },
+ invert({ target }) {
+ const desired = span(target);
+ return desired === undefined ? [] : [{ constraints: [
+ { input: "start", target: { kind: "instant", frame: desired.startFrame } },
+ { input: "extent", target: { kind: "extent", frameCount: desired.endFrameExclusive - desired.startFrame } },
+ ] }];
+ },
+ trace({ output, trace }) {
+ const held = value<ConstructionSpan>(output, "Span");
+ const start = pointTrace(trace("start")); const length = trace("extent");
+ if (start === undefined || length?.kind !== "extent") return undefined;
+ const authority = parameterFromExtent(length, "after-start");
+ const end = withFrame({ ...start, expression: `${held.endFrameExclusive}f`, reference: "absolute",
+ authority: authority ?? { kind: "fixed" } }, held.endFrameExclusive);
+ return { kind: "window", start: withFrame(start, held.startFrame), end,
+ startFrame: held.startFrame, endFrameExclusive: held.endFrameExclusive };
+ },
+ }, {
+ id: "span-ending", match: { producer: timelineAuthorProducers.spanEnding, output: "span" },
+ invert({ target }) {
+ const desired = span(target);
+ return desired === undefined ? [] : [{ constraints: [
+ { input: "end", target: { kind: "instant", frame: desired.endFrameExclusive } },
+ { input: "extent", target: { kind: "extent", frameCount: desired.endFrameExclusive - desired.startFrame } },
+ ] }];
+ },
+ trace({ output, trace }) {
+ const held = value<ConstructionSpan>(output, "Span");
+ const end = pointTrace(trace("end")); const length = trace("extent");
+ if (end === undefined || length?.kind !== "extent") return undefined;
+ const authority = parameterFromExtent(length, "before-end");
+ const start = withFrame({ ...end, expression: `${held.startFrame}f`, reference: "absolute",
+ authority: authority ?? { kind: "fixed" } }, held.startFrame);
+ return { kind: "window", start, end: withFrame(end, held.endFrameExclusive),
+ startFrame: held.startFrame, endFrameExclusive: held.endFrameExclusive };
+ },
+ }, {
+ id: "duration", match: { producer: timelineAuthorProducers.duration, output: "extent" },
+ invert({ target, inputs }) {
+ const desired = extent(target);
+ const spec = value<ConstructionDurationSpec>(inputs.duration, "Duration Spec");
+ return desired === undefined || spec.author === undefined ? [] : [{ writes: [{
+ input: "duration", binding: spec.author.binding, replacement: `${desired.frameCount}f`,
+ }] }];
+ },
+ trace({ output, inputs }) {
+ const held = value<ConstructionExtent>(output, "Extent");
+ const specInput = inputs.duration;
+ const spec = value<ConstructionDurationSpec>(specInput, "Duration Spec");
+ return { kind: "extent", frameCount: held.frameCount,
+ ...(spec.author === undefined || specInput === undefined ? {} : { authority: {
+ kind: "parameter" as const, binding: spec.author.binding,
+ owner: `${specInput.record}:${spec.author.binding}`, relation: "direct" as const,
+ } }) };
+ },
+ }, {
+ id: "resolved-extent", match: { producer: timelineAuthorProducers.resolvedExtent, output: "extent" },
+ invert({ target, output }) {
+ const desired = extent(target);
+ const current = value<ConstructionExtent>(output, "Extent");
+ return desired !== undefined && desired.frameCount === current.frameCount ? [{}] : [];
+ },
+ trace({ output }) { return { kind: "extent", frameCount: value<ConstructionExtent>(output, "Extent").frameCount }; },
+ }, {
+ id: "offset-point", match: { producer: timelineAuthorProducers.offset, output: "point" },
+ invert({ target, inputs }) {
+ const desired = instant(target);
+ if (desired === undefined) return [];
+ const spec = value<ConstructionOffsetSpec>(inputs.spec, "Offset Spec");
+ const base = value<ConstructionPoint>(inputs.point, "base Point").frame;
+ if (spec.author?.expression?.kind === "absolute") {
+ return [{ writes: [{ input: "spec", binding: spec.author.binding, replacement: `${desired.frame}f` }] }];
+ }
+ if (spec.author?.expression?.kind === "offset") {
+ const difference = desired.frame - base;
+ const sign = difference < 0 ? "-" : "+";
+ return [{
+ constraints: [{ input: "point", target: { kind: "instant", frame: base } }],
+ writes: [{ input: "spec", binding: spec.author.binding,
+ replacement: `${spec.author.expression.base}${sign}${Math.abs(difference)}f` }],
+ }];
+ }
+ const held = value<ConstructionExtent>(inputs.extent, "offset Extent").frameCount;
+ return [{ constraints: [{ input: "point", target: {
+ kind: "instant", frame: desired.frame - spec.direction * held,
+ } }] }];
+ },
+ trace({ output, inputs, trace }) {
+ const held = value<ConstructionPoint>(output, "Point");
+ const specInput = inputs.spec;
+ const spec = value<ConstructionOffsetSpec>(specInput, "Offset Spec");
+ const upstream = pointTrace(trace("point"));
+ if (upstream === undefined) return undefined;
+ if (spec.author === undefined || specInput === undefined) return withFrame(upstream, held.frame);
+ return { ...upstream, frame: held.frame,
+ expression: spec.author.expression?.kind === "offset"
+ ? `${spec.author.expression.base}${spec.direction < 0 ? "-" : "+"}${value<ConstructionExtent>(inputs.extent, "Extent").frameCount}f`
+ : `${held.frame}f`,
+ reference: "absolute",
+ authority: { kind: "parameter", binding: spec.author.binding,
+ owner: `${specInput.record}:${spec.author.binding}`, relation: "direct" } };
+ },
+ }, {
+ id: "origin", match: { producer: timelineAuthorProducers.origin, output: "point" },
+ invert({ target, output }) {
+ const desired = instant(target);
+ const current = value<ConstructionPoint>(output, "origin Point");
+ return desired !== undefined && desired.frame === current.frame ? [{}] : [];
+ },
+ trace({ output }) {
+ const held = value<ConstructionPoint>(output, "origin Point");
+ return { kind: "instant", expression: "timeline.start", reference: "timeline.start", frame: held.frame,
+ source: { timelineId: "", type: output.type, kind: "construction", id: "start" }, authority: { kind: "fixed" } };
+ },
+ }, ...[timelineAuthorProducers.earliest, timelineAuthorProducers.latest].map((producer): StudioTemporalRelationCompanion => ({
+ id: producer.name, match: { producer, output: "point" },
+ invert({ target, output }) {
+ const desired = instant(target);
+ const current = value<ConstructionPoint>(output, "aggregate Point");
+ return desired !== undefined && desired.frame === current.frame ? [{}] : [];
+ },
+ trace({ output, trace }) {
+ const held = value<ConstructionPoint>(output, "aggregate Point");
+ const candidates = [pointTrace(trace("left")), pointTrace(trace("right"))]
+ .filter((point): point is StudioTemporalInstantProjection => point !== undefined && point.frame === held.frame);
+ return candidates.length === 1 ? candidates[0] : {
+ kind: "instant", expression: `${held.frame}f`, reference: "absolute", frame: held.frame,
+ source: { timelineId: "", type: output.type, kind: "construction", id: output.record }, authority: { kind: "fixed" },
+ };
+ },
+ })),
+];
diff --git a/packages/timeline-author/src/surface.ts b/packages/timeline-author/src/surface.ts
index 3c3b2bc1..57feccd7 100644
--- a/packages/timeline-author/src/surface.ts
+++ b/packages/timeline-author/src/surface.ts
@@ -83,11 +83,20 @@ export const decodeTimelineAuthorSurface: StructuredSurfaceHandler = ({ element,
}
const plan = compileTimelineAuthorFragment({ id, end, declarations });
+ const authoredRange = (item: (typeof plan.inlineInputs)[number]) => {
+ if (item.author?.declarationId === undefined) return element.range;
+ const child = element.children.find((candidate) => candidate.kind === "element"
+ && candidate.attributes.id === item.author!.declarationId);
+ if (child === undefined || child.kind !== "element") {
+ throw new Error(`Timeline declaration ${item.author.declarationId} has no author element.`);
+ }
+ return child.range;
+ };
const headerRecord = `${id}.__header`;
const records = [{ id: headerRecord, type: timelineAuthorTypes.header,
value: { kind: "inline" as const, value: canonicalize({ id }) }, range: element.range },
...plan.inlineInputs.map((item) => ({ id: `${id}.__${item.name}`, type: item.type,
- value: { kind: "inline" as const, value: canonicalize(item.value) }, range: element.range }))];
+ value: { kind: "inline" as const, value: canonicalize(item.value) }, range: authoredRange(item) }))];
const inputs = {
header: { kind: "record" as const, id: headerRecord },
clock: clock.ref,
diff --git a/packages/timeline-author/src/types.ts b/packages/timeline-author/src/types.ts
index 44c032c7..d045270f 100644
--- a/packages/timeline-author/src/types.ts
+++ b/packages/timeline-author/src/types.ts
@@ -4,9 +4,16 @@ export type TimelineAuthorHeader = { readonly id: string };
export type ConstructionPoint = { readonly frame: number };
export type ConstructionExtent = { readonly frameCount: number };
export type ConstructionSpan = { readonly startFrame: number; readonly endFrameExclusive: number };
-export type ConstructionOffsetSpec = { readonly direction: 1 | -1 };
+export type TimelineAuthorBinding = {
+ readonly binding: "end" | "at" | "from" | "until" | "for";
+ readonly declarationId?: string;
+ readonly expression?:
+ | { readonly kind: "absolute" }
+ | { readonly kind: "offset"; readonly base: string };
+};
+export type ConstructionOffsetSpec = { readonly direction: 1 | -1; readonly author?: TimelineAuthorBinding };
export type ConstructionIdentitySpec = { readonly id: string; readonly subjectId?: string };
-export type ConstructionDurationSpec = TemporalDuration;
+export type ConstructionDurationSpec = { readonly duration: TemporalDuration; readonly author?: TimelineAuthorBinding };
export type TimelineInstantDeclaration = {
readonly id: string;
diff --git a/packages/timeline-author/test/program.test.ts b/packages/timeline-author/test/program.test.ts
index f3c2e8d0..51db5e4e 100644
--- a/packages/timeline-author/test/program.test.ts
+++ b/packages/timeline-author/test/program.test.ts
@@ -67,6 +67,13 @@ test("Surface planning lowers author Instants and Windows to typed graph operati
assert(plan.fragment.operations.some((item) => item.producer.name === "latest-point"));
assert(plan.fragment.operations.some((item) => item.id === "decl:claim:point"));
assert.deepEqual(plan.extentInputs, [{ name: "voice-extent", declarationId: "speech" }]);
+ assert.deepEqual(plan.inlineInputs.flatMap((item) => item.author === undefined ? [] : [{
+ binding: item.author.binding, declarationId: item.author.declarationId,
+ expression: item.author.expression?.kind,
+ }]), [
+ { binding: "for", declarationId: "outro", expression: undefined },
+ { binding: "at", declarationId: "claim", expression: "offset" },
+ ]);
assert.equal(JSON.stringify(plan.fragment).includes("speech.end-12f"), false);
verifyGraphFragment(link(createResolvedClosure([...videoContractManifests, timelineAuthorManifest]), []), plan.fragment);
});
diff --git a/packages/timeline-author/test/studio.test.ts b/packages/timeline-author/test/studio.test.ts
new file mode 100644
index 00000000..e7e732d5
--- /dev/null
+++ b/packages/timeline-author/test/studio.test.ts
@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { StudioPlacement } from "@hypit/studio-companion";
+
+import { timelineAuthorModuleRef } from "../src/manifest.js";
+import { timelineAuthorStudioTemporalDeclarations } from "../src/studio.js";
+
+const placement = (surface: string, outputPorts: StudioPlacement["outputPorts"],
+ children: StudioPlacement["children"] = []): StudioPlacement => ({
+ tag: `time:${surface}`,
+ module: timelineAuthorModuleRef,
+ sourcePath: "main.svml",
+ surface,
+ id: surface === "timeline" ? "program" : "cue",
+ range: { start: 0, end: 100 },
+ records: [], values: [], outputs: outputPorts.map((item) => item.ref), outputPorts,
+ children, attributes: {}, attributeValueRanges: {}, referenceAttributes: {}, referenceTypes: {}, references: [],
+});
+
+test("Timeline author companions expose only primary authored temporal declarations", () => {
+ const timeline = placement("timeline", [
+ { name: "timeline", ref: "program.timeline" },
+ { name: "window", ref: "program.window" },
+ { name: "start", ref: "program.start" },
+ { name: "end", ref: "program.end" },
+ { name: "anchor-speech", ref: "program.speech" },
+ { name: "anchor-speech-start", ref: "program.speech.start" },
+ { name: "anchor-speech-end", ref: "program.speech.end" },
+ { name: "anchor-cue", ref: "program.cue" },
+ ], [{ tag: "time:Window", sourcePath: "main.svml", id: "speech", range: { start: 10, end: 30 },
+ attributes: {}, attributeValueRanges: {}, references: [], referenceAttributes: {}, referenceTypes: {}, values: [] },
+ { tag: "time:Instant", sourcePath: "main.svml", id: "cue", range: { start: 31, end: 45 },
+ attributes: {}, attributeValueRanges: {}, references: [], referenceAttributes: {}, referenceTypes: {}, values: [] }]);
+ const companion = timelineAuthorStudioTemporalDeclarations.find((item) => item.match.surface === "timeline")!;
+ assert.deepEqual(companion.project({ placement: timeline }), [{ id: "speech", label: "speech",
+ output: "program.speech", range: { start: 10, end: 30 } }, { id: "cue", label: "cue",
+ output: "program.cue", range: { start: 31, end: 45 } }]);
+});
diff --git a/packages/timeline-author/test/surface.test.ts b/packages/timeline-author/test/surface.test.ts
index c7b1d757..6c9e12b3 100644
--- a/packages/timeline-author/test/surface.test.ts
+++ b/packages/timeline-author/test/surface.test.ts
@@ -41,6 +41,9 @@ test("Timeline Surface publishes its range and every named Instant or Window", a
]);
assert.equal(JSON.stringify(output.fragments).includes("speech.end"), false);
assert.equal(JSON.stringify(output.fragments).includes("3s"), false);
+ const childRecords = output.records.filter((record) => record.range.start !== element.range.start);
+ assert(childRecords.some((record) => record.range.start === source.indexOf('<time:Window id="outro"')));
+ assert(childRecords.every((record) => record.range.start !== source.indexOf('<time:Instant id="private-cue"')));
});
test("Timeline Window requires exactly two of from, until and for", () => {
diff --git a/packages/visual-track/src/studio.ts b/packages/visual-track/src/studio.ts
index e470a3c7..2927ea28 100644
--- a/packages/visual-track/src/studio.ts
+++ b/packages/visual-track/src/studio.ts
@@ -2,12 +2,12 @@ import { compositionTypes } from "@hypit/hypit/composition";
import type {
StudioTrackCompanion,
StudioTrackCompanionContext,
- StudioEntityDraft,
+ StudioItemDraft,
StudioInspectorFieldDeclaration,
StudioMaterialPreview,
StudioSourceBindingDeclaration,
} from "@hypit/studio-companion";
-import { artifactPreview, authoredItemTitle, childEntities, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalDomainSource } from "@hypit/studio-companion";
+import { artifactPreview, authoredItemTitle, childItems, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalDomainSource } from "@hypit/studio-companion";
import { visualTreatmentDefaults } from "./author.js";
import { visualTrackMarkupSurfaces, visualTrackModuleRef, visualTrackTypes } from "./manifest.js";
import type { MediaLayerProgram, VisualTrackProgram } from "./types.js";
@@ -135,7 +135,7 @@ function materialPreview(
return artifactPreview(layer.source.kind === "still" ? "image" : "video", layer.source.artifact.resource);
}
-function projectVisualClips(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectVisualItems(context: StudioTrackCompanionContext): readonly StudioItemDraft[] {
const program = requiredSurfaceValue(context, "program") as VisualTrackProgram;
const clips = program.clips.map((clip) => ({
id: clip.id,
@@ -147,17 +147,17 @@ function projectVisualClips(context: StudioTrackCompanionContext): readonly Stud
temporalInput: "window",
sourceTypes: [visualTrackTypes.clipSpec],
}));
- return childEntities(context, clips, "visual-clip", "standard")
- .map((entity, index) => {
+ return childItems(context, clips, "visual-clip", "standard")
+ .map((projected, index) => {
const clip = clips[index];
- if (clip === undefined) return entity;
+ if (clip === undefined) return projected;
const temporal = temporalLineageFor(context, clip.id, clip.temporalInput);
const semanticSource = temporalDomainSource(temporal);
return {
- ...entity,
+ ...projected,
display: {
- ...entity.display,
- title: authoredItemTitle(context, entity.authoredId, clip.sourceTypes, ["image", "media", "surface"]),
+ ...projected.display,
+ title: authoredItemTitle(context, projected.authoredId, clip.sourceTypes, ["image", "media", "surface"]),
...(clip.preview === undefined ? {} : {
layers: [previewLayer(clip.preview, clip.preview.kind === "video" ? "storyboard" : "repeat-x")],
}),
@@ -202,7 +202,7 @@ export const visualTrackStudioTrackCompanions: readonly StudioTrackCompanion[] =
...directClipInspector,
...visualClipTreatmentStudioFields.inspector,
],
- requiredValues: ["program"], project: projectVisualClips,
+ requiredValues: ["program"], project: projectVisualItems,
lane: { heightPx: 76 },
},
];
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 01938fd9..85e64339 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1537,6 +1537,9 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ '@hypit/studio-companion':
+ specifier: workspace:*
+ version: link:../studio-companion
'@hypit/temporal':
specifier: workspace:*
version: link:../temporal
@@ -2433,6 +2436,9 @@ importers:
'@hypit/script':
specifier: workspace:*
version: link:../script
+ '@hypit/studio-companion':
+ specifier: workspace:*
+ version: link:../studio-companion
'@hypit/temporal':
specifier: workspace:*
version: link:../temporal