feat: integrate vite devtools

.gitignore

@@ -43,5 +43,6 @@ logs
 
 # Comark
 packages/comark/skills
+packages/comark/src/devtools/renderer/styles.ts
 .vercel
 .env*

AGENTS.md

@@ -53,6 +53,22 @@ packages/comark/
 │   │   ├── index.ts          # Re-exports (comark/ast entry point)
 │   │   ├── types.ts          # ComarkTree, ComarkNode, ComarkElement, ComarkText
 │   │   └── utils.ts          # textContent(), visit() tree utilities
+│   ├── devtools/             # Vite DevTools integration
+│   │   ├── index.ts          # Public exports (comark/devtools entry point)
+│   │   ├── bridge.ts         # Context ↔ HMR bridge for the Vite DevTools panel
+│   │   ├── client.ts         # Injected client entry (connectDevtools)
+│   │   ├── vite.ts           # Vite plugin with RPC endpoints (comark/devtools/vite entry point)
+│   │   ├── renderer.ts       # Re-export barrel (comark/devtools/renderer entry point)
+│   │   ├── types.ts          # Shared TypeScript interfaces for RPC and panel
+│   │   ├── constants.ts      # Icon assets and Shiki theme/lang config
+│   │   └── renderer/         # DevTools panel UI (internal)
+│   │       ├── index.ts      # Entry point, exports DevtoolsPanel
+│   │       ├── panel.ts      # Panel class: tabs, editor, polling, RPC orchestration
+│   │       ├── dom.ts        # DOM element factories (editor, tab bar, states)
+│   │       ├── output.ts     # AST rendering, regex fallback highlighter
+│   │       ├── styles.ts     # CSS styles (imports styles.css)
+│   │       ├── styles.css    # Panel stylesheet
+│   │       └── theme.ts      # Light/dark/auto theme toggle
 │   ├── plugins/              # Built-in and optional plugins
 │   │   ├── alert.ts          # Alert/callout blocks
 │   │   ├── emoji.ts          # Emoji shortcodes
@@ -76,9 +92,10 @@ packages/comark/
 
 | Peer | Required by |
 |------|-------------|
-| `shiki` | `comark/plugins/highlight` |
+| `shiki` | `comark/plugins/highlight`, `comark/devtools/vite` (devtools Shiki highlighting) |
 | `katex` | `comark/plugins/math` |
 | `beautiful-mermaid` | `comark/plugins/mermaid` |
+| `@vitejs/devtools-kit` | `comark/devtools/vite` (Vite DevTools integration) |
 
 All are optional — only install what you use.
 
@@ -380,6 +397,13 @@ import emoji from 'comark/plugins/emoji'
 import toc from 'comark/plugins/toc'
 import alert from 'comark/plugins/alert'
 
+// Vite DevTools integration
+import { comarkDevtools } from 'comark/devtools/vite'
+// Ambient live-document context (used by renderers via comarkKey)
+import { createComarkContext } from 'comark'
+// Optional: manual bridge connect (normally injected by comarkDevtools())
+import { connectDevtools } from 'comark/devtools'
+
 // NOTE: All framework packages re-export every core plugin via their own subpath.
 // Prefer the framework-specific path when using a framework renderer:
 //   @comark/vue/plugins/highlight, @comark/react/plugins/highlight, etc.
@@ -402,7 +426,7 @@ import math, { Math } from '@comark/vue/plugins/math'
 import mermaid, { Mermaid } from '@comark/vue/plugins/mermaid'
 
 // React — renderer + plugin wrappers (plugin fn + React component)
-import { Comark, ComarkRenderer, defineComarkComponent } from '@comark/react'
+import { Comark, ComarkServer, ComarkClient, ComarkRenderer, defineComarkComponent } from '@comark/react'
 import math, { Math } from '@comark/react/plugins/math'
 import mermaid, { Mermaid } from '@comark/react/plugins/mermaid'
 

docs/content/3.rendering/5.react.md

@@ -43,10 +43,10 @@ bun add @comark/react
 
 ## `<Comark>`
 
-The `<Comark>` component is the simplest way to render markdown in React. It handles parsing and rendering automatically.
+The `<Comark>` component is the simplest way to render markdown in React. It handles parsing and rendering automatically, and works in both client-side (Vite, CRA) and server-side (Next.js) contexts.
 
-::warning{to="#code-comarkrenderer"}
-`<Comark>` is an **async** component. You can also use the `<ComarkRenderer>` component to handle parsing yourself.
+::info
+For React Server Components (Next.js `app/` directory), you can also use [`<ComarkServer>`](#code-comarkserver) to parse markdown on the server with `await`.
 ::
 
 ```tsx [App.tsx]
@@ -371,6 +371,29 @@ export default async function Page({ params }: { params: { slug: string } }) {
 
 ---
 
+## `<ComarkServer>`
+
+Async server-only component that parses markdown on the server using `await`. Only works in React Server Components (Next.js `app/` directory). For client-side usage, use [`<Comark>`](#code-comark).
+
+Accepts the same props as `<Comark>`. When `streaming` is true, it delegates to the client-side `<ComarkClient>`.
+
+```tsx [app/docs/[slug]/page.tsx]
+import { ComarkServer } from '@comark/react'
+import Alert from '@/components/Alert'
+
+export default async function Page({ params }: { params: { slug: string } }) {
+  const content = await getDocContent(params.slug)
+
+  return <ComarkServer components={{ alert: Alert }}>{content}</ComarkServer>
+}
+```
+
+::warning
+`<ComarkServer>` is an `async` function component and will throw in client-only environments (Vite, CRA). Use `<Comark>` instead for universal usage.
+::
+
+---
+
 ## `<ComarkRenderer>`
 
 Renders a pre-parsed `ComarkTree` without any parsing. Use it when you parse on the server, in a build step, or via an API, so no parser or plugin code is shipped to the browser.

docs/content/7.kb/5.devtools.md

@@ -0,0 +1,130 @@
+---
+title: Vite DevTools
+description: Interactive Comark playground panel inside Vite DevTools for real-time markdown editing and AST inspection.
+seo:
+  title: Vite DevTools Integration
+navigation:
+  icon: i-lucide-wrench
+links:
+  - label: Vite DevTools
+    icon: i-lucide-external-link
+    to: https://devtools.vite.dev/
+    color: neutral
+    variant: soft
+---
+
+Comark integrates with [Vite DevTools](https://devtools.vite.dev/) to provide an interactive playground panel for real-time markdown editing and AST inspection. This is a development tool that uses the Vite dev server's HMR and RPC capabilities.
+
+## Setup
+
+Install the `@vitejs/devtools` peer dependency alongside `comark`:
+
+::code-group
+
+```bash [pnpm]
+pnpm add -D @vitejs/devtools
+```
+
+```bash [npm]
+npm install -D @vitejs/devtools
+```
+
+```bash [yarn]
+yarn add -D @vitejs/devtools
+```
+
+::
+
+Add both plugins to your Vite config:
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite'
+import { DevTools } from '@vitejs/devtools'
+import { comarkDevtools } from 'comark/devtools/vite'
+
+export default defineConfig({
+  plugins: [
+    DevTools(),
+    comarkDevtools(),
+  ],
+})
+```
+
+> [!TIP]
+> If you use `@comark/vue`, its Vite plugin already includes `comarkDevtools()` automatically - no extra config needed:
+> ```ts [vite.config.ts]
+> import { defineConfig } from 'vite'
+> import vue from '@vitejs/plugin-vue'
+> import { DevTools } from '@vitejs/devtools'
+> import comark from '@comark/vue/vite'
+>
+> export default defineConfig({
+>   plugins: [vue(), DevTools(), comark()],
+> })
+> ```
+
+## Features
+
+### Markdown Editor
+
+The panel includes a markdown editor with [Shiki](https://shiki.style/)-powered syntax highlighting using the `mdc` grammar. A transparent `<textarea>` overlays a syntax-highlighted `<pre>` element, providing native editing (cursor, selection, undo/redo) with rich colors.
+
+Highlighting updates are near-instant (16ms debounce) via a dedicated Shiki RPC call, while instance updates are debounced at 300ms to avoid excessive parsing. If Shiki is unavailable, a regex-based fallback highlighter provides basic coloring.
+
+### AST Tab
+
+Displays the full parsed AST as syntax-highlighted JSON. Useful for understanding how Comark transforms your markdown and inspecting node structure.
+
+### Push to App
+
+When a live `<Comark>` instance is connected, edits in the devtools editor are pushed to the running application in real time. The Vite plugin parses the markdown on the server and broadcasts the updated tree to the browser via HMR, where the framework renderer (Vue, React, Svelte, or Angular) re-renders the component with the new content.
+
+Parse errors during editing (e.g. malformed frontmatter YAML) are caught gracefully - the previous tree is preserved so the editor never breaks mid-edit.
+
+### Live Instance Connection
+
+When a Comark component (`<Comark>` from `@comark/vue`, `@comark/react`, `@comark/svelte`, or `@comark/angular`) is mounted on the page, the DevTools panel automatically detects it via polling.
+
+A green dot in the instance bar indicates a connected instance. The editor loads the instance's current markdown source so you can inspect and experiment with it.
+
+## How It Works
+
+The devtools integration has three layers:
+
+| Layer | Module | Role |
+|---|---|---|
+| **Context bridge** | `comark/devtools` (`connectDevtools`) | Browser-side bridge that mirrors `globalThis.comarkContext` over HMR |
+| **Vite Plugin** | `comark/devtools/vite` | Dev server plugin that injects the client bridge and exposes RPC endpoints |
+| **Panel** | `comark/devtools/renderer` | Internal — UI panel rendered inside the Vite DevTools iframe (not intended for end users) |
+
+### Live documents (no per-renderer registration)
+
+Framework renderers never talk to devtools directly. They only subscribe to the ambient context via `comarkKey` / `meta.key`:
+
+```ts
+import { createComarkContext, parse } from 'comark'
+
+// Driver (app, collab, agent, or the Vite DevTools bridge):
+const ctx = createComarkContext() // installs globalThis.comarkContext
+const doc = ctx.get('page', await parse('# Hello'))
+
+// In the UI:
+// <ComarkRenderer :tree="tree" comark-key="page" />
+// Panel edits call doc.set(newTree); the mounted renderer re-renders.
+```
+
+When `comarkDevtools()` is in your Vite config, it injects a client entry that connects `import.meta.hot` to the ambient context — listing keys, reverse-rendering markdown for the panel, and applying panel edits via `doc.set`.
+
+### RPC Endpoints
+
+The Vite plugin registers three RPC endpoints:
+
+| Endpoint | Type | Description |
+|---|---|---|
+| `comark:highlight` | query | Syntax-highlight markdown via Shiki with the `mdc` grammar (dual light/dark themes) |
+| `comark:list-instances` | query | List all registered Comark instances on the page |
+| `comark:update-instance` | mutation | Parse markdown and broadcast the updated tree to the live instance via HMR |
+
+## Theme Support
+
+The panel includes a theme toggle (light/dark/auto) in the top-right corner. Auto mode follows the system preference via `prefers-color-scheme`.

examples/1.frameworks/nextjs/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import './.next/dev/types/routes.d.ts'
+import './.next/types/routes.d.ts'
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

examples/2.vite/angular/package.json

@@ -28,6 +28,7 @@
     "@angular/compiler": "catalog:",
     "@angular/compiler-cli": "catalog:",
     "@tailwindcss/vite": "catalog:",
+    "@vitejs/devtools": "catalog:",
     "tailwindcss": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:"

examples/2.vite/angular/vite.config.ts

@@ -1,7 +1,9 @@
+import { DevTools } from '@vitejs/devtools'
 import { defineConfig } from 'vite'
 import angular from '@analogjs/vite-plugin-angular'
 import tailwindcss from '@tailwindcss/vite'
 import { resolve } from 'node:path'
+import { comarkDevtools } from 'comark/devtools/vite'
 import type { Plugin } from 'vite'
 
 /**
@@ -56,6 +58,7 @@ function escapeRegExp(s: string): string {
 
 export default defineConfig({
   plugins: [
+    DevTools(),
     pnpmWorkspaceCompat(),
     angular({
       tsconfig: './tsconfig.json',
@@ -66,5 +69,6 @@ export default defineConfig({
       transformFilter: (_code, id) => !id.includes('/define.ts'),
     }),
     tailwindcss(),
+    comarkDevtools(),
   ],
 })

examples/2.vite/html/package.json

@@ -15,6 +15,8 @@
     "shiki": "catalog:"
   },
   "devDependencies": {
+    "@vitejs/devtools": "catalog:",
+    "comark": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:"
   }

examples/2.vite/html/vite.config.ts

@@ -1,3 +1,7 @@
+import { DevTools } from '@vitejs/devtools'
 import { defineConfig } from 'vite'
+import { comarkDevtools } from 'comark/devtools/vite'
 
-export default defineConfig({})
+export default defineConfig({
+  plugins: [DevTools(), comarkDevtools()],
+})

examples/2.vite/react/package.json

@@ -18,9 +18,11 @@
   "devDependencies": {
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
+    "@vitejs/devtools": "catalog:",
     "@vitejs/plugin-react": "catalog:",
     "autoprefixer": "catalog:",
     "postcss": "catalog:",
+    "tailwindcss": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:"
   }

examples/2.vite/react/vite.config.ts

@@ -1,7 +1,9 @@
+import { DevTools } from '@vitejs/devtools'
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
+import { comarkDevtools } from 'comark/devtools/vite'
 
 export default defineConfig({
-  plugins: [react(), tailwindcss()],
+  plugins: [DevTools(), react(), comarkDevtools(), tailwindcss()],
 })

examples/2.vite/svelte/package.json

@@ -16,7 +16,9 @@
   },
   "devDependencies": {
     "@sveltejs/vite-plugin-svelte": "catalog:",
+    "@vitejs/devtools": "catalog:",
     "autoprefixer": "catalog:",
+    "comark": "catalog:",
     "postcss": "catalog:",
     "svelte": "catalog:",
     "typescript": "catalog:",

examples/2.vite/svelte/vite.config.ts

@@ -1,7 +1,9 @@
+import { DevTools } from '@vitejs/devtools'
 import { defineConfig } from 'vite'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
 import tailwindcss from '@tailwindcss/vite'
+import { comarkDevtools } from 'comark/devtools/vite'
 
 export default defineConfig({
-  plugins: [svelte(), tailwindcss()],
+  plugins: [DevTools(), svelte(), comarkDevtools(), tailwindcss()],
 })

examples/2.vite/vue/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@comark/vue": "latest",
+    "@comark/vue": "workspace:*",
     "@nuxt/ui": "catalog:",
     "@shikijs/langs": "catalog:",
     "shiki": "catalog:",
@@ -18,6 +18,7 @@
     "vue-router": "catalog:"
   },
   "devDependencies": {
+    "@vitejs/devtools": "catalog:",
     "@vitejs/plugin-vue": "catalog:",
     "autoprefixer": "catalog:",
     "postcss": "catalog:",