@jay-framework/jay-stack-cli 0.15.5 → 0.16.0

package/agent-kit-template/developer/dev-server-service.md

@@ -0,0 +1,126 @@
+# Dev Server Service API
+
+The dev server exposes a `DevServerService` for design board applications, CLI tools, and plugins. It provides route listing, param discovery, and freeze management.
+
+## Service Marker
+
+Registered as `DEV_SERVER_SERVICE` — injectable in actions and components:
+
+```typescript
+import { DEV_SERVER_SERVICE } from '@jay-framework/dev-server';
+
+export const listAllRoutes = makeJayAction('admin.listRoutes')
+  .withServices(DEV_SERVER_SERVICE)
+  .withHandler(async (_input, devServer) => {
+    return devServer.listRoutes();
+  });
+```
+
+## Direct Access
+
+Also returned from `mkDevServer()` for CLI usage:
+
+```typescript
+const { service } = await mkDevServer(options);
+```
+
+## Routes
+
+### listRoutes()
+
+Returns all page routes in the project:
+
+```typescript
+const routes = service.listRoutes();
+// [{ path: '/products/kitan/[[category]]', jayHtmlPath: '...', compPath: '...' }]
+```
+
+### loadRouteParams(route, onBatch)
+
+Async generator that yields param batches from the route's `loadParams`:
+
+```typescript
+for await (const batch of service.loadRouteParams('/products/kitan/[[category]]')) {
+  console.log(batch); // [{ category: 'shirts' }, { category: 'pants' }]
+}
+```
+
+Returns empty if the route has no `page.ts` or no `loadParams`. Throws if the route doesn't exist.
+
+## Freeze Management
+
+### FreezeStore
+
+Accessible via `service.freezeStore`:
+
+```typescript
+const store = service.freezeStore;
+
+// Save a ViewState snapshot
+const entry = await store.save('/products/kitan', viewState);
+
+// List freezes for a route
+const freezes = await store.list('/products/kitan');
+
+// Get a specific freeze
+const freeze = await store.get('abc123');
+
+// Rename
+await store.rename('abc123', 'in-stock state');
+
+// Delete
+await store.delete('abc123');
+```
+
+## Editor Protocol
+
+These APIs are also exposed via the editor protocol (Socket.IO) for design board applications:
+
+| Protocol Message  | Service Method                            |
+| ----------------- | ----------------------------------------- |
+| `listRoutes`      | `service.listRoutes()`                    |
+| `listFreezes`     | `service.freezeStore.list(route)`         |
+| `renameFreeze`    | `service.freezeStore.rename(id, name)`    |
+| `deleteFreeze`    | `service.freezeStore.delete(id)`          |
+| `loadRouteParams` | `service.loadRouteParams(route, onBatch)` |
+
+### Streaming Events
+
+`loadRouteParams` streams batches via `routeParamsBatch` socket events:
+
+```typescript
+// Client sends: { type: 'loadRouteParams', route: '/products/[slug]' }
+// Server responds: { type: 'loadRouteParams', success: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [...], hasMore: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [...], hasMore: true }
+// Server emits:   { type: 'routeParamsBatch', route: '...', params: [], hasMore: false }
+```
+
+### Freeze Changed Event
+
+The `freezeChanged` socket event is emitted when jay-html or CSS files change. Design board applications should listen for this to refresh their frozen views:
+
+```typescript
+socket.on('freezeChanged', () => {
+  // Re-fetch frozen page fragments
+});
+```
+
+## Iframe / Embed Mode
+
+When a page is loaded inside an iframe with `?_jay_embed=true` (e.g., by the AIditor), the Alt+S shortcut is disabled (parent owns it). Freeze is triggered via `postMessage`:
+
+```typescript
+// Parent → iframe: request freeze
+iframe.contentWindow.postMessage({ type: 'jay:requestFreeze' }, '*');
+
+// Iframe → parent: freeze done
+// { type: 'jay:freeze', id: string, route: string }
+```
+
+The parent constructs the frozen page URL:
+
+```
+route + '?_jay_freeze=' + id                        // full page
+route + '?_jay_freeze=' + id + '&format=fragment'   // shadow DOM fragment
+```

package/agent-kit-template/developer/page-components.md

@@ -0,0 +1,103 @@
+# Page Components
+
+A page component (`page.ts`) uses `makeJayStackComponent` to provide page-level data across rendering phases.
+
+## Basic Page Component
+
+```typescript
+import { makeJayStackComponent, phaseOutput } from '@jay-framework/fullstack-component';
+import type { HomePageContract } from './page.jay-contract.generated';
+
+export const page = makeJayStackComponent<HomePageContract>()
+  .withSlowlyRender(async () => {
+    return phaseOutput({ heroTitle: 'Welcome', heroSubtitle: 'Build something great' }, {});
+  })
+  .withFastRender(async () => {
+    return phaseOutput({ featuredCount: 12 }, {});
+  });
+```
+
+The export name must be `page` for page-level components.
+
+## Page Component with Params
+
+For dynamic routes, use `withLoadParams` and access params via props:
+
+```typescript
+export const page = makeJayStackComponent<ProductPageContract>()
+  .withServices(PRODUCTS_DB)
+  .withLoadParams(async function* (db) {
+    const products = await db.getAll();
+    yield products.map((p) => ({ slug: p.slug }));
+  })
+  .withSlowlyRender(async (props, db) => {
+    const product = await db.getBySlug(props.slug);
+    if (!product) return notFound('Product not found');
+    return phaseOutput(
+      { title: product.name, description: product.desc },
+      { productId: product.id },
+    );
+  })
+  .withFastRender(async (props, db) => {
+    const price = await db.getPrice(props.carryForward.productId);
+    return phaseOutput({ price, inStock: price > 0 }, {});
+  });
+```
+
+## Page Component with Interactive Phase
+
+Add client-side interactivity:
+
+```typescript
+export const page = makeJayStackComponent<ProductPageContract>()
+  .withServices(PRODUCTS_DB)
+  .withSlowlyRender(async (props, db) => {
+    // ... slow render
+  })
+  .withFastRender(async (props, db) => {
+    // ... fast render
+  })
+  .withInteractive(function ProductPage(props, refs) {
+    const [quantity, setQuantity] = createSignal(1);
+
+    refs.addToCart.onClick(async () => {
+      await addToCartAction({
+        productId: props.carryForward.productId,
+        quantity: quantity(),
+      });
+    });
+
+    refs.quantityInput.exec$((input) => {
+      input.addEventListener('change', (e) => {
+        setQuantity(parseInt((e.target as HTMLInputElement).value));
+      });
+    });
+
+    return {
+      render: () => ({
+        quantity: quantity(),
+      }),
+    };
+  });
+```
+
+## Combining with Headless Plugins
+
+A page component handles page-level data. Plugin headless components handle their own data independently. Both render into the same page:
+
+```
+src/pages/products/[slug]/
+├── page.jay-html          # Template: binds to both page + plugin data
+├── page.jay-contract      # Page-level contract (title, breadcrumbs, etc.)
+├── page.ts                # Page component
+```
+
+The jay-html template uses unprefixed bindings for page data and key-prefixed bindings for plugin data.
+
+## Builder API Reference
+
+See the plugin [component-structure.md](../plugin/component-structure.md) for the full builder API: `.withProps()`, `.withServices()`, `.withContexts()`, phase rendering, and render results.
+
+## State Hooks Reference
+
+See [component-state.md](component-state.md) for `createSignal`, `createMemo`, `createEffect`, and other hooks used in the interactive phase.

package/agent-kit-template/developer/page-contracts.md

@@ -0,0 +1,114 @@
+# Page Contracts
+
+A page can have its own contract (`page.jay-contract`) defining page-level data, alongside headless plugin contracts.
+
+## When to Use a Page Contract
+
+- The page has its own data that isn't provided by a plugin
+- The page component (`page.ts`) renders data into ViewState
+- You want type-safe bindings between the page component and its jay-html template
+
+If the page only uses plugin headless components and has no page-level data, a page contract is optional.
+
+## Basic Page Contract
+
+```yaml
+name: home-page
+tags:
+  - tag: heroTitle
+    type: data
+    dataType: string
+    phase: slow
+  - tag: heroSubtitle
+    type: data
+    dataType: string
+    phase: slow
+  - tag: featuredCount
+    type: data
+    dataType: number
+    phase: fast
+```
+
+Place as `page.jay-contract` next to `page.jay-html`:
+
+```
+src/pages/
+├── page.jay-html
+├── page.jay-contract
+└── page.ts
+```
+
+## Page Contract with Params
+
+If the page has a dynamic route, declare `params` in the contract:
+
+```yaml
+name: product-page
+description: Product detail page
+params:
+  slug: string
+tags:
+  - tag: title
+    type: data
+    dataType: string
+    phase: slow
+  - tag: price
+    type: data
+    dataType: number
+    phase: fast+interactive
+```
+
+The route must have matching dynamic segments:
+
+```
+src/pages/products/[slug]/
+├── page.jay-html
+├── page.jay-contract
+└── page.ts
+```
+
+## Page Contract with Props
+
+Pages rarely use props (they're top-level), but page contracts can declare them for reusable page patterns:
+
+```yaml
+name: category-page
+props:
+  - name: categoryId
+    type: string
+    required: true
+tags:
+  - tag: categoryName
+    type: data
+    dataType: string
+```
+
+## Combining with Plugin Contracts
+
+A page can have both a page contract and headless plugin contracts. The page contract covers page-owned data; plugins cover their own domains:
+
+```html
+<!-- page.jay-html -->
+<html>
+  <head>
+    <script
+      type="application/jay-headless"
+      plugin="wix-stores"
+      contract="product-page"
+      key="product"
+    ></script>
+  </head>
+  <body>
+    <!-- Page contract data -->
+    <h1>{heroTitle}</h1>
+
+    <!-- Plugin contract data (prefixed with key) -->
+    <div>{product.name}</div>
+    <div>{product.price}</div>
+  </body>
+</html>
+```
+
+## Contract Format Reference
+
+See the plugin [contracts-guide.md](../plugin/contracts-guide.md) for the full contract format: tag types, phases, sub-contracts, async data, and validation rules.

package/agent-kit-template/developer/project-structure.md

@@ -0,0 +1,242 @@
+# Project Structure
+
+## Directory Layout
+
+A jay-stack project follows this structure:
+
+```
+my-project/
+├── .jay                         # Dev server configuration (optional)
+├── package.json                 # Dependencies and scripts
+├── tsconfig.json                # TypeScript config
+├── public/                      # Static assets (images, fonts, etc.)
+├── config/                      # Plugin configuration (generated by jay-stack setup)
+│   ├── project.conf.yaml       # Project metadata (name, etc.)
+│   └── <plugin-name>.yaml      # Plugin-specific config files
+├── src/
+│   ├── pages/                   # Pages (directory-based routing)
+│   │   ├── page.jay-html        # Homepage → /
+│   │   ├── page.jay-contract    # Homepage contract (optional)
+│   │   ├── products/
+│   │   │   ├── page.jay-html    # Products list → /products
+│   │   │   └── [slug]/
+│   │   │       └── page.jay-html       # Product detail → /products/:slug
+│   │   └── cart/
+│   │       └── page.jay-html    # Cart → /cart
+│   └── styles/
+│       └── theme.css            # Global theme stylesheet
+└── agent-kit/                   # Generated by jay-stack agent-kit
+    ├── INSTRUCTIONS.md
+    ├── materialized-contracts/  # Contracts and indexes
+    └── references/              # Plugin reference data (product catalogs, schemas)
+        └── <plugin-name>/       # Per-plugin discovery data
+```
+
+## What You Create
+
+As an agent building pages, you typically create:
+
+1. **`src/pages/**/\*.jay-html`\*\* — Page templates (the main output)
+2. **`src/pages/**/\*.jay-contract`\*\* — Page-level contracts (when the page has its own data)
+3. **`src/styles/*.css`** — Theme stylesheet (one per project, reused across pages)
+
+You do **not** need to create: `package.json`, `tsconfig.json`, `.jay`, `page.conf.yaml`, `src/init.ts`, server actions, or services — these are set up by the project scaffolding, the Figma plugin, or provided by plugins.
+
+## Styling
+
+### Global Theme (src/styles/)
+
+Each project has a theme CSS file in `src/styles/` with CSS custom properties (design tokens):
+
+```css
+:root {
+  /* Colors */
+  --bg-primary: #faf8f5;
+  --bg-card: #ffffff;
+  --text-primary: #2d2a26;
+  --text-secondary: #6b665e;
+  --accent: #c45c3e;
+  --accent-hover: #d4704f;
+  --border: #e8e4dd;
+
+  /* Typography */
+  --font-serif: 'Cormorant Garamond', Georgia, serif;
+  --font-sans: 'DM Sans', -apple-system, sans-serif;
+
+  /* Spacing & Layout */
+  --radius-md: 10px;
+  --radius-lg: 14px;
+  --container-max: 1400px;
+  --page-padding: 48px;
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.04);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.06);
+}
+```
+
+The theme provides reusable CSS classes for common UI patterns:
+
+- **Layout**: `.container`, `.container-narrow`
+- **Cards**: `.card`, `.card-elevated`
+- **Buttons**: `.btn`, `.btn-primary`, `.btn-secondary`, `.btn-ghost`, `.btn-sm`, `.btn-lg`
+- **Forms**: `.input`, `.select`, `.checkbox`
+- **Badges**: `.badge`, `.badge-accent`, `.badge-success`, `.badge-error`
+- **Typography**: `.page-title`, `.section-title`, `.label`
+- **Product components**: `.product-card`, `.product-card-image`, `.product-card-content`, `.product-card-price`
+
+### Linking the Theme from Pages
+
+Use a relative path from the page to the theme file:
+
+```html
+<!-- From src/pages/page.jay-html (depth 1) -->
+<link rel="stylesheet" href="../styles/theme.css" />
+
+<!-- From src/pages/products/page.jay-html (depth 2) -->
+<link rel="stylesheet" href="../../styles/theme.css" />
+
+<!-- From src/pages/products/[slug]/page.jay-html (depth 3) -->
+<link rel="stylesheet" href="../../../styles/theme.css" />
+```
+
+### Page-Specific Styles
+
+Add page-specific styles in `<style>` tags within the jay-html `<head>`:
+
+```html
+<head>
+  <link rel="stylesheet" href="../../styles/theme.css" />
+  <style>
+    .hero {
+      padding: 80px 0;
+      text-align: center;
+    }
+    .featured-grid {
+      display: grid;
+      grid-template-columns: repeat(3, 1fr);
+      gap: 24px;
+    }
+  </style>
+</head>
+```
+
+### External Fonts
+
+Import fonts in the theme CSS or via `<link>` in jay-html:
+
+```css
+/* In theme.css */
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+```
+
+### Responsive Design
+
+Use media queries in the theme CSS or page-specific styles:
+
+```css
+@media (max-width: 1024px) {
+  .product-page-layout {
+    grid-template-columns: 1fr;
+  }
+}
+@media (max-width: 768px) {
+  .products-grid {
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+## Configuration Files
+
+### config/ (Plugin Configuration)
+
+The `config/` folder holds plugin configuration files, typically generated by `jay-stack setup`:
+
+```
+config/
+├── project.conf.yaml       # Project name and metadata
+└── wix-data.yaml           # Plugin-specific config (auto-generated by setup)
+```
+
+Plugins create their config files here during setup. The location is configured via `configBase` in the `.jay` file (defaults to `./config`).
+
+You generally don't need to create files here manually — plugins handle this via `jay-stack setup`. However, you may need to read these files to understand how a plugin is configured.
+
+### .jay (Dev Server Config)
+
+Optional YAML file at project root:
+
+```yaml
+devServer:
+  portRange:
+    - 3000
+    - 3100
+  pagesBase: ./src/pages
+  componentsBase: ./src/components
+  publicFolder: ./public
+editorServer:
+  portRange:
+    - 3101
+    - 3200
+```
+
+### package.json (Scripts)
+
+Standard scripts for jay-stack projects:
+
+```json
+{
+  "scripts": {
+    "dev": "jay-stack-cli dev",
+    "validate": "jay-stack-cli validate",
+    "definitions": "jay-cli definitions src",
+    "build": "npm run definitions"
+  }
+}
+```
+
+## Common Page Patterns
+
+### Product List / Search Page
+
+Uses a product search contract with filters, sorting, and pagination:
+
+```
+src/pages/products/
+└── page.jay-html     # Search input, filters sidebar, product grid, load more
+```
+
+### Product Detail Page (Dynamic Route)
+
+Uses a product page contract with media gallery, options, and add-to-cart:
+
+```
+src/pages/products/[slug]/
+└── page.jay-html      # Gallery, options, quantity, actions
+```
+
+### Category Page
+
+Uses a category contract with product grid:
+
+```
+src/pages/categories/[slug]/
+└── page.jay-html      # Category hero, product grid, load more
+```
+
+### Cart Page
+
+Uses a cart contract with line items and checkout:
+
+```
+src/pages/cart/
+└── page.jay-html      # Line items, quantity controls, summary, coupon, checkout
+```
+
+### Homepage
+
+Combines multiple headless components:
+
+```
+src/pages/
+└── page.jay-html      # Hero, featured products, categories, etc.
+```

package/agent-kit-template/developer/render-results.md

@@ -0,0 +1,112 @@
+# Render Results
+
+Each rendering phase (slow, fast) returns a render result indicating success, error, or redirect.
+
+## phaseOutput — Success
+
+Returns ViewState data and optional carry-forward data for the next phase:
+
+```typescript
+import { phaseOutput } from '@jay-framework/fullstack-component';
+
+return phaseOutput(
+  { title: 'My Product', price: 29.99 }, // ViewState — sent to template
+  { productId: 'abc123' }, // CarryForward — passed to next phase only
+);
+```
+
+CarryForward is available in the next phase via `props.carryForward` but is not part of the ViewState.
+
+## Error Results
+
+Return errors to stop rendering and show an error page:
+
+```typescript
+import {
+  notFound,
+  badRequest,
+  unauthorized,
+  forbidden,
+  serverError5xx,
+  clientError4xx,
+} from '@jay-framework/fullstack-component';
+
+// 404
+if (!product) return notFound('Product not found');
+
+// 400
+if (!input.query) return badRequest('Query is required');
+
+// 401
+if (!session) return unauthorized('Please log in');
+
+// 403
+if (!canAccess) return forbidden('Access denied');
+
+// Custom 4xx
+return clientError4xx(429, 'Rate limit exceeded');
+
+// 5xx
+return serverError5xx(500, 'Database connection failed');
+```
+
+## Redirects
+
+```typescript
+import { redirect3xx } from '@jay-framework/fullstack-component';
+
+return redirect3xx(301, '/new-location');
+return redirect3xx(302, `/products/${product.slug}`);
+```
+
+## RenderPipeline — Composable Rendering
+
+For complex render logic, `RenderPipeline` chains operations with automatic error propagation:
+
+```typescript
+import { RenderPipeline } from '@jay-framework/fullstack-component';
+
+const Pipeline = RenderPipeline.for<SlowViewState, CarryForward>();
+
+return Pipeline.try(() => db.getProduct(props.slug))
+  .map((product) => product ?? Pipeline.notFound('Product not found'))
+  .map(async (product) => ({
+    ...product,
+    reviews: await db.getReviews(product.id),
+  }))
+  .toPhaseOutput((product) => ({
+    viewState: { title: product.name, price: product.price },
+    carryForward: { productId: product.id },
+  }));
+```
+
+### Pipeline Factory Methods
+
+```typescript
+const P = RenderPipeline.for<VS, CF>();
+
+P.ok(value); // Wrap a value
+P.try(() => fetchData()); // Wrap a function (catches errors)
+P.from(previousPhaseResult); // Continue from a prior phase result
+P.notFound('message'); // Error pipeline
+P.badRequest('message'); // Error pipeline
+P.unauthorized('message'); // Error pipeline
+P.forbidden('message'); // Error pipeline
+P.serverError(500, 'message'); // Error pipeline
+P.redirect(301, '/path'); // Redirect pipeline
+```
+
+### Pipeline Chain Methods
+
+```typescript
+pipeline
+    .map(value => transform(value))           // Transform the value
+    .map(async value => await asyncOp(value)) // Async transform
+    .recover(error => P.ok(fallbackValue))    // Recover from errors
+    .toPhaseOutput(value => ({                // Convert to PhaseOutput
+        viewState: { ... },
+        carryForward: { ... },
+    }));
+```
+
+Errors short-circuit — if any step returns an error pipeline, subsequent `.map()` calls are skipped.