@definite-app/data-apps 1.0.0

package/CLAUDE.md

@@ -0,0 +1,686 @@
+# Definite Data Apps
+
+Build source-authored React data apps that compile to a single HTML file and run through the Definite iframe bridge with DuckDB WASM and Perspective.js.
+
+## How data flows (read this first)
+
+Understanding this pipeline prevents the most common bugs:
+
+```
+app.json          Definite platform       Browser DuckDB WASM        App.tsx
+(manifest)   -->  (server-side fetch) --> (local tables)        -->  (client-side SQL)
+```
+
+1. **app.json** declares every data resource the app needs. Each resource has a key, a `kind`, and a `source` (SQL, Cube, or file).
+2. **The Definite platform** reads the manifest and fetches data server-side (from DuckLake, Cube, GCS, etc.). The app itself never talks to the warehouse directly.
+3. **The runtime** loads the fetched data into a **browser-side DuckDB WASM** instance as local tables. Each `kind: "dataset"` resource becomes a DuckDB table; `kind: "json"` resources are returned as plain arrays.
+4. **App.tsx** queries those local tables via `useSqlQuery(dataset, sql, deps)`. These SQL queries run in the browser against DuckDB WASM, not against the server.
+
+**Key implication:** The column names in your `useSqlQuery` SQL must match the column names in the local DuckDB table, which are determined by how the data was fetched:
+
+- **SQL resources (`type: "sql"`):** Column names are the aliases you define in the SQL. `SELECT foo AS myColumn` means the local table has a column called `myColumn`. **You control the names. Always use camelCase aliases.**
+- **Cube resources (`type: "cube"`):** Column names are the Cube member **titles** (e.g., `"Credit Projects FICO Band"`), NOT the member names (e.g., `projects.fico_band`). These are long, have spaces, and require double-quoting in SQL. **Prefer SQL resources over Cube resources for data apps** to avoid this complexity.
+
+### Manifest-backed access is enforced
+
+Apps can only access data declared in `app.json`. This is validated at two levels:
+
+- **Build time:** `build.mjs` scans App.tsx and checks that every `useDataset("key")` and `useJsonResource("key")` call uses a literal string key that exists in `app.json` with the correct `kind`. Build fails if not.
+- **Runtime:** The platform only sends data for resources listed in the manifest. There is no way to run arbitrary SQL against the warehouse from the app.
+
+The build **cannot** validate column names inside `useSqlQuery` strings. Column name mismatches are runtime errors that show as "Binder Error: Referenced column not found" in the app.
+
+## What you build
+
+Each app lives under `examples/{slug}/`:
+
+```
+examples/{slug}/
+  app.json                  <-- manifest: declares all data resources
+  src/main.tsx              <-- entry point (don't edit)
+  src/App.tsx               <-- your UI code (imports from "@definite/runtime")
+  preview-data.json         <-- optional: dummy data for local preview
+  dist/index.html           <-- built artifact (generated by build.mjs)
+```
+
+### Repo layout
+
+```
+definite-data-apps/
+  build.mjs                   <-- build script (compiles app to single HTML)
+  preview.mjs                 <-- preview script (builds with embedded dummy data)
+  Makefile                    <-- convenience commands
+  package.json
+  runtime/
+    definite-runtime.tsx      <-- canonical runtime source
+  templates/
+    blank/                    <-- starter template for new apps
+      app.json
+      src/main.tsx
+      src/App.tsx             <-- imports from "@definite/runtime"
+  examples/
+    revenue-explorer/         <-- example app
+  starter/                    <-- symlink to examples/revenue-explorer/
+```
+
+## Bootstrap flow
+
+### 1. Create a new app
+
+```bash
+make new-app NAME=my-app                     # blank template (default)
+make new-app NAME=my-app TEMPLATE=refined    # sidebar shell + drill drawer
+```
+
+This copies `templates/<template>/` to `examples/my-app/`. The runtime is resolved via the `@definite/runtime` import alias; no per-app runtime file is needed.
+
+**Pick the template by shape, not by app size:**
+
+| Template | When to use |
+|----------|-------------|
+| `blank` (default) | Single-view dashboards, embedded Doc tiles, anything that doesn't need a navigation rail. Built on `AppShell`. |
+| `refined` | Multi-view analytics apps with ≥ 2 views, a sidebar, or ≥ 5 filter dimensions. Built on `ShellLayout` + `Sidebar` + `DrillProvider`. |
+
+A `refined` app that turns out to only need one view is fine — strip the nav down to one item and keep the shell. But a `blank` app that grows to 6 views will end up reinventing the sidebar; switch templates early if you see that coming.
+
+### 2. Edit app.json and src/App.tsx
+
+- Update `app.json` with your data resources (SQL queries, column aliases).
+- Update `src/App.tsx` with your UI code and queries.
+- Do NOT edit `src/main.tsx`. The runtime comes from the `@definite/runtime` alias, resolved at build time.
+
+### 3. Build
+
+```bash
+make build NAME=my-app
+# or directly:
+node build.mjs examples/my-app
+```
+
+This produces `examples/my-app/dist/index.html`.
+
+### 4. Preview with dummy data (optional)
+
+Create a `preview-data.json` in your app directory, then:
+
+```bash
+make preview NAME=my-app
+# or directly:
+node preview.mjs my-app
+```
+
+This builds with embedded preview data so you can open the HTML directly in a browser without the Definite platform.
+
+### Build validation
+
+The build validates manifest-backed resource usage before emitting `dist/index.html`. It fails if:
+
+- `useDataset()` or `useJsonResource()` is called without a literal string key
+- A hook key is missing from `app.json`
+- A hook key exists in `app.json` but has the wrong `kind`
+
+## Critical constraints
+
+1. Keep DuckDB WASM at `1.29.0`, Apache Arrow at `17.0.0`, and Perspective at `4.3.0`. These are pinned because the current Arrow ingestion path is version-sensitive.
+2. **Resource access is manifest-backed.** Every dataset or JSON resource must be declared in `app.json` before App.tsx can use it. Do not hardcode arbitrary bridge SQL in the component tree.
+3. **Always use SQL resources (`type: "sql"`) instead of Cube resources (`type: "cube"`) for data apps.** SQL resources give you full control over column names via aliases. Cube resources return columns named by their Cube *titles* (e.g., `"Credit Projects FICO Band"`) which are long, have spaces, and require double-quoting everywhere. This is the #1 source of bugs.
+4. **Column names in `useSqlQuery` must exactly match the aliases in your app.json SQL.** If app.json has `SELECT fico::INTEGER AS fico`, the local table column is `fico`. If you write `useSqlQuery(data, "SELECT ficoBand FROM ...")` but `ficoBand` isn't an alias in app.json, you get a runtime Binder Error.
+5. Keep Perspective table columns camelCase and convert DuckDB dates/timestamps to `VARCHAR` via `STRFTIME(col, '%Y-%m-%d')` in the app.json SQL. Do not pass raw underscored warehouse column names through.
+6. If a resource is a `.duckdb` file, prefer manifest fields like `alias` and `table` so the app can address it cleanly after attach.
+7. Public embeds are snapshot-only. If a resource needs to work publicly, give it a `snapshot` block in `app.json` or use a downloadable `duckdbFile` / Arrow / Parquet source.
+8. The runtime uses IndexedDB with a 24-hour TTL for datasets and JSON resources. Cache keys include the resource key, mode, and the embedded manifest resource definition so rebuilt apps invalidate naturally.
+9. `refresh()` on `useDataset()` and `useJsonResource()` is a hard refresh. It bypasses IndexedDB and repopulates the cache.
+10. **Never use complex CASE WHEN expressions in client-side `useSqlQuery`.** DuckDB WASM silently returns 0 for compound boolean conditions (especially `NOT IN` with many values, chained `AND`/`LIKE` conditions). Pre-compute all flags as 0/1 integer columns in the app.json SQL (server-side), then use `SUM(flag)::INTEGER` in client-side queries. See "DuckDB WASM limitations" below.
+11. **Always cast `SUM` results to `::INTEGER`** in client-side SQL. DuckDB WASM may return HUGEINT from SUM which JavaScript cannot handle cleanly. Write `SUM(col)::INTEGER AS myCount`, not `SUM(col) AS myCount`.
+
+## Manifest shape
+
+```json
+{
+  "version": 2,
+  "name": "Revenue Explorer",
+  "entry": "src/main.tsx",
+  "resources": {
+    "transactions": {
+      "kind": "dataset",
+      "source": {
+        "type": "sql",
+        "sql": "SELECT id AS transactionId, STRFTIME(created_at, '%Y-%m-%d') AS transactionDate, amount::DOUBLE AS amount FROM LAKE.SCHEMA.transactions LIMIT 200000"
+      },
+      "public": false
+    },
+    "semanticModel": {
+      "kind": "dataset",
+      "source": {
+        "type": "duckdbFile",
+        "drivePath": "apps-v2/revenue-explorer/snapshots/model.duckdb",
+        "alias": "model",
+        "table": "transactions"
+      },
+      "public": true
+    },
+    "branches": {
+      "kind": "json",
+      "source": {
+        "type": "sql",
+        "sql": "SELECT branch_id AS branchId, branch_name AS branchName FROM LAKE.SCHEMA.branches ORDER BY 2 LIMIT 3000"
+      },
+      "snapshot": {
+        "format": "json",
+        "drivePath": "apps-v2/revenue-explorer/snapshots/branches.json"
+      },
+      "public": true
+    }
+  }
+}
+```
+
+### Resource kinds
+
+- **`kind: "dataset"`**: Loaded into browser-side DuckDB WASM as a table. Queried via `useSqlQuery()`.
+- **`kind: "json"`**: Returned as a plain JavaScript array. Accessed via `useJsonResource()`.
+
+### Source types
+
+- **`type: "sql"`**: SQL query run server-side against DuckLake. Column names are your `AS` aliases.
+- **`type: "duckdbFile"`**: A `.duckdb` file downloaded and attached locally. Use `alias` and `table` fields.
+- **`type: "cube"`**: Cube semantic layer query. **Avoid for data apps** (see constraint #3).
+
+## Runtime helpers
+
+Exported from `@definite/runtime`:
+
+### Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useDataset(key, opts?)` | Load a `kind: "dataset"` resource into DuckDB WASM. Returns `{ loading, error, tableRef, perspectiveTable, refresh }`. |
+| `useJsonResource(key, opts?)` | Load a `kind: "json"` resource. Returns `{ loading, error, data, refresh }`. |
+| `useSqlQuery(dataset, sql, deps?)` | Run SQL against a loaded dataset's DuckDB table. Returns `{ loading, error, data }`. `sql` must reference columns by their app.json aliases. |
+| `useTheme()` | Returns current theme (`"dark"` or `"light"`). |
+| `usePerspective(dataset)` | Get Perspective client and table for a dataset. Returns `{ client, table }`. |
+
+### Components
+
+See the "UI components" section below for full details on each.
+
+**Layout:** `AppShell`, `Card`, `TabGroup`
+
+**Data display:** `KpiCard`, `DataTable`, `ReportTable`, `Badge`, `EChart`, `PerspectivePanel`
+
+**Inputs:** `MultiSelect`, `Select`, `FilterPills`, `TextInput`, `DateInput`
+
+**Overlay:** `Tooltip`
+
+**Feedback:** `LoadingState`, `ErrorState`, `ResourceCacheBadge`
+
+## UI components
+
+### Layout
+
+- **`AppShell`**: Page wrapper with title, subtitle, theme toggle, meta slot.
+- **`Card`**: Container with optional `title`, `headerRight`, `noPadding`. Use for all content sections.
+- **`TabGroup`**: Tab bar with accent underline. Props: `tabs` (Array\<string\>, NOT objects), `activeTab` (string), `onTabChange` (string => void), `children`. Example: `<TabGroup tabs={["Approved", "Funded"]} activeTab={tab} onTabChange={setTab}>`. Do NOT pass `{key, label}` objects; `tabs` must be a plain string array.
+
+### Data display
+
+- **`KpiCard`**: Metric card with hover lift, accent top-line, shimmer loading. Props: `title`, `value`, `format` ("number" | "currency" | "percent"), `loading`, `detail` (ReactNode for comparison deltas, badges, etc. below the value). The `format` prop is **required**. Behavior:
+  - `format="number"`: formats with commas, no decimals (e.g., `15,212`)
+  - `format="currency"`: formats as USD (e.g., `$1,234`)
+  - `format="percent"`: appends "%" with 1 decimal (e.g., `value={82.2} format="percent"` renders `82.2%`)
+  - **Pre-formatted strings** (e.g., `"53.6s"`, `"82.2%"`) are passed through as-is when they can't be parsed as a number
+  - NaN/Infinity values display as a dash
+- **`DataTable`**: Simple table with row hover. Props: `columns` (key/label), `rows`, `emptyState`.
+- **`ReportTable`**: Rich management report table. Supports grouped column headers with colored bands, section dividers, subtotal/total rows, and per-cell conditional styling. Props: `headerGroups` (label, colSpan, color, subHeaders[]), `rows` (type: data/section/subtotal/total, indent, cells), `emptyState`.
+- **`Badge`**: Status indicator with colored dot. Props: `variant` ("default" | "success" | "warning" | "error" | "info"), `dot`, `children`.
+- **`EChart`**: Apache ECharts wrapper. Handles init/dispose lifecycle, theme switching, resize, and click events. Pass the full ECharts option spec. Props: `option`, `height`, `theme`, `onClick`. See "ECharts configuration" section below.
+- **`PerspectivePanel`**: Wrapper for perspective-viewer. Props: `client`, `table`, `theme`, `config`, `onSelect`. See "Perspective chart configuration" section below.
+
+### Inputs
+
+- **`MultiSelect`**: Searchable checkbox dropdown. Props: `options`, `selected`, `onChange`, `labelKey`, `valueKey`, `label`, `placeholder`.
+- **`Select`**: Single-select dropdown. Props: `options` ({value, label}[]), `value`, `onChange`, `label`, `placeholder`.
+- **`FilterPills`**: Single-select horizontal toggle group. Props: `options` ({value, label}[]), `value`, `onChange`, `label`.
+- **`TextInput`**: Input with focus ring and optional icon. Props: `value`, `onChange`, `placeholder`, `label`, `icon`.
+- **`DateInput`**: Native date picker with design system styling. Props: `value`, `onChange`, `label`, `max`, `min`.
+
+### Overlay
+
+- **`Tooltip`**: Hover tooltip with arbitrary ReactNode content. Use for metric definitions, column explanations, filter descriptions. Props: `content` (ReactNode), `children` (trigger element), `position` ("top" | "bottom"), `maxWidth`.
+
+### Feedback
+
+- **`LoadingState`**: Full-page pulsing dots. Props: `message`.
+- **`ErrorState`**: Full-page error with red left bar. Props: `title`, `message`.
+- **`ResourceCacheBadge`**: Cache metadata popover. Props: `rows`, `cache`, `onClearAndReload`.
+
+## Refined SaaS shell (multi-view apps)
+
+A second track of primitives designed for apps with a sidebar and multiple views. Driven by a palette object instead of CSS vars, so customer brand accents flow through every chrome surface. Ships as the `refined` template.
+
+Canonical structure:
+
+```tsx
+import {
+  buildPalette, PaletteProvider, usePalette,
+  ShellLayout, Sidebar, SaasKpiCard, CachePopover,
+  DrillProvider, useDrill,
+  callFiFast, buildDrillPrompt,
+  useDataset, useSqlQuery, useTheme,
+} from "@definite/runtime";
+
+export default function App() {
+  const { theme, toggleTheme } = useTheme();
+  const palette = useMemo(() => buildPalette(theme, { accent: "#FF006E" }), [theme]);
+  const data = useDataset("main");
+  if (data.loading) return <LoadingState />;
+  if (data.error) return <ErrorState title="..." message={data.error} />;
+
+  return (
+    <PaletteProvider value={palette}>
+      <DrillProvider
+        aiChat={{
+          onAsk: (q, entity) => callFiFast({ prompt: buildDrillPrompt(q, entity) }),
+        }}
+      >
+        <InnerApp theme={theme} onThemeChange={(t) => t !== theme && toggleTheme()} dataset={data} />
+      </DrillProvider>
+    </PaletteProvider>
+  );
+}
+```
+
+### Shell primitives
+
+| Export | Role |
+|--------|------|
+| `buildPalette(theme, { accent? })` | Palette tokens with optional brand accent. |
+| `PaletteProvider` / `usePalette()` | Context for descendants. |
+| `ShellLayout` | Flex container with sidebar slot, breadcrumb, title, headerRight slot. Wraps children in `PaletteProvider`. |
+| `Sidebar` | Logo, nav, `dateRangeSlot`, `filterGroups` + `filters` (renders `FilterAccordion`), theme toggle, footer. |
+| `FilterAccordion` | Collapsible groups with per-group counts, global + per-group search, selected chips, swatch dots. |
+| `SaasKpiCard` | Accent top-line + sparkline + delta pill + loading shimmer. |
+| `CachePopover` | Click-to-inspect cache pill. |
+| `Sparkline` / `SkeletonShimmer` / `Breadcrumb` | Tiny primitives. |
+
+### Drill drawer
+
+Context-driven slide-over. Any descendant calls `useDrill().open(entity)`:
+
+```tsx
+drill.open({
+  kind: "kpi" | "row" | "chart",
+  id: "total_outstanding",
+  title: "Total outstanding",
+  value: "$50.8M",
+  breadcrumb: "Overview",
+  stats: [["Active", "2,511"]],
+  breakdown: [{ label: "2026-04", value: 1_780_000 }],
+  sql: "SELECT SUM(balance) FROM loans WHERE ...",
+  narrative: "Total principal balance across active contracts.",
+});
+```
+
+Author drill content inline at the call site — don't try to compute it in a shared helper yet. The pattern is young; wait until we have 3+ apps before extracting.
+
+### AI follow-up chat
+
+Pass `aiChat` to `DrillProvider` to render a chat input at the bottom of the drawer. `onAsk(userMessage, entity)` returns a string; throw to show an error message. The `callFiFast()` helper wraps `/v4/fi-fast`, extracting `response.content.parts[0].text`:
+
+```tsx
+<DrillProvider
+  aiChat={{
+    onAsk: (q, entity) => callFiFast({
+      prompt: buildDrillPrompt(q, entity),
+      // endpoint defaults to "/v4/fi-fast"; authToken optional
+    }),
+    placeholder: "Ask a follow-up…",
+  }}
+>
+```
+
+`callFiFast` defaults to same-origin cookies; pass `authToken` for Bearer auth. It's safe to leave wired in preview builds — the fetch will just 401 and the error bubbles into the chat as a message.
+
+### When to use `ShellLayout` vs `AppShell`
+
+| Use case | Component |
+|----------|-----------|
+| Multi-view analytics app (Loans, Risk, Originations...) | `ShellLayout` + `Sidebar` |
+| Single-view dashboard tile inside a Definite Doc | `AppShell` |
+| Embedded email-receipt-style full-width view | `AppShell` |
+
+Both are supported; they co-exist.
+
+## Best practices
+
+### Default recommendation
+
+- **Always use `type: "sql"` for dataset resources.** Write the SQL in app.json with camelCase aliases for all columns. This gives you full control over column names and avoids Cube title issues.
+- Use `kind: "json"` resources for small lookup lists (installer names, dropdown options, config maps).
+- Use `.duckdb` file resources when you need multiple tables, views, or semantic snapshots on the client.
+- **Never use `type: "cube"` in data apps** unless you have a specific reason. Cube responses use long title-based column names that are painful to work with in client-side SQL.
+
+### Column naming pattern
+
+Always alias columns to camelCase in app.json SQL. Then reference those exact aliases in `useSqlQuery`.
+
+```json
+// app.json: alias everything to camelCase
+"sql": "SELECT installer_account_name AS installerAccountName, fico::INTEGER AS fico, STRFTIME(application_date, '%Y-%m-%d') AS applicationDate, approval_cnt::INTEGER AS approvalCnt FROM LAKE.credit.projects WHERE ... LIMIT 500000"
+```
+
+```tsx
+// App.tsx: useSqlQuery references the camelCase aliases, NOT warehouse column names
+const result = useSqlQuery(data, data.tableRef
+  ? `SELECT installerAccountName, SUM(approvalCnt)::INTEGER AS approvals
+     FROM ${data.tableRef} WHERE applicationDate >= '2025-01-01' GROUP BY 1`
+  : "", []);
+```
+
+The column names in `useSqlQuery` (`installerAccountName`, `approvalCnt`, `applicationDate`) must exactly match the `AS` aliases in the app.json SQL. If they don't match, you get a runtime "Binder Error: Referenced column not found".
+
+### Pre-computed flags pattern (for conditional aggregation)
+
+When your dashboard needs conditional counts (e.g., "handled calls", "SLA calls"), **always** pre-compute the flags server-side:
+
+```json
+// app.json: compute flags server-side where complex CASE WHEN works correctly
+"sql": "SELECT ..., CASE WHEN Agent_Time > 0 AND Skill_No NOT IN ('123','456') AND Campaign NOT LIKE '%Outbound' THEN 1 ELSE 0 END AS isHandled, CASE WHEN Campaign LIKE '%Outbound' THEN 1 ELSE 0 END AS isOutbound FROM ..."
+```
+
+```tsx
+// App.tsx: simple aggregation of pre-computed flags (always works in DuckDB WASM)
+const kpis = useSqlQuery(data, data.tableRef ? `
+  SELECT
+    COUNT(*) AS totalCalls,
+    SUM(isHandled)::INTEGER AS handledCalls,
+    SUM(isOutbound)::INTEGER AS obAttempts,
+    ROUND(SUM(isHandled)::INTEGER * 100.0 / NULLIF(COUNT(*), 0), 1) AS handleRatePct
+  FROM ${data.tableRef}
+  WHERE startDate >= '${dateFrom}' AND startDate <= '${dateTo}'
+` : "", [dateFrom, dateTo]);
+
+// Display in KpiCard
+<KpiCard title="Handled Calls" value={handledCalls} format="number" />
+<KpiCard title="Handle Rate" value={handleRatePct} format="percent" />
+```
+
+Do NOT put compound CASE WHEN logic in `useSqlQuery`. It will silently return 0 in DuckDB WASM.
+
+### General guidance
+
+- Keep client-side SQL in `useSqlQuery` as simple as possible: GROUP BY, SUM, COUNT, simple WHERE filters.
+- Push all complex logic (joins, subqueries, CTEs, compound CASE WHEN, regex, LIKE patterns) into the app.json server-side SQL.
+- Always cast SUM results to `::INTEGER` in client-side SQL.
+- Convert dates to VARCHAR with `STRFTIME(col, '%Y-%m-%d')` in app.json SQL.
+- Use the `AppShell` component as your top-level wrapper.
+- Use `Card` for every content section.
+
+## DuckDB WASM limitations
+
+DuckDB WASM 1.29.0 has known issues with complex expressions in client-side SQL. These work correctly on the server but silently produce wrong results (usually 0) in the browser.
+
+### Compound CASE WHEN returns 0
+
+**This is the #1 source of silent data bugs.** Any `CASE WHEN` with compound boolean conditions (AND/OR chains, NOT IN with many values, LIKE patterns) may return 0 for all rows in DuckDB WASM, even though the same query returns correct results server-side.
+
+**Bad (client-side SQL in App.tsx):**
+```sql
+-- This silently returns 0 in DuckDB WASM
+SELECT SUM(CASE WHEN agent_time > 0
+  AND skill_no NOT IN ('123','456','789',...)
+  AND campaign NOT LIKE '%Outbound'
+  THEN 1 ELSE 0 END) AS handled
+FROM ${t} WHERE ${DATE_FILTER}
+```
+
+**Good (pre-compute in app.json, aggregate client-side):**
+```json
+// app.json: compute the flag server-side
+"sql": "SELECT ..., CASE WHEN Agent_Time > 0 AND Skill_No NOT IN ('123','456','789',...) AND Campaign_Name NOT LIKE '%Outbound' THEN 1 ELSE 0 END AS isHandled FROM ..."
+```
+```tsx
+// App.tsx: simple SUM of pre-computed flag
+const kpis = useSqlQuery(data, `
+  SELECT SUM(isHandled)::INTEGER AS handled
+  FROM ${t} WHERE ${DATE_FILTER}
+`, [dateFrom, dateTo]);
+```
+
+### General rule: keep client-side SQL simple
+
+| Server-side (app.json SQL) | Client-side (useSqlQuery) |
+|---|---|
+| Complex joins, subqueries, CTEs | Simple GROUP BY + aggregation |
+| CASE WHEN with compound booleans | SUM/COUNT of pre-computed columns |
+| NOT IN, LIKE, regex filters | Simple WHERE on date/string equality |
+| Type casts (BIGINT, DOUBLE) | `::INTEGER` on SUM results |
+| Flag computation, banding logic | Date range filters |
+
+If you find yourself writing a CASE WHEN with more than one condition in `useSqlQuery`, move it to app.json instead.
+
+## Perspective chart configuration
+
+`PerspectivePanel` accepts a `config` object passed to `viewer.restore()`. The key properties:
+
+### Plugin types
+
+| Plugin | Type | Best for |
+|--------|------|----------|
+| `"Datagrid"` | Table | Raw data, record views |
+| `"Y Bar"` | Vertical bar | Category comparisons |
+| `"X Bar"` | Horizontal bar | Ranked categories, long labels |
+| `"Y Line"` | Line chart | Time series, trends |
+| `"Y Area"` | Area chart | Stacked volumes over time |
+| `"Y Scatter"` | Scatter plot | Correlations |
+| `"Heatmap"` | Heatmap | Two-dimensional patterns |
+| `"Treemap"` | Treemap | Hierarchical proportions |
+| `"Sunburst"` | Sunburst | Hierarchical categories |
+
+### Config properties
+
+```tsx
+<PerspectivePanel
+  client={perspective.client}
+  table={transactions.perspectiveTable}
+  theme={theme}
+  config={{
+    plugin: "Y Bar",
+    columns: ["amount"],             // Measures to display
+    group_by: ["branchName"],        // X-axis / grouping dimension
+    split_by: ["status"],            // Optional: series breakdown
+    aggregates: { amount: "sum" },   // Aggregation per column
+    sort: [["amount", "desc"]],      // Sort order
+    filter: [["status", "==", "Funded"]],  // Filters
+    settings: false,                 // Hide settings panel
+    title: "Revenue by Branch",      // Chart title
+    columns_config: {                // Number formatting (Intl.NumberFormat)
+      amount: { number_format: { style: "currency", currency: "USD", maximumFractionDigits: 0 } },
+    },
+  }}
+/>
+```
+
+### Chart patterns
+
+**Bar chart (category comparison):**
+```tsx
+config={{ plugin: "Y Bar", columns: ["amount"], group_by: ["branchName"], aggregates: { amount: "sum" }, sort: [["amount", "desc"]] }}
+```
+
+**Line/Area chart (time series):**
+```tsx
+config={{ plugin: "Y Line", columns: ["transactionId"], group_by: ["transactionDate"], split_by: ["status"], aggregates: { transactionId: "count" } }}
+```
+
+**Stacked area (volume over time by category):**
+```tsx
+config={{ plugin: "Y Area", columns: ["amount"], group_by: ["transactionDate"], split_by: ["branchName"], aggregates: { amount: "sum" } }}
+```
+
+### Drill-down (click-to-filter)
+
+Use `perspective-select` events on the viewer element. **Do NOT use `perspective-click`**; it only fires on Datagrid. For D3FC chart plugins (bar, line, area), use `perspective-select`.
+
+Event payload:
+```typescript
+e.detail = {
+  selected: true,       // true on select, false on deselect
+  row: { ... },         // data for clicked element
+  column_names: ["col"] // column name strings
+}
+```
+
+**Gotcha:** Keys in `e.detail.row` may not match your column names. Always inspect `Object.keys(row)` first.
+
+To wire drill-down in a React component, attach an event listener to the `perspective-viewer` ref inside a `PerspectivePanel`:
+
+```tsx
+// In a custom wrapper around PerspectivePanel, after the viewer loads:
+viewerRef.current.addEventListener('perspective-select', (e) => {
+  const row = e.detail?.row;
+  if (!row) return;
+  const value = row['branchName'] ?? row[Object.keys(row)[0]];
+  if (value == null) return;
+  // Toggle: click same value to clear filter
+  setFilter(prev => prev === value ? '' : String(value));
+});
+```
+
+For multi-chart drill-down (clicking a bar in one chart filters all others), maintain shared filter state in the parent component and pass Perspective `filter` arrays to each `PerspectivePanel` config.
+
+### Perspective tips
+
+- Keep using the provided `PerspectivePanel` / `usePerspective()` wiring unless you have a concrete reason not to.
+- For `.duckdb` resources, set `source.table` if the UI needs a default table name for Perspective or local SQL.
+- If the UI uses tabs, call `viewer.notifyResize?.()` when a hidden Perspective view becomes visible.
+
+## ECharts configuration
+
+Apache ECharts is loaded from CDN (`window.echarts`). The `EChart` component is a thin lifecycle wrapper; pass the full ECharts option spec as the `option` prop. Docs: https://echarts.apache.org/en/option.html
+
+### CRITICAL: No functions in EChart options
+
+The `EChart` component serializes the option object through `JSON.stringify` / `JSON.parse` for change detection. **This strips all JavaScript functions.** Any `formatter`, `valueFormatter`, or callback function in your option will be silently removed and ECharts will use its defaults (or crash).
+
+**Do this instead:**
+
+| Instead of | Do this |
+|------------|---------|
+| `yAxis.axisLabel.formatter: (v) => "$" + v + "M"` | Scale data to millions in your query, use string template: `formatter: "${value}M"` |
+| `tooltip.valueFormatter: (v) => ...` | Remove it; ECharts will format the raw value. Or pre-format data. |
+| `series.label.formatter: (params) => ...` | Pre-compute label strings and embed them per data point: `data: values.map((v, i) => ({ value: v, label: { formatter: precomputedLabels[i] } }))` |
+| `tooltip.formatter: (params) => ...` | Cannot use custom tooltip formatters. Use default tooltip or restructure data so defaults look good. |
+
+**String templates that work:** ECharts template syntax like `"{value}%"` and `"{b}: {c}"` survives JSON serialization because they're plain strings, not functions. Use `${value}` to prepend a literal dollar sign (the `$` is literal, `{value}` is replaced by ECharts).
+
+### When to use EChart vs PerspectivePanel
+
+| EChart | PerspectivePanel |
+|--------|-----------------|
+| Custom styled charts (conditional bar colors, combo bar+line, dashed forecast lines) | Interactive data grids with sort/filter/pivot |
+| Chart.js-style management report charts | Exploratory data analysis |
+| Small to medium datasets (pre-aggregated) | Large datasets (DuckDB-backed, client-side SQL) |
+| Full control over every visual element | Quick setup with sensible defaults |
+
+### Bar chart
+
+```tsx
+<EChart theme={theme} option={{
+  xAxis: { type: "category", data: ["Austin", "Denver", "Chicago"] },
+  yAxis: { type: "value" },
+  series: [{ type: "bar", data: [42000, 38000, 51000], itemStyle: { borderRadius: [4, 4, 0, 0] } }],
+}} />
+```
+
+### Combo bar + line (actual vs forecast)
+
+```tsx
+<EChart theme={theme} option={{
+  tooltip: { trigger: "axis" },
+  legend: { data: ["Actual", "Target"] },
+  xAxis: { type: "category", data: ["Jan", "Feb", "Mar", "Apr"] },
+  yAxis: { type: "value" },
+  series: [
+    { name: "Actual", type: "bar", data: [
+      { value: 42000, itemStyle: { color: "#22c55e" } },
+      { value: 28000, itemStyle: { color: "#f87171" } },
+    ]},
+    { name: "Target", type: "line", data: [35000, 35000, 40000, 40000],
+      lineStyle: { type: "dashed", color: "#eab308" },
+      itemStyle: { color: "#eab308" } },
+  ],
+}} />
+```
+
+### Per-bar conditional coloring
+
+Use `data` as an array of objects with `itemStyle`:
+```tsx
+data: values.map(v => ({
+  value: v.amount,
+  itemStyle: { color: v.amount >= v.target ? "#22c55e" : "#f87171" },
+}))
+```
+
+### Click events (drill-down)
+
+```tsx
+<EChart
+  theme={theme}
+  onClick={(params) => {
+    const name = params.name;  // category label
+    setFilter(prev => prev === name ? "" : name);
+  }}
+  option={...}
+/>
+```
+
+### Theme switching
+
+The `EChart` component handles theme automatically. Pass `theme` from `useTheme()` and the chart re-initializes with the correct ECharts built-in theme ("dark" or "light") on toggle.
+
+## Quick reference: starter App.tsx pattern
+
+```tsx
+import React from "react";
+import {
+  useDataset,
+  useSqlQuery,
+  useTheme,
+  AppShell,
+  Card,
+  KpiCard,
+  LoadingState,
+  ErrorState,
+} from "@definite/runtime";
+
+export default function App() {
+  const theme = useTheme();
+  const data = useDataset("main");
+
+  const summary = useSqlQuery(
+    data,
+    data.tableRef
+      ? `SELECT COUNT(*)::INTEGER AS totalRows FROM ${data.tableRef}`
+      : "",
+    [],
+  );
+
+  if (data.loading) return <LoadingState message="Loading data..." />;
+  if (data.error) return <ErrorState title="Load Error" message={data.error} />;
+
+  return (
+    <AppShell title="My App" subtitle="Dashboard subtitle here">
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-4 mb-6">
+        <KpiCard
+          title="Total Rows"
+          value={summary.data?.[0]?.totalRows}
+          format="number"
+          loading={summary.loading}
+        />
+      </div>
+    </AppShell>
+  );
+}
+```