@design-twin/dtwin 0.1.1 → 0.1.2

package/README.md

@@ -14,17 +14,18 @@ the package, `@design-twin/dtwin`, from npm:
 bun add -g @design-twin/dtwin   # puts `dtwin` in ~/.bun/bin (on your PATH via the Bun installer)
 ```
 `npm i -g @design-twin/dtwin` installs the same thing, but `dtwin` still runs on Bun: without Bun on PATH it stops at
-`env: bun: No such file or directory`. The package also carries the built Figma plugin (`figma-plugin/manifest.json`
-inside it — `dtwin init` prints the full path to import) and the design-to-code bundles the MCP server's
-`design_get_component` / `design_drift_lint` load (`layer/`).
+`env: bun: No such file or directory`. The package also carries the built Figma plugin, which `dtwin plugin install`
+(or `dtwin init`) copies to a per-user folder for you to import once — see [The Figma plugin: `dtwin plugin`](#the-figma-plugin-dtwin-plugin) —
+and the design-to-code bundles the MCP server's `design_get_component` / `design_drift_lint` load (`layer/`).
 
 Or with Homebrew (macOS, Linux), which installs Bun for you and keeps both up to date with `brew upgrade`:
 ```
 brew install its-magdy/tap/dtwin
 ```
 The formula installs the same npm package into Homebrew's prefix; every release updates it. Paths `dtwin init` writes
-(the `.mcp.json` server entry, the plugin manifest it prints) are spelt through `$(brew --prefix)/opt/dtwin/…`, which
-survives an upgrade — not the versioned `Cellar/dtwin/<version>/` folder the next `brew upgrade` deletes.
+(the `.mcp.json` server entry) are spelt through `$(brew --prefix)/opt/dtwin/…`, which
+survives an upgrade — not the versioned `Cellar/dtwin/<version>/` folder the next `brew upgrade` deletes. The Figma
+plugin is imported from its per-user copy (`dtwin plugin`), which `brew upgrade` leaves where it is.
 
 Or from a clone (to work on the code):
 ```
@@ -43,11 +44,13 @@ The plugin manifest allows the bridge in **both** dev and published builds
 (`allowedDomains: ws://localhost:{8787,8788,8789}`). Those three ports are the only ones the plugin can dial — `FIGMA_BRIDGE_PORT` is
 validated against them and exits rather than binding a port nothing could ever reach.
 
-> **Re-import the plugin after its manifest changes — required for library reads.** The manifest declares
-> `"permissions": ["teamlibrary"]`, without which Figma denies the team-library APIs. A plugin
-> imported from an older manifest keeps running happily and simply returns **no libraries** — a silent
-> empty result, not an error. If `--list-libraries` / `figma_list_libraries` shows nothing, re-import
-> `figma-plugin/manifest.json` (Plugins → Development → Import plugin from manifest…) first.
+> **Library reads need the manifest's permission.** The manifest declares `"permissions": ["teamlibrary"]`,
+> without which Figma denies the team-library APIs. A plugin still running an older manifest keeps working
+> and simply returns **no libraries** — a silent empty result, not an error. If `--list-libraries` /
+> `figma_list_libraries` shows nothing, turn on Plugins → Development → **Hot reload plugin** and reopen the plugin;
+> if it is still empty, re-import the manifest `dtwin plugin path` prints (Plugins → Development → Import plugin from
+> manifest…). Updates need no re-import: `dtwin plugin update` (or any dtwin that starts a bridge) replaces the files
+> in place, and with hot reload on, reopening the plugin runs them — a changed manifest's permissions included.
 
 **Languages:** the whole bridge is **TypeScript** (ESM) under `src/` — `figma-pull.ts` (read CLI),
 `server-core.ts` (WS core), `figma-mcp.ts` (MCP server), and the modules they share. From a checkout,
@@ -190,7 +193,7 @@ README documents the flags, and either spelling is fine everywhere:
 | `dtwin serve` · `stop` · `status` | `--serve` · `--stop` · `--daemon-status` |
 | `dtwin token` · `token show` · `token rotate` · `token forget` | `--token-status` · `--show-token` · `--rotate-token` · `--forget-token` |
 | `dtwin help` | `--help` |
-| `dtwin doctor` · `dtwin init` · `dtwin mcp` · `dtwin seed` | their own entry points (no flag form) |
+| `dtwin doctor` · `dtwin init` · `dtwin mcp` · `dtwin seed` · `dtwin plugin` | their own entry points (no flag form) |
 
 Every verb has its own page: `dtwin <verb> --help` (e.g. `dtwin whoami --help`, `dtwin serve --help`) prints
 that verb's flags and exits without starting a bridge. `outDir` is **positional** (`dtwin pull my-dir`):
@@ -204,6 +207,38 @@ With no outDir the export lands in `design/export` — the only place doctor, cr
 build-screen read. Never pull into bare `design`: that writes a second, parallel export tree beside
 `design/export/` (dtwin warns when it sees one).
 
+## The Figma plugin: `dtwin plugin`
+
+The plugin is not on Figma Community; it is imported into Figma **desktop** as a development plugin (Plugins →
+Development → Import plugin from manifest…). Figma remembers the manifest's path, so the folder must not move — and a
+path inside the npm package does (Bun's and npm's
+global folders differ, a Node version manager gives each Node its own, a `bunx` cache comes and goes, an uninstall
+deletes it). So the package's plugin is copied to one per-user folder, beside the bridge token, and imported from there
+once:
+
+```
+dtwin plugin install     # copy it to <config dir>/figma-plugin and print the one-time import step (--open shows it)
+dtwin plugin update      # the same, then says to reopen the plugin (and when the manifest changed too)
+dtwin plugin status      # (default) installed where, and is it this dtwin's? (--json)
+dtwin plugin path        # the manifest to import, on stdout
+dtwin plugin uninstall   # remove the copied files (then remove the plugin in Figma: Plugins → Manage plugins)
+```
+
+`<config dir>` is the bridge token's: `~/.config/design-twin` (or `$XDG_CONFIG_HOME/design-twin`), `%APPDATA%\design-twin`
+on Windows, `DESIGNTWIN_CONFIG_DIR` overriding both. The folder is hidden in a file picker: on macOS press ⌘⇧G and paste
+the path; on Windows paste it into the File name box. `dtwin init` installs (or refreshes) the copy and prints the same
+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
+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.
+
 ## Seed the component map from Code Connect: `dtwin seed`
 
 If the project you are building already has Code Connect files, they are the Figma-component →

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.0",
+            pluginVersion: "0.1.2",
             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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-twin/dtwin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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.",
   "license": "MIT",
   "author": "Mohamed Magdy Omar",

package/src/bridge-holder.ts

@@ -30,6 +30,7 @@ import { commitToken, daemonAddressOf, humanMs } from "./settings.ts";
 import type { BridgeSettings } from "./settings.ts";
 import type { Bridge, BridgeOptions } from "./server-core.ts";
 import { errMsg } from "./errmsg.ts";
+import { refreshInstalledPlugin } from "./plugin-install.ts";
 
 export type Lifetime = "one-shot" | "serve" | "session";
 
@@ -131,6 +132,9 @@ export function bridgeHolder(lifetime: Lifetime, deps: HolderDeps): Holder {
       settings = c.settings;
       for (const line of c.notice) log(line);
     }
+    // About to hold the bridge, so no plugin is connected to this process yet: the moment to bring an installed
+    // per-user copy of the plugin up to this package's (plugin-install.ts — once per process, never from a checkout).
+    refreshInstalledPlugin(log);
     let failed: (e: Error) => void = () => {};
     const bindFailed = new Promise<never>((_, reject) => { failed = reject; });
     const b = deps.createBridge(settings, survive ? { onListenError: (e) => failed(e) } : {});

package/src/cli-commands.ts

@@ -407,6 +407,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: "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/doctor.ts

@@ -39,6 +39,8 @@ import { ifDefined } from "./json-util.ts";
 import * as LAYOUT from "./project-layout.ts";
 import { isOurMcpEntry, mcpEntryProblems, PROFILES, readMcpJson } from "./init.ts";
 import { daemonRowStalenessNote } from "./staleness.ts";
+import { describeState, pluginState } from "./plugin-install.ts";
+import type { PluginState } from "./plugin-install.ts";
 // The manifest's allowedDomains ports and the FIGMA_BRIDGE_PORT parse — ports.ts, the same list and
 // parse settings.ts reads the port with. A bad value is a finding here (the very case this exists to diagnose).
 import { ALLOWED_PORTS, parsePortEnv } from "./ports.ts";
@@ -51,7 +53,7 @@ import { exitCli } from "./stdio.ts";
 import { daemonAddressOf, readSettings, tokenSetting } from "./settings.ts";
 
 /** Every check this report can carry, by id — what `--json` consumers key on. */
-export type CheckId = "bun" | "token" | "daemon" | "port" | "plugin" | "project" | "profile" | "layout" | "export" | "map" | "mcp";
+export type CheckId = "bun" | "token" | "daemon" | "port" | "plugin" | "plugin-files" | "project" | "profile" | "layout" | "export" | "map" | "mcp";
 
 /** One line of the report. `next` is the single next step (absent, or undefined, when there is none). `skipped`: the
  *  check could not run (a warn), so nothing it would have verified was — the report is not ok beside one. */
@@ -327,6 +329,14 @@ function exportChecks(v: ExportVerdict, rel: string): Check[] {
 // custom stack written in design/profile.md), plus design/profile.md read after a bundled profile as the project's own
 // rules. An older project's root profiles/<profile>.md is read the same way.
 export const OVERLAY_FILE = path.join(LAYOUT.DESIGN_DIR, "profile.md");
+// The plugin's files on disk (plugin-install.ts), not the running plugin: is there a per-user copy to import, and is it
+// this dtwin's? Read only — doctor never installs or refreshes it. A note, never a failure: someone who imported from
+// a clone or the package folder before is still working.
+function checkPluginFiles(s: PluginState): Check {
+  const d = describeState(s);
+  return d.ok ? ok("plugin-files", "Plugin files", d.detail) : warn("plugin-files", "Plugin files", d.detail, d.next);
+}
+
 function checkProfile(cwd: string): Check {
   let profile: string | null = null;
   try {
@@ -549,6 +559,7 @@ async function run({ cwd = process.cwd(), waitSec = 10, onCheck, onWait }: RunOp
     }
   }
   if (tok.shadowed) add(checkToken(tok, pluginCheck, viaDaemon));
+  add(checkPluginFiles(pluginState()));
 
   add(...checkProject(cwd));
   return { ok: reportOk(checks), checks };
@@ -599,4 +610,4 @@ async function main(argv: string[]): Promise<void> {
   process.exitCode = report.ok ? 0 : 1;
 }
 
-export { checkBun, checkToken, checkDaemon, sharedTokenNote, resolvePort, ephemeralPortWarning, checkPort, checkPlugin, checkProject, exportChecks, reportOk, probePort, probePlugin, run, main };
+export { checkBun, checkToken, checkDaemon, sharedTokenNote, resolvePort, ephemeralPortWarning, checkPort, checkPlugin, checkPluginFiles, checkProject, exportChecks, reportOk, probePort, probePlugin, run, main };

package/src/figma-pull.ts

@@ -1146,6 +1146,7 @@ const ROUTES = {
   init: async (args) => { (await import("./init.ts")).main(args); },
   doctor: async (args) => { await (await import("./doctor.ts")).main(args); },
   seed: async (args) => { (await import("./seed-components.ts")).main(args); },
+  plugin: async (args) => { (await import("./plugin-install.ts")).main(args); },
 } satisfies Record<RoutedVerb, (args: string[]) => Promise<void>>;
 const routed = (word: string | undefined): word is RoutedVerb => word !== undefined && Object.hasOwn(ROUTES, word);
 
@@ -1177,7 +1178,7 @@ async function runMcp(args: string[]): Promise<void> {
 // first, then --version/--help, then the arguments are parsed, THEN the settings are read (settings.ts — port, token
 // with --token-file, limits) and the command runs.
 async function cli(argv: string[]): Promise<void> {
-  // `dtwin mcp|init|doctor|seed` — their own entry points, before anything else runs (in particular before
+  // `dtwin mcp|init|doctor|seed|plugin` — their own entry points, before anything else runs (in particular before
   // the settings are read): `dtwin mcp` is taken ONLY when the first argument is exactly "mcp", so `dtwin …` and
   // importing this module from the test suites are untouched, and `bun bridge/src/figma-mcp.ts` still works.
   const word = argv[0];

package/src/init.ts

@@ -31,6 +31,8 @@ import type { ResolvedToken } from "./token-store.ts";
 import * as LAYOUT from "./project-layout.ts";
 import { ifDefined, isRecord } from "./json-util.ts";
 import { exitCli } from "./stdio.ts";
+import { errMsg } from "./errmsg.ts";
+import { hiddenHint, installPlugin, nextSteps, pluginHome, pluginSource } from "./plugin-install.ts";
 
 /** One .mcp.json server entry, as init writes it. */
 export interface McpEntry {
@@ -400,10 +402,25 @@ function main(argv: string[]): void {
   if (dry) for (const a of actions) log(`${a.kind === "write" ? "would write" : a.kind === "mkdir" ? "would create" : a.kind} ${"path" in a ? a.path + " — " : ""}${a.note}`);
   else apply(cwd, actions, log);
 
-  // The Figma plugin's manifest: a repo checkout's (bridge/src/ -> ../../figma-plugin/), else the copy the npm
-  // package carries (../figma-plugin/, put there by bridge/pack.ts). Neither: the step names the repo instead.
-  // Spelt from `here` too: Figma remembers the path a plugin was imported from, and a Cellar one is gone after an upgrade.
-  const manifest = [path.join(here, "..", "..", "figma-plugin", "manifest.json"), path.join(here, "..", "figma-plugin", "manifest.json")].find((m) => fs.existsSync(m));
+  // The Figma plugin's manifest: a repo checkout's own figma-plugin/, else the per-user copy (plugin-install.ts),
+  // installed — or refreshed — here from the files the npm package carries, so the path to import never moves.
+  // Neither: the step names the repo instead.
+  const manifest = ((): string | null => {
+    const source = pluginSource();
+    if (!source) return null;
+    if (source.kind === "checkout") return path.join(source.dir, "manifest.json");
+    if (dry) { log(`would install the Figma plugin to ${pluginHome()} (dtwin plugin install)`); return path.join(pluginHome(), "manifest.json"); }
+    try {
+      const r = installPlugin(source);
+      log(`plugin  Figma plugin v${r.version ?? "?"} ${r.status === "current" ? "already up to date" : r.status} at ${r.home}`);
+      if (r.status !== "installed") for (const s of nextSteps(r)) log("        " + s);
+      return r.manifest;
+    } catch (e) {
+      log(`warn    could not install the Figma plugin to ${pluginHome()} (${errMsg(e)}); import the package's own copy instead`);
+      // Spelt through opt under Homebrew: Figma remembers the path, and a Cellar one is gone after an upgrade.
+      return path.join(stableKegPath(source.dir), "manifest.json");
+    }
+  })();
   // Step 3 is already done for anyone who reached init THROUGH the installed plugin's help skill —
   // which is the documented path. Claude Code records installed plugins under ~/.claude; when the
   // marker is there, saying "install the plugin" is noise at best and confusing at worst.
@@ -425,7 +442,8 @@ function main(argv: string[]): void {
   })();
 
   const steps = [
-    "In Figma DESKTOP: 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)"),
+    "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",
   ];
   if (!pluginInstalled) {

package/src/plugin-install.ts

@@ -0,0 +1,285 @@
+// plugin-install.ts — the Figma plugin's per-user copy, and `dtwin plugin install|update|status|path|uninstall`.
+//
+// The plugin cannot be listed on Figma Community, so it is imported as a development plugin: Plugins → Development →
+// Import plugin from manifest…. Figma remembers the manifest's PATH, so the folder it was imported from must not move —
+// and then replacing the files there is the whole update. With Plugins → Development → Hot reload plugin ON,
+// reopening the plugin runs the new code and picks up a changed manifest's permissions too (seen live, Figma
+// desktop 126); with it OFF, Figma kept running the code it had loaded. A path inside the npm package does move (Bun's and npm's global
+// folders differ, a Node version manager gives every Node its own prefix, a bunx cache is replaced whenever Bun likes,
+// an uninstall deletes it), so an install copies the plugin to ONE per-user folder, next to the bridge token:
+// <configDir>/figma-plugin (token-store.ts: ~/.config/design-twin, %APPDATA%\design-twin on Windows,
+// DESIGNTWIN_CONFIG_DIR overriding both). That is the path to import, once.
+//
+// A copy whose manifest.json changed (permissions, networkAccess) says so, with re-importing as the fallback for when
+// reopening does not pick the change up.
+//
+// The copy is refreshed — never created — whenever this process is about to bind a bridge (refreshInstalledPlugin,
+// from bridge-holder.ts): an upgraded package brings its plugin along with no command to remember, and at that moment
+// no plugin is connected to this process, so no export of ours is mid-run when the files change. A dtwin running from
+// a repo checkout never refreshes it: a developer imports figma-plugin/ itself, and their copy is theirs.
+//
+// Each file is written atomically (atomic-write.ts: a tmp file and a rename — the folder itself is never swapped,
+// since the path Figma holds must stay the one it imported), ui.html and code.js before manifest.json, install.json
+// last, all under one lock (file-lock.ts), so two processes refreshing at once write each file once and a reader
+// never sees half a file.
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { writeFileAtomic } from "./atomic-write.ts";
+import { errMsg } from "./errmsg.ts";
+import { withFileLock } from "./file-lock.ts";
+import { sha256Hex } from "./hash.ts";
+import { BRIDGE_VERSION } from "./staleness.ts";
+import { exitCli } from "./stdio.ts";
+import { configDir } from "./token-store.ts";
+
+/** The files Figma loads: the manifest and the two it names (bridge/pack.ts ships exactly these). */
+export const PLUGIN_FILES = ["manifest.json", "code.js", "ui.html"] as const;
+type PluginFile = (typeof PLUGIN_FILES)[number];
+// The manifest last: a manifest that names code.js / ui.html is never on disk before they are.
+const WRITE_ORDER: readonly PluginFile[] = ["ui.html", "code.js", "manifest.json"];
+const RECORD = "install.json";
+
+/** Where the plugin is installed for this user: <configDir>/figma-plugin. */
+export const pluginHome = (): string => path.join(configDir(), "figma-plugin");
+const lockOf = (home: string): string => home + ".lock";
+
+/** Where this dtwin's plugin files are: a repo checkout's figma-plugin/ (bridge/src/ → ../../figma-plugin/, told
+ *  apart by the ui.template.html no package ships), else the copy the npm package carries (../figma-plugin/,
+ *  bridge/pack.ts). null: neither (a package packed without it). */
+export interface PluginSource { dir: string; kind: "checkout" | "package" }
+export function pluginSource(here: string = import.meta.dirname): PluginSource | null {
+  const checkout = path.join(here, "..", "..", "figma-plugin");
+  if (fs.existsSync(path.join(checkout, "ui.template.html")) && fs.existsSync(path.join(checkout, "manifest.json"))) return { dir: checkout, kind: "checkout" };
+  const packaged = path.join(here, "..", "figma-plugin");
+  if (PLUGIN_FILES.every((f) => fs.existsSync(path.join(packaged, f)))) return { dir: packaged, kind: "package" };
+  return null;
+}
+
+/** What install.json records: the version installed, each file's sha256, from where, when. */
+export interface InstallRecord { version: string | null; files: Record<string, string>; from: PluginSource["kind"]; installedAt: string }
+
+function readRecord(home: string): InstallRecord | null {
+  try {
+    const r: unknown = JSON.parse(fs.readFileSync(path.join(home, RECORD), "utf8"));
+    if (typeof r !== "object" || r === null || !("files" in r) || typeof r.files !== "object" || r.files === null) return null;
+    return r as InstallRecord; // shape checked above; every other field is only printed
+  } catch { return null; }
+}
+const shaOf = (file: string): string | null => {
+  try { return sha256Hex(fs.readFileSync(file)); } catch { return null; }
+};
+const shas = (dir: string): Record<PluginFile, string | null> =>
+  Object.fromEntries(PLUGIN_FILES.map((f) => [f, shaOf(path.join(dir, f))])) as Record<PluginFile, string | null>;
+
+/** The per-user copy as it is now, against this dtwin's own plugin files. */
+export interface PluginState {
+  home: string;
+  /** the manifest to import into Figma: the checkout's own when this dtwin runs from one, else the installed copy's */
+  importPath: string;
+  source: PluginSource | null;
+  /** every plugin file is in the home folder */
+  installed: boolean;
+  record: InstallRecord | null;
+  /** the installed files are byte-for-byte this dtwin's (null: not installed, or nothing to compare with) */
+  current: boolean | null;
+}
+export function pluginState(source: PluginSource | null = pluginSource(), home: string = pluginHome()): PluginState {
+  const have = shas(home);
+  const installed = PLUGIN_FILES.every((f) => have[f] !== null);
+  const want = source ? shas(source.dir) : null;
+  const current = installed && want ? PLUGIN_FILES.every((f) => have[f] === want[f]) : null;
+  const importPath = source?.kind === "checkout" ? path.join(source.dir, "manifest.json") : path.join(home, "manifest.json");
+  return { home, importPath, source, installed, record: readRecord(home), current };
+}
+
+export interface InstallResult {
+  status: "installed" | "updated" | "current";
+  home: string;
+  manifest: string;
+  version: string | null;
+  /** the files rewritten, in the order written */
+  written: PluginFile[];
+  /** an earlier copy's manifest.json differed (permissions / network access): if reopening does not pick it up, re-import */
+  manifestChanged: boolean;
+}
+
+/** Copy `source`'s plugin files into `home`, writing only the ones that differ. Idempotent: an up-to-date copy is
+ *  left untouched ("current"). */
+export function installPlugin(source: PluginSource, home: string = pluginHome(), now: () => Date = () => new Date()): InstallResult {
+  fs.mkdirSync(path.dirname(home), { recursive: true });
+  return withFileLock(lockOf(home), () => {
+    const have = shas(home);
+    const fresh = !PLUGIN_FILES.some((f) => have[f] !== null);
+    const bytes = Object.fromEntries(PLUGIN_FILES.map((f) => [f, fs.readFileSync(path.join(source.dir, f))])) as Record<PluginFile, Buffer>;
+    const want = Object.fromEntries(PLUGIN_FILES.map((f) => [f, sha256Hex(bytes[f])])) as Record<PluginFile, string>;
+    const written = WRITE_ORDER.filter((f) => have[f] !== want[f]);
+    for (const f of written) writeFileAtomic(path.join(home, f), bytes[f]);
+    const record = readRecord(home);
+    const recordStale = !record || record.version !== BRIDGE_VERSION || PLUGIN_FILES.some((f) => record.files[f] !== want[f]);
+    if (written.length || recordStale) {
+      const next: InstallRecord = { version: BRIDGE_VERSION, files: want, from: source.kind, installedAt: now().toISOString() };
+      writeFileAtomic(path.join(home, RECORD), JSON.stringify(next, null, 2) + "\n");
+    }
+    return {
+      status: fresh ? "installed" : written.length ? "updated" : "current",
+      home,
+      manifest: path.join(home, "manifest.json"),
+      version: BRIDGE_VERSION,
+      written,
+      manifestChanged: !fresh && have["manifest.json"] !== null && have["manifest.json"] !== want["manifest.json"],
+    };
+  });
+}
+
+/** Remove the files an install wrote (and the folder, once empty). Anything else in it is left alone. */
+export function uninstallPlugin(home: string = pluginHome()): string[] {
+  if (!fs.existsSync(home)) return [];
+  return withFileLock(lockOf(home), () => {
+    const removed: string[] = [];
+    for (const f of [...PLUGIN_FILES, RECORD]) {
+      const p = path.join(home, f);
+      if (fs.existsSync(p)) { fs.rmSync(p, { force: true }); removed.push(f); }
+    }
+    try { fs.rmdirSync(home); } catch { /* not empty, or gone: left as it is */ }
+    return removed;
+  });
+}
+
+// Reopening runs replaced files only while Figma's hot reload is on; with it off, Figma kept the old code.
+const REOPEN = "reopen the plugin in Figma (Plugins → Development → Design Twin) with Plugins → Development → Hot reload plugin on, to run the new code";
+const importStep = (manifest: string): string => "Plugins → Development → Import plugin from manifest… → " + manifest;
+/** The manifest's folder is hidden in a file picker (a dot folder, or AppData on Windows): how to get there anyway. */
+export function hiddenHint(manifest: string): string | null {
+  if (process.platform === "darwin" && manifest.split(path.sep).some((s) => s.startsWith("."))) return "the folder is hidden in Finder: in the file picker press ⌘⇧G and paste the path";
+  if (process.platform === "win32") return "the folder is hidden in Explorer: paste the path into the file picker's File name box";
+  return null;
+}
+/** What to do in Figma after an install, an update or nothing (empty: nothing to do). */
+export function nextSteps(r: InstallResult): string[] {
+  if (r.status === "installed") {
+    const hint = hiddenHint(r.manifest);
+    return ["once, in Figma DESKTOP: " + importStep(r.manifest), ...(hint ? [hint] : []),
+      "imported the plugin from somewhere else before (a clone, the package folder)? Remove that one: Plugins → Manage plugins"];
+  }
+  if (r.manifestChanged) return [REOPEN + "; its manifest (permissions / network access) changed too — if a new permission still does not work, re-import once: " + importStep(r.manifest)];
+  if (r.status === "updated") return [REOPEN + " — no re-import needed"];
+  return [];
+}
+
+let refreshed = false;
+/** Bring an EXISTING per-user copy up to this dtwin's plugin files — once per process, never from a checkout, never
+ *  creating one. Failures are logged, never thrown: a refresh must not stop a bridge from starting. */
+export function refreshInstalledPlugin(log: (m: string) => void, source: PluginSource | null = pluginSource(), home: string = pluginHome()): InstallResult | null {
+  if (refreshed) return null;
+  refreshed = true;
+  if (source?.kind !== "package" || !fs.existsSync(path.join(home, RECORD))) return null;
+  try {
+    const r = installPlugin(source, home);
+    if (r.status !== "current") log(`updated the Figma plugin at ${home} to v${r.version ?? "?"} — ` + (nextSteps(r)[0] ?? ""));
+    return r;
+  } catch (e) {
+    log(`could not refresh the Figma plugin at ${home}: ${errMsg(e)} — run \`dtwin plugin update\``);
+    return null;
+  }
+}
+/** Test seam: let refreshInstalledPlugin run again in this process. */
+export const resetRefreshForTests = (): void => { refreshed = false; };
+
+/** One line on the state, for `dtwin plugin status` and doctor. */
+export function describeState(s: PluginState): { ok: boolean; detail: string; next?: string } {
+  if (s.source?.kind === "checkout") return { ok: true, detail: `this dtwin runs from a repo checkout — import ${s.importPath} itself (the per-user copy is not refreshed from here)` };
+  if (!s.installed) {
+    if (!s.source) return { ok: false, detail: "this dtwin carries no Figma plugin files", next: "reinstall it: bun add -g @design-twin/dtwin" };
+    return { ok: false, detail: `not installed in ${s.home}`, next: `dtwin plugin install, then (once) in Figma DESKTOP: ${importStep(s.importPath)}` };
+  }
+  const v = s.record?.version ? `v${s.record.version} ` : "";
+  if (s.current === false) return { ok: false, detail: `${v}at ${s.home} differs from this dtwin's (v${BRIDGE_VERSION ?? "?"})`, next: "dtwin plugin update" };
+  return { ok: true, detail: `${v}installed at ${s.home} — import ${s.importPath}` };
+}
+
+function reveal(manifest: string): void {
+  const [cmd, args] = process.platform === "darwin" ? ["open", ["-R", manifest]]
+    : process.platform === "win32" ? ["explorer", ["/select," + manifest]]
+    : ["xdg-open", [path.dirname(manifest)]];
+  try {
+    const p = spawn(cmd, args, { stdio: "ignore", detached: true });
+    p.on("error", () => { /* no file manager: the path is printed anyway */ });
+    p.unref();
+  } catch { /* the path is printed anyway */ }
+}
+
+export const PLUGIN_HELP =
+  "dtwin plugin [install|update|status|path|uninstall] [--json] [--open]\n\n" +
+  "  The Figma plugin is imported into Figma DESKTOP as a development plugin, from a folder that must not move.\n" +
+  "  install    copy this dtwin's plugin to a per-user folder (" + path.join("<config dir>", "figma-plugin") + ", beside the bridge\n" +
+  "             token; DESIGNTWIN_CONFIG_DIR moves it) and print the one-time import step. Writes only what differs.\n" +
+  "  update     the same, then says to reopen the plugin (with Plugins → Development → Hot reload plugin on)\n" +
+  "  status     (default) where it is installed, and whether it matches this dtwin\n" +
+  "  path       print the manifest to import (stdout): a checkout's own figma-plugin/manifest.json, else the copy's\n" +
+  "  uninstall  remove the copied files (then remove the plugin in Figma: Plugins → Manage plugins)\n\n" +
+  "  --json     machine output on stdout\n" +
+  "  --open     show the manifest in Finder / Explorer (install, update, path)\n\n" +
+  "  Once installed, the copy is kept current by itself: every dtwin that starts a bridge refreshes it from its own\n" +
+  "  package, so after upgrading @design-twin/dtwin you only reopen the plugin (hot reload on). Never from a checkout.\n" +
+  "  Needs no bridge, no plugin and no token; never touches the network.";
+
+const SUBS = ["install", "update", "status", "path", "uninstall"] as const;
+type Sub = (typeof SUBS)[number];
+const isSub = (s: string | undefined): s is Sub => SUBS.some((x) => x === s);
+
+export function main(argv: string[]): void {
+  if (argv.includes("--help") || argv.includes("-h")) { console.log(PLUGIN_HELP); exitCli(0); }
+  const json = argv.includes("--json"), open = argv.includes("--open");
+  const rest = argv.filter((a) => a !== "--json" && a !== "--open");
+  const word = rest[0] ?? "status";
+  if (!isSub(word) || rest.length > 1) {
+    console.error(`[dtwin plugin] error: unknown \`dtwin plugin ${rest.join(" ")}\` — use: dtwin plugin [${SUBS.join("|")}] [--json] [--open]`);
+    exitCli(1);
+  }
+  const log = (m: string): void => console.error("[dtwin plugin] " + m);
+  const source = pluginSource();
+
+  if (word === "status" || word === "path") {
+    const s = pluginState(source);
+    if (word === "path") {
+      console.log(json ? JSON.stringify({ importPath: s.importPath, installed: s.installed || s.source?.kind === "checkout" }) : s.importPath);
+      if (!s.installed && s.source?.kind !== "checkout") log("not installed yet — run `dtwin plugin install`");
+      if (open) reveal(s.importPath);
+      return;
+    }
+    const d = describeState(s);
+    if (json) console.log(JSON.stringify({ ...s, version: BRIDGE_VERSION, ok: d.ok, detail: d.detail, ...(d.next ? { next: d.next } : {}) }, null, 2));
+    else {
+      log(`${d.ok ? "✓" : "!"} ${d.detail}`);
+      if (d.next) log("  → " + d.next);
+    }
+    return;
+  }
+
+  if (word === "uninstall") {
+    const removed = uninstallPlugin();
+    if (json) console.log(JSON.stringify({ home: pluginHome(), removed }));
+    else log(removed.length ? `removed ${removed.join(", ")} from ${pluginHome()} — now remove the plugin in Figma too: Plugins → Manage plugins` : `nothing installed in ${pluginHome()}`);
+    return;
+  }
+
+  if (!source) {
+    log("error: this dtwin carries no Figma plugin files to install — reinstall it: bun add -g @design-twin/dtwin");
+    exitCli(1);
+  }
+  let r: InstallResult;
+  try { r = installPlugin(source); } catch (e) {
+    log(`error: could not install the Figma plugin into ${pluginHome()}: ${errMsg(e)}`);
+    exitCli(1);
+  }
+  const steps = nextSteps(r);
+  if (json) console.log(JSON.stringify({ ...r, next: steps }, null, 2));
+  else {
+    const what = r.status === "current" ? "already up to date" : r.status;
+    log(`✓ Figma plugin v${r.version ?? "?"} ${what} at ${r.home}`);
+    for (const s of steps) log("  → " + s);
+    if (source.kind === "checkout") log("  note: this dtwin runs from a repo checkout — you can import figma-plugin/manifest.json there directly");
+  }
+  if (open) reveal(r.manifest);
+}