hono-decks 1.4.1 → 1.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-decks",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Slide decks for Hono and Cloudflare Workers",
   "keywords": [
     "cloudflare-workers",
@@ -83,9 +83,9 @@
     "check": "bun run typecheck && bun run test && bun run skills:validate"
   },
   "dependencies": {
-    "@babel/parser": "^7.29.3",
+    "@babel/parser": "^7.29.12",
     "@mdx-js/mdx": "^3.1.1",
-    "esbuild": "^0.28.1",
+    "esbuild": "^0.28.2",
     "remark-directive": "^4.0.0",
     "remark-gfm": "^4.0.0",
     "remark-mdx": "^3.1.1",

package/skills/hono-decks/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.
+  Create, style, integrate, and troubleshoot hono-decks presentations in Hono and Cloudflare Workers. Load for installation, Markdown and MDX deck 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
@@ -13,7 +13,7 @@ Use this skill as a router. Inspect the application and the request, then read o
 | 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) |
+| Write or fix `deck.mdx` or adapter-backed `deck.md`, frontmatter, 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) |
@@ -25,16 +25,16 @@ If the request is simply “make a deck,” read Authoring MDX and Styling. If i
 
 ## Non-negotiable architecture
 
-1. Compile MDX with Node.js or Bun at build time.
-2. Import generated TypeScript modules in the Worker runtime.
+1. Compile deck sources with Node.js or Bun during development or build, never in the Worker runtime.
+2. For Vite integrations use `virtual:hono-decks`; for the CLI/file workflow import generated TypeScript modules.
 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`.
+4. Use the framework integration to register routes, or mount manually with `app.route(decks.mountPath, decks.router())`. 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.
+- Use supported `:::fire` blocks, `<Fire>` groups in MDX, 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.
@@ -51,7 +51,7 @@ Wrong:
 // Hand-edit the generated manifest or routes.
 ```
 
-Correct: edit `decks/product/deck.mdx`, `theme.css`, assets, or components, then run `bunx hono-decks compile`.
+Correct: edit the deck source, `theme.css`, assets, or components. Vite integrations compile automatically; run `hono-decks compile` for the CLI/file workflow.
 
 ### Compiling inside the Worker
 
@@ -163,7 +163,7 @@ Correct: use `:::fire` and define project-specific classes explicitly in `theme.
 
 After changes:
 
-1. Run `hono-decks compile` through the application's package manager.
+1. Run the application build; use `hono-decks compile` explicitly for the CLI/file workflow.
 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.

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

@@ -1,6 +1,6 @@
 # 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.
+Use this route when writing or correcting `deck.mdx` or an adapter-backed `deck.md` file. Start with the basic syntax, then load the advanced sections only when the requested deck needs them.
 
 ## Basic deck structure
 
@@ -77,7 +77,7 @@ app.route(decks.mountPath, decks.router())
 
 Local image paths are rewritten during compilation. Put deck-local files under `assets/` and use relative paths.
 
-MDX exports, expressions, and JSX are supported:
+In `.mdx`, exports, expressions, and JSX are supported:
 
 ```mdx
 export const release = "2026.07"
@@ -88,6 +88,10 @@ export const metrics = ["42% faster", "3 fewer steps"]
 {metrics.map((metric) => <Badge label={metric} />)}
 ```
 
+## Markdown adapter and islands
+
+`.md` decks require a configured Markdown adapter. Void init configures it; Hono and HonoX default to MDX. For Hono Markdown, a `<script>` may contain relative default TSX/JSX imports marked `with { island: "load" }` (also `visible`, `idle`, or `media:(query)`). Imported island tags accept literal string and boolean props, not JSX expressions or children; arbitrary script code is unsupported. Do not substitute MDX component-registry or expression syntax into `.md`. See the package README for setup and examples.
+
 ## Speaker notes
 
 Use the slide `notes` frontmatter field or MDX comments. Comments are removed from visible slide output and collected as presenter notes.
@@ -197,4 +201,4 @@ Client props may contain only strings, finite numbers, booleans, `null`, arrays,
 - 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.
+- Confirm the application build or development compiler succeeds after syntax changes and resolve warnings.

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

@@ -22,7 +22,7 @@ for manual integration and non-Vite applications.
 
 For an existing Void app, use `npx hono-decks init --framework void` after
 installing the compatible packages and Markdown peers described in the README.
-Use `void-plugin-hono-jsx@^0.6.0` for its standalone compiler and client exports. Init connects the existing Vite config, creates the routing
+New installs use `void-plugin-hono-jsx@^0.9.1`; existing compatible Void 1.1 apps may retain adapter 0.6. Init connects the existing Vite config, creates the routing
 middleware and a sample `.md` deck at `/slides/welcome`, and uses virtual modules without generated
 files. Use the app's normal `dev` and `build` scripts without changes or a manual
 compile. Existing `.mdx` files remain supported. Unsupported configs or existing
@@ -146,7 +146,7 @@ export default defineConfig({
 - Missing config: run `hono-decks init` or create a default-exported `hono-decks.config.ts`.
 - Missing virtual module types: reference `hono-decks/vite-env`; a dev/build or manual compile is not required for typechecking.
 - Missing generated import in the CLI/file workflow: 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.
+- Deck not discovered: use `decks/<slug>/deck.mdx` or a supported single-file deck in the configured root; `.md` requires a configured Markdown adapter.
 - 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.
@@ -159,4 +159,4 @@ retain manual dependency installation by omitting --install. Yarn PnP is not
 supported by the automatic installer. The generated Markdown sample includes a
 Counter.tsx island. Markdown uses relative default imports with `island: "load"`,
 `visible`, `idle`, or `media:(query)` and literal props, with no separate registry.
-Arbitrary script code/JSX expressions remain unsupported; MDX stays unchanged.
+Arbitrary script code/JSX expressions remain unsupported; MDX stays unchanged. For Hono or HonoX, MDX is the default; enable `.md` explicitly with `build.markdown: { adapter: "hono-decks/adapters/hono-markdown" }` and install the common Markdown package and its compiler peers as documented in the package README.

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

@@ -4,7 +4,7 @@ Use this route when adding hono-decks to an existing Hono, HonoX, Vite, Wrangler
 
 ## 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.
+The compiler and `hono-decks/node` use Node filesystem tooling. Run them during development or build, never in the Worker. Vite framework init uses `virtual:hono-decks`; the following generated facade applies to the CLI/file workflow.
 
 ```ts
 // src/decks.ts
@@ -81,6 +81,10 @@ export default defineConfig({
 
 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.
 
+## Development updates
+
+In Vite integrations, successful source edits update the presentation in place when island identities can be matched safely, preserving supported state and the current slide/step. Client code edits reload the presentation iframe and reset island state while retaining the viewer and slide/step. Ambiguous identities, unsupported hydration, and update failures also fall back to an iframe reload. Wrangler direct mode uses its own `--live-reload`.
+
 ## Application-owned routes
 
 Use `decks.context()` to share deck lookup, draft policy, paths, and viewer configuration:
@@ -149,7 +153,7 @@ Review any application-wide CSP middleware after mounting: it must preserve the
 
 ## Integration verification
 
-- Start the normal application dev command and confirm MDX changes recompile.
+- Start the normal application dev command and confirm deck changes recompile and appear.
 - 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.