mdx-artifacts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdx-artifacts contributors
+
+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,234 @@
+# MDX Artifacts
+
+Interactive MDX artifacts for agents.
+
+MDX Artifacts lets an agent write structured MDX with reusable React components, then compile it into a standalone HTML artifact that can be opened locally in a browser.
+
+The goal is not to make agents generate raw HTML from scratch. The goal is to make agents call stable, high-level components:
+
+```mdx
+import { DecisionMatrix, ExportPanel } from "mdx-artifacts/react";
+
+<DecisionMatrix
+  question="Should stage one focus on a Vite single HTML artifact?"
+  options={[
+    {
+      name: "Vite single HTML artifact",
+      pros: ["Short feedback loop", "Fits one-off tool artifacts"],
+      cons: ["No docs-site navigation yet"],
+      verdict: "Recommended for stage one"
+    }
+  ]}
+/>
+
+<ExportPanel
+  title="Export decision"
+  formats={["markdown", "json"]}
+  value={{ recommendation: "Start with a single HTML artifact." }}
+/>
+```
+
+The CLI turns that MDX file into a self-contained HTML file.
+
+## Current Scope
+
+The first stage focuses on the smallest useful loop:
+
+1. `artifact-docs/**/*.mdx` is the source format.
+2. `src/react` provides high-level artifact components.
+3. `src/cli` provides `init`, `components`, `validate`, `dev`, `build`, and narrow review-state commands.
+4. `components` exposes component props and examples for agents.
+5. `build` outputs a standalone HTML artifact.
+
+Astro is intentionally not part of the core yet. It can become a later adapter for long-lived docs sites.
+
+## Install
+
+Install in a project that should build local artifacts:
+
+```bash
+pnpm add mdx-artifacts react react-dom
+```
+
+Initialize a workspace:
+
+```bash
+pnpm exec artifact-kit init
+```
+
+This creates:
+
+```text
+artifact-kit.config.mjs
+artifact-docs/examples/hello.mdx
+agents/AGENTS.snippet.md
+```
+
+Build the initialized example:
+
+```bash
+pnpm exec artifact-kit validate artifact-docs/examples/hello.mdx
+pnpm exec artifact-kit build artifact-docs/examples/hello.mdx
+```
+
+Default output:
+
+```text
+dist/artifacts/examples/hello.html
+```
+
+## CLI
+
+Inspect available components:
+
+```bash
+pnpm exec artifact-kit components
+pnpm exec artifact-kit components ExportPanel
+pnpm exec artifact-kit components --json
+```
+
+Build one MDX file:
+
+```bash
+pnpm exec artifact-kit build artifact-docs/examples/hello.mdx
+```
+
+## Review State
+
+Artifact Kit can keep local review threads beside an MDX file while the dev server is running. Review state is stored in a sibling `.state.json` file:
+
+```text
+artifact-docs/examples/hello.mdx
+artifact-docs/examples/hello.state.json
+```
+
+Use stable anchors in MDX so review threads can survive edits:
+
+```mdx
+import { DecisionMatrix, Section } from "mdx-artifacts/react";
+
+<Section id="section.context">
+
+## Context
+
+Native MDX prose can be reviewed through the section anchor.
+
+</Section>
+
+<DecisionMatrix
+  id="decision.stage-one"
+  question="Should this artifact use stable anchors?"
+  options={[
+    {
+      id: "yes",
+      name: "Use stable anchors",
+      verdict: "Recommended"
+    }
+  ]}
+/>
+```
+
+Agents can add a user thread, append an assistant reply, and validate that saved threads still point at anchors in the current MDX:
+
+```bash
+pnpm exec artifact-kit review add artifact-docs/examples/hello.mdx \
+  --anchor decision.stage-one \
+  --body "Clarify this decision."
+
+pnpm exec artifact-kit review reply artifact-docs/examples/hello.mdx \
+  --thread thr_decision_stage_one \
+  --body "Updated the decision copy." \
+  --status resolved
+
+pnpm exec artifact-kit review validate artifact-docs/examples/hello.mdx
+```
+
+Review commands read and write the sibling `.state.json` file for the source MDX. They do not edit the MDX source. `review validate` checks whether saved review threads still point at anchors that exist in the current MDX.
+
+When an anchor is removed from MDX, the browser review layer keeps the thread visible as an unplaced comment instead of deleting it. The CLI reports the same problem:
+
+```text
+review validate failed
+missing: 1
+- thread: thr_removed anchorId: comparison.removed status: open title: Removed comparison
+```
+
+Resolve missing anchors by restoring the old id, migrating the thread to a new anchor, or marking the thread resolved with an assistant reply that explains the structural change.
+
+## Repository Development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Validate and build the repository example artifact:
+
+```bash
+pnpm check
+pnpm artifact:validate
+pnpm artifact:build
+```
+
+Develop components in Storybook:
+
+```bash
+pnpm storybook
+```
+
+Storybook is only for component development. The artifact workflow is still verified through `artifact-kit validate/build`.
+
+Run the test baseline:
+
+```bash
+pnpm test
+pnpm typecheck
+pnpm artifact:validate
+```
+
+Run the package smoke test before publishing:
+
+```bash
+pnpm pack:smoke
+```
+
+## Style Injection
+
+Artifact Kit injects default styles by default. Users can add brand styles through `artifact-kit.config.mjs`:
+
+```js
+/** @type {import("mdx-artifacts").ArtifactKitConfig} */
+const config = {
+  docsDir: "artifact-docs",
+  outDir: "dist/artifacts",
+  includeDefaultStyles: true,
+  styles: ["artifact-theme.css"]
+};
+
+export default config;
+```
+
+Custom styles are imported after the default styles, so they can override CSS variables or `ak-*` classes. Set `includeDefaultStyles: false` to fully own the styling.
+
+## Design Principles
+
+- Source files are MDX, not raw HTML.
+- Component APIs should be semantic and self-describing.
+- Interactive artifacts must provide an export path.
+- Bulky data should live in adjacent JSON files instead of JSX props.
+- Core components stay React/TypeScript and should be reusable from Vite, Astro, or artifact builders.
+- Tailwind is an internal styling build tool; the final artifact still inlines CSS.
+- Radix primitives are introduced only when complex interactions need them.
+- shadcn/ui and daisyUI are not core dependencies; they may become optional templates or registries later.
+- Basic tests protect registry metadata, controlled text rendering, CLI component lookup, and MDX validation.
+
+## Documentation
+
+- [Roadmap](ROADMAP.md)
+- [Design notes](docs/design.md)
+- [Naming conventions](docs/naming.md)
+- [Component protocol](docs/component-protocol.md)
+- [Component taxonomy](docs/component-taxonomy.md)
+- [Testing](docs/testing.md)
+- [Chinese README](README.zh-CN.md)

package/README.zh-CN.md

@@ -0,0 +1,129 @@
+# MDX Artifacts
+
+一个面向 Agent 的交互式 MDX artifact 工具原型。
+
+目标不是让模型每次生成一整份裸 HTML，而是让模型写较稳定的 MDX：
+
+```mdx
+import { DecisionMatrix, ExportPanel } from "../../src/react";
+
+<DecisionMatrix
+  question="是否先用 Vite 跑通单 HTML artifact？"
+  options={[
+    {
+      name: "先做 Vite 单页",
+      pros: ["闭环短", "更贴近交互工具"],
+      cons: ["暂时没有文档站导航"],
+      verdict: "第一阶段推荐"
+    }
+  ]}
+/>
+
+<ExportPanel
+  title="导出决策"
+  formats={["markdown", "json"]}
+  value={{ recommendation: "先做单 HTML artifact" }}
+/>
+```
+
+再由 CLI 输出一个可在浏览器中直接打开的 HTML artifact。
+
+## 当前阶段
+
+第一阶段只做最小闭环：
+
+1. `artifact-docs/**/*.mdx` 作为源文件。
+2. `src/react` 提供高阶组件。
+3. `src/cli` 提供 `dev`、`build`、`validate`、`init`。
+4. CLI 提供 `components` 查询组件参数和示例。
+5. `build` 输出单个 self-contained HTML 文件。
+6. `InlineText` / `MarkdownBody` 提供受控的文本渲染边界。
+
+暂不把核心绑定到 Astro。Astro 后续只作为“结构化文档站 adapter”加入。
+
+## 命令
+
+安装依赖后：
+
+```bash
+pnpm check
+pnpm artifact:validate
+pnpm artifact:dev
+pnpm artifact:build
+pnpm storybook
+```
+
+查询组件：
+
+```bash
+pnpm artifact components
+pnpm artifact components ExportPanel
+pnpm artifact components --json
+```
+
+单文件构建：
+
+```bash
+pnpm artifact build artifact-docs/examples/decision-matrix.mdx
+```
+
+默认输出：
+
+```text
+dist/artifacts/examples/decision-matrix.html
+```
+
+组件开发：
+
+```bash
+pnpm storybook
+```
+
+Storybook 只用于隔离调试 React 组件；最终 artifact 闭环仍以 `artifact-kit validate/build` 为准。
+
+基础测试：
+
+```bash
+pnpm test
+pnpm typecheck
+pnpm artifact:validate
+```
+
+## 样式注入
+
+默认情况下，Artifact Kit 会注入内置样式。使用者可以在 `artifact-kit.config.ts` 里追加自己的品牌 CSS：
+
+```ts
+import type { ArtifactKitConfig } from "./src/cli/types";
+
+const config: ArtifactKitConfig = {
+  docsDir: "artifact-docs",
+  outDir: "dist/artifacts",
+  includeDefaultStyles: true,
+  styles: ["artifact-theme.css"]
+};
+
+export default config;
+```
+
+`styles` 会在默认样式之后导入，因此可以覆盖 CSS variables 或 `ak-*` class。若要完全接管样式，可以设置 `includeDefaultStyles: false`。
+
+## 设计原则
+
+- 源文件是 MDX，不是裸 HTML。
+- 组件 API 要语义化，避免让 Agent 手写布局。
+- 交互工具必须提供导出能力。
+- 大数据后续应放到相邻 JSON 文件，不要塞进 MDX props。
+- 核心组件保持 React/TypeScript，可被 Vite、Astro、Claude artifact builder 复用。
+- Tailwind 作为内部样式构建能力，最终仍输出内联 CSS 的单 HTML。
+- Radix 只按需用于复杂交互 primitives，不把 shadcn/ui 或 daisyUI 作为核心依赖。
+- 基础测试覆盖 registry 元数据、受控文本渲染、CLI 组件查询和 MDX validate。
+
+## 后续阶段
+
+- [公开路线图](ROADMAP.md)
+- [设计说明](docs/design.zh-CN.md)
+- [英文命名规范](docs/naming.md)
+- [英文组件协议](docs/component-protocol.md)
+- [英文组件分类](docs/component-taxonomy.md)
+- [英文测试协议](docs/testing.md)

package/agents/AGENTS.snippet.md

@@ -0,0 +1,13 @@
+# Artifact Kit Agent Instructions
+
+When creating an interactive report, option comparison, temporary tool, or visual explanation page:
+
+1. Do not generate raw HTML unless explicitly requested.
+2. Create `.mdx` files under `artifact-docs/`.
+3. Prefer high-level components from `mdx-artifacts/react`.
+4. Interactive artifacts must include `ExportPanel` or an equivalent export path.
+5. Do not inline bulky data in JSX props. Prefer adjacent `.json` files.
+6. Run `artifact-kit components <ComponentName>` when component props are unclear.
+7. Run `artifact-kit components --json` when machine-readable component metadata is needed.
+8. Run `artifact-kit validate <file.mdx>` before build.
+9. Run `artifact-kit build <file.mdx>` to produce standalone HTML.

package/artifact-docs/examples/commentable-feedback.mdx

@@ -0,0 +1,126 @@
+import {
+  Callout,
+  CommentTarget,
+  DecisionMatrix,
+  ExportPanel,
+  OptionGrid,
+  Section,
+} from "mdx-artifacts/react";
+
+# Commentable Artifact Feedback
+
+This example shows a local block-level comment loop. The author marks stable review targets with `Section` or component ids, the reader adds comments in the browser, and artifact state is saved beside the MDX file during local dev.
+
+<DecisionMatrix
+  id="decision.comment-targets"
+  question="Should comment targets be explicit blocks in v1?"
+  options={[
+    {
+      id: "explicit",
+      name: "Explicit comment blocks",
+      summary:
+        "Authors wrap reviewable sections with a stable block id and title.",
+      pros: [
+        "Stable export target",
+        "Works for prose and components",
+        "Does not change existing component props",
+      ],
+      cons: ["Adds one wrapper around reviewable regions"],
+      confidence: "high",
+      verdict: "Recommended for v1",
+    },
+    {
+      id: "implicit",
+      name: "Implicit component comments",
+      summary: "Every artifact component becomes commentable by default.",
+      pros: ["Less explicit authoring syntax"],
+      cons: [
+        "Cannot naturally target prose",
+        "Requires changing many component APIs",
+      ],
+      confidence: "medium",
+      verdict: "Defer until block comments prove useful",
+    },
+  ]}
+/>
+
+<Section id="section.prose-guidance">
+
+## Prose guidance
+
+A section target gives the exported state enough context for the next agent turn without requiring text selection or component internals.
+
+Use section comments when feedback should attach to a visible native MDX region:
+
+- a short prose explanation
+  - a nested supporting point
+    - a deeper supporting point
+- a paragraph plus a list
+- a decision summary before a component
+- a custom composed section boundary
+
+1. First ordered list item
+   1. Nested ordered list item
+   2. Another nested ordered item
+2. Second ordered list item
+
+</Section>
+
+<OptionGrid
+  id="option.comment-flow"
+  title="Comment workflow pieces"
+  options={[
+    {
+      id: "layer",
+      name: "CommentLayer",
+      intent:
+        "The artifact shell now provides this review context automatically.",
+      tradeoffs: [
+        "No production backend",
+        "Local dev persists to sidecar state",
+      ],
+    },
+    {
+      id: "section",
+      name: "Section",
+      intent:
+        "Marks native MDX prose with a stable anchor id while keeping native headings in the section body.",
+      tradeoffs: [
+        "Clear review context",
+        "Authors choose the section boundary",
+      ],
+    },
+    {
+      id: "export",
+      name: "ExportPanel",
+      intent: "Exports the artifact result when a static handoff is needed.",
+      tradeoffs: [
+        "Agent-friendly handoff",
+        "State is handled by the local dev shell",
+      ],
+    },
+  ]}
+/>
+
+<CommentTarget
+  targetId="custom-comment-target"
+  title="Custom comment target"
+  description="A hand-authored target for content that is not inside a built-in component."
+>
+  <Callout
+    id="callout.custom-target"
+    tone="warning"
+    title="Custom targets still work"
+    body="Use CommentTarget when an artifact has a smaller local region that should be commentable without turning the whole section into a target."
+  />
+</CommentTarget>
+
+<ExportPanel
+  title="Export artifact feedback"
+  value={{
+    recommendation:
+      "Use explicit comment targets first, then evaluate implicit Markdown comments.",
+    reviewModel: "One comment per target",
+    nextStep: "Validate Section around native MDX prose blocks and unplaced comments",
+  }}
+/>

package/artifact-docs/examples/decision-matrix.mdx

@@ -0,0 +1,80 @@
+import { DecisionMatrix, ExportPanel, OptionGrid } from "mdx-artifacts/react";
+
+# Artifact Kit Stage One Decision
+
+<DecisionMatrix
+  id="decision.stage-one"
+  question="Should stage one focus on a **Vite single HTML artifact** instead of starting with an Astro docs site?"
+  options={[
+    {
+      id: "vite",
+      name: "**Vite** single HTML artifact",
+      summary: "Validate the shortest `MDX -> HTML` loop first.",
+      pros: ["Shortest loop", "Direct interactive component debugging", "Fits one-off tool artifacts"],
+      cons: ["No docs-site navigation yet", "Weaker long-term archive experience"],
+      confidence: "high",
+      verdict: "Recommended for stage one"
+    },
+    {
+      id: "astro",
+      name: "Astro docs site",
+      summary: "Turn the artifact-docs tree into a structured static docs site.",
+      pros: ["Better long-term reading experience", "File-based pages", "Good for archives"],
+      cons: ["Too heavy for stage one", "Mixes component protocol work with docs-site engineering"],
+      confidence: "medium",
+      verdict: "Add in stage two"
+    },
+    {
+      id: "raw-html",
+      name: "Raw HTML",
+      summary: "Let agents generate complete HTML directly.",
+      pros: ["No toolchain", "Fast for very small throwaway pages"],
+      cons: ["Duplicated code", "Style drift", "~~Reusable~~ export behavior is hard to reuse"],
+      confidence: "low",
+      verdict: "Keep only as fallback"
+    }
+  ]}
+/>
+
+<OptionGrid
+  id="option.first-components"
+  title="First component scope"
+  options={[
+    {
+      id: "decision-matrix",
+      name: "DecisionMatrix",
+      intent: "Compare options",
+      tradeoffs: ["Stable **decision** structure", "Does not own complex interaction"]
+    },
+    {
+      id: "option-grid",
+      name: "OptionGrid",
+      intent: "Show alternatives side by side",
+      tradeoffs: ["Easy to scan", "Can add selection later"]
+    },
+    {
+      id: "export-panel",
+      name: "ExportPanel",
+      intent: "Return conclusions or edits to the workflow",
+      tradeoffs: ["Copy-only in v1", "Can add file download later"]
+    }
+  ]}
+/>
+
+<ExportPanel
+  title="Export recommendation"
+  formats={["markdown", "json"]}
+  value={{
+    recommendation: "Start with Vite + React + MDX to single HTML artifact.",
+    reasons: [
+      "Validate the high-level component protocol and exporter first.",
+      "Avoid binding the core to Astro docs-site structure too early.",
+      "The same MDX tree can still feed an Astro template later."
+    ],
+    nextSteps: [
+      "Keep CLI validate/build/dev reliable.",
+      "Ensure the example MDX outputs standalone HTML.",
+      "Design the Astro adapter after the component protocol stabilizes."
+    ]
+  }}
+/>