@sanity-labs/slides 0.0.0

package/src/dev/use-keyboard-nav.ts

@@ -0,0 +1,64 @@
+import { useEffect, useRef } from 'react';
+
+export type KeyboardActions = {
+  readonly onPrev: () => void;
+  readonly onNext: () => void;
+  readonly onFirst: () => void;
+  readonly onLast: () => void;
+  readonly onZoomIn: () => void;
+  readonly onZoomOut: () => void;
+  readonly onZoomFit: () => void;
+  readonly onToggleNav: () => void;
+  readonly onShowHelp: () => void;
+};
+
+const isTypingTarget = (el: EventTarget | null): boolean => {
+  if (!(el instanceof HTMLElement)) return false;
+  if (el.isContentEditable) return true;
+  const tag = el.tagName;
+  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+};
+
+export const useKeyboardNav = (actions: KeyboardActions): void => {
+  const ref = useRef(actions);
+  ref.current = actions;
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (isTypingTarget(e.target)) return;
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      const handler = SHORTCUTS[e.key];
+      if (!handler) return;
+      e.preventDefault();
+      handler(ref.current);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+};
+
+const SHORTCUTS: Record<string, (a: KeyboardActions) => void> = {
+  ArrowDown: (a) => a.onNext(),
+  ArrowUp: (a) => a.onPrev(),
+  ArrowRight: (a) => a.onNext(),
+  ArrowLeft: (a) => a.onPrev(),
+  j: (a) => a.onNext(),
+  k: (a) => a.onPrev(),
+  Home: (a) => a.onFirst(),
+  End: (a) => a.onLast(),
+  '0': (a) => a.onZoomFit(),
+  '+': (a) => a.onZoomIn(),
+  '=': (a) => a.onZoomIn(),
+  '-': (a) => a.onZoomOut(),
+  '[': (a) => a.onToggleNav(),
+  '?': (a) => a.onShowHelp(),
+};
+
+export const SHORTCUT_LIST: ReadonlyArray<{ keys: string; label: string }> = [
+  { keys: '↑ ↓ / j k', label: 'Previous / next slide' },
+  { keys: 'Home / End', label: 'First / last slide' },
+  { keys: '0', label: 'Auto zoom' },
+  { keys: '+ / –', label: 'Zoom in / out' },
+  { keys: '[', label: 'Toggle navigation' },
+  { keys: '?', label: 'Show this help' },
+];

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `@sanity-labs/slides` — root export.
+ *
+ * The renderer (React reconciler + PPTX runtime + `Template` type +
+ * primitives). What template authors `import` to write their slides.
+ *
+ * Other subpaths:
+ *   - `@sanity-labs/slides/mcp`      → MCP server framework
+ *   - `@sanity-labs/slides/dev`      → browser dev viewer
+ *   - `@sanity-labs/slides/sanity`   → Sanity reference template
+ *   - `@sanity-labs/slides/scaffold` → scaffold-a-new-template
+ *
+ * The `slidesctl` bin exposes the MCP server + generator + scaffolder as a
+ * single CLI driven by Claude (or any MCP client) — see the README.
+ */
+
+export * from './core/index.js';

package/src/mcp/errors.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'vitest';
+import { z } from 'zod';
+import { errorResult, formatZodIssue, zodErrorResult } from './errors.js';
+
+describe('formatZodIssue', () => {
+  test('formats a path-bearing issue', () => {
+    const result = z.object({ a: z.object({ b: z.string() }) }).safeParse({ a: { b: 1 } });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const issue = result.error.issues[0];
+      if (!issue) throw new Error('expected at least one issue');
+      const formatted = formatZodIssue(issue);
+      expect(formatted.path).toBe('a.b');
+      expect(formatted.message).toMatch(/string/i);
+    }
+  });
+
+  test('uses (root) for top-level issues', () => {
+    const result = z.string().safeParse(42);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const issue = result.error.issues[0];
+      if (!issue) throw new Error('expected at least one issue');
+      expect(formatZodIssue(issue).path).toBe('(root)');
+    }
+  });
+});
+
+describe('zodErrorResult', () => {
+  test('returns isError: true with bullets and a hint', () => {
+    const parse = z.object({ x: z.string() }).safeParse({});
+    if (parse.success) throw new Error('expected failure');
+    const result = zodErrorResult('Validation error in foo:', parse.error, 'Try again.');
+    expect(result.isError).toBe(true);
+    const text = result.content[0]?.text ?? '';
+    expect(text).toMatch(/Validation error in foo/);
+    expect(text).toMatch(/x:/);
+    expect(text).toMatch(/Try again\./);
+    expect(result.structuredContent.error.code).toBe('validation_error');
+    expect(result.structuredContent.error.issues?.[0]?.path).toBe('x');
+  });
+});
+
+describe('errorResult', () => {
+  test('builds a generic actionable error', () => {
+    const result = errorResult('boom', 'Something bad. Retry later.');
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toBe('Something bad. Retry later.');
+    expect(result.structuredContent.error.code).toBe('boom');
+  });
+});

package/src/mcp/errors.ts

@@ -0,0 +1,76 @@
+/**
+ * Error formatting for MCP tool responses.
+ *
+ * Per SEP-1303 and the mcp-best-practices doc: tool errors are returned
+ * **inside the result with `isError: true`** rather than as JSON-RPC errors,
+ * with messages that include actionable next steps so the LLM can self-correct.
+ */
+
+import type { ZodError, ZodIssue } from 'zod';
+
+/**
+ * The shape of an MCP tool result error response (subset we use).
+ *
+ * Includes `[x: string]: unknown` so it's assignable to the SDK's wider
+ * `CallToolResult` type (which carries an open index signature). The fields
+ * we set are the only ones we depend on.
+ */
+export type ToolErrorResult = {
+  isError: true;
+  content: Array<{ type: 'text'; text: string }>;
+  structuredContent: { error: ToolErrorPayload };
+  [extra: string]: unknown;
+};
+
+/** Structured-content payload for tool errors, exposed for callers that want to inspect. */
+export interface ToolErrorPayload {
+  /** Stable error code, e.g., `validation_error`, `unknown_component`. */
+  readonly code: string;
+  /** Human-readable message including suggested next steps. */
+  readonly message: string;
+  /** For validation errors: the per-field issues. */
+  readonly issues?: ReadonlyArray<{ readonly path: string; readonly message: string }>;
+}
+
+/** Format a single Zod issue as a one-line bullet for inclusion in an error message. */
+export const formatZodIssue = (issue: ZodIssue): { path: string; message: string } => ({
+  path: issue.path.length > 0 ? issue.path.map(String).join('.') : '(root)',
+  message: issue.message,
+});
+
+/**
+ * Build a tool-error result for a Zod validation failure.
+ *
+ * The text is structured so an LLM can read off (a) which fields failed,
+ * (b) why, and (c) the next-step hint. The structuredContent carries the
+ * machine-readable shape for non-LLM callers.
+ */
+export const zodErrorResult = (context: string, error: ZodError, hint: string): ToolErrorResult => {
+  const issues = error.issues.map(formatZodIssue);
+  const bullets = issues.map((i) => `  • ${i.path}: ${i.message}`).join('\n');
+  const text = `${context}\n${bullets}\n${hint}`;
+  return {
+    isError: true,
+    content: [{ type: 'text', text }],
+    structuredContent: {
+      error: {
+        code: 'validation_error',
+        message: text,
+        issues,
+      },
+    },
+  };
+};
+
+/** Build a generic actionable tool error, optionally carrying field-level issues. */
+export const errorResult = (
+  code: string,
+  message: string,
+  issues?: ReadonlyArray<{ readonly path: string; readonly message: string }>,
+): ToolErrorResult => ({
+  isError: true,
+  content: [{ type: 'text', text: message }],
+  structuredContent: {
+    error: issues === undefined ? { code, message } : { code, message, issues },
+  },
+});

package/src/mcp/index.ts

@@ -0,0 +1,45 @@
+/**
+ * react-pptx-mcp — template-agnostic MCP server framework.
+ *
+ * The substrate a template package wires into to expose its slide-component
+ * library as an MCP server. Iterates the template's components, derives one
+ * MCP tool per slide type (default name `slides_add_<component>`; override
+ * via `SlideServerConfig.toolPrefix`), plus a discovery tool (`slides_list`)
+ * and a one-shot create tool (`slides_create`), then starts a stdio transport.
+ *
+ * The `start({ transport })` shape is the seam for Streamable HTTP / remote
+ * transports later. Today only stdio is implemented.
+ *
+ * Public API:
+ *
+ * ```ts
+ * import { createSlideServer } from '../mcp/index.js';
+ * import { PptxSlidesRuntime } from '../core/index.js'; // or any SlidesRuntime
+ *
+ * const runtime = new PptxSlidesRuntime({ outputDir: '/tmp/decks' });
+ * const server = createSlideServer({ template: myTemplate, runtime });
+ * await server.start({ transport: 'stdio' });
+ * ```
+ */
+
+export {
+  createSlideServer,
+  type SlideServer,
+  type SlideServerConfig,
+  type StartOptions,
+} from './server.js';
+export { renderSlides, type RenderResult, type RenderIssue, type SlideSpec } from './render.js';
+export {
+  componentToTool,
+  deriveComponentTools,
+  type DerivedTool,
+  type JsonSchema,
+} from './schema.js';
+export { DEFAULT_COMPONENT_TOOL_PREFIX, componentToolName, toSnakeCase } from './naming.js';
+export {
+  errorResult,
+  formatZodIssue,
+  zodErrorResult,
+  type ToolErrorPayload,
+  type ToolErrorResult,
+} from './errors.js';

package/src/mcp/naming.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'vitest';
+import { DEFAULT_COMPONENT_TOOL_PREFIX, componentToolName, toSnakeCase } from './naming.js';
+
+describe('toSnakeCase', () => {
+  test('PascalCase → snake_case', () => {
+    expect(toSnakeCase('Cover')).toBe('cover');
+    expect(toSnakeCase('TwoColumn')).toBe('two_column');
+    expect(toSnakeCase('SectionDivider')).toBe('section_divider');
+  });
+
+  test('handles consecutive caps', () => {
+    expect(toSnakeCase('HTTPServer')).toBe('http_server');
+    expect(toSnakeCase('IOQueue')).toBe('io_queue');
+    expect(toSnakeCase('XMLHttpRequest')).toBe('xml_http_request');
+  });
+
+  test('passes through already-snake', () => {
+    expect(toSnakeCase('two_column')).toBe('two_column');
+  });
+
+  test('replaces kebab-case', () => {
+    expect(toSnakeCase('two-column')).toBe('two_column');
+  });
+});
+
+describe('componentToolName', () => {
+  test('joins prefix and snake_case component name', () => {
+    expect(componentToolName('Cover')).toBe('slides_add_cover');
+    expect(componentToolName('TwoColumn')).toBe('slides_add_two_column');
+  });
+
+  test('default prefix is exposed for downstream consumers', () => {
+    expect(DEFAULT_COMPONENT_TOOL_PREFIX).toBe('slides_add_');
+  });
+
+  test('respects a custom prefix', () => {
+    expect(componentToolName('Cover', 'report_add_')).toBe('report_add_cover');
+  });
+});

package/src/mcp/naming.ts

@@ -0,0 +1,49 @@
+/**
+ * Tool-name conversion helpers.
+ *
+ * MCP tool names follow `{service}_{action}_{resource}` snake_case per
+ * Anthropic's mcp-builder guidance. The default `service_action` prefix is
+ * `slides_add_` since this framework's first target is slide decks; brand
+ * servers can override via `SlideServerConfig.toolPrefix` when they ship a
+ * different verb or service.
+ *
+ * Examples (with the default prefix):
+ *   Cover           → slides_add_cover
+ *   TwoColumn       → slides_add_two_column
+ *   SectionDivider  → slides_add_section_divider
+ */
+
+/** The default tool-name prefix used for brand-component-derived tools. */
+export const DEFAULT_COMPONENT_TOOL_PREFIX = 'slides_add_';
+
+/**
+ * Convert a PascalCase / camelCase identifier to snake_case.
+ *
+ * Behavior:
+ * - `TwoColumn` → `two_column`
+ * - `HTTPServer` → `http_server` (consecutive caps treated as a unit, then lowercased)
+ * - `IOQueue` → `io_queue`
+ * - already-snake or kebab text passes through with the kebabs replaced.
+ *
+ * Template components are expected to use PascalCase by convention, but this
+ * function is forgiving so a brand author who slips can still get a stable
+ * tool name without the framework refusing to start.
+ */
+export const toSnakeCase = (name: string): string =>
+  name
+    // boundary between a run of caps and a following Title-case word: `HTTPServer` → `HTTP_Server`
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    // boundary between lowercase/digit and a cap: `twoColumn` → `two_Column`
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/-/g, '_')
+    .toLowerCase();
+
+/**
+ * Build the MCP tool name for a brand component.
+ *
+ * `prefix` defaults to `DEFAULT_COMPONENT_TOOL_PREFIX` (`slides_add_`).
+ */
+export const componentToolName = (
+  componentName: string,
+  prefix: string = DEFAULT_COMPONENT_TOOL_PREFIX,
+): string => `${prefix}${toSnakeCase(componentName)}`;

package/src/mcp/render.ts

@@ -0,0 +1,110 @@
+/**
+ * The full pipeline from a list of slide specs to a `.pptx` file on disk.
+ *
+ * Shared by the `slides_create` MCP tool and the `generate` CLI subcommand a
+ * template binary would normally ship. Both call this; both branch on the
+ * tagged `Result` it returns.
+ */
+
+import { createElement, Fragment, type ReactElement, type ReactNode } from 'react';
+import { renderToOps, ReconcilerError, type SlidesRuntime, type Template } from '../core/index.js';
+
+/** One slide spec: which component, what props. */
+export interface SlideSpec {
+  readonly component: string;
+  readonly props: Record<string, unknown>;
+}
+
+/** A field-level validation issue. */
+export interface RenderIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+/** Result of a render. Tagged union for explicit branching. */
+export type RenderResult =
+  | { readonly ok: true; readonly filePath: string; readonly slideCount: number }
+  | {
+      readonly ok: false;
+      readonly code:
+        | 'unknown_component'
+        | 'validation_error'
+        | 'reconciler_error'
+        | 'runtime_error';
+      readonly message: string;
+      readonly issues?: readonly RenderIssue[];
+    };
+
+/**
+ * Render a list of slide specs to a `.pptx` file. Validates every spec
+ * against its component's schema before constructing the tree.
+ *
+ * @param template - The template (slide-component vocabulary + tokens).
+ * @param runtime  - The PPTX runtime to write through.
+ * @param title    - Deck title (also the `.pptx` filename stem).
+ * @param slides   - The slide specs, in order.
+ */
+export const renderSlides = async (params: {
+  readonly template: Template;
+  readonly runtime: SlidesRuntime;
+  readonly title: string;
+  readonly slides: ReadonlyArray<SlideSpec>;
+}): Promise<RenderResult> => {
+  const { template, runtime, title, slides } = params;
+
+  const children: ReactNode[] = [];
+  for (let i = 0; i < slides.length; i++) {
+    const spec = slides[i];
+    if (spec === undefined) continue;
+    const component = template.components[spec.component];
+    if (!component) {
+      const known = Object.keys(template.components).sort().join(', ') || '(none)';
+      return {
+        ok: false,
+        code: 'unknown_component',
+        message:
+          `slides[${i}].component "${spec.component}" is not a slide type in template ` +
+          `"${template.name}". Known types: ${known}. Call slides_list to see them with descriptions.`,
+      };
+    }
+    const parsed = component.schema.safeParse(spec.props);
+    if (!parsed.success) {
+      const issues: RenderIssue[] = parsed.error.issues.map((issue) => ({
+        path: issue.path.length > 0 ? issue.path.map(String).join('.') : '(root)',
+        message: issue.message,
+      }));
+      const bullets = issues.map((it) => `  • ${it.path}: ${it.message}`).join('\n');
+      return {
+        ok: false,
+        code: 'validation_error',
+        message: `Validation error in slides[${i}].props (slide type "${spec.component}"):\n${bullets}`,
+        issues,
+      };
+    }
+    children.push(createElement(component.component, { key: i, ...parsed.data }));
+  }
+  const tree: ReactElement = createElement(Fragment, null, ...children);
+
+  try {
+    const { deckId } = await runtime.createDeckFromMaster(template.name, title);
+    const reconciled = renderToOps({ tree, template, deckId });
+    await runtime.applyOps(deckId, reconciled.ops);
+    runtime.attachManifest(deckId, reconciled.manifest);
+    const { filePath } = await runtime.write(deckId);
+    return { ok: true, filePath, slideCount: slides.length };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof ReconcilerError) {
+      return {
+        ok: false,
+        code: 'reconciler_error',
+        message: `Reconciler rejected the slide tree: ${message}.`,
+      };
+    }
+    return {
+      ok: false,
+      code: 'runtime_error',
+      message: `Error generating PPTX: ${message}.`,
+    };
+  }
+};

package/src/mcp/schema.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from 'vitest';
+import { z } from 'zod';
+import { CANVAS_16_9, type Template } from '../core/index.js';
+import { componentToTool, deriveComponentTools } from './schema.js';
+
+const TestBrand: Template = {
+  name: 'test',
+  canvas: CANVAS_16_9,
+  fonts: { display: ['Inter'], body: ['Inter'], mono: ['Mono'] },
+  colors: { 'fg.base': '#000000' },
+  typography: { 'body-md': { fontFamily: 'body', fontSize: 18, lineHeight: 1.5 } },
+  spacing: { md: 12 },
+  components: {
+    Cover: {
+      component: () => null,
+      schema: z
+        .object({
+          title: z.string().min(1).describe('The cover title.'),
+          subtitle: z.string().optional().describe('Optional subtitle.'),
+        })
+        .strict(),
+      description: 'Use as the first slide. Sets title and stance.',
+    },
+    TwoColumn: {
+      component: () => null,
+      schema: z
+        .object({
+          left: z.string(),
+          right: z.string(),
+        })
+        .strict(),
+      description: 'Use to compare two parallel ideas of equal weight.',
+    },
+    SectionDivider: {
+      component: () => null,
+      schema: z.object({ label: z.string() }).strict(),
+      description: 'Use to separate major sections of the deck.',
+    },
+  },
+};
+
+describe('deriveComponentTools', () => {
+  test('returns one tool per brand component, in object order', () => {
+    const tools = deriveComponentTools(TestBrand);
+    expect(tools.map((t) => t.name)).toEqual([
+      'slides_add_cover',
+      'slides_add_two_column',
+      'slides_add_section_divider',
+    ]);
+  });
+
+  test('description is taken from the brand component', () => {
+    const tools = deriveComponentTools(TestBrand);
+    const cover = tools.find((t) => t.componentName === 'Cover');
+    expect(cover?.description).toBe('Use as the first slide. Sets title and stance.');
+  });
+
+  test('inputShape carries the raw Zod shape', () => {
+    const cover = TestBrand.components.Cover;
+    if (!cover) throw new Error('Cover missing from test brand');
+    const tool = componentToTool('Cover', cover);
+    expect(Object.keys(tool.inputShape).sort()).toEqual(['subtitle', 'title']);
+  });
+});
+
+describe('componentToTool — JSON Schema derivation', () => {
+  test('produces a JSON-Schema-7-shaped object with required fields', () => {
+    const cover = TestBrand.components.Cover;
+    if (!cover) throw new Error('Cover missing from test brand');
+    const tool = componentToTool('Cover', cover);
+    const schema = tool.inputJsonSchema;
+    expect(schema.type).toBe('object');
+    expect(schema.required).toEqual(['title']);
+    const properties = schema.properties as Record<string, { type?: string; description?: string }>;
+    expect(properties.title?.type).toBe('string');
+    expect(properties.title?.description).toBe('The cover title.');
+    expect(properties.subtitle?.type).toBe('string');
+  });
+
+  test('preserves .strict() as additionalProperties: false', () => {
+    const cover = TestBrand.components.Cover;
+    if (!cover) throw new Error('Cover missing from test brand');
+    const tool = componentToTool('Cover', cover);
+    expect(tool.inputJsonSchema.additionalProperties).toBe(false);
+  });
+});

package/src/mcp/schema.ts

@@ -0,0 +1,93 @@
+/**
+ * Schema-derivation helpers.
+ *
+ * Two things happen here:
+ *
+ * 1. **Template component → MCP tool definition.** We iterate `brand.components`
+ *    and return a list of `DerivedTool` records — each one is everything the
+ *    server needs to call `McpServer.registerTool`.
+ *
+ * 2. **Zod → JSON Schema conversion.** The MCP wire format uses JSON Schema
+ *    for tool input/output. The SDK's `registerTool` accepts Zod and converts
+ *    internally; we ALSO produce JSON Schema explicitly via `zod-to-json-schema`
+ *    so callers (and unit tests) can inspect the derived shape without
+ *    spinning up a server.
+ */
+
+import { zodToJsonSchema, type Options as ZodToJsonSchemaOptions } from 'zod-to-json-schema';
+
+import type { z } from 'zod';
+import type { Template, TemplateComponent } from '../core/index.js';
+import { componentToolName } from './naming.js';
+
+/** A JSON Schema document. We keep this loose; consumers can refine if needed. */
+export type JsonSchema = Record<string, unknown>;
+
+/**
+ * Everything the server needs to register a single brand-component-backed tool.
+ *
+ * Exposed as part of the package's public surface so callers (CLI smoke tests,
+ * doc generators, anything inspecting the brand) can list the derived tools
+ * without instantiating a server.
+ */
+export interface DerivedTool {
+  /** The MCP tool name, e.g. `slides_add_cover`. */
+  readonly name: string;
+  /** The tool description (LLM-facing, taken from the brand component). */
+  readonly description: string;
+  /** The input shape. `Record<string, ZodType>` is what the SDK expects. */
+  readonly inputShape: z.ZodRawShape;
+  /** The Zod object schema, retained for runtime validation in tool handlers. */
+  readonly inputSchema: z.ZodObject<z.ZodRawShape>;
+  /** JSON Schema representation of the input, for inspection. */
+  readonly inputJsonSchema: JsonSchema;
+  /** Stable component name from the brand (e.g., `Cover`). */
+  readonly componentName: string;
+}
+
+/**
+ * Convert a single brand component to a derived-tool record.
+ *
+ * Pure function: same component → same DerivedTool. The conversion of
+ * `schema` to JSON Schema runs through `zod-to-json-schema`, which produces
+ * Draft-07 by default (matching the MCP wire format).
+ *
+ * `toolPrefix` defaults to `'slides_add_'`. Servers that want a different
+ * verb or service prefix (e.g., `'report_add_'`) override it.
+ */
+export const componentToTool = (
+  componentName: string,
+  component: TemplateComponent,
+  toolPrefix?: string,
+): DerivedTool => {
+  const inputShape = component.schema.shape;
+  const inputJsonSchema = zodToJsonSchema(component.schema, JSON_SCHEMA_OPTIONS);
+  return {
+    name: componentToolName(componentName, toolPrefix),
+    description: component.description,
+    inputShape,
+    inputSchema: component.schema,
+    inputJsonSchema,
+    componentName,
+  };
+};
+
+/** Derive every per-component tool from a brand. */
+export const deriveComponentTools = (brand: Template, toolPrefix?: string): DerivedTool[] =>
+  Object.entries(brand.components).map(([name, component]) =>
+    componentToTool(name, component, toolPrefix),
+  );
+
+/**
+ * Options passed to `zod-to-json-schema`.
+ *
+ * - `target: 'jsonSchema7'` matches the dialect MCP servers emit (and what the
+ *   official SDK produces internally when given a Zod schema).
+ * - `$refStrategy: 'none'` inlines all sub-schemas — simpler for LLMs to read
+ *   in tool descriptions, and the schemas are typically shallow so the inline
+ *   bloat is negligible.
+ */
+const JSON_SCHEMA_OPTIONS: Partial<ZodToJsonSchemaOptions> = {
+  target: 'jsonSchema7',
+  $refStrategy: 'none',
+};