@hypit/hypit 0.0.1 → 0.1.0

package/packages/compiler-node/src/run.ts

@@ -0,0 +1,355 @@
+import type { WorkspaceSession } from "@hypit/workspace";
+import {
+  sliceExecution,
+  defineBuild,
+  materializeBuild,
+  planBuild,
+} from "@hypit/core";
+import type { BuildCandidateSelection } from "@hypit/core";
+import type {
+  ArtifactAttachment,
+} from "@hypit/workspace";
+import type {
+  BuildDefinition,
+  BuildState,
+  StoredValue,
+  TypeRef,
+} from "@hypit/protocol";
+import { sameType } from "@hypit/protocol";
+import {
+  collectRunModuleRequests,
+  compileRunSource,
+  resolveRunDocument,
+  sealRunGraph,
+} from "@hypit/run";
+import type {
+  RunCompilation,
+  RunFragmentRegistryLike,
+  RunFrontendRegistryLike,
+  RunSourceUnit,
+} from "@hypit/run";
+import type { LinkedProgram } from "@hypit/protocol";
+
+import type { NodeCompiledSourceClosure } from "./compiler.js";
+import { mergeAttachments, NodeCompiler } from "./compiler.js";
+
+export type NodeRunCompilerOptions = {
+  readonly authorCompiler: NodeCompiler;
+  readonly frontends: RunFrontendRegistryLike;
+  readonly fragments: RunFragmentRegistryLike;
+  readonly resolveHistoricalOutput?: (
+    build: string,
+    output: string,
+  ) => Promise<{
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+    readonly attachments?: readonly ArtifactAttachment[];
+  } | undefined>
+    | {
+      readonly type: TypeRef;
+      readonly value: StoredValue;
+      readonly attachments?: readonly ArtifactAttachment[];
+    }
+    | undefined;
+};
+
+export type NodeCompiledRun = {
+  readonly source: string;
+  readonly authorSource: string;
+  readonly author: NodeCompiledSourceClosure;
+  /** Author program rebound to the union closure required by Author and selected Run code. */
+  readonly program: LinkedProgram;
+  readonly run: RunCompilation;
+  readonly attachments: readonly ArtifactAttachment[];
+};
+
+export type NodeCheckedRun = {
+  readonly source: string;
+  readonly authorSource: string;
+  readonly author: NodeCompiledSourceClosure;
+  readonly program: LinkedProgram;
+  readonly document: RunCompilation["document"];
+  readonly unresolvedHistoricalOutputs: readonly {
+    readonly id: string;
+    readonly build: string;
+    readonly output: string;
+  }[];
+  readonly attachments: readonly ArtifactAttachment[];
+};
+
+export type PlannedBuild = {
+  readonly compilation: NodeCompiledRun;
+  /** Compiler-only explanation of how the two graphs became the execution plan. */
+  readonly selections: readonly BuildCandidateSelection[];
+  /** Whole-Output historical sources selected by the plan; Result storage may forward them directly. */
+  readonly resultForwards: readonly {
+    readonly output: string;
+    readonly build: string;
+    readonly sourceOutput: string;
+  }[];
+  /** Immutable authority persisted once for every fresh Runtime Build. */
+  readonly definition: BuildDefinition;
+  /** Materialized plan/read view; durable Stores persist Definition + Facts instead. */
+  readonly state: BuildState;
+};
+
+function decodeStoredValue(bytes: Uint8Array, from: string): StoredValue {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch (error) {
+    throw new Error(`${from} is not valid UTF-8 StoredValue JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${from} must contain one StoredValue object`);
+  }
+  return parsed as StoredValue;
+}
+
+async function attachmentBytes(attachment: ArtifactAttachment): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for await (const chunk of await attachment.open()) {
+    chunks.push(Uint8Array.from(chunk));
+    size += chunk.byteLength;
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+async function storedValueFromWorkspace(
+  workspace: WorkspaceSession,
+  source: RunSourceUnit,
+  from: string,
+): Promise<StoredValue> {
+  const resolved = await workspace.resolveAsset(source, { from, mediaType: "application/json" });
+  const attachment = (await workspace.attachments()).find((item) => item.artifact.resource === resolved.artifact.resource);
+  if (attachment === undefined) throw new Error(`Workspace did not retain bytes for ${from}`);
+  return decodeStoredValue(await attachmentBytes(attachment), from);
+}
+
+async function fileValueFromWorkspace(
+  workspace: WorkspaceSession,
+  source: RunSourceUnit,
+  from: string,
+  mediaType: string,
+): Promise<StoredValue> {
+  return (await workspace.resolveAsset(source, { from, mediaType })).artifact;
+}
+
+/** Node Host for the second, mandatory source graph. It never guesses a Frontend from a suffix. */
+export class NodeRunCompiler {
+  readonly #options: NodeRunCompilerOptions;
+
+  constructor(options: NodeRunCompilerOptions) {
+    this.#options = options;
+  }
+
+  supportsFrontend(id: string): boolean {
+    return this.#options.frontends.resolve(id) !== undefined;
+  }
+
+  async compileFile(file: string): Promise<NodeCompiledRun> {
+    const workspace = await this.#options.authorCompiler.openFile(file);
+    return await this.compileSource(workspace.entry, workspace);
+  }
+
+  /**
+   * Validate both source documents without materializing historical Build values.
+   *
+   * A future BuildRecord is valid Run intent even before that Build exists. It
+   * becomes executable only when plan/build resolves its exact historical Result value.
+   */
+  async checkSource(source: RunSourceUnit, workspace: WorkspaceSession): Promise<NodeCheckedRun> {
+    const decoded = await compileRunSource(source, this.#options.frontends);
+    const authorSource = await workspace.resolveSource(source, {
+      from: decoded.document.author.source,
+      alias: "author",
+    });
+    const author = await this.#options.authorCompiler.compileSource(authorSource, workspace);
+    const program = this.#options.authorCompiler.extendExecutionProgram(
+      author.program,
+      collectRunModuleRequests(decoded.document, this.#options.fragments),
+    );
+    const executionCompilation = program === author.program ? author : { ...author, program };
+    const structuralRun = await resolveRunDocument(decoded.document, {
+      compilation: executionCompilation,
+      fragments: this.#options.fragments,
+    });
+    const structuralPlan = planBuild(program, author.graph, structuralRun.graph);
+    const selectedLocalSources = new Set(structuralPlan.selections
+      .filter((selection) => {
+        const candidateSource = structuralRun.candidateSources[selection.candidate];
+        return candidateSource?.kind === "stored-value" || candidateSource?.kind === "file";
+      })
+      .map((selection) => selection.candidate));
+    const resolvedValues = new Map<string, StoredValue>();
+    for (const candidate of selectedLocalSources) {
+      const candidateSource = structuralRun.candidateSources[candidate]!;
+      const value = candidateSource.kind === "stored-value"
+        ? await storedValueFromWorkspace(workspace, source, candidateSource.from)
+        : candidateSource.kind === "file"
+          ? await fileValueFromWorkspace(workspace, source, candidateSource.from, candidateSource.mediaType)
+          : undefined;
+      if (value !== undefined) resolvedValues.set(candidate, value);
+    }
+    const checkedRunGraph = sealRunGraph({
+      ...structuralRun.graph,
+      candidates: structuralRun.graph.candidates.map((candidate) => {
+        const value = resolvedValues.get(candidate.id);
+        if (value === undefined) return candidate;
+        if (candidate.root.kind !== "value") throw new Error(`Run Candidate ${candidate.id} is not a zero-input value`);
+        return {
+          ...candidate,
+          root: {
+            kind: "value" as const,
+            value: { id: candidate.root.value.id, value },
+          },
+        };
+      }),
+    });
+    const checkedPlan = planBuild(program, author.graph, checkedRunGraph);
+    const admitRecord = (this.#options.authorCompiler as NodeCompiler & {
+      readonly admitRecord?: NodeCompiler["admitRecord"];
+    }).admitRecord;
+    if (typeof admitRecord === "function") {
+      const localRecordIds = new Set(checkedPlan.selections
+        .filter((selection) => selectedLocalSources.has(selection.candidate))
+        .map((selection) => selection.record));
+      for (const record of checkedRunGraph.records) localRecordIds.add(record.id);
+      for (const record of checkedPlan.initialRecords) {
+        if (localRecordIds.has(record.id)) await admitRecord.call(this.#options.authorCompiler, program, record);
+      }
+    }
+    return {
+      source: source.id,
+      authorSource: authorSource.id,
+      author,
+      program,
+      document: decoded.document,
+      unresolvedHistoricalOutputs: decoded.document.candidates.flatMap((item) => item.kind === "build-record"
+        ? [{ id: item.id, build: item.build, output: item.output }]
+        : []),
+      attachments: mergeAttachments([author.attachments, await workspace.attachments()]),
+    };
+  }
+
+  /** Compile both source graphs in one read-once Workspace session selected by the Host. */
+  async compileSource(source: RunSourceUnit, workspace: WorkspaceSession): Promise<NodeCompiledRun> {
+    const decoded = await compileRunSource(source, this.#options.frontends);
+    const authorSource = await workspace.resolveSource(source, {
+      from: decoded.document.author.source,
+      alias: "author",
+    });
+    const author = await this.#options.authorCompiler.compileSource(authorSource, workspace);
+    const program = this.#options.authorCompiler.extendExecutionProgram(
+      author.program,
+      collectRunModuleRequests(decoded.document, this.#options.fragments),
+    );
+    const executionCompilation = program === author.program ? author : { ...author, program };
+    const resolveHistoricalOutput = this.#options.resolveHistoricalOutput;
+    const buildAttachments: ArtifactAttachment[] = [];
+    const structuralRun = await resolveRunDocument(decoded.document, {
+      compilation: executionCompilation,
+      fragments: this.#options.fragments,
+    });
+    const structuralPlan = planBuild(program, author.graph, structuralRun.graph);
+    const selectedSources = new Set(structuralPlan.selections
+      .filter((selection) => structuralRun.candidateSources[selection.candidate] !== undefined)
+      .map((selection) => selection.candidate));
+    const resolvedValues = new Map<string, StoredValue>();
+    for (const candidate of selectedSources) {
+      const candidateSource = structuralRun.candidateSources[candidate]!;
+      if (candidateSource.kind === "stored-value") {
+        resolvedValues.set(candidate, await storedValueFromWorkspace(workspace, source, candidateSource.from));
+        continue;
+      }
+      if (candidateSource.kind === "file") {
+        resolvedValues.set(candidate, await fileValueFromWorkspace(
+          workspace,
+          source,
+          candidateSource.from,
+          candidateSource.mediaType,
+        ));
+        continue;
+      }
+      if (resolveHistoricalOutput === undefined) {
+        throw new Error(`Historical Build Candidate ${candidateSource.build}/${candidateSource.output} requires a project Result Store`);
+      }
+      const resolved = await resolveHistoricalOutput(candidateSource.build, candidateSource.output);
+      if (resolved === undefined) {
+        throw new Error(`Build ${candidateSource.build} has no Output ${candidateSource.output}`);
+      }
+      const declaration = structuralRun.graph.candidates.find((item) => item.id === candidate)!;
+      if (!sameType(resolved.type, declaration.type)) {
+        throw new Error(`Build ${candidateSource.build} Output ${candidateSource.output} has the wrong type for its satisfied Logical Output`);
+      }
+      resolvedValues.set(candidate, resolved.value);
+      buildAttachments.push(...(resolved.attachments ?? []));
+    }
+    const run = {
+      ...structuralRun,
+      graph: sealRunGraph({
+        ...structuralRun.graph,
+        candidates: structuralRun.graph.candidates.map((candidate) => {
+          const resolved = resolvedValues.get(candidate.id);
+          if (resolved === undefined) return candidate;
+          if (candidate.root.kind !== "value") throw new Error(`Historical Candidate ${candidate.id} is not a zero-input value`);
+          return {
+            ...candidate,
+            root: {
+              kind: "value" as const,
+              value: { id: candidate.root.value.id, value: resolved },
+            },
+          };
+        }),
+      }),
+    };
+    const admitted = planBuild(program, author.graph, run.graph);
+    const admitRecord = (this.#options.authorCompiler as NodeCompiler & {
+      readonly admitRecord?: NodeCompiler["admitRecord"];
+    }).admitRecord;
+    if (typeof admitRecord === "function") {
+      for (const record of admitted.initialRecords) {
+        await admitRecord.call(this.#options.authorCompiler, program, record);
+      }
+    }
+    return {
+      source: source.id,
+      authorSource: authorSource.id,
+      author,
+      program,
+      run,
+      attachments: mergeAttachments([author.attachments, await workspace.attachments(), buildAttachments]),
+    };
+  }
+
+  planCompilation(compilation: NodeCompiledRun): PlannedBuild {
+    const sliced = sliceExecution(compilation.program, compilation.author.graph, compilation.run.graph);
+    const definition = defineBuild({
+      program: sliced.program,
+      initialRecords: sliced.initialRecords,
+      plan: sliced.plan,
+      targets: sliced.targets,
+    });
+    const state = materializeBuild(definition, []);
+    const resultForwards = sliced.selections.flatMap((selection) => {
+      const source = compilation.run.candidateSources[selection.candidate];
+      return source?.kind !== "build-output" ? [] : [{
+        output: selection.output,
+        build: source.build,
+        sourceOutput: source.output,
+      }];
+    });
+    return { compilation, selections: sliced.selections, resultForwards, definition, state };
+  }
+
+  async planFile(file: string): Promise<PlannedBuild> {
+    return this.planCompilation(await this.compileFile(file));
+  }
+}

package/packages/component-kit/README.md

@@ -0,0 +1,97 @@
+# `@hypit/component-kit`
+
+The minimal host-neutral SDK for trusted deterministic compute components. A package exports
+enumerable Producer and Type-owner Validator facets. Both identities are data: an exact nominal
+reference plus handler. Hosts enumerate them without running an opaque `install()` callback.
+Producer handlers receive only the
+Core command, Producer identity and immutable typed inputs.
+
+They receive no ResourceStore, credentials, network client, queue or Runtime infrastructure. Work that
+needs those authorities must emit an explicit Need and be implemented by a separately selected
+Endpoint package. `@hypit/driver-node` implements the structural registrar but is not part of this
+SDK.
+
+This is dependency inversion, not a sandbox. Until components run in an isolated Worker, selected
+JavaScript packages remain trusted code and may still possess ambient authority from their process.
+
+## Wiring a project Author Package
+
+A component normally lives in the video's `packages/` and is installed through that project's
+ordinary package manager. Use the owner's scope, such as `@studio/score-strip`; the active
+Distribution reserves `@hypit/*`. A Source imports the package's logical Module ABI, for example
+`<import as="score" from="@studio/score-strip@1"/>`. That `1` is not its npm release version.
+
+External Author Packages use the released Distribution's public subpaths. The small framework-facing
+surface is `@hypit/hypit/author-kit`; domain values continue to come from their own owners:
+
+| Owner | Interface |
+| --- | --- |
+| `@hypit/hypit/author-kit` | Module declarations, deterministic handlers, sealed Fragments and Markup Surface handlers |
+| `@hypit/hypit/temporal-markup` | author-time semantic Window/Instant projection helpers |
+| `@hypit/hypit/composition`, `@hypit/hypit/visual-ir` | peer Track values and renderer-independent visual representation |
+| `@hypit/hypit/studio-adapter` (optional, in Companion code) | editor entity projection, Inspector bindings and executed temporal lineage |
+
+The Author Package keeps one development dependency on `@hypit/hypit`, compiles its activation to
+JavaScript, and publishes only its own files. The active Distribution supplies these subpaths at
+execution, so a component does not carry a second Core or choose its own framework version. This
+package remains the internal deterministic-handler owner; `@hypit/hypit/author-kit` is the deliberately
+small public composition boundary, not a facade for every video domain.
+
+An ESM package names its activation entry in `package.json`, for example
+`"hypit": { "activation": "./dist/activation.js" }`. The built files, preview assets and package
+dependencies must actually be included. A TypeScript entry can be used when the selected development
+Host supports it; a compiled JavaScript entry avoids depending on a TypeScript loader.
+
+The activation module connects the implementation pieces; this is a wiring excerpt, assuming the
+local Manifest, ComponentPackage and Surface declarations/handlers already exist:
+
+```ts
+import { createMarkupSurfaceHostFacet } from "@hypit/hypit/author-kit";
+import { manifest, moduleRef, surfaces } from "./manifest.js";
+import { component } from "./component.js";
+import { decodeTrack } from "./surface.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest }],
+  components: [component],
+  hostFacets: surfaces.map((declaration) => createMarkupSurfaceHostFacet({
+    module: moduleRef, declaration, handler: decodeTrack,
+  })),
+};
+export default hypitPackage;
+```
+
+If several Surfaces have different handlers, bind each declaration to its actual handler instead of
+mapping them all to `decodeTrack`. Surface metadata is registered through the Markup Host facet;
+it does not make Markup syntax part of the semantic Module Manifest.
+
+Structured handlers return `records`, `components`, `fragments` and optionally explicit `exports`.
+A resolved input contains its nominal `type` and graph `ref`; only authored values necessarily carry
+an inline `record`. A future generated image has a reference, not image bytes available during
+Source compilation. Decode Recipes or Styles from inline authored values, and retain produced
+inputs as graph edges.
+
+Component output mappings use **Fragment export name → public Source name**. If a Fragment exports
+`track`, the mapping is ``outputs: { track: `${id}.track` }``; choosing another public name does not
+rename the Fragment port. The Manifest's Producer ports, Fragment wiring and handler output names
+must agree for that operation.
+
+Read the closest installed implementation for the behavior being authored: Emoji Reveal for a
+persistent event-driven strip, Media Track for sampling and transitions, Caption Fine for a
+schedule/render split. Their package-local files supply concrete patterns without requiring a
+monorepo checkout. A new component owns its own mechanics, not a fork of the framework loader or
+Runtime.
+
+## Optional Studio presentation
+
+A component can render through the ordinary Track protocol without custom editor behavior. When it
+needs meaningful timeline entities or Inspector fields, put a Companion in a separate file and
+merge `createStudioTrackCompanionHostFacet(companions)` into the same activation's `hostFacets`.
+Retain the existing Module, Producer and Surface contributions. The selected project's package
+supplies the extension; do not edit Studio's registry or add editor metadata to the domain Manifest.
+
+The [Studio Adapter README](../studio-adapter/README.md) owns the working declaration and activation
+example. Expose any required deterministic schedule/program values through actual Surface outputs,
+and retain the real temporal input edges. The Companion describes those facts and writable Source
+parameters; it neither renders the video nor performs Source filesystem writes.

package/packages/component-kit/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@hypit/component-kit",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/component-kit/src/index.ts

@@ -0,0 +1,155 @@
+import type {
+  BuildState,
+  CanonicalValue,
+  CapabilityRef,
+  InvokeProducerCommand,
+  ProducerRef,
+  StoredValue,
+  TypeRef,
+  TypedRecord,
+} from "@hypit/protocol";
+
+export type Awaitable<T> = T | Promise<T>;
+
+export type TypeValidatorContext = {
+  readonly type: TypeRef;
+  readonly value: StoredValue;
+};
+
+export type TypeValidatorHandler = (
+  context: TypeValidatorContext,
+) => void | Promise<void>;
+
+/** Minimal structural port implemented by a validation Host. */
+export interface TypeValidatorRegistrar {
+  register(
+    type: TypeRef,
+    handler: TypeValidatorHandler,
+  ): void;
+}
+
+export type ProducerHandlerResult = {
+  readonly outputs: Readonly<Record<string, StoredValue>>;
+  readonly needs: Readonly<Record<string, CanonicalValue>>;
+};
+
+/**
+ * Pure compute context. Artifact bytes, credentials, network and stores are deliberately absent;
+ * those effects must cross an explicit Need into a Provider.
+ */
+export type ProducerHandlerContext = {
+  readonly command: InvokeProducerCommand;
+  readonly producer: ProducerRef;
+  readonly inputs: Readonly<Record<string, TypedRecord>>;
+};
+
+export type ProducerHandler = (
+  context: ProducerHandlerContext,
+) => Awaitable<ProducerHandlerResult>;
+
+/** Minimal structural port implemented by a Producer registry. */
+export interface ProducerRegistrar {
+  registerProducer(
+    producer: ProducerRef,
+    handler: ProducerHandler,
+  ): void;
+}
+
+/** Enumerable deterministic Producer handler owned by its package. */
+export type ProducerFacet = {
+  readonly producer: ProducerRef;
+  readonly handler: ProducerHandler;
+};
+
+/** One input whose value will exist only after an upstream Build step has run. */
+export type PlannedNeedInput = {
+  readonly input: string;
+  readonly record: string;
+  readonly sourceStep?: string;
+  /** Capability-owned semantic role when the value represents media, such as image or audio. */
+  readonly role?: string;
+};
+
+/**
+ * The complete support-relevant request known before external work starts. Values produced later
+ * are represented by input slots; their eventual StoredValues are execution bindings, not missing
+ * author intent. A slot may be a Resource or a structured value.
+ */
+export type PlannedNeedSpecification = {
+  readonly constraints: CanonicalValue;
+  readonly pendingInputs: readonly PlannedNeedInput[];
+};
+
+/** Package-owned, presentation-neutral reading of one request. */
+export type PlannedNeedPresentation = {
+  readonly fields: Readonly<Record<string, readonly CanonicalValue[]>>;
+  readonly references: Readonly<Record<string, number>>;
+};
+
+export type PlannedNeedFacet = {
+  readonly producer: ProducerRef;
+  readonly port: string;
+  readonly capability: CapabilityRef;
+  plan(input: {
+    readonly state: BuildState;
+    readonly step: string;
+    readonly port: string;
+  }): PlannedNeedSpecification | undefined;
+  present?(specification: PlannedNeedSpecification): PlannedNeedPresentation;
+};
+
+/** Missing direct inputs of one planned Need, preserved as graph edges rather than guessed values. */
+export function plannedNeedInputs(
+  state: BuildState,
+  stepId: string,
+  roles: Readonly<Record<string, string>> = {},
+): readonly PlannedNeedInput[] {
+  const step = state.plan.steps.find((item) => item.id === stepId);
+  if (step === undefined) return [];
+  const available = new Set(state.records.map((record) => record.id));
+  const producedBy = new Map(state.plan.steps.flatMap((item) =>
+    Object.values(item.outputs).map((record) => [record, item.id] as const)));
+  return Object.entries(step.inputs).flatMap(([input, record]) => {
+    if (available.has(record)) return [];
+    const sourceStep = producedBy.get(record);
+    const role = roles[input];
+    return [{
+      input,
+      record,
+      ...(sourceStep === undefined ? {} : { sourceStep }),
+      ...(role === undefined ? {} : { role }),
+    }];
+  });
+}
+
+export function registerProducerFacets(
+  registry: ProducerRegistrar,
+  facets: readonly ProducerFacet[],
+): void {
+  for (const facet of facets) {
+    registry.registerProducer(facet.producer, facet.handler);
+  }
+}
+
+/** Package-owned semantic validator. */
+export type TypeValidatorFacet = {
+  readonly type: TypeRef;
+  readonly handler: TypeValidatorHandler;
+};
+
+export function registerTypeValidatorFacets(
+  registry: TypeValidatorRegistrar,
+  facets: readonly TypeValidatorFacet[],
+): void {
+  for (const facet of facets) {
+    registry.register(facet.type, facet.handler);
+  }
+}
+
+/** Trusted deterministic implementation package; it selects no Provider or Runtime infrastructure. */
+export type ComponentPackage = {
+  readonly producers?: readonly ProducerFacet[];
+  readonly validators?: readonly TypeValidatorFacet[];
+  /** Planning knowledge owned by the package that declares the external request. */
+  readonly plannedNeeds?: readonly PlannedNeedFacet[];
+};

package/packages/composition/README.md

@@ -0,0 +1,53 @@
+# `@hypit/composition`
+
+Provider-neutral visual and audio Track contracts and their final Composition.
+
+## VisualTrack
+
+`sealVisualTrack` accepts `id`, `programSpaceId`, `visualIr: VISUAL_IR_V1` and `presents` and returns
+a value with `kind: "visual"`. `assertVisualTrackIdentity(track, space)` also checks it against a
+specific ProgramSpace. Both functions are exported from this package.
+
+Each Present supplies:
+
+| Field | Meaning |
+| --- | --- |
+| `id`, optional `subjectId` | Appearance identity and, when useful, the domain entity it depicts |
+| `span` | `{ startFrame, endFrameExclusive }` in program frames |
+| `stacking` | `{ order, tieBreak }`, absolute paint order across Presents |
+| `elements` | One rooted element tree owned by the Present |
+
+Higher stacking order paints later. Element `order` values are distinct within a Present and
+determine order inside its tree. A child names
+its `parent`; its position is relative to that parent. Root positioning is relative to the Canvas.
+Animation keyframes use `atFrame` offsets from the Present's start. Media sampling targets use the
+same local frame origin and map to exact source frames.
+
+The exported `VisualElement` union covers `box`, `mask`, `text`, `text-flow`, `path-text`, `image`,
+`video`, `surface` and `program`. Text carries exact FontArtifactRef values; images and videos carry BlobRefs;
+`surface` carries a CompositableSurfaceRef. The schema and exported TypeScript types in `src/track.ts`
+give each shape. `hypit vocabulary --visual visual-track` and focused element queries expose those
+schemas through the installed Distribution.
+
+A `program` carries `{ format, payload, artifacts }`. The rendering package owns the object payload
+and supports named formats. It may place typed children in its own local structure, so video, text
+and graphics can share behavior while retaining explicit material dependencies. The parent
+relationship remains local to the Present; internal layout belongs to that program.
+
+## AudioTrack
+
+An AudioTrack contributes explicit clips with source audio artifacts, source sample ranges, target
+sample ranges, gain, fades and playback. Target positions use the ProgramSpace's canonical 48 kHz
+sample domain. Use `programSpaceSampleFrames` and the temporal/media helpers when converting an
+authored event into that domain. Source timing and target timing are separate.
+
+`sealAudioTrack` and `assertAudioTrackIdentity` are the corresponding public constructors/checks.
+An Author Package can publish visual and audio Tracks as separate Outputs; the composition includes
+each selected Output explicitly.
+
+## Composition
+
+A Composition carries its id, Canvas with clear color, and peer Tracks. The Tracks retain their
+ProgramSpace identity; assembly and rendering receive the corresponding time domain separately.
+`@hypit/film` is one author-facing way to assemble it;
+`@hypit/render-hyperframes` consumes it to produce a video.