mdx-artifacts 0.1.0

package/docs/design.md

@@ -0,0 +1,239 @@
+# MDX Artifacts Design Notes
+
+## Language Policy
+
+For open source and npm publishing:
+
+- Code, types, runtime UI, CLI output, and error messages are English-first.
+- `componentRegistry` is English because it is consumed by the CLI, agents, and future generated docs.
+- `artifact-docs/examples` is English because examples double as public fixtures.
+- `agents/AGENTS.snippet.md` is English so it does not impose a local language preference on user projects.
+- `README.md` is English-first.
+- Chinese notes live in `README.zh-CN.md` and `docs/design.zh-CN.md`.
+
+## Background
+
+The value of an HTML artifact is not that it replaces Markdown. Its value is that comparison, tuning, sorting, exporting, and visual explanation workflows can become directly operable interfaces.
+
+Asking an agent to generate raw HTML for every artifact has recurring problems:
+
+- High token cost.
+- Repeated layout and interaction code.
+- Inconsistent export behavior.
+- Poor diff quality.
+- Throwaway pages rarely become reusable workflow assets.
+
+This project keeps MDX as the source format and lets agents call reusable high-level components. The output is a standalone HTML artifact.
+
+## Architecture
+
+### 1. Component Protocol
+
+The core asset is the high-level component protocol, not a specific frontend shell.
+
+First-stage components:
+
+- `InlineText`: short text with controlled inline Markdown.
+- `MarkdownBody`: controlled component-local body Markdown.
+- `DecisionMatrix`: compare options.
+- `OptionGrid`: show alternatives side by side.
+- `ExportPanel`: export Markdown or JSON.
+
+Planned components:
+
+- `PriorityBoard`: drag-and-drop priority sorting.
+- `PromptWorkbench`: prompt variables and sample previews.
+- `DiffExplainer`: PR and diff explanation.
+- `ParameterTuner`: parameter tuning UI.
+
+### 2. Build Layer
+
+Stage one uses Vite, React, and MDX:
+
+```text
+artifact-docs/foo.mdx
+  -> Vite bundle
+  -> inline JS/CSS/assets
+  -> dist/artifacts/foo.html
+```
+
+The goal is to validate the single HTML artifact loop before building a docs site.
+
+### 3. Docs Site Layer
+
+Stage two can add an Astro adapter:
+
+```text
+artifact-docs/
+  decisions/auth.mdx
+  pr-reviews/backpressure.mdx
+
+-> Astro adapter
+
+dist/site/
+  decisions/auth/index.html
+  pr-reviews/backpressure/index.html
+```
+
+Astro is a good fit for long-lived documentation, but it should not define the core component API.
+
+## Why Not Bind the Core to Astro
+
+Astro is useful for long-lived MDX documentation:
+
+- MDX files can map naturally to pages.
+- Layouts, frontmatter, routing, and static output are built in.
+- Documentation archives become easier to maintain.
+
+But it is not the right core abstraction for one-off artifacts:
+
+- It is heavier than needed for temporary interactive tools.
+- Agents need to understand Astro-specific `client:*` directives.
+- High-level artifact components should remain portable.
+
+Current strategy:
+
+```text
+Core asset: React components + exporter protocol
+First target: Vite single HTML artifact
+Second target: Astro docs site
+```
+
+## Styling Protocol
+
+Artifact Kit provides default CSS, but the default theme is not part of the core artifact contract.
+
+Users can inject 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"]
+};
+```
+
+Rules:
+
+- `includeDefaultStyles: true` imports Artifact Kit default styles first.
+- `styles` are imported in array order after the default styles.
+- Users can override CSS variables or `ak-*` classes.
+- `includeDefaultStyles: false` means the user owns all styling.
+- The final CSS is still inlined into the standalone HTML artifact.
+
+## UI Dependencies
+
+The current route is intentionally light:
+
+- Tailwind is an internal styling build tool.
+- Radix primitives are added only for complex headless interactions.
+- shadcn/ui is not a runtime dependency; it may become a future registry/template option.
+- daisyUI is not a core dependency; it may become a future demo theme/template.
+
+## Component Development
+
+Storybook is a development dependency for isolated component previews.
+
+Storybook is responsible for:
+
+- Showing component states.
+- Debugging long text, empty data, and narrow layouts.
+- Providing public component examples.
+
+Storybook is not responsible for:
+
+- Compiling MDX artifacts.
+- Producing standalone HTML.
+- Managing agent workflows.
+- Replacing a future Astro docs site.
+
+Current workflow:
+
+```text
+Component development: pnpm storybook
+Protocol verification: pnpm typecheck / pnpm test / pnpm artifact:validate
+Artifact verification: pnpm artifact:build
+```
+
+## Testing Protocol
+
+The first test baseline protects the component protocol rather than browser behavior.
+
+Current coverage:
+
+- registry metadata contract
+- `InlineText` and `MarkdownBody` controlled Markdown rendering
+- CLI component lookup output
+- MDX validation rules
+
+The operational testing path lives in `docs/testing.md`.
+
+Out of scope for the first baseline:
+
+- browser E2E
+- visual regression
+- Astro adapter tests
+- package tarball smoke tests
+
+## Agent Contract
+
+When generating an artifact, agents should:
+
+1. Create `.mdx` files instead of raw HTML.
+2. Prefer existing high-level components.
+3. Provide an export path for interactive artifacts.
+4. Move bulky data into adjacent `.json` files.
+5. Run `artifact-kit components <ComponentName>` when props are unclear.
+6. Run `artifact-kit components --json` for machine-readable metadata.
+7. Run `artifact-kit validate <file.mdx>` before build.
+8. Run `artifact-kit build <file.mdx>` to produce standalone HTML.
+
+## CLI Component Query
+
+To keep skills and agent instructions short, the CLI exposes component metadata:
+
+```bash
+artifact-kit components
+artifact-kit components ExportPanel
+artifact-kit components --json
+artifact-kit components ExportPanel --json
+```
+
+The data comes from `componentRegistry`. Future docs, Storybook docs, validation rules, and agent skills should derive from the same source.
+
+Component naming rules:
+
+- Names must be self-describing, such as `DecisionMatrix` and `ExportPanel`.
+- Avoid generic names such as `Panel` or `CardList`.
+- A component should represent an artifact workflow, not a primitive UI element.
+- Text rendering is intentionally split into `InlineText`, `MarkdownBody`, and future long-form prose components.
+
+## Public Roadmap and Local Execution Notes
+
+Public project direction lives in:
+
+- `ROADMAP.md`
+- `docs/design.md`
+- `docs/naming.md`
+- `docs/component-protocol.md`
+- `docs/component-taxonomy.md`
+- `docs/testing.md`
+
+Local phase execution notes belong in `docs/local/*.local.md` and are not committed. They can track temporary decisions, verification notes, and agent working state without adding process noise to the public repository.
+
+## Success Criteria
+
+Stage one is complete when:
+
+- Example MDX passes validation.
+- Example MDX can be previewed locally.
+- Example MDX builds into standalone HTML.
+- The HTML opens directly and supports copy/export.
+
+Stage two is complete when:
+
+- The `artifact-docs` tree can generate a static docs site.
+- The docs site uses the same high-level components.
+- Single artifacts and the docs site share the same source files.

package/docs/design.zh-CN.md

@@ -0,0 +1,217 @@
+# MDX Artifacts 设计说明
+
+## 语言策略
+
+面向开源和 npm 发布时，项目语言边界如下：
+
+- 代码、类型、运行时 UI、CLI 输出、错误信息使用英文。
+- `componentRegistry` 使用英文，因为它会被 CLI、Agent 和未来文档生成共同消费。
+- `artifact-docs/examples` 使用英文，作为开源示例和测试素材。
+- `agents/AGENTS.snippet.md` 使用英文，避免下发给用户项目后造成语言预设。
+- `README.md` 英文优先，中文内容放在 `README.zh-CN.md`。
+- `docs/design.md` 英文优先，中文设计备忘放在 `docs/design.zh-CN.md`。
+
+这个约定的目标是：开源用户看到的默认行为是英文，同时保留中文文档服务当前产品和架构讨论。
+
+## 背景
+
+HTML artifact 的价值不在于替代 Markdown，而在于把一些阅读、比较、调参、排序、导出类任务变成可操作界面。
+
+直接让 Agent 生成裸 HTML 有几个问题：
+
+- Token 成本高。
+- 样式和交互重复生成。
+- 导出逻辑不稳定。
+- HTML diff 不适合长期维护。
+- 一次性页面难以沉淀成工作流资产。
+
+本项目的判断是：保留 MDX 作为源文件，让 Agent 调用预置高阶组件，最终编译成 HTML artifact。
+
+## 三层架构
+
+### 1. 组件协议层
+
+核心资产是高阶组件和数据协议，而不是某个前端框架壳。
+
+第一批组件：
+
+- `InlineText`：单行短文本，支持受控 inline Markdown。
+- `MarkdownBody`：组件内部正文，支持受控 block Markdown。
+- `DecisionMatrix`：方案比较。
+- `OptionGrid`：多个方案并排展示。
+- `ExportPanel`：导出 Markdown / JSON。
+
+后续组件：
+
+- `PriorityBoard`：任务拖拽排序。
+- `PromptWorkbench`：提示词变量和样例预览。
+- `DiffExplainer`：PR / diff 解释。
+- `ParameterTuner`：参数调试器。
+
+### 2. 构建层
+
+第一阶段使用 Vite + React + MDX：
+
+```text
+artifact-docs/foo.mdx
+  -> Vite bundle
+  -> inline JS/CSS/assets
+  -> dist/artifacts/foo.html
+```
+
+这个阶段的目标是验证单个 HTML artifact 闭环，不做文档站。
+
+### 3. 文档站层
+
+第二阶段提供 Astro template：
+
+```text
+artifact-docs/
+  decisions/auth.mdx
+  pr-reviews/backpressure.mdx
+
+-> Astro adapter
+
+dist/site/
+  decisions/auth/index.html
+  pr-reviews/backpressure/index.html
+```
+
+Astro 适合长期文档库，但不应该决定核心组件 API。
+
+## 为什么不先绑定 Astro
+
+Astro 的优点：
+
+- MDX 文件天然适合作为页面。
+- 多页面、layout、frontmatter、静态输出更完整。
+- 适合长期开发文档站。
+
+Astro 的代价：
+
+- 对一次性交互工具偏重。
+- Agent 需要理解 `client:*` 这类 Astro 特有规则。
+- 高阶组件本身不应该依赖 Astro。
+
+所以当前策略是：
+
+```text
+核心资产：React 高阶组件 + exporter 协议
+第一出口：Vite 单 HTML artifact
+第二出口：Astro 文档站
+```
+
+## UI 依赖边界
+
+当前采用“Tailwind + Radix primitives”的轻量路线。
+
+## 样式协议
+
+Artifact Kit 提供默认 CSS，但默认样式不是闭环的一部分。
+
+使用者可以通过 `artifact-kit.config.ts` 注入品牌样式：
+
+```ts
+const config = {
+  docsDir: "artifact-docs",
+  outDir: "dist/artifacts",
+  includeDefaultStyles: true,
+  styles: ["artifact-theme.css"]
+};
+```
+
+约定：
+
+- `includeDefaultStyles: true` 时，先导入 Artifact Kit 默认样式。
+- `styles` 按数组顺序在默认样式之后导入。
+- 使用者可以通过覆盖 CSS variables 或 `ak-*` class 调整品牌。
+- `includeDefaultStyles: false` 表示完全接管样式。
+- CLI 构建仍会把最终 CSS 内联到单文件 HTML。
+
+### Tailwind 的角色
+
+Tailwind 是 artifact-kit 内部的样式生产工具，不要求用户项目自己配置 Tailwind。
+
+### Radix 的角色
+
+Radix 只作为按需引入的 headless primitives，用于 Tabs、Dialog、Tooltip、Select、Accordion 这类复杂交互。
+
+第一阶段只在 `ExportPanel` 中使用 `@radix-ui/react-tabs` 验证集成边界。
+
+## 组件开发方式
+
+当前引入 Storybook 作为开发依赖，用于隔离调试 React 高阶组件。
+
+Storybook 不负责：
+
+- 编译 MDX artifact。
+- 输出单文件 HTML。
+- 管理 Agent 工作流。
+- 替代后续 Astro 文档站。
+
+因此当前工作方式是：
+
+```text
+组件开发：pnpm storybook
+协议验证：pnpm typecheck / pnpm test / pnpm artifact:validate
+artifact 验证：pnpm artifact:build
+```
+
+## 测试协议
+
+第一版测试基线先保护组件协议，不直接进入浏览器 E2E。
+
+当前覆盖：
+
+- registry 元数据约束
+- `InlineText` / `MarkdownBody` 的受控 Markdown 渲染
+- CLI 组件查询输出
+- MDX validate 规则
+
+具体测试路径见 `docs/testing.md`。
+
+第一版暂不覆盖：
+
+- 浏览器 E2E
+- 视觉回归
+- Astro adapter 测试
+- npm tarball 安装 smoke test
+
+## Agent 使用约定
+
+Agent 生成 artifact 时应该遵守：
+
+1. 优先创建 `.mdx` 文件，不直接写裸 HTML。
+2. 优先使用已有高阶组件，不临时重写同类 UI。
+3. 交互型 artifact 必须提供导出入口。
+4. 大型数据后续应拆到相邻 `.json`。
+5. 不确定组件参数时运行 `artifact-kit components <ComponentName>`。
+6. 需要机器可读元数据时运行 `artifact-kit components --json`。
+7. 构建前运行 `artifact-kit validate <file.mdx>`。
+8. 单页输出运行 `artifact-kit build <file.mdx>`。
+
+## CLI 查询协议
+
+为了减少 skill、AGENTS.md、CLAUDE.md 中的冗余组件说明，CLI 提供组件查询能力：
+
+```bash
+artifact-kit components
+artifact-kit components ExportPanel
+artifact-kit components --json
+artifact-kit components ExportPanel --json
+```
+
+查询数据来自 `componentRegistry`，未来应同时服务 CLI 查询、Storybook docs、validate 规则和 Agent skill 说明。
+
+## 公开路线图与本地执行记录
+
+公开项目方向放在：
+
+- `ROADMAP.md`
+- `docs/design.md`
+- `docs/naming.md`
+- `docs/component-protocol.md`
+- `docs/component-taxonomy.md`
+- `docs/testing.md`
+
+本地阶段执行记录放在 `docs/local/*.local.md`，不提交到开源仓库。它用于记录临时判断、验收过程和 Agent 工作状态，避免把过程噪音暴露到公开文档中。

package/docs/naming.md

@@ -0,0 +1,123 @@
+# Naming Conventions
+
+Naming should help agents choose the right component without long prompt instructions.
+
+## Component Names
+
+Use `PascalCase`.
+
+Component names should describe the artifact workflow:
+
+- `DecisionMatrix`
+- `OptionGrid`
+- `ExportPanel`
+- `InlineText`
+- `MarkdownBody`
+
+Avoid vague primitive names:
+
+- `Text`
+- `Panel`
+- `CardList`
+- `Box`
+
+Use `Markdown` in a component name only when the component consumes a Markdown string.
+
+## Text Field Names
+
+Use a small shared vocabulary:
+
+- `title`: short title, usually `inlineMarkdown`
+- `subtitle`: secondary short title, usually `inlineMarkdown`
+- `description`: short explanation, usually `inlineMarkdown`
+- `caption`: auxiliary note, usually `inlineMarkdown`
+- `text`: primary field for `InlineText`
+- `body`: primary field for `MarkdownBody` and future long-form prose components
+
+Avoid introducing synonyms unless a component has a specific workflow reason:
+
+- `copy`
+- `message`
+- `content`
+- `details`
+- `richText`
+
+## Content Types
+
+The registry can label prop content with these content types:
+
+- `plainText`
+- `inlineMarkdown`
+- `blockMarkdown`
+- `json`
+- `code`
+
+Agents should inspect content types through:
+
+```bash
+artifact-kit components <ComponentName>
+artifact-kit components <ComponentName> --json
+```
+
+## Complex Prop Types
+
+Complex object props must be queryable without opening TypeScript source files.
+
+If a prop type references a named object or object array, add `types` metadata in `src/react/registry.ts`.
+
+Examples:
+
+- `DecisionMatrixOption[]` requires a `DecisionMatrixOption` type entry.
+- `DiffLine[]` requires a `DiffLine` type entry.
+- `CodeAnnotation[]` requires a `CodeAnnotation` type entry.
+
+Each nested field should include:
+
+- `name`
+- `type`
+- `required` when true
+- `contentType` when the field contains text, Markdown, JSON, or code
+- `description`
+
+The CLI output should be sufficient for an agent to write valid MDX without relying on editor LSP hover information.
+
+## Markdown Levels
+
+`inlineMarkdown` supports:
+
+- bold
+- emphasis
+- strikethrough
+- inline code
+- links
+
+`blockMarkdown` supports:
+
+- headings
+- paragraphs
+- ordered lists
+- unordered lists
+- blockquotes
+- bold
+- emphasis
+- strikethrough
+- inline code
+- links
+
+`blockMarkdown` intentionally does not support tables, HTML, math, or code blocks.
+
+For main artifact structure, prefer component title props or `InlineText as="h2"` instead of headings inside body strings. Headings inside `MarkdownBody` are for local body sections.
+
+Use:
+
+```tsx
+<InlineText as="h3" text="**Recommended option**" />
+```
+
+Avoid:
+
+```md
+### **Recommended option**
+```
+
+inside component string props.

package/docs/testing.md

@@ -0,0 +1,138 @@
+# Testing
+
+The current test baseline protects the component protocol. It does not try to prove every browser behavior or release boundary yet.
+
+## Current Baseline
+
+Run the default local check:
+
+```bash
+pnpm check
+```
+
+This runs:
+
+1. `pnpm typecheck`
+2. `pnpm test`
+3. `pnpm artifact:validate`
+
+Current test coverage:
+
+- registry metadata contract
+- controlled text rendering for `InlineText` and `MarkdownBody`
+- CLI component lookup output
+- MDX validation rules
+
+Current test files:
+
+- `src/react/registry.test.ts`
+- `src/react/components/text-components.test.tsx`
+- `src/cli/components.test.ts`
+- `src/cli/validate.test.ts`
+
+## Package Smoke Test
+
+Run the package smoke test before publishing or after changes to package metadata, CLI output, config loading, generated scaffold files, dependency boundaries, or build output:
+
+```bash
+pnpm pack:smoke
+```
+
+The smoke test creates an npm tarball, installs it into a temporary project, and verifies:
+
+- `import("mdx-artifacts/react")`
+- `artifact-kit components`
+- `artifact-kit init`
+- `artifact-kit validate artifact-docs/examples/hello.mdx`
+- `artifact-kit build artifact-docs/examples/hello.mdx`
+
+It also checks that the tarball does not include `src/`, `docs/local/`, `.state.json`, or `.local.*` files.
+
+This smoke test is intentionally narrow. It proves that the published package can be installed, imported, initialized, validated, and built. It does not yet cover the dev server, browser review UI, review state writes, or multi-artifact workspaces.
+
+## When Adding a Component
+
+Add tests at the same layer as the new behavior.
+
+Required:
+
+- Add or update `src/react/registry.test.ts` if registry metadata shape changes.
+- Add a component render test when the component owns rendering rules.
+- Add a Storybook story for visual development states.
+- Add or update an MDX example if the component changes the artifact workflow.
+- Run `pnpm check`.
+
+Recommended assertions:
+
+- Important text renders.
+- Optional fields can be omitted.
+- Empty lists or missing optional data do not break layout.
+- Controlled Markdown fields respect their documented content type.
+- The component is registered with a clear example.
+- Complex object props have matching registry `types` metadata.
+
+Do not add browser E2E just because a component was added. Add browser tests only when the behavior depends on real browser APIs, focus, layout, clipboard, drag-and-drop, or navigation.
+
+## When Adding CLI Behavior
+
+Required:
+
+- Add or update a focused `src/cli/*.test.ts` file.
+- Test command formatting through exported command functions when possible.
+- Test errors and warnings as data before testing process exit behavior.
+- Run `pnpm check`.
+
+For CLI behavior that writes files or builds artifacts, prefer small integration tests with temporary directories.
+
+Do not make the first assertion depend on full HTML build output unless the feature specifically changes build output.
+
+## When Adding Validation Rules
+
+Required:
+
+- Add a positive case.
+- Add a negative case.
+- Keep error and warning messages stable enough for agents to understand.
+- Run `pnpm check`.
+
+Validation rules should protect the artifact protocol, not personal style preferences.
+
+## When Adding Export Behavior
+
+Required:
+
+- Test serialization output as plain strings or structured data.
+- Test the component wiring separately only if rendering logic changes.
+
+Future export formats should have focused tests before being added to `ExportPanel`.
+
+## Heavier Checks
+
+These checks are not part of the current default baseline:
+
+- browser E2E
+- visual regression
+- Storybook test runner
+- Astro adapter tests
+- `artifact:build`
+- `npm pack --dry-run`
+
+Use them before npm publishing or when the changed behavior touches packaging, standalone HTML output, browser-only APIs, or future docs-site adapters.
+
+## Rule of Thumb
+
+Use the lightest test that can fail for the bug you are trying to prevent.
+
+For Phase 1, prefer:
+
+```text
+typecheck + unit tests + validate
+```
+
+over:
+
+```text
+browser E2E + full build + package smoke test
+```
+
+unless the change specifically needs the heavier layer.