@linxin666/dsh-remote-web-ui 0.3.22 → 0.3.24

package/lib/types/public-base.js

@@ -0,0 +1,110 @@
+/**
+ * The public base the pairing fence trusts while a tunnel is not running
+ * (issue #1547).
+ *
+ * The fence reads exactly one public host: `service.publicBaseUrl`. Dropping
+ * it the instant the tunnel leaves `running` makes every public request from
+ * the address still printed in the QR code answer 403 — including
+ * `/api/pair/status`, which exists to be callable before pairing. Two of the
+ * three tunnel modes never lose their host: a named tunnel keeps its fixed
+ * dashboard hostname, and a registered relay keeps its stable subdomain. A
+ * quick tunnel does mint a new hostname on restart, so its previous host is
+ * kept only for a bounded grace window: Cloudflare's edge can still deliver a
+ * connection the phone already opened, and a mobile network reconnects
+ * constantly, so an instant drop turns the phone's retry into a silent 403.
+ * @module @linxin666/dsh-remote-web-ui/public-base
+ */
+/** How long a quick-tunnel host stays trusted after the tunnel stops running. */
+export const PUBLIC_BASE_GRACE_MS = 60_000;
+/**
+ * Owns the trusted public base across tunnel and relay transitions.
+ *
+ * The keeper never decides on its own to widen trust: it only postpones
+ * dropping an address the operator (named/relay) or the tunnel (quick) had
+ * already published, and it forgets it once the tunnel comes back with the
+ * address that actually serves the QR.
+ */
+export class PublicBaseKeeper {
+    onChange;
+    graceMs;
+    mode = 'off';
+    tunnelUrl;
+    relayUrl;
+    graceTimer;
+    /**
+     * @param onChange - receives the base the fence should trust from now on.
+     * @param graceMs - how long a quick-tunnel host outlives its tunnel.
+     */
+    constructor(onChange, graceMs = PUBLIC_BASE_GRACE_MS) {
+        this.onChange = onChange;
+        this.graceMs = graceMs;
+    }
+    /** The base a fresh fence read should trust: the stable relay origin wins. */
+    current() {
+        return this.relayUrl ?? this.tunnelUrl;
+    }
+    /** The mode that currently owns the public base. */
+    setMode(mode) {
+        this.mode = mode;
+    }
+    /** The last quick-tunnel URL, for callers that must announce it downstream. */
+    quickUrl() {
+        return this.tunnelUrl;
+    }
+    /** A relay registration result; undefined withdraws the stable origin. */
+    setRelay(url) {
+        this.relayUrl = url;
+        this.emit();
+    }
+    /** The tunnel reported a live URL: it supersedes any pending grace. */
+    markRunning(url) {
+        this.cancelGrace();
+        this.tunnelUrl = url;
+        this.emit();
+    }
+    /**
+     * The tunnel left `running` (starting again, or failed). A named tunnel's
+     * fixed hostname stays trusted; a quick tunnel's previous host stays
+     * trusted for the grace window, then is dropped if nothing replaced it.
+     */
+    markReconnecting() {
+        if (this.mode === 'named')
+            return;
+        this.startGrace();
+    }
+    /** Re-publish the current base after a branch change that did not move it. */
+    refresh() {
+        this.emit();
+    }
+    /** Forget everything (teardown, or a mode change that stops the tunnel). */
+    reset() {
+        this.cancelGrace();
+        this.tunnelUrl = undefined;
+        this.relayUrl = undefined;
+        this.emit();
+    }
+    /** Cancel the pending grace timer; the keeper keeps its last base. */
+    dispose() {
+        this.cancelGrace();
+    }
+    startGrace() {
+        if (this.tunnelUrl === undefined)
+            return;
+        if (this.graceTimer !== undefined)
+            return;
+        this.graceTimer = setTimeout(() => {
+            this.graceTimer = undefined;
+            this.tunnelUrl = undefined;
+            this.emit();
+        }, this.graceMs);
+    }
+    cancelGrace() {
+        if (this.graceTimer === undefined)
+            return;
+        clearTimeout(this.graceTimer);
+        this.graceTimer = undefined;
+    }
+    emit() {
+        this.onChange(this.current());
+    }
+}

package/lib/types/remote-channel-boot.d.ts

@@ -17,8 +17,11 @@
  * transport hook `__DSH_TRANSPORT__ = { ownsHost: true }` before the
  * connection plugin reads it: the paired remote desktop gets the full
  * settings/credentials/presets surface, and every call still rides the
- * gated /remote channel. The script self-skips on loopback origins and
- * never throws.
+ * gated /remote channel. It finally publishes the official pre-Cordis
+ * upload hook (`__DSH_FILE_UPLOAD__`), because the background upload
+ * transport otherwise runs inside a Web Worker whose own globals the
+ * main-thread rewrite cannot reach (issue #1580). The script self-skips on
+ * loopback origins and never throws.
  * @module @linxin666/dsh-remote-web-ui/remote-channel-boot
  */
 import { type RemoteChannelRules } from './remote-channel-rules.ts';

package/lib/types/remote-channel-boot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-channel-boot.d.ts","sourceRoot":"","sources":["../../src/remote-channel-boot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAoD,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAErH;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,GAAE,kBAAyC,GAAG,MAAM,CA8HrG;AAED,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,2BAA2B,CAAA;AAQzD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAwB,EAAE,MAAM,SAAwB,GAAG,MAAM,CAgB9G;AAED,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,EAAE,MAAuC,CAAA"}
+{"version":3,"file":"remote-channel-boot.d.ts","sourceRoot":"","sources":["../../src/remote-channel-boot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAoD,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAErH;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,GAAE,kBAAyC,GAAG,MAAM,CAqJrG;AAED,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,2BAA2B,CAAA;AAQzD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAwB,EAAE,MAAM,SAAwB,GAAG,MAAM,CAgB9G;AAED,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,EAAE,MAAuC,CAAA"}

package/lib/types/remote-channel-boot.js

@@ -17,8 +17,11 @@
  * transport hook `__DSH_TRANSPORT__ = { ownsHost: true }` before the
  * connection plugin reads it: the paired remote desktop gets the full
  * settings/credentials/presets surface, and every call still rides the
- * gated /remote channel. The script self-skips on loopback origins and
- * never throws.
+ * gated /remote channel. It finally publishes the official pre-Cordis
+ * upload hook (`__DSH_FILE_UPLOAD__`), because the background upload
+ * transport otherwise runs inside a Web Worker whose own globals the
+ * main-thread rewrite cannot reach (issue #1580). The script self-skips on
+ * loopback origins and never throws.
  * @module @linxin666/dsh-remote-web-ui/remote-channel-boot
  */
 import { REMOTE_CHANNEL_BOOT_GLOBAL, REMOTE_CHANNEL_RULES } from "./remote-channel-rules.js";
@@ -140,6 +143,29 @@ export function buildRemoteChannelBootScript(rules = REMOTE_CHANNEL_RULES) {
         'Object.defineProperty(C.prototype,"src",{configurable:true,enumerable:d.enumerable!==false,get:d.get,set:function(v){os.call(this,rr(String(v)))}});' +
         'restores.push(function(){Object.defineProperty(C.prototype,"src",d)})}' +
         'patchSrc(w.HTMLImageElement);patchSrc(w.HTMLScriptElement);patchSrc(w.HTMLIFrameElement);' +
+        // Background uploads must stay on the patched main-thread fetch
+        // (issue #1580). Without this hook @deepseek-ai/dsh-client-file-upload
+        // runs its carrier in a Web Worker, whose own globals no main-thread
+        // patch reaches: the worker's XHR goes straight to <origin>/api/...
+        // without the /remote rewrite and without the device credential, so the
+        // harness browser-auth fence answers 401 and every upload from a paired
+        // browser fails. The hook is the official pre-Cordis seam (the runtime
+        // reads it once in its constructor) and rewriting the worker URL is
+        // provably insufficient - a worker context carries neither the pairing
+        // cookie nor the device header. Hand the runtime the patched fetch
+        // instead: it takes the absolute route URL and a RequestInit, and hands
+        // both to the patched w.fetch, which owns the /remote rewrite AND the
+        // cookieless device header. Delegating the whole decision is deliberate:
+        // rewriting the path here first would make w.fetch see an already-gated
+        // /remote/api path, skip its own rewrite branch, and drop the device
+        // credential that the fence requires.
+        'function uf(u,init){' +
+        'var raw=typeof u==="string"?u:u.href;' +
+        'if(typeof raw!=="string")return of.call(w,u,init||{});' +
+        'var q=new URL(raw,loc.href);' +
+        'if(so(q)&&q.pathname===R.uploadPath)return w.fetch(raw,init||{});' +
+        'return of.call(w,u,init||{})}' +
+        'try{if(w[R.uploadHookGlobal]===undefined)w[R.uploadHookGlobal]={fetch:uf}}catch(e){}' +
         'seat.restore=function(){' +
         'w.fetch=of;' +
         'w.WebSocket=OW;' +

package/lib/types/remote-channel-rules.d.ts

@@ -28,6 +28,10 @@ export interface RemoteChannelRules {
     readonly deviceKey: string;
     /** Query parameter carrying it on WebSocket upgrades. */
     readonly deviceQuery: string;
+    /** Raw upload route the boot hook keeps on the gated channel. */
+    readonly uploadPath: string;
+    /** Page global the pre-Cordis upload hook is published under. */
+    readonly uploadHookGlobal: string;
 }
 /** The live rule set. */
 export declare const REMOTE_CHANNEL_RULES: RemoteChannelRules;

package/lib/types/remote-channel-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-channel-rules.d.ts","sourceRoot":"","sources":["../../src/remote-channel-rules.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kEAAkE;AAClE,eAAO,MAAM,aAAa,YAAY,CAAA;AAEtC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE/E,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,CAAA;AAEpD,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,gBAAyB,CAAA;AAEvD,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,yBAAyB;AACzB,eAAO,MAAM,oBAAoB,EAAE,kBAqBlC,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,gCAAgC,CAAA;AAEvE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;IAC/B,QAAQ,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;IAC7B,eAAe,EAAE,OAAO,CAAA;IACxB,OAAO,IAAI,IAAI,CAAA;CAChB"}
+{"version":3,"file":"remote-channel-rules.d.ts","sourceRoot":"","sources":["../../src/remote-channel-rules.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kEAAkE;AAClE,eAAO,MAAM,aAAa,YAAY,CAAA;AAEtC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE/E,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,CAAA;AAEpD,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,gBAAyB,CAAA;AAEvD,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED,yBAAyB;AACzB,eAAO,MAAM,oBAAoB,EAAE,kBAuBlC,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,gCAAgC,CAAA;AAEvE;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;IAC/B,QAAQ,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAA;IAC7B,eAAe,EAAE,OAAO,CAAA;IACxB,OAAO,IAAI,IAAI,CAAA;CAChB"}

package/lib/types/remote-channel-rules.js

@@ -33,6 +33,8 @@ export const REMOTE_CHANNEL_RULES = {
     deviceHeader: REMOTE_DEVICE_HEADER,
     deviceKey: 'dsh-remote-device',
     deviceQuery: REMOTE_DEVICE_QUERY,
+    uploadPath: '/api/session/uploadFileBinary',
+    uploadHookGlobal: '__DSH_FILE_UPLOAD__',
 };
 /** The window global the boot patch publishes its seat under. */
 export const REMOTE_CHANNEL_BOOT_GLOBAL = '__DSH_REMOTE_CHANNEL_BOOT__';

package/lib/types/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/update.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/update.ts"],"names":[],"mappings":"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"}

package/lib/types/update.js

@@ -11,6 +11,7 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawn } from 'node:child_process';
+import { decodeConsoleBytes } from "./console-output.js";
 /** npm registry base used for version probes. */
 export const NPM_REGISTRY = 'https://registry.npmjs.org';
 /** The family scope every dsh-web package is published under. */
@@ -434,20 +435,12 @@ const WIN_CMD_MISSING_RE = /not recognized as an internal or external command|
 /**
  * Decode process output with tolerant decoding:
  * Defaults to UTF-8; if invalid byte sequences are encountered (common on
- * Windows consoles using code page 936/GBK), falls back to GBK via TextDecoder.
+ * Windows consoles using code page 936/GBK), falls back to the code page that
+ * loses the least text. Bytes are decoded once per whole chunk by the caller's
+ * accumulator — decoding per \`data\` event would split multi-byte characters.
  */
 function decodeProcessChunk(chunk) {
-    try {
-        return new TextDecoder('utf-8', { fatal: true }).decode(chunk);
-    }
-    catch {
-        try {
-            return new TextDecoder('gbk').decode(chunk);
-        }
-        catch {
-            return chunk.toString('utf8');
-        }
-    }
+    return decodeConsoleBytes(chunk);
 }
 /**
  * Bypass for pnpm 11's supply-chain gate: `minimumReleaseAge` (default 24 h)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-remote-web-ui",
   "description": "Scan-to-pair remote access for the dsh web GUI that shares one official interface: a QR beside the settings button pairs phones and PCs into the same Web GUI (a portrait-touch adaptation layer for phones, full desktop on PCs) through one-time tokens and revocable device sessions, with a LAN bind toggle, optional Cloudflare tunnel, and one-click family self-update",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"

package/src/client/index.ts

@@ -39,6 +39,7 @@ import {
 import { FenceNotice } from './FenceNotice.tsx'
 import { reportDailyHeartbeat } from './telemetry.ts'
 import { startMobileAdapt, type RemoteAdaptGlobal } from './mobile-adapt.ts'
+import { installPluginCard } from './plugin-card-seat.ts'
 
 // Portrait-touch adaptation of the official UI: installed under the plugin
 // lifecycle (apply) so disabling the plugin in cordis patch (disabled: true)
@@ -232,25 +233,20 @@ export function apply(ctx: ClientContext): void {
   })
 
   // Plugin configuration card: one staged form over the `remote-web-ui`
-  // settings namespace, contributed to the Web UI plugin group.
+  // settings namespace, contributed to whichever plugin-card seat the running
+  // host declares (the family group's list seat, or the official keyed seat of
+  // the plugin-configuration tab when dsh-web-settings is not installed —
+  // issue #1589).
   const remoteSettings = new RemoteSettingsCardController(settingsScope)
-  ctx.slots.inject('web-ui.plugin.item', () => {
-    try {
-      const unregister = ctx.slots.register({
-        name: 'web-ui.plugin.item',
-        id: 'remote-web-ui',
-        order: 90,
-        locale: NS,
-        inject: () => remoteSettings.inject(),
-      }, RemoteSettingsCard)
-      return () => {
-        remoteSettings.dispose()
-        unregister()
-      }
-    } catch {
-      return () => {}
-    }
+  installPluginCard(ctx, {
+    namespace: REMOTE_WEB_UI_NS,
+    id: 'remote-web-ui',
+    order: 90,
+    locale: NS,
+    inject: () => remoteSettings.inject(),
+    component: RemoteSettingsCard,
   })
+  ctx.effect(() => () => { remoteSettings.dispose() }, 'remote-web-ui: settings card')
 
   // Phone-side boot flow + heartbeats. Loopback pages (the desktop) never
   // heartbeat; the server ignores unpaired heartbeats anyway. Both run only

package/src/client/mobile-adapt.ts

@@ -64,6 +64,12 @@ const EFFORT_BTN_ID = 'dshRemoteEffortPick'
 const COMPACT_CLASS = 'dsh-remote-compact-picker'
 /** Body class while the header actions are seated in the tabs row. */
 const HEADER_SEATED_CLASS = 'dsh-remote-header-seated'
+/**
+ * Width the seated header actions paint over the tabs row, as a CSS variable
+ * on <html>. The row caps its own width with it (see the v80 rules) instead of
+ * reserving the space with padding.
+ */
+const HEADER_RESERVE_VAR = '--dsh-remote-header-actions-reserve'
 /** The two composer picker entries the compact buttons drill into. */
 type PickerKind = 'model' | 'effort'
 /** Locale-dependent fast path for the official picker cells (zh/en). */
@@ -254,6 +260,20 @@ const ADAPT_CSS: readonly string[] = [
   // [class$="_tab"] misses the active tab (its class ends in "_tabActive")
   // — containment so BOTH tabs match.
   '[class$="_header"] [class$="_tabs"] [class*="_tab"]{font-size:12px;white-space:nowrap}',
+  // v80: the tabs row must give the painted actions their width up on its own.
+  // The v67 padding reservation could not do it: the row is a nowrap flex
+  // container, and once the tab labels plus their gaps overflow the reduced
+  // content box the flex items spill over the padding box, so the trailing
+  // tabs render underneath the actions (reported on a phone: a long agent
+  // preset label covered the last tabs). Cap the row against the reserve and
+  // let the labels scroll instead. The value rides a CSS variable on <html>
+  // because the update lands before React re-creates the row node, and an
+  // inline reservation on that node is dropped until the next sync tick.
+  // The 2px bottom padding keeps the active-tab underline inside the clipping
+  // box; the matching negative margin keeps the header height official.
+  `body.${HEADER_SEATED_CLASS} [class$="_header"] [class$="_tabs"]{max-width:max(0px,calc(100% - var(${HEADER_RESERVE_VAR},0px)));overflow-x:auto;overflow-y:hidden;scrollbar-width:none;-webkit-overflow-scrolling:touch;padding-bottom:2px;margin-bottom:-2px}`,
+  `body.${HEADER_SEATED_CLASS} [class$="_header"] [class$="_tabs"]::-webkit-scrollbar{display:none}`,
+  `body.${HEADER_SEATED_CLASS} [class$="_header"] [class$="_tabs"] > [class*="_tab"]{flex:0 0 auto}`,
   // Mobile scope: hide the plugin surfaces that do not fit a phone — the
   // right-hand details column and every desktop-oriented tool surface. The
   // list keys on the L2 semantic roots (data-dsh-plugin, ownership stays
@@ -764,9 +784,14 @@ export function startMobileAdapt(): void {
     let dx = translate !== null ? parseFloat(translate[1] ?? '0') : 0
     let dy = translate !== null ? parseFloat(translate[2] ?? '0') : 0
     const actionsRect = actions.getBoundingClientRect()
-    const tabsRect = tabs.getBoundingClientRect()
-    // Horizontal: the actions' right edge lands on the tabs row's right edge.
-    const rightDiff = tabsRect.right - actionsRect.right
+    // Horizontal: the actions' right edge lands on the header's content edge,
+    // NOT on the tabs row's right edge. The row caps its own width against the
+    // reserve below (v80), so anchoring to the row would let the pair walk
+    // leftwards on every measurement.
+    const headerRect = header.getBoundingClientRect()
+    const headerStyle = getComputedStyle(header)
+    const contentRight = headerRect.right - (parseFloat(headerStyle.paddingRight) || 0) - (parseFloat(headerStyle.borderRightWidth) || 0)
+    const rightDiff = contentRight - actionsRect.right
     if (Math.abs(rightDiff) >= 0.5) dx = Math.round((dx + rightDiff) * 10) / 10
     // Vertical: the actions' text bottom lands on the tab text bottom.
     const tabBottom = textBottom(tabBtn)
@@ -783,17 +808,26 @@ export function startMobileAdapt(): void {
     }
     const next = `translate(${dx}px, ${dy}px)`
     if (actions.style.transform !== next) actions.style.transform = next
-    // Reserve the painted width so the tab labels never slide under it.
+    // Reserve the painted width on the row itself, so the tab labels never
+    // slide under it. The value rides a CSS variable on <html>: React
+    // recreates the row node on re-render, which would drop an inline
+    // reservation until the next sync tick, and until then the labels render
+    // underneath the painted actions.
     const reserve = `${Math.ceil(actionsRect.width) + 8}px`
-    if (tabs.style.paddingRight !== reserve) tabs.style.paddingRight = reserve
+    const rootStyle = document.documentElement.style
+    if (rootStyle.getPropertyValue(HEADER_RESERVE_VAR) !== reserve) rootStyle.setProperty(HEADER_RESERVE_VAR, reserve)
   }
 
   function unseatHeaderActions(): void {
     document.body.classList.remove(HEADER_SEATED_CLASS)
+    document.documentElement.style.removeProperty(HEADER_RESERVE_VAR)
     const header = document.querySelector('[class$="_header"]')
     const tabs = header !== null ? header.querySelector('[class$="_tabs"]') : null
     const actions = header !== null ? header.querySelector('[class$="_titleCluster"] [class$="_headerActions"]') : null
     if (actions instanceof HTMLElement) actions.style.transform = ''
+    // The v67 padding reservation is gone with the v80 cap; clearing it keeps a
+    // profile that hot-updated from an older build from keeping a stale inline
+    // width on the row.
     if (tabs instanceof HTMLElement) tabs.style.paddingRight = ''
     if (headerObserver !== null) {
       headerObserver.disconnect()

package/src/client/plugin-card-seat.ts

@@ -0,0 +1,185 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/plugin-card-seat.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Family plugin-card seat.
+ *
+ * A family plugin contributes its settings card to whichever plugin-card seat
+ * the running host actually renders:
+ *
+ * - `web-ui.plugin.item` — the list seat declared by the dsh-web-settings
+ *   group section (this family's own first-level "Web UI plugins" section);
+ * - `settings.plugin.item` — the official keyed seat of the harness's
+ *   `ui-settings-plugins` tab, keyed by the settings namespace the card edits.
+ *
+ * SEAT SELECTION IS NOT A DECLARATION PROBE. The official `ui-settings-plugins`
+ * row belongs to the harness bundle and its `configurable` tab always declares
+ * `settings.plugin.item` before any external plugin's `apply()` runs, so
+ * "is the official seat declared?" answers yes even in the deployment whose
+ * whole point is the family group. Choosing on that probe sends every family
+ * card to the official Plugins tab and leaves the group's own section
+ * permanently empty — the family of reports where the section renders its
+ * heading and zero cards.
+ *
+ * The signal that actually distinguishes the two deployments is whether
+ * dsh-web-settings is loaded: it is the package that owns the group section and
+ * it publishes the `webUiSettings` service during `apply()`, which every
+ * family plugin already reads for its settings scope. Group loaded -> the family
+ * seat; group absent -> the official seat.
+ *
+ * The decision is re-evaluated on every `slots/changed` because the group may
+ * apply after this plugin (the family aggregate orders it first, a profile that
+ * installs the group separately need not): the initial contribution goes to the
+ * official seat, then moves to the family seat the moment the group's section
+ * registers. The entry is disposed before the replacement is registered, so a
+ * card is never in two seats at once.
+ *
+ * The shared tree has no client-SDK dependency, so this module reads its
+ * context through the structural shape below; callers pass the plugin's own
+ * `ctx`.
+ */
+
+/** The family list seat key. */
+export const FAMILY_PLUGIN_CARD_SEAT = 'web-ui.plugin.item'
+
+/** The official keyed plugin-card seat key. */
+export const OFFICIAL_PLUGIN_CARD_SEAT = 'settings.plugin.item'
+
+/** The service dsh-web-settings publishes while it is loaded. */
+export const FAMILY_GROUP_SERVICE = 'webUiSettings'
+
+/** The slot-registry member this helper uses (structurally satisfied by ctx.slots). */
+export interface PluginCardSlots {
+  /** Contribution of one card entry. */
+  register(options: never, component: never): unknown
+}
+
+/** The slice of the client context a card contribution needs. */
+export interface PluginCardContext {
+  slots: PluginCardSlots
+  /** Service lookup; absent on a context double that only models the slots. */
+  get?(name: string): unknown
+  /** Event subscription seat; absent on an event-less test double. */
+  on?(event: string, listener: (...args: never[]) => void): unknown
+}
+
+/** Owner share of a plugin card (both seats supply nothing). */
+export interface SettingsPluginItemOwnerProps {
+  /** Marker field: card owner props are intentionally empty. */
+  children?: never
+}
+
+/** One family plugin's card contribution. */
+export interface PluginCardSeat {
+  /** Settings namespace the card edits (the official seat's dispatch key). */
+  namespace: string
+  /** Family list-seat entry id. */
+  id: string
+  /** Family list-seat sort order. */
+  order?: number
+  /** Family list-seat display label; the official keyed seat carries none. */
+  label?: () => string
+  /** Locale namespace the card renders with. */
+  locale: string
+  /** Business-face factory of the registration. */
+  inject?: () => object
+  /**
+   * The card component. Its props type is the seat's composed shape, which is
+   * chosen at runtime, so the helper takes it erased; the registrant keeps its
+   * own precise typing at the call site.
+   */
+  component: unknown
+}
+
+/**
+ * Whether the family group (dsh-web-settings) is loaded in this page. The
+ * service is the group package's own contract, so the probe cannot be fooled
+ * by a harness release that starts declaring the official seat differently.
+ */
+export function familyGroupLoaded(ctx: PluginCardContext): boolean {
+  const get = ctx.get
+  if (typeof get !== 'function') return false
+  try {
+    return get.call(ctx, FAMILY_GROUP_SERVICE) !== undefined
+  } catch {
+    // A context that refuses the lookup: treat the group as absent, which
+    // falls back to the official seat the harness declares.
+    return false
+  }
+}
+
+/** Report a refused registration instead of leaving the user with no card. */
+function warnRefusedSeat(seat: string, error: unknown): void {
+  try {
+    console.warn(`[dsh-web] plugin card registration into "${seat}" was refused; the card will not render`, error)
+  } catch {
+    // Best-effort console write; a failed warning must not break the plugin.
+  }
+}
+
+/**
+ * Contribute one family plugin card to the seat this host renders, following
+ * the group if it loads later. The entry is disposed and re-registered on a
+ * seat change, never duplicated.
+ * @param ctx - client context (its slot registry decides the seat).
+ * @param seat - the card contribution.
+ */
+export function installPluginCard(ctx: PluginCardContext, seat: PluginCardSeat): void {
+  const slots = ctx.slots
+  const component = seat.component as never
+  const inject = seat.inject as never
+
+  let dispose: (() => void) | undefined
+  let current: string | undefined
+  /**
+   * Re-entrancy latch. The registry emits a change event synchronously from
+   * inside both `register` and the previous entry's disposer, so an unguarded
+   * reconcile would re-enter itself mid-move and register the card twice into
+   * the seat it is leaving ("already has an entry for key ...").
+   */
+  let reconciling = false
+
+  /** Reconcile the contribution with the currently live seat (no-op when unchanged). */
+  const reconcile = (): void => {
+    if (reconciling) return
+    const target = familyGroupLoaded(ctx) ? FAMILY_PLUGIN_CARD_SEAT : OFFICIAL_PLUGIN_CARD_SEAT
+    if (current === target) return
+    reconciling = true
+    const previous = dispose
+    dispose = undefined
+    current = undefined
+    previous?.()
+    try {
+      dispose = slots.register((target === FAMILY_PLUGIN_CARD_SEAT
+        ? {
+          name: FAMILY_PLUGIN_CARD_SEAT,
+          id: seat.id,
+          ...(seat.order === undefined ? {} : { order: seat.order }),
+          ...(seat.label === undefined ? {} : { label: seat.label }),
+          locale: seat.locale,
+          ...(seat.inject === undefined ? {} : { inject }),
+        }
+        : {
+          name: OFFICIAL_PLUGIN_CARD_SEAT,
+          key: seat.namespace,
+          locale: seat.locale,
+          ...(seat.inject === undefined ? {} : { inject }),
+        }) as never, component) as () => void
+      current = target
+    } catch (error) {
+      warnRefusedSeat(target, error)
+    } finally {
+      reconciling = false
+    }
+  }
+
+  if (typeof ctx.on === 'function') {
+    try {
+      ctx.on('slots/changed', () => { reconcile() })
+    } catch {
+      // An event seat that refuses the subscription leaves the initial
+      // decision in place; the card still renders in the seat chosen below.
+    }
+  }
+  // The initial decision: the group, when it is already loaded (the aggregate
+  // order), otherwise the official seat the harness declares.
+  reconcile()
+}