@hypit/hypit 0.0.1 → 0.1.1

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

@@ -0,0 +1,102 @@
+import type { ModuleManifest, TypeRef, ValueSchema } from "@hypit/protocol";
+
+/** Exact boundaries in the fixed 16 kHz Speech Evidence Audio sample domain. */
+export type SpeechWordEvidence = {
+  readonly text: string;
+  readonly startSample?: number;
+  readonly endSampleExclusive?: number;
+  readonly score?: number;
+};
+
+export type SpeechCharacterEvidence = {
+  readonly char: string;
+  /** Index into the containing passage's words. */
+  readonly wordIndex: number;
+  readonly startSample?: number;
+  readonly endSampleExclusive?: number;
+  readonly score?: number;
+};
+
+export type SpeechActivitySpan = {
+  readonly startSample: number;
+  readonly endSampleExclusive: number;
+};
+
+/**
+ * One acoustic passage reported by the evidence provider. It deliberately has
+ * no authored Segment identity; assigning evidence to the explicitly connected
+ * Script Segment belongs to the later deterministic Speech Alignment step.
+ */
+export type SpeechTranscriptPassage = {
+  readonly startSample?: number;
+  readonly endSampleExclusive?: number;
+  readonly words: readonly SpeechWordEvidence[];
+  readonly chars: readonly SpeechCharacterEvidence[];
+  readonly speechActivity?: readonly SpeechActivitySpan[];
+};
+
+export type AlignedTranscriptEvidence = {
+  readonly passages: readonly SpeechTranscriptPassage[];
+};
+
+const sample = { kind: "number", integer: true, minimum: 0 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const score = { kind: "number", minimum: 0, maximum: 1 } as const;
+const object = (
+  fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>,
+): ValueSchema => ({ kind: "object", fields });
+
+const word = object({
+  text: { schema: { kind: "string" } },
+  startSample: { schema: sample, optional: true },
+  endSampleExclusive: { schema: sample, optional: true },
+  score: { schema: score, optional: true },
+});
+const char = object({
+  char: { schema: { kind: "string" } },
+  wordIndex: { schema: integer },
+  startSample: { schema: sample, optional: true },
+  endSampleExclusive: { schema: sample, optional: true },
+  score: { schema: score, optional: true },
+});
+const activity = object({
+  startSample: { schema: sample },
+  endSampleExclusive: { schema: sample },
+});
+
+export const alignedTranscriptEvidenceFields = {
+  passages: {
+    schema: {
+      kind: "array",
+      items: object({
+        startSample: { schema: sample, optional: true },
+        endSampleExclusive: { schema: sample, optional: true },
+        words: { schema: { kind: "array", items: word } },
+        chars: { schema: { kind: "array", items: char } },
+        speechActivity: { schema: { kind: "array", items: activity }, optional: true },
+      }),
+    },
+  },
+} as const satisfies Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>;
+
+export const alignedTranscriptEvidenceSchema: ValueSchema = object(alignedTranscriptEvidenceFields);
+export const speechEvidenceModuleRef = { name: "@hypit/speech-evidence", version: "1" } as const;
+export const speechEvidenceTypes = {
+  alignedTranscript: { module: speechEvidenceModuleRef, name: "AlignedTranscriptEvidence" },
+} satisfies Record<string, TypeRef>;
+export const speechEvidenceManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: speechEvidenceModuleRef.name,
+  version: speechEvidenceModuleRef.version,
+  dependencies: [],
+  types: [{ name: speechEvidenceTypes.alignedTranscript.name }],
+  capabilities: [],
+  producers: [],
+};
+export const speechEvidenceDependency = {
+  module: speechEvidenceModuleRef,
+} as const;
+
+export function sealAlignedTranscriptEvidence(value: AlignedTranscriptEvidence): AlignedTranscriptEvidence {
+  return structuredClone(value);
+}

package/packages/speech-track/README.md

@@ -0,0 +1,51 @@
+# `@hypit/speech-track`
+
+Assemble ordered SemanticTakes into a semantic timeline and its original sound. The performance
+carrying the Script is the A-roll, whether its picture fills the screen, appears in an inset,
+is a transparent cutout, or is covered by other pictures. This role establishes time; the visual
+composition decides where and how that material appears.
+
+```svml
+<speech:Track id="speech">
+  <speech:Take source={opening.take}/>
+  <speech:Take source={answer.take}/>
+</speech:Track>
+```
+
+The Takes are already normalized and semantic. Source order and actual prepared lengths establish
+the shared ProgramSpace. Local word positions and Segment boundaries become global positions.
+One Take may contain several speakers or camera cuts; a wordless Take supplies its media boundaries.
+
+| Output | Use |
+| --- | --- |
+| `.semantic` | Semantic time and prepared materials for Film, Caption, Media and project components |
+| `.audio` | Original performance sound at its assembled positions |
+
+Select `.audio` in Film when that sound belongs in the result. This explicit convenience projection
+keeps the prepared source at its original speed and gain; a Take without audio contributes no clip.
+For independent music, effects or authored mixing choices, use [Audio Track](../audio-track/README.md).
+
+## Present the performance
+
+[Media Track](../media-track/README.md#display-a-semantic-performance) can consume the assembled
+performance through a Media Performance:
+
+```svml
+<media:Track id="performance" semantic={speech.semantic} canvas={canvas}>
+  <media:Performance during="program" frame={layout.full}
+    appearance={look.performance}/>
+</media:Track>
+```
+
+Include `performance.visual` and `speech.audio` in Film. The Media Recipe supplies `stack-order`,
+fit, clipping, rounded corners, border and other presentation choices. A selected window that starts
+inside a Take begins at the matching source frame. Presentation continues across Take boundaries.
+
+A project component can also consume `.semantic` and use `projectSemanticMedia` from
+`@hypit/hypit/semantic-track` to obtain selected material spans and their source positions. When video and
+graphics share layout or motion, that component can own both in one visual program. Independent
+Caption or other overlays can remain separate Tracks.
+
+[Media Pipeline](../media-pipeline/README.md) owns preparation;
+[Semantic Track](../semantic-track/README.md) owns the timeline and its projections.
+The [Studio Companion](../speech-track-studio/src/index.ts) exposes the original audio clips.

package/packages/speech-track/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hypit/speech-track",
+  "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/component-kit": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/speech": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/core": "workspace:*",
+    "@hypit/script": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/validation": "workspace:*"
+  }
+}

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

@@ -0,0 +1,19 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+  decodeSpeechTrackSurface, speechTrackComponent, speechTrackManifest,
+  speechTrackModuleRef,
+  speechTrackMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{
+    manifest: speechTrackManifest,
+  }],
+  components: [speechTrackComponent],
+  hostFacets: [createMarkupSurfaceHostFacet({
+    module: speechTrackModuleRef,
+    declaration: speechTrackMarkupSurfaces.find((item) => item.name === "track")!, handler: decodeSpeechTrackSurface,
+  })],
+};
+export default hypitPackage;

package/packages/speech-track/src/component.ts

@@ -0,0 +1,45 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+import type { SemanticTake } from "@hypit/speech";
+
+import { speechTrackProducers } from "./manifest.js";
+import { appendSpeechTrackTake, assembleSpeechTrack, createSpeechTrackSet } from "./program.js";
+import type { SpeechTrackHeader, SpeechTrackSet } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, subject: string): T {
+  if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
+  return value.value as unknown as T;
+}
+
+export const speechTrackComponent = {
+  producers: [
+    {
+      producer: speechTrackProducers.createSet,
+      handler: () => ({
+        outputs: { set: { kind: "inline", value: canonicalize(createSpeechTrackSet()) } },
+        needs: {},
+      }),
+    },
+    {
+      producer: speechTrackProducers.appendTake,
+      handler: ({ inputs }) => ({
+        outputs: { set: { kind: "inline", value: canonicalize(appendSpeechTrackTake(
+          inline<SpeechTrackSet>(inputs.set?.value, "SpeechTrackSet"),
+          inline<SemanticTake>(inputs.take?.value, "SemanticTake"),
+        )) } },
+        needs: {},
+      }),
+    },
+    {
+      producer: speechTrackProducers.assembleTrack,
+      handler: ({ inputs }) => ({
+        outputs: { track: { kind: "inline", value: canonicalize(assembleSpeechTrack(
+          inline<SpeechTrackHeader>(inputs.header?.value, "SpeechTrackHeader"),
+          inline<SpeechTrackSet>(inputs.set?.value, "SpeechTrackSet"),
+        )) } },
+        needs: {},
+      }),
+    },
+  ],
+} satisfies ComponentPackage;

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

@@ -0,0 +1,74 @@
+import { speechTypes } from "@hypit/speech";
+import { compositionTypes } from "@hypit/composition";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation } from "@hypit/elaborator";
+import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
+import type { TypeRef } from "@hypit/protocol";
+
+import { speechTrackProducers, speechTrackTypes } from "./manifest.js";
+import type { SpeechTrackFragmentOptions } from "./types.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export function createSpeechTrackFragment(options: SpeechTrackFragmentOptions) {
+  if (options.takes.length === 0) throw new Error("Speech Track requires at least one Take");
+  const declaredInputs = new Map<string, TypeRef>();
+  const addInput = (name: string, type: TypeRef): void => {
+    if (!name) throw new Error("Speech Track Fragment input names must not be empty");
+    const previous = declaredInputs.get(name);
+    if (previous !== undefined && (previous.module.name !== type.module.name
+      || previous.module.version !== type.module.version || previous.name !== type.name)) {
+      throw new Error(`Speech Track Fragment input ${name} is reused with another Type`);
+    }
+    declaredInputs.set(name, type);
+  };
+  addInput("header", speechTrackTypes.header);
+  for (const take of options.takes) {
+    addInput(take.takeName, speechTypes.semanticTake);
+  }
+  const operations: FragmentOperation[] = [{
+    id: "track:set:empty",
+    producer: speechTrackProducers.createSet,
+    inputs: {},
+    result: { kind: "output", name: "set" },
+  }];
+  let current = "track:set:empty";
+  options.takes.forEach((take, index) => {
+    const id = `track:set:append:${String(index + 1).padStart(4, "0")}`;
+    operations.push({
+      id,
+      producer: speechTrackProducers.appendTake,
+      inputs: {
+        set: operation(current),
+        take: input(take.takeName),
+      },
+      result: { kind: "output", name: "set" },
+    });
+    current = id;
+  });
+  operations.push(
+    {
+      id: "track:semantic",
+      producer: speechTrackProducers.assembleTrack,
+      inputs: { header: input("header"), set: operation(current) },
+      result: { kind: "output", name: "track" },
+    },
+    {
+      id: "track:audio-track",
+      producer: semanticTrackProducers.projectAudio,
+      inputs: { track: operation("track:semantic") },
+      result: { kind: "output", name: "audio" },
+    },
+  );
+  return sealGraphFragment({
+    inputs: [...declaredInputs.entries()].map(([name, type]) => ({ name, type })),
+    operations,
+    exports: [
+      { name: "semantic", type: semanticTrackTypes.track, root: operation("track:semantic") },
+      {
+        name: "audio", type: compositionTypes.audioTrack, root: operation("track:audio-track"),
+      },
+    ],
+  });
+}

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

@@ -0,0 +1,7 @@
+/** Official Speech Track authoring and deterministic SemanticTrack assembly. */
+export { speechTrackComponent } from "./component.js";
+export { createSpeechTrackFragment } from "./fragment.js";
+export { speechTrackManifest, speechTrackMarkupSurfaces, speechTrackModuleRef, speechTrackProducers, speechTrackTypes, speechTrackHeaderSchema, speechTrackSetSchema } from "./manifest.js";
+export { appendSpeechTrackTake, assembleSpeechTrack, assertSpeechTrackHeader, assertSpeechTrackSet, createSpeechTrackSet, sealSpeechTrackHeader } from "./program.js";
+export { decodeSpeechTrackSurface } from "./surface.js";
+export type * from "./types.js";

package/packages/speech-track/src/manifest.ts

@@ -0,0 +1,73 @@
+import { semanticTakeSchema, speechDependency, speechTypes } from "@hypit/speech";
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import type { ModuleManifest, ValueSchema } from "@hypit/protocol";
+export const speechTrackModuleRef = { name: "@hypit/speech-track", version: "1" } as const;
+export const speechTrackTypes = {
+  header: { module: speechTrackModuleRef, name: "SpeechTrackHeader" },
+  trackSet: { module: speechTrackModuleRef, name: "SpeechTrackSet" },
+} as const;
+export const speechTrackProducers = {
+  createSet: { module: speechTrackModuleRef, name: "create-track-set" },
+  appendTake: { module: speechTrackModuleRef, name: "append-track-take" },
+  assembleTrack: { module: speechTrackModuleRef, name: "assemble-semantic-track" },
+} as const;
+export const speechTrackHeaderSchema: ValueSchema = { kind: "object", fields: { id: { schema: { kind: "string", minLength: 1 } } } };
+export const speechTrackSetSchema: ValueSchema = { kind: "object", fields: { takes: { schema: { kind: "array", items: { kind: "object", fields: { semantic: { schema: semanticTakeSchema } } } } } } };
+export const speechTrackMarkupSurfaces = [{
+  name: "track", tag: "Track", mode: "structured",
+  outputs: [speechTrackTypes.header, semanticTrackTypes.track, compositionTypes.audioTrack],
+  vocabulary: {
+    summary: "Assembles ordered SemanticTakes into one semantic timeline and its original performance audio.",
+    attributes: [{ name: "id", kind: "identifier", required: true, summary: "Names the semantic assembly and its outputs." }],
+    children: [{ tag: "Take", cardinality: "many", summary: "A prepared SemanticTake in performance order.",
+      attributes: [{ name: "source", kind: "reference", required: true, accepts: [speechTypes.semanticTake], summary: "The normalized, aligned performance." }] }],
+    ports: [
+      { name: "semantic", type: semanticTrackTypes.track, summary: "The semantic timeline, retaining its prepared material." },
+      { name: "audio", type: compositionTypes.audioTrack, summary: "Original performance audio aligned to that timeline; select it explicitly in Film." },
+    ],
+    example: '<speech:Track id="speech"><speech:Take source={opening.take}/><speech:Take source={answer.take}/></speech:Track>',
+    notes: ["Use Media or a project visual component to present the performance. Those components choose placement and motion independently of semantic assembly."],
+  },
+}] as const;
+export const speechTrackManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: speechTrackModuleRef.name,
+  version: speechTrackModuleRef.version,
+  dependencies: [
+    speechDependency,
+    compositionDependency,
+    semanticTrackDependency,
+  ],
+  types: [
+    { name: speechTrackTypes.header.name },
+    { name: speechTrackTypes.trackSet.name },
+  ],
+  capabilities: [],
+  producers: [
+    {
+      name: speechTrackProducers.createSet.name,
+      inputs: [],
+      outputs: [{ name: "set", type: speechTrackTypes.trackSet }],
+      needs: [],
+    },
+    {
+      name: speechTrackProducers.appendTake.name,
+      inputs: [
+        { name: "set", type: speechTrackTypes.trackSet },
+        { name: "take", type: speechTypes.semanticTake },
+      ],
+      outputs: [{ name: "set", type: speechTrackTypes.trackSet }],
+      needs: [],
+    },
+    {
+      name: speechTrackProducers.assembleTrack.name,
+      inputs: [
+        { name: "header", type: speechTrackTypes.header },
+        { name: "set", type: speechTrackTypes.trackSet },
+      ],
+      outputs: [{ name: "track", type: semanticTrackTypes.track }],
+      needs: [],
+    },
+  ],
+};

package/packages/speech-track/src/program.ts

@@ -0,0 +1,64 @@
+import { assertSemanticTakeIdentity } from "@hypit/speech";
+import type { SemanticTake } from "@hypit/speech";
+import { sealSemanticTrack } from "@hypit/semantic-track";
+import type { SemanticTrack } from "@hypit/semantic-track";
+import type { SpeechTrackHeader, SpeechTrackSet, SpeechTrackTake } from "./types.js";
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+export function sealSpeechTrackHeader(value: SpeechTrackHeader): SpeechTrackHeader { return { id: value.id }; }
+export function assertSpeechTrackHeader(value: SpeechTrackHeader): void {
+  assert(value.id.trim().length > 0, "SpeechTrackHeader id must not be empty");
+}
+function sealSpeechTrackSet(value: SpeechTrackSet): SpeechTrackSet { return structuredClone(value); }
+function assertTake(take: SpeechTrackTake): void { assertSemanticTakeIdentity(take.semantic); }
+export function assertSpeechTrackSet(value: SpeechTrackSet): void {
+  const segments = new Set<string>();
+  for (const take of value.takes) {
+    assertSemanticTakeIdentity(take.semantic);
+    const segmentId = take.semantic.segment.segmentId;
+    assert(!segments.has(segmentId), `Speech Track repeats Segment ${segmentId}`);
+    segments.add(segmentId);
+  }
+}
+
+export function createSpeechTrackSet(): SpeechTrackSet {
+  return sealSpeechTrackSet({
+    takes: [],
+  });
+}
+
+function appendTake(
+  set: SpeechTrackSet,
+  take: SpeechTrackTake,
+): SpeechTrackSet {
+  assertSpeechTrackSet(set);
+  assertTake(take);
+  assert(!set.takes.some((item) => item.semantic.segment.segmentId === take.semantic.segment.segmentId),
+    `Speech Track repeats Segment ${take.semantic.segment.segmentId}`);
+  return sealSpeechTrackSet({
+    takes: [...set.takes, take],
+  });
+}
+
+export function appendSpeechTrackTake(set: SpeechTrackSet, semantic: SemanticTake): SpeechTrackSet {
+  return appendTake(set, { semantic });
+}
+
+export function assembleSpeechTrack(
+  header: SpeechTrackHeader,
+  set: SpeechTrackSet,
+): SemanticTrack {
+  assertSpeechTrackHeader(header);
+  assertSpeechTrackSet(set);
+  assert(set.takes.length > 0, "Speech Track must contain at least one Take");
+  for (const take of set.takes) assertTake(take);
+  const narrativeId = set.takes[0]!.semantic.narrativeId;
+  assert(set.takes.every((take) => take.semantic.narrativeId === narrativeId),
+    "Speech Track cannot mix Takes from different Narratives");
+  return sealSemanticTrack({
+    id: header.id,
+    narrativeId,
+    items: set.takes.map((item) => ({ take: item.semantic })),
+  });
+}

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

@@ -0,0 +1,35 @@
+import { assertAttributes, assertEmptyElement, localName, textAttribute, type StructuredSurfaceHandler } from "@hypit/markup";
+import { sameType } from "@hypit/protocol";
+import { speechTypes } from "@hypit/speech";
+import { createSpeechTrackFragment } from "./fragment.js";
+import { speechTrackTypes } from "./manifest.js";
+
+export const decodeSpeechTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id"]);
+  const id = textAttribute(element, "id");
+  const takes = element.children.flatMap(child => {
+    if (child.kind === "text") {
+      if (child.value.trim()) throw new Error("Speech Track accepts only Take children.");
+      return [];
+    }
+    if (localName(child.name) !== "Take") throw new Error("Speech Track accepts only Take children.");
+    assertAttributes(child, ["source"]);
+    assertEmptyElement(child);
+    const source = child.attributes.source;
+    if (typeof source !== "object" || source.kind !== "reference") throw new Error("Speech Take source must be a reference.");
+    const resolved = resolveReference(source.path);
+    if (resolved === undefined || !sameType(resolved.type, speechTypes.semanticTake)) throw new Error("Speech Take source must be a SemanticTake.");
+    return [resolved];
+  });
+  const inputs = takes.map((_, index) => ({ takeName: `take-${index + 1}` }));
+  const fragment = createSpeechTrackFragment({ takes: inputs });
+  return {
+    records: [{ id: `${id}.header`, type: speechTrackTypes.header, value: { kind: "inline", value: { id } }, range: element.range }],
+    fragments: [fragment],
+    components: [{ id, fragment: fragment.id, inputs: {
+      header: { kind: "record", id: `${id}.header` },
+      ...Object.fromEntries(takes.map((take, index) => [inputs[index]!.takeName, take.ref])),
+    }, outputs: { semantic: `${id}.semantic`, audio: `${id}.audio` }, range: element.range }],
+    exports: [`${id}.semantic`, `${id}.audio`],
+  };
+};

package/packages/speech-track/src/types.ts

@@ -0,0 +1,6 @@
+import type { SemanticTake } from "@hypit/speech";
+export type SpeechTrackHeader = { readonly id: string };
+export type SpeechTrackTake = { readonly semantic: SemanticTake };
+export type SpeechTrackSet = { readonly takes: readonly SpeechTrackTake[] };
+export type SpeechTrackInput = { readonly takeName: string };
+export type SpeechTrackFragmentOptions = { readonly takes: readonly SpeechTrackInput[] };

package/packages/speech-track-studio/README.md

@@ -0,0 +1,3 @@
+# `@hypit/speech-track-studio`
+
+Hypit Studio Companion for the original audio projection of `@hypit/speech-track`.

package/packages/speech-track-studio/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@hypit/speech-track-studio",
+  "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/speech-track": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*"
+  }
+}

package/packages/speech-track-studio/src/activation.ts

@@ -0,0 +1,7 @@
+import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
+import { speechTrackStudioTrackCompanions } from "./index.js";
+
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createStudioTrackCompanionHostFacet(speechTrackStudioTrackCompanions)],
+};

package/packages/speech-track-studio/src/index.ts

@@ -0,0 +1,40 @@
+import { speechTrackModuleRef } from "@hypit/speech-track";
+import { compositionTypes } from "@hypit/composition";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
+import { artifactPreview, previewLayer } from "@hypit/studio-adapter";
+type SpeechAudioTrack = {
+  readonly clips?: readonly {
+    readonly id: string;
+    readonly subjectId?: string;
+    readonly artifact?: { readonly resource?: string };
+  }[];
+};
+
+function projectSpeechAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const clips = new Map(((context.track.value as SpeechAudioTrack).clips ?? [])
+    .map((clip) => [clip.id, clip] as const));
+  return context.generic().map((entity) => {
+    const id = entity.presentId ?? entity.authoredId;
+    const clip = clips.get(id);
+    const subjectId = clip?.subjectId;
+    return {
+      ...entity,
+      authoredId: subjectId ?? id,
+      display: {
+        title: subjectId ?? entity.authoredId,
+        layers: clip?.artifact?.resource === undefined ? [] : [previewLayer(artifactPreview("audio", clip.artifact.resource), "waveform")],
+      },
+      presentation: { entity: "audio-clip", chrome: "standard" },
+    };
+  });
+}
+
+export const speechTrackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+  {
+    id: "audio", role: "track",
+    output: { type: compositionTypes.audioTrack, surface: "track", modules: [speechTrackModuleRef] },
+    family: "speech-audio", tone: "green", label: "Speech Audio", icon: "waveform",
+    bindings: [], inspector: [], project: projectSpeechAudio,
+    lane: { heightPx: 48 },
+  },
+];

package/packages/store-sqlite/README.md

@@ -0,0 +1,14 @@
+# `@hypit/store-sqlite`
+
+Private durable state used by `@hypit/runtime-local`.
+
+One SQLite file stores Build facts, external Operations, the active Build work set, capacity reservations
+a small output catalog, resource waiters and action rate budgets. No ready-command queue is stored: Core derives ready work from the saved
+Build facts whenever the Worker advances it.
+
+Operation receipts retain task IDs, original Need identity and credential references until the Result
+has recorded them. Unknown remote outcomes do not keep a failed Build active.
+
+Artifact bytes and secret credential values never enter this database. Components and Endpoint packages do not import
+SQLite. `SqliteRuntimeState` exposes the narrow stores needed by the local Runtime and owns their shared
+connection.

package/packages/store-sqlite/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@hypit/store-sqlite",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/core": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*"
+  }
+}

package/packages/store-sqlite/src/index.ts

@@ -0,0 +1,2 @@
+export { SqliteRuntimeState } from "./store.js";
+export type * from "./store.js";