sketch · diff

git:20261101.c041da3 to git:20261101.56072ba

2 added, 2 removed. Audit A to A.

---

name: sketch

description: Draw one Sketch on the public viewer.

argument-hint: "[picture intent]"

---

# sketch

Write one Sketch source and open it on the public viewer.

Done when the returned short `url` is shown.

## Script Macros

| Macro | CLI |

|---|---|

| `$SKETCH_CTL` | `python3 scripts/sketch_control.py` |

## Source

Three lines. Payloads have no braces.

1. First line is `sketch "<title>"`. The quotes hold the title. Always write a short title that names the diagram.

2. `style`, then one base64 token, is the camera and appearance. On an update, leave that line unchanged. Omit it when minting.

3. `content`, then one base64 token, is the fragment.

## Fragment

The fragment is the picture.

1. Contains `<style>` and markup.

2. Excludes `<!doctype>`, `<html>`, `<head>`, and `<body>`.

3. Excludes `<iframe>`, `<object>`, `<embed>`, and `<link>`. Board removes them before mounting. Put CSS in `<style>`.

## Render Environment

The viewer mounts the fragment in its own document. Write for this environment.

1. The fragment renders in a sandboxed `iframe`. Board's CSS, variables, and fonts do not reach it. Its CSS does not reach Board.

- 2. Board supplies `html` and `body` with zero margin and a transparent background. `:root`, `html`, and `body` selectors act on that document.

+ 2. Board supplies `html` and `body` with zero margin and a transparent background. `:root`, `html`, and `body` selectors act on that document. The runner pads `html` by 12px on every side. That room keeps a shadow, outline, or ring at the picture edge from being cut off. Anything farther than 12px outside the picture is cut. The room is not part of the picture and stays transparent: a background on `body` paints the picture only, and a background on `html` is ignored. To color the picture, set the background on `body` or on the root element.

3. Scripts run when the sketch mounts, inside the sandbox. They cannot reach Board's page, storage, or cookies. `fetch`, `XMLHttpRequest`, and `WebSocket` are blocked. Use a script to build the picture.

4. The frame takes no pointer input. The canvas pans and zooms over it. Buttons, inputs, and links draw as pictures with no hover or click. Scripts get no pointer events, so click handlers and `:hover` do nothing.

5. No network. Put every style, shape, glyph, and script in the fragment.

- 6. The frame matches the picture on both axes, so the camera centers it. Give the root element an explicit width for a stable picture.

+ 6. The picture is the fragment's own size, and the camera centers it on both axes. The frame is the picture plus the 12px room. Give the root element an explicit width for a stable picture. Do not size the root by `100vh` or `100vw`: they follow the frame, so such a root gets no 12px room.

## Performance

The frame is resized by its content and exported as one still image. Write for that.

1. Draw a still picture. Add animation only when the user asks for it.

2. Animate only `transform` and `opacity`. A change in size resizes the frame on every step.

3. Avoid `filter`, `backdrop-filter`, and large blurred shadows. They are slow to paint.

4. Run no endless loop. Keep script work short: the viewer gives up when the sketch does not report a size in time.

5. Keep the element count low.

## Show

1. Pipe the source to `$SKETCH_CTL preview --kind sketch`, or pass `--file`.

2. Show only the CLI stdout `url` and stop.

3. To change, edit the source and preview again. That creates a new short url.

4. To keep, use `#b:`.