@hypit/hypit 0.0.1 → 0.1.0

package/packages/video-cli/src/package-selection.ts

@@ -0,0 +1,34 @@
+import { discoverSourcePackages } from "@hypit/cli";
+import {
+  createMarkupAuthorFrontend,
+  MarkupSurfaceRegistry,
+} from "@hypit/markup";
+import type { LoadedPackage } from "@hypit/package-loader-node";
+
+const markupFrontend = createMarkupAuthorFrontend({
+  registry: new MarkupSurfaceRegistry(),
+  resolveModule(request) {
+    throw new Error(`Markup discovery unexpectedly resolved Module ${request.from}`);
+  },
+});
+
+/** Video Distribution bootstrap: generic Source discovery plus the bare Markup Frontend. */
+export async function discoverVideoSourcePackages(
+  sourcePath: string,
+  options: {
+    readonly workspaceRoot?: string;
+    readonly packageRoot?: string;
+    readonly distributionPackageRoot?: string;
+    readonly packages?: readonly LoadedPackage[];
+  } = {},
+) {
+  return await discoverSourcePackages(sourcePath, {
+    ...(options.workspaceRoot === undefined ? {} : { workspaceRoot: options.workspaceRoot }),
+    ...(options.packageRoot === undefined ? {} : { packageRoot: options.packageRoot }),
+    ...(options.distributionPackageRoot === undefined
+      ? {}
+      : { distributionPackageRoot: options.distributionPackageRoot }),
+    ...(options.packages === undefined ? {} : { packages: options.packages }),
+    bootstrapAuthorFrontends: [markupFrontend],
+  });
+}

package/packages/video-cli/src/process.ts

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+
+type ProcessInput = Uint8Array | Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
+type ProcessOutput = { readonly stdout: Buffer; readonly stderr: string };
+
+function run(
+  executable: string,
+  args: readonly string[],
+  input: ProcessInput | undefined,
+  timeoutMs: number,
+): Promise<ProcessOutput> {
+  return new Promise((resolveRun, reject) => {
+    const child = spawn(executable, [...args], { stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], windowsHide: true });
+    const out: Buffer[] = [];
+    let err = "";
+    let settled = false;
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error === undefined) resolveRun({ stdout: Buffer.concat(out), stderr: err });
+      else reject(error);
+    };
+    const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new Error(`${executable} timed out after ${timeoutMs} ms`)); }, timeoutMs);
+    child.stdout?.on("data", (chunk: Buffer) => out.push(chunk));
+    child.stderr?.on("data", (chunk: Buffer) => { err = `${err}${chunk.toString("utf8")}`.slice(-100_000); });
+    child.on("error", (error) => finish(new Error(`${executable} could not start: ${error.message}`)));
+    child.on("close", (code) => {
+      if (code === 0) finish();
+      else finish(new Error(`${executable} exited with ${code}: ${err.trim()}`));
+    });
+    if (input !== undefined && child.stdin !== null) {
+      child.stdin.on("error", (error: NodeJS.ErrnoException) => {
+        if (error.code !== "EPIPE") finish(new Error(`${executable} input failed: ${error.message}`));
+      });
+      void (async () => {
+        const chunks: Iterable<Uint8Array> | AsyncIterable<Uint8Array> = input instanceof Uint8Array ? [input] : input;
+        for await (const chunk of chunks) {
+          if (!child.stdin!.write(chunk)) await once(child.stdin!, "drain");
+        }
+        child.stdin!.end();
+      })().catch((error: unknown) => {
+        if (!(error instanceof Error && "code" in error && error.code === "EPIPE")) {
+          child.kill("SIGKILL");
+          finish(error instanceof Error ? error : new Error(String(error)));
+        }
+      });
+    }
+  });
+}
+
+/** Run one external program to completion and return its stdout; stderr becomes the error text. */
+export async function runProcess(executable: string, args: readonly string[], timeoutMs = 300_000): Promise<Buffer> {
+  return (await run(executable, args, undefined, timeoutMs)).stdout;
+}
+
+/** Successful stderr can carry tool metadata, such as the timestamp of an extracted frame. */
+export function runProcessOutput(executable: string, args: readonly string[], timeoutMs = 300_000): Promise<ProcessOutput> {
+  return run(executable, args, undefined, timeoutMs);
+}
+
+/** The same process boundary when a deterministic byte stream is one of the program's inputs. */
+export async function runProcessWithInput(
+  executable: string,
+  args: readonly string[],
+  input: ProcessInput,
+  timeoutMs = 300_000,
+): Promise<Buffer> {
+  return (await run(executable, args, input, timeoutMs)).stdout;
+}

package/packages/video-cli/src/studio-distribution.ts

@@ -0,0 +1,19 @@
+/**
+ * Studio Companions carried by the official video distribution.
+ *
+ * This is distribution policy, not Studio discovery policy: a different video
+ * distribution may assemble a different set without changing Studio itself.
+ */
+export const videoStudioCompanionPackages = [
+  "@hypit/audio-track-studio",
+  "@hypit/caption-fine-studio",
+  "@hypit/comment-sticker-studio",
+  "@hypit/deck-track-studio",
+  "@hypit/film-studio",
+  "@hypit/media-track-studio",
+  "@hypit/ranking-studio",
+  "@hypit/screen-overlay-studio",
+  "@hypit/script-studio",
+  "@hypit/speech-track-studio",
+  "@hypit/typography-track-studio",
+] as const;

package/packages/video-cli/src/transcript.ts

@@ -0,0 +1,71 @@
+import { readFile } from "node:fs/promises";
+
+/** The seconds-based file written by `hypit transcribe`. Missing word times stay missing. */
+export type TranscriptWord = {
+  readonly text: string;
+  readonly start?: number;
+  readonly end?: number;
+};
+export type FrameWords = {
+  readonly active: readonly TranscriptWord[];
+  readonly context: readonly TranscriptWord[];
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export async function readTranscript(path: string): Promise<readonly TranscriptWord[]> {
+  const raw = JSON.parse(await readFile(path, "utf8"));
+  assert(raw?.format === "hypit.transcript@1" && Array.isArray(raw.passages), `${path}: expected hypit.transcript@1`);
+  return raw.passages.flatMap((passage: { words?: unknown }) => {
+    assert(passage !== null && Array.isArray(passage.words), `${path}: each passage needs words`);
+    return passage.words.map((word: Record<string, unknown>) => {
+      assert(word !== null && typeof word.text === "string", `${path}: each word needs text`);
+      const start = word.start_seconds;
+      const end = word.end_seconds;
+      assert(start === undefined || (typeof start === "number" && Number.isFinite(start) && start >= 0), `${path}: invalid word start`);
+      assert(end === undefined || (typeof end === "number" && Number.isFinite(end) && end >= 0), `${path}: invalid word end`);
+      assert(start === undefined || end === undefined || end >= start, `${path}: word end precedes start`);
+      return { text: word.text, ...(start === undefined ? {} : { start }), ...(end === undefined ? {} : { end }) };
+    });
+  });
+}
+
+export function wordsAt(words: readonly TranscriptWord[], at: number): FrameWords {
+  const active = words.filter((word) => word.start !== undefined && word.end !== undefined && word.start <= at && at < word.end);
+  let anchor = active.length > 0 ? words.indexOf(active[0]!) : -1;
+  if (anchor < 0) {
+    let distance = Infinity;
+    for (const [index, word] of words.entries()) {
+      const time = word.start ?? word.end;
+      if (time !== undefined && Math.abs(time - at) < distance) { anchor = index; distance = Math.abs(time - at); }
+    }
+  }
+  const last = active.length > 0 ? words.indexOf(active.at(-1)!) : anchor;
+  return { active, context: anchor < 0 ? [] : words.slice(Math.max(0, anchor - 3), last + 4) };
+}
+
+function searchable(text: string): string {
+  return text.normalize("NFKC").toLowerCase().replace(/[\p{P}\p{Z}\s]/gu, "");
+}
+
+/** Find whole, consecutive transcript words; punctuation and case do not affect matching. */
+export function phraseRanges(words: readonly TranscriptWord[], text: string): readonly { start: number; end: number }[] {
+  const query = searchable(text);
+  assert(query.length > 0, "--around needs a word or phrase");
+  const matches: { start: number; end: number }[] = [];
+  for (let first = 0; first < words.length; first += 1) {
+    if (searchable(words[first]!.text).length === 0) continue;
+    let joined = "";
+    for (let last = first; last < words.length && joined.length < query.length; last += 1) {
+      joined += searchable(words[last]!.text);
+      if (joined !== query) continue;
+      const start = words[first]!.start;
+      const end = words[last]!.end;
+      assert(start !== undefined && end !== undefined, `The phrase ${JSON.stringify(text)} has missing boundary times; inspect its passage and choose --start/--end`);
+      matches.push({ start, end });
+    }
+  }
+  return matches;
+}

package/packages/video-cli/src/vocabulary.ts

@@ -0,0 +1,386 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import type { CliIo } from "@hypit/cli";
+import {
+  animatableLocalStyles,
+  visualProgramSchema, visualBoxSchema, visualElementSchema, visualImageSchema, visualMaskSchema, visualPathCommandSchema,
+  visualSurfaceSchema, visualTextDocumentSchema, visualTextFlowSchema, visualTextPaintSchema,
+  visualTextSchema, visualTextTypographySchema, visualTrackSchema, visualVideoSchema,
+} from "@hypit/composition";
+import { markupSurfaceHostFacetAbi } from "@hypit/markup";
+import type {
+  RegisteredSurface,
+  SurfaceAttributeVocabulary,
+  SurfacePortVocabulary,
+  SurfaceVocabulary,
+} from "@hypit/markup";
+import { exactModelHostAbi } from "@hypit/model-kit";
+import { loadNodePackageSelection, locateNodePackage } from "@hypit/package-loader-node";
+import type { NodePackageLoadOptions } from "@hypit/package-loader-node";
+import type { ValueSchema } from "@hypit/protocol";
+import { VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1 } from "@hypit/visual-ir";
+
+import { videoCliDistribution } from "./distribution.js";
+
+/**
+ * What a Source may write: the installed packages, and the Surfaces each one declares.
+ *
+ * The manifest is the authority; this prints it. A system you never inspected is a system you are
+ * about to invent, so the listing shows every scope and the project's own `packages/`, and a named
+ * package answers with its own Surfaces only, not with everything it happens to depend on.
+ */
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+async function nearestPackageRoot(start: string): Promise<string> {
+  let directory = resolve(start);
+  while (true) {
+    if (await stat(resolve(directory, "package.json")).then((item) => item.isFile(), () => false)) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) return resolve(start);
+    directory = parent;
+  }
+}
+
+function loading(): NodePackageLoadOptions {
+  return videoCliDistribution.packageRoot === undefined ? {} : { fallbackRoots: [videoCliDistribution.packageRoot] };
+}
+
+async function readJson<T>(path: string): Promise<T | undefined> {
+  try { return JSON.parse(await readFile(path, "utf8")) as T; } catch { return undefined; }
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Listing
+
+export type PackageListing = {
+  readonly name: string;
+  readonly description?: string;
+  readonly tags: readonly string[];
+  readonly models?: readonly string[];
+  readonly unreadable?: string;
+};
+
+export async function listPackages(projectRoot: string): Promise<readonly PackageListing[]> {
+  // Every scope, and the project's own directory, from both the project's node_modules and the
+  // Distribution's: the packages a project does not carry are in the Distribution, and the ones it
+  // does are beside it.
+  const roots = [...new Set([
+    join(projectRoot, "node_modules"),
+    ...(videoCliDistribution.packageRoot === undefined ? [] : [join(videoCliDistribution.packageRoot, "node_modules")]),
+  ])];
+  const candidates: { readonly name: string; readonly directory: string }[] = [];
+  for (const modules of roots) {
+    const scopes = (await readdir(modules, { withFileTypes: true }).catch(() => []))
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith("@"))
+      .map((entry) => entry.name)
+      .sort();
+    for (const scope of scopes) {
+      for (const inside of (await readdir(join(modules, scope)).catch(() => [] as string[])).sort()) {
+        const name = `${scope}/${inside}`;
+        if (!candidates.some((item) => item.name === name)) candidates.push({ name, directory: join(modules, scope, inside) });
+      }
+    }
+  }
+  // A project's own packages are its `packages/<name>/`, where the loader finds them by name whether
+  // or not a package manager linked them.
+  for (const entry of (await readdir(join(projectRoot, "packages")).catch(() => [] as string[])).sort()) {
+    const directory = join(projectRoot, "packages", entry);
+    const own = await readJson<{ readonly name?: string }>(join(directory, "package.json"));
+    if (own?.name !== undefined && !candidates.some((item) => item.name === own.name)) candidates.push({ name: own.name, directory });
+  }
+  const listing: PackageListing[] = [];
+  for (const { name, directory } of candidates) {
+    const manifest = await readJson<{ readonly hypit?: { readonly activation?: string }; readonly description?: string }>(join(directory, "package.json"));
+    if (manifest?.hypit?.activation === undefined) continue;
+    const tags: string[] = [];
+    const models: string[] = [];
+    let unreadable: string | undefined;
+    try {
+      for (const pack of await loadNodePackageSelection([name], projectRoot, loading())) {
+        for (const facet of pack.contribution.hostFacets ?? []) {
+          if (facet.abi === markupSurfaceHostFacetAbi) tags.push((facet.implementation as RegisteredSurface).tag);
+          else if (facet.abi === exactModelHostAbi) models.push(...(facet as { readonly offers?: readonly string[] }).offers ?? []);
+        }
+      }
+    } catch (error) { unreadable = error instanceof Error ? error.message : String(error); }
+    listing.push({
+      name,
+      ...(manifest.description === undefined ? {} : { description: manifest.description }),
+      tags: [...new Set(tags)].sort(),
+      ...(models.length === 0 ? {} : { models: [...new Set(models)].sort() }),
+      ...(unreadable === undefined ? {} : { unreadable }),
+    });
+  }
+  return listing;
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Surfaces
+
+export type SurfaceListing = {
+  readonly package: string;
+  readonly module: RegisteredSurface["module"];
+  readonly surface: string;
+  readonly tag: string;
+  readonly mode: RegisteredSurface["mode"];
+  readonly outputs: RegisteredSurface["outputs"];
+  readonly vocabulary?: unknown;
+  readonly readme?: string;
+};
+
+function printableVocabulary(value: SurfaceVocabulary | undefined): unknown {
+  if (value === undefined) return undefined;
+  // The poster is a file the manifest opens; the listing names it and does not read it.
+  return { ...value, ...(value.preview === undefined ? {} : { preview: { mediaType: value.preview.mediaType, path: value.preview.path } }) };
+}
+
+function readmePath(name: string, projectRoot: string): string | undefined {
+  try {
+    const located = locateNodePackage(name, {
+      from: join(projectRoot, "__hypit_vocabulary__.mjs"),
+      workspaceRoots: [projectRoot],
+      ...(videoCliDistribution.packageRoot === undefined ? {} : { distributionRoots: [videoCliDistribution.packageRoot] }),
+    });
+    return join(located.root, "README.md");
+  } catch { return undefined; }
+}
+
+export async function listSurfaces(projectRoot: string, packages: readonly string[], tags?: readonly string[]): Promise<readonly SurfaceListing[]> {
+  assert(packages.length > 0, "name at least one package");
+  const loaded = await loadNodePackageSelection(packages, projectRoot, loading());
+  const named = new Set(packages);
+  const wanted = tags === undefined ? undefined : new Set(tags);
+  const surfaces: SurfaceListing[] = [];
+  for (const pack of loaded) {
+    // Loading a package brings its dependencies with it; the answer is about the ones named.
+    if (!named.has(pack.specifier)) continue;
+    for (const facet of pack.contribution.hostFacets ?? []) {
+      if (facet.abi !== markupSurfaceHostFacetAbi) continue;
+      const surface = facet.implementation as RegisteredSurface;
+      if (wanted !== undefined && !wanted.has(surface.tag) && !wanted.has(surface.surface)) continue;
+      const readme = readmePath(pack.specifier, projectRoot);
+      surfaces.push({
+        package: pack.specifier,
+        module: surface.module,
+        surface: surface.surface,
+        tag: surface.tag,
+        mode: surface.mode,
+        outputs: surface.outputs,
+        ...(surface.vocabulary === undefined ? {} : { vocabulary: printableVocabulary(surface.vocabulary) }),
+        ...(readme === undefined ? {} : { readme }),
+      });
+    }
+  }
+  return surfaces;
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Visual schema, for a component that draws
+
+/** Render a declared value shape as prose an author can act on. */
+export function describeSchema(schema: ValueSchema, indent = ""): string[] {
+  const step = `${indent}  `;
+  switch (schema.kind) {
+    case "object": {
+      const lines: string[] = [];
+      for (const [name, field] of Object.entries(schema.fields)) {
+        const inner = describeSchema(field.schema, step);
+        lines.push(`${indent}${name}${field.optional === true ? " (optional)" : ""}: ${inner[0]!.trimStart()}`, ...inner.slice(1));
+      }
+      if (schema.allowUnknown === true) lines.push(`${indent}… further fields are admitted`);
+      return lines;
+    }
+    case "oneOf": {
+      const pinned = schema.variants.map((variant) => {
+        if (variant.kind !== "object") return undefined;
+        const literal = Object.entries(variant.fields).find(([, field]) => field.schema.kind === "literal");
+        return literal === undefined ? undefined : String((literal[1].schema as { value: unknown }).value);
+      });
+      return [pinned.every((value) => value !== undefined) ? `${indent}one of ${pinned.join(", ")}` : `${indent}one of ${schema.variants.length} shapes`];
+    }
+    case "array": return [`${indent}a list${schema.minItems === undefined ? "" : ` (at least ${schema.minItems})`} of:`, ...describeSchema(schema.items, step)];
+    case "string": return [schema.enum !== undefined ? `${indent}one of ${schema.enum.join(", ")}` : `${indent}${schema.minLength === undefined ? "text" : `text, at least ${schema.minLength} characters`}`];
+    case "number": {
+      const parts = [schema.integer === true ? "a whole number" : "a number"];
+      if (schema.minimum !== undefined) parts.push(`at least ${schema.minimum}`);
+      if (schema.maximum !== undefined) parts.push(`at most ${schema.maximum}`);
+      return [`${indent}${parts.join(", ")}`];
+    }
+    case "literal": return [`${indent}exactly ${JSON.stringify(schema.value)}`];
+    case "boolean": return [`${indent}true or false`];
+    case "null": return [`${indent}null`];
+    default: return [`${indent}${(schema as { kind: string }).kind}`];
+  }
+}
+
+const VISUAL_SHAPES: Readonly<Record<string, ValueSchema>> = {
+  "visual-track": visualTrackSchema,
+  "visual-element": visualElementSchema,
+  program: visualProgramSchema,
+  box: visualBoxSchema,
+  mask: visualMaskSchema,
+  text: visualTextSchema,
+  image: visualImageSchema,
+  video: visualVideoSchema,
+  surface: visualSurfaceSchema,
+  "text-flow": visualTextFlowSchema,
+  "text-typography": visualTextTypographySchema,
+  "text-paint": visualTextPaintSchema,
+  "text-document": visualTextDocumentSchema,
+  "path-command": visualPathCommandSchema,
+};
+
+// Each of these is refused somewhere in composition, or follows from how the emitted CSS is written.
+const VISUAL_RULES = [
+  "A Present holds exactly one element with no `parent`; every other element names one, and it must be a box, mask or program.",
+  "`order` is unique across the whole Present, not among siblings.",
+  "A child's position is measured from its parent's box, not from the Canvas.",
+  "An animation carries at least two keyframes, and every keyframe of one animation declares the same properties; `atFrame` is Present-relative.",
+  "A plain text element provides exact ordered font artifacts and cannot combine them with raw `font`, `font-family`, `font-style`, `font-synthesis` or `font-weight` styles.",
+  "A text element using glyph Paint cannot also declare raw stroke or paint-order styles.",
+  "A media element's artifact media type must match image/video, and still images cannot carry sampling.",
+  "A Surface with still timing cannot carry sampling; frame-based Surface sampling must match its typed timing.",
+  "Mask roots must be direct children of one Present and both mask/content references must resolve to owned elements.",
+] as const;
+
+export function visualSchema(shape?: string): {
+  readonly shapes: readonly { readonly shape: string; readonly describes: string }[];
+  readonly animatableLocalStyles: readonly string[];
+  readonly styleNames: readonly string[];
+  readonly styleEnumValues: typeof VISUAL_STYLE_ENUM_VALUES_V1;
+  readonly rules: readonly string[];
+} {
+  const asked = shape?.trim();
+  assert(asked === undefined || asked.length === 0 || Object.hasOwn(VISUAL_SHAPES, asked), `shape must be one of ${Object.keys(VISUAL_SHAPES).join(", ")}`);
+  const chosen = asked === undefined || asked.length === 0 ? Object.keys(VISUAL_SHAPES) : [asked];
+  return {
+    shapes: chosen.map((name) => ({ shape: name, describes: describeSchema(VISUAL_SHAPES[name]!).join("\n") })),
+    animatableLocalStyles: [...animatableLocalStyles],
+    styleNames: [...VISUAL_STYLE_NAMES_V1],
+    styleEnumValues: VISUAL_STYLE_ENUM_VALUES_V1,
+    rules: VISUAL_RULES,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Command
+
+function attributeLine(attribute: SurfaceAttributeVocabulary): string {
+  const shape = attribute.values !== undefined ? attribute.values.join(" | ")
+    : attribute.accepts !== undefined ? attribute.accepts.map((type) => type.name).join(" | ")
+    : attribute.kind;
+  return `      ${attribute.name}${attribute.required ? "" : "?"}  ${shape}  ${attribute.summary}`;
+}
+
+function moduleSpecifier(surface: SurfaceListing): string {
+  return `${surface.module.name}@${surface.module.version}`;
+}
+
+function sourceImport(surface: SurfaceListing, vocabulary: SurfaceVocabulary): string {
+  const prefixedTag = vocabulary.example.match(/<([A-Za-z_][A-Za-z0-9_.-]*):([A-Za-z_][A-Za-z0-9_.-]*)\b/u);
+  const alias = prefixedTag?.[2] === surface.tag ? prefixedTag[1] : undefined;
+  return alias === undefined
+    ? `<import from="${moduleSpecifier(surface)}"/>`
+    : `<import as="${alias}" from="${moduleSpecifier(surface)}"/>`;
+}
+
+function portLine(port: SurfacePortVocabulary): string {
+  const type = `${port.type.name} (${port.type.module.name}@${port.type.module.version})`;
+  return `      ${port.name}  ${type}  ${port.summary}`;
+}
+
+function surfaceText(surface: SurfaceListing): string {
+  const vocabulary = surface.vocabulary as SurfaceVocabulary | undefined;
+  const lines = [
+    `  <${surface.tag}>  ${surface.mode}`,
+    `    package  ${surface.package}`,
+    `    module   ${moduleSpecifier(surface)}`,
+  ];
+  if (vocabulary !== undefined) {
+    lines.push(`    import   ${sourceImport(surface, vocabulary)}`);
+    lines.push(`    ${vocabulary.summary}`);
+    if (vocabulary.appearance !== undefined) lines.push(`    ${vocabulary.appearance}`);
+    if (vocabulary.attributes.length > 0) lines.push("    attributes", ...vocabulary.attributes.map(attributeLine));
+    for (const child of vocabulary.children ?? []) {
+      lines.push(`    child <${child.tag}> (${child.cardinality})  ${child.summary}`, ...(child.attributes ?? []).map(attributeLine));
+    }
+    if (vocabulary.ports !== undefined && vocabulary.ports.length > 0) {
+      lines.push("    ports", ...vocabulary.ports.map(portLine));
+    }
+    lines.push("    example", ...vocabulary.example.split("\n").map((line) => `      ${line}`));
+    for (const note of vocabulary.notes ?? []) lines.push(`    note: ${note}`);
+  }
+  if (surface.readme !== undefined) lines.push(`    README ${surface.readme}`);
+  return lines.join("\n");
+}
+
+export function writeVocabularyHelp(io: CliIo): void {
+  io.write([
+    "hypit vocabulary",
+    "What a Source may write. Prints installed package manifests; no Runtime Profile, no request, no state.",
+    "",
+    "  hypit vocabulary                         every installed package with its tags and models",
+    "  hypit vocabulary <package…> [--tag <tag>] the Surfaces a package declares: module, import, attributes, children, ports, example",
+    "  hypit vocabulary --visual [<shape>]      the value shapes and rules a drawing Producer must emit",
+    "",
+    "Read the package README the listing names before writing its elements. Add --json for a machine view.",
+    "",
+  ].join("\n"));
+}
+
+export async function runVocabularyCli(argv: readonly string[], io: CliIo, cwd = process.cwd()): Promise<void> {
+  const rest = argv.slice(1);
+  if (rest.includes("--help")) { writeVocabularyHelp(io); return; }
+  const json = rest.includes("--json");
+  const words = rest.filter((item) => item !== "--json" && item !== "--debug" && item !== "--verbose" && item !== "--no-color");
+  const projectRoot = await nearestPackageRoot(cwd);
+
+  if (words[0] === "--visual") {
+    const shape = words[1];
+    assert(words.length <= 2, "hypit vocabulary --visual takes at most one shape name");
+    const schema = visualSchema(shape);
+    if (json) { io.write(`${JSON.stringify(schema, null, 2)}\n`); return; }
+    io.write(`${schema.shapes.map((item) => `${item.shape}\n${item.describes.split("\n").map((line) => `  ${line}`).join("\n")}`).join("\n\n")}\n\n`
+      + `animatable local styles: ${schema.animatableLocalStyles.join(", ")}\nstyle names: ${schema.styleNames.join(", ")}\n\nrules\n${schema.rules.map((rule) => `  ${rule}`).join("\n")}\n`);
+    return;
+  }
+
+  const tags: string[] = [];
+  const packages: string[] = [];
+  for (let index = 0; index < words.length; index += 1) {
+    const word = words[index]!;
+    if (word === "--tag") {
+      const value = words[index + 1];
+      assert(value !== undefined && !value.startsWith("--"), "--tag requires a value");
+      tags.push(value);
+      index += 1;
+    } else {
+      assert(!word.startsWith("--"), `unknown option ${word}`);
+      packages.push(word);
+    }
+  }
+
+  if (packages.length === 0) {
+    assert(tags.length === 0, "--tag narrows a named package; name the package first");
+    const listing = await listPackages(projectRoot);
+    if (json) { io.write(`${JSON.stringify({ projectRoot, packages: listing }, null, 2)}\n`); return; }
+    assert(listing.length > 0, `no Hypit packages installed under ${projectRoot} or the Distribution`);
+    io.write(`${listing.map((item) => {
+      const parts = [item.name];
+      if (item.tags.length > 0) parts.push(`tags: ${item.tags.join(", ")}`);
+      if (item.models !== undefined) parts.push(`models: ${item.models.join(", ")}`);
+      if (item.unreadable !== undefined) parts.push(`unreadable: ${item.unreadable}`);
+      return `${parts.join("\n    ")}${item.description === undefined ? "" : `\n    ${item.description}`}`;
+    }).join("\n")}\n`);
+    return;
+  }
+
+  const surfaces = await listSurfaces(projectRoot, packages, tags.length === 0 ? undefined : tags);
+  if (json) { io.write(`${JSON.stringify({ projectRoot, packages, surfaces }, null, 2)}\n`); return; }
+  assert(surfaces.length > 0, `${packages.join(", ")} ${packages.length === 1 ? "declares" : "declare"} no Markup Surface${tags.length === 0 ? "" : ` tagged ${tags.join(", ")}`}`);
+  io.write(`${surfaces.map(surfaceText).join("\n\n")}\n`);
+}

package/packages/visual-ir/README.md

@@ -0,0 +1,36 @@
+# `@hypit/visual-ir`
+
+The terminal visual vocabulary includes structural elements and explicit renderer-program payloads.
+HyperFrames renders both structural elements and its browser program format.
+
+## Writing a visual program
+
+`VISUAL_IR_V1` identifies the supported visual vocabulary. A component emits ordinary Track,
+Present and element data through `@hypit/composition`. The exported constants
+`VISUAL_STYLE_NAMES_V1` and `VISUAL_STYLE_ENUM_VALUES_V1` describe supported CSS-shaped declarations;
+`assertVisualStyleV1` checks an individual property/value pair. Element schemas are exposed by
+`hypit vocabulary --visual <kind>`.
+
+Static style values are strings or numbers. Resource-bearing image, video and text elements carry
+their actual artifacts or font references as fields. Parents are local to one Present, and child
+coordinates are relative to their parent.
+
+An element may have an `animation` with ordered `keyframes`. Each keyframe has `atFrame`, optional
+`easing`, and `style`. `atFrame` is measured from the containing Present's start. Supported animated
+properties are `opacity`, `transform`, `filter`, `backdrop-filter` and `clip-path`; easing is `linear`, `ease-in`,
+`ease-out` or `ease-in-out`. A renderer can evaluate these values at any requested frame.
+
+Video playback uses the element's separate `sampling` map. Its local target intervals select source
+frame positions and rates, with explicit loops or held frames where wanted. Typography can carry
+richer text layout and unit motion through the text-flow/path-text shapes.
+
+For prepared pixels from another rendering tool, emit a `surface` element with a typed
+CompositableSurfaceRef. Its resource, geometry, color/alpha and temporal metadata let composition
+place and sample it through the same Track model. Local masks name their owned content and mask
+children. Preparation that transforms another material receives that material as an explicit input.
+
+A `program` element carries an explicit format, an object payload and referenced artifacts. The
+rendering package owns that payload's language and execution. It can place owned structural children
+inside a local program, retaining typed media and fonts. For browser HTML/CSS/JavaScript see
+[HyperFrames](../hyperframes/README.md#local-browser-programs). This separates structural convenience
+from the renderer's fuller composition capabilities.

package/packages/visual-ir/package.json

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

package/packages/visual-ir/src/activation.ts

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

package/packages/visual-ir/src/index.ts

@@ -0,0 +1,7 @@
+import type { ModuleManifest } from "@hypit/protocol";
+export { assertVisualStyleV1, VISUAL_IR_V1, VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1 } from "./style.js";
+export type * from "./style.js";
+export const visualIrModuleRef = { name: "@hypit/visual-ir", version: "1" } as const;
+export const visualIrManifest: ModuleManifest = { format: "hypit.module@1", name: visualIrModuleRef.name, version: visualIrModuleRef.version,
+  dependencies: [], types: [], capabilities: [], producers: [] };
+export const visualIrDependency = { module: visualIrModuleRef } as const;