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: make Studio edits follow temporal lineage

kashorind88b3400aa57
diff --git a/packages/ranking/src/component.ts b/packages/ranking/src/component.ts
index 022beabb..e2ac1900 100644
--- a/packages/ranking/src/component.ts
+++ b/packages/ranking/src/component.ts
@@ -8,7 +8,7 @@ import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
import type { Text } from "@hypit/text";
import { rankingProducers, rankingTypes } from "./manifest.js";
-import { appendColumnItem, appendColumnWindowCandidateWindow, appendRankingItemSpec, appendRankingSound, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertRankingSchedule, assertRankingSoundEventPlan, assertTierBoardProgram, assertTopThreeProgram, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowCandidateSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, materializeRankingTextItem } from "./schedule.js";
+import { appendColumnItem, appendColumnWindow, appendRankingItemSpec, appendRankingSound, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertRankingSchedule, assertRankingSoundEventPlan, assertTierBoardProgram, assertTopThreeProgram, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, materializeRankingTextItem } from "./schedule.js";
import {
renderColumn,
renderRankingAudio,
@@ -20,7 +20,7 @@ import type {
ColumnItemSpec,
ColumnProgram,
ColumnStyle,
- ColumnWindowCandidateSet,
+ ColumnWindowSet,
RankingHeader,
RankingItemSpec,
RankingItemSpecSet,
@@ -102,13 +102,13 @@ export const rankingComponent = {
})) }, needs: {} }),
},
{
- producer: rankingProducers.createColumnCandidates,
- handler: () => ({ outputs: { set: output(createColumnWindowCandidateSet()) }, needs: {} }),
+ producer: rankingProducers.createColumnWindows,
+ handler: () => ({ outputs: { set: output(createColumnWindowSet()) }, needs: {} }),
},
{
- producer: rankingProducers.appendColumnCandidate,
- handler: ({ inputs }) => ({ outputs: { set: output(appendColumnWindowCandidateWindow(
- inline<ColumnWindowCandidateSet>(inputs.set?.value, "ColumnWindowCandidateSet"),
+ producer: rankingProducers.appendColumnWindow,
+ handler: ({ inputs }) => ({ outputs: { set: output(appendColumnWindow(
+ inline<ColumnWindowSet>(inputs.set?.value, "ColumnWindowSet"),
inline<ColumnItemSpec>(inputs.spec?.value, "ColumnItemSpec"),
inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
)) }, needs: {} }),
@@ -119,7 +119,7 @@ export const rankingComponent = {
header: inline<RankingHeader>(inputs.header?.value, "RankingHeader"),
items: inline<RankingItemSpecSet>(inputs.items?.value, "RankingItemSpecSet"),
outer: inline<TemporalWindow>(inputs.outer?.value, "TemporalWindow"),
- candidates: inline<ColumnWindowCandidateSet>(inputs.candidates?.value, "ColumnWindowCandidateSet"),
+ windows: inline<ColumnWindowSet>(inputs.windows?.value, "ColumnWindowSet"),
})) }, needs: {} }),
},
...([
diff --git a/packages/ranking/src/fragment.ts b/packages/ranking/src/fragment.ts
index d0623a25..de96e102 100644
--- a/packages/ranking/src/fragment.ts
+++ b/packages/ranking/src/fragment.ts
@@ -76,7 +76,7 @@ export function createRankingFragment(
{ id: "specs", producer: rankingProducers.createSpecs, inputs: { header: input("header") }, result: { kind: "output", name: "set" } },
{ id: "resolved", producer: selected.create, inputs: {}, result: { kind: "output", name: "set" } },
{ id: "candidates", producer: variant === "column"
- ? rankingProducers.createColumnCandidates
+ ? rankingProducers.createColumnWindows
: rankingProducers.createTriggeredCandidates, inputs: {}, result: { kind: "output" as const, name: "set" } },
];
let specs = operation("specs");
@@ -135,7 +135,7 @@ export function createRankingFragment(
operations.push({
id: timingId,
producer: variant === "column"
- ? rankingProducers.appendColumnCandidate
+ ? rankingProducers.appendColumnWindow
: rankingProducers.appendTriggeredCandidate,
inputs: {
set: candidates, spec: resolvedSpec,
@@ -159,7 +159,7 @@ export function createRankingFragment(
operations.push({
id: "schedule",
producer: rankingProducers.columnSchedule,
- inputs: { header: input("header"), items: specs, outer: operation("outer-window"), candidates },
+ inputs: { header: input("header"), items: specs, outer: operation("outer-window"), windows: candidates },
result: { kind: "output", name: "schedule" },
});
} else {
diff --git a/packages/ranking/src/index.ts b/packages/ranking/src/index.ts
index 60b9d7d1..6bbb20a6 100644
--- a/packages/ranking/src/index.ts
+++ b/packages/ranking/src/index.ts
@@ -1,4 +1,4 @@
-export { appendColumnWindowCandidateWindow, appendRankingItemSpec, appendRankingSound, appendColumnItem, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertColumnStyle, assertColumnWindowCandidateSet, assertRankingHeader, assertRankingItemSpec, assertRankingItemSpecSet, assertRankingTextItemShell, assertRankingSchedule, assertRankingSoundEventPlan, assertRankingSoundStyle, assertTierBoardProgram, assertTierBoardStyle, assertTopThreeProgram, assertTopThreeStyle, assertTriggeredRankingCandidateSet, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowCandidateSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, sealRankingHeader, sealRankingTextItemShell, materializeRankingTextItem } from "./schedule.js";
+export { appendColumnWindow, appendRankingItemSpec, appendRankingSound, appendColumnItem, appendTierBoardItem, appendTopThreeItem, appendTriggeredRankingCandidate, assertColumnProgram, assertColumnStyle, assertColumnWindowSet, assertRankingHeader, assertRankingItemSpec, assertRankingItemSpecSet, assertRankingTextItemShell, assertRankingSchedule, assertRankingSoundEventPlan, assertRankingSoundStyle, assertTierBoardProgram, assertTierBoardStyle, assertTopThreeProgram, assertTopThreeStyle, assertTriggeredRankingCandidateSet, buildColumnProgram, buildColumnSchedule, buildColumnSoundEvents, buildTriggeredRankingSchedule, buildTierBoardProgram, buildTierBoardSoundEvents, buildTopThreeProgram, buildTopThreeSoundEvents, createColumnItemSet, createColumnWindowSet, createRankingItemSpecSet, createRankingSoundSet, createTierBoardItemSet, createTopThreeItemSet, createTriggeredRankingCandidateSet, sealRankingHeader, sealRankingTextItemShell, materializeRankingTextItem } from "./schedule.js";
export {
decodeColumnStyle,
decodeTierBoardStyle,
@@ -13,7 +13,7 @@ export {
export { rankingComponent } from "./component.js";
export { createRankingFragment } from "./fragment.js";
export type { RankingFragmentItem, RankingFragmentSound } from "./fragment.js";
-export { columnWindowCandidateSetSchema, triggeredRankingCandidateSetSchema, rankingDependency, rankingHeaderSchema, rankingItemSpecSchema, rankingTextItemShellSchema, rankingItemSpecSetSchema, rankingManifest, rankingMarkupSurfaces, rankingModuleRef, rankingProducers, rankingScheduleSchema, rankingSoundEventsSchema, rankingSoundSetSchema, rankingSoundStyleSchema, rankingTypes } from "./manifest.js";
+export { columnWindowSetSchema, triggeredRankingCandidateSetSchema, rankingDependency, rankingHeaderSchema, rankingItemSpecSchema, rankingTextItemShellSchema, rankingItemSpecSetSchema, rankingManifest, rankingMarkupSurfaces, rankingModuleRef, rankingProducers, rankingScheduleSchema, rankingSoundEventsSchema, rankingSoundSetSchema, rankingSoundStyleSchema, rankingTypes } from "./manifest.js";
export {
decodeColumnStyleSurface,
decodeColumnSurface,
diff --git a/packages/ranking/src/manifest.ts b/packages/ranking/src/manifest.ts
index 3a96ddfc..9f407e81 100644
--- a/packages/ranking/src/manifest.ts
+++ b/packages/ranking/src/manifest.ts
@@ -25,7 +25,7 @@ export const rankingTypes = {
textItemShell: { module: rankingModuleRef, name: "RankingTextItemShell" },
itemSpecs: { module: rankingModuleRef, name: "RankingItemSpecSet" },
triggeredCandidates: { module: rankingModuleRef, name: "TriggeredRankingCandidateSet" },
- columnCandidates: { module: rankingModuleRef, name: "ColumnWindowCandidateSet" },
+ columnWindows: { module: rankingModuleRef, name: "ColumnWindowSet" },
schedule: { module: rankingModuleRef, name: "RankingSchedule" },
soundStyle: { module: rankingModuleRef, name: "RankingSoundStyle" },
soundEvents: { module: rankingModuleRef, name: "RankingSoundEventPlan" },
@@ -47,8 +47,8 @@ export const rankingProducers = {
createTriggeredCandidates: { module: rankingModuleRef, name: "create-triggered-ranking-candidates" },
appendTriggeredCandidate: { module: rankingModuleRef, name: "append-triggered-ranking-candidate" },
schedule: { module: rankingModuleRef, name: "build-ranking-schedule" },
- createColumnCandidates: { module: rankingModuleRef, name: "create-column-window-candidates" },
- appendColumnCandidate: { module: rankingModuleRef, name: "append-column-window-candidate" },
+ createColumnWindows: { module: rankingModuleRef, name: "create-column-windows" },
+ appendColumnWindow: { module: rankingModuleRef, name: "append-column-window" },
columnSchedule: { module: rankingModuleRef, name: "build-column-schedule" },
createTierItems: { module: rankingModuleRef, name: "create-tier-board-items" },
appendTierItem: { module: rankingModuleRef, name: "append-tier-board-item" },
@@ -114,7 +114,7 @@ export const triggeredRankingCandidateSetSchema: ValueSchema = object({
}) },
}) } },
});
-export const columnWindowCandidateSetSchema: ValueSchema = object({
+export const columnWindowSetSchema: ValueSchema = object({
entries: { schema: { kind: "array", items: object({
itemId: { schema: string }, window: { schema: object({
id: { schema: string }, source: { schema: object({ kind: { schema: string }, id: { schema: string } }) },
@@ -137,7 +137,7 @@ const columnScheduleSchema: ValueSchema = object({
entries: { schema: { kind: "array", minItems: 1, items: { kind: "oneOf", variants: [
object({ itemId: { schema: string }, mode: { schema: { kind: "literal", value: "preset" } }, settled: { schema: frameSpan } }),
object({ itemId: { schema: string }, mode: { schema: { kind: "literal", value: "reveal" } },
- preferred: { schema: frameSpan }, active: { schema: frameSpan }, settled: { schema: frameSpan },
+ window: { schema: frameSpan }, settled: { schema: frameSpan },
}),
] } } },
});
@@ -531,7 +531,7 @@ export const rankingMarkupSurfaces = [
{ name: "preset", kind: "literal", required: false, values: ["true", "false"],
summary: "Settles the row from the start of the outer window; defaults to false." },
{ name: "during", kind: "reference", required: false, accepts: [narrativeTypes.selection],
- summary: "Chooses this row's preferred reveal Selection; required unless preset is true." },
+ summary: "Chooses this row's reveal Selection; required unless preset is true." },
{ name: "icon", kind: "reference", required: false, accepts: [mediaTypes.blobArtifact],
summary: "Chooses the image drawn beside the row." },
{ name: "stack", kind: "literal", required: false,
@@ -559,7 +559,7 @@ export const rankingMarkupSurfaces = [
notes: [
"The board requires at least one ColumnItem, accepts no other child and no text of its own, and Item ids must be unique within it.",
"Ranks must be unique; child order does not determine either final placement or reveal order.",
- "Non-preset Selection windows are clamped to the outer window and resolved into non-overlapping intervals; preset Items have no child `during`.",
+ "Every non-preset Selection window must already lie inside the outer window and be disjoint from every sibling; invalid input is refused, never repaired.",
"A `label` written as a reference materializes the row from that exact Text before the board is scheduled.",
"Authoring either sound also connects the Style's `.sound` output, so `style` must name a ColumnStyle written in this Source.",
],
@@ -640,7 +640,7 @@ export const rankingManifest: ModuleManifest = {
{ name: rankingTypes.textItemShell.name },
{ name: rankingTypes.itemSpecs.name },
{ name: rankingTypes.triggeredCandidates.name },
- { name: rankingTypes.columnCandidates.name },
+ { name: rankingTypes.columnWindows.name },
{ name: rankingTypes.schedule.name },
{ name: rankingTypes.soundStyle.name },
{ name: rankingTypes.soundEvents.name },
@@ -673,16 +673,16 @@ export const rankingManifest: ModuleManifest = {
{ name: "outer", type: temporalTypes.window }, { name: "candidates", type: rankingTypes.triggeredCandidates },
{ name: "terminal", type: temporalTypes.point },
], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [] },
- { name: rankingProducers.createColumnCandidates.name, inputs: [], outputs: [
- { name: "set", type: rankingTypes.columnCandidates },
+ { name: rankingProducers.createColumnWindows.name, inputs: [], outputs: [
+ { name: "set", type: rankingTypes.columnWindows },
], needs: [] },
- { name: rankingProducers.appendColumnCandidate.name, inputs: [
- { name: "set", type: rankingTypes.columnCandidates }, { name: "spec", type: rankingTypes.itemSpec },
+ { name: rankingProducers.appendColumnWindow.name, inputs: [
+ { name: "set", type: rankingTypes.columnWindows }, { name: "spec", type: rankingTypes.itemSpec },
{ name: "window", type: temporalTypes.window },
- ], outputs: [{ name: "set", type: rankingTypes.columnCandidates }], needs: [] },
+ ], outputs: [{ name: "set", type: rankingTypes.columnWindows }], needs: [] },
{ name: rankingProducers.columnSchedule.name, inputs: [
{ name: "header", type: rankingTypes.header }, { name: "items", type: rankingTypes.itemSpecs },
- { name: "outer", type: temporalTypes.window }, { name: "candidates", type: rankingTypes.columnCandidates },
+ { name: "outer", type: temporalTypes.window }, { name: "windows", type: rankingTypes.columnWindows },
], outputs: [{ name: "schedule", type: rankingTypes.schedule }], needs: [] },
...([
[rankingProducers.createTierItems, rankingTypes.tierItems],
diff --git a/packages/ranking/src/render.ts b/packages/ranking/src/render.ts
index 7aa92abd..a2eff832 100644
--- a/packages/ranking/src/render.ts
+++ b/packages/ranking/src/render.ts
@@ -511,7 +511,7 @@ export function renderColumn(space: ProgramSpace, program: ColumnProgram): Visua
return elements;
};
if (entry.mode === "reveal") {
- const duration = entry.active.endFrameExclusive - entry.active.startFrame;
+ const duration = entry.window.endFrameExclusive - entry.window.startFrame;
const fitted = fitColumnRevealMotion(duration, style.motion.appearFrames, style.motion.moveFrames);
const rootAnimation = fitted.mode === "direct" ? undefined : columnRevealAnimation({
duration, appearFrames: fitted.appearFrames, moveFrames: fitted.moveFrames,
@@ -519,7 +519,7 @@ export function renderColumn(space: ProgramSpace, program: ColumnProgram): Visua
stageSize: style.stageSizePx, finalSize: contentSize, easing: style.motion.easing,
});
presents.push(present({
- id: `${program.id}:item:${item.id}:stage`, start: entry.active.startFrame, end: entry.active.endFrameExclusive,
+ id: `${program.id}:item:${item.id}:stage`, start: entry.window.startFrame, end: entry.window.endFrameExclusive,
stacking: item.stackingOrder ?? style.stageStackingOrder,
tieBreak: `${program.id}:item:${String(item.rank).padStart(4, "0")}:${item.id}:stage`, elements: itemElements(rootAnimation),
}));
diff --git a/packages/ranking/src/schedule.ts b/packages/ranking/src/schedule.ts
index 7521e0ab..beae9a53 100644
--- a/packages/ranking/src/schedule.ts
+++ b/packages/ranking/src/schedule.ts
@@ -23,7 +23,7 @@ import type {
ColumnProgram,
ColumnSchedule,
ColumnStyle,
- ColumnWindowCandidateSet,
+ ColumnWindowSet,
RankingBoardPaint,
RankingHeader,
RankingItemSpec,
@@ -356,103 +356,77 @@ export function buildTriggeredRankingSchedule(input: {
return canonicalize(result) as unknown as TriggeredRankingSchedule;
}
-export function createColumnWindowCandidateSet(): ColumnWindowCandidateSet {
+export function createColumnWindowSet(): ColumnWindowSet {
return { entries: [] };
}
-export function assertColumnWindowCandidateSet(value: ColumnWindowCandidateSet): void {
- assert(Array.isArray(value.entries), "ColumnWindowCandidateSet.entries is invalid.");
+export function assertColumnWindowSet(value: ColumnWindowSet): void {
+ assert(Array.isArray(value.entries), "ColumnWindowSet.entries is invalid.");
const ids = new Set<string>();
for (const [index, entry] of value.entries.entries()) {
- identity(entry.itemId, `ColumnWindowCandidateSet.entries.${index}.itemId`);
- assert(!ids.has(entry.itemId), `ColumnWindowCandidateSet repeats ${entry.itemId}.`);
+ identity(entry.itemId, `ColumnWindowSet.entries.${index}.itemId`);
+ assert(!ids.has(entry.itemId), `ColumnWindowSet repeats ${entry.itemId}.`);
ids.add(entry.itemId);
- frame(entry.window.span.startFrame, `ColumnWindowCandidateSet.entries.${index}.window.span.startFrame`);
- frame(entry.window.span.endFrameExclusive, `ColumnWindowCandidateSet.entries.${index}.window.span.endFrameExclusive`);
+ frame(entry.window.span.startFrame, `ColumnWindowSet.entries.${index}.window.span.startFrame`);
+ frame(entry.window.span.endFrameExclusive, `ColumnWindowSet.entries.${index}.window.span.endFrameExclusive`);
assert(entry.window.span.endFrameExclusive > entry.window.span.startFrame,
- `ColumnWindowCandidateSet.entries.${index}.window is empty.`);
+ `ColumnWindowSet.entries.${index}.window is empty.`);
}
}
-export function appendColumnWindowCandidateWindow(
- set: ColumnWindowCandidateSet,
+export function appendColumnWindow(
+ set: ColumnWindowSet,
spec: ColumnItemSpec,
window: TemporalWindow,
-): ColumnWindowCandidateSet {
- assertColumnWindowCandidateSet(set);
+): ColumnWindowSet {
+ assertColumnWindowSet(set);
assertRankingItemSpec(spec);
assert(!spec.preset, `Preset Column Item ${spec.id} cannot consume a Selection window.`);
assert(!set.entries.some((entry) => entry.itemId === spec.id), `Column Item ${spec.id} already has a Selection window.`);
- const result: ColumnWindowCandidateSet = {
+ const result: ColumnWindowSet = {
entries: [...set.entries, { itemId: spec.id, window: structuredClone(window) }]
.sort((left, right) => left.itemId.localeCompare(right.itemId)),
};
- assertColumnWindowCandidateSet(result);
- return canonicalize(result) as unknown as ColumnWindowCandidateSet;
-}
-
-function clampColumnCandidate(
- preferred: { readonly startFrame: number; readonly endFrameExclusive: number },
- outer: { readonly startFrame: number; readonly endFrameExclusive: number },
-): { readonly startFrame: number; readonly endFrameExclusive: number } {
- const startFrame = Math.max(preferred.startFrame, outer.startFrame);
- const endFrameExclusive = Math.min(preferred.endFrameExclusive, outer.endFrameExclusive);
- if (endFrameExclusive > startFrame) return { startFrame, endFrameExclusive };
- if (preferred.endFrameExclusive <= outer.startFrame) {
- return { startFrame: outer.startFrame, endFrameExclusive: outer.startFrame + 1 };
- }
- return { startFrame: outer.endFrameExclusive - 1, endFrameExclusive: outer.endFrameExclusive };
-}
-
-function resolveColumnActiveWindows(
- candidates: readonly ColumnWindowCandidateSet["entries"][number][],
- outer: { readonly startFrame: number; readonly endFrameExclusive: number },
-): ReadonlyMap<string, { readonly startFrame: number; readonly endFrameExclusive: number }> {
- const capacity = outer.endFrameExclusive - outer.startFrame;
- assert(capacity >= candidates.length,
- `Column outer window has ${capacity} frames for ${candidates.length} non-preset Items.`);
- const ordered = candidates.map((candidate) => ({
- ...candidate,
- clamped: clampColumnCandidate(candidate.window.span, outer),
- })).sort((left, right) =>
- left.clamped.startFrame - right.clamped.startFrame
- || left.clamped.endFrameExclusive - right.clamped.endFrameExclusive
- || left.itemId.localeCompare(right.itemId));
- const resolved = new Map<string, { readonly startFrame: number; readonly endFrameExclusive: number }>();
- let cursor = outer.startFrame;
- for (const [index, candidate] of ordered.entries()) {
- const remaining = ordered.length - index - 1;
- const latestEnd = outer.endFrameExclusive - remaining;
- const startFrame = Math.min(Math.max(candidate.clamped.startFrame, cursor), latestEnd - 1);
- const endFrameExclusive = Math.min(Math.max(candidate.clamped.endFrameExclusive, startFrame + 1), latestEnd);
- resolved.set(candidate.itemId, { startFrame, endFrameExclusive });
- cursor = endFrameExclusive;
- }
- return resolved;
+ assertColumnWindowSet(result);
+ return canonicalize(result) as unknown as ColumnWindowSet;
}
export function buildColumnSchedule(input: {
readonly header: RankingHeader;
readonly items: RankingItemSpecSet;
readonly outer: TemporalWindow;
- readonly candidates: ColumnWindowCandidateSet;
+ readonly windows: ColumnWindowSet;
}): ColumnSchedule {
assertRankingHeader(input.header);
assert(input.header.variant === "column", "Column Schedule requires a Column header.");
assertRankingItemSpecSet(input.items);
assert(input.items.variant === "column", "Column Schedule requires Column Items.");
assert(input.items.items.length > 0, "Column requires at least one Item.");
- assertColumnWindowCandidateSet(input.candidates);
+ assertColumnWindowSet(input.windows);
frame(input.outer.span.startFrame, "Column outer window start");
frame(input.outer.span.endFrameExclusive, "Column outer window end");
assert(input.outer.span.endFrameExclusive > input.outer.span.startFrame, "Column outer window is empty.");
const items = [...input.items.items as readonly ColumnItemSpec[]]
.sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));
const expected = new Set(items.filter((item) => !item.preset).map((item) => item.id));
- const received = new Set(input.candidates.entries.map((entry) => entry.itemId));
+ const received = new Set(input.windows.entries.map((entry) => entry.itemId));
assert(expected.size === received.size && [...expected].every((id) => received.has(id)),
"Column non-preset Items and Selection windows differ.");
- const active = resolveColumnActiveWindows(input.candidates.entries, input.outer.span);
+ const orderedWindows = [...input.windows.entries].sort((left, right) =>
+ left.window.span.startFrame - right.window.span.startFrame
+ || left.window.span.endFrameExclusive - right.window.span.endFrameExclusive
+ || left.itemId.localeCompare(right.itemId));
+ for (const entry of orderedWindows) {
+ assert(entry.window.span.startFrame >= input.outer.span.startFrame
+ && entry.window.span.endFrameExclusive <= input.outer.span.endFrameExclusive,
+ `Column Item ${entry.itemId} window is outside the outer window.`);
+ }
+ for (let index = 1; index < orderedWindows.length; index += 1) {
+ const previous = orderedWindows[index - 1]!;
+ const current = orderedWindows[index]!;
+ assert(current.window.span.startFrame >= previous.window.span.endFrameExclusive,
+ `Column Item windows ${previous.itemId} and ${current.itemId} overlap.`);
+ }
const result: ColumnSchedule = {
id: input.header.id,
variant: "column",
@@ -463,13 +437,11 @@ export function buildColumnSchedule(input: {
mode: "preset" as const,
settled: { ...input.outer.span },
};
- const candidate = input.candidates.entries.find((entry) => entry.itemId === item.id)!;
- const window = active.get(item.id)!;
+ const window = input.windows.entries.find((entry) => entry.itemId === item.id)!.window.span;
return {
itemId: item.id,
mode: "reveal" as const,
- preferred: { ...candidate.window.span },
- active: { ...window },
+ window: { ...window },
settled: { startFrame: window.endFrameExclusive, endFrameExclusive: input.outer.span.endFrameExclusive },
};
}),
@@ -519,7 +491,7 @@ function assertColumnSchedule(value: ColumnSchedule): void {
assert(value.outer.endFrameExclusive > value.outer.startFrame, "ColumnSchedule.outer is empty.");
assert(value.entries.length > 0, "ColumnSchedule.entries is empty.");
const ids = new Set<string>();
- const active: Array<{ readonly itemId: string; readonly startFrame: number; readonly endFrameExclusive: number }> = [];
+ const windows: Array<{ readonly itemId: string; readonly startFrame: number; readonly endFrameExclusive: number }> = [];
for (const [index, entry] of value.entries.entries()) {
identity(entry.itemId, `ColumnSchedule.entries.${index}.itemId`);
assert(!ids.has(entry.itemId), `ColumnSchedule repeats ${entry.itemId}.`);
@@ -530,26 +502,22 @@ function assertColumnSchedule(value: ColumnSchedule): void {
`ColumnSchedule preset ${entry.itemId} does not occupy the outer window.`);
continue;
}
- frame(entry.preferred.startFrame, `ColumnSchedule.entries.${index}.preferred.startFrame`);
- frame(entry.preferred.endFrameExclusive, `ColumnSchedule.entries.${index}.preferred.endFrameExclusive`);
- assert(entry.preferred.endFrameExclusive > entry.preferred.startFrame,
- `ColumnSchedule.entries.${index}.preferred is empty.`);
- frame(entry.active.startFrame, `ColumnSchedule.entries.${index}.active.startFrame`);
- frame(entry.active.endFrameExclusive, `ColumnSchedule.entries.${index}.active.endFrameExclusive`);
- assert(entry.active.startFrame >= value.outer.startFrame
- && entry.active.endFrameExclusive <= value.outer.endFrameExclusive
- && entry.active.endFrameExclusive > entry.active.startFrame,
- `ColumnSchedule.entries.${index}.active is outside the outer window.`);
- assert(entry.settled.startFrame === entry.active.endFrameExclusive
+ frame(entry.window.startFrame, `ColumnSchedule.entries.${index}.window.startFrame`);
+ frame(entry.window.endFrameExclusive, `ColumnSchedule.entries.${index}.window.endFrameExclusive`);
+ assert(entry.window.startFrame >= value.outer.startFrame
+ && entry.window.endFrameExclusive <= value.outer.endFrameExclusive
+ && entry.window.endFrameExclusive > entry.window.startFrame,
+ `ColumnSchedule.entries.${index}.window is outside the outer window.`);
+ assert(entry.settled.startFrame === entry.window.endFrameExclusive
&& entry.settled.endFrameExclusive === value.outer.endFrameExclusive,
`ColumnSchedule.entries.${index}.settled is inconsistent.`);
- active.push({ itemId: entry.itemId, ...entry.active });
+ windows.push({ itemId: entry.itemId, ...entry.window });
}
- active.sort((left, right) => left.startFrame - right.startFrame
+ windows.sort((left, right) => left.startFrame - right.startFrame
|| left.endFrameExclusive - right.endFrameExclusive || left.itemId.localeCompare(right.itemId));
- for (let index = 1; index < active.length; index += 1) {
- assert(active[index]!.startFrame >= active[index - 1]!.endFrameExclusive,
- `ColumnSchedule active windows ${active[index - 1]!.itemId} and ${active[index]!.itemId} overlap.`);
+ for (let index = 1; index < windows.length; index += 1) {
+ assert(windows[index]!.startFrame >= windows[index - 1]!.endFrameExclusive,
+ `ColumnSchedule windows ${windows[index - 1]!.itemId} and ${windows[index]!.itemId} overlap.`);
}
}
@@ -753,11 +721,11 @@ export function buildColumnSoundEvents(schedule: RankingSchedule, style: ColumnS
columnIdsEqual(schedule, specs.items);
const events = schedule.entries.flatMap((entry) => {
if (entry.mode === "preset") return [];
- const duration = entry.active.endFrameExclusive - entry.active.startFrame;
+ const duration = entry.window.endFrameExclusive - entry.window.startFrame;
const fitted = fitColumnRevealMotion(duration, style.motion.appearFrames, style.motion.moveFrames);
- return [event(schedule.id, entry.itemId, "appear", entry.active.startFrame),
+ return [event(schedule.id, entry.itemId, "appear", entry.window.startFrame),
...(fitted.mode === "direct" ? []
- : [event(schedule.id, entry.itemId, "move", entry.active.endFrameExclusive - fitted.moveFrames)])];
+ : [event(schedule.id, entry.itemId, "move", entry.window.endFrameExclusive - fitted.moveFrames)])];
}).sort((left, right) => left.frame - right.frame || left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id));
return sealEvents(schedule.id, schedule.variant, events);
}
diff --git a/packages/ranking/src/types.ts b/packages/ranking/src/types.ts
index c46e8d54..32083817 100644
--- a/packages/ranking/src/types.ts
+++ b/packages/ranking/src/types.ts
@@ -39,13 +39,13 @@ export type TriggeredRankingCandidateSet = {
readonly entries: readonly TriggeredRankingCandidate[];
};
-export type ColumnWindowCandidate = {
+export type ColumnWindowInput = {
readonly itemId: string;
readonly window: TemporalWindow;
};
-export type ColumnWindowCandidateSet = {
- readonly entries: readonly ColumnWindowCandidate[];
+export type ColumnWindowSet = {
+ readonly entries: readonly ColumnWindowInput[];
};
export type ColumnScheduleEntry =
@@ -57,8 +57,7 @@ export type ColumnScheduleEntry =
| {
readonly itemId: string;
readonly mode: "reveal";
- readonly preferred: FrameSpan;
- readonly active: FrameSpan;
+ readonly window: FrameSpan;
readonly settled: FrameSpan;
};
diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.ts
index 2a8296b3..ee0edd10 100644
--- a/packages/ranking/test/ranking.test.ts
+++ b/packages/ranking/test/ranking.test.ts
@@ -14,7 +14,7 @@ import type { SvsRecipe } from "@hypit/svs";
import {
appendColumnItem,
- appendColumnWindowCandidateWindow,
+ appendColumnWindow,
appendRankingItemSpec,
appendRankingSound,
appendTierBoardItem,
@@ -29,7 +29,7 @@ import {
buildTopThreeProgram,
buildTopThreeSoundEvents,
createColumnItemSet,
- createColumnWindowCandidateSet,
+ createColumnWindowSet,
createRankingItemSpecSet,
createRankingSoundSet,
createTierBoardItemSet,
@@ -128,6 +128,7 @@ const selection = (id: string, startAnchorId: string, endAnchorId: string): Narr
});
const early = selection("early", "early-start", "early-end");
const overlapping = selection("overlapping", "overlap-start", "overlap-end");
+const middle = selection("middle", "early-end", "overlap-end");
const late = selection("late", "late-start", "late-end");
const triggerAnchors = ["one", "two", "three", "four"] as const;
const font: FontArtifactRef = {
@@ -198,11 +199,11 @@ function buildRankingSchedule(input: {
});
}
-function appendColumnWindowCandidate(
- set: ReturnType<typeof createColumnWindowCandidateSet>, spec: ColumnItemSpec,
+function appendProjectedColumnWindow(
+ set: ReturnType<typeof createColumnWindowSet>, spec: ColumnItemSpec,
semantic: typeof semanticTrack, selection: NarrativeSelectionRef,
) {
- return appendColumnWindowCandidateWindow(set, spec, projectSelectionWindow({
+ return appendColumnWindow(set, spec, projectSelectionWindow({
itemId: spec.id, semantic, selection,
projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}));
@@ -231,14 +232,14 @@ function columnSchedule(
windows: Readonly<Record<string, NarrativeSelectionRef>>,
outerWindow = projectColumnSegmentOuterWindow(semanticTrack, rankingSegment),
): ColumnSchedule {
- let candidates = createColumnWindowCandidateSet();
+ let set = createColumnWindowSet();
for (const value of values) {
if (value.preset) continue;
const timing = windows[value.id];
if (timing === undefined) throw new Error(`Missing test Selection for ${value.id}.`);
- candidates = appendColumnWindowCandidate(candidates, value, semanticTrack, timing);
+ set = appendProjectedColumnWindow(set, value, semanticTrack, timing);
}
- return buildColumnSchedule({ header: owner, items: specs(owner, values), outer: outerWindow, candidates });
+ return buildColumnSchedule({ header: owner, items: specs(owner, values), outer: outerWindow, windows: set });
}
test("RankingSchedule derives chronological Item order from item-owned Moments and preserves a settled suffix", () => {
@@ -297,7 +298,7 @@ test("TierBoard owns cumulative direct/stage placement and rejects invalid sched
}), /outside|strictly increasing/u);
});
-test("Column projects a Segment outer, keeps rank independent from reveal time, presets rows and avoids overlaps", () => {
+test("Column consumes explicit disjoint reveal windows without changing them", () => {
const owner = header("column", "column");
const semantic = [
columnSpec("late-rank-one", 1),
@@ -316,19 +317,19 @@ test("Column projects a Segment outer, keeps rank independent from reveal time,
const value = columnSchedule(owner, semantic, {
"late-rank-one": late,
"early-rank-five": early,
- "overlap-rank-two": overlapping,
+ "overlap-rank-two": middle,
}, outerWindow);
const program = buildColumnProgram(owner, canvas, frame, value, style, set);
const track = renderColumn(space, program);
assert.deepEqual(program.items.map((item) => [item.id, item.rank]), [
["late-rank-one", 1], ["overlap-rank-two", 2], ["preset-rank-three", 3], ["early-rank-five", 5],
]);
- const active = value.entries.filter((entry) => entry.mode === "reveal")
- .map((entry) => [entry.itemId, entry.preferred, entry.active]);
- assert.deepEqual(active, [
- ["late-rank-one", { startFrame: 120, endFrameExclusive: 160 }, { startFrame: 120, endFrameExclusive: 160 }],
- ["overlap-rank-two", { startFrame: 55, endFrameExclusive: 95 }, { startFrame: 65, endFrameExclusive: 95 }],
- ["early-rank-five", { startFrame: 25, endFrameExclusive: 65 }, { startFrame: 25, endFrameExclusive: 65 }],
+ const windows = value.entries.filter((entry) => entry.mode === "reveal")
+ .map((entry) => [entry.itemId, entry.window]);
+ assert.deepEqual(windows, [
+ ["late-rank-one", { startFrame: 120, endFrameExclusive: 160 }],
+ ["overlap-rank-two", { startFrame: 65, endFrameExclusive: 95 }],
+ ["early-rank-five", { startFrame: 25, endFrameExclusive: 65 }],
]);
const preset = value.entries.find((entry) => entry.itemId === "preset-rank-three")!;
assert.deepEqual(preset, { itemId: "preset-rank-three", mode: "preset", settled: outerWindow.span });
@@ -339,6 +340,27 @@ test("Column projects a Segment outer, keeps rank independent from reveal time,
assert.equal(track.presents.find((item) => item.id.endsWith(":item:preset-rank-three:settled"))?.span.startFrame, 10);
});
+test("Column rejects overlapping or out-of-bounds reveal windows", () => {
+ const owner = header("column", "strict-column");
+ const values = [columnSpec("one", 1), columnSpec("two", 2)];
+ assert.throws(() => columnSchedule(owner, values, { one: early, two: overlapping }),
+ /windows one and two overlap/u);
+
+ const outerWindow = projectColumnSegmentOuterWindow(semanticTrack, rankingSegment);
+ let windows = createColumnWindowSet();
+ const projected = projectSelectionWindow({
+ itemId: "one", semantic: semanticTrack, selection: early,
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ });
+ windows = appendColumnWindow(windows, values[0]!, {
+ ...projected,
+ span: { startFrame: outerWindow.span.startFrame - 1, endFrameExclusive: projected.span.endFrameExclusive },
+ });
+ assert.throws(() => buildColumnSchedule({
+ header: owner, items: specs(owner, [values[0]!]), outer: outerWindow, windows,
+ }), /one window is outside/u);
+});
+
test("TopThree accepts one to three optional-image Items and removes active accent in the settled suffix", () => {
const owner = header("top-three", "podium");
const semantic = [topSpec("gold"), topSpec("silver"), topSpec("bronze")];
@@ -374,7 +396,7 @@ test("visual and sound event plans share exact phase frames while absent sound s
const decoded = decodeColumnStyle(recipe("ranking.column", {
"appear-frames": 4, "move-frames": 6, "appear-gain": 0.8, "move-gain": 0.6,
}), font);
- const value = columnSchedule(owner, semantic, { one: early, two: overlapping });
+ const value = columnSchedule(owner, semantic, { one: early, two: middle });
const events = buildColumnSoundEvents(value, decoded.style, specs(owner, semantic));
assert.deepEqual(events.events.map((item) => [item.kind, item.frame]), [
["appear", 25], ["move", 59], ["appear", 65], ["move", 89],
diff --git a/packages/script/src/edit.ts b/packages/script/src/edit.ts
new file mode 100644
index 00000000..dffeac40
--- /dev/null
+++ b/packages/script/src/edit.ts
@@ -0,0 +1,161 @@
+import type { SourceRange } from "@hypit/protocol";
+
+import { narrativeValue } from "./narrative.js";
+import { parseScript } from "./parser.js";
+import type { Affinity, ParsedNarrative, SemanticAnchor } from "./types.js";
+
+export type ScriptAnchorEditSite = {
+ readonly anchorId: string;
+ readonly kind: SemanticAnchor["kind"];
+ readonly segmentId: string;
+ readonly offset: number;
+ readonly affinity: Affinity;
+ readonly placement: "before" | "after";
+};
+
+export type ScriptSelectionAdjustment = {
+ readonly id: string;
+ readonly startAnchorId: string;
+ readonly endAnchorId: string;
+};
+
+export type ScriptMomentAdjustment = {
+ readonly id: string;
+ readonly anchorId: string;
+};
+
+type Edit = { readonly range: SourceRange; readonly replacement: string };
+
+/** Script owns the exact source inverse of every one of its 2M + 2N anchors. */
+export function scriptAnchorEditSites(parsed: ParsedNarrative): readonly ScriptAnchorEditSite[] {
+ const segments = new Map(parsed.segments.map((segment) => [segment.id, segment] as const));
+ const tokens = new Map(parsed.tokens.map((token) => [token.id, token] as const));
+ return parsed.semanticIndex.anchors.map((anchor): ScriptAnchorEditSite => {
+ const segment = segments.get(anchor.segmentId);
+ if (segment === undefined) throw new Error(`Semantic Anchor ${anchor.id} names unknown Segment ${anchor.segmentId}.`);
+ if (anchor.kind === "segment-start") {
+ const first = parsed.tokens[segment.tokenStart];
+ return {
+ anchorId: anchor.id, kind: anchor.kind, segmentId: anchor.segmentId,
+ offset: first?.range.start ?? segment.contentRange.start,
+ affinity: "left", placement: "before",
+ };
+ }
+ if (anchor.kind === "segment-end") {
+ const last = parsed.tokens[segment.tokenEndExclusive - 1];
+ return {
+ anchorId: anchor.id, kind: anchor.kind, segmentId: anchor.segmentId,
+ offset: last?.range.end ?? segment.contentRange.end,
+ affinity: "right", placement: "after",
+ };
+ }
+ const token = anchor.tokenId === undefined ? undefined : tokens.get(anchor.tokenId);
+ if (token === undefined) throw new Error(`Semantic Anchor ${anchor.id} names no Script Token.`);
+ return anchor.kind === "token-start" ? {
+ anchorId: anchor.id, kind: anchor.kind, segmentId: anchor.segmentId,
+ offset: token.range.start, affinity: "right", placement: "before",
+ } : {
+ anchorId: anchor.id, kind: anchor.kind, segmentId: anchor.segmentId,
+ offset: token.range.end, affinity: "left", placement: "after",
+ };
+ });
+}
+
+function marker(id: string, edge: "open" | "close", affinity: Affinity): string {
+ if (edge === "open") return affinity === "left" ? `~@${id}` : `@${id}`;
+ return affinity === "left" ? `@/${id}` : `@/${id}~`;
+}
+
+function insertion(id: string, edge: "open" | "close", site: ScriptAnchorEditSite): string {
+ const value = marker(id, edge, site.affinity);
+ return site.placement === "before" ? `${value} ` : ` ${value}`;
+}
+
+function momentInsertion(id: string, site: ScriptAnchorEditSite): string {
+ const value = site.affinity === "left" ? `~@${id}!` : `@${id}!`;
+ return site.placement === "before" ? `${value} ` : ` ${value}`;
+}
+
+function applyEdits(source: string, edits: readonly Edit[]): string {
+ let next = source;
+ const ordered = [...edits].sort((left, right) =>
+ right.range.start - left.range.start || right.range.end - left.range.end);
+ for (const edit of ordered) {
+ if (edit.range.start < 0 || edit.range.end < edit.range.start || edit.range.end > source.length) {
+ throw new Error("Script marker edit lies outside its Source.");
+ }
+ next = `${next.slice(0, edit.range.start)}${edit.replacement}${next.slice(edit.range.end)}`;
+ }
+ return next;
+}
+
+/**
+ * Relocate one shared Selection by anchor identity. The returned Source is accepted only when
+ * reparsing proves the requested public Narrative, so Studio never edits prose by frame guess.
+ */
+export function adjustScriptSelection(input: {
+ readonly sourceName: string;
+ readonly source: string;
+ readonly parsed: ParsedNarrative;
+ readonly adjustment: ScriptSelectionAdjustment;
+}): string {
+ const selection = input.parsed.selections.find((candidate) => candidate.id === input.adjustment.id);
+ if (selection === undefined) throw new Error(`Script Selection ${input.adjustment.id} does not exist.`);
+ const sites = new Map(scriptAnchorEditSites(input.parsed).map((site) => [site.anchorId, site] as const));
+ const start = sites.get(input.adjustment.startAnchorId);
+ const end = sites.get(input.adjustment.endAnchorId);
+ if (start === undefined) throw new Error(`Selection start Anchor ${input.adjustment.startAnchorId} does not exist.`);
+ if (end === undefined) throw new Error(`Selection end Anchor ${input.adjustment.endAnchorId} does not exist.`);
+
+ const edits: Edit[] = [];
+ if (selection.startAnchorId !== start.anchorId) {
+ edits.push({ range: selection.open.range, replacement: "" });
+ edits.push({ range: { start: start.offset, end: start.offset }, replacement: insertion(selection.id, "open", start) });
+ }
+ if (selection.endAnchorId !== end.anchorId) {
+ edits.push({ range: selection.close.range, replacement: "" });
+ edits.push({ range: { start: end.offset, end: end.offset }, replacement: insertion(selection.id, "close", end) });
+ }
+ if (edits.length === 0) return input.source;
+ const next = applyEdits(input.source, edits);
+ const reparsed = parseScript(input.sourceName, next);
+ const rewritten = reparsed.selections.find((candidate) => candidate.id === selection.id);
+ if (rewritten?.startAnchorId !== start.anchorId || rewritten.endAnchorId !== end.anchorId) {
+ throw new Error(`Script refused to move Selection ${selection.id} to the requested Anchors.`);
+ }
+ const before = narrativeValue(input.parsed) as unknown as { readonly selections: readonly { readonly id: string }[] };
+ const after = narrativeValue(reparsed) as unknown as { readonly selections: readonly { readonly id: string }[] };
+ if (before.selections.length !== after.selections.length
+ || before.selections.some((item) => !after.selections.some((candidate) => candidate.id === item.id))) {
+ throw new Error("Script Selection adjustment changed authored identities.");
+ }
+ return next;
+}
+
+/** Relocate one Moment to an exact semantic Anchor without changing its identity. */
+export function adjustScriptMoment(input: {
+ readonly sourceName: string;
+ readonly source: string;
+ readonly parsed: ParsedNarrative;
+ readonly adjustment: ScriptMomentAdjustment;
+}): string {
+ const moment = input.parsed.moments.find((candidate) => candidate.id === input.adjustment.id);
+ if (moment === undefined) throw new Error(`Script Moment ${input.adjustment.id} does not exist.`);
+ const site = scriptAnchorEditSites(input.parsed).find((candidate) => candidate.anchorId === input.adjustment.anchorId);
+ if (site === undefined) throw new Error(`Moment Anchor ${input.adjustment.anchorId} does not exist.`);
+ if (moment.anchorId === site.anchorId) return input.source;
+ const next = applyEdits(input.source, [
+ { range: moment.range, replacement: "" },
+ { range: { start: site.offset, end: site.offset }, replacement: momentInsertion(moment.id, site) },
+ ]);
+ const reparsed = parseScript(input.sourceName, next);
+ const rewritten = reparsed.moments.find((candidate) => candidate.id === moment.id);
+ if (rewritten?.anchorId !== site.anchorId) {
+ throw new Error(`Script refused to move Moment ${moment.id} to the requested Anchor.`);
+ }
+ if (reparsed.moments.length !== input.parsed.moments.length
+ || input.parsed.moments.some((item) => !reparsed.moments.some((candidate) => candidate.id === item.id))) {
+ throw new Error("Script Moment adjustment changed authored identities.");
+ }
+ return next;
+}
diff --git a/packages/script/src/index.ts b/packages/script/src/index.ts
index e958c315..f502de57 100644
--- a/packages/script/src/index.ts
+++ b/packages/script/src/index.ts
@@ -1,4 +1,5 @@
export { ScriptSyntaxError } from "./error.js";
+export { adjustScriptMoment, adjustScriptSelection, scriptAnchorEditSites } from "./edit.js";
export { formatScript } from "./format.js";
export { captionDocumentType, narrativeExcerptType, narrativeMomentType, narrativeSelectionType, narrativeSchema, narrativeType, scriptManifest, scriptMarkupSurfaces, scriptModuleRef } from "./manifest.js";
export {
diff --git a/packages/script/src/parser.ts b/packages/script/src/parser.ts
index 898545bc..0e18ef53 100644
--- a/packages/script/src/parser.ts
+++ b/packages/script/src/parser.ts
@@ -35,6 +35,7 @@ type MutableSegment = {
readonly atoms: ParsedAtom[];
readonly tokenStart: number;
readonly sourceStart: number;
+ readonly contentStart: number;
lexicalRun: string;
readonly lexicalMarkers: Array<{ readonly position: number; readonly offset: number }>;
};
@@ -131,7 +132,9 @@ export function parseScript(
input: string,
sourceOffset = 0,
): ParsedNarrative {
- const source = input.replace(/\r\n?/gu, "\n").normalize("NFC");
+ // Source ranges are a public inverse used by Studio and diagnostics. Parse
+ // the exact UTF-16 text so CRLF and decomposed Unicode never shift an edit.
+ const source = input;
const fail = (code: string, message: string, offset?: number): never => {
throw new ScriptSyntaxError(code, message, sourceName, offset === undefined ? undefined : sourceOffset + offset);
};
@@ -520,7 +523,7 @@ export function parseScript(
}
};
- const closeCurrent = (end: number, selfClosing: boolean): void => {
+ const closeCurrent = (end: number, selfClosing: boolean, contentEnd = end): void => {
const segment = current
?? fail("SCRIPT_SEGMENT_CLOSE", "Segment close has no matching open.", end);
finishLexicalRun();
@@ -533,6 +536,7 @@ export function parseScript(
tokenEndExclusive: tokens.length,
atoms: segment.atoms,
range: { start: segment.sourceStart, end: sourceOffset + end },
+ contentRange: { start: segment.contentStart, end: sourceOffset + contentEnd },
selfClosing,
});
current = undefined;
@@ -559,16 +563,18 @@ export function parseScript(
if (segments.some((segment) => segment.id === id)) {
fail("SCRIPT_SEGMENT_DUPLICATE", `Duplicate Segment id "${id}".`, offset);
}
+ const contentStart = offset + open[0].length;
current = {
id,
index: segments.length,
atoms: [],
tokenStart: tokens.length,
sourceStart: sourceOffset + offset,
+ contentStart: sourceOffset + contentStart,
lexicalRun: "",
lexicalMarkers: [],
};
- offset += open[0].length;
+ offset = contentStart;
if (self) closeCurrent(offset, true);
continue;
}
@@ -587,8 +593,9 @@ export function parseScript(
if (close[1] !== current.id) {
fail("SCRIPT_SEGMENT_MISMATCH", `Segment "${current.id}" was closed by "${close[1]}".`, offset);
}
+ const contentEnd = offset;
offset += close[0].length;
- closeCurrent(offset, false);
+ closeCurrent(offset, false, contentEnd);
continue;
}
diff --git a/packages/script/src/types.ts b/packages/script/src/types.ts
index 383d7589..ac5a7675 100644
--- a/packages/script/src/types.ts
+++ b/packages/script/src/types.ts
@@ -35,6 +35,8 @@ export type ParsedSegment = NarrativeSegment & {
readonly index: number;
readonly atoms: readonly ParsedAtom[];
readonly range: SourceRange;
+ /** Exact body range between the Segment tags, used only for source-preserving marker edits. */
+ readonly contentRange: SourceRange;
readonly selfClosing: boolean;
};
diff --git a/packages/script/test/script.test.ts b/packages/script/test/script.test.ts
index c4fe92d9..7f649d3d 100644
--- a/packages/script/test/script.test.ts
+++ b/packages/script/test/script.test.ts
@@ -3,6 +3,8 @@ import test from "node:test";
import {
ScriptSyntaxError,
+ adjustScriptMoment,
+ adjustScriptSelection,
captionDocument,
narrativeValue,
parseScript,
@@ -11,6 +13,54 @@ import {
serializeSpeech,
} from "@hypit/script";
+test("Selection source edits relocate markers by 2M + 2N Anchor identity", () => {
+ const source = "<one><HOST>@focus alpha beta @/focus gamma</one>\r\n<two><HOST>delta epsilon</two>";
+ const parsed = parseScript("selection-adjust.svml", source);
+ const movedWords = adjustScriptSelection({
+ sourceName: "selection-adjust.svml",
+ source,
+ parsed,
+ adjustment: {
+ id: "focus",
+ startAnchorId: "segment:one:token:2:start",
+ endAnchorId: "segment:one:token:3:end",
+ },
+ });
+ const wordSelection = parseScript("selection-adjust.svml", movedWords).selections[0]!;
+ assert.deepEqual([wordSelection.startAnchorId, wordSelection.endAnchorId], [
+ "segment:one:token:2:start", "segment:one:token:3:end",
+ ]);
+
+ const movedSegment = adjustScriptSelection({
+ sourceName: "selection-adjust.svml",
+ source: movedWords,
+ parsed: parseScript("selection-adjust.svml", movedWords),
+ adjustment: {
+ id: "focus",
+ startAnchorId: "segment:two:start",
+ endAnchorId: "segment:two:end",
+ },
+ });
+ const reparsed = parseScript("selection-adjust.svml", movedSegment);
+ assert.deepEqual(reparsed.tokens.map((token) => token.text), ["alpha", "beta", "gamma", "delta", "epsilon"]);
+ assert.deepEqual([reparsed.selections[0]!.startAnchorId, reparsed.selections[0]!.endAnchorId], [
+ "segment:two:start", "segment:two:end",
+ ]);
+});
+
+test("Moment source edits relocate one marker to an exact semantic Anchor", () => {
+ const source = "<one><HOST>alpha @cue! beta</one><two><HOST>gamma</two>";
+ const moved = adjustScriptMoment({
+ sourceName: "moment-adjust.svml",
+ source,
+ parsed: parseScript("moment-adjust.svml", source),
+ adjustment: { id: "cue", anchorId: "segment:two:end" },
+ });
+ const parsed = parseScript("moment-adjust.svml", moved);
+ assert.equal(parsed.moments[0]!.anchorId, "segment:two:end");
+ assert.deepEqual(parsed.tokens.map((token) => token.text), ["alpha", "beta", "gamma"]);
+});
+
test("Script keeps speech, dialogue and CaptionDocument as separate projections", () => {
const parsed = parseScript("rich.svml", "<answer><BOB>I <laughed | laughed my ass off> there.</answer>");
assert.equal(serializeSpeech(parsed), "I laughed my ass off there.");
diff --git a/packages/studio-adapter/src/index.ts b/packages/studio-adapter/src/index.ts
index 542c66a5..ebee757c 100644
--- a/packages/studio-adapter/src/index.ts
+++ b/packages/studio-adapter/src/index.ts
@@ -118,18 +118,14 @@ export type StudioParameterDeclaration = {
readonly referenced?: readonly StudioParameterDeclaration[];
};
-export type StudioEditOperation =
+export type StudioTimelineGesture =
| "move"
| "trim-start"
- | "trim-end"
- | "slip"
- | "split"
- | "delete"
- | "duplicate"
- | "canvas-transform";
+ | "trim-end";
export type StudioEditCoordinate =
| "program-frame"
+ | "semantic-anchor"
| "source-frame"
| "canvas-pixel"
| "normalized-progress";
@@ -143,16 +139,32 @@ export type StudioEditSource = {
readonly source: StudioParameter["source"];
};
+export type StudioSemanticEditTarget =
+ | {
+ readonly kind: "selection";
+ readonly id: string;
+ readonly startAnchorId: string;
+ readonly endAnchorId: string;
+ }
+ | {
+ readonly kind: "moment";
+ readonly id: string;
+ readonly anchorId: string;
+ };
+
/** A timeline affordance is present only when its source write is explicit. */
export type StudioEditHandle = {
readonly id: string;
- readonly operation: StudioEditOperation;
+ readonly operation: "timeline.adjust";
+ readonly gesture: StudioTimelineGesture;
readonly enabled: boolean;
/** Coordinate space in which the central gesture resolver measures intent. */
readonly coordinate?: StudioEditCoordinate;
/** Snap policy is data, not a timeline-wide guess. */
readonly snapTo?: readonly StudioSnapTarget[];
readonly sources?: readonly StudioEditSource[];
+ /** Shared Script identity adjusted by this rectangle; every consumer follows it. */
+ readonly semantic?: StudioSemanticEditTarget;
readonly disabledReason?: string;
};
@@ -230,11 +242,14 @@ export type StudioSemanticTimeline = {
readonly tokens: readonly StudioSemanticToken[];
readonly selections: readonly {
readonly id: string;
+ readonly startAnchorId: string;
+ readonly endAnchorId: string;
readonly startFrame: number;
readonly endFrameExclusive: number;
}[];
readonly moments: readonly {
readonly id: string;
+ readonly anchorId: string;
readonly frame: number;
}[];
readonly provenance: StudioCandidateProvenance;
@@ -375,7 +390,7 @@ export type StudioAdapter = {
readonly inspector?: StudioInspectorDescription;
readonly parameters?: readonly StudioParameterDeclaration[];
/** Operations this adapter explicitly understands for its entities. */
- readonly editOperations?: readonly StudioEditOperation[];
+ readonly timelineGestures?: readonly StudioTimelineGesture[];
readonly project?: (context: StudioAdapterContext) => readonly StudioEntityDraft[];
};
@@ -431,7 +446,7 @@ export type StudioLaneAttachment = {
readonly interaction?: StudioInteraction;
readonly inspector?: StudioInspectorDescription;
readonly parameters?: readonly StudioParameterDeclaration[];
- readonly editOperations?: readonly StudioEditOperation[];
+ readonly timelineGestures?: readonly StudioTimelineGesture[];
};
export const readonlyInteraction: StudioInteraction = {
diff --git a/packages/studio-video-adapters/src/audio.ts b/packages/studio-video-adapters/src/audio.ts
index cc6f4a9b..bf738722 100644
--- a/packages/studio-video-adapters/src/audio.ts
+++ b/packages/studio-video-adapters/src/audio.ts
@@ -1,6 +1,7 @@
import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft } from "@hypit/studio-adapter";
import { childEntities, readonlyInteraction, sameSurfaceValue } from "@hypit/studio-adapter";
import { videoLaneHeights } from "./presentation.js";
+import { itemTemporalLineage } from "./temporal.js";
type AudioTrackProgramValue = {
readonly items?: readonly {
@@ -18,10 +19,17 @@ function projectAudio(context: StudioAdapterContext): readonly StudioEntityDraft
stackOrder: Number.MIN_SAFE_INTEGER,
preview: { kind: "audio" as const, url: `/__studio/material/${item.source.artifact.digest}` },
}));
- return childEntities(context, items, "audio-clip", "waveform").map((entity, index) => ({
- ...entity,
- preview: items[index]!.preview,
- }));
+ return childEntities(context, items, "audio-clip", "waveform").map((entity, index) => {
+ const temporal = itemTemporalLineage(context, items[index]!.id);
+ return {
+ ...entity,
+ preview: items[index]!.preview,
+ ...(temporal?.source.kind === "program" || temporal?.source.id === undefined
+ ? {}
+ : { markerId: temporal.source.id }),
+ ...(temporal === undefined ? {} : { temporal }),
+ };
+ });
}
export const audioAdapters: readonly StudioAdapter[] = [
@@ -29,7 +37,7 @@ export const audioAdapters: readonly StudioAdapter[] = [
{
id: "audio", role: "track", output: { type: "AudioTrack", surface: "track", modules: ["@hypit/audio-track"] },
family: "audio", icon: "waveform", interaction: readonlyInteraction,
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "semantic", label: "Semantic", writable: false },
{ name: "source", label: "Source", writable: false },
diff --git a/packages/studio-video-adapters/src/deck.ts b/packages/studio-video-adapters/src/deck.ts
index 567a960b..e81ebb59 100644
--- a/packages/studio-video-adapters/src/deck.ts
+++ b/packages/studio-video-adapters/src/deck.ts
@@ -44,6 +44,7 @@ export const deckAdapters: readonly StudioAdapter[] = [
id: "deck", role: "track",
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/deck-track"] },
family: "component", icon: "layers", realizationPorts: ["program"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "frame", label: "Frame", writable: false },
{ name: "appearance", label: "Appearance", writable: false },
diff --git a/packages/studio-video-adapters/src/generic.ts b/packages/studio-video-adapters/src/generic.ts
index 7747ed11..94163b35 100644
--- a/packages/studio-video-adapters/src/generic.ts
+++ b/packages/studio-video-adapters/src/generic.ts
@@ -43,6 +43,28 @@ type TerminalAudioTrack = {
}[];
};
+function withTemporalLineage(
+ context: StudioAdapterContext,
+ entity: StudioEntityDraft,
+): StudioEntityDraft {
+ const identities = [
+ entity.authoredId,
+ entity.markerId,
+ entity.presentId,
+ ...(entity.renderIds ?? []),
+ ].filter((value): value is string => value !== undefined);
+ const temporal = identities.map((identity) => itemTemporalLineage(context, identity))
+ .find((candidate) => candidate !== undefined);
+ if (temporal === undefined) return entity;
+ return {
+ ...entity,
+ ...(temporal.source.kind === "program" || temporal.source.id === undefined
+ ? {}
+ : { markerId: temporal.source.id }),
+ temporal,
+ };
+}
+
/** Terminal media has one Studio treatment regardless of which package authored it. */
export function projectTerminalVisual(context: StudioAdapterContext): readonly StudioEntityDraft[] {
const presents = new Map(((context.track.value as TerminalVisualTrack).presents ?? [])
@@ -52,7 +74,7 @@ export function projectTerminalVisual(context: StudioAdapterContext): readonly S
const material = present?.elements?.find((element) =>
(element.kind === "image" || element.kind === "video") && element.artifact?.digest !== undefined);
const digest = material?.artifact?.digest;
- return {
+ return withTemporalLineage(context, {
...entity,
presentation: { entity: "media-item", shape: "picture", depth: 0 },
...(digest === undefined ? {} : {
@@ -61,7 +83,7 @@ export function projectTerminalVisual(context: StudioAdapterContext): readonly S
url: `/__studio/material/${digest}`,
},
}),
- };
+ });
});
}
@@ -70,13 +92,13 @@ export function projectTerminalAudio(context: StudioAdapterContext): readonly St
.map((clip) => [clip.id, clip] as const));
return context.generic().map((entity, index) => {
const digest = clips.get(context.spans[index]?.id ?? "")?.artifact?.digest;
- return {
+ return withTemporalLineage(context, {
...entity,
presentation: { entity: "audio-clip", shape: "waveform", depth: 0 },
...(digest === undefined ? {} : {
preview: { kind: "audio" as const, url: `/__studio/material/${digest}` },
}),
- };
+ });
});
}
@@ -105,19 +127,23 @@ function projectText(context: StudioAdapterContext): readonly StudioEntityDraft[
}
function projectCaption(context: StudioAdapterContext): readonly StudioEntityDraft[] {
- return context.generic().map((entity) => ({
+ return context.generic().map((entity) => withTemporalLineage(context, {
...entity,
presentation: { entity: "caption-cue", shape: "text", depth: 0 },
interaction: readonlyInteraction,
}));
}
+function projectGenericComponent(context: StudioAdapterContext): readonly StudioEntityDraft[] {
+ return context.generic().map((entity) => withTemporalLineage(context, entity));
+}
+
export const genericAdapters: readonly StudioAdapter[] = [
{ id: "typography-program", role: "realization", output: { type: "TypographyTrackProgram", modules: ["@hypit/typography-track"] } },
{
id: "text", role: "text", output: { type: "VisualTrack", surface: "track", modules: ["@hypit/typography-track"] },
family: "text", icon: "text", interaction: readonlyInteraction,
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "semantic", label: "Semantic", writable: false },
{ name: "placement", label: "Placement", writable: false },
@@ -138,7 +164,7 @@ export const genericAdapters: readonly StudioAdapter[] = [
{
id: "caption", role: "caption", output: { type: "VisualTrack", surface: "track", modules: ["@hypit/caption-fine"] },
family: "caption", icon: "captions", interaction: readonlyInteraction,
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "document", label: "Document", writable: false },
{ name: "semantic", label: "Semantic", writable: false },
@@ -157,7 +183,7 @@ export const genericAdapters: readonly StudioAdapter[] = [
id: "component", role: "track",
output: { type: "VisualTrack", modules: ["@hypit/ranking", "@hypit/comment-sticker", "@hypit/screen-overlay"] },
family: "component", icon: "component", interaction: readonlyInteraction,
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "canvas", label: "Canvas", writable: false },
{ name: "semantic", label: "Semantic", writable: false },
@@ -202,10 +228,11 @@ export const genericAdapters: readonly StudioAdapter[] = [
{ name: "scan-line-opacity", label: "Scan-line opacity", control: "number", writable: true },
{ name: "motion-rate", label: "Motion rate", control: "number", writable: true },
],
+ project: projectGenericComponent,
lane: { layout: "flat", height: videoLaneHeights.component },
},
{ id: "audio-track", role: "track", output: { type: "AudioTrack" }, family: "audio", icon: "waveform", interaction: readonlyInteraction,
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "semantic", label: "Semantic", writable: false },
{ name: "during", label: "During", writable: false },
@@ -227,7 +254,7 @@ export const genericAdapters: readonly StudioAdapter[] = [
],
project: projectTerminalAudio, lane: { layout: "flat", height: videoLaneHeights.audio } },
{ id: "visual-track", role: "track", output: { type: "VisualTrack" }, family: "media", icon: "video", interaction: readonlyInteraction,
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "during", label: "During", writable: false },
{ name: "start", label: "Start", writable: true },
diff --git a/packages/studio-video-adapters/src/media.ts b/packages/studio-video-adapters/src/media.ts
index f8902b1e..2a29ab3b 100644
--- a/packages/studio-video-adapters/src/media.ts
+++ b/packages/studio-video-adapters/src/media.ts
@@ -91,7 +91,7 @@ export const mediaAdapters: readonly StudioAdapter[] = [
id: "media-visual", role: "media",
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/media-track"] },
family: "media", icon: "video", interaction: readonlyInteraction,
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "semantic", label: "Semantic", writable: false },
{ name: "canvas", label: "Canvas", writable: false },
@@ -133,7 +133,7 @@ export const mediaAdapters: readonly StudioAdapter[] = [
id: "media-audio", role: "media",
output: { type: "AudioTrack", surface: "track", modules: ["@hypit/media-track"] },
family: "media", icon: "waveform", interaction: readonlyInteraction,
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "semantic", label: "Semantic", writable: false },
{ name: "canvas", label: "Canvas", writable: false },
diff --git a/packages/studio-video-adapters/src/ranking.ts b/packages/studio-video-adapters/src/ranking.ts
index 2cadbb2d..7c3c4316 100644
--- a/packages/studio-video-adapters/src/ranking.ts
+++ b/packages/studio-video-adapters/src/ranking.ts
@@ -9,8 +9,7 @@ type RankingSchedule = {
readonly entries?: readonly ({ readonly itemId: string; readonly mode: "preset"; readonly settled: Span } | {
readonly itemId: string;
readonly mode: "reveal";
- readonly preferred: Span;
- readonly active: Span;
+ readonly window: Span;
readonly settled: Span;
} | {
readonly itemId: string;
@@ -80,7 +79,7 @@ function projectRanking(context: StudioAdapterContext): readonly StudioEntityDra
const temporal = temporalLineageFor(context, entry.itemId, "mode" in entry ? "window" : "activation");
const markerId = temporal?.source.id;
const preview = itemPreview(context, entry.itemId);
- const visible = "mode" in entry ? entry.active : entry.cumulative;
+ const visible = "mode" in entry ? entry.window : entry.cumulative;
return [{
id: `${context.track.outputRef}:entity:${entry.itemId}`,
authoredId: entry.itemId,
@@ -106,7 +105,7 @@ export const rankingAdapters: readonly StudioAdapter[] = [
id: "ranking-column", role: "track",
output: { type: "VisualTrack", surface: "column", modules: ["@hypit/ranking"] },
family: "component", label: "Ranking", icon: "ranking", realizationPorts: ["schedule"],
- editOperations: ["move", "trim-start", "trim-end"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "semantic", label: "Semantic", writable: false },
{ name: "canvas", label: "Canvas", writable: false },
@@ -144,6 +143,7 @@ export const rankingAdapters: readonly StudioAdapter[] = [
parameters: [
{ name: "during", label: "During", writable: false },
],
+ timelineGestures: ["move", "trim-start", "trim-end"],
}],
interaction: readonlyInteraction, project: projectRanking,
},
@@ -155,6 +155,7 @@ export const rankingAdapters: readonly StudioAdapter[] = [
id, role: "track",
output: { type: "VisualTrack", surface, modules: ["@hypit/ranking"] },
family: "component", label, icon: "ranking", realizationPorts: ["schedule"],
+ timelineGestures: ["move", "trim-start", "trim-end"],
parameters: [
{ name: "semantic", label: "Semantic", writable: false },
{ name: "style", label: "Style", writable: false },
@@ -171,6 +172,7 @@ export const rankingAdapters: readonly StudioAdapter[] = [
id: "activation", family: "ranking-reveal", label: "Activations", icon: "ranking", facet: "visual",
lane: { layout: "flat", height: { minPx: 34, preferredPx: 40, maxPx: 56 } },
parameters: [{ name: "at", label: "At", writable: false }],
+ timelineGestures: ["move", "trim-start", "trim-end"],
}],
interaction: readonlyInteraction,
project: projectRanking,
diff --git a/packages/studio/src/observe.ts b/packages/studio/src/observe.ts
index 0a6c193f..a5b838bc 100644
--- a/packages/studio/src/observe.ts
+++ b/packages/studio/src/observe.ts
@@ -217,15 +217,20 @@ function harvestScript(input: RawInput, into: Record<string, unknown>[]): void {
into.push({
format: "hypit.script-source-map@1",
record: id,
+ sourcePath: input.sourceName,
range: { start: input.openingStart, end: end + closing.length },
+ content: { start: input.contentStart, end },
segments: parsed.segments.map((segment) => ({ id: segment.id, range: segment.range })),
selections: parsed.selections.map((selection) => ({
id: selection.id,
+ startAnchorId: selection.startAnchorId,
+ endAnchorId: selection.endAnchorId,
open: selection.open.range,
close: selection.close.range,
})),
moments: parsed.moments.map((moment) => ({
id: moment.id,
+ anchorId: moment.anchorId,
range: moment.range,
})),
tokens: parsed.tokens.map((token) => ({ id: token.id, range: token.range })),
diff --git a/packages/studio/src/parameters.ts b/packages/studio/src/parameters.ts
index b72516c1..344d914b 100644
--- a/packages/studio/src/parameters.ts
+++ b/packages/studio/src/parameters.ts
@@ -6,6 +6,9 @@ import type {
StudioEntityDraft,
StudioPlacement,
StudioEditHandle,
+ StudioSemanticTimeline,
+ StudioTemporalLineage,
+ StudioTimelineGesture,
} from "@hypit/studio-adapter";
import { parseSvs } from "@hypit/svs";
@@ -85,13 +88,17 @@ function sourceFor(
files: readonly StudioSourceFile[],
base?: string,
): StudioSourceFile | undefined {
- const absolute = isAbsolute(path)
- ? resolve(path)
- : resolve(base === undefined ? root : dirname(base), path);
- return files.find((file) => resolve(file.path) === absolute)
+ const absolute = sourceAbsolute(root, path, base);
+ return files.find((file) => sourceAbsolute(root, file.path) === absolute)
?? files.find((file) => file.path === relative(root, absolute));
}
+function sourceAbsolute(root: string, path: string, base?: string): string {
+ if (isAbsolute(path)) return resolve(path);
+ const directory = base === undefined ? root : dirname(sourceAbsolute(root, base));
+ return resolve(directory, path);
+}
+
function svsText(source: string): string {
const header = /^\s*<\?svml[\s\S]*?\?>/u.exec(source);
if (header === null) return source;
@@ -145,7 +152,7 @@ function recipeParameters(input: {
language: "svs" as const,
writable: true,
source: {
- path: relative(input.root, resolve(source.path)),
+ path: relative(input.root, sourceAbsolute(input.root, source.path)),
range: property.valueRange,
preimage,
},
@@ -186,7 +193,7 @@ function referencedParameters(input: {
...(declaration.options === undefined ? {} : { options: declaration.options }),
...(declaration.unit === undefined ? {} : { unit: declaration.unit }),
source: {
- path: relative(input.root, resolve(target.sourcePath)),
+ path: relative(input.root, sourceAbsolute(input.root, target.sourcePath)),
range,
preimage,
},
@@ -239,7 +246,7 @@ export function parametersForDraft(input: {
...(declaration.options === undefined ? {} : { options: declaration.options }),
...(declaration.unit === undefined ? {} : { unit: declaration.unit }),
source: {
- path: relative(input.root, resolve(element.sourcePath)),
+ path: relative(input.root, sourceAbsolute(input.root, element.sourcePath)),
range,
preimage,
},
@@ -281,14 +288,17 @@ export function parametersForDraft(input: {
const ABSOLUTE_DURATION = /^\s*\d+(?:\.\d+)?(?:f|ms|s)\s*$/u;
/**
- * Timing handles are deliberately narrower than timing parameters. A literal
- * absolute start/end can be rewritten as frames without changing its semantic
- * source; a Selection/Moment expression cannot be moved from a downstream
- * rectangle. `at + for` has one legal edge: changing `for` changes only its end.
+ * Resolve an adapter-declared gesture through the entity's actual temporal
+ * lineage. A Selection is the writable author identity, so every rectangle
+ * projected from it edits the same Script markers. Literal absolute Windows
+ * remain directly writable. Other projections stay visible but read-only
+ * until their package declares an unambiguous inverse.
*/
-export function timingEditHandles(
+export function timelineAdjustHandles(
parameters: readonly StudioParameter[],
- declared: readonly import("@hypit/studio-adapter").StudioEditOperation[] = ["move", "trim-start", "trim-end"],
+ declared: readonly StudioTimelineGesture[] = ["move", "trim-start", "trim-end"],
+ temporal?: StudioTemporalLineage,
+ semantic?: StudioSemanticTimeline,
): readonly StudioEditHandle[] {
const byName = new Map<string, StudioParameter>();
for (const parameter of parameters) {
@@ -304,45 +314,98 @@ export function timingEditHandles(
const absolute = (parameter: StudioParameter | undefined): parameter is StudioParameter =>
parameter !== undefined && parameter.writable && ABSOLUTE_DURATION.test(parameter.value);
const allowed = new Set(declared);
- const disabled = (id: string, operation: StudioEditHandle["operation"], reason: string): StudioEditHandle => ({
- id, operation, enabled: false, disabledReason: reason,
+ const disabled = (gesture: StudioTimelineGesture, reason: string): StudioEditHandle => ({
+ id: `timeline.adjust:${gesture}`,
+ operation: "timeline.adjust",
+ gesture,
+ enabled: false,
+ disabledReason: reason,
});
const handles: StudioEditHandle[] = [];
- if (absolute(start) && absolute(end)) {
+ const selectionId = temporal?.source.kind === "selection" ? temporal.source.id : undefined;
+ const selection = selectionId === undefined
+ ? undefined
+ : semantic?.selections.find((candidate) => candidate.id === selectionId);
+ const momentId = temporal?.source.kind === "moment" ? temporal.source.id : undefined;
+ const moment = momentId === undefined
+ ? undefined
+ : semantic?.moments.find((candidate) => candidate.id === momentId);
+ if (selection !== undefined) {
+ const target = {
+ kind: "selection" as const,
+ id: selection.id,
+ startAnchorId: selection.startAnchorId,
+ endAnchorId: selection.endAnchorId,
+ };
+ for (const gesture of ["move", "trim-start", "trim-end"] as const) {
+ if (!allowed.has(gesture)) continue;
+ handles.push({
+ id: `timeline.adjust:${gesture}`,
+ operation: "timeline.adjust",
+ gesture,
+ enabled: true,
+ coordinate: "semantic-anchor",
+ snapTo: ["semantic-anchor"],
+ semantic: target,
+ });
+ }
+ } else if (moment !== undefined) {
+ if (allowed.has("move")) handles.push({
+ id: "timeline.adjust:move",
+ operation: "timeline.adjust",
+ gesture: "move",
+ enabled: true,
+ coordinate: "semantic-anchor",
+ snapTo: ["semantic-anchor"],
+ semantic: { kind: "moment", id: moment.id, anchorId: moment.anchorId },
+ });
+ if (allowed.has("trim-start")) {
+ handles.push(disabled("trim-start", "起点由 Moment 决定;拖动实体会移动 Moment,不能单独裁起点。"));
+ }
+ if (allowed.has("trim-end")) {
+ if (absolute(duration)) handles.push({
+ id: "timeline.adjust:trim-end",
+ operation: "timeline.adjust",
+ gesture: "trim-end",
+ enabled: true,
+ coordinate: "program-frame",
+ snapTo: ["frame", "semantic-anchor", "item-edge"],
+ sources: [{ role: "duration", source: duration.source }],
+ });
+ else handles.push(disabled("trim-end", "该 Moment 消费没有独立可写的 duration。"));
+ }
+ } else if (absolute(start) && absolute(end)) {
if (allowed.has("move")) handles.push({
- id: "move", operation: "move", enabled: true, coordinate: "program-frame",
+ id: "timeline.adjust:move", operation: "timeline.adjust", gesture: "move", enabled: true, coordinate: "program-frame",
snapTo: ["frame", "semantic-anchor", "item-edge"], sources: [
{ role: "start", source: start.source },
{ role: "end", source: end.source },
],
});
if (allowed.has("trim-start")) handles.push({
- id: "trim-start", operation: "trim-start", enabled: true, coordinate: "program-frame",
+ id: "timeline.adjust:trim-start", operation: "timeline.adjust", gesture: "trim-start", enabled: true, coordinate: "program-frame",
snapTo: ["frame", "semantic-anchor", "item-edge"], sources: [{ role: "start", source: start.source }],
});
if (allowed.has("trim-end")) handles.push({
- id: "trim-end", operation: "trim-end", enabled: true, coordinate: "program-frame",
+ id: "timeline.adjust:trim-end", operation: "timeline.adjust", gesture: "trim-end", enabled: true, coordinate: "program-frame",
snapTo: ["frame", "semantic-anchor", "item-edge"], sources: [{ role: "end", source: end.source }],
});
} else if (at !== undefined && !at.writable && absolute(duration)) {
- if (allowed.has("move")) handles.push(disabled("move", "move", "起点由 At 引用决定,不能独立移动。"));
- if (allowed.has("trim-start")) handles.push(disabled("trim-start", "trim-start", "起点由 At 引用决定,不能独立裁剪。"));
+ if (allowed.has("move")) handles.push(disabled("move", "起点由 At 引用决定,不能独立移动。"));
+ if (allowed.has("trim-start")) handles.push(disabled("trim-start", "起点由 At 引用决定,不能独立裁剪。"));
if (allowed.has("trim-end")) handles.push({
- id: "trim-end", operation: "trim-end", enabled: true, coordinate: "program-frame",
+ id: "timeline.adjust:trim-end", operation: "timeline.adjust", gesture: "trim-end", enabled: true, coordinate: "program-frame",
snapTo: ["frame", "semantic-anchor", "item-edge"], sources: [{ role: "duration", source: duration.source }],
});
} else {
- const reason = parameters.some((parameter) => parameter.name === "during" && !parameter.writable)
- ? "时间窗由 Selection、Segment、Moment 或 Program 投影提供。请修改来源或投影,不拖动消费结果。"
+ const reason = selectionId !== undefined
+ ? `Selection ${selectionId} 没有出现在当前语义 Candidate 中。`
+ : parameters.some((parameter) => parameter.name === "during" && !parameter.writable)
+ ? "该投影尚未声明唯一的作者语义逆变换。"
: "没有可逆的绝对时间端点源码范围。";
- if (allowed.has("move")) handles.push(disabled("move", "move", reason));
- if (allowed.has("trim-start")) handles.push(disabled("trim-start", "trim-start", reason));
- if (allowed.has("trim-end")) handles.push(disabled("trim-end", "trim-end", reason));
+ if (allowed.has("move")) handles.push(disabled("move", reason));
+ if (allowed.has("trim-start")) handles.push(disabled("trim-start", reason));
+ if (allowed.has("trim-end")) handles.push(disabled("trim-end", reason));
}
- if (allowed.has("slip")) handles.push(disabled("slip", "slip", "素材内部时间尚未声明为可回写的作者参数。"));
- if (allowed.has("split")) handles.push(disabled("split", "split", "切分会创建新的作者实体,当前没有唯一的 SVML 写回方案。"));
- if (allowed.has("delete")) handles.push(disabled("delete", "delete", "删除需要同时处理作者元素与全部引用,当前保持只读。"));
- if (allowed.has("duplicate")) handles.push(disabled("duplicate", "duplicate", "复制需要生成新的作者身份和引用,当前保持只读。"));
- if (allowed.has("canvas-transform")) handles.push(disabled("canvas-transform", "canvas-transform", "画布几何由 Frame/Point 作者值控制,当前没有唯一可写范围。"));
return handles;
}
diff --git a/packages/studio/src/server.ts b/packages/studio/src/server.ts
index c1d1c7a7..ca2fbf60 100644
--- a/packages/studio/src/server.ts
+++ b/packages/studio/src/server.ts
@@ -5,6 +5,7 @@ import { readFile, rename, writeFile, unlink } from "node:fs/promises";
import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
import type { Plugin, ViteDevServer } from "vite";
+import { adjustScriptMoment, adjustScriptSelection, parseScript } from "@hypit/script";
import type { StudioArchive } from "./archive.js";
import type { ServedFile } from "./compile.js";
@@ -12,7 +13,7 @@ import type { StudioDomain } from "./domain.js";
import type { StudioAdapterRegistry } from "./studio-registry.js";
import { loadStudioRun } from "./run.js";
import { readStudioSession } from "./session.js";
-import type { Range, StudioFailure, StudioSnapshot } from "./shared.js";
+import type { Range, StudioFailure, StudioMutation, StudioSnapshot } from "./shared.js";
import { createStudioStoryboard } from "./storyboard.js";
import type { StudioStoryboard } from "./storyboard.js";
import { findSurfacePreview } from "./surface-preview.js";
@@ -46,9 +47,11 @@ function rangeOf(error: unknown): Range | undefined {
}
function conflict(error: unknown): boolean {
- return error instanceof Error && /changed outside Studio|Source changed outside Studio/u.test(error.message);
+ return error instanceof Error && /changed outside Studio|Source changed outside Studio|mutation is already in progress/u.test(error.message);
}
+class StudioMutationRejected extends Error {}
+
export function studioPlugin(options: StudioPluginOptions): Plugin {
let snapshot: StudioSnapshot | undefined;
let failure: StudioFailure | undefined;
@@ -56,6 +59,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
let revision = 0;
let server: ViteDevServer | undefined;
let timer: ReturnType<typeof setTimeout> | undefined;
+ let mutating = false;
let requestedRevision = 0;
let currentSource = options.source;
let allowedSourceFiles = new Set<string>();
@@ -65,14 +69,14 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
const watchSource = (path: string): void => {
if (watched.has(path)) return;
try {
- watched.set(path, watch(path, () => schedule()));
+ watched.set(path, watch(path, () => { if (!mutating) schedule(); }));
} catch {
// Some Hosts may report virtual Source ids. They are still recompiled
// whenever a real Source revision is scheduled; they simply emit no file event.
}
};
- const publish = async (attempt: number): Promise<void> => {
+ const publish = async (attempt: number, notify = true): Promise<void> => {
try {
// SVML and SVRun form one Studio source of truth. Recompile both for
// every revision so a new Author graph is never executed through an old
@@ -104,7 +108,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
snapshot = result.snapshot;
material = result.material;
failure = undefined;
- server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
+ if (notify) server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
} catch (error) {
if (attempt !== requestedRevision) return;
revision = attempt;
@@ -114,7 +118,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
error: error instanceof Error ? error.message : String(error),
...(range === undefined ? {} : { range }),
};
- server?.ws.send({ type: "custom", event: "studio:error", data: failure });
+ if (notify) server?.ws.send({ type: "custom", event: "studio:error", data: failure });
}
};
@@ -131,7 +135,26 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
readonly preimage: string;
};
- const applyTransaction = async (patches: readonly Patch[], expectedRevision: number): Promise<void> => {
+ const replaceFiles = async (files: ReadonlyMap<string, string>): Promise<void> => {
+ const temporaries: { readonly path: string; readonly temporary: string }[] = [];
+ try {
+ for (const [absolute, text] of files) {
+ const temporary = join(dirname(absolute), `.${basename(absolute)}.hypit-studio.tmp`);
+ await writeFile(temporary, text, "utf8");
+ temporaries.push({ path: absolute, temporary });
+ }
+ for (const item of temporaries) await rename(item.temporary, item.path);
+ } finally {
+ for (const item of temporaries) {
+ try { await unlink(item.temporary); } catch { /* already renamed */ }
+ }
+ }
+ };
+
+ const applyTransaction = async (
+ patches: readonly Patch[],
+ expectedRevision: number,
+ ): Promise<ReadonlyMap<string, string>> => {
if (snapshot !== undefined && expectedRevision !== snapshot.revision) {
throw new Error("The Source changed outside Studio.");
}
@@ -152,8 +175,10 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
grouped.set(absolute, held);
}
const nextFiles = new Map<string, string>();
+ const previousFiles = new Map<string, string>();
for (const [absolute, filePatches] of grouped) {
const text = await readFile(absolute, "utf8");
+ previousFiles.set(absolute, text);
const ordered = [...filePatches].sort((left, right) => left.range.start - right.range.start);
for (let index = 1; index < ordered.length; index += 1) {
const previous = ordered[index - 1]!;
@@ -169,22 +194,161 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
if (current !== patch.preimage) throw new Error(`Source changed outside Studio: ${patch.path}.`);
next = `${next.slice(0, patch.range.start)}${patch.replacement}${next.slice(patch.range.end)}`;
}
- nextFiles.set(absolute, next);
+ if (next !== text) nextFiles.set(absolute, next);
}
- // Validate every file before touching any file. Temp files make a single
- // multi-file write observable as one Studio transaction in normal hosts.
- const temporaries: { readonly path: string; readonly temporary: string }[] = [];
+ await replaceFiles(nextFiles);
+ 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.`);
+ return found;
+ };
+
+ const timelinePatches = async (
+ mutation: Extract<StudioMutation, { readonly type: "timeline.adjust" }>,
+ ): Promise<readonly Patch[]> => {
+ const clip = currentClip(mutation.entityId);
+ const handle = clip.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 (mutation.target.kind === "selection" || mutation.target.kind === "moment") {
+ const target = mutation.target;
+ if (handle.semantic?.kind !== target.kind) {
+ throw new Error(`Entity ${mutation.entityId} is not bound to a writable ${target.kind}.`);
+ }
+ const current = snapshot;
+ const script = current?.script;
+ if (current === undefined || script === undefined) throw new Error("Studio has no writable Script source map.");
+ if (target.kind === "selection") {
+ const startIndex = current.semantic.anchors.findIndex((anchor) => anchor.id === target.startAnchorId);
+ const endIndex = current.semantic.anchors.findIndex((anchor) => anchor.id === target.endAnchorId);
+ if (startIndex < 0 || endIndex < 0 || startIndex >= endIndex
+ || current.semantic.anchors[startIndex]!.frame >= current.semantic.anchors[endIndex]!.frame) {
+ throw new Error("A Selection must span two ordered semantic Anchors with positive time.");
+ }
+ } else if (!current.semantic.anchors.some((anchor) => anchor.id === target.anchorId)) {
+ throw new Error(`Moment Anchor ${target.anchorId} does not exist in the current semantic Candidate.`);
+ }
+ const absolute = resolve(options.workspaceRoot, script.sourcePath);
+ const source = await readFile(absolute, "utf8");
+ if (script.content.start < 0 || script.content.end < script.content.start || script.content.end > source.length) {
+ throw new Error("The current Script source range is invalid.");
+ }
+ const body = source.slice(script.content.start, script.content.end);
+ const parsed = parseScript(script.sourcePath, body);
+ const replacement = target.kind === "selection"
+ ? adjustScriptSelection({
+ sourceName: script.sourcePath,
+ source: body,
+ parsed,
+ adjustment: {
+ id: handle.semantic.id,
+ startAnchorId: target.startAnchorId,
+ endAnchorId: target.endAnchorId,
+ },
+ })
+ : adjustScriptMoment({
+ sourceName: script.sourcePath,
+ source: body,
+ parsed,
+ adjustment: { id: handle.semantic.id, anchorId: target.anchorId },
+ });
+ return replacement === body ? [] : [{
+ path: relative(options.workspaceRoot, absolute),
+ range: script.content,
+ replacement,
+ preimage: body,
+ }];
+ }
+
+ if (handle.sources === undefined) throw new Error("This timeline projection has no direct Window inverse.");
+ const { startFrame, endFrameExclusive } = mutation.target;
+ if (!Number.isInteger(startFrame) || !Number.isInteger(endFrameExclusive)
+ || startFrame < 0 || endFrameExclusive <= startFrame) {
+ throw new Error("A timeline Window must contain positive whole frames.");
+ }
+ if (mutation.gesture === "move"
+ && endFrameExclusive - startFrame !== clip.endFrameExclusive - clip.startFrame) {
+ throw new Error("Move must preserve the Window duration.");
+ }
+ if (mutation.gesture === "trim-start" && endFrameExclusive !== clip.endFrameExclusive) {
+ throw new Error("Trim start cannot change the Window end.");
+ }
+ if (mutation.gesture === "trim-end" && startFrame !== clip.startFrame) {
+ throw new Error("Trim end cannot change the Window start.");
+ }
+ const source = (role: "start" | "end" | "duration") =>
+ handle.sources?.find((candidate) => candidate.role === role)?.source;
+ const frame = (value: number): string => `${value}f`;
+ const patches = mutation.gesture === "move"
+ ? [
+ source("start") === undefined ? undefined : { ...source("start")!, replacement: frame(startFrame) },
+ source("end") === undefined ? undefined : { ...source("end")!, replacement: frame(endFrameExclusive) },
+ ]
+ : mutation.gesture === "trim-start"
+ ? [source("start") === undefined ? undefined : { ...source("start")!, replacement: frame(startFrame) }]
+ : source("duration") !== undefined
+ ? [{ ...source("duration")!, replacement: frame(endFrameExclusive - startFrame) }]
+ : [source("end") === undefined ? undefined : { ...source("end")!, replacement: frame(endFrameExclusive) }];
+ const resolved = patches.filter((patch): patch is Patch => patch !== undefined);
+ if (resolved.length === 0) throw new Error(`No Source endpoint implements ${mutation.gesture}.`);
+ return resolved.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.parameters.find((candidate) => candidate.id === mutation.parameterId);
+ if (parameter === undefined || !parameter.writable) {
+ throw new Error(`Entity ${mutation.entityId} has no writable parameter ${mutation.parameterId}.`);
+ }
+ if (parameter.control === "boolean" && mutation.value !== "true" && mutation.value !== "false") {
+ throw new Error(`${parameter.label} expects true or false.`);
+ }
+ if (parameter.control === "number" && !Number.isFinite(Number(mutation.value))) {
+ throw new Error(`${parameter.label} expects a number.`);
+ }
+ if (parameter.options !== undefined && !parameter.options.includes(mutation.value)) {
+ throw new Error(`${parameter.label} does not accept ${mutation.value}.`);
+ }
+ return mutation.value === parameter.source.preimage ? [] : [{
+ ...parameter.source,
+ replacement: mutation.value,
+ }];
+ };
+
+ const commitMutation = async (mutation: StudioMutation): Promise<number> => {
+ if (mutating) throw new Error("A Studio author mutation is already in progress.");
+ if (snapshot === undefined || mutation.revision !== snapshot.revision) {
+ throw new Error("The Source changed outside Studio.");
+ }
+ if (timer !== undefined) {
+ clearTimeout(timer);
+ timer = undefined;
+ }
+ mutating = true;
try {
- for (const [absolute, text] of nextFiles) {
- const temporary = join(dirname(absolute), `.${basename(absolute)}.hypit-studio.tmp`);
- await writeFile(temporary, text, "utf8");
- temporaries.push({ path: absolute, temporary });
+ const patches = await mutationPatches(mutation);
+ if (patches.length === 0) return snapshot.revision;
+ const previous = await applyTransaction(patches, mutation.revision);
+ const attempt = ++requestedRevision;
+ await publish(attempt, false);
+ if (failure?.revision !== attempt) {
+ server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
+ return attempt;
}
- for (const item of temporaries) await rename(item.temporary, item.path);
+ const rejected = failure.error;
+ await replaceFiles(previous);
+ await publish(++requestedRevision, false);
+ server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
+ throw new StudioMutationRejected(rejected);
} finally {
- for (const item of temporaries) {
- try { await unlink(item.temporary); } catch { /* already renamed */ }
- }
+ mutating = false;
}
};
@@ -199,6 +363,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
if (request.method === "PUT" && url.pathname === "/__studio/source") {
void (async () => {
try {
+ if (mutating) throw new Error("A Studio author mutation is already in progress.");
const chunks: Buffer[] = [];
for await (const chunk of request) chunks.push(Buffer.from(chunk));
const body = JSON.parse(Buffer.concat(chunks).toString("utf8")) as {
@@ -229,33 +394,33 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
})();
return;
}
- if (request.method === "POST" && url.pathname === "/__studio/transaction") {
+ if (request.method === "POST" && url.pathname === "/__studio/mutation") {
void (async () => {
try {
const chunks: Buffer[] = [];
for await (const chunk of request) chunks.push(Buffer.from(chunk));
- const body = JSON.parse(Buffer.concat(chunks).toString("utf8")) as {
- readonly revision?: unknown;
- readonly patches?: unknown;
- };
- if (typeof body.revision !== "number" || !Array.isArray(body.patches)) {
- json(response, 400, { error: "Expected a revision and source patches." });
+ 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") {
+ json(response, 400, { error: "Expected a Studio author mutation." });
return;
}
- const patches = body.patches as Patch[];
- if (patches.some((patch) => typeof patch.path !== "string"
- || typeof patch.replacement !== "string"
- || typeof patch.preimage !== "string"
- || typeof patch.range !== "object" || patch.range === null)) {
- json(response, 400, { error: "Invalid source patch." });
+ if (body.type === "timeline.adjust"
+ && (typeof body.gesture !== "string" || typeof body.target !== "object" || body.target === null)) {
+ json(response, 400, { error: "Expected a timeline gesture and target." });
return;
}
- await applyTransaction(patches, body.revision);
- schedule();
- json(response, 202, { revision: body.revision });
+ if (body.type === "parameter.adjust"
+ && (typeof body.parameterId !== "string" || typeof body.value !== "string")) {
+ json(response, 400, { error: "Expected a parameter identity and value." });
+ return;
+ }
+ const committed = await commitMutation(body as StudioMutation);
+ json(response, 200, { revision: committed });
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
- json(response, conflict(error) ? 409 : 500, { error: message });
+ json(response, conflict(error) ? 409 : error instanceof StudioMutationRejected ? 422 : 500, { error: message });
}
})();
return;
diff --git a/packages/studio/src/shared.ts b/packages/studio/src/shared.ts
index 470a5c64..c2237b3a 100644
--- a/packages/studio/src/shared.ts
+++ b/packages/studio/src/shared.ts
@@ -19,6 +19,7 @@ import type {
StudioTemporalPhase,
StudioTemporalProjection,
StudioTemporalSource,
+ StudioTimelineGesture,
StudioTimelinePresentation,
StudioTrackFamily,
} from "@hypit/studio-adapter";
@@ -123,9 +124,13 @@ export type Track = {
export type ScriptMap = {
readonly recordId: string;
+ readonly sourcePath: string;
readonly range: Range;
+ readonly content: Range;
readonly selections: readonly {
readonly id: string;
+ readonly startAnchorId: string;
+ readonly endAnchorId: string;
/** How many Selections enclose this one. Nesting is what depth means. */
readonly depth: number;
readonly open: Range;
@@ -139,6 +144,7 @@ export type ScriptMap = {
}[];
readonly moments: readonly {
readonly id: string;
+ readonly anchorId: string;
readonly range: Range;
}[];
/** Spoken words placed on the timeline by the selected semantic Candidate. */
@@ -210,6 +216,37 @@ export type StudioSnapshot = {
};
};
+/** The complete author mutation vocabulary exposed by Studio. */
+export type StudioMutation =
+ | {
+ readonly type: "timeline.adjust";
+ readonly revision: number;
+ readonly entityId: string;
+ readonly gesture: StudioTimelineGesture;
+ readonly target:
+ | {
+ readonly kind: "selection";
+ readonly startAnchorId: string;
+ readonly endAnchorId: string;
+ }
+ | {
+ readonly kind: "moment";
+ readonly anchorId: string;
+ }
+ | {
+ readonly kind: "window";
+ readonly startFrame: number;
+ readonly endFrameExclusive: number;
+ };
+ }
+ | {
+ readonly type: "parameter.adjust";
+ readonly revision: number;
+ readonly entityId: string;
+ readonly parameterId: string;
+ readonly value: string;
+ };
+
export type StudioFailure = {
readonly revision: number;
readonly error: string;
diff --git a/packages/studio/src/snapshot.ts b/packages/studio/src/snapshot.ts
index b14421bd..8ff0a2d2 100644
--- a/packages/studio/src/snapshot.ts
+++ b/packages/studio/src/snapshot.ts
@@ -22,7 +22,7 @@ import {
} from "./studio-registry.js";
import type { StudioAdapterRegistry } from "./studio-registry.js";
import type { StudioEntityDraft } from "./studio-registry.js";
-import { parametersForDraft, timingEditHandles } from "./parameters.js";
+import { parametersForDraft, timelineAdjustHandles } from "./parameters.js";
import type { StudioSourceFile } from "./parameters.js";
type Present = {
@@ -106,7 +106,9 @@ function scriptMap(
const moments = (found.moments ?? []) as ScriptMap["moments"];
return {
recordId: String(found.record ?? ""),
+ sourcePath: String(found.sourcePath ?? ""),
range: (found.range ?? { start: 0, end: 0 }) as Range,
+ content: (found.content ?? { start: 0, end: 0 }) as Range,
// A Segment is the outermost range a Script declares; a Selection written
// inside one is a level down, and one inside that another.
segments: segments.map((segment) => ({ ...segment, depth: 0 })),
@@ -226,11 +228,17 @@ function semanticTimeline(
const startFrame = frame(selection.startAnchorId);
const endFrameExclusive = frame(selection.endAnchorId);
if (startFrame === undefined || endFrameExclusive === undefined || endFrameExclusive <= startFrame) return [];
- return [{ id: selection.id, startFrame, endFrameExclusive }];
+ return [{
+ id: selection.id,
+ startAnchorId: selection.startAnchorId,
+ endAnchorId: selection.endAnchorId,
+ startFrame,
+ endFrameExclusive,
+ }];
});
const moments = (narrative.moments ?? []).flatMap((moment) => {
const at = frame(moment.anchorId);
- return at === undefined ? [] : [{ id: moment.id, frame: at }];
+ return at === undefined ? [] : [{ id: moment.id, anchorId: moment.anchorId, frame: at }];
});
if (segments.length === 0) throw new Error("Studio SemanticTrack resolves no authored Segment anchors.");
const provenance: CandidateProvenance = {
@@ -246,7 +254,9 @@ function semanticTimeline(
// the authored Speech Track id into this label: it is the timebase, not a
// second Speech output.
presentation: registry.semanticTimelinePresentation(),
- anchors: anchors.sort((left, right) => left.frame - right.frame || left.id.localeCompare(right.id)),
+ // Narrative order is the semantic ruler. Frame ties are common and must
+ // not erase the discrete 2M+2N anchor ordering used by writeback.
+ anchors,
segments: segments.sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id)),
tokens: tokens.sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id)),
selections: selections.sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id)),
@@ -348,7 +358,12 @@ export function snapshot(registry: StudioAdapterRegistry, built: Preview, input:
declarations: registry.parameterDeclarations(item, placement, draft.lane),
placements: built.source.observations.placements,
});
- const editHandles = timingEditHandles(parameters, registry.editOperations(item, placement, draft.lane));
+ const editHandles = timelineAdjustHandles(
+ parameters,
+ registry.timelineGestures(item, placement, draft.lane),
+ draft.temporal,
+ semantic,
+ );
return parameters.length === 0 && editHandles.length === 0
? draft
: { ...draft, parameters, ...(editHandles.length === 0 ? {} : { editHandles }) };
diff --git a/packages/studio/src/studio-registry.ts b/packages/studio/src/studio-registry.ts
index 298bf979..9d70d993 100644
--- a/packages/studio/src/studio-registry.ts
+++ b/packages/studio/src/studio-registry.ts
@@ -2,11 +2,11 @@ import type {
StudioAdapter,
StudioAdapterContext,
StudioEntityDraft,
- StudioEditOperation,
StudioLaneAttachment,
StudioProjectionRole,
StudioResolvedTrack,
StudioSpan,
+ StudioTimelineGesture,
} from "@hypit/studio-adapter";
import { readonlyInteraction } from "@hypit/studio-adapter";
@@ -201,16 +201,16 @@ export class StudioAdapterRegistry {
return adapter.parameters ?? [];
}
- editOperations(
+ timelineGestures(
track: StudioResolvedTrack,
placement: Placement | undefined,
lane?: string,
- ): readonly StudioEditOperation[] {
+ ): readonly StudioTimelineGesture[] {
const adapter = this.#trackAdapter(track);
if (lane !== undefined) {
- return adapter.attachments?.find((attachment) => attachment.id === lane)?.editOperations ?? [];
+ return adapter.attachments?.find((attachment) => attachment.id === lane)?.timelineGestures ?? [];
}
- return adapter.editOperations ?? [];
+ return adapter.timelineGestures ?? [];
}
}
diff --git a/packages/studio/src/ui/main.ts b/packages/studio/src/ui/main.ts
index 0d07dfdb..24714f26 100644
--- a/packages/studio/src/ui/main.ts
+++ b/packages/studio/src/ui/main.ts
@@ -6,7 +6,7 @@ import type { Highlight } from "./code.js";
import { intentAtOffset, spanAtOffset } from "./markers.js";
import { clipAtOffset, createStore } from "./selection.js";
import { createStage } from "./stage.js";
-import { writeSourceTransaction } from "./writeback.js";
+import { applyStudioMutation } from "./writeback.js";
import { createTimeline } from "./timeline.js";
import "../style.css";
@@ -136,7 +136,7 @@ function group(label: string, items: readonly HTMLElement[], className = ""): HT
return node;
}
-function parameterControl(parameter: Clip["parameters"][number]): HTMLElement {
+function parameterControl(entityId: string, parameter: Clip["parameters"][number]): HTMLElement {
const row = document.createElement("label");
row.className = `parameter-row${parameter.writable ? " parameter-editable" : " parameter-readonly"}`;
const name = document.createElement("span");
@@ -157,7 +157,7 @@ function parameterControl(parameter: Clip["parameters"][number]): HTMLElement {
value.dataset.parameterId = parameter.id;
value.title = parameter.source.preimage;
value.addEventListener("change", () => {
- void writeParameter(parameter, value.type === "checkbox" ? String(value.checked) : value.value);
+ void writeParameter(entityId, parameter, value.type === "checkbox" ? String(value.checked) : value.value);
});
} else if (value instanceof HTMLSelectElement) {
for (const option of parameter.options ?? []) {
@@ -167,7 +167,7 @@ function parameterControl(parameter: Clip["parameters"][number]): HTMLElement {
item.selected = option === parameter.value;
value.append(item);
}
- value.addEventListener("change", () => void writeParameter(parameter, value.value));
+ value.addEventListener("change", () => void writeParameter(entityId, parameter, value.value));
} else {
value.textContent = parameter.value;
value.title = parameter.disabledReason ?? parameter.source.preimage;
@@ -186,7 +186,7 @@ function parameterControl(parameter: Clip["parameters"][number]): HTMLElement {
return row;
}
-function parameterGroups(parameters: readonly Clip["parameters"][number][]): readonly HTMLElement[] {
+function parameterGroups(entityId: string, parameters: readonly Clip["parameters"][number][]): readonly HTMLElement[] {
type StudioParameterValue = Clip["parameters"][number];
const groups = new Map<string, StudioParameterValue[]>();
for (const parameter of parameters) {
@@ -198,23 +198,19 @@ function parameterGroups(parameters: readonly Clip["parameters"][number][]): rea
return [...groups].map(([key, values]) => {
const [language, path = ""] = key.split("\u0000");
const title = path.length === 0 ? language!.toUpperCase() : `${language!.toUpperCase()} · ${path}`;
- return group(title, values.map(parameterControl), "parameter-group");
+ return group(title, values.map((parameter) => parameterControl(entityId, parameter)), "parameter-group");
});
}
-const operationLabels: Readonly<Record<Clip["editHandles"][number]["operation"], string>> = {
+const operationLabels: Readonly<Record<Clip["editHandles"][number]["gesture"], string>> = {
move: "Move",
"trim-start": "Trim start",
"trim-end": "Trim end",
- slip: "Slip",
- split: "Split",
- delete: "Delete",
- duplicate: "Duplicate",
- "canvas-transform": "Canvas transform",
};
const operationCoordinateLabels: Readonly<Record<NonNullable<Clip["editHandles"][number]["coordinate"]>, string>> = {
"program-frame": "program frames",
+ "semantic-anchor": "semantic anchors",
"source-frame": "source frames",
"canvas-pixel": "canvas pixels",
"normalized-progress": "normalized progress",
@@ -229,7 +225,7 @@ function operationGroups(handles: readonly Clip["editHandles"][number][]): reado
copy.className = "operation-copy";
const label = document.createElement("strong");
label.className = "operation-label";
- label.textContent = operationLabels[handle.operation];
+ label.textContent = operationLabels[handle.gesture];
const detail = document.createElement("small");
detail.className = "operation-detail";
const coordinate = handle.coordinate === undefined ? "" : operationCoordinateLabels[handle.coordinate];
@@ -252,19 +248,20 @@ function operationGroups(handles: readonly Clip["editHandles"][number][]): reado
}
let parameterWriteState: "" | "Saving" | "Saved" | "Failed" = "";
-async function writeParameter(parameter: Clip["parameters"][number], replacement: string): Promise<void> {
+async function writeParameter(entityId: string, parameter: Clip["parameters"][number], replacement: string): Promise<void> {
const state = store.current();
if (state === undefined || !parameter.writable) return;
parameterWriteState = "Saving";
status.textContent = parameterWriteState;
status.className = "status saving";
try {
- await writeSourceTransaction(state.snapshot.revision, [{
- path: parameter.source.path,
- range: parameter.source.range,
- replacement,
- preimage: parameter.source.preimage,
- }]);
+ await applyStudioMutation({
+ type: "parameter.adjust",
+ revision: state.snapshot.revision,
+ entityId,
+ parameterId: parameter.id,
+ value: replacement,
+ });
parameterWriteState = "Saved";
status.textContent = parameterWriteState;
status.className = "status saved";
@@ -336,7 +333,7 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
property("Writeback", "Run source · read-only"),
]);
const operations = operationGroups(clip.editHandles);
- const parameters = parameterGroups(clip.parameters);
+ const parameters = parameterGroups(clip.id, clip.parameters);
inspector.replaceChildren(hero, placement, timing, ...operations, ...parameters,
...(source === undefined ? [] : [source]), ...(run === undefined ? [] : [run]));
}
diff --git a/packages/studio/src/ui/timeline.ts b/packages/studio/src/ui/timeline.ts
index 1132df4e..d604dfb4 100644
--- a/packages/studio/src/ui/timeline.ts
+++ b/packages/studio/src/ui/timeline.ts
@@ -2,13 +2,13 @@ import type {
SemanticToken,
StudioSnapshot,
} from "../shared.js";
-import type { StudioEditSource } from "@hypit/studio-adapter";
+import type { StudioEditHandle } from "@hypit/studio-adapter";
import { icon, setIcon } from "./icons.js";
import { mountMaterialPreview } from "./material-preview.js";
import type { State, Store } from "./selection.js";
import { createHandle } from "./resize.js";
import { createZoom } from "./zoom.js";
-import { writeSourceTransaction } from "./writeback.js";
+import { applyStudioMutation } from "./writeback.js";
export type Timeline = {
readonly element: HTMLElement;
@@ -192,15 +192,16 @@ export function createTimeline(store: Store): Timeline {
return distance <= threshold ? nearest : frame;
};
- const frameAt = (clientX: number): number => {
+ const rawFrameAt = (clientX: number): number => {
const box = lanes.getBoundingClientRect();
if (box.width === 0 || state === undefined) return 0;
const across = Math.max(0, Math.min(1, (clientX - box.left) / box.width));
const shown = zoom.window();
- return snapFrame(Math.floor(
+ return Math.floor(
(shown.start + across * (shown.end - shown.start)) * state.snapshot.space.frameCount,
- ));
+ );
};
+ const frameAt = (clientX: number): number => snapFrame(rawFrameAt(clientX));
const frameTimecode = (snapshot: StudioSnapshot, frame: number): string => {
const rate = Math.max(1, Math.round(fps(snapshot)));
@@ -213,12 +214,146 @@ export function createTimeline(store: Store): Timeline {
let pointerDownOnItem = false;
let activeEdit: {
readonly clip: StudioSnapshot["tracks"][number]["clips"][number];
- readonly operation: "move" | "trim-start" | "trim-end";
- readonly sources: readonly StudioEditSource[];
+ readonly handle: StudioEditHandle;
readonly startFrame: number;
+ readonly pointerAnchorIndex?: number;
readonly pointerId: number;
readonly node: HTMLElement;
+ readonly originalLeft: string;
+ readonly originalWidth: string;
} | undefined;
+
+ const nearestAnchorIndex = (
+ frame: number,
+ indices: readonly number[],
+ preferredIndex?: number,
+ ): number | undefined => {
+ if (state === undefined) return undefined;
+ const anchors = state.snapshot.semantic.anchors;
+ const preferredKind = preferredIndex === undefined ? undefined : anchors[preferredIndex]?.kind;
+ return [...indices].sort((left, right) => {
+ const leftAnchor = anchors[left]!;
+ const rightAnchor = anchors[right]!;
+ return Math.abs(leftAnchor.frame - frame) - Math.abs(rightAnchor.frame - frame)
+ || Number(leftAnchor.kind !== preferredKind) - Number(rightAnchor.kind !== preferredKind)
+ || Math.abs(left - (preferredIndex ?? left)) - Math.abs(right - (preferredIndex ?? right))
+ || left - right;
+ })[0];
+ };
+
+ const semanticTarget = (
+ edit: NonNullable<typeof activeEdit>,
+ nextFrame: number,
+ ): { readonly kind: "selection"; readonly startAnchorId: string; readonly endAnchorId: string }
+ | { readonly kind: "moment"; readonly anchorId: string }
+ | undefined => {
+ if (state === undefined || edit.handle.semantic === undefined) return undefined;
+ const semantic = edit.handle.semantic;
+ const anchors = state.snapshot.semantic.anchors;
+ if (semantic.kind === "moment") {
+ if (edit.handle.gesture !== "move") return undefined;
+ const currentIndex = anchors.findIndex((anchor) => anchor.id === semantic.anchorId);
+ const anchorIndex = nearestAnchorIndex(
+ nextFrame,
+ anchors.map((_, index) => index),
+ currentIndex < 0 ? undefined : currentIndex,
+ );
+ return anchorIndex === undefined ? undefined : { kind: "moment", anchorId: anchors[anchorIndex]!.id };
+ }
+ const startIndex = anchors.findIndex((anchor) => anchor.id === semantic.startAnchorId);
+ const endIndex = anchors.findIndex((anchor) => anchor.id === semantic.endAnchorId);
+ if (startIndex < 0 || endIndex < 0 || startIndex >= endIndex) return undefined;
+ let nextStart = startIndex;
+ let nextEnd = endIndex;
+ if (edit.handle.gesture === "trim-start") {
+ const allowed = anchors.flatMap((anchor, index) =>
+ index < endIndex && anchor.frame < anchors[endIndex]!.frame ? [index] : []);
+ nextStart = nearestAnchorIndex(nextFrame, allowed, startIndex) ?? startIndex;
+ } else if (edit.handle.gesture === "trim-end") {
+ const allowed = anchors.flatMap((anchor, index) =>
+ index > startIndex && anchor.frame > anchors[startIndex]!.frame ? [index] : []);
+ nextEnd = nearestAnchorIndex(nextFrame, allowed, endIndex) ?? endIndex;
+ } else if (edit.handle.gesture === "move") {
+ const pointerIndex = edit.pointerAnchorIndex ?? startIndex;
+ const deltas = anchors.flatMap((_, index) => {
+ const delta = index - pointerIndex;
+ const movedStart = startIndex + delta;
+ const movedEnd = endIndex + delta;
+ return movedStart >= 0 && movedEnd < anchors.length
+ && anchors[movedStart]!.frame < anchors[movedEnd]!.frame
+ ? [delta]
+ : [];
+ });
+ const targetPointer = nearestAnchorIndex(
+ nextFrame,
+ deltas.map((delta) => pointerIndex + delta),
+ pointerIndex,
+ );
+ const delta = targetPointer === undefined ? 0 : targetPointer - pointerIndex;
+ nextStart += delta;
+ nextEnd += delta;
+ } else {
+ return undefined;
+ }
+ return {
+ kind: "selection",
+ startAnchorId: anchors[nextStart]!.id,
+ endAnchorId: anchors[nextEnd]!.id,
+ };
+ };
+
+ const absoluteWindowTarget = (
+ edit: NonNullable<typeof activeEdit>,
+ nextFrame: number,
+ ): { readonly startFrame: number; readonly endFrameExclusive: number } => {
+ if (state === undefined) return {
+ startFrame: edit.clip.startFrame,
+ endFrameExclusive: edit.clip.endFrameExclusive,
+ };
+ const rawDelta = nextFrame - edit.startFrame;
+ const delta = Math.max(-edit.clip.startFrame,
+ Math.min(state.snapshot.space.frameCount - edit.clip.endFrameExclusive, rawDelta));
+ if (edit.handle.gesture === "move") return {
+ startFrame: edit.clip.startFrame + delta,
+ endFrameExclusive: edit.clip.endFrameExclusive + delta,
+ };
+ if (edit.handle.gesture === "trim-start") return {
+ startFrame: Math.min(edit.clip.endFrameExclusive - 1, nextFrame),
+ endFrameExclusive: edit.clip.endFrameExclusive,
+ };
+ return {
+ startFrame: edit.clip.startFrame,
+ endFrameExclusive: Math.max(edit.clip.startFrame + 1, nextFrame),
+ };
+ };
+
+ const previewWindow = (
+ edit: NonNullable<typeof activeEdit>,
+ nextFrame: number,
+ ): { readonly startFrame: number; readonly endFrameExclusive: number } | undefined => {
+ if (state === undefined) return undefined;
+ const target = semanticTarget(edit, nextFrame);
+ if (target?.kind === "selection" && edit.handle.semantic?.kind === "selection") {
+ const current = state.snapshot.semantic.selections.find((selection) => selection.id === edit.handle.semantic!.id);
+ const nextStart = state.snapshot.semantic.anchors.find((anchor) => anchor.id === target.startAnchorId)?.frame;
+ const nextEnd = state.snapshot.semantic.anchors.find((anchor) => anchor.id === target.endAnchorId)?.frame;
+ if (current === undefined || nextStart === undefined || nextEnd === undefined) return undefined;
+ return {
+ startFrame: nextStart + edit.clip.startFrame - current.startFrame,
+ endFrameExclusive: nextEnd + edit.clip.endFrameExclusive - current.endFrameExclusive,
+ };
+ }
+ if (target?.kind === "moment" && edit.handle.semantic?.kind === "moment") {
+ const current = state.snapshot.semantic.moments.find((moment) => moment.id === edit.handle.semantic!.id);
+ const next = state.snapshot.semantic.anchors.find((anchor) => anchor.id === target.anchorId)?.frame;
+ if (current === undefined || next === undefined) return undefined;
+ const delta = next - current.frame;
+ return edit.clip.temporal?.projection?.kind === "point"
+ ? { startFrame: edit.clip.startFrame + delta, endFrameExclusive: edit.clip.endFrameExclusive }
+ : { startFrame: edit.clip.startFrame + delta, endFrameExclusive: edit.clip.endFrameExclusive + delta };
+ }
+ return edit.handle.sources === undefined ? undefined : absoluteWindowTarget(edit, nextFrame);
+ };
lanes.addEventListener("pointerdown", (event) => {
pointerDownOnItem = (event.target as HTMLElement).closest(
".clip, .semantic-segment, .semantic-word, .semantic-selection, .semantic-moment",
@@ -243,7 +378,19 @@ export function createTimeline(store: Store): Timeline {
hover.style.transform = `translate3d(${at}px,0,0)`;
hoverTime.textContent = state === undefined ? "" : frameTimecode(state.snapshot, frame);
hover.classList.add("visible");
- if (activeEdit !== undefined) return;
+ if (activeEdit !== undefined && state !== undefined) {
+ const nextFrame = activeEdit.handle.coordinate === "semantic-anchor"
+ ? rawFrameAt(event.clientX)
+ : frameAt(event.clientX);
+ const preview = previewWindow(activeEdit, nextFrame);
+ if (preview !== undefined) {
+ const from = place(preview.startFrame, state.snapshot.space.frameCount, zoom.window());
+ const to = place(preview.endFrameExclusive, state.snapshot.space.frameCount, zoom.window());
+ activeEdit.node.style.left = `${from * 100}%`;
+ activeEdit.node.style.width = `max(2px, calc(${Math.max(0, to - from) * 100}% - ${itemMetrics.gapPx}px))`;
+ }
+ return;
+ }
if (!pointerArmed || event.buttons !== 1) return;
if (pointerDownOnItem && Math.abs(event.clientX - pointerDownX) < 3) return;
store.seek(frame, "timeline");
@@ -252,38 +399,38 @@ export function createTimeline(store: Store): Timeline {
const edit = activeEdit;
activeEdit = undefined;
edit?.node.classList.remove("editing");
+ if (edit !== undefined) {
+ edit.node.style.left = edit.originalLeft;
+ edit.node.style.width = edit.originalWidth;
+ }
pointerArmed = false;
try { lanes.releasePointerCapture(event.pointerId); } catch { /* already released */ }
if (edit === undefined || state === undefined || event.type === "pointercancel") return;
- const nextFrame = frameAt(event.clientX);
- const rawDelta = nextFrame - edit.startFrame;
- const delta = Math.max(
- -edit.clip.startFrame,
- Math.min(state.snapshot.space.frameCount - edit.clip.endFrameExclusive, rawDelta),
- );
- const replacement = (frame: number): string => `${Math.max(0, Math.round(frame))}f`;
- const startSource = edit.sources.find((item) => item.role === "start");
- const endSource = edit.sources.find((item) => item.role === "end");
- const durationSource = edit.sources.find((item) => item.role === "duration");
- const patches = edit.operation === "move"
- ? startSource === undefined || endSource === undefined
- ? []
- : [
- { ...startSource.source, replacement: replacement(edit.clip.startFrame + delta) },
- { ...endSource.source, replacement: replacement(edit.clip.endFrameExclusive + delta) },
- ]
- : edit.operation === "trim-start"
- ? startSource === undefined
- ? []
- : [{ ...startSource.source, replacement: replacement(Math.min(edit.clip.endFrameExclusive - 1, nextFrame)) }]
- : durationSource !== undefined
- ? [{ ...durationSource.source, replacement: replacement(Math.max(1, nextFrame - edit.clip.startFrame)) }]
- : endSource === undefined
- ? []
- : [{ ...endSource.source, replacement: replacement(Math.max(edit.clip.startFrame + 1, nextFrame)) }];
- if (patches.every((patch) => patch.replacement === patch.preimage)) return;
+ const nextFrame = edit.handle.coordinate === "semantic-anchor"
+ ? rawFrameAt(event.clientX)
+ : frameAt(event.clientX);
+ const resolvedSemanticTarget = semanticTarget(edit, nextFrame);
+ const windowTarget = { kind: "window" as const, ...absoluteWindowTarget(edit, nextFrame) };
+ const target = resolvedSemanticTarget ?? (edit.handle.sources === undefined ? undefined : windowTarget);
+ if (target === undefined) return;
+ if (target.kind === "selection"
+ && edit.handle.semantic?.kind === "selection"
+ && target.startAnchorId === edit.handle.semantic.startAnchorId
+ && target.endAnchorId === edit.handle.semantic.endAnchorId) return;
+ if (target.kind === "moment"
+ && edit.handle.semantic?.kind === "moment"
+ && target.anchorId === edit.handle.semantic.anchorId) return;
+ if (target.kind === "window"
+ && target.startFrame === edit.clip.startFrame
+ && target.endFrameExclusive === edit.clip.endFrameExclusive) return;
element.dispatchEvent(new CustomEvent("studio:write", { detail: { state: "saving" } }));
- void writeSourceTransaction(state.snapshot.revision, patches).then(() => {
+ void applyStudioMutation({
+ type: "timeline.adjust",
+ revision: state.snapshot.revision,
+ entityId: edit.clip.id,
+ gesture: edit.handle.gesture,
+ target,
+ }).then(() => {
element.dispatchEvent(new CustomEvent("studio:write", { detail: { state: "saved" } }));
}).catch((error: unknown) => {
// The next snapshot/error event is the source of truth; a failed gesture
@@ -673,19 +820,30 @@ export function createTimeline(store: Store): Timeline {
const nearEnd = rect.right - event.clientX <= edge;
const handle = clip.editHandles.find((candidate) =>
candidate.enabled
- && ((candidate.operation === "trim-start" && nearStart)
- || (candidate.operation === "trim-end" && nearEnd)
- || (candidate.operation === "move" && !nearStart && !nearEnd)));
- if (handle !== undefined && handle.sources !== undefined
- && (handle.operation === "move" || handle.operation === "trim-start" || handle.operation === "trim-end")) {
+ && ((candidate.gesture === "trim-start" && nearStart)
+ || (candidate.gesture === "trim-end" && nearEnd)
+ || (candidate.gesture === "move" && !nearStart && !nearEnd)));
+ if (handle !== undefined
+ && (handle.gesture === "move" || handle.gesture === "trim-start" || handle.gesture === "trim-end")) {
event.stopPropagation();
+ const pointerFrame = handle.coordinate === "semantic-anchor"
+ ? rawFrameAt(event.clientX)
+ : frameAt(event.clientX);
+ const pointerAnchorIndex = handle.semantic !== undefined
+ ? nearestAnchorIndex(
+ pointerFrame,
+ state?.snapshot.semantic.anchors.map((_, index) => index) ?? [],
+ )
+ : undefined;
activeEdit = {
clip,
- operation: handle.operation,
- sources: handle.sources,
- startFrame: frameAt(event.clientX),
+ handle,
+ startFrame: pointerFrame,
+ ...(pointerAnchorIndex === undefined ? {} : { pointerAnchorIndex }),
pointerId: event.pointerId,
node,
+ originalLeft: node.style.left,
+ originalWidth: node.style.width,
};
node.classList.add("editing");
try { lanes.setPointerCapture(event.pointerId); } catch { /* local pointer */ }
diff --git a/packages/studio/src/ui/writeback.ts b/packages/studio/src/ui/writeback.ts
index 0b1897f2..c0a67968 100644
--- a/packages/studio/src/ui/writeback.ts
+++ b/packages/studio/src/ui/writeback.ts
@@ -1,17 +1,10 @@
-import type { Range } from "../shared.js";
+import type { StudioMutation } from "../shared.js";
-export type SourcePatch = {
- readonly path: string;
- readonly range: Range;
- readonly replacement: string;
- readonly preimage: string;
-};
-
-export async function writeSourceTransaction(revision: number, patches: readonly SourcePatch[]): Promise<void> {
- const response = await fetch("/__studio/transaction", {
+export async function applyStudioMutation(mutation: StudioMutation): Promise<void> {
+ const response = await fetch("/__studio/mutation", {
method: "POST",
headers: { "content-type": "application/json" },
- body: JSON.stringify({ revision, patches }),
+ body: JSON.stringify(mutation),
});
if (!response.ok) throw new Error(await response.text());
}
diff --git a/packages/studio/test/parameters.test.ts b/packages/studio/test/parameters.test.ts
new file mode 100644
index 00000000..c11bd141
--- /dev/null
+++ b/packages/studio/test/parameters.test.ts
@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { StudioSemanticTimeline, StudioTemporalLineage } from "@hypit/studio-adapter";
+
+import { parametersForDraft, timelineAdjustHandles } from "../src/parameters.js";
+
+const semantic: StudioSemanticTimeline = {
+ presentation: {
+ family: "speech",
+ icon: "speech",
+ lane: { layout: "flat", height: { minPx: 44, preferredPx: 52, maxPx: 96 } },
+ },
+ anchors: [
+ { id: "segment:a:start", kind: "segment-start", frame: 0, segmentId: "a" },
+ { id: "segment:a:token:1:start", kind: "token-start", frame: 0, segmentId: "a", tokenId: "segment:a:token:1" },
+ { id: "segment:a:token:1:end", kind: "token-end", frame: 12, segmentId: "a", tokenId: "segment:a:token:1" },
+ { id: "segment:a:end", kind: "segment-end", frame: 12, segmentId: "a" },
+ ],
+ segments: [{ id: "a", startFrame: 0, endFrameExclusive: 12 }],
+ tokens: [{ id: "segment:a:token:1", segmentId: "a", text: "hello", startFrame: 0, endFrameExclusive: 12 }],
+ selections: [{
+ id: "claim",
+ startAnchorId: "segment:a:token:1:start",
+ endAnchorId: "segment:a:token:1:end",
+ startFrame: 0,
+ endFrameExclusive: 12,
+ }],
+ moments: [],
+ provenance: { output: "speech", origin: "run", status: "resolved", errors: [] },
+};
+
+test("timeline gestures resolve through the shared Selection identity", () => {
+ const temporal: StudioTemporalLineage = {
+ source: { kind: "selection", id: "claim" },
+ projection: {
+ kind: "window",
+ startExpression: "selection.claim.start",
+ endExpression: "selection.claim.end",
+ startFrame: 0,
+ endFrameExclusive: 12,
+ },
+ phases: [],
+ };
+ const handles = timelineAdjustHandles([], ["move", "trim-start", "trim-end"], temporal, semantic);
+
+ assert.deepEqual(handles.map((handle) => [handle.operation, handle.gesture, handle.coordinate, handle.enabled]), [
+ ["timeline.adjust", "move", "semantic-anchor", true],
+ ["timeline.adjust", "trim-start", "semantic-anchor", true],
+ ["timeline.adjust", "trim-end", "semantic-anchor", true],
+ ]);
+ assert.deepEqual(handles.map((handle) => handle.semantic), Array.from({ length: 3 }, () => ({
+ kind: "selection",
+ id: "claim",
+ startAnchorId: "segment:a:token:1:start",
+ endAnchorId: "segment:a:token:1:end",
+ })));
+});
+
+test("moving a Moment projection resolves to the shared Moment identity", () => {
+ const handles = timelineAdjustHandles([], ["move", "trim-start", "trim-end"], {
+ source: { kind: "moment", id: "beat" },
+ projection: { kind: "point", expression: "moment.beat", frame: 12 },
+ phases: [],
+ }, {
+ ...semantic,
+ moments: [{ id: "beat", anchorId: "segment:a:token:1:end", frame: 12 }],
+ });
+
+ assert.deepEqual(handles.map((handle) => [handle.gesture, handle.enabled]), [
+ ["move", true],
+ ["trim-start", false],
+ ["trim-end", false],
+ ]);
+ assert.deepEqual(handles[0]!.semantic, {
+ kind: "moment",
+ id: "beat",
+ anchorId: "segment:a:token:1:end",
+ });
+});
+
+test("parameter Source paths stay relative to the author workspace", () => {
+ const text = "start=\"1f\"";
+ const parameters = parametersForDraft({
+ root: "/workspace",
+ files: [{ path: "/workspace/main.svml", text, language: "svml" }],
+ placement: {
+ sourcePath: "main.svml",
+ tag: "Item",
+ module: { name: "example", version: "1" },
+ surface: "track",
+ id: "item",
+ range: { start: 0, end: text.length },
+ records: [], values: [], outputs: [], outputPorts: [], children: [],
+ attributes: { start: "1f" },
+ attributeValueRanges: { start: { start: 7, end: 9 } },
+ referenceAttributes: {}, referenceTypes: {}, references: [],
+ },
+ draft: {
+ id: "entity:item", authoredId: "item", label: "item",
+ startFrame: 1, endFrameExclusive: 2, stackOrder: 0,
+ elementRange: { start: 0, end: text.length },
+ },
+ declarations: [{ name: "start", writable: true }],
+ });
+
+ assert.equal(parameters[0]!.source.path, "main.svml");
+ assert.equal(parameters[0]!.source.preimage, "1f");
+});