@thorprovider/create-storefront 0.1.1

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

@@ -0,0 +1,194 @@
+---
+name: next
+description: Next.js renderer for json-render that turns JSON specs into full Next.js applications with routes, layouts, SSR, and metadata. Use when working with @json-render/next, building Next.js apps from JSON specs, or creating AI-generated multi-page applications.
+---
+
+# @json-render/next
+
+Next.js renderer that converts JSON specs into full Next.js applications with routes, pages, layouts, metadata, and SSR support.
+
+## Quick Start
+
+```bash
+npm install @json-render/core @json-render/react @json-render/next
+```
+
+### 1. Define Your Spec
+
+```typescript
+// lib/spec.ts
+import type { NextAppSpec } from "@json-render/next";
+
+export const spec: NextAppSpec = {
+  metadata: {
+    title: { default: "My App", template: "%s | My App" },
+    description: "A json-render Next.js application",
+  },
+  layouts: {
+    main: {
+      root: "shell",
+      elements: {
+        shell: { type: "Container", props: {}, children: ["nav", "slot"] },
+        nav: { type: "NavBar", props: { links: [
+          { href: "/", label: "Home" },
+          { href: "/about", label: "About" },
+        ]}, children: [] },
+        slot: { type: "Slot", props: {}, children: [] },
+      },
+    },
+  },
+  routes: {
+    "/": {
+      layout: "main",
+      metadata: { title: "Home" },
+      page: {
+        root: "hero",
+        elements: {
+          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
+        },
+      },
+    },
+    "/about": {
+      layout: "main",
+      metadata: { title: "About" },
+      page: {
+        root: "content",
+        elements: {
+          content: { type: "Card", props: { title: "About Us" }, children: [] },
+        },
+      },
+    },
+  },
+};
+```
+
+### 2. Create the App
+
+```typescript
+// lib/app.ts
+import { createNextApp } from "@json-render/next/server";
+import { spec } from "./spec";
+
+export const { Page, generateMetadata, generateStaticParams } = createNextApp({
+  spec,
+  loaders: {
+    // Server-side data loaders (optional)
+    loadPost: async ({ slug }) => {
+      const post = await getPost(slug as string);
+      return { post };
+    },
+  },
+});
+```
+
+### 3. Wire Up Route Files
+
+```tsx
+// app/[[...slug]]/page.tsx
+export { Page as default, generateMetadata, generateStaticParams } from "@/lib/app";
+```
+
+```tsx
+// app/[[...slug]]/layout.tsx
+import { NextAppProvider } from "@json-render/next";
+import { registry, handlers } from "@/lib/registry";
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <NextAppProvider registry={registry} handlers={handlers}>
+          {children}
+        </NextAppProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Key Concepts
+
+### NextAppSpec
+
+The top-level spec defines an entire Next.js application:
+
+- **metadata**: Root-level SEO metadata (title template, description, OpenGraph)
+- **layouts**: Reusable layout element trees (each must include a `Slot` component)
+- **routes**: Route definitions keyed by URL pattern
+- **state**: Global initial state shared across all routes
+
+### Route Patterns
+
+Routes use Next.js URL conventions:
+
+- `"/"` -- home page
+- `"/about"` -- static route
+- `"/blog/[slug]"` -- dynamic segment
+- `"/docs/[...path]"` -- catch-all segment
+- `"/settings/[[...path]]"` -- optional catch-all segment
+
+### Layouts
+
+Layouts wrap page content. Every layout MUST include a `Slot` component where page content will be rendered. Layouts are defined once in `spec.layouts` and referenced by routes via the `layout` field.
+
+### Built-in Components
+
+- **Slot**: Placeholder in layouts where page content is rendered
+- **Link**: Client-side navigation link (wraps `next/link`)
+
+### Built-in Actions
+
+- **setState**: Update state value. Params: `{ statePath, value }`
+- **pushState**: Append to array. Params: `{ statePath, value, clearStatePath? }`
+- **removeState**: Remove from array by index. Params: `{ statePath, index }`
+- **navigate**: Client-side navigation. Params: `{ href }`
+
+### Data Loaders
+
+Server-side async functions that run in the Server Component before rendering. Results are merged into the page's initial state.
+
+```typescript
+createNextApp({
+  spec,
+  loaders: {
+    loadPost: async ({ slug }) => {
+      const post = await db.post.findUnique({ where: { slug } });
+      return { post };
+    },
+  },
+});
+```
+
+### SSR
+
+Pages are server-rendered automatically. The `createNextApp` `Page` component is an async Server Component that:
+
+1. Matches the route from the spec
+2. Runs server-side data loaders
+3. Generates metadata
+4. Passes the resolved spec to the client renderer for hydration
+
+### Entry Points
+
+- `@json-render/next` -- Client components (NextAppProvider, PageRenderer, Link)
+- `@json-render/next/server` -- Server utilities (createNextApp, matchRoute, schema)
+
+## API Reference
+
+### Server Exports (`@json-render/next/server`)
+
+- `createNextApp(options)` -- Create Page, generateMetadata, generateStaticParams
+- `schema` -- Custom schema for Next.js apps (for AI catalog generation)
+- `matchRoute(spec, pathname)` -- Match a URL to a route spec
+- `resolveMetadata(spec, route)` -- Resolve metadata for a route
+- `slugToPath(slug)` -- Convert catch-all slug array to pathname
+- `collectStaticParams(spec)` -- Collect static params for all routes
+
+### Client Exports (`@json-render/next`)
+
+- `NextAppProvider` -- Context provider for registry and handlers
+- `PageRenderer` -- Renders a page spec with optional layout
+- `NextErrorBoundary` -- Error boundary component
+- `NextLoading` -- Loading state component
+- `NextNotFound` -- Not-found component
+- `Link` -- Built-in navigation component (wraps next/link)

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

@@ -0,0 +1,298 @@
+---
+name: react
+description: React renderer for json-render that turns JSON specs into React components. Use when working with @json-render/react, building React UIs from JSON, creating component catalogs, or rendering AI-generated specs.
+---
+
+# @json-render/react
+
+React renderer that converts JSON specs into React component trees.
+
+## Quick Start
+
+```typescript
+import { defineRegistry, Renderer } from "@json-render/react";
+import { catalog } from "./catalog";
+
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: ({ props, children }) => <div>{props.title}{children}</div>,
+  },
+});
+
+function App({ spec }) {
+  return <Renderer spec={spec} registry={registry} />;
+}
+```
+
+## Creating a Catalog
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { defineRegistry } from "@json-render/react";
+import { z } from "zod";
+
+// Create catalog with props schemas
+export const catalog = defineCatalog(schema, {
+  components: {
+    Button: {
+      props: z.object({
+        label: z.string(),
+        variant: z.enum(["primary", "secondary"]).nullable(),
+      }),
+      description: "Clickable button",
+    },
+    Card: {
+      props: z.object({ title: z.string() }),
+      slots: ["default"],
+      description: "Card container with title",
+    },
+    Layout: {
+      props: z.object({}),
+      slots: ["default", "header", "footer"],
+      description: "Layout with named content regions",
+    },
+  },
+});
+
+// Define component implementations with type-safe props
+const { registry } = defineRegistry(catalog, {
+  components: {
+    Button: ({ props }) => (
+      <button className={props.variant}>{props.label}</button>
+    ),
+    Card: ({ props, children }) => (
+      <div className="card">
+        <h2>{props.title}</h2>
+        {children}
+      </div>
+    ),
+    Layout: ({ children, slots }) => (
+      <div>
+        <header>{slots?.header}</header>
+        <main>{children}</main>
+        <footer>{slots?.footer}</footer>
+      </div>
+    ),
+  },
+});
+```
+
+## Spec Structure (Element Tree)
+
+The React schema uses an element tree format:
+
+```json
+{
+  "root": {
+    "type": "Card",
+    "props": { "title": "Hello" },
+    "children": [{ "type": "Button", "props": { "label": "Click me" } }]
+  }
+}
+```
+
+## Named Slots
+
+Use `children` for the `"default"` slot. Use the element's top-level `slots` object for other slot names declared by the catalog:
+
+```json
+{
+  "type": "Layout",
+  "props": {},
+  "children": ["main"],
+  "slots": {
+    "header": ["heading"],
+    "footer": ["actions"]
+  }
+}
+```
+
+Registry components receive named content as `slots?.header`, `slots?.footer`, and so on. Do not use `slots.default`.
+
+## Visibility Conditions
+
+Use `visible` on elements to show/hide based on state. New syntax: `{ "$state": "/path" }`, `{ "$state": "/path", "eq": value }`, `{ "$state": "/path", "not": true }`, `{ "$and": [cond1, cond2] }` for AND, `{ "$or": [cond1, cond2] }` for OR. Helpers: `visibility.when("/path")`, `visibility.unless("/path")`, `visibility.eq("/path", val)`, `visibility.and(cond1, cond2)`, `visibility.or(cond1, cond2)`.
+
+## Providers
+
+| Provider             | Purpose                                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------------------ |
+| `StateProvider`      | Share state across components (JSON Pointer paths). Accepts optional `store` prop for controlled mode. |
+| `ActionProvider`     | Handle actions dispatched via the event system                                                         |
+| `VisibilityProvider` | Enable conditional rendering based on state                                                            |
+| `ValidationProvider` | Form field validation                                                                                  |
+
+### External Store (Controlled Mode)
+
+Pass a `StateStore` to `StateProvider` (or `JSONUIProvider` / `createRenderer`) to use external state management (Redux, Zustand, XState, etc.):
+
+```tsx
+import { createStateStore, type StateStore } from "@json-render/react";
+
+const store = createStateStore({ count: 0 });
+
+<StateProvider store={store}>{children}</StateProvider>;
+
+// Mutate from anywhere — React re-renders automatically:
+store.set("/count", 1);
+```
+
+When `store` is provided, `initialState` and `onStateChange` are ignored.
+
+## Dynamic Prop Expressions
+
+Any prop value can be a data-driven expression resolved by the renderer before components receive props:
+
+- **`{ "$state": "/state/key" }`** - reads from 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.
+- **Filtered lists**: `repeat` plus an `$item` visible condition on the same container renders only matching items: `{ "repeat": { "statePath": "/tasks", "key": "id" }, "visible": { "$item": "status", "eq": "todo" }, "children": ["task-card"] }`. AND-composed `$state` conjuncts gate the container shell; `$item`/`$index` conjuncts filter items.
+- **Nested lists**: inside a repeat, use `{ "repeat": { "statePath": { "$item": "comments" }, "key": "id" } }` to iterate an array on the enclosing item.
+- **`{ "$cond": <condition>, "$then": <value>, "$else": <value> }`** - conditional value
+- **`{ "$template": "Hello, ${/name}!" }`** - interpolates state values into strings
+- **`{ "$computed": "fn", "args": { ... } }`** - calls registered functions with resolved args
+
+```json
+{
+  "type": "Input",
+  "props": {
+    "value": { "$bindState": "/form/email" },
+    "placeholder": "Email"
+  }
+}
+```
+
+Components do not use a `statePath` prop for two-way binding. Use `{ "$bindState": "/path" }` on the natural value prop instead.
+
+Components receive already-resolved props. For two-way bound props, use the `useBoundProp` hook with the `bindings` map the renderer provides.
+
+Register `$computed` functions via the `functions` prop on `JSONUIProvider` or `createRenderer`:
+
+```tsx
+<JSONUIProvider
+  functions={{ fullName: (args) => `${args.first} ${args.last}` }}
+>
+```
+
+## Event System
+
+Components use `emit` to fire named events, or `on()` to get an event handle with metadata. The element's `on` field maps events to action bindings:
+
+```tsx
+// Simple event firing
+Button: ({ props, emit }) => (
+  <button onClick={() => emit("press")}>{props.label}</button>
+),
+
+// Event handle with metadata (e.g. preventDefault)
+Link: ({ props, on }) => {
+  const click = on("click");
+  return (
+    <a href={props.href} onClick={(e) => {
+      if (click.shouldPreventDefault) e.preventDefault();
+      click.emit();
+    }}>{props.label}</a>
+  );
+},
+```
+
+```json
+{
+  "type": "Button",
+  "props": { "label": "Submit" },
+  "on": { "press": { "action": "submit" } }
+}
+```
+
+The `EventHandle` returned by `on()` has: `emit()`, `shouldPreventDefault` (boolean), and `bound` (boolean).
+
+## 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" } },
+  "children": []
+}
+```
+
+## Built-in Actions
+
+The `setState`, `pushState`, `removeState`, and `validateForm` actions are built into the React schema and handled automatically by `ActionProvider`. They are injected into AI prompts without needing to be declared in catalog `actions`:
+
+```json
+{ "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } }
+{ "action": "pushState", "params": { "statePath": "/items", "value": { "text": "New" } } }
+{ "action": "removeState", "params": { "statePath": "/items", "index": 0 } }
+{ "action": "validateForm", "params": { "statePath": "/formResult" } }
+```
+
+`validateForm` validates all registered fields and writes `{ valid, errors }` to state.
+
+Note: `statePath` in action params (e.g. `setState.statePath`) targets the mutation path. Two-way binding in component props uses `{ "$bindState": "/path" }` on the value prop, not `statePath`.
+
+## useBoundProp
+
+For form components that need two-way binding, use `useBoundProp` with the `bindings` map the renderer provides when a prop uses `{ "$bindState": "/path" }` or `{ "$bindItem": "field" }`:
+
+```tsx
+import { useBoundProp } from "@json-render/react";
+
+Input: ({ element, bindings }) => {
+  const [value, setValue] = useBoundProp<string>(
+    element.props.value,
+    bindings?.value
+  );
+  return (
+    <input
+      value={value ?? ""}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+},
+```
+
+`useBoundProp(propValue, bindingPath)` returns `[value, setValue]`. The `value` is the resolved prop; `setValue` writes back to the bound state path (no-op if not bound).
+
+## BaseComponentProps
+
+For building reusable component libraries not tied to a specific catalog (e.g. `@json-render/shadcn`):
+
+```typescript
+import type { BaseComponentProps } from "@json-render/react";
+
+const Card = ({ props, children }: BaseComponentProps<{ title?: string }>) => (
+  <div>{props.title}{children}</div>
+);
+```
+
+## defineRegistry
+
+`defineRegistry` conditionally requires the `actions` field only when the catalog declares actions. Catalogs with `actions: {}` can omit it.
+
+## Key Exports
+
+| Export                  | Purpose                                                                                               |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `defineRegistry`        | Create a type-safe component registry from a catalog                                                  |
+| `Renderer`              | Render a spec using a registry                                                                        |
+| `schema`                | Element tree schema (includes built-in state actions: setState, pushState, removeState, validateForm) |
+| `useStateStore`         | Access state context                                                                                  |
+| `useStateValue`         | Get single value from state                                                                           |
+| `useBoundProp`          | Two-way binding for `$bindState`/`$bindItem` expressions                                              |
+| `useActions`            | Access actions context                                                                                |
+| `useAction`             | Get a single action dispatch function                                                                 |
+| `useOptionalValidation` | Non-throwing variant of useValidation (returns null if no provider)                                   |
+| `useUIStream`           | Stream specs from an API endpoint                                                                     |
+| `createStateStore`      | Create a framework-agnostic in-memory `StateStore`                                                    |
+| `StateStore`            | Interface for plugging in external state management                                                   |
+| `BaseComponentProps`    | Catalog-agnostic base type for reusable component libraries                                           |
+| `EventHandle`           | Event handle type (`emit`, `shouldPreventDefault`, `bound`)                                           |
+| `ComponentContext`      | Typed component context (catalog-aware)                                                               |

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

@@ -0,0 +1,111 @@
+---
+name: remotion
+description: Remotion renderer for json-render that turns JSON timeline specs into videos. Use when working with @json-render/remotion, building video compositions from JSON, creating video catalogs, or rendering AI-generated video timelines.
+---
+
+# @json-render/remotion
+
+Remotion renderer that converts JSON timeline specs into video compositions.
+
+## Quick Start
+
+```typescript
+import { Player } from "@remotion/player";
+import { Renderer, type TimelineSpec } from "@json-render/remotion";
+
+function VideoPlayer({ spec }: { spec: TimelineSpec }) {
+  return (
+    <Player
+      component={Renderer}
+      inputProps={{ spec }}
+      durationInFrames={spec.composition.durationInFrames}
+      fps={spec.composition.fps}
+      compositionWidth={spec.composition.width}
+      compositionHeight={spec.composition.height}
+      controls
+    />
+  );
+}
+```
+
+## Using Standard Components
+
+```typescript
+import { defineCatalog } from "@json-render/core";
+import {
+  schema,
+  standardComponentDefinitions,
+  standardTransitionDefinitions,
+  standardEffectDefinitions,
+} from "@json-render/remotion";
+
+export const videoCatalog = defineCatalog(schema, {
+  components: standardComponentDefinitions,
+  transitions: standardTransitionDefinitions,
+  effects: standardEffectDefinitions,
+});
+```
+
+## Adding Custom Components
+
+```typescript
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+  components: {
+    ...standardComponentDefinitions,
+    MyCustomClip: {
+      props: z.object({ text: z.string() }),
+      type: "scene",
+      defaultDuration: 90,
+      description: "My custom video clip",
+    },
+  },
+});
+
+// Pass custom component to Renderer
+<Player
+  component={Renderer}
+  inputProps={{
+    spec,
+    components: { MyCustomClip: MyCustomComponent },
+  }}
+/>
+```
+
+## Timeline Spec Structure
+
+```json
+{
+  "composition": { "id": "video", "fps": 30, "width": 1920, "height": 1080, "durationInFrames": 300 },
+  "tracks": [{ "id": "main", "name": "Main", "type": "video", "enabled": true }],
+  "clips": [
+    { "id": "clip-1", "trackId": "main", "component": "TitleCard", "props": { "title": "Hello" }, "from": 0, "durationInFrames": 90 }
+  ],
+  "audio": { "tracks": [] }
+}
+```
+
+## Standard Components
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| `TitleCard` | scene | Full-screen title with subtitle |
+| `TypingText` | scene | Terminal-style typing animation |
+| `ImageSlide` | image | Full-screen image display |
+| `SplitScreen` | scene | Two-panel comparison |
+| `QuoteCard` | scene | Quote with attribution |
+| `StatCard` | scene | Animated statistic display |
+| `TextOverlay` | overlay | Text overlay |
+| `LowerThird` | overlay | Name/title overlay |
+
+## Key Exports
+
+| Export | Purpose |
+|--------|---------|
+| `Renderer` | Render spec to Remotion composition |
+| `schema` | Timeline schema |
+| `standardComponents` | Pre-built component registry |
+| `standardComponentDefinitions` | Catalog definitions |
+| `useTransition` | Transition animation hook |
+| `ClipWrapper` | Wrap clips with transitions |