@markdstage/markdstage 3.1.0 → 3.3.0

package/shared/renderer/theme.mjs

@@ -91,6 +91,60 @@ export function serializeThemeVariables(variables) {
     .join("");
 }
 
+// Mermaid's "base" theme accepts a `themeVariables` palette instead of one of
+// its built-in named themes (dark/default/neutral/forest). Deriving that
+// palette from the rendered deck's custom properties makes Mermaid diagrams
+// share the slide's background, border, and text colors instead of only
+// approximating the deck theme, and it reuses the same primary/secondary
+// roles as the Architecture DSL (nodes: surface+border+fg, groups:
+// accent-soft+accent-line+accent-strong) so both diagram types match.
+//
+// `secondaryColor`/`tertiaryColor` also back many categorical fills across
+// Mermaid's diagram types (pie slices, git graph nodes, venn/quadrant charts,
+// activation highlights, ...), so they must stay solid and clearly visible
+// against `--bg` rather than reusing the translucent `--accent-soft` wash or
+// `--bg` itself, which rendered those fills nearly invisible. `noteBkgColor`/
+// `noteBorderColor`/`noteTextColor` are hardcoded by Mermaid's base theme
+// (always a pale yellow) unless set explicitly, so sequence-diagram notes
+// need their own override to follow the deck theme too.
+export function mermaidThemeVariables(style) {
+  const read = (name) => style.getPropertyValue(name).trim();
+  const background = read("--bg");
+  const surface = read("--surface");
+  const border = read("--border");
+  const foreground = read("--fg");
+  const muted = read("--muted");
+  const accent = read("--accent");
+  const accentStrong = read("--accent-strong");
+  const accentSoft = read("--accent-soft");
+  const accentLine = read("--accent-line");
+
+  return {
+    background,
+    primaryColor: surface,
+    primaryTextColor: foreground,
+    primaryBorderColor: border,
+    secondaryColor: accentStrong,
+    secondaryTextColor: background,
+    secondaryBorderColor: accentLine,
+    tertiaryColor: muted,
+    tertiaryTextColor: background,
+    tertiaryBorderColor: border,
+    lineColor: accent,
+    textColor: foreground,
+    mainBkg: surface,
+    nodeBorder: border,
+    clusterBkg: accentSoft,
+    clusterBorder: accentLine,
+    titleColor: foreground,
+    edgeLabelBackground: background,
+    noteBkgColor: accentSoft,
+    noteBorderColor: accentLine,
+    noteTextColor: accentStrong,
+    pie1: accent,
+  };
+}
+
 function assertPlainObject(value, path) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`${path} must be an object`);

package/shared/runtime/architecture-editor-server.mjs

@@ -581,6 +581,11 @@ export async function startArchitectureEditorServer({
     if (
       [
         "/renderer/architecture.mjs",
+        "/renderer/architecture-scene.mjs",
+        "/renderer/scene-graph.mjs",
+        "/renderer/scene-svg.mjs",
+        "/renderer/architecture-contract.mjs",
+        "/renderer/architecture-diagnostics.mjs",
         "/renderer/architecture-edit.mjs",
         "/renderer/architecture-document.mjs",
       ].includes(route)

package/shared/runtime/architecture-source.mjs

@@ -2,6 +2,7 @@ import { readFile, realpath, stat } from "node:fs/promises";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 
 import { parseArchitecture } from "../renderer/architecture.mjs";
+import { ArchitectureError } from "../renderer/architecture-diagnostics.mjs";
 import {
   findArchitectureBlocks,
   replaceArchitectureBlock,
@@ -85,7 +86,11 @@ export async function readArchitectureSourceTarget(workspaceRoot, sourcePath, bl
   try {
     parseArchitecture(block.body);
   } catch (error) {
-    throw sourceError("invalid_architecture", error?.message || "Invalid Architecture DSL.");
+    if (!(error instanceof ArchitectureError)) throw error;
+    throw Object.assign(
+      sourceError("invalid_architecture", error.message || "Invalid Architecture DSL."),
+      { diagnostic: error.diagnostic, validation: error.validation },
+    );
   }
   return { ...target, markdown, source: block.body };
 }
@@ -103,10 +108,13 @@ export function saveArchitectureSource({
     try {
       parseArchitecture(source);
     } catch (error) {
+      if (!(error instanceof ArchitectureError)) throw error;
       return {
         ok: false,
         error: "invalid_architecture",
         message: error?.message || "The diagram is invalid.",
+        diagnostic: error.diagnostic,
+        validation: error.validation,
       };
     }
 

package/shared/runtime/pptx-package.mjs

@@ -707,7 +707,7 @@ function tableXml(element, path, id, relationships) {
   return `<p:graphicFrame><p:nvGraphicFramePr><p:cNvPr id="${id}" name="Table ${id}"/><p:cNvGraphicFramePr/><p:nvPr/></p:nvGraphicFramePr>${xfrmXml(bounds, "p:xfrm")}<a:graphic><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/table"><a:tbl><a:tblPr firstRow="1" bandRow="1"/><a:tblGrid>${columns}</a:tblGrid>${rows}</a:tbl></a:graphicData></a:graphic></p:graphicFrame>`;
 }
 
-function arrowXml(value, path) {
+function arrowXml(value, path, end = "tailEnd") {
   if (value === undefined || value === null || value === false || value === "none") {
     return "";
   }
@@ -722,7 +722,7 @@ function arrowXml(value, path) {
           oval: "oval",
         }[value];
   if (!type) fail(`${path} is not a supported arrow end`);
-  return `<a:tailEnd type="${type}"/>`;
+  return `<a:${end} type="${type}"/>`;
 }
 
 function connectorXml(element, path, nextId, relationships) {
@@ -756,6 +756,7 @@ function connectorXml(element, path, nextId, relationships) {
     const y = Math.min(start.y, end.y);
     const flipH = end.x < start.x ? ' flipH="1"' : "";
     const flipV = end.y < start.y ? ' flipV="1"' : "";
+    const head = index === 0 ? arrowXml(element.arrowStart, `${path}.arrowStart`, "headEnd") : "";
     const tail =
       index === points.length - 2
         ? arrowXml(element.arrowEnd, `${path}.arrowEnd`)
@@ -763,7 +764,7 @@ function connectorXml(element, path, nextId, relationships) {
     shapes.push(
       `<p:sp><p:nvSpPr><p:cNvPr id="${id}" name="Connector ${id}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr><p:spPr><a:xfrm${flipH}${flipV}><a:off x="${emu(x)}" y="${emu(y)}"/><a:ext cx="${emu(Math.abs(end.x - start.x))}" cy="${emu(Math.abs(end.y - start.y))}"/></a:xfrm><a:prstGeom prst="line"><a:avLst/></a:prstGeom><a:ln w="${emu(width)}"><a:solidFill><a:srgbClr val="${color.hex}">${
         alpha < 100000 ? `<a:alpha val="${alpha}"/>` : ""
-      }</a:srgbClr></a:solidFill>${dash}${tail}</a:ln></p:spPr></p:sp>`,
+      }</a:srgbClr></a:solidFill>${dash}${head}${tail}</a:ln></p:spPr></p:sp>`,
     );
   }
   if (element.label !== undefined) {

package/shared/schema/README.md

@@ -9,8 +9,8 @@ fences. It supports editor completion and validation as well as automated CI val
 | `examples/*.architecture.json` | Working examples with `$schema` |
 
 This directory is **intentionally included in the distribution ZIP** so users can
-reference the schema locally. The extension does not load it at runtime (see
-`.github/RELEASING.md`).
+reference the schema locally. Browser rendering uses a generated, dependency-free
+ES-module contract rather than loading JSON Schema or a validation package.
 
 ## Usage
 
@@ -91,7 +91,7 @@ constraints, so `renderer/architecture.mjs` is authoritative:
 | Self-referencing connectors are prohibited | Same as above |
 | Each `id` is unique across the complete tree | Applies to the flattened set of nested elements |
 | 200 elements / 100 connectors / 20,000 text characters | Aggregated **after flattening**, not expressible by `maxItems` on one array |
-| 64 KiB source | String length before parsing |
+| 65,536 source code units (UTF-16) | Existing JavaScript string-length limit before parsing; distinct from UTF-8 guide-response budgets |
 | Layout fit (`children do not fit`) | Calculated dynamically from child sizes and group interior dimensions |
 | Child `width` / `height` maximum under `layout` | Maximum depends on `cellWidth` / `cellHeight` |
 | The `assets/` file referenced by `node.icon` / `image.src` exists | The parser does not access the file system; a missing file renders an empty image region |
@@ -99,6 +99,43 @@ constraints, so `renderer/architecture.mjs` is authoritative:
 `parseArchitecture` can fail even after schema validation. **The parser always
 makes the final determination of whether a diagram can render.**
 
+### Shared authoring and diagnostic boundary
+
+The bundled JSON Schema is the source of structural vocabulary, not a second
+runtime acceptance policy. A reproducible generation step derives browser-safe
+metadata for permitted fields, element types, scalar constraints, and conditional
+requirements. The compact AI reference and runtime vocabulary consume that same
+metadata. No UI or tool maintains its own permitted-field list.
+
+Rendering, editing, saving, CLI validation, and unloaded-input validation share
+the existing normalizer and semantic checks. Successfully normalized v1 input
+remains accepted even where the authoring schema is intentionally stricter.
+Such differences are authoring warnings, not new errors. On rejected input,
+the common diagnostic layer explains independently checkable structural issues
+from the derived contract and uses the same ID/reference checks as rendering.
+It neither repairs the input nor reruns the parser with deleted fields or
+invented defaults.
+
+Diagnostics carry stable codes, categories, severity, JSON Pointers, human
+messages, and nonautomatic suggestions. A conflicting replacement value is
+reported rather than overwritten. JSON parsing, structural, semantic, and
+layout stages distinguish passed, failed, and skipped work. Bounded diagnostic
+collection reports truncation explicitly; a skipped stage is not evidence that
+its constraints passed. Legacy exception messages and block-level error arrays
+remain available alongside the detailed report.
+
+Unloaded validation is a read-only boundary: it accepts explicit DSL text or
+individual Markdown slide fragments and has no authority to open a canvas,
+change its current page, read or write files, or modify editor drafts.
+API execution success is separate from content validity and completeness.
+Diagnostic budgets are not additional DSL v1 restrictions. Image existence,
+slide clipping, and visual clarity still require separate asset/output review.
+
+This preserves the existing schema/runtime responsibility split without a
+browser-side schema dependency or a parser replacement. The tradeoff is a
+generated artifact that must be kept in sync; a drift check makes that
+requirement enforceable.
+
 ### Invariant: P ⊆ A, except for documented divergences
 
 As a rule, documents accepted by the parser (P) must also be accepted by the
@@ -112,6 +149,8 @@ divergence must make the schema stricter, and every instance is listed below.**
 | # | Case | Behavior | Reason |
 | --- | --- | --- | --- |
 | 1 | A child of a group with `layout` has nonnumeric `x` / `y` | Parser accepts; schema rejects | Placement is calculated automatically under `layout`, so the parser silently discards `x` / `y` without validating their values. This likely indicates an authoring mistake that the schema should report. Tightening the parser would reject previously accepted input and would be a breaking change. |
+| 2 | A layout child has numeric `x` / `y` outside the schema range | Parser accepts; schema rejects | Parent-managed placement ignores these values just as it ignores nonnumeric coordinates. Preflight reports a compatibility warning. |
+| 3 | Root `$schema` is not a string | Parser accepts; schema rejects | v1 ignores this metadata without resolving it. Editor completion requires a string; preflight warns without changing runtime acceptance. |
 
 Divergences are recorded as `divergence` entries in `test/schema/corpus.mjs`,
 and tests fail when no reason string is present. **CI detects silent divergence.**
@@ -224,5 +263,21 @@ Because `layered` calculates hierarchy from connector direction, **do not specif
 child `x` / `y`**. This matches existing `grid` / `row` / `column` behavior.
 
 The validation library (`ajv`) is a **root devDependency**. The extension ships
-as a ZIP and must run without `node_modules`, so do not import the schema or ajv
-from `renderer/architecture.mjs`.
+as a ZIP and must run without `node_modules`, so do not import JSON Schema or
+ajv from the renderer. Regenerate the browser-safe metadata after a schema
+change with:
+
+```powershell
+node .github\extensions\markdstage\scripts\generate-architecture-contract.mjs
+```
+
+The same command with `--check` fails on drift. The authoring reference, including
+its self-contained example, must remain within 8 KiB UTF-8. Public valid examples
+are checked against both Schema and runtime; intentionally invalid examples
+remain explicitly marked as described above.
+
+The generated module has a separate distribution budget: it must stay below
+1,000,000 bytes, the conservative interpretation of the installer's 1 MB
+single-file limit. An automated size check measures the actual generated file.
+This is independent of both the 8 KiB guide-response budget and the existing
+DSL source-length limit.

package/shared/schema/architecture-contract.mjs

@@ -0,0 +1,355 @@
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const annotations = new Set(["$schema", "$id", "$anchor", "$comment", "title", "description", "examples"]);
+const schemaMaps = new Set(["properties", "patternProperties", "dependentSchemas", "$defs"]);
+const schemaArrays = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+const schemaValues = new Set([
+  "items", "contains", "additionalProperties", "unevaluatedProperties", "unevaluatedItems",
+  "propertyNames", "not", "if", "then", "else", "contentSchema",
+]);
+const scalarKeywords = new Set([
+  ...annotations, "type", "enum", "const", "required", "default", "deprecated", "readOnly",
+  "writeOnly", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf",
+  "minLength", "maxLength", "pattern", "format", "minItems", "maxItems", "uniqueItems",
+  "minContains", "maxContains", "minProperties", "maxProperties", "dependentRequired",
+  "contentEncoding", "contentMediaType",
+]);
+
+function unsupported(path, message) {
+  throw new Error(`Unsupported Architecture contract derivation at ${path}: ${message}`);
+}
+
+function ordered(value) {
+  if (Array.isArray(value)) return value.map(ordered);
+  if (!object(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, ordered(value[key])]));
+}
+
+function signature(value) {
+  return JSON.stringify(ordered(value));
+}
+
+function assertions(value) {
+  if (!object(value)) return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !annotations.has(key))
+    .map(([key, entry]) => [
+      key,
+      schemaMaps.has(key)
+        ? Object.fromEntries(Object.entries(entry).map(([name, child]) => [name, assertions(child)]))
+        : schemaArrays.has(key) ? entry.map(assertions)
+          : schemaValues.has(key) ? assertions(entry) : entry,
+    ]));
+}
+
+function conjoin(left, right, path) {
+  if (left === true) return right;
+  if (right === true) return left;
+  if (left === false || right === false) return false;
+  for (const [closed, other] of [[left, right], [right, left]]) {
+    if (closed.additionalProperties === false &&
+        Object.keys(other.properties ?? {}).some((key) => !own(closed.properties ?? {}, key))) {
+      unsupported(path, "allOf cannot widen a closed object's permitted properties");
+    }
+  }
+  const result = { ...left };
+  // Keep complete conditional clauses together; independently merging their if/then/else
+  // keywords would change which assertion a branch applies to.
+  if (own(left, "if") && own(right, "if")) {
+    const condition = Object.fromEntries(["if", "then", "else"]
+      .filter((key) => own(right, key)).map((key) => [key, right[key]]));
+    right = Object.fromEntries(Object.entries(right)
+      .filter(([key]) => !["if", "then", "else"].includes(key)));
+    result.allOf = [...(result.allOf ?? []), condition];
+  }
+  for (const [key, value] of Object.entries(right)) {
+    if (!own(result, key) || annotations.has(key)) {
+      result[key] = value;
+    } else if (key === "properties") {
+      result.properties = { ...result.properties };
+      for (const [name, property] of Object.entries(value)) {
+        result.properties[name] = own(result.properties, name)
+          ? conjoin(result.properties[name], property, `${path}/properties/${name}`)
+          : property;
+      }
+    } else if (key === "required") {
+      result.required = [...new Set([...result.required, ...value])];
+    } else if (key === "allOf") {
+      result.allOf = [...result.allOf, ...value];
+    } else if (key === "enum") {
+      result.enum = result.enum.filter((entry) => value.some((other) => signature(entry) === signature(other)));
+      if (!result.enum.length) unsupported(path, "allOf has disjoint enums");
+    } else if (key === "type") {
+      const types = [result.type].flat().filter((entry) => [value].flat().includes(entry));
+      if (!types.length) unsupported(path, "allOf has disjoint types");
+      result.type = types.length === 1 ? types[0] : types;
+    } else if (/^(minimum|exclusiveMinimum|minLength|minItems|minContains|minProperties)$/.test(key)) {
+      result[key] = Math.max(result[key], value);
+    } else if (/^(maximum|exclusiveMaximum|maxLength|maxItems|maxContains|maxProperties)$/.test(key)) {
+      result[key] = Math.min(result[key], value);
+    } else if (signature(result[key]) !== signature(value)) {
+      unsupported(path, `cannot flatten conflicting ${key} assertions without losing information`);
+    }
+  }
+  if (own(result, "const") && result.enum) {
+    if (!result.enum.some((entry) => signature(entry) === signature(result.const))) {
+      unsupported(path, "const is excluded by enum");
+    }
+    delete result.enum;
+  }
+  return result;
+}
+
+function createResolver(schema) {
+  function dereference(ref) {
+    if (typeof ref !== "string" || !ref.startsWith("#/")) {
+      unsupported(String(ref), "only local JSON Pointer $ref values are supported");
+    }
+    let target = schema;
+    for (const part of ref.slice(2).split("/")) {
+      const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+      if (!object(target) || !own(target, key)) unsupported(ref, "unresolved $ref");
+      target = target[key];
+    }
+    return target;
+  }
+
+  function discriminator(input, seen = new Set()) {
+    if (!object(input)) return null;
+    if (input.$ref) {
+      if (seen.has(input.$ref)) unsupported(input.$ref, "recursive discriminator");
+      return discriminator(dereference(input.$ref), new Set([...seen, input.$ref]));
+    }
+    return input.properties?.type?.enum ?? null;
+  }
+
+  function resolve(input, path = "#", stack = []) {
+    if (typeof input === "boolean") return input;
+    if (!object(input)) unsupported(path, "expected a JSON Schema object or boolean");
+    let result = {};
+    if (input.$ref) {
+      if (stack.includes(input.$ref)) unsupported(path, "recursive $ref outside an element array");
+      result = resolve(dereference(input.$ref), input.$ref, [...stack, input.$ref]);
+    }
+    const local = {};
+    for (const [key, value] of Object.entries(input)) {
+      if (key === "$ref" || key === "allOf") continue;
+      if (schemaMaps.has(key)) {
+        local[key] = Object.fromEntries(Object.entries(value)
+          .map(([name, child]) => [name, resolve(child, `${path}/${key}/${name}`, stack)]));
+      } else if (schemaArrays.has(key)) {
+        local[key] = value.map((child, index) => resolve(child, `${path}/${key}/${index}`, stack));
+      } else if (schemaValues.has(key)) {
+        // Element arrays are the tree boundary. Keep their standard local references rather
+        // than unrolling every nesting level (or a future recursive element definition).
+        if (key === "items" && object(value) && value.$ref && discriminator(value)) {
+          dereference(value.$ref);
+          if (Object.keys(value).some((name) => name !== "$ref")) {
+            unsupported(`${path}/items`, "element-array $ref siblings need explicit derivation support");
+          }
+          local[key] = { $ref: value.$ref };
+        } else {
+          local[key] = resolve(value, `${path}/${key}`, stack);
+        }
+      } else if (scalarKeywords.has(key)) {
+        local[key] = structuredClone(value);
+      } else {
+        unsupported(`${path}/${key}`, "unrecognized JSON Schema keyword");
+      }
+    }
+    result = conjoin(result, local, path);
+    for (const [index, branch] of (input.allOf ?? []).entries()) {
+      const resolved = resolve(branch, `${path}/allOf/${index}`, stack);
+      if (object(resolved) && ["if", "anyOf", "oneOf", "not"].some((key) => own(resolved, key))) {
+        result = conjoin(result, { allOf: [resolved] }, path);
+      } else {
+        result = conjoin(result, resolved, path);
+      }
+    }
+    return result;
+  }
+  return { resolve, discriminator };
+}
+
+function typeGuard(condition, path) {
+  if (!condition?.properties?.type) return null;
+  const allowed = new Set(["type", "properties", "required"]);
+  if (Object.keys(condition).some((key) => !allowed.has(key))
+      || Object.keys(condition.properties).some((key) => key !== "type")
+      || condition.required?.length !== 1 || condition.required[0] !== "type"
+      || (condition.type !== undefined && condition.type !== "object")) {
+    unsupported(path, "element discriminator must test only the required type field");
+  }
+  const value = condition.properties.type;
+  if (Object.keys(value).length !== 1 || (!own(value, "const") && !own(value, "enum"))) {
+    unsupported(path, "element discriminator must use const or enum");
+  }
+  return own(value, "const") ? [value.const] : value.enum;
+}
+
+function elementVariants(table, path) {
+  const types = table.properties?.type?.enum;
+  if (!Array.isArray(types) || !types.length || types.some((type) => typeof type !== "string")) {
+    unsupported(path, "element items must declare a nonempty string type enum");
+  }
+  const selected = {};
+  for (const type of types) {
+    let matched = false;
+    function select(input) {
+      if (!object(input)) unsupported(path, "boolean element branches are not supported");
+      if (input.anyOf || input.oneOf || input.not) unsupported(path, "ambiguous element object composition");
+      let result = Object.fromEntries(Object.entries(input).filter(([key]) => key !== "allOf"));
+      if (input.if) {
+        const guard = typeGuard(input.if, path);
+        if (guard) {
+          result = Object.fromEntries(Object.entries(result)
+            .filter(([key]) => !["if", "then", "else"].includes(key)));
+          const applies = guard.includes(type);
+          matched ||= applies && own(input, "then");
+          const branch = applies ? input.then : input.else;
+          if (branch !== undefined) result = conjoin(result, select(branch), path);
+        }
+      }
+      for (const branch of input.allOf ?? []) result = conjoin(result, select(branch), path);
+      return result;
+    }
+    selected[type] = select(table);
+    if (!matched) unsupported(path, `no conditional element branch for ${JSON.stringify(type)}`);
+    if (selected[type].additionalProperties !== false) {
+      unsupported(path, `${type} must explicitly bound its permitted properties`);
+    }
+  }
+  return selected;
+}
+
+function fields(descriptor, path) {
+  const result = { ...(descriptor.properties ?? {}) };
+  function conditional(input) {
+    if (!object(input)) return;
+    if (input.anyOf || input.oneOf) unsupported(path, "conditional object unions need explicit field derivation");
+    for (const [name, value] of Object.entries(input.properties ?? {})) {
+      // A conditional assertion may narrow an existing field (connector.points, for example).
+      // The complete condition stays on the element and in definitions; it is not an
+      // unconditional restriction on the property descriptor.
+      if (!own(result, name)) {
+        if (descriptor.additionalProperties === false) {
+          unsupported(path, `conditional field ${name} is outside the closed object's permitted properties`);
+        }
+        result[name] = value;
+      }
+    }
+    for (const branch of input.allOf ?? []) conditional(branch);
+    if (input.then) conditional(input.then);
+    if (input.else) conditional(input.else);
+  }
+  conditional(descriptor);
+  return result;
+}
+
+function elementConditions(descriptor) {
+  return Object.fromEntries(["if", "then", "else", "allOf"]
+    .filter((key) => own(descriptor, key)).map((key) => [key, descriptor[key]]));
+}
+
+function conditionSignature(conditions, resolver) {
+  // Child selectors vary by nesting depth; their exact rules remain in definitions.
+  // All other element-level conditions must agree across fixed/flow contexts.
+  return JSON.stringify(ordered(assertions(conditions)), (key, value) =>
+    key === "items" && resolver.discriminator(value) ? {} : value);
+}
+
+function childTables(descriptor, resolver, path) {
+  const result = [];
+  function visit(input, mode) {
+    if (!object(input)) return;
+    for (const property of Object.values(input.properties ?? {})) {
+      if (property.items && resolver.discriminator(property.items)) {
+        result.push({ items: property.items, mode });
+      }
+    }
+    for (const branch of input.allOf ?? []) visit(branch, mode);
+    if (input.if) {
+      const before = result.length;
+      visit(input.then, "flow");
+      visit(input.else, "fixed");
+      if (result.length !== before && (
+        input.if.type !== "object" || input.if.required?.length !== 1
+        || input.if.required[0] !== "layout"
+        || Object.keys(input.if).some((key) => !["type", "required"].includes(key))
+      )) {
+        unsupported(path, "child layout context must be selected by presence of the parent's layout");
+      }
+    }
+  }
+  visit(descriptor, "fixed");
+  return result;
+}
+
+/**
+ * Derive vocabulary from JSON Schema, not an independent validator. The fixed/flow projection
+ * follows the schema's parent-layout branches. Element conditions and resolved definitions
+ * retain JSON Schema keywords; depth-specific child selectors remain in definitions.
+ * Unsupported projections fail rather than silently publishing partial metadata.
+ */
+export function deriveArchitectureContract(schema) {
+  if (!object(schema) || !object(schema.$defs)) unsupported("#", "expected a schema with $defs");
+  const resolver = createResolver(schema);
+  const { $defs, ...rootSchema } = schema;
+  const root = resolver.resolve(rootSchema);
+  if (root.type !== "object" || root.additionalProperties !== false || !root.properties?.elements?.items) {
+    unsupported("#", "expected a closed root object with elements.items");
+  }
+  if (root.if || root.allOf || root.anyOf || root.oneOf) {
+    unsupported("#", "conditional root fields need explicit derivation support");
+  }
+  const elements = {};
+  const queue = [{ items: root.properties.elements.items, mode: "fixed" }];
+  const visited = new Set();
+  while (queue.length) {
+    const { items, mode } = queue.shift();
+    const key = `${mode}:${signature(items)}`;
+    if (visited.has(key)) continue;
+    visited.add(key);
+    const variants = elementVariants(resolver.resolve(items), key);
+    for (const [type, descriptor] of Object.entries(variants)) {
+      const properties = fields(descriptor, `${key}/${type}`);
+      const required = descriptor.required ?? [];
+      const conditions = elementConditions(descriptor);
+      if (required.some((name) => !own(properties, name))) unsupported(key, `${type} requires an undeclared field`);
+      const existing = elements[type] ??= { properties, required: {}, ...conditions };
+      if (signature(assertions({ properties: existing.properties })) !== signature(assertions({ properties }))) {
+        unsupported(key, `${type} properties vary by parent context; cannot publish one field record`);
+      }
+      if (conditionSignature(elementConditions(existing), resolver) !== conditionSignature(conditions, resolver)) {
+        unsupported(key, `${type} conditional rules vary by parent context beyond child element arrays`);
+      }
+      if (existing.required[mode] && signature([...existing.required[mode]].sort()) !== signature([...required].sort())) {
+        unsupported(key, `${type} requirements vary within ${mode} context`);
+      }
+      existing.required[mode] = required;
+      queue.push(...childTables(descriptor, resolver, `${key}/${type}`));
+    }
+  }
+  for (const [type, element] of Object.entries(elements)) {
+    if (!element.required.fixed || !element.required.flow) {
+      unsupported("#/properties/elements", `${type} has no reachable fixed and flow variants`);
+    }
+  }
+  return {
+    root: { properties: root.properties, required: root.required ?? [] },
+    elements,
+    definitions: Object.fromEntries(Object.entries($defs)
+      .map(([name, definition]) => [name, resolver.resolve(definition, `#/$defs/${name}`)])),
+  };
+}
+
+export function architectureContractModule(schema) {
+  // Declaration order is also the runtime's diagnostic field/type order.
+  return [
+    "// Generated from schema/architecture-v1.schema.json. Do not edit.",
+    "// Regenerate: node .github/extensions/markdstage/scripts/generate-architecture-contract.mjs",
+    "// Structural metadata only; renderer/architecture.mjs remains the semantic authority.",
+    `export const architectureContract = ${JSON.stringify(deriveArchitectureContract(schema), null, 2)};`,
+    "",
+  ].join("\n");
+}

package/shared/scripts/generate-architecture-contract.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { architectureContractModule } from "../schema/architecture-contract.mjs";
+
+const schemaUrl = new URL("../schema/architecture-v1.schema.json", import.meta.url);
+const outputUrl = new URL("../renderer/architecture-contract.mjs", import.meta.url);
+
+export async function generateArchitectureContract({
+  check = false,
+  source = schemaUrl,
+  output = outputUrl,
+} = {}) {
+  const expected = architectureContractModule(JSON.parse(await readFile(source, "utf8")));
+  let current;
+  try {
+    current = await readFile(output, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const changed = expected !== current?.replace(/\r\n/g, "\n");
+  if (changed && check) {
+    throw new Error("Architecture contract is out of date. Run npm run generate:architecture.");
+  }
+  if (changed) await writeFile(output, expected, "utf8");
+  return { changed, checked: check };
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  try {
+    const args = process.argv.slice(2);
+    if (args.some((arg) => arg !== "--check") || args.length > 1) {
+      throw new Error("Usage: node generate-architecture-contract.mjs [--check]");
+    }
+    const result = await generateArchitectureContract({ check: args.includes("--check") });
+    console.log(`Architecture contract ${result.checked ? "is current" : result.changed ? "generated" : "unchanged"}.`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}