@hypit/hypit 0.1.3 → 0.1.5

package/packages/studio/start.ts

@@ -11,9 +11,12 @@ Open a Run in the browser to inspect its composition, Sources and Results.
   hypit studio --run <build.svrun> [--runtime <hypit.runtime.json>]
     [--port <number>] [--workspace <directory>] [--package-root <directory>]
 
-Paths are relative to the invoking project. Without --runtime, Studio uses
-that project's selected Runtime Profile. The server prints its browser URL;
-press Ctrl+C to stop it.
+Relative command-line paths start at the current directory; --workspace selects
+the project, without rebasing those paths. Otherwise the nearest package.json
+above the current directory defines the project (or the current directory if none).
+Without --runtime, Studio uses that project's .hypit/runtime selection.
+The server prints its project, Run, Runtime selection and browser URL.
+Press Ctrl+C to stop it.
 `);
 }
 
@@ -47,7 +50,7 @@ export async function runStudio(argv: readonly string[], io: Pick<CliIo, "write"
   const runArgument = values.get("run");
   if (runArgument === undefined || runArgument.trim().length === 0) invalidArguments("Missing --run");
   const { createServer } = await import("vite");
-  const { findRuntimeProfile, resolveProjectRoot } = await import("@hypit/cli");
+  const { findRuntimeProfile, resolveProjectRoot } = await import("@hypit/project-context-node");
   const { resolveDistributionPackageImport } = await import("@hypit/package-loader-node");
   const { videoCliDistribution, videoStudioCompanionPackages } = await import("@hypit/video-cli");
   const { openStudioBuildLibrary } = await import("./src/build-library.js");
@@ -55,6 +58,7 @@ export async function runStudio(argv: readonly string[], io: Pick<CliIo, "write"
   const { loadStudioDomain } = await import("./src/domain.js");
   const { loadStudioRun } = await import("./src/run.js");
   const { studioPlugin } = await import("./src/server.js");
+  const { studioFeedbackPlugin } = await import("./src/feedback-server.js");
   const { inspectStudioRun } = await import("./src/studio-preflight.js");
   const runPath = resolve(invokedFrom, runArgument);
   const packageRootArgument = values.get("package-root");
@@ -76,6 +80,15 @@ export async function runStudio(argv: readonly string[], io: Pick<CliIo, "write"
   const runtimePath = runtimeArgument === undefined
     ? selectedRuntime?.profile
     : resolve(invokedFrom, runtimeArgument);
+  console.info([
+    `  Project            ${workspaceRoot}`,
+    `  Run                ${runPath}`,
+    `  Runtime Profile    ${runtimePath ?? "not selected"}`,
+    `  Runtime selection  ${runtimeArgument !== undefined
+      ? "command argument (this session only)" : selectedRuntime?.selectionFile ?? "none"}`,
+    ...(packageRoot === workspaceRoot ? [] : [`  Package root       ${packageRoot}`]),
+    "",
+  ].join("\n"));
   const port = Number(values.get("port") ?? "5179");
   if (!Number.isSafeInteger(port) || port <= 0) invalidArguments("--port must be a positive integer");
 
@@ -124,7 +137,7 @@ export async function runStudio(argv: readonly string[], io: Pick<CliIo, "write"
       // available for Source and material previews.
       fs: { allow: [workspaceRoot, packageRoot, distributionPackageRoot, here] },
     },
-    plugins: [distributionImports, studioPlugin({
+    plugins: [distributionImports, studioFeedbackPlugin(workspaceRoot, runPath), studioPlugin({
       source,
       runPath,
       workspaceRoot,
@@ -140,4 +153,5 @@ export async function runStudio(argv: readonly string[], io: Pick<CliIo, "write"
   });
   await server.listen();
   server.printUrls();
+  for (const url of server.resolvedUrls?.local ?? []) io.write(`  Comments           ${url}#comments\n`);
 }

package/packages/studio-adapter/README.md

@@ -48,6 +48,22 @@ nominal output Type and authored input names of the component. A Companion does
 author attribute. Omitting `project` uses generic terminal entities; `poster` adds the declared
 Surface preview when one exists, without changing the component's rendered video.
 
+Each lane occupies one timeline row. Entities overlap in ascending `stackOrder`,
+with later projected entities above earlier ones when orders tie. Studio keeps
+overlapping entities mounted and raises the selected entity within its lane;
+selection does not change the rendered composition or write stacking back to Source.
+Expose `presentId` or `renderIds` for visual entities so picture selection can
+address the same entity shown in the timeline. Attached lanes represent distinct
+Companion projections, not extra rows allocated to avoid temporal overlap.
+
+An entity's timeline interval describes the operation being edited; its rendered
+parts may remain visible afterward. Associate every relevant phase through
+`renderIds` (for example, an entrance and the settled object). Studio picks the
+currently visible part in rendered stacking order and selects the same entity,
+without extending its editable interval. Give the parent the board or background
+parts and its children their own parts when they should be independently selectable.
+The component decides this granularity. A composite can remain one selectable entity.
+
 Merge the facet into the package's existing activation. In this example `authorContribution`
 exports its existing modules, deterministic component and Markup facets:
 
@@ -90,7 +106,8 @@ ordered layers, `startFrame`, `endFrameExclusive` and `stackOrder`. Useful optio
 
 | Field/helper | Purpose |
 | --- | --- |
-| `presentation` | Name the entity's role and choose `standard`, `group` or `point` chrome |
+| `selectionGroup` | Link disjoint displayed intervals of one author entity; selection highlights them together without changing their independent timing |
+| `presentation` | Name the entity's role and choose `standard`, `group`, `point` or `compact` chrome (a single-line primary label) |
 | `textLayer(text)` | Put explicit domain text in the timeline body |
 | `previewLayer(artifactPreview(kind, resource), layout)` | Show a declared image/video/audio Resource with a finite layout; Studio resolves transport |
 | `renderIds` | Relate an entity to its actual rendered elements |
@@ -98,6 +115,7 @@ ordered layers, `startFrame`, `endFrameExclusive` and `stackOrder`. Useful optio
 | `temporal` | Carry the executed Instant/Window lineage and its edit authority |
 | `lane` and Companion `attachments` | Put child entities on a declared additional lane, with its own bindings and Inspector |
 | `childEntities` / `authoredChildFor` | Resolve children from public identity and exact Spec Types rather than source order guesses |
+| `authoredItemTitle` | Prefer an explicit author id, then a source reference from the attributes chosen by the Companion; presentation leaves editing identity unchanged |
 
 Use the program's frame space and half-open intervals. Persistent visibility and its activation are
 different facts: a board item can remain visible until the board ends while its reveal occupies only
@@ -136,12 +154,11 @@ physical package identity, so executable package code cannot impersonate an
 official Companion. The Source closure selects project packages; Studio does not
 scan `node_modules` for plugins or use Runtime Profiles to select Companions.
 
-The same host facet can contribute Film and Script boundary companions. A Film companion declares
-the accepted `timeSources` (author attribute and Type) and its terminal Tracks. Film accepts either
-a SemanticTrack or a declared ProgramSpace. Track Companion context includes `semantic` when the
-time source supplies a semantic timeline; pure animation leaves it undefined. A Script companion owns
-raw source observation and marker adjustment. Studio core only matches and invokes these declarations;
-it does not import either domain package.
+The same host facet can contribute Film, Script and parameter Companions. A Film Companion
+identifies its Timeline and terminal Tracks. The Timeline supplies the program range; semantic
+rows are populated when it carries Script anchors. A Script Companion owns source observation,
+projection of its values into Studio's segment/word/marker rows, and marker adjustment. Studio
+consumes that projection without reading the Script package's Narrative representation.
 
 For a domain item whose Spec is consumed beside a Window or Instant, call
 `temporalLineageFor(context, item.id, "window")` using the actual projection input name. Attach the
@@ -156,8 +173,8 @@ Inspector editing deliberately has two declarations:
 
 - `bindings` names exact author endpoints, including explicit reference paths
   into authored elements or SVS Recipes. A binding is not visible by itself;
-- `inspector` selects writable bindings and gives them a `where`, `how` or
-  `when` domain, an optional package-owned page, a section and one of Studio's
+- `inspector` selects bindings and gives them a `where`, `when` or
+  `how` domain, an optional package-owned page, a section and one of Studio's
   finite controls (`text`, `number`, `boolean`, `select`, `color`, `list` or
   `record`). A domain Recipe may declare a shared canonical-value schema; the
   companion chooses its presentation while Studio derives and validates the
@@ -165,8 +182,16 @@ Inspector editing deliberately has two declarations:
 
 This keeps source traversal, timeline inverses and editor presentation from
 silently becoming one policy. Studio resolves the declarations against the
-current Source closure, publishes only real writable fields, renders all DOM
-and CSS itself, and commits changes through `parameter.adjust`.
+current Source closure. Visible read-only bindings render as text alongside editable fields.
+A projected entity can also supply `inspector` values with an `id`, `label`, `domain`, `section`
+and `value`, such as its resolved interval. These facts need no Source endpoint.
+Only resolved fields with an `edit` endpoint accept `parameter.adjust`. Studio renders all DOM
+and CSS itself; grouping does not grant edit authority.
+
+Fields can declare `number` display scaling, supported suffixes, limits and step; `unit` alone is
+only a label. Select options can carry separate scalar values, labels, descriptions and color/font
+preview hints. Text may be multiline; colors may offer package-chosen swatches. See
+[Inspector presentation and conversion](../studio/INSPECTOR.md) for examples and ownership.
 
 Structured controls keep a local draft and commit one complete canonical value.
 Their codec is the author language (`@hypit/svs` for Recipe values), not a
@@ -184,3 +209,118 @@ is selected, its field reaches the correct Source or Recipe, and changing it rec
 For semantic handles, verify the exact marker and its other consumers too. Read-only derived timing
 is preferable to an invented inverse. The Companion explains the component; its Producers remain
 responsible for identical video behavior in Studio, seeking and encoded rendering.
+
+Compact chrome uses `display.title` as its complete single-line content: a Cue can put its subtitle
+text there and a Use can put its Style name there. It has no separate thumbnail/body region or
+inline duration. Time remains in the tooltip and Companion-selected Inspector facts. Tone and lane
+height are independent declarations; compact does not recognize Caption or Use names.
+
+Choose lane tones explicitly. The `blue-muted`, `green-muted`, `magenta-muted`
+and `orange-muted` palette entries provide quieter rows within the same color
+family. For example, content and its presentation Uses can share a hue while
+the Uses take the muted tone. Studio does not derive tone from attachment depth
+or the entity name.
+
+### Internal bands and child Tracks
+
+A Track can place independently timed entities in internal `bands`. These strips share its label
+and meet without gaps. Use them for aspects of the same content, such as a bottom strip of
+presentation rules. Keep `attachments` for independently represented child objects with their own
+labels, such as a ranking board's reveals. These declarations affect Studio presentation only.
+
+```ts
+{
+  lane: { heightPx: 60 },
+  bands: [{
+    id: "rules",
+    placement: "after",
+    heightPx: 15,
+    display: "label",
+    bindings: [{ name: "style" }],
+    inspector: [{
+      binding: "style", label: "Style", domain: "how", control: "text",
+      section: { id: "presentation", label: "Presentation" },
+    }],
+  }],
+}
+```
+
+The projection puts `band: "rules"` on the corresponding entity drafts. Other entities remain in
+the main content area. A band can be `before` or `after` that area; declarations retain their order
+within each placement. `display: "label"` fills the strip with entity titles, while `"content"`
+retains the entity's normal chrome and body. An optional `tone` selects another palette entry;
+omission inherits the Track tone. Heights are independent, so a label band can match the 15px
+standard item header.
+
+An entity selects either an internal `band` or a child `lane`. Bands retain their own intervals,
+overlap ordering, selection, Inspector declarations and temporal writeback. A rule spanning three
+content blocks stays one entity; Studio does not split it at content boundaries. Band entities stay
+in the Track's `clips` collection, so ordinary selection and editing use the same identities.
+
+### Parameters owned by referenced objects
+
+A consumer opts a reference into its owner's parameter Companion:
+
+```ts
+bindings: [{ name: "style", companion: true }]
+```
+
+The package that authors the referenced object contributes through
+`createStudioCompanionHostFacet({ parameters: [...] })`:
+
+```ts
+{
+  id: "slide",
+  match: { module: myModule, surface: "slide" },
+  bindings: [{ name: "distance", writable: true, fallback: 0.25 }],
+  inspector: [{
+    binding: "distance", label: "Travel", domain: "where",
+    section: { id: "path", label: "Path" }, control: "number",
+    unit: "%", number: { scale: 100 },
+  }],
+}
+```
+
+Studio resolves the actual reference and matches its Module/Surface. It prefixes this object's
+bindings and fields under the consumer reference; the example becomes `style.distance`.
+Nested `referenced` and `recipe` bindings use the same composition. The Use retains its own
+Window and time gestures. Several Uses referencing one Style edit the same source object.
+A project Style can therefore publish controls without replacing the Performance, Sound or
+Caption Track Companion. No parameter Companion means the reference remains visible with only
+its consumer-declared fields.
+
+A source or Recipe binding may declare a typed `fallback`, or a function of the authored
+properties for a dependent default. For example, Sound's end gain follows its start gain until
+authored explicitly. The field displays the fallback; the first edit inserts the attribute/property
+in its owning SVML/SVS file. Source recompilation remains the owner of current values.
+Only expose omitted defaults whose insertion preserves valid author semantics; geometry inputs
+whose legality depends on a different Frame form can remain tied to the authored form.
+
+Fields without `page` remain visible alongside the selected named page within Where, When or How.
+Read-only and editable fields can share a section. Each package chooses a small useful field set.
+
+### Edit related attributes together
+
+A source binding can expose several scalar attributes as one `record` field:
+
+```ts
+{ name: "layout", writable: true, attributes: ["mode", "columns"],
+  fallback: { mode: "flow" },
+  schema: { kind: "oneOf", variants: [
+    { kind: "object", fields: { mode: { schema: { kind: "literal", value: "flow" } } } },
+    { kind: "object", fields: {
+      mode: { schema: { kind: "literal", value: "grid" } },
+      columns: { schema: { kind: "number", integer: true, minimum: 1 } },
+    } },
+  ] } }
+```
+
+The synthetic binding name is editor vocabulary; it creates no `layout` Source attribute.
+The field's `control: "record"` saves a complete, valid value when editing ends. Object alternatives with a shared, distinct
+literal field provide a mode selector; selecting one prepares that alternative's fields.
+Incomplete values stay in the editor with a completion hint until the required fields are filled.
+Only the declared attributes are replaced together. Omitted members are removed, while unrelated
+attributes, references and child content survive. Existing references within the group remain
+read-only. Domain validation still owns valid author values; existing transactions reject an
+invalid edit without leaving invalid Source behind. Source grouping is available on direct and
+referenced element bindings and stays data-only across the editor boundary.

package/packages/studio-adapter/src/index.ts

@@ -21,18 +21,21 @@ export type StudioIcon =
 /** Studio-owned visual palette. Domain families never become CSS selectors. */
 export type StudioTimelineTone =
   | "blue"
+  | "blue-muted"
   | "green"
+  | "green-muted"
   | "teal"
   | "violet"
   | "magenta"
+  | "magenta-muted"
   | "orange"
   | "orange-muted"
   | "neutral";
 
 export type StudioTimelinePresentation = {
   readonly entity: string;
-  /** Studio-owned shell. It never decides whether title, time or body exists. */
-  readonly chrome: "standard" | "group" | "point";
+  /** Studio-owned shell. Compact presents the primary label in one line, with time in details. */
+  readonly chrome: "standard" | "group" | "point" | "compact";
 };
 
 export type StudioTemporalSource = {
@@ -122,6 +125,30 @@ export const studioParameterControls = [
 export type StudioParameterControl = typeof studioParameterControls[number];
 export type StudioParameterLanguage = "svml" | "svs" | "svrun";
 
+/** Data-only choices. Packages supply meaning; Studio owns all option rendering. */
+export type StudioParameterOption = string | {
+  readonly value: string | number | boolean;
+  readonly label: string;
+  readonly description?: string;
+  readonly preview?: { readonly kind: "color"; readonly color: string }
+    | { readonly kind: "font"; readonly family: string; readonly sample?: string };
+};
+
+/** Displayed number = authored number × scale. Suffixes are retained, never converted. */
+export type StudioNumberPresentation = {
+  readonly scale?: number;
+  readonly suffixes?: readonly string[];
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly step?: number;
+};
+
+/** Attribute ranges are relative to the owning element's source preimage. */
+export type StudioAttributeGroupEdit = {
+  readonly insertionOffset: number;
+  readonly ranges: Readonly<Record<string, Range | null>>;
+};
+
 /** A real author endpoint. Its existence never implies Inspector visibility. */
 export type StudioSourceBinding = {
   readonly id: string;
@@ -144,10 +171,11 @@ export type StudioSourceBinding = {
     readonly prefix?: string;
     readonly suffix?: string;
   };
+  readonly attributes?: StudioAttributeGroupEdit;
   readonly disabledReason?: string;
 };
 
-export type StudioInspectorDomain = "where" | "how" | "when";
+export type StudioInspectorDomain = "where" | "when" | "how";
 
 export type StudioInspectorPageDeclaration = {
   readonly id: string;
@@ -159,7 +187,7 @@ export type StudioInspectorSectionDeclaration = {
   readonly label: string;
 };
 
-/** One visible, writable field selected from a Companion's source bindings. */
+/** One visible field selected from a Companion's source bindings. */
 export type StudioInspectorFieldDeclaration = {
   readonly binding: string;
   readonly label: string;
@@ -170,18 +198,33 @@ export type StudioInspectorFieldDeclaration = {
   readonly summary?: string;
   /** Omit when the binding's public schema selects the finite Studio control. */
   readonly control?: StudioParameterControl;
-  readonly options?: readonly string[];
+  readonly options?: readonly StudioParameterOption[];
   readonly unit?: string;
+  readonly number?: StudioNumberPresentation;
+  readonly multiline?: boolean;
+  /** Optional suggested colors, independent of the accepted color value. */
+  readonly swatches?: readonly string[];
+};
+
+/** A selected entity's package-owned fact, with no author write endpoint. */
+export type StudioInspectorValue = Pick<StudioInspectorFieldDeclaration,
+  "label" | "domain" | "page" | "section" | "summary" | "unit"> & {
+  readonly id: string;
+  readonly value: CanonicalValue;
 };
 
-/** Resolved Inspector DTO. Studio renders it and executes its exact source write. */
-export type StudioInspectorField = Omit<StudioInspectorFieldDeclaration, "control"> & {
+/** Display and edit authority are independent of the Where / When / How grouping. */
+export type StudioInspectorField = Omit<StudioInspectorFieldDeclaration, "binding" | "control"> & {
+  readonly binding?: string;
   readonly id: string;
   readonly control: StudioParameterControl;
   readonly value: CanonicalValue;
   readonly schema?: ValueSchema;
-  readonly language: StudioParameterLanguage;
-  readonly source: StudioSourceBinding["source"];
+  readonly edit?: {
+    readonly language: StudioParameterLanguage;
+    readonly source: StudioSourceBinding["source"];
+    readonly attributes?: StudioAttributeGroupEdit;
+  };
 };
 
 /** Companion-owned source allowlist. It contains no editor presentation. */
@@ -189,6 +232,12 @@ export type StudioSourceBindingDeclaration = {
   readonly name: string;
   readonly writable?: boolean;
   readonly schema?: ValueSchema;
+  /** Typed value used when this editable attribute is omitted. */
+  readonly fallback?: CanonicalValue | ((authored: Readonly<Record<string, CanonicalValue>>) => CanonicalValue | undefined);
+  /** Compose the referenced object's package-owned parameter Companion. */
+  readonly companion?: boolean;
+  /** Edit these scalar attributes together as one schema-described record. */
+  readonly attributes?: readonly string[];
   /** Optional declaration for the authored element named by a reference. */
   readonly referenced?: readonly StudioSourceBindingDeclaration[];
   /**
@@ -212,7 +261,7 @@ export type StudioRecipeBindingDeclaration = {
   /** Domain-owned public Recipe value structure, never editor presentation. */
   readonly schema?: ValueSchema;
   /** Typed public fallback; Studio writes the property only after the author changes it. */
-  readonly fallback?: CanonicalValue;
+  readonly fallback?: CanonicalValue | ((authored: Readonly<Record<string, CanonicalValue>>) => CanonicalValue | undefined);
 };
 
 export type StudioTimelineGesture =
@@ -301,13 +350,14 @@ export type StudioDisplayLayer =
     };
 
 export type StudioEntityDisplay = {
-  /** First row. Studio always places computed time immediately after it. */
+  /** Primary label: a header in standard chrome, the complete single-line content in compact chrome. */
   readonly title: string;
   /** Ordered back-to-front body layers. */
   readonly layers: readonly StudioDisplayLayer[];
 };
 
 export type StudioLaneDescription = {
+  /** Height of this single timeline lane; overlapping entities share it. */
   readonly heightPx: number;
   readonly groupId?: string;
   readonly attachedTo?: string;
@@ -463,7 +513,7 @@ export type StudioResolvedTrack = {
 };
 
 export type StudioViewRole =
-  | "semantic-track"
+  | "timeline"
   | "supporting-value"
   | "track";
 
@@ -482,17 +532,25 @@ export type StudioEntityDraft = {
   readonly display: StudioEntityDisplay;
   readonly startFrame: number;
   readonly endFrameExclusive: number;
+  /** Back-to-front timeline order. Ties preserve projection order. Selection raises only the timeline item. */
   readonly stackOrder: number;
   readonly elementRange?: Range;
   readonly markerId?: string;
   readonly presentId?: string;
+  /** Rendered parts belonging to this entity, including phases beyond its editable timeline interval. */
   readonly renderIds?: readonly string[];
   /** Resolved author references that differ per derived entity, such as one Cue's actual Style. */
   readonly parameterReferences?: Readonly<Record<string, string>>;
+  /** Disjoint displayed intervals belonging to one selectable author entity. */
+  readonly selectionGroup?: string;
+  /** Deliberately selected facts, presented beside bound Inspector fields. */
+  readonly inspector?: readonly StudioInspectorValue[];
   readonly presentation?: StudioTimelinePresentation;
   readonly temporal?: StudioTemporalLineage;
-  /** Studio-local lane partition; omitted means the root lane. */
+  /** Independent child Track partition; omitted means this Track. */
   readonly lane?: string;
+  /** Internal band of this Track; mutually exclusive with lane. */
+  readonly band?: string;
 };
 
 export type StudioTrackCompanionContext = {
@@ -525,6 +583,8 @@ export type StudioTrackCompanion = {
   /** Opts root timeline entities into the component's package-owned Surface preview. */
   readonly poster?: { readonly source: "surface-preview" };
   readonly attachments?: readonly StudioLaneAttachment[];
+  /** Internal bands share this Track’s label and contain independently timed entities. */
+  readonly bands?: readonly StudioTrackBand[];
   /** Same-Surface output values required to project this Track for Studio. */
   readonly requiredValues?: readonly string[];
   readonly lane?: StudioLaneDescription;
@@ -535,11 +595,20 @@ export type StudioTrackCompanion = {
   readonly project?: (context: StudioTrackCompanionContext) => readonly StudioEntityDraft[];
 };
 
+/** Parameters owned by an authored object, independently of its consumers. */
+export type StudioParameterCompanion = {
+  readonly id: string;
+  readonly match: { readonly module: ModuleRef; readonly surface: string };
+  readonly bindings: readonly StudioSourceBindingDeclaration[];
+  readonly inspector: readonly StudioInspectorFieldDeclaration[];
+};
+
 export type StudioCompanionContribution = {
   readonly format: "hypit.studio-companions@1";
   readonly tracks: readonly StudioTrackCompanion[];
   readonly films?: readonly StudioFilmCompanion[];
   readonly scripts?: readonly StudioScriptCompanion[];
+  readonly parameters?: readonly StudioParameterCompanion[];
 };
 
 /** Declarative Film boundary. Studio follows only the references named here. */
@@ -580,6 +649,13 @@ export type StudioScriptAdjustment =
   | { readonly kind: "selection"; readonly id: string; readonly startAnchorId: string; readonly endAnchorId: string }
   | { readonly kind: "moment"; readonly id: string; readonly anchorId: string };
 
+export type StudioScriptProjection = Pick<StudioSemanticTimeline, "anchors" | "segments" | "tokens" | "selections" | "moments">;
+export type StudioScriptProjectionInput = {
+  readonly source: StudioScriptSourceMap;
+  readonly values: readonly StudioObservedValue[];
+  readonly anchors: ReadonlyMap<string, number>;
+};
+
 /** Script grammar companion. It owns source observation and semantic inverse edits. */
 export type StudioScriptCompanion = {
   readonly id: string;
@@ -594,6 +670,7 @@ export type StudioScriptCompanion = {
     readonly nextOffset?: number;
     readonly attributes: Readonly<Record<string, unknown>>;
   }) => Omit<StudioScriptSourceMap, "companion"> | undefined;
+  readonly project?: (input: StudioScriptProjectionInput) => StudioScriptProjection;
   readonly adjust: (input: {
     readonly sourceName: string;
     readonly source: string;
@@ -617,6 +694,7 @@ export function createStudioCompanionHostFacet(input: {
   readonly tracks?: readonly StudioTrackCompanion[];
   readonly films?: readonly StudioFilmCompanion[];
   readonly scripts?: readonly StudioScriptCompanion[];
+  readonly parameters?: readonly StudioParameterCompanion[];
 }): StudioCompanionHostFacet {
   return {
     abi: studioCompanionHostAbi,
@@ -625,6 +703,7 @@ export function createStudioCompanionHostFacet(input: {
       tracks: input.tracks ?? [],
       ...(input.films === undefined ? {} : { films: input.films }),
       ...(input.scripts === undefined ? {} : { scripts: input.scripts }),
+      ...(input.parameters === undefined ? {} : { parameters: input.parameters }),
     },
   };
 }
@@ -633,6 +712,7 @@ export type StudioPackageContribution = {
   readonly tracks: readonly StudioTrackCompanion[];
   readonly films: readonly StudioFilmCompanion[];
   readonly scripts: readonly StudioScriptCompanion[];
+  readonly parameters: readonly StudioParameterCompanion[];
 };
 
 function qualify(owner: string, local: string, subject: string): string {
@@ -650,6 +730,7 @@ export function studioContributionFromPackage(
   const tracks: StudioTrackCompanion[] = [];
   const films: StudioFilmCompanion[] = [];
   const scripts: StudioScriptCompanion[] = [];
+  const parameters: StudioParameterCompanion[] = [];
   for (const facet of facets) {
     if (facet.abi !== studioCompanionHostAbi) continue;
     const contribution = facet.implementation as Partial<StudioCompanionContribution>;
@@ -664,12 +745,15 @@ export function studioContributionFromPackage(
       ...film,
       id: qualify(owner, film.id, "Studio Film companion"),
     })));
+    parameters.push(...(contribution.parameters ?? []).map((parameter) => ({
+      ...parameter, id: qualify(owner, parameter.id, "Studio Parameter companion"),
+    })));
     scripts.push(...(contribution.scripts ?? []).map((script) => ({
       ...script,
       id: qualify(owner, script.id, "Studio Script companion"),
     })));
   }
-  return { tracks, films, scripts };
+  return { tracks, films, scripts, parameters };
 }
 
 /**
@@ -683,6 +767,18 @@ export function studioTrackCompanionsFromPackage(
   return studioContributionFromPackage(owner, facets).tracks;
 }
 
+/** A contiguous internal strip, not a child Track. Declaration order is visual order. */
+export type StudioTrackBand = {
+  readonly id: string;
+  readonly placement: "before" | "after";
+  readonly heightPx: number;
+  /** Label bands use the whole strip for each entity's title; content bands retain its chrome. */
+  readonly display: "label" | "content";
+  readonly tone?: StudioTimelineTone;
+  readonly bindings?: readonly StudioSourceBindingDeclaration[];
+  readonly inspector?: readonly StudioInspectorFieldDeclaration[];
+};
+
 export type StudioLaneAttachment = {
   readonly id: string;
   readonly family: StudioTrackFamily;
@@ -811,6 +907,22 @@ export function temporalSemanticSource(lineage: StudioTemporalLineage | undefine
     : undefined;
 }
 
+/** A package chooses which source references can name an otherwise unnamed Item. */
+export function authoredItemTitle(
+  context: StudioTrackCompanionContext,
+  authoredId: string,
+  sourceTypes: readonly TypeRef[],
+  sourceAttributes: readonly string[],
+): string {
+  const child = authoredChildFor(context, authoredId, sourceTypes);
+  if (child?.attributes.id) return child.attributes.id;
+  for (const attribute of sourceAttributes) {
+    const reference = child?.referenceAttributes[attribute];
+    if (reference) return reference;
+  }
+  return authoredId;
+}
+
 export function childEntities(
   context: StudioTrackCompanionContext,
   items: readonly {

package/packages/temporal/README.md

@@ -12,20 +12,20 @@ or editor metadata. A graph-qualified projection `id` and its author-facing `sub
 on purpose.
 
 Author syntax does not live here. `@hypit/temporal-markup` lowers SVML timing forms into ordinary
-Instant projection and Window composition operations. The graph supplies ProgramSpace separately;
-domain components receive only ProgramSpace plus the resulting Instant or Window and never locate a
+Instant projection and Window composition operations. The graph supplies one Timeline;
+domain components receive that Timeline plus the resulting Instant or Window and never locate a
 Selection, Segment or Moment themselves.
 
 Every official consumer verifies the projection at its public boundary: `subjectId` must name the
-domain object being built, both endpoints must retain one ProgramSpace, and that identity
-must equal the explicitly supplied ProgramSpace. ProgramSpace is therefore an ordinary graph input
+domain object being built, both endpoints must retain one time-range identity, and that identity
+must equal the explicitly supplied Timeline. Timeline is therefore an ordinary graph input
 to the consumer, not ambient renderer state.
 
 Temporal rejects Instants outside ProgramSpace and Windows that are reversed or empty. It does not
 clip or repair author time. The package also provides sibling-window validation and triggered-stage
 scheduling, but no renderer, Provider, media policy or Studio behavior.
 
-Program-bound projection receives ProgramSpace directly. Semantic-bound projection receives the
-SemanticTrack that locates its Script anchors. Both produce the same Instant type; program-bound
+All projection Producers receive Timeline. Program-bound projection uses its complete range;
+semantic-bound projection locates its Script anchors. Both produce the same Instant type; program-bound
 sources have no Narrative identity. A Window can combine a semantic endpoint with a program endpoint
 on the same time axis. `absolute` expressions may include a duration offset, as used by `at`/`for`.

package/packages/temporal/package.json

@@ -15,6 +15,6 @@
     "@hypit/narrative": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*"
+    "@hypit/timeline": "workspace:*"
   }
 }