@hypit/hypit 0.0.1 → 0.1.1

package/packages/seedream/src/index.ts

@@ -0,0 +1,162 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type { SurfaceAttributeVocabulary } from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const seedreamModuleRef = { name: "@hypit/seedream", version: "1" } as const;
+
+export const seedream5LitePorts: GenerationPortTable = sealGenerationPortTable({
+  model: "seedream-5-lite",
+  result: "image",
+  ports: [
+    { name: "prompt", value: { kind: "text", maxChars: 3_000 }, minItems: 1, maxItems: 1 },
+    {
+      name: "aspectRatio",
+      value: { kind: "enum", values: ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"] },
+      minItems: 1,
+      maxItems: 1,
+    },
+    /** Basic renders 2K, high 3K and ultra 4K. */
+    { name: "quality", value: { kind: "enum", values: ["basic", "high", "ultra"] }, minItems: 1, maxItems: 1 },
+    { name: "outputFormat", value: { kind: "enum", values: ["png", "jpeg"] }, minItems: 1, maxItems: 1 },
+    /** Explicit author choice; the Provider never silently changes this policy. */
+    { name: "nsfwCheck", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },
+    { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 14 },
+  ],
+  requires: [],
+});
+
+export function sealSeedreamRequest(
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(seedream5LitePorts, ports);
+}
+
+const seedreamBaseDefinition = defineExactModelModule({
+  module: seedreamModuleRef,
+  endpoints: [{
+    key: "image",
+    requestTypeName: "Seedream5LiteRequest",
+    producerName: "request-seedream-5-lite",
+    ports: seedream5LitePorts,
+  }],
+});
+
+export const seedreamEndpoints = seedreamBaseDefinition.endpoints;
+export const seedreamComponent = seedreamBaseDefinition.component;
+const endpoint = seedreamEndpoints.image!;
+
+const seedreamAttributes: readonly SurfaceAttributeVocabulary[] = [
+  {
+    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: ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"],
+  },
+  {
+    name: "quality",
+    kind: "literal",
+    required: true,
+    summary: "The render band the model works at, basic 2K, high 3K and ultra 4K.",
+    values: ["basic", "high", "ultra"],
+  },
+  {
+    name: "output-format",
+    kind: "literal",
+    required: true,
+    summary: "The encoding of the returned image.",
+    values: ["png", "jpeg"],
+  },
+  {
+    name: "nsfw-check",
+    kind: "literal",
+    required: true,
+    summary: "Whether the Provider applies its safety check to this request.",
+    values: ["true", "false"],
+  },
+];
+
+const seedreamImagePort = {
+  name: "image",
+  type: artifactTypes.blob,
+  summary: "The primary generated image, addressed as `<id>.image`.",
+} as const;
+
+export const seedreamMarkupSurfaces = [{
+    name: "text-image", tag: "TextImage", mode: "structured" as const,
+    outputs: [endpoint.draftType],
+    vocabulary: {
+      summary: "Generates one picture with the exact Seedream 5 Lite model from a Text prompt alone.",
+      attributes: seedreamAttributes,
+      ports: [seedreamImagePort],
+      example: `<seedream:TextImage
+  id="scene"
+  prompt={prompt}
+  aspect-ratio="9:16"
+  quality="high"
+  output-format="png"
+  nsfw-check="true"
+/>`,
+      notes: [
+        "The element accepts no children; reference pictures belong to `ReferenceImage`.",
+        "Every request field is written by the author; the Runtime chooses no model on the author's behalf.",
+      ],
+    },
+  }, {
+    name: "reference-image", tag: "ReferenceImage", mode: "structured" as const,
+    outputs: [endpoint.draftType, endpoint.mediaBindings.images!.type],
+    vocabulary: {
+      summary: "Generates one picture with the exact Seedream 5 Lite model from a Text prompt and one or more reference images.",
+      attributes: seedreamAttributes,
+      children: [{
+        tag: "Reference",
+        cardinality: "many",
+        summary: "Attaches one image Artifact to the request as a reference picture.",
+        attributes: [{
+          name: "image",
+          kind: "reference",
+          required: true,
+          summary: "The Artifact supplied as a reference picture, which must carry image media.",
+          accepts: [artifactTypes.blob],
+        }],
+      }],
+      ports: [seedreamImagePort],
+      example: `<seedream:ReferenceImage
+  id="variation"
+  prompt={variationPrompt}
+  aspect-ratio="9:16"
+  quality="high"
+  output-format="png"
+  nsfw-check="true"
+>
+  <seedream:Reference image={scene.image}/>
+</seedream:ReferenceImage>`,
+      notes: [
+        "The element requires at least one `Reference` child and accepts at most 14.",
+        "The Surface copies no runtime media into request metadata; every reference stays a graph edge.",
+      ],
+    },
+  }] as const;
+
+export const seedreamManifest = {
+  ...seedreamBaseDefinition.manifest,
+};
+export const seedreamDefinition = {
+  ...seedreamBaseDefinition, manifest: seedreamManifest,
+};

package/packages/seedream/src/surface.ts

@@ -0,0 +1,84 @@
+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 { MarkupAttributeValue, StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/markup";
+import type { CanonicalValue, TypeRef } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+import { seedreamEndpoints } 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(a: TypeRef, b: TypeRef): boolean { return a.name === b.name && a.module.name === b.module.name && a.module.version === b.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 boolean(element: StructuredElement, name: string): boolean {
+  const value = text(element, name);
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`${element.name}.${name} must be true or false`);
+}
+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(referenceMode: boolean): StructuredSurfaceHandler {
+  return ({ element, resolveReference }) => {
+    exact(element, ["id", "prompt", "aspect-ratio", "quality", "output-format", "nsfw-check"]);
+    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 endpoint = seedreamEndpoints.image!;
+    const imagePort = generationPort(endpoint.ports, "images");
+    assert(imagePort.value.kind === "media", "Seedream 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(referenceMode && localName(child.name) === "Reference", `${element.name} accepts no such child`);
+      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 be image media`);
+      images.push(image);
+    }
+    assert(referenceMode ? images.length >= 1 : images.length === 0,
+      referenceMode ? `${element.name} requires at least one Reference` : `${element.name} does not accept References`);
+    assert(images.length <= imagePort.maxItems, `${element.name} accepts at most ${imagePort.maxItems} References`);
+    const draft = sealGenerationRequestDraft(endpoint.ports, {
+      aspectRatio: [text(element, "aspect-ratio")], quality: [text(element, "quality")],
+      outputFormat: [text(element, "output-format")], nsfwCheck: [boolean(element, "nsfw-check")],
+    });
+    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 decodeSeedreamTextImageSurface = decoder(false);
+export const decodeSeedreamReferenceImageSurface = decoder(true);

package/packages/semantic-take-adjust/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/semantic-take-adjust",
+  "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/elaborator": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/speech": "workspace:*"
+  }
+}

package/packages/semantic-take-adjust/src/activation.ts

@@ -0,0 +1,22 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeSemanticTakeAdjustSurface,
+  semanticTakeAdjustComponent,
+  semanticTakeAdjustManifest,
+  semanticTakeAdjustMarkupSurfaces,
+  semanticTakeAdjustModuleRef,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: semanticTakeAdjustManifest }],
+  components: [semanticTakeAdjustComponent],
+  hostFacets: [createMarkupSurfaceHostFacet({
+    module: semanticTakeAdjustModuleRef,
+    declaration: semanticTakeAdjustMarkupSurfaces.find((item) => item.name === "semantic-take")!,
+    handler: decodeSemanticTakeAdjustSurface,
+  })],
+};
+
+export default hypitPackage;

package/packages/semantic-take-adjust/src/component.ts

@@ -0,0 +1,31 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+import type { SemanticTake } from "@hypit/speech";
+
+import { semanticTakeAdjustProducers } from "./manifest.js";
+import { adjustSemanticTake } from "./program.js";
+import type { SemanticTakeAdjustmentPlan } 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 semanticTakeAdjustComponent = {
+  producers: [{
+    producer: semanticTakeAdjustProducers.adjust,
+    handler: ({ inputs }) => ({
+      outputs: {
+        take: {
+          kind: "inline",
+          value: canonicalize(adjustSemanticTake(
+            inline<SemanticTake>(inputs.source?.value, "SemanticTake"),
+            inline<SemanticTakeAdjustmentPlan>(inputs.plan?.value, "SemanticTake adjustment plan"),
+          )),
+        },
+      },
+      needs: {},
+    }),
+  }],
+} satisfies ComponentPackage;

package/packages/semantic-take-adjust/src/fragment.ts

@@ -0,0 +1,24 @@
+import { sealGraphFragment } from "@hypit/elaborator";
+import { speechTypes } from "@hypit/speech";
+
+import { semanticTakeAdjustProducers, semanticTakeAdjustTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+
+export const semanticTakeAdjustFragment = sealGraphFragment({
+  inputs: [
+    { name: "source", type: speechTypes.semanticTake },
+    { name: "plan", type: semanticTakeAdjustTypes.plan },
+  ],
+  operations: [{
+    id: "adjust",
+    producer: semanticTakeAdjustProducers.adjust,
+    inputs: { source: input("source"), plan: input("plan") },
+    result: { kind: "output", name: "take" },
+  }],
+  exports: [{
+    name: "take",
+    type: speechTypes.semanticTake,
+    root: { kind: "fragment-operation", operation: "adjust" },
+  }],
+});

package/packages/semantic-take-adjust/src/index.ts

@@ -0,0 +1,12 @@
+export { semanticTakeAdjustComponent } from "./component.js";
+export { semanticTakeAdjustFragment } from "./fragment.js";
+export {
+  semanticTakeAdjustManifest,
+  semanticTakeAdjustMarkupSurfaces,
+  semanticTakeAdjustModuleRef,
+  semanticTakeAdjustProducers,
+  semanticTakeAdjustTypes,
+} from "./manifest.js";
+export { adjustSemanticTake } from "./program.js";
+export { decodeSemanticTakeAdjustSurface } from "./surface.js";
+export type { SemanticTakeAdjustmentPlan, SemanticTakeAnchorAdjustment } from "./types.js";

package/packages/semantic-take-adjust/src/manifest.ts

@@ -0,0 +1,57 @@
+import { narrativeDependency } from "@hypit/narrative";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+import { speechDependency, speechTypes } from "@hypit/speech";
+
+export const semanticTakeAdjustModuleRef = { name: "@hypit/semantic-take-adjust", version: "1" } as const;
+
+export const semanticTakeAdjustTypes = {
+  plan: { module: semanticTakeAdjustModuleRef, name: "SemanticTakeAdjustmentPlan" },
+} satisfies Record<string, TypeRef>;
+
+export const semanticTakeAdjustProducers = {
+  adjust: { module: semanticTakeAdjustModuleRef, name: "adjust-semantic-take" },
+} satisfies Record<string, ProducerRef>;
+
+export const semanticTakeAdjustMarkupSurfaces = [{
+  name: "semantic-take",
+  tag: "SemanticTake",
+  mode: "structured",
+  outputs: [semanticTakeAdjustTypes.plan, speechTypes.semanticTake],
+  vocabulary: {
+    summary: "Applies explicit author corrections to measured SemanticTake anchor frames without changing its media or Script identities.",
+    attributes: [
+      { name: "id", kind: "identifier", required: true,
+        summary: "Names the corrected SemanticTake." },
+      { name: "source", kind: "reference", required: true, accepts: [speechTypes.semanticTake],
+        summary: "Selects the measured SemanticTake being corrected." },
+    ],
+    ports: [{ name: "take", type: speechTypes.semanticTake,
+      summary: "The corrected SemanticTake, addressed as `<id>.take`." }],
+    example: `<adjust:SemanticTake id="opening-corrected" source={opening-measured.take}>
+  <adjust:Anchor at={story.moment.answer} frame="63"/>
+</adjust:SemanticTake>`,
+    notes: [
+      "Each Anchor names an author-declared Script Moment and gives its exact Segment-local frame.",
+      "This is an explicit correction layer over measured evidence; it does not guess timing or modify media.",
+      "Every Token boundary that owns the corrected Anchor is updated together, preserving SemanticTake identity invariants.",
+    ],
+  },
+}] as const;
+
+export const semanticTakeAdjustManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: semanticTakeAdjustModuleRef.name,
+  version: semanticTakeAdjustModuleRef.version,
+  dependencies: [narrativeDependency, speechDependency],
+  types: [{ name: semanticTakeAdjustTypes.plan.name }],
+  capabilities: [],
+  producers: [{
+    name: semanticTakeAdjustProducers.adjust.name,
+    inputs: [
+      { name: "source", type: speechTypes.semanticTake },
+      { name: "plan", type: semanticTakeAdjustTypes.plan },
+    ],
+    outputs: [{ name: "take", type: speechTypes.semanticTake }],
+    needs: [],
+  }],
+};

package/packages/semantic-take-adjust/src/program.ts

@@ -0,0 +1,49 @@
+import { assertSemanticTakeIdentity, sealSemanticTake } from "@hypit/speech";
+import type { SemanticTake } from "@hypit/speech";
+
+import type { SemanticTakeAdjustmentPlan } from "./types.js";
+
+export function adjustSemanticTake(
+  source: SemanticTake,
+  plan: SemanticTakeAdjustmentPlan,
+): SemanticTake {
+  assertSemanticTakeIdentity(source);
+  if (plan.narrativeId !== source.narrativeId) {
+    throw new Error(`SemanticTake adjustment belongs to Narrative ${plan.narrativeId}, not ${source.narrativeId}.`);
+  }
+  if (plan.anchors.length === 0) throw new Error("SemanticTake adjustment requires at least one Anchor.");
+
+  const sourceAnchorIds = new Set(source.anchors.map((anchor) => anchor.identity));
+  const adjusted = new Map<string, number>();
+  for (const anchor of plan.anchors) {
+    if (!sourceAnchorIds.has(anchor.anchorId)) {
+      throw new Error(`SemanticTake does not contain adjusted Anchor ${anchor.anchorId}.`);
+    }
+    if (adjusted.has(anchor.anchorId)) {
+      throw new Error(`SemanticTake Anchor ${anchor.anchorId} is adjusted more than once.`);
+    }
+    if (!Number.isSafeInteger(anchor.frame) || anchor.frame < 0 || anchor.frame > source.media.timeline.frameCount) {
+      throw new Error(`SemanticTake Anchor ${anchor.anchorId} has an invalid adjusted frame.`);
+    }
+    adjusted.set(anchor.anchorId, anchor.frame);
+  }
+
+  const frame = (anchorId: string, fallback: number): number => adjusted.get(anchorId) ?? fallback;
+  return sealSemanticTake({
+    ...source,
+    segment: {
+      ...source.segment,
+      startFrame: frame(source.segment.startAnchorId, source.segment.startFrame),
+      endFrameExclusive: frame(source.segment.endAnchorId, source.segment.endFrameExclusive),
+    },
+    anchors: source.anchors.map((anchor) => ({
+      ...anchor,
+      frame: frame(anchor.identity, anchor.frame),
+    })),
+    tokens: source.tokens.map((token) => ({
+      ...token,
+      startFrame: frame(token.startAnchorId, token.startFrame),
+      endFrameExclusive: frame(token.endAnchorId, token.endFrameExclusive),
+    })),
+  });
+}

package/packages/semantic-take-adjust/src/surface.ts

@@ -0,0 +1,96 @@
+import {
+  assertExactAttributes,
+  localName,
+  textAttribute,
+} from "@hypit/markup";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+import { narrativeTypes } from "@hypit/narrative";
+import type { NarrativeMomentRef } from "@hypit/narrative";
+import { canonicalize, sameType } from "@hypit/protocol";
+import { speechTypes } from "@hypit/speech";
+
+import { semanticTakeAdjustFragment } from "./fragment.js";
+import { semanticTakeAdjustTypes } from "./manifest.js";
+import type { SemanticTakeAdjustmentPlan } from "./types.js";
+
+function reference(
+  element: StructuredElement,
+  name: string,
+  expected: SurfaceResolvedReference["type"],
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const raw: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof raw !== "object" || raw.kind !== "reference") {
+    throw new Error(`${element.name}.${name} must be a whole-value reference.`);
+  }
+  const resolved = resolveReference(raw.path);
+  if (resolved === undefined) throw new Error(`${element.name}.${name} cannot resolve ${raw.path}.`);
+  if (!sameType(resolved.type, expected)) throw new Error(`${element.name}.${name} has the wrong type.`);
+  return resolved;
+}
+
+function inline<T>(value: SurfaceResolvedReference, subject: string): T {
+  if (value.record?.value.kind !== "inline") throw new Error(`${subject} must reference an authored inline Record.`);
+  return value.record.value.value as unknown as T;
+}
+
+function frameAttribute(element: StructuredElement): number {
+  const value = Number(textAttribute(element, "frame"));
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${element.name}.frame must be a non-negative integer.`);
+  return value;
+}
+
+export const decodeSemanticTakeAdjustSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertExactAttributes(element, ["id", "source"]);
+  const id = textAttribute(element, "id");
+  const source = reference(element, "source", speechTypes.semanticTake, resolveReference);
+  const moments: NarrativeMomentRef[] = [];
+  const anchors: SemanticTakeAdjustmentPlan["anchors"][number][] = [];
+
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim()) throw new Error(`${element.name} accepts only Anchor children.`);
+      continue;
+    }
+    if (localName(child.name) !== "Anchor") throw new Error(`${element.name} accepts only Anchor children.`);
+    assertExactAttributes(child, ["at", "frame"]);
+    if (child.children.some((item) => item.kind === "element" || item.value.trim())) {
+      throw new Error(`${child.name} must be empty.`);
+    }
+    const moment = inline<NarrativeMomentRef>(
+      reference(child, "at", narrativeTypes.moment, resolveReference),
+      `${child.name}.at`,
+    );
+    moments.push(moment);
+    anchors.push({ anchorId: moment.anchorId, frame: frameAttribute(child) });
+  }
+  if (anchors.length === 0) throw new Error(`${element.name} requires at least one Anchor child.`);
+  const narrativeId = moments[0]!.narrativeId;
+  if (moments.some((moment) => moment.narrativeId !== narrativeId)) {
+    throw new Error(`${element.name} cannot mix Moments from different Narratives.`);
+  }
+
+  const planId = `${id}.plan`;
+  const plan: SemanticTakeAdjustmentPlan = { narrativeId, anchors };
+  return {
+    records: [{
+      id: planId,
+      type: semanticTakeAdjustTypes.plan,
+      value: { kind: "inline", value: canonicalize(plan) },
+      range: element.range,
+    }],
+    components: [{
+      id,
+      fragment: semanticTakeAdjustFragment.id,
+      inputs: { source: source.ref, plan: { kind: "record", id: planId } },
+      outputs: { take: `${id}.take` },
+      range: element.range,
+    }],
+    fragments: [semanticTakeAdjustFragment],
+  };
+};

package/packages/semantic-take-adjust/src/types.ts

@@ -0,0 +1,9 @@
+export type SemanticTakeAnchorAdjustment = {
+  readonly anchorId: string;
+  readonly frame: number;
+};
+
+export type SemanticTakeAdjustmentPlan = {
+  readonly narrativeId: string;
+  readonly anchors: readonly SemanticTakeAnchorAdjustment[];
+};

package/packages/semantic-track/README.md

@@ -0,0 +1,21 @@
+# @hypit/semantic-track
+
+`SemanticTrack` is the single global semantic-timeline fact. It is the continuous program skeleton:
+every item is a real segment-local `SemanticTake`, and global frame positions are the prefix sum of
+their normalized local frame counts. There are no gap items or empty items. A Take may carry only
+audio or only visual media; its word array may be empty. An empty Script Segment such as
+`<empty></empty>` can therefore retain a real media span and both Segment anchors without speech.
+An empty word array is not an empty Track item. Visual placement is deliberately not
+part of this semantic truth.
+
+The package exposes pure projections to `ProgramSpace` and `AudioTrack`, plus the
+selection/segment/moment lookup functions used by semantic components. It performs no media I/O,
+mixing, transcription or rendering.
+
+## Prepared material in a semantic window
+
+`projectSemanticMedia(track, window?)` returns each intersecting Take's `media`, `segmentId`, global
+`span` and local `source` frame span. The default window is the whole performance. An interval
+beginning inside a Take preserves its source offset. Audio-only Takes remain represented so the
+consumer can choose the streams it displays. This projection makes no layout or layering decisions;
+Media and custom visual components can consume the same prepared performance.

package/packages/semantic-track/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@hypit/semantic-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/media": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/speech": "workspace:*"
+  }
+}

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

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

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

@@ -0,0 +1,24 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+
+import { semanticTrackProducers, semanticTrackTypes } from "./manifest.js";
+import { assertSemanticTrackIdentity } from "./identity.js";
+import { projectSemanticAudioTrack, projectSemanticProgramSpace } from "./projection.js";
+import type { SemanticTrack } from "./types.js";
+
+function track(value: StoredValue | undefined): SemanticTrack {
+  if (value?.kind !== "inline") throw new Error("SemanticTrack must be inline.");
+  return value.value as unknown as SemanticTrack;
+}
+
+export const semanticTrackComponent = {
+  producers: [
+    { producer: semanticTrackProducers.projectProgramSpace, handler: ({ inputs }) => ({ outputs: { space: { kind: "inline", value: canonicalize(projectSemanticProgramSpace(track(inputs.track?.value))) } }, needs: {} }) },
+    { producer: semanticTrackProducers.projectAudio, handler: ({ inputs }) => ({ outputs: { audio: { kind: "inline", value: canonicalize(projectSemanticAudioTrack(track(inputs.track?.value))) } }, needs: {} }) },
+  ],
+  validators: [{
+    type: semanticTrackTypes.track,
+    handler: ({ value }) => assertSemanticTrackIdentity(track(value)),
+  }],
+} satisfies ComponentPackage;