@hypit/hypit 0.1.4 → 0.1.5

package/packages/studio/src/parameters.ts

@@ -5,7 +5,6 @@ import type {
   StudioInspectorFieldDeclaration,
   StudioSourceBinding,
   StudioSourceBindingDeclaration,
-  StudioParameterControl,
   StudioRecipeReferenceBindingDeclaration,
   StudioEntityDraft,
   StudioEditSource,
@@ -17,6 +16,11 @@ import type {
   StudioTimelineGesture,
 } from "@hypit/studio-adapter";
 import { parseSvs } from "@hypit/svs";
+import { parseOpeningTag } from "@hypit/markup";
+import { parameterControlForSchema, parameterRecordSchema } from "./parameter-values.js";
+import type { CanonicalValue } from "@hypit/protocol";
+
+import type { StudioCompanionRegistry } from "./studio-registry.js";
 
 import type { Range } from "./shared.js";
 import type { Placement } from "./observe.js";
@@ -30,6 +34,7 @@ export type StudioSourceFile = {
 };
 
 type AuthorElement = {
+  readonly range: Range;
   readonly authorElement?: string;
   readonly authorEndpoints: Readonly<Record<string, string>>;
   readonly id?: string;
@@ -48,6 +53,7 @@ function authoredElements(placements: readonly Placement[]): readonly AuthorElem
       ...(placement.authorElement === undefined ? {} : { authorElement: placement.authorElement }),
       authorEndpoints: placement.authorEndpoints ?? {},
       ...(placement.id === undefined ? {} : { id: placement.id }),
+      range: placement.range,
       sourcePath: placement.sourcePath,
       attributes: placement.attributes,
       references: placement.referenceAttributes,
@@ -60,6 +66,7 @@ function authoredElements(placements: readonly Placement[]): readonly AuthorElem
       ...(child.authorElement === undefined ? {} : { authorElement: child.authorElement }),
       authorEndpoints: child.authorEndpoints ?? {},
       ...(child.id === undefined ? {} : { id: child.id }),
+      range: child.range,
       sourcePath: child.sourcePath,
       attributes: child.attributes,
       references: child.referenceAttributes,
@@ -175,7 +182,8 @@ function recipeParameters(input: {
   return input.recipe.bindings.flatMap((declaration): readonly StudioSourceBinding[] => {
     const property = recipe.properties.find((candidate) => candidate.name === declaration.name);
     if (property === undefined) {
-      if (declaration.fallback === undefined) return [];
+      const fallback = typeof declaration.fallback === "function" ? declaration.fallback(recipe.value.properties) : declaration.fallback;
+      if (fallback === undefined) return [];
       const close = recipe.range.end - 1;
       const lineStart = Math.max(source.text.lastIndexOf("\n", close - 1), source.text.lastIndexOf("\r", close - 1)) + 1;
       const closeIndent = source.text.slice(lineStart, close);
@@ -189,7 +197,7 @@ function recipeParameters(input: {
         id: `${input.draft.id}:${input.referenceName}:${declaration.name}`,
         binding: `${input.referenceName}.${declaration.name}`,
         name: declaration.name,
-        value: declaration.fallback,
+        value: fallback,
         ...(declaration.schema === undefined ? {} : { schema: declaration.schema }),
         language: "svs" as const,
         writable: declaration.writable ?? true,
@@ -220,6 +228,57 @@ function recipeParameters(input: {
   });
 }
 
+function attributeGroup(file: StudioSourceFile, target: AuthorElement, draft: StudioEntityDraft,
+  declaration: StudioSourceBindingDeclaration, binding: string, root: string): readonly StudioSourceBinding[] {
+  if (declaration.schema === undefined) throw new Error(`Attribute group ${binding} needs a schema.`);
+  const tag = parseOpeningTag({ name: file.path, text: file.text }, target.range.start);
+  const sourceRange = { start: target.range.start, end: tag.end };
+  const preimage = file.text.slice(sourceRange.start, sourceRange.end);
+  const opening = /^<[\w:.-]+/u.exec(preimage);
+  if (!opening) throw new Error(`Cannot locate opening tag for ${binding}.`);
+  const fallback = typeof declaration.fallback === "function" ? declaration.fallback(target.attributes) : declaration.fallback;
+  const value: Record<string, CanonicalValue> = fallback !== null && typeof fallback === "object" && !Array.isArray(fallback) ? { ...(fallback as Readonly<Record<string, CanonicalValue>>) } : {};
+  const ranges: Record<string, Range | null> = {};
+  let writable = declaration.writable === true;
+  for (const name of declaration.attributes!) {
+    const range = target.attributeValueRanges[name];
+    ranges[name] = null;
+    if (range === undefined) continue;
+    if (target.references[name] !== undefined) { writable = false; value[name] = target.references[name]!; continue; }
+    value[name] = target.attributes[name] ?? target.references[name] ?? "";
+    const before = file.text.slice(target.range.start, range.start);
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const prefix = new RegExp(`\\s+${escaped}\\s*=\\s*["']$`, "u").exec(before);
+    if (!prefix) throw new Error(`Cannot locate scalar attribute ${name}.`);
+    ranges[name] = { start: prefix.index, end: range.end - target.range.start + 1 };
+  }
+  const schema = parameterRecordSchema(declaration.schema, value);
+  for (const [name, held] of Object.entries(value)) {
+    if (target.references[name] !== undefined || typeof held !== "string") continue;
+    const kind = schema?.fields[name]?.schema.kind;
+    if (kind === "number" && held.trim() !== "") value[name] = Number(held);
+    if (kind === "boolean" && (held === "true" || held === "false")) value[name] = held === "true";
+  }
+  return [{ id: `${draft.id}:${binding}`, binding, name: declaration.name, value, schema: declaration.schema,
+    language: file.language, writable, source: { path: relative(root, sourceAbsolute(root, target.sourcePath)),
+      range: sourceRange, preimage }, attributes: { insertionOffset: opening[0].length, ranges } }];
+}
+
+function omittedAttribute(file: StudioSourceFile, target: AuthorElement, draft: StudioEntityDraft,
+  declaration: StudioSourceBindingDeclaration, binding: string, root: string): readonly StudioSourceBinding[] {
+  const value = typeof declaration.fallback === "function" ? declaration.fallback(target.attributes) : declaration.fallback;
+  if (value === undefined) return [];
+  const tag = /^<[\w:.-]+/u.exec(file.text.slice(target.range.start));
+  if (tag === null) throw new Error(`Cannot locate opening tag for ${binding}.`);
+  const at = target.range.start + tag[0].length;
+  return [{ id: `${draft.id}:${binding}`, binding, name: declaration.name, value,
+    ...(declaration.schema === undefined ? {} : { schema: declaration.schema }),
+    language: file.language, writable: declaration.writable === true,
+    source: { path: relative(root, sourceAbsolute(root, target.sourcePath)),
+      range: { start: at, end: at }, preimage: "", prefix: ` ${declaration.name}="`, suffix: '"' },
+  }];
+}
+
 function referencedParameters(input: {
   readonly root: string;
   readonly files: readonly StudioSourceFile[];
@@ -238,16 +297,25 @@ function referencedParameters(input: {
   const file = sourceFor(input.root, target.sourcePath, input.files);
   if (file === undefined) return [];
   return input.declarations.flatMap((declaration) => {
+    if (declaration.attributes) return attributeGroup(file, target, input.draft, declaration, `${input.referenceName}.${declaration.name}`, input.root);
     const nestedPath = target.references[declaration.name];
-    const nested = nestedPath === undefined || declaration.referenced === undefined ? [] : referencedParameters({
+    const referenced = nestedPath === undefined || declaration.referenced === undefined ? [] : referencedParameters({
       root: input.root, files: input.files, draft: input.draft, placements: input.placements,
       referenceName: `${input.referenceName}.${declaration.name}`,
       referencePath: nestedPath,
       ...(target.resolvedReferences[declaration.name] === undefined ? {} : { referenceRef: target.resolvedReferences[declaration.name] }),
       declarations: declaration.referenced,
     });
+    const recipe = nestedPath === undefined || declaration.recipe === undefined ? [] : recipeParameters({
+      root: input.root, files: input.files, draft: input.draft, placements: input.placements,
+      current: file, referenceName: `${input.referenceName}.${declaration.name}`,
+      referencePath: nestedPath,
+      ...(target.resolvedReferences[declaration.name] === undefined ? {} : { referenceRef: target.resolvedReferences[declaration.name] }), recipe: declaration.recipe,
+      through: declaration.recipe.through ?? [],
+    });
+    const nested = [...referenced, ...recipe];
     const range = target.attributeValueRanges[declaration.name];
-    if (range === undefined) return nested;
+    if (range === undefined) return [...omittedAttribute(file, target, input.draft, declaration, `${input.referenceName}.${declaration.name}`, input.root), ...nested];
     const preimage = file.text.slice(range.start, range.end);
     const reference = target.references[declaration.name];
     const value = reference === undefined ? (target.attributes[declaration.name] ?? preimage) : reference;
@@ -288,6 +356,37 @@ function parameterReference(
   return ref === undefined ? { path } : { path, ref };
 }
 
+/** Resolve only references opted into by the consuming Companion. */
+export function composeParameterDeclarations(input: {
+  readonly placement: StudioPlacement | undefined;
+  readonly draft: StudioEntityDraft;
+  readonly placements: readonly Placement[];
+  readonly registry: StudioCompanionRegistry;
+  readonly bindings: readonly StudioSourceBindingDeclaration[];
+  readonly inspector: readonly StudioInspectorFieldDeclaration[];
+}): { bindings: readonly StudioSourceBindingDeclaration[]; inspector: readonly StudioInspectorFieldDeclaration[] } {
+  const inspector = [...input.inspector];
+  const element = input.placement === undefined ? undefined : elementFor(input.placement, input.draft);
+  const expand = (declarations: readonly StudioSourceBindingDeclaration[], owner: AuthorElement | undefined,
+    prefix: string, seen: ReadonlySet<string>): readonly StudioSourceBindingDeclaration[] => declarations.map(declaration => {
+    const path = prefix ? `${prefix}.${declaration.name}` : declaration.name;
+    const reference = prefix ? owner?.references[declaration.name] : input.draft.parameterReferences?.[declaration.name] ?? owner?.references[declaration.name];
+    const resolved = !prefix && input.draft.parameterReferences?.[declaration.name] !== undefined ? undefined : owner?.resolvedReferences[declaration.name];
+    const target = input.placements.find(candidate => resolved !== undefined
+      ? candidate.records.includes(resolved) || candidate.outputs.includes(resolved)
+      : candidate.id === reference && candidate.sourcePath === owner?.sourcePath);
+    const companion = declaration.companion && target !== undefined
+      ? input.registry.parameterCompanionFor(target.module, target.surface) : undefined;
+    const key = target?.authorElement ?? `${target?.sourcePath}:${target?.range.start}`;
+    if (companion !== undefined && seen.has(key)) throw new Error(`Circular Studio parameter reference at ${path}.`);
+    if (companion !== undefined) inspector.push(...companion.inspector.map(field => ({ ...field, binding: `${path}.${field.binding}` })));
+    const next = target === undefined ? undefined : elementFor(target, { ...input.draft, authoredId: target.id ?? "", elementRange: target.range });
+    const nested = [...(declaration.referenced ?? []), ...(companion?.bindings ?? [])];
+    return { ...declaration, referenced: expand(nested, next, path, new Set([...seen, key])) };
+  });
+  return { bindings: expand(input.bindings, element, "", new Set()), inspector };
+}
+
 /**
  * Expose only attributes a package explicitly registered. The source range is
  * still discovered by the generic markup frontend, while the meaning and
@@ -310,8 +409,9 @@ export function sourceBindingsForDraft(input: {
 
   const direct = input.declarations.flatMap((declaration) => {
     const name = declaration.name;
+    if (declaration.attributes) return attributeGroup(file, element, input.draft, declaration, name, input.root);
     const range = element.attributeValueRanges[name];
-    if (range === undefined) return [];
+    if (range === undefined) return omittedAttribute(file, element, input.draft, declaration, name, input.root);
     const preimage = file.text.slice(range.start, range.end);
     const reference = element.references[name];
     const value = reference === undefined
@@ -372,29 +472,17 @@ export function sourceBindingsForDraft(input: {
   return [...direct, ...recipes];
 }
 
-function controlForSchema(schema: StudioSourceBinding["schema"]): StudioParameterControl | undefined {
-  if (schema === undefined) return undefined;
-  if (schema.kind === "boolean") return "boolean";
-  if (schema.kind === "number") return "number";
-  if (schema.kind === "string") return schema.enum === undefined
-    ? schema.format === "color" ? "color" : "text"
-    : "select";
-  if (schema.kind === "array") return "list";
-  if (schema.kind === "object") return "record";
-  return undefined;
-}
-
-/** Resolve the Companion's visible field table against real writable bindings. */
+/** Resolve the Companion's visible field table against real bindings and entity facts. */
 export function inspectorFieldsForBindings(
   draft: StudioEntityDraft,
   bindings: readonly StudioSourceBinding[],
   declarations: readonly StudioInspectorFieldDeclaration[],
 ): readonly StudioInspectorField[] {
   const byBinding = new Map(bindings.map((binding) => [binding.binding, binding] as const));
-  return declarations.flatMap((declaration): readonly StudioInspectorField[] => {
+  const fields = declarations.flatMap((declaration): readonly StudioInspectorField[] => {
     const binding = byBinding.get(declaration.binding);
-    if (binding === undefined || !binding.writable) return [];
-    const control = declaration.control ?? controlForSchema(binding.schema);
+    if (binding === undefined) return [];
+    const control = declaration.control ?? (binding.attributes ? "record" : parameterControlForSchema(binding.schema));
     if (control === undefined) {
       throw new Error(`Studio Inspector binding ${declaration.binding} has neither a control nor a supported public schema.`);
     }
@@ -408,10 +496,12 @@ export function inspectorFieldsForBindings(
       ...(declaration.options !== undefined || schemaOptions === undefined
         ? {}
         : { options: schemaOptions }),
-      language: binding.language,
-      source: binding.source,
+      ...(binding.writable ? { edit: { language: binding.language, source: binding.source, ...(binding.attributes ? { attributes: binding.attributes } : {}) } } : {}),
     }];
   });
+  return [...fields, ...(draft.inspector ?? []).map((fact): StudioInspectorField => ({
+    ...fact, id: `${draft.id}:inspector:fact:${fact.id}`, control: "text",
+  }))];
 }
 
 /** Runtime authority, rather than a Companion allowlist, makes timing fields writable. */

package/packages/studio/src/preview/render.ts

@@ -45,7 +45,11 @@ export function renderPreview(input: RenderInput): string {
       data-loop="${clip.source.loop}"
       data-phase="${clip.source.phaseSample / 48_000}"
       data-playback-rate="${clip.playbackRate}"
-      data-gain="${clip.gain}"></audio>`;
+      data-gain="${clip.gain}"
+      data-presentation="${encodeURIComponent(JSON.stringify({
+        gainEnvelope: clip.gainEnvelope, audibility: clip.audibility,
+        fadeInSamples: clip.fadeInSamples, fadeOutSamples: clip.fadeOutSamples,
+      }))}"></audio>`;
     }).join("");
   return injectRuntimeShim(html, audio);
 }

package/packages/studio/src/preview/runtime-shim.ts

@@ -1,3 +1,5 @@
+import { audioEnvelopeGainAt } from "@hypit/composition";
+
 /**
  * Studio's frame driver for a compiled HyperFrames document.
  *
@@ -48,6 +50,7 @@ function shim(): string {
       rate: parseFloat(element.getAttribute('data-playback-rate') || '1') || 1
     });
   }
+  var audioContext;
   var programmeAudio = [];
   for (var element of document.querySelectorAll('.hypit-studio-audio')) {
     programmeAudio.push({
@@ -59,10 +62,51 @@ function shim(): string {
       loop: element.getAttribute('data-loop') === 'true',
       phase: parseFloat(element.getAttribute('data-phase') || '0') || 0,
       rate: parseFloat(element.getAttribute('data-playback-rate') || '1') || 1,
-      gain: parseFloat(element.getAttribute('data-gain') || '1') || 1
+      gain: Number(element.getAttribute('data-gain') ?? '1'),
+      presentation: JSON.parse(decodeURIComponent(element.getAttribute('data-presentation') || '%7B%7D'))
     });
   }
 
+  function scheduleEnvelope(param, points, sample, now) {
+    param.cancelScheduledValues(now);
+    param.setValueAtTime(audioEnvelopeGainAt(points, sample), now);
+    for (var point of points || []) {
+      if (point.sample > sample) param.linearRampToValueAtTime(point.gain, now + (point.sample - sample) / 48000);
+    }
+  }
+
+  // Each factor has its own GainNode so intersecting ramps multiply exactly.
+  // These are the same absolute-sample envelopes consumed by the render mixer.
+  function placeAudioGain(record, seconds) {
+    if (!record.nodes) {
+      var source = audioContext.createMediaElementSource(record.element);
+      record.nodes = Array.from({ length: 5 }, function () { return audioContext.createGain(); });
+      var previous = source;
+      for (var node of record.nodes) { previous.connect(node); previous = node; }
+      previous.connect(audioContext.destination);
+      record.element.volume = 1;
+    }
+    var sample = seconds * 48000;
+    var now = audioContext.currentTime;
+    var p = record.presentation;
+    var start = record.start * 48000, end = (record.start + record.duration) * 48000;
+    record.nodes[0].gain.setValueAtTime(record.gain, now);
+    scheduleEnvelope(record.nodes[1].gain, p.gainEnvelope, sample, now);
+    scheduleEnvelope(record.nodes[2].gain, p.fadeInSamples > 0
+      ? [{ sample: start, gain: 0 }, { sample: start + p.fadeInSamples, gain: 1 }] : undefined, sample, now);
+    scheduleEnvelope(record.nodes[3].gain, p.fadeOutSamples > 0
+      ? [{ sample: end - p.fadeOutSamples, gain: 1 }, { sample: end, gain: 0 }] : undefined, sample, now);
+    var gate = record.nodes[4].gain;
+    gate.cancelScheduledValues(now);
+    gate.setValueAtTime(p.audibility === undefined || p.audibility.some(function (span) {
+      return sample >= span.startSample && sample < span.endSampleExclusive;
+    }) ? 1 : 0, now);
+    for (var span of p.audibility || []) {
+      if (span.startSample > sample) gate.setValueAtTime(1, now + (span.startSample - sample) / 48000);
+      if (span.endSampleExclusive > sample) gate.setValueAtTime(0, now + (span.endSampleExclusive - sample) / 48000);
+    }
+  }
+
   function seekDecoded(element, target) {
     if (Math.abs(element.currentTime - target) < 0.0005 && element.readyState >= 2) return Promise.resolve();
     return new Promise(function (resolve) {
@@ -148,7 +192,7 @@ function shim(): string {
       } else {
         if (Math.abs(element.currentTime - target) > 0.08) element.currentTime = target;
         element.playbackRate = record.rate;
-        element.volume = Math.max(0, Math.min(1, record.gain));
+        placeAudioGain(record, currentSeconds + frameSeconds / 2);
         if (element.paused) {
           var started = element.play();
           if (started) started.catch(function () {});
@@ -169,6 +213,8 @@ function shim(): string {
   };
   window.__hypitPlayFrame = function (frame) {
     playing = true;
+    if (programmeAudio.length && !audioContext) audioContext = new AudioContext();
+    if (audioContext && audioContext.state === 'suspended') audioContext.resume();
     return apply(frame / fps, false);
   };
   window.__hypitFrameReady = apply(0, true);
@@ -178,7 +224,7 @@ function shim(): string {
 }
 
 export function injectRuntimeShim(html: string, audio = ""): string {
-  const script = audio + shim();
+  const script = audio + shim().replace("(function () {", `(function () {\n${audioEnvelopeGainAt.toString()}`);
   const at = html.lastIndexOf("</body>");
   return at < 0 ? html + script : html.slice(0, at) + script + html.slice(at);
 }

package/packages/studio/src/programme.ts

@@ -4,13 +4,13 @@ import { sameType } from "@hypit/protocol";
 import type { Composition } from "@hypit/composition";
 import { compositionTypes } from "@hypit/composition";
 import {
-  projectSemanticProgramSpace,
+  projectTimelineSpace,
   semanticAnchorFrames,
-  semanticTrackSpans,
-} from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
-import { semanticTrackTypes } from "@hypit/semantic-track";
-import { assertProgramSpaceIdentity, programSpaceTypes } from "@hypit/program-space";
+  timelineSpans,
+} from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+import { timelineTypes } from "@hypit/timeline";
+import { assertProgramSpaceIdentity } from "@hypit/program-space";
 import type { ProgramSpace } from "@hypit/program-space";
 import type { StudioResolvedTrack, StudioTemporalBinding } from "@hypit/studio-adapter";
 import type { RuntimeHostTransientExecution } from "@hypit/runtime-host-node";
@@ -36,7 +36,6 @@ export type Preview = {
   readonly values: ReadonlyMap<string, unknown>;
   readonly temporalBindings: ReadonlyMap<string, readonly StudioTemporalBinding[]>;
   readonly composition: Composition;
-  readonly timing: "measured" | "authored";
   readonly narrativeId?: string;
   readonly timingOutput?: { readonly name: string; readonly ref: string };
   readonly timingCandidateId?: string;
@@ -173,11 +172,11 @@ export async function preview(input: {
   const timingType = timingOutput?.typeRef ?? timingRecord?.type;
   const timingValue = selectedValue(executed.state, input.timeRef);
   if (timingValue?.kind !== "inline" || timingType === undefined) throw new Error("Studio requires a resolved film time source.");
-  const semantic = sameType(timingType, semanticTrackTypes.track) ? timingValue.value as unknown as SemanticTrack : undefined;
-  if (semantic === undefined && !sameType(timingType, programSpaceTypes.programSpace)) throw new Error("Unsupported Studio time source.");
-  const spans = semantic === undefined ? [] : semanticTrackSpans(semantic);
-  const anchors = semantic === undefined ? new Map<string, number>() : semanticAnchorFrames(semantic);
-  const space = semantic === undefined ? timingValue.value as unknown as ProgramSpace : projectSemanticProgramSpace(semantic);
+  if (!sameType(timingType, timelineTypes.track)) throw new Error("Studio requires the declared Timeline.");
+  const semantic = timingValue.value as unknown as Timeline;
+  const spans = timelineSpans(semantic);
+  const anchors = semanticAnchorFrames(semantic);
+  const space = projectTimelineSpace(semantic);
   assertProgramSpaceIdentity(space);
   const rate = space.frameRate;
   const compositionValue = selectedValue(executed.state, input.compositionRef);
@@ -227,22 +226,8 @@ export async function preview(input: {
     const stored = selectedValue(executed.state, target.ref);
     if (stored?.kind === "inline") values.set(target.ref, stored.value);
   }
-  // Author Records are already deterministic inline values from this exact
-  // compilation. Studio Track Companions may need them to name a resolved projection
-  // (for example Caption cue text); exposing them here avoids recomputing the
-  // domain value or turning a Record into a fake graph target.
-  for (const placement of input.source.observations.placements) {
-    for (const value of placement.values) {
-      const suffixes = [`::record::${value.id}`, `::output::${value.id}`];
-      for (const reference of input.projections.flatMap((projection) => projection.trace.references)) {
-        if (suffixes.some((suffix) => reference.ref.endsWith(suffix))) values.set(reference.ref, value.value);
-      }
-    }
-  }
-  // Script is a raw Surface, so its inline Records are not among the structured
-  // element observations above. They are still ordinary Author values from
-  // the same compilation and are needed to turn Caption atom ids back into the
-  // text the author actually sees.
+  // Author records from this compilation already carry exact qualified references.
+  // Expose referenced inline values to Companions without guessing their owner by suffix.
   for (const record of input.source.compiled.program.records) {
     if (record.value.kind !== "inline") continue;
     if (input.projections.some((projection) => projection.trace.references
@@ -257,8 +242,7 @@ export async function preview(input: {
     values,
     temporalBindings,
     composition,
-    timing: semantic === undefined ? "authored" : "measured",
-    ...(semantic === undefined ? {} : { narrativeId: semantic.narrativeId }),
+    ...(semantic.narrativeId === undefined ? {} : { narrativeId: semantic.narrativeId }),
     timingOutput: { name: timingOutput?.name ?? space.id, ref: input.timeRef },
     ...(timingCandidateId === undefined ? {} : { timingCandidateId }),
     timingCandidateOrigin: timingCandidateId === undefined ? "source" : "run",

package/packages/studio/src/server.ts

@@ -15,7 +15,7 @@ import type { ServedFile } from "./compile.js";
 import type { StudioDomain } from "./domain.js";
 import type { StudioCompanionRegistry } from "./studio-registry.js";
 import { loadStudioRun } from "./run.js";
-import { parameterAuthorValue, parameterOption, serializeParameterValue, validateParameterValue } from "./parameter-values.js";
+import { parameterAuthorValue, parameterOption, serializeParameterValue, serializeAttributeGroup, validateParameterValue } from "./parameter-values.js";
 import { readStudioSession } from "./session.js";
 import type { Range, StudioFailure, StudioLibraryRequest, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
 import { createStudioStoryboard } from "./storyboard.js";
@@ -402,7 +402,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
     if (mutation.type === "timeline.adjust") return timelinePatches(mutation);
     const clip = currentClip(mutation.entityId);
     const parameter = clip.inspector.find((candidate) => candidate.id === mutation.parameterId);
-    if (parameter === undefined) {
+    if (parameter?.edit === undefined) {
       throw new Error(`Entity ${mutation.entityId} has no writable parameter ${mutation.parameterId}.`);
     }
     const authorValue = parameterAuthorValue(parameter, mutation.value);
@@ -420,10 +420,14 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       throw new Error(`${parameter.label} does not accept ${mutation.value}.`);
     }
     if (parameter.control === "color") validateParameterValue(authorValue, { kind: "string", format: "color" }, parameter.label);
-    const encoded = serializeParameterValue(authorValue, parameter.language);
-    const replacement = `${parameter.source.prefix ?? ""}${encoded}${parameter.source.suffix ?? ""}`;
-    return replacement === parameter.source.preimage ? [] : [{
-      ...parameter.source,
+    if (parameter.edit.attributes) {
+      const replacement = serializeAttributeGroup(parameter, authorValue);
+      return replacement === parameter.edit.source.preimage ? [] : [{ ...parameter.edit.source, replacement }];
+    }
+    const encoded = serializeParameterValue(authorValue, parameter.edit.language);
+    const replacement = `${parameter.edit.source.prefix ?? ""}${encoded}${parameter.edit.source.suffix ?? ""}`;
+    return replacement === parameter.edit.source.preimage ? [] : [{
+      ...parameter.edit.source,
       replacement,
     }];
   };

package/packages/studio/src/shared.ts

@@ -9,6 +9,7 @@ import type {
   StudioIcon,
   StudioEditHandle,
   StudioLaneDescription,
+  StudioTrackBand,
   StudioMaterialPreview,
   StudioInspectorField,
   StudioInspectorDomain,
@@ -63,6 +64,7 @@ export type StudioTrackBinding = {
   readonly companion: string;
   /** Studio-local partition key for an attached projection. */
   readonly attachmentId?: string;
+  readonly bands?: readonly Omit<StudioTrackBand, "bindings" | "inspector">[];
   readonly lane: StudioLaneDescription;
   readonly authoredTag?: string;
   readonly references: readonly { readonly name: string; readonly type: string }[];
@@ -95,6 +97,8 @@ export type Clip = {
   readonly presentId?: string;
   /** The authored id this Present is named after, when it names one. */
   readonly authoredId: string;
+  readonly selectionGroup?: string;
+  readonly band?: string;
   /** The Script marker that placed it, when something said put it there. */
   readonly markerId?: string;
   readonly display: StudioEntityDisplay;
@@ -281,8 +285,6 @@ export type StudioSnapshot = {
   /** The Tracks, compiled into the document the renderer photographs. */
   readonly preview: { readonly kind: "hyperframes"; readonly srcdoc: string };
   readonly provenance: {
-    /** Where the timeline came from. The frame domain always shares its source. */
-    readonly timing: "measured" | "authored";
     readonly picture: "resolved";
     /** What the badges above are standing for, in one sentence. */
     readonly note: string;