svamp-cli 0.2.56 → 0.2.58

package/bin/skills/artifact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artifact
-version: 1.0.0
+version: 1.2.0
 description: Embed a rendered HTML file or live URL inline in chat via a single self-closing `<artifact src="..." />` tag — the Svamp client renders it as a sandboxed iframe with modes for inline, card, bare, and immersive.
 tags:
   - svamp
@@ -23,24 +23,28 @@ The client reads the file, inlines relative refs (`./image.png` etc.) as data UR
 
 ## Strategy: which mechanism?
 
-Three options, pick the lightest that works:
+Four options, pick the lightest that works:
 
 | Mechanism | When |
 |---|---|
-| **Inline `<artifact src="./viz.html" />`** | Self-contained visualization. Cards, charts, animations, prototypes. Files live on disk; the chat marker is tiny. |
-| **URL `<artifact src="https://my-app.example.com/" height="540" />`** | Embed a live server you're running, or any external site. Like a Canvas panel inline. |
-| **Standalone server (`svamp serve` / `svamp service expose`)** | Real apps with backend, database, multi-user state. Post the URL as a normal markdown link. |
+| **Inline body** `<artifact title="…">…html…</artifact>` | Tiny self-contained widgets: a styled metric card, an SVG diagram, a small Chart.js plot. No file needed; the HTML lives in the chat message. Keep under ~10 KB. |
+| **File `<artifact src="./viz.html" />`** | Substantial visualization (dashboards, 3D scenes, multi-section explorers). Persists on disk, supports relative-ref inlining for `./image.png`, can be `svamp serve`-shared as a stable URL, iterates cleanly via singleton dedupe. |
+| **URL `<artifact src="https://my-app.example.com/" height="540" />`** | Embed a live server you're running, or any external site. Canvas-panel-style. |
+| **Standalone server (`svamp serve` / `svamp service expose`)** | Real apps with backend, database, multi-user state. Post the URL as a normal markdown link, no artifact tag needed. |
 
 **Decision tree:**
 1. Need a backend / database / persistent state? → standalone server.
-2. Iterating on a single artifact (HTML file, dashboard, dataviz)? → write to file, emit `<artifact src="..." />`.
-3. Want to embed a running server inline (preview a dev server, show a deployed app)? → URL src.
+2. ~10 KB or less, throwaway widget? → **inline body** (`<artifact>...html...</artifact>`).
+3. Will you iterate on it across messages? → **file** (write file, emit `<artifact src="..." />`).
+4. Embed a running server or external site? → **URL src**.
+
+While the agent is still emitting the body content (closing `</artifact>` not yet received), the client shows a "Generating… N chars" placeholder. The iframe only mounts once the close tag arrives — no flashing of half-rendered HTML.
 
 ## Attributes
 
 ```html
 <artifact
-    src="./outputs/viz.html"     <!-- REQUIRED: relative file path or absolute URL -->
+    src="./outputs/viz.html"     <!-- file path OR absolute URL; OR omit and use inline body -->
     title="Dashboard"            <!-- header label -->
     height="540"                 <!-- fixed pixel height (10..4000); default = auto-size for files -->
     wide                         <!-- extend beyond bubble width -->
@@ -50,7 +54,7 @@ Three options, pick the lightest that works:
 />
 ```
 
-Only `src` is required.
+Either `src` or an inline body is required. All other attributes optional.
 
 ### Modes
 
@@ -75,6 +79,28 @@ In `default` and `bare` modes, the user gets a header (or hover bar) with three
 - **Fullscreen** (⛶) — toggles iframe fullscreen. Hidden automatically on browsers that don't support it (some mobile WebViews).
 - **⋮ menu** — *Open in new window* (standalone tab), *Reload* (same as the icon), *Show as card* (only when the agent originally emitted `mode="card"` and the user expanded it).
 
+## Going inline (no file)
+
+For widgets that don't deserve a file — a metric card, a small SVG diagram, a single Chart.js plot — omit `src` and put the HTML directly inside the tag:
+
+```
+<artifact title="Quarterly revenue">
+<div style="font-family:system-ui;padding:16px;background:var(--svamp-surface);border-radius:8px;color:var(--svamp-text)">
+  <div style="font-size:11px;color:var(--svamp-text-secondary);text-transform:uppercase;letter-spacing:0.05em">Q4 revenue</div>
+  <div style="font-size:28px;font-weight:600;margin-top:4px">$4.2M</div>
+  <div style="font-size:12px;color:#059669;margin-top:2px">↑ 18% vs Q3</div>
+</div>
+</artifact>
+```
+
+Inline body works exactly like file content — same sandbox, same theme bridge, same CSP, same auto-resize, same modes. Differences:
+
+- **No relative file refs.** Inline body has no associated directory, so `<img src="./local.png">` won't resolve. If you need files, use `src=`.
+- **Bloats chat history.** Inline content lives in the message JSONL, so every replay/sync sends it. Keep under ~10 KB. For anything substantial, write to a file.
+- **No `svamp serve`-style stable URL.** Inline blobs are ephemeral. Use `src=` to a file if you want shareable URLs.
+
+When in doubt: inline for tiny standalone widgets, file for anything you might iterate on or share.
+
 ## Writing the file
 
 Use the standard Write tool. Two storage conventions:
@@ -190,16 +216,153 @@ if (req.method === 'OPTIONS') return res.end();
 
 If the iframe console shows `CORS error`, your server is missing one of these headers.
 
-## Style philosophy
+## Style & design system
+
+These are **recommendations, not rules**. They produce coherent, polished output by default; deviate when the content calls for it (artistic visualizations, branded posters, deliberately moody experiences).
+
+### Philosophy
+
+- **Seamless** — the artifact should feel like it belongs in the chat, not a foreign embed. Use `var(--svamp-bg)` / `var(--svamp-text)` so the visual flips with the host theme.
+- **Flat** — solid fills only by default. Skip gradients, shadows, glow, neon unless the content explicitly calls for them. Use **borders OR shadows, not both**.
+- **Warm minimal** — clean geometric layouts with soft rounded corners (8–12 px). Indigo or sky as primary accent. Slate / zinc / stone for structural neutrals.
+- **Diverse** — pick the visualization type that fits the content: flowchart, timeline, hierarchy, cycle, comparison, chart, calculator. Don't default to one.
+- **Text outside, visuals inside** — prose explanation goes in markdown *around* the artifact, not inside it.
+
+### Typography
+
+- Base 14–16 px, line-height ~1.5, system-ui font stack (`system-ui, -apple-system, "Segoe UI", Roboto, sans-serif`).
+- Font weights **400 / 500 / 600** only. Skip 700+ unless it's deliberately punchy.
+- Sentence case for titles. No ALL CAPS labels unless they're tiny (10–11 px) UI labels with letter-spacing.
+- Never set font-size below 11 px — unreadable on mobile.
+- Round every displayed number (`$4.2M`, not `$4218354.97`).
+
+### Spacing
+
+Use a 4-px rhythm: 4 / 8 / 12 / 16 / 24 / 32 / 48 px. Pick one scale and stick to it — sloppy spacing reads as noise even when individual elements look fine.
+
+### Color palette (when you need accents)
+
+A handy ramp library — five shades per ramp. Use 2–3 ramps per artifact max. Indigo / sky for the primary accent, slate / zinc as structural neutrals.
+
+| Ramp | 50 (fill) | 200 (stroke) | 400 (accent) | 600 (subtitle) | 800 (title) |
+|------|-----------|-------------|-------------|----------------|-------------|
+| Indigo | `#EEF2FF` | `#C7D2FE` | `#818CF8` | `#4F46E5` | `#3730A3` |
+| Sky | `#F0F9FF` | `#BAE6FD` | `#38BDF8` | `#0284C7` | `#075985` |
+| Emerald | `#ECFDF5` | `#A7F3D0` | `#34D399` | `#059669` | `#065F46` |
+| Amber | `#FFFBEB` | `#FDE68A` | `#FBBF24` | `#D97706` | `#92400E` |
+| Rose | `#FFF1F2` | `#FECDD3` | `#FB7185` | `#E11D48` | `#9F1239` |
+| Slate | `#F8FAFC` | `#E2E8F0` | `#94A3B8` | `#64748B` | `#334155` |
+
+- Text on a 50-fill: use 800 from the same ramp. Never pure black.
+- SVG defaults: 50 fill + 200 stroke + 800 title + 600 subtitle.
+- Chart.js: 400 for `borderColor`, 400 with 0.1 alpha for `backgroundColor`.
+
+For inline widgets, you can still reference `var(--svamp-accent)` etc. and skip the ramps — both approaches are fine.
+
+### Animation
+
+Animation should *convey* state change, not decorate. Entry animations: 200–400 ms ease-out, stagger child elements by 60–100 ms. Anything longer feels slow.
+
+### Streaming-friendly write order
+
+If you're emitting an inline artifact body that the agent generates token-by-token (the user will see streaming progress in the placeholder, but if they ever see partial HTML rendered, this order minimizes flashing):
+
+- **SVG**: open `<svg>`, emit `<defs>` (markers, gradients) first, then visual elements top-to-bottom.
+- **HTML**: `<style>` block first, then content, then `<script>` last. Solid fills work even mid-stream; gradients can flash during DOM diffs.
+
+### Mobile-first
+
+Single column by default. Widen at media queries (`@media (min-width: 768px)`) only when there's information that benefits from columns. Test by mentally resizing to 320 px wide.
+
+## Chart.js patterns
+
+Chart.js is the go-to for data viz. Recommended setup:
+
+```html
+<div style="position:relative;width:100%;height:300px">
+  <canvas id="c"></canvas>
+</div>
+<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+<script>
+  const chart = new Chart(document.getElementById('c'), {
+    type: 'line',
+    data: {
+      labels: ['Jan','Feb','Mar','Apr','May'],
+      datasets: [{
+        data: [30, 45, 28, 50, 42],
+        borderColor: '#818CF8',
+        backgroundColor: 'rgba(129,140,248,0.1)',
+        fill: true,
+        tension: 0.3,
+      }],
+    },
+    options: {
+      responsive: true,
+      maintainAspectRatio: false,
+      plugins: { legend: { display: false } },
+      scales: {
+        y: { grid: { color: 'rgba(0,0,0,0.06)' } },
+        x: { grid: { display: false } },
+      },
+    },
+  });
+</script>
+```
+
+Rules of thumb:
+- Wrapper `<div>` owns the height (Chart.js can't size to a parent that has `auto` height). `width: 100%; height: <N>px`.
+- `responsive: true` + `maintainAspectRatio: false` so the canvas fills the wrapper.
+- Hide the legend by default (`legend: { display: false }`) — adds noise more often than information. Show it only when there are 2+ datasets.
+- Bars: `borderRadius: 6`. Lines: `tension: 0.3` for smooth, `0` for stepped.
+- Multiple charts on one artifact: unique `canvas` IDs.
+- Interactive controls **must** call `chart.update()` after mutating `chart.data`.
+
+```js
+function refresh() {
+  const v = +document.getElementById('slider').value;
+  chart.data.datasets[0].data = base.map(d => Math.round(d * v / 50));
+  chart.update();
+}
+```
+
+## SVG patterns
+
+For flowcharts, timelines, hierarchy diagrams, comparisons:
+
+```html
+<svg width="100%" viewBox="0 0 680 H" style="display:block">
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
+            markerWidth="6" markerHeight="6" orient="auto">
+      <path d="M0,0 L10,5 L0,10 z" fill="#94A3B8"/>
+    </marker>
+  </defs>
+  <!-- nodes & connectors here -->
+</svg>
+```
+
+ViewBox sizing:
+- Fix width at **680** for a comfortable column. Adjust `H` to fit content + 40 px bottom buffer.
+- Keep all content within `x = 0..680`. `text-anchor="end"` extends left from the x coord.
+- `width="100%"` on the `<svg>` element so it scales to bubble width on mobile.
+
+Recommended defaults for diagram shapes:
+- Node fill: ramp **50** (light), stroke: ramp **200**, stroke-width 1 or 1.5.
+- Node title text: ramp **800**, weight 500, size 14 px.
+- Node subtitle: ramp **600**, weight 400, size 11–12 px.
+- Connector lines: `#94A3B8` (slate-400) with an arrow marker.
+
+## Common UI patterns
 
-Lean on what HTML does well — flow layout, typography, animation — without overengineering.
+A short catalog. Pick the one that fits, don't force a single template.
 
-- **Restrained palette.** 1–2 accent colors, lots of neutrals. Slate / zinc / stone ramps work well.
-- **Type first.** 14–16px base, 1.5 line-height, system-ui font.
-- **Spacing rhythm.** 4 / 8 / 12 / 16 / 24 / 32 / 48 (Tailwind's scale).
-- **Borders or shadows, not both.**
-- **Animation conveys, not decorates.** 200–400 ms ease-out on entry; longer is noise.
-- **Mobile-first.** Single column by default; widen at `md:` only when columns add information.
+- **Metric dashboard** — grid of small stat cards (label / number / delta). 4-col on desktop, 2-col on tablet, 1-col on mobile. See the "Quarterly metrics" template below.
+- **Comparison** — side-by-side panels, the recommended option bordered in the accent color with a small label badge.
+- **Calculator** — labeled `<input type="range">` sliders + live result display. Slider inputs must call `chart.update()` (or update the DOM directly) on every `input` event.
+- **Timeline** — vertical or horizontal sequence with dates, dots, and connector lines.
+- **Flowchart** — boxes + arrows in SVG; arrow markers via `<defs>`. Use a `viewBox` for crisp scaling.
+- **Bar comparison** — horizontal bars with labels left, value right, bar fills indigo-200, value text indigo-800.
+- **Toggle / select** — segmented buttons or a `<select>` to flip between dataset views.
 
 ## Templates
 

package/dist/cli.mjs

@@ -314,7 +314,7 @@ async function main() {
   } else if (!subcommand || subcommand === "start") {
     await handleInteractiveCommand();
   } else if (subcommand === "--version" || subcommand === "-v") {
-    const pkg = await import('./package-DUYA_zrl.mjs').catch(() => ({ default: { version: "unknown" } }));
+    const pkg = await import('./package-GG73qTsa.mjs').catch(() => ({ default: { version: "unknown" } }));
     console.log(`svamp version: ${pkg.default.version}`);
   } else {
     console.error(`Unknown command: ${subcommand}`);

package/dist/{package-DUYA_zrl.mjs → package-GG73qTsa.mjs}

@@ -1,5 +1,5 @@
 var name = "svamp-cli";
-var version = "0.2.56";
+var version = "0.2.58";
 var description = "Svamp CLI — AI workspace daemon on Hypha Cloud";
 var author = "Amun AI AB";
 var license = "SEE LICENSE IN LICENSE";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svamp-cli",
-  "version": "0.2.56",
+  "version": "0.2.58",
   "description": "Svamp CLI — AI workspace daemon on Hypha Cloud",
   "author": "Amun AI AB",
   "license": "SEE LICENSE IN LICENSE",