@graphit/cli 0.1.18 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "type": "module",
   "bin": {

package/skills/graphit/SKILL.md

@@ -43,7 +43,7 @@ Your HTML must NEVER contain:
 - `<img src="https://...">` - no external images
 
 If you use ANY `src=` or `href=` pointing to a URL, the dashboard will be blank.
-All CSS in `<style>`, all JS in `<script>`, all fonts from system stack. The iframe has a built-in runtime (`graphit.chart`, `graphit.table`, `graphit.kpi`) for standard visualizations - use it instead of importing libraries.
+All CSS in `<style>`, all JS in `<script>`, all fonts from system stack. The iframe has a built-in runtime (`graphit.chart`, `graphit.table`, `graphit.kpi`, `graphit.presentation`) for standard visualizations - use it instead of importing libraries.
 
 ### 2. ALWAYS query through data sources
 NEVER query the warehouse directly when a cached data source covers the table. Data sources return in ~100ms. Warehouse queries take ~10s and cost Snowflake credits.
@@ -322,6 +322,7 @@ The iframe also provides optional convenience helpers if you want quick standard
 | `graphit.chart(el, {type, data, x, y, ...})` | Bar, line, area, donut, scatter, stacked-bar, heatmap, funnel, gauge, sparkline |
 | `graphit.table(el, {data, columns?, maxRows?})` | Styled HTML table. `columns` is a `string[]` of data keys (NOT objects), defaults to `Object.keys(data[0])` |
 | `graphit.kpi(el, {value, label?, format?})` | KPI card with optional delta |
+| `graphit.presentation(el)` | Full-screen slide deck. Returns builder: `.slide({bg, layout, html})` then `.start()`. See `presentations.md` |
 
 These are shortcuts, not requirements. Use them when a standard chart is all you need. Hand-roll when you want full control over the visualization.
 
@@ -378,3 +379,4 @@ Detailed knowledge lives in `references/`. Consult the relevant file when you ne
 | `graphit-style.md` | Building the HTML. Design principles, typography scale, color system with usage rules, layout patterns (page structure, KPI cards, data tables). |
 | `chart-patterns.md` | Custom chart implementations. Inline SVG/CSS code for: scatter/bubble, heatmap, funnel, gauge, sparkline, stacked bar, and the shared tooltip pattern. |
 | `governance.md` | Query governance. Reference syntax, trust tiers, enforceable rules, override flow, governance commands. |
+| `presentations.md` | Slide deck presentations. Builder API, layouts (center/split/full), backgrounds, navigation, live data inside slides. |

package/skills/graphit/cursor/graphit-presentations.mdc

@@ -0,0 +1,56 @@
+---
+alwaysApply: false
+description: "Graphit: Build full-screen slide deck presentations inside canvas dashboards using graphit.presentation(). Builder pattern with layouts, backgrounds, and keyboard navigation."
+globs: []
+---
+
+# Presentations
+
+Build slide deck presentations inside Graphit canvas dashboards using `graphit.presentation()`.
+
+## API
+
+```js
+var deck = graphit.presentation('#my-deck');
+deck.slide({ bg: 'dark', layout: 'center', html: '<h1>Title</h1>' });
+deck.slide({ bg: 'white', layout: 'split', html: '<div>Left</div><div>Right</div>' });
+deck.slide({ bg: 'paper', layout: 'full', html: '<div id="charts">...</div>' });
+var ctrl = deck.start();
+```
+
+## Slide Config
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `layout` | `'center'` / `'split'` / `'full'` | `'center'` | Content arrangement |
+| `bg` | `'paper'` / `'white'` / `'dark'` / `'teal'` / hex | `'paper'` | Fixed background |
+| `html` | `string` | `''` | Raw HTML content |
+
+## Layouts
+
+- **center**: Centered horizontally/vertically. Title slides, CTAs.
+- **split**: First two child elements become left/right panels. Text + image.
+- **full**: Top-to-bottom flow. Tables, grids, live data.
+
+## Backgrounds (fixed, not theme-aware)
+
+| Name | Background | Text |
+|------|-----------|------|
+| `paper` | `#F7F6F2` | `#222224` |
+| `white` | `#FFFFFF` | `#222224` |
+| `dark` | `#222224` | `#F7F6F2` |
+| `teal` | `#4DB6AC` | `#FFFFFF` |
+
+## Navigation
+
+Arrow keys, spacebar, Home/End. Prev/Next buttons bottom-right with slide counter.
+
+## Live data works inside slides
+
+`graphit.resolve()` + `graphit.chart/table/kpi` work inside slides. Entity wrapping (`data-graphit-*`) works normally.
+
+## Anti-Patterns
+
+- Don't use external fonts/images (CSP blocks). Embed as base64 or use system fonts.
+- Don't put scrollable content on slides. Split into multiple slides.
+- One `graphit.presentation()` per dashboard.

package/skills/graphit/cursor/graphit-sql-reference.mdc

@@ -128,12 +128,14 @@ Canvas `graphit.resolve()` queries that follow these shapes serve from a semanti
 - Literal dates (`>= '2026-01-01'`), never `CURRENT_DATE` expressions
 - GROUP BY column names or ordinals; ORDER BY / LIMIT allowed (outer only)
 - CTEs are fine when the CTE body follows the same rules
+- Top-N rank queries: project the sort metric in SELECT (`SELECT dim, SUM(metric) AS rv ... ORDER BY rv DESC LIMIT N`), not only in ORDER BY
 
 **Shapes that skip the cache** (fall back to normal execution, still correct):
 - `COUNT(DISTINCT x)`, window functions, HAVING, QUALIFY
 - OR / NOT in WHERE
 - Ratio metrics (`SUM(a)/NULLIF(SUM(b),0)`) - compute client-side or use two resolves
 - `CURRENT_DATE`-relative predicates
+- Top-N with aggregate only in ORDER BY (`SELECT dim FROM t GROUP BY dim ORDER BY SUM(metric) DESC LIMIT N` - no decomposable aggregate in SELECT)
 
 ## Data Source Routing
 

package/skills/graphit/references/graphit-style.md

@@ -37,6 +37,17 @@ NEVER use hardcoded hex colors. Use CSS custom properties that automatically ada
 - **Warning:** `var(--graphit-warning)`
 - **Danger / bad:** `var(--graphit-error)`
 
+### Custom Colors
+
+When the user explicitly requests specific colors or a custom color theme, ask for both light and dark mode variants. Write explicit CSS with `.dark` class overrides so the dashboard adapts to both modes:
+
+```css
+.revenue-card { background: #001f3f; color: #ffffff; }
+.dark .revenue-card { background: #0a3d6b; color: #e0e0e0; }
+```
+
+NEVER hardcode a structural color (background, color, border-color) without a `.dark` counterpart. Data/chart series colors (bar fills, line strokes) are exempt - they work in both modes.
+
 ### Multi-Series
 Use `var(--graphit-accent)` as the primary series. For additional series, choose muted complementary colors that work on both light and dark backgrounds.
 

package/skills/graphit/references/presentations.md

@@ -0,0 +1,143 @@
+# Presentations
+
+Build full-screen slide deck presentations inside Graphit canvas dashboards using `graphit.presentation()`.
+
+## API
+
+```js
+var deck = graphit.presentation('#my-deck');
+
+deck.slide({ bg: 'dark', layout: 'center', html: '<h1>Title</h1><p>Subtitle</p>' });
+deck.slide({ bg: 'white', layout: 'split', html: '<div>Left panel</div><div>Right panel</div>' });
+deck.slide({ bg: 'paper', layout: 'full', html: '<div id="charts">...</div>' });
+
+var ctrl = deck.start();
+// ctrl.go(3)  - jump to slide 4
+// ctrl.total  - number of slides
+```
+
+`graphit.presentation(el)` returns a **builder**. Call `.slide()` to add slides (chainable), then `.start()` to render and wire navigation. `start()` returns a controller with `go(n)` and `total`.
+
+## Slide Config
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `layout` | `'center'` / `'split'` / `'full'` | `'center'` | How content is arranged inside the slide |
+| `bg` | `'paper'` / `'white'` / `'dark'` / `'teal'` / hex | `'paper'` | Fixed background color (not theme-aware) |
+| `html` | `string` | `''` | Raw HTML content for the slide |
+
+## Layouts
+
+### `center` (default)
+Content is centered horizontally and vertically. Use for title slides, quotes, big stats, CTAs.
+
+### `split`
+The first two child elements in `html` become left and right panels (50/50 flex). Use for text + image, comparison, side-by-side content. On mobile (<700px), panels stack vertically.
+
+```js
+deck.slide({
+  layout: 'split',
+  bg: 'white',
+  html: '<div><h2>Left Title</h2><p>Text content</p></div><div><img src="data:..."></div>'
+});
+```
+
+### `full`
+Content flows top-to-bottom with generous padding. Use for tables, grids, live data dashboards, complex layouts that need the full slide width.
+
+## Background Themes
+
+Backgrounds are **fixed colors** - they do not change with the app's light/dark mode. A dark slide stays dark. Content inside CAN use `var(--graphit-*)` tokens.
+
+| Name | Background | Text Color |
+|------|-----------|------------|
+| `paper` | `#F7F6F2` (warm cream) | `#222224` (charcoal) |
+| `white` | `#FFFFFF` | `#222224` |
+| `dark` | `#222224` (charcoal) | `#F7F6F2` (cream) |
+| `teal` | `#4DB6AC` (brand teal) | `#FFFFFF` |
+| hex string | Custom (e.g. `#1a1a2e`) | Inherited from content HTML |
+
+## Navigation
+
+The slide deck includes built-in navigation:
+- **Arrow keys**: Left/Right to navigate (guarded - skips when focus is on input/textarea)
+- **Spacebar**: Next slide
+- **Home/End**: First/last slide
+- **Prev/Next buttons**: Bottom-right corner with slide counter
+
+## Live Data Inside Slides
+
+`graphit.resolve()` and `graphit.chart/table/kpi` work inside slides. All resolve calls fire on page load (cached queries are fast). Charts render into their target elements regardless of which slide is visible.
+
+```js
+// Slide with live entities
+deck.slide({
+  layout: 'full',
+  bg: 'white',
+  html: `
+    <h2>Live Data</h2>
+    <div data-graphit-id="spend-chart" data-graphit-label="Ad Spend"
+         data-graphit-kb="metric:TOTAL_AD_SPEND,table:MARKETING_UA"
+         data-graphit-sql="SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) AS spend FROM MARKETING_UA_DS GROUP BY 1 ORDER BY spend DESC LIMIT 6"
+         data-graphit-ds="ds_abc123">
+      <div id="chart1" class="gh-loading">
+        <div class="gh-loading-overlay"><svg class="gh-loading-spin" width="24" height="24" viewBox="0 0 24 24" fill="none"><circle cx="12" cy="12" r="10" stroke="#e5e5e5" stroke-width="2.5"/><path d="M12 2a10 10 0 0 1 10 10" stroke="#4DB6AC" stroke-width="2.5" stroke-linecap="round"/></svg></div>
+      </div>
+    </div>
+  `
+});
+
+// After deck.start(), fire resolve calls
+deck.start();
+
+graphit.resolve({
+  sql: "SELECT MEDIA_SOURCE, SUM(APPSFLYER_COST) AS spend FROM MARKETING_UA_DS GROUP BY 1 ORDER BY spend DESC LIMIT 6",
+  dataSourceId: "ds_abc123",
+  target: "#chart1"
+}).then(function(r) {
+  graphit.chart("#chart1", { type: "bar", data: r.data, x: "MEDIA_SOURCE", y: "spend", valueFormat: "currency" });
+});
+```
+
+## Entity Wrapping
+
+Every data element inside slides should have full `data-graphit-*` entity wrapping, same as regular dashboards. The entity provenance panel, @ mentions, and click-to-inspect all work inside slides.
+
+## Example: Complete Pitch Deck
+
+```js
+var deck = graphit.presentation('#deck');
+
+deck.slide({
+  bg: 'paper',
+  layout: 'center',
+  html: '<h1 style="font-size:6rem;font-weight:300">Company Update</h1><p style="font-size:1.5rem;color:#6B7280;margin-top:16px">Q2 2026</p>'
+});
+
+deck.slide({
+  bg: 'dark',
+  layout: 'split',
+  html: '<div style="color:#F7F6F2"><h2 style="font-size:3rem">The Problem</h2><p style="font-size:1.25rem;opacity:0.7;margin-top:16px">Analysts spend 80% of their time assembling dashboards instead of finding insights.</p></div><div style="display:flex;align-items:center;justify-content:center"><img src="data:image/webp;base64,..." style="max-height:60vh;border-radius:16px"></div>'
+});
+
+deck.slide({
+  bg: 'white',
+  layout: 'full',
+  html: '<h2 style="font-size:2.5rem;margin-bottom:24px">Key Metrics</h2><div style="display:grid;grid-template-columns:repeat(3,1fr);gap:16px">...</div>'
+});
+
+deck.slide({
+  bg: 'teal',
+  layout: 'center',
+  html: '<h2 style="font-size:4rem;color:#fff">Thank You</h2><p style="font-size:1.25rem;color:rgba(255,255,255,0.7);margin-top:16px">company.com</p>'
+});
+
+deck.start();
+```
+
+## Anti-Patterns
+
+- **Don't put too much content on one slide.** If it scrolls, split into multiple slides.
+- **Don't use external fonts via @import or link.** The iframe CSP blocks them. Embed as base64 @font-face or use system fonts.
+- **Don't use external images.** Use data URIs (base64) or inline SVG.
+- **Don't nest presentations.** One `graphit.presentation()` per dashboard.

package/skills/graphit/references/sql-reference.md

@@ -122,12 +122,14 @@ Canvas `graphit.resolve()` queries that follow these shapes serve from a semanti
 - Literal dates (`>= '2026-01-01'`), never `CURRENT_DATE` expressions
 - GROUP BY column names or ordinals; ORDER BY / LIMIT allowed (outer only)
 - CTEs are fine when the CTE body follows the same rules
+- Top-N rank queries: project the sort metric in SELECT (`SELECT dim, SUM(metric) AS rv ... ORDER BY rv DESC LIMIT N`), not only in ORDER BY
 
 **Shapes that skip the cache** (fall back to normal execution, still correct):
 - `COUNT(DISTINCT x)`, window functions, HAVING, QUALIFY
 - OR / NOT in WHERE
 - Ratio metrics (`SUM(a)/NULLIF(SUM(b),0)`) - compute client-side or use two resolves
 - `CURRENT_DATE`-relative predicates
+- Top-N with aggregate only in ORDER BY (`SELECT dim FROM t GROUP BY dim ORDER BY SUM(metric) DESC LIMIT N` - no decomposable aggregate in SELECT)
 
 ## Data Source Routing