hono-decks 0.2.2 → 0.3.1

package/README.ja.md

@@ -12,6 +12,8 @@ bunx hono-decks init
 bunx hono-decks compile
 ```
 
+AI agent を使う場合は `npx @tanstack/intent@latest install` を実行してください。公開パッケージには、agent が `node_modules` から検出できるバージョン付きの hono-decks Skill が含まれます。
+
 `init` は次の2ファイルを作ります。既存ファイルは上書きしません。
 
 - `hono-decks.config.ts`: CLI と runtime が共有する唯一の設定

package/README.md

@@ -14,6 +14,8 @@ bunx hono-decks init
 bunx hono-decks compile
 ~~~
 
+If you use an AI agent, run `npx @tanstack/intent@latest install`. The published package includes a versioned hono-decks skill that the agent can discover from `node_modules`.
+
 <code>init</code> creates two files without overwriting existing files:
 
 - <code>hono-decks.config.ts</code>: the shared configuration for the CLI and runtime

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "hono-decks",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Slide decks for Hono and Cloudflare Workers",
   "keywords": [
     "cloudflare-workers",
     "hono",
     "mdx",
-    "slides"
+    "slides",
+    "tanstack-intent"
   ],
   "homepage": "https://github.com/ts-76/hono-decks#readme",
   "bugs": {
@@ -25,7 +26,8 @@
   "files": [
     "dist",
     "README.md",
-    "README.ja.md"
+    "README.ja.md",
+    "skills"
   ],
   "type": "module",
   "sideEffects": false,
@@ -62,9 +64,11 @@
     "build": "tsdown",
     "prepack": "bun run build",
     "decks:compile": "bun run build && node dist/bin.js compile",
+    "skills:validate": "intent validate skills",
+    "skills:stale": "intent stale .",
     "typecheck": "bun run build && tsc --noEmit && tsc --noEmit -p tsconfig.worker.json",
     "test": "bun run build && vp test run",
-    "check": "bun run typecheck && bun run test"
+    "check": "bun run typecheck && bun run test && bun run skills:validate"
   },
   "dependencies": {
     "@mdx-js/mdx": "^3.1.1",
@@ -77,6 +81,7 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
+    "@tanstack/intent": "^0.3.6",
     "hono": "^4.12.30",
     "vite": "catalog:",
     "vite-plus": "catalog:",

package/skills/hono-decks/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: hono-decks
+description: >
+  Create, style, integrate, and troubleshoot hono-decks presentations in Hono and Cloudflare Workers. Load for installation, deck.mdx and frontmatter authoring, Fire reveals, theme.css, generated createDecks modules, Hono routing, Vite or Wrangler builds, R2 assets, PDF or PNG export, OGP generation, embeds, or custom DeckSource pipelines.
+---
+
+# hono-decks
+
+Use this skill as a router. Inspect the application and the request, then read only the relevant reference files before editing. Combine routes when a request spans topics.
+
+## Route the request
+
+| User intent | Read |
+| --- | --- |
+| Install, initialize, first deck, compile failure | [Getting started](references/getting-started.md) |
+| Write or fix `deck.mdx`, frontmatter, Markdown, MDX, Fire, embeds, components, notes | [Authoring MDX](references/authoring-mdx.md) |
+| Create or improve `theme.css`, layout, typography, visual quality, overflow | [Styling](references/styling.md) |
+| Add to an existing Hono, HonoX, Vite, Wrangler, or Worker app; configure routes, presenter, or external embed | [Integrating](references/integrating.md) |
+| Serve deck images or other local assets from R2 | [R2 assets](references/r2-assets.md) plus [Integrating](references/integrating.md) |
+| Generate PDF or PNG with Cloudflare Browser Rendering | [Browser export](references/browser-export.md) plus [Integrating](references/integrating.md) |
+| Generate OGP/social images | [OGP generation](references/ogp-generation.md) |
+| Use a manifest, database, remote store, custom `DeckSource`, or low-level router | [Custom sources](references/custom-sources.md) |
+
+If the request is simply “make a deck,” read Authoring MDX and Styling. If it also asks to put the deck in an application, read Integrating. Do not load the advanced references unless the request or inspected code needs them.
+
+## Non-negotiable architecture
+
+1. Compile MDX with Node.js or Bun at build time.
+2. Import generated TypeScript modules in the Worker runtime.
+3. Keep `hono-decks.config.ts` as the single mount-path and build configuration.
+4. Mount with `app.route(decks.mountPath, decks.router())` and obtain URLs from `decks.paths(slug)` or `meta.paths`.
+5. Edit source decks, deck-local components, assets, and themes. Never hand-edit the generated output directory.
+
+## Authoring and design defaults
+
+- hono-decks is not Slidev. Never generate `v-click`, Slidev frontmatter, or UnoCSS utility classes unless the application independently installed and configured those features.
+- Use supported `:::fire` blocks or block-level custom components with `fire`; reveals follow source order.
+- Design for the fixed 1920 × 1080, 16:9 canvas. Responsive slide layouts are not required.
+- Keep body text presentation-sized (the base root size is 32px), preserve strong contrast, and keep every slide inside the canvas.
+- Prefer one idea per slide. Split dense content instead of shrinking text or relying on hidden overflow.
+- Preserve print behavior and respect `prefers-reduced-motion` for custom animation.
+
+## Common mistakes
+
+### Editing generated modules
+
+Wrong:
+
+```ts
+// src/generated/decks.ts
+// Hand-edit the generated manifest or routes.
+```
+
+Correct: edit `decks/product/deck.mdx`, `theme.css`, assets, or components, then run `bunx hono-decks compile`.
+
+### Compiling inside the Worker
+
+Wrong:
+
+```ts
+import { compileDecks } from "hono-decks/node";
+
+app.get("/decks", async (c) => c.json(await compileDecks({ cwd: "." })));
+```
+
+Correct:
+
+```ts
+import { decks } from "./decks";
+
+app.route(decks.mountPath, decks.router());
+```
+
+### Duplicating route strings
+
+Wrong:
+
+```ts
+app.route("/slides", decks.router());
+const presenter = `/decks/${slug}/presenter`;
+```
+
+Correct:
+
+```ts
+app.route(decks.mountPath, decks.router());
+const presenter = decks.paths(slug).presenter;
+```
+
+### Passing executable values to client islands
+
+Wrong:
+
+```mdx
+<Counter onChange={() => save()} startedAt={new Date()} />
+```
+
+Correct:
+
+```mdx
+<Counter label="Votes" initial={3} />
+```
+
+Keep event handlers, dates, class instances, and component state inside `components/client/index.tsx`; island props must be JSON-serializable.
+
+### Using unsupported Fire forms
+
+Wrong:
+
+```mdx
+<p fire="fade-up">Reveal me</p>
+<Fire order={2}>Later</Fire>
+```
+
+Correct:
+
+```mdx
+:::fire{effect="fade-up"}
+Reveal me
+:::
+
+<Chart fire="scale" at="+1" />
+```
+
+### Treating iframe embedding as CORS
+
+Wrong: add `Access-Control-Allow-Origin` and leave `router.embed` without a parent policy.
+
+Correct:
+
+```ts
+router: {
+  embed: { frameAncestors: ["https://blog.example.com"] },
+}
+```
+
+Iframe navigation uses CSP `frame-ancestors`, not CORS.
+
+### Publishing unprotected browser exports
+
+Wrong:
+
+```ts
+export: {
+  browser: ({ c }) => c.env.BROWSER,
+  pdf: true,
+}
+```
+
+Correct: add an `authorize` resolver backed by a Wrangler secret. Export authorization defaults to allowed when the resolver is absent.
+
+### Generating Slidev or UnoCSS syntax
+
+Wrong:
+
+```mdx
+<div v-click class="grid grid-cols-2 gap-4">Content</div>
+```
+
+Correct: use `:::fire` and define project-specific classes explicitly in `theme.css`.
+
+## Verification
+
+After changes:
+
+1. Run `hono-decks compile` through the application's package manager.
+2. Run the application's typecheck and tests.
+3. Open the viewer and check every slide at 16:9 for readable text and overflow.
+4. Check presentation, presenter, print, embed, export, or OGP routes that the change affects.
+5. Verify production policies for drafts, presenter access, CSP `frame-ancestors`, and export authorization.

package/skills/hono-decks/references/authoring-mdx.md

@@ -0,0 +1,200 @@
+# Authoring MDX
+
+Use this route when writing or correcting a `deck.mdx` file. Start with the basic syntax, then load the advanced sections only when the requested deck needs them.
+
+## Basic deck structure
+
+The first frontmatter block describes the deck. Each following `---` boundary starts a slide; a slide may immediately include its own frontmatter.
+
+```mdx
+---
+title: Product update
+description: What changed and why it matters
+author: Product team
+date: 2026-07-17
+tags: [product, engineering]
+theme: default
+transition: fade
+transitionDuration: 300ms
+transitionEasing: ease-out
+draft: false
+presenter: true
+---
+
+---
+title: Opening
+layout: cover
+class: opening-slide
+background: "#0b1020"
+---
+
+# Product update
+
+One clear sentence that frames the talk.
+
+{/* Introduce the customer problem before the feature. */}
+
+---
+title: Outcomes
+layout: default
+transition: slide-left
+---
+
+## Outcomes
+
+- Faster setup
+- Fewer production surprises
+- Clearer ownership
+```
+
+Deck frontmatter supports `title`, `description`, `author`, `date`, `tags`, `theme`, `transition`, `transitionDuration`, `transitionEasing`, `assets`, `draft`, and `presenter`.
+
+Slide frontmatter supports `title`, `layout`, `class`, `notes`, `background`, `transition`, `transitionDuration`, and `transitionEasing`. Unknown keys are preserved in `meta` and produce a compile warning.
+
+Supported transitions are `none`, `fade`, `fade-out`, `slide-left`, `slide-right`, `slide-up`, `slide-down`, and `view-transition`.
+
+## Markdown and MDX basics
+
+Use headings, paragraphs, emphasis, links, images, blockquotes, ordered and unordered lists, task lists, tables, inline code, and fenced code. GFM is enabled.
+
+~~~mdx
+## Release checklist
+
+- [x] Compile the deck
+- [ ] Verify the print route
+
+| Surface | Path |
+| --- | --- |
+| Viewer | `/decks/product` |
+| Presenter | `/decks/product/presenter` |
+
+```ts
+app.route(decks.mountPath, decks.router())
+```
+
+![Architecture](./assets/architecture.svg)
+~~~
+
+Local image paths are rewritten during compilation. Put deck-local files under `assets/` and use relative paths.
+
+MDX exports, expressions, and JSX are supported:
+
+```mdx
+export const release = "2026.07"
+export const metrics = ["42% faster", "3 fewer steps"]
+
+## Release {release}
+
+{metrics.map((metric) => <Badge label={metric} />)}
+```
+
+## Speaker notes
+
+Use the slide `notes` frontmatter field or MDX comments. Comments are removed from visible slide output and collected as presenter notes.
+
+```mdx
+---
+notes: |
+  Pause after the headline.
+  Explain the build/runtime boundary.
+---
+
+## Compile once, serve everywhere
+
+{/* Open the presenter route before the live demo. */}
+```
+
+## Built-in components
+
+- `<Hero>`: `title`, `subtitle` or `description`, `eyebrow`, `image` or `src`, and `featured`
+- `<CodeBlock>`: `lang`, `filename` or `title`, and `highlight`
+- `<EmbedFrame>`: iframe with sandbox, fallback, and print behavior
+- `<SocialEmbed>`, `<TweetEmbed>`, and `<LinkCard>`: social and link surfaces
+- `<Fire>`: explicit reveal wrapper; prefer the Markdown directive for ordinary prose
+
+```mdx
+<Hero
+  eyebrow="Architecture"
+  title="Build-time MDX"
+  subtitle="Generated modules run on the Worker"
+  image="./assets/pipeline.svg"
+/>
+
+<CodeBlock lang="ts" filename="src/index.ts" highlight="4">
+import { Hono } from "hono";
+import { decks } from "./decks";
+
+const app = new Hono();
+app.route(decks.mountPath, decks.router());
+</CodeBlock>
+```
+
+## Fire reveals
+
+Markdown content uses a container directive:
+
+```mdx
+:::fire{effect="fade-up"}
+This appears on the next reveal step.
+:::
+```
+
+Lists can reveal items in source order:
+
+```mdx
+:::fire{each="item" depth="2" every="1"}
+- First point
+  - Nested detail
+- Second point
+:::
+```
+
+Block-level custom components may use `fire` and `at`:
+
+```mdx
+<MetricCard fire="scale" at="+1" label="Activation" value="42%" />
+```
+
+`at` accepts a non-negative integer or a relative value such as `+1`. Do not use `$fire`, `order`, `v-click`, or `fire` on HTML elements or inline custom components.
+
+## Embeds and link cards
+
+```mdx
+@[youtube](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
+
+@[x](https://x.com/honojs/status/1659577874821836801)
+
+@[card](https://hono.dev/)
+
+@[embed](https://example.com/embed/status)
+```
+
+`@[card]` metadata is resolved at compile time when available. `build.ogpCacheFile` stores that external metadata cache; it is not the deck's social share image.
+
+## Deck-local components
+
+Use this structure:
+
+```text
+decks/product/
+  deck.mdx
+  theme.css
+  assets/
+    diagram.svg
+  components/
+    index.tsx
+    client/
+      index.tsx
+```
+
+`components/index.tsx` contains server-rendered Hono JSX components. Mark a component as client-enabled in the server registry and export its browser implementation with the same name from `components/client/index.tsx`.
+
+Client props may contain only strings, finite numbers, booleans, `null`, arrays, and plain objects composed from those values. Keep callbacks and interactive state in the client component.
+
+## Authoring quality check
+
+- Use a short title and one primary idea per slide.
+- Keep visible body copy sparse enough for a 32px base size.
+- Split long lists, large tables, and multi-screen code into multiple slides.
+- Add useful alt text to images and titles to embeds.
+- Compile after syntax changes and resolve all warnings instead of hiding them.

package/skills/hono-decks/references/browser-export.md

@@ -0,0 +1,84 @@
+# PDF and PNG browser export
+
+Use this route only when the request explicitly asks for server-side PDF or PNG generation with Cloudflare Browser Rendering.
+
+Browser export renders the deck print route. The export endpoint is a billable production capability, so always configure authorization.
+
+## Configure bindings and secrets
+
+Declare the Browser Rendering binding in the application's Wrangler config and store the token as a secret:
+
+```bash
+wrangler secret put DECK_EXPORT_TOKEN
+```
+
+Use the binding shape generated by the application's current Wrangler version. Regenerate types with `wrangler types`.
+
+## Configure export
+
+```ts
+// hono-decks.config.ts
+import {
+  defineDecksConfig,
+  type DeckBrowserRunBinding,
+} from "hono-decks";
+
+interface Env {
+  Bindings: {
+    BROWSER?: DeckBrowserRunBinding;
+    DECK_EXPORT_TOKEN?: string;
+  };
+}
+
+export default defineDecksConfig<Env>({
+  mountPath: "/decks",
+  build: {
+    root: "decks",
+    outDir: "src/generated",
+  },
+  router: {
+    export: {
+      authorize: ({ c }) => {
+        const token = c.env.DECK_EXPORT_TOKEN;
+        const authorization = c.req.header("authorization");
+        const provided = authorization?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim();
+        return typeof token === "string" && token.length > 0 && provided === token;
+      },
+      browser: ({ c }) => c.env.BROWSER,
+      pdf: {
+        filename: (deck) => `${deck.slug}-slides`,
+      },
+      png: {
+        filename: (deck) => `${deck.slug}-slides`,
+      },
+    },
+  },
+});
+```
+
+The endpoints are available from `decks.paths(slug).exportPdf` and `decks.paths(slug).exportPng`. Export controls are shown only when that request is authorized.
+
+## Request an export
+
+```bash
+curl \
+  -H "Authorization: Bearer $DECK_EXPORT_TOKEN" \
+  -o product.pdf \
+  https://slides.example.com/decks/product/export.pdf
+```
+
+Use an environment variable supplied by the caller; never commit a token or put it in Wrangler `vars`.
+
+## CSP and network checks
+
+Browser Rendering must be able to load the absolute print URL and every font, image, stylesheet, and embedded fallback it needs. Review CSP and authentication middleware on the print route. Interactive iframes are replaced by print fallbacks, so provide useful fallback links or posters.
+
+## Verification
+
+- no token, empty token, and incorrect token return 403
+- missing Browser binding returns 503 without exposing internals
+- authorized PDF has `application/pdf` and a safe attachment filename
+- authorized PNG has `image/png` and a safe attachment filename
+- draft decks remain unavailable outside development
+- every slide appears in print order with backgrounds and local assets
+- exported pages contain no clipped content; fix the deck rather than increasing the browser viewport to hide overflow

package/skills/hono-decks/references/custom-sources.md

@@ -0,0 +1,95 @@
+# Custom sources and low-level APIs
+
+Use this route only when the request needs an existing manifest, database, remote object store, custom `DeckSource`, or a router pipeline that the generated `createDecks(config)` kit cannot express.
+
+For normal file-based decks, stay with `hono-decks init`, generated modules, and `createDecks(config)`.
+
+## Custom DeckSource
+
+A source lists deck summaries, returns compiled decks, and optionally serves assets:
+
+```ts
+import type {
+  CompiledDeck,
+  DeckEntry,
+  DeckSource,
+} from "hono-decks";
+
+export function databaseDeckSource(input: {
+  list(): Promise<DeckEntry[]>;
+  find(slug: string): Promise<CompiledDeck | null>;
+}): DeckSource {
+  return {
+    async listDecks() {
+      return input.list();
+    },
+    async getCompiledDeck(_c, slug) {
+      return input.find(slug);
+    },
+  };
+}
+```
+
+Compiled data must satisfy the public `CompiledDeck` model. Do not send raw MDX to the Worker and invoke the Node compiler per request.
+
+## Decorate generated data
+
+If only asset lookup, visibility, metadata, or caching changes, prefer `config.source(source)` over replacing the entire generated flow:
+
+```ts
+import { defineDecksConfig, type DeckSource } from "hono-decks";
+
+export default defineDecksConfig({
+  mountPath: "/decks",
+  source(source: DeckSource): DeckSource {
+    return {
+      async listDecks(c) {
+        return (await source.listDecks(c)).filter((deck) => !deck.draft);
+      },
+      getCompiledDeck: (c, slug) => source.getCompiledDeck(c, slug),
+      getAsset: (c, slug, assetPath) => source.getAsset?.(c, slug, assetPath) ?? Promise.resolve(null),
+    };
+  },
+});
+```
+
+## Assemble a low-level router
+
+```ts
+import { Hono } from "hono";
+import {
+  decksRouter,
+  manifestDeckSource,
+  type DeckManifest,
+} from "hono-decks/advanced";
+
+export function createInternalSlides(manifest: DeckManifest) {
+  const app = new Hono();
+  const source = manifestDeckSource(manifest);
+
+  app.route(
+    "/internal-slides",
+    decksRouter({
+      source,
+      dev: false,
+      presenter: false,
+      embed: false,
+      export: false,
+    }),
+  );
+
+  return app;
+}
+```
+
+At this level the application owns the mount path, option merging, source policy, draft behavior, and security. Use `createDeckPaths(mountPath, slug)` whenever low-level code needs a route map.
+
+## Boundary checks
+
+- compile or validate raw MDX before deployment, outside the Worker
+- return 404 for missing or unauthorized decks without leaking their existence
+- keep asset paths normalized and prevent traversal into unrelated objects
+- keep `listDecks` and `getCompiledDeck` visibility policies consistent
+- preserve JSON-serializable client-island props in custom compiled data
+- explicitly configure presenter, embed CSP, and export authorization when enabling those surfaces
+- add contract tests for every custom source method and route surface

package/skills/hono-decks/references/getting-started.md

@@ -0,0 +1,123 @@
+# Getting started
+
+Use this route for installation, initialization, a first deck, or a failed initial compile.
+
+## Inspect before changing
+
+Identify the package manager, application entry point, Hono environment type, build tool, Wrangler config format, and existing Vite plugins. Preserve the application's established structure and scripts.
+
+## Install and initialize
+
+```bash
+bun add hono hono-decks
+bunx hono-decks init
+```
+
+`init` creates these files without overwriting existing files:
+
+- `hono-decks.config.ts`: shared build and runtime configuration
+- `src/decks.ts`: editable facade around generated modules
+
+Use the equivalent `npm`, `pnpm`, or Yarn commands when the repository does not use Bun.
+
+## Configure once
+
+```ts
+// hono-decks.config.ts
+import { defineDecksConfig } from "hono-decks";
+
+export default defineDecksConfig({
+  mountPath: "/decks",
+  build: {
+    root: "decks",
+    outDir: "src/generated",
+  },
+});
+```
+
+```ts
+// src/decks.ts
+import config from "../hono-decks.config";
+import { createDecks } from "./generated/decks";
+
+export const decks = createDecks(config);
+```
+
+Create `decks/welcome/deck.mdx`:
+
+```mdx
+---
+title: Welcome
+description: My first hono-decks presentation
+---
+
+---
+layout: cover
+---
+
+# Welcome
+
+MDX slides served by Hono.
+
+---
+layout: default
+---
+
+## Build-time compilation
+
+- Author in `decks/`
+- Compile to `src/generated/`
+- Serve generated modules from Hono
+```
+
+Compile and mount it:
+
+```bash
+bunx hono-decks compile
+```
+
+```ts
+// src/index.ts
+import { Hono } from "hono";
+import { decks } from "./decks";
+
+const app = new Hono();
+
+app.get("/", (c) => c.redirect(decks.paths("welcome").viewer));
+app.route(decks.mountPath, decks.router());
+
+export default app;
+```
+
+## Add compilation to development
+
+For a Wrangler Worker, use the existing JSONC config:
+
+```jsonc
+{
+  "build": {
+    "command": "hono-decks compile",
+    "watch_dir": ["decks"]
+  }
+}
+```
+
+For Vite or HonoX, add the plugin to the existing plugin array:
+
+```ts
+import { honoDecks } from "hono-decks/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [honoDecks()],
+});
+```
+
+## Diagnose setup failures
+
+- Missing config: run `hono-decks init` or create a default-exported `hono-decks.config.ts`.
+- Missing generated import: run `hono-decks compile` before typechecking the application.
+- Deck not discovered: use `decks/<slug>/deck.mdx` or a supported single-file deck in the configured root.
+- Broken routes or assets: remove duplicated strings and use `decks.mountPath` and `decks.paths(slug)`.
+- Worker bundling Node modules: import `hono-decks/node` only from build scripts, never from Worker runtime code.
+- Lost edits after compile: move changes out of `src/generated` and into source decks or configuration.

package/skills/hono-decks/references/integrating.md

@@ -0,0 +1,146 @@
+# Integrating with an application
+
+Use this route when adding hono-decks to an existing Hono, HonoX, Vite, Wrangler, or Cloudflare Workers application, or when configuring application routes, presenter access, or external embedding.
+
+## Preserve the build/runtime boundary
+
+The compiler and `hono-decks/node` use Node filesystem tooling. Run them in a build command. Worker runtime code imports the generated facade and root package only.
+
+```ts
+// src/decks.ts
+import config from "../hono-decks.config";
+import { createDecks } from "./generated/decks";
+
+export const decks = createDecks(config);
+```
+
+```ts
+// src/index.ts
+import { Hono } from "hono";
+import { decks } from "./decks";
+
+const app = new Hono();
+
+app.route(decks.mountPath, decks.router());
+
+export default app;
+```
+
+## Use the configured kit
+
+- `decks.mountPath`: normalized path for `app.route`
+- `decks.source`: configured `DeckSource`
+- `decks.router(overrides?)`: built-in viewer, renderer, presenter, embed, export, and asset routes
+- `decks.context(overrides?)`: middleware for application-owned deck routes
+- `decks.paths(slug)`: viewer, render, print, presentation, presenter, embed, PDF, PNG, OGP, and asset paths
+
+Never rebuild these paths with string concatenation.
+
+## Existing Wrangler application
+
+Merge this into the existing `wrangler.jsonc`:
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-07-14",
+  "build": {
+    "command": "hono-decks compile",
+    "watch_dir": ["decks"]
+  }
+}
+```
+
+Keep other bindings, assets, routes, and compatibility flags intact. Run `wrangler types` after changing bindings.
+
+## Existing Vite or HonoX application
+
+Add the plugin to the existing config rather than replacing other plugins:
+
+```ts
+import { honoDecks } from "hono-decks/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [honoDecks()],
+});
+```
+
+For HonoX, mount the router from a HonoX route module while keeping the generated facade outside the route tree. Follow the application's established catch-all route convention.
+
+## Application-owned routes
+
+Use `decks.context()` to share deck lookup, draft policy, paths, and viewer configuration:
+
+```ts
+import { Hono } from "hono";
+import type { DeckContextVariables } from "hono-decks";
+import { decks } from "./decks";
+
+const app = new Hono<{ Variables: DeckContextVariables }>();
+
+app.get(
+  `${decks.mountPath}/:slug/about`,
+  decks.context(),
+  (c) => c.json({
+    title: c.var.deckMeta.title,
+    viewer: c.var.deckMeta.paths.viewer,
+    slides: c.var.deckToc,
+  }),
+);
+
+app.route(decks.mountPath, decks.router());
+```
+
+Register more specific application routes before the mounted deck router.
+
+## Presenter policy
+
+Presenter view can contain notes and previews. Enable it intentionally:
+
+```ts
+router: {
+  presenter: {
+    enabled: ({ dev }) => dev,
+    viewerControl: true,
+  },
+}
+```
+
+For production, replace the development condition with application authentication or a trusted binding policy.
+
+## External iframe embedding
+
+Enable the embed route and explicitly list allowed parent origins:
+
+```ts
+router: {
+  embed: {
+    frameAncestors: ["https://blog.example.com"],
+    robots: false,
+  },
+}
+```
+
+```html
+<iframe
+  src="https://slides.example.com/decks/product/embed"
+  title="Product deck"
+  allow="fullscreen"
+></iframe>
+```
+
+The response writes CSP `frame-ancestors` and removes conflicting `X-Frame-Options`. Invalid origins do not widen access. Do not use CORS headers to solve iframe permission.
+
+Review any application-wide CSP middleware after mounting: it must preserve the embed response's `frame-ancestors` directive and allow the scripts, styles, images, frames, and fonts actually used by the deck.
+
+## Integration verification
+
+- Start the normal application dev command and confirm MDX changes recompile.
+- Verify direct navigation and application links use `decks.paths`.
+- Confirm draft decks are unavailable outside development.
+- Test application-owned routes before the deck router catch-all.
+- Check presenter notes are not exposed by an unintended production policy.
+- Test the external embed from an allowed and a disallowed parent origin.
+- Run the deployment dry run so Worker-only bundling errors are caught before publish.

package/skills/hono-decks/references/ogp-generation.md

@@ -0,0 +1,85 @@
+# OGP and social image generation
+
+Use this route when the request explicitly asks to generate Open Graph or social sharing images.
+
+hono-decks exposes OGP paths and metadata but intentionally does not bundle an image renderer. Generate 1200 × 630 PNGs at build time and serve them from Workers Static Assets or another application-owned asset pipeline.
+
+## Enable viewer metadata
+
+```ts
+// hono-decks.config.ts
+import { defineDecksConfig } from "hono-decks";
+
+export default defineDecksConfig({
+  mountPath: "/decks",
+  build: {
+    root: "decks",
+    outDir: "src/generated",
+  },
+  router: {
+    viewer: {
+      openGraph: true,
+    },
+  },
+});
+```
+
+The default image URL is `decks.paths(slug).ogImage`. The viewer turns it into an absolute Open Graph and Twitter Card URL from the request origin.
+
+## Build-time pipeline
+
+Use `compileDecks()` from `hono-decks/node`, then generate one image for each non-draft manifest entry:
+
+```ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createDeckPaths } from "hono-decks";
+import { compileDecks } from "hono-decks/node";
+import config from "../hono-decks.config";
+import { renderOgpCard } from "./ogp-card";
+
+const cwd = process.cwd();
+const manifest = await compileDecks({
+  cwd,
+  root: config.build?.root ?? "decks",
+  out: config.build?.outDir ?? "src/generated",
+  mountPath: config.mountPath,
+  ogpCacheFile: config.build?.ogpCacheFile,
+});
+
+for (const deck of manifest.decks) {
+  if (deck.meta.draft) continue;
+  const paths = createDeckPaths(config.mountPath, deck.slug);
+  const png = await renderOgpCard({
+    title: deck.meta.title ?? deck.slug,
+    description: deck.meta.description,
+    author: deck.meta.author,
+    path: paths.viewer,
+  });
+  const output = join(cwd, "public", paths.ogImage.replace(/^\//, ""));
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, png);
+}
+```
+
+Implement `renderOgpCard` with application-selected tooling such as Satori plus resvg. Keep those dependencies in the application, not the hono-decks runtime bundle.
+
+Satori accepts TTF, OTF, and WOFF fonts, but not WOFF2. Bundle fonts that cover every language used in deck metadata; builds should not depend on fetching remote fonts.
+
+## Separate concepts
+
+- `router.viewer.openGraph`: emits social metadata for the viewer
+- `decks.paths(slug).ogImage`: canonical image output/serving path
+- `build.ogpCacheFile`: caches external page metadata for `@[card](...)`; it does not generate the deck share image
+
+## Verification
+
+- generate only non-draft decks
+- output exactly 1200 × 630 PNG files
+- avoid rewriting unchanged bytes so local watchers do not loop
+- verify the viewer emits absolute `og:image` and Twitter Card metadata
+- request the generated image path from the deployed asset setup
+- use an `imagePath` resolver when images live on a separate CDN
+- ensure titles, descriptions, and fonts fit languages with wider glyphs
+
+The repository's `examples/ogp` directory is the canonical complete recipe.

package/skills/hono-decks/references/r2-assets.md

@@ -0,0 +1,77 @@
+# R2-backed assets
+
+Use this route only when the request explicitly asks to serve deck-local images or other assets from Cloudflare R2.
+
+Compilation still discovers and rewrites local asset URLs. `withR2Assets` decorates the generated source so requests prefer R2 and fall back to the original embedded asset source.
+
+## Configure a binding
+
+```jsonc
+{
+  "r2_buckets": [
+    {
+      "binding": "DECK_ASSETS",
+      "bucket_name": "production-deck-assets"
+    }
+  ]
+}
+```
+
+Generate binding types with `wrangler types`.
+
+## Decorate the source
+
+```ts
+// hono-decks.config.ts
+import {
+  defineDecksConfig,
+  withR2Assets,
+  type DeckSource,
+  type R2BucketLike,
+} from "hono-decks";
+
+interface Env {
+  Bindings: {
+    DECK_ASSETS?: R2BucketLike;
+  };
+}
+
+export default defineDecksConfig<Env>({
+  mountPath: "/decks",
+  build: {
+    root: "decks",
+    outDir: "src/generated",
+  },
+  source(source: DeckSource<Env>) {
+    return withR2Assets(source, {
+      bucket: (c) => c.env.DECK_ASSETS,
+      keyPrefix: "slides",
+      cacheControl: "public, max-age=31536000, immutable",
+    });
+  },
+});
+```
+
+By default the R2 key comes from the compiled asset's source path, optionally prefixed by `keyPrefix`. If the upload pipeline uses a different layout, provide a deterministic key resolver:
+
+```ts
+source(source: DeckSource<Env>) {
+  return withR2Assets(source, {
+    bucket: (c) => c.env.DECK_ASSETS,
+    key: ({ slug, assetPath }) => `decks/${slug}/${assetPath}`,
+    cacheControl: ({ asset }) =>
+      asset.publicPath.includes("/versioned/")
+        ? "public, max-age=31536000, immutable"
+        : "public, max-age=300",
+  });
+}
+```
+
+## Operational requirements
+
+- Upload the same paths that the key resolver produces; `withR2Assets` only reads objects.
+- Set correct R2 HTTP metadata, especially `contentType`. The decorator falls back to the compiled asset type when needed.
+- Use immutable caching only for versioned or content-addressed keys.
+- Keep the generated fallback if local development must work without an R2 binding.
+- Test a present object, missing object, and missing binding. Missing R2 data should fall back to the underlying source.
+- Do not replace slide image URLs with arbitrary public R2 URLs unless bypassing hono-decks asset routes is an explicit requirement.

package/skills/hono-decks/references/styling.md

@@ -0,0 +1,151 @@
+# Styling
+
+Use this route for deck-local `theme.css`, layout decisions, typography, visual hierarchy, animation, and overflow correction.
+
+## Canvas contract
+
+hono-decks renders a fixed 1920 × 1080 design canvas with a 16:9 aspect ratio and scales it into the viewer. Do not build responsive slide breakpoints. Style the canvas itself, then verify the scaled result and print route.
+
+The base root font size is 32px. Treat that as body copy, not a value to shrink globally. A practical hierarchy is:
+
+- body: `1rem` (32px)
+- supporting text: no smaller than `.75rem` (24px)
+- slide title: `1.75rem` to `2.5rem`
+- cover title: `3rem` to `5rem`
+- line height: about `1.15` for headings and `1.35` to `1.5` for body text
+
+## Start with deck-scoped CSS
+
+Create `decks/product/theme.css`:
+
+```css
+:root {
+  --hono-decks-color: #f7f8fb;
+  --hono-decks-muted-color: #c3c8d4;
+  --hono-decks-accent-color: #8bd3ff;
+  --hono-decks-border-color: rgba(255, 255, 255, 0.2);
+  --hono-decks-card-background: rgba(12, 18, 34, 0.82);
+  --hono-decks-inline-code-background: rgba(12, 18, 34, 0.72);
+  --hono-decks-code-background: #0a1020;
+}
+
+.layout-cover,
+.layout-default,
+.layout-statement,
+.layout-comparison {
+  background: #080d1a;
+  color: var(--hono-decks-color);
+}
+
+.slide h1,
+.slide h2 {
+  margin: 0 0 0.65em;
+  max-width: 18ch;
+  line-height: 1.08;
+  letter-spacing: -0.025em;
+}
+
+.slide p,
+.slide li {
+  line-height: 1.42;
+}
+
+.comparison-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1.5rem;
+  align-items: stretch;
+}
+
+.comparison-card {
+  min-width: 0;
+  border: 1px solid var(--hono-decks-border-color);
+  border-radius: 20px;
+  background: var(--hono-decks-card-background);
+  padding: 1.25rem;
+}
+```
+
+Use explicit semantic classes in MDX:
+
+```mdx
+---
+layout: comparison
+---
+
+## Build and runtime
+
+<div class="comparison-grid">
+  <section class="comparison-card">
+    <h3>Build</h3>
+    <p>Compile MDX with Node.js or Bun.</p>
+  </section>
+  <section class="comparison-card">
+    <h3>Runtime</h3>
+    <p>Serve generated modules from Hono.</p>
+  </section>
+</div>
+```
+
+Do not assume UnoCSS or Tailwind utility classes exist.
+
+## Readability and density rules
+
+- Prefer 20–40 visible words for a typical slide; use more only when the layout is deliberately text-led.
+- Keep lists to about 3–6 short items. Split a long sequence across slides.
+- Use at most two primary columns. More columns usually force unreadable type.
+- Keep code examples focused on the lines needed to explain the idea. Use `CodeBlock` or fenced code, both of which scroll instead of enlarging the canvas.
+- Use images and diagrams at a size that can be interpreted from the back of a room; remove decorative detail before reducing text.
+- Maintain strong foreground/background contrast and never communicate state by color alone.
+
+## Prevent overflow
+
+The slide intentionally uses `overflow: hidden`. Hidden content is a failure, not an invitation to add scrolling.
+
+When content overflows, fix it in this order:
+
+1. Remove repetition and shorten prose.
+2. Split the content into two slides.
+3. Replace a dense table with a focused comparison or chart.
+4. Reduce gaps or decorative padding modestly.
+5. Reduce a local type size only when it remains at least 24px.
+
+Avoid global transforms, `zoom`, negative margins that pull content outside the safe area, and font sizes chosen only to make one crowded slide fit.
+
+## Motion
+
+Built-in slide transitions and Fire reveals already respect `prefers-reduced-motion`. Custom animation must do the same:
+
+```css
+.signal-dot {
+  animation: pulse 2.4s ease-in-out infinite;
+}
+
+@keyframes pulse {
+  50% {
+    transform: scale(1.08);
+    opacity: 0.72;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .signal-dot {
+    animation: none;
+  }
+}
+```
+
+Animation should clarify sequence or change. Do not animate every object or make critical information depend on motion.
+
+## Visual QA
+
+Inspect every slide in the viewer and check:
+
+- no clipped headings, lists, code, images, or footers
+- body text remains readable when the 1920 × 1080 canvas is scaled down
+- titles and key claims dominate the hierarchy
+- repeated layouts align consistently
+- images retain aspect ratio and meaningful content is not cropped
+- Fire states remain understandable at each reveal step
+- print preview contains every slide and does not depend on live embeds
+- custom motion has a reduced-motion fallback