@json-to-office/mcp-server 1.2.0 → 1.5.0

package/README.md

@@ -164,12 +164,14 @@ Nested components collapse to their names on purpose — describe those separate
 
 ### `jto_validate`
 
-**In** — `format` (required); document source; `renderer` (validate against this profile instead of the document's own, for this check only); `maxDiagnostics` (1–1000, default 100 — errors are kept ahead of warnings when the cap bites).
+**In** — `format` (required); document source; `renderer` (validate against this profile instead of the document's own, for this check only); `quality` `{profile?, policy?}`; `maxDiagnostics` (1–1000, default 100 — errors are kept ahead of warnings when the cap bites).
 
 **Out** — `valid`, `format`, `renderer` (when one was requested), `source` `{origin, handle?, revision?}`, `counts` `{error, warning, info}` (before any cap), `truncated`.
 
 `ok` mirrors the gate generation applies: schema and semantic errors block it, renderer-profile findings (`W_UNSUPPORTED_RENDERER_FEATURE`) come back as warnings, because the renderer has the last word on those.
 
+Design-quality findings ride the same envelope as `W_QUALITY_*` warnings and infos: an undeclared slide canvas, estimated text overflow, overcrowding, unreadable type, table overflow, or a skipped heading. They carry category, certainty, evidence, suggestion, and optional fixes. They are advisory by default; `quality.policy.gate: "warning"` makes warning-or-higher findings set `ok: false` without turning the tool call into a protocol error.
+
 The gate, not `jto://schema/{format}/document`. The two agree except on component nodes whose props are all optional, where the generated schema asks for a `props: {}` the validator and both renderers treat as omissible; validate follows the renderer, because that is what `jto_generate` runs.
 
 ### `jto_generate`
@@ -229,6 +231,7 @@ The same catalogues, for clients that read resources. URIs are stable.
 | `jto://catalog`              | The resource form of `jto_discover`: every format, in full.               |
 | `jto://renderers`            | Renderer ids per format, which is default, what each profile can draw.    |
 | `jto://themes`               | Built-in theme names per format.                                          |
+| `jto://themes/values`        | What each built-in theme actually is: palette, fonts, style tables.       |
 | `jto://templates`            | Every starter document.                                                   |
 | `jto://schema/docx/document` | Generated JSON Schema for a complete `.docx` document, by renderer.       |
 | `jto://schema/pptx/document` | The same for `.pptx`.                                                     |

package/dist/cli.js

@@ -7,7 +7,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { McpServer } from "@modelcontextprotocol/server";
 
 // src/lib/version.ts
-var SERVER_VERSION = true ? "1.2.0" : "dev-mode";
+var SERVER_VERSION = true ? "1.5.0" : "dev-mode";
 var SERVER_NAME = "json-to-office";
 var PACKAGE_NAME = "@json-to-office/mcp-server";
 
@@ -170,6 +170,9 @@ function outputSchema(properties, required = []) {
 import {
   runWithDiagnosticSink
 } from "@json-to-office/jto-ops";
+import {
+  RENDERER_DEPENDENCY_MISSING
+} from "@json-to-office/shared";
 import { ValueErrorType } from "@sinclair/typebox/errors";
 var ERROR_CODES = {
   /** An exception escaped a tool handler. Always a bug here, never the caller's. */
@@ -218,6 +221,8 @@ var ERROR_CODES = {
   HOST_NOTE: "W_HOST_NOTE",
   /** A generation warning the core raised without a code of its own. */
   GENERATION: "W_GENERATION",
+  /** A design-quality rule threw, so its whole class of findings is missing. */
+  QUALITY_RULE_ERROR: "W_QUALITY_RULE_ERROR",
   /** A required host binary (LibreOffice, poppler) is absent. */
   DEPENDENCY_MISSING: "E_DEPENDENCY_MISSING",
   /** The client cancelled the request. */
@@ -313,7 +318,30 @@ function toolResult(payload) {
     structuredContent: payload
   };
 }
-var HOST_DEPENDENCY_ERRORS = /* @__PURE__ */ new Set(["RendererDependencyMissingError"]);
+var HOST_DEPENDENCY_ERRORS = /* @__PURE__ */ new Set([RENDERER_DEPENDENCY_MISSING]);
+function qualityOptionDiagnostic(error) {
+  const code = qualityCallerCode(error);
+  if (code === void 0 || code === ERROR_CODES.INVALID_DOCUMENT) {
+    return void 0;
+  }
+  return diagnostic(
+    code,
+    error instanceof Error ? error.message : String(error)
+  );
+}
+function qualityCallerCode(error) {
+  const code = error?.code;
+  if (code === "QUALITY_PROFILE_INCOMPATIBLE")
+    return OPTION_ERROR_CODES.INVALID_QUALITY_PROFILE;
+  if (code === "QUALITY_POLICY_INVALID")
+    return OPTION_ERROR_CODES.INVALID_QUALITY_POLICY;
+  if (code === "QUALITY_GATE_FAILED") return ERROR_CODES.INVALID_DOCUMENT;
+  return void 0;
+}
+function stackAllowed() {
+  const flag = process.env.JTO_MCP_DEBUG_STACKS;
+  return flag === "1" || flag === "true";
+}
 function hostNote(text, tone = "muted") {
   return {
     // Never `error`. The body has already decided `ok` by the time a note
@@ -360,11 +388,11 @@ async function guarded(body) {
     return withHostNotes(result, notes);
   } catch (error) {
     const message2 = error instanceof Error ? error.message : String(error);
-    const code = error instanceof Error && HOST_DEPENDENCY_ERRORS.has(error.name) ? ERROR_CODES.DEPENDENCY_MISSING : ERROR_CODES.INTERNAL;
+    const code = qualityCallerCode(error) ?? (error instanceof Error && HOST_DEPENDENCY_ERRORS.has(error.name) ? ERROR_CODES.DEPENDENCY_MISSING : ERROR_CODES.INTERNAL);
     return withHostNotes(
       failure(code, message2, {
         context: {
-          ...error instanceof Error && error.stack !== void 0 && { stack: error.stack }
+          ...stackAllowed() && error instanceof Error && error.stack !== void 0 && { stack: error.stack }
         }
       }),
       notes
@@ -379,7 +407,11 @@ var OPTION_ERROR_CODES = {
   /** `themePath` is not a data-only JSON theme path. */
   INVALID_THEME_PATH: "E_INVALID_THEME_PATH",
   /** The tool does not support the requested format. */
-  UNSUPPORTED_FORMAT: "E_UNSUPPORTED_FORMAT"
+  UNSUPPORTED_FORMAT: "E_UNSUPPORTED_FORMAT",
+  /** `quality.profile` does not cover the format or renderer of this run. */
+  INVALID_QUALITY_PROFILE: "E_INVALID_QUALITY_PROFILE",
+  /** `quality.policy` sets a gate, severity or budget that is not a legal value. */
+  INVALID_QUALITY_POLICY: "E_INVALID_QUALITY_POLICY"
 };
 var DEFERRED_TO_COMPILER = /* @__PURE__ */ new Set([
   ERROR_CODES.UNSUPPORTED_RENDERER_FEATURE
@@ -419,6 +451,34 @@ function validationDiagnostics(errors) {
     })
   );
 }
+function qualityAnalysisDiagnostics(analysis) {
+  return analysis.diagnostics.map((diagnostic2) => ({
+    source: diagnostic2.source,
+    ruleId: diagnostic2.ruleId,
+    category: diagnostic2.category,
+    certainty: diagnostic2.certainty,
+    severity: diagnostic2.severity,
+    code: diagnostic2.code,
+    message: diagnostic2.message,
+    path: diagnostic2.path,
+    blocking: diagnostic2.blocking,
+    ...diagnostic2.suggestion !== void 0 && {
+      suggestion: diagnostic2.suggestion
+    },
+    ...diagnostic2.context !== void 0 && {
+      context: { ...diagnostic2.context }
+    },
+    ...diagnostic2.relatedPaths !== void 0 && {
+      relatedPaths: diagnostic2.relatedPaths
+    },
+    ...diagnostic2.evidence !== void 0 && {
+      evidence: { ...diagnostic2.evidence }
+    },
+    ...diagnostic2.fixes !== void 0 && {
+      fixes: diagnostic2.fixes
+    }
+  }));
+}
 function looksLikeValidationErrors(value) {
   return Array.isArray(value) && value.length > 0 && value.every(
     (entry) => typeof entry === "object" && entry !== null && typeof entry.message === "string"
@@ -607,7 +667,7 @@ function register(server, deps) {
     "jto_info",
     {
       title: "Server info",
-      description: "Versions, supported formats and renderer ids, workspace availability, output-root and size limits, and whether the optional host dependencies (LibreOffice and poppler for jto_preview, a Highcharts export server for the DOCX `highcharts` component) are present on this host. Call this first.",
+      description: "Versions, supported formats with each renderer and whether its backend loads here, workspace availability, output-root and size limits, and whether the optional host dependencies (LibreOffice and poppler for jto_preview, a Highcharts export server for the DOCX `highcharts` component) are present on this host. Call this first.",
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: S({
         type: "object",
@@ -659,10 +719,32 @@ function register(server, deps) {
                   rendererIds: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Defaults first."
+                    description: "Defaults first. Registered, which is not the same as usable \u2014 read `renderers` before picking one."
+                  },
+                  renderers: {
+                    type: "array",
+                    description: "Every registered renderer with whether its backend loads on this host. A renderer with `available: false` will fail every render until `installHint` is run.",
+                    items: {
+                      type: "object",
+                      properties: {
+                        id: { type: "string" },
+                        default: { type: "boolean" },
+                        available: { type: "boolean" },
+                        reason: { type: "string" },
+                        installHint: { type: "string" }
+                      },
+                      required: ["id", "default", "available"],
+                      additionalProperties: false
+                    }
                   }
                 },
-                required: ["name", "extension", "label", "rendererIds"],
+                required: [
+                  "name",
+                  "extension",
+                  "label",
+                  "rendererIds",
+                  "renderers"
+                ],
                 additionalProperties: false
               }
             },
@@ -718,9 +800,21 @@ function register(server, deps) {
         const formats = await Promise.all(
           FORMAT_NAMES.map(async (name) => {
             const adapter = deps.getAdapter(name);
-            let rendererIds = [];
+            let renderers = [];
             try {
-              rendererIds = [...await adapter.rendererIds()];
+              renderers = (await adapter.rendererStatuses()).map(
+                (status) => ({
+                  id: status.id,
+                  default: status.default,
+                  available: status.available,
+                  ...status.reason !== void 0 && {
+                    reason: status.reason
+                  },
+                  ...status.installHint !== void 0 && {
+                    installHint: status.installHint
+                  }
+                })
+              );
             } catch (error) {
               diagnostics.push(
                 diagnostic(
@@ -730,11 +824,32 @@ function register(server, deps) {
                 )
               );
             }
+            for (const renderer of renderers) {
+              if (renderer.available) continue;
+              diagnostics.push(
+                diagnostic(
+                  ERROR_CODES.DEPENDENCY_MISSING,
+                  `The "${renderer.id}" ${name} renderer is registered but cannot load on this host, so every render through it will fail.`,
+                  {
+                    severity: "warning",
+                    ...renderer.installHint && {
+                      suggestion: `Install its backend: ${renderer.installHint}. Until then use one of: ${renderers.filter((entry) => entry.available).map((entry) => `"${entry.id}"`).join(", ")}.`
+                    },
+                    context: {
+                      format: name,
+                      renderer: renderer.id,
+                      ...renderer.reason && { reason: renderer.reason }
+                    }
+                  }
+                )
+              );
+            }
             return {
               name: adapter.name,
               extension: adapter.extension,
               label: adapter.label,
-              rendererIds
+              rendererIds: renderers.map((renderer) => renderer.id),
+              renderers
             };
           })
         );
@@ -1060,10 +1175,10 @@ var STARTERS = [
     id: "pptx-minimal",
     format: "pptx",
     title: "Minimal presentation",
-    description: "The smallest valid .pptx: root, one slide, one title text.",
+    description: "The smallest well-formed .pptx: root with a declared 16:9 canvas, one slide, one title text. The canvas stays: without it the renderer silently falls back to 4:3.",
     document: {
       name: "pptx",
-      props: { title: "Untitled deck" },
+      props: { title: "Untitled deck", slideWidth: 13.333, slideHeight: 7.5 },
       children: [
         {
           name: "slide",
@@ -1122,8 +1237,16 @@ async function catalogFormat(format, deps, diagnostics) {
   const schemas = formatSchemas(format);
   const adapter = deps.getAdapter(format);
   let rendererIds = [];
+  const availability = /* @__PURE__ */ new Map();
+  const installHints = /* @__PURE__ */ new Map();
+  let probed = false;
   try {
-    rendererIds = [...await adapter.rendererIds()];
+    for (const status of await adapter.rendererStatuses()) {
+      rendererIds.push(status.id);
+      availability.set(status.id, status.available);
+      if (status.installHint) installHints.set(status.id, status.installHint);
+    }
+    probed = true;
   } catch (error) {
     diagnostics.push(
       diagnostic(
@@ -1239,6 +1362,14 @@ async function catalogFormat(format, deps, diagnostics) {
     renderers: orderedIds.map((id, index) => ({
       id,
       default: index === 0,
+      // Three cases, and they are not the same. A probed renderer answers for
+      // itself. A profile the cores never registered has no status but is
+      // already reported as drift above, so calling it unavailable would be a
+      // second, worse description of that. And a probe that threw knows
+      // nothing about any of them — reporting those as usable would contradict
+      // the diagnostic pushed beside them.
+      available: availability.get(id) ?? probed,
+      ...installHints.has(id) && { installHint: installHints.get(id) },
       components: [...byRenderer.get(id)?.components.keys() ?? []].sort(),
       unsupported: allNames.filter((name) => !byRenderer.get(id)?.components.has(name)).sort()
     })),
@@ -1308,6 +1439,14 @@ function register2(server, deps) {
                       properties: {
                         id: { type: "string" },
                         default: { type: "boolean" },
+                        available: {
+                          type: "boolean",
+                          description: "Whether this renderer's backend loads on this host. A renderer that is registered but unavailable accepts the components below and then fails every render."
+                        },
+                        installHint: {
+                          type: "string",
+                          description: "The command that would make an unavailable renderer available."
+                        },
                         components: {
                           type: "array",
                           items: { type: "string" }
@@ -1318,7 +1457,13 @@ function register2(server, deps) {
                           description: "Components another renderer of this format accepts and this one does not."
                         }
                       },
-                      required: ["id", "default", "components", "unsupported"],
+                      required: [
+                        "id",
+                        "default",
+                        "available",
+                        "components",
+                        "unsupported"
+                      ],
                       additionalProperties: false
                     }
                   },
@@ -1758,6 +1903,39 @@ function withRenderer(document, renderer) {
   }
   return { ...document, renderer };
 }
+function effectiveRenderer(document, override2) {
+  if (override2 !== void 0) return override2;
+  if (typeof document === "object" && document !== null) {
+    const declared = document.renderer;
+    if (typeof declared === "string") return declared;
+  }
+  return void 0;
+}
+async function rendererAvailability(adapter, document, override2) {
+  const wanted = effectiveRenderer(document, override2);
+  let statuses;
+  try {
+    statuses = await adapter.rendererStatuses();
+  } catch {
+    return void 0;
+  }
+  const status = wanted ? statuses.find((entry) => entry.id === wanted) : statuses.find((entry) => entry.default);
+  if (!status || status.available) return void 0;
+  const usable = statuses.filter((entry) => entry.available).map((entry) => `"${entry.id}"`);
+  return diagnostic(
+    ERROR_CODES.DEPENDENCY_MISSING,
+    `This document validates against the "${status.id}" ${adapter.name} renderer, but that renderer cannot load on this host \u2014 generating with it will fail.`,
+    {
+      severity: "warning",
+      suggestion: status.installHint ? `Install its backend: ${status.installHint}.${usable.length > 0 ? ` Or render with ${usable.join(" or ")}.` : ""}` : `Render with ${usable.join(" or ")} instead.`,
+      context: {
+        format: adapter.name,
+        renderer: status.id,
+        ...status.reason && { reason: status.reason }
+      }
+    }
+  );
+}
 
 // src/lib/workspace-store.ts
 var unavailable = () => failure(
@@ -1857,17 +2035,26 @@ function capDiagnostics(diagnostics, limit) {
   if (diagnostics.length <= limit)
     return { kept: diagnostics, truncated: false };
   const ordered = [...diagnostics].sort(
-    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
+    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || Number(b.blocking === true) - Number(a.blocking === true)
   );
   return { kept: ordered.slice(0, limit), truncated: true };
 }
+function ruleErrorDiagnostics(analysis) {
+  return analysis.ruleErrors.map(
+    (entry) => diagnostic(
+      ERROR_CODES.QUALITY_RULE_ERROR,
+      `Quality rule "${entry.ruleId}" failed: ${entry.message}`,
+      { severity: "warning", source: "quality", ruleId: entry.ruleId }
+    )
+  );
+}
 var DEFAULT_MAX_DIAGNOSTICS = 100;
 function register4(server, deps) {
   server.registerTool(
     "jto_validate",
     {
       title: "Validate a document",
-      description: "Check a document against its format schema and report every defect as a path-addressed diagnostic. Paths are RFC 6901 JSON Pointers into the document you passed, so they can be used directly as patch targets; codes are the stable `E_`/`W_` vocabulary, e.g. `E_REQUIRED_PROPERTY`, `E_UNEXPECTED_PROPERTY`, `E_TYPE_MISMATCH`, `E_UNKNOWN_COMPONENT`. `ok` mirrors the gate generation applies: schema and semantic errors block it \u2014 the semantic rules the published JSON Schema cannot state, such as a text component needing one of `text`/`runs`, are checked here and only here \u2014 while renderer-profile findings (code `W_UNSUPPORTED_RENDERER_FEATURE`) come back as warnings because the renderer, not the schema, has the last word on those. A broken document is a normal result with `ok: false`, never an error.",
+      description: "Check a document against its format schema and report every defect as a path-addressed diagnostic. Paths are RFC 6901 JSON Pointers into the document you passed, so they can be used directly as patch targets; codes are the stable `E_`/`W_` vocabulary. `ok` mirrors generation: schema and semantic errors block; design-quality `W_QUALITY_*` findings advise by default and block only when `quality.policy.gate` requests it. A broken document is a normal result with `ok: false`, never a protocol error.",
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: S({
         type: "object",
@@ -1883,6 +2070,29 @@ function register4(server, deps) {
             minimum: 1,
             maximum: 1e3,
             description: `Cap on returned diagnostics (default ${DEFAULT_MAX_DIAGNOSTICS}). Errors are kept ahead of warnings when the cap bites.`
+          },
+          quality: {
+            type: "object",
+            description: "Optional design profile plus per-run enforcement policy.",
+            properties: {
+              profile: {
+                type: "object",
+                properties: { id: { type: "string", minLength: 1 } },
+                required: ["id"],
+                additionalProperties: true
+              },
+              policy: {
+                type: "object",
+                properties: {
+                  gate: {
+                    type: "string",
+                    enum: ["none", "error", "warning", "info"]
+                  }
+                },
+                additionalProperties: true
+              }
+            },
+            additionalProperties: false
           }
         },
         required: ["format"],
@@ -1913,7 +2123,11 @@ function register4(server, deps) {
           },
           truncated: {
             type: "boolean",
-            description: "`diagnostics` was capped by `maxDiagnostics`."
+            description: "`diagnostics` was capped, by `maxDiagnostics` or by the budget the quality policy set."
+          },
+          profileId: {
+            type: "string",
+            description: "The quality profile the design analysis ran under, when one applied."
           }
         })
       )
@@ -1928,21 +2142,57 @@ function register4(server, deps) {
         const result = adapter.validateDocument(
           withRenderer(resolved.document, args.renderer)
         );
-        const all = validationDiagnostics(result.errors);
+        const unavailable2 = await rendererAvailability(
+          adapter,
+          resolved.document,
+          args.renderer
+        );
+        let analysis;
+        let qualityOption;
+        if (adapter.analyzeQuality) {
+          try {
+            analysis = await adapter.analyzeQuality(resolved.document, {
+              renderer: args.renderer,
+              quality: args.quality
+            });
+          } catch (error) {
+            const option = result.valid ? void 0 : qualityOptionDiagnostic(error);
+            if (!option) throw error;
+            qualityOption = option;
+          }
+        }
+        const structural = [
+          ...validationDiagnostics(result.errors),
+          ...unavailable2 ? [unavailable2] : [],
+          ...qualityOption ? [qualityOption] : []
+        ];
+        const all = [
+          ...structural,
+          ...analysis ? [
+            ...qualityAnalysisDiagnostics(analysis),
+            ...ruleErrorDiagnostics(analysis)
+          ] : []
+        ];
         const counts = countDiagnostics(all);
+        const blocked = countDiagnostics(structural).error > 0 || analysis?.blocked === true;
         const { kept, truncated } = capDiagnostics(
           all,
           args.maxDiagnostics ?? DEFAULT_MAX_DIAGNOSTICS
         );
         return {
-          ok: counts.error === 0,
+          ok: !blocked,
           diagnostics: kept,
-          valid: counts.error === 0,
+          valid: !blocked,
           format: args.format,
           ...args.renderer !== void 0 && { renderer: args.renderer },
           source: sourceSummary(resolved),
           counts,
-          truncated
+          // The engine caps its own list under a policy budget, so a report
+          // shortened there would otherwise come back reading complete.
+          truncated: truncated || analysis?.truncated === true,
+          ...analysis?.profileId !== void 0 && {
+            profileId: analysis.profileId
+          }
         };
       })
     )
@@ -2818,6 +3068,9 @@ import crypto2 from "crypto";
 import { promises as fs6 } from "fs";
 import os2 from "os";
 import path5 from "path";
+import {
+  RENDERER_DEPENDENCY_MISSING as RENDERER_DEPENDENCY_MISSING2
+} from "@json-to-office/shared";
 import { getFontStager } from "@json-to-office/jto-ops";
 
 // src/preview/cache-key.ts
@@ -3149,6 +3402,15 @@ function renderFailure(stage, detail, context = {}) {
     { suggestion, context: { stage, ...context } }
   );
 }
+function buildFailure(error) {
+  if (error instanceof Error && error.name === RENDERER_DEPENDENCY_MISSING2) {
+    return failure(ERROR_CODES.DEPENDENCY_MISSING, message(error), {
+      suggestion: "Install the renderer's backend, or re-run with a renderer jto_info reports as available. The document is not at fault.",
+      context: { stage: "build" }
+    });
+  }
+  return renderFailure("build", message(error));
+}
 var PNG_SIGNATURE = Buffer.from([
   137,
   80,
@@ -3355,9 +3617,10 @@ async function renderPreview(options) {
     converters = versions;
   } catch (error) {
     if (signal?.aborted) return cancelled2();
+    const build = buildFailure(error);
     return failureFrom([
-      ...validationDiagnostics2(options.getAdapter(format), document),
-      ...renderFailure("build", message(error)).diagnostics
+      ...build.diagnostics[0]?.code === ERROR_CODES.DEPENDENCY_MISSING ? [] : validationDiagnostics2(options.getAdapter(format), document),
+      ...build.diagnostics
     ]);
   }
   const generateMs = elapsed(generateStarted);
@@ -5559,6 +5822,7 @@ var RESOURCE_URIS = {
   catalog: "jto://catalog",
   renderers: "jto://renderers",
   themes: "jto://themes",
+  themeValues: "jto://themes/values",
   templates: "jto://templates",
   documentSchema: (format) => `jto://schema/${format}/document`,
   themeSchema: (format) => `jto://schema/${format}/theme`
@@ -5610,7 +5874,7 @@ function register9(server, deps) {
     RESOURCE_URIS.themes,
     {
       title: "Built-in themes",
-      description: "Theme names shipped with each format, usable as a document\u2019s props.theme or as the tools\u2019 theme option.",
+      description: "Theme names shipped with each format, usable as a document\u2019s props.theme or as the tools\u2019 theme option. jto://themes/values carries what each name actually looks like.",
       mimeType: JSON_MIME
     },
     async (uri) => {
@@ -5623,6 +5887,33 @@ function register9(server, deps) {
       });
     }
   );
+  server.registerResource(
+    "theme-values",
+    RESOURCE_URIS.themeValues,
+    {
+      title: "Built-in theme values",
+      description: "The palette, fonts, style tables and component defaults behind every built-in theme name \u2014 what a document actually opts into with props.theme. A name alone cannot tell you whether a theme fits the brief; this can.",
+      mimeType: JSON_MIME
+    },
+    async (uri) => {
+      const formats = await Promise.all(
+        FORMAT_NAMES.map(async (format) => {
+          const adapter = deps.getAdapter(format);
+          let themes;
+          try {
+            themes = adapter.getBuiltinThemeValues ? await adapter.getBuiltinThemeValues() : adapter.getBuiltinThemes();
+          } catch {
+            themes = adapter.getBuiltinThemes();
+          }
+          return {
+            format,
+            themes
+          };
+        })
+      );
+      return jsonContents(uri, { formats });
+    }
+  );
   server.registerResource(
     "templates",
     RESOURCE_URIS.templates,
@@ -5671,6 +5962,7 @@ Working rules:
 - Discover before authoring. Call jto_info first, then jto_discover and jto_describe_component (or read the jto:// resources) for the components and renderer ids a format actually supports.
 - Make small edits. With a workspace handle, patch precisely (RFC 6902 over RFC 6901 paths) instead of resending the whole document; without one, change one region at a time.
 - Validate often. Run jto_validate after each edit rather than once at the end; diagnostics are path-addressed, so they map straight back onto the JSON you just changed.
+- Treat design findings as defects. Schema-valid is not well-designed: jto_validate also lints layout and legibility (W_QUALITY_* \u2014 undeclared slide canvas, text overflowing its box, overcrowded slides, table widths exceeding their section). These never block generation, but they almost always show in the rendered result \u2014 repair them like errors.
 - Preview when the answer is visual. jto_preview renders pages to PNG; use it whenever layout, overflow or fit is in question, not only before finishing.
 - Snapshot before risky changes. jto_workspace_snapshot pins the current revision so a restructuring you cannot cleanly undo is still recoverable.