@jay-framework/jay-stack-cli 0.15.4 → 0.15.6

package/agent-kit-template/developer/component-state.md

@@ -0,0 +1,140 @@
+# Component State Hooks
+
+All hooks are used inside the interactive phase (the `withInteractive` constructor function). They provide reactive state management for client-side behavior.
+
+## createSignal
+
+Creates a reactive getter/setter pair:
+
+```typescript
+import { createSignal } from '@jay-framework/component';
+
+const [count, setCount] = createSignal(0);
+
+// Read
+count(); // 0
+
+// Write
+setCount(5); // set to 5
+setCount((n) => n + 1); // increment
+```
+
+Can initialize from a getter (reactive dependency):
+
+```typescript
+const [label, setLabel] = createSignal(() => 'Hello ' + props.name());
+```
+
+## createPatchableSignal
+
+Creates a signal with JSON Patch support for fine-grained updates to complex objects:
+
+```typescript
+import { createPatchableSignal } from '@jay-framework/component';
+import { REPLACE } from '@jay-framework/json-patch';
+
+const [data, setData, patchData] = createPatchableSignal({
+  label: 'Hello',
+  count: 0,
+  nested: { value: 42 },
+});
+
+// Patch a specific field
+patchData({ op: REPLACE, path: ['label'], value: 'Updated' });
+
+// Patch nested field
+patchData({ op: REPLACE, path: ['nested', 'value'], value: 99 });
+```
+
+See [component-data.md](component-data.md) for more on immutable data and patching.
+
+## createMemo
+
+Creates a memoized computed value that recalculates only when dependencies change:
+
+```typescript
+import { createMemo } from '@jay-framework/component';
+
+const fullName = createMemo(() => `${firstName()} ${lastName()}`);
+
+// Read
+fullName(); // recomputes only when firstName() or lastName() change
+```
+
+With initial value:
+
+```typescript
+const total = createMemo((prev) => prev + latestValue(), 0);
+```
+
+## createEffect
+
+Registers a side effect that runs on mount and when dependencies change. Optional cleanup function:
+
+```typescript
+import { createEffect } from '@jay-framework/component';
+
+createEffect(() => {
+  const handler = () => setWindowWidth(window.innerWidth);
+  window.addEventListener('resize', handler);
+  return () => window.removeEventListener('resize', handler); // cleanup
+});
+```
+
+Effects track reactive dependencies automatically:
+
+```typescript
+createEffect(() => {
+  document.title = `${count()} items`; // reruns when count() changes
+});
+```
+
+## createDerivedArray
+
+Efficiently maps an array with smart caching. Only remaps items that actually changed:
+
+```typescript
+import { createDerivedArray } from '@jay-framework/component';
+
+const displayItems = createDerivedArray(
+  () => products(),
+  (item, index, length) => ({
+    name: item().name,
+    displayPrice: formatPrice(item().price),
+    isLast: index() === length() - 1,
+  }),
+);
+
+// Read the mapped array
+displayItems();
+```
+
+Key optimizations:
+
+- Reuses mapped items when the source item hasn't changed
+- Only tracks `index()` and `length()` if you actually call them
+- Uses object identity (not deep equality) for cache hits
+
+## createEvent
+
+Creates an event emitter for component-to-parent communication:
+
+```typescript
+import { createEvent } from '@jay-framework/component';
+
+const onChange = createEvent<{ value: number }>((emitter) => {
+  emitter.emit({ value: count() });
+});
+```
+
+## useReactive
+
+Gets the current reactive context for advanced use cases:
+
+```typescript
+import { useReactive } from '@jay-framework/component';
+
+const reactive = useReactive();
+```
+
+Most components won't need this — prefer the higher-level hooks above.

package/agent-kit-template/developer/configuration.md

@@ -0,0 +1,76 @@
+# Configuration
+
+## .jay File
+
+Optional YAML file at project root configuring the dev server:
+
+```yaml
+devServer:
+  portRange:
+    - 3000
+    - 3100
+  pagesBase: ./src/pages
+  componentsBase: ./src/components
+  publicFolder: ./public
+editorServer:
+  portRange:
+    - 3101
+    - 3200
+```
+
+### Key Fields
+
+- `devServer.pagesBase` — Root directory for pages (default: `./src/pages`)
+- `devServer.componentsBase` — Root directory for components
+- `devServer.publicFolder` — Static assets directory
+- `devServer.portRange` — Port range for the dev server
+
+## Plugin Configuration (config/)
+
+The `config/` folder holds plugin configuration files generated by `jay-stack setup`:
+
+```
+config/
+├── project.conf.yaml       # Project name and metadata
+└── wix-data.yaml           # Plugin-specific config (auto-generated)
+```
+
+Plugins create their config files here during setup. The location is configured via `configBase` in the `.jay` file (defaults to `./config`).
+
+## Project Init (src/init.ts)
+
+The project can have an `init.ts` for project-level initialization:
+
+```typescript
+import { makeJayInit, registerService } from '@jay-framework/fullstack-component';
+
+export const init = makeJayInit()
+  .withServer(async () => {
+    // Register project-level services
+    registerService(MY_SERVICE, createMyService());
+
+    // Return data for client
+    return { locale: 'en-US' };
+  })
+  .withClient((data) => {
+    // Client-side init
+    console.log('Locale:', data.locale);
+  });
+```
+
+Init runs after all plugin inits, in dependency order.
+
+## package.json Scripts
+
+```json
+{
+  "scripts": {
+    "dev": "jay-stack-cli dev",
+    "validate": "jay-stack-cli validate",
+    "definitions": "jay-cli definitions src",
+    "build": "npm run definitions",
+    "setup": "jay-stack-cli setup",
+    "agent-kit": "jay-stack-cli agent-kit"
+  }
+}
+```

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.
+```