mdx-artifacts 0.1.1 → 0.2.0

package/docs/design.zh-CN.md

@@ -37,13 +37,14 @@ HTML artifact 的价值不在于替代 Markdown，而在于把一些阅读、比
 
 - `InlineText`：单行短文本，支持受控 inline Markdown。
 - `MarkdownBody`：组件内部正文，支持受控 block Markdown。
-- `DecisionMatrix`：方案比较。
-- `OptionGrid`：多个方案并排展示。
+- `ContentItem`：独立可读内容卡片。
+- `ContentSet`：带 tone 和 emphasis 的成组内容卡片。
+- `SortableList`：可拖拽的结构化优先级列表，保存用户排序结果。
 - `ExportPanel`：导出 Markdown / JSON。
 
 后续组件：
 
-- `PriorityBoard`：任务拖拽排序。
+- `KanbanBoard`：按列组织的卡片排序。
 - `PromptWorkbench`：提示词变量和样例预览。
 - `DiffExplainer`：PR / diff 解释。
 - `ParameterTuner`：参数调试器。
@@ -107,30 +108,34 @@ Astro 的代价：
 
 ## 样式协议
 
-Artifact Kit 提供默认 CSS，但默认样式不是闭环的一部分。
+MDX Artifacts 提供默认 CSS，但默认样式不是闭环的一部分。
 
-使用者可以通过 `artifact-kit.config.ts` 注入品牌样式：
+使用者可以通过 `mdx-artifacts.config.mjs` 注入品牌样式：
 
-```ts
+```js
+/** @type {import("mdx-artifacts").MdxArtifactsConfig} */
 const config = {
   docsDir: "artifact-docs",
   outDir: "dist/artifacts",
   includeDefaultStyles: true,
-  styles: ["artifact-theme.css"]
+  styles: ["artifact-theme.css"],
+  tailwindSources: ["artifact-components/**/*.{ts,tsx}"]
 };
 ```
 
 约定：
 
-- `includeDefaultStyles: true` 时，先导入 Artifact Kit 默认样式。
+- `includeDefaultStyles: true` 时，先导入 MDX Artifacts 默认样式。
 - `styles` 按数组顺序在默认样式之后导入。
 - 使用者可以通过覆盖 CSS variables 或 `ak-*` class 调整品牌。
-- `includeDefaultStyles: false` 表示完全接管样式。
+- `includeDefaultStyles: false` 表示关闭 MDX Artifacts 默认样式。
+- 当前 MDX 文件会自动注册为 Tailwind source，用于支持本地 MDX 组件。
+- `tailwindSources` 用于注册额外的项目本地组件文件。
 - CLI 构建仍会把最终 CSS 内联到单文件 HTML。
 
 ### Tailwind 的角色
 
-Tailwind 是 artifact-kit 内部的样式生产工具，不要求用户项目自己配置 Tailwind。
+Tailwind 是 mdx-artifacts 内部的样式生产工具，不要求用户项目自己配置 Tailwind。
 
 ### Radix 的角色
 
@@ -153,8 +158,8 @@ Storybook 不负责：
 
 ```text
 组件开发：pnpm storybook
-协议验证：pnpm typecheck / pnpm test / pnpm artifact:validate
-artifact 验证：pnpm artifact:build
+协议验证：pnpm typecheck / pnpm test / pnpm mdx-artifacts:validate
+artifact 验证：pnpm mdx-artifacts:build
 ```
 
 ## 测试协议
@@ -175,7 +180,9 @@ artifact 验证：pnpm artifact:build
 - 浏览器 E2E
 - 视觉回归
 - Astro adapter 测试
-- npm tarball 安装 smoke test
+- 默认 `pnpm check` 中的 npm tarball 安装 smoke test
+
+Package readiness 由单独命令覆盖：`pnpm release:check`、`pnpm pack:smoke`，以及发布前手动 `npm pack --dry-run`。
 
 ## Agent 使用约定
 
@@ -185,24 +192,37 @@ Agent 生成 artifact 时应该遵守：
 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>`。
+5. 不确定组件参数时运行 `mdx-artifacts components <ComponentName>`。
+6. 需要机器可读元数据时运行 `mdx-artifacts components --json`。
+7. 构建前运行 `mdx-artifacts validate <file.mdx>`。
+8. 单页输出运行 `mdx-artifacts 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
+mdx-artifacts components
+mdx-artifacts components ExportPanel
+mdx-artifacts components --json
+mdx-artifacts components ExportPanel --json
 ```
 
 查询数据来自 `componentRegistry`，未来应同时服务 CLI 查询、Storybook docs、validate 规则和 Agent skill 说明。
 
+## 包边界
+
+当前继续保持单个 npm 包。
+
+这个包通过不同入口暴露当前稳定表面：
+
+- `mdx-artifacts`：CLI。
+- `mdx-artifacts/react`：React components。
+- `mdx-artifacts/registry`：组件 registry metadata。
+- `mdx-artifacts/styles.css`：默认样式。
+
+暂不拆成 `@mdx-artifacts/react`、`@mdx-artifacts/cli` 或 `@mdx-artifacts/schema`。只有当独立版本、依赖隔离、adapter 发布节奏成为真实维护压力时，再重新评估拆包。当前优先保持安装、初始化和 agent guidance 简单。
+
 ## 公开路线图与本地执行记录
 
 公开项目方向放在：

package/docs/naming.md

@@ -8,8 +8,8 @@ Use `PascalCase`.
 
 Component names should describe the artifact workflow:
 
-- `DecisionMatrix`
-- `OptionGrid`
+- `ContentSet`
+- `ContentItem`
 - `ExportPanel`
 - `InlineText`
 - `MarkdownBody`
@@ -29,7 +29,9 @@ Use a small shared vocabulary:
 
 - `title`: short title, usually `inlineMarkdown`
 - `subtitle`: secondary short title, usually `inlineMarkdown`
-- `description`: short explanation, usually `inlineMarkdown`
+- `badge`: short display label, usually `plainText`
+- `summary`: one-line explanation, usually `inlineMarkdown`
+- `description`: short explanation for non-content metadata only, usually `plainText`
 - `caption`: auxiliary note, usually `inlineMarkdown`
 - `text`: primary field for `InlineText`
 - `body`: primary field for `MarkdownBody` and future long-form prose components
@@ -42,6 +44,15 @@ Avoid introducing synonyms unless a component has a specific workflow reason:
 - `details`
 - `richText`
 
+For content components, prefer the display slot model:
+
+- `title`
+- `badge`
+- `summary`
+- `children`
+
+Do not introduce component-specific aliases such as `name`, `intent`, `verdict`, or `tradeoffs` unless the component has a clear workflow reason and the field is not just a display slot.
+
 ## Content Types
 
 The registry can label prop content with these content types:
@@ -55,8 +66,8 @@ The registry can label prop content with these content types:
 Agents should inspect content types through:
 
 ```bash
-artifact-kit components <ComponentName>
-artifact-kit components <ComponentName> --json
+mdx-artifacts components <ComponentName>
+mdx-artifacts components <ComponentName> --json
 ```
 
 ## Complex Prop Types
@@ -67,7 +78,6 @@ If a prop type references a named object or object array, add `types` metadata i
 
 Examples:
 
-- `DecisionMatrixOption[]` requires a `DecisionMatrixOption` type entry.
 - `DiffLine[]` requires a `DiffLine` type entry.
 - `CodeAnnotation[]` requires a `CodeAnnotation` type entry.
 
@@ -111,7 +121,7 @@ For main artifact structure, prefer component title props or `InlineText as="h2"
 Use:
 
 ```tsx
-<InlineText as="h3" text="**Recommended option**" />
+<InlineText as="h3">**Recommended option**</InlineText>
 ```
 
 Avoid:

package/docs/releasing.md

@@ -0,0 +1,132 @@
+# Releasing
+
+This project currently uses manual npm publishing.
+
+CI and release checks are quality gates. They do not publish the package and they do not configure an npm token.
+
+## Release Model
+
+- Publish from a clean local checkout.
+- Keep `mdx-artifacts` as a single npm package.
+- Use CI, `release:check`, `pack:smoke`, and `npm pack --dry-run` as pre-publish gates.
+- Run `npm publish` manually only after the package contents and version are confirmed.
+
+## Before Publishing
+
+1. Confirm the worktree is clean.
+
+```bash
+git status --short
+```
+
+2. Confirm the version in `package.json` is the version intended for npm.
+
+```bash
+node -p "require('./package.json').version"
+```
+
+3. Confirm CI has passed for the commit being published.
+
+If CI is not available yet, run the local gates below and treat the publish as local-manual.
+
+4. Run the default validation baseline.
+
+```bash
+pnpm check
+```
+
+5. Run the lightweight release gate.
+
+```bash
+pnpm release:check
+```
+
+6. Run the package smoke test.
+
+```bash
+pnpm pack:smoke
+```
+
+7. Run the final npm pack dry run.
+
+```bash
+npm pack --dry-run --cache /private/tmp/mdx-artifacts-npm-cache
+```
+
+8. Inspect the dry-run output.
+
+Confirm the tarball includes expected files such as:
+
+- `dist/lib`
+- `agents/AGENTS.snippet.md`
+- `artifact-docs/examples/*.mdx`
+- `docs/*.md`
+- `README.md`
+- `README.zh-CN.md`
+- `LICENSE`
+
+Confirm the tarball does not include:
+
+- `src/`
+- `docs/local/`
+- `.storybook/`
+- Storybook stories
+- sourcemaps
+- `node_modules/`
+- generated `dist/artifacts`
+- `.state.json`
+- `.local.*`
+- `.log`
+- `.tgz`
+
+## Publishing
+
+1. Confirm npm authentication.
+
+```bash
+npm whoami
+```
+
+2. Publish the package.
+
+```bash
+npm publish
+```
+
+Do not publish if any pre-publish gate failed or if the dry-run tarball contains unexpected files.
+
+## After Publishing
+
+1. Confirm npm shows the expected version.
+
+```bash
+npm view mdx-artifacts version
+```
+
+2. Smoke test the published package from a temporary project.
+
+```bash
+mkdir -p /private/tmp/mdx-artifacts-published-smoke
+cd /private/tmp/mdx-artifacts-published-smoke
+npm init -y
+npm install --save-dev mdx-artifacts
+npx mdx-artifacts init --yes
+npx mdx-artifacts validate artifact-docs/examples/hello.mdx
+npx mdx-artifacts build artifact-docs/examples/hello.mdx
+```
+
+3. If the post-publish smoke test fails, do not overwrite the published version.
+
+Publish a follow-up patch version with a fix instead.
+
+## Not Automated Yet
+
+These steps are intentionally not automated yet:
+
+- npm token setup
+- GitHub release creation
+- changelog generation
+- version bump automation
+- tag-based publishing
+
+Add those only when manual publishing becomes a real bottleneck.

package/docs/testing.md

@@ -14,7 +14,7 @@ This runs:
 
 1. `pnpm typecheck`
 2. `pnpm test`
-3. `pnpm artifact:validate`
+3. `pnpm mdx-artifacts:validate`
 
 Current test coverage:
 
@@ -26,9 +26,26 @@ Current test coverage:
 Current test files:
 
 - `src/react/registry.test.ts`
-- `src/react/components/text-components.test.tsx`
+- `src/react/primitives/markdown-body/text-components.test.tsx`
 - `src/cli/components.test.ts`
-- `src/cli/validate.test.ts`
+- `src/cli/commands/validate.test.ts`
+
+## Release Check
+
+Run the release check before publishing or after changes to package metadata, public docs, agent guidance, examples, or release scripts:
+
+```bash
+pnpm release:check
+```
+
+The release check is a lightweight static gate. It does not build the package and does not publish to npm.
+
+It verifies:
+
+- `package.json` `files` matches the intended publish allowlist
+- package file candidates do not include forbidden paths such as `src/`, `docs/local/`, `.state.json`, `.local.*`, logs, tarballs, sourcemaps, Storybook output, or generated artifacts
+- public English/code files do not contain Han characters
+- public files do not contain legacy package naming
 
 ## Package Smoke Test
 
@@ -41,14 +58,22 @@ 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`
+- `mdx-artifacts components`
+- `mdx-artifacts init`
+- `mdx-artifacts validate artifact-docs/examples/hello.mdx`
+- `mdx-artifacts build artifact-docs/examples/hello.mdx`
+- `mdx-artifacts dev artifact-docs/examples/hello.mdx`
+- `mdx-artifacts review validate`
+- `mdx-artifacts review add`
+- `mdx-artifacts review reply`
+
+It also checks that:
 
-It also checks that the tarball does not include `src/`, `docs/local/`, `.state.json`, or `.local.*` files.
+- the tarball does not include `src/`, `docs/local/`, `.state.json`, or `.local.*` files
+- the temporary project can install only the `mdx-artifacts` tarball without explicitly adding `react` or `react-dom`
+- dev server MDX imports and the generated artifact shell resolve `mdx-artifacts/react` to the same package entry, so comment context is not split by dependency prebundling
 
-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.
+This smoke test proves that the published package can be installed, imported, initialized, validated, built, served in dev mode, and used with review-state commands. It does not yet cover a real browser click-through of the review UI or multi-artifact workspaces.
 
 ## When Adding a Component
 
@@ -114,7 +139,7 @@ These checks are not part of the current default baseline:
 - visual regression
 - Storybook test runner
 - Astro adapter tests
-- `artifact:build`
+- `mdx-artifacts: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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdx-artifacts",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Build interactive MDX artifacts with reusable React components and a local CLI.",
   "type": "module",
   "license": "MIT",
@@ -41,23 +41,24 @@
     "./styles.css": "./dist/lib/react/styles.css"
   },
   "bin": {
-    "artifact-kit": "dist/lib/cli/index.js"
+    "mdx-artifacts": "dist/lib/cli/index.js"
   },
   "scripts": {
-    "artifact": "tsx src/cli/index.ts",
-    "artifact:dev": "tsx src/cli/index.ts dev artifact-docs/examples/decision-matrix.mdx",
-    "artifact:build": "tsx src/cli/index.ts build artifact-docs/examples/decision-matrix.mdx",
-    "artifact:validate": "tsx src/cli/index.ts validate artifact-docs/examples/decision-matrix.mdx",
+    "mdx-artifacts": "tsx src/cli/index.ts",
+    "mdx-artifacts:dev": "tsx src/cli/index.ts dev artifact-docs/examples/decision-matrix.mdx",
+    "mdx-artifacts:build": "tsx src/cli/index.ts build artifact-docs/examples/decision-matrix.mdx",
+    "mdx-artifacts:validate": "tsx src/cli/index.ts validate artifact-docs/examples/decision-matrix.mdx",
     "storybook": "storybook dev -p 6106 --no-open",
     "test": "vitest run",
     "test:watch": "vitest",
-    "check": "pnpm typecheck && pnpm test && pnpm artifact:validate",
+    "check": "pnpm typecheck && pnpm test && pnpm mdx-artifacts:validate",
     "typecheck": "tsc --noEmit",
     "clean:lib": "rm -rf dist/lib",
     "build:lib": "tsc -p tsconfig.build.json",
     "build:esm": "node scripts/fix-dist-esm.mjs",
     "build:styles": "cp src/react/styles.css dist/lib/react/styles.css",
     "build:cli": "pnpm clean:lib && pnpm build:lib && pnpm build:esm && pnpm build:styles",
+    "release:check": "node scripts/check-release.mjs",
     "pack:smoke": "node scripts/pack-smoke.mjs",
     "prepack": "pnpm build:cli"
   },
@@ -76,6 +77,7 @@
     "react-dom": ">=18.3.0 <20"
   },
   "devDependencies": {
+    "@storybook/addon-docs": "10.3.6",
     "@storybook/react-vite": "^10.3.6",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",

package/dist/lib/cli/config.d.ts

@@ -1,2 +0,0 @@
-import type { ArtifactKitConfig } from "./types";
-export declare function loadConfig(projectRoot: string): Promise<Required<ArtifactKitConfig>>;

package/dist/lib/cli/review.d.ts

@@ -1,33 +0,0 @@
-type ReviewReply = {
-    threadId: string;
-    body: string;
-};
-type ReviewAddOptions = {
-    anchorId: string;
-    body: string;
-    title?: string;
-};
-type ReviewReplyOptions = {
-    replies: ReviewReply[];
-    status?: string;
-};
-export type ReviewValidationResult = {
-    anchorCount: number;
-    missingThreads: ReviewMissingThread[];
-    output: string;
-    threadCount: number;
-};
-export type ReviewMissingThread = {
-    anchorId: string;
-    threadId: string;
-    title?: string;
-    status?: string;
-};
-export declare function reviewCommand(projectRoot: string, args: string[]): Promise<void>;
-export declare function addReviewThread(projectRoot: string, input: string, options: ReviewAddOptions): Promise<string>;
-export declare function replyToReviewThread(projectRoot: string, input: string, options: ReviewReply & {
-    status?: string;
-}): Promise<string>;
-export declare function replyToReviewThreads(projectRoot: string, input: string, options: ReviewReplyOptions): Promise<string>;
-export declare function validateReviewState(projectRoot: string, input: string): Promise<ReviewValidationResult>;
-export {};

package/dist/lib/cli/scaffold.d.ts

@@ -1 +0,0 @@
-export declare function initProject(projectRoot: string): Promise<void>;

package/dist/lib/cli/scaffold.js

@@ -1,56 +0,0 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import path from "node:path";
-export async function initProject(projectRoot) {
-    const docsDir = path.join(projectRoot, "artifact-docs", "examples");
-    const agentsDir = path.join(projectRoot, "agents");
-    await mkdir(docsDir, { recursive: true });
-    await mkdir(agentsDir, { recursive: true });
-    await writeFile(path.join(projectRoot, "artifact-kit.config.mjs"), `/** @type {import("mdx-artifacts").ArtifactKitConfig} */
-const config = {
-  docsDir: "artifact-docs",
-  outDir: "dist/artifacts",
-  includeDefaultStyles: true,
-  styles: []
-};
-
-export default config;
-`, { flag: "wx" }).catch(ignoreExisting);
-    await writeFile(path.join(agentsDir, "AGENTS.snippet.md"), `# Artifact Kit Agent Instructions
-
-1. Create .mdx files under artifact-docs/.
-2. Prefer Artifact Kit high-level components. Do not generate raw HTML unless explicitly requested.
-3. Interactive artifacts must include ExportPanel or an equivalent export path.
-4. Run artifact-kit components <ComponentName> when component props are unclear.
-5. Run artifact-kit validate <file.mdx> before build.
-6. Run artifact-kit build <file.mdx> to produce standalone HTML.
-`, { flag: "wx" }).catch(ignoreExisting);
-    await writeFile(path.join(docsDir, "hello.mdx"), `import { DecisionMatrix, ExportPanel } from "mdx-artifacts/react";
-
-# Hello Artifact
-
-<DecisionMatrix
-  id="decision.initialized"
-  question="Has Artifact Kit been initialized?"
-  options={[
-    {
-      name: "Initialized",
-      pros: ["MDX source exists", "Export panel exists"],
-      cons: ["Real content still needs to be added"],
-      verdict: "Ready to continue generating artifacts"
-    }
-  ]}
-/>
-
-<ExportPanel
-  value={{
-    recommendation: "Continue generating interactive HTML artifacts with MDX and high-level components"
-  }}
-/>
-`, { flag: "wx" }).catch(ignoreExisting);
-    console.log("Artifact Kit initialized.");
-}
-function ignoreExisting(error) {
-    if (error.code !== "EEXIST") {
-        throw error;
-    }
-}

package/dist/lib/cli/validate.d.ts

@@ -1,6 +0,0 @@
-export type ValidationResult = {
-    errors: string[];
-    warnings: string[];
-};
-export declare function validateMdx(filePath: string): Promise<ValidationResult>;
-export declare function printValidationResult(result: ValidationResult): void;

package/dist/lib/cli/validate.js

@@ -1,79 +0,0 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { componentRegistry } from "../react/registry.js";
-const componentsRequiringStableId = [
-    "Section",
-    "DecisionMatrix",
-    "OptionGrid",
-    "ComparisonSet",
-    "ComparisonSet.Item",
-    "AnnotatedCode",
-    "CodeBlock",
-    "DiffBlock",
-    "Callout"
-];
-export async function validateMdx(filePath) {
-    const result = { errors: [], warnings: [] };
-    if (path.extname(filePath) !== ".mdx") {
-        result.errors.push("Input file must be .mdx.");
-        return result;
-    }
-    let source = "";
-    try {
-        source = await readFile(filePath, "utf8");
-    }
-    catch {
-        result.errors.push(`Failed to read file: ${filePath}`);
-        return result;
-    }
-    if (source.includes("<script")) {
-        result.errors.push("Do not write <script> directly in MDX. Wrap behavior in a controlled component.");
-    }
-    if (!source.includes("ExportPanel") && !source.includes("CommentExport")) {
-        result.warnings.push("ExportPanel or equivalent export component not found. Interactive artifacts should provide an export path.");
-    }
-    if (source.length > 40_000) {
-        result.warnings.push("MDX file is large. Move bulky data to adjacent JSON files.");
-    }
-    const knownComponents = componentRegistry.map((component) => component.name);
-    const usedArtifactComponent = knownComponents.some((name) => source.includes(`<${name}`));
-    if (!usedArtifactComponent) {
-        result.warnings.push("No first-stage high-level artifact component found. Confirm plain MDX is intentional.");
-    }
-    const sourceWithoutStringLiterals = stripStringLiterals(source);
-    for (const componentName of componentsRequiringStableId) {
-        if (hasOpeningTagWithoutProp(sourceWithoutStringLiterals, componentName, "id")) {
-            result.warnings.push(`${componentName} should include a stable id prop so comments and state can use a durable anchorId.`);
-        }
-    }
-    return result;
-}
-export function printValidationResult(result) {
-    for (const error of result.errors) {
-        console.error(`error: ${error}`);
-    }
-    for (const warning of result.warnings) {
-        console.warn(`warn: ${warning}`);
-    }
-    if (result.errors.length === 0 && result.warnings.length === 0) {
-        console.log("validate ok");
-    }
-}
-function stripStringLiterals(source) {
-    return source
-        .replace(/`(?:\\[\s\S]|[^`\\])*`/g, "``")
-        .replace(/"(?:\\.|[^"\\])*"/g, '""')
-        .replace(/'(?:\\.|[^'\\])*'/g, "''");
-}
-function hasOpeningTagWithoutProp(source, componentName, propName) {
-    const escapedName = componentName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const tagPattern = new RegExp(`<${escapedName}(?=[\\s>/])[^>]*>`, "g");
-    const propPattern = new RegExp(`\\s${propName}\\s*=`);
-    for (const match of source.matchAll(tagPattern)) {
-        const openingTag = match[0];
-        if (!propPattern.test(openingTag)) {
-            return true;
-        }
-    }
-    return false;
-}