@design-twin/dtwin 0.1.3 → 0.1.5

package/README.md

@@ -1,10 +1,32 @@
-# Design Twin — bridge
+<!-- npm renders no <picture> and no repo-relative paths: one absolute PNG, dark ink, made for npm's white page. -->
+<img alt="Design Twin" src="https://raw.githubusercontent.com/its-magdy/design-twin/main/assets/wordmark-light.png" height="56">
 
-**figma-pull (read CLI) + figma-mcp (write MCP).**
+# Design Twin — `dtwin`
 
-Local, loopback-only bridge between Claude Code and the **Design Twin** Figma plugin.
-The plugin's hidden UI iframe is a WebSocket **client**; these processes are the **server**
-(`127.0.0.1:8787`). Nothing touches the internet. See `../ARCHITECTURE.md` for the full design.
+> Figma → code with Claude Code, on the **free** Figma plan. No REST API key, no cloud service in between: the design
+> goes from your Figma app to your coding agent and nowhere else.
+
+`@design-twin/dtwin` is the **`dtwin` CLI** (pulls a design onto disk) and the **MCP server** (the same reads as live
+tools, plus the only write path) of [Design Twin](https://github.com/its-magdy/design-twin). It also ships the Figma
+plugin they talk to. The bridge is local and loopback-only: the plugin's hidden UI iframe is a WebSocket **client**,
+and these processes are the **server** (`127.0.0.1:8787`). Nothing touches the internet. See
+[ARCHITECTURE.md](https://github.com/its-magdy/design-twin/blob/main/ARCHITECTURE.md) for the full design.
+
+**Quick start**, in the project you are building, after the install below:
+
+```
+dtwin init --mcp   # design/, the bridge token, the Figma plugin's copy, a .mcp.json entry
+dtwin plugin path  # import this manifest once: Figma desktop → Plugins → Development → Import plugin from manifest…
+dtwin token show   # paste into the plugin: Connect to Claude Code (optional) → Bridge token → Save
+dtwin doctor       # checks everything and names the next step
+dtwin list         # then: dtwin pull --node <id>
+```
+
+For the Claude Code skills (audit, build, verify, sync), see the
+[project README](https://github.com/its-magdy/design-twin#readme): its
+[first screen in 5 minutes](https://github.com/its-magdy/design-twin#first-screen-in-5-minutes) goes from install
+to a built screen, and [known limitations](https://github.com/its-magdy/design-twin#known-limitations--platform-support)
+covers what it needs (Figma desktop, Bun) and where it runs.
 
 ## Install (once)
 It needs [Bun](https://bun.sh/install) ≥ 1.4.2 (`engines.bun`) on your PATH; Node is not supported. Install Bun
@@ -34,7 +56,7 @@ dependency tree the release was tested with, never a newer one published since.
 Or from a clone (to work on the code):
 ```
 git clone https://github.com/its-magdy/design-twin.git && cd design-twin
-bun install                     # @modelcontextprotocol/sdk (+ zod), for every workspace
+bun install --frozen-lockfile   # @modelcontextprotocol/sdk (+ zod), for every workspace
 cd bridge && bun link           # puts `dtwin` in ~/.bun/bin (on your PATH); nothing to build
 ```
 Or skip the link and run `bun --no-install --no-env-file /path/to/design-twin/bridge/src/figma-pull.ts` wherever
@@ -75,8 +97,9 @@ access control (a sandboxed browser iframe on any site the user visits sends `Or
 could otherwise drive the plugin), so the token is the real gate.
 
 **You do not have to set anything up.** The first time a bridge starts it generates a token, saves it,
-prints it once, and reuses it forever after. Paste it into the plugin's **Bridge token** field (the
-plugin saves it per-user in `clientStorage`) and neither side asks again.
+prints it once, and reuses it forever after. Paste it into the plugin's **Bridge token** field, under the
+window's collapsed **Connect to Claude Code (optional)** section, and press **Save** (the plugin keeps it
+per-user in `clientStorage`); neither side asks again.
 
 ```
 dtwin --token-status    # where it lives, which source wins, its fingerprint — never the token
@@ -234,14 +257,15 @@ the path; on Windows paste it into the File name box. `dtwin init` installs (or
 step. Install writes only the files that differ, each one atomically, under a lock, and is safe to run any number of times.
 
 **Updates need no command.** Once a copy is installed, every `dtwin` that starts a bridge (a command, `dtwin serve`, the
-MCP server) first brings it up to its own package's files, so after `bun add -g @design-twin/dtwin@latest` you only
+MCP server) first brings it up to its own package's files, so after `bun add -g @design-twin/dtwin@latest` (or
+`brew upgrade dtwin`) you only
 reopen the plugin — with Plugins → Development → **Hot reload plugin** on. With it on, reopening runs the replaced
 `code.js` / `ui.html` and picks up a changed manifest's permissions too (seen in Figma desktop 126); with it off, Figma
 kept running the code it had already loaded. An update whose manifest changed says so, with re-importing as the
 fallback if a new permission still does not work. Nothing is created that you did not
 install, the network is never touched, and a `dtwin` running from a **repo checkout** never refreshes the copy —
 developers import `figma-plugin/manifest.json` from the checkout itself (`dtwin plugin path` prints that one there).
-`dtwin doctor` reports the copy as its "Plugin files" line.
+`dtwin doctor` reports the copy as its "Plugin files" check.
 
 ## Seed the component map from Code Connect: `dtwin seed`
 
@@ -289,7 +313,9 @@ open file is seen), then each file's `hello` (so it is named).
    bridge (almost always the MCP server), or held by something unrelated.
 5. **Figma plugin** — can it actually connect? If a plugin is running with a *different* token, doctor
    says so with both fingerprints, instead of the "nothing connected" that case otherwise looks like.
-6. **Project** (the current directory) — `design/`, `design/target.json` and the profile build-screen will use
+6. **Plugin files** — the per-user plugin copy `dtwin plugin` manages: installed or not, where, and whether it
+   matches this dtwin.
+7. **Project** (the current directory) — `design/`, `design/target.json` and the profile build-screen will use
    (bundled or custom, plus the project's own `design/profile.md` when it exists), which export LAYOUT it
    found, the age of the last export (its newest stamp; stale past 24h), **which Figma files that export mixes**, the component map
    (`design/codeconnect.local.json`, or the older repo-root location), and the `.mcp.json`
@@ -840,7 +866,7 @@ Behaviour worth knowing:
 while you are working *on* the bridge. Register it in the project you are *building*: a `.mcp.json`
 there that runs `bridge/src/figma-mcp.ts` on Bun — `"command"`: the absolute path of `bun`, `"args"`:
 `["--no-install", "--no-env-file", "<abs path>/bridge/src/figma-mcp.ts"]` — under the key `designtwin` (`dtwin init --mcp`
-writes exactly that, with the `bun` and the clone that ran it; an absolute `bun` keeps working when Claude Code is
+writes exactly that, with the `bun` and the install — package or clone — that ran it; an absolute `bun` keeps working when Claude Code is
 started without `~/.bun/bin` on its PATH). Claude Code then launches it over stdio, and its tools surface as
 `mcp__designtwin__<tool>` (e.g. `mcp__designtwin__figma_status`).
 No token needs to go in that `.mcp.json`: the MCP server reads the same per-user stored token the CLI

package/figma-plugin/code.js

@@ -4069,7 +4069,7 @@
             // freshly reloaded one, since neither startedAt nor code.js's mtime can. Reused verbatim by
             // the `hello` announcement below (main.ts's get-identity -> ui.html -> bridge), so `whoami`,
             // `dtwin list clients` and `dtwin doctor` can never disagree about which build is running.
-            pluginVersion: "0.1.3",
+            pluginVersion: "0.1.5",
             fileKey: fileKey === void 0 ? null : fileKey,
             fileKeyAvailable: typeof fileKey === "string" && fileKey.length > 0,
             // So figma_write's dry run can say a real write would be refused before anyone sends one.

package/figma-plugin/ui.html

@@ -68,11 +68,17 @@
                  background: var(--figma-color-bg-secondary, #f6f6f6); color: var(--figma-color-text-tertiary, #888); }
   #edits-state.on { background: var(--figma-color-bg-warning-tertiary, #fff4e0); color: var(--figma-color-text-warning, #8a5a00); }
   #cancel { border-color: var(--figma-color-border-danger-strong, #c0362c); color: var(--figma-color-text-danger, #c0362c); }
+  /* Bo, the brand mark (assets/logo-16.svg), in front of the status line: it "says" the status. It sits in the
+     line's own height, so no control moves and the window keeps its size. The frame and eyes are currentColor
+     (they follow Figma's theme); the four handles stay brand magenta. */
+  #head { display: flex; align-items: flex-start; gap: 8px; margin-bottom: 12px; }
+  #head svg { flex: 0 0 auto; margin-top: 1px; }
+  #head #status { flex: 1; margin-bottom: 0; }
 </style>
 
 <!-- role=status / role=alert: a screen-reader user otherwise never hears that a long export finished
      or that a download batch failed. -->
-<div id="status" role="status" aria-live="polite">Loading…</div>
+<div id="head"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" shape-rendering="crispEdges" aria-hidden="true"><rect x="3.5" y="3.5" width="9" height="9" stroke="currentColor"/><g fill="#d6409f"><rect x="2" y="2" width="3" height="3"/><rect x="11" y="2" width="3" height="3"/><rect x="2" y="11" width="3" height="3"/><rect x="11" y="11" width="3" height="3"/></g><g fill="currentColor"><rect x="5" y="6" width="2" height="3"/><rect x="9" y="6" width="2" height="3"/></g></svg><div id="status" role="status" aria-live="polite">Loading…</div></div>
 <div id="banner" role="alert" hidden></div>
 <div id="progress" hidden><div id="bar"></div></div>
 
@@ -90,7 +96,7 @@
 <button id="layers" disabled>Download layers (<span id="lcount">0</span>)</button>
 <button id="assets" disabled>Download assets (<span id="acount">0</span>)</button>
 
-<div class="hint">Save the downloads into your project's <code>design/</code> folder (assets into <code>design/assets/</code>).</div>
+<div class="hint">Save the downloads into your project's <code>design/export/</code> folder (assets into <code>design/export/assets/</code>).</div>
 
 <div class="sep"></div>
 <div class="label">Edits</div>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@design-twin/dtwin",
-  "version": "0.1.3",
-  "description": "Design Twin bridge: local CLI + MCP server between Claude Code and the Design Twin Figma plugin. Reads a design on the free Figma plan, fully offline.",
+  "version": "0.1.5",
+  "description": "Figma → code with Claude Code: the dtwin CLI + MCP server (and the Figma plugin) that read a design on the free Figma plan into your project. No REST API key, no cloud service in between.",
   "license": "MIT",
   "author": "Mohamed Magdy Omar",
   "repository": {
@@ -9,17 +9,21 @@
     "url": "git+https://github.com/its-magdy/design-twin.git",
     "directory": "bridge"
   },
-  "homepage": "https://github.com/its-magdy/design-twin/tree/main/bridge#readme",
+  "homepage": "https://github.com/its-magdy/design-twin#readme",
   "bugs": "https://github.com/its-magdy/design-twin/issues",
   "keywords": [
     "figma",
-    "mcp",
-    "model-context-protocol",
+    "figma-plugin",
+    "figma-to-code",
     "design-to-code",
     "design-system",
     "design-tokens",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
     "claude-code",
-    "figma-plugin",
+    "bun",
     "cli"
   ],
   "type": "module",
@@ -42,7 +46,7 @@
     "prepack": "bun --no-install --no-env-file pack.ts",
     "postpack": "bun --no-install --no-env-file pack.ts --clean",
     "pull": "bun src/figma-pull.ts",
-    "pull:selection": "bun src/figma-pull.ts design --selection",
+    "pull:selection": "bun src/figma-pull.ts --selection",
     "mcp": "bun src/figma-mcp.ts"
   },
   "dependencies": {

package/src/cli-commands.ts

@@ -280,9 +280,11 @@ export const MCP_HELP =
   "  (`dtwin init --mcp` writes one); you do not normally run it by hand.\n\n" +
   "  It takes no flags. While it runs it owns the bridge, so ordinary `dtwin` commands\n" +
   "  route through it rather than starting a second one — `dtwin doctor` says who holds the port.\n\n" +
-  "  Its tools mirror the CLI: figma_list_clients / figma_list / figma_export_* / figma_screenshot /\n" +
-  "  figma_status / figma_write. Pass writeToDisk:true to get files plus a compact index instead\n" +
-  "  of node payloads inline — asset bytes are never returned inline.";
+  "  Its tools mirror the CLI: figma_status / figma_whoami / figma_list_clients / figma_list_pages /\n" +
+  "  figma_list_children / figma_list_libraries / figma_get_selection / figma_screenshot / figma_export_*,\n" +
+  "  plus figma_write (refused until the designer ticks \"Allow edits\" in the plugin) and two that read\n" +
+  "  the export on disk: design_get_component / design_drift_lint. Pass writeToDisk:true to get\n" +
+  "  files plus a compact index instead of node payloads inline — asset bytes are never returned inline.";
 
 // Row order is the order of `dtwin --help`'s command summary.
 export const VERB_ROWS = [
@@ -407,7 +409,7 @@ export const VERB_ROWS = [
   { word: "doctor", to: "routed", usage: "  dtwin doctor [--wait N] [--json]         # diagnose the setup; changes nothing. See doctor --help" },
   { word: "init", to: "routed", usage: "  dtwin init [--mcp] [--dry-run]           # set up the project you are building. See init --help" },
   { word: "seed", to: "routed", usage: "  dtwin seed [codeRoot] [outDir]           # components.json from your Code Connect files. See seed --help", help: SEED_HELP },
-  { word: "plugin", to: "routed", usage: "  dtwin plugin [install|update|status|path] # the Figma plugin's per-user copy, to import once. See plugin --help" },
+  { word: "plugin", to: "routed", usage: "  dtwin plugin [install|update|status|path|uninstall]  # the Figma plugin's per-user copy, to import once. See plugin --help" },
   { word: "mcp", to: "routed", usage: "  dtwin mcp                                # run the MCP server (what .mcp.json points at). See mcp --help", help: MCP_HELP },
   { word: "help", to: "--help", usage: "  dtwin help                               = --help" },
   {

package/src/figma-pull.ts

@@ -83,6 +83,7 @@ import { ifDefined, isUnknownArray } from "./json-util.ts";
 // too): `dtwin --version` prints its version.
 import pkg from "../package.json" with { type: "json" };
 import { CliExit, exitCli, exitFlushed, runCli } from "./stdio.ts";
+import { spriteAllowed, versionText } from "./mascot.ts";
 
 // --help / -h: print USAGE and exit 0. Handled in cli() BEFORE the settings are read, so help has no
 // side effects at all — no token minted, no port bound. A constant, not text read back from this file
@@ -110,7 +111,7 @@ ${COMMAND_SUMMARY}
 
 Full reference:
   dtwin init [--mcp]          # set up the project you are BUILDING: design/, target.json, the bridge
-                              # token, (optionally) .mcp.json — then prints the steps left. See init --help
+                              # token, the Figma plugin copy, (optionally) .mcp.json — then the steps left. See init --help
   dtwin [outDir]              # full: design-system.json + current-page frames + assets
   dtwin [outDir] --all-pages  # like full, but frame trees from EVERY page
   dtwin [outDir] --selection  # just the current selection
@@ -893,7 +894,9 @@ async function openSession(parsed: ParsedArgs, settings: BridgeSettings): Promis
   // one gets more time once a plugin is connected, and with no target or a file name the fresh bridge
   // settles first (timeouts.ts SETTLE_MS), so a second open file a redial behind is connected — and the
   // command refused as ambiguous, or listed — instead of the first file to land being taken silently.
-  timing.connectMs = (await route.connect(client)).waitedMs;
+  // No plugin in the whole window fails here (route.ts), so no command prints "plugin connected — …" first; the
+  // clients listing alone answers "none".
+  timing.connectMs = (await route.connect(client, { listing: command.id === "listClients" })).waitedMs;
   // Where the time went, for the closing `done in …` line. The connect wait is measured above
   // (own bridge only — a daemon does its waiting inside the request), the export is the time inside
   // every request, the write is every write-out (read-run.ts adds both to `timing`). All measured from
@@ -1205,7 +1208,8 @@ async function cli(argv: string[]): Promise<void> {
     }
   }
   if (argv[0] === "--version" || argv[0] === "-v") {
-    console.log(pkg.version);
+    // On a terminal, Bo (mascot.ts) beside the name; piped, redirected or with --json, the bare version, as scripts expect.
+    console.log(versionText(pkg.version, spriteAllowed(process.stdout.isTTY === true, argv), process.env));
     exitCli(0);
   }
   if (argv.some((a) => a === "--help" || a === "-h")) {

package/src/init.ts

@@ -337,7 +337,7 @@ function plan(cwd: string, { mcp = false, mcpEntry, refuseMcp, probe, token }: P
         const next = { ...doc, mcpServers: { ...servers, [MCP_KEY]: mcpEntry } };
         // merge:true — the ONE write allowed onto an existing file: it re-serialises the user's own
         // document with one key added. Everything else is written with "wx" and cannot clobber.
-        actions.push({ kind: "write", merge: fs.existsSync(file), path: rel(file), content: JSON.stringify(next, null, 2) + "\n", note: `registered the "${MCP_KEY}" MCP server (enable it with /mcp, then restart Claude Code). While it runs it holds port 8787 — use its writeToDisk:true instead of one-shot dtwin pulls` });
+        actions.push({ kind: "write", merge: fs.existsSync(file), path: rel(file), content: JSON.stringify(next, null, 2) + "\n", note: `registered the "${MCP_KEY}" MCP server (restart Claude Code here and approve it when asked; /mcp shows its status). While it runs it holds port 8787 — use its writeToDisk:true instead of one-shot dtwin pulls` });
       }
     }
   }
@@ -362,14 +362,17 @@ function main(argv: string[]): void {
   if (argv.includes("--help") || argv.includes("-h")) {
     console.log(
       "dtwin init [--mcp] [--dry-run]\n\n" +
-      "  Run in the root of the project you are BUILDING. Creates exactly these four things:\n" +
+      "  Run in the root of the project you are BUILDING. In it, creates exactly these four things\n" +
+      "  (plus ./.mcp.json with --mcp):\n" +
       "    design/                  the directory your decisions live under\n" +
       "    design/export/           where every dtwin pull lands, empty at first — safe to delete and re-pull\n" +
       "    design/README.md         which half of design/ a re-pull is allowed to destroy\n" +
       "    design/target.json       the detected stack, or profile:null for build-screen to fill in\n" +
       "  It does NOT create codeconnect.local.json, plan/, audit/ or verify/ — those are written later,\n" +
       "  on demand, by map-bootstrap.ts, build-screen, audit-design and verify respectively.\n" +
-      "  …makes sure a bridge token exists, and prints the remaining steps.\n\n" +
+      "  Outside the project it makes sure a bridge token exists and installs (or refreshes) the Figma\n" +
+      "  plugin's per-user copy (`dtwin plugin install`; a repo checkout imports its own instead), then\n" +
+      "  prints the steps left.\n\n" +
       "  --mcp      also register the Design Twin MCP server in ./.mcp.json (merged, never overwritten;\n" +
       "             an entry of ours that can no longer start — a moved bun or figma-mcp.ts, a Node-era\n" +
       "             entry — is repaired in place, and the output says so)\n" +
@@ -444,10 +447,10 @@ function main(argv: string[]): void {
   const steps = [
     "In Figma DESKTOP, once: Plugins → Development → Import plugin from manifest… → " + (manifest ?? "figma-plugin/manifest.json from a clone of the Design Twin repo (this install does not include it)") +
       (manifest && hiddenHint(manifest) ? ` (${hiddenHint(manifest) ?? ""})` : ""),
-    "Run the plugin (Plugins → Development → Design Twin), paste the bridge token into its \"Bridge token\" field, Save:  dtwin --show-token | pbcopy",
+    "Run the plugin (Plugins → Development → Design Twin), open \"Connect to Claude Code (optional)\", paste the bridge token into \"Bridge token\", Save:  dtwin --show-token | pbcopy",
   ];
   if (!pluginInstalled) {
-    steps.push("In Claude Code, once:  claude plugin marketplace add <path-or-repo of Design Twin>  then  claude plugin install designtwin@designtwin-marketplace");
+    steps.push("In Claude Code, once:  claude plugin marketplace add its-magdy/design-twin  then  claude plugin install designtwin@designtwin-marketplace");
   }
   steps.push(
     "Then, with the Figma file open and the plugin running:  dtwin list   →  /designtwin:extract  →  /designtwin:audit-design <screen>  →  /designtwin:build-screen <screen>"

package/src/mascot.ts

@@ -0,0 +1,107 @@
+// Bo, the Design Twin mark, as a terminal sprite: the same drawing as assets/logo.svg (a hollow selection box,
+// four magenta handles, two eyes), drawn in half-blocks so one text cell holds two pixels stacked.
+//
+// Shown only by `dtwin --version` / `dtwin version` when stdout is a terminal and no --json was asked for. Piped,
+// redirected or with --json, --version prints the bare version string and nothing else, so a script reading it is
+// unaffected. A locale that is set and is not UTF-8 (LANG=C, a Latin-1 locale) also gets the bare version: the
+// half-blocks would print as mojibake there.
+//
+// The grid is drawn so no cell mixes a handle pixel with an ink pixel. The ink is the terminal's own foreground
+// colour (right on light and dark themes), and only the handles get a colour, so a cell never needs two colours.
+// Colour follows the usual conventions: FORCE_COLOR (1/true/empty = 16 colours, 2 = 256, 3 = truecolor, anything else = off) wins, then
+// NO_COLOR (https://no-color.org) and TERM=dumb turn it off; otherwise the depth is read from COLORTERM / TERM. With
+// colour off the handles print in the foreground colour too: just the outline.
+
+// "a" handle (magenta), "k" ink (the terminal's foreground), "." empty. 13 × 12 pixels → 13 × 6 cells.
+export const BO_GRID: readonly string[] = [
+  "aaa.......aaa",
+  "aaakkkkkkkaaa",
+  ".k.........k.",
+  ".k.kk...kk.k.",
+  ".k.kk...kk.k.",
+  ".k.kk...kk.k.",
+  ".k.........k.",
+  ".k.........k.",
+  ".k.........k.",
+  ".k.........k.",
+  "aaakkkkkkkaaa",
+  "aaa.......aaa",
+];
+
+// Brand magenta per colour depth: truecolor #e05aaf (a touch lighter than #d6409f, so it holds up on dark terminals
+// as well as light ones), xterm-256 colour 169 (#d75faf), and bright magenta on a 16-colour terminal.
+export type ColorLevel = 0 | 1 | 2 | 3;
+const HANDLE: Record<Exclude<ColorLevel, 0>, string> = { 3: "\u001b[38;2;224;90;175m", 2: "\u001b[38;5;169m", 1: "\u001b[95m" };
+const RESET = "\u001b[0m";
+type Env = Record<string, string | undefined>;
+
+/** The sprite as lines of text, every line 13 cells wide: ▀ / ▄ / █ per cell, handles coloured at `level` (0 = none).
+ *  Throws on a cell that mixes a handle with ink (it cannot be drawn without picking a background colour). */
+export function boLines(level: ColorLevel): string[] {
+  const handle = level === 0 ? "" : HANDLE[level];
+  const lines: string[] = [];
+  for (let y = 0; y < BO_GRID.length; y += 2) {
+    const top = BO_GRID[y] ?? "";
+    const bottom = BO_GRID[y + 1] ?? "";
+    let line = "";
+    let open = false;
+    for (let x = 0; x < Math.max(top.length, bottom.length); x++) {
+      const t = top[x] ?? ".";
+      const b = bottom[x] ?? ".";
+      const kinds = new Set([t, b].filter((p) => p !== "."));
+      if (kinds.size > 1) throw new Error(`mascot: cell ${x},${y / 2} mixes a handle with ink`);
+      const ch = t !== "." && b !== "." ? "█" : t !== "." ? "▀" : b !== "." ? "▄" : " ";
+      const wantColor = handle !== "" && kinds.has("a");
+      if (wantColor && !open) { line += handle; open = true; }
+      if (!wantColor && open) { line += RESET; open = false; }
+      line += ch;
+    }
+    if (open) line += RESET;
+    lines.push(line);
+  }
+  return lines;
+}
+
+// The depth the terminal says it has, ignoring the on/off switches.
+function detectedLevel(env: Env, platform: string): Exclude<ColorLevel, 0> {
+  const colorterm = (env.COLORTERM ?? "").toLowerCase();
+  if (colorterm === "truecolor" || colorterm === "24bit") return 3;
+  if (platform === "win32" && env.TERM === undefined) return 3; // Windows Terminal and the Windows 10+ console
+  if (/256/.test(env.TERM ?? "") || colorterm !== "") return 2;
+  return 1;
+}
+
+/** How to colour the handles: FORCE_COLOR first, then NO_COLOR / TERM=dumb, then what the terminal reports. */
+export function colorLevel(env: Env, platform: string = process.platform): ColorLevel {
+  const force = env.FORCE_COLOR;
+  if (force !== undefined) {
+    if (force === "0" || force.toLowerCase() === "false") return 0;
+    if (force === "" || force === "1" || force.toLowerCase() === "true") return 1; // as Node and chalk read it
+    if (force === "2") return 2;
+    if (force === "3") return 3;
+    return 0; // any other value: off, as Node reads it
+  }
+  if (env.NO_COLOR) return 0;
+  if (env.TERM === "dumb") return 0;
+  return detectedLevel(env, platform);
+}
+
+/** Whether the half-block glyphs can be printed: false only when a locale is set and is not UTF-8. */
+export function utf8Locale(env: Env, platform: string = process.platform): boolean {
+  if (platform === "win32") return true; // the console decodes Bun's UTF-8 output itself
+  const locale = env.LC_ALL || env.LC_CTYPE || env.LANG;
+  return !locale || /utf-?8/i.test(locale);
+}
+
+/** Whether --version may draw Bo at all: only on an interactive terminal, and never when --json was asked for. */
+export function spriteAllowed(stdoutIsTTY: boolean, argv: readonly string[]): boolean {
+  return stdoutIsTTY && !argv.includes("--json");
+}
+
+/** What `dtwin --version` prints. `tty` false (piped, redirected, or --json) → the bare version; true → Bo beside it. */
+export function versionText(version: string, tty: boolean, env: Env, platform: string = process.platform): string {
+  if (!tty || !utf8Locale(env, platform)) return version;
+  const art = boLines(colorLevel(env, platform));
+  const text = ["", "", `Design Twin ${version}`, "the Figma ↔ code companion", "", ""];
+  return art.map((row, i) => `${row}   ${text[i] ?? ""}`.trimEnd()).join("\n");
+}

package/src/route.ts

@@ -169,8 +169,10 @@ export interface RouteRequest {
 export interface Route {
   /** Spend the connect window (a one-shot route over its own bridge; otherwise nothing to wait for here) —
    *  once: later calls answer the first one's result. Requests and listClients call it themselves; a caller
-   *  calls it first only to time the wait. `target` is what that first wait waits for. */
-  connect(target?: string | null): Promise<{ waitedMs: number }>;
+   *  calls it first only to time the wait. `target` is what that first wait waits for. A window in which no plugin
+   *  ever connected throws the never-connected text here, before the caller says what it is about to do — unless
+   *  `listing` (the clients listing, whose answer is then "none"). */
+  connect(target?: string | null, o?: { listing?: boolean }): Promise<{ waitedMs: number }>;
   request<C extends Cmd>(cmd: C, args: Commands[C]["args"], o?: RouteRequest): Promise<Sent<C>>;
   listClients(): Promise<ClientRow[]>;
   /** The socket half of whoami for `connId` (the connection a request was answered by), and who holds it. */
@@ -206,8 +208,9 @@ export function createRoute(upstream: () => Promise<Upstream>, policy: RoutePoli
   }
 
   return {
-    async connect(target) {
-      const { waitedMs } = await spend(await upstream(), target);
+    async connect(target, { listing = false } = {}) {
+      const { waitedMs, everConnected } = await spend(await upstream(), target);
+      if (everConnected === false && !listing) throw neverConnected(policy.connectWaitMs);
       return { waitedMs };
     },
     async request(cmd, args, o = {}) {