pmx-canvas 0.1.0

package/skills/pmx-canvas/evals/evals.json

@@ -0,0 +1,186 @@
+{
+  "skill_name": "pmx-canvas",
+  "evals": [
+    {
+      "id": 1,
+      "name": "investigation-board",
+      "prompt": "I'm debugging a memory leak in our Node.js API. The /api/users endpoint is leaking memory on every request. I found a suspicious closure in src/handlers/users.ts that captures the entire request object, and the heap snapshot shows growing EventEmitter listeners. Can you set up an investigation board on the canvas so I can see the full picture?",
+      "expected_output": "Creates multiple nodes (bug description, code file, heap findings, hypothesis) connected with edges, arranged in a tree layout. Uses appropriate node types (markdown for findings, file for source, status for investigation progress).",
+      "assertions": [
+        {
+          "name": "creates-multiple-nodes",
+          "description": "Creates at least 3 nodes representing different aspects of the investigation",
+          "type": "output_check"
+        },
+        {
+          "name": "uses-edges",
+          "description": "Connects nodes with labeled edges showing relationships between evidence",
+          "type": "output_check"
+        },
+        {
+          "name": "uses-tree-or-arrange",
+          "description": "Arranges the nodes using tree layout or explicit positioning for readability",
+          "type": "output_check"
+        },
+        {
+          "name": "uses-appropriate-types",
+          "description": "Uses file nodes for source code and markdown/status for findings rather than all markdown",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "name": "architecture-diagram",
+      "prompt": "We're building a microservices backend with these services: API Gateway (Express, port 3000), Auth Service (JWT + OAuth2, port 3001), User Service (CRUD, port 3002), PostgreSQL (port 5432), and Redis (caching, port 6379). The API Gateway routes to Auth and User services, both Auth and User read/write to PostgreSQL, and User Service uses Redis for caching. Can you visualize this architecture on the canvas?",
+      "expected_output": "Creates nodes for each service with relevant details, connects them with flow/depends-on edges with descriptive labels, groups related services, and arranges in a readable layout.",
+      "assertions": [
+        {
+          "name": "all-services-present",
+          "description": "Creates nodes for all 5 services/datastores mentioned",
+          "type": "output_check"
+        },
+        {
+          "name": "correct-connections",
+          "description": "Creates edges matching the described relationships (Gateway->Auth, Gateway->User, Auth->PG, User->PG, User->Redis)",
+          "type": "output_check"
+        },
+        {
+          "name": "edge-labels",
+          "description": "Uses descriptive edge labels (not bare unlabeled edges)",
+          "type": "output_check"
+        },
+        {
+          "name": "layout-applied",
+          "description": "Applies auto-arrange or uses explicit positioning for readable layout",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "name": "task-plan-tracking",
+      "prompt": "I need to implement a new payment feature. Here's the plan: 1) Define payment schema (done), 2) Build Stripe integration (in progress), 3) Create payment API routes (blocked by #2), 4) Add webhook handlers (blocked by #3), 5) Write integration tests (blocked by #4), 6) Update API docs (can start anytime). Show this on the canvas as a task board with dependencies.",
+      "expected_output": "Creates status nodes for each task with appropriate colors (green=done, yellow=in-progress, red=blocked, blue=ready), connects with depends-on edges, and arranges to show dependency flow.",
+      "assertions": [
+        {
+          "name": "six-task-nodes",
+          "description": "Creates exactly 6 task nodes, one for each task",
+          "type": "output_check"
+        },
+        {
+          "name": "semantic-colors",
+          "description": "Uses green for done, yellow for in-progress, red for blocked tasks",
+          "type": "output_check"
+        },
+        {
+          "name": "dependency-edges",
+          "description": "Creates depends-on edges matching the described blocking relationships",
+          "type": "output_check"
+        },
+        {
+          "name": "status-node-type",
+          "description": "Uses status node type (not markdown) for task items",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "name": "read-pinned-context",
+      "prompt": "I've pinned some nodes on the canvas that I want you to look at. Can you read what I've pinned and summarize what you think I'm focusing on?",
+      "expected_output": "Reads canvas://pinned-context resource, summarizes the pinned nodes' content, identifies spatial neighborhoods, and explains what the human appears to be focusing on based on the pinned context and nearby nodes.",
+      "assertions": [
+        {
+          "name": "reads-pinned-context",
+          "description": "Reads the canvas://pinned-context MCP resource (not just canvas_get_layout)",
+          "type": "output_check"
+        },
+        {
+          "name": "summarizes-content",
+          "description": "Provides a meaningful summary of what the pinned nodes contain",
+          "type": "output_check"
+        },
+        {
+          "name": "interprets-intent",
+          "description": "Makes an interpretation of what the human is focusing on based on pinned context",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 5,
+      "name": "code-exploration-files",
+      "prompt": "I'm trying to understand how the authentication flow works in this project. Can you put the relevant auth files on the canvas so I can see how they connect? The main files are src/auth/login.ts, src/auth/middleware.ts, src/auth/jwt.ts, and src/routes/auth.ts.",
+      "expected_output": "Creates file nodes for each mentioned file (content auto-loads), relies on code graph to auto-detect import dependencies, groups auth files together, and reads canvas://code-graph for dependency analysis.",
+      "assertions": [
+        {
+          "name": "uses-file-nodes",
+          "description": "Creates file type nodes (not markdown with pasted code) for source files",
+          "type": "output_check"
+        },
+        {
+          "name": "all-files-added",
+          "description": "Adds all 4 mentioned files to the canvas",
+          "type": "output_check"
+        },
+        {
+          "name": "groups-files",
+          "description": "Groups the auth files together in a canvas group",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 6,
+      "name": "status-dashboard-updates",
+      "prompt": "I'm running a deployment pipeline. Create a dashboard on the canvas showing: Build (passing), Unit Tests (running), Integration Tests (queued), Deploy to Staging (queued). Then update it - unit tests just passed and integration tests are now running.",
+      "expected_output": "Creates status nodes with semantic colors, arranges as grid dashboard, then updates nodes in place using canvas_update_node (not delete+recreate) to reflect new state.",
+      "assertions": [
+        {
+          "name": "initial-dashboard",
+          "description": "Creates 4 status nodes with appropriate initial colors",
+          "type": "output_check"
+        },
+        {
+          "name": "updates-in-place",
+          "description": "Uses canvas_update_node to change status (not remove+add)",
+          "type": "output_check"
+        },
+        {
+          "name": "grid-layout",
+          "description": "Arranges nodes in grid layout for dashboard view",
+          "type": "output_check"
+        },
+        {
+          "name": "color-transitions",
+          "description": "Updates colors to reflect new state (unit tests -> green, integration -> yellow)",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 7,
+      "name": "snapshot-before-changes",
+      "prompt": "I want to reorganize the canvas to explore a different approach, but I don't want to lose what's there now. Can you save the current state, clear it, and set up a fresh workspace for the new approach? If it doesn't work out I want to go back.",
+      "expected_output": "Takes a named snapshot of current state, then clears the canvas. Mentions that canvas_restore can bring back the old state. Does NOT just clear without snapshotting.",
+      "assertions": [
+        {
+          "name": "takes-snapshot",
+          "description": "Saves a snapshot with canvas_snapshot before clearing",
+          "type": "output_check"
+        },
+        {
+          "name": "clears-after-snapshot",
+          "description": "Clears the canvas after (not before) saving the snapshot",
+          "type": "output_check"
+        },
+        {
+          "name": "mentions-restore",
+          "description": "Tells the user how to restore (canvas_restore) if they want to go back",
+          "type": "output_check"
+        }
+      ]
+    }
+  ]
+}

package/skills/pmx-canvas-testing/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: pmx-canvas-testing
+description: >
+  Repo-standard test and verification workflow for PMX Canvas. Use when you change code, add
+  tests, debug regressions, prepare handoff, or need to decide which local verification commands
+  to run. This skill defines the default test ladder, when to run Bun tests vs. browser tests,
+  how to handle pre-existing failures, and what evidence to report back.
+---
+
+# PMX Canvas Testing
+
+Use this skill whenever you touch code in this repo and need a consistent verification path.
+
+## When To Use
+
+- Any code change that should be validated before handoff
+- Adding or updating tests
+- Debugging a regression or flaky behavior
+- Updating CI or coverage commands
+- Deciding the minimum acceptable verification for a task
+
+## Default Verification Ladder
+
+Pick the narrowest command that proves the change, then escalate if the change crosses layers.
+
+```bash
+bun run test                # Fast Bun suite for server/state/API coverage
+bun run test:coverage       # Same Bun suite with coverage output
+bun run test:web-canvas     # Browser smoke against a real running app
+bun run test:all            # Bun suite + browser smoke
+```
+
+## Which Command To Run
+
+- Server/state/API-only changes: run `bun run test`
+- Test-only changes: run `bun run test` and `bun run test:coverage` if coverage matters
+- Client/UI/browser interaction changes: run `bun run test:web-canvas`
+- Cross-stack or non-trivial changes: run `bun run test:all`
+- Before changing browser-visible behavior under `src/client/`: rebuild with `bun run build`
+  Manual browser validation also requires a fresh client bundle. `bun run test:web-canvas`
+  already does this for you.
+
+## Current Project Test Surface
+
+- Bun tests live under `tests/unit/`
+- Playwright browser smoke lives under `tests/e2e/`
+- CI runs coverage plus the browser smoke flow
+
+Prefer extending the existing suites before inventing a one-off script.
+
+## Test Authoring Rules
+
+- Keep unit tests isolated. Reset singleton server state between tests.
+- Test public behavior first: HTTP endpoints, persisted state, visible UI outcomes
+- Use browser tests for interactions the user actually performs: node creation, pins, snapshots,
+  loading the workbench, and other sync-sensitive flows
+- Avoid brittle selectors. Prefer stable text, roles, titles, or deliberate component hooks
+- If a change spans server and client, add at least one server-side assertion and one browser or
+  API-level proof
+
+## Failure Handling
+
+- Never wave away a failure without checking whether your change caused it
+- If the failure is truly pre-existing, say that explicitly and include the failing command
+- If a command cannot run in the environment, say what blocked it
+- If browser tests fail after a client change, confirm the bundle was rebuilt and the server
+  started from the updated code
+
+## Handoff Standard
+
+Before marking work done, report:
+
+- Which verification command(s) you ran
+- Whether they passed
+- Any meaningful gaps, skipped checks, or known pre-existing failures
+
+For non-trivial changes, the default expectation is `bun run test:all` unless there is a clear
+reason to scope verification more narrowly.

package/skills/published-consumer-e2e/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: published-consumer-e2e
+description: Re-run PMX Canvas like an external user by packing the repo, installing the tarball into a clean temp workspace, seeding the SDLC demo, and validating it in a browser. Use when asked to verify the published-package workflow, artifact/json-render coverage, or the full outside-in demo.
+---
+
+# Published Consumer E2E
+
+Use this skill when the goal is to test PMX Canvas from the outside instead of the repo dev path.
+
+## Default Path
+
+Run:
+
+```bash
+bash skills/published-consumer-e2e/scripts/run-published-consumer-e2e.sh
+```
+
+That script will:
+
+1. pack the current repo as a tarball,
+2. create a clean temp consumer workspace,
+3. install the tarball with Bun,
+4. copy `examples/published-consumer-sdlc/` into that workspace,
+5. start the seeded demo through the package's public SDK,
+6. run a headed `playwright-cli` browser pass that snapshots the live workbench and asserts the article, artifact, json-render, graph, trace, and context surfaces are present.
+
+## Flags
+
+- `--port=4600` to change the server port
+- `--skip-playwright` to stop after pack/install + HTTP smoke
+- `--headless` if a visible browser is impossible
+- `--keep-running` to leave the temp consumer server alive after the script exits
+- `--workdir=/tmp/custom-dir` to reuse a known temp location
+
+## Notes
+
+- Install the browser tool once with `bun add -g @playwright/cli@latest`.
+- Default to headed browser validation so the human can watch the run.
+- Prefer the script over manually rebuilding the temp consumer.
+- If you change the example assets or this browser test, rerun the full script instead of repo-only tests.
+- The script assembles the tarball manually instead of relying on `npm pack` or `bun pm pack`, because pack/build commands can hang in this workspace.
+- The skill uses `playwright-cli` instead of the repo-local `playwright test` path because the local Playwright CLI is currently incompatible with the Bun/Node mix in this environment.
+- On failure, inspect the temp workspace log path printed by the script before changing code.

package/skills/published-consumer-e2e/scripts/run-published-consumer-e2e.sh

@@ -0,0 +1,241 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+REPO_ROOT="$(cd "${SKILL_DIR}/../.." && pwd)"
+
+BUN_BIN="${BUN_BIN:-$HOME/.bun/bin/bun}"
+PORT="4513"
+WORKDIR=""
+KEEP_RUNNING=0
+SKIP_PLAYWRIGHT=0
+HEADED=1
+
+for arg in "$@"; do
+  case "$arg" in
+    --port=*)
+      PORT="${arg#*=}"
+      ;;
+    --workdir=*)
+      WORKDIR="${arg#*=}"
+      ;;
+    --keep-running)
+      KEEP_RUNNING=1
+      ;;
+    --skip-playwright)
+      SKIP_PLAYWRIGHT=1
+      ;;
+    --headless)
+      HEADED=0
+      ;;
+    --headed)
+      HEADED=1
+      ;;
+    *)
+      echo "Unknown argument: $arg" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ ! -x "${BUN_BIN}" ]]; then
+  echo "Bun binary not found at ${BUN_BIN}. Set BUN_BIN or install Bun." >&2
+  exit 1
+fi
+
+export PATH="/opt/homebrew/bin:/usr/local/bin:$(dirname "${BUN_BIN}"):${PATH}"
+
+if [[ -z "${WORKDIR}" ]]; then
+  WORKDIR="$(mktemp -d "${TMPDIR:-/tmp}/pmx-canvas-published-consumer.XXXXXX")"
+else
+  mkdir -p "${WORKDIR}"
+fi
+
+PACK_DIR="${WORKDIR}/pack"
+PACKAGE_STAGING="${WORKDIR}/package"
+CONSUMER_DIR="${WORKDIR}/consumer"
+LOG_FILE="${WORKDIR}/server.log"
+rm -rf "${PACK_DIR}" "${PACKAGE_STAGING}"
+mkdir -p "${PACK_DIR}" "${PACKAGE_STAGING}/package" "${CONSUMER_DIR}/demo"
+
+cleanup() {
+  if [[ -n "${SERVER_PID:-}" ]] && kill -0 "${SERVER_PID}" 2>/dev/null; then
+    kill "${SERVER_PID}" 2>/dev/null || true
+    wait "${SERVER_PID}" 2>/dev/null || true
+  fi
+}
+
+trap cleanup EXIT
+
+echo "[published-consumer] assembling install tarball from ${REPO_ROOT}"
+cp "${REPO_ROOT}/package.json" "${PACKAGE_STAGING}/package/package.json"
+cp "${REPO_ROOT}/Readme.md" "${PACKAGE_STAGING}/package/Readme.md"
+if [[ -f "${REPO_ROOT}/LICENSE" ]]; then
+  cp "${REPO_ROOT}/LICENSE" "${PACKAGE_STAGING}/package/LICENSE"
+fi
+cp -R "${REPO_ROOT}/src" "${PACKAGE_STAGING}/package/src"
+mkdir -p "${PACKAGE_STAGING}/package/dist/canvas" "${PACKAGE_STAGING}/package/dist/json-render"
+cp "${REPO_ROOT}/dist/canvas/index.js" "${PACKAGE_STAGING}/package/dist/canvas/index.js"
+cp "${REPO_ROOT}/dist/canvas/global.css" "${PACKAGE_STAGING}/package/dist/canvas/global.css"
+cp "${REPO_ROOT}/dist/json-render/index.js" "${PACKAGE_STAGING}/package/dist/json-render/index.js"
+cp "${REPO_ROOT}/dist/json-render/index.css" "${PACKAGE_STAGING}/package/dist/json-render/index.css"
+TARBALL="pmx-canvas-published-consumer.tgz"
+tar -czf "${PACK_DIR}/${TARBALL}" -C "${PACKAGE_STAGING}" package
+
+echo "[published-consumer] staging temp consumer at ${CONSUMER_DIR}"
+rm -rf "${CONSUMER_DIR}"
+mkdir -p "${CONSUMER_DIR}/demo"
+cp -R "${REPO_ROOT}/examples/published-consumer-sdlc/." "${CONSUMER_DIR}/demo/"
+cat > "${CONSUMER_DIR}/package.json" <<'JSON'
+{
+  "name": "pmx-canvas-published-consumer",
+  "private": true,
+  "type": "module"
+}
+JSON
+
+(cd "${CONSUMER_DIR}" && "${BUN_BIN}" add "${PACK_DIR}/${TARBALL}")
+
+echo "[published-consumer] starting seeded demo on port ${PORT}"
+SERVER_PID="$(
+  python3 - "${CONSUMER_DIR}" "${BUN_BIN}" "${PORT}" "${LOG_FILE}" <<'PY'
+import subprocess
+import sys
+
+consumer_dir, bun_bin, port, log_file = sys.argv[1:5]
+
+with open(log_file, "ab", buffering=0) as log:
+    proc = subprocess.Popen(
+        [bun_bin, "run", "demo/seed-demo.ts", f"--port={port}", "--hold"],
+        cwd=consumer_dir,
+        stdin=subprocess.DEVNULL,
+        stdout=log,
+        stderr=subprocess.STDOUT,
+        start_new_session=True,
+    )
+    print(proc.pid)
+PY
+)"
+
+READY=0
+for _ in $(seq 1 90); do
+  if curl -fsS "http://127.0.0.1:${PORT}/api/canvas/state" >/dev/null 2>&1; then
+    READY=1
+    break
+  fi
+  sleep 1
+done
+
+if [[ "${READY}" -ne 1 ]]; then
+  echo "[published-consumer] server did not become ready. Log follows:" >&2
+  cat "${LOG_FILE}" >&2 || true
+  exit 1
+fi
+
+SEEDED=0
+NODE_COUNT="0"
+for _ in $(seq 1 120); do
+  if ! kill -0 "${SERVER_PID}" 2>/dev/null; then
+    echo "[published-consumer] seeded demo process exited early. Log follows:" >&2
+    cat "${LOG_FILE}" >&2 || true
+    exit 1
+  fi
+
+  NODE_COUNT="$(
+    curl -fsS "http://127.0.0.1:${PORT}/api/canvas/state" \
+      | "${BUN_BIN}" -e 'let raw="";for await (const chunk of Bun.stdin.stream()){raw+=chunk instanceof Uint8Array ? Buffer.from(chunk).toString() : String(chunk);} const state=JSON.parse(raw); console.log(state.nodes.length);'
+  )"
+
+  if [[ "${NODE_COUNT}" -ge 18 ]]; then
+    SEEDED=1
+    break
+  fi
+
+  sleep 1
+done
+
+if [[ "${SEEDED}" -ne 1 ]]; then
+  echo "[published-consumer] demo did not finish seeding. Last node count: ${NODE_COUNT}" >&2
+  cat "${LOG_FILE}" >&2 || true
+  exit 1
+fi
+
+echo "[published-consumer] workspace ready"
+echo "  url: http://127.0.0.1:${PORT}/workbench"
+echo "  node-count: ${NODE_COUNT}"
+echo "  temp-workdir: ${WORKDIR}"
+echo "  server-log: ${LOG_FILE}"
+
+if [[ "${SKIP_PLAYWRIGHT}" -ne 1 ]]; then
+  echo "[published-consumer] running browser validation"
+  if ! command -v playwright-cli >/dev/null 2>&1; then
+    echo "[published-consumer] playwright-cli is required for browser validation." >&2
+    echo "Install it with: bun add -g @playwright/cli@latest" >&2
+    exit 1
+  fi
+
+  PLAYWRIGHT_SESSION="pc${PORT}"
+  PLAYWRIGHT_OPEN_CMD=(playwright-cli "-s=${PLAYWRIGHT_SESSION}" open "http://127.0.0.1:${PORT}/workbench" --browser chrome)
+  if [[ "${HEADED}" -eq 1 ]]; then
+    PLAYWRIGHT_OPEN_CMD+=(--headed)
+  fi
+
+  (
+    cd "${REPO_ROOT}"
+    rm -f .playwright-cli/page-*.yml .playwright-cli/page-*.png .playwright-cli/console-*.log 2>/dev/null || true
+    "${PLAYWRIGHT_OPEN_CMD[@]}"
+    sleep 3
+    playwright-cli "-s=${PLAYWRIGHT_SESSION}" snapshot >/dev/null
+
+    SNAPSHOT_FILE="$(ls -t .playwright-cli/page-*.yml | head -n 1)"
+    if [[ -z "${SNAPSHOT_FILE}" ]]; then
+      echo "[published-consumer] playwright-cli did not produce a snapshot." >&2
+      exit 1
+    fi
+
+    for expected in \
+      "Synthetic SDLC Report" \
+      "Pipeline Atlas" \
+      "SDLC Control Room Artifact" \
+      "Control Tower Widgets" \
+      "Release Gate Intake" \
+      "Service Readiness Matrix" \
+      "Lead Time Trend" \
+      "Defects by Stage" \
+      "Operational Load" \
+      "Context (3)" \
+      "npm pack" \
+      "canvas.buildWebArtifact" \
+      "playwright"
+    do
+      if ! rg -Fq "${expected}" "${SNAPSHOT_FILE}"; then
+        echo "[published-consumer] expected browser snapshot to include: ${expected}" >&2
+        echo "Snapshot: ${SNAPSHOT_FILE}" >&2
+        exit 1
+      fi
+    done
+
+    playwright-cli "-s=${PLAYWRIGHT_SESSION}" screenshot >/dev/null
+    SCREENSHOT_FILE="$(ls -t .playwright-cli/page-*.png | head -n 1)"
+    echo "[published-consumer] browser snapshot: ${SNAPSHOT_FILE}"
+    echo "[published-consumer] browser screenshot: ${SCREENSHOT_FILE}"
+
+    if [[ "${KEEP_RUNNING}" -ne 1 ]]; then
+      playwright-cli "-s=${PLAYWRIGHT_SESSION}" close >/dev/null || true
+    fi
+  )
+fi
+
+if [[ "${KEEP_RUNNING}" -eq 1 ]]; then
+  trap - EXIT
+  echo "[published-consumer] leaving server running"
+  echo "  PMX_CANVAS_URL=http://127.0.0.1:${PORT}"
+  echo "  PMX_CONSUMER_DIR=${CONSUMER_DIR}"
+  echo "  PMX_SERVER_PID=${SERVER_PID}"
+  exit 0
+fi
+
+cleanup
+trap - EXIT
+echo "[published-consumer] completed"

package/skills/web-artifacts-builder/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: web-artifacts-builder
+description: Suite of tools for creating elaborate, multi-component single-file HTML web artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
+license: Complete terms in LICENSE.txt
+---
+
+# Web Artifacts Builder
+
+To build powerful single-file frontend web artifacts, follow these steps:
+1. Initialize the frontend repo using `scripts/init-artifact.sh`
+2. Develop your artifact by editing the generated code
+3. Bundle all code into a single HTML file using `scripts/bundle-artifact.sh`
+4. Display artifact to user
+5. (Optional) Test the artifact
+
+**Stack**: React 18 + TypeScript + Vite + Parcel (bundling) + Tailwind CSS + shadcn/ui
+
+## Design & Style Guidelines
+
+VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font.
+
+## Quick Start
+
+In `pmx-canvas`, prefer the `canvas_build_web_artifact` MCP tool when available. It uses the same
+bundled runtime scripts, writes reusable source under `.pmx-canvas/artifacts/.web-artifacts/`,
+emits a bundled HTML file under `.pmx-canvas/artifacts/`, and can open the result directly on the
+canvas as an embedded node.
+For browser verification after the build, pair this skill with the local `playwright-cli` skill.
+
+### Step 1: Initialize Project
+
+Run the initialization script to create a new React project:
+```bash
+bash scripts/init-artifact.sh <project-name>
+cd <project-name>
+```
+
+This creates a fully configured project with:
+- ✅ React + TypeScript (via Vite)
+- ✅ Tailwind CSS 3.4.1 with shadcn/ui theming system
+- ✅ Path aliases (`@/`) configured
+- ✅ 40+ shadcn/ui components pre-installed
+- ✅ All Radix UI dependencies included
+- ✅ Parcel configured for bundling (via .parcelrc)
+- ✅ Node 18+ compatibility (auto-detects and pins Vite version)
+
+### Step 2: Develop Your Artifact
+
+To build the artifact, edit the generated files. See **Common Development Tasks** below for guidance.
+
+### Step 3: Bundle to Single HTML File
+
+To bundle the React app into a single HTML artifact:
+```bash
+bash scripts/bundle-artifact.sh
+```
+
+This creates `bundle.html` - a self-contained artifact with all JavaScript, CSS, and dependencies inlined. This file can be opened directly in a browser or shared in artifact-capable clients.
+
+**Requirements**: Your project must have an `index.html` in the root directory.
+
+**What the script does**:
+- Reuses existing bundling dependencies when present; otherwise installs them once
+- Creates `.parcelrc` config with path alias support
+- Builds with Parcel (no source maps) using a quieter log profile
+- Inlines all assets into single HTML using html-inline
+
+### Step 4: Share Artifact with User
+
+Finally, share the bundled HTML file with the user or open it in the browser so they can view it.
+
+### Step 5: Testing/Visualizing the Artifact (Optional)
+
+Note: This is a completely optional step. Only perform if necessary or requested.
+
+To test/visualize the artifact, use available tools (including other Skills or built-in tools like Playwright or Puppeteer). In general, avoid testing the artifact upfront as it adds latency between the request and when the finished artifact can be seen. Test later, after presenting the artifact, if requested or if issues arise.
+
+## Reference
+
+- **shadcn/ui components**: https://ui.shadcn.com/docs/components