hono-decks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ts-76
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# hono-decks
+
+Hono と Cloudflare Workers 上で MDX のスライドを配信するためのライブラリです。ビルド時に MDX を TypeScript module へ変換し、Worker runtime ではファイルシステムや compiler を読み込みません。
+
+## Quick start
+
+```bash
+bun add hono hono-decks
+bunx hono-decks init
+bunx hono-decks compile
+```
+
+`init` は次の2ファイルを作ります。既存ファイルは上書きしません。
+
+- `hono-decks.config.ts`: CLI と runtime が共有する唯一の設定
+- `src/decks.ts`: generated module をアプリへ接続する編集可能な facade
+
+```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);
+```
+
+```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;
+```
+
+`decks/welcome/deck.mdx` を作り、`bunx hono-decks compile` を実行すると `src/generated/decks.ts` と slide modules が更新されます。generated directory は直接編集しません。
+
+## One config, one runtime kit
+
+以前のように compile option、`app.route()`、asset URL の mount path を別々に指定する必要はありません。`mountPath` は config に一度だけ書きます。generated module の `createDecks(config)` は次の configured kit を返します。
+
+- `decks.mountPath`: `app.route()` に渡す正規化済みパス
+- `decks.source`: config の `source()` が適用された `DeckSource`
+- `decks.router(overrides?)`: config と呼び出し時 override を安全に深く合成した router
+- `decks.context(overrides?)`: custom route 用 middleware
+- `decks.paths(slug)`: viewer、render、print、presentation、presenter、embed、export、OGP image、assets の完全な route map
+
+```ts
+const paths = decks.paths("product");
+paths.viewer;       // /decks/product
+paths.render;       // /decks/product/render
+paths.print;        // /decks/product/print
+paths.presentation; // /decks/product/presentation
+paths.presenter;    // /decks/product/presenter
+paths.embed;        // /decks/product/embed
+paths.exportPdf;    // /decks/product/export.pdf
+paths.exportPng;    // /decks/product/export.png
+paths.ogImage;      // /decks/product/og.png
+paths.assets;       // /decks/product/assets
+```
+
+Viewer callbacks では同じ map を `input.meta.paths` から参照できます。文字列連結で route を再構築しないでください。
+
+```ts
+export default defineDecksConfig({
+  mountPath: "/decks",
+  router: {
+    viewer: {
+      controls: {
+        after: ({ meta }) => [
+          { type: "link", href: `${meta.paths.viewer}/about`, label: "Details" },
+        ],
+      },
+    },
+  },
+});
+```
+
+## Development integration
+
+Cloudflare Workersでは、deck compilerをWranglerのcustom buildへ登録します。
+
+```jsonc
+// wrangler.jsonc
+{
+  "build": {
+    "command": "hono-decks compile",
+    "watch_dir": ["decks"]
+  }
+}
+```
+
+`wrangler dev --live-reload`が初回compileとMDX、deck-local component、asset、theme CSSの変更監視、ブラウザ更新を担当します。deploy時にも同じbuild commandが実行されます。
+
+HonoXまたはViteでは、既存のVite configへpluginを追加します。
+
+```ts
+import { honoDecks } from "hono-decks/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [honoDecks()],
+});
+```
+
+pluginはVite起動前にcompileし、deck rootと`hono-decks.config.ts`をVite watcherへ登録します。再compileに成功するとfull reloadを通知するため、手動更新は不要です。どちらの構成でも通常の`bun run dev`だけでauthoringできます。
+
+## Runtime configuration
+
+すべての resolver は1個の object argument を受け取ります。引数の順序を覚える必要がなく、将来 input が増えても callback の意味が崩れません。
+
+```ts
+interface AppEnv {
+  Bindings: {
+    BROWSER?: DeckBrowserRunBinding;
+    DECK_EXPORT_TOKEN?: string;
+  };
+}
+
+export default defineDecksConfig<AppEnv>({
+  mountPath: "/decks",
+  build: { root: "decks", outDir: "src/generated" },
+  router: {
+    presenter: {
+      enabled: ({ dev }) => dev,
+      viewerControl: true,
+    },
+    export: {
+      authorize: ({ c }) =>
+        c.req.header("authorization") === `Bearer ${c.env.DECK_EXPORT_TOKEN}`,
+      browser: ({ c }) => c.env.BROWSER,
+      pdf: true,
+      png: true,
+    },
+  },
+});
+```
+
+`dev`を省略すると、ViteとWranglerが設定する`NODE_ENV`から判定します。標準設定では、`vite`と`wrangler dev`は開発モード、プロダクションビルドと`wrangler deploy`は本番モードになります。`dev: false`やresolverを指定した場合は明示値が優先され、判定できない環境では本番モードとして扱われます。
+
+呼び出し元で一部だけ変える場合は `decks.router({ viewer: ... })` を使います。viewer controls、document surfaces、presenter、embed、export などの nested option は config を失わずに合成されます。機能を止めるときは `presenter: false`、`embed: false`、`export: false` のように明示できます。
+
+## Custom application routes
+
+```ts
+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,
+  }),
+);
+```
+
+`decks.context()` は configured source、mount path、dev policy、viewer controls を自動的に共有します。custom route と標準 viewer で draft 判定や URL がずれません。
+
+標準ページ全体を差し替える場合は config の `viewer.render` を使います。callback には `frame`、`controls`、`toc`、`meta.paths` が渡るため、標準部品を再利用しながら app-owned layout を構築できます。
+
+## Deck-local components and CSS
+
+Directory deck は次の構造を使えます。
+
+```text
+decks/product/
+  deck.mdx
+  theme.css
+  assets/
+    diagram.svg
+  components/
+    index.tsx
+    client/
+      index.tsx
+```
+
+`components/index.tsx` は server-side JSX component、`components/client/index.tsx` は browser で hydrate する component です。`theme.css` はその deck だけに適用されます。画像は compile 時に検出され、`mountPath` と slug を使った public URL に書き換えられます。
+
+## Embedding
+
+同じdocumentへ複数配置する場合は `createDeckViewerEmbed()` を使えます。これは app が取得済みの `CompiledDeck` から iframe viewer、controls、TOC を組み立てる high-level helper です。
+
+Embedding from an external blog では `router.embed` を有効にし、`frameAncestors` に許可する親 origin を明示してください。`iframe navigationにCORSは不要`ですが、CSP の `frame-ancestors` は必要です。
+
+```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>
+```
+
+## Browser export
+
+PDF/PNG export は Cloudflare Browser Rendering binding を resolver から返すと有効になります。viewer に export control が表示されるのは、その request が `authorize` を通った場合だけです。token は `vars` ではなく Wrangler secret として管理してください。
+
+`Cmd + P` / `Ctrl + P` は viewer から print route を開き、印刷用に全 slide を表示します。server-side export も同じ print route を Browser Rendering に渡します。
+
+## Build-time OGP recipe
+
+viewer の share image をビルド時に生成する場合は、`router.viewer.openGraph` を有効にします。既定の画像パスは `decks.paths(slug).ogImage` です。viewer は request origin から Open Graph / Twitter Card の絶対URLを生成します。
+
+```ts
+export default defineDecksConfig({
+  mountPath: "/decks",
+  router: {
+    viewer: { openGraph: true },
+  },
+});
+```
+
+独自CDNを使う場合は `imagePath: ({ deck }) => \`https://cdn.example.com/${deck.slug}.png\`` のように resolver で上書きできます。`false` または未指定なら social metadata は出力しません。
+
+生成処理は core に含まれません。`examples/ogp` では `hono-decks/node` の `compileDecks()` が返す manifest を Satori + resvg へ渡し、1200×630 PNG を Workers Static Assets へ保存します。Satori / resvg は example だけの依存で、Browser Rendering binding は不要です。Satori は TTF / OTF / WOFF を読み込めますが WOFF2 は扱えないため、対象言語の font file を build script から明示的に渡してください。
+
+`build.ogpCacheFile` は `@[card](...)` が参照する外部サイトのメタデータキャッシュです。viewer 自身の share image とは別機能です。
+
+## Public entries
+
+- `hono-decks`: config、configured kit の型、deck authoring、viewer/embed customization、source decorator
+- `hono-decks/advanced`: `defineDecks()`、`decksRouter()`、`deckContext()`、raw renderer など独自 pipeline 用
+- `hono-decks/client`: browser hydration
+- `hono-decks/node`: compiler と Node filesystem adapter
+- `hono-decks/cli`: programmatic CLI runner
+
+通常の generated workflow では root entry だけを import します。`hono-decks/advanced` は custom `DeckSource` や router をゼロから組み立てる場合に限定してください。
+
+## Cloudflare Workers
+
+Wrangler は JSONC config、current compatibility date、必要に応じた `nodejs_compat` を使います。binding types は `wrangler types` で生成し、hand-written binding interface と実際の config がずれないようにしてください。
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-decks",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-07-14",
+  "compatibility_flags": ["nodejs_compat"]
+}
+```
+
+## Advanced API
+
+既存 manifest、database、remote object store から完全に独自の runtime を作る場合だけ advanced entry を使います。
+
+```ts
+import { decksRouter, manifestDeckSource } from "hono-decks/advanced";
+
+const source = manifestDeckSource(manifest);
+app.route("/internal-slides", decksRouter({ source, dev: true }));
+```
+
+このレベルでは mount path、source policy、option merge をアプリ側が管理します。通常の利用では generated `createDecks(config)` のほうが安全で短くなります。
+
+## Examples
+
+- `examples/minimal`: standalone Worker の最小構成
+- `examples/basic`: R2、Browser Rendering、custom routes、client components
+- `examples/honox`: HonoX integration

package/dist/advanced.d.ts

@@ -0,0 +1,62 @@
+import { C as CompiledDeck, R as ResolvedDeckDocument, a as CompiledSlide, A as AssetRef, D as DeckManifest, b as DeckSource } from './define-decks-U4NxIs66.js';
+export { c as CompileWarning, d as ComponentPlaceholder, e as ConfiguredDecks, f as DeckBrowserRunBinding, g as DeckBrowserRunPdfOptions, h as DeckBrowserRunPngOptions, i as DeckContextOptions, j as DeckContextVariables, k as DeckControlIconName, l as DeckDevResolver, m as DeckDevResolverInput, n as DeckDocumentOptions, o as DeckDocumentPageOptions, p as DeckDocumentRenderInput, q as DeckDocumentSurface, r as DeckEntry, s as DeckExportOptions, t as DeckExportResolverInput, u as DeckExternalEmbedContext, v as DeckExternalEmbedOptions, w as DeckExternalEmbedRenderInput, x as DeckExternalEmbedViewerOptions, y as DeckFrontmatter, z as DeckIndexPageInput, B as DeckIndexPageOptions, E as DeckIndexRenderInput, F as DeckKind, G as DeckPageMeta, H as DeckPaths, I as DeckPresenterEnabledInput, J as DeckPresenterEnabledResolver, K as DeckPresenterViewerControlOptions, L as DeckRequestContext, M as DeckRouteEnabled, N as DeckRouteEnabledResolver, O as DeckRouteSurface, P as DeckRouteSurfaceInput, Q as DeckTocItem, S as DeckViewerAvailablePages, T as DeckViewerControlDefaults, U as DeckViewerControlItem, V as DeckViewerControlItemRenderer, W as DeckViewerControlKey, X as DeckViewerControlRenderInput, Y as DeckViewerControlSlotItems, Z as DeckViewerControlsContext, _ as DeckViewerControlsItemsResolver, $ as DeckViewerControlsOptions, a0 as DeckViewerDefaultControlItem, a1 as DeckViewerEmbed, a2 as DeckViewerEmbedOptions, a3 as DeckViewerExportPaths, a4 as DeckViewerLinkControlItem, a5 as DeckViewerOptions, a6 as DeckViewerPart, a7 as DeckViewerParts, a8 as DeckViewerRenderControlItem, a9 as DeckViewerRenderInput, aa as DecksBuildConfig, ab as DecksConfig, ac as DecksOptions, ad as DecksRouterConfig, ae as DecksRouterExtension, af as DecksRouterOptions, ag as DecksRouterOverrides, ah as DecksRouterPagesOptions, ai as DecksRouterPresenterOptions, aj as DefinedDecks, ak as SLIDE_TRANSITIONS, al as SlideFrontmatter, am as SlideTransition, an as configureDecks, ao as controlIconLabel, ap as createDeckPaths, aq as createDeckViewerEmbed, ar as createDeckViewerParts, as as deckContext, at as decksRouter, au as defineDecks, av as defineDecksConfig, aw as mergeDecksRouterOptions, ax as renderControlIcon, ay as renderControlIconHtml } from './define-decks-U4NxIs66.js';
+export { R2AssetKeyInput, R2AssetSourceOptions, R2BucketLike, R2BucketResolver, R2ObjectBodyLike, R2ObjectHttpMetadataLike, withR2Assets } from './mod.js';
+import { a as SlideComponentRegistry, b as SlideComponentInput } from './jsx-renderer-BO-N4tMZ.js';
+export { D as DeckRenderable, M as MaybePromise, S as SlideComponent, c as SlideComponentDefinition, d as SlideComponentProps, e as builtInSlideComponents, f as defineSlideComponents } from './jsx-renderer-BO-N4tMZ.js';
+import { Handler, Env } from 'hono';
+import 'hono/jsx';
+import 'hono/utils/html';
+
+declare function renderCompiledDeckPage(input: {
+    deck: CompiledDeck;
+    mountPath: string;
+    style?: string;
+    liveReloadPath?: string;
+    components?: SlideComponentRegistry | Record<string, SlideComponentInput>;
+    clientEntry?: string;
+    printPreview?: boolean;
+    speakerNotes?: boolean;
+    document?: ResolvedDeckDocument;
+}): string;
+declare function renderCompiledDeckPageAsync(input: {
+    deck: CompiledDeck;
+    mountPath: string;
+    style?: string;
+    liveReloadPath?: string;
+    components?: SlideComponentRegistry | Record<string, SlideComponentInput>;
+    clientEntry?: string;
+    printPreview?: boolean;
+    speakerNotes?: boolean;
+    document?: ResolvedDeckDocument;
+}): Promise<string>;
+
+declare function renderCompiledDeck(deck: CompiledDeck, input?: {
+    components?: SlideComponentRegistry | Record<string, SlideComponentInput>;
+    speakerNotes?: boolean;
+}): string;
+declare function renderCompiledDeckAsync(deck: CompiledDeck, input?: {
+    components?: SlideComponentRegistry | Record<string, SlideComponentInput>;
+    speakerNotes?: boolean;
+}): Promise<string>;
+declare function renderCompiledSlide(slide: CompiledSlide, assets?: AssetRef[], input?: {
+    components?: SlideComponentRegistry | Record<string, SlideComponentInput>;
+    deck?: CompiledDeck;
+    speakerNotes?: boolean;
+    slideState?: "active" | "inactive";
+}): string;
+declare function renderCompiledSlideAsync(slide: CompiledSlide, assets?: AssetRef[], input?: {
+    components?: SlideComponentRegistry | Record<string, SlideComponentInput>;
+    deck?: CompiledDeck;
+    speakerNotes?: boolean;
+    slideState?: "active" | "inactive";
+}): Promise<string>;
+
+interface ServeDecksClientEntryOptions {
+    cacheControl?: string | false;
+    contentType?: string;
+}
+declare function serveDecksClientEntry(clientEntry: string, options?: ServeDecksClientEntryOptions): Handler;
+
+declare function manifestDeckSource<E extends Env = any>(manifest: DeckManifest): DeckSource<E>;
+
+export { AssetRef, CompiledDeck, CompiledSlide, DeckManifest, DeckSource, ResolvedDeckDocument, type ServeDecksClientEntryOptions, SlideComponentInput, SlideComponentRegistry, manifestDeckSource, renderCompiledDeck, renderCompiledDeckAsync, renderCompiledDeckPage, renderCompiledDeckPageAsync, renderCompiledSlide, renderCompiledSlideAsync, serveDecksClientEntry };