@vellumai/assistant 0.6.2 → 0.6.4

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -8,6 +8,10 @@ metadata:
     display-name: "App Builder"
     includes:
       - "frontend-design"
+    activation-hints:
+      - "User asks to build an app, landing page, website, dashboard, tool, calculator, game, tracker, or interactive page"
+      - "User asks to visualize data or says 'let's visualize this' — use the app sandbox to build interactive visualizations"
+      - "ALWAYS prefer the app sandbox over building standalone web apps, local servers, or outputting raw HTML/CSS/JS in chat — even when the user says 'make this an app' or 'turn this into an app'"
 ---
 
 You are an expert app builder and visual designer. When the user asks you to create an app, tool, or utility, you immediately design a data schema, choose a stunning visual direction, build the interface, and open it - all in one step. You don't discuss or ask for permission to be creative. You ARE the designer: you pick the colors, the layout, the atmosphere, the micro-interactions. Your apps should make users stop and say "whoa" - they should feel designed, not generated.
@@ -173,13 +177,16 @@ export const Header: FunctionComponent<Props> = ({ title, count }) => {
 
 **CSS:** Import CSS files directly in TSX (`import './styles.css'`). You can also use inline styles via the `style` attribute on JSX elements.
 
-**Data bridge:** The same `window.vellum.data` API works in TSX components - call it from `useEffect` hooks or event handlers:
+**Custom routes in TSX:** Use `window.vellum.fetch()` to call custom route handlers from components — see the [Custom route handlers](#custom-route-handlers-user-defined-routes) section for full details:
 
 ```tsx
-const [records, setRecords] = useState<Record[]>([]);
+const [items, setItems] = useState<Item[]>([]);
 
 useEffect(() => {
-  window.vellum.data.query().then(setRecords).catch(console.error);
+  window.vellum.fetch("/v1/x/items")
+    .then((res) => (res.ok ? res.json() : Promise.reject(res.status)))
+    .then(setItems)
+    .catch(console.error);
 }, []);
 ```
 
@@ -211,7 +218,10 @@ export const App: FunctionComponent = () => {
   const [records, setRecords] = useState([]);
 
   useEffect(() => {
-    window.vellum.data.query().then(setRecords);
+    window.vellum.fetch("/v1/x/projects")
+      .then((res) => res.ok ? res.json() : Promise.reject(res.status))
+      .then(setRecords)
+      .catch(console.error);
   }, []);
 
   return (
@@ -309,131 +319,15 @@ window.addEventListener("vellum-theme-change", (e) => {
 
 #### Widget component library
 
-A CSS/JS widget library is auto-injected alongside the design system. Use these for standard UI patterns - skip them when custom HTML serves the user better.
-
-**Layout widgets** (class names, infer HTML structure):
-
-| Widget                                                       | Purpose                                                        |
-| ------------------------------------------------------------ | -------------------------------------------------------------- |
-| `.v-metric-card` (`.v-metric-grid`)                          | Big number with emoji icon, label, trend                       |
-| `.v-data-table`                                              | Sortable table with sticky header, `th[data-sortable]`         |
-| `.v-tabs` / `.v-tab-bar` / `.v-tab-panel`                    | Tab navigation with keyboard support                           |
-| `.v-accordion` / `.v-accordion-item`                         | Collapsible sections                                           |
-| `.v-search-bar`                                              | Search input with clear button                                 |
-| `.v-empty-state`                                             | No-data placeholder with CTA                                   |
-| `.v-timeline` / `.v-timeline-entry`                          | Vertical timeline (`.active`/`.success`/`.error`)              |
-| `.v-action-list` / `.v-action-list-item`                     | Rows with per-item actions                                     |
-| `.v-card-grid`                                               | Responsive card grid                                           |
-| `.v-progress-bar` / `.v-progress-track` / `.v-progress-fill` | Horizontal progress                                            |
-| `.v-status-badge`                                            | Colored pill with dot (`.success`/`.error`/`.warning`/`.info`) |
-| `.v-stat-row` / `.v-stat`                                    | Horizontal label-value pairs                                   |
-| `.v-toast`                                                   | Notification banner - prefer `vellum.widgets.toast()`          |
-| `.v-avatar-row`                                              | Contact/team display                                           |
-| `.v-tag-group`                                               | Wrapping tag row                                               |
-
-**Domain-specific widgets** (class names, infer HTML structure):
-
-| Widget             | Purpose                |
-| ------------------ | ---------------------- |
-| `.v-weather-card`  | Temperature + forecast |
-| `.v-stock-ticker`  | Price display + chart  |
-| `.v-flight-card`   | Flight info with route |
-| `.v-billing-chart` | Usage/billing display  |
-| `.v-boarding-pass` | Pass-styled layout     |
-| `.v-itinerary`     | Day-by-day travel plan |
-| `.v-receipt`       | Receipt layout         |
-| `.v-invoice`       | Formal invoice         |
-
-**Content & landing page components** (class names, infer HTML structure):
-
-| Widget                                           | Purpose                                             |
-| ------------------------------------------------ | --------------------------------------------------- |
-| `.v-hero` / `.v-hero-badge` / `.v-hero-subtitle` | Hero banner with gradient, trust badge, accent word |
-| `.v-section-header` / `.v-section-label`         | Section intro with label                            |
-| `.v-feature-grid` / `.v-feature-card`            | Feature showcase with hover lift                    |
-| `.v-pullquote`                                   | Blockquote with gradient accent border              |
-| `.v-comparison`                                  | Before/after cards (`.before`/`.after`)             |
-| `.v-page`                                        | Centered container (max-width 600px)                |
-| `.v-gradient-text`                               | Accent-colored gradient text                        |
-| `.v-animate-in`                                  | Staggered fade-in for children                      |
-
-#### Widget JavaScript utilities
-
-Interactive utilities at `window.vellum.widgets.*`:
-
-**Charts** (always use these instead of hand-coding SVG/CSS charts):
+A CSS/JS widget library is auto-injected alongside the design system. Use `.v-*` class names for standard UI patterns (tables, metrics, timelines, cards, etc.) and `window.vellum.widgets.*` JS utilities for charts, data formatting, and interactive behaviors. **ALWAYS use `vellum.widgets.*` chart functions** instead of hand-coding SVG/CSS charts.
 
-```javascript
-vellum.widgets.sparkline("container-id", [10, 25, 15, 30], {
-  width: 200,
-  height: 40,
-  color: "var(--v-success)",
-  strokeWidth: 2,
-  fill: true,
-});
-vellum.widgets.barChart(
-  "container-id",
-  [
-    { label: "Jan", value: 120 },
-    { label: "Feb", value: 180, color: "var(--v-success)" },
-  ],
-  {
-    width: 400,
-    height: 200,
-    showLabels: true,
-    showValues: true,
-    horizontal: false,
-  },
-);
-vellum.widgets.lineChart(
-  "container-id",
-  [
-    { label: "Mon", value: 42 },
-    { label: "Tue", value: 58 },
-  ],
-  { width: 400, height: 200, showDots: true, showGrid: true, gridLines: 4 },
-);
-vellum.widgets.progressRing("container-id", 75, {
-  size: 100,
-  strokeWidth: 8,
-  color: "var(--v-success)",
-  label: "75%",
-});
-```
-
-**Data Formatting:**
-
-```javascript
-vellum.widgets.formatCurrency(1234.56, "USD"); // "$1,234.56"
-vellum.widgets.formatDate("2025-01-15", "relative"); // "3d ago"
-vellum.widgets.formatDate("2025-01-15", "short"); // "1/15/25"
-vellum.widgets.formatNumber(1234567, { compact: true }); // "1.2M"
-```
-
-**Interactive Behaviors:**
-
-```javascript
-vellum.widgets.sortTable("table-id"); // Wire th[data-sortable] click-to-sort
-vellum.widgets.filterTable("table-id", "input-id"); // Live text search
-vellum.widgets.tabs("tabs-id"); // Tab switching + keyboard nav
-vellum.widgets.accordion("accordion-id", { allowMultiple: true });
-vellum.widgets.multiSelect("table-id"); // Checkboxes + select-all
-vellum.widgets.toast("Saved!", "success", 4000); // Auto-dismiss notification
-vellum.widgets.countdown("timer-el", "2025-12-31T00:00:00Z", {
-  onComplete: () => {},
-});
-```
-
-#### When to use widgets vs custom HTML
+For the full widget reference (class names, JS APIs, chart functions, formatting utilities), see **[Widget Component Library](references/WIDGETS.md)**.
 
-- **Use widgets** for standard patterns - tables, metrics, timelines, notifications
-- **Use custom HTML** for novel or creative UIs - games, art tools, unique dashboards
-- **Mix freely** - widgets compose well together and with custom elements
-- **ALWAYS use `vellum.widgets.*` chart functions** instead of hand-coding SVG/CSS charts. They handle overflow clipping, bounds, scaling, and dark mode. Hand-coded charts break layouts.
+#### Data bridge API (deprecated)
 
-#### Data bridge API
+> **Prefer custom route handlers** for new apps. The data bridge (`window.vellum.data`) only works for assistants that run on the same machine as the desktop app, which will also be deprecated soon.
 
-The HTML interface can read and write records via `window.vellum.data`. All methods return Promises.
+The native WebView can read and write app records via `window.vellum.data`. All methods return Promises.
 
 - `window.vellum.data.query()` - Returns all records: `{ id, appId, data, createdAt, updatedAt }[]`
 - `window.vellum.data.create(data)` - Creates a record. Returns the created record.
@@ -450,85 +344,9 @@ Important:
 
 #### Custom route handlers (user-defined routes)
 
-When the app needs server-side persistence, custom API logic, or workspace file access, use **user-defined routes**. Route handlers are TypeScript or JavaScript files that live in the workspace `routes/` directory and are served under the `/v1/x/` URL path.
-
-**Common use cases:** CRUD storage, file-based persistence, search/aggregation, external API proxying, webhook receivers.
-
-**Handler file convention:**
-
-Each handler file exports named functions for the HTTP methods it supports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Handlers use the standard Web API `Request`/`Response` signature.
-
-```
-{workspaceDir}/routes/
-  items.ts               # Handles /v1/x/items
-  items/
-    [id].ts              # Not supported — use query params instead
-    index.ts             # Also handles /v1/x/items (index convention)
-```
-
-**Example handler — JSON file persistence:**
-
-```typescript
-// routes/items.ts
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
-
-export const description = "Item CRUD — stores records as a JSON file";
-
-const DATA_DIR = join(process.env.VELLUM_WORKSPACE_DIR!, "data");
-const DATA_FILE = join(DATA_DIR, "items.json");
-
-function loadItems(): Array<Record<string, unknown>> {
-  mkdirSync(DATA_DIR, { recursive: true });
-  if (!existsSync(DATA_FILE)) return [];
-  return JSON.parse(readFileSync(DATA_FILE, "utf-8"));
-}
-
-function saveItems(items: Array<Record<string, unknown>>): void {
-  mkdirSync(DATA_DIR, { recursive: true });
-  writeFileSync(DATA_FILE, JSON.stringify(items, null, 2));
-}
-
-export function GET(): Response {
-  return Response.json(loadItems());
-}
-
-export async function POST(request: Request): Promise<Response> {
-  const body = await request.json();
-  const items = loadItems();
-  const item = { id: crypto.randomUUID(), ...body, createdAt: new Date().toISOString() };
-  items.push(item);
-  saveItems(items);
-  return Response.json(item, { status: 201 });
-}
-```
-
-**Calling routes from the app frontend:**
+When the app needs server-side persistence, custom API logic, or workspace file access, use **user-defined routes**. Route handlers are TypeScript/JavaScript files in the workspace `routes/` directory, served under `/v1/x/`. Call them from the frontend via `window.vellum.fetch("/v1/x/...")`. **Never use raw `fetch()` for `/v1/x/` routes** — it will fail in the sandboxed origin.
 
-Apps call custom routes via `fetch()` using the `/v1/x/` prefix. The assistant's runtime HTTP server requires the `/v1/` namespace for all API requests.
-
-```typescript
-// In a TSX component or HTML script
-const res = await fetch("/v1/x/items");
-const items = await res.json();
-
-// Create a new item
-await fetch("/v1/x/items", {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ name: "New item", status: "active" }),
-});
-```
-
-**Key rules:**
-
-- Always create the route handler files via `file_write` before calling `app_refresh`
-- Export an optional `description` string for CLI discoverability (`assistant routes list`)
-- Handlers have full Node.js API access — `fs`, `path`, `crypto`, etc.
-- Handlers get a 30-second timeout per request
-- Files are hot-reloaded on change (mtime-based cache)
-- Use `.ts` (preferred) or `.js` extensions
-- Route resolution: `routes/foo.ts` → `/v1/x/foo`, `routes/bar/index.ts` → `/v1/x/bar`
+For handler conventions, examples, key rules, and frontend usage patterns, see **[Custom Route Handlers](references/CUSTOM_ROUTES.md)**.
 
 #### Client-side state management
 
@@ -549,7 +367,8 @@ let allRecords = [];
 
 async function loadRecords() {
   try {
-    const res = await fetch("/v1/x/records");
+    const res = await window.vellum.fetch("/v1/x/records");
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
     allRecords = await res.json();
     render();
   } catch (err) {
@@ -652,58 +471,16 @@ Slides are a different domain from apps. Skip app-specific patterns (contextual
 
 ## Error Handling
 
-- All `fetch()` calls to custom routes must be wrapped in `try/catch` with user-friendly feedback.
+- All `window.vellum.fetch()` calls to custom routes must be wrapped in `try/catch` with user-friendly feedback. Always check `res.ok` before parsing the response body.
 - Never let a failed operation silently pass - always show a toast or inline error.
 - If the page loads with no data, show a designed empty state (`.v-empty-state`).
 - For forms, show validation errors inline next to the relevant field.
 
 ## App Interaction Hooks
 
-When building apps, proactively wire `sendAction` hooks so the assistant stays aware of meaningful user interactions. Two patterns are available:
-
-### Reactive hooks
-
-Reactive hooks trigger an assistant response. Use them for moments where the assistant's input adds value - selections that need explanation, completions worth celebrating, or submissions that benefit from feedback.
-
-```javascript
-// User selects a city on a map — assistant can provide insights
-window.vellum.sendAction('city_selected', { city: 'Tokyo' });
-
-// User submits a form — assistant can confirm and suggest next steps
-window.vellum.sendAction('form_submitted', { formId: 'signup', email: 'user@example.com' });
-
-// User completes a level — assistant can congratulate and hint at what's next
-window.vellum.sendAction('level_complete', { level: 5, score: 2400 });
-```
-
-### Silent hooks
-
-Silent hooks accumulate state without interrupting the user. The state is automatically included as context when the next reactive hook fires.
-
-```javascript
-// User navigates to a new tab — no response needed, but assistant should know
-window.vellum.sendAction('state_update', { currentView: 'forecast', city: 'Tokyo' });
-
-// Score changes during gameplay — track silently
-window.vellum.sendAction('state_update', { score: 1250, lives: 2 });
-
-// User applies a filter — context for future questions
-window.vellum.sendAction('state_update', { filter: 'last-30-days', sortBy: 'revenue' });
-```
-
-### When to use reactive vs silent
-
-Choose based on whether the assistant's response would genuinely help the user at that moment:
-
-| App type | Silent (state accumulation) | Reactive (triggers response) |
-|---|---|---|
-| **Dashboards** | Tab navigation, filter changes, date range selection | Anomaly detected, threshold breached, data export complete |
-| **Games** | Score updates, move tracking, timer ticks | Level complete, achievement unlocked, game over |
-| **Forms & wizards** | Field focus, partial input, step navigation | Form submitted, validation failed on submit |
-| **Trackers** | Incremental progress, status toggles, reordering | Milestone reached, streak achieved, all items complete |
-| **Data explorers** | Sorting, paging, column toggling | Row selected for detail, comparison initiated |
+Proactively wire `window.vellum.sendAction()` hooks so the assistant stays aware of meaningful user interactions. Two patterns: **reactive** hooks (trigger assistant response) and **silent** hooks (`state_update` — accumulate context without interrupting). Wire hooks during the initial build, don't wait for the user to ask.
 
-Wire hooks during the initial build - don't wait for the user to ask. Apps that communicate state back to the assistant feel alive; apps that don't feel like static pages.
+For examples, reactive vs silent guidance, and per-app-type recommendations, see **[App Interaction Hooks](references/INTERACTION_HOOKS.md)**.
 
 ## Actionable UI
 

package/src/config/bundled-skills/app-builder/references/CUSTOM_ROUTES.md

@@ -0,0 +1,141 @@
+# Custom Route Handlers (User-Defined Routes)
+
+When the app needs server-side persistence, custom API logic, or workspace file access, use **user-defined routes**. Route handlers are TypeScript or JavaScript files that live in the workspace `routes/` directory and are served under the `/v1/x/` URL path.
+
+**Common use cases:** CRUD storage, file-based persistence, search/aggregation, external API proxying, webhook receivers.
+
+## Handler file convention
+
+Each handler file exports named functions for the HTTP methods it supports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Handlers receive two arguments: the standard Web API `Request` and an optional `context` object with runtime singletons.
+
+```
+{workspaceDir}/routes/
+  items.ts               # Handles /v1/x/items
+  items/
+    [id].ts              # Not supported — use query params instead
+    index.ts             # Also handles /v1/x/items (index convention)
+```
+
+## Example handler — JSON file persistence
+
+```typescript
+// routes/items.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const description = "Item CRUD — stores records as a JSON file";
+
+const DATA_DIR = join(process.env.VELLUM_WORKSPACE_DIR!, "data");
+const DATA_FILE = join(DATA_DIR, "items.json");
+
+function loadItems(): Array<Record<string, unknown>> {
+  mkdirSync(DATA_DIR, { recursive: true });
+  if (!existsSync(DATA_FILE)) return [];
+  return JSON.parse(readFileSync(DATA_FILE, "utf-8"));
+}
+
+function saveItems(items: Array<Record<string, unknown>>): void {
+  mkdirSync(DATA_DIR, { recursive: true });
+  writeFileSync(DATA_FILE, JSON.stringify(items, null, 2));
+}
+
+export function GET(): Response {
+  return Response.json(loadItems());
+}
+
+export async function POST(request: Request): Promise<Response> {
+  const body = await request.json();
+  const items = loadItems();
+  const item = {
+    id: crypto.randomUUID(),
+    ...body,
+    createdAt: new Date().toISOString(),
+  };
+  items.push(item);
+  saveItems(items);
+  return Response.json(item, { status: 201 });
+}
+```
+
+## Calling routes from the app frontend
+
+Apps call custom routes via `window.vellum.fetch()` using the `/v1/x/` prefix. This authenticated wrapper automatically injects the gateway URL and auth headers so requests reach the assistant runtime. **Never use raw `fetch()` for `/v1/x/` routes** — it will fail because the app runs in a sandboxed origin.
+
+```typescript
+// In a TSX component or HTML script
+const res = await window.vellum.fetch("/v1/x/items");
+if (!res.ok) throw new Error(`HTTP ${res.status}`);
+const items = await res.json();
+
+// Create a new item
+const createRes = await window.vellum.fetch("/v1/x/items", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "New item", status: "active" }),
+});
+if (!createRes.ok) throw new Error(`HTTP ${createRes.status}`);
+```
+
+## Runtime context
+
+Every handler receives a frozen `context` object as its second argument. This provides access to daemon singletons that are otherwise unreachable from dynamically imported route modules.
+
+```typescript
+export async function POST(request: Request, context): Promise<Response> {
+  // context.assistantEventHub — publish events to connected SSE clients
+  // context.assistantId       — the daemon's logical assistant ID ("self")
+}
+```
+
+### Publishing events to the client
+
+Use `context.assistantEventHub` to push real-time events to connected desktop/mobile clients. This is how route handlers can trigger client-side navigation, update UI, or deliver notifications.
+
+```typescript
+// routes/open-conversation.ts
+export async function POST(request: Request, context): Promise<Response> {
+  const { conversationId } = await request.json();
+
+  await context.assistantEventHub.publish({
+    id: crypto.randomUUID(),
+    assistantId: context.assistantId,
+    conversationId,
+    emittedAt: new Date().toISOString(),
+    message: { type: "open_conversation", conversationId },
+  });
+
+  return Response.json({ ok: true });
+}
+```
+
+The context object is **immutable** — attempting to reassign its properties will throw in strict mode (ESM). This prevents user route handlers from accidentally corrupting shared state.
+
+Legacy handlers that only accept `(request)` continue to work — the context is passed positionally but ignored if the handler doesn't declare the parameter.
+
+## Key rules
+
+- Always create the route handler files via `file_write` before calling `app_refresh`
+- Export an optional `description` string for CLI discoverability (`assistant routes list`)
+- Handlers have full Node.js API access — `fs`, `path`, `crypto`, etc.
+- Handlers get a 30-second timeout per request
+- Files are hot-reloaded on change (mtime-based cache)
+- Use `.ts` (preferred) or `.js` extensions
+- Route resolution: `routes/foo.ts` → `/v1/x/foo`, `routes/bar/index.ts` → `/v1/x/bar`
+
+## Using custom routes in TSX components
+
+```tsx
+const [items, setItems] = useState<Item[]>([]);
+
+useEffect(() => {
+  window.vellum
+    .fetch("/v1/x/items")
+    .then((res) => (res.ok ? res.json() : Promise.reject(res.status)))
+    .then(setItems)
+    .catch(console.error);
+}, []);
+```
+
+## Error handling
+
+All `window.vellum.fetch()` calls to custom routes must be wrapped in `try/catch` with user-friendly feedback. Always check `res.ok` before parsing the response body. Never let a failed operation silently pass — always show a toast or inline error.

package/src/config/bundled-skills/app-builder/references/INTERACTION_HOOKS.md

@@ -0,0 +1,56 @@
+# App Interaction Hooks
+
+When building apps, proactively wire `sendAction` hooks so the assistant stays aware of meaningful user interactions. Two patterns are available:
+
+## Reactive hooks
+
+Reactive hooks trigger an assistant response. Use them for moments where the assistant's input adds value - selections that need explanation, completions worth celebrating, or submissions that benefit from feedback.
+
+```javascript
+// User selects a city on a map — assistant can provide insights
+window.vellum.sendAction("city_selected", { city: "Tokyo" });
+
+// User submits a form — assistant can confirm and suggest next steps
+window.vellum.sendAction("form_submitted", {
+  formId: "signup",
+  email: "user@example.com",
+});
+
+// User completes a level — assistant can congratulate and hint at what's next
+window.vellum.sendAction("level_complete", { level: 5, score: 2400 });
+```
+
+## Silent hooks
+
+Silent hooks accumulate state without interrupting the user. The state is automatically included as context when the next reactive hook fires.
+
+```javascript
+// User navigates to a new tab — no response needed, but assistant should know
+window.vellum.sendAction("state_update", {
+  currentView: "forecast",
+  city: "Tokyo",
+});
+
+// Score changes during gameplay — track silently
+window.vellum.sendAction("state_update", { score: 1250, lives: 2 });
+
+// User applies a filter — context for future questions
+window.vellum.sendAction("state_update", {
+  filter: "last-30-days",
+  sortBy: "revenue",
+});
+```
+
+## When to use reactive vs silent
+
+Choose based on whether the assistant's response would genuinely help the user at that moment:
+
+| App type            | Silent (state accumulation)                          | Reactive (triggers response)                               |
+| ------------------- | ---------------------------------------------------- | ---------------------------------------------------------- |
+| **Dashboards**      | Tab navigation, filter changes, date range selection | Anomaly detected, threshold breached, data export complete |
+| **Games**           | Score updates, move tracking, timer ticks            | Level complete, achievement unlocked, game over            |
+| **Forms & wizards** | Field focus, partial input, step navigation          | Form submitted, validation failed on submit                |
+| **Trackers**        | Incremental progress, status toggles, reordering     | Milestone reached, streak achieved, all items complete     |
+| **Data explorers**  | Sorting, paging, column toggling                     | Row selected for detail, comparison initiated              |
+
+Wire hooks during the initial build - don't wait for the user to ask. Apps that communicate state back to the assistant feel alive; apps that don't feel like static pages.

package/src/config/bundled-skills/app-builder/references/WIDGETS.md

@@ -0,0 +1,125 @@
+# Widget Component Library
+
+A CSS/JS widget library is auto-injected alongside the design system. Use these for standard UI patterns - skip them when custom HTML serves the user better.
+
+## Layout widgets
+
+| Widget                                                       | Purpose                                                        |
+| ------------------------------------------------------------ | -------------------------------------------------------------- |
+| `.v-metric-card` (`.v-metric-grid`)                          | Big number with emoji icon, label, trend                       |
+| `.v-data-table`                                              | Sortable table with sticky header, `th[data-sortable]`         |
+| `.v-tabs` / `.v-tab-bar` / `.v-tab-panel`                    | Tab navigation with keyboard support                           |
+| `.v-accordion` / `.v-accordion-item`                         | Collapsible sections                                           |
+| `.v-search-bar`                                              | Search input with clear button                                 |
+| `.v-empty-state`                                             | No-data placeholder with CTA                                   |
+| `.v-timeline` / `.v-timeline-entry`                          | Vertical timeline (`.active`/`.success`/`.error`)              |
+| `.v-action-list` / `.v-action-list-item`                     | Rows with per-item actions                                     |
+| `.v-card-grid`                                               | Responsive card grid                                           |
+| `.v-progress-bar` / `.v-progress-track` / `.v-progress-fill` | Horizontal progress                                            |
+| `.v-status-badge`                                            | Colored pill with dot (`.success`/`.error`/`.warning`/`.info`) |
+| `.v-stat-row` / `.v-stat`                                    | Horizontal label-value pairs                                   |
+| `.v-toast`                                                   | Notification banner - prefer `vellum.widgets.toast()`          |
+| `.v-avatar-row`                                              | Contact/team display                                           |
+| `.v-tag-group`                                               | Wrapping tag row                                               |
+
+## Domain-specific widgets
+
+| Widget             | Purpose                |
+| ------------------ | ---------------------- |
+| `.v-weather-card`  | Temperature + forecast |
+| `.v-stock-ticker`  | Price display + chart  |
+| `.v-flight-card`   | Flight info with route |
+| `.v-billing-chart` | Usage/billing display  |
+| `.v-boarding-pass` | Pass-styled layout     |
+| `.v-itinerary`     | Day-by-day travel plan |
+| `.v-receipt`       | Receipt layout         |
+| `.v-invoice`       | Formal invoice         |
+
+## Content & landing page components
+
+| Widget                                           | Purpose                                             |
+| ------------------------------------------------ | --------------------------------------------------- |
+| `.v-hero` / `.v-hero-badge` / `.v-hero-subtitle` | Hero banner with gradient, trust badge, accent word |
+| `.v-section-header` / `.v-section-label`         | Section intro with label                            |
+| `.v-feature-grid` / `.v-feature-card`            | Feature showcase with hover lift                    |
+| `.v-pullquote`                                   | Blockquote with gradient accent border              |
+| `.v-comparison`                                  | Before/after cards (`.before`/`.after`)             |
+| `.v-page`                                        | Centered container (max-width 600px)                |
+| `.v-gradient-text`                               | Accent-colored gradient text                        |
+| `.v-animate-in`                                  | Staggered fade-in for children                      |
+
+## Widget JavaScript utilities
+
+Interactive utilities at `window.vellum.widgets.*`:
+
+### Charts
+
+Always use these instead of hand-coding SVG/CSS charts:
+
+```javascript
+vellum.widgets.sparkline("container-id", [10, 25, 15, 30], {
+  width: 200,
+  height: 40,
+  color: "var(--v-success)",
+  strokeWidth: 2,
+  fill: true,
+});
+vellum.widgets.barChart(
+  "container-id",
+  [
+    { label: "Jan", value: 120 },
+    { label: "Feb", value: 180, color: "var(--v-success)" },
+  ],
+  {
+    width: 400,
+    height: 200,
+    showLabels: true,
+    showValues: true,
+    horizontal: false,
+  },
+);
+vellum.widgets.lineChart(
+  "container-id",
+  [
+    { label: "Mon", value: 42 },
+    { label: "Tue", value: 58 },
+  ],
+  { width: 400, height: 200, showDots: true, showGrid: true, gridLines: 4 },
+);
+vellum.widgets.progressRing("container-id", 75, {
+  size: 100,
+  strokeWidth: 8,
+  color: "var(--v-success)",
+  label: "75%",
+});
+```
+
+### Data Formatting
+
+```javascript
+vellum.widgets.formatCurrency(1234.56, "USD"); // "$1,234.56"
+vellum.widgets.formatDate("2025-01-15", "relative"); // "3d ago"
+vellum.widgets.formatDate("2025-01-15", "short"); // "1/15/25"
+vellum.widgets.formatNumber(1234567, { compact: true }); // "1.2M"
+```
+
+### Interactive Behaviors
+
+```javascript
+vellum.widgets.sortTable("table-id"); // Wire th[data-sortable] click-to-sort
+vellum.widgets.filterTable("table-id", "input-id"); // Live text search
+vellum.widgets.tabs("tabs-id"); // Tab switching + keyboard nav
+vellum.widgets.accordion("accordion-id", { allowMultiple: true });
+vellum.widgets.multiSelect("table-id"); // Checkboxes + select-all
+vellum.widgets.toast("Saved!", "success", 4000); // Auto-dismiss notification
+vellum.widgets.countdown("timer-el", "2025-12-31T00:00:00Z", {
+  onComplete: () => {},
+});
+```
+
+## When to use widgets vs custom HTML
+
+- **Use widgets** for standard patterns - tables, metrics, timelines, notifications
+- **Use custom HTML** for novel or creative UIs - games, art tools, unique dashboards
+- **Mix freely** - widgets compose well together and with custom elements
+- **ALWAYS use `vellum.widgets.*` chart functions** instead of hand-coding SVG/CSS charts. They handle overflow clipping, bounds, scaling, and dark mode. Hand-coded charts break layouts.