hono-decks 0.1.0 → 0.2.0

package/README.ja.md

@@ -0,0 +1,289 @@
+# hono-decks
+
+[English](https://github.com/ts-76/hono-decks/blob/main/packages/decks/README.md) | 日本語
+
+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/README.md

@@ -1,21 +1,25 @@
 # hono-decks
 
-Hono と Cloudflare Workers 上で MDX のスライドを配信するためのライブラリです。ビルド時に MDX を TypeScript module へ変換し、Worker runtime ではファイルシステムや compiler を読み込みません。
+English | [日本語](https://github.com/ts-76/hono-decks/blob/main/packages/decks/README.ja.md)
+
+hono-decks serves MDX slide decks from Hono applications and Cloudflare Workers. It compiles MDX into TypeScript modules at build time, so the Worker runtime does not load the filesystem or the compiler.
 
 ## Quick start
 
-```bash
+The examples below use Bun. npm, pnpm, and Yarn are supported as well.
+
+~~~bash
 bun add hono hono-decks
 bunx hono-decks init
 bunx hono-decks compile
-```
+~~~
 
-`init` は次の2ファイルを作ります。既存ファイルは上書きしません。
+<code>init</code> creates two files without overwriting existing files:
 
-- `hono-decks.config.ts`: CLI と runtime が共有する唯一の設定
-- `src/decks.ts`: generated module をアプリへ接続する編集可能な facade
+- <code>hono-decks.config.ts</code>: the shared configuration for the CLI and runtime
+- <code>src/decks.ts</code>: an editable facade that connects the generated modules to your application
 
-```ts
+~~~ts
 // hono-decks.config.ts
 import { defineDecksConfig } from "hono-decks";
 
@@ -26,17 +30,17 @@ export default defineDecksConfig({
     outDir: "src/generated",
   },
 });
-```
+~~~
 
-```ts
+~~~ts
 // src/decks.ts
 import config from "../hono-decks.config";
 import { createDecks } from "./generated/decks";
 
 export const decks = createDecks(config);
-```
+~~~
 
-```ts
+~~~ts
 // src/index.ts
 import { Hono } from "hono";
 import { decks } from "./decks";
@@ -45,21 +49,21 @@ 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 は直接編集しません。
+Create <code>decks/welcome/deck.mdx</code>, then run <code>bunx hono-decks compile</code>. The command updates <code>src/generated/decks.ts</code> and the generated slide modules. Do not edit the generated directory directly.
 
 ## One config, one runtime kit
 
-以前のように compile option、`app.route()`、asset URL の mount path を別々に指定する必要はありません。`mountPath` は config に一度だけ書きます。generated module の `createDecks(config)` は次の configured kit を返します。
+You do not need to repeat the mount path across compiler options, <code>app.route()</code>, and asset URLs. Define <code>mountPath</code> once in the config. The generated <code>createDecks(config)</code> function returns a 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
+- <code>decks.mountPath</code>: the normalized path to pass to <code>app.route()</code>
+- <code>decks.source</code>: the <code>DeckSource</code> after applying the config's <code>source()</code> decorator
+- <code>decks.router(overrides?)</code>: a router that safely deep-merges config and call-site overrides
+- <code>decks.context(overrides?)</code>: middleware for application-owned routes
+- <code>decks.paths(slug)</code>: the complete route map for the viewer, renderer, print view, presentation views, embeds, exports, OGP image, and assets
 
-```ts
+~~~ts
 const paths = decks.paths("product");
 paths.viewer;       // /decks/product
 paths.render;       // /decks/product/render
@@ -71,30 +75,34 @@ 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 を再構築しないでください。
+Viewer callbacks receive the same map as <code>input.meta.paths</code>. Use it instead of rebuilding routes with string concatenation.
 
-```ts
+~~~ts
 export default defineDecksConfig({
   mountPath: "/decks",
   router: {
     viewer: {
       controls: {
         after: ({ meta }) => [
-          { type: "link", href: `${meta.paths.viewer}/about`, label: "Details" },
+          {
+            type: "link",
+            href: meta.paths.viewer + "/about",
+            label: "Details",
+          },
         ],
       },
     },
   },
 });
-```
+~~~
 
 ## Development integration
 
-Cloudflare Workersでは、deck compilerをWranglerのcustom buildへ登録します。
+For Cloudflare Workers, register the deck compiler as a Wrangler custom build.
 
-```jsonc
+~~~jsonc
 // wrangler.jsonc
 {
   "build": {
@@ -102,28 +110,28 @@ Cloudflare Workersでは、deck compilerをWranglerのcustom buildへ登録し
     "watch_dir": ["decks"]
   }
 }
-```
+~~~
 
-`wrangler dev --live-reload`が初回compileとMDX、deck-local component、asset、theme CSSの変更監視、ブラウザ更新を担当します。deploy時にも同じbuild commandが実行されます。
+<code>wrangler dev --live-reload</code> performs the initial compile, watches MDX, deck-local components, assets, and theme CSS, and reloads the browser. Wrangler runs the same build command during deployment.
 
-HonoXまたはViteでは、既存のVite configへpluginを追加します。
+For HonoX or another Vite application, add the plugin to the existing Vite config.
 
-```ts
+~~~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できます。
+The plugin compiles before Vite starts and adds the deck root and <code>hono-decks.config.ts</code> to the Vite watcher. After a successful recompile, it requests a full browser reload. In both setups, the application's normal <code>dev</code> command is enough for authoring.
 
 ## Runtime configuration
 
-すべての resolver は1個の object argument を受け取ります。引数の順序を覚える必要がなく、将来 input が増えても callback の意味が崩れません。
+Every resolver receives one object argument. Callbacks remain readable as inputs are added because their meaning does not depend on positional parameters.
 
-```ts
+~~~ts
 interface AppEnv {
   Bindings: {
     BROWSER?: DeckBrowserRunBinding;
@@ -141,29 +149,29 @@ export default defineDecksConfig<AppEnv>({
     },
     export: {
       authorize: ({ c }) =>
-        c.req.header("authorization") === `Bearer ${c.env.DECK_EXPORT_TOKEN}`,
+        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を指定した場合は明示値が優先され、判定できない環境では本番モードとして扱われます。
+When <code>dev</code> is omitted, hono-decks uses the <code>NODE_ENV</code> value supplied by Vite or Wrangler. The standard Vite and <code>wrangler dev</code> commands are treated as development, while production builds and <code>wrangler deploy</code> are treated as production. An explicit <code>dev: false</code> value or resolver takes precedence. Unknown environments fail closed as production.
 
-呼び出し元で一部だけ変える場合は `decks.router({ viewer: ... })` を使います。viewer controls、document surfaces、presenter、embed、export などの nested option は config を失わずに合成されます。機能を止めるときは `presenter: false`、`embed: false`、`export: false` のように明示できます。
+Use <code>decks.router({ viewer: ... })</code> for call-site overrides. Nested options for viewer controls, document surfaces, the presenter, embeds, and exports are merged without discarding the config. Disable a feature explicitly with values such as <code>presenter: false</code>, <code>embed: false</code>, or <code>export: false</code>.
 
 ## Custom application routes
 
-```ts
+~~~ts
 import type { DeckContextVariables } from "hono-decks";
 import { decks } from "./decks";
 
 const app = new Hono<{ Variables: DeckContextVariables }>();
 
 app.get(
-  `${decks.mountPath}/:slug/about`,
+  decks.mountPath + "/:slug/about",
   decks.context(),
   (c) => c.json({
     title: c.var.deckMeta.title,
@@ -171,17 +179,17 @@ app.get(
     slides: c.var.deckToc,
   }),
 );
-```
+~~~
 
-`decks.context()` は configured source、mount path、dev policy、viewer controls を自動的に共有します。custom route と標準 viewer で draft 判定や URL がずれません。
+<code>decks.context()</code> shares the configured source, mount path, development policy, and viewer controls. Application routes and the built-in viewer therefore use the same draft policy and URLs.
 
-標準ページ全体を差し替える場合は config の `viewer.render` を使います。callback には `frame`、`controls`、`toc`、`meta.paths` が渡るため、標準部品を再利用しながら app-owned layout を構築できます。
+To replace a built-in page, configure <code>viewer.render</code>. The callback receives <code>frame</code>, <code>controls</code>, <code>toc</code>, and <code>meta.paths</code>, allowing an application-owned layout to reuse the standard parts.
 
 ## Deck-local components and CSS
 
-Directory deck は次の構造を使えます。
+A directory deck can use this structure:
 
-```text
+~~~text
 decks/product/
   deck.mdx
   theme.css
@@ -191,73 +199,73 @@ decks/product/
     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 に書き換えられます。
+<code>components/index.tsx</code> contains server-side JSX components. <code>components/client/index.tsx</code> contains components hydrated in the browser. <code>theme.css</code> applies only to that deck. Local images are detected during compilation and rewritten to public URLs based on the mount path and deck slug.
 
 ## Embedding
 
-同じdocumentへ複数配置する場合は `createDeckViewerEmbed()` を使えます。これは app が取得済みの `CompiledDeck` から iframe viewer、controls、TOC を組み立てる high-level helper です。
+Use <code>createDeckViewerEmbed()</code> to embed multiple decks into the same document. This high-level helper builds an iframe viewer, controls, and a table of contents from a <code>CompiledDeck</code> already loaded by the application.
 
-Embedding from an external blog では `router.embed` を有効にし、`frameAncestors` に許可する親 origin を明示してください。`iframe navigationにCORSは不要`ですが、CSP の `frame-ancestors` は必要です。
+When embedding from an external blog, enable <code>router.embed</code> and list the allowed parent origins in <code>frameAncestors</code>. Iframe navigation does not require CORS, but it does require an appropriate CSP <code>frame-ancestors</code> directive.
 
-```ts
+~~~ts
 router: {
   embed: {
     frameAncestors: ["https://blog.example.com"],
     robots: false,
   },
 }
-```
+~~~
 
-```html
+~~~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 として管理してください。
+Enable PDF and PNG exports by returning a Cloudflare Browser Rendering binding from the resolver. The viewer displays export controls only for requests accepted by <code>authorize</code>. Store export tokens as Wrangler secrets rather than in <code>vars</code>.
 
-`Cmd + P` / `Ctrl + P` は viewer から print route を開き、印刷用に全 slide を表示します。server-side export も同じ print route を Browser Rendering に渡します。
+<code>Cmd + P</code> and <code>Ctrl + P</code> open the viewer's print route, which renders every slide for printing. Server-side export sends the same print route to Browser Rendering.
 
 ## Build-time OGP recipe
 
-viewer の share image をビルド時に生成する場合は、`router.viewer.openGraph` を有効にします。既定の画像パスは `decks.paths(slug).ogImage` です。viewer は request origin から Open Graph / Twitter Card の絶対URLを生成します。
+Enable <code>router.viewer.openGraph</code> when generating share images at build time. The default image path is <code>decks.paths(slug).ogImage</code>. The viewer derives absolute Open Graph and Twitter Card URLs from the request origin.
 
-```ts
+~~~ts
 export default defineDecksConfig({
   mountPath: "/decks",
   router: {
     viewer: { openGraph: true },
   },
 });
-```
+~~~
 
-独自CDNを使う場合は `imagePath: ({ deck }) => \`https://cdn.example.com/${deck.slug}.png\`` のように resolver で上書きできます。`false` または未指定なら social metadata は出力しません。
+Override <code>imagePath</code> with a resolver when images are served from a separate CDN. Set Open Graph configuration to <code>false</code>, or omit it, to suppress 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 から明示的に渡してください。
+Image generation is intentionally not part of the core package. The <code>examples/ogp</code> recipe passes the manifest returned by <code>compileDecks()</code> from <code>hono-decks/node</code> to Satori and resvg, then stores 1200 by 630 PNG files in Workers Static Assets. Satori and resvg are example-only dependencies, and the recipe does not require Browser Rendering. Satori accepts TTF, OTF, and WOFF fonts but not WOFF2, so the build script must receive a font file that covers the target language.
 
-`build.ogpCacheFile` は `@[card](...)` が参照する外部サイトのメタデータキャッシュです。viewer 自身の share image とは別機能です。
+<code>build.ogpCacheFile</code> stores external site metadata used by <code>@[card](...)</code>. It is separate from the viewer's 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
+- <code>hono-decks</code>: configuration, configured-kit types, deck authoring, viewer and embed customization, and source decorators
+- <code>hono-decks/advanced</code>: <code>defineDecks()</code>, <code>decksRouter()</code>, <code>deckContext()</code>, raw renderers, and other low-level pipeline APIs
+- <code>hono-decks/client</code>: browser hydration
+- <code>hono-decks/node</code>: the compiler and Node filesystem adapter
+- <code>hono-decks/cli</code>: the programmatic CLI runner
 
-通常の generated workflow では root entry だけを import します。`hono-decks/advanced` は custom `DeckSource` や router をゼロから組み立てる場合に限定してください。
+The generated workflow normally imports only the root entry. Use <code>hono-decks/advanced</code> only when assembling a custom <code>DeckSource</code> or router from the lower-level primitives.
 
 ## Cloudflare Workers
 
-Wrangler は JSONC config、current compatibility date、必要に応じた `nodejs_compat` を使います。binding types は `wrangler types` で生成し、hand-written binding interface と実際の config がずれないようにしてください。
+Use a JSONC Wrangler config, a current compatibility date, and <code>nodejs_compat</code> when required. Generate binding types with <code>wrangler types</code> so handwritten environment types cannot drift from the deployed configuration.
 
-```jsonc
+~~~jsonc
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "my-decks",
@@ -265,23 +273,23 @@ Wrangler は JSONC config、current compatibility date、必要に応じた `nod
   "compatibility_date": "2026-07-14",
   "compatibility_flags": ["nodejs_compat"]
 }
-```
+~~~
 
 ## Advanced API
 
-既存 manifest、database、remote object store から完全に独自の runtime を作る場合だけ advanced entry を使います。
+Use the advanced entry only when building a custom runtime from an existing manifest, database, or remote object store.
 
-```ts
+~~~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)` のほうが安全で短くなります。
+At this level, the application owns the mount path, source policy, and option merging. For normal use, the generated <code>createDecks(config)</code> API is shorter and safer.
 
 ## Examples
 
-- `examples/minimal`: standalone Worker の最小構成
-- `examples/basic`: R2、Browser Rendering、custom routes、client components
-- `examples/honox`: HonoX integration
+- <code>examples/minimal</code>: the smallest standalone Worker setup
+- <code>examples/basic</code>: R2, Browser Rendering, custom routes, and client components
+- <code>examples/honox</code>: HonoX integration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-decks",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Slide decks for Hono and Cloudflare Workers",
   "keywords": [
     "cloudflare-workers",
@@ -8,15 +8,15 @@
     "mdx",
     "slides"
   ],
-  "homepage": "https://github.com/ts-76/hono-slides#readme",
+  "homepage": "https://github.com/ts-76/hono-decks#readme",
   "bugs": {
-    "url": "https://github.com/ts-76/hono-slides/issues"
+    "url": "https://github.com/ts-76/hono-decks/issues"
   },
   "license": "MIT",
   "author": "ts-76",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ts-76/hono-slides.git",
+    "url": "git+https://github.com/ts-76/hono-decks.git",
     "directory": "packages/decks"
   },
   "bin": {
@@ -24,7 +24,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "README.ja.md"
   ],
   "type": "module",
   "sideEffects": false,