@nimbus-sh/worker 0.4.0 → 0.6.0

package/dist/session/ws.js

@@ -40,6 +40,7 @@ import { handleFsWatchSubscribe, handleFsWatchUnsubscribe, cleanupFsWatchOnClose
 import { parseProcessLogClientFrame } from '@nimbus-sh/core/runtime/process-io-protocol.js';
 import { applyProcessClientFrame } from '@nimbus-sh/core/runtime/process-input-routing.js';
 import { z } from 'zod/v4';
+import { clearShellSocketStamp, noteShellSocketActivity } from './shell-socket.js';
 import { PRIOR_GENERATION_EXIT_REASON } from './rpc.js';
 /**
  * Snapshot the live Shell state and write it through to DO SQLite
@@ -151,6 +152,12 @@ export async function wsMessage(self, ws, message) {
             await routeProcessLogClientMessage(self, ws, attach, message);
             return;
         }
+        // A frame arriving is the peer proving it is still on this socket.
+        // The stamp goes in the attachment because isolate memory does not
+        // survive hibernation and the /ws upgrade has to read it afterwards.
+        // Rate-limited inside; see src/session/shell-socket.ts.
+        if (attach?.kind === 'shell')
+            noteShellSocketActivity(ws);
         const data = typeof message === 'string' ? message : dec.decode(message);
         const value = JSON.parse(data);
         // file-tree-watch (2026-05-15): handle fs-watch-* on this WS BEFORE
@@ -304,6 +311,11 @@ export async function wsClose(self, ws, _code, _reason, _wasClean) {
     // wrangler dev) + long-running facets must still survive the
     // terminal reconnect (see 607e472 — do NOT kill running processes
     // here). Only reap per-tab state.
+    // The runtime says this socket is finished, so it no longer holds the
+    // terminal. Drop its liveness stamp before anything else: the frame
+    // that triggered this close stamped it moments ago, and leaving that
+    // behind would make the reconnect look like a second tab.
+    clearShellSocketStamp(ws);
     // ── Phase 3 B'.1: transitionTo('drained') ──────────────────────────
     // The Track B' state-machine transition. Persist final shell
     // state + record a recovery_event BEFORE we null the in-memory
@@ -352,10 +364,9 @@ export async function wsClose(self, ws, _code, _reason, _wasClean) {
     // upgrade calls terminal.attach(newWs) to swap in the new socket.
     //
     // Pre-B'.5 we nulled these three fields to avoid two-tab cross-
-    // wiring (the 409 in nimbus-session-routes.ts:97 protected against
-    // overwriting an active shell). With phase=drained surfaced on the
-    // host, the /ws handler can disambiguate "warm session waiting for
-    // rejoin" (warmJoin path) from "active session busy" (still 409).
+    // wiring, which cost every reconnect a full rebuild. The upgrade now
+    // reads the sockets instead: a shell socket a peer still holds is the
+    // busy session it refuses, and this one is closing.
     // Reset the one-shot "wrangler alias" banner so a reconnecting user
     // sees it again — terminal-lifetime state, not session-lifetime.
     self.wranglerAliasBannerShown = false;
@@ -387,6 +398,10 @@ export async function wsError(self, ws, _error) {
         catch { /* best-effort */ }
         return;
     }
+    // Same reasoning as wsClose: this socket stops holding the terminal
+    // here. It matters more on this path, because the handler that just
+    // blew the 5-s cap is the one that stamped the socket.
+    clearShellSocketStamp(ws);
     // ── Phase 3 B'.1: transitionTo('drained') ──────────────────────────
     // Same architectural step as wsClose: persist shell state + record
     // a drained event before nulling. wsError is a different physical

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/worker",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Nimbus runtime package for Cloudflare Workers, re-exported publicly through @nimbus-sh/sdk/worker.",
   "keywords": [
     "cloudflare",
@@ -84,9 +84,9 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^2.0.41",
-    "@nimbus-sh/core": "^0.6.0",
-    "@nimbus-sh/fabric": "^0.2.0",
-    "@nimbus-sh/platform": "^0.1.0",
+    "@nimbus-sh/core": "^0.8.0",
+    "@nimbus-sh/fabric": "^0.4.0",
+    "@nimbus-sh/platform": "^0.3.0",
     "@renovatebot/pep440": "^5.0.0",
     "ai": "^6.0.182",
     "clean-git-ref": "^2.0.1",

package/public/_assets/runtime/{node-shims-fea906843f6d594e.js → node-shims-9e1380d9ee430fcc.js}

@@ -324,7 +324,19 @@ const __BufferMod = (() => {
 
   function alloc(n, fill) { const a = new Uint8Array(n); if (fill !== undefined) a.fill(typeof fill === "number" ? fill : 0); return _wrap(a); }
   function allocUnsafe(n) { return _wrap(new Uint8Array(Number(n) || 0)); }
-  function isBuffer(o) { return o instanceof Uint8Array && typeof o.toString === "function" && o.__isBuffer; }
+  // Marker check plus native-brand recognition: forwarded node:* builtins
+  // (zlib streams and results, crypto) hand back the host realm's own Buffer
+  // instances, which carry no __isBuffer marker. Their constructor brand is
+  // the closest cross-realm equivalent of Node's instanceof check, so
+  // Buffer.isBuffer stays truthful across the shim/native boundary instead
+  // of rejecting genuine host Buffers. Always returns a boolean (the old
+  // single-expression form leaked an undefined when the marker was absent).
+  function isBuffer(o) {
+    if (!(o instanceof Uint8Array)) return false;
+    if (o.__isBuffer) return true;
+    const ctor = o.constructor;
+    return typeof ctor === "function" && ctor.name === "Buffer";
+  }
   function concat(bufs, len) {
     const total = len ?? bufs.reduce((s, b) => s + b.length, 0);
     const r = new Uint8Array(total); let off = 0;
@@ -6884,6 +6896,21 @@ const __processMod = {
   },
   platform: "linux", arch: "x64",
   version: "v22.19.0", versions: {"node":"22.19.0","v8":"12.4.254.21","modules":"127"},
+  features: Object.freeze({
+    inspector: false,
+    debug: false,
+    uv: false,
+    ipv6: true,
+    tls_alpn: true,
+    tls_sni: true,
+    tls_ocsp: false,
+    tls: true,
+    openssl_is_boringssl: true,
+  }),
+  getBuiltinModule: (specifier) => {
+    const key = String(specifier).replace(/^node:/, "");
+    return Object.prototype.hasOwnProperty.call(builtins, key) ? builtins[key] : undefined;
+  },
   execPath: "/usr/local/bin/node",
   execArgv: [],
   pid: 1, ppid: 0, title: "node",
@@ -7443,10 +7470,295 @@ const __nimbusFacetProvidedPackages = new Set(["undici"]);
 // timers.setInterval(...)), which clack's spinner — used by
 // create-cloudflare — triggers.
 builtins.timers = { setTimeout: globalThis.setTimeout.bind(globalThis), setInterval: globalThis.setInterval.bind(globalThis), clearTimeout: globalThis.clearTimeout.bind(globalThis), clearInterval: globalThis.clearInterval.bind(globalThis), setImmediate: (fn,...a) => globalThis.setTimeout(fn,0,...a), clearImmediate: globalThis.clearTimeout.bind(globalThis) };
+// ──  zlib ───────────────────────────────────────────────────────────
+//
+// Two runtimes, one surface:
+//   1. Facet templates prepend the static import block
+//      (_shared/real-node-imports.ts), which carries workerd's native
+//      node:zlib — complete at the production compat date: every *Sync
+//      variant, brotli/zstd, crc32, constants, and real streaming create*
+//      factories. Forward verbatim: results are the host realm's own Buffer
+//      instances, and __BufferMod.isBuffer recognizes that brand (see the
+//      Buffer shim), so Buffer checks stay truthful without copying every
+//      result or intercepting stream chunks.
+//   2. Scopes without the import block keep the CompressionStream fallback.
+//      It is async-only by nature; the sync names refuse with an honest,
+//      actionable error instead of pretending.
 builtins.zlib = (() => {
-  function _c(d,a) { const i=typeof d==="string"?new TextEncoder().encode(d):d; return new Response(new Blob([i]).stream().pipeThrough(new CompressionStream(a))).arrayBuffer().then(ab=>__BufferMod.from(new Uint8Array(ab))); }
-  function _d(d,a) { const i=d instanceof Uint8Array?d:new Uint8Array(d); return new Response(new Blob([i]).stream().pipeThrough(new DecompressionStream(a))).arrayBuffer().then(ab=>__BufferMod.from(new Uint8Array(ab))); }
-  return { gzip:(d,o,cb)=>{if(typeof o==="function")cb=o;_c(d,"gzip").then(r=>cb(null,r)).catch(e=>cb(e));}, gunzip:(d,o,cb)=>{if(typeof o==="function")cb=o;_d(d,"gzip").then(r=>cb(null,r)).catch(e=>cb(e));}, deflate:(d,o,cb)=>{if(typeof o==="function")cb=o;_c(d,"deflate").then(r=>cb(null,r)).catch(e=>cb(e));}, inflate:(d,o,cb)=>{if(typeof o==="function")cb=o;_d(d,"deflate").then(r=>cb(null,r)).catch(e=>cb(e));}, gzipSync:()=>{throw new Error("use async gzip()");}, gunzipSync:()=>{throw new Error("use async gunzip()");}, createGzip:()=>new __streamMod.Transform({transform(c,e,cb){_c(c,"gzip").then(r=>cb(null,r)).catch(e=>cb(e));}}), createGunzip:()=>new __streamMod.Transform({transform(c,e,cb){_d(c,"gzip").then(r=>cb(null,r)).catch(e=>cb(e));}}), createDeflate:()=>new __streamMod.Transform({transform(c,e,cb){_c(c,"deflate").then(r=>cb(null,r)).catch(e=>cb(e));}}), createInflate:()=>new __streamMod.Transform({transform(c,e,cb){_d(c,"deflate").then(r=>cb(null,r)).catch(e=>cb(e));}}), constants:{Z_NO_FLUSH:0,Z_PARTIAL_FLUSH:1,Z_SYNC_FLUSH:2,Z_FULL_FLUSH:3,Z_FINISH:4,Z_BEST_COMPRESSION:9,Z_DEFAULT_COMPRESSION:-1} };
+  const __real = (typeof __real_zlib !== "undefined") ? (__real_zlib.default ?? __real_zlib) : null;
+  if (__real && typeof __real.gzipSync === "function") {
+    const mod = {};
+    // Constants, lookup tables, crc32, and the stream factories/classes pass
+    // through bound to the native module (capitalized names are classes —
+    // binding would strip their prototype and break `new`).
+    for (const k of Object.keys(__real)) {
+      const v = __real[k];
+      mod[k] = (typeof v === "function" && /^[a-z]/.test(k)) ? v.bind(__real) : v;
+    }
+    if (__real.promises) mod.promises = __real.promises;
+    mod.default = mod;
+    return mod;
+  }
+  function _c(i,a) { return new Response(new Blob([i]).stream().pipeThrough(new CompressionStream(a))).arrayBuffer().then(ab=>__BufferMod.from(new Uint8Array(ab))); }
+  // Decompression is driven by hand rather than piped: feeding and draining
+  // run together, because a write only completes while somebody reads.
+  async function _d(i,a) {
+    const codec = _openCodec("decompress", a);
+    const chunks = [];
+    let failure = null;
+    const record = (reason) => { if (!failure) failure = { reason }; };
+    const drain = (async () => {
+      for (;;) {
+        const next = await codec.reader.read();
+        if (next.done) return;
+        chunks.push(next.value);
+      }
+    })().catch(record);
+    const feed = (async () => {
+      await codec.writer.write(i);
+      await codec.writer.close();
+    })().catch(record);
+    await Promise.all([drain, feed]);
+    if (failure) throw _decompressFailure(failure.reason);
+    return __BufferMod.from(_concat(chunks));
+  }
+  function _syncRefusal(name, asyncName) {
+    const e = new Error("zlib." + name + ": synchronous compression is not available on this runtime (no native node:zlib in scope). Use the async zlib." + asyncName + "(data, callback) form.");
+    e.code = "ERR_ZLIB_SYNC_UNAVAILABLE";
+    throw e;
+  }
+  // Node accepts strings, ArrayBuffers, and any ArrayBufferView; one funnel
+  // yields a byte-addressed Uint8Array over the caller's own region —
+  // byteOffset/byteLength preserved, element values never reinterpreted.
+  function _u8(d) {
+    if (typeof d === "string") return new TextEncoder().encode(d);
+    if (d instanceof Uint8Array) return d;
+    if (ArrayBuffer.isView(d)) return new Uint8Array(d.buffer, d.byteOffset, d.byteLength);
+    return new Uint8Array(d);
+  }
+  // Node splits decompression failures two ways, and the engine's own
+  // failure is the only thing that can tell them apart: an input that ran
+  // out is Z_BUF_ERROR / errno -5, everything else — bad header, bad block,
+  // and a checksum or length trailer that only fails once the member is
+  // complete — is Z_DATA_ERROR / errno -3. Which side of a write or close
+  // the failure lands on says nothing about that, so it is not consulted.
+  function _zdata(e) {
+    const err = new Error(e instanceof Error && e.message ? e.message : String(e));
+    err.code = "Z_DATA_ERROR";
+    err.errno = -3;
+    err.cause = e;
+    return err;
+  }
+  function _zbuf(e) {
+    const err = new Error("unexpected end of file");
+    err.code = "Z_BUF_ERROR";
+    err.errno = -5;
+    if (e != null) err.cause = e;
+    return err;
+  }
+  function _isUnexpectedEnd(e) {
+    const m = e instanceof Error && typeof e.message === "string" ? e.message : String(e);
+    return /unexpected end|end of (?:file|input|stream)|premature|truncated|\bEOF\b/i.test(m);
+  }
+  function _decompressFailure(e) { return _isUnexpectedEnd(e) ? _zbuf(e) : _zdata(e); }
+  function _destroyedWrite() {
+    const e = new Error("Cannot call write after a stream was destroyed");
+    e.code = "ERR_STREAM_DESTROYED";
+    return e;
+  }
+  // Node throws synchronously rather than deferring a callback that is not
+  // there; this surface has no promise form to fall back on.
+  function _invalidCallback(v) {
+    const got = v === undefined ? "undefined"
+      : v === null ? "null"
+      : typeof v === "object" ? "an instance of " + ((v.constructor && v.constructor.name) || "Object")
+      : "type " + typeof v + " (" + String(v) + ")";
+    const e = new TypeError('The "callback" argument must be of type function. Received ' + got);
+    e.code = "ERR_INVALID_ARG_TYPE";
+    return e;
+  }
+  // Node's Unzip contract sniffs the wrapper itself: gzip magic or zlib.
+  function _isGzip(u8) { return u8.length >= 2 && u8[0] === 0x1f && u8[1] === 0x8b; }
+  function _concat(chunks) {
+    let n = 0;
+    for (const c of chunks) n += c.length;
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const c of chunks) { out.set(c, o); o += c.length; }
+    return out;
+  }
+  function _process(mode, fmt, input) {
+    const algo = mode === "compress" ? fmt : (fmt || (_isGzip(input) ? "gzip" : "deflate"));
+    return mode === "compress" ? _c(input, algo) : _d(input, algo);
+  }
+  function _async(mode, fmt) {
+    return (d, o, cb) => {
+      const callback = typeof o === "function" ? o : cb;
+      if (typeof callback !== "function") throw _invalidCallback(callback);
+      // Two arms, not .then().catch(): a callback that throws on success must
+      // not be handed its own exception as a second, failed invocation.
+      _process(mode, fmt, _u8(d)).then(
+        (r) => callback(null, r),
+        (e) => callback(e instanceof Error ? e : new Error(String(e))),
+      );
+    };
+  }
+  // Live codec per Transform lifetime: every write feeds one real
+  // CompressionStream/DecompressionStream writer (its queue serializes
+  // ordering; the write promise settles before the callback), a reader pump
+  // relays output as it is produced instead of accumulating the payload,
+  // and flush closes the writer then awaits full drain before completing.
+  // Chunks are copied so later caller mutations cannot reach the codec, and
+  // createUnzip holds copies only until two bytes decide the wrapper.
+  function _openCodec(openMode, openAlgo) {
+    const cs = openMode === "compress" ? new CompressionStream(openAlgo) : new DecompressionStream(openAlgo);
+    return { writer: cs.writable.getWriter(), reader: cs.readable.getReader() };
+  }
+  // The legacy Readable has no resume notification, so room below the
+  // high-water mark is observed by yielding to the task queue until the
+  // consumer drains or the stream is destroyed.
+  async function _drainRoom(stream) {
+    while (
+      stream._readableState &&
+      !stream._readableState.destroyed &&
+      stream.readableLength >= stream._readableState.highWaterMark
+    ) {
+      await new Promise((tick) => setTimeout(tick, 0));
+    }
+    // True when the wait ended because the stream went away, not because
+    // the consumer made room.
+    return !!(stream._readableState && stream._readableState.destroyed);
+  }
+  function _streamFactory(factoryMode, fmt) {
+    return () => {
+      let writer = null;
+      let reader = null;
+      let drained = Promise.resolve();
+      let pumpFailure = null;
+      let algo = fmt;
+      let held = [];
+      let heldLen = 0;
+      let destroyed = false;
+      const t = new __streamMod.Transform({
+        transform: async (chunk, _enc, cb) => {
+          try {
+            if (destroyed) return cb(_destroyedWrite());
+            const bytes = _u8(chunk).slice();
+            let feed = bytes;
+            if (!writer) {
+              if (fmt === null && heldLen + bytes.length < 2) {
+                held.push(bytes);
+                heldLen += bytes.length;
+                return cb();
+              }
+              if (heldLen > 0) feed = _concat([...held, bytes]);
+              held = [];
+              heldLen = 0;
+              if (fmt === null) algo = _isGzip(feed) ? "gzip" : "deflate";
+              start();
+            }
+            await writer.write(feed);
+            cb();
+          } catch (e) {
+            cb(destroyed ? _destroyedWrite() : factoryMode === "decompress" ? _decompressFailure(e) : e);
+          }
+        },
+        flush: async (cb) => {
+          try {
+            if (destroyed) return cb(_destroyedWrite());
+            if (!writer) {
+              if (factoryMode !== "compress") {
+                // Nothing was ever fed: the input ended before a member
+                // began, which is Node's unexpected-end buffer error rather
+                // than corrupt data. No codec is invented to hide it.
+                return cb(_zbuf(null));
+              }
+              start();
+            }
+            await writer.close();
+            await drained;
+            cb(pumpFailure);
+          } catch (e) {
+            if (pumpFailure) return cb(pumpFailure);
+            if (destroyed) return cb(_destroyedWrite());
+            cb(factoryMode === "decompress" ? _decompressFailure(e) : e);
+          }
+        },
+      });
+      // Every destroy exit fires 'close' on the custom Transform — even when
+      // the pump sits parked inside reader.read() on truncated input that can
+      // never decode. Waking there is immediate: cancel settles the parked
+      // read, abort fails queued writes, and writes arriving after destroy
+      // report ERR_STREAM_DESTROYED instead of silent acceptance.
+      t.on("close", () => {
+        destroyed = true;
+        _releaseCodec();
+      });
+      // One cleanup path for every destroy exit: cancel the readable side,
+      // abort the writable side, and stop the pump.
+      function _releaseCodec() {
+        if (reader) reader.cancel().catch(() => {});
+        if (writer) writer.abort().catch(() => {});
+      }
+      function start() {
+        const opened = _openCodec(factoryMode, algo);
+        writer = opened.writer;
+        reader = opened.reader;
+        drained = (async () => {
+          try {
+            for (;;) {
+              // A destroy can land while a read is in flight; check on both
+              // sides so nothing buffers after the stream went away.
+              if (destroyed) return _releaseCodec();
+              const next = await reader.read();
+              if (destroyed) return _releaseCodec();
+              if (next.done) {
+                return;
+              }
+              // Backpressure: once push reports pressure, park the pump and
+              // do not read again until the consumer drains below the
+              // high-water mark. The pending writer.write promise then holds
+              // the transform callback, so producer writes stop resolving
+              // instead of accumulating. A destroy while parked releases the
+              // codec through the close hook above.
+              if (!t.push(__BufferMod.from(next.value))) {
+                if (await _drainRoom(t)) return _releaseCodec();
+              }
+            }
+          } catch (e) {
+            pumpFailure = factoryMode === "decompress"
+              ? _decompressFailure(e)
+              : (e instanceof Error ? e : new Error(String(e)));
+          }
+        })();
+      }
+      return t;
+    };
+  }
+  return {
+    gzip: _async("compress", "gzip"),
+    gunzip: _async("decompress", "gzip"),
+    deflate: _async("compress", "deflate"),
+    inflate: _async("decompress", "deflate"),
+    deflateRaw: _async("compress", "deflate-raw"),
+    inflateRaw: _async("decompress", "deflate-raw"),
+    unzip: _async("decompress", null),
+    gzipSync: (d, o) => _syncRefusal("gzipSync", "gzip"),
+    gunzipSync: (d, o) => _syncRefusal("gunzipSync", "gunzip"),
+    deflateSync: (d, o) => _syncRefusal("deflateSync", "deflate"),
+    inflateSync: (d, o) => _syncRefusal("inflateSync", "inflate"),
+    deflateRawSync: (d, o) => _syncRefusal("deflateRawSync", "deflateRaw"),
+    inflateRawSync: (d, o) => _syncRefusal("inflateRawSync", "inflateRaw"),
+    unzipSync: (d, o) => _syncRefusal("unzipSync", "unzip"),
+    createGzip: _streamFactory("compress", "gzip"),
+    createGunzip: _streamFactory("decompress", "gzip"),
+    createDeflate: _streamFactory("compress", "deflate"),
+    createInflate: _streamFactory("decompress", "deflate"),
+    createDeflateRaw: _streamFactory("compress", "deflate-raw"),
+    createInflateRaw: _streamFactory("decompress", "deflate-raw"),
+    createUnzip: _streamFactory("decompress", null),
+    constants: { Z_NO_FLUSH: 0, Z_PARTIAL_FLUSH: 1, Z_SYNC_FLUSH: 2, Z_FULL_FLUSH: 3, Z_FINISH: 4, Z_BEST_COMPRESSION: 9, Z_DEFAULT_COMPRESSION: -1 },
+  };
 })();
 builtins.readline = (() => {
   function emitKeypressEvents(stream) {
@@ -8280,9 +8592,11 @@ function __resolveImportsField(name, fromDir) {
 function __mkCompiledFn(code) {
   const reFn = /(?:^|\n|;)\s*(?:const|let|var)\s+__filename\s*=/m;
   const reDn = /(?:^|\n|;)\s*(?:const|let|var)\s+__dirname\s*=/m;
+  const reRequire = /(?:^|\n|;)\s*(?:const|let|var)\s+require\s*=/m;
   const fnName = reFn.test(code) ? "__filename__nimbus_unused" : "__filename";
   const dnName = reDn.test(code) ? "__dirname__nimbus_unused"  : "__dirname";
-  return new Function("exports", "require", "module", fnName, dnName, code);
+  const requireName = reRequire.test(code) ? "require__nimbus_unused" : "require";
+  return new Function("exports", requireName, "module", fnName, dnName, code);
 }
 
 function __exportsTarget(mod) {
@@ -8361,6 +8675,7 @@ function __loadModule(resolvedPath) {
   };
   scopedRequire.cache = __moduleCache;
   scopedRequire.main = __require.main;
+  mod.require = scopedRequire;
 
   // X.5-M3: thread currently-loading module path through globalThis so the
   // URL shim null-base fallback (in node-shims url module) can compose

package/public/s/index.html

@@ -1835,6 +1835,23 @@
       }
     }
 
+    function previewNavigation(url) {
+      try {
+        const parsed = new URL(url, location.origin);
+        if (!parsed.searchParams.has('nimbus_token')) {
+          return { url, attachUrl: null, attachPending: false };
+        }
+        parsed.searchParams.delete('nimbus_token');
+        return {
+          url: parsed.href,
+          attachUrl: url,
+          attachPending: true,
+        };
+      } catch {
+        return { url, attachUrl: null, attachPending: false };
+      }
+    }
+
     function absolutePreviewUrl(url) {
       return new URL(url, location.origin).href;
     }
@@ -1919,6 +1936,39 @@
       return ensurePreviewTab(appTabFor('vite')).id;
     }
 
+    function previewFrameOwnsAttach(tab) {
+      if (!previewFrame || !tab.attachUrl) return false;
+      const src = previewFrame.getAttribute('src') || '';
+      return previewFrame.dataset.previewTabId === tab.id
+        && previewFrame.dataset.previewAttachGeneration === String(tab.attachGeneration || 0)
+        && absolutePreviewUrl(src) === absolutePreviewUrl(tab.attachUrl);
+    }
+
+    function refreshPortPreviewAttach(tab) {
+      if (!tab || tab.type !== 'port' || tab.attachRefresh) return;
+      const generation = (tab.attachGeneration || 0) + 1;
+      tab.attachGeneration = generation;
+      tab.attachPending = true;
+      tab.attachInFlight = false;
+      tab.attachUrl = null;
+      tab.attachRefresh = portPreviewUrl(tab.port).then((minted) => {
+        const current = previewTabs.get(tab.id);
+        if (!current || current.attachGeneration !== generation) return;
+        Object.assign(current, previewNavigation(minted), {
+          attachGeneration: generation,
+          attachInFlight: false,
+          attachRefresh: null,
+        });
+        if (activePreviewTabId === current.id) activatePreviewTab(current.id);
+      }).catch(() => {
+        const current = previewTabs.get(tab.id);
+        if (!current || current.attachGeneration !== generation) return;
+        current.attachPending = false;
+        current.attachInFlight = false;
+        current.attachRefresh = null;
+      });
+    }
+
     function activatePreviewTab(id) {
       const tab = previewTabs.get(id);
       if (!tab) return;
@@ -1937,8 +1987,44 @@
       if (markdownPreview) markdownPreview.classList.remove('active');
       if (previewFrame) {
         previewFrame.style.display = 'block';
-        const next = absolutePreviewUrl(tab.url);
-        if (previewFrame.src !== next) previewFrame.src = tab.url;
+        if (tab.type === 'port' && tab.attachPending) {
+          if (tab.attachInFlight) {
+            if (!previewFrameOwnsAttach(tab)) refreshPortPreviewAttach(tab);
+            setPreviewUrlBar(tab.url);
+            return;
+          }
+          if (!tab.attachUrl) {
+            refreshPortPreviewAttach(tab);
+            setPreviewUrlBar(tab.url);
+            return;
+          }
+          const generation = (tab.attachGeneration || 0) + 1;
+          const attachUrl = tab.attachUrl;
+          tab.attachGeneration = generation;
+          tab.attachInFlight = true;
+          previewFrame.dataset.previewTabId = tab.id;
+          previewFrame.dataset.previewAttachGeneration = String(generation);
+          previewFrame.addEventListener('load', () => {
+            const current = previewTabs.get(tab.id);
+            if (!current
+              || current.attachGeneration !== generation
+              || previewFrame.dataset.previewTabId !== tab.id
+              || previewFrame.dataset.previewAttachGeneration !== String(generation)
+              || absolutePreviewUrl(previewFrame.getAttribute('src') || '') !== absolutePreviewUrl(attachUrl)) {
+              return;
+            }
+            current.attachPending = false;
+            current.attachInFlight = false;
+            current.attachUrl = null;
+            current.attachRefresh = null;
+          }, { once: true });
+          previewFrame.src = attachUrl;
+        } else {
+          previewFrame.dataset.previewTabId = tab.id;
+          delete previewFrame.dataset.previewAttachGeneration;
+          const next = absolutePreviewUrl(tab.url);
+          if (previewFrame.src !== next) previewFrame.src = tab.url;
+        }
       }
       setPreviewUrlBar(tab.url);
     }
@@ -1982,7 +2068,13 @@
 
       for (const entry of visiblePorts) {
         const id = 'port:' + entry.port;
-        const existed = previewTabs.has(id);
+        let existing = previewTabs.get(id);
+        let navigation = {};
+        if (!existing) {
+          const minted = await portPreviewUrl(entry.port);
+          existing = previewTabs.get(id);
+          if (!existing) navigation = previewNavigation(minted);
+        }
         ensurePreviewTab({
           id,
           type: 'port',
@@ -1990,9 +2082,9 @@
           pid: entry.pid,
           label: ':' + entry.port,
           title: 'Port ' + entry.port,
-          url: await portPreviewUrl(entry.port),
+          ...navigation,
           running: true,
-        }, { focusNew: !existed });
+        }, { focusNew: !existing });
       }
 
       if (activeWasRemoved || !activePreviewTabId || !previewTabs.has(activePreviewTabId)) {
@@ -2083,6 +2175,10 @@
         Editor.refreshMarkdownPreview().catch(() => {});
         return;
       }
+      if (active?.type === 'port' && active.attachPending) {
+        refreshPortPreviewAttach(active);
+        return;
+      }
       // Refreshing without a running backend should re-poll the
       // placeholder so users see dev-server status update promptly.
       if (!active || previewFrame.src === 'about:blank') {