@hypit/hypit 0.1.3 → 0.1.5

package/packages/studio/src/parameter-values.ts

@@ -1,5 +1,44 @@
 import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
 import { formatSvsValue } from "@hypit/svs";
+import type { StudioInspectorField, StudioParameterControl, StudioParameterOption, StudioNumberPresentation } from "@hypit/studio-adapter";
+
+export const parameterOption = (option: StudioParameterOption): Exclude<StudioParameterOption, string> =>
+  typeof option === "string" ? { value: option, label: option } : option;
+
+// Keep binary floating-point residue out of decimal controls (0.55 × 100 is 55).
+const scaledDecimal = (value: number, scale: number): number =>
+  scale === 1 ? value : Number((value * scale).toPrecision(15));
+
+export function parameterNumber(value: CanonicalValue, presentation: StudioNumberPresentation = {}): { value: number; suffix: string } {
+  let held = value;
+  let suffix = "";
+  if (presentation.suffixes !== undefined) {
+    if (typeof held !== "string") throw new Error("A suffixed number must be authored as text.");
+    const text = held.trim();
+    const found = [...presentation.suffixes].sort((a, b) => b.length - a.length).find(item => text.endsWith(item));
+    if (found === undefined) throw new Error("The authored unit is not supported by this field.");
+    suffix = found;
+    held = text.slice(0, text.length - suffix.length).trim();
+  }
+  if (typeof held !== "number" && (typeof held !== "string" || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/iu.test(held.trim()))) {
+    throw new Error("This field needs a numeric value.");
+  }
+  const number = scaledDecimal(Number(held), presentation.scale ?? 1);
+  if (!Number.isFinite(number)) throw new Error("This field needs a finite number.");
+  return { value: number, suffix };
+}
+
+/** Decode the displayed edit before validating and serializing the authored value. */
+export function parameterAuthorValue(field: StudioInspectorField, displayed: CanonicalValue): CanonicalValue {
+  if (field.control !== "number") return displayed;
+  if (typeof displayed !== "number" || !Number.isFinite(displayed)) throw new Error(`${field.label} expects a finite number.`);
+  const presentation = field.number ?? {};
+  if (presentation.minimum !== undefined && displayed < presentation.minimum) throw new Error(`${field.label} must be at least ${presentation.minimum}.`);
+  if (presentation.maximum !== undefined && displayed > presentation.maximum) throw new Error(`${field.label} must be at most ${presentation.maximum}.`);
+  const value = scaledDecimal(displayed, 1 / (presentation.scale ?? 1));
+  if (!Number.isFinite(value)) throw new Error(`${field.label} cannot be represented.`);
+  return presentation.suffixes === undefined ? value : `${value}${parameterNumber(field.value, presentation).suffix}`;
+}
 
 function fail(path: string, expectation: string): never {
   throw new Error(`${path} ${expectation}.`);
@@ -76,6 +115,49 @@ export function validateParameterValue(value: CanonicalValue, schema: ValueSchem
 
 export function serializeParameterValue(value: CanonicalValue, language: "svml" | "svs" | "svrun"): string {
   if (language === "svs") return formatSvsValue(value);
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+  if (typeof value === "string") return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
   throw new Error(`${language.toUpperCase()} parameter bindings currently accept scalar values only.`);
 }
+
+/** Record alternatives are selected by an explicitly literal-valued field. */
+export function parameterRecordVariants(schema: ValueSchema): readonly {
+  key: string; value: CanonicalValue; schema: Extract<ValueSchema, { kind: "object" }>;
+}[] {
+  if (schema.kind !== "oneOf" || !schema.variants.every(variant => variant.kind === "object")) return [];
+  const records = schema.variants as readonly Extract<ValueSchema, { kind: "object" }>[];
+  const key = Object.keys(records[0]?.fields ?? {}).find(name => records.every(record => record.fields[name]?.schema.kind === "literal")
+    && new Set(records.map(record => JSON.stringify((record.fields[name]!.schema as { value: CanonicalValue }).value))).size === records.length);
+  return key === undefined ? [] : records.map(record => ({ key, value: (record.fields[key]!.schema as { value: CanonicalValue }).value, schema: record }));
+}
+
+export function parameterRecordSchema(schema: ValueSchema, value: CanonicalValue): Extract<ValueSchema, { kind: "object" }> | undefined {
+  if (schema.kind === "object") return schema;
+  if (value === null || Array.isArray(value) || typeof value !== "object") return undefined;
+  return parameterRecordVariants(schema).find(variant => (value as Readonly<Record<string, CanonicalValue>>)[variant.key] === variant.value)?.schema;
+}
+
+/** Replace only a Companion-declared group; unrelated attributes and child content survive. */
+export function serializeAttributeGroup(field: StudioInspectorField, value: CanonicalValue): string {
+  const group = field.edit?.attributes;
+  if (!group || value === null || Array.isArray(value) || typeof value !== "object") throw new Error("Expected an attribute record.");
+  const entries = Object.entries(value);
+  if (entries.some(([name]) => !Object.hasOwn(group.ranges, name))) throw new Error("Attribute is outside this group.");
+  let text = field.edit!.source.preimage;
+  const ranges = Object.values(group.ranges).filter((range): range is NonNullable<typeof range> => range !== null);
+  for (const range of ranges.sort((a, b) => b.start - a.start)) text = text.slice(0, range.start) + text.slice(range.end);
+  const attributes = entries.map(([name, held]) => ` ${name}="${serializeParameterValue(held, field.edit!.language)}"`).join("");
+  return text.slice(0, group.insertionOffset) + attributes + text.slice(group.insertionOffset);
+}
+
+export function parameterControlForSchema(schema: ValueSchema | undefined): 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" || parameterRecordVariants(schema).length > 0) return "record";
+  return undefined;
+}

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,8 +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 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 [];
+    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;
@@ -263,7 +339,7 @@ function referencedParameters(input: {
       ...(!writable
         ? { disabledReason: reference === undefined ? "该几何值由组件声明为只读。" : "引用由作者在 SVML 中绑定，面板不替换引用关系。" }
         : {}),
-    } satisfies StudioSourceBinding];
+    } satisfies StudioSourceBinding, ...nested];
   });
 }
 
@@ -280,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
@@ -302,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
@@ -364,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.`);
     }
@@ -400,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. */
@@ -484,7 +582,7 @@ export function resolveTimelineEditHandles(
     moveEffect?: "translate-window" | "move-start",
   ): StudioEditHandle => {
     const unavailable = affected.find(({ endpoint }) => endpoint.authority.kind === "fixed");
-    if (unavailable !== undefined) return disabled(gesture, "该端点由 Program 或 Segment 结构固定，不能从组件时间线反写。");
+    if (unavailable !== undefined) return disabled(gesture, "该时间表达未开放时间轴回写。");
     const projected: ({ readonly missing: string } | StudioEditSource)[] = [];
     for (const { endpoint, role } of affected) {
       if (endpoint.authority.kind !== "parameter") continue;
@@ -527,24 +625,15 @@ export function resolveTimelineEditHandles(
   }
   const start = { endpoint: projection.start, role: "start" as const };
   const end = { endpoint: projection.end, role: "end" as const };
-  const move = projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-    ? [start]
-    : projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-      ? [end]
-      : [start, end];
-  const trimStart = projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-    ? [start]
-    : projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-      ? [start, end]
-      : [start];
-  const trimEnd = projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-    ? [end]
-    : projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-      ? [start, end]
-      : [end];
+  if (projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start") {
+    return [handle("move", [start], "translate-window"), handle("trim-end", [end])];
+  }
+  if (projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end") {
+    return [handle("move", [end], "translate-window"), handle("trim-start", [start])];
+  }
   return [
-    handle("move", move, "translate-window"),
-    handle("trim-start", trimStart),
-    handle("trim-end", trimEnd),
+    handle("move", [start, end], "translate-window"),
+    handle("trim-start", [start]),
+    handle("trim-end", [end]),
   ];
 }

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",