@suzumiyaaoba/mdxr 0.1.0

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "@suzumiyaaoba/mdxr",
+  "version": "0.1.0",
+  "description": "Render agent-authored MDX documents (plans, reports) to standalone HTML with a semantic component catalog",
+  "keywords": [
+    "agents",
+    "cli",
+    "documentation",
+    "html",
+    "mdx",
+    "renderer",
+    "static-site"
+  ],
+  "homepage": "https://github.com/SuzumiyaAoba/mdxr#readme",
+  "bugs": "https://github.com/SuzumiyaAoba/mdxr/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SuzumiyaAoba/mdxr.git"
+  },
+  "bin": {
+    "mdxr": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./components": {
+      "types": "./dist/components.d.mts",
+      "default": "./dist/components.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.8.0",
+    "@dagrejs/dagre": "^3.1.1",
+    "@iconify-json/lucide": "1.2.130",
+    "@iconify-json/vscode-icons": "1.2.77",
+    "@iconify/react": "6.0.2",
+    "@iconify/tailwind4": "1.2.3",
+    "@mdx-js/mdx": "^3.1.1",
+    "@shadcn/react": "^0.3.1",
+    "@shikijs/transformers": "4.4.3",
+    "@tailwindcss/node": "^4.3.3",
+    "@tailwindcss/oxide": "^4.3.3",
+    "@tailwindcss/typography": "^0.5.16",
+    "cac": "^7.0.0",
+    "class-variance-authority": "^0.7.1",
+    "cmdk": "^1.1.1",
+    "cn": "^0.3.0",
+    "date-fns": "^4.4.0",
+    "embla-carousel-react": "^8.6.0",
+    "esbuild": "^0.28.2",
+    "input-otp": "^1.5.0",
+    "katex": "^0.18.7",
+    "lucide-react": "^1.45.0",
+    "react": "^19.3.0",
+    "react-day-picker": "^10.0.1",
+    "react-dom": "^19.3.0",
+    "react-resizable-panels": "^4.12.4",
+    "recharts": "^3.8.0",
+    "rehype-katex": "^7.0.1",
+    "remark-directive": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "shiki": "^4.4.3",
+    "tailwindcss": "^4.3.3",
+    "tw-animate-css": "^1.4.0",
+    "unist-util-visit": "^5.0.0",
+    "unist-util-visit-parents": "6.0.2",
+    "valibot": "^1.5.0",
+    "vfile": "^6.0.3",
+    "vfile-matter": "^5.0.1"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^5.3.1",
+    "@fontsource-variable/geist": "^5.3.0",
+    "@storybook/addon-a11y": "^10.6.0",
+    "@storybook/addon-docs": "^10.6.0",
+    "@storybook/addon-vitest": "^10.6.0",
+    "@storybook/react-vite": "^10.6.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
+    "@types/mdx": "^2.0.14",
+    "@types/node": "^22.15.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/unist": "^3.0.3",
+    "@vitest/browser-playwright": "4.1.11",
+    "@vitest/coverage-v8": "4.1.11",
+    "lefthook": "^2.1.14",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
+    "oxlint-plugin-complexity": "2.1.8",
+    "oxlint-tsgolint": "^7.0.2001",
+    "playwright": "^1.63.0",
+    "react-doctor": "^0.9.14",
+    "storybook": "^10.6.0",
+    "typescript": "^5.8.0",
+    "ultracite": "7.11.1",
+    "vite": "npm:@voidzero-dev/vite-plus-core@^0.3.2",
+    "vite-plus": "^0.3.2",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "build:examples": "pnpm build && node scripts/render-examples.ts",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit",
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "react-doctor": "react-doctor"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: mdxr
+description: Write rich plan/report documents as MDX using the mdxr component catalog, then render them to standalone HTML with `npx @suzumiyaaoba/mdxr render`. Use when creating plan files, status reports, reviews, or any structured document meant to be viewed as a styled HTML page.
+---
+
+# mdxr — agent-authored documents rendered to HTML
+
+Write documents as **Markdown + a small set of JSX components** (MDX). Do NOT write raw HTML: `mdxr render` compiles the document deterministically, so markup, styling and scripts are never emitted by the model.
+
+## Workflow
+
+1. Write the document as `*.mdx` using Markdown plus the components below.
+2. Render: `npx @suzumiyaaoba/mdxr render plan.mdx -o plan.html`
+3. Or pipe MDX directly: `cat plan.mdx | npx @suzumiyaaoba/mdxr render > plan.html` (`mdxr render -` also reads stdin; `-o out.html` writes a file).
+4. On errors, the message includes `file:line:col` — fix and re-run. `npx @suzumiyaaoba/mdxr render plan.mdx --format json` prints machine-readable errors.
+5. Preview while editing: `npx @suzumiyaaoba/mdxr serve plan.mdx` — or pipe: `cat plan.mdx | npx @suzumiyaaoba/mdxr serve`
+
+## Rules
+
+- **No JS in documents.** `import`/`export` and `{expressions}` are rejected. All attributes are strings: `<Step status="done">`, not `status={...}`.
+- Prefer plain Markdown for prose; use components only for structure.
+- If a needed component is missing, run `npx @suzumiyaaoba/mdxr catalog --json` to see the full catalog, then define it in the project's component file — see `references/extending.md` for the extension mechanism.
+- For component usage, read `references/components.md` (the index — includes a syntax cheatsheet), then only the `references/components/*.md` detail file(s) the document needs.
+
+## Component categories
+
+| Category | Covers | Details |
+| --- | --- | --- |
+| Document scaffolding | `<Plan>` root, meta row, callouts, TOC, glossary, refs, code blocks | `references/components/document.md` |
+| Planning & status | phases, steps, timeline, gantt, decisions, risks, board, matrix, stats | `references/components/planning.md` |
+| Code investigation | findings, hypotheses, terminal, traces, searches, files, flows, trees | `references/components/investigation.md` |
+| Output artifacts | diff cards, graphs, tests, endpoints, JSON, waterfalls | `references/components/output.md` |
+| Reports | code review, CI checks, vuln/dep audits, metrics, schema/env docs, status/release/incident | `references/components/reports.md` |
+| Data visualization | bar/line/pie/scatter/radar/funnel/quadrant/bridge/treemap/sankey/venn | `references/components/charts.md` |
+| Layout | columns, grid, row, stack, before/after panels | `references/components/layout.md` |
+| Reader input | `<Ask>` question forms with copyable Markdown answers | `references/components/forms.md` |
+| shadcn/ui | `Button`, `Card`, `Table`, `Tabs`, … — interactive via hydration | `references/components/shadcn.md` |
+
+## Common syntax
+
+| Write | Get |
+| --- | --- |
+| `:::note` / `:::warning` / `:::decision` / `> [!NOTE]` | `<Callout>` |
+| `:::phase{title="…" status="doing"}` | `<Phase>` heading with status badge |
+| ` ```ts title="src/x.ts" ` | highlighted code block + filename bar |
+| ` ```diff ` / ` ```mermaid ` / ` ```console ` | diff cards / diagram / terminal transcript |
+| `` `src/x.ts` `` naming a real file | `<FileRef>` chip with editor link |
+| `- [ ]` / `- [x]` | styled task list |
+| frontmatter `status:` / `date:` / `owner:` | document header badge + meta row |

package/skill/references/components/charts.md

@@ -0,0 +1,172 @@
+# Charts — quantitative data visualizations
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+Every chart renders a static SVG/HTML panel at render time — no client JS, no CDN. Containers share the same frame: an icon + `title` caption bar and an optional right-side figure (range or total + `unit`). Data comes from typed child elements (`<Bar>`, `<Slice>`, …); anything else renders below the chart.
+
+Shared conventions:
+
+- Numeric attrs accept numbers or numeric strings (`value="42"`); comma lists (`values="1,2,3"`, `labels="Mon,Tue"`) split on `,`.
+- `tone="sky|emerald|amber|violet|teal|indigo|orange|red"` pins an item's color; without it the palette cycles by position.
+- `unit="ms"` (etc.) labels values in axes, legends and tooltips; `title` sets the caption.
+- Standalone children (outside their container) degrade to a small `name value` chip instead of failing.
+
+### `<BarChart title direction series stacked max unit>` / `<Bar name value values note tone>` / `:::barchart`
+
+Categorical comparison. `<Bar name value>` needs `name` and `value` (or `values` for multi-series). `direction="horizontal"` flips to labeled rows for long names. `series="a,b"` names the `values` slots (legend + per-slot colors); `stacked` sums them into one column instead of grouping. `max` overrides the axis ceiling (defaults to a "nice" bound over the data).
+
+```mdx
+<BarChart title="deploys per quarter" unit="deploys">
+  <Bar name="Q1" value="18" />
+  <Bar name="Q2" value="26" note="launch" />
+  <Bar name="Q3" tone="emerald" value="34" />
+</BarChart>
+```
+
+```mdx
+<BarChart series="this year,last year" title="latency by endpoint" unit="ms">
+  <Bar name="/users" values="42,58" />
+  <Bar name="/search" values="120,210" />
+</BarChart>
+```
+
+### `<LineChart title labels area min max unit>` / `<Series name values tone dash>` / `:::linechart`
+
+Trend lines over evenly-spaced categories. `labels="Mon,Tue,…"` names the x slots; each `<Series values="…">` aligns with them (extra points extend the axis). The y domain snaps to round bounds — `min`/`max` pin it. `area` adds a soft fill under each line; `dash` on a series draws it dashed (baselines/targets).
+
+```mdx
+<LineChart labels="Mon,Tue,Wed,Thu,Fri" title="p95 latency" unit="ms">
+  <Series name="api" values="120,118,132,125,110" />
+  <Series name="edge" tone="emerald" values="60,58,64,70,55" />
+</LineChart>
+```
+
+### `<PieChart title donut unit>` / `<Slice name value note tone>` / `:::piechart`
+
+Part-of-whole share. `<Slice name value>` rows fill the legend with name · value · %; `donut` cuts a center hole carrying the total. Empty or all-zero data renders a neutral ring.
+
+```mdx
+<PieChart donut title="build minutes" unit="min">
+  <Slice name="compile" value="38" />
+  <Slice name="tests" value="27" />
+  <Slice name="lint" value="9" />
+</PieChart>
+```
+
+### `<Scatter title x y>` / `<Point x y name size tone>` / `:::scatter`
+
+Two-variable correlation on auto-scaled numeric axes — `x`/`y` on the container name them. `<Point>` needs `x` and `y`; `name` labels the dot, `size` turns it into a bubble (radius ∝ √size).
+
+```mdx
+<Scatter title="latency vs payload" x="payload kb" y="latency ms">
+  <Point x="12" y="40" />
+  <Point name="bulk export" size="90" tone="amber" x="140" y="210" />
+</Scatter>
+```
+
+### `<Radar title axes max unit>` / `<Series>` / `:::radar`
+
+Spider chart for multivariate comparison — needs ≥3 axes. `axes="Perf,DX,Tests"` names the corners; each `<Series>` becomes a polygon. `max` fixes the ring scale (default: largest value snapped up); ring gridlines sit at quarter steps.
+
+```mdx
+<Radar axes="Perf,DX,Tests,Docs,Security" title="service health">
+  <Series name="api" values="80,65,90,40,70" />
+  <Series name="web" tone="emerald" values="60,85,55,70,60" />
+</Radar>
+```
+
+### `<Funnel title unit>` / `<Stage name value note tone>` / `:::funnel`
+
+Stage-by-stage narrowing — centered bars shrink through `<Stage>` rows in order. Each row shows the value plus its share of the first stage; the left column carries the conversion from the previous stage when it drops.
+
+```mdx
+<Funnel title="signup funnel" unit="users">
+  <Stage name="visited" value="12800" />
+  <Stage name="signed up" value="3400" />
+  <Stage name="paid" tone="emerald" value="420" />
+</Funnel>
+```
+
+### `<Quadrant title x y quadrants>` / `<Pin name x y note tone>` / `:::quadrant`
+
+2-axis positioning map — `<Pin>` items on a 0–100 square split by midlines. `x`/`y` name the axes; `quadrants="TL,TR,BL,BR"` labels the four regions (top-left → top-right → bottom-left → bottom-right).
+
+```mdx
+<Quadrant
+  title="capability map"
+  x="adoption"
+  y="impact"
+  quadrants="invest,bet,maintain,drop"
+>
+  <Pin name="mdxr" tone="sky" x="78" y="85" />
+  <Pin name="legacy" tone="red" x="15" y="15" />
+</Quadrant>
+```
+
+### `<Bridge title unit>` / `<Delta name value note total>` / `:::bridge`
+
+Running-total waterfall — a start pillar carried to an end pillar by signed `<Delta>` contributions. Deltas float from the previous sum to the new one (emerald up / red down); `total` re-anchors the running sum at its `value` as a neutral pillar. Connector ticks link each column to the previous total.
+
+```mdx
+<Bridge title="FY revenue bridge" unit="M$">
+  <Delta name="FY24" total value="120" />
+  <Delta name="new sales" value="48" />
+  <Delta name="churn" value="-15" />
+  <Delta name="FY25" total value="175" />
+</Bridge>
+```
+
+### `<Treemap title unit>` / `<Tile name value note tone>` / `:::treemap`
+
+Part-of-whole areas packed by the squarified algorithm — `<Tile>` area ∝ `value`. Labels carry the name plus value and share percent (small tiles drop the number line).
+
+```mdx
+<Treemap title="bundle by workspace" unit="kB">
+  <Tile name="ui" value="184" />
+  <Tile name="vendor" note="react+mdx" value="260" />
+  <Tile name="cli" value="72" />
+</Treemap>
+```
+
+### `<Sankey title stages unit>` / `<Link from to value label>` + `<Node id label stage>` / `:::sankey`
+
+Quantity splitting/merging across stage columns — ribbon thickness ∝ `<Link value>`. Nodes are implicit from link endpoints; `<Node>` children (the same element `<Graph>` uses) rename them via `label`, pin a column via `stage`, or recolor via `tone`. Stage columns come from longest-path layering when not pinned; `stages="A,B,C"` titles the columns. Cycles fall back to stage 0.
+
+```mdx
+<Sankey stages="source,grid,use" title="energy flow" unit="TWh">
+  <Link from="solar" to="grid" value="40" />
+  <Link from="wind" to="grid" value="35" />
+  <Link from="grid" to="homes" value="55" />
+  <Link from="grid" to="industry" value="20" />
+</Sankey>
+```
+
+### `<Venn title unit>` / `<Set name value tone>` + `<Overlap sets value>` / `:::venn`
+
+Set overlaps — 2 or 3 `<Set>` circles (uniform size; a Venn is not to scale). `<Overlap sets="a,b" value>` prints a value at the intersection named by comma-joined set names.
+
+```mdx
+<Venn title="skill coverage" unit="devs">
+  <Set name="frontend" value="14" />
+  <Set name="backend" value="18" />
+  <Overlap sets="frontend,backend" value="6" />
+</Venn>
+```
+
+## Choosing
+
+| Data shape | Component |
+| --- | --- |
+| Category comparison, single or grouped/stacked series | `<BarChart>` |
+| Trend over ordered slots, one or more series | `<LineChart>` |
+| Shares of a total (≤ ~8 parts) | `<PieChart>` or `<Treemap>` (many/uneven parts) |
+| Two numeric variables, optional bubble | `<Scatter>` |
+| Multivariate profile on 3+ shared axes | `<Radar>` |
+| Sequential narrowing / conversion | `<Funnel>` |
+| 0–100 positioning on two named axes | `<Quadrant>` |
+| Start→deltas→end reconciliation | `<Bridge>` |
+| Flow splitting/merging between columns | `<Sankey>` |
+| 2–3 set membership overlap | `<Venn>` |
+| Timing offsets on a shared clock | `<Waterfall>` (output.md) |
+| Date-based schedule | `<Gantt>` (planning.md) |
+| Arbitrary node/edge topology | `<Graph>` (output.md) |

package/skill/references/components/document.md

@@ -0,0 +1,98 @@
+# Document scaffolding
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+### `<Plan title="…" status="…" date owner version updated>`
+
+Document root. Renders a title header with an optional status badge and a metadata row. If frontmatter `title:` exists, a header is generated automatically — frontmatter `status:`, `date:`, `owner:`, `version:` and `updated:` are picked up too.
+
+```mdx
+<Plan title="Renderer rewrite" status="doing" owner="@alice" date="2026-09-10" version="v3">
+```
+
+### `<Meta date owner version updated>` / `<MetaItem label="…" icon="…">`
+
+Document metadata row (muted line: `Date: … · Owner: …`). Usable anywhere, not only inside `<Plan>`. For custom entries nest `<MetaItem label="Spec" icon="lucide:tag">…</MetaItem>` — `MetaItem` children may contain Markdown links; `icon` takes any Iconify name (`lucide` bundled, prefix optional).
+
+### `<Callout kind="…" title="…">`
+
+Highlighted block. `:::note`, `:::warning`, `> [!NOTE]` produce the same output. Kinds: `note` `tip` `important` `warning` `caution` `danger` `decision` `goal` `nongoal` `question` `answer` — `goal`/`nongoal`/`question` cover plan-doc conventions, `answer` is the conclusion block of an investigation report. `:::non-goal` and `> [!NON-GOAL]` are aliases of `nongoal`.
+
+### `<Details summary="…" open>`
+
+Collapsible section on a native `<details>` element — opens/closes even without client JS (unlike the shadcn `Collapsible`, which needs the hydration bundle). `open` starts it expanded.
+
+### `<Toc depth="3" min="2" title="Contents" open />` / `:::toc`
+
+Table of contents auto-built from the document's headings (h2–h3 by default — h1 is the document title). Headings always get slug `id`s, so `[link](#slug)` deep links work anywhere. Renders as a collapsible outline — numbered top-level entries, guide-lined nesting — on a native `<details>` (works without JS); `open="false"` starts it folded.
+
+### `<Glossary>` / `<Term name="…">`
+
+Definition list (`<dl>`) for domain terms. `name` is the term; children are the definition.
+
+### `<Figure src="…" alt="…" caption="…">`
+
+Image with an optional caption (children work too). Use for screenshots or diagrams mermaid can't express.
+
+### `<Ref href="…" title="…">` / `<Issue repo="o/r" number="12">` / `<PR repo="o/r" number="5">` / `<Commit repo="o/r" sha="…">`
+
+`Ref` is a linked reference card (use for a "References" section). `Issue`/`PR`/`Commit` are inline chips linking to `github.com/{repo}/issues|pull|commit/{id}` — `repo` may also be `host/owner/repo` or a full URL for GitHub Enterprise. `Commit` displays the first 7 chars of `sha`, children become the title; `href` overrides the URL.
+
+### `<Cmd>`
+
+Inline command chip — terminal icon + copy button.
+
+```mdx
+Run <Cmd>pnpm build</Cmd> then <Cmd>mdxr render plan.mdx</Cmd>.
+```
+
+### `<Icon name="lucide:rocket" label className />`
+
+Inline Iconify icon rendered as SVG — no runtime fetch. The `lucide` and `vscode-icons` sets are bundled; the `lucide:` prefix may be omitted (`name="check"`). Unknown names are render-time validation errors. Decorative by default (`aria-hidden`); pass `label` to expose it as an image with `aria-label`. Size and color come from `className` (`h-4 w-4 text-teal-500`).
+
+Status badges, step markers, callouts, chips and the file tree all carry appropriate icons automatically.
+
+```mdx
+Launch checklist <Icon name="lucide:rocket" className="h-4 w-4" />
+```
+
+Icons also work as CSS classes (mask-image, single-color) on any element:
+
+```mdx
+<span className="icon-[lucide--github] h-5 w-5" />
+```
+
+### Fenced code
+
+````
+```ts title="src/cli.ts"
+…
+```
+````
+
+renders a framed block with filename + copy button; the header carries a file-type icon picked from the filename (or language), and links to the file in your editor when it exists on disk (see "File links" in [../components.md](../components.md)). Code is syntax-highlighted with Shiki (light/dark dual theme), so always tag the fence with a language (`ts`, `python`, `diff`, …). ` ```mermaid ` renders a diagram.
+
+The fence meta also controls line presentation:
+
+````
+```ts {1,3-4} ln title="src/cli.ts"
+…
+```
+````
+
+- `{1,3-4}` highlights those lines; `/pattern/` highlights every match (word highlight).
+- `ln` shows line numbers (also `line-numbers`, `lineNumbers`, `showLineNumbers`).
+
+Inside the code, `// [!code …]` markers annotate lines and are stripped from output:
+
+| Marker | Effect |
+| --- | --- |
+| `// [!code hl]` / `// [!code highlight]` | highlight the line |
+| `// [!code ++]` / `// [!code --]` | green/red diff rows (works in any language) |
+| `// [!code warning]` / `// [!code error]` | amber/red line bands |
+| `// [!code focus]` | dim all other lines |
+| `// [!code word:foo]` | highlight every `foo` occurrence |
+
+### Math
+
+`$…$` inline and `$$…$$` blocks render via KaTeX (stylesheet from CDN, only linked when math is present).

package/skill/references/components/forms.md

@@ -0,0 +1,35 @@
+# Reader input components
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+### `<Ask title description>` / `<Question name type label>` / `<Choice value checked>`
+
+Question block that asks the reader for input — open decisions in a plan, sign-off toggles, free-form answers. Built on **native** form controls (unlike the shadcn set), so every field is interactive in the static document. Answers render live as a Markdown sheet in the block's output pane — `# title` then `- **label**: answer` per question — which "Copy answers" copies to the clipboard and "Save .md" downloads as a file the user can keep or paste back.
+
+`<Question>` `type`: `choice` (radio cards), `multi` (checkbox cards), `select` (dropdown), `text`, `textarea`, `toggle` (switch). Default: `choice` when it has `<Choice>` children, else `text`. `name` is the answer key; `label`, `description`, `required`, `placeholder`, `value` (text default), `rows` (textarea), `checked` (toggle) are supported.
+
+```mdx
+<Ask title="確認事項" description="プランに反映します">
+  <Question name="approach" type="choice" label="実装方針" required>
+    <Choice value="gradual" checked>
+      段階的移行
+    </Choice>
+    <Choice value="rewrite" description="ロールバック経路が必要">
+      一括書き換え
+    </Choice>
+  </Question>
+  <Question name="scope" type="multi" label="含める範囲">
+    <Choice value="api" checked>
+      API
+    </Choice>
+    <Choice value="ui">UI</Choice>
+  </Question>
+  <Question name="prio" type="select" label="優先度" placeholder="選択">
+    <Choice value="high">高</Choice>
+    <Choice value="mid">中</Choice>
+  </Question>
+  <Question name="deadline" type="text" label="期限" placeholder="YYYY-MM-DD" />
+  <Question name="notes" type="textarea" label="補足" rows="2" />
+  <Question name="preview" type="toggle" label="プレビュー環境を作る" checked />
+</Ask>
+```