@thorprovider/create-storefront 0.1.1

package/skills/building-storefronts/references/frontend-integration.md

@@ -0,0 +1,229 @@
+# Frontend SDK Integration
+
+## Contents
+- [Frontend SDK Pattern](#frontend-sdk-pattern)
+  - [Locating the SDK](#locating-the-sdk)
+  - [Using sdk.client.fetch()](#using-sdkclientfetch)
+- [React Query Pattern](#react-query-pattern)
+- [Query Key Best Practices](#query-key-best-practices)
+- [Error Handling](#error-handling)
+- [Optimistic Updates](#optimistic-updates)
+
+This guide covers how to integrate Medusa custom API routes with frontend applications using the Medusa SDK and React Query.
+
+**Note:** API routes are also referred to as "endpoints" - these terms are interchangeable.
+
+## Frontend SDK Pattern
+
+### Locating the SDK
+
+**IMPORTANT:** Never hardcode SDK import paths. Always locate where the SDK is instantiated in the project first.
+
+Look for `@medusajs/js-sdk`
+
+The SDK instance is typically exported as `sdk`:
+
+```typescript
+import { sdk } from "[LOCATE IN PROJECT]"
+```
+
+### Using sdk.client.fetch()
+
+**⚠️ CRITICAL: ALWAYS use the Medusa JS SDK for ALL API requests - NEVER use regular fetch()**
+
+**Why this is critical:**
+- **Store API routes** require the publishable API key in headers
+- **Admin API routes** require authentication headers
+- **Regular fetch()** without these headers will cause errors
+- The SDK automatically handles all required headers for you
+
+**When to use what:**
+- **Existing endpoints** (built-in Medusa routes): Use existing SDK methods like `sdk.store.product.list()`, `sdk.admin.order.retrieve()`
+- **Custom endpoints** (your custom API routes): Use `sdk.client.fetch()` for custom routes
+
+**⚠️ CRITICAL: The SDK handles JSON serialization automatically. NEVER use JSON.stringify() on the body.**
+
+Call custom API routes using the SDK:
+
+```typescript
+import { sdk } from "[LOCATE SDK INSTANCE IN PROJECT]"
+
+// ✅ CORRECT - Pass object directly
+const result = await sdk.client.fetch("/store/my-route", {
+  method: "POST",
+  body: {
+    email: "user@example.com",
+    name: "John Doe",
+  },
+})
+
+// ❌ WRONG - Don't use JSON.stringify
+const result = await sdk.client.fetch("/store/my-route", {
+  method: "POST",
+  body: JSON.stringify({  // ❌ DON'T DO THIS!
+    email: "user@example.com",
+  }),
+})
+```
+
+**Key points:**
+
+- **The SDK handles JSON serialization automatically** - just pass plain objects
+- **NEVER use JSON.stringify()** - this will break the request
+- No need to set Content-Type headers - SDK adds them
+- Session/JWT authentication is handled automatically
+- Publishable API key is automatically added
+
+### Built-in Endpoints vs Custom Endpoints
+
+**⚠️ CRITICAL: Use the appropriate SDK method based on endpoint type**
+
+```typescript
+import { sdk } from "[LOCATE SDK INSTANCE IN PROJECT]"
+
+// ✅ CORRECT - Built-in endpoint: Use existing SDK method
+const products = await sdk.store.product.list({
+  limit: 10,
+  offset: 0
+})
+
+// ✅ CORRECT - Custom endpoint: Use sdk.client.fetch()
+const reviews = await sdk.client.fetch("/store/products/prod_123/reviews")
+
+// ❌ WRONG - Using regular fetch for ANY endpoint
+const products = await fetch("http://localhost:9000/store/products")
+// ❌ Error: Missing publishable API key header!
+
+// ❌ WRONG - Using regular fetch for custom endpoint
+const reviews = await fetch("http://localhost:9000/store/products/prod_123/reviews")
+// ❌ Error: Missing publishable API key header!
+
+// ❌ WRONG - Using sdk.client.fetch() for built-in endpoint when SDK method exists
+const products = await sdk.client.fetch("/store/products")
+// ❌ Less type-safe than using sdk.store.product.list()
+```
+
+**Why this matters:**
+- **Store routes** require `x-publishable-api-key` header - SDK adds it automatically
+- **Admin routes** require `Authorization` and session cookie headers - SDK adds them automatically
+- **Regular fetch()** doesn't include these headers → API returns authentication/authorization errors
+- Using existing SDK methods provides **better type safety** and autocomplete
+
+## React Query Pattern
+
+Use `useQuery` for GET requests and `useMutation` for POST/DELETE:
+
+```typescript
+import { sdk } from "[LOCATE SDK INSTANCE IN PROJECT]"
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
+
+function MyComponent({ userId }: { userId: string }) {
+  const queryClient = useQueryClient()
+
+  // GET request - fetching data
+  const { data, isLoading } = useQuery({
+    queryKey: ["my-data", userId],
+    queryFn: () => sdk.client.fetch(`/store/my-route?userId=${userId}`),
+    enabled: !!userId,
+  })
+
+  // POST request - mutation with cache invalidation
+  const mutation = useMutation({
+    mutationFn: (input: { email: string }) =>
+      sdk.client.fetch("/store/my-route", { method: "POST", body: input }),
+    onSuccess: () => {
+      // Invalidate and refetch related queries
+      queryClient.invalidateQueries({ queryKey: ["my-data"] })
+    },
+  })
+
+  if (isLoading) return <p>Loading...</p>
+
+  return (
+    <div>
+      <p>{data?.title}</p>
+      <button
+        onClick={() => mutation.mutate({ email: "test@example.com" })}
+        disabled={mutation.isPending}
+      >
+        {mutation.isPending ? "Loading..." : "Submit"}
+      </button>
+      {mutation.isError && <p>Error occurred</p>}
+    </div>
+  )
+}
+```
+
+**Key states:** `isLoading`, `isPending`, `isSuccess`, `isError`, `error`
+
+## Query Key Best Practices
+
+Structure query keys for effective cache management:
+
+```typescript
+// Good: Hierarchical structure
+queryKey: ["products", productId]
+queryKey: ["products", "list", { page, filters }]
+
+// Invalidate all product queries
+queryClient.invalidateQueries({ queryKey: ["products"] })
+
+// Invalidate specific product
+queryClient.invalidateQueries({ queryKey: ["products", productId] })
+```
+
+## Error Handling
+
+Handle API errors gracefully:
+
+```typescript
+const mutation = useMutation({
+  mutationFn: (input) => sdk.client.fetch("/store/my-route", {
+    method: "POST",
+    body: input
+  }),
+  onError: (error) => {
+    console.error("Mutation failed:", error)
+    // Show error message to user
+  },
+})
+
+// In component
+{mutation.isError && (
+  <p className="error">
+    {mutation.error?.message || "An error occurred"}
+  </p>
+)}
+```
+
+## Optimistic Updates
+
+Update UI immediately before server confirms:
+
+```typescript
+const mutation = useMutation({
+  mutationFn: (newItem) =>
+    sdk.client.fetch("/store/items", { method: "POST", body: newItem }),
+  onMutate: async (newItem) => {
+    // Cancel outgoing refetches
+    await queryClient.cancelQueries({ queryKey: ["items"] })
+
+    // Snapshot previous value
+    const previousItems = queryClient.getQueryData(["items"])
+
+    // Optimistically update
+    queryClient.setQueryData(["items"], (old) => [...old, newItem])
+
+    // Return context with snapshot
+    return { previousItems }
+  },
+  onError: (err, newItem, context) => {
+    // Rollback on error
+    queryClient.setQueryData(["items"], context.previousItems)
+  },
+  onSettled: () => {
+    // Refetch after mutation
+    queryClient.invalidateQueries({ queryKey: ["items"] })
+  },
+})
+```

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

@@ -0,0 +1,291 @@
+---
+name: 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
+
+## Experimental Decision-Model Composition
+
+For decision-model composition, import `experimental_composeSpec` and `experimental_createEvaluator` from `@json-render/core`. These APIs are unreleased; use a source build until published, then pin exact versions. Experimental exports and `Experimental_` types can change in any release.
+
+- Run the Gateway evaluator server-side with `{ model: "typesafe-ai/jev", apiKey: process.env.AI_GATEWAY_API_KEY! }`. A plain model identifier is required; Jev is the current example; do not import a provider constructor.
+- Call `experimental_composeSpec({ catalog, candidates, prompt, evaluate, initialState, signal })`. It is an async generator; stream `step.spec` snapshots to your existing renderer and inspect `complete.stopReason` (`finish`, `limit`, `unavailable`). Errors and cancellation throw; retain the last snapshot as partial UI.
+- New trees default to `strategy: "batch"`: one evaluation selects root/membership, then a second arranges the selected elements when needed. The first snapshot contains selected content in catalog order under the root's default/first slot. Resource variants share one exclusive question; repeated counts include the root. Root selection takes precedence over conflicting speculative membership for that recipe/resource. Equal sibling positions retain catalog order. Combined layouts are validated before publication; cycles or excessive depth throw. `maxElements` caps batched creation (default 32). Limit-truncated selections or a missing required layout call return `limit`. Use `strategy: "sequential"` for legacy `next`/`parent` adapters or sequential creation. Edits stay sequential.
+- Batched trace steps use `choice: "select" | "layout"` and an `answers` record. Count each trace as one evaluation, including its tokens and latency once. Custom evaluators must answer every offered question; names/choices are opaque and include `root`/`select_*`, then `parent_*`/`order_*` for batches.
+- For follow-up edits, pass the selected version as `initialSpec`. It is cloned and validated; the evaluator may add, replace, remove non-root subtrees, or move/reorder them. Unchanged IDs, bindings, and state are preserved. Optional `elementDescriptions` shares identifying descriptions without exposing raw props/state. `initialState` overrides the seed state. Seeds must be valid trees within the catalog, expression subset, and depth limit. Matching recipes consume usage/resource limits; removals/replacements release them. Replacements/moves use two evaluations (select target, then recipe/destination), each counted against the budget. Treat operation and position keys as opaque.
+- Supply atomic candidates with `{ id, description, element: { type, props, on?, visible? }, root?, maxUses?, resource? }`. Catalog alone is insufficient: the app must supply values and binding recipes. Jev chooses elements and parent slots, never free-form text or code. It never executes actions.
+- Candidates are configured component instances, not page templates. Build them from current app records/operations or bind props to `initialState`; offer explicit alternatives for chart types, field configurations, and layout variants. The model chooses grouping and order within those options. Name required sections in prompts; structural validity does not imply semantic completeness.
+- V1 supports flat Spec catalogs, named slots, literals, `$state`, `$bindState`, and state visibility. No prebuilt children, repeat/watch, computed/template/conditional props, or custom directives. Success/error callbacks must reference allowed actions. Events must be declared in the component catalog.
+- Props and action params are validated against initial state without applying schema transforms/defaults. Supply valid initial values and validate/authorize action calls at runtime. Built-ins without parameter schemas get name validation only.
+- `root` defaults true, `maxUses` defaults one, shared `resource` values make alternatives mutually exclusive. Defaults: 32 evaluations (terminal calls included; no extra finish call for batches), depth eight, 10-second Gateway timeout per call. Supply an overall abort signal.
+- Candidate descriptions, prompt, instructions, topology, and explicit `context` are sent to the evaluator. Initial state and raw props/binding values are not sent automatically.
+- For custom providers implement `Experimental_CompositionEvaluator`: accept `{ state, questions, signal }`, return `{ answers: { [question]: { choice, confidence? } }, usage?: { inputTokens? } }`. Only return offered criteria keys.
+
+See `packages/core/README.md` and `/docs/jev` for app integration and source-build instructions. The web playground is an example consumer, not a dependency of the API.
+
+## 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);
+// issues include: missing_child, invalid_visible (malformed conditions),
+// repeat_without_children, repeat_item_outside_scope, repeat_state_mismatch
+
+const { spec: fixed, fixDetails } = autoFixSpec(spec);
+// fixDetails entries are { message, lossy }. Lossless fixes relocate
+// misplaced fields; lossy fixes prune dangling children references.
+// In a repair loop, withhold lossy fixes until retries are exhausted:
+const attempt = autoFixSpec(spec, { lossy: retriesExhausted });
+```
+
+## 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; classifies fixes lossy/lossless, `{ lossy: false }` withholds pruning |
+| `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) |