@anthusai/papyrus 0.0.0 → 1.0.0-next.2

package/lib/markus-body.ts

@@ -0,0 +1,168 @@
+/**
+ * Reads the stored Markus body IR (`bodyIr`, the envelope written by
+ * `derive_body` in src/papyrus_content/markus_renderer/derive.py) and projects
+ * it into the flat structures the Pretext solver consumes. The solver input
+ * (`Article.body: string[]`) is unchanged; only its source changed.
+ *
+ * There is no fallback: an envelope with an unknown schema version, or a
+ * placeholder token that the envelope cannot resolve, throws `BodyIrError`.
+ */
+
+import { MarkusSchemaVersionError, parseMarkusDocument } from "./markus-ir";
+import { projectMarkusDocumentToPretext } from "./markus-projection";
+
+export class BodyIrError extends Error {}
+
+export type BodyProjectionImage = {
+  src: string;
+  alt: string;
+  caption?: string;
+  credit?: string;
+  layout?: string;
+};
+
+export type BodyProjection = {
+  body: string[];
+  pullQuotes: string[];
+  imageSrcs: BodyProjectionImage[];
+};
+
+const SUPPORTED_ENVELOPE_SCHEMA_VERSION = 1;
+const SUPPORTED_MARKUS_IR_SCHEMA_VERSION = 1;
+const TOKEN_PATTERN = /PAPYRUSMARKUP\d{5}END/g;
+const WHOLE_TOKEN_PATTERN = /^PAPYRUSMARKUP\d{5}END$/;
+
+type PapyrusSidecar = {
+  images: Record<string, Record<string, unknown>>;
+  citations: Record<string, string[]>;
+  citationLists: Record<string, unknown>;
+  bibliography: string[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseEnvelope(raw: unknown): Record<string, unknown> {
+  let value = raw;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      throw new BodyIrError("bodyIr is not valid JSON");
+    }
+  }
+  if (!isRecord(value)) throw new BodyIrError("bodyIr must be a JSON object");
+  return value;
+}
+
+function readSidecar(envelope: Record<string, unknown>): PapyrusSidecar {
+  const sidecar = envelope.papyrus;
+  if (!isRecord(sidecar)) throw new BodyIrError("bodyIr.papyrus is missing");
+  const { images, citations, citationLists, bibliography } = sidecar;
+  if (!isRecord(images) || !isRecord(citations) || !isRecord(citationLists) || !Array.isArray(bibliography)) {
+    throw new BodyIrError("bodyIr.papyrus must contain images, citations, citationLists and bibliography");
+  }
+  return {
+    images: images as PapyrusSidecar["images"],
+    citations: citations as PapyrusSidecar["citations"],
+    citationLists: citationLists,
+    bibliography: bibliography.map(String),
+  };
+}
+
+function numberCitationKeysByFirstAppearance(document: unknown, sidecar: PapyrusSidecar): Map<string, number> {
+  const numbers = new Map<string, number>();
+  for (const token of JSON.stringify(document).match(TOKEN_PATTERN) ?? []) {
+    for (const key of sidecar.citations[token] ?? []) {
+      if (!numbers.has(key)) numbers.set(key, numbers.size + 1);
+    }
+  }
+  return numbers;
+}
+
+function resolveCitationTokens(text: string, sidecar: PapyrusSidecar, numbers: Map<string, number>): string {
+  return text.replace(TOKEN_PATTERN, (token) => {
+    const keys = sidecar.citations[token];
+    if (!keys) return token;
+    return keys.map((key) => `[${numbers.get(key)}]`).join("");
+  });
+}
+
+function imageFromSidecar(token: string, sidecar: PapyrusSidecar): BodyProjectionImage {
+  const entry = sidecar.images[token];
+  if (typeof entry?.src !== "string" || !entry.src) {
+    throw new BodyIrError(`bodyIr image ${token} has no src`);
+  }
+  const image: BodyProjectionImage = { src: entry.src, alt: typeof entry.alt === "string" ? entry.alt : "" };
+  if (typeof entry.caption === "string" && entry.caption) image.caption = entry.caption;
+  if (typeof entry.credit === "string" && entry.credit) image.credit = entry.credit;
+  if (typeof entry.layout === "string" && entry.layout) image.layout = entry.layout;
+  return image;
+}
+
+export function projectBodyIr(raw: unknown): BodyProjection {
+  const envelope = parseEnvelope(raw);
+  if (envelope.schemaVersion !== SUPPORTED_ENVELOPE_SCHEMA_VERSION) {
+    throw new BodyIrError(
+      `bodyIr schemaVersion ${String(envelope.schemaVersion)} is not supported (expected ${SUPPORTED_ENVELOPE_SCHEMA_VERSION})`,
+    );
+  }
+  const markus = envelope.markus;
+  if (!isRecord(markus) || markus.irSchemaVersion !== SUPPORTED_MARKUS_IR_SCHEMA_VERSION) {
+    throw new BodyIrError(
+      `bodyIr markus.irSchemaVersion ${String(isRecord(markus) ? markus.irSchemaVersion : undefined)} is not supported (expected ${SUPPORTED_MARKUS_IR_SCHEMA_VERSION})`,
+    );
+  }
+  const sidecar = readSidecar(envelope);
+
+  let projected;
+  try {
+    projected = projectMarkusDocumentToPretext(parseMarkusDocument(envelope.document));
+  } catch (error) {
+    if (error instanceof MarkusSchemaVersionError) throw new BodyIrError(error.message);
+    throw error;
+  }
+
+  const numbers = numberCitationKeysByFirstAppearance(envelope.document, sidecar);
+  const body: string[] = [];
+  const imageSrcs: BodyProjectionImage[] = [];
+  for (const paragraph of projected.body) {
+    if (WHOLE_TOKEN_PATTERN.test(paragraph) && paragraph in sidecar.images) {
+      imageSrcs.push(imageFromSidecar(paragraph, sidecar));
+      continue;
+    }
+    if (WHOLE_TOKEN_PATTERN.test(paragraph) && paragraph in sidecar.citationLists) {
+      sidecar.bibliography.forEach((entry, index) => body.push(`${index + 1}. ${entry}`));
+      continue;
+    }
+    body.push(resolveCitationTokens(paragraph, sidecar, numbers));
+  }
+  const pullQuotes = projected.pullQuotes.map((quote) => resolveCitationTokens(quote, sidecar, numbers));
+
+  if ([...body, ...pullQuotes].some((text) => /PAPYRUSMARKUP\d{5}END/.test(text))) {
+    throw new BodyIrError("bodyIr contains a placeholder token with no entry in bodyIr.papyrus");
+  }
+  return { body, pullQuotes, imageSrcs };
+}
+
+export type BodyImageMatch =
+  | { kind: "media"; mediaIndex: number }
+  | { kind: "external"; image: BodyProjectionImage };
+
+/**
+ * Matches each image the body references to a stored media row by the
+ * `srcPath` the row was created from. Absolute http(s) sources need no media
+ * row. Any other source without a row is an error, never skipped.
+ */
+export function matchBodyImages(
+  imageSrcs: BodyProjectionImage[],
+  mediaSrcPaths: Array<string | null>,
+): BodyImageMatch[] {
+  return imageSrcs.map((image) => {
+    const mediaIndex = mediaSrcPaths.indexOf(image.src);
+    if (mediaIndex >= 0) return { kind: "media", mediaIndex };
+    if (/^https?:\/\//i.test(image.src)) return { kind: "external", image };
+    throw new BodyIrError(`bodyIr references image "${image.src}" but no media asset has that srcPath`);
+  });
+}

package/lib/markus-ir.ts

@@ -0,0 +1,235 @@
+/**
+ * Typed TypeScript mirror of the Markus document IR (`markus ast`, Markus
+ * repo branch `feature/document-ir`, `src/markusmd/ast.py` +
+ * `src/markusmd/blocks.py`).
+ *
+ * This is NOT invented from the Markus language docs -- it is typed
+ * directly from a real `markus ast` invocation (see
+ * `scripts/fixtures/markus-sample.ast.json`, captured from
+ * `scripts/fixtures/markus-sample.md` via `markus ast`) cross-checked
+ * against the emitting Python dataclasses' `to_dict()` methods. Papyrus
+ * does NOT re-parse Markdown; it only ingests this JSON shape.
+ *
+ * `IR_SCHEMA_VERSION` mirrors `markusmd.blocks.IR_SCHEMA_VERSION`. Bump it
+ * only in lockstep with a corresponding bump on the Markus side, and only
+ * after re-deriving the types below from a fresh `markus ast` capture --
+ * never by hand-editing the number.
+ */
+
+/** The Markus document IR schema version Papyrus is typed against. */
+export const MARKUS_IR_SCHEMA_VERSION = 1 as const;
+
+// --------------------------------------------------------------------------
+// Inline nodes (markusmd/blocks.py: Text | Emphasis | Strong | Strikethrough
+// | CodeSpan | Link | Image | SoftBreak | HardBreak | HtmlInline)
+// --------------------------------------------------------------------------
+
+export type MarkusInlineText = { type: "text"; text: string };
+
+export type MarkusInlineEmphasis = { type: "emphasis"; children: MarkusInline[] };
+
+export type MarkusInlineStrong = { type: "strong"; children: MarkusInline[] };
+
+export type MarkusInlineStrikethrough = { type: "strikethrough"; children: MarkusInline[] };
+
+/**
+ * An inline code span, e.g. `` `code` ``. Distinct from the block-level
+ * `code` node (`MarkusCodeBlock`, type `"code"`) below -- do not conflate
+ * the two. `code_span` never has a `lang`; it is always plain text.
+ */
+export type MarkusInlineCodeSpan = { type: "code_span"; code: string };
+
+export type MarkusInlineLink = {
+  type: "link";
+  href: string | null;
+  title: string | null;
+  children: MarkusInline[];
+};
+
+export type MarkusInlineImage = {
+  type: "image";
+  src: string | null;
+  alt: string;
+  title: string | null;
+};
+
+export type MarkusInlineSoftBreak = { type: "soft_break" };
+
+export type MarkusInlineHardBreak = { type: "hard_break" };
+
+/**
+ * Raw inline HTML. Only produced when the document was parsed with
+ * `allow_html=True` (`markus ast --allow-html`). Papyrus builds fragments
+ * with `--allow-html` OFF (see docs/pluggable-publishers security note), so
+ * this node type should not appear in IR Papyrus ingests in practice; it is
+ * still typed here because the emitter can produce it, and the projection
+ * must not silently drop it if it ever does.
+ */
+export type MarkusInlineHtml = { type: "html_inline"; value: string };
+
+export type MarkusInline =
+  | MarkusInlineText
+  | MarkusInlineEmphasis
+  | MarkusInlineStrong
+  | MarkusInlineStrikethrough
+  | MarkusInlineCodeSpan
+  | MarkusInlineLink
+  | MarkusInlineImage
+  | MarkusInlineSoftBreak
+  | MarkusInlineHardBreak
+  | MarkusInlineHtml;
+
+// --------------------------------------------------------------------------
+// Typed Markdown block nodes (markusmd/blocks.py: Heading | Paragraph |
+// List | Blockquote | CodeBlock | ThematicBreak | HtmlBlock | Table).
+// These sit as ordered PEERS of directive nodes in one children[] array --
+// there is no opaque raw-markdown node in the IR.
+// --------------------------------------------------------------------------
+
+export type MarkusHeading = {
+  type: "heading";
+  level: number;
+  inline: MarkusInline[];
+  line: number | null;
+};
+
+export type MarkusParagraph = {
+  type: "paragraph";
+  inline: MarkusInline[];
+  line: number | null;
+};
+
+export type MarkusListItem = {
+  type: "list_item";
+  checked: boolean | null;
+  children: MarkusBlock[];
+  line: number | null;
+};
+
+export type MarkusList = {
+  type: "list";
+  ordered: boolean;
+  start: number | null;
+  items: MarkusListItem[];
+  line: number | null;
+};
+
+export type MarkusBlockquote = {
+  type: "blockquote";
+  children: MarkusBlock[];
+  line: number | null;
+};
+
+/**
+ * A fenced or indented code BLOCK. Distinct from the inline `code_span`
+ * node above -- do not conflate the two.
+ */
+export type MarkusCodeBlock = {
+  type: "code";
+  lang: string | null;
+  value: string;
+  line: number | null;
+};
+
+export type MarkusThematicBreak = { type: "thematic_break"; line: number | null };
+
+/**
+ * A raw HTML block. Only produced when `allow_html=True`; see
+ * `MarkusInlineHtml` above for why Papyrus's build should never emit this
+ * in the IR it ingests, and why it is still typed and handled anyway.
+ */
+export type MarkusHtmlBlock = { type: "html"; value: string; line: number | null };
+
+export type MarkusTable = {
+  type: "table";
+  align: Array<string | null>;
+  header: MarkusInline[][];
+  rows: MarkusInline[][][];
+  line: number | null;
+};
+
+export type MarkusBlock =
+  | MarkusHeading
+  | MarkusParagraph
+  | MarkusList
+  | MarkusBlockquote
+  | MarkusCodeBlock
+  | MarkusThematicBreak
+  | MarkusHtmlBlock
+  | MarkusTable;
+
+// --------------------------------------------------------------------------
+// Directives (markusmd/ast.py: Directive). Container directives have
+// `leaf: false` and nest further nodes; leaf directives (`metric`, `video`)
+// have `leaf: true` and always `children: []`. `attributes` is whatever the
+// directive's validated attribute schema produced -- Papyrus treats it as
+// an open record rather than typing every directive's attribute set, since
+// the vocabulary (and its attributes) are owned and validated by Markus,
+// not re-specified here.
+// --------------------------------------------------------------------------
+
+export type MarkusDirectiveAttributes = Record<string, string | number | boolean | null>;
+
+export type MarkusDirective = {
+  type: "directive";
+  name: string;
+  attributes: MarkusDirectiveAttributes;
+  leaf: boolean;
+  line: number;
+  children: MarkusNode[];
+};
+
+/** A document child: a typed Markdown block or a directive, in document order. */
+export type MarkusNode = MarkusBlock | MarkusDirective;
+
+// --------------------------------------------------------------------------
+// Document root (markusmd/ast.py: Document.to_dict()).
+// --------------------------------------------------------------------------
+
+export type MarkusFrontMatter = Record<string, unknown>;
+
+export type MarkusDocument = {
+  type: "document";
+  schema_version: number;
+  front_matter: MarkusFrontMatter;
+  children: MarkusNode[];
+};
+
+/**
+ * Thrown when ingested IR declares a `schema_version` this module was not
+ * typed against. This is the "fail loudly on mismatch" boundary check
+ * required before any projection runs -- silently proceeding against an
+ * unknown shape would risk mis-typed access on fields that changed shape.
+ */
+export class MarkusSchemaVersionError extends Error {
+  constructor(public readonly received: unknown) {
+    super(
+      `Markus document IR schema_version mismatch: this build understands ` +
+        `schema_version ${MARKUS_IR_SCHEMA_VERSION}, but received ` +
+        `${JSON.stringify(received)}. Re-derive lib/markus-ir.ts from a fresh ` +
+        `\`markus ast\` capture before ingesting this document.`,
+    );
+    this.name = "MarkusSchemaVersionError";
+  }
+}
+
+/**
+ * Parse + validate a raw `markus ast` JSON payload into a typed
+ * `MarkusDocument`, checking `schema_version` at the boundary. This is the
+ * only place Papyrus should accept untyped Markus IR JSON -- everything
+ * downstream (the Pretext projection, a future Markus build step) should
+ * consume the typed `MarkusDocument` this returns, never raw `unknown`.
+ */
+export function parseMarkusDocument(raw: unknown): MarkusDocument {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("Markus document IR must be a JSON object");
+  }
+  const candidate = raw as Record<string, unknown>;
+  if (candidate.type !== "document") {
+    throw new Error(`Expected Markus IR root node of type "document", got ${JSON.stringify(candidate.type)}`);
+  }
+  if (candidate.schema_version !== MARKUS_IR_SCHEMA_VERSION) {
+    throw new MarkusSchemaVersionError(candidate.schema_version);
+  }
+  return candidate as MarkusDocument;
+}

package/lib/markus-projection.ts

@@ -0,0 +1,243 @@
+/**
+ * The Pretext projection: turns a typed Markus document IR
+ * (`lib/markus-ir.ts`) into the flat structures the Pretext client solver
+ * consumes today -- `Article.body: string[]`, `Article.pullQuotes: string[]`,
+ * and figure-derived `ArticleImageAsset[]`.
+ *
+ * THIS PROJECTION IS LOSSY BY DESIGN. Markus's directive vocabulary
+ * (card-grid, two-up, callout, tabs, timeline, ...) is a strict superset of
+ * what Pretext can lay out -- Pretext cannot render a card grid. The
+ * non-negotiable degradation rule (decided on PPY-92f846 / PPY-a10206):
+ *
+ *   Any directive Pretext cannot express recurses into its children so its
+ *   content is preserved INLINE in `body`. Nothing is ever silently
+ *   dropped.
+ *
+ * The two directives Pretext *can* express get pulled into their own
+ * side-channels instead of `body`:
+ *   - `pull-quote`  -> `pullQuotes[]`
+ *   - `figure`      -> `images[]` (as `ArticleImageAsset`)
+ *
+ * This mirrors the verified prototype recorded on PPY-a10206: walk
+ * `children` in order; paragraph/heading push their flattened text onto
+ * `body`; `pull-quote` pushes onto `pullQuotes`; any other directive
+ * recurses into its children. This module generalizes that same rule to
+ * the rest of the typed block vocabulary (list/blockquote/code/table/
+ * thematic_break/html) that the prototype's sample article didn't happen
+ * to exercise, and to leaf directives with no children (`metric`, `video`)
+ * by degrading to their textual attributes rather than dropping them.
+ */
+
+import type { ArticleImageAsset } from "./articles";
+import {
+  parseMarkusDocument,
+  type MarkusBlock,
+  type MarkusDirective,
+  type MarkusDocument,
+  type MarkusInline,
+  type MarkusNode,
+} from "./markus-ir";
+
+export type PretextProjection = {
+  body: string[];
+  pullQuotes: string[];
+  images: ArticleImageAsset[];
+};
+
+/** Flatten an inline node tree to plain text. No markup survives -- Pretext's
+ * `body` is plain-text paragraphs, so emphasis/strong/links/code spans all
+ * degrade to their text content. Images are dropped here (they are not
+ * textual); a top-level `image` inline node inside a paragraph is rare in
+ * practice and, if it occurs, its alt text is preserved instead of the
+ * image itself, so no content vanishes silently. */
+function inlineText(nodes: MarkusInline[]): string {
+  return nodes
+    .map((node): string => {
+      switch (node.type) {
+        case "text":
+          return node.text;
+        case "code_span":
+          return node.code;
+        case "emphasis":
+        case "strong":
+        case "strikethrough":
+          return inlineText(node.children);
+        case "link":
+          return inlineText(node.children);
+        case "image":
+          return node.alt ?? "";
+        case "soft_break":
+          return " ";
+        case "hard_break":
+          return "\n";
+        case "html_inline":
+          // --allow-html is off for real Papyrus builds (see module doc);
+          // preserve the raw text rather than silently dropping it in the
+          // defensive case this ever appears.
+          return node.value;
+        default:
+          return "";
+      }
+    })
+    .join("")
+    .trim();
+}
+
+/** Flatten a block node's own text content (not directives -- callers walk
+ * directives separately so their degradation/side-channel rules apply). */
+function blockText(block: MarkusBlock): string[] {
+  switch (block.type) {
+    case "heading":
+    case "paragraph":
+      return [inlineText(block.inline)];
+    case "list":
+      return block.items.map((item) => flattenBlocksToText(item.children).join(" "));
+    case "blockquote":
+      return flattenBlocksToText(block.children);
+    case "code":
+      // A code block has no inline richness; preserve its literal text
+      // wholesale rather than dropping it because Pretext has no code
+      // rendering of its own.
+      return block.value.trim().length > 0 ? [block.value] : [];
+    case "thematic_break":
+      // No textual content exists to preserve; there is nothing to drop.
+      return [];
+    case "html":
+      // See `inlineText`'s html_inline case: only reachable if IR was ever
+      // produced with --allow-html, which Papyrus's build does not do.
+      return block.value.trim().length > 0 ? [block.value] : [];
+    case "table": {
+      const rowText = (row: MarkusInline[][]) => row.map((cell) => inlineText(cell)).join(" | ");
+      const lines = [rowText(block.header), ...block.rows.map(rowText)];
+      return lines.filter((line) => line.trim().length > 0);
+    }
+    default:
+      return [];
+  }
+}
+
+function isDirective(node: MarkusNode): node is MarkusDirective {
+  return node.type === "directive";
+}
+
+/** Degrade a leaf directive (no children by definition) to its textual
+ * attributes, so `metric`/`video` don't vanish just because they have
+ * nothing to recurse into. */
+function leafDirectiveText(directive: MarkusDirective): string[] {
+  const attrs = directive.attributes;
+  if (directive.name === "metric") {
+    const label = attrs.label != null ? String(attrs.label) : null;
+    const value = attrs.value != null ? String(attrs.value) : null;
+    const unit = attrs.unit != null ? String(attrs.unit) : "";
+    const text = [label, value != null ? `${value}${unit}` : null].filter(Boolean).join(": ");
+    return text.length > 0 ? [text] : [];
+  }
+  if (directive.name === "video") {
+    const title = attrs.title != null ? String(attrs.title) : null;
+    return title ? [title] : [];
+  }
+  // Unknown future leaf directive: fall back to whatever string-ish
+  // attributes it has rather than dropping it silently.
+  const text = Object.values(attrs)
+    .filter((value) => typeof value === "string" && value.trim().length > 0)
+    .join(" ");
+  return text ? [text] : [];
+}
+
+/** Extract an ArticleImageAsset from a `figure` directive's attributes. */
+function figureToImageAsset(directive: MarkusDirective, index: number): ArticleImageAsset {
+  const attrs = directive.attributes;
+  const src = attrs.src != null ? String(attrs.src) : "";
+  const alt = attrs.alt != null ? String(attrs.alt) : "";
+  const caption = attrs.caption != null ? String(attrs.caption) : undefined;
+  const credit = attrs.credit != null ? String(attrs.credit) : "";
+  return {
+    id: `figure-${index}`,
+    type: "image",
+    src,
+    alt,
+    caption,
+    credit,
+  };
+}
+
+function flattenBlocksToText(nodes: MarkusNode[]): string[] {
+  const out: string[] = [];
+  for (const node of nodes) {
+    if (isDirective(node)) {
+      out.push(...directiveDegradedText(node));
+    } else {
+      out.push(...blockText(node));
+    }
+  }
+  return out.filter((line) => line.trim().length > 0);
+}
+
+/** The degradation rule for a directive Pretext cannot render as itself:
+ * recurse into its children (or, for a leaf directive with no children,
+ * degrade to its attributes) so nothing is silently dropped. */
+function directiveDegradedText(directive: MarkusDirective): string[] {
+  if (directive.leaf || directive.children.length === 0) {
+    return leafDirectiveText(directive);
+  }
+  return flattenBlocksToText(directive.children);
+}
+
+/**
+ * Project a typed Markus document IR into the flat shape Pretext consumes.
+ * Walks `document.children` in order:
+ *   - `paragraph` / `heading` -> pushed onto `body`
+ *   - `list` / `blockquote` / `code` / `table` / `thematic_break` / `html`
+ *     -> degrade-preserved onto `body` (see `blockText`)
+ *   - directive `pull-quote` -> its flattened text goes to `pullQuotes`,
+ *     NOT `body`
+ *   - directive `figure` -> becomes an `ArticleImageAsset` in `images`,
+ *     NOT `body`
+ *   - any other directive (`card-grid`, `card`, `two-up`, `column`,
+ *     `callout`, `aside`, `details`, `tabs`, `tab`, `step-list`, `step`,
+ *     `timeline`, `timeline-event`, and any future addition to the
+ *     vocabulary) -> recurses into its children per the degradation rule
+ */
+export function projectMarkusDocumentToPretext(document: MarkusDocument): PretextProjection {
+  const body: string[] = [];
+  const pullQuotes: string[] = [];
+  const images: ArticleImageAsset[] = [];
+  let figureIndex = 0;
+
+  for (const node of document.children) {
+    if (isDirective(node)) {
+      if (node.name === "pull-quote") {
+        const text = flattenBlocksToText(node.children).join(" ");
+        if (text.trim().length > 0) pullQuotes.push(text);
+        continue;
+      }
+      if (node.name === "figure") {
+        images.push(figureToImageAsset(node, figureIndex));
+        figureIndex += 1;
+        // A figure directive's own children (if any future Markus version
+        // ever nests content under it) are still degraded into body so
+        // nothing is dropped, matching the non-negotiable rule.
+        if (node.children.length > 0) body.push(...flattenBlocksToText(node.children));
+        continue;
+      }
+      body.push(...directiveDegradedText(node));
+      continue;
+    }
+    body.push(...blockText(node));
+  }
+
+  return {
+    body: body.filter((line) => line.trim().length > 0),
+    pullQuotes,
+    images,
+  };
+}
+
+/**
+ * Convenience entry point: parse + validate raw `markus ast` JSON (failing
+ * loudly on schema mismatch, per `parseMarkusDocument`) and project it in
+ * one call.
+ */
+export function projectMarkusJsonToPretext(raw: unknown): PretextProjection {
+  return projectMarkusDocumentToPretext(parseMarkusDocument(raw));
+}