@topik/content 0.0.0-stage → 0.1.0-alpha.6

package/dist/index.d.mts

@@ -0,0 +1,783 @@
+import { Code, Node, Root, RootContent } from "mdast";
+//#region src/expressions.d.ts
+/** The deliberately small expression language accepted in authored conditionals. */
+type Expression = {
+  type: "literal";
+  value: string | number | boolean | null;
+} | {
+  type: "variable";
+  path: string[];
+} | {
+  type: "call";
+  name: "equals" | "and" | "or" | "not";
+  args: Expression[];
+};
+//#endregion
+//#region src/code-presentation.d.ts
+/** Bounds are independent of ordinary, unpresented code admission. */
+export declare const CODE_PRESENTATION_LIMITS: Readonly<{
+  metadataLength: 16384;
+  selectionIntervals: 1024;
+  rows: 20000;
+  decorativeOutput: 8000000;
+}>;
+type CodeLineRange = [number, number];
+type CodeLineSelection = CodeLineRange[];
+/** Only explicitly authored keys are stored. Selections are closed, merged intervals. */
+interface CodePresentationOptions {
+  filename?: string;
+  title?: string;
+  lineNumbers?: boolean;
+  startLine?: number;
+  highlight?: CodeLineSelection;
+  focus?: CodeLineSelection;
+  collapse?: CodeLineSelection;
+  wrap?: boolean;
+  added?: CodeLineSelection;
+  removed?: CodeLineSelection;
+}
+interface CodePresentationEffectiveOptions extends CodePresentationOptions {
+  lineNumbers: boolean;
+  startLine: number;
+  wrap: boolean;
+}
+export declare function effectiveCodePresentationOptions(options: CodePresentationOptions): CodePresentationEffectiveOptions;
+//#endregion
+//#region src/model.d.ts
+type Scalar = string | number | boolean;
+/** Unevaluated text with an explicit distinction between literals and references. */
+type TextTemplate = {
+  type: "topikTextTemplate";
+  segments: Array<{
+    type: "literal";
+    value: string;
+  } | {
+    type: "variable";
+    path: string[];
+  }>;
+};
+type AuthoredAttributeValue = Scalar | TextTemplate;
+interface CodeTemplate extends Node {
+  type: "topikCodeTemplate";
+  lang?: string | null;
+  meta?: string | null;
+  template: TextTemplate;
+}
+/** Authoritative, unevaluated options for one fenced code payload. */
+interface CodePresentation extends Node {
+  type: "topikCodePresentation";
+  children: [Code | CodeTemplate];
+  options: CodePresentationOptions;
+  /** Decoded opaque metadata, including its separating spaces/tabs. */
+  opaqueMetaSuffix: string;
+}
+interface Variable extends Node {
+  type: "topikVariable";
+  path: string[];
+}
+interface Branch extends Node {
+  type: "topikBranch";
+  condition: Expression | null;
+  children: Array<RootContent | Component | Conditional>;
+}
+interface Conditional extends Node {
+  type: "topikConditional";
+  children: Branch[];
+}
+interface Component extends Node {
+  type: "topikComponent";
+  name: string;
+  props: Record<string, AuthoredAttributeValue>;
+  children: Array<RootContent | Component>;
+}
+declare module "mdast" {
+  interface BlockContentMap {
+    topikComponent: Component;
+    topikConditional: Conditional;
+    topikCodeTemplate: CodeTemplate;
+    topikCodePresentation: CodePresentation;
+  }
+  interface PhrasingContentMap {
+    topikComponent: Component;
+    topikVariable: Variable;
+  }
+  interface RootContentMap {
+    topikComponent: Component;
+    topikConditional: Conditional;
+    topikVariable: Variable;
+    topikCodeTemplate: CodeTemplate;
+    topikCodePresentation: CodePresentation;
+  }
+}
+interface ContentDocument extends Omit<Root, "children"> {
+  children: Array<RootContent | Component>;
+}
+interface Diagnostic {
+  /** Stable machine-readable code for public compatibility adapters. */
+  id?: string;
+  /** Bounded code-presentation option name; never an authored value. */
+  option?: string;
+  type?: string;
+  message: string;
+  line?: number;
+  column?: number;
+}
+type ParseResult = {
+  ok: true;
+  document: ContentDocument;
+  source: string;
+} | {
+  ok: false;
+  diagnostics: Diagnostic[];
+  source: string;
+};
+//#endregion
+//#region src/extensions/native.d.ts
+declare const nativeComponents: {
+  readonly codeBlock: {
+    readonly name: "codeBlock";
+    readonly render: "TopikCodeBlock";
+    readonly kind: "block";
+    readonly description: "A fenced code block with an optional language.";
+    readonly attributes: {
+      readonly language: {
+        readonly type: "string";
+        readonly description: "Code language identifier.";
+      };
+    };
+  };
+  readonly inlineCode: {
+    readonly name: "inlineCode";
+    readonly render: "TopikInlineCode";
+    readonly kind: "inline";
+    readonly description: "Inline code text.";
+  };
+  readonly image: {
+    readonly name: "image";
+    readonly render: "TopikImage";
+    readonly kind: "block";
+    readonly description: "Markdown image rendered through Topik asset resolution.";
+    readonly attributes: {
+      readonly src: {
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "Image source URL.";
+        readonly assetReference: {
+          readonly slot: "image.src";
+          readonly role: "image";
+        };
+      };
+      readonly alt: {
+        readonly type: "string";
+        readonly description: "Accessible alternative text.";
+      };
+      readonly title: {
+        readonly type: "string";
+        readonly description: "Optional image title.";
+      };
+    };
+  };
+  readonly link: {
+    readonly name: "link";
+    readonly render: "TopikLink";
+    readonly kind: "inline";
+    readonly description: "Markdown link with optional application-level navigation interception.";
+    readonly attributes: {
+      readonly href: {
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "Link target URL.";
+        readonly assetReference: {
+          readonly slot: "link.href";
+          readonly role: "download";
+          readonly conditional: "proven-download";
+        };
+      };
+      readonly title: {
+        readonly type: "string";
+        readonly description: "Optional link title.";
+      };
+    };
+  };
+  readonly mermaid: {
+    readonly name: "mermaid";
+    readonly render: "TopikMermaid";
+    readonly kind: "block";
+    readonly description: "Mermaid diagram rendered from a fenced mermaid code block.";
+    readonly attributes: {
+      readonly content: {
+        readonly type: "string";
+        readonly required: true;
+        readonly description: "Mermaid diagram source.";
+      };
+    };
+  };
+  readonly table: {
+    readonly name: "table";
+    readonly render: "TopikTable";
+    readonly kind: "block";
+    readonly description: "Markdown table.";
+  };
+  readonly tableRow: {
+    readonly name: "tableRow";
+    readonly render: "TopikTableRow";
+    readonly kind: "block";
+    readonly description: "A row inside a Markdown table.";
+  };
+  readonly tableCell: {
+    readonly name: "tableCell";
+    readonly render: "TopikTableCell";
+    readonly kind: "block";
+    readonly description: "A cell inside a Markdown table.";
+  };
+  readonly tableHeader: {
+    readonly name: "tableHeader";
+    readonly render: "TopikTableHeader";
+    readonly kind: "block";
+    readonly description: "A header cell inside a Markdown table.";
+  };
+};
+//#endregion
+//#region src/registry.d.ts
+export declare const TOPIK_CONTENT_SCHEMA_VERSION = "0.2.2";
+export declare const CALLOUT_VARIANTS: readonly ["info", "tip", "warning", "danger"];
+export declare const BADGE_VARIANTS: readonly ["neutral", "info", "success", "warning", "danger"];
+export declare const QUIZ_QUESTION_TYPES: readonly ["single-choice", "multiple-choice"];
+type TopikAssetReferenceRole = "image" | "image-light" | "image-dark" | "media" | "download";
+interface TopikAssetReferenceDefinition {
+  slot: string;
+  role: TopikAssetReferenceRole;
+  conditional?: "proven-download";
+}
+type AttributeOptions<T extends Scalar> = {
+  required?: boolean;
+  default?: T;
+  description?: string;
+  asset?: boolean;
+  assetReference?: TopikAssetReferenceDefinition;
+};
+type AttributeDefinition = (AttributeOptions<string> & {
+  type: "string";
+  escapedWhitespace?: boolean;
+  /** Canonical text slots alone admit explicit authored templates. */
+  interpolation?: "text";
+  values?: never;
+  min?: never;
+  max?: never;
+}) | (AttributeOptions<string> & {
+  type: "enum";
+  values: readonly string[];
+  min?: never;
+  max?: never;
+}) | (AttributeOptions<number> & {
+  type: "number";
+  min?: number;
+  max?: number;
+  integer?: boolean;
+  values?: never;
+}) | (AttributeOptions<boolean> & {
+  type: "boolean";
+  values?: never;
+  min?: never;
+  max?: never;
+});
+type ChildConstraint = "blocks" | "inline" | "none" | {
+  components: readonly string[];
+  min?: number;
+} | {
+  nodes: readonly string[];
+  min?: number;
+};
+interface ValidationIssue {
+  id: string;
+  message: string;
+  /** Safe authored presentation option name, never a supplied value. */
+  option?: string;
+}
+/** Declarative schema accepted in application configuration. */
+interface ComponentSchema {
+  kind: "block" | "inline";
+  render: string | boolean;
+  description?: string;
+  attributes: Record<string, AttributeDefinition>;
+  children: ChildConstraint;
+  /** Allows an empty block body to use a self-closing source tag. */
+  selfClosing?: boolean;
+  allowedParents?: readonly string[];
+}
+/** Runtime definitions additionally carry the canonical catalog's semantic rules. */
+interface ComponentDefinition extends ComponentSchema {
+  /** Only for rules depending on sibling properties, such as quiz answers. */
+  validate?: (component: Component, effectiveProps: Record<string, AuthoredAttributeValue>) => ValidationIssue[];
+}
+type Registry = Record<string, ComponentDefinition>;
+interface TopikComponentDefinition {
+  name: string;
+  kind: "block" | "inline";
+  render: string;
+  description: string;
+  attributes?: Record<string, AttributeDefinition>;
+  allowedChildren?: readonly string[];
+  requiredChildren?: readonly string[];
+}
+type TopikComponentAttributeDefinition = AttributeDefinition;
+declare const authoredComponents: {
+  accordion: ComponentDefinition;
+  badge: ComponentDefinition;
+  callout: ComponentDefinition;
+  card: ComponentDefinition;
+  cardGrid: ComponentDefinition;
+  codeGroup: ComponentDefinition;
+  codeTab: {
+    kind: "block" | "inline";
+    render: string | boolean;
+    description?: string;
+    attributes: Record<string, AttributeDefinition>;
+    /** Allows an empty block body to use a self-closing source tag. */
+    selfClosing?: boolean;
+    allowedParents?: readonly string[];
+    /** Only for rules depending on sibling properties, such as quiz answers. */
+    validate?: (component: Component, effectiveProps: Record<string, AuthoredAttributeValue>) => ValidationIssue[];
+    children: {
+      nodes: string[];
+      min: number;
+    };
+  };
+  choice: ComponentDefinition;
+  explanation: ComponentDefinition;
+  figure: ComponentDefinition;
+  math: ComponentDefinition;
+  mathInline: ComponentDefinition;
+  question: ComponentDefinition;
+  quiz: ComponentDefinition;
+  step: ComponentDefinition;
+  steps: ComponentDefinition;
+  tab: ComponentDefinition;
+  tabs: ComponentDefinition;
+  underline: ComponentDefinition;
+};
+/** Canonical schemas are immutable; callers add custom names in a separate registry. */
+export declare const components: Registry;
+/** Legacy catalog metadata, derived from authored definitions plus native mdast nodes. */
+export declare const topikComponents: Record<keyof typeof authoredComponents | keyof typeof nativeComponents, TopikComponentDefinition>;
+type TopikComponentName = keyof typeof topikComponents;
+/** Defaults are for reading/rendering; authored absence stays unchanged. */
+export declare function getEffectiveProps(component: Pick<Component, "name" | "props">, registry?: Registry): Record<string, AuthoredAttributeValue>;
+//#endregion
+//#region src/validation.d.ts
+export declare function validateDocument(document: ContentDocument, registry?: Registry): Diagnostic[];
+//#endregion
+//#region src/document-meaning.d.ts
+/** Compare admitted authoring trees, retaining explicit heading IDs and every authored branch.
+ * Source positions, cosmetic spelling and derived metadata do not affect equality.
+ * This compares meaning; it does not validate arbitrary caller-constructed trees.
+ */
+export declare function sameDocumentMeaning(left: ContentDocument, right: ContentDocument): boolean;
+//#endregion
+//#region src/parser.d.ts
+export declare const FORMAT_VERSION = 1;
+//#endregion
+//#region src/writer.d.ts
+export declare function writeDocument(document: ContentDocument, registry?: Registry, formatVersion?: number): string;
+//#endregion
+//#region src/markdown.d.ts
+export declare function parseDocument(source: string, registry?: Registry, formatVersion?: number): ParseResult;
+export declare function formatDocument(source: string, registry?: Registry): ParseResult & {
+  formatted?: string;
+};
+//#endregion
+//#region src/assets.d.ts
+/** Rewrite asset definitions once, preserving reference identity and unrelated navigation. */
+export declare function rewriteAssets(document: ContentDocument, replace: (url: string) => string | undefined, registry?: Registry): ContentDocument;
+//#endregion
+//#region src/evaluate.d.ts
+export declare class ContentEvaluationError extends Error {
+  constructor(message: string);
+}
+/** Resolve into a new, writable document; the authored branches remain untouched. */
+export declare function evaluateDocument(document: ContentDocument, context: Record<string, unknown>, registry?: Registry): ContentDocument;
+//#endregion
+//#region src/limits.d.ts
+/** Fixed admission limits, measured in UTF-16 code units and tree nodes. */
+export declare const CONTENT_LIMITS: Readonly<{
+  sourceLength: 1000000;
+  /** Inline delimiter attempts; code-span attempts are weighted by delimiter run length. */
+  parserSteps: 4096;
+  treeDepth: 64;
+  treeNodes: 50000;
+  dataDepth: 160;
+  dataEntries: 500000;
+  dataStringLength: 1000000;
+  expressionLength: 16384;
+  expressionDepth: 32;
+  expressionNodes: 256;
+  /** Bounded escaped payload and row decorations, before reader allocation. */
+  presentationOutputLength: 8000000;
+}>;
+export declare class ContentLimitError extends Error {
+  readonly id = "topik-content-limit";
+  constructor(message: string);
+}
+//#endregion
+//#region src/config.d.ts
+interface TopikContentConfig {
+  /** Additional component schemas. Canonical Topik definitions cannot be replaced. */
+  components?: Record<string, ComponentSchema>;
+  /** Reader context used only by explicit evaluation or rendering. */
+  variables?: Record<string, unknown>;
+}
+interface ResolvedTopikContentConfig {
+  components: Registry;
+  variables: Record<string, unknown>;
+}
+/** Isolate schemas before validation; runtime variables are read without invoking accessors. */
+export declare function mergeTopikContentConfig(extension?: TopikContentConfig): ResolvedTopikContentConfig;
+//#endregion
+//#region src/asset-reference-policy.d.ts
+export declare const TOPIK_ASSET_REFERENCE_VERSION: "topik-asset-reference-v1";
+/** Public grammar descriptor. Runtime admission uses an isolated boundary. */
+export declare const TOPIK_GENERATED_ASSET_NAME_PATTERN: RegExp;
+declare const topikGeneratedAssetNameBrand: unique symbol;
+/** Compiler-generated name used by the compiled-content Asset reference protocol. */
+type TopikGeneratedAssetName = string & {
+  readonly [topikGeneratedAssetNameBrand]: "TopikGeneratedAssetName";
+};
+export declare function isTopikGeneratedAssetName(value: unknown): value is TopikGeneratedAssetName;
+export declare function parseTopikGeneratedAssetName(value: string): TopikGeneratedAssetName;
+type TopikAssetReferenceValidation = {
+  valid: true;
+  kind: "asset";
+  name: TopikGeneratedAssetName;
+} | {
+  valid: true;
+  kind: "local";
+  decodedPath: string;
+} | {
+  valid: true;
+  kind: "external-https";
+} | {
+  valid: false;
+  kind: "unsafe";
+  failureKind: "local" | "external";
+};
+/** Validate the URL-facing portion of topik-asset-reference-v1 without filesystem access. */
+export declare function validateTopikAssetReference(reference: string): TopikAssetReferenceValidation;
+//#endregion
+//#region src/asset-references.d.ts
+interface TopikAssetReferenceSlot {
+  node: "image" | "tag" | "link";
+  tag?: "figure";
+  attribute: "src" | "darkSrc" | "href";
+  slot: "image.src" | "figure.src" | "figure.darkSrc" | "link.href";
+  role: TopikAssetReferenceRole;
+  conditional?: "proven-download";
+}
+/**
+ * Closed registry for topik-asset-reference-v1. Extractors never infer a slot from an
+ * attribute name and never recursively inspect arbitrary strings.
+ */
+export declare const topikAssetReferenceSlots: readonly [{
+  readonly node: "image";
+  readonly attribute: "src";
+  readonly slot: "image.src";
+  readonly role: "image";
+}, {
+  readonly node: "tag";
+  readonly tag: "figure";
+  readonly attribute: "src";
+  readonly slot: "figure.src";
+  readonly role: "image-light";
+}, {
+  readonly node: "tag";
+  readonly tag: "figure";
+  readonly attribute: "darkSrc";
+  readonly slot: "figure.darkSrc";
+  readonly role: "image-dark";
+}, {
+  readonly node: "link";
+  readonly attribute: "href";
+  readonly slot: "link.href";
+  readonly role: "download";
+  readonly conditional: "proven-download";
+}];
+type TopikAssetOccurrenceKind = "asset" | "reserved-asset" | "local" | "external-https" | "unsafe";
+interface TopikAssetOccurrenceSemantics {
+  alt?: string;
+  /** Authored text, detached from source nodes and never resolved by asset operations. */
+  altTemplate?: TextTemplate;
+  decorative?: boolean;
+  title?: string;
+  caption?: string;
+  captionTemplate?: TextTemplate;
+  lightDarkRole?: "light" | "dark";
+  linkLabel?: string;
+}
+interface TopikAssetOccurrence {
+  /** Stable normalized tree position, independent from other occurrences. */
+  position: string;
+  treePath: readonly number[];
+  slot: TopikAssetReferenceSlot["slot"];
+  role: TopikAssetReferenceRole;
+  /** Parser-produced destination used only to prove what the exact source bytes resolve to. */
+  parsedReference: string;
+  reference: string;
+  kind: TopikAssetOccurrenceKind;
+  semantics: TopikAssetOccurrenceSemantics;
+}
+interface ExtractTopikAssetOccurrencesOptions {
+  config?: TopikContentConfig;
+  /** Decoded regular-file paths. Enables unambiguous generic download-link occurrences. */
+  provenDownloadPaths?: ReadonlySet<string> | readonly string[];
+  /** Return generic-link candidates so a compiler can prove plain-mode downloads. */
+  includeGenericLinkCandidates?: boolean;
+}
+export declare function extractTopikAssetOccurrences(source: string, options?: ExtractTopikAssetOccurrencesOptions): TopikAssetOccurrence[];
+/** Remove unsafe destinations from a preview tree, retaining readable descriptions. */
+export declare function removeInvalidTopikAssetReferences(document: ContentDocument, source?: string, options?: {
+  config?: TopikContentConfig;
+}): void;
+//#endregion
+//#region src/content.d.ts
+type TopikContentNode = ContentDocument;
+interface ParseTopikContentOptions {
+  /** @deprecated Compatibility-only; use validation/analysis options for diagnostic labels. */
+  file?: string;
+  /** @deprecated Compatibility-only; parsing always retains available source positions. */
+  location?: boolean;
+  config?: TopikContentConfig;
+}
+/** Parse the authoring tree. Use validateTopikContent at publication boundaries. */
+export declare function parseTopikContent(source: string, options?: ParseTopikContentOptions): ContentDocument;
+//#endregion
+//#region src/diagnostics.d.ts
+type TopikContentDiagnosticLevel = "debug" | "info" | "warning" | "error" | "critical";
+interface ContentValidationIssue {
+  type: string;
+  lines: number[];
+  location?: {
+    file?: string;
+  };
+  error: {
+    id: string;
+    level: TopikContentDiagnosticLevel;
+    message: string;
+  };
+}
+interface TopikContentDiagnostic {
+  /** Stable diagnostic identifier. */
+  id: string;
+  /** Content node type that produced the diagnostic. */
+  type: string;
+  /** Diagnostic severity. */
+  level: TopikContentDiagnosticLevel;
+  /** Human-readable diagnostic message. */
+  message: string;
+  /** One-based source lines associated with the diagnostic, when available. */
+  lines: number[];
+  /** Optional sanitized source label. Absolute directories and URL secrets are removed. */
+  file?: string;
+  /** Authored template text slot, when available. */
+  attribute?: string;
+  /** Bounded authored variable path; context values are never included. */
+  variable?: string;
+  /** Supported code presentation option, with no authored/resolved values. */
+  option?: string;
+  /** One-based source column when available. */
+  column?: number;
+}
+/** Fixed public wording for link diagnostics; authored targets are never accepted as input. */
+export declare function topikLinkDiagnosticMessage(id: string): string | undefined;
+/** Re-apply fixed public messages and safe file labels when diagnostics cross package layers. */
+export declare function sanitizeTopikContentDiagnostic(diagnostic: TopikContentDiagnostic): TopikContentDiagnostic;
+export declare function toTopikContentDiagnostic(error: ContentValidationIssue): TopikContentDiagnostic;
+/** Convert an untrusted diagnostic location to a browser-compatible safe label. */
+export declare function sanitizeTopikDiagnosticFile(file: string | undefined): string | undefined;
+//#endregion
+//#region src/source.d.ts
+interface ValidateTopikContentOptions {
+  file?: string;
+  config?: TopikContentConfig;
+  /** Accept compiler-produced references at a compiled-output boundary. */
+  allowCompiledAssetReferences?: boolean;
+}
+//#endregion
+//#region src/validate.d.ts
+interface ValidateTopikContentResult {
+  source: string;
+  valid: boolean;
+  errors: TopikContentDiagnostic[];
+}
+/** Source admission is the same boundary used by formatting and asset rewriting. */
+export declare function validateTopikContent(source: string, options?: ValidateTopikContentOptions): ValidateTopikContentResult;
+//#endregion
+//#region src/format.d.ts
+interface FormatTopikContentOptions extends ValidateTopikContentOptions {}
+interface FormatTopikContentSuccess {
+  ok: true;
+  /** Exact caller-supplied source. */
+  source: string;
+  diagnostics: TopikContentDiagnostic[];
+  formatted: string;
+}
+interface FormatTopikContentFailure {
+  ok: false;
+  /** Exact caller-supplied source, unchanged and unformatted. */
+  source: string;
+  diagnostics: TopikContentDiagnostic[];
+}
+type FormatTopikContentResult = FormatTopikContentSuccess | FormatTopikContentFailure;
+/** Validate source before formatting so unsupported input remains an exact opaque handoff. */
+export declare function formatTopikContent(source: string, options?: FormatTopikContentOptions): FormatTopikContentResult;
+//#endregion
+//#region src/rewrite.d.ts
+interface RewriteTopikAssetOccurrencesOptions extends ExtractTopikAssetOccurrencesOptions, ValidateTopikContentOptions {}
+interface RewriteTopikAssetOccurrencesSuccess {
+  ok: true;
+  /** Exact caller-supplied source before rewriting. */
+  source: string;
+  diagnostics: TopikContentDiagnostic[];
+  /** Rewritten content. Replacements are validated, including compiler-generated Asset references. */
+  content: string;
+}
+interface RewriteTopikAssetOccurrencesFailure {
+  ok: false;
+  /** Exact caller-supplied source, unchanged and unformatted. */
+  source: string;
+  diagnostics: TopikContentDiagnostic[];
+}
+type RewriteTopikAssetOccurrencesResult = RewriteTopikAssetOccurrencesSuccess | RewriteTopikAssetOccurrencesFailure;
+export declare function rewriteTopikAssetOccurrences(source: string, replace: (occurrence: TopikAssetOccurrence) => string | undefined, options?: RewriteTopikAssetOccurrencesOptions): RewriteTopikAssetOccurrencesResult;
+//#endregion
+//#region src/headings.d.ts
+interface TopikHeading {
+  id: string;
+  level: number;
+  title: string;
+}
+export declare function assignTopikHeadingIds(document: ContentDocument): TopikHeading[];
+//#endregion
+//#region src/resource-references.d.ts
+/** Version of the portable compiled-content resource reference contract. */
+export declare const TOPIK_RESOURCE_REFERENCE_VERSION: 1;
+interface TopikResourceReference {
+  /** Schema resource type; no repository or application namespace is implied. */
+  type: "WikiPage" | "Guide" | "CoursePage";
+  /** Schema resource name (at most 63 characters), independent of its public route. */
+  name: string;
+  /** URI query, including its leading '?' when present. */
+  search: string;
+  /** URI fragment, without a leading '#'. */
+  hash: string;
+}
+/** Parse an explicit resource identity without consulting routes or fetching a catalogue. */
+export declare function parseTopikResourceReference(href: string): TopikResourceReference | null;
+/** Serialize an identity as a canonical ref:// URI; this is not a browser-facing URL. */
+export declare function serializeTopikResourceReference(reference: TopikResourceReference): string;
+//#endregion
+//#region src/navigation-rewrite.d.ts
+interface TopikNavigationReference {
+  href: string;
+  kind: "link" | "card";
+  position: string;
+}
+type RewriteTopikNavigationResult = {
+  ok: true;
+  content: string;
+  changes: readonly (TopikNavigationReference & {
+    replacement: string;
+  })[];
+  diagnostics: TopikContentDiagnostic[];
+} | {
+  ok: false;
+  source: string;
+  diagnostics: TopikContentDiagnostic[];
+};
+/** Rewrite actual navigation references, retaining definitions/scopes and every authored branch. */
+export declare function rewriteTopikNavigationReferences(source: string, replace: (reference: TopikNavigationReference) => string | undefined, options?: ValidateTopikContentOptions): RewriteTopikNavigationResult;
+//#endregion
+//#region src/links.d.ts
+type ValidationError = {
+  id: string;
+  level: "error";
+  message: string;
+};
+type TopikContentLinkKind = "card" | "link";
+interface TopikContentLink {
+  file?: string;
+  href: string;
+  kind: TopikContentLinkKind;
+  lines: number[];
+}
+interface TopikAnalyzedHeading extends TopikHeading {
+  file?: string;
+  lines: number[];
+}
+interface AnalyzeTopikContentResult {
+  diagnostics: TopikContentDiagnostic[];
+  headings: TopikAnalyzedHeading[];
+  links: TopikContentLink[];
+}
+interface AnalyzeTopikContentOptions {
+  file?: string;
+  config?: TopikContentConfig;
+}
+export declare function analyzeTopikContent(source: string, options?: AnalyzeTopikContentOptions): AnalyzeTopikContentResult;
+export declare function validateTopikHref(value: unknown): ValidationError[];
+/** Admit only resolved hrefs at a boundary that can emit browser navigation. */
+export declare function validateTopikBrowserHref(value: unknown): ValidationError[];
+export declare function validateTopikNavigationHref(value: unknown): ValidationError[];
+/** Remove invalid navigation attributes before a renderer can emit a browser-facing URL. */
+export declare function removeInvalidTopikNavigationReferences(root: ContentDocument): void;
+//#endregion
+//#region src/render.d.ts
+/** Framework-independent, serializable output. It contains no executable values. */
+type RenderableTreeNode = ContentTag | string | number | boolean | null | RenderableTreeNode[];
+export declare class ContentTag {
+  name: string;
+  attributes: Record<string, unknown>;
+  children: RenderableTreeNode[];
+  readonly type = "element";
+  constructor(name: string, attributes?: Record<string, unknown>, children?: RenderableTreeNode[]);
+}
+export declare function isContentTag(value: unknown): value is ContentTag;
+/** Render a validated authored document through a separate evaluated document. */
+export declare function transformTopikContent(document: ContentDocument, options?: TopikContentConfig): RenderableTreeNode;
+//#endregion
+//#region src/compiled.d.ts
+interface CompiledTopikContent {
+  sourceFormat: "topik";
+  topikSchemaVersion: string;
+  formatVersion: number;
+  configHash: string;
+  renderableTree: RenderableTreeNode;
+  diagnostics: TopikContentDiagnostic[];
+}
+//#endregion
+//#region src/compile.d.ts
+interface CompileTopikContentOptions {
+  file?: string;
+  config?: TopikContentConfig;
+  onDiagnostic?: (diagnostic: TopikContentDiagnostic) => void;
+}
+interface CompileTopikContentSuccess {
+  ok: true;
+  /** Exact caller-supplied source. */
+  source: string;
+  diagnostics: TopikContentDiagnostic[];
+  tree: RenderableTreeNode;
+}
+interface CompileTopikContentFailure {
+  ok: false;
+  /** Exact caller-supplied source, unchanged and never transformed. */
+  source: string;
+  diagnostics: TopikContentDiagnostic[];
+}
+type CompileTopikContentResult = CompileTopikContentSuccess | CompileTopikContentFailure;
+/** Admit source once, including compiled asset references, and produce a reader tree. */
+export declare function compileTopikContent(source: string, options?: CompileTopikContentOptions): CompileTopikContentResult;
+//#endregion
+//#region src/index.d.ts
+export type TopikComponentKind = "block" | "inline";
+export type TopikAttributeType = "string" | "number" | "boolean" | "enum";
+//#endregion
+export type { AnalyzeTopikContentOptions, AnalyzeTopikContentResult, AttributeDefinition, AuthoredAttributeValue, Branch, ChildConstraint, CodeLineSelection, CodePresentation, CodePresentationEffectiveOptions, CodePresentationOptions, CodeTemplate, CompileTopikContentFailure, CompileTopikContentOptions, CompileTopikContentResult, CompileTopikContentSuccess, CompiledTopikContent, Component, ComponentDefinition, ComponentSchema, Conditional, ContentDocument, Diagnostic, Expression, ExtractTopikAssetOccurrencesOptions, FormatTopikContentFailure, FormatTopikContentOptions, FormatTopikContentResult, FormatTopikContentSuccess, ParseResult, ParseTopikContentOptions, Registry, RenderableTreeNode, ResolvedTopikContentConfig, RewriteTopikAssetOccurrencesFailure, RewriteTopikAssetOccurrencesOptions, RewriteTopikAssetOccurrencesResult, RewriteTopikAssetOccurrencesSuccess, RewriteTopikNavigationResult, Scalar, TextTemplate, TopikAnalyzedHeading, TopikAssetOccurrence, TopikAssetOccurrenceKind, TopikAssetOccurrenceSemantics, TopikAssetReferenceDefinition, TopikAssetReferenceRole, TopikAssetReferenceSlot, TopikAssetReferenceValidation, TopikComponentAttributeDefinition, TopikComponentDefinition, TopikComponentName, TopikContentConfig, TopikContentDiagnostic, TopikContentDiagnosticLevel, TopikContentLink, TopikContentLinkKind, TopikContentNode, TopikGeneratedAssetName, TopikHeading, TopikNavigationReference, TopikResourceReference, ValidateTopikContentOptions, ValidateTopikContentResult, Variable };