@compilr-dev/sdk 0.18.9 → 0.18.11

package/dist/skills/canvas-skills.js

@@ -35,19 +35,41 @@ export const canvasSkill = defineSkill({
 
 ## STEPS
 
-1. **Collect the essentials from the user FIRST — this is the standard approach.** A canvas is an expensive authoring pass; building it on guessed requirements wastes that pass and lands wide of what the user wanted. So before you author, use **\`ask_user\`** (batch several questions into ONE call) to gather what the canvas needs:
-   - **Purpose & audience** — what is it for, who reads it?
-   - **Canvas type** — infographic, carousel, or board? (Offer the choice unless obvious.)
-   - **Key content / data** — the actual points, numbers, sections, or slides to include. Don't invent data.
-   - **Style / brand** — theme-matched (default), a specific palette/brand, or a named **aesthetic**? For infographics & carousels you can offer a look from the \`canvas-styles\` skill (skeuomorphic, glass, brutalist, editorial, retro) as part of THIS same question — don't default every canvas to the flat theme look.
-   For open design directions (which layout, which visual approach), present concrete options with **\`propose_alternatives\`** instead of guessing.
-   **Skip questions the user already answered**, and if they gave full detail or explicitly said "just make it / surprise me / your call", go straight to authoring. Keep it to ONE focused round — a short question batch, never a long interview — then build.
+⚠️ **Two passes, not one.** Most weak canvases are weak because layout and decoration got
+decided in the same breath, and the decoration ends up compensating for a structure that
+never worked. Structure first, with the real content; skin it second, from a recipe.
 
-2. **Build the canvas in small steps — never one giant tool call.** A canvas is HTML/SVG you emit as tool arguments; a single very large \`canvas_write\` can overrun the output limit, get cut off mid-arguments, and fail. So author it incrementally, and emit each tool call immediately with NO prose preamble (narration competes with the HTML for the same output budget):
+1. **Ask purpose, audience and content — never taste.** Use **\`ask_user\`** (batch into ONE
+   call):
+   - **Purpose & audience** — what is it for, who reads it?
+   - **Key content / data** — the actual points, numbers, sections or slides. Don't invent
+     data; if you need a figure you were not given, ask for it.
+
+   ⚠️ **Do NOT ask which style or aesthetic they want.** "Brutalist or editorial?" asks
+   someone to imagine two things they have never seen, in a vocabulary they did not choose,
+   before the canvas exists — and then commits you to whatever comes back. Purpose,
+   audience and content are answerable from what the user already knows. Style is
+   answerable from what they can SEE, which is step 8.
+
+   **Skip the round entirely** when they said "just make it / surprise me / your call" or
+   already gave full detail. This round asks LESS than it used to, not more.
+
+2. **Route the type and style from the content**, using the cheatsheet in
+   \`canvas_guide("styles")\`. One screen of an app → \`infographic\` + the app-screen style.
+   Several options compared → \`board\`. Slides → \`carousel\`. Data or a one-pager →
+   \`infographic\` + theme-flat.
+
+3. **Pass one — structure, with the FINAL content.** No colour decisions, no type scale yet:
+   get the real words and real numbers into the real layout. A structure that works with
+   placeholder text is not a structure.
+
+   Build it in small steps — never one giant tool call. A canvas is HTML/SVG you emit as
+   tool arguments; a single very large \`canvas_write\` can overrun the output limit, get cut
+   off mid-arguments, and fail. Emit each call immediately with NO prose preamble
+   (narration competes with the HTML for the same output budget):
    - **2a. First \`canvas_write\`** (type, title, html) = a COMPACT skeleton: the \`<style>\` block, the overall layout, and just the first section or heading. This is the ONLY way to create a canvas — describing it in chat does nothing.
    - **2b. Then \`canvas_edit\` (operation=append)** to add each remaining section, one call per section. The preview grows as you go, and every call stays small and reliable. (You can also leave \`<!-- placeholder -->\` markers in 2a and str_replace them.)
    - Put the whole thing in one \`canvas_write\` ONLY if it is genuinely small (a single stat card / short poster).
-
    HTML constraints for every write:
    - Do NOT include \`<html>\`, \`<head>\`, \`<meta>\`, \`<!doctype>\`, or your own CSP — the host injects the sandbox and CSP. Just the body content + a \`<style>\` and optional \`<script>\`.
    - The sandbox is \`allow-scripts\` with NO same-origin and CSP \`default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:\`. So: inline \`<style>\`/\`<script>\` only, no external fonts/CSS/JS/network, no remote images (use inline SVG or data: URIs).
@@ -56,7 +78,13 @@ export const canvasSkill = defineSkill({
    - Make it look intentional: a clear grid, strong type scale, generous spacing. Use \`var(--canvas-accent)\` sparingly for emphasis. Prefer inline SVG for shapes/charts/icons (fill/stroke with the theme vars).
    - For a **carousel**, wrap each slide in \`<section data-sheet>…</section>\` — a natural unit to add one per \`canvas_edit\` append.
 
-3. **Add a Tweaks controls manifest when it helps** (the \`controls\` argument). Each control is \`{ type, param, label, default, …type config }\` where type ∈ slider | number | toggle | select | color | text.
+4. **Pass two — skin it.** Read \`canvas_guide\` for your style's recipe and its exemplar
+   (\`exemplar-infographic\` or \`exemplar-app-screen\`), then apply the values. This pass is
+   mechanical, because the recipe supplies every number — surfaces, type ladder, spacing
+   scale, accent budget. Edit in place with \`canvas_edit\`; pass one already put the content
+   where it belongs.
+
+5. **Add a Tweaks controls manifest when it helps** (the \`controls\` argument). Each control is \`{ type, param, label, default, …type config }\` where type ∈ slider | number | toggle | select | color | text.
    - **⚠️ EVERY control you declare MUST be bound in the HTML — a declared-but-unbound control is a dead knob that visibly does nothing when the user drags it. Declaring the control is only half the job; you MUST also reference its param.** Bind each param one of these ways:
      - CSS custom property (most common): use \`var(--param)\` directly in your styles — e.g. a \`headline\` slider means \`font-size: var(--headline)\` (NOT a literal \`48px\`), an \`accent\` color means \`color: var(--accent)\`. The host sets \`--param\` on the root and updates it live. Include a unit in the CSS if the raw value is a number: \`font-size: calc(var(--headline) * 1px)\`.
      - Text binding: \`<span data-bind="param"></span>\` — its text is replaced with the value.
@@ -65,13 +93,48 @@ export const canvasSkill = defineSkill({
    - Give every canvas at least 2–4 sensible controls (accent color, a headline size slider, a toggle to show/hide a section). Seed \`default\` values that MATCH what you authored (a slider default of 48 means the HTML's initial \`var(--headline)\` should read 48).
    - **Before finishing, re-check: is each control's \`param\` actually referenced in the HTML?** If not, either bind it or drop the control — never ship a dead knob.
 
-4. **To EDIT an existing canvas, do NOT re-send the whole document.** First call \`canvas_get\` with \`outline=true\` (or a \`startLine\`/\`maxLines\` slice) to find the exact snippet, then \`canvas_edit\` with \`operation=str_replace\` (old_str must be unique — include surrounding context — or set replace_all=true), or append/prepend. Reserve \`canvas_write\` with \`canvas_id\` for a full intentional rewrite.
+6. **To EDIT an existing canvas, do NOT re-send the whole document.** First call \`canvas_get\` with \`outline=true\` (or a \`startLine\`/\`maxLines\` slice) to find the exact snippet, then \`canvas_edit\` with \`operation=str_replace\` (old_str must be unique — include surrounding context — or set replace_all=true), or append/prepend. Reserve \`canvas_write\` with \`canvas_id\` for a full intentional rewrite.
+
+7. **Validate.** Call \`canvas_validate\` (canvas_id) — a fast static check for content that
+   won't render (Mermaid/Markdown/CDN), a board missing its \`data-board\` bounds or with
+   nodes off-canvas, sparse output, hardcoded colours that ignore the theme, a card that
+   shares its ground's value, text under 4.5:1, too many hues, and dead Tweaks. Fix every
+   **error** and address applicable **warnings**.
+
+8. **The gate — screenshot, verdict, fix, screenshot AGAIN.** Call \`canvas_screenshot\`
+   (canvas_id), then give all six verdicts explicitly, in this form:
+
+   \`01 pass · 02 fail → fixed · 03 pass · 04 pass · 05 fail → fixed · 06 pass\`
+
+   | # | check | the question to ask |
+   |---|---|---|
+   | 01 | One dominant element | Squint: what do you see FIRST? If the answer is "the whole thing at once", nothing dominates. The largest element should be ≥2x the next and hold the FINDING, not merely the first metric. |
+   | 02 | Cards differ from their ground | Cover the borders with your thumb — can you still see the cards? If the layout only exists because of its lines, the ramp is missing. |
+   | 03 | Nothing under 4.5:1 | Check every label against the surface it ACTUALLY sits on, not against the page. |
+   | 04 | Every value is specific | Do the numbers add up? Could a reader challenge one? A total that does not reconcile with its rows is what makes a canvas feel machine-made. |
+   | 05 | Density varies | Blur it until the text goes — is there a composition left? A uniform grid of equal boxes is a form. |
+   | 06 | One accent, one family | Count the hues, then count the reasons. More hues than reasons means colour is decoration. |
 
-5. **Validate before you hand it off.** Once the canvas is composed, call \`canvas_validate\` (canvas_id) — a fast static check that catches content that won't render (Mermaid/Markdown/CDN), a board missing its \`data-board\` bounds or with nodes off-canvas, sparse output, and hardcoded colors that ignore the theme tokens. Fix any **errors** (they render broken) and address applicable **warnings**, then move on.
+   ⚠️ **Naming each check is what forces looking at it.** Asked for a summary judgement, a
+   model writes "looks good" every time.
 
-6. **See it before you trust it (if you can).** If you're vision-capable, call \`canvas_screenshot\` (canvas_id) — it renders the canvas and returns the image so you can catch what static checks can't: overflow / cut-off content, unreadable or low-contrast text, cramped or empty areas, broken layout. If something's off, fix it with \`canvas_edit\` and screenshot again. (No-op on text-only models / hosts that can't render.)
+   ⚠️ **FAILING IS NORMAL** — most first drafts fail two of these. A failed check is
+   something to EDIT, not something to argue with. Do not write a justification.
 
-7. **After writing, tell the user what you made in one line** and point them at the Tweaks they can adjust. The canvas opens in its own tab.
+   ⚠️ **The second screenshot is the one that matters**, because it catches a fix that broke
+   something else. Cap at two rounds; if something still fails, hand off and say so in one
+   clause.
+
+   Checks 02, 03 and 06 are also computed by \`canvas_validate\`, so on a text-only model run
+   the gate on 01, 04 and 05 — they need judgement, not eyes.
+
+   ⚠️ **Do not report the gate to the user.** The verdicts are working notes.
+
+9. **One line, then offer two alternates as PICTURES.** Say what you made and point at the
+   Tweaks. Then use **\`propose_alternatives\`** with **two** further skins of the same
+   canvas — never a list of style names. The content is already fixed, so each variant
+   costs one \`canvas_write\` and the user picks by looking. This is the aesthetic menu,
+   moved to the only point where the choice is cheap for them and informative for you.
 
 ## Rules
 - CALL THE TOOL — don't describe the HTML you "would" write and stop. A canvas only exists once the tool succeeds.
@@ -177,6 +240,11 @@ export const boardSkill = defineSkill({
 ## SHOW, don't TELL (the #1 rule)
 A board is a VISUAL surface — its value is that it *depicts* things, not that it holds text. If your board is mostly paragraphs and bullet lists, you've built a text document on a grid and failed the medium. That is what the "propose alternatives" text tool is for — a board must EARN its place by being visual.
 - **Depict, don't describe.** Exploring website / UI options? DRAW each option as a **wireframe mock** — a browser/window frame with a nav bar, a hero block, and content sections as labeled BOXES — laid side by side so they can be compared at a glance. Do NOT write "Option A: terminal-first hero, CLI-style product list…" as prose; SKETCH it.
+  - ⚠️ **This is for COMPARING several options, at low fidelity.** For ONE screen at full
+    fidelity — "mock up the admissions dashboard" — use \`infographic\` with the
+    **app-screen** style instead (\`canvas_guide("styles")\`), and draw NO window chrome
+    there. The frame below earns its place only because several options sitting side by
+    side need something to separate them.
 - **Architecture / flow?** Draw boxes-and-arrows (nodes + inline-SVG connectors), not a written description of the components.
 - **Mind-map?** A central node with branches and sub-nodes, not an outline.
 - Text belongs INSIDE the visual as short labels (titles, captions, a few key words) — never as the primary content of a node.
@@ -187,7 +255,7 @@ Build each screen mock as nested boxes so it reads as a *picture of a page*:
 <div style="position:absolute;left:80px;top:120px;width:520px;background:var(--canvas-card);
      border:1px solid var(--canvas-border);border-radius:8px;overflow:hidden">
   <div style="height:28px;background:var(--canvas-bg);display:flex;align-items:center;gap:6px;padding:0 10px">
-    <span style="width:8px;height:8px;border-radius:50%;background:var(--canvas-muted)"></span> …traffic lights…
+    <span style="width:8px;height:8px;border-radius:50%;background:var(--canvas-muted)"></span> …dots that say "this is a window"…
   </div>
   <div style="height:44px;border-bottom:1px solid var(--canvas-border);display:flex;align-items:center;
        justify-content:space-between;padding:0 16px"><b style="color:var(--canvas-fg)">logo</b><span style="color:var(--canvas-muted)">nav · nav · nav</span></div>
@@ -231,8 +299,8 @@ Give each mock a small title above it ("OPTION A — Terminal-first"). Two or th
 // =============================================================================
 export const canvasStylesSkill = defineSkill({
     name: 'canvas-styles',
-    description: 'The visual STYLE CATALOGUE for canvases — six named aesthetics (theme-flat, skeuomorphic, ' +
-        'glassmorphism, brutalist, editorial/print, retro/synthwave) each with a concrete, sandbox-safe, ' +
+    description: 'The visual STYLE CATALOGUE for canvases — seven named aesthetics (theme-flat, skeuomorphic, ' +
+        'glassmorphism, brutalist, editorial/print, retro/synthwave, app-screen) each with a concrete, sandbox-safe, ' +
         'export-safe CSS recipe. Consult when picking or offering a look beyond the default theme-matched flat style.',
     tags: ['visual', 'canvas', 'style', 'aesthetic', 'design'],
     prompt: `The STYLE CATALOGUE for canvases — pick a coherent visual aesthetic instead of defaulting to the flat theme look. Design guidance; author with the canvas tools (see the \`canvas\` skill for mechanics). Applies to **infographic** and **carousel** (a board is a diagram surface — keep it theme-flat unless asked).
@@ -252,8 +320,40 @@ export const canvasStylesSkill = defineSkill({
 
 ### 1. theme-flat  — DEFAULT
 Clean, modern, theme-driven. Reach for it for data, dashboards, and anything "serious/neutral".
-- Font: \`system-ui, -apple-system, "Segoe UI", Roboto, sans-serif\`. Palette: the \`var(--canvas-*)\` tokens as-is.
-- Flat surfaces, thin \`1px var(--canvas-border)\` lines, subtle or no shadow, radius 0–8px, strong type scale, generous whitespace, \`var(--canvas-accent)\` used sparingly.
+
+⚠️ This recipe is LITERAL VALUES, not adjectives. "Generous whitespace" and "used
+sparingly" are what the old entry said, and they produced a canvas that followed every
+instruction and still looked machine-made. Read \`canvas_guide("exemplar-infographic")\`
+for a worked example — it is worth more than everything below.
+
+**Surfaces — three, never two.** Radius **0**, and **no shadows at all**: the ramp is the
+depth.
+- page ground \`var(--canvas-bg)\` · raised card \`var(--canvas-surface-1, var(--canvas-card))\` · inset (tables, code) \`var(--canvas-surface-2, var(--canvas-card))\`
+- hairlines \`1px solid var(--canvas-hairline, var(--canvas-border))\`
+- A card that shares its ground's value is a rectangle of text. If you ever find yourself
+  relying on the border to show where a card is, the ramp is missing.
+
+**Type — one family, \`system-ui, -apple-system, "Segoe UI", Roboto, sans-serif\`.**
+- hero figure **72–88px / 700 / -0.035em** · standfirst **20px / 600** · stat **34px / 700**
+  · body **14px / 1.65** · label **10–11px / 600 / 0.12em / uppercase**
+- \`font-variant-numeric: tabular-nums\` on **every** figure, or columns of numbers jitter.
+
+**Spacing — an 8px scale.** Gaps 16 · card padding 18–32 · outer padding 40.
+
+**Grid — asymmetric tracks**, e.g. \`grid-template-columns: 1.35fr 1fr\`. Equal columns make
+a canvas read as a form.
+
+**Accent — three times maximum**, and they are: one kicker, one delta, one bar. Everything
+else is greys.
+
+**Dominance is geometric.** The hero figure is ~2.5x the next largest type, in a card ~1.35x
+its neighbour. Bolder is not bigger.
+
+**Two derived colours** the token set does not carry, and which get invented badly:
+- body copy \`color-mix(in oklab, var(--canvas-fg) 78%, var(--canvas-bg))\`
+- chart neutral \`color-mix(in oklab, var(--canvas-fg) 22%, var(--canvas-bg))\`
+
+Both work in either polarity, so they need no host support.
 
 ### 2. skeuomorphic  — tactile, physical
 Soft, real-material surfaces — great for device/app-UI mockups and "premium product" one-pagers.
@@ -287,9 +387,49 @@ Hype/launch/gaming/music. Dark base, neon glow, chrome.
 - Neon palette: hot pink \`#ff2bd6\`, cyan \`#22d3ee\`, violet \`#a855f7\`. Glow on headings/borders: \`text-shadow:0 0 8px currentColor,0 0 22px currentColor\` and \`box-shadow:0 0 12px #22d3ee,inset 0 0 12px rgba(34,211,238,.3)\`.
 - Optional perspective grid at the bottom via repeating linear-gradients or an inline SVG. Chrome/gradient text with \`background:linear-gradient(#fff,#8ab4ff);-webkit-background-clip:text;color:transparent\`. (Glow via \`text-shadow\` exports fine.)
 
+### 7. app-screen  — a single UI screen
+A mockup of one screen of an application. Read \`canvas_guide("exemplar-app-screen")\` before
+drawing one.
+
+⚠️ **Route a mockup here, not to \`board\`.** A single screen is one composition, so the
+container is \`infographic\`; \`board\` teaches low-fidelity wireframe boxes for comparing
+options side by side, which is not what anyone means by "mock up the dashboard".
+
+**Four surfaces, in this order** — this is what makes a screen read as an application
+rather than a document:
+- chrome (rail, header) at \`surface-1\` · **the work canvas INSET at \`surface-2\`** ·
+  cards back up to \`surface-1\` on top of it · table headers at \`surface-2\`
+
+**Exactly one active state**, and no hover states drawn at all. A static mock showing three
+highlighted rows reads as a bug. The active row gets a 10% accent tint plus a 2px inset
+accent edge; one filter chip gets the \`--canvas-fg\` border and the rest carry hairlines.
+
+**One primary action, and it is INK, not accent** (\`background: var(--canvas-fg)\`). The
+accent is reserved for the thing that needs attention. Two filled buttons side by side is
+the commonest mock tell; the secondary is a hairline outline.
+
+**State a finding, not a page name.** A real dashboard says "Overview" and stops; a MOCK
+has to argue why the screen is worth building, so the largest text is a claim and the
+accent marks its evidence. "Interviews are keeping pace. Document review is not." — not
+"Admissions Dashboard".
+
+**Numbers must reconcile.** 248 applied → 193 documents in → 152 reviewed → 67 interviewed,
+and the listed programmes account for the 41 waiting. Figures that contradict each other
+are what make a mock feel machine-made, more than any styling choice. If you were not given
+real data, ask for it rather than inventing it.
+
+**Do not draw the OS.** No traffic lights, no browser tab bar, no URL field, no dock. Window
+chrome costs vertical space and dates the mock; the app's own header is the frame. Add it
+only when the point being made is about the window itself.
+
+Icons: use the set in \`canvas_guide("icons")\` — never an emoji, never a guessed path.
+
 ## Pick-by-content cheatsheet
+- **One screen of an app / a UI mockup** → \`infographic\` + **app-screen**. Several options
+  compared side by side → \`board\` + wireframe. (Asking for "a mockup" used to route to one
+  of three types, none of which was right.)
 - **Data / stats / dashboard / neutral** → theme-flat (or glass for a hero moment)
-- **App / device / product-UI showcase** → skeuomorphic or glass
+- **A device or product SHOWCASE, not its screen** → skeuomorphic or glass
 - **Manifesto / dev-tool / bold statement** → brutalist
 - **Long-form / essay / report / "serious"** → editorial
 - **Launch / hype / gaming / music / 80s** → retro

package/dist/skills/platform-skills.d.ts

@@ -12,6 +12,8 @@ export { brandSetupSkill, contentStrategySkill, contentCalendarSkill, createCont
 export { curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, } from './course-skills.js';
 export { bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './book-skills.js';
 export { canvasSkill, infographicSkill, carouselSkill, boardSkill, canvasStylesSkill, } from './canvas-skills.js';
+export { canvasExemplarInfographicSkill, canvasExemplarAppScreenSkill, } from './canvas-exemplars.js';
+export { canvasIconsSkill } from './canvas-icons.js';
 /**
  * All platform-specific skills (38 total).
  */

package/dist/skills/platform-skills.js

@@ -18,6 +18,9 @@ export { curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseRe
 export { bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './book-skills.js';
 // Canvas (visual)
 export { canvasSkill, infographicSkill, carouselSkill, boardSkill, canvasStylesSkill, } from './canvas-skills.js';
+// Canvas exemplars — generated from the design handoff; see canvas-exemplars.ts.
+export { canvasExemplarInfographicSkill, canvasExemplarAppScreenSkill, } from './canvas-exemplars.js';
+export { canvasIconsSkill } from './canvas-icons.js';
 // Import all for the aggregate array
 import { designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, } from './software-skills.js';
 import { outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, } from './research-skills.js';
@@ -26,6 +29,8 @@ import { brandSetupSkill, contentStrategySkill, contentCalendarSkill, createCont
 import { curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, } from './course-skills.js';
 import { bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './book-skills.js';
 import { canvasSkill, infographicSkill, carouselSkill, boardSkill, canvasStylesSkill, } from './canvas-skills.js';
+import { canvasExemplarInfographicSkill, canvasExemplarAppScreenSkill, } from './canvas-exemplars.js';
+import { canvasIconsSkill } from './canvas-icons.js';
 /**
  * All platform-specific skills (38 total).
  */
@@ -76,4 +81,7 @@ export const platformSkills = [
     carouselSkill,
     boardSkill,
     canvasStylesSkill,
+    canvasExemplarInfographicSkill,
+    canvasExemplarAppScreenSkill,
+    canvasIconsSkill,
 ];

package/dist/team/tool-config.js

@@ -296,6 +296,7 @@ export const TOOL_GROUPS = {
             'canvas_delete',
             'canvas_validate',
             'canvas_screenshot',
+            'canvas_guide',
         ],
         readOnly: false,
         tier: 'meta',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.18.9",
+  "version": "0.18.11",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",