@sanity-labs/slides 0.0.0

package/README.md

@@ -0,0 +1,241 @@
+# @sanity-labs/slides
+
+**Brand-locked PowerPoint generation for LLMs. Write your slide template in React; Claude writes the deck.**
+
+[![ci](https://github.com/sanity-labs/slides/actions/workflows/ci.yml/badge.svg)](https://github.com/sanity-labs/slides/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@sanity-labs/slides)](https://www.npmjs.com/package/@sanity-labs/slides)
+
+A template is a React project. Each slide type is a component + a Zod schema. The bundled MCP server reads your template and exposes it to Claude (or any MCP client) as auto-derived tools. The LLM can pick slide types and fill props, but it cannot pick fonts, colors, or layout — those are locked in the template.
+
+One package on npm. Four subpath exports. One CLI bin.
+
+---
+
+## Quickstart
+
+### 1. Scaffold a template
+
+```bash
+npx @sanity-labs/slides scaffold my-template
+cd my-template
+pnpm install
+pnpm dev    # opens the hot-reloading viewer at http://localhost:5173
+```
+
+You get a working template with one starter slide (`Cover`) and a Vite-backed dev viewer. Edit anything under `src/` and the page updates.
+
+### 2. Build it
+
+```bash
+pnpm build
+```
+
+That emits `dist/index.js` — the file the MCP server will import.
+
+### 3. Wire it into Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (or the equivalent on your OS):
+
+```json
+{
+  "mcpServers": {
+    "slides": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@sanity-labs/slides",
+        "serve",
+        "--template",
+        "/absolute/path/to/my-template/dist/index.js",
+        "--output",
+        "/Users/you/Desktop"
+      ]
+    }
+  }
+}
+```
+
+Restart Claude.
+
+### 4. Ask
+
+> "Make me a 5-slide Q4 review deck with my template."
+
+Claude calls `slides_list` to learn what slide types exist, fills props from the conversation, calls `slides_create`, and hands you back the absolute path to the `.pptx`.
+
+Total setup time once you have a template: about two minutes.
+
+---
+
+## What you ship when you build a template
+
+```
+my-template/
+├── package.json
+├── src/
+│   ├── index.ts          # the Template value — tokens, fonts, components map
+│   ├── preview.tsx       # canonical slide order shown in the viewer
+│   └── components/
+│       └── Cover.tsx     # one component = one slide type = one MCP tool
+└── dist/                 # `pnpm build` output — what the MCP server imports
+```
+
+A slide type is a React component with a Zod schema next to it:
+
+```tsx
+// src/components/Quote.tsx
+import { Slide, Box, Text } from '@sanity-labs/slides';
+import { z } from 'zod';
+
+export const QuoteSchema = z
+  .object({
+    quote: z.string().min(1).describe('The pull quote. Plain text.'),
+    attribution: z.string().optional().describe('Optional speaker.'),
+  })
+  .strict();
+
+export const Quote = ({ quote, attribution }: z.infer<typeof QuoteSchema>) => (
+  <Slide>
+    <Box rect={{ x: 0, y: 0, w: 960, h: 540 }} fill={{ kind: 'solid', color: '#ff5500' }} />
+    <Box rect={{ x: 60, y: 200, w: 840, h: 160 }}>
+      <Text textStyle={{ fontFamily: 'display', fontSize: 48, foregroundColor: '#0b0b0b' }}>
+        “{quote}”
+      </Text>
+    </Box>
+    {attribution ? (
+      <Box rect={{ x: 60, y: 380, w: 840, h: 32 }}>
+        <Text textStyle={{ fontFamily: 'mono', fontSize: 14, foregroundColor: '#0b0b0b' }}>
+          — {attribution}
+        </Text>
+      </Box>
+    ) : null}
+  </Slide>
+);
+```
+
+Register it in `src/index.ts`:
+
+```ts
+components: {
+  Quote: defineTemplateComponent({
+    component: Quote,
+    schema: QuoteSchema,
+    description: 'Pull-quote slide. Use sparingly between sections.',
+  }),
+}
+```
+
+`pnpm build` and Claude will see a new `slides_add_quote` tool on its next request.
+
+The Zod schema field `.describe(...)` text becomes the LLM-facing documentation. The `description` on the template entry tells Claude when to pick the type.
+
+---
+
+## What Claude sees
+
+After you wire the MCP server in, Claude has three tools, auto-derived from your template:
+
+| Tool                | Purpose                                                                   |
+| ------------------- | ------------------------------------------------------------------------- |
+| `slides_list`       | Lists every slide type with its description.                              |
+| `slides_add_<type>` | Validates a single slide's props against the Zod schema.                  |
+| `slides_create`     | Takes `{ title, slides }`, writes the `.pptx`, returns the absolute path. |
+
+The package also ships an LLM skill describing the calling convention. Print it with:
+
+```bash
+npx @sanity-labs/slides skill
+```
+
+Paste it into a Claude project's knowledge sources to teach the model the workflow up front.
+
+---
+
+## Subpath layout
+
+One npm package, four import surfaces:
+
+| Subpath                        | Contents                                                                |
+| ------------------------------ | ----------------------------------------------------------------------- |
+| `@sanity-labs/slides`          | Renderer + `Template` type + `Slide`/`Box`/`Text` primitives + runtime. |
+| `@sanity-labs/slides/mcp`      | `createSlideServer`, `renderSlides` — programmatic MCP API.             |
+| `@sanity-labs/slides/dev`      | Dev-viewer building blocks (`composeDeck`, `DeckViewer`).               |
+| `@sanity-labs/slides/scaffold` | `scaffoldTemplate({ target, name })` — programmatic scaffold API.       |
+| `@sanity-labs/slides/skill`    | The bundled `SKILL.md` Markdown file.                                   |
+
+Vite, tailwind, react-dom, lucide-react and friends are listed as **optional peer dependencies**, only required when you import `/dev`. Users wiring the MCP into Claude pay for none of that install weight.
+
+### Bins
+
+| Bin          | Purpose                                                                                        |
+| ------------ | ---------------------------------------------------------------------------------------------- |
+| `slidesctl`  | The CLI the MCP server runs on. Subcommands: `serve`, `generate`, `list`, `scaffold`, `skill`. |
+| `slides-dev` | The Vite-backed dev viewer used by template authors' `pnpm dev`.                               |
+
+`npx @sanity-labs/slides …` resolves to the `slidesctl` bin (matches the package's short name).
+
+---
+
+## Reference template
+
+The Sanity-branded reference template lives in its own repo at [`sanity-labs/slides-template`](https://github.com/sanity-labs/slides-template). It's the most thorough authoring example — eight slide types, brand chrome helpers, embedded raster assets, and SVG textures — and it dogfoods this package by consuming `@sanity-labs/slides` exactly the way an external user would.
+
+To use it:
+
+```bash
+git clone git@github.com:sanity-labs/slides-template.git
+cd slides-template
+pnpm install
+pnpm build
+```
+
+Then point Claude at it the same way as any other template:
+
+```json
+"args": ["-y", "@sanity-labs/slides", "serve", "--template", "/abs/path/to/slides-template/dist/index.js"]
+```
+
+---
+
+## Repo layout
+
+```text
+src/
+├── index.ts              # root: renderer + Template + primitives
+├── cli.ts                # `slidesctl` bin
+├── core/                 # renderer + PPTX runtime
+├── mcp/                  # MCP server framework
+├── dev/                  # browser dev viewer (incl. slides-dev bin)
+├── scaffold/             # scaffold logic + template-base/
+└── __tests__/            # framework smoke tests + synthetic fixture template
+
+scripts/copy-static-assets.mjs    copies non-TS assets (CSS, template-base, shims) into dist/
+docs/                             architecture, testing strategy
+.changeset/                       changesets config + queued release notes
+.github/workflows/                CI + release pipeline
+SKILL.md                          LLM skill — served by `slidesctl skill`
+```
+
+---
+
+## Contributing
+
+See [`docs/architecture.md`](./docs/architecture.md) for the layer pyramid.
+
+```bash
+pnpm install
+pnpm verify    # typecheck + lint + format + build + test + knip + verify-bins
+```
+
+Releases use [Changesets](https://github.com/changesets/changesets):
+
+```bash
+pnpm changeset    # describe what changed (single package — just pick patch/minor/major)
+git commit -am "feat: …"
+# A "Version Packages" PR opens automatically on push to main.
+# Merge that PR and the release workflow publishes @sanity-labs/slides to npm.
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: react-pptx-slides
+description: How to drive a `react-pptx` template MCP server. Use this skill whenever the user asks for a slide deck or `.pptx` file and an MCP server exposing the `slides_list`, `slides_add_*`, and `slides_create` tools is available. The skill teaches the calling convention, the validation contract, and the recovery patterns for the three error codes the server returns.
+license: MIT
+metadata:
+  author: react-pptx
+  version: '1.0.0'
+---
+
+# react-pptx slide-deck MCP
+
+`react-pptx` template servers expose a brand's slide vocabulary as MCP tools. Every template has its own server binary (`<template>-slides`) that publishes the same three tools, derived from the template's component schemas at startup.
+
+## When to apply
+
+Use this skill when the user asks for a slide deck and any of the following are true:
+
+- The conversation context contains a `react-pptx`-derived MCP server (tool names beginning with `slides_`).
+- The user references "the template", "our brand template", or a specific template name they've installed.
+- The user asks for a `.pptx` / PowerPoint file.
+
+Do **not** invent slide content with `Box`/`Text` primitives directly. The template's components are the only legal vocabulary; anything else is off-brand and will be rejected.
+
+## Tool surface
+
+| Tool                | Direction         | Use it for                                                                                      |
+| ------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
+| `slides_list`       | discovery         | Learn what slide types this template supports and what each is for.                             |
+| `slides_add_<type>` | per-slide preview | Validate a single slide's props against the schema. Returns a `SlideSpec`. Optional but useful. |
+| `slides_create`     | final write       | Take an array of `SlideSpec`s, render the deck, write the `.pptx`, return the absolute path.    |
+
+## The standard flow
+
+1. **Discover.** Call `slides_list` once. It returns `{ template, slides: [{ name, toolName, description, inputJsonSchema }] }`. Read every `description` and `inputJsonSchema` so you know which component to pick for each beat in the user's outline.
+2. **Plan.** Map the user's request to a sequence of slide types. The first slide is usually the template's `Cover`; the last is usually a closing slide (`Closing`, `ThankYou`, or similar — read the descriptions). In between, choose from the available types based on what the user is communicating.
+3. **Validate (optional).** If you're unsure about a slide's props, call `slides_add_<type>` with them. The server returns either a clean `SlideSpec` or a validation error with field-level paths. Use this when you've drafted a complex slide (grids, lists) and want a sanity check before paying the cost of a full render.
+4. **Create.** Call `slides_create` with `{ title, slides: [...] }`. On success it returns `{ filePath, slideCount }`. Surface the absolute `filePath` to the user.
+
+## Response shape from `slides_create`
+
+```json
+{ "filePath": "/Users/you/Desktop/Q4-Review.pptx", "slideCount": 6 }
+```
+
+On error, the server returns a structured error with one of three codes:
+
+| Code                                 | Meaning                                                                 | Recovery                                                                                                                      |
+| ------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `unknown_component`                  | You used a `component` name that isn't in the template.                 | Re-read `slides_list` (the server lists known types in the error message). Pick a real one.                                   |
+| `validation_error`                   | Zod rejected the props on a slide. The error includes `path` per issue. | Fix only the failing fields and resend the full `slides_create` call. Don't re-emit slides that weren't flagged.              |
+| `reconciler_error` / `runtime_error` | Something went wrong below the schema layer.                            | Report the message to the user verbatim. Suggest they file an issue against the template; this is rarely an LLM-side problem. |
+
+## Conventions
+
+- **Prefer one `slides_create` call, not many.** The tool atomically writes one file from the full slide list. Calling it per slide produces N files, not one deck.
+- **Don't ask the user for fonts, colors, or sizes.** They're inexpressible through the tool surface for a reason. The template owns them.
+- **Read schema descriptions before guessing.** Every Zod field carries a `.describe(...)` that tells you what content goes there. The default in `inputJsonSchema.properties.<field>.description` is authoritative.
+- **Default to the template's `preview` order when unsure of structure.** A common shape is: `Cover` → 1–3 body slides (`OneColumn`, `TitleAndBody`, `TitleAndGrid`) → optional `SectionDivider`s → 1–2 more body slides → `Closing`. Templates that diverge from this carry it in their descriptions.
+- **Respect array minimums.** `cells` in a grid, `items` in an agenda, `bullets` in a detail row — the schema specifies the minimum count. Padding is not allowed; pick a different component if the user has fewer items than the schema demands.
+- **Surface the file path.** After `slides_create` succeeds, tell the user the path verbatim — don't paraphrase or shorten.
+
+## Worked example
+
+User: _"Make me a five-slide Q4 review. Cover, two metric grids, one quote from the CEO, and a thank-you."_
+
+1. Call `slides_list`. Suppose the template returns `Cover`, `TitleAndGrid`, `Quote`, `Closing`.
+2. Compose:
+
+```json
+{
+  "title": "Q4 Review",
+  "slides": [
+    { "component": "Cover", "props": { "title": "Q4 Review", "subtitle": "Year in numbers" } },
+    {
+      "component": "TitleAndGrid",
+      "props": {
+        "title": "Revenue lines",
+        "cols": 3,
+        "rows": 1,
+        "cells": [
+          { "eyebrow": "ARR", "body": "$54M, +18% YoY" },
+          { "eyebrow": "NDR", "body": "121%" },
+          { "eyebrow": "Logos", "body": "+47 enterprise" }
+        ]
+      }
+    },
+    {
+      "component": "TitleAndGrid",
+      "props": {
+        "title": "Org",
+        "cols": 2,
+        "rows": 1,
+        "cells": [
+          { "eyebrow": "Headcount", "body": "180" },
+          { "eyebrow": "Hiring", "body": "12 open roles" }
+        ]
+      }
+    },
+    {
+      "component": "Quote",
+      "props": {
+        "quote": "Structure powers intelligence.",
+        "attribution": "Lars Bakker, CEO"
+      }
+    },
+    { "component": "Closing", "props": {} }
+  ]
+}
+```
+
+3. Call `slides_create` with that payload. Report the returned `filePath` to the user.
+
+## Anti-patterns
+
+- ❌ Asking the user "what color should the title be?" — the template decides.
+- ❌ Calling `slides_create` multiple times to "build the deck up" — it isn't incremental, one call writes the final file.
+- ❌ Inventing component names — only what `slides_list` returned will be accepted.
+- ❌ Stuffing prose into a `Cover.title` — keep titles short, put paragraphs in `OneColumn` or `TitleAndBody`.
+- ❌ Hiding the file path from the user once you have it. Always print the absolute path verbatim.

package/dist/cli.d.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * `slidesctl` — the CLI bin shipped with `@sanity-labs/slides`.
+ *
+ * Subcommands:
+ *
+ *   serve     --template <path-or-specifier> [--output <dir>] [--name <id>]
+ *               Start an MCP server over stdio. Exposes `slides_list`,
+ *               `slides_add_<type>`, and `slides_create` derived from the
+ *               loaded template.
+ *
+ *   generate  --template <path-or-specifier> [--output <dir>]
+ *               Read `{ title, slides: [...] }` JSON from stdin and write
+ *               the resulting `.pptx`. Prints the absolute path on stdout.
+ *
+ *   list      --template <path-or-specifier>
+ *               Print every slide type the template exposes, with
+ *               descriptions. Useful for humans inspecting a template
+ *               without an MCP client.
+ *
+ *   scaffold  <dir> [--name <slug>]
+ *               Scaffold a new template into <dir>. Replaces the old
+ *               `npm create react-pptx-template` flow.
+ *
+ *   skill     [--path]
+ *               Print the bundled `SKILL.md` to stdout (or its absolute
+ *               path with `--path`). Paste into a Claude project to teach
+ *               the model how to drive any react-pptx MCP server.
+ *
+ * The `--template` flag accepts:
+ *   - A bare package specifier resolved from the current directory
+ *     (e.g. `@acme/slide-template`).
+ *   - A path to a built JS file (`./dist/index.js`).
+ *   - A path to a directory containing `package.json` (the bin reads
+ *     `main` / `exports['.']`).
+ */
+export declare const main: (argv: readonly string[]) => Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA0UH,eAAO,MAAM,IAAI,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CA6ChE,CAAC"}