@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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

@@ -1,229 +0,0 @@
-# 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-remotion/SKILL.md

@@ -1,111 +0,0 @@
----
-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 |

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

@@ -1,204 +0,0 @@
----
-name: solid
-description: SolidJS renderer for json-render. Use when building @json-render/solid catalogs/registries, wiring Renderer providers, implementing bindings/actions, or troubleshooting Solid-specific reactivity patterns.
----
-
-# @json-render/solid
-
-`@json-render/solid` renders json-render specs into Solid component trees with fine-grained reactivity.
-
-## Quick Start
-
-```tsx
-import { Renderer, JSONUIProvider } from "@json-render/solid";
-import type { Spec } from "@json-render/solid";
-import { registry } from "./registry";
-
-export function App(props: { spec: Spec | null }) {
-  return (
-    <JSONUIProvider registry={registry} initialState={{}}>
-      <Renderer spec={props.spec} registry={registry} />
-    </JSONUIProvider>
-  );
-}
-```
-
-## Create a Catalog
-
-```typescript
-import { defineCatalog } from "@json-render/core";
-import { schema } from "@json-render/solid/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",
-    },
-    Card: {
-      props: z.object({ title: z.string() }),
-      description: "Card container",
-    },
-  },
-  actions: {
-    submit: { description: "Submit data" },
-  },
-});
-```
-
-## Define Components
-
-Components receive `ComponentRenderProps` from the renderer:
-
-```ts
-interface ComponentRenderProps<P = Record<string, unknown>> {
-  element: UIElement<string, P>;
-  children?: JSX.Element;
-  emit: (event: string) => void;
-  on: (event: string) => EventHandle;
-  bindings?: Record<string, string>;
-  loading?: boolean;
-}
-```
-
-Example:
-
-```tsx
-import type { BaseComponentProps } from "@json-render/solid";
-
-export function Button(props: BaseComponentProps<{ label: string }>) {
-  return (
-    <button onClick={() => props.emit("press")}>{props.props.label}</button>
-  );
-}
-```
-
-## Create a Registry
-
-```typescript
-import { defineRegistry } from "@json-render/solid";
-import { catalog } from "./catalog";
-import { Card } from "./Card";
-import { Button } from "./Button";
-
-const { registry, handlers, executeAction } = defineRegistry(catalog, {
-  components: {
-    Card,
-    Button,
-  },
-  actions: {
-    submit: async (params, setState, state) => {
-      // custom action logic
-    },
-  },
-});
-```
-
-## Spec Structure
-
-```json
-{
-  "root": "card1",
-  "elements": {
-    "card1": {
-      "type": "Card",
-      "props": { "title": "Hello" },
-      "children": ["btn1"]
-    },
-    "btn1": {
-      "type": "Button",
-      "props": { "label": "Click me" },
-      "on": {
-        "press": { "action": "submit" }
-      }
-    }
-  }
-}
-```
-
-## Providers
-
-- `StateProvider`: state model read/write and controlled mode via `store`
-- `VisibilityProvider`: evaluates `visible` conditions
-- `ValidationProvider`: field validation + `validateForm` integration
-- `ActionProvider`: runs built-in and custom actions
-- `JSONUIProvider`: combined provider wrapper
-
-## Hooks
-
-- `useStateStore`, `useStateValue`, `useStateBinding`
-- `useVisibility`, `useIsVisible`
-- `useActions`, `useAction`
-- `useValidation`, `useOptionalValidation`, `useFieldValidation`
-- `useBoundProp`
-- `useUIStream`, `useChatUI`
-
-## Built-in Actions
-
-Handled automatically by `ActionProvider`:
-
-- `setState`
-- `pushState`
-- `removeState`
-- `validateForm`
-
-## Dynamic Props and Bindings
-
-Nested lists can set `repeat.statePath` to `{ "$item": "field" }` inside an enclosing repeat.
-
-Supported expression forms include:
-
-- `{"$state": "/path"}`
-- `{"$bindState": "/path"}`
-- `{"$bindItem": "field"}`
-- `{"$template": "Hi ${/user/name}"}`
-- `{"$computed": "fn", "args": {...}}`
-- `{"$cond": <condition>, "$then": <value>, "$else": <value>}`
-
-Use `useBoundProp` in components for writable bound values:
-
-```tsx
-import { useBoundProp } from "@json-render/solid";
-
-function Input(props: BaseComponentProps<{ value?: string }>) {
-  const [value, setValue] = useBoundProp(
-    props.props.value,
-    props.bindings?.value,
-  );
-  return (
-    <input
-      value={String(value() ?? "")}
-      onInput={(e) => setValue(e.currentTarget.value)}
-    />
-  );
-}
-```
-
-`useStateValue`, `useStateBinding`, and the `state` / `errors` / `isValid` fields from `useFieldValidation` are reactive accessors in Solid. Call them as functions inside JSX, `createMemo`, or `createEffect`.
-
-## Solid Reactivity Rules
-
-- Do not destructure component props in function signatures when values need to stay reactive.
-- Keep changing reads inside JSX expressions, `createMemo`, or `createEffect`.
-- Context values are exposed through getter-based objects so consumers always observe live signals.
-
-## Streaming UI
-
-```tsx
-import { useUIStream, Renderer } from "@json-render/solid";
-
-const stream = useUIStream({ api: "/api/generate-ui" });
-await stream.send("Create a support dashboard");
-
-<Renderer
-  spec={stream.spec}
-  registry={registry}
-  loading={stream.isStreaming}
-/>;
-```
-
-Use `useChatUI` for chat + UI generation flows.