show

# show Create a visual artifact as a **raw, self-contained SVG file** and stream it to the show viewer pane. ## Workflow Do NOT open the viewer pane before the artifact is ready. The pane opens as the last step, landing directly on the new artifact — never on an old one while you work. 1. **Read the canvas budget** (published by the viewer; the file persists between sessions): ```bash cat ~/.show/viewport # {"cols":94,"rows":51,"cell_w_px":20,"cell_h_px":40,"width_px":1880,"height_px":2040} ``` `width_px` × `height_px` is your drawing area. If the file is missing (viewer has never run), assume 900×1300 portrait. 2. **Design the SVG to that budget** (rules below) and write it to disk. Any path works — prefer the project, e.g. `./diagrams/<slug>.svg`. 3. **Publish it** — append to the queue *first*, then open/focus the viewer: ```bash echo "/absolute/path/to/artifact.svg" >> ~/.show/queue herdr plugin action invoke show.show ``` The viewer always displays the newest queue entry, so it opens straight onto your artifact. If it was already open, the queue append alone re-renders it instantly. ## Design rules **Canvas.** - Set `viewBox="0 0 W H"` with `W = width_px`, so 1 SVG unit renders as ≈1 real pixel — all the size numbers below then mean what they say. - Keep `H ≤ height_px` for a pixel-perfect fit. Exceeding it triggers uniform downscaling; never exceed ~1.4× or text becomes unreadable. - 24-unit safe margin on every side; nothing touches the edge. - **Transparent background** — no full-canvas `<rect>`, no page/paper backdrop. The artifact composites directly onto a dark terminal; a white canvas looks like a hideous pasted document. **Layout — SVG has no layout engine, so do the arithmetic before writing markup.** - Plan every coordinate first: panel at x=80 with width 360 means its right edge is 440, so the next column starts at ~468. Catch collisions in this arithmetic pass, not by eyeballing. - Budget text width numerically: ≈ 0.6 × font-size per character (0.62 for monospace). An 18px label of 22 chars is ~240 units wide — check it fits before placing it. If a label doesn't fit, **shorten the label**; never shrink the font or let it overflow. - Grid rhythm: fixed row pitch (34–40 units), consistent 16-unit padding, one alignment column per element type. - Use `dominant-baseline="central"` so text sits vertically centered in rows and pills. - No overlapping text, ever. Annotations live in clear space and point with short leader lines — they never sit on top of content. **Style.** - Light-on-dark: light text and strokes (e.g. `#cdd6f4`, `#a6adc8`), 2–3 accent colors maximum, **one meaning per color** (e.g. blue = component, yellow = data flow, green = external). - Exactly three text sizes: heading ~26, body ~17, secondary ~13. Body text never below 15 units. - Local panels (node boxes, cards) are encouraged — rounded rects with strokes or subtle dark fills, scoped to their content, not the canvas. **Scope.** - **Use the full canvas.** The artifact renders at pane-filling size — design like it owns the space. If the content is sparse, scale the composition up (larger nodes, roomier spacing, bigger type) rather than leaving most of a tall pane empty. - Degradation is asymmetric: too tall → uniform downscale → unreadable text (never do this); shorter than the budget → just empty space below (acceptable). When unsure, err short, never tall. - Don't cram. The pane is usually tall and narrow — favor vertical stacking over wide sprawl. - If the topic needs more than one screenful, emit **multiple focused artifacts** (append several paths to the queue) — the viewer is a stream with `n`/`p` navigation. One artifact = one idea. ## Notes - SVG only. Do not generate HTML or raster images for this flow. - Self-contained only: inline styles, no external images/fonts/scripts. - Always append an **absolute** path to the queue. - If a later request refines the same diagram, write a new file (or overwrite and re-append) — each queue line is one entry in the visual stream. - If `herdr` is not available (not inside a herdr session), skip the publish steps and just tell the user where the SVG was saved.