diagram

# /diagram — prompt → diagram in the Tidal Diagrams app Turn the user's description into a **quick-text** diagram, encode it into a deep-link, and print the link. When the user opens it, the running app loads the diagram (decoded by `src/diagram/urlLoad.ts`, laid out fresh via the same path as Mermaid import). ## Steps 1. **Author quick-text** from the user's prompt using the syntax below. Aim for a clear, well-grouped diagram — pick a sensible `direction`, give nodes real labels, use shapes (`#db`, `#pill`) and groups where they add meaning. 2. **Build the link** by piping the quick-text into the encoder script. Give it a short title: ```bash # The encoder is bundled with this skill. Pick the path that exists: # • installed as a plugin → "$CLAUDE_PLUGIN_ROOT/scripts/diagram-link.mjs" # • working inside the tidal-diagrams repo → scripts/diagram-link.mjs ENC="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/}scripts/diagram-link.mjs" printf '%s' "$QUICKTEXT" | node "$ENC" --title "Checkout flow" ``` - **Target host** is resolved automatically: installed as a plugin it points at the hosted app (`https://tidal-diagrams.vercel.app`) — so the user just opens the link, nothing to run locally. Working in this repo it points at `http://localhost:5173` (pass `--port <n>` / `$TIDAL_PORT` if the dev server moved; start it with `npm run dev` if it isn't up). Override either with `--host <url>` or `$TIDAL_HOST`. - **Direction**: prefer a `direction LR` line in the quick-text. The `--direction LR|TB|RL|BT` flag is a convenience override for the whole diagram. - **Aspect / dimensions**: pass `--aspect 4:3` (also `16:9`, `1.5`) to bias the layout so the content bounding box approximates that ratio. This is *best-effort* — dagre never wraps ranks, so a long linear chain keeps its shape; branching diagrams respond well. If the user wants a specific ratio, prefer a `direction` that suits it (wide ratios → `LR`, tall → `TB`) and add branching where natural. 3. **Show the result**: print the quick-text in a code block (so the user can read/tweak it) followed by the link on its own line, e.g. `Open: <url>`. The link is long — that's expected. If the app is already open in the browser, opening the link in that same tab swaps in the new diagram live (the app also listens for `hashchange`). ## Quick-text syntax (cheat-sheet) ``` direction LR # flow direction: LR | TB | RL | BT (also right/down/left/up) Node Label # a card (default shape) Service / detail line # two-line card: title / mono subtitle Database #db # cylinder shape Gateway #pill # pill shape Cache #outline # surface: #solid | #outline | #ghost Queue @q # explicit id with @id (so edges can reference it) Group Name: # group header; indent the lines under it to nest Worker A Worker B A -> B # arrow A --> B is the same A ..> B # dotted arrow A <-> B # bidirectional A <..> B bidirectional dotted A -- B # plain line, no arrow A -> |label| B # labelled edge (also A ..> |retries| B) A, B -> C, D # fan-out: every left node connects to every right node // a comment line ``` Notes: - Reference a node in an edge by its label text (its id is the slugged title) or by an explicit `@id`. - Quote a label to keep punctuation literal: `"Auth (OAuth2)"`. - Keep it to flowchart-style nodes/edges/groups. Sequence diagrams use a different syntax and are imported separately, not via this command. ## Example Prompt: *"a checkout flow with payment retries"* Quick-text: ``` direction LR Cart #pill Checkout Payment / Stripe #db Order Service Cart -> Checkout Checkout -> |charge| Payment Payment ..> |retry| Checkout Checkout -> |on success| Order Service ``` Then run the encoder with `--title "Checkout flow"` and share the printed URL. > Label placement matters: the label goes **right after the operator** — > `A -> |label| B`, not `A -> B |label|`. The latter folds the label into B's name.