dsh-url-router 0.4.0 → 0.4.1

package/AGENTS.md

@@ -83,7 +83,7 @@
 ## 桌面地址栏契约（2026-10-24 起，改之前先读）
 
 - **形态**：Windows 桌面版的标题栏是**页面里画的** ✓ —— preload（`app.asar` 的 `lib/preload-app.cjs`）跑 `syncWindowsAppearance()`：给 `<html>` 打 `data-windows-titlebar`、设 `--dsh-windows-titlebar-height: 40px`，并用 shadow DOM 画菜单条（宿主 `[data-windows-menu]`，`position:fixed; top:0; left:var(--dsh-windows-menu-start,48px); z-index:1100; -webkit-app-region:no-drag`）。⇒ 那条 strip 是**页面空间** ✓，插件可以往里画 ✓。
-- **门控**：只有 `documentElement.getAttribute('data-windows-titlebar') !== null` 时才画 ✓；Web 版与 macOS 上**一行都不执行** ✓（"并进 url-router 但不影响其它平台"的全部机制就是这个 ✓）。
+- **门控**：Windows 那条路径只在 `documentElement.getAttribute('data-windows-titlebar') !== null` 时执行 ✓；Web 版**一行都不执行** ✓。macOS 走另一条分支 ✓（见下节 ✓），两者靠 `macInHeader = !windowsStrip && macDesktopWindow(root)` 互斥 ✓，`place()` 里就是一个 if/else ✓ —— **不是两个各自独立挂载的组件** ✓。
 - **定位**：`left = 48 + 菜单宿主宽度 + 8` ✓（宽度用宿主 `getBoundingClientRect()` 量 ✓，**不要**读 shadow 内部 ✗）；`right = TITLEBAR_CAPTION_WIDTH = 138px` 是 Windows 窗口按钮宽度常量 ✓（改缩放/换系统可能要调 ✓）；高度一律走 CSS 变量 ✓，不要写死 40 ✓。
 - **交互**：`-webkit-app-region: no-drag` 必须留 ✓ —— strip 本身是拖拽区 ✗，去掉它输入框点不动 ✗。
 - **落地只写 hash** ✓：`window.location.hash = fragment` ✓，绝不自己调路由内部 ✗ —— 浏览器触发 `hashchange` ✓，落地就是"粘贴链接"那条已验证的路 ✓。
@@ -91,6 +91,18 @@
 - **假 DOM 不支持 `#id` 选择器** ✗ → 地址栏带 `data-dsh-part="url-router-address-bar"` ✓，测试用属性选择器 ✓（行锚点当年同理 ✓）。
 - **验收**：布局可在 Web 版上用 `document.documentElement.setAttribute('data-windows-titlebar','')` + 那个 CSS 变量预演 ✓（同一套 CSS ✓），但 `dsh-app://` 下的 `replaceState` / `hashchange` 行为**只能真机确认** ✓。
 
+## macOS 地址栏契约（2026-10-25 起，改之前先读）
+
+- **形态**：macOS 没有页面里画的 strip ✓（标题栏是原生的，红黄绿三个灯在左上 ✓）。借的是会话页顶部那行**常驻标题行** ✓：面包屑 + 模式标签 + 右侧一排按钮 + 电源按钮 ✓。bar 仍是 `position:fixed` 挂在 body 上 ✓ —— 和 Windows 同一套挂载方式 ✓。
+- **判定**：`data-platform=darwin`（或 UA 是 Mac）**且**（UA 有 `Electron/<x>` **或**协议是 `dsh-app:`）✓。**实测桌面版把 UA 里的 `Electron/` 抹掉了** ✓（UA 形如 `… @deepseek-ai/dsh-desktop/0.2.1-rc` ✓），所以真正生效的是 `dsh-app:` 那条 ✓ —— 别以为 UA 分支在兜底 ✓。
+- **定位 = 量空白段，不是探矩形** ✓：`macLeaves()` 走一遍行内**所有真正占位的元素** ✓（有自己文字、或 `button/a/input/[role=button]/[role=tab]/img/svg`、或没有子元素 ✓）→ 只留和电源按钮同一行的 ✓ → 按左边界排序并**合并重叠** ✓ → 求所有空白段 ✓ → 取**最宽**那段 ✓ → `fitBar()` 右对齐（贴着头部按钮）+ 两侧 `MAC_BAR_INSET = 25` 内缩 ✓。
+- **宽度必须封顶** ✓（`MAC_BAR_MAX_WIDTH = 1150`）：空白段的左边界就是**会话标题文字的右边界** ✓，不封顶的话每换一个会话框就变一次宽 ✓。
+- **「探测矩形 + 一撞就隐藏」那套别再写** ✗：它把候选框放在电源按钮左侧 ✓，必然横跨头部那排按钮 ✓，于是每次都被判"不空"然后整框 `display:none` ✓ —— 这就是"框怎么都不出来"的历史 bug ✓。
+- **没有电源按钮的界面**（插件页 / 设置页 / 面板页 ✓）：沿用上一次量到的空白段 ✓，位置不动 ✓。**但要把窗口宽度一起存** ✓（`{top, viewport, gap}` ✓）：头部按钮是**右对齐**的 ✓，窗口一变它们就移动 ✓，旧空白段会把框画到标题甚至侧边栏上 ✓（真机抓到过 `bar.left=122` 而 `row.left=301` ✓）。宽度差超过 `MAC_BAR_RESIZE_SLACK = 8` 就**不猜** ✓，先隐藏，等回会话页重新量 ✓。
+- **只有一个框** ✓：挂载前先 `getElementById` 摘掉同 id 的旧 bar 和旧样式表 ✓ —— effect 重跑（热重载 / 重复 apply）不会多一个 ✓。
+- **调试不在产品里** ✓：`dev/inspect/` 是一个**独立观察器插件** ✓（`private: true`，靠根 `files` 白名单不进 npm ✓），只读公开契约（`#dsh-url-router-titlebar`、`data-dsh-url-router-platform`、`[class*="titleRow"]`、`.dshpm-trigger`）✓。判据三条：`bars` 恒为 1 ✓、`onTop` ✓、`leaves` 有没有被压住 ✓。**别再把调试代码写回 `lib/client.js`** ✗ —— 发布物必须是跑过测试的那一份 ✓。
+- **假 DOM 不支持 `#id` 选择器** ✗：mac 侧的新代码对 `getElementById` / `querySelectorAll` 全部用了可选调用 ✓，测试里缺失即跳过 ✓。
+
 ## 跨机开发日志
 
 改动记录在私有库 [DDDMUC/repo-devlogs](https://github.com/DDDMUC/repo-devlogs) 的 **`dsh-url-router/`** 文件夹（`HANDOFF.md` 最新一轮在最上面；macOS 端写 `WORKLOG-macos.md`，条目以 `[macOS]` 开头）。按该库规矩，每条先写 `**运行环境**`（设备 / 应用 / 服务商与模型），再写做了什么、动了哪些文件、怎么验证、遗留问题。

package/README.md

@@ -55,8 +55,21 @@ dsh plugin --profile web add "link:/path/to/dsh-url-router"
 
 DSH 桌面版（Windows）的标题栏是**画在网页里的**：preload 给 `<html>` 打上 `data-windows-titlebar`、给出 `--dsh-windows-titlebar-height`，菜单条本身是页面里的一个 shadow DOM 固定元素（`[data-windows-menu]`）。那条 strip 里的空白是**页面空间**，而桌面版**自己没有地址栏** —— 于是本插件把地址栏放在那儿：
 
-- 只在 `html[data-windows-titlebar]` 存在时出现 ✓（Web 版与 macOS 上什么都不画 ✓）。
+- 只在 `html[data-windows-titlebar]` 存在时出现 ✓（纯 Web 版什么都不画 ✓）。
 - 位置：紧跟 shell 自己的菜单条右侧 ✓、右端避开窗口按钮 ✓；高度取 `--dsh-windows-titlebar-height` ✓；`-webkit-app-region: no-drag` 保证能点 ✓。
+
+### macOS 桌面的地址栏
+
+macOS 的标题栏是**原生**的（左边红黄绿三个灯），页面里没有 Windows 那条 strip 可以借。但会话页顶部有一行**常驻的标题行**（面包屑 + 模式标签 + 右侧按钮 + 电源按钮），地址栏就落在那行里：
+
+- 判定：shell 给 `<html>` 打上 `data-platform=darwin`（或 UA 是 Mac）**并且**（UA 里有 `Electron/<x>` **或**页面跑在 `dsh-app:` 协议上）→ 只有桌面 App 满足，浏览器里开 Web 版不画 ✓。（实测桌面版会把 UA 里的 `Electron/<x>` 抹掉，所以真正生效的是 `dsh-app:` 那条 ✓。）
+- 位置：先量这一行里**所有真正占位的东西**（有自己文字的元素、按钮、图标），按左边界排序并合并重叠 → 得到若干空白段 → 取**最宽的那一段**，右端贴着头部按钮、左端跟着走，两边各留 25px 内缩 ✓。
+- 宽度封顶 **1150px**：空白段的左边界是跟着**会话标题长度**跑的 ✓，不封顶的话换个会话框就变一次宽 ✓；放不下时按实际空白缩 ✓。
+- 和电源按钮**同一行**（垂直居中于它 ✓），`position: fixed` —— 所以既不遮挡也不挤压任何东西 ✓。
+- 没有电源按钮的界面（插件页、设置页、面板页）：沿用上一次量到的空白段，**位置不动** ✓。但如果窗口尺寸变过（> 8px），旧空白段已经不可信 ✓（头部按钮是靠右对齐的，窗口一变它们就移动了），此时**不猜** —— 先隐藏，等回到会话页重新量 ✓。
+- **只有一个框** ✓：挂载前先按 id 摘掉旧的 bar 和样式表 ✓，所以 effect 重跑多少次（热重载、重复 apply）都只有一个 ✓。
+- Windows 那条路径完全不变，`data-windows-titlebar` 优先，两种形态互斥 ✓。
+- 输入、反射、拒识、Escape 恢复的逻辑与 Windows 版共用同一份代码 ✓。
 - 输入什么 ✓：任何 `#/…` 路由（会话 / 工作区 / 视图 / 轮次 / 行 / 面板 / 设置三层 / 右栏 pane）、**裸会话 id**、或**整条链接**（只取它的 fragment）✓；回车写 hash → 浏览器触发 `hashchange` → 落地走的就是"粘贴链接"那条已验证的路 ✓。
 - 它同时是**反映** ✓：本插件每次写地址栏都会同步进这个框 ✓，所以它显示的就是"现在在哪" ✓。Escape 还原 ✓；认不出的文本不动地址栏 ✓。
 
@@ -130,7 +143,8 @@ Conversation rows and both plugin-list groups carry a transparent full-row ancho
 
 The Windows desktop window draws its own title bar **inside the page**: the preload marks `<html data-windows-titlebar>` and publishes `--dsh-windows-titlebar-height`, and its menu is a fixed shadow-DOM element in the page (`[data-windows-menu]`). That strip is page space, and the desktop window has **no address bar of its own** — so this plugin puts one there:
 
-- Drawn only when `html[data-windows-titlebar]` is present (nothing at all on the web app or macOS).
+- Drawn only when `html[data-windows-titlebar]` is present (nothing at all on the plain web app).
+- On the **macOS desktop** build there is no in-page strip to borrow, so the bar becomes a floating pill instead: pinned just under the native title bar at the window's top-right, 380×30, rounded, blurred and shadowed. It is recognised by the shell's `<html data-platform="darwin">` marker (or a Mac user agent) together with the window being the application — Electron in the user agent or the `dsh-app:` scheme — so the web app in a browser never draws it. It sits inside the 48px the shell reserves above its frame (`--dsh-frame-top-clearance`), clear of the traffic lights. Both shapes share one code path; the Windows marker wins when present.
 - Placed right after the shell's own menu and before the window buttons, at `--dsh-windows-titlebar-height`, with `-webkit-app-region: no-drag` so it stays clickable.
 - Accepts any `#/…` route, a bare conversation id, or a whole link (only its fragment is used); Enter writes the hash, the browser fires `hashchange`, and the link lands through the very same path a pasted link takes.
 - It also **reflects**: every write this plugin makes to the address bar is mirrored into the box, so it always names what is on screen. Escape restores it; text that names no route is refused.

package/lib/client.js

@@ -131,14 +131,14 @@ window.__ModuleLoader__.load({
 		 * The router's own version, for the report a human files. A test keeps it equal to the
 		 * package version, so a release cannot forget to bump it.
 		 */
-		const ROUTER_VERSION = '0.4.0'
+		const ROUTER_VERSION = '0.4.1'
 		/**
 		 * Hand-maintained build marker, reported alongside the version. A working copy that is
 		 * linked into a profile serves this file straight from disk, so the package version
 		 * cannot say *which* copy a live window loaded — this can, and `report().build` is how a
 		 * real-machine check answers that. Bump it whenever a live window must be told apart.
 		 */
-		const ROUTER_BUILD = 'desktop-bar+settings-marker+modal-dismiss'
+		const ROUTER_BUILD = 'desktop-bar+settings-marker+modal-dismiss+mac-header-bar.2'
 
 		const TAG = '[url-router]'
 
@@ -155,10 +155,173 @@ window.__ModuleLoader__.load({
 		const TITLEBAR_STYLE_ID = 'dsh-url-router-titlebar-style'
 		/** Width the window's caption buttons take at the right end of the strip. */
 		const TITLEBAR_CAPTION_WIDTH = 138
-		/** Gap between the shell's menu and the bar. */
-		const TITLEBAR_GAP = 8
-		/** How long the bar waits for a handed-over link to land before it says it did not. */
-		const TITLEBAR_SETTLE_MS = 900
+	/** Gap between the shell's menu and the bar. */
+	const TITLEBAR_GAP = 8
+	/**
+	 * macOS has no in-page title-bar strip, so the bar cannot borrow window chrome
+	 * the way the Windows build does. It borrows the next best thing: the shell's
+	 * resident header row, which exists on every screen. The bar stays mounted in
+	 * the body with fixed positioning — exactly the Windows approach — and `place`
+	 * measures the title cluster and the right-hand cluster to get its insets.
+	 */
+	const MAC_BAR_HEIGHT = 26
+	/** The least room the bar will draw itself into; below this it stays hidden. */
+	const MAC_BAR_MIN_WIDTH = 120
+	/** The breathing space the bar keeps from whatever stands next to it. */
+	const MAC_BAR_GAP = 8
+	/** The margin the bar leaves inside the free stretch, on each side. */
+	const MAC_BAR_INSET = 25
+	/**
+	 * The bar's own length.
+	 *
+	 * The free stretch begins wherever the conversation's title happens to end, so
+	 * without a length of its own the bar would grow and shrink as titles change.
+	 * It stops here instead, and only gets shorter when the row cannot spare this
+	 * much.
+	 */
+	const MAC_BAR_MAX_WIDTH = 1150
+	/**
+	 * How much the window may change before a remembered stretch stops counting.
+	 *
+	 * The stretch was measured against one window; a different one moves the
+	 * header's buttons, and there is nothing to re-measure from on a screen that
+	 * has no power button. A couple of pixels is rounding, more is a resize.
+	 */
+	const MAC_BAR_RESIZE_SLACK = 8
+	const MAC_STYLE_TEXT = [
+		`#${TITLEBAR_BAR_ID}[data-dsh-url-router-platform="mac"]{position:fixed;display:flex;align-items:center;height:${MAC_BAR_HEIGHT}px;z-index:1200;-webkit-app-region:no-drag}`,
+		`#${TITLEBAR_BAR_ID}[data-dsh-url-router-platform="mac"] input{height:${MAC_BAR_HEIGHT}px;width:100%;box-sizing:border-box;border:1px solid rgba(127,127,127,.34);border-radius:8px;padding:0 10px;font:inherit;font-size:12px;color:inherit;background:rgba(127,127,127,.16);outline:none;-webkit-app-region:no-drag}`,
+		`#${TITLEBAR_BAR_ID}[data-dsh-url-router-platform="mac"] input:focus{border-color:var(--dsw-alias-brand-primary,rgba(79,124,255,.9))}`,
+		`#${TITLEBAR_BAR_ID}[data-dsh-url-router-platform="mac"][data-dsh-url-router-state="refused"] input{border-color:rgba(214,69,69,.85);color:rgba(214,69,69,1)}`,
+	].join('')
+	/** Where the bar's last spot is kept, so a screen without a power button still gets it. */
+	const MAC_PLACEMENT_KEY = 'dsh-url-router-placement'
+	/**
+	 * Describe one element: what it is, and where it sits.
+	 * @param {object} el - the element to describe.
+	 * @returns {object|null} the description, or null when there is no element.
+	 */
+	function macDescribe(el) {
+		if (el === null || el === undefined) return null
+		const rect = el.getBoundingClientRect?.()
+		const cls = el.className?.baseVal ?? el.className ?? ''
+		return {
+			tag: String(el.tagName ?? '?').toLowerCase(),
+			cls: typeof cls === 'string' ? cls.slice(0, 70) : '',
+			rect: rect === undefined || rect === null
+				? null
+				: { top: Math.round(rect.top), left: Math.round(rect.left), width: Math.round(rect.width), height: Math.round(rect.height) },
+		}
+	}
+	/**
+	 * Every descendant of an element that carries text of its own or answers a
+	 * click — the header's real contents, so the bar can find the gap between
+	 * them instead of guessing where it is.
+	 * @param {object} el - the element to walk.
+	 * @param {number} depth - how far down to walk.
+	 * @returns {Array<object>} the leaves, with their boxes.
+	 */
+	function macLeaves(el, depth) {
+		const leaves = []
+		if (el === null || el === undefined || depth > 6) return leaves
+		for (const child of el.children ?? []) {
+			const own = ownText(child)
+			const interactive = typeof child.closest === 'function'
+				&& child.matches?.('button, a, input, [role="button"], [role="tab"], img, svg') === true
+			if (own !== '' || interactive || child.children.length === 0) {
+				leaves.push({ ...macDescribe(child), own: own.slice(0, 40) })
+			} else {
+				leaves.push(...macLeaves(child, depth + 1))
+			}
+		}
+		return leaves
+	}
+	/**
+	 * The header row the bar has to live in: the row that carries the
+	 * conversation's title on the left and the header's own buttons on the right.
+	 *
+	 * The shell names the row in its stylesheet, so that name is tried first; when
+	 * it has changed, the row is taken from the power button's own corner, whose
+	 * parent is the row the button was mounted on.
+	 *
+	 * @param {object} trigger - the power-menu trigger.
+	 * @returns {object|undefined} the row element, or undefined when there is none.
+	 */
+	function macHeaderRow(trigger) {
+		const corner = document.querySelector?.('[data-conversation-header-corner]')
+		const named = document.querySelector?.('[class*="titleRow"]')
+		if (named !== undefined && named !== null) {
+			// Only the row that actually holds the button is the row to measure.
+			if (trigger === undefined || trigger === null) return named
+			if (typeof named.contains !== 'function' || named.contains(trigger)) return named
+		}
+		return corner?.parentElement ?? undefined
+	}
+	/**
+	 * The free stretch of the header row the bar can live in.
+	 *
+	 * The row is measured rather than guessed: every leaf that shares the power
+	 * button's row — the title text, the mode label, the header's own buttons — is
+	 * turned into an interval, overlapping intervals are merged, and the widest
+	 * stretch between them is the one the bar goes into. Nothing is covered,
+	 * because that stretch holds nothing; nothing is pushed, because the bar is a
+	 * fixed-position layer of its own.
+	 *
+	 * @param {Array<object>} leaves - the row's measured contents.
+	 * @param {object} rect - the power button's rectangle, which ends the search.
+	 * @param {object} [bounds] - the row's own rectangle, which begins it.
+	 * @returns {{left: number, right: number}|null} the stretch, or null when the row has no room.
+	 */
+	function macFreeGap(leaves, rect, bounds) {
+		if (rect === undefined || rect === null) return null
+		const rowTop = rect.top
+		const rowBottom = rect.top + rect.height
+		// The power button is the anchor: the bar never reaches past its left edge.
+		const limit = Math.round(rect.left)
+		const occupied = []
+		for (const leaf of leaves ?? []) {
+			const box = leaf?.rect
+			if (box === undefined || box === null) continue
+			if (!(box.width > 0) || !(box.height > 0)) continue
+			// Only what stands on the power button's row can be in the way.
+			if (box.top >= rowBottom || box.top + box.height <= rowTop) continue
+			const left = Math.round(box.left)
+			const right = Math.round(box.left + box.width)
+			if (right <= 0 || left >= limit) continue
+			occupied.push({ left, right })
+		}
+		occupied.sort((a, b) => a.left - b.left)
+		// Merge what overlaps, so a box inside another cannot split a stretch.
+		const merged = []
+		for (const span of occupied) {
+			const last = merged[merged.length - 1]
+			if (last !== undefined && span.left <= last.right) {
+				if (span.right > last.right) last.right = span.right
+				continue
+			}
+			merged.push({ left: span.left, right: span.right })
+		}
+		// The row begins at its own left edge when that is known, and at the first
+		// thing standing on it otherwise.
+		const start = bounds !== undefined && bounds !== null && bounds.left > 0
+			? Math.round(bounds.left)
+			: (merged[0]?.left ?? limit)
+		const runs = []
+		let cursor = start
+		for (const span of merged) {
+			if (span.left > cursor) runs.push({ left: cursor, right: span.left })
+			if (span.right > cursor) cursor = span.right
+		}
+		if (limit > cursor) runs.push({ left: cursor, right: limit })
+		let best = null
+		for (const run of runs) {
+			if (run.right - run.left < MAC_BAR_MIN_WIDTH) continue
+			if (best === null || run.right - run.left > best.right - best.left) best = run
+		}
+		return best
+	}
+	/** How long the bar waits for a handed-over link to land before it says it did not. */
+	const TITLEBAR_SETTLE_MS = 900
 		/** What the address bar accepts, said in its placeholder. */
 		const TITLEBAR_PLACEHOLDER = '#/session/… · #/panel/… · #/settings · 会话 id · 链接'
 		/** The strip belongs to the shell, so only the bar itself is styled. */
@@ -284,12 +447,6 @@ window.__ModuleLoader__.load({
 			return undefined
 		}
 
-		/**
-		 * The kind inside a tab id: the bar builds one as `sidebar://<kind>` and appends a uuid for
-		 * kinds that may be opened more than once, so the kind is right there in the address.
-		 * @param {string} value - a tab id.
-		 * @returns {string|undefined} the kind, when the value is one of these addresses.
-		 */
 		/**
 		 * The right bar's registry, normalised: one row per page type with its kind, the label
 		 * the tab shows, whether more than one may be open, and its empty-state card (measured
@@ -297,36 +454,6 @@ window.__ModuleLoader__.load({
 		 * @param {object} faces - the probed host faces.
 		 * @returns {{kind: string, label: string|undefined, multiple: boolean}[]|undefined} the rows.
 		 */
-		/**
-		 * The seq of a turn's start event, from the `turnOutline` projection.
-		 *
-		 * The projection is a public read on the session controller (the core reads it the same
-		 * way: `session.projections.faceOf("turnOutline").getSnapshot()`), and each entry carries
-		 * the `seq` of that turn's `turn/start` — which is exactly what `loadThrough` pages back
-		 * to. Reading it is what makes a turn link work for a turn that is not loaded yet.
-		 * @param {object} faces - the probed host faces.
-		 * @param {string|undefined} sessionId - the session the turn belongs to.
-		 * @param {string} turn - the turn number.
-		 * @returns {number|undefined} the seq, when the projection names that turn.
-		 */
-		function turnSeqOf(faces, sessionId, turn) {
-			if (typeof sessionId !== 'string' || sessionId === '') return undefined
-			// Reached by retaining the session's scope: `sessions.binding(id)` answers undefined
-			// for a session nobody materialised yet (measured), while `retainScope(id, source)`
-			// materialises it and returns a reference whose `binding` is the live one. Released here
-			// because only the projection is read.
-			const reference = attemptValue(() => faces.sessions?.retainScope?.(sessionId, 'url-router'))
-			const outline = attemptValue(() => session?.projections?.faceOf?.('turnOutline')?.getSnapshot?.())
-			attempt(() => reference?.release?.())
-			if (!Array.isArray(outline)) return undefined
-			const wanted = String(turn)
-			for (const entry of outline) {
-				if (entry === null || typeof entry !== 'object') continue
-				if (String(entry.turn) !== wanted) continue
-				return typeof entry.seq === 'number' ? entry.seq : undefined
-			}
-			return undefined
-		}
 
 		function paneRegistryOf(faces) {
 			const rows = attemptValue(() => faces.sidebarRightTabs?.entries?.())
@@ -2383,6 +2510,55 @@ window.__ModuleLoader__.load({
 			return `打不开 ${name}（当前 ${shown}，侧栏 ${rows} 行）`
 		}
 
+		/**
+		 * Whether this window is the macOS desktop build.
+		 *
+		 * The macOS desktop shell draws a native title bar and publishes no in-page
+		 * strip, so the Windows marker is absent there — which used to mean "draw
+		 * nothing". Two facts together identify a macOS desktop window: the shell marks
+		 * `<html data-platform="darwin">` (or the user agent says Mac), and the window
+		 * is the application rather than a browser tab (Electron in the user agent, or
+		 * the page served over the app's own `dsh-app:` scheme). The plain web app in a
+		 * browser satisfies neither and stays empty, as before.
+		 *
+		 * @param {object} root - `document.documentElement`.
+		 * @returns {boolean} true when the address bar belongs on screen.
+		 */
+		function macDesktopWindow(root) {
+			const ua = typeof navigator === 'object' && navigator !== null ? String(navigator.userAgent ?? '') : ''
+			const platform = typeof root?.getAttribute === 'function' ? root.getAttribute('data-platform') : null
+			const isMac = platform === 'darwin' || /Mac OS X|Macintosh/u.test(ua)
+			if (!isMac) return false
+			const protocol = String(globalThis.location?.protocol ?? '')
+			return /Electron\/\d/u.test(ua) || protocol.startsWith('dsh-app')
+		}
+
+
+		/**
+		 * The power-menu trigger, the one element that is guaranteed to sit on the
+		 * same row on every screen. The address bar anchors to it.
+		 *
+		 * @returns {object|undefined} the trigger element, or undefined when absent.
+		 */
+		function powerTrigger() {
+			if (typeof document?.querySelector !== 'function') return undefined
+			return document.querySelector('[data-dshpm-mount] .dshpm-trigger')
+				?? document.querySelector('.dshpm-trigger')
+				?? document.querySelector('[aria-label="电源菜单"]')
+				?? undefined
+		}
+
+		/** An element's own text, ignoring the text of its children. */
+		function ownText(el) {
+			if (el === null || el === undefined || typeof el.childNodes !== 'object') return ''
+			let text = ''
+			for (const node of el.childNodes) {
+				if (node !== null && node.nodeType === 3) text += node.textContent ?? ''
+			}
+			return text.trim()
+		}
+
+
 		/**
 		 * Draw the address bar into the desktop window's title bar strip.
 		 * @param {object} document - the document to draw into.
@@ -2393,14 +2569,32 @@ window.__ModuleLoader__.load({
 			if (document === undefined || document === null) return () => {}
 			const root = document.documentElement
 			// The marker is the shell's own statement that this page has a title bar drawn
-			// inside it. Without it there is no strip, and nothing is drawn.
-			if (typeof root?.getAttribute !== 'function' || root.getAttribute(WINDOWS_TITLEBAR_ATTRIBUTE) === null) return () => {}
+			// inside it. Without it there is no strip — but the macOS desktop build still
+			// gets a bar, drawn into the session header row instead.
+			const windowsStrip = typeof root?.getAttribute === 'function' && root.getAttribute(WINDOWS_TITLEBAR_ATTRIBUTE) !== null
+			const macInHeader = !windowsStrip && macDesktopWindow(root)
+			if (!windowsStrip && !macInHeader) return () => {}
 			if (typeof document.createElement !== 'function' || typeof document.body?.appendChild !== 'function') return () => {}
+			// One bar, one stylesheet — however many times this runs.
+			//
+			// The effect that draws the bar can run again in a live window (a hot
+			// reload of this plugin re-applies it), and a second mount would leave a
+			// second box on screen. Both are identified by id, so anything already
+			// there is taken down before the new one goes up: the platform split
+			// decides *where* the one bar lives, never how many there are.
+			try {
+				const staleBar = document.getElementById?.(TITLEBAR_BAR_ID)
+				if (staleBar !== null && staleBar !== undefined) staleBar.remove?.()
+				const staleStyle = document.getElementById?.(TITLEBAR_STYLE_ID)
+				if (staleStyle !== null && staleStyle !== undefined) staleStyle.remove?.()
+			} catch {
+				// A document without getElementById keeps the disposer as its only guard.
+			}
 			let style
 			try {
 				style = document.createElement('style')
 				style.id = TITLEBAR_STYLE_ID
-				style.textContent = TITLEBAR_STYLE_TEXT
+				style.textContent = macInHeader ? `${TITLEBAR_STYLE_TEXT}\n${MAC_STYLE_TEXT}` : TITLEBAR_STYLE_TEXT
 				const parent = document.head ?? document.body
 				if (parent !== undefined && parent !== null && typeof parent.appendChild === 'function') parent.appendChild(style)
 			} catch {
@@ -2408,26 +2602,156 @@ window.__ModuleLoader__.load({
 			}
 			const bar = document.createElement('div')
 			bar.id = TITLEBAR_BAR_ID
-			if (typeof bar.setAttribute === 'function') bar.setAttribute('data-dsh-part', TITLEBAR_PART)
+			if (typeof bar.setAttribute === 'function') {
+				bar.setAttribute('data-dsh-part', TITLEBAR_PART)
+				bar.setAttribute('data-dsh-url-router-platform', macInHeader ? 'mac' : 'windows')
+			}
 			const input = document.createElement('input')
 			input.type = 'text'
 			input.spellcheck = false
 			input.placeholder = TITLEBAR_PLACEHOLDER
 			if (typeof input.setAttribute === 'function') input.setAttribute('aria-label', '地址栏 / address bar')
 			bar.appendChild(input)
-			/** Start after the shell's menu, stop before its window buttons. */
-			const place = () => {
-				let menuWidth = 0
-				try {
-					const menu = typeof document.querySelector === 'function' ? document.querySelector(`[${WINDOWS_MENU_ATTRIBUTE}]`) : null
-					if (menu !== null && menu !== undefined && typeof menu.getBoundingClientRect === 'function') menuWidth = menu.getBoundingClientRect().width || 0
-				} catch {
-					menuWidth = 0
+		/**
+		 * The free stretch the bar was last fitted into.
+		 *
+		 * A screen with no power button — a panel, the plugins page, settings — has
+		 * nothing to align to. The bar keeps this stretch there, so changing views
+		 * neither moves it nor makes it vanish. The stretch is also kept on disk, so
+		 * a window that starts on such a screen still gets the bar where it belongs;
+		 * and because the box is fitted from the stretch each time, a change to the
+		 * bar's margins applies there too, without waiting for a conversation.
+		 */
+		let lastPlacement = attemptValue(() => {
+			const raw = globalThis.localStorage?.getItem?.(MAC_PLACEMENT_KEY)
+			if (raw === null || raw === undefined || raw === '') return null
+			const parsed = JSON.parse(raw)
+			const gap = parsed?.gap
+			if (typeof parsed?.top !== 'number' || typeof parsed?.viewport !== 'number') return null
+			if (typeof gap?.left !== 'number' || typeof gap?.right !== 'number') return null
+			return { top: parsed.top, viewport: parsed.viewport, gap: { left: gap.left, right: gap.right } }
+		}) ?? null
+		/**
+		 * Fit the bar into a free stretch of the header row.
+		 *
+		 * The bar takes the whole stretch bar a margin on each side, so it is as
+		 * long as the row can spare without touching what stands beside it. A
+		 * narrow row keeps the whole stretch rather than a sliver of it.
+		 *
+		 * @param {{left: number, right: number}} gap - the free stretch.
+		 * @param {number} top - the row's line, already centred on the power button.
+		 * @returns {{left: number, top: number, width: number}} the box to draw.
+		 */
+		const fitBar = (gap, top) => {
+			const right = gap.right - MAC_BAR_GAP - MAC_BAR_INSET
+			const room = gap.left + MAC_BAR_INSET
+			const available = right - room
+			const width = available >= MAC_BAR_MIN_WIDTH
+				? Math.round(Math.min(MAC_BAR_MAX_WIDTH, available))
+				: Math.round(gap.right - MAC_BAR_GAP - gap.left)
+			return { left: Math.round(right - width), top, width }
+		}
+		/**
+		 * Remember the stretch the bar went into, and put it on disk when it moved.
+		 * @param {object} placement - the line and the stretch just used.
+		 */
+		const remember = placement => {
+			const previous = lastPlacement
+			lastPlacement = placement
+			if (previous !== null
+				&& previous.top === placement.top
+				&& previous.viewport === placement.viewport
+				&& previous.gap.left === placement.gap.left
+				&& previous.gap.right === placement.gap.right) return
+			attemptValue(() => globalThis.localStorage?.setItem?.(MAC_PLACEMENT_KEY, JSON.stringify(placement)))
+		}
+		/**
+		 * Put the bar where it belongs.
+		 *
+		 * Windows: start after the shell's menu, stop before its window buttons.
+		 * macOS: sit in the free stretch of the header row, on the power button's
+		 * own line.
+		 */
+		const place = () => {
+			if (macInHeader) {
+				// The bar lives on the header row, on the same line as the power
+				// button, in the free stretch between the title text and the
+				// header's own buttons. The row's real contents are measured and the
+				// widest free stretch is chosen, so the bar covers nothing — and,
+				// being a fixed-position layer, it pushes nothing either.
+				const trigger = powerTrigger()
+				const rect = trigger?.getBoundingClientRect?.()
+				const row = macHeaderRow(trigger)
+				const rowRect = row?.getBoundingClientRect?.()
+				const anchored = rect !== undefined && rect !== null && rect.width > 0
+				// The row is only walked when there is a button to measure from.
+				const gap = anchored ? macFreeGap(macLeaves(row, 0), rect, rowRect) : null
+				if (gap === null) {
+					// Nothing on this screen to align to. Keep the stretch the
+					// conversation gave the bar, so switching views does not move it
+					// and does not make it disappear.
+					//
+					// Only while the window is still the one that stretch was measured
+					// in: the header's buttons sit at the right end of the window, so a
+					// resize moves them, and reusing an old stretch would draw the bar
+					// straight across the title and the buttons. With no button to
+					// measure from there is nothing to re-derive it from either, so a
+					// resized window hides the bar until a conversation places it again.
+					const viewport = Math.round(globalThis.innerWidth ?? 0)
+					if (lastPlacement === null || viewport <= 0
+						|| Math.abs(viewport - lastPlacement.viewport) > MAC_BAR_RESIZE_SLACK) {
+						bar.style.display = 'none'
+						return
+					}
+					const box = fitBar(lastPlacement.gap, lastPlacement.top)
+					const left = Math.max(MAC_BAR_GAP, Math.min(box.left, viewport - box.width - MAC_BAR_GAP))
+					bar.style.display = ''
+					bar.style.top = `${box.top}px`
+					bar.style.left = `${left}px`
+					bar.style.right = 'auto'
+					bar.style.width = `${box.width}px`
+					return
 				}
-				bar.style.left = `${WINDOWS_MENU_START + menuWidth + TITLEBAR_GAP}px`
-				bar.style.right = `${TITLEBAR_CAPTION_WIDTH}px`
+				const top = Math.round(rect.top + (rect.height - MAC_BAR_HEIGHT) / 2)
+				const box = fitBar(gap, top)
+				bar.style.display = ''
+				bar.style.top = `${box.top}px`
+				bar.style.left = `${box.left}px`
+				bar.style.right = 'auto'
+				bar.style.width = `${box.width}px`
+				remember({ top, viewport: Math.round(globalThis.innerWidth ?? 0), gap })
+				return
 			}
-			place()
+			let menuWidth = 0
+			try {
+				const menu = typeof document.querySelector === 'function' ? document.querySelector(`[${WINDOWS_MENU_ATTRIBUTE}]`) : null
+				if (menu !== null && menu !== undefined && typeof menu.getBoundingClientRect === 'function') menuWidth = menu.getBoundingClientRect().width || 0
+			} catch {
+				menuWidth = 0
+			}
+			bar.style.left = `${WINDOWS_MENU_START + menuWidth + TITLEBAR_GAP}px`
+			bar.style.right = `${TITLEBAR_CAPTION_WIDTH}px`
+			bar.style.width = 'auto'
+		}
+		/**
+		 * Place the bar at most once per frame.
+		 *
+		 * A streaming answer mutates the document constantly, and every mutation
+		 * would otherwise re-measure the header row. Coalescing the runs into one
+		 * frame keeps the bar where it belongs without measuring the header dozens
+		 * of times a second.
+		 */
+		let placeFrame
+		const schedulePlace = () => {
+			if (placeFrame !== undefined) return
+			placeFrame = attemptValue(() => globalThis.requestAnimationFrame?.(() => {
+				placeFrame = undefined
+				place()
+			}))
+			// No animation frames in this host: place it straight away.
+			if (placeFrame === undefined) place()
+		}
+		place()
 			/** How the bar looks right now: idle, waiting for a link to land, or refused. */
 			const mark = (state, hint) => {
 				if (typeof bar.setAttribute === 'function') bar.setAttribute('data-dsh-url-router-state', state)
@@ -2510,11 +2834,31 @@ window.__ModuleLoader__.load({
 				settle(fragment, false)
 			}
 			input.addEventListener('keydown', onKeyDown)
+			// Both platforms mount the bar in the body: Windows pins it into the
+			// title-bar strip, macOS pins it over the resident header row.
 			document.body.appendChild(bar)
+			// The first placement measured the header before the bar was in the
+			// document. Place it again now that it is, so the bar's own box is laid
+			// out and can be checked, and so the first paint is already correct.
+			place()
+			/**
+			 * The shell re-renders the session header whenever the view changes, which
+			 * takes the bar with it. A watcher puts it back where it belongs — the same
+			 * node, so what was typed into it survives.
+			 */
+			let headerWatcher
+			if (macInHeader && typeof MutationObserver === 'function') {
+				try {
+					headerWatcher = new MutationObserver(() => schedulePlace())
+					headerWatcher.observe(document.body, { childList: true, subtree: true })
+				} catch {
+					headerWatcher = undefined
+				}
+			}
 			const offRoute = subscribe(show)
 			let onResize
 			try {
-				onResize = () => place()
+				onResize = () => schedulePlace()
 				window.addEventListener('resize', onResize)
 			} catch {
 				onResize = undefined
@@ -2524,6 +2868,7 @@ window.__ModuleLoader__.load({
 				stopSettle()
 				input.removeEventListener?.('keydown', onKeyDown)
 				if (onResize !== undefined) window.removeEventListener?.('resize', onResize)
+				headerWatcher?.disconnect?.()
 				bar.remove?.()
 				style?.remove?.()
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-url-router",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "DSH 地址栏路由插件：每个界面都有自己的链接（会话 / 主面板 / 插件页与组件页 / 任务看板 / 设置），整行即真链接，只写 fragment；Windows 桌面版把地址栏画在标题栏里。",
   "repository": {
     "type": "git",