@hypit/hypit 0.1.3 → 0.1.5

package/packages/film/src/program.ts

@@ -1,5 +1,5 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import { assertCanvasSpace } from "@hypit/spatial";
 import type { CanvasSpace } from "@hypit/spatial";
 import { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackIdentity, sealComposition } from "@hypit/composition";
@@ -64,7 +64,7 @@ export function createFilmTrackSet(): FilmTrackSet {
   });
 }
 
-function appendTrack(set: FilmTrackSet, programSpace: ProgramSpace, track: Track): FilmTrackSet {
+function appendTrack(set: FilmTrackSet, programSpace: Timeline, track: Track): FilmTrackSet {
   assertFilmTrackSetIdentity(set);
   assertProgramSpaceIdentity(programSpace);
   if (track.kind === "visual") assertVisualTrackIdentity(track, programSpace);
@@ -78,18 +78,18 @@ function appendTrack(set: FilmTrackSet, programSpace: ProgramSpace, track: Track
   });
 }
 
-export function appendFilmVisualTrack(set: FilmTrackSet, programSpace: ProgramSpace, track: VisualTrack): FilmTrackSet {
+export function appendFilmVisualTrack(set: FilmTrackSet, programSpace: Timeline, track: VisualTrack): FilmTrackSet {
   return appendTrack(set, programSpace, track);
 }
 
-export function appendFilmAudioTrack(set: FilmTrackSet, programSpace: ProgramSpace, track: AudioTrack): FilmTrackSet {
+export function appendFilmAudioTrack(set: FilmTrackSet, programSpace: Timeline, track: AudioTrack): FilmTrackSet {
   return appendTrack(set, programSpace, track);
 }
 
 export function compileFilmComposition(
   program: FilmProgram,
   canvas: CanvasSpace,
-  programSpace: ProgramSpace,
+  programSpace: Timeline,
   set: FilmTrackSet,
 ): Composition {
   assertFilmProgramIdentity(program);

package/packages/film/src/recipe.ts

@@ -1,7 +1,8 @@
+import type { Timeline } from "@hypit/timeline";
 import type { SvsRecipe } from "@hypit/svs";
 
 /**
- * The Film Recipe owns Film appearance only. Canvas geometry and ProgramSpace
+ * The Film Recipe owns Film appearance only. Canvas geometry and Timeline
  * remain separate graph inputs and cannot be smuggled into a stylesheet.
  */
 

package/packages/film/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import { spatialTypes } from "@hypit/spatial";
 import { compositionTypes } from "@hypit/composition";
 import type { AudioTrack, Track, VisualTrack } from "@hypit/composition";
@@ -93,13 +93,13 @@ function trackKind(reference: SurfaceResolvedReference): "visual" | "audio" {
 }
 
 export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  exactAttributes(element, ["id", "canvas", element.attributes.space === undefined ? "semantic" : "space", "appearance"]);
+  exactAttributes(element, ["id", "canvas", "timeline", "appearance"]);
   const id = stringAttribute(element, "id");
   const canvas = requiredReference(element, "canvas", resolveReference);
   if (!sameType(canvas.type, spatialTypes.canvas)) {
     throw new Error(`${element.name}.canvas must reference CanvasSpace`);
   }
-  const time = createTemporalSpace({ id, element, ...resolveTemporalContext({ element, resolveReference }) });
+  const context = resolveTemporalContext({ element, resolveReference });
   const appearanceReference = requiredReference(element, "appearance", resolveReference);
   const appearance = filmAppearanceFromRecipe(
     recipe(appearanceReference, `${element.name}.appearance`).properties,
@@ -129,18 +129,18 @@ export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveRe
       value: { kind: "inline", value: program },
       range: element.range,
     }],
-    components: [...time.components, {
+    components: [{
       id,
       fragment: fragment.id,
       inputs: {
         program: { kind: "record", id: programId },
         canvas: canvas.ref,
-        space: time.space.ref,
+        timeline: context.timeline.ref,
         ...Object.fromEntries(tracks.map((track) => [track.name, track.source.ref])),
       },
       outputs: { composition: `${id}.composition` },
       range: element.range,
     }],
-    fragments: [...time.fragments, fragment],
+    fragments: [fragment],
   };
 };

package/packages/film-studio/package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "@hypit/composition": "workspace:*",
     "@hypit/film": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/studio-adapter": "workspace:*",
     "@hypit/program-space": "workspace:*"
   }

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

@@ -2,13 +2,13 @@ import { programSpaceTypes } from "@hypit/program-space";
 import type { StudioFilmCompanion } from "@hypit/studio-adapter";
 import { compositionTypes } from "@hypit/composition";
 import { filmModuleRef } from "@hypit/film";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 
 /** Film owns the author vocabulary that selects its time source and peer Tracks. */
 export const filmStudioCompanions: readonly StudioFilmCompanion[] = [{
   id: "film",
   match: { module: filmModuleRef, surface: "film", outputType: compositionTypes.composition },
-  timeSources: [{ attribute: "semantic", type: semanticTrackTypes.track }, { attribute: "space", type: programSpaceTypes.programSpace }],
+  timeSources: [{ attribute: "timeline", type: timelineTypes.track }],
   tracks: {
     childSurface: "Track",
     sourceAttribute: "source",

package/packages/fishaudio-speech/README.md

@@ -0,0 +1,33 @@
+# `@hypit/fishaudio-speech`
+
+Exact model contracts and author Surfaces for Fish Audio Voice Design and Voice Clone.
+
+The package owns two distinct speech operations:
+
+- `voice-design-1` creates an ordinary audio voice reference from a natural-language description
+  and a short authored speech sample;
+- `voice-clone` uses one accepted audio voice reference to create independent speech.
+
+It contains no API URL, credential, retry, queue or Fish Audio wire encoding. Those belong to a
+Runtime Endpoint such as `@hypit/provider-hypihub`. Both models return the shared
+`GeneratedAudioSet`; the author Surfaces expose its primary member as an ordinary audio Resource.
+
+```xml
+<import as="fish" from="@hypit/fishaudio-speech@1"/>
+
+<fish:VoiceDesign id="host" speech={story.segment.voiceSample.speech}>
+  A clear young woman with a grounded, confident conversational delivery.
+</fish:VoiceDesign>
+
+<fish:VoiceClone id="narration" speech={story.segment.reveal.speech} voice={host.reference}/>
+```
+
+`host.reference` is not a special identity record. It is a normal audio Resource, so the same
+accepted reference can also feed an A-roll video model that accepts reference audio.
+`VoiceClone` takes spoken text and a voice reference. It has no separate natural-language delivery
+instruction input; the description in `VoiceDesign` establishes the reference voice.
+
+Official API reference: <https://docs.fish.audio/>
+
+The Source import selects author syntax and exact model semantics only. The Runtime Profile
+independently selects the Provider that fulfils either capability.

package/packages/fishaudio-speech/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/fishaudio-speech",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/artifact": "workspace:*",
+    "@hypit/generation": "workspace:*",
+    "@hypit/model-kit": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  }
+}

package/packages/fishaudio-speech/src/activation.ts

@@ -0,0 +1,32 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeFishAudioVoiceCloneSurface,
+  decodeFishAudioVoiceDesignSurface,
+  fishAudioSpeechComponent,
+  fishAudioSpeechDefinition,
+  fishAudioSpeechManifest,
+  fishAudioSpeechMarkupSurfaces,
+  fishAudioSpeechModuleRef,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: fishAudioSpeechManifest }],
+  components: [fishAudioSpeechComponent],
+  hostFacets: [
+    fishAudioSpeechDefinition.hostFacet,
+    createMarkupSurfaceHostFacet({
+      module: fishAudioSpeechModuleRef,
+      declaration: fishAudioSpeechMarkupSurfaces.find((item) => item.name === "voiceDesign")!,
+      handler: decodeFishAudioVoiceDesignSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: fishAudioSpeechModuleRef,
+      declaration: fishAudioSpeechMarkupSurfaces.find((item) => item.name === "voiceClone")!,
+      handler: decodeFishAudioVoiceCloneSurface,
+    }),
+  ],
+};
+
+export default hypitPackage;

package/packages/fishaudio-speech/src/fragment.ts

@@ -0,0 +1,11 @@
+import { createExactModelPrimaryGenerationFragment } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput, ExactModelTextInput } from "@hypit/model-kit";
+
+/** Model result projection over the same graph-native request assembly as every exact model. */
+export function createFishAudioSpeechAudioFragment(
+  endpoint: ExactModelEndpoint,
+  mediaInputs: readonly ExactModelMediaInput[] = [],
+  textInputs: readonly ExactModelTextInput[] = [],
+) {
+  return createExactModelPrimaryGenerationFragment(endpoint, mediaInputs, textInputs);
+}

package/packages/fishaudio-speech/src/index.ts

@@ -0,0 +1,156 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationRequestDraft, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const fishAudioSpeechModuleRef = { name: "@hypit/fishaudio-speech", version: "1" } as const;
+export const fishAudioSpeechModels = [
+  "voice-design-1",
+  "voice-clone",
+] as const;
+export type FishAudioSpeechModel = typeof fishAudioSpeechModels[number];
+
+// Fish Audio documents no fixed character ceiling. Service-side limits stay service-side
+// instead of becoming an invented model constraint in Author Source.
+const spokenText = { kind: "text" } as const;
+const voiceDescription = { kind: "text" } as const;
+
+function table(model: FishAudioSpeechModel): GenerationPortTable {
+  if (model === "voice-design-1") {
+    return sealGenerationPortTable({
+      model,
+      result: "audio",
+      ports: [
+        { name: "text", value: spokenText, minItems: 1, maxItems: 1 },
+        { name: "voiceDescription", value: voiceDescription, minItems: 1, maxItems: 1 },
+      ],
+      requires: [],
+    });
+  }
+  return sealGenerationPortTable({
+    model,
+    result: "audio",
+    ports: [
+      { name: "text", value: spokenText, minItems: 1, maxItems: 1 },
+      { name: "voiceReference", value: { kind: "media", accepts: ["audio"] }, minItems: 1, maxItems: 1 },
+    ],
+    requires: [],
+  });
+}
+
+export const fishAudioSpeechPorts: Readonly<Record<FishAudioSpeechModel, GenerationPortTable>> = {
+  "voice-design-1": table("voice-design-1"),
+  "voice-clone": table("voice-clone"),
+};
+
+export function sealFishAudioSpeechRequest(
+  model: FishAudioSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(fishAudioSpeechPorts[model], ports);
+}
+
+export function sealFishAudioSpeechRequestDraft(
+  model: FishAudioSpeechModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+) {
+  return sealGenerationRequestDraft(fishAudioSpeechPorts[model], ports);
+}
+
+const base = defineExactModelModule({
+  module: fishAudioSpeechModuleRef,
+  endpoints: ([
+    ["voiceDesign", "voice-design-1", "FishAudioVoiceDesignRequest"],
+    ["voiceClone", "voice-clone", "FishAudioVoiceCloneRequest"],
+  ] as const).map(([key, model, requestTypeName]) => ({
+    key,
+    requestTypeName,
+    producerName: `request-${model}`,
+    ports: fishAudioSpeechPorts[model],
+  })),
+});
+
+export const fishAudioSpeechEndpoints = base.endpoints;
+
+const spokenAttributes: readonly SurfaceAttributeVocabulary[] = [
+  {
+    name: "id",
+    kind: "identifier",
+    required: true,
+    summary: "Names this speech request and prefixes the binding it publishes.",
+  },
+  {
+    name: "speech",
+    kind: "reference",
+    required: true,
+    summary: "The Text edge whose exact words are spoken.",
+    accepts: [textTypes.text],
+  },
+];
+
+const referencePort: readonly SurfacePortVocabulary[] = [{
+  name: "reference",
+  type: artifactTypes.blob,
+  summary: "The designed voice reference, addressed as `<id>.reference`.",
+}];
+
+const audioPort: readonly SurfacePortVocabulary[] = [{
+  name: "audio",
+  type: artifactTypes.blob,
+  summary: "The independent speech, addressed as `<id>.audio`.",
+}];
+
+export const fishAudioSpeechMarkupSurfaces = [
+  {
+    name: "voiceDesign", tag: "VoiceDesign", mode: "structured",
+    outputs: [fishAudioSpeechEndpoints.voiceDesign.draftType],
+    vocabulary: {
+      summary: "Creates a reusable voice reference from a natural-language voice description.",
+      attributes: spokenAttributes,
+      ports: referencePort,
+      text: "The element's own text is the voice description and is required.",
+      example: `<fish:VoiceDesign id="host" speech={story.segment.voiceSample.speech}>
+  A clear young woman with a grounded, confident conversational delivery.
+</fish:VoiceDesign>`,
+      notes: [
+        "The element accepts no child elements; only its text is read.",
+        "The result is an ordinary audio Resource that can be supplied anywhere an audio reference is accepted.",
+      ],
+    },
+  },
+  {
+    name: "voiceClone", tag: "VoiceClone", mode: "structured",
+    outputs: [
+      fishAudioSpeechEndpoints.voiceClone.draftType,
+      ...Object.values(fishAudioSpeechEndpoints.voiceClone.mediaBindings).map((binding) => binding.type),
+    ],
+    vocabulary: {
+      summary: "Creates independent speech in the voice heard in one accepted audio reference.",
+      attributes: [
+        ...spokenAttributes,
+        {
+          name: "voice",
+          kind: "reference",
+          required: true,
+          summary: "The audio Resource carrying the voice identity to reproduce.",
+          accepts: [artifactTypes.blob],
+        },
+      ],
+      ports: audioPort,
+      example: `<fish:VoiceClone id="narration" speech={story.segment.reveal.speech} voice={host.reference}/>`,
+      notes: [
+        "The element takes its spoken words from speech and voice identity from voice; it has no body input.",
+        "The voice reference remains a normal audio Resource rather than a separate identity record.",
+      ],
+    },
+  },
+] as const;
+
+export const fishAudioSpeechManifest = { ...base.manifest } as const;
+export const fishAudioSpeechComponent = base.component;
+export const fishAudioSpeechDefinition = { ...base, manifest: fishAudioSpeechManifest };
+
+export { createFishAudioSpeechAudioFragment } from "./fragment.js";
+export { decodeFishAudioVoiceCloneSurface, decodeFishAudioVoiceDesignSurface } from "./surface.js";

package/packages/fishaudio-speech/src/surface.ts

@@ -0,0 +1,192 @@
+import { artifactTypes } from "@hypit/artifact";
+import { generationPort, sealGenerationMediaBinding } from "@hypit/generation";
+import type { GenerationMediaPort } from "@hypit/generation";
+import { exactModelMediaInputNames, exactModelTextInputName } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput, ExactModelTextInput } from "@hypit/model-kit";
+import type { CanonicalValue } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+
+import { createFishAudioSpeechAudioFragment } from "./fragment.js";
+import { fishAudioSpeechEndpoints, sealFishAudioSpeechRequestDraft } from "./index.js";
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function attributes(element: StructuredElement, required: readonly string[]): void {
+  const allowed = new Set(required);
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.has(name));
+  if (unknown.length > 0 || required.some((name) => element.attributes[name] === undefined)) {
+    throw new Error(`${element.name} requires ${required.join(", ")}`);
+  }
+}
+
+function stringAttribute(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${element.name}.${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function referencePath(element: StructuredElement, name: string): string {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference" || value.path.length === 0) {
+    throw new Error(`${element.name}.${name} must be a whole-value reference`);
+  }
+  return value.path;
+}
+
+function resolved(
+  element: StructuredElement,
+  name: string,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const path = referencePath(element, name);
+  const value = resolveReference(path);
+  if (value === undefined) throw new Error(`${element.name}.${name} cannot resolve ${path}`);
+  return value;
+}
+
+function speechText(reference: SurfaceResolvedReference, subject: string): SurfaceResolvedReference {
+  if (!sameType(reference.type, textTypes.text)) throw new Error(`${subject} must reference Text`);
+  const value = reference.record?.value;
+  if (value !== undefined) {
+    if (value.kind !== "inline") throw new Error(`${subject} has an invalid authored Text value`);
+    verifyText(value.value);
+  }
+  return reference;
+}
+
+function voiceReference(reference: SurfaceResolvedReference, subject: string): SurfaceResolvedReference {
+  if (!sameType(reference.type, artifactTypes.blob)) throw new Error(`${subject} must reference an audio Resource`);
+  const value = reference.record?.value;
+  if (value !== undefined && (value.kind !== "blob" || !value.mediaType.startsWith("audio/"))) {
+    throw new Error(`${subject} must reference audio media`);
+  }
+  return reference;
+}
+
+function body(element: StructuredElement): string {
+  if (element.children.some((child) => child.kind === "element")) {
+    throw new Error(`${element.name} accepts instruction text only`);
+  }
+  const lines = element.children.map((child) => child.kind === "text" ? child.value : "").join("")
+    .replaceAll("\r\n", "\n").split("\n");
+  while (lines[0]?.trim() === "") lines.shift();
+  while (lines.at(-1)?.trim() === "") lines.pop();
+  const indents = lines.filter((line) => line.trim()).map((line) => /^\s*/u.exec(line)?.[0].length ?? 0);
+  const indent = indents.length === 0 ? 0 : Math.min(...indents);
+  const value = lines.map((line) => line.slice(indent).trimEnd()).join("\n").trim();
+  if (value.length === 0) {
+    throw new Error(`${element.name} requires a voice description in its body`);
+  }
+  return value;
+}
+
+function output(
+  element: StructuredElement,
+  endpoint: ExactModelEndpoint,
+  draft: ReturnType<typeof sealFishAudioSpeechRequestDraft>,
+  outputName: "reference" | "audio",
+  text: readonly { readonly input: ExactModelTextInput; readonly source: SurfaceResolvedReference }[],
+  media: readonly { readonly input: ExactModelMediaInput; readonly source: SurfaceResolvedReference }[] = [],
+) {
+  const id = stringAttribute(element, "id");
+  const draftId = `${id}.draft`;
+  const records: Array<{
+    readonly id: string;
+    readonly type: SurfaceResolvedReference["type"];
+    readonly value: { readonly kind: "inline"; readonly value: CanonicalValue };
+    readonly range: StructuredElement["range"];
+  }> = [{
+    id: draftId,
+    type: endpoint.draftType,
+    value: { kind: "inline", value: draft as unknown as CanonicalValue },
+    range: element.range,
+  }];
+  const inputs: Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }> = {
+    draft: { kind: "record", id: draftId },
+  };
+  for (const item of text) inputs[exactModelTextInputName(item.input.name)] = item.source.ref;
+  for (const item of media) {
+    const binding = endpoint.mediaBindings[item.input.port];
+    if (binding === undefined) throw new Error(`${endpoint.ports.model} has no media port ${item.input.port}`);
+    const port = generationPort(endpoint.ports, item.input.port);
+    if (port.value.kind !== "media") throw new Error(`${endpoint.ports.model} port ${item.input.port} is not media`);
+    const names = exactModelMediaInputNames(item.input.name);
+    const bindingId = `${id}.${item.input.name}.binding`;
+    records.push({
+      id: bindingId,
+      type: binding.type,
+      value: {
+        kind: "inline",
+        value: sealGenerationMediaBinding(port as GenerationMediaPort, { role: "audio" }) as unknown as CanonicalValue,
+      },
+      range: element.range,
+    });
+    inputs[names.binding] = { kind: "record", id: bindingId };
+    inputs[names.artifact] = item.source.ref;
+  }
+  const fragment = createFishAudioSpeechAudioFragment(
+    endpoint,
+    media.map((item) => item.input),
+    text.map((item) => item.input),
+  );
+  return {
+    records,
+    components: [{
+      id,
+      fragment: fragment.id,
+      inputs,
+      outputs: { audio: `${id}.${outputName}` },
+      range: element.range,
+    }],
+    fragments: [fragment],
+  };
+}
+
+function speechInput(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+) {
+  return {
+    input: { name: "speech", port: "text" },
+    source: speechText(resolved(element, "speech", resolveReference), `${element.name}.speech`),
+  } as const;
+}
+
+export const decodeFishAudioVoiceDesignSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "speech"]);
+  return output(
+    element,
+    fishAudioSpeechEndpoints.voiceDesign,
+    sealFishAudioSpeechRequestDraft("voice-design-1", { voiceDescription: [body(element)] }),
+    "reference",
+    [speechInput(element, resolveReference)],
+  );
+};
+
+export const decodeFishAudioVoiceCloneSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "speech", "voice"]);
+  if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
+    throw new Error(`${element.name} accepts speech and voice references, with no body input`);
+  }
+  return output(
+    element,
+    fishAudioSpeechEndpoints.voiceClone,
+    sealFishAudioSpeechRequestDraft("voice-clone", {}),
+    "audio",
+    [speechInput(element, resolveReference)],
+    [{
+      input: { name: "voice", port: "voiceReference" },
+      source: voiceReference(resolved(element, "voice", resolveReference), `${element.name}.voice`),
+    }],
+  );
+};

package/packages/fonts-open/README.md

@@ -1,5 +1,10 @@
 # `@hypit/fonts-open`
 
+The optional `@hypit/fonts-open/studio` export supplies data-only catalog choices for Companions.
+`openFontStudioFields(owner)` returns the explicit nested font binding and Inspector fields for a
+Style reference such as `program` or `style`. It edits the referenced catalog face's family, keeping
+its authored weight, style and fallback faces. Ordinary font validation still applies.
+
 Workspace package exposing 109 redistributable open font families as exact,
 Resource-backed `FontArtifactRef` values. The installed packages carry their font bytes and license
 files. Author compilation and rendering never download fonts or inspect system font directories.

package/packages/fonts-open/package.json

@@ -5,7 +5,8 @@
   "private": true,
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./studio": "./src/studio.ts"
   },
   "hypit": {
     "activation": "./src/activation.ts"
@@ -126,5 +127,8 @@
     "@hypit/package-loader-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/markup": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/studio-adapter": "workspace:*"
   }
 }

package/packages/fonts-open/src/studio.ts

@@ -0,0 +1,21 @@
+import type { StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
+import { openFontFamilies } from "./catalog.js";
+
+/** Optional Companion declarations for the primary catalog face reached through a Style's font. */
+export function openFontStudioFields(owner: string): {
+  readonly binding: StudioSourceBindingDeclaration;
+  readonly fields: readonly StudioInspectorFieldDeclaration[];
+} {
+  return {
+    binding: { name: "font", referenced: [{ name: "family", writable: true }] },
+    fields: [{
+      binding: `${owner}.font.family`, label: "Font Family", domain: "how",
+      page: { id: "font", label: "Font" }, section: { id: "face", label: "Primary Face" },
+      summary: "Changes the shared catalog face. Its authored weight and style must be available in the selected family.",
+      control: "select",
+      options: Object.entries(openFontFamilies).map(([value, family]) => ({
+        value, label: family.label, description: `${family.category} · ${family.intendedUse}`,
+      })),
+    }],
+  };
+}

package/packages/generation/README.md

@@ -15,5 +15,15 @@ schemas, validators and graph facets. Generated sets are atomic Products: a Prov
 returned bytes in an ResourceStore and returns typed Blob references rather than transient URLs.
 
 This package does not choose a model, Provider, credential, queue or retry policy. Model packages
-declare exact request Capabilities; Endpoint packages such as `@hypit/provider-kie` implement those
+declare exact request Capabilities; selected Endpoint packages implement those
 Capabilities in a selected Runtime Profile.
+
+## Reference fields in resource transport
+
+A service may consume per-media metadata while preparing a URL rather than in its generation JSON.
+Media wire mappings (`url`, `urlArray`, `itemObject`) may declare `resourceFields: ["fieldName"]`.
+`compileWireRequest` supplies those present item fields as the second argument to its URL resolver;
+`itemObject.fieldKeys` separately maps fields into the generation body. Port coverage checks both
+paths against the declared media fields. False, zero and empty strings remain values; omitted fields
+remain absent. The resolver implements the service protocol; this package knows no particular
+service or classification. Providers using custom transports carry those fields through that boundary.