pmx-canvas 0.1.0

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+In `pmx-canvas`, use `canvas_build_web_artifact` when the result should be a full custom React app,
+and use `canvas_add_json_render_node` when a schema-driven UI panel is enough.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

package/skills/json-render-codegen/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: json-render-codegen
+description: Code generation utilities for json-render. Use when generating code from UI specs, building custom code exporters, traversing specs, or serializing props for @json-render/codegen.
+---
+
+# @json-render/codegen
+
+Framework-agnostic utilities for generating code from json-render UI trees. Use these to build custom code exporters for Next.js, Remix, or other frameworks.
+
+## Installation
+
+```bash
+npm install @json-render/codegen
+```
+
+## Tree Traversal
+
+```typescript
+import {
+  traverseSpec,
+  collectUsedComponents,
+  collectStatePaths,
+  collectActions,
+} from "@json-render/codegen";
+
+// Walk the spec depth-first
+traverseSpec(spec, (element, key, depth, parent) => {
+  console.log(`${" ".repeat(depth * 2)}${key}: ${element.type}`);
+});
+
+// Get all component types used
+const components = collectUsedComponents(spec);
+// Set { "Card", "Metric", "Button" }
+
+// Get all state paths referenced
+const statePaths = collectStatePaths(spec);
+// Set { "analytics/revenue", "user/name" }
+
+// Get all action names
+const actions = collectActions(spec);
+// Set { "submit_form", "refresh_data" }
+```
+
+## Serialization
+
+```typescript
+import {
+  serializePropValue,
+  serializeProps,
+  escapeString,
+  type SerializeOptions,
+} from "@json-render/codegen";
+
+// Serialize a single value
+serializePropValue("hello");
+// { value: '"hello"', needsBraces: false }
+
+serializePropValue({ $state: "/user/name" });
+// { value: '{ $state: "/user/name" }', needsBraces: true }
+
+// Serialize props for JSX
+serializeProps({ title: "Dashboard", columns: 3, disabled: true });
+// 'title="Dashboard" columns={3} disabled'
+
+// Escape strings for code
+escapeString('hello "world"');
+// 'hello \"world\"'
+```
+
+### SerializeOptions
+
+```typescript
+interface SerializeOptions {
+  quotes?: "single" | "double";
+  indent?: number;
+}
+```
+
+## Types
+
+```typescript
+import type { GeneratedFile, CodeGenerator } from "@json-render/codegen";
+
+const myGenerator: CodeGenerator = {
+  generate(spec) {
+    return [
+      { path: "package.json", content: "..." },
+      { path: "app/page.tsx", content: "..." },
+    ];
+  },
+};
+```
+
+## Building a Custom Generator
+
+```typescript
+import {
+  collectUsedComponents,
+  collectStatePaths,
+  traverseSpec,
+  serializeProps,
+  type GeneratedFile,
+} from "@json-render/codegen";
+import type { Spec } from "@json-render/core";
+
+export function generateNextJSProject(spec: Spec): GeneratedFile[] {
+  const files: GeneratedFile[] = [];
+  const components = collectUsedComponents(spec);
+  // Generate package.json, component files, main page...
+  return files;
+}
+```

package/skills/json-render-core/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: json-render-core
+description: Core package for defining schemas, catalogs, and AI prompt generation for json-render. Use when working with @json-render/core, defining schemas, creating catalogs, or building JSON specs for UI/video generation.
+---
+
+# @json-render/core
+
+Core package for schema definition, catalog creation, and spec streaming.
+
+## Key Concepts
+
+- **Schema**: Defines the structure of specs and catalogs (use `defineSchema`)
+- **Catalog**: Maps component/action names to their definitions (use `defineCatalog`)
+- **Spec**: JSON output from AI that conforms to the schema
+- **SpecStream**: JSONL streaming format for progressive spec building
+
+## Defining a Schema
+
+```typescript
+import { defineSchema } from "@json-render/core";
+
+export const schema = defineSchema((s) => ({
+  spec: s.object({
+    // Define spec structure
+  }),
+  catalog: s.object({
+    components: s.map({
+      props: s.zod(),
+      description: s.string(),
+    }),
+  }),
+}), {
+  promptTemplate: myPromptTemplate, // Optional custom AI prompt
+});
+```
+
+## Creating a Catalog
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "./schema";
+import { z } from "zod";
+
+export const catalog = defineCatalog(schema, {
+  components: {
+    Button: {
+      props: z.object({
+        label: z.string(),
+        variant: z.enum(["primary", "secondary"]).nullable(),
+      }),
+      description: "Clickable button component",
+    },
+  },
+});
+```
+
+## Generating AI Prompts
+
+```typescript
+const systemPrompt = catalog.prompt(); // Uses schema's promptTemplate
+const systemPrompt = catalog.prompt({ customRules: ["Rule 1", "Rule 2"] });
+```
+
+## SpecStream Utilities
+
+For streaming AI responses (JSONL patches):
+
+```typescript
+import { createSpecStreamCompiler } from "@json-render/core";
+
+const compiler = createSpecStreamCompiler<MySpec>();
+
+// Process streaming chunks
+const { result, newPatches } = compiler.push(chunk);
+
+// Get final result
+const finalSpec = compiler.getResult();
+```
+
+## Dynamic Prop Expressions
+
+Any prop value can be a dynamic expression resolved at render time:
+
+- **`{ "$state": "/state/key" }`** - reads a value from the state model (one-way read)
+- **`{ "$bindState": "/path" }`** - two-way binding: reads from state and enables write-back. Use on the natural value prop (value, checked, pressed, etc.) of form components.
+- **`{ "$bindItem": "field" }`** - two-way binding to a repeat item field. Use inside repeat scopes.
+- **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - evaluates a visibility condition and picks a branch
+- **`{ "$template": "Hello, ${/user/name}!" }`** - interpolates `${/path}` references with state values
+- **`{ "$computed": "fnName", "args": { "key": <expression> } }`** - calls a registered function with resolved args
+
+`$cond` uses the same syntax as visibility conditions (`$state`, `eq`, `neq`, `not`, arrays for AND). `$then` and `$else` can themselves be expressions (recursive).
+
+Components do not use a `statePath` prop for two-way binding. Instead, use `{ "$bindState": "/path" }` on the natural value prop (e.g. `value`, `checked`, `pressed`).
+
+```json
+{
+  "color": {
+    "$cond": { "$state": "/activeTab", "eq": "home" },
+    "$then": "#007AFF",
+    "$else": "#8E8E93"
+  },
+  "label": { "$template": "Welcome, ${/user/name}!" },
+  "fullName": {
+    "$computed": "fullName",
+    "args": {
+      "first": { "$state": "/form/firstName" },
+      "last": { "$state": "/form/lastName" }
+    }
+  }
+}
+```
+
+```typescript
+import { resolvePropValue, resolveElementProps } from "@json-render/core";
+
+const resolved = resolveElementProps(element.props, { stateModel: myState });
+```
+
+## State Watchers
+
+Elements can declare a `watch` field (top-level, sibling of type/props/children) to trigger actions when state values change:
+
+```json
+{
+  "type": "Select",
+  "props": { "value": { "$bindState": "/form/country" }, "options": ["US", "Canada"] },
+  "watch": {
+    "/form/country": { "action": "loadCities", "params": { "country": { "$state": "/form/country" } } }
+  },
+  "children": []
+}
+```
+
+Watchers only fire on value changes, not on initial render.
+
+## Validation
+
+Built-in validation functions: `required`, `email`, `url`, `numeric`, `minLength`, `maxLength`, `min`, `max`, `pattern`, `matches`, `equalTo`, `lessThan`, `greaterThan`, `requiredIf`.
+
+Cross-field validation uses `$state` expressions in args:
+
+```typescript
+import { check } from "@json-render/core";
+
+check.required("Field is required");
+check.matches("/form/password", "Passwords must match");
+check.lessThan("/form/endDate", "Must be before end date");
+check.greaterThan("/form/startDate", "Must be after start date");
+check.requiredIf("/form/enableNotifications", "Required when enabled");
+```
+
+## User Prompt Builder
+
+Build structured user prompts with optional spec refinement and state context:
+
+```typescript
+import { buildUserPrompt } from "@json-render/core";
+
+// Fresh generation
+buildUserPrompt({ prompt: "create a todo app" });
+
+// Refinement with edit modes (default: patch-only)
+buildUserPrompt({ prompt: "add a toggle", currentSpec: spec, editModes: ["patch", "merge"] });
+
+// With runtime state
+buildUserPrompt({ prompt: "show data", state: { todos: [] } });
+```
+
+Available edit modes: `"patch"` (RFC 6902 JSON Patch), `"merge"` (RFC 7396 Merge Patch), `"diff"` (unified diff).
+
+## Spec Validation
+
+Validate spec structure and auto-fix common issues:
+
+```typescript
+import { validateSpec, autoFixSpec } from "@json-render/core";
+
+const { valid, issues } = validateSpec(spec);
+const fixed = autoFixSpec(spec);
+```
+
+## Visibility Conditions
+
+Control element visibility with state-based conditions. `VisibilityContext` is `{ stateModel: StateModel }`.
+
+```typescript
+import { visibility } from "@json-render/core";
+
+// Syntax
+{ "$state": "/path" }                    // truthiness
+{ "$state": "/path", "not": true }      // falsy
+{ "$state": "/path", "eq": value }      // equality
+[ cond1, cond2 ]                         // implicit AND
+
+// Helpers
+visibility.when("/path")                 // { $state: "/path" }
+visibility.unless("/path")               // { $state: "/path", not: true }
+visibility.eq("/path", val)              // { $state: "/path", eq: val }
+visibility.and(cond1, cond2)             // { $and: [cond1, cond2] }
+visibility.or(cond1, cond2)             // { $or: [cond1, cond2] }
+visibility.always                        // true
+visibility.never                         // false
+```
+
+## Built-in Actions in Schema
+
+Schemas can declare `builtInActions` -- actions that are always available at runtime and auto-injected into prompts:
+
+```typescript
+const schema = defineSchema(builder, {
+  builtInActions: [
+    { name: "setState", description: "Update a value in the state model" },
+  ],
+});
+```
+
+These appear in prompts as `[built-in]` and don't require handlers in `defineRegistry`.
+
+## StateStore
+
+The `StateStore` interface allows external state management libraries (Redux, Zustand, XState, etc.) to be plugged into json-render renderers. The `createStateStore` factory creates a simple in-memory implementation:
+
+```typescript
+import { createStateStore, type StateStore } from "@json-render/core";
+
+const store = createStateStore({ count: 0 });
+
+store.get("/count");         // 0
+store.set("/count", 1);      // updates and notifies subscribers
+store.update({ "/a": 1, "/b": 2 }); // batch update
+
+store.subscribe(() => {
+  console.log(store.getSnapshot()); // { count: 1 }
+});
+```
+
+The `StateStore` interface: `get(path)`, `set(path, value)`, `update(updates)`, `getSnapshot()`, `subscribe(listener)`.
+
+## Key Exports
+
+| Export | Purpose |
+|--------|---------|
+| `defineSchema` | Create a new schema |
+| `defineCatalog` | Create a catalog from schema |
+| `createStateStore` | Create a framework-agnostic in-memory `StateStore` |
+| `resolvePropValue` | Resolve a single prop expression against data |
+| `resolveElementProps` | Resolve all prop expressions in an element |
+| `buildUserPrompt` | Build user prompts with refinement and state context |
+| `buildEditUserPrompt` | Build user prompt for editing existing specs |
+| `buildEditInstructions` | Generate prompt section for available edit modes |
+| `isNonEmptySpec` | Check if spec has root and at least one element |
+| `deepMergeSpec` | RFC 7396 deep merge (null deletes, arrays replace, objects recurse) |
+| `diffToPatches` | Generate RFC 6902 JSON Patch operations from object diff |
+| `EditMode` | Type: `"patch" \| "merge" \| "diff"` |
+| `validateSpec` | Validate spec structure |
+| `autoFixSpec` | Auto-fix common spec issues |
+| `createSpecStreamCompiler` | Stream JSONL patches into spec |
+| `createJsonRenderTransform` | TransformStream separating text from JSONL in mixed streams |
+| `parseSpecStreamLine` | Parse single JSONL line |
+| `applySpecStreamPatch` | Apply patch to object |
+| `StateStore` | Interface for plugging in external state management |
+| `ComputedFunction` | Function signature for `$computed` expressions |
+| `check` | TypeScript helpers for creating validation checks |
+| `BuiltInAction` | Type for built-in action definitions (`name` + `description`) |
+| `ActionBinding` | Action binding type (includes `preventDefault` field) |