hono-decks 0.2.1 → 0.3.0

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