@hypit/hypit 0.1.4 → 0.1.5

package/packages/studio/src/snapshot.ts

@@ -1,16 +1,15 @@
+import { composeParameterDeclarations } from "./parameters.js";
 /**
  * Turn a built programme into what the panels read.
  *
- * A timeline is the Presents of every Track, and a Present carries a span, an
- * identity and a stacking order - the whole contract, for every package. So the
- * timeline is assembled without knowing what made any of it, and a package that
- * grows a new Track shows up without this file changing.
+ * The Timeline owns the work range. Companions project selectable entities onto
+ * that range without extending it or requiring component-specific editor code.
  */
 import { relative } from "node:path";
 
 import type { MarkupSurfaceRegistryLike } from "@hypit/markup";
 import { compositionTypes } from "@hypit/composition";
-import { narrativeTypes } from "@hypit/narrative";
+import { programSpaceFrameCount } from "@hypit/program-space";
 import { sameModule, sameType } from "@hypit/protocol";
 
 import type {
@@ -138,43 +137,10 @@ function scriptMap(
   };
 }
 
-type NarrativeValue = {
-  readonly id?: string;
-  readonly segments?: readonly {
-    readonly id: string;
-    readonly startAnchorId: string;
-    readonly endAnchorId: string;
-  }[];
-  readonly tokens?: readonly {
-    readonly id: string;
-    readonly segmentId: string;
-    readonly startAnchorId: string;
-    readonly endAnchorId: string;
-    readonly text: string;
-  }[];
-  readonly selections?: readonly {
-    readonly id: string;
-    readonly startAnchorId: string;
-    readonly endAnchorId: string;
-  }[];
-  readonly moments?: readonly {
-    readonly id: string;
-    readonly anchorId: string;
-  }[];
-  readonly semanticIndex?: {
-    readonly anchors?: readonly {
-      readonly id: string;
-      readonly kind: "program-start" | "segment-start" | "segment-end" | "token-start" | "token-end" | "program-end";
-      readonly segmentId?: string;
-      readonly tokenId?: string;
-    }[];
-  };
-};
-
 /**
  * Project the compiled Narrative into the frame domain that the preview is
  * already using. No frontend timing is invented here: if an anchor is absent
- * from the built SemanticTrack, the corresponding item is simply not drawable yet.
+ * from the built Timeline, the corresponding item is simply not drawable yet.
  */
 function semanticTimeline(
   registry: StudioCompanionRegistry,
@@ -182,77 +148,13 @@ function semanticTimeline(
   script: ScriptMap | undefined,
 ): SemanticTimeline | undefined {
   if (built.narrativeId === undefined) return undefined;
-  const records = built.source.compiled.program.records.filter((item) =>
-    sameType(item.type, narrativeTypes.narrative)
-    && item.value.kind === "inline"
-    && (item.value.value as NarrativeValue).id === built.narrativeId);
-  if (records.length > 1) {
-    throw new Error(`Studio Narrative id ${built.narrativeId} resolves to more than one authored value.`);
-  }
-  const record = records[0];
-  const narrative = record?.value.kind === "inline"
-    ? record.value.value as NarrativeValue
-    : undefined;
-  if (narrative === undefined) throw new Error("Studio Narrative is not an inline authored value.");
-
-  const segmentRanges = new Map((script?.segments ?? []).map((item) => [item.id, item.range]));
-  const tokenRanges = new Map((script?.tokens ?? []).map((item) => [item.id, item.range]));
-  const frame = (id: string): number | undefined => built.anchors.get(id);
-
-  const segments = (narrative.segments ?? []).flatMap((segment) => {
-    const startFrame = frame(segment.startAnchorId);
-    const endFrame = frame(segment.endAnchorId);
-    if (startFrame === undefined || endFrame === undefined) return [];
-    return [{
-      id: segment.id,
-      startFrame,
-      endFrameExclusive: Math.max(startFrame + 1, endFrame),
-      ...(segmentRanges.has(segment.id) ? { range: segmentRanges.get(segment.id)! } : {}),
-    }];
+  if (script === undefined) throw new Error("Timeline's Script has no Studio source mapping.");
+  const projected = registry.projectScript({ source: script, anchors: built.anchors,
+    values: built.source.compiled.program.records.flatMap(record => record.value.kind === "inline"
+      ? [{ id: record.id, type: record.type, value: record.value.value }] : []),
   });
-  const tokens = (narrative.tokens ?? []).flatMap((token) => {
-    const startFrame = frame(token.startAnchorId);
-    const endFrame = frame(token.endAnchorId);
-    if (startFrame === undefined || endFrame === undefined) return [];
-    return [{
-      id: token.id,
-      segmentId: token.segmentId,
-      text: token.text,
-      startFrame,
-      endFrameExclusive: Math.max(startFrame + 1, endFrame),
-      ...(tokenRanges.has(token.id) ? { range: tokenRanges.get(token.id)! } : {}),
-    }];
-  });
-  const anchors = (narrative.semanticIndex?.anchors ?? []).flatMap((anchor) => {
-    const at = frame(anchor.id);
-    if (at === undefined) return [];
-    return [{
-      id: anchor.id,
-      kind: anchor.kind,
-      frame: at,
-      ...(anchor.segmentId === undefined ? {} : { segmentId: anchor.segmentId }),
-      ...(anchor.tokenId === undefined ? {} : { tokenId: anchor.tokenId }),
-    }];
-  });
-  const selections = (narrative.selections ?? []).flatMap((selection) => {
-    const startFrame = frame(selection.startAnchorId);
-    const endFrameExclusive = frame(selection.endAnchorId);
-    if (startFrame === undefined || endFrameExclusive === undefined || endFrameExclusive <= startFrame) return [];
-    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, anchorId: moment.anchorId, frame: at }];
-  });
-  if (segments.length === 0) throw new Error("Studio SemanticTrack resolves no authored Segment anchors.");
   const provenance: CandidateProvenance = {
-    output: built.timingOutput?.name ?? "SemanticTrack",
+    output: built.timingOutput?.name ?? "Timeline",
     ...(built.timingOutput?.ref === undefined ? {} : { outputRef: built.timingOutput.ref }),
     ...(built.timingCandidateId === undefined ? {} : { candidateId: built.timingCandidateId }),
     origin: built.timingCandidateOrigin,
@@ -262,17 +164,10 @@ function semanticTimeline(
   return {
     spaceId: built.space.id,
     narrativeId: built.narrativeId,
-    // Semantic is a Studio lane with its own registered meaning. Do not copy
-    // the authored Speech Track id into this label: it is the timebase, not a
-    // second Speech output.
+    // The generic ruler presentation is independent of the authored Timeline id.
     presentation: registry.semanticTimelinePresentation(),
-    // Narrative order is the semantic ruler. Frame ties are common and must
-    // not erase the discrete 2M+2N+2 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)),
-    moments: moments.sort((left, right) => left.frame - right.frame || left.id.localeCompare(right.id)),
+    // Preserve the Companion's ordered anchors, including coincident boundaries.
+    ...projected,
     provenance,
   };
 }
@@ -338,13 +233,18 @@ export function snapshot(registry: StudioCompanionRegistry, built: Preview, inpu
       semantic,
       generic,
     }).map((draft) => {
+      const declarations = composeParameterDeclarations({
+        placement, draft, placements: built.source.observations.placements, registry,
+        bindings: registry.bindingDeclarations(item, placement, draft.lane, draft.band),
+        inspector: registry.inspectorDeclarations(item, placement, draft.lane, draft.band),
+      });
       const bindings = sourceBindingsForDraft({
         root: input.workspaceRoot,
         files: input.sourceFiles,
         placement,
         draft,
         declarations: [
-          ...registry.bindingDeclarations(item, placement, draft.lane),
+          ...declarations.bindings,
           ...temporalBindingDeclarations(draft.temporal),
         ],
         placements: built.source.observations.placements,
@@ -352,7 +252,7 @@ export function snapshot(registry: StudioCompanionRegistry, built: Preview, inpu
       const inspector = inspectorFieldsForBindings(
         draft,
         bindings,
-        registry.inspectorDeclarations(item, placement, draft.lane),
+        declarations.inspector,
       );
       const editHandles = resolveTimelineEditHandles(
         bindings,
@@ -404,17 +304,7 @@ export function snapshot(registry: StudioCompanionRegistry, built: Preview, inpu
   // root that produced them in this list.
   const rows = tracks.map((track, row) => ({ ...track, row }));
 
-  const declared = (built.space as { durationSec?: number; frameRate?: { numerator: number; denominator: number } })
-    ?.durationSec;
-  const frameCount = Math.max(
-    1,
-    declared === undefined
-      ? 0
-      : Math.round(declared * input.frameRate.numerator / input.frameRate.denominator),
-    ...rows.flatMap((track) => track.clips.map((clip) => clip.endFrameExclusive)),
-    ...(semantic?.segments ?? []).map((segment) => segment.endFrameExclusive),
-    ...(semantic?.tokens ?? []).map((token) => token.endFrameExclusive),
-  );
+  const frameCount = programSpaceFrameCount(built.space);
   return {
     revision: input.revision,
     source: {
@@ -442,7 +332,6 @@ export function snapshot(registry: StudioCompanionRegistry, built: Preview, inpu
     ...(semantic === undefined ? {} : { semantic }),
     preview: input.preview,
     provenance: {
-      timing: built.timing,
       picture: "resolved",
       note: note(built),
     },

package/packages/studio/src/studio-preflight.ts

@@ -1,7 +1,7 @@
 import type { Candidate } from "@hypit/protocol";
 import { sameType } from "@hypit/protocol";
 import type { StudioFilmCompanion } from "@hypit/studio-adapter";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 
 import type { CompiledSource } from "./compile.js";
 import type { Placement } from "./observe.js";
@@ -137,7 +137,7 @@ export function inspectStudioRun(
   });
   const timeOutput = times[0];
   if (times.length !== 1) issues.push("Film requires one traceable time source.");
-  const semanticOutput = timeOutput !== undefined && sameType(timeOutput.typeRef, semanticTrackTypes.track) ? timeOutput : undefined;
+  const semanticOutput = timeOutput !== undefined && sameType(timeOutput.typeRef, timelineTypes.track) ? timeOutput : undefined;
   let companionValueRefs: readonly string[] = [];
   try {
     companionValueRefs = unique(filmTrackRefs.flatMap((ref) =>
@@ -149,7 +149,7 @@ export function inspectStudioRun(
 
   const projectionRefs = unique([
     ...filmTrackRefs,
-    ...(semanticOutput !== undefined && sameType(semanticOutput.typeRef, semanticTrackTypes.track) ? [semanticOutput.ref] : []),
+    ...(semanticOutput !== undefined && sameType(semanticOutput.typeRef, timelineTypes.track) ? [semanticOutput.ref] : []),
     ...companionValueRefs,
   ]);
   const projections: StudioViewRequirement[] = [];

package/packages/studio/src/studio-registry.ts

@@ -1,5 +1,6 @@
 import type {
   StudioTrackCompanion,
+  StudioParameterCompanion,
   StudioTrackCompanionContext,
   StudioEditHandle,
   StudioEntityDraft,
@@ -8,6 +9,7 @@ import type {
   StudioViewRole,
   StudioResolvedTrack,
   StudioScriptAdjustment,
+  StudioScriptProjectionInput,
   StudioScriptCompanion,
   StudioScriptSourceMap,
   StudioSourceBindingDeclaration,
@@ -18,7 +20,7 @@ import { parameterOption } from "./parameter-values.js";
 import { compositionTypes } from "@hypit/composition";
 import { sameModule, sameType } from "@hypit/protocol";
 import type { ModuleRef, TypeRef } from "@hypit/protocol";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 
 import type { Placement } from "./observe.js";
 import type { Clip, StudioTrackBinding } from "./shared.js";
@@ -29,9 +31,9 @@ const flatLane = {
   heightPx: 52,
 };
 
-const tones = new Set(["blue", "green", "teal", "violet", "magenta", "orange", "orange-muted", "neutral"]);
+const tones = new Set(["blue", "blue-muted", "green", "green-muted", "teal", "violet", "magenta", "magenta-muted", "orange", "orange-muted", "neutral"]);
 const icons = new Set(["brand", "captions", "component", "layers", "ranking", "text", "timeline", "video", "waveform"]);
-const chromes = new Set(["standard", "group", "point"]);
+const chromes = new Set(["standard", "group", "point", "compact"]);
 const layouts = new Set(["repeat-x", "cover", "contain", "storyboard", "waveform"]);
 const inspectorDomains = new Set(["where", "how", "when"]);
 const inspectorControls = new Set<string>(studioParameterControls);
@@ -100,6 +102,17 @@ function validateCompanionVocabulary(companion: StudioTrackCompanion): void {
     throw new Error(`Studio Track Companion ${companion.id} selects unsupported icon ${companion.icon}`);
   }
   validateInspector(`Studio Track Companion ${companion.id}`, companion.bindings, companion.inspector);
+  const bandIds = new Set<string>();
+  for (const band of companion.bands ?? []) {
+    if (!band.id.trim() || bandIds.has(band.id)) throw new Error(`Studio Companion ${companion.id} has a duplicate or empty band id`);
+    bandIds.add(band.id);
+    if (!Number.isFinite(band.heightPx) || band.heightPx <= 0
+      || !["before", "after"].includes(band.placement) || !["label", "content"].includes(band.display)) {
+      throw new Error(`Studio Companion ${companion.id} band ${band.id} has invalid layout`);
+    }
+    if (band.tone !== undefined && !tones.has(band.tone)) throw new Error(`Studio Companion ${companion.id} band ${band.id} has unsupported tone`);
+    validateInspector(`Studio Companion ${companion.id} band ${band.id}`, band.bindings, band.inspector);
+  }
   for (const attachment of companion.attachments ?? []) {
     if (attachment.tone !== undefined && !tones.has(attachment.tone)) {
       throw new Error(`Studio Track Companion ${companion.id} attachment ${attachment.id} selects unsupported tone ${attachment.tone}`);
@@ -112,6 +125,10 @@ function validateCompanionVocabulary(companion: StudioTrackCompanion): void {
 }
 
 function validateDraftVocabulary(companion: StudioTrackCompanion, draft: StudioEntityDraft): void {
+  if (draft.band !== undefined && (draft.lane !== undefined || !companion.bands?.some(band => band.id === draft.band))) {
+    throw new Error(`Studio Companion ${companion.id} entity ${draft.id} must select one declared band within its own Track`);
+  }
+
   if (draft.display === undefined || typeof draft.display.title !== "string" || draft.display.title.trim().length === 0) {
     throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} has no display title`);
   }
@@ -168,6 +185,7 @@ function specificity(companion: StudioTrackCompanion): number {
 
 /** Immutable interpretation assembled for one project session. */
 export class StudioCompanionRegistry {
+  readonly #parameters: readonly StudioParameterCompanion[];
   readonly #tracks: readonly StudioTrackCompanion[];
   readonly #films: readonly StudioFilmCompanion[];
   readonly #scripts: readonly StudioScriptCompanion[];
@@ -177,6 +195,7 @@ export class StudioCompanionRegistry {
     options: {
       readonly films?: readonly StudioFilmCompanion[];
       readonly scripts?: readonly StudioScriptCompanion[];
+      readonly parameters?: readonly StudioParameterCompanion[];
     } = {},
   ) {
     const ids = new Set<string>();
@@ -197,11 +216,23 @@ export class StudioCompanionRegistry {
         ids.add(companion.id);
       }
     }
+    this.#parameters = Object.freeze([...(options.parameters ?? [])]);
+    for (const companion of this.#parameters) {
+      if (ids.has(companion.id)) throw new Error(`Studio Parameter Companion id is repeated: ${companion.id}`);
+      ids.add(companion.id);
+      validateInspector(`Studio Parameter Companion ${companion.id}`, companion.bindings, companion.inspector);
+    }
     this.#tracks = Object.freeze([...tracks]);
     this.#films = Object.freeze(films);
     this.#scripts = Object.freeze(scripts);
   }
 
+  parameterCompanionFor(module: ModuleRef, surface: string): StudioParameterCompanion | undefined {
+    const found = this.#parameters.filter(companion => sameModule(companion.match.module, module) && companion.match.surface === surface);
+    if (found.length > 1) throw new Error(`Studio Parameter companions are ambiguous for ${module.name}#${surface}.`);
+    return found[0];
+  }
+
   filmCompanionFor(
     type: TypeRef,
     placement: Pick<Placement, "surface" | "module"> | undefined,
@@ -234,6 +265,12 @@ export class StudioCompanionRegistry {
       : { ...found, companion: companion.id };
   }
 
+  projectScript(input: StudioScriptProjectionInput) {
+    const companion = this.#scripts.find(item => item.id === input.source.companion);
+    if (companion?.project === undefined) throw new Error(`Script Companion ${input.source.companion} does not provide a timeline projection.`);
+    return companion.project(input);
+  }
+
   adjustScript(input: {
     readonly companion: string;
     readonly sourceName: string;
@@ -286,7 +323,7 @@ export class StudioCompanionRegistry {
     readonly icon: StudioTrackBinding["icon"];
     readonly lane: StudioTrackBinding["lane"];
   } {
-    const companion = this.trackCompanionFor(semanticTrackTypes.track, undefined, []);
+    const companion = this.trackCompanionFor(timelineTypes.track, undefined, []);
     return {
       family: companion?.family ?? "semantic",
       tone: companion?.tone ?? "teal",
@@ -334,7 +371,7 @@ export class StudioCompanionRegistry {
   bindTrack(track: StudioResolvedTrack): StudioTrackBinding {
     const companion = this.#trackCompanion(track);
     // A Companion may provide a deliberate presentation label for a facet
-    // (e.g. Speech Visual / Speech Audio). Authored ids remain the fallback
+    // (e.g. a component’s picture and sound outputs). Authored ids remain the fallback
     // for ordinary user-named tracks.
     const label = companion.label ?? track.trace.authoredId;
     return {
@@ -346,6 +383,7 @@ export class StudioCompanionRegistry {
       icon: companion.icon ?? (sameType(track.typeRef, compositionTypes.audioTrack) ? "waveform" : "layers"),
       companion: companion.id,
       lane: companion.lane ?? flatLane,
+      ...(companion.bands === undefined ? {} : { bands: companion.bands.map(({ bindings: _bindings, inspector: _inspector, ...band }) => band) }),
       ...(track.trace.placement === undefined ? {} : { authoredTag: track.trace.placement }),
       references: track.trace.references.map(({ name, type }) => ({ name, type })),
     };
@@ -360,7 +398,7 @@ export class StudioCompanionRegistry {
       : { kind: "preview", role: "decoration", preview, layout: "repeat-x" };
     const projected: readonly StudioEntityDraft[] = companion.poster?.source !== "surface-preview" || surfaceLayer === undefined
       ? drafts
-      : drafts.map((draft) => draft.lane !== undefined
+      : drafts.map((draft) => draft.lane !== undefined || draft.band !== undefined
       ? draft
       : {
           ...draft,
@@ -377,8 +415,10 @@ export class StudioCompanionRegistry {
     track: StudioResolvedTrack,
     placement: Placement | undefined,
     lane?: string,
+    band?: string,
   ) {
     const companion = this.#trackCompanion(track);
+    if (band !== undefined) return companion.bands?.find(item => item.id === band)?.bindings ?? [];
     if (lane !== undefined) {
       return companion.attachments?.find((attachment) => attachment.id === lane)?.bindings ?? [];
     }
@@ -389,8 +429,10 @@ export class StudioCompanionRegistry {
     track: StudioResolvedTrack,
     placement: Placement | undefined,
     lane?: string,
+    band?: string,
   ) {
     const companion = this.#trackCompanion(track);
+    if (band !== undefined) return companion.bands?.find(item => item.id === band)?.inspector ?? [];
     if (lane !== undefined) {
       return companion.attachments?.find((attachment) => attachment.id === lane)?.inspector ?? [];
     }
@@ -410,6 +452,8 @@ export function sealStudioClip(
     id: draft.id.startsWith(`${outputRef}:`) ? draft.id : `${outputRef}:${draft.id}`,
     ...(draft.presentId === undefined ? {} : { presentId: draft.presentId }),
     authoredId: draft.authoredId,
+    ...(draft.band === undefined ? {} : { band: draft.band }),
+    ...(draft.selectionGroup === undefined ? {} : { selectionGroup: draft.selectionGroup }),
     ...(draft.markerId === undefined ? {} : { markerId: draft.markerId }),
     display: draft.display,
     startFrame: draft.startFrame,