@hypit/hypit 0.0.1 → 0.1.0

package/packages/nano-banana/README.md

@@ -0,0 +1,23 @@
+# `@hypit/nano-banana`
+
+Exact author/compute contracts and package-owned author Surfaces for Nano Banana 2 and Nano Banana Pro.
+
+The model variants are separate endpoints with exact request validation. Their Surfaces project the
+primary result to an ordinary image Artifact. The package contains no Provider selection, API key or
+network execution; `@hypit/provider-kie` is one optional Runtime implementation.
+
+Import the model variant you mean and connect prompt and references as ordinary graph edges:
+
+```xml
+<nano:Image id="draft" prompt={prompt} aspect-ratio="9:16" resolution="2K" output-format="png">
+  <nano:Reference image={person.image}/>
+</nano:Image>
+
+<nano:ProImage id="final" prompt={finalPrompt} aspect-ratio="9:16" resolution="4K" output-format="png"/>
+```
+
+The Surface only lowers this syntax into the package's exact model request. It does not select a Provider.
+
+Nano Banana 2 accepts prompts up to 20,000 characters, up to 14 references and its wider aspect-ratio
+set. Nano Banana Pro accepts prompts up to 10,000 characters, up to eight references and the ratios
+its exact model exposes; the two Surfaces do not share a guessed common request table.

package/packages/nano-banana/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/nano-banana",
+  "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/markup": "workspace:*",
+    "@hypit/model-kit": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/text": "workspace:*"
+  }
+}

package/packages/nano-banana/src/activation.ts

@@ -0,0 +1,14 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+  nanoBananaComponent, nanoBananaDefinition, nanoBananaManifest, nanoBananaModuleRef,
+  nanoBananaMarkupSurfaces,
+} from "./index.js";
+import { decodeNanoBananaImageSurface, decodeNanoBananaProImageSurface } from "./surface.js";
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: nanoBananaManifest }], components: [nanoBananaComponent], hostFacets: [
+  nanoBananaDefinition.hostFacet,
+  createMarkupSurfaceHostFacet({ module: nanoBananaModuleRef,
+    declaration: nanoBananaMarkupSurfaces.find((item) => item.name === "image")!, handler: decodeNanoBananaImageSurface }),
+  createMarkupSurfaceHostFacet({ module: nanoBananaModuleRef,
+    declaration: nanoBananaMarkupSurfaces.find((item) => item.name === "pro-image")!, handler: decodeNanoBananaProImageSurface }),
+] };
+export default hypitPackage;

package/packages/nano-banana/src/index.ts

@@ -0,0 +1,172 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary, SurfaceChildVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const nanoBananaModuleRef = { name: "@hypit/nano-banana", version: "1" } as const;
+export const nanoBananaModels = ["nano-banana-2", "nano-banana-pro"] as const;
+export type NanoBananaModel = typeof nanoBananaModels[number];
+
+const NANO_BANANA_2_RATIOS = ["auto", "1:1", "2:3", "3:2", "1:4", "4:1", "3:4", "4:3", "4:5",
+  "5:4", "1:8", "8:1", "9:16", "16:9", "21:9"] as const;
+const NANO_BANANA_PRO_RATIOS = ["auto", "1:1", "2:3", "3:2", "3:4", "4:3", "4:5",
+  "5:4", "9:16", "16:9", "21:9"] as const;
+
+function nanoBananaPortTable(model: NanoBananaModel): GenerationPortTable {
+  const pro = model === "nano-banana-pro";
+  return sealGenerationPortTable({
+    model,
+    result: "image",
+    ports: [
+      { name: "prompt", value: { kind: "text", maxChars: pro ? 10_000 : 20_000 }, minItems: 1, maxItems: 1 },
+      { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: pro ? 8 : 14 },
+      {
+        name: "aspectRatio",
+        value: {
+          kind: "enum",
+          values: pro ? [...NANO_BANANA_PRO_RATIOS] : [...NANO_BANANA_2_RATIOS],
+        },
+        minItems: 1,
+        maxItems: 1,
+      },
+      { name: "resolution", value: { kind: "enum", values: ["1K", "2K", "4K"] }, minItems: 1, maxItems: 1 },
+      { name: "outputFormat", value: { kind: "enum", values: ["png", "jpg"] }, minItems: 1, maxItems: 1 },
+    ],
+    requires: [],
+  });
+}
+
+export const nanoBananaPorts: Readonly<Record<NanoBananaModel, GenerationPortTable>> = {
+  "nano-banana-2": nanoBananaPortTable("nano-banana-2"),
+  "nano-banana-pro": nanoBananaPortTable("nano-banana-pro"),
+};
+
+export function sealNanoBananaRequest(
+  model: NanoBananaModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(nanoBananaPorts[model], ports);
+}
+
+const nanoBananaBaseDefinition = defineExactModelModule({
+  module: nanoBananaModuleRef,
+  endpoints: nanoBananaModels.map((model) => ({
+    key: model === "nano-banana-2" ? "v2" : "pro",
+    requestTypeName: model === "nano-banana-2" ? "NanoBanana2Request" : "NanoBananaProRequest",
+    producerName: `request-${model}`,
+    ports: nanoBananaPorts[model],
+  })),
+});
+
+export const nanoBananaEndpoints = nanoBananaBaseDefinition.endpoints;
+export const nanoBananaComponent = nanoBananaBaseDefinition.component;
+function nanoBananaAttributes(pro: boolean): readonly SurfaceAttributeVocabulary[] {
+  return [
+    {
+      name: "id",
+      kind: "identifier",
+      required: true,
+      summary: "Names this generation and prefixes the bindings it publishes.",
+    },
+    {
+      name: "prompt",
+      kind: "reference",
+      required: true,
+      summary: "The Text edge describing the picture the model renders.",
+      accepts: [textTypes.text],
+    },
+    {
+      name: "aspect-ratio",
+      kind: "literal",
+      required: true,
+      summary: "The shape of the generated picture.",
+      values: pro ? [...NANO_BANANA_PRO_RATIOS] : [...NANO_BANANA_2_RATIOS],
+    },
+    {
+      name: "resolution",
+      kind: "literal",
+      required: true,
+      summary: "The size band the model renders at.",
+      values: ["1K", "2K", "4K"],
+    },
+    {
+      name: "output-format",
+      kind: "literal",
+      required: true,
+      summary: "The encoding of the returned image Artifact.",
+      values: ["png", "jpg"],
+    },
+  ];
+}
+
+const nanoBananaChildren: readonly SurfaceChildVocabulary[] = [
+  { tag: "Reference", cardinality: "many",
+    summary: "Attaches one image Artifact as a reference picture.",
+    attributes: [
+      { name: "image", kind: "reference", required: true, accepts: [artifactTypes.blob],
+        summary: "Selects the image Artifact this reference contributes." },
+    ] },
+];
+
+const surface = (
+  name: "image" | "pro-image",
+  tag: "Image" | "ProImage",
+  endpoint: (typeof nanoBananaEndpoints)["v2" | "pro"],
+  pro: boolean,
+  summary: string,
+  example: string,
+) => ({
+  name,
+  tag,
+  mode: "structured" as const,
+  outputs: [endpoint!.draftType, endpoint!.mediaBindings.images!.type],
+  vocabulary: {
+    summary,
+    attributes: nanoBananaAttributes(pro),
+    children: nanoBananaChildren,
+    ports: [{
+      name: "image",
+      type: artifactTypes.blob,
+      summary: "The primary generated image, addressed as `<id>.image`.",
+    }],
+    example,
+    notes: [
+      `The element accepts at most ${pro ? 8 : 14} \`Reference\` children and no text content.`,
+      "Every `Reference` is an ordinary image Artifact edge; the Surface copies no runtime media into request metadata.",
+      "The Surface lowers the element into the package's exact model request and selects no Provider.",
+    ],
+  },
+});
+
+export const nanoBananaMarkupSurfaces = [
+    surface("image", "Image", nanoBananaEndpoints.v2!, false,
+      "Generates one picture with the exact Nano Banana 2 model from a Text prompt and optional reference images.",
+      `<nano:Image
+  id="draft"
+  prompt={prompt}
+  aspect-ratio="9:16"
+  resolution="2K"
+  output-format="png"
+>
+  <nano:Reference image={person.image}/>
+</nano:Image>`),
+    surface("pro-image", "ProImage", nanoBananaEndpoints.pro!, true,
+      "Generates one picture with the exact Nano Banana Pro model from a Text prompt and optional reference images.",
+      `<nano:ProImage
+  id="final"
+  prompt={finalPrompt}
+  aspect-ratio="9:16"
+  resolution="4K"
+  output-format="png"
+/>`),
+  ] as const;
+
+export const nanoBananaManifest = {
+  ...nanoBananaBaseDefinition.manifest,
+};
+export const nanoBananaDefinition = {
+  ...nanoBananaBaseDefinition,
+  manifest: nanoBananaManifest,
+};

package/packages/nano-banana/src/surface.ts

@@ -0,0 +1,120 @@
+import { artifactTypes } from "@hypit/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@hypit/generation";
+import type { GenerationMediaPort } from "@hypit/generation";
+import {
+  createExactModelPrimaryGenerationFragment,
+  exactModelMediaInputNames,
+  exactModelTextInputName,
+} from "@hypit/model-kit";
+import type { ExactModelEndpoint } from "@hypit/model-kit";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+import type { CanonicalValue, TypeRef } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+
+import { nanoBananaEndpoints } from "./index.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function localName(name: string): string {
+  return name.includes(":") ? name.slice(name.lastIndexOf(":") + 1) : name;
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+  return left.name === right.name && left.module.name === right.module.name && left.module.version === right.module.version;
+}
+
+function exact(element: StructuredElement, allowed: readonly string[], required = allowed): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+  assert(unknown.length === 0, `${element.name} does not accept ${unknown[0]}`);
+  const missing = required.filter((name) => element.attributes[name] === undefined);
+  assert(missing.length === 0, `${element.name} requires ${missing.join(", ")}`);
+}
+
+function text(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  assert(typeof value === "string" && value.trim().length > 0, `${element.name}.${name} must be text`);
+  return value.trim();
+}
+
+function ref(
+  element: StructuredElement,
+  name: string,
+  type: TypeRef,
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  assert(typeof value === "object" && value.kind === "reference", `${element.name}.${name} must be a reference`);
+  const result = resolve(value.path);
+  assert(result !== undefined && sameType(result.type, type), `${element.name}.${name} has the wrong type`);
+  return result;
+}
+
+function decoder(endpoint: ExactModelEndpoint): StructuredSurfaceHandler {
+  return ({ element, resolveReference }) => {
+    exact(element, ["id", "prompt", "aspect-ratio", "resolution", "output-format"]);
+    const id = text(element, "id");
+    const prompt = ref(element, "prompt", textTypes.text, resolveReference);
+    if (prompt.record !== undefined) {
+      assert(prompt.record.value.kind === "inline", `${element.name}.prompt must reference Text`);
+      verifyText(prompt.record.value.value);
+    }
+    const imagePort = generationPort(endpoint.ports, "images");
+    assert(imagePort.value.kind === "media", "Nano Banana images port is not media");
+    const images: SurfaceResolvedReference[] = [];
+    for (const child of element.children) {
+      if (child.kind === "text") {
+        assert(child.value.trim().length === 0, `${element.name} accepts only Reference children`);
+        continue;
+      }
+      assert(localName(child.name) === "Reference", `${element.name} accepts only Reference children`);
+      exact(child, ["image"]);
+      assert(!child.children.some((item) => item.kind === "element" || item.value.trim()), `${child.name} must be empty`);
+      const image = ref(child, "image", artifactTypes.blob, resolveReference);
+      if (image.record !== undefined) {
+        assert(image.record.value.kind === "blob" && image.record.value.mediaType.startsWith("image/"),
+          `${child.name}.image must reference image media`);
+      }
+      images.push(image);
+    }
+    assert(images.length <= imagePort.maxItems, `${element.name} accepts at most ${imagePort.maxItems} references`);
+    const draft = sealGenerationRequestDraft(endpoint.ports, {
+      aspectRatio: [text(element, "aspect-ratio")],
+      resolution: [text(element, "resolution")],
+      outputFormat: [text(element, "output-format")],
+    });
+    const records: Array<{ id: string; type: TypeRef; value: { kind: "inline"; value: CanonicalValue }; range: StructuredElement["range"] }> = [{
+      id: `${id}.draft`, type: endpoint.draftType,
+      value: { kind: "inline", value: draft as unknown as CanonicalValue }, range: element.range,
+    }];
+    const inputs: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+      draft: { kind: "record", id: `${id}.draft` }, [exactModelTextInputName("prompt")]: prompt.ref,
+    };
+    const media = images.map((image, index) => {
+      const name = `image-${String(index + 1).padStart(4, "0")}`;
+      const bindingId = `${id}.${name}.binding`;
+      records.push({
+        id: bindingId, type: endpoint.mediaBindings.images!.type,
+        value: { kind: "inline", value: sealGenerationMediaBinding(imagePort as GenerationMediaPort, { role: "image" }) as unknown as CanonicalValue },
+        range: element.range,
+      });
+      const names = exactModelMediaInputNames(name);
+      inputs[names.binding] = { kind: "record", id: bindingId };
+      inputs[names.artifact] = image.ref;
+      return { name, port: "images" } as const;
+    });
+    const fragment = createExactModelPrimaryGenerationFragment(endpoint, media, [{ name: "prompt", port: "prompt" }]);
+    return { records, fragments: [fragment], components: [{
+      id, fragment: fragment.id, inputs, outputs: { image: `${id}.image` }, range: element.range,
+    }] };
+  };
+}
+
+export const decodeNanoBananaImageSurface = decoder(nanoBananaEndpoints.v2!);
+export const decodeNanoBananaProImageSurface = decoder(nanoBananaEndpoints.pro!);

package/packages/narrative/README.md

@@ -0,0 +1,7 @@
+# `@hypit/narrative`
+
+External components use `@hypit/hypit/narrative` from their `@hypit/hypit` development dependency. The package
+owns the types and helpers below; Source imports retain the `@hypit/narrative@1` Module identity.
+
+
+Public, provider-neutral contracts for authored speech and semantic selections.

package/packages/narrative/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@hypit/narrative",
+  "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/protocol": "workspace:*"
+  }
+}

package/packages/narrative/src/activation.ts

@@ -0,0 +1,7 @@
+import { narrativeComponent, narrativeManifest } from "./index.js";
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: narrativeManifest }],
+  components: [narrativeComponent],
+};
+export default hypitPackage;

package/packages/narrative/src/component.ts

@@ -0,0 +1,33 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { StoredValue } from "@hypit/protocol";
+
+import {
+  assertCaptionDocumentIdentity,
+  assertNarrativeExcerptIdentity,
+  assertNarrativeIdentity,
+  assertNarrativeMomentRefIdentity,
+  assertNarrativeSelectionRefIdentity,
+} from "./identity.js";
+import { narrativeTypes } from "./manifest.js";
+import type {
+  CaptionDocument,
+  Narrative,
+  NarrativeExcerpt,
+  NarrativeMomentRef,
+  NarrativeSelectionRef,
+} from "./types.js";
+
+function inline<T>(value: StoredValue, subject: string): T {
+  if (value.kind !== "inline") throw new Error(`${subject} must be inline.`);
+  return value.value as T;
+}
+
+export const narrativeComponent = {
+  validators: [
+    { type: narrativeTypes.narrative, handler: ({ value }) => assertNarrativeIdentity(inline<Narrative>(value, "Narrative")) },
+    { type: narrativeTypes.excerpt, handler: ({ value }) => assertNarrativeExcerptIdentity(inline<NarrativeExcerpt>(value, "NarrativeExcerpt")) },
+    { type: narrativeTypes.selection, handler: ({ value }) => assertNarrativeSelectionRefIdentity(inline<NarrativeSelectionRef>(value, "NarrativeSelection")) },
+    { type: narrativeTypes.moment, handler: ({ value }) => assertNarrativeMomentRefIdentity(inline<NarrativeMomentRef>(value, "NarrativeMoment")) },
+    { type: narrativeTypes.captionDocument, handler: ({ value }) => assertCaptionDocumentIdentity(inline<CaptionDocument>(value, "CaptionDocument")) },
+  ],
+} satisfies ComponentPackage;

package/packages/narrative/src/identity.ts

@@ -0,0 +1,131 @@
+import type {
+  CaptionDocument,
+  Narrative,
+  NarrativeExcerpt,
+  NarrativeMomentRef,
+  NarrativeSelectionRef,
+} from "./types.js";
+
+function nonempty(value: string, subject: string): void {
+  if (value.trim().length === 0) throw new Error(`${subject} must not be empty.`);
+}
+
+function unique(values: readonly string[], subject: string): Set<string> {
+  const found = new Set<string>();
+  for (const value of values) {
+    nonempty(value, subject);
+    if (found.has(value)) throw new Error(`${subject} repeats ${value}.`);
+    found.add(value);
+  }
+  return found;
+}
+
+export function assertNarrativeIdentity(value: Narrative): void {
+  nonempty(value.id, "Narrative id");
+  if (value.segments.length === 0) throw new Error("Narrative must contain at least one Segment.");
+  const segmentIds = unique(value.segments.map((item) => item.id), "Narrative Segment id");
+  const tokenIds = unique(value.tokens.map((item) => item.id), "Narrative Token id");
+  unique(value.turns.map((item) => item.id), "Narrative Turn id");
+  unique(value.selections.map((item) => item.id), "Narrative Selection id");
+  unique(value.moments.map((item) => item.id), "Narrative Moment id");
+  const anchorIds = unique(value.semanticIndex.anchors.map((item) => item.id), "Narrative Anchor id");
+  const anchors = value.semanticIndex.anchors;
+  if (anchors[0]?.id !== "program:start" || anchors[0].kind !== "program-start"
+    || anchors.at(-1)?.id !== "program:end" || anchors.at(-1)?.kind !== "program-end") {
+    throw new Error("Narrative semantic anchors must begin and end with the Program boundaries.");
+  }
+  const anchorOrder = new Map(anchors.map((anchor, index) => [anchor.id, index] as const));
+  let tokenCursor = 0;
+  for (const segment of value.segments) {
+    if (!Number.isSafeInteger(segment.tokenStart) || !Number.isSafeInteger(segment.tokenEndExclusive)
+      || segment.tokenStart !== tokenCursor || segment.tokenEndExclusive < segment.tokenStart
+      || segment.tokenEndExclusive > value.tokens.length
+      || !anchorIds.has(segment.startAnchorId) || !anchorIds.has(segment.endAnchorId)) {
+      throw new Error(`Narrative Segment ${segment.id} has invalid token or Anchor boundaries.`);
+    }
+    for (let index = segment.tokenStart; index < segment.tokenEndExclusive; index += 1) {
+      const token = value.tokens[index]!;
+      if (token.segmentId !== segment.id || !tokenIds.has(token.id)
+        || !anchorIds.has(token.startAnchorId) || !anchorIds.has(token.endAnchorId)
+        || token.text.length === 0 || token.normalized.length === 0) {
+        throw new Error(`Narrative Token ${token.id} disagrees with Segment ${segment.id}.`);
+      }
+    }
+    tokenCursor = segment.tokenEndExclusive;
+  }
+  if (tokenCursor !== value.tokens.length) throw new Error("Narrative Segments must partition Tokens in order.");
+  for (const turn of value.turns) {
+    if (!segmentIds.has(turn.segmentId) || !Number.isSafeInteger(turn.tokenStart)
+      || !Number.isSafeInteger(turn.tokenEndExclusive) || turn.tokenEndExclusive <= turn.tokenStart
+      || turn.tokenStart < 0 || turn.tokenEndExclusive > value.tokens.length
+      || value.tokens.slice(turn.tokenStart, turn.tokenEndExclusive).some((token) => token.segmentId !== turn.segmentId)) {
+      throw new Error(`Narrative Turn ${turn.id} has invalid Token coverage.`);
+    }
+  }
+  for (const selection of value.selections) {
+    const start = anchorOrder.get(selection.startAnchorId);
+    const end = anchorOrder.get(selection.endAnchorId);
+    if (start === undefined || end === undefined || end < start) {
+      throw new Error(`Narrative Selection ${selection.id} has invalid Anchor order.`);
+    }
+  }
+  for (const moment of value.moments) {
+    if (!anchorIds.has(moment.anchorId)) throw new Error(`Narrative Moment ${moment.id} names an unknown Anchor.`);
+  }
+}
+
+export function assertNarrativeExcerptIdentity(value: NarrativeExcerpt): void {
+  if (value.kind !== "segment") throw new Error("NarrativeExcerpt must be a Segment.");
+  nonempty(value.narrativeId, "NarrativeExcerpt narrativeId");
+  nonempty(value.id, "NarrativeExcerpt id");
+  if (!Number.isSafeInteger(value.tokenStart) || !Number.isSafeInteger(value.tokenEndExclusive)
+    || value.tokenStart < 0 || value.tokenEndExclusive < value.tokenStart) {
+    throw new Error("NarrativeExcerpt Token coverage is invalid.");
+  }
+}
+
+export function assertNarrativeSelectionRefIdentity(value: NarrativeSelectionRef): void {
+  nonempty(value.narrativeId, "NarrativeSelection narrativeId");
+  nonempty(value.id, "NarrativeSelection id");
+  nonempty(value.startAnchorId, "NarrativeSelection startAnchorId");
+  nonempty(value.endAnchorId, "NarrativeSelection endAnchorId");
+}
+
+export function assertNarrativeMomentRefIdentity(value: NarrativeMomentRef): void {
+  nonempty(value.narrativeId, "NarrativeMoment narrativeId");
+  nonempty(value.id, "NarrativeMoment id");
+  nonempty(value.anchorId, "NarrativeMoment anchorId");
+}
+
+export function assertCaptionDocumentIdentity(value: CaptionDocument): void {
+  nonempty(value.narrativeId, "CaptionDocument narrativeId");
+  nonempty(value.id, "CaptionDocument id");
+  if ((value.units.length === 0) !== (value.words.length === 0)) {
+    throw new Error("CaptionDocument units and words must be empty together.");
+  }
+  const unitIds = unique(value.units.map((item) => item.id), "CaptionDocument unit id");
+  const wordIds = unique(value.words.map((item) => item.id), "CaptionDocument word id");
+  const words = new Map(value.words.map((word) => [word.id, word] as const));
+  const orderedWords: string[] = [];
+  for (const unit of value.units) {
+    if (unit.wordIds.length === 0 || unit.sourceTokenIds.length === 0) {
+      throw new Error(`Caption unit ${unit.id} is empty.`);
+    }
+    for (const wordId of unit.wordIds) {
+      const word = words.get(wordId);
+      if (word === undefined || word.unitId !== unit.id || word.segmentId !== unit.segmentId
+        || word.turnId !== unit.turnId || word.role !== unit.role) {
+        throw new Error(`Caption unit ${unit.id} references a foreign word.`);
+      }
+      orderedWords.push(wordId);
+    }
+  }
+  if (orderedWords.length !== wordIds.size
+    || orderedWords.some((id, index) => id !== value.words[index]?.id)) {
+    throw new Error("CaptionDocument units must partition words in order.");
+  }
+  unique(value.cueBreaks.map((item) => item.afterUnitId), "CaptionDocument Cue Break");
+  if (value.cueBreaks.some((item) => !unitIds.has(item.afterUnitId))) {
+    throw new Error("CaptionDocument Cue Break names an unknown unit.");
+  }
+}

package/packages/narrative/src/index.ts

@@ -0,0 +1,11 @@
+export { narrativeDependency, narrativeManifest, narrativeModuleRef, narrativeTypes } from "./manifest.js";
+export { narrativeComponent } from "./component.js";
+export {
+  assertCaptionDocumentIdentity,
+  assertNarrativeExcerptIdentity,
+  assertNarrativeIdentity,
+  assertNarrativeMomentRefIdentity,
+  assertNarrativeSelectionRefIdentity,
+} from "./identity.js";
+export { captionDocumentSchema, narrativeExcerptSchema, narrativeMomentSchema, narrativeSchema, narrativeSelectionSchema } from "./schema.js";
+export type * from "./types.js";

package/packages/narrative/src/manifest.ts

@@ -0,0 +1,30 @@
+import type { ModuleManifest, TypeRef } from "@hypit/protocol";
+import {
+  captionDocumentSchema,
+  narrativeExcerptSchema,
+  narrativeSchema,
+  narrativeMomentSchema,
+  narrativeSelectionSchema,
+} from "./schema.js";
+
+export const narrativeModuleRef = { name: "@hypit/narrative", version: "1" } as const;
+export const narrativeTypes = {
+  narrative: { module: narrativeModuleRef, name: "Narrative" },
+  excerpt: { module: narrativeModuleRef, name: "NarrativeExcerpt" },
+  selection: { module: narrativeModuleRef, name: "NarrativeSelection" },
+  moment: { module: narrativeModuleRef, name: "NarrativeMoment" },
+  captionDocument: { module: narrativeModuleRef, name: "CaptionDocument" },
+} satisfies Record<string, TypeRef>;
+export const narrativeManifest: ModuleManifest = {
+  format: "hypit.module@1", name: narrativeModuleRef.name, version: narrativeModuleRef.version,
+  dependencies: [],
+  types: [
+    { name: narrativeTypes.narrative.name },
+    { name: narrativeTypes.excerpt.name },
+    { name: narrativeTypes.selection.name },
+    { name: narrativeTypes.moment.name },
+    { name: narrativeTypes.captionDocument.name },
+  ],
+  capabilities: [], producers: [],
+};
+export const narrativeDependency = { module: narrativeModuleRef } as const;