@hypit/hypit 0.1.4 → 0.1.6

package/packages/studio/src/localization-node.ts

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { isAbsolute, resolve } from "node:path";
+import type { Plugin } from "vite";
+import { builtinLanguages, languageCoverage, readLanguagePack } from "./localization.js";
+import type { LanguagePack } from "./localization.js";
+
+export async function loadLanguagePack(specifier: string, cwd: string, packageRoot: string): Promise<LanguagePack> {
+  const path = isAbsolute(specifier) || specifier.startsWith(".")
+    ? resolve(cwd, specifier)
+    : createRequire(resolve(packageRoot, "package.json")).resolve(specifier);
+  try { return readLanguagePack(JSON.parse(await readFile(path, "utf8"))); }
+  catch (error) { throw new Error(`Language pack ${specifier}: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+export function describeLanguagePack(pack: LanguagePack): string {
+  const { missing, unknown } = languageCoverage(pack);
+  return [`${pack.name} (${pack.locale})`,
+    `Missing translations (${missing.length}; English is used): ${missing.join(", ") || "none"}`,
+    `Unknown message IDs (${unknown.length}): ${unknown.join(", ") || "none"}`,
+  ].join("\n");
+}
+
+export async function studioLanguages(specifiers: readonly string[], cwd: string, packageRoot: string): Promise<readonly LanguagePack[]> {
+  const packs = new Map(builtinLanguages.map(pack => [pack.locale, pack]));
+  for (const specifier of specifiers) {
+    const pack = await loadLanguagePack(specifier, cwd, packageRoot);
+    packs.set(pack.locale, pack);
+  }
+  return [...packs.values()];
+}
+
+export function studioLocalizationPlugin(packs: readonly LanguagePack[]): Plugin {
+  return {
+    name: "hypit-studio-localization",
+    configureServer(server) {
+      server.middlewares.use((request, response, next) => {
+        if (new URL(request.url ?? "/", "http://localhost").pathname !== "/__studio/locales") return next();
+        if (request.method !== "GET") { response.statusCode = 405; response.end(); return; }
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        response.setHeader("cache-control", "no-store");
+        response.end(JSON.stringify(packs));
+      });
+    },
+  };
+}

package/packages/studio/src/localization.ts

@@ -0,0 +1,85 @@
+import english from "../locales/en.json" with { type: "json" };
+import chinese from "../locales/zh-CN.json" with { type: "json" };
+
+export type Message = keyof typeof english.messages;
+export type MessageValue = string | ({ readonly other: string } & Partial<Record<Intl.LDMLPluralRule, string>>);
+export type LanguagePack = {
+  readonly locale: string;
+  /** Native language name, displayed without translation. */
+  readonly name: string;
+  readonly direction: "ltr" | "rtl";
+  readonly messages: Readonly<Record<string, MessageValue>>;
+};
+export const defaultLanguage: LanguagePack = english as LanguagePack;
+export const builtinLanguages: readonly LanguagePack[] = [defaultLanguage, chinese as LanguagePack];
+export type MessageValues = Readonly<Record<string, string | number>>;
+const plurals = new Set(["zero", "one", "two", "few", "many", "other"]);
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const variants = (message: MessageValue): readonly string[] => typeof message === "string" ? [message] : Object.values(message);
+const variables = (text: string): string[] => [...new Set([...text.matchAll(/\{(\w+)\}/gu)].map(match => match[1]!))].sort();
+
+/** Read data, never executable translation code. Partial translations remain useful. */
+export function readLanguagePack(value: unknown): LanguagePack {
+  if (!record(value) || typeof value.locale !== "string" || typeof value.name !== "string" || !value.name.trim()
+    || (value.direction !== "ltr" && value.direction !== "rtl") || !record(value.messages)) {
+    throw new Error("A Studio language pack needs locale, name, direction (ltr/rtl) and messages.");
+  }
+  const locale = Intl.getCanonicalLocales(value.locale)[0];
+  if (!locale) throw new Error("A Studio language pack needs a BCP 47 locale.");
+  const messages: Record<string, MessageValue> = {};
+  for (const [id, message] of Object.entries(value.messages)) {
+    if (typeof message !== "string" && (!record(message) || typeof message.other !== "string"
+      || Object.entries(message).some(([form, text]) => !plurals.has(form) || typeof text !== "string"))) {
+      throw new Error(`${id}: expected text or plural forms with an 'other' form.`);
+    }
+    const translated = message as MessageValue;
+    const original = Object.hasOwn(defaultLanguage.messages, id) ? defaultLanguage.messages[id] : undefined;
+    if (original !== undefined) {
+      const expected = variables(variants(original)[0]!).join(",");
+      for (const text of variants(translated)) {
+        if (variables(text).join(",") !== expected) throw new Error(`${id}: preserve the named variables {${expected.split(",").join("}, {")}}.`);
+      }
+      if (typeof translated !== "string" && !variables(variants(original)[0]!).includes("count")) {
+        throw new Error(`${id}: plural forms require a count variable.`);
+      }
+    }
+    messages[id] = translated;
+  }
+  return { locale, name: value.name, direction: value.direction, messages };
+}
+
+export function languageCoverage(pack: LanguagePack): { missing: string[]; unknown: string[] } {
+  return {
+    missing: Object.keys(defaultLanguage.messages).filter(id => !Object.hasOwn(pack.messages, id)),
+    unknown: Object.keys(pack.messages).filter(id => !Object.hasOwn(defaultLanguage.messages, id)),
+  };
+}
+
+export function chooseLanguage(packs: readonly LanguagePack[], preferences: readonly string[]): LanguagePack {
+  for (const preference of preferences) {
+    let locale: string;
+    try { locale = Intl.getCanonicalLocales(preference)[0]!; } catch { continue; }
+    const exact = packs.find(pack => pack.locale === locale);
+    if (exact) return exact;
+    // Match regional/script variants without a list of special language cases.
+    const requested = new Intl.Locale(locale).maximize();
+    const related = packs.find(pack => {
+      const candidate = new Intl.Locale(pack.locale).maximize();
+      return candidate.language === requested.language && candidate.script === requested.script;
+    });
+    if (related) return related;
+  }
+  return packs.find(pack => pack.locale === defaultLanguage.locale) ?? defaultLanguage;
+}
+
+export function formatMessage(pack: LanguagePack, id: Message, values: MessageValues = {}): string {
+  const translated = pack.messages[id];
+  const message = translated ?? defaultLanguage.messages[id]!;
+  const locale = translated === undefined ? defaultLanguage.locale : pack.locale;
+  const template = typeof message === "string" ? message
+    : message[new Intl.PluralRules(locale).select(Number(values.count))] ?? message.other;
+  return template.replace(/\{(\w+)\}/gu, (match, key: string) => {
+    const value = values[key];
+    return typeof value === "number" ? new Intl.NumberFormat(pack.locale).format(value) : value ?? match;
+  });
+}

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

@@ -1,6 +1,6 @@
 import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
 import { formatSvsValue } from "@hypit/svs";
-import type { StudioInspectorField, StudioParameterOption, StudioNumberPresentation } from "@hypit/studio-adapter";
+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;
@@ -119,3 +119,45 @@ export function serializeParameterValue(value: CanonicalValue, language: "svml"
   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,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",