@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/asset-owners.ts

@@ -0,0 +1,280 @@
+// asset-owners.ts — who owns an exported graphic, and which hidden graphic can reuse a visible twin's file.
+//
+// Pure: plain IR trees in, plain answers out (no fs) — write-out.ts does the reading and writing, so every
+// rule here is testable offline on hand-built trees.
+//
+// 1. Owners. An asset file is named after its layer, and a layer is very often called
+//    `Vector`, `Icon` or `Group_N`. What it IS lives on the nearest component instance above it (or on the
+//    node itself): `Checkbox / Status=Checked`. One walk gives every `asset` pointer its uses — node id,
+//    layer name, hidden or not, owner, the instance above the owner (`context`, which names a self-owned
+//    icon component such as `Glyph 12` inside `Nav item / Type=Settings`) — and the `.assets.json`
+//    row carries them, so a builder searches by component instead of by file name. File names never change.
+//
+// 2. Hidden reuse. The plugin does not export a hidden graphic (`assetSkipped:"hidden"`): its
+//    exporter has nothing to render. When a VISIBLE node in the same pull (or in another screen already
+//    pulled) is the same graphic — the same main component, the same source node inside it, the same
+//    chain of components and variants above the owner, the same non-boolean props, the same effective
+//    variable modes, the same size and transform, and no paint override (nor a shape/visibility override
+//    on a sublayer of the graphic) on either side — the hidden
+//    node points at that file instead (`asset` + `assetFrom`). An owner's booleans are left out of the key
+//    because they are the visibility toggles that hid the node; a SELF-owned icon's own booleans are its
+//    internal toggles (`Show badge`), so they stay in. Variant props are covered by the main
+//    component id. The modes are in because a bound colour renders per mode.
+//    The chain is in the key because a parent variant may recolour a nested icon in its own DEFINITION
+//    (`Button / Type=Danger` drawing its icon red), and Figma's `overrides` list only what is overridden
+//    directly on an instance, never what it inherits — so no override would block that twin.
+import type { InstanceOverride, IrNode } from "./doc-types.ts";
+import { OVERRIDE_CAP } from "./instance-overrides.ts";
+
+/** The nearest INSTANCE ancestor-or-self that names its main component. */
+export interface AssetOwner {
+  /** the component set's name, else the component's own */
+  component: string;
+  variant?: string;
+  componentId?: string;
+  componentKey?: string;
+  /** the owning instance's node id */
+  instance: string;
+  /** the node IS the owning instance (a self-owned icon component) */
+  self: boolean;
+  /** a paint override, a shape/visibility override on a sublayer (or a truncated override list) on this
+   *  use — never reused across, either way */
+  paintOverrides?: true;
+}
+/** The next INSTANCE above the owner. */
+export interface AssetContext { component: string; variant?: string }
+
+/** One node in a tree that holds an exported graphic (`asset`) or a hidden one that was not (`assetSkipped:"hidden"`). */
+export interface Graphic {
+  node: IrNode;
+  /** the node or an ancestor is hidden */
+  hidden: boolean;
+  owner?: AssetOwner;
+  context?: AssetContext;
+  /** see reuseKeyOf; absent without an owner that names a component id or key */
+  reuseKey?: string;
+  /** a paint override, a sublayer shape/visibility override or a truncated override list blocks reuse */
+  blocked: boolean;
+}
+
+// Figma's overriddenFields that change how a graphic LOOKS. Anything else (a text, a swapped instance's
+// visibility, a name) leaves the exported pixels of an icon alone.
+const PAINT_FIELD_RE = /^(?:fills|strokes|strokeWeight|sto?ke\w*Weight|opacity|effects|effectStyleId|blendMode|fillStyleId|strokeStyleId|boundVariables|explicitVariableModes|vectorNetwork)$/;
+// On a SUBLAYER of the graphic (inside the exported file), any field but these changes the drawing: a
+// `visible` override drops a layer, a size/corner/transform one reshapes it.
+const INERT_SUBLAYER_FIELD_RE = /^(?:name|locked|pluginData|reactions|description|exportSettings|expanded|autoRename|hyperlink|characters|styledTextSegments|textStyleId|fontName)$/;
+
+const lastSegment = (id: string): string => { const i = id.lastIndexOf(";"); return i >= 0 ? id.slice(i + 1) : id; };
+const isOwnerInstance = (n: IrNode): boolean => n.type === "INSTANCE" && !!n.mainComponent;
+const overridesOf = (n: IrNode): readonly InstanceOverride[] => (Array.isArray(n.overrides) ? n.overrides : []);
+// The plugin cuts the list at OVERRIDE_CAP (and warns): at that length, what was cut is unknown.
+const truncated = (n: IrNode): boolean => overridesOf(n).length >= OVERRIDE_CAP;
+const paintEntry = (o: InstanceOverride): boolean => !!o && Array.isArray(o.fields) && o.fields.some((f) => typeof f === "string" && PAINT_FIELD_RE.test(f));
+
+// (iii) of the reuse guard. On every instance from the root down to the graphic, a paint entry ABOUT the
+// graphic or one of its sublayers counts (a sublayer id is `<id>;…`, or `I<id>;…` under a top-level
+// instance): an outer instance records a recolour of a nested vector on ITS own `overrides`, not on the
+// vector's owner. For a graphic that is not itself an instance, each paint entry on its owner counts
+// as well — the override's target cannot always be tied to the node more precisely than that from the tree.
+// On a STRICT sublayer (`<id>;…`, inside the exported file) any field but an inert one blocks: a `visible`
+// override drops a layer, a size/corner one reshapes it. The graphic's own `visible` is what hid it.
+// A truncated list on any of those instances blocks too: what was cut is unknown.
+function hasPaintOverride(node: IrNode, instances: readonly IrNode[], owner: IrNode | undefined): boolean {
+  const id = typeof node.id === "string" ? node.id : "";
+  const prefixes = [id + ";", "I" + id + ";"];
+  const about = (o: InstanceOverride): boolean => !!o && typeof o.id === "string" && (o.id === id || prefixes.some((p) => o.id.startsWith(p)));
+  const sub = (o: InstanceOverride): boolean => !!o && typeof o.id === "string" && o.id !== id && prefixes.some((p) => o.id.startsWith(p));
+  const reshapes = (o: InstanceOverride): boolean => Array.isArray(o.fields) && o.fields.some((f) => typeof f === "string" && !INERT_SUBLAYER_FIELD_RE.test(f));
+  if (instances.some((inst) => truncated(inst) || overridesOf(inst).some((o) => (about(o) && paintEntry(o)) || (sub(o) && reshapes(o))))) return true;
+  if (node.type === "INSTANCE" || !owner) return false;
+  return overridesOf(owner).some(paintEntry);
+}
+
+const sortedProps = (n: IrNode, booleans: boolean): Array<[string, unknown]> => {
+  const props = n.props && typeof n.props === "object" ? Object.entries(n.props) : [];
+  return props.filter(([, v]) => booleans || typeof v !== "boolean").sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+};
+
+/** `<componentKey||componentId>|<self|last id segment>|<sorted props JSON>|<chain JSON>[|<modes JSON>]`, or
+ *  undefined. The props drop booleans unless the node IS the owner; `modes` is the effective
+ *  `[collection, mode]` list, sorted (collectGraphics), left off when empty. `chain` is the main component (key, else id — which names the variant; `?` when unnamed) of
+ *  every INSTANCE above the owner, outermost first: `instances` is the root-down list of instances above
+ *  `node` (the owner included, when it is an ancestor). The whole chain, not only the next instance up: an
+ *  outer component's definition can recolour the nested icon just as the parent variant's can.
+ *  Not in the key: WHERE in the parent the owner sits. The full id path would keep a leading and a trailing
+ *  icon of one button variant apart, but on the real exports it refused every same-screen reuse — list
+ *  rows inside an instance carry document ids in that path, different per row for the very same icon. */
+export function reuseKeyOf(node: IrNode, owner: IrNode | undefined, instances: readonly IrNode[] = [], modes = ""): string | undefined {
+  const mc = owner && owner.mainComponent;
+  const comp = mc && (mc.key || mc.id);
+  if (!owner || !comp || typeof node.id !== "string") return undefined;
+  const at = instances.indexOf(owner);
+  const above = at >= 0 ? instances.slice(0, at) : instances.filter((i) => i !== owner);
+  const chain = above.map((i) => (i.mainComponent && (i.mainComponent.key || i.mainComponent.id)) || "?");
+  return comp + "|" + (node === owner ? "self" : lastSegment(node.id)) + "|" + JSON.stringify(sortedProps(owner, node === owner)) + "|" + JSON.stringify(chain) + (modes ? "|" + modes : "");
+}
+
+function ownerRef(inst: IrNode, node: IrNode, blocked: boolean): AssetOwner | undefined {
+  const mc = inst.mainComponent;
+  if (!mc) return undefined;
+  const o: AssetOwner = { component: mc.setName ?? mc.name, instance: inst.id, self: inst === node };
+  if (mc.variant) o.variant = mc.variant;
+  if (mc.id) o.componentId = mc.id;
+  if (mc.key) o.componentKey = mc.key;
+  if (blocked) o.paintOverrides = true;
+  return o;
+}
+
+/** Every graphic node (`asset` string, or `assetSkipped:"hidden"`) in tree order, with its owner and reuse key. */
+export function collectGraphics(roots: readonly IrNode[] | null | undefined): Graphic[] {
+  const out: Graphic[] = [];
+  // instances: every INSTANCE from the root down (paint-override scope); owners: the ones naming a main component.
+  // modes: the effective variable mode per collection (the root's resolvedModes, then every variableModes
+  // pinned on the way down) — a bound colour renders per mode, so a Dark section never reuses a Light file.
+  const visit = (n: IrNode, instances: readonly IrNode[], owners: readonly IrNode[], hiddenAbove: boolean, modesAbove: ReadonlyMap<string, string>): void => {
+    if (!n || typeof n !== "object") return;
+    let modes = modesAbove;
+    for (const pinned of [n.resolvedModes, n.variableModes]) {
+      if (!pinned || typeof pinned !== "object") continue;
+      const next = new Map(modes);
+      for (const [c, m] of Object.entries(pinned)) if (typeof m === "string") next.set(c, m);
+      modes = next;
+    }
+    const insts = n.type === "INSTANCE" ? [...instances, n] : instances;
+    const owns = isOwnerInstance(n) ? [...owners, n] : owners;
+    const hidden = hiddenAbove || n.hidden === true;
+    if (typeof n.asset === "string" || n.assetSkipped === "hidden") {
+      const owner = owns[owns.length - 1];
+      const above = owns[owns.length - 2];
+      const blocked = hasPaintOverride(n, insts, owner);
+      const g: Graphic = { node: n, hidden, blocked };
+      const o = owner && ownerRef(owner, n, blocked);
+      if (o) g.owner = o;
+      const ac = above && above.mainComponent;
+      if (ac) g.context = ac.variant ? { component: ac.setName ?? ac.name, variant: ac.variant } : { component: ac.setName ?? ac.name };
+      const mk = [...modes].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+      const key = reuseKeyOf(n, owner, insts, mk.length ? JSON.stringify(mk) : "");
+      if (key !== undefined) g.reuseKey = key;
+      out.push(g);
+    }
+    // An unrelated screen's JSON on disk may be malformed (`children: {}`): skipped, never a throw.
+    if (Array.isArray(n.children)) for (const c of n.children) visit(c, insts, owns, hidden, modes);
+  };
+  for (const r of roots || []) visit(r, [], [], false, new Map());
+  return out;
+}
+
+/** pointer (`assets/<name>`) → its uses in tree order. */
+export function usesByPointer(graphics: readonly Graphic[]): Map<string, Graphic[]> {
+  const map = new Map<string, Graphic[]>();
+  for (const g of graphics) {
+    const p = g.node.asset;
+    if (typeof p !== "string") continue;
+    let list = map.get(p);
+    if (!list) { list = []; map.set(p, list); }
+    list.push(g);
+  }
+  return map;
+}
+
+// (ii): the transform Figma drew into the file. A visible asset leaf carries it as `sourceTransform`; an older
+// export, and the hidden node before reuse, carry it bare.
+function transformOf(n: IrNode): { rotation: number; flipped: boolean; skew: number } {
+  const t = n.sourceTransform;
+  return t
+    ? { rotation: t.rotation ?? 0, flipped: t.flipped === true, skew: t.skew ?? 0 }
+    : { rotation: n.rotation ?? 0, flipped: n.flipped === true, skew: n.skew ?? 0 };
+}
+const BOX_TOL = 0.5;
+const ANGLE_TOL = 0.01;
+function sameLook(hidden: IrNode, twin: IrNode): boolean {
+  const a = hidden.box, b = twin.box;
+  // `!(d <= tol)`, not `d > tol`: a non-number size (a malformed tree on disk) is NaN and must refuse.
+  if (!a || !b || !(Math.abs(a.w - b.w) <= BOX_TOL) || !(Math.abs(a.h - b.h) <= BOX_TOL)) return false;
+  const x = transformOf(hidden), y = transformOf(twin);
+  return x.flipped === y.flipped && Math.abs(x.rotation - y.rotation) <= ANGLE_TOL && Math.abs(x.skew - y.skew) <= ANGLE_TOL;
+}
+
+// A twin's pointer must be the plugin's own shape, `assets/<name>`: a hand-edited or foreign sibling JSON
+// naming `../x.svg` or another dir would hand that path on, and the reusing screen's `.assets.json` would
+// read the file's bytes.
+const ASSET_POINTER_RE = /^assets\/(?!\.\.?$)[^/\\]+$/;
+const twinOk = (g: Graphic): boolean => !g.hidden && !g.blocked && typeof g.node.asset === "string" && ASSET_POINTER_RE.test(g.node.asset) && g.node.assetFrom === undefined && g.reuseKey !== undefined;
+
+export interface ReuseOptions {
+  /** Trees of OTHER screens that may hold a twin for one of `keys` (writeScreen: from their `.assets.json`
+   *  `reuseKey`). Called at most once, and only when a candidate is left unmatched in its own tree. */
+  otherTrees?: (keys: ReadonlySet<string>) => Iterable<readonly IrNode[]>;
+  /** The twin's pointer names a file on disk — a reuse must never create a dangling pointer. */
+  pointerExists?: (pointer: string) => boolean;
+}
+export interface ReuseResult {
+  /** `assetSkipped:"hidden"` nodes seen */
+  hidden: number;
+  /** of which now point at a twin's file */
+  reused: number;
+  /** of which the twin was in another screen */
+  crossScreen: number;
+}
+
+// The transform move: the reused file already has the twin's transform drawn in, so the bare fields go under
+// `sourceTransform` — a builder that applies `rotation` would otherwise rotate it twice.
+function moveTransform(n: IrNode): void {
+  const t: NonNullable<IrNode["sourceTransform"]> = {};
+  if (typeof n.rotation === "number") t.rotation = n.rotation;
+  if (n.flipped === true) t.flipped = true;
+  if (typeof n.skew === "number") t.skew = n.skew;
+  delete n.rotation; delete n.flipped; delete n.skew;
+  if (Object.keys(t).length) n.sourceTransform = t;
+}
+
+/** Point every hidden graphic that has a visible twin at the twin's file. Mutates `roots` in place. */
+export function reuseHiddenAssets(roots: readonly IrNode[] | null | undefined, opts: ReuseOptions = {}): ReuseResult {
+  const graphics = collectGraphics(roots);
+  const candidates = graphics.filter((g) => g.node.assetSkipped === "hidden");
+  const result: ReuseResult = { hidden: candidates.length, reused: 0, crossScreen: 0 };
+  if (!candidates.length) return result;
+  const exists = opts.pointerExists || (() => true);
+  const pool = (list: readonly Graphic[]): Map<string, Graphic[]> => {
+    const m = new Map<string, Graphic[]>();
+    for (const g of list) {
+      if (!twinOk(g) || g.reuseKey === undefined) continue;
+      let l = m.get(g.reuseKey);
+      if (!l) { l = []; m.set(g.reuseKey, l); }
+      l.push(g);
+    }
+    return m;
+  };
+  const pick = (c: Graphic, twins: Map<string, Graphic[]>): Graphic | undefined =>
+    c.reuseKey === undefined ? undefined : (twins.get(c.reuseKey) || []).find((t) => typeof t.node.asset === "string" && exists(t.node.asset) && sameLook(c.node, t.node));
+  const apply = (c: Graphic, t: Graphic): void => {
+    const n = c.node, file = t.node.asset;
+    if (typeof file !== "string") return; // pick() only returns twins with a pointer
+    n.asset = file;
+    n.assetFrom = t.node.id;
+    delete n.assetSkipped;
+    moveTransform(n);
+  };
+
+  const local = pool(graphics);
+  const left: Graphic[] = [];
+  for (const c of candidates) {
+    if (c.blocked || c.reuseKey === undefined) continue;
+    const t = pick(c, local);
+    if (t) { apply(c, t); result.reused++; } else left.push(c);
+  }
+  if (left.length && opts.otherTrees) {
+    const keys = new Set<string>();
+    for (const c of left) if (c.reuseKey !== undefined) keys.add(c.reuseKey);
+    const other: Graphic[] = [];
+    for (const tree of opts.otherTrees(keys)) {
+      try { other.push(...collectGraphics(tree)); } catch { /* a malformed other screen holds no twin */ }
+    }
+    const far = pool(other);
+    for (const c of left) {
+      const t = pick(c, far);
+      if (t) { apply(c, t); result.reused++; result.crossScreen++; }
+    }
+  }
+  return result;
+}

package/src/atomic-write.ts

@@ -0,0 +1,79 @@
+// The one atomic file write: a tmp file beside the target, then a rename over it. Shared by bridge/ and
+// design-to-code/ (the layer may import bridge/src; bridge cannot import the layer).
+//
+// rename(2) replaces the destination atomically on POSIX, so a run killed mid-write (Ctrl-C, OOM) leaves the
+// PREVIOUS file whole instead of a truncated one every later reader fails on. The tmp file sits in the target's
+// own directory so the rename never crosses a filesystem. There is no fsync by default: these files are
+// re-creatable exports, plans and reports, and the guarantee wanted is "never half a file after a killed process",
+// which rename gives; surviving a power cut would cost a sync per write on hundreds of layer files. A file that has
+// to outlive a power cut as well (a migration's journal) passes `sync`. `sync` is fsyncSync (node:fs). On macOS a
+// plain fsync does not flush the drive's write cache (that takes fcntl F_FULLFSYNC); which one Bun issues is unverified.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { errCode } from "./errmsg.ts";
+
+/** A `.tmp-<pid>-<random>` suffix: unique per call, so two writers (two processes, or two writes in one) never
+ *  share a tmp name, and a stale tmp from a killed run is never reused. */
+export const tmpSuffix = (): string => `.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+
+// On Windows a rename over a file that another process has open — a reader polling it (verify-screen --wait reads the live
+// status every --interval while the verifier writes it), an antivirus scan or an indexer — is refused
+// (ERROR_ACCESS_DENIED / ERROR_SHARING_VIOLATION → EPERM, EACCES, EBUSY) until that handle closes, which is a moment: the
+// rename is retried for up to RENAME_RETRY_MS (as graceful-fs does for npm) before the refusal stands. POSIX renames over
+// an open file at once; there the first error is final — as it is for a target that is a directory (a refusal no handle
+// closing will lift).
+const RENAME_RETRY_MS = 2_000;
+const RENAME_TRANSIENT = new Set(["EPERM", "EACCES", "EBUSY"]);
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+/** fs.renameSync(from, to), retried on Windows while the refusal can be another process's open handle (see above). */
+export function renameOver(from: string, to: string): void {
+  const t0 = Date.now();
+  for (let delay = 5; ; delay = Math.min(delay * 2, 100)) {
+    try { fs.renameSync(from, to); return; } catch (e) {
+      const code = errCode(e);
+      if (process.platform !== "win32" || code === undefined || !RENAME_TRANSIENT.has(code) || Date.now() - t0 >= RENAME_RETRY_MS) throw e;
+      let dir = false;
+      try { dir = fs.statSync(to).isDirectory(); } catch { /* gone or unreadable: retried */ }
+      if (dir) throw e;
+      Atomics.wait(sleeper, 0, 0, delay);
+    }
+  }
+}
+
+/** The directory's entries flushed to disk (a rename into it, made durable). Not on Windows, where a directory
+ *  cannot be opened for it; a filesystem that refuses it keeps the rename as it is. */
+function syncDir(dir: string): void {
+  if (process.platform === "win32") return;
+  try {
+    const fd = fs.openSync(dir, "r");
+    try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  } catch { /* no directory fsync here: the rename stands, only its durability is the filesystem's */ }
+}
+
+/** Writes `data` to `file` atomically: a reader sees the old file or the new one, never half of either. The parent
+ *  directory is created when missing. On any error the tmp file is removed, the old file is left as it was and the
+ *  error is rethrown. `mode`: the new file's permission bits (a secret passes 0o600) — applied to the tmp file
+ *  with open(2)'s mode AND chmod, because the umask masks the first. Without `mode` the umask default applies.
+ *  `sync`: the bytes are fsynced before the rename and the directory after it, so the new file survives a power
+ *  cut too. */
+export function writeFileAtomic(file: string, data: string | Uint8Array, opts: { mode?: number; sync?: boolean } = {}): void {
+  const dir = path.dirname(path.resolve(file));
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = file + tmpSuffix();
+  try {
+    // "wx": exclusive create — never follows a symlink planted at the tmp name
+    if (opts.sync) {
+      const fd = fs.openSync(tmp, "wx", opts.mode);
+      try { fs.writeFileSync(fd, data); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    } else {
+      fs.writeFileSync(tmp, data, { flag: "wx", ...(opts.mode === undefined ? {} : { mode: opts.mode }) });
+    }
+    if (opts.mode !== undefined) fs.chmodSync(tmp, opts.mode);
+    renameOver(tmp, file);
+  } catch (e) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    throw e;
+  }
+  if (opts.sync) syncDir(dir);
+}

package/src/bridge-holder.ts

@@ -0,0 +1,294 @@
+// bridge-holder.ts — find the bridge's owner, or take the bridge and share it: one module for the three ways a
+// process reaches the plugin.
+//
+// Port 8787 has one owner. Every front-end used to work out for itself whether a daemon already held it, when to
+// open a bridge of its own, whether to publish that bridge on the daemon socket, and how to let go — three times,
+// with three startup orders and teardowns (the CLI's one-shot session, `dtwin serve`, and the MCP server, whose
+// version kept five module globals, an in-flight memo against a double bind, and read the daemon's frame counters
+// across the seam to decide whether it could exit). Here it is once. A front-end picks a LIFETIME and supplies its
+// events; the holder hides probe-or-bind, publishing on the daemon socket, whether others used it, the idle
+// window, and releasing exactly once.
+//
+//   one-shot  a CLI command: the running daemon when there is one, else a bridge of its own for this command only
+//             (never shared — a process that finds the port held exits on it, as it always did). release() closes it.
+//   serve     `dtwin serve`: must be the owner (a live daemon is refused, naming --stop), publishes its bridge on the
+//             daemon socket with the settings' idle window, and owns the process's signals (daemon.ts serve).
+//   session   the MCP server: lives as long as its MCP client. Re-resolves the owner whenever it does not hold the
+//             bridge itself (a daemon it routed through may have gone — that session closed, `dtwin stop`), so it
+//             takes the bridge over when the owner goes. Holding it, it publishes it with no idle window; when the
+//             client leaves (clientLeft) it releases at once unless OTHER processes have used the socket, and then
+//             keeps serving them with the settings' idle window. A held port is the caller's error, never an exit:
+//             the process is the user's stdio session.
+//
+// What the front-ends keep: their own events (the CLI's command finishing, the MCP server's stdin / stdout errors
+// / signals) turned into release() or clientLeft(), and what to do once `released` settles (exit).
+import { daemonUpstream, ownUpstream, servedBridge } from "./route.ts";
+import type { HeldBridge, Upstream } from "./route.ts";
+import type { DaemonBridge, DaemonConnection, DaemonStatusView, ServeHandle } from "./daemon.ts";
+import * as daemon from "./daemon.ts";
+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";
+
+export type Lifetime = "one-shot" | "serve" | "session";
+
+/** What the holder needs of a bridge it opens: what the route's adapters use (HeldBridge) and when it is bound.
+ *  server-core's createBridge result is one; a suite passes a fake. It is given the settings with their token
+ *  committed (commitToken): it only admits with it. */
+export type OwnBridge = HeldBridge & Pick<Bridge, "listening">;
+export type BridgeFactory = (settings: BridgeSettings, opts: BridgeOptions) => OwnBridge;
+
+/** What the holder needs of the daemon socket, bound to one resolved address (daemonSide). */
+export interface DaemonSide {
+  /** the live daemon's connection, or null */
+  connect(): Promise<DaemonConnection | null>;
+  status(): Promise<DaemonStatusView | null>;
+  /** throws when a live daemon (or a foreign holder) already has the socket */
+  assertNoDaemon(): Promise<string>;
+  serve(bridge: DaemonBridge, o: { idleMs: number; signals: boolean; log: (m: string) => void }): Promise<ServeHandle>;
+}
+
+/** The daemon module, bound to the address `settings` resolve to (settings.ts daemonAddressOf) — resolved here, once. */
+export function daemonSide(settings: BridgeSettings): DaemonSide {
+  const at = daemonAddressOf(settings);
+  return {
+    connect: () => daemon.connect(at),
+    status: () => daemon.status(at),
+    assertNoDaemon: () => daemon.assertNoDaemon(at),
+    serve: (bridge, o) => daemon.serve(bridge, at, o),
+  };
+}
+
+export interface HolderDeps {
+  settings: BridgeSettings;
+  createBridge: BridgeFactory;
+  /** the daemon side for the settings as they are NOW (daemonSide): a token this process mints and saves keys every
+   *  later lookup, so a first-run session still finds the daemon a later `dtwin serve` names from that token */
+  daemon: (settings: BridgeSettings) => DaemonSide;
+  /** the front-end's log line (stderr) */
+  log: (m: string) => void;
+}
+
+/** Where this process is in relation to the bridge, for a status line. */
+export type Held =
+  | { kind: "none" }
+  | { kind: "daemon"; sock: string }
+  | { kind: "own"; port: number; sock: string | null };
+
+export interface Holder {
+  /** Where requests go now: a daemon's socket, or the bridge this process holds — resolved as the lifetime says.
+   *  Concurrent calls share one resolution (two first calls never both bind). */
+  upstream(): Promise<Upstream>;
+  /** session: the client has gone. Releases now unless other processes have used the shared socket; then serves
+   *  them on, and releases after the settings' idle window without one. Once only; a no-op for other lifetimes. */
+  clientLeft(how: string): void;
+  /** Let go of everything this process holds, exactly once: the served socket (its forwarded requests aborted, its
+   *  file unlinked) and the bridge (a cancel frame for every request still in flight). `why` is logged when given. */
+  release(why?: string): void;
+  /** Settles with the reason once the holder has let go — release(), clientLeft, `dtwin stop`, the idle shutdown. */
+  readonly released: Promise<string>;
+  held(): Held;
+}
+
+const RELEASED = "the bridge has been released";
+
+export function bridgeHolder(lifetime: Lifetime, deps: HolderDeps): Holder {
+  const { log } = deps;
+  // The settings, with their token committed before our first bind (commitToken): a token minted then is saved from
+  // then on, and every later bridge and daemon lookup uses it as saved — a rebind must not write it over a file rotated
+  // since, nor print it again. Committed once, even when that first bind then fails (a held port).
+  let settings = deps.settings;
+  let committed = false;
+  // The daemon side for the settings as they are now: resolved once per settings value — again only after a commit
+  // changed the token it is keyed on.
+  let sideOf: { settings: BridgeSettings; side: DaemonSide } | null = null;
+  const side = (): DaemonSide => {
+    if (sideOf?.settings !== settings) sideOf = { settings, side: deps.daemon(settings) };
+    return sideOf.side;
+  };
+  // The bridge this process holds, its adapter, and the socket it is published on (null until serve() bound it).
+  let own: { bridge: OwnBridge; up: Upstream; close: () => void } | null = null;
+  let served: ServeHandle | null = null;
+  let resolving: Promise<Upstream> | null = null;
+  let viaDaemon: string | null = null;
+  let gone = false; // session: the client has left
+  let done = false;
+  let settle: (why: string) => void = () => {};
+  const released = new Promise<string>((r) => { settle = r; });
+  const finish = (why: string): void => {
+    if (done) return;
+    done = true;
+    settle(why);
+  };
+
+  // Open a bridge of our own. `survive`: a held port is this call's error (session), not an exit (one-shot, serve
+  // — server-core prints the fix and exits 1 when no onListenError is given).
+  async function bind(survive: boolean): Promise<OwnBridge> {
+    if (!committed) {
+      committed = true;
+      const c = commitToken(settings);
+      settings = c.settings;
+      for (const line of c.notice) log(line);
+    }
+    let failed: (e: Error) => void = () => {};
+    const bindFailed = new Promise<never>((_, reject) => { failed = reject; });
+    const b = deps.createBridge(settings, survive ? { onListenError: (e) => failed(e) } : {});
+    try {
+      await (survive ? Promise.race([b.listening, bindFailed]) : b.listening);
+    } catch (e) {
+      b.close();
+      throw e;
+    }
+    // Released while it was binding (the command finished, a signal, the client left): nobody is left to use it.
+    if (done) { b.close(); throw new Error(RELEASED); }
+    return b;
+  }
+
+  // Hold `b`: its adapter, and a close that forgets it — so a session re-resolves instead of talking to a closed
+  // server. Closed from outside (`dtwin stop`, the idle shutdown) after the client has gone, nothing is left to do.
+  function hold(b: OwnBridge): NonNullable<typeof own> {
+    const up = ownUpstream(b);
+    let closed = false;
+    const close = (): void => {
+      if (closed) return;
+      closed = true;
+      own = null;
+      served = null;
+      resolving = null;
+      b.close();
+      if (lifetime === "serve") finish("the daemon shut down");
+      else if (gone) release("the shared bridge was stopped after the MCP client went away — exiting");
+    };
+    own = { bridge: b, up, close };
+    return own;
+  }
+
+  // Publish the held bridge on the daemon socket. `idleMs` 0 for a session while its client is here.
+  function publish(b: OwnBridge, close: () => void, idleMs: number, signals: boolean): Promise<ServeHandle> {
+    return side().serve(servedBridge(b, close), { idleMs, signals, log });
+  }
+
+  // A daemon found: its adapter (listings from its status, at the place it was found).
+  async function viaDaemonOr(): Promise<Upstream | null> {
+    const d = side();
+    const via = await d.connect();
+    if (done) throw new Error(RELEASED);
+    if (!via) { viaDaemon = null; return null; }
+    viaDaemon = via.sock;
+    return daemonUpstream(via, () => d.status());
+  }
+
+  async function resolveSession(): Promise<Upstream> {
+    if (own) return own.up;
+    const via = await viaDaemonOr();
+    if (via) return via;
+    let b: OwnBridge;
+    try {
+      b = await bind(true);
+    } catch (e) {
+      throw gone && errMsg(e) === RELEASED ? new Error("the MCP client went away before the bridge was up") : e;
+    }
+    const mine = hold(b);
+    publish(b, mine.close, 0, false).then(
+      (h) => {
+        // Gone (or this bridge stopped) while the socket was binding: take it down again at once.
+        if (own !== mine || done) { h.shutdown(); return; }
+        served = h;
+      },
+      (e) => log("not sharing the bridge with other sessions: " + errMsg(e)),
+    );
+    return mine.up;
+  }
+
+  async function resolveOneShot(): Promise<Upstream> {
+    return (await viaDaemonOr()) ?? hold(await bind(false)).up;
+  }
+
+  async function resolveServe(): Promise<Upstream> {
+    // The already-running probe FIRST: binding with a daemon already up is an EADDRINUSE exit naming "another dtwin
+    // bridge" — the right answer is the daemon's own refusal, which names --stop. serve() probes again right before
+    // listening (the race is handled there). No saved token yet (Windows, first run): nothing can be serving a pipe
+    // named from a token nobody saved, and bind() commits the one it mints — the socket is then named from it.
+    try { await side().assertNoDaemon(); } catch (e) { if (errMsg(e) !== daemon.NO_DAEMON_TOKEN) throw e; }
+    if (done) throw new Error(RELEASED);
+    const b = await bind(false);
+    const mine = hold(b);
+    let h: ServeHandle;
+    try {
+      h = await publish(b, mine.close, settings.idleMs, true);
+    } catch (e) {
+      // Another daemon won the race to the socket: this bridge serves nobody. Let it go without "the daemon shut down".
+      own = null;
+      b.close();
+      throw e;
+    }
+    // Released while the socket was binding: release() closed the bridge (hold()'s close); take the socket down too.
+    if (done) { h.shutdown(); throw new Error(RELEASED); }
+    served = h;
+    return mine.up;
+  }
+
+  const resolveFor = { "one-shot": resolveOneShot, serve: resolveServe, session: resolveSession }[lifetime];
+
+  function release(why?: string): void {
+    if (done) return;
+    if (why) log(why);
+    // finish() first: the shutdown below closes the bridge through hold()'s close, which must not log a second reason.
+    finish(why ?? "released");
+    const s = served;
+    served = null;
+    const o = own;
+    if (s) s.shutdown(); // aborts its forwarded requests, unlinks the socket, closes the bridge (hold()'s close)
+    if (o) o.close();
+  }
+
+  function clientLeft(how: string): void {
+    if (lifetime !== "session" || gone || done) return;
+    gone = true;
+    const s = served;
+    if (!own || !s) return release(`the MCP client went away (${how}) — exiting`);
+    const a = s.activity();
+    if (a.frames === 0) return release(`the MCP client went away (${how}) and no other dtwin command or session used the shared bridge — closing it and exiting`);
+    const ms = settings.idleMs;
+    // Already quiet for the whole window (and nothing in flight): idleOut's check-at-once would shut it down right
+    // away, so say that instead of "still serving".
+    if (ms && a.inFlight === 0 && a.idleForMs >= ms) {
+      return release(`the MCP client went away (${how}); other dtwin commands/sessions used this shared bridge (${a.frames} request(s)), but none in the last ${humanMs(ms)} (FIGMA_DAEMON_IDLE_MIN) — closing it and exiting`);
+    }
+    const used = `other dtwin commands/sessions use this shared bridge (${a.frames} request(s) so far)`;
+    log(ms
+      ? `the MCP client went away (${how}); ${used} — still serving it, shutting down after ${humanMs(ms)} without one (FIGMA_DAEMON_IDLE_MIN)`
+      : `the MCP client went away (${how}); ${used} — still serving it, and it never shuts down on its own (${idleOffWhy(settings.idleRaw)}) — stop it with dtwin stop`);
+    // Its shutdown closes the bridge through hold()'s close, which releases.
+    s.idleOut(ms);
+  }
+
+  return {
+    upstream() {
+      if (done) return Promise.reject(new Error(RELEASED));
+      // One resolution shared by every caller while it is in flight, so concurrent first calls never both bind.
+      // one-shot and serve keep it for good. A session keeps it only while it holds the bridge (hold()'s close drops
+      // it): a daemon route or a failure is re-resolved on the next call — that owner may have gone since.
+      if (lifetime !== "session") return (resolving ??= resolveFor());
+      if (own) return Promise.resolve(own.up);
+      return (resolving ??= resolveFor().finally(() => { if (!own) resolving = null; }));
+    },
+    clientLeft,
+    release,
+    released,
+    held(): Held {
+      if (own) return { kind: "own", port: own.bridge.port, sock: served?.sock ?? null };
+      return viaDaemon ? { kind: "daemon", sock: viaDaemon } : { kind: "none" };
+    },
+  };
+}
+
+// Why the idle window is 0: the variable says 0, or it is not a usable number of minutes (idleMsFromEnv turns an
+// unparsable or negative value into 0 = off, as it always has) — name which, with the raw value.
+function idleOffWhy(raw: string | undefined): string {
+  const v = (raw ?? "").trim();
+  return v !== "" && Number(v) === 0
+    ? `FIGMA_DAEMON_IDLE_MIN=${v}`
+    : `FIGMA_DAEMON_IDLE_MIN=${JSON.stringify(raw ?? "")} is not a number of minutes above 0, which turns the idle shutdown off`;
+}