@agent-native/core 0.122.4 → 0.123.1

package/corpus/core/docs/content/template-slides-developers.mdx

@@ -0,0 +1,488 @@
+---
+title: "Slides: Developer Guide"
+description: "The Slides data model, persistence model, full action inventory, routes, and where to make common changes when forking or extending the template."
+---
+
+# Developer Guide
+
+This page is for anyone forking the Slides template or extending it: the SQL data model, how concurrent writers are kept safe, every agent-callable action, the route map, and where to make common changes.
+
+## Quick start
+
+```bash
+npx @agent-native/core@latest create my-slides --standalone --template slides
+```
+
+See [Getting started](/docs/getting-started) for the rest of the setup (`cd`, `pnpm install`, `pnpm dev`) and the framework fundamentals.
+
+## Persistence model
+
+Each deck is one JSON blob in `decks.data`. Every write goes through a server-side read-modify-write action that holds a per-deck lock, so concurrent writers — a human and the agent, or two humans — touching different slides of the same deck never overwrite each other's work.
+
+- **Agent actions** (`add-slide`, `update-slide`) use their own dedicated, granular actions and share that same lock.
+- **The browser editor** enqueues granular ops — `patch-slide`, `delete-slide`, `reorder-slides`, `add-slide`, `patch-deck-fields` — through `patch-deck` instead of a full-deck PUT.
+
+<Callout id="doc-block-slides10" tone="warning">
+
+If you're extending the editor's save path, enqueue a new op through `patch-deck`. Do not add a new full-deck PUT — that would reintroduce the last-write-wins race the lock exists to prevent.
+
+</Callout>
+
+## Data model
+
+All deck data lives in SQL via Drizzle ORM. Schema: `templates/slides/server/db/schema.ts`.
+
+<DataModel
+  id="doc-block-slides7"
+  title="Slides data model"
+  summary={
+    "A deck owns its slides as JSON in decks.data; comments, versions, shares, and design systems hang off it."
+  }
+  entities={[
+    {
+      id: "decks",
+      name: "decks",
+      note: "Slides live as JSON in data; carries ownableColumns",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+          note: "e.g. deck-1712345-abc",
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "data",
+          type: "text",
+          note: "JSON: { title, slides: [{ id, content, layout }] }",
+        },
+        {
+          name: "design_system_id",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "created_at",
+          type: "text",
+        },
+        {
+          name: "updated_at",
+          type: "text",
+        },
+      ],
+    },
+    {
+      id: "slide_comments",
+      name: "slide_comments",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "deck_id",
+          type: "text",
+          fk: "decks.id",
+        },
+        {
+          name: "slide_id",
+          type: "text",
+          note: "Slide the comment lives on",
+        },
+        {
+          name: "thread_id",
+          type: "text",
+          note: "Threading",
+        },
+        {
+          name: "parent_id",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "content",
+          type: "text",
+        },
+        {
+          name: "quoted_text",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "author_email",
+          type: "text",
+        },
+        {
+          name: "author_name",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "resolved",
+          type: "boolean",
+        },
+      ],
+    },
+    {
+      id: "deck_versions",
+      name: "deck_versions",
+      note: "Point-in-time snapshots for restore",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "deck_id",
+          type: "text",
+          fk: "decks.id",
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "data",
+          type: "text",
+          note: "Full deck JSON",
+        },
+        {
+          name: "change_label",
+          type: "text",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "design_systems",
+      name: "design_systems",
+      note: "Reusable brand tokens; ownableColumns",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "description",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "data",
+          type: "text",
+          note: "colors / typography / spacing",
+        },
+        {
+          name: "assets",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "custom_instructions",
+          type: "text",
+        },
+        {
+          name: "is_default",
+          type: "boolean",
+        },
+      ],
+    },
+    {
+      id: "deck_share_links",
+      name: "deck_share_links",
+      note: "Persisted public share-link snapshots",
+      fields: [
+        {
+          name: "token",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "slides",
+          type: "text",
+          note: "JSON slides snapshot",
+        },
+        {
+          name: "aspect_ratio",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "created_at",
+          type: "text",
+        },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "decks",
+      to: "slide_comments",
+      kind: "1-n",
+      label: "comments",
+    },
+    {
+      from: "decks",
+      to: "deck_versions",
+      kind: "1-n",
+      label: "snapshots",
+    },
+    {
+      from: "design_systems",
+      to: "decks",
+      kind: "1-n",
+      label: "applied to",
+    },
+  ]}
+/>
+
+Framework shares tables (`deck_shares`, `design_system_shares`) map principals — users or orgs — to viewer / editor / admin roles per resource, and are created via the shared `createSharesTable` helper rather than hand-written.
+
+#### Slide structure
+
+Each slide inside `decks.data` is:
+
+```json
+{
+  "id": "slide-1",
+  "layout": "title",
+  "content": "<div class=\"fmd-slide\" style=\"...\">...</div>"
+}
+```
+
+`content` is raw HTML — the renderer provides the fixed aspect ratio and background, and the HTML provides everything inside. Rich embedding is supported too: hand-drawn diagrams and live-rendered charts can live inside a slide alongside plain HTML.
+
+## Action inventory
+
+### Deck lifecycle
+
+- `create-deck` — new deck, optionally pre-populated with slides, or an atomic bulk replace of an existing deck's slides
+- `get-deck` — full deck JSON, or a compact slide-summary view
+- `list-decks` — every deck the caller can see, with light/compact/full-slide projections for cheap polling
+- `duplicate-deck` — copy a deck with fresh slide ids
+- `update-deck-aspect-ratio` — 16:9, 1:1, 9:16, or 4:5
+
+`add-deck`, `save-deck`, and `delete-deck` back the browser editor's optimistic-create, undo/redo, and delete flows — the agent uses `create-deck`, `add-slide`/`update-slide`/`patch-deck`, and the framework's own sharing actions instead.
+
+### Slide edits
+
+- `add-slide` — append (or insert at a position) one slide; how the agent builds a deck slide by slide
+- `update-slide` — surgical find/replace or full-content slide edit
+- `patch-deck` — the granular op queue the browser editor uses instead of a full-deck PUT
+
+### History
+
+- `list-deck-versions`, `get-deck-version`, `restore-deck-version` — every write snapshots first, so any point in time can be listed and restored
+
+### Comments
+
+- `list-slide-comments`, `add-slide-comment`, `update-slide-comment`, `delete-slide-comment`
+
+### Import
+
+- `import-pptx`, `import-docx`, `import-google-doc` — dedicated single-format importers
+- `import-file` — one entry point for PPTX, DOCX, or PDF, or a Figma `.fig` file (which routes into Builder design-system indexing instead of a slide import)
+- `extract-pdf` — CLI-only raw text dump of a PDF, mostly for local debugging
+
+### Export
+
+- `export-pptx` — native, editable PowerPoint
+- `export-google-slides` — generates the same PPTX plus a ready Google Slides import link
+- `export-html` — a standalone, self-contained HTML file with built-in keyboard navigation
+
+### Images
+
+- `generate-image` — agent-facing, deck-aware, and delegates to the Images app over A2A for brand-grounded generation when it's configured
+- `edit-image`, `check-image-gen`, `image-gen-status`, `search-images`, `search-logos`
+
+### Design systems
+
+- `create-design-system`, `update-design-system`, `get-design-system`, `list-design-systems`, `set-default-design-system`, `apply-design-system` (link one to a deck)
+- `analyze-brand-assets`, `import-document`, `import-from-url` — gather raw brand signals (website CSS/fonts, uploaded document metadata) for a **local**, agent-drafted design system
+- `index-design-system-with-builder`, `import-design-project` — the Builder-indexed path for Figma files, connected code/GitHub repos, and `design.md`; `import-design-project` forks from an existing design system rather than a raw source
+
+### Creative Context
+
+- `clone-context-slide` — insert one pinned Library slide into a deck unchanged, without regenerating its HTML/CSS
+- `clone-creative-context-deck` — recreate one exact governed deck version
+- Retrieval and Library submission (search, fetching a context item, managing Library membership) are shared framework actions the agent calls the same way in every app that supports Creative Context — see the `creative-context` skill for the retrieval procedure and reuse ladder.
+
+### Escalation and staged data
+
+- `provider-api-catalog`, `provider-api-docs`, `provider-api-request` — raw Google Drive API access when a canned import/export action is too narrow; Slides resolves auth from the user's connected Google Docs account
+- `list-staged-datasets`, `query-staged-dataset`, `delete-staged-dataset` — aggregate a large staged provider result without re-fetching it
+
+### Navigation and context
+
+- `view-screen` — what the user is currently looking at: open deck, current slide, and any active visual selection
+- `navigate` — move the UI to a deck, slide, or view
+
+## Routes reference
+
+| Route                  | Renders                                                                 |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `/`                    | Deck list                                                               |
+| `/deck/:id`            | The editor                                                              |
+| `/deck/:id/present`    | Full-screen presentation                                                |
+| `/p/:id`               | Public/agent-readable live deck preview — distinct from `/share/:token` |
+| `/share/:token`        | Public read-only snapshot, frozen at share time                         |
+| `/slide`               | Single-slide embed used for chat previews                               |
+| `/design-systems`      | Manage saved design systems                                             |
+| `/agent`               | Full-page Agent tab                                                     |
+| `/extensions`, `/team` | Redirect into the relevant `/settings` tab                              |
+
+## Customizing it
+
+The Slides template is fully forkable. Key places to look when extending it:
+
+#### Actions — `templates/slides/actions/`
+
+Every agent-callable operation lives here as a TypeScript file, mounted automatically at `POST /_agent-native/actions/:name` and callable from the CLI as `pnpm action <name>`. Add a new file here to give the agent a new capability.
+
+<AnnotatedCode
+  id="doc-block-slides9"
+  title="Anatomy of a slide edit action"
+  filename="actions/update-slide.ts (simplified)"
+  language="ts"
+  code={
+    'import { defineAction } from "@agent-native/core";\nimport { assertAccess } from "@agent-native/core/sharing";\nimport { eq } from "drizzle-orm";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\nimport { notifyClients } from "../server/handlers/decks.js";\nimport { withDeckLock } from "./patch-deck.js";\n\nexport default defineAction({\n  description:\n    "Surgically edit a slide\'s content using search-replace or full replacement. " +\n    "Syncs live to open editors. Prefer this over full deck rewrites.",\n  schema: z.object({\n    deckId: z.string(),\n    slideId: z.string(),\n    find: z.string().optional(),\n    replace: z.string().optional(),\n    fullContent: z.string().optional(),\n  }),\n  run: async ({ deckId, slideId, find, replace, fullContent }) => {\n    await assertAccess("deck", deckId, "editor");\n    return withDeckLock(deckId, async () => {\n      const db = getDb();\n      const [row] = await db\n        .select()\n        .from(schema.decks)\n        .where(eq(schema.decks.id, deckId));\n      if (!row) throw new Error(`Deck ${deckId} not found`);\n\n      const deck = JSON.parse(row.data);\n      const slide = deck.slides.find((s: { id: string }) => s.id === slideId);\n      if (!slide) throw new Error(`Slide ${slideId} not found`);\n\n      if (fullContent) {\n        slide.content = fullContent;\n      } else if (find) {\n        const idx = slide.content.indexOf(find);\n        if (idx === -1) return { ok: false, message: "Text not found" };\n        slide.content =\n          slide.content.slice(0, idx) +\n          (replace ?? "") +\n          slide.content.slice(idx + find.length);\n      }\n\n      deck.updatedAt = new Date().toISOString();\n      await db\n        .update(schema.decks)\n        .set({ data: JSON.stringify(deck), updatedAt: deck.updatedAt })\n        .where(eq(schema.decks.id, deckId));\n\n      notifyClients(deckId, { slideId, actor: "agent" });\n      return { ok: true, deckId, slideId };\n    });\n  },\n});'
+  }
+  annotations={[
+    {
+      lines: "22",
+      label: "Access check",
+      note: "`assertAccess` throws before anything else runs if the caller isn't at least an editor on this deck.",
+    },
+    {
+      lines: "23-29",
+      label: "Per-deck lock",
+      note: "`withDeckLock` serializes this against every other write to the same deck — `add-slide` and the browser's `patch-deck` share the same lock, so two writers touching different slides never clobber each other.",
+    },
+    {
+      lines: "35-44",
+      label: "Surgical edit",
+      note: "A `find`/`replace` pair changes only the matched text; `fullContent` swaps the whole slide. Prefer the narrower form for real edits.",
+    },
+    {
+      lines: "47-50",
+      label: "SQL is the source of truth",
+      note: "The whole deck is one JSON blob in `decks.data` — there's no separate `slides` table, so every write reads, edits, and rewrites that one column.",
+    },
+    {
+      lines: "52",
+      label: "Live sync",
+      note: "`notifyClients` pushes the change to any open editor immediately; polling is the fallback path. See [Real-Time Collaboration](/docs/real-time-collaboration).",
+    },
+  ]}
+/>
+
+The real action also records Creative Context reuse provenance and waits briefly for the editor to report a layout-overflow measurement — trimmed here to the core read-modify-write shape.
+
+#### Layout
+
+<FileTree
+  id="doc-block-slides8"
+  title="templates/slides/ shape"
+  entries={[
+    {
+      path: "actions/create-deck.ts",
+      note: "New deck, optionally pre-populated with slides, or an atomic bulk replace",
+    },
+    {
+      path: "actions/add-slide.ts",
+      note: "Append one slide; used for streaming generation",
+    },
+    {
+      path: "actions/update-slide.ts",
+      note: "Find/replace or full-content slide edit",
+    },
+    {
+      path: "actions/patch-deck.ts",
+      note: "Granular ops the browser editor uses instead of a full-deck PUT",
+    },
+    {
+      path: "actions/generate-image.ts",
+      note: "Agent-facing image generation, deck-aware, optional A2A delegation to Images",
+    },
+    {
+      path: "actions/index-design-system-with-builder.ts",
+      note: "Starts Builder design-system indexing from Figma, GitHub, or code",
+    },
+    {
+      path: "app/routes/deck.$id.tsx",
+      note: "The deck editor",
+    },
+    {
+      path: "app/routes/deck.$id_.present.tsx",
+      note: "Full-screen presentation mode",
+    },
+    {
+      path: "app/routes/agent.tsx",
+      note: "Full-page Agent tab",
+    },
+    {
+      path: "app/routes/p.$id.tsx",
+      note: "Public/agent-readable single-deck preview",
+    },
+    {
+      path: "app/routes/share.$token.tsx",
+      note: "Public read-only snapshot page",
+    },
+    {
+      path: "app/components/editor/",
+      note: "Slide canvas, toolbar, sidebar, and panels",
+    },
+    {
+      path: "server/db/schema.ts",
+      note: "decks, slide_comments, deck_versions, design_systems, deck_share_links",
+    },
+    {
+      path: ".agents/skills/create-deck/SKILL.md",
+      note: "Exact slide HTML templates for every layout",
+    },
+    {
+      path: ".agents/skills/creative-context/SKILL.md",
+      note: "The reuse ladder and retrieval procedure",
+    },
+  ]}
+/>
+
+Most editor UI customization happens under `app/components/editor/`: the slide canvas, toolbar, sidebar, bubble menu, slash menu, and the panels for image generation, search, and history.
+
+#### Skills — `templates/slides/.agents/skills/`
+
+Agent skills that explain patterns when the agent needs to modify code:
+
+- `create-deck` — how to create a new deck, with exact slide HTML templates for every layout
+- `slide-editing` — how to edit individual slides
+- `deck-management` — how decks are stored and accessed
+- `slide-images`, `image-generation-via-a2a` — image generation and search
+- `design-systems` — design-system data shape and how tokens apply to generated slides
+- `creative-context` — the reuse ladder, retrieval procedure, and Library submission
+
+#### AGENTS.md
+
+`templates/slides/AGENTS.md` is the short router the agent reads on every conversation. It points at the skills under `.agents/skills/` and lays out the core rules, persistence model, and application-state contract. Update the relevant skill whenever you add or change a slide layout, image path, or design-system source.
+
+## What's next
+
+- [**Generating & Editing Decks**](/docs/template-slides-editing) — the user-facing editing, presenting, and sharing flow
+- [**Design Systems & Media**](/docs/template-slides-design-and-media) — the design-system and import/export flow this data model backs
+- [**Talking to the Agent & Creative Context**](/docs/template-slides-agent) — the reuse ladder these actions implement
+- [**Sharing**](/docs/sharing) — the share-grant model `deck_shares` and `design_system_shares` build on
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — the Yjs pipeline decks share with other collaborative surfaces
+- [**Slides overview**](/docs/template-slides) — back to the app summary

package/corpus/core/docs/content/template-slides-editing.mdx

@@ -0,0 +1,56 @@
+---
+title: "Slides: Generating & Editing Decks"
+description: "Generate a deck from a prompt, edit it slide by slide, choose an aspect ratio, present full-screen, and collaborate with comments and version history."
+---
+
+# Generating & Editing Decks
+
+This page covers day-to-day deck work in [Slides](/docs/template-slides): generating a deck from a prompt, editing it slide by slide, presenting it, and collaborating with comments and version history. It's written for anyone using Slides, not just developers.
+
+## Generating a deck from a prompt
+
+Ask for a deck the way you'd brief a person: "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors." The agent plans the slides first, then builds the deck one slide at a time so you watch it appear in the editor rather than waiting for the whole thing to land at once. Keep refining in the same conversation — "add a pricing slide after slide 3," "make this section shorter" — and only the slides you asked about change.
+
+Every new deck defaults to a 16:9 widescreen canvas. Ask the agent to switch it to 1:1 (square), 9:16 (vertical — Stories-style), or 4:5 (portrait) when you need a different shape. Changing it updates the editor canvas, presentation mode, and PDF/PPTX export together, so you never end up with an export that doesn't match what you built.
+
+## Editing slides visually
+
+- **Inline text editing.** Double-click any text to edit it directly on the slide.
+- **The bubble menu.** Click a block — a heading, a bullet list, an image — to get quick formatting options for just that block.
+- **The slash menu.** Type `/` to insert a new block — a heading, bullets, a table, a code block, an image placeholder — without leaving the keyboard.
+- **Reordering.** Drag slides in the filmstrip to reorder them; undo and redo work the way you'd expect.
+- **Rich embeds.** A slide can hold a hand-drawn diagram or a live-rendered chart alongside your text and images, not just static HTML.
+
+Select text on a slide and hit `Cmd+I` to hand the agent that exact selection — see [Talking to the Agent & Creative Context](/docs/template-slides-agent) for how selection-aware edits work.
+
+## Presenting full-screen
+
+<WireframeBlock id="doc-block-slides3">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='background:#0a0a0a;min-height:520px;display:flex;flex-direction:column;box-sizing:border-box;border-radius:8px;overflow:hidden;position:relative'><div style='flex:1;display:flex;align-items:center;justify-content:center;color:#fff;text-align:center;padding:40px'><div><div style='font-size:12px;letter-spacing:3px;text-transform:uppercase;color:#00E5FF;margin-bottom:18px'>Roadmap</div><h1 style='margin:0;font-size:36px'>Three Core Priorities</h1><p style='margin:14px 0 0;color:rgba(255,255,255,0.5)'>Speaker notes visible only to you</p></div></div><div style='display:flex;align-items:center;justify-content:space-between;padding:10px 18px;background:rgba(255,255,255,0.06);color:rgba(255,255,255,0.6);font-size:12px'><span>4 / 10</span><span style='display:flex;gap:14px'><span>&larr; &rarr; navigate</span><span>F fullscreen</span><span>Esc exit</span></span></div></div>"
+    }
+  />
+</WireframeBlock>
+
+Click **Present** to go full-screen, with the arrow keys (or space bar) to advance, controls that fade out until you move the mouse, and your speaker notes visible only to you. Press `F` to toggle fullscreen and `Esc` to exit.
+
+## Comments and real-time collaboration
+
+Anyone with edit access can leave a comment anchored to a specific slide — optionally quoting the exact text or element it's about — and reply in a thread. Resolve a thread once it's addressed. Multiple people (and the agent) can edit the same deck at the same time without clobbering each other's changes; see [Real-Time Collaboration](/docs/real-time-collaboration) for how that works under the hood.
+
+## Sharing a deck
+
+Share a deck the same way you'd share any Agent-Native resource: keep it private, share it with specific teammates as a viewer or editor, or generate a public read-only link anyone can open without an account. See [Sharing](/docs/sharing) for the full model.
+
+## Restoring an earlier version
+
+Every meaningful change — yours or the agent's — snapshots the deck first, so nothing is ever silently lost. Open version history to see a timeline of past snapshots and restore any one of them; restoring takes its own snapshot first too, so a restore is never a dead end.
+
+## What's next
+
+- [**Design Systems & Media**](/docs/template-slides-design-and-media) — brand tokens, images, and import/export
+- [**Talking to the Agent & Creative Context**](/docs/template-slides-agent) — prompts by task and selection-aware edits
+- [**Developer Guide**](/docs/template-slides-developers) — the deck, slide, comment, and version actions behind this page
+- [**Slides overview**](/docs/template-slides) — back to the app summary