@hypit/hypit 0.0.1 → 0.1.0

package/packages/markup/src/registry.ts

@@ -0,0 +1,83 @@
+import type { ModuleRef } from "@hypit/protocol";
+
+import type {
+  RawSurfaceDeclaration,
+  RawSurfaceHandler,
+  RegisteredSurface,
+  MarkupSurfaceRegistryLike,
+  StructuredSurfaceDeclaration,
+  StructuredSurfaceHandler,
+} from "./types.js";
+
+function key(module: ModuleRef, surface: string): string {
+  return `${module.name}@${module.version}#${surface}`;
+}
+
+export class MarkupSurfaceRegistry implements MarkupSurfaceRegistryLike {
+  readonly #values = new Map<string, RegisteredSurface>();
+  readonly #tags = new Set<string>();
+  readonly #byModule = new Map<string, RegisteredSurface[]>();
+
+  register(value: RegisteredSurface): void {
+    if (value.module.name.trim().length === 0 || value.module.version.trim().length === 0) {
+      throw new Error("Surface module is invalid");
+    }
+    if (value.surface.trim().length === 0) throw new Error("Surface name is empty");
+    if (value.tag.trim().length === 0) throw new Error("Surface tag is empty");
+    if (value.mode !== "raw" && value.mode !== "structured") throw new Error("Surface mode is invalid");
+    const surfaceKey = key(value.module, value.surface);
+    if (this.#values.has(surfaceKey)) throw new Error(`Surface ${surfaceKey} is already registered`);
+    const module = `${value.module.name}@${value.module.version}`;
+    const tag = `${module}#${value.tag}`;
+    if (this.#tags.has(tag)) throw new Error(`Surface tag ${value.tag} is already registered for ${module}`);
+    this.#values.set(surfaceKey, value);
+    this.#tags.add(tag);
+    const surfaces = this.#byModule.get(module) ?? [];
+    surfaces.push(value);
+    this.#byModule.set(module, surfaces);
+  }
+
+  registerRaw(options: {
+    readonly module: ModuleRef;
+    readonly declaration: RawSurfaceDeclaration;
+    readonly handler: RawSurfaceHandler;
+  }): void {
+    this.register({
+      module: options.module,
+      surface: options.declaration.name,
+      tag: options.declaration.tag,
+      outputs: options.declaration.outputs,
+      ...(options.declaration.vocabulary === undefined
+        ? {}
+        : { vocabulary: options.declaration.vocabulary }),
+      mode: "raw",
+      handler: options.handler,
+    });
+  }
+
+  registerStructured(options: {
+    readonly module: ModuleRef;
+    readonly declaration: StructuredSurfaceDeclaration;
+    readonly handler: StructuredSurfaceHandler;
+  }): void {
+    this.register({
+      module: options.module,
+      surface: options.declaration.name,
+      tag: options.declaration.tag,
+      outputs: options.declaration.outputs,
+      ...(options.declaration.vocabulary === undefined
+        ? {}
+        : { vocabulary: options.declaration.vocabulary }),
+      mode: "structured",
+      handler: options.handler,
+    });
+  }
+
+  resolve(module: ModuleRef, surface: string): RegisteredSurface | undefined {
+    return this.#values.get(key(module, surface));
+  }
+
+  surfaces(module: ModuleRef): readonly RegisteredSurface[] {
+    return [...(this.#byModule.get(`${module.name}@${module.version}`) ?? [])];
+  }
+}

package/packages/markup/src/syntax.ts

@@ -0,0 +1,271 @@
+import { MarkupFrontendError } from "./error.js";
+import type { SourceRange } from "@hypit/protocol";
+import type {
+  MarkupSource,
+  StructuredElement,
+  StructuredNode,
+  MarkupAttributeValue,
+  MarkupDiscovery,
+  MarkupImportRequest,
+} from "./types.js";
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_.:-]*/u;
+const ALIAS = /^[a-z][a-z0-9_-]{0,63}$/u;
+const REFERENCE = /^[A-Za-z_][A-Za-z0-9_.:-]*(?:\.[A-Za-z_][A-Za-z0-9_.:-]*)*$/u;
+
+type OpeningTag = {
+  readonly name: string;
+  readonly attributes: Readonly<Record<string, MarkupAttributeValue>>;
+  readonly attributeValueRanges: Readonly<Record<string, SourceRange>>;
+  readonly start: number;
+  readonly end: number;
+  readonly selfClosing: boolean;
+};
+
+function fail(source: MarkupSource, code: string, message: string, offset?: number): never {
+  throw new MarkupFrontendError(code, message, source.name, offset, source.text);
+}
+
+function decodeEntities(value: string, source: MarkupSource, offset: number): string {
+  return value.replace(/&(?:lt|gt|amp|quot|apos);/gu, (entity) => {
+    switch (entity) {
+      case "&lt;": return "<";
+      case "&gt;": return ">";
+      case "&amp;": return "&";
+      case "&quot;": return "\"";
+      case "&apos;": return "'";
+      default: fail(source, "MARKUP_ENTITY", `Unsupported entity ${entity}.`, offset);
+    }
+  });
+}
+
+function skipSpace(text: string, start: number): number {
+  let cursor = start;
+  while (/\s/u.test(text[cursor] ?? "")) cursor += 1;
+  return cursor;
+}
+
+function skipTrivia(source: MarkupSource, start: number): number {
+  let cursor = start;
+  while (cursor < source.text.length) {
+    const next = skipSpace(source.text, cursor);
+    if (source.text.startsWith("<!--", next)) {
+      const end = source.text.indexOf("-->", next + 4);
+      if (end < 0) fail(source, "MARKUP_COMMENT", "Unclosed comment.", next);
+      cursor = end + 3;
+      continue;
+    }
+    return next;
+  }
+  return cursor;
+}
+
+function parseName(source: MarkupSource, start: number): { readonly value: string; readonly end: number } {
+  const match = NAME.exec(source.text.slice(start));
+  if (!match) fail(source, "MARKUP_NAME", "Expected a name.", start);
+  return { value: match[0], end: start + match[0].length };
+}
+
+function parseAttributeValue(
+  source: MarkupSource,
+  start: number,
+): { readonly value: MarkupAttributeValue; readonly end: number; readonly valueStart: number; readonly valueEnd: number } {
+  const quote = source.text[start];
+  if (quote === "\"" || quote === "'") {
+    const close = source.text.indexOf(quote, start + 1);
+    if (close < 0) fail(source, "MARKUP_ATTRIBUTE", "Unclosed quoted attribute.", start);
+    return {
+      value: decodeEntities(source.text.slice(start + 1, close), source, start),
+      end: close + 1,
+      valueStart: start + 1,
+      valueEnd: close,
+    };
+  }
+  if (quote === "{") {
+    const close = source.text.indexOf("}", start + 1);
+    if (close < 0) fail(source, "MARKUP_REFERENCE", "Unclosed reference attribute.", start);
+    const path = source.text.slice(start + 1, close).trim();
+    if (!REFERENCE.test(path)) fail(source, "MARKUP_REFERENCE", `Invalid reference "${path}".`, start);
+    return { value: { kind: "reference", path }, end: close + 1, valueStart: start, valueEnd: close + 1 };
+  }
+  fail(source, "MARKUP_ATTRIBUTE", "Attribute values must be quoted strings or whole-value references.", start);
+}
+
+export function parseOpeningTag(source: MarkupSource, start: number): OpeningTag {
+  if (source.text[start] !== "<" || source.text[start + 1] === "/") {
+    fail(source, "MARKUP_OPEN", "Expected an opening tag.", start);
+  }
+  const parsedName = parseName(source, start + 1);
+  let cursor = parsedName.end;
+  const attributes: Record<string, MarkupAttributeValue> = {};
+  const attributeValueRanges: Record<string, SourceRange> = {};
+  while (cursor < source.text.length) {
+    cursor = skipSpace(source.text, cursor);
+    if (source.text.startsWith("/>", cursor)) {
+      return {
+        name: parsedName.value, attributes, attributeValueRanges, start, end: cursor + 2, selfClosing: true,
+      };
+    }
+    if (source.text[cursor] === ">") {
+      return {
+        name: parsedName.value, attributes, attributeValueRanges, start, end: cursor + 1, selfClosing: false,
+      };
+    }
+    const attribute = parseName(source, cursor);
+    if (Object.hasOwn(attributes, attribute.value)) {
+      fail(source, "MARKUP_ATTRIBUTE_DUPLICATE", `Duplicate attribute "${attribute.value}".`, cursor);
+    }
+    cursor = skipSpace(source.text, attribute.end);
+    if (source.text[cursor] !== "=") fail(source, "MARKUP_ATTRIBUTE", `Attribute "${attribute.value}" requires =.`, cursor);
+    cursor = skipSpace(source.text, cursor + 1);
+    const value = parseAttributeValue(source, cursor);
+    Object.defineProperty(attributes, attribute.value, {
+      value: value.value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+    attributeValueRanges[attribute.value] = { start: value.valueStart, end: value.valueEnd };
+    cursor = value.end;
+  }
+  fail(source, "MARKUP_OPEN", `Opening tag <${parsedName.value}> is not closed.`, start);
+}
+
+function parseClose(source: MarkupSource, start: number): { readonly name: string; readonly end: number } {
+  if (!source.text.startsWith("</", start)) fail(source, "MARKUP_CLOSE", "Expected a closing tag.", start);
+  const name = parseName(source, start + 2);
+  const cursor = skipSpace(source.text, name.end);
+  if (source.text[cursor] !== ">") fail(source, "MARKUP_CLOSE", "Malformed closing tag.", start);
+  return { name: name.value, end: cursor + 1 };
+}
+
+export function parseStructuredElement(
+  source: MarkupSource,
+  start: number,
+): { readonly element: StructuredElement; readonly nextOffset: number } {
+  const opening = parseOpeningTag(source, start);
+  if (opening.selfClosing) {
+    return {
+      element: {
+        kind: "element",
+        name: opening.name,
+        attributes: opening.attributes,
+        attributeValueRanges: opening.attributeValueRanges,
+        children: [],
+        range: { start, end: opening.end },
+      },
+      nextOffset: opening.end,
+    };
+  }
+  const children: StructuredNode[] = [];
+  let cursor = opening.end;
+  while (cursor < source.text.length) {
+    if (source.text.startsWith("<!--", cursor)) {
+      const end = source.text.indexOf("-->", cursor + 4);
+      if (end < 0) fail(source, "MARKUP_COMMENT", "Unclosed comment.", cursor);
+      cursor = end + 3;
+      continue;
+    }
+    if (source.text.startsWith("</", cursor)) {
+      const close = parseClose(source, cursor);
+      if (close.name !== opening.name) {
+        fail(source, "MARKUP_CLOSE_MISMATCH", `<${opening.name}> was closed by </${close.name}>.`, cursor);
+      }
+      return {
+        element: {
+          kind: "element",
+          name: opening.name,
+          attributes: opening.attributes,
+          attributeValueRanges: opening.attributeValueRanges,
+          children,
+          range: { start, end: close.end },
+        },
+        nextOffset: close.end,
+      };
+    }
+    if (source.text[cursor] === "<") {
+      const child = parseStructuredElement(source, cursor);
+      children.push(child.element);
+      cursor = child.nextOffset;
+      continue;
+    }
+    const next = source.text.indexOf("<", cursor);
+    const end = next < 0 ? source.text.length : next;
+    children.push({
+      kind: "text",
+      value: decodeEntities(source.text.slice(cursor, end), source, cursor),
+      range: { start: cursor, end },
+    });
+    cursor = end;
+  }
+  fail(source, "MARKUP_ELEMENT_UNCLOSED", `<${opening.name}> is not closed.`, start);
+}
+
+function stringAttribute(
+  source: MarkupSource,
+  opening: OpeningTag,
+  name: string,
+  required = false,
+): string | undefined {
+  const value = opening.attributes[name];
+  if (value === undefined) {
+    if (required) fail(source, "MARKUP_IMPORT", `<import> requires ${name}.`, opening.start);
+    return undefined;
+  }
+  if (typeof value !== "string") fail(source, "MARKUP_IMPORT", `<import> ${name} must be a string.`, opening.start);
+  return value;
+}
+
+function importRequest(source: MarkupSource, opening: OpeningTag): MarkupImportRequest {
+  if (opening.name !== "import" || !opening.selfClosing) {
+    fail(source, "MARKUP_IMPORT", "Imports must use <import .../>.", opening.start);
+  }
+  const unknown = Object.keys(opening.attributes).filter((name) => !["from", "source", "as"].includes(name));
+  if (unknown.length) fail(source, "MARKUP_IMPORT", `Unknown import attribute "${unknown[0]}".`, opening.start);
+  const alias = stringAttribute(source, opening, "as");
+  if (alias !== undefined && !ALIAS.test(alias)) fail(source, "MARKUP_IMPORT_ALIAS", `Invalid alias "${alias}".`, opening.start);
+  const module = stringAttribute(source, opening, "from");
+  const importedSource = stringAttribute(source, opening, "source");
+  if ((module === undefined) === (importedSource === undefined)) {
+    fail(source, "MARKUP_IMPORT_KIND", "<import> requires exactly one of from or source.", opening.start);
+  }
+  if (importedSource !== undefined && alias === undefined) {
+    fail(source, "MARKUP_IMPORT_SOURCE_ALIAS", "A source import requires an alias.", opening.start);
+  }
+  return {
+    kind: importedSource === undefined ? "module" : "source",
+    from: importedSource ?? module!,
+    ...(alias === undefined ? {} : { alias }),
+    range: { start: opening.start, end: opening.end },
+  };
+}
+
+export function discoverMarkup(source: MarkupSource): MarkupDiscovery {
+  let cursor = skipTrivia(source, 0);
+  const root = parseOpeningTag(source, cursor);
+  if (root.name !== "svml" || root.selfClosing) fail(source, "MARKUP_ROOT", "Document must open with <svml>.", cursor);
+  if (Object.keys(root.attributes).length) fail(source, "MARKUP_ROOT_ATTRIBUTE", "<svml> declares no attributes.", cursor);
+  cursor = root.end;
+  const imports: MarkupImportRequest[] = [];
+  while (true) {
+    cursor = skipTrivia(source, cursor);
+    if (source.text.startsWith("</", cursor) || source.text[cursor] !== "<") break;
+    const opening = parseOpeningTag(source, cursor);
+    if (opening.name !== "import") break;
+    imports.push(importRequest(source, opening));
+    cursor = imports.at(-1)!.range.end;
+  }
+  return { imports, bodyStart: cursor };
+}
+
+export function closeDocument(source: MarkupSource, start: number): number {
+  const close = parseClose(source, start);
+  if (close.name !== "svml") fail(source, "MARKUP_ROOT_CLOSE", `Expected </svml>, received </${close.name}>.`, start);
+  const end = skipTrivia(source, close.end);
+  if (end !== source.text.length) fail(source, "MARKUP_TRAILING", "Only trivia may follow </svml>.", end);
+  return end;
+}
+
+export function skipTextTrivia(source: MarkupSource, start: number): number {
+  return skipTrivia(source, start);
+}

package/packages/markup/src/types.ts

@@ -0,0 +1,246 @@
+import type {
+  CanonicalValue,
+  ModuleRef,
+  ResolvedModuleClosure,
+  SourceRange,
+  StoredValue,
+  TypeRef,
+  TypedRecord,
+  ValueSchema,
+} from "@hypit/protocol";
+import type {
+  AuthorComponent,
+  AuthorFrontend,
+  AuthorSourceAssetRequest,
+  AuthorSourceExport,
+  AuthorSourceIdentity,
+  AuthorElementProvenanceDraft,
+  AuthorValueRef,
+  Awaitable,
+  GraphFragment,
+  ResolvedAuthorSourceImport,
+} from "@hypit/elaborator";
+
+/** Decoder-local Markup text; Source identity and closure ownership stay outside the parser. */
+export type MarkupSource = {
+  readonly name: string;
+  readonly text: string;
+};
+
+export type MarkupImportRequest = {
+  readonly kind: "module" | "source";
+  readonly from: string;
+  readonly alias?: string;
+  readonly range: SourceRange;
+};
+
+export type MarkupDiscovery = {
+  readonly imports: readonly MarkupImportRequest[];
+  readonly bodyStart: number;
+};
+
+export type MarkupReference = {
+  readonly kind: "reference";
+  readonly path: string;
+};
+
+export type MarkupAttributeValue = string | MarkupReference;
+
+export type StructuredText = {
+  readonly kind: "text";
+  readonly value: string;
+  readonly range: SourceRange;
+};
+
+export type StructuredElement = {
+  readonly kind: "element";
+  readonly name: string;
+  readonly attributes: Readonly<Record<string, MarkupAttributeValue>>;
+  /** Exact ranges of literal/reference values in the opening tag. */
+  readonly attributeValueRanges?: Readonly<Record<string, SourceRange>>;
+  readonly children: readonly StructuredNode[];
+  readonly range: SourceRange;
+};
+
+export type StructuredNode = StructuredText | StructuredElement;
+
+export type SurfaceRecordDraft = {
+  readonly id: string;
+  readonly type: TypeRef;
+  readonly value: StoredValue;
+  readonly range: SourceRange;
+};
+
+/** Source-local diagnostics are removed before the component enters semantic elaboration. */
+export type SurfaceComponentDraft = AuthorComponent & {
+  readonly range: SourceRange;
+};
+
+export type SurfaceDecodeOutput = {
+  readonly records: readonly SurfaceRecordDraft[];
+  readonly components: readonly SurfaceComponentDraft[];
+  readonly fragments: readonly GraphFragment[];
+  /** Domain-owned public identities that must be unique in the Source closure. */
+  readonly identities?: readonly AuthorSourceIdentity[];
+  /**
+   * Public source bindings contributed by this Surface invocation. Omit to
+   * publish every generated binding; use an explicit list to keep plumbing
+   * addressable inside the source without exposing it from the source.
+   */
+  readonly exports?: readonly string[];
+};
+
+export type RawSurfaceInput = {
+  readonly sourceName: string;
+  readonly source: string;
+  readonly tag: string;
+  readonly openingStart: number;
+  readonly contentStart: number;
+  readonly attributes: Readonly<Record<string, MarkupAttributeValue>>;
+  readonly resolveAsset: (request: AuthorSourceAssetRequest) => Awaitable<import("@hypit/elaborator").ResolvedAuthorSourceAsset>;
+};
+
+export type RawSurfaceOutput = SurfaceDecodeOutput & {
+  readonly nextOffset: number;
+};
+
+export type StructuredSurfaceInput = {
+  readonly sourceName: string;
+  readonly element: StructuredElement;
+  /**
+   * Resolve an explicitly written author reference. Imported record values are
+   * available because their source has already been compiled and admitted.
+   * A component output has a ref and Type but no compile-time Record value.
+   */
+  readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
+  readonly resolveAsset: (request: AuthorSourceAssetRequest) => Awaitable<import("@hypit/elaborator").ResolvedAuthorSourceAsset>;
+};
+
+export type SurfaceResolvedReference = {
+  readonly path: string;
+  readonly ref: AuthorValueRef;
+  readonly type: TypeRef;
+  readonly record?: TypedRecord;
+};
+
+export type RawSurfaceHandler = (input: RawSurfaceInput) => Awaitable<RawSurfaceOutput>;
+export type StructuredSurfaceHandler = (input: StructuredSurfaceInput) => Awaitable<SurfaceDecodeOutput>;
+
+export type SurfaceAttributeKind = "identifier" | "literal" | "reference" | "expression";
+
+export type SurfaceRecipePropertyVocabulary = {
+  readonly name: string;
+  readonly required: boolean;
+  readonly summary: string;
+  /** The author value's public structure; it contains no editor presentation. */
+  readonly schema?: ValueSchema;
+  readonly values?: readonly string[];
+  /** Decoded author default; when a schema is present this value conforms to that public structure. */
+  readonly fallback?: CanonicalValue;
+};
+
+export type SurfaceAttributeVocabulary = {
+  readonly name: string;
+  readonly kind: SurfaceAttributeKind;
+  readonly required: boolean;
+  readonly summary: string;
+  readonly values?: readonly string[];
+  readonly accepts?: readonly TypeRef[];
+  readonly recipe?: readonly SurfaceRecipePropertyVocabulary[];
+};
+
+export type SurfaceChildVocabulary = {
+  readonly tag: string;
+  readonly cardinality: "one" | "optional" | "many";
+  readonly summary: string;
+  readonly attributes?: readonly SurfaceAttributeVocabulary[];
+  /** Elements written inside this child, declared to the same depth the Surface accepts them. */
+  readonly children?: readonly SurfaceChildVocabulary[];
+  readonly text?: string;
+};
+
+export type SurfacePortVocabulary = {
+  readonly name: string;
+  readonly type: TypeRef;
+  readonly summary: string;
+};
+
+export type SurfacePreview = {
+  readonly mediaType: string;
+  readonly path: string;
+  readonly open: () => Promise<Uint8Array>;
+};
+
+export type SurfaceVocabulary = {
+  readonly summary: string;
+  readonly appearance?: string;
+  readonly preview?: SurfacePreview;
+  readonly attributes: readonly SurfaceAttributeVocabulary[];
+  readonly children?: readonly SurfaceChildVocabulary[];
+  readonly ports?: readonly SurfacePortVocabulary[];
+  readonly text?: string;
+  readonly example: string;
+  readonly notes?: readonly string[];
+};
+
+type MarkupSurfaceDeclarationBase = {
+  readonly name: string;
+  readonly tag: string;
+  readonly outputs: readonly TypeRef[];
+  readonly vocabulary?: SurfaceVocabulary;
+};
+
+export type RawSurfaceDeclaration = MarkupSurfaceDeclarationBase & { readonly mode: "raw" };
+export type StructuredSurfaceDeclaration = MarkupSurfaceDeclarationBase & { readonly mode: "structured" };
+export type MarkupSurfaceDeclaration = RawSurfaceDeclaration | StructuredSurfaceDeclaration;
+
+type RegisteredSurfaceBase = {
+  readonly module: ModuleRef;
+  readonly surface: string;
+  readonly tag: string;
+  readonly outputs: readonly TypeRef[];
+  readonly vocabulary?: SurfaceVocabulary;
+};
+
+export type RegisteredRawSurface = RegisteredSurfaceBase & {
+  readonly mode: "raw";
+  readonly handler: RawSurfaceHandler;
+};
+
+export type RegisteredStructuredSurface = RegisteredSurfaceBase & {
+  readonly mode: "structured";
+  readonly handler: StructuredSurfaceHandler;
+};
+
+export type RegisteredSurface =
+  | RegisteredRawSurface
+  | RegisteredStructuredSurface;
+
+export type MarkupDecodeContext = {
+  readonly closure: ResolvedModuleClosure;
+  readonly registry: MarkupSurfaceRegistryLike;
+  readonly resolveModule: (request: MarkupImportRequest) => ModuleRef;
+  readonly sourceImports?: readonly ResolvedAuthorSourceImport[];
+  readonly resolveAsset?: (request: AuthorSourceAssetRequest) => Awaitable<import("@hypit/elaborator").ResolvedAuthorSourceAsset>;
+};
+
+export type MarkupDecodeResult = {
+  readonly records: readonly TypedRecord[];
+  readonly components: readonly AuthorComponent[];
+  readonly fragments: readonly GraphFragment[];
+  readonly exports: readonly AuthorSourceExport[];
+  readonly identities: readonly AuthorSourceIdentity[];
+  readonly provenance: readonly AuthorElementProvenanceDraft[];
+};
+
+export type MarkupAuthorFrontendOptions = {
+  readonly registry: MarkupSurfaceRegistryLike;
+  readonly resolveModule: (request: MarkupImportRequest) => ModuleRef;
+};
+
+export type MarkupAuthorFrontend = AuthorFrontend;
+
+export interface MarkupSurfaceRegistryLike {
+  resolve(module: ModuleRef, surface: string): RegisteredSurface | undefined;
+  surfaces(module: ModuleRef): readonly RegisteredSurface[];
+}

package/packages/media/README.md

@@ -0,0 +1,37 @@
+# `@hypit/media`
+
+Author-facing media declarations for the neutral `@hypit/media` contract module.
+
+`<media:Image>`, `<media:Audio>`, `<media:Video>` and `<media:Font>` request bytes through the Host-owned source-asset
+capability. Image, Audio and Video emit one Resource-backed `BlobArtifact`; Font wraps the same immutable
+bytes with exact weight/style metadata as a one-source `FontArtifactRef`. A logical font face may
+also contain several exact Unicode-range sources when another package, such as
+`@hypit/fonts-open`, owns a sharded installed font. `FontStackRef` is the generic ordered value
+for one primary face followed by exact glyph fallbacks. Media declarations do not open files themselves,
+inspect media, call a Provider or promote declared audio to speech. The consuming author package
+decides whether an audio artifact is a voice reference, soundtrack, evidence source or something
+else, whether a video is a generation reference or another input, and which visual component uses
+an exact Font.
+
+The same module owns the deliberately narrow `SynchronizedMedia` contract used after technical
+normalization. It contains one common `frameRate`/`frameCount`, an optional visual Artifact with its
+intrinsic pixel extent, and an optional audio Artifact. Source stream indexes, selection authority,
+normalization ledgers and repeated codec/rate constants are not downstream media fields.
+
+## Font files
+
+`Font` takes an explicit source path and the selected face's real weight and style:
+
+```svml
+<media:Font id="caption-font" src="./assets/fonts/creator-bold.otf" weight="700" style="normal"/>
+```
+
+The source can be a project font, a user-supplied file, or an installed font's file path. The Host
+stages its bytes as an ordinary resource; the render machine does not need that font installed.
+Project-relative assets make the Source portable. The supported filename extensions are `.ttf`,
+`.otf`, `.woff` and `.woff2`. The Surface has no selector for a face within a `.ttc`/`.otc` collection;
+use the intended standalone face. Weight/style metadata describes that face, not a synthetic transform.
+
+Caption Fine and Typography Styles can consume this value as their primary `font` or an explicit
+Fallback face. `@hypit/fonts-open` offers bundled faces through the same media types; its catalog
+does not limit which external fonts an author may supply.

package/packages/media/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hypit/media",
+  "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/component-kit": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  }
+}

package/packages/media/src/activation.ts

@@ -0,0 +1,38 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeMediaAudioSurface, decodeMediaFontSurface, decodeMediaImageSurface, decodeMediaVideoSurface, mediaComponent,
+  mediaManifest,
+  mediaModuleRef,
+  mediaMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: mediaManifest }],
+  components: [mediaComponent],
+  hostFacets: [
+    createMarkupSurfaceHostFacet({
+      module: mediaModuleRef,
+    declaration: mediaMarkupSurfaces.find((item) => item.name === "image")!,
+      handler: decodeMediaImageSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: mediaModuleRef,
+    declaration: mediaMarkupSurfaces.find((item) => item.name === "audio")!,
+      handler: decodeMediaAudioSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: mediaModuleRef,
+    declaration: mediaMarkupSurfaces.find((item) => item.name === "video")!,
+      handler: decodeMediaVideoSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: mediaModuleRef,
+    declaration: mediaMarkupSurfaces.find((item) => item.name === "font")!,
+      handler: decodeMediaFontSurface,
+    }),
+  ],
+};
+
+export default hypitPackage;