@legionworks/facet 1.9.0 → 1.10.1

package/src/service/store/repository-lifecycle.ts

@@ -2,6 +2,11 @@ import type { Database } from "bun:sqlite";
 
 import { type Template, TemplateSchema } from "../../shared/contracts/artifact";
 import { now } from "../../shared/util/time";
+import { FacetError } from "../../shared/errors/facet-error";
+import { PROMOTION_GATE } from "../../shared/contracts/promotion";
+import type { RenderStatus } from "../../shared/contracts/validation";
+import { verdictFromStoredRun } from "../stored-verdict";
+import type { ArtifactRepository } from "./repository";
 import { asStoreError, FacetStoreError } from "./database";
 
 export interface TemplateInput {
@@ -11,6 +16,7 @@ export interface TemplateInput {
   readonly description?: string | null;
   readonly promotedBy: string;
   readonly promotedAt?: string;
+  readonly promotionOverride?: string | null;
 }
 
 export interface PromoteRevisionInput {
@@ -20,6 +26,7 @@ export interface PromoteRevisionInput {
   readonly description?: string | null;
   readonly promotedBy: string;
   readonly promotedAt?: string;
+  readonly allowUnverified?: boolean;
 }
 
 export function evictRevisions(
@@ -59,23 +66,75 @@ export function evictRevisions(
   }
 }
 
-export function promoteRevision(db: Database, input: PromoteRevisionInput): Template {
-  const owner = db
-    .query("SELECT artifact_id FROM revisions WHERE id = ?")
-    .get(input.revisionId) as { artifact_id: string } | null;
-  if (!owner) throw new FacetStoreError("foreign_key", `Revision not found: ${input.revisionId}`);
-  // The template table has independent foreign keys on artifact_id and
-  // revision_id, not a composite ownership constraint, so an explicit
-  // artifactId that disagrees with the revision's real owner would
-  // otherwise insert silently — instantiation would then copy the wrong
-  // artifact's bytes under the caller-supplied artifact's identity.
-  if (input.artifactId !== undefined && input.artifactId !== owner.artifact_id) {
-    throw new FacetStoreError(
-      "foreign_key",
-      `Revision ${input.revisionId} belongs to artifact ${owner.artifact_id}, not ${input.artifactId}`,
-    );
-  }
-  return createTemplate(db, { ...input, artifactId: owner.artifact_id });
+export function promoteRevision(
+  db: Database,
+  repository: ArtifactRepository,
+  input: PromoteRevisionInput,
+): Template {
+  return db
+    .transaction(() => {
+      const owner = db
+        .query("SELECT artifact_id FROM revisions WHERE id = ?")
+        .get(input.revisionId) as { artifact_id: string } | null;
+      if (!owner)
+        throw new FacetStoreError("foreign_key", `Revision not found: ${input.revisionId}`);
+      // The template table has independent foreign keys on artifact_id and
+      // revision_id, not a composite ownership constraint, so an explicit
+      // artifactId that disagrees with the revision's real owner would
+      // otherwise insert silently — instantiation would then copy the wrong
+      // artifact's bytes under the caller-supplied artifact's identity.
+      if (input.artifactId !== undefined && input.artifactId !== owner.artifact_id) {
+        throw new FacetStoreError(
+          "foreign_key",
+          `Revision ${input.revisionId} belongs to artifact ${owner.artifact_id}, not ${input.artifactId}`,
+        );
+      }
+      const revision = repository.getRevisionById(input.revisionId);
+      if (revision === null)
+        throw new FacetStoreError("foreign_key", `Revision not found: ${input.revisionId}`);
+      const tier1 = repository.listRenderRuns({ revisionId: revision.id, tier: 1 })[0];
+      const tier0 = repository.listRenderRuns({ revisionId: revision.id, tier: 0 })[0];
+      // Read the marker from the reconstructed verdict object rather than
+      // the raw `insecure_json` column — `verdictFromStoredRun` is the single
+      // source of truth for cross-boundary reconstruction and keeps the
+      // precedence between status, tier, and marker consistent with the
+      // dispatcher's wire form.
+      const tier1Verdict = tier1 === undefined ? null : verdictFromStoredRun(revision, tier1);
+      const tier0Verdict = tier0 === undefined ? null : verdictFromStoredRun(revision, tier0);
+      const tier1Status = tier1Verdict === null ? null : tier1Verdict.status;
+      const tier0Status = tier0Verdict === null ? null : tier0Verdict.status;
+      // Level 3 opts out of the validation contract (publish skips Tier 0). A
+      // visual read-back still runs the browser, but a result carrying
+      // `insecure.level === 3` is not trusted verification for a template, so
+      // refuse even when the status alone would allow. Levels 1 and 2 keep the
+      // status decision: they run real validators under relaxed sandboxing.
+      const insecureLevel3 = tier1Verdict !== null && tier1Verdict.insecure?.level === 3;
+      const reason =
+        tier1Status === null
+          ? "no_visual_verification"
+          : tier0Status === "error"
+            ? "error"
+            : insecureLevel3
+              ? "insecure:unvalidated"
+              : PROMOTION_GATE[tier1Status as RenderStatus] === "allow"
+                ? null
+                : tier1Status;
+      if (reason !== null && input.allowUnverified !== true) {
+        throw new FacetError(
+          "promotion_refused",
+          `Promotion refused (${reason}). Run facet read-back --artifact-id ${owner.artifact_id} --tier visual on revision ${input.revisionId}, or pass --allow-unverified to record an override.`,
+          {
+            details: { revisionId: input.revisionId, reason, tier1Status, tier0Status },
+          },
+        );
+      }
+      return createTemplate(db, {
+        ...input,
+        artifactId: owner.artifact_id,
+        promotionOverride: reason,
+      });
+    })
+    .immediate();
 }
 
 export function createTemplate(db: Database, input: TemplateInput): Template {
@@ -88,10 +147,11 @@ export function createTemplate(db: Database, input: TemplateInput): Template {
     description: input.description ?? null,
     promotedBy: input.promotedBy,
     promotedAt,
+    promotionOverride: input.promotionOverride ?? null,
   };
   try {
     db.query(
-      "INSERT INTO templates(id, artifact_id, revision_id, name, description, promoted_by, promoted_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+      "INSERT INTO templates(id, artifact_id, revision_id, name, description, promoted_by, promoted_at, promotion_override) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
     ).run(
       value.id,
       value.artifactId,
@@ -100,10 +160,22 @@ export function createTemplate(db: Database, input: TemplateInput): Template {
       value.description,
       value.promotedBy,
       value.promotedAt,
+      value.promotionOverride,
     );
     return TemplateSchema.parse(value);
   } catch (error) {
-    throw asStoreError(error);
+    const mapped = asStoreError(error);
+    if (mapped.code === "template_name_taken") {
+      throw new FacetStoreError(
+        "template_name_taken",
+        `Template name already exists: ${input.name}`,
+        {
+          cause: error,
+          details: { name: input.name },
+        },
+      );
+    }
+    throw mapped;
   }
 }
 

package/src/service/store/repository.ts

@@ -32,6 +32,7 @@ import {
   type TemplateInput,
 } from "./repository-lifecycle";
 import { enforceEvidenceRetention, removeUnreferencedEvidence } from "./evidence-retention";
+import { latestStoredVerdict } from "../stored-verdict";
 
 interface ProjectInput {
   readonly projectRoot: string;
@@ -407,7 +408,7 @@ export class ArtifactRepository {
     try {
       const row = this.db
         .query(
-          "SELECT id, artifact_id, revision_id, name, description, promoted_by, promoted_at FROM templates WHERE name = ? ORDER BY promoted_at DESC LIMIT 1",
+          "SELECT id, artifact_id, revision_id, name, description, promoted_by, promoted_at, promotion_override FROM templates WHERE name = ? ORDER BY promoted_at DESC LIMIT 1",
         )
         .get(name) as {
         id: string;
@@ -417,6 +418,7 @@ export class ArtifactRepository {
         description: string | null;
         promoted_by: string;
         promoted_at: string;
+        promotion_override: string | null;
       } | null;
       if (!row) return null;
       return TemplateSchema.parse({
@@ -427,12 +429,68 @@ export class ArtifactRepository {
         description: row.description,
         promotedBy: row.promoted_by,
         promotedAt: row.promoted_at,
+        promotionOverride: row.promotion_override,
       });
     } catch (error) {
       throw asStoreError(error);
     }
   }
 
+  listTemplates(limit = DEFAULT_LIST_LIMIT): Array<{
+    name: string;
+    artifactId: string;
+    revisionId: string;
+    revisionSha: string;
+    promotedBy: string;
+    promotedAt: string;
+    promotionOverride: string | null;
+    sourceVerdict: {
+      status: import("../../shared/contracts/validation").RenderStatus;
+      tier: 0 | 1;
+    } | null;
+  }> {
+    const rows = this.db
+      .query(
+        "SELECT id, artifact_id, revision_id, name, description, promoted_by, promoted_at, promotion_override FROM templates ORDER BY promoted_at DESC, id DESC LIMIT ?",
+      )
+      .all(limit) as Array<{
+      id: string;
+      artifact_id: string;
+      revision_id: string;
+      name: string;
+      description: string | null;
+      promoted_by: string;
+      promoted_at: string;
+      promotion_override: string | null;
+    }>;
+    return rows.map((row) => {
+      const revision = this.getRevisionById(row.revision_id);
+      if (revision === null)
+        throw new FacetStoreError("foreign_key", `Template revision not found: ${row.revision_id}`);
+      const template = TemplateSchema.parse({
+        id: row.id,
+        artifactId: row.artifact_id,
+        revisionId: row.revision_id,
+        name: row.name,
+        description: row.description,
+        promotedBy: row.promoted_by,
+        promotedAt: row.promoted_at,
+        promotionOverride: row.promotion_override,
+      });
+      const verdict = latestStoredVerdict(this, revision);
+      return {
+        name: template.name,
+        artifactId: template.artifactId,
+        revisionId: template.revisionId,
+        revisionSha: revision.sha256,
+        promotedBy: template.promotedBy,
+        promotedAt: template.promotedAt,
+        promotionOverride: template.promotionOverride,
+        sourceVerdict: verdict === null ? null : { status: verdict.status, tier: verdict.tier },
+      };
+    });
+  }
+
   createArtifact(input: ArtifactInput): Artifact {
     const createdAt = now();
     const value = { id: crypto.randomUUID(), ...input, createdAt, updatedAt: createdAt };
@@ -715,7 +773,7 @@ export class ArtifactRepository {
   }
 
   promoteRevision(input: PromoteRevisionInput): Template {
-    return promoteLifecycleRevision(this.db, input);
+    return promoteLifecycleRevision(this.db, this, input);
   }
 
   instantiateTemplate(input: TemplateInput): Template {

package/src/service/store/schema.ts

@@ -216,3 +216,7 @@ export const V9_SCHEMA_FRAGMENT = `
 ALTER TABLE render_runs ADD COLUMN screenshot_format TEXT
   CHECK(screenshot_format IN ('png','webp'));
 `;
+
+export const V10_SCHEMA_FRAGMENT = `
+ALTER TABLE templates ADD COLUMN promotion_override TEXT;
+`;

package/src/service/stored-verdict.ts

@@ -39,6 +39,9 @@ export function withTolerantObserved(parsed: unknown): VerdictObserved {
     visibleSvgCount: num("visibleSvgCount", 0),
     opaqueRegionCount: num("opaqueRegionCount", 0),
     externalImageCount: num("externalImageCount", 0),
+    ...(typeof observed.emptyRendererRoot === "boolean"
+      ? { emptyRendererRoot: observed.emptyRendererRoot }
+      : {}),
     // errorCount is required on the schema; pre-arc rows that never
     // recorded it default to 0.
     errorCount: num("errorCount", 0),

package/src/shared/contracts/artifact.ts

@@ -94,5 +94,6 @@ export const TemplateSchema = z.object({
   description: z.string().nullable(),
   promotedBy: z.string().min(1),
   promotedAt: IsoTimestampSchema,
+  promotionOverride: z.string().nullable(),
 });
 export type Template = z.infer<typeof TemplateSchema>;

package/src/shared/contracts/commands/index.ts

@@ -33,6 +33,7 @@ import {
   CreateRequestSchema,
   InstantiateRequestSchema,
   ListRequestSchema,
+  TemplatesRequestSchema,
   OpenRequestSchema,
   PinRequestSchema,
   PromoteRequestSchema,
@@ -45,6 +46,7 @@ import {
   type CreateRequest,
   type InstantiateRequest,
   type ListRequest,
+  type TemplatesRequest,
   type OpenRequest,
   type PinRequest,
   type PromoteRequest,
@@ -58,6 +60,7 @@ import {
   CreateResultSchema,
   InstantiateResultSchema,
   ListResultSchema,
+  TemplatesResultSchema,
   OpenResultSchema,
   PinResultSchema,
   PromoteResultSchema,
@@ -72,6 +75,7 @@ import {
   type CreateResult,
   type InstantiateResult,
   type ListResult,
+  type TemplatesResult,
   type OpenResult,
   type PinResult,
   type PromoteResult,
@@ -98,6 +102,7 @@ export const CommandRequestSchema = z.discriminatedUnion("command", [
   CreateRequestSchema,
   PublishRequestSchema,
   ListRequestSchema,
+  TemplatesRequestSchema,
   ReadBackRequestSchema,
   StatusRequestSchema,
   OpenRequestSchema,
@@ -112,6 +117,7 @@ export const CommandResultSchema = z.discriminatedUnion("command", [
   CreateResultSchema,
   PublishResultSchema,
   ListResultSchema,
+  TemplatesResultSchema,
   ReadBackResultSchema,
   StatusResultSchema,
   OpenResultSchema,
@@ -145,6 +151,7 @@ export {
   PublishRequestSchema,
   PublishArtifactTypeSchema,
   ListRequestSchema,
+  TemplatesRequestSchema,
   ReadBackRequestSchema,
   StatusRequestSchema,
   OpenRequestSchema,
@@ -157,6 +164,7 @@ export {
   CreateResultSchema,
   PublishResultSchema,
   ListResultSchema,
+  TemplatesResultSchema,
   ReadBackResultSchema,
   StatusResultSchema,
   OpenResultSchema,
@@ -180,6 +188,7 @@ export type {
   CreateRequest,
   PublishRequest,
   ListRequest,
+  TemplatesRequest,
   ReadBackRequest,
   StatusRequest,
   OpenRequest,
@@ -191,6 +200,7 @@ export type {
   CreateResult,
   PublishResult,
   ListResult,
+  TemplatesResult,
   ReadBackResult,
   StatusResult,
   DoctorResult,

package/src/shared/contracts/commands/names.ts

@@ -9,6 +9,7 @@ export const CommandNameSchema = z.enum([
   "create",
   "publish",
   "list",
+  "templates",
   "readBack",
   "status",
   "open",
@@ -23,6 +24,7 @@ export const IMPLEMENTED_COMMANDS: readonly CommandName[] = [
   "create",
   "publish",
   "list",
+  "templates",
   "readBack",
   "status",
   "open",

package/src/shared/contracts/commands/requests.ts

@@ -82,6 +82,12 @@ export const ListRequestSchema = BaseRequestSchema.extend({
 });
 export type ListRequest = z.infer<typeof ListRequestSchema>;
 
+export const TemplatesRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("templates"),
+  limit: z.number().int().positive().max(MAX_LIST_LIMIT).optional(),
+});
+export type TemplatesRequest = z.infer<typeof TemplatesRequestSchema>;
+
 export const ReadBackRequestSchema = BaseRequestSchema.extend({
   command: z.literal("readBack"),
   artifactId: z.string().min(1),
@@ -116,6 +122,7 @@ export const PromoteRequestSchema = BaseRequestSchema.extend({
   name: z.string().min(1),
   description: z.string().nullable().optional(),
   promotedBy: z.string().min(1),
+  allowUnverified: z.boolean().optional(),
 });
 export type PromoteRequest = z.infer<typeof PromoteRequestSchema>;
 

package/src/shared/contracts/commands/results.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-import { Tier1ResultSchema, VerdictSchema } from "../validation";
+import { Tier1ResultSchema, VerdictSchema, RenderStatusSchema } from "../validation";
 import { ArtifactTypeSchema, RendererSchema } from "../artifact";
 import { EvidenceImageFormatSchema } from "../../evidence-image";
 import { ExportFormatSchema } from "./requests";
@@ -64,6 +64,25 @@ export const ListResultSchema = BaseResultSchema.extend({
 });
 export type ListResult = z.infer<typeof ListResultSchema>;
 
+export const TemplatesResultSchema = BaseResultSchema.extend({
+  command: z.literal("templates"),
+  templates: z.array(
+    z.object({
+      name: z.string().min(1),
+      artifactId: z.string().min(1),
+      revisionId: z.string().min(1),
+      revisionSha: z.string().regex(/^[a-f0-9]{64}$/),
+      promotedBy: z.string().min(1),
+      promotedAt: z.string().datetime({ offset: true }),
+      promotionOverride: z.string().nullable(),
+      sourceVerdict: z
+        .object({ status: RenderStatusSchema, tier: z.union([z.literal(0), z.literal(1)]) })
+        .nullable(),
+    }),
+  ),
+});
+export type TemplatesResult = z.infer<typeof TemplatesResultSchema>;
+
 /**
  * Read-back result embeds the canonical `VerdictSchema` from
  * `validation.ts`. The two definitions are the SAME object so a

package/src/shared/contracts/promotion.ts

@@ -0,0 +1,16 @@
+import type { RenderStatus } from "./validation";
+
+export const PROMOTION_GATE = {
+  ok: "allow",
+  error: "refuse",
+  "partial:layout_unverified": "allow",
+  "partial:opaque_content": "allow",
+  "partial:external_resources": "allow",
+  "partial:unstable": "allow",
+  "partial:empty_render": "refuse",
+  tampered: "refuse",
+  timeout: "refuse",
+  shim_only: "refuse",
+  probe_only: "refuse",
+  "insecure:unvalidated": "refuse",
+} as const satisfies Record<RenderStatus, "allow" | "refuse">;

package/src/shared/contracts/validation.ts

@@ -36,6 +36,7 @@ export const RenderStatusSchema = z.enum([
   "partial:opaque_content",
   "partial:external_resources",
   "partial:unstable",
+  "partial:empty_render",
   "tampered",
   "timeout",
   "shim_only",
@@ -134,9 +135,14 @@ export type LexicalCounters = z.infer<typeof LexicalCountersSchema>;
 const ObservedCountShape = Object.fromEntries(
   OBSERVED_COUNT_KEYS.map((key) => [key, z.number().int().nonnegative()]),
 ) as Record<(typeof OBSERVED_COUNT_KEYS)[number], z.ZodNumber>;
+const RenderedContentShape = {
+  // Legacy stored observations lack this TSX-only probe; absence never proves an empty render.
+  emptyRendererRoot: z.boolean().optional(),
+};
 
 export const VerdictObservedSchema = z.object({
   ...ObservedCountShape,
+  ...RenderedContentShape,
   html: HtmlStructureCountsSchema.optional(),
   viewBoxes: z.array(z.string()).optional(),
   errorCount: z.number().int().nonnegative(),
@@ -288,6 +294,7 @@ export type Tier1Result = z.infer<typeof Tier1ResultSchema>;
  */
 export const ProtocolObservationSchema = z.object({
   ...ObservedCountShape,
+  ...RenderedContentShape,
   html: HtmlStructureCountsSchema.optional(),
   viewBoxes: z.array(z.string()),
   errorCount: z.number().int().nonnegative(),

package/src/shared/errors/facet-error.ts

@@ -12,6 +12,7 @@ export const FacetErrorCodes = {
   database_busy: true,
   disk_full: true,
   duplicate_revision: true,
+  template_name_taken: true,
   foreign_key: true,
   immutable_revision: true,
   migration_failed: true,
@@ -27,6 +28,7 @@ export const FacetErrorCodes = {
   artifact_not_found: true,
   revision_not_found: true,
   template_not_found: true,
+  promotion_refused: true,
   evidence_unavailable: true,
   output_unwritable: true,
   revision_capacity_pinned: true,

package/src/shared/errors/store-error.ts

@@ -18,6 +18,7 @@ export type StoreErrorCode = Extract<
   | "database_busy"
   | "disk_full"
   | "duplicate_revision"
+  | "template_name_taken"
   | "foreign_key"
   | "immutable_revision"
   | "migration_failed"
@@ -62,6 +63,9 @@ export function asStoreError(error: unknown): FacetStoreError {
     return new FacetStoreError("foreign_key", message, { cause: error });
   }
   if (lower.includes("unique constraint")) {
+    if (lower.includes("templates.name")) {
+      return new FacetStoreError("template_name_taken", message, { cause: error });
+    }
     return new FacetStoreError("duplicate_revision", message, { cause: error });
   }
   return new FacetStoreError("constraint", message, { cause: error });

package/src/shared/html/artifact-main.ts

@@ -0,0 +1,3 @@
+export function artifactMainAttributes(artifactType: string): string {
+  return `id="artifact" data-facet-artifact-type="${artifactType}"`;
+}

package/src/shared/html/style-vocabulary.ts

@@ -28,6 +28,7 @@ export const HTML_TAILWIND_CLASSES = [
   "mt-4",
   "mb-2",
   "mb-4",
+  "mx-auto",
   "w-full",
   "max-w-prose",
   "max-w-2xl",

package/src/shared/storage-version.ts

@@ -1,2 +1,2 @@
 /** Latest schema migration applied by the service. */
-export const CURRENT_STORAGE_VERSION = 9 as const;
+export const CURRENT_STORAGE_VERSION = 10 as const;

package/src/validation/tier0/dom-shim.ts

@@ -1,12 +1,9 @@
 /**
  * linkedom-based DOM shim for the Tier 0 worker.
  *
- * Mermaid and other browser-shaped libraries perform import-time
- * initialization against `globalThis.document`, `window`, and the
- * `implementation.createHTMLDocument` API. Bun's worker process has
- * none of these by default, so a naive `import mermaid from "mermaid"`
- * throws `DOMPurify.addHook is not a function` (or its equivalent)
- * before the parser ever sees source.
+ * Mermaid needs a minimal DOM for import and parsing in the worker.
+ * Tier 0 does not render labels; their sanitization is a render concern
+ * verified by Tier 1.
  *
  * This module installs the shim at IMPORT TIME (top-level) so any
  * subsequent `import "mermaid"` sees a DOM. It is structural only —
@@ -24,17 +21,6 @@ function installDomShim(): void {
   installed = true;
   const { document, window } = parseHTML("<!DOCTYPE html><html><body></body></html>");
   domShimDocument = document as unknown as Document;
-  // DOMPurify's isSupported check looks for `implementation.createHTMLDocument`.
-  // linkedom ships without an implementation object; we attach a minimal shim
-  // that returns a freshly-parsed document. This is structural only —
-  // we never serialize against this DOM.
-  const fakeImpl = {
-    createHTMLDocument: (html: string): Document => {
-      const r = parseHTML(html);
-      return r.document as unknown as Document;
-    },
-  };
-  Object.defineProperty(document, "implementation", { value: fakeImpl, configurable: true });
   const g = globalThis as unknown as Record<string, unknown>;
   g["document"] = document;
   g["window"] = window;
@@ -43,7 +29,6 @@ function installDomShim(): void {
   g["Node"] = window.Node;
   g["DocumentFragment"] = window.DocumentFragment;
   g["HTMLTemplateElement"] = window.HTMLTemplateElement;
-  g["NodeFilter"] = window.NodeFilter;
 }
 
 // Top-level install — runs synchronously when this module is first

package/src/validation/tier0/markdown.ts

@@ -30,6 +30,7 @@ import { Lexer, type Token, type Tokens } from "marked";
 
 import type { DiscriminativeError, VerdictObserved } from "../../shared/contracts/validation";
 import { countMermaidNodeDeclarations } from "../../shared/util/mermaid-nodes";
+import { parseMermaidText } from "./mermaid";
 
 export interface MarkdownParseOk {
   readonly status: "ok";
@@ -54,6 +55,7 @@ interface MarkdownCounts {
   hasScript: boolean;
   hasOnHandler: boolean;
   hasExternalRef: boolean;
+  mermaidBodies: string[];
 }
 
 function isExternalHttpsUrl(value: string): boolean {
@@ -102,6 +104,7 @@ function walkTokens(tokens: Token[], counts: MarkdownCounts): void {
       counts.totalFenced += 1;
       const lang = (code.lang ?? "").trim().toLowerCase();
       if (lang === "mermaid") {
+        counts.mermaidBodies.push(code.text);
         counts.mermaidFenced += 1;
         counts.rendererRoots += 1;
         const nodes = countMermaidNodeDeclarations(code.text);
@@ -161,12 +164,11 @@ function walkTokens(tokens: Token[], counts: MarkdownCounts): void {
 }
 
 /**
- * Parse the source bytes as markdown. Pure tokenization — no DOM, no
- * render, no script execution. Raw HTML is counted (it must NOT
- * execute, and we surface structural red flags if it tries to smuggle
- * one) but never interpreted.
+ * Tokenize Markdown and grammar-check Mermaid fences without rendering
+ * or executing source. Raw HTML is counted and checked for structural
+ * red flags, but never interpreted.
  */
-export function parseMarkdown(bytes: Uint8Array): MarkdownParseResult {
+export async function parseMarkdown(bytes: Uint8Array): Promise<MarkdownParseResult> {
   const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
   const counts: MarkdownCounts = {
     totalFenced: 0,
@@ -178,6 +180,7 @@ export function parseMarkdown(bytes: Uint8Array): MarkdownParseResult {
     hasScript: false,
     hasOnHandler: false,
     hasExternalRef: false,
+    mermaidBodies: [],
   };
   let lexError: unknown = null;
   let tokens: Token[] = [];
@@ -189,6 +192,26 @@ export function parseMarkdown(bytes: Uint8Array): MarkdownParseResult {
     lexError = error;
   }
 
+  for (let i = 0; i < counts.mermaidBodies.length; i += 1) {
+    const message = await parseMermaidText(counts.mermaidBodies[i]!);
+    if (message !== null) {
+      // Fence grammar errors take precedence over lexer and hostile-HTML errors.
+      return {
+        status: "error",
+        observed: {
+          rendererRootSvgCount: counts.rendererRoots,
+          graphCount: counts.mermaidFenced,
+          mermaidNodeCount: counts.mermaidNodeCount ?? 0,
+          visibleSvgCount: 0,
+          externalImageCount: counts.externalImageCount,
+          errorCount: 1,
+          opaqueRegionCount: 0,
+        },
+        errors: [{ code: "mermaid_parse_error", message, location: `mermaid fence ${i}` }],
+      };
+    }
+  }
+
   if (lexError !== null) {
     const message = lexError instanceof Error ? lexError.message : String(lexError);
     return {