@markdstage/markdstage 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdstage/markdstage",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Present, validate, inspect, capture, and export MarkdStage Markdown decks from the command line — no Copilot canvas required.",
   "license": "MIT",
   "author": "runceel",

package/shared/README.md

@@ -206,13 +206,48 @@ OS file dialog is used.
 The extension provides `markdstage_guide`. Before authoring Markdown for the
 MarkdStage canvas, AI should request the required `overview`, `slide-format`,
 `themes`, `custom-themes`, `theme-schema`, `architecture-dsl`, or
-`architecture-schema` topic. Runtime guidance is generated from this README and
-`schema/architecture-v1.schema.json`, so user-scoped extension installs expose
-the same contract.
+`architecture-schema` topic. **Before drafting Architecture DSL, request
+`architecture-schema` first.** It contains the schema-derived element fields,
+fixed versus parent-managed placement requirements, and a self-contained example
+within an 8 KiB UTF-8 response budget. Use `architecture-dsl` for detailed behavior.
+Runtime guidance is generated from this README and the bundled schema contract,
+so user-scoped extension installs expose the same vocabulary.
 
-When the extension detects a presentation-related prompt, it adds a short hint
-to use `markdstage_guide` at most once per session. No hint is added after the
-tool has already been called, and session-end cleanup removes the state.
+Use the standalone **`markdstage_validate`** tool before opening a newly authored
+diagram. Its input is explicitly one of:
+
+```json
+{ "format": "dsl", "source": "{\"elements\":[]}" }
+```
+
+```json
+{ "format": "slides", "slides": ["## Diagram\n\n```architecture\n{\"elements\":[]}\n```"] }
+```
+
+Each `slides` entry is one slide fragment, not an entire Markdown deck. The tool
+does not require a canvas and never changes the displayed deck, page, files, or
+editor save state. Optional `maxDiagnostics` is an integer from 1 to 100
+(default 50). Inspection examines at most 200 slide positions and 200 blocks,
+262,144 UTF-16 code units per source/slide input, and 2,097,152 code units across
+slides. These inspection budgets do not replace the existing DSL source and
+element limits. Reports distinguish API `ok`, content `valid`, validation `complete`,
+and `truncated` collection, with per-block stage status and stable-coded
+diagnostics. JSON Pointers identify fields; slide inputs add page/block positions.
+Repair suggestions are contextual and never applied automatically.
+
+Fix reported independent problems together, then validate again and pass
+**the same content** to saving and `open_canvas` or `load_deck`. Check
+`inspect_layout` separately afterward. A valid DSL does not guarantee asset
+existence, readable labels, or slide fit. Invalid JSON stops dependent checks in
+that block, not other readable blocks; bounded checks never claim skipped work
+succeeded. The existing canvas still permits invalid diagrams to appear as
+inline errors rather than rejecting an entire load.
+
+Authoring guidance is carried by tool/canvas descriptions, the overview, and
+Agent Skills. The extension does not register advisory SDK session hooks:
+some hosts cannot provide a hook processor, and optional guide reminders must
+not prevent tools or canvases from starting. This does not change the host's
+permission handling or file-hook settings.
 
 ### Markdown file syntax
 
@@ -451,7 +486,8 @@ When writing explicit JSON, `elements` is required by the JSON Schema.
   unsupported elements, styles, or colors render an inline diagram error while
   preserving other slide content. DSL values never generate HTML, script, or
   event attributes. Generated asset URLs stay on same-origin `/assets/...`.
-- `version` is currently `1` and defaults to v1. Limits include 64 KiB source,
+- `version` is currently `1` and defaults to v1. Limits include 65,536 source
+  code units (UTF-16),
   200 total elements, 100 connectors, four nesting levels, 12 polyline
   intermediate points, 20,000 total text characters, and 200-character icon/src
   references.
@@ -996,7 +1032,7 @@ fails with `invalid_input`; pass the complete `slides` array or call
 | `load_deck` | `{ slides: string[], index?: number, theme?: "dark" | "light" | "microsoft" | "custom", sourceName?: string }`. Replace/reload the deck for mid-presentation content or theme changes. `index` defaults to `0`; theme defaults to `dark`. `sourceName` is metadata only and never reads or watches Markdown. Appends one back cover without duplication. Returns `{ ok, version, index, total, theme, validationFeedback? }`. Missing front matter or Architecture errors do not prevent display; remediation is returned in `validationFeedback` and logged for open. |
 | `goto_slide` | `{ index: number }`. Select a clamped zero-based index. Intended for explicit chat requests, not normal navigation. Returns `{ ok, changed, version, index, total }`. |
 | `show_slide` | `{ markdown: string }`. Temporarily replace the current slide. Supports front matter keys `deck`, `kicker`, `page`, `total`, `title`, `layout`, `size`, and `theme`. Omitted theme inherits the deck theme. The override is included in output snapshots until navigation or deck replacement resumes the registered deck. |
-| `get_architecture_errors` | `{ index?: number }`. Validate the complete deck or one zero-based slide, including temporary content. Returns `{ ok, scope, index?, page?, total, errorCount, errors }`; errors contain `{ slideIndex, page, blockIndex, architecture, code, message }`. No deck and out-of-range indexes are errors. |
+| `get_architecture_errors` | `{ index?: number }`. Validate the complete deck or one zero-based slide, including temporary content. Preserves `{ ok, scope, index?, page?, total, errorCount, errors }` and legacy block errors; adds `valid`, `complete`, `truncated`, detailed `diagnostics`, and block-stage results from the same validator as `markdstage_validate`. No deck and out-of-range indexes are errors. |
 | `open_presenter` | No input. Start one synchronized movable/resizable 1280×720 Chromium app-mode window. Use `F11` on Windows for full screen. Returns `{ ok, started, alreadyRunning, browser?, pid? }`. |
 | `close_presenter` | No input. Stop presenter and remove its temporary profile. Returns `{ ok, stopped }`. |
 | `inspect_layout` | `{ index?: number, includeFits?: boolean }`. Render the registered in-memory PDF snapshot with the fixed 1280×720 output layout; this does not inspect the source file on disk. Omit `index` for one preferred whole-deck inspection. Serialize targeted calls because PDF, layout, and PNG jobs are exclusive. By default, return only clipped pages; `includeFits` includes successful pages. Returns dimensions, issue counts, overflow measurements, nested scroll containers, and a bounded list of element hints. Requires Edge, Chrome, or Chromium. |
@@ -1037,6 +1073,8 @@ fails with `invalid_input`; pass the complete `slides` array or call
 .github/extensions/markdstage/
   extension.mjs             # Canvas declaration, loopback server, and actions
   architecture-canvas.mjs   # Canvas adapter for the shared Architecture Editor
+  architecture-reference.mjs # Compact schema-derived authoring reference
+  architecture-validation.mjs # Pure unloaded-input and slide validation
   architecture-editor/
     index.html               # Full diagram-editor canvas shell
     editor.css               # Workspace, tree, and inspector styles
@@ -1044,6 +1082,7 @@ fails with `invalid_input`; pass the complete `slides` array or call
   copilot-extension.json     # Manifest for Gist sharing
   markdown-deck.mjs         # Raw Markdown splitting for canvas import
   scripts/
+    generate-architecture-contract.mjs # Generate/check browser-safe schema metadata
     markdown-blocks.mjs     # Scan and replace architecture fences
     markdown-files.mjs      # Scan workspace Markdown
     markdown-watcher.mjs    # Watch and debounce source-backed Markdown
@@ -1054,6 +1093,8 @@ fails with `invalid_input`; pass the complete `slides` array or call
     slides.css              # Built-in dark/light/microsoft themes and navigation UI
     renderer.js             # Front matter, marked, Mermaid, Architecture, SSE, controls
     architecture.mjs        # Validate JSON DSL and create safe SVG DOM
+    architecture-contract.mjs # Generated structural vocabulary; no runtime dependencies
+    architecture-diagnostics.mjs # Bounded structured diagnostics and reference checks
     architecture-edit.mjs   # DOM-independent move/detach/Undo/Redo/serialization
     architecture-editor.mjs # Placement UI and Advanced editing entry point
     architecture-document.mjs # Full-editor command/session API
@@ -1062,6 +1103,7 @@ fails with `invalid_input`; pass the complete `slides` array or call
     architecture-source.mjs # Atomic Architecture block persistence and conflicts
   schema/
     architecture-v1.schema.json # Architecture DSL v1 JSON Schema (draft 2020-12)
+    architecture-contract.mjs # Derive metadata from Schema references and conditions
     README.md               # Schema use, versioning, and migration policy
     examples/               # Samples with relative $schema references
   vendor/

package/shared/architecture-editor/editor.js

@@ -142,7 +142,7 @@ function toggleResponsivePanel(panel) {
     opened = desktopInspectorOpen;
   }
   syncResponsivePanels();
-  if (opened) requestAnimationFrame(() => focusPanel(panel));
+  if (opened) focusPanel(panel);
 }
 
 function focusPanel(panel) {

package/shared/architecture-reference.mjs

@@ -0,0 +1,150 @@
+import { architectureContract } from "./renderer/architecture-contract.mjs";
+
+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",
+]);
+
+function assertions(schema) {
+  if (typeof schema === "boolean") return schema;
+  return Object.fromEntries(Object.entries(schema)
+    .filter(([key]) => !annotations.has(key))
+    .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+    .map(([key, value]) => [
+      key,
+      schemaMaps.has(key)
+        ? Object.fromEntries(Object.keys(value).sort().map((name) => [name, assertions(value[name])]))
+        : schemaArrays.has(key) ? value.map(assertions)
+          : schemaValues.has(key) ? assertions(value) : value,
+    ]));
+}
+
+const minimalExample = {
+  version: 1,
+  title: "Request path",
+  canvas: { width: 1600, height: 900 },
+  elements: [
+    { type: "node", id: "client", x: 160, y: 300, width: 280, height: 140, text: "Client" },
+    { type: "node", id: "api", x: 860, y: 300, width: 280, height: 140, text: "API" },
+    { type: "connector", from: "client", to: "api", label: "HTTPS", arrow: true },
+  ],
+};
+
+/**
+ * A complete, bounded authoring reference, not a second list of permitted fields.
+ * Names and constraints come from the generated contract; prose explains runtime semantics.
+ */
+export function architectureSchemaReference(contract = architectureContract) {
+  const aliases = new Map();
+  const used = new Set();
+  for (const name of Object.keys(contract.definitions).sort((a, b) => a.length - b.length || (a < b ? -1 : 1))) {
+    const signature = JSON.stringify(assertions(contract.definitions[name]));
+    if (!aliases.has(signature)) aliases.set(signature, name);
+  }
+  function describe(schema, defining) {
+    if (typeof schema === "boolean") return schema ? "any" : "never";
+    const alias = aliases.get(JSON.stringify(assertions(schema)));
+    if (alias && alias !== defining) {
+      used.add(alias);
+      return alias;
+    }
+    if (schema.$ref) {
+      const name = schema.$ref.slice("#/$defs/".length).replace(/~1/g, "/").replace(/~0/g, "~");
+      const definition = contract.definitions[name];
+      if (!definition) throw new Error(`Unresolved reference in Architecture reference: ${schema.$ref}`);
+      if (definition.properties?.type?.enum?.every((type) => contract.elements[type])) return "element";
+      used.add(name);
+      return name;
+    }
+    const parts = [];
+    const rendered = new Set();
+    if (Object.hasOwn(schema, "const")) {
+      parts.push(JSON.stringify(schema.const));
+      rendered.add("const");
+    } else if (schema.enum) {
+      parts.push(schema.enum.map((value) => JSON.stringify(value)).join("|"));
+      rendered.add("enum");
+    } else if (schema.type === "object" || schema.properties) {
+      parts.push(`object{${propertyList(schema.properties ?? {})}}`);
+      rendered.add("properties");
+    } else if (schema.type === "array") {
+      parts.push(schema.items ? `array<${describe(schema.items)}>` : "array");
+      rendered.add("items");
+    } else if (schema.type) {
+      parts.push([schema.type].flat().join("|"));
+    }
+    rendered.add("type");
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
+      if (!schema[key]) continue;
+      const operator = key === "allOf" ? " & " : key === "oneOf" ? " XOR " : " | ";
+      parts.push(`(${schema[key].map((child) => describe(child)).join(operator)})`);
+      rendered.add(key);
+    }
+    for (const [key, value] of Object.entries(schema)) {
+      if (rendered.has(key) || annotations.has(key)) continue;
+      parts.push(`${key}=${JSON.stringify(schemaValues.has(key) ? assertions(value) : value)}`);
+    }
+    return parts.join(" ");
+  }
+  function propertyList(properties) {
+    return Object.entries(properties)
+      .map(([name, schema]) => `${JSON.stringify(name)}: ${describe(schema)}`).join("; ");
+  }
+  const lines = [
+    "# Architecture DSL v1 authoring reference",
+    "",
+    "Schema-derived structural contract. Every permitted field is listed; unspecified fields are optional unless required below. Unknown fields are rejected, including inside style, canvas, point and layout objects. Do not invent aliases or CSS.",
+    "",
+    "## Root",
+    `Required: ${JSON.stringify(contract.root.required)}.`,
+    propertyList(contract.root.properties),
+    "",
+    "## Element fields and requirements",
+    "fixed = immediate parent has no layout (including the root). flow = immediate parent group has layout. A group's OWN layout places its children; it does NOT waive that group's fixed box requirements. Grandchildren follow their own parent's layout.",
+    "",
+  ];
+  for (const [type, element] of Object.entries(contract.elements)) {
+    const conditions = Object.fromEntries(["if", "then", "else", "allOf"]
+      .filter((key) => Object.hasOwn(element, key)).map((key) => [key, element[key]]));
+    lines.push(
+      `### ${type}`,
+      `Required fixed: ${JSON.stringify(element.required.fixed)}; flow: ${JSON.stringify(element.required.flow)}.`,
+      propertyList(element.properties),
+      ...(Object.keys(conditions).length ? [`Conditional constraints: ${describe(conditions)}.`] : []),
+      "",
+    );
+  }
+  lines.push("## Shared value schemas");
+  // Definitions are discovered transitively from the property descriptors, not a curated list.
+  for (const name of used) {
+    lines.push(`- ${name}${name === "iconName" ? ' ("builtIn")' : ""}: ${describe(contract.definitions[name], name)}`);
+  }
+  lines.push(
+    "",
+    "## Authoring rules",
+    'Visible node text uses "text" (use \\n for multiple lines); group headings use "title"; connector annotations use "label". Root "title" is the accessible diagram name. A connector has no "id". Group children are elements.',
+    "Conditional constraints are emitted from Schema alongside the fields and shared values. A field permitted in one routing/layout mode is not automatically permitted in every mode.",
+    "For flow children omit x/y: runtime ignores them. Width/height are optional there and must fit the calculated cells. Use node.icon for built-in icons or assets/ paths; image.src is an asset path, not a URL. Theme tokens adapt; literal colors and image artwork do not.",
+    "",
+    "## Runtime checks",
+    "Schema validity is necessary for authoring, not sufficient for rendering. parseArchitecture also checks unique IDs across the tree, existing non-connector endpoints, no self-links, flattened element/connector/text limits, nesting depth and layout fit. Assets need separate existence/content checks; inspect visual clipping separately. Existing v1 runtime compatibility is preserved: ignored flow x/y and root $schema can differ from the stricter authoring schema. Never resolve $schema at runtime.",
+    "",
+    "## Complete minimal example",
+    "Two nodes and one connector; no assets or schema URL required. Paste into an architecture fence:",
+    "```architecture",
+    JSON.stringify(minimalExample, null, 2),
+    "```",
+    "",
+    "## Details",
+    "Full structural schema: bundled schema/architecture-v1.schema.json (offline editor completion). For layout semantics, constraints, examples and editing request markdstage_guide topic=architecture-dsl; this compact contract is topic=architecture-schema. See schema/README.md for schema/runtime differences and v1 compatibility.",
+  );
+  const reference = lines.join("\n");
+  const bytes = new TextEncoder().encode(reference).byteLength;
+  if (bytes > 8192) {
+    throw new RangeError(`Architecture reference is ${bytes} UTF-8 bytes; the complete reference must fit within 8192 bytes.`);
+  }
+  return reference;
+}

package/shared/architecture-validation.mjs

@@ -0,0 +1,309 @@
+import { validateArchitecture } from "./renderer/architecture.mjs";
+import { findArchitectureBlocks } from "./scripts/markdown-blocks.mjs";
+
+export const ARCHITECTURE_VALIDATION_LIMITS = Object.freeze({
+  maxSourceChars: 262_144,
+  maxSlideChars: 262_144,
+  maxTotalChars: 2_097_152,
+  maxSlides: 200,
+  maxBlocks: 200,
+});
+export const UNCLOSED_ARCHITECTURE_MESSAGE =
+  "The architecture code fence is not closed. Add ``` at the end.";
+
+const STAGES = ["json", "structure", "semantic", "layout"];
+const skippedStages = () => Object.fromEntries(STAGES.map((stage) => [stage, "skipped"]));
+
+export class ArchitectureValidationInputError extends TypeError {
+  constructor(message) {
+    super(message);
+    this.name = "ArchitectureValidationInputError";
+    this.code = "invalid_input";
+  }
+}
+
+function checkInput(input) {
+  const reject = (message) => {
+    throw new ArchitectureValidationInputError(message);
+  };
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    reject("Provide an object with an explicit format of 'dsl' or 'slides'.");
+  }
+  const allowed = new Set(["format", "source", "slides", "maxDiagnostics"]);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) reject(`Unknown validation input field: ${key}.`);
+  }
+  if (!Object.hasOwn(input, "format") || (input.format !== "dsl" && input.format !== "slides")) {
+    reject("format must be explicitly set to 'dsl' or 'slides'.");
+  }
+  const hasSource = Object.hasOwn(input, "source");
+  const hasSlides = Object.hasOwn(input, "slides");
+  if (input.format === "dsl") {
+    if (!hasSource || hasSlides || typeof input.source !== "string") {
+      reject("format 'dsl' requires a string source and must not include slides.");
+    }
+  } else {
+    if (hasSource || !hasSlides || !Array.isArray(input.slides) || !input.slides.length) {
+      reject("format 'slides' requires a non-empty array of one-slide Markdown fragments and must not include source.");
+    }
+    const inspectableSlides = Math.min(input.slides.length, ARCHITECTURE_VALIDATION_LIMITS.maxSlides);
+    for (let index = 0; index < inspectableSlides; index += 1) {
+      if (typeof input.slides[index] !== "string") {
+        reject(`slides[${index}] must be a one-slide Markdown string.`);
+      }
+    }
+  }
+  const maxDiagnostics = Object.hasOwn(input, "maxDiagnostics") ? input.maxDiagnostics : 50;
+  if (!Number.isInteger(maxDiagnostics) || maxDiagnostics < 1 || maxDiagnostics > 100) {
+    reject("maxDiagnostics must be an integer from 1 to 100.");
+  }
+  return maxDiagnostics;
+}
+
+function blockPosition(slideIndex, block, lineCount) {
+  return {
+    slideIndex,
+    page: slideIndex + 1,
+    blockIndex: block.index,
+    architecture: block.index + 1,
+    openLine: block.open + 1,
+    closeLine: block.end < lineCount ? block.end + 1 : null,
+    endLine: block.end < lineCount ? block.end + 1 : lineCount,
+    closed: block.end < lineCount,
+  };
+}
+
+/**
+ * Validate explicit, unloaded content. Limits bound this inspection only; they
+ * do not add restrictions to the Architecture DSL parser or alter any source.
+ */
+export function validateArchitectureInput(input) {
+  const maxDiagnostics = checkInput(input);
+  const limits = { ...ARCHITECTURE_VALIDATION_LIMITS, maxDiagnostics };
+  const diagnostics = [];
+  const blocks = [];
+  const skipped = [];
+  const budget = {
+    inputChars: input.format === "dsl"
+      ? input.source.length
+      : input.slides.length > limits.maxSlides
+        ? null
+        : input.slides.reduce((total, slide) => total + slide.length, 0),
+    scannedChars: 0,
+    scannedSlides: 0,
+    processedBlocks: 0,
+    skippedSlides: 0,
+    skippedBlocks: 0,
+    limitsReached: [],
+  };
+  let truncated = false;
+
+  function reachLimit(reason, position = {}) {
+    truncated = true;
+    if (budget.limitsReached.includes(reason)) return;
+    budget.limitsReached.push(reason);
+    if (diagnostics.length < maxDiagnostics) {
+      diagnostics.push({
+        code: "validation_budget_exceeded",
+        category: "structure",
+        severity: "warning",
+        pointer: "",
+        message: `Validation stopped at the ${reason} inspection limit (${limits[reason]}). Unchecked content is not valid or complete.`,
+        suggestions: [{
+          action: "review",
+          message: "Validate smaller explicit inputs separately; no source was changed.",
+          automatic: false,
+        }],
+        ...position,
+      });
+    }
+  }
+
+  function skipSlides(slideIndex, count, reason) {
+    if (!count) return;
+    reachLimit(reason, { slideIndex, page: slideIndex + 1 });
+    skipped.push({
+      slideIndex,
+      page: slideIndex + 1,
+      slideCount: count,
+      reason,
+      stages: skippedStages(),
+    });
+    budget.skippedSlides += count;
+    // Counting fences would itself inspect slides that were skipped.
+    budget.skippedBlocks = null;
+  }
+
+  function skipBlocks(position, count, reason) {
+    reachLimit(reason, position);
+    skipped.push({ ...position, blockCount: count, reason, stages: skippedStages() });
+    if (budget.skippedBlocks !== null) budget.skippedBlocks += count;
+  }
+
+  function inspect(source, position = {}) {
+    const remaining = maxDiagnostics - diagnostics.length;
+    const report = validateArchitecture(source, { maxDiagnostics: remaining });
+    const diagnosticStart = diagnostics.length;
+    diagnostics.push(...report.diagnostics.map((diagnostic) => ({ ...diagnostic, ...position })));
+    let blockTruncated = report.truncated;
+    const truncationReasons = new Set(report.truncated ? report.truncationReasons : []);
+    if (position.closed === false) {
+      if (diagnostics.length < maxDiagnostics) {
+        diagnostics.push({
+          code: "unclosed_architecture_fence",
+          category: "structure",
+          severity: "error",
+          pointer: "",
+          message: UNCLOSED_ARCHITECTURE_MESSAGE,
+          suggestions: [{
+            action: "review",
+            message: "Close the architecture fence with the same marker and at least its opening length.",
+            automatic: false,
+          }],
+          ...position,
+        });
+      } else {
+        blockTruncated = true;
+        truncationReasons.add("maxDiagnostics");
+      }
+    }
+    if (blockTruncated) {
+      truncated = true;
+      for (const reason of truncationReasons) {
+        // maxDiagnostics here is deck-wide, not this block's remaining allowance.
+        if (reason !== "maxDiagnostics" && Object.hasOwn(report.limits ?? {}, reason)) {
+          limits[reason] = report.limits[reason];
+        }
+        reachLimit(reason, position);
+      }
+    }
+    blocks.push({
+      ...position,
+      valid: report.valid && position.closed !== false && !blockTruncated,
+      dslValid: report.valid,
+      complete: report.complete && !blockTruncated,
+      truncated: blockTruncated,
+      ...(blockTruncated ? { truncationReasons: [...truncationReasons] } : {}),
+      stages: report.stages,
+      diagnosticStart,
+      diagnosticCount: diagnostics.length - diagnosticStart,
+    });
+    budget.processedBlocks += 1;
+  }
+
+  if (input.format === "dsl") {
+    if (input.source.length > limits.maxSourceChars) {
+      skipBlocks({}, 1, "maxSourceChars");
+    } else {
+      budget.scannedChars = input.source.length;
+      inspect(input.source);
+    }
+  } else {
+    for (let slideIndex = 0; slideIndex < input.slides.length; slideIndex += 1) {
+      const remainingSlides = input.slides.length - slideIndex;
+      if (slideIndex >= limits.maxSlides) {
+        skipSlides(slideIndex, remainingSlides, "maxSlides");
+        break;
+      }
+      if (diagnostics.length >= maxDiagnostics) {
+        skipSlides(slideIndex, remainingSlides, "maxDiagnostics");
+        break;
+      }
+      if (budget.processedBlocks >= limits.maxBlocks) {
+        skipSlides(slideIndex, remainingSlides, "maxBlocks");
+        break;
+      }
+      const slide = input.slides[slideIndex];
+      if (slide.length > limits.maxSlideChars) {
+        skipSlides(slideIndex, 1, "maxSlideChars");
+        continue;
+      }
+      if (budget.scannedChars + slide.length > limits.maxTotalChars) {
+        skipSlides(slideIndex, remainingSlides, "maxTotalChars");
+        break;
+      }
+      budget.scannedChars += slide.length;
+      budget.scannedSlides += 1;
+      const found = findArchitectureBlocks(slide);
+      const lineCount = slide.split(/\r\n?|\n/).length;
+      for (let index = 0; index < found.length; index += 1) {
+        const position = blockPosition(slideIndex, found[index], lineCount);
+        const reason = diagnostics.length >= maxDiagnostics
+          ? "maxDiagnostics"
+          : budget.processedBlocks >= limits.maxBlocks ? "maxBlocks" : null;
+        if (reason) {
+          skipBlocks(position, found.length - index, reason);
+          break;
+        }
+        inspect(found[index].body, position);
+      }
+    }
+  }
+
+  const complete = !truncated && blocks.every((block) => block.complete);
+  const valid = complete && blocks.every((block) => block.valid);
+  const stages = Object.fromEntries(STAGES.map((stage) => {
+    const failed = blocks.some((block) => block.stages[stage] === "failed") ||
+      diagnostics.some((diagnostic) => diagnostic.category === stage && diagnostic.severity === "error");
+    const unchecked = skipped.length > 0 || blocks.some((block) => block.stages[stage] === "skipped");
+    return [stage, failed ? "failed" : unchecked ? "skipped" : "passed"];
+  }));
+  return {
+    ok: true,
+    format: input.format,
+    scope: input.format === "dsl" ? "dsl" : "deck",
+    ...(input.format === "slides" ? { total: input.slides.length } : {}),
+    valid,
+    complete,
+    truncated,
+    stages,
+    diagnostics,
+    diagnosticCount: diagnostics.length,
+    blocks,
+    skipped,
+    limits,
+    budget,
+  };
+}
+
+export function createArchitectureValidationTool() {
+  return {
+    name: "markdstage_validate",
+    description:
+      "Read-only preflight of explicit, unloaded Architecture DSL or one-slide Markdown fragments. Call markdstage_guide with architecture-schema BEFORE drafting DSL, then call this tool BEFORE display. Requires format 'dsl' with source OR format 'slides' with slides, never both. Does not open, inspect, navigate, or modify a canvas or file. Returns bounded canonical diagnostics; ok describes invocation, while valid/complete/truncated describe the content check.",
+    parameters: {
+      type: "object",
+      properties: {
+        format: { type: "string", enum: ["dsl", "slides"] },
+        source: { type: "string", description: "Raw Architecture DSL JSON, only with format 'dsl'." },
+        slides: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          description: "One-slide Markdown fragments, only with format 'slides'; this does not split whole Markdown files.",
+        },
+        maxDiagnostics: { type: "integer", minimum: 1, maximum: 100, default: 50 },
+      },
+      required: ["format"],
+      additionalProperties: false,
+      oneOf: [
+        { properties: { format: { const: "dsl" } }, required: ["source"], not: { required: ["slides"] } },
+        { properties: { format: { const: "slides" } }, required: ["slides"], not: { required: ["source"] } },
+      ],
+    },
+    handler: async (input) => {
+      try {
+        return {
+          textResultForLlm: JSON.stringify(validateArchitectureInput(input)),
+          resultType: "success",
+        };
+      } catch (error) {
+        if (!(error instanceof ArchitectureValidationInputError)) throw error;
+        return {
+          textResultForLlm: JSON.stringify({ ok: false, error: error.code, message: error.message }),
+          resultType: "failure",
+        };
+      }
+    },
+  };
+}