mdx-artifacts 0.1.0

package/artifact-docs/examples/layout-composition.mdx

@@ -0,0 +1,216 @@
+import {
+  Columns,
+  ComparisonSet,
+  DecisionMatrix,
+  ExportPanel,
+  Frame,
+  Grid,
+  InlineText,
+  MarkdownBody,
+  SplitPane,
+  Stack,
+} from "mdx-artifacts/react";
+
+# Layout Composition Example
+
+<Stack gap="lg">
+  <Frame surface="plain" padding="lg">
+    <Stack gap="sm">
+      <InlineText
+        as="h2"
+        variant="title"
+        text="A composed artifact using **layout primitives** and text components"
+      />
+      <MarkdownBody
+        body={`This example shows how \`Stack\`, \`Columns\`, \`Grid\`, \`SplitPane\`, and \`Frame\` can arrange existing semantic components without replacing them.
+
+The layout components control placement and surface. Components such as \`DecisionMatrix\`, \`ComparisonSet\`, and \`ExportPanel\` still own the artifact meaning.`}
+/>
+
+</Stack>
+
+  </Frame>
+
+  <SplitPane ratio="3:1" gap="lg">
+    <DecisionMatrix
+      id="decision.layout-authoring"
+      question="Should layout primitives become the default authoring path?"
+      options={[
+        {
+          id: "semantic-first",
+          name: "Semantic-first authoring",
+          summary: "Agents choose task-oriented components first, then use layout only when composition needs it.",
+          pros: ["Stable protocol", "Less ad hoc JSX", "Better validation path"],
+          cons: ["Less free-form than raw HTML"],
+          confidence: "high",
+          verdict: "Recommended"
+        },
+        {
+          id: "layout-first",
+          name: "Layout-first authoring",
+          summary: "Agents assemble artifacts from generic layout blocks and arbitrary children.",
+          pros: ["Maximum flexibility"],
+          cons: ["Easy to recreate raw HTML", "Harder to query through CLI", "Harder to keep consistent"],
+          confidence: "low",
+          verdict: "Keep as an advanced escape hatch"
+        }
+      ]}
+    />
+
+    <Frame surface="subtle">
+      <Stack gap="sm">
+        <InlineText as="h3" variant="subtitle" text="Reading note" />
+        <MarkdownBody
+          variant="compact"
+          body={`Use layout primitives when the artifact needs a custom reading shape:
+
+- main content plus sidebar
+- equal option previews
+- framed snippets or mockups
+
+Do not use them to rebuild existing semantic components.`}
+/>
+
+</Stack>
+</Frame>
+
+  </SplitPane>
+
+  <Columns ratio="1:1:1" gap="md">
+    <Frame surface="outlined">
+      <InlineText as="h3" variant="subtitle" text="InlineText" />
+      <MarkdownBody
+        variant="compact"
+        body={`Short labels and headings can use **inline Markdown**, including *emphasis*, ~~removed text~~, and \`inline code\`.`}
+      />
+    </Frame>
+
+    <Frame surface="outlined">
+      <InlineText as="h3" variant="subtitle" text="MarkdownBody" />
+      <MarkdownBody
+        variant="compact"
+        body={`Body copy supports controlled Markdown:
+
+1.  paragraphs
+2.  ordered lists
+3.  unordered lists
+4.  blockquotes`}
+    />
+
+                  </Frame>
+
+                  <Frame surface="outlined">
+
+              <InlineText as="h3" variant="subtitle" text="Frame" />
+
+          <MarkdownBody
+
+    variant="compact"
+    body={`Frame provides surface treatment:
+
+- \`none\`
+- \`plain\`
+- \`subtle\`
+- \`outlined\``}
+  />
+
+                </Frame>
+
+            </Columns>
+
+              <ComparisonSet id="comparison.content-shapes" title="Compare content shapes" columns={3}>
+
+          <ComparisonSet.Item id="markdown-body" title="Markdown body" value="markdown-body">
+
+      <MarkdownBody
+
+  variant="compact"
+  body={`# This **item** is ~~plain Markdown content~~.
+
+  #### **item** is ~~plain Markdown content~~.
+
+- Good for notes
+- Easy for agents to write
+- Easy to validate
+
+1. Ordered item
+2. Nested content check
+
+`}
+/>
+
+                  </ComparisonSet.Item>
+
+<ComparisonSet.Item id="framed-snippet" title="Framed snippet" value="framed-snippet">
+  <Frame surface="subtle">
+    <MarkdownBody
+      variant="compact"
+      body={`This slot can hold a future \`CodeBlock\`, \`MermaidBlock\`, image renderer, or project-local component.`}
+    />
+  </Frame>
+</ComparisonSet.Item>
+
+                  <ComparisonSet.Item id="custom-composition" title="Custom composition" value="custom-composition">
+                  <Stack gap="sm">
+                    <InlineText text="Nested layout is allowed when the item needs it." variant="label" />
+                    <MarkdownBody body="The comparison item owns the title. Its body remains open to child components." variant="compact" />
+                  </Stack>
+
+                </ComparisonSet.Item>
+
+            </ComparisonSet>
+
+                <Grid columns={2} gap="md">
+
+              <Frame surface="outlined">
+
+          <InlineText as="h3" variant="subtitle" text="Grid is only layout" />
+
+      <MarkdownBody
+
+body={`This card is built manually from \`Frame\`, \`InlineText\`, and \`MarkdownBody\`.
+
+Use this when there is no reusable artifact meaning beyond placement.`}
+/>
+
+</Frame>
+
+    <Frame surface="plain" padding="lg">
+      <Stack gap="md">
+        <InlineText as="h3" variant="subtitle" text="Surface check" />
+        <MarkdownBody
+          body={`This frame uses \`surface=\"plain\"\`. In light mode it should read as a white surface on a very light neutral page background.
+
+In dark mode it should read as a quiet elevated surface, not as a blue-tinted panel.`}
+/>
+
+</Stack>
+</Frame>
+
+  </Grid>
+
+  <ExportPanel
+    title="Export layout review"
+    formats={["markdown", "json"]}
+    value={{
+      recommendation: "Keep layout primitives as advanced composition tools and use ComparisonSet for comparable mixed-content candidates.",
+      componentsShown: [
+        "Stack",
+        "Columns",
+        "Grid",
+        "SplitPane",
+        "Frame",
+        "ComparisonSet",
+        "InlineText",
+        "MarkdownBody"
+      ],
+      reviewChecklist: [
+        "Light mode surface contrast is readable.",
+        "Dark mode surface contrast is readable.",
+        "Semantic components remain the main authoring path.",
+        "ComparisonSet items can hold mixed child components.",
+        "Text components render controlled Markdown correctly."
+      ]
+    }}
+  />
+</Stack>

package/artifact-docs/examples/streamlit-style-mixed.mdx

@@ -0,0 +1,183 @@
+import {
+  Callout,
+  CodeBlock,
+  ComparisonSet,
+  DecisionMatrix,
+  ExportPanel,
+  Frame,
+  MarkdownBody,
+  OptionGrid,
+} from "mdx-artifacts/react";
+
+# Streamlit-Style Linear Artifact
+
+This example tests the simplest authoring path: write native MDX prose, place a component, continue writing prose, then place the next component.
+
+The goal is not to create a complex layout. The goal is to check whether the artifact already feels natural when the author writes in a linear flow.
+
+## Context
+
+Streamlit works well because authors can write a small amount of text, drop in a widget or chart, then keep going. MDX already gives this project a similar baseline:
+
+- markdown headings define the reading structure
+- paragraphs carry narrative context
+- components own reusable workflow UI
+- the artifact shell controls page width and vertical rhythm
+
+<Callout
+  id="callout.linear-check"
+  tone="info"
+  title="What this example is checking"
+  body="The artifact should read as one continuous document, not as disconnected component demos."
+/>
+
+## Decision point
+
+The first question is whether the core authoring experience should stay close to native MDX or move toward more explicit text components.
+
+<DecisionMatrix
+  id="decision.native-mdx"
+  question="Should top-level prose use native MDX by default?"
+  options={[
+    {
+      id: "native-mdx",
+      name: "Native MDX prose",
+      summary:
+        "Use regular headings, paragraphs, lists, links, and blockquotes between workflow components.",
+      pros: [
+        "Shortest authoring path",
+        "Agent-friendly",
+        "No extra text API to learn",
+      ],
+      cons: [
+        "Needs strong default prose styling",
+        "Harder to constrain every edge case",
+      ],
+      confidence: "high",
+      verdict: "Recommended baseline",
+    },
+    {
+      id: "text-components",
+      name: "Text components everywhere",
+      summary:
+        "Require components such as InlineText and MarkdownBody for most visible copy.",
+      pros: ["More controlled rendering", "Clear metadata boundary"],
+      cons: ["Verbose for simple documents", "Less natural than MDX"],
+      confidence: "medium",
+      verdict: "Use inside reusable components",
+    },
+    {
+      id: "raw-html",
+      name: "Raw HTML escape hatch",
+      summary:
+        "Let authors write arbitrary HTML when layout or text rendering gets specific.",
+      pros: ["Maximum flexibility"],
+      cons: ["Style drift", "Weak validation", "Harder for agents to reuse"],
+      confidence: "low",
+      verdict: "Avoid unless necessary",
+    },
+  ]}
+/>
+
+After the decision block, the document should continue naturally. This paragraph is intentionally plain MDX so the spacing between prose and the component above is easy to judge.
+
+> A good default artifact should let the author think in reading order first, then reach for layout primitives only when the content needs a custom arrangement.
+
+## Component menu
+
+The next block lists the current component roles. It should feel like a continuation of the same document, not a separate app screen.
+
+<OptionGrid
+  id="option.linear-building-blocks"
+  title="Linear authoring building blocks"
+  options={[
+    {
+      id: "native-mdx",
+      name: "Native MDX",
+      intent: "Own top-level narrative flow.",
+      tradeoffs: [
+        "Best for headings and explanatory paragraphs",
+        "Needs polished document-level CSS",
+      ],
+    },
+    {
+      id: "markdown-body",
+      name: "MarkdownBody",
+      intent: "Own controlled body copy inside a component slot.",
+      tradeoffs: [
+        "Good for reusable components",
+        "Less convenient for top-level prose",
+      ],
+    },
+    {
+      id: "workflow-components",
+      name: "Workflow components",
+      intent:
+        "Own structured decisions, comparisons, code notes, and export surfaces.",
+      tradeoffs: [
+        "Agent-queryable through the registry",
+        "Should stay higher-level than raw cards",
+      ],
+    },
+  ]}
+/>
+
+## Mixed content
+
+Here is a small comparison set with component-local Markdown inside each item. This shows the boundary between native MDX prose and reusable component content.
+
+<ComparisonSet id="comparison.text-forms" title="Where each text form belongs" columns={3}>
+  <ComparisonSet.Item id="top-level-mdx" title="Top-level MDX" value="top-level-mdx">
+    <Frame surface="subtle">
+      <MarkdownBody
+        variant="compact"
+        body="Use this for the document's main reading order: headings, paragraphs, lists, and short notes between components."
+      />
+    </Frame>
+  </ComparisonSet.Item>
+
+<ComparisonSet.Item id="markdown-body" title="MarkdownBody" value="markdown-body">
+  <Frame surface="subtle">
+    <MarkdownBody
+      variant="compact"
+      body="Use this when a component needs a controlled body field with safe Markdown rendering."
+    />
+  </Frame>
+</ComparisonSet.Item>
+
+  <ComparisonSet.Item id="code-block" title="CodeBlock" value="code-block">
+    <CodeBlock
+      id="code.linear-example"
+      filename="artifact-docs/examples/streamlit-style-mixed.mdx"
+      language="mdx"
+      code={`# Title
+
+Plain MDX prose.
+
+<DecisionMatrix ... />
+
+More prose.`}
+/>
+
+  </ComparisonSet.Item>
+</ComparisonSet>
+
+## Export
+
+The export block closes the artifact with a structured summary. In a real artifact, this is where the reader or agent can copy the decision back into the workflow.
+
+<ExportPanel
+  title="Export linear authoring verdict"
+  formats={["markdown", "json"]}
+  value={{
+    pattern: "Native MDX prose plus ordered workflow components",
+    recommendation:
+      "Keep native MDX as the top-level write path and use components for reusable structured UI.",
+    checks: [
+      "Top-level headings and paragraphs remain readable.",
+      "Components appear in the same order they are written.",
+      "Document spacing makes the artifact feel continuous.",
+      "MarkdownBody stays useful inside component slots.",
+    ],
+  }}
+/>

package/dist/lib/cli/artifact-state.d.ts

@@ -0,0 +1,27 @@
+export type ArtifactRoute = {
+    routePath: string;
+    slug: string;
+    sourcePath: string;
+    sourceRelativePath: string;
+    statePath: string;
+    stateRelativePath: string;
+};
+export type ArtifactState = {
+    version: number;
+    source: string;
+    threads: unknown[];
+    interactions: Record<string, unknown>;
+    [key: string]: unknown;
+};
+export declare function createArtifactRoute(projectRoot: string, mdxPath: string, docsDir: string): ArtifactRoute;
+export declare function createArtifactMeta(projectRoot: string, artifact: ArtifactRoute): Promise<{
+    routePath: string;
+    slug: string;
+    sourcePath: string;
+    statePath: string;
+    stateExists: boolean;
+    writable: boolean;
+}>;
+export declare function readArtifactState(artifact: ArtifactRoute): Promise<ArtifactState>;
+export declare function writeArtifactState(projectRoot: string, artifact: ArtifactRoute, value: unknown): Promise<ArtifactState>;
+export declare function createDefaultArtifactState(artifact: ArtifactRoute): ArtifactState;

package/dist/lib/cli/artifact-state.js

@@ -0,0 +1,115 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export function createArtifactRoute(projectRoot, mdxPath, docsDir) {
+    const sourcePath = path.resolve(mdxPath);
+    const statePath = sourcePath.replace(/\.mdx$/i, ".state.json");
+    const slug = createArtifactSlug(projectRoot, sourcePath, docsDir);
+    return {
+        routePath: `/artifacts/${slug}`,
+        slug,
+        sourcePath,
+        sourceRelativePath: toProjectRelativePath(projectRoot, sourcePath),
+        statePath,
+        stateRelativePath: toProjectRelativePath(projectRoot, statePath)
+    };
+}
+export async function createArtifactMeta(projectRoot, artifact) {
+    return {
+        routePath: artifact.routePath,
+        slug: artifact.slug,
+        sourcePath: artifact.sourceRelativePath,
+        statePath: artifact.stateRelativePath,
+        stateExists: await fileExists(artifact.statePath),
+        writable: isSafeStatePath(projectRoot, artifact)
+    };
+}
+export async function readArtifactState(artifact) {
+    try {
+        const source = await readFile(artifact.statePath, "utf8");
+        return normalizeArtifactState(JSON.parse(source), artifact);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return createDefaultArtifactState(artifact);
+        }
+        throw error;
+    }
+}
+export async function writeArtifactState(projectRoot, artifact, value) {
+    if (!isSafeStatePath(projectRoot, artifact)) {
+        throw new Error("State file must be next to its MDX source inside the project workspace.");
+    }
+    const state = normalizeArtifactState(value, artifact);
+    await mkdir(path.dirname(artifact.statePath), { recursive: true });
+    await writeFile(artifact.statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    return state;
+}
+export function createDefaultArtifactState(artifact) {
+    return {
+        version: 1,
+        source: artifact.sourceRelativePath,
+        threads: [],
+        interactions: {}
+    };
+}
+function normalizeArtifactState(value, artifact) {
+    if (!isRecord(value)) {
+        throw new Error("Artifact state must be a JSON object.");
+    }
+    return {
+        ...value,
+        version: typeof value.version === "number" ? value.version : 1,
+        source: artifact.sourceRelativePath,
+        threads: Array.isArray(value.threads) ? value.threads : [],
+        interactions: isRecord(value.interactions) ? value.interactions : {}
+    };
+}
+function createArtifactSlug(projectRoot, mdxPath, docsDir) {
+    const docsRoot = path.resolve(projectRoot, docsDir);
+    const relativeToDocs = path.relative(docsRoot, mdxPath);
+    const pathForSlug = relativeToDocs.startsWith("..") || path.isAbsolute(relativeToDocs)
+        ? path.basename(mdxPath, path.extname(mdxPath))
+        : relativeToDocs.replace(/\.mdx$/i, "");
+    return pathForSlug
+        .split(path.sep)
+        .map((segment) => slugify(segment))
+        .filter(Boolean)
+        .join("/");
+}
+function slugify(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[`*_~[\]()]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return slug || "artifact";
+}
+function isSafeStatePath(projectRoot, artifact) {
+    return (isInsidePath(projectRoot, artifact.sourcePath) &&
+        isInsidePath(projectRoot, artifact.statePath) &&
+        isSiblingStatePath(artifact));
+}
+function isInsidePath(root, target) {
+    const relative = path.relative(path.resolve(root), path.resolve(target));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function isSiblingStatePath(artifact) {
+    const expected = artifact.sourcePath.replace(/\.mdx$/i, ".state.json");
+    return path.resolve(expected) === path.resolve(artifact.statePath);
+}
+function toProjectRelativePath(projectRoot, target) {
+    return path.relative(projectRoot, target).replaceAll(path.sep, "/");
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

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

package/dist/lib/cli/build.js

@@ -0,0 +1,25 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { loadConfig } from "./config.js";
+import { buildArtifact, createArtifactProject } from "./vite-artifact.js";
+export async function buildCommand(projectRoot, input) {
+    const config = await loadConfig(projectRoot);
+    const mdxPath = path.resolve(projectRoot, input);
+    const project = await createArtifactProject(projectRoot, mdxPath, config);
+    try {
+        const html = await buildArtifact(project);
+        const outputPath = outputFileFor(projectRoot, mdxPath, config.docsDir, config.outDir);
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, html);
+        console.log(`built ${path.relative(projectRoot, outputPath)}`);
+    }
+    finally {
+        await project.cleanup();
+    }
+}
+function outputFileFor(projectRoot, mdxPath, docsDir, outDir) {
+    const docsRoot = path.resolve(projectRoot, docsDir);
+    const relative = path.relative(docsRoot, mdxPath);
+    const safeRelative = relative.startsWith("..") ? path.basename(mdxPath) : relative;
+    return path.resolve(projectRoot, outDir, safeRelative.replace(/\.mdx$/, ".html"));
+}

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

@@ -0,0 +1,3 @@
+export declare function componentsCommand(input?: string, options?: {
+    json?: boolean;
+}): void;

package/dist/lib/cli/components.js

@@ -0,0 +1,58 @@
+import { componentRegistry, findComponentMeta } from "../react/registry.js";
+export function componentsCommand(input, options = {}) {
+    if (input) {
+        const component = findComponentMeta(input);
+        if (!component) {
+            throw new Error(`Unknown component: ${input}`);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(component, null, 2));
+            return;
+        }
+        printComponent(component);
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(componentRegistry, null, 2));
+        return;
+    }
+    console.log("Available artifact components:\n");
+    for (const component of componentRegistry) {
+        console.log(`- ${component.name}: ${component.description}`);
+    }
+    console.log("\nUse `artifact-kit components <ComponentName>` to inspect props and examples.");
+    console.log("Use `artifact-kit components --json` for machine-readable metadata.");
+}
+function printComponent(component) {
+    console.log(`${component.name}\n`);
+    console.log(component.description);
+    if (component.category || component.stability) {
+        console.log(`\nMetadata: ${[component.category ? `category=${component.category}` : undefined, component.stability ? `stability=${component.stability}` : undefined].filter(Boolean).join(", ")}`);
+    }
+    console.log("\nUse when:");
+    for (const item of component.useWhen) {
+        console.log(`- ${item}`);
+    }
+    console.log("\nProps:");
+    for (const prop of component.props) {
+        printProp(prop);
+    }
+    if (component.types?.length) {
+        console.log("\nNested types:");
+        for (const type of component.types) {
+            console.log(`\n${type.name}${type.description ? `: ${type.description}` : ""}`);
+            for (const field of type.fields) {
+                printProp(field);
+            }
+        }
+    }
+    console.log("\nExample:");
+    console.log(component.example);
+}
+function printProp(prop) {
+    console.log(`- ${prop.name}${prop.required ? " (required)" : ""}: ${prop.type}`);
+    if (prop.contentType) {
+        console.log(`  content type: ${prop.contentType}`);
+    }
+    console.log(`  ${prop.description}`);
+}

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

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

package/dist/lib/cli/config.js

@@ -0,0 +1,36 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const defaultConfig = {
+    docsDir: "artifact-docs",
+    includeDefaultStyles: true,
+    outDir: "dist/artifacts",
+    port: 4321,
+    styles: []
+};
+export async function loadConfig(projectRoot) {
+    const configPath = await findConfigPath(projectRoot);
+    if (!configPath) {
+        return defaultConfig;
+    }
+    try {
+        const imported = (await import(pathToFileURL(configPath).href));
+        return { ...defaultConfig, ...(imported.default ?? {}) };
+    }
+    catch (error) {
+        throw new Error(`Failed to read ${path.basename(configPath)}: ${String(error)}`);
+    }
+}
+async function findConfigPath(projectRoot) {
+    for (const filename of ["artifact-kit.config.mjs", "artifact-kit.config.js", "artifact-kit.config.ts"]) {
+        const configPath = path.join(projectRoot, filename);
+        try {
+            await access(configPath);
+            return configPath;
+        }
+        catch {
+            // Try the next supported config filename.
+        }
+    }
+    return undefined;
+}

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

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