dsh-inner-browser-use 0.27.0 → 0.34.95

package/client.js

@@ -32,7 +32,8 @@ window.__ModuleLoader__.load({
     const DICT = {
       zh: {
         'side.label': '后台浏览器',
-        'side.empty': '还没有打开的页面',
+        'side.empty': '后台的独立 Chrome 还没有页面，在上方地址栏输入网址',
+        'side.restore': '恢复上次的页面',
         'side.connecting': '正在连接…',
         'side.failed': '画面没有连上',
         'side.foreign': '这个浏览器属于发起它的会话，回到那个会话继续。',
@@ -44,7 +45,8 @@ window.__ModuleLoader__.load({
       },
       en: {
         'side.label': 'Background browser',
-        'side.empty': 'No page open',
+        'side.empty': 'The background Chrome has no page yet; type an address above',
+        'side.restore': 'Reopen the last page',
         'side.connecting': 'Connecting…',
         'side.failed': 'The picture did not connect',
         'side.foreign': 'This browser belongs to the chat that opened it.',
@@ -73,6 +75,8 @@ window.__ModuleLoader__.load({
          on screen at once, and moving the mouse never takes the arrow over. */
       '.dshib-side-ptr{position:absolute;width:20px;height:20px;pointer-events:none;z-index:2;transform:translate(-2px,-2px);transition:left 60ms linear,top 60ms linear;filter:drop-shadow(0 1px 2px rgba(0,0,0,.45))}',
       '.dshib-side-note{font-size:12px;color:var(--dsw-alias-label-tertiary);padding:0 16px;text-align:center}',
+      '.dshib-side-back{border:0;border-radius:8px;background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:12px;padding:6px 12px;cursor:pointer}',
+      '.dshib-side-back:hover{background:var(--dsw-alias-bg-subtle)}',
     ].join('')
 
     return {
@@ -84,6 +88,9 @@ window.__ModuleLoader__.load({
           /* one locale service or none */
         }
         ctx.effect(() => {
+          /* A reload keeps one sheet, not one per lifetime: the same id is
+             replaced instead of stacked. */
+          document.getElementById?.(STYLE_ID)?.remove()
           const style = document.createElement('style')
           style.id = STYLE_ID
           /* A sheet is keyed by the plugin that brought it. */
@@ -109,6 +116,12 @@ window.__ModuleLoader__.load({
             }
           }
           const closeHere = (sessionId) => {
+            /* A tab the person closed is not a tab they want back on return. */
+            try {
+              void fetch(`${ROUTE}/sidecar/forget?session=${encodeURIComponent(sessionId)}`, { method: 'POST' }) // ui-copy-ignore
+            } catch {
+              /* a page that cannot hear it keeps its note */
+            }
             let records = []
             try {
               records = surface?.tabsIn?.(sessionId) ?? []
@@ -138,14 +151,29 @@ window.__ModuleLoader__.load({
               /* a column that refuses keeps its own tabs */
             }
           }
-          disposers.push(tabs.register({
+          /* The same rule on this side: a second mount of the same tab is a
+             no-op, not a thrown error that takes the pane down. */
+          const safely = (register) => {
+            try {
+              return register()
+            } catch (error) {
+              return () => {}
+            }
+          }
+          disposers.push(safely(() => tabs.register({
             id: SIDE_ID, // ui-copy-ignore
             kind: SIDE_KIND, // ui-copy-ignore
             keepMounted: true,
             single: true,
             priority: 'extension',
             title: () => L('side.label'),
-          }))
+            /* The tab strip's close control is not the pane's own button: a
+               tab closed there never told the host, the ask stayed alive, and
+               the keepalive put the mirror back a few seconds later — a tab
+               the person closed that would not stay closed. Every close path
+               ends here. */
+            onClose: (_tab, where) => closeHere(String(where?.sessionId ?? mountedOf())),
+          })))
           disposers.push(scope.slots.inject(SLOT, () => scope.slots.register({
             name: SLOT, // ui-copy-ignore
             key: SIDE_ID, // ui-copy-ignore
@@ -177,7 +205,10 @@ window.__ModuleLoader__.load({
           }
           const syncAsk = () => {
             const who = mountedOf()
-            if (who === askWho) return
+            /* A stream the browser gave up on keeps its address here, so the
+               next tick has to notice it is dead and open a fresh one, or this
+               chat never hears an ask again. */
+            if (who === askWho && askSource !== null && Number(askSource.readyState) !== 2) return
             closeAsk()
             if (who === '') return
             try {
@@ -202,7 +233,10 @@ window.__ModuleLoader__.load({
           const watchAsk = () => {
             try {
               if (typeof surface?.mounted?.subscribe === 'function') {
-                const off = surface.mounted.subscribe(syncAsk)
+                const off = surface.mounted.subscribe(() => {
+                  syncAsk()
+                  restore()
+                })
                 if (typeof off === 'function') return off
               }
             } catch {
@@ -211,10 +245,41 @@ window.__ModuleLoader__.load({
             return null
           }
           syncAsk()
+          /* An app restart leaves the browser alive but no ask on the wire, so
+             the column would come back empty in a chat that never closed it.
+             This chat asking for the state of the browser it still owns is what
+             puts the mirror back without anyone pressing anything. */
+          const restoreTimers = []
+          const restore = (tries = 0) => {
+            const who = mountedOf()
+            if (who === '') return
+            const again = () => {
+              if (tries >= 2) return
+              restoreTimers.push(setTimeout(() => restore(tries + 1), 1500))
+            }
+            try {
+              fetch(`${ROUTE}/sidecar/state?session=${encodeURIComponent(who)}`) // ui-copy-ignore
+                .then((said) => (said.ok === true ? said.json() : null))
+                .then((state) => {
+                  if (state?.owner !== who) return
+                  const live = state?.alive === true || state?.chat?.alive === true
+                  if (live !== true) {
+                    again()
+                    return
+                  }
+                  ask(who)
+                })
+                .catch(again)
+            } catch {
+              again()
+            }
+          }
+          restore()
           const offAsk = watchAsk()
           const pollAsk = setInterval(syncAsk, 1000)
           const stopAsk = () => {
             clearInterval(pollAsk)
+            for (const timer of restoreTimers) clearTimeout(timer)
             if (typeof offAsk === 'function') {
               try {
                 offAsk()
@@ -249,8 +314,37 @@ window.__ModuleLoader__.load({
     function SidecarBody(props) {
       const [frame, setFrame] = React.useState(null)
       const [ptr, setPtr] = React.useState(null)
+      /* The page is laid out at the size of this column, so the picture it
+         sends already has the right shape; these are its pixels. */
+      const [view, setView] = React.useState({ w: SIDE_VIEW.width, h: SIDE_VIEW.height })
+      /* The person at the mirror drives with their own hand: while they are,
+         the agent's arrow stays out of the way, and it comes back by itself
+         once their hold runs out. */
+      const [person, setPerson] = React.useState(false)
+      const personTimer = React.useRef(0)
+      /* The person's own hand hides the arrow the moment it lands, without
+         waiting for the browser to report a hold: the arrow is a claim about
+         what the agent did, and a claim that outlives the agent's turn is a lie
+         the person has to look past. It returns when their hand stops. */
+      const [hand, setHand] = React.useState(false)
+      const handTimer = React.useRef(0)
+      const touched = () => {
+        setHand(true)
+        clearTimeout(handTimer.current)
+        handTimer.current = setTimeout(() => setHand(false), 1500)
+      }
+      const hearHold = (message) => {
+        const hold = Number(message?.hold ?? 0)
+        if (!Number.isFinite(hold) || hold <= 0) return
+        setPerson(true)
+        clearTimeout(personTimer.current)
+        personTimer.current = setTimeout(() => setPerson(false), hold + 120)
+      }
       const [phase, setPhase] = React.useState('connecting')
       const [note, setNote] = React.useState('')
+      /* The address this chat had before its tab went away: the pane reopens
+         that address, so a lost picture costs one click. */
+      const [back, setBack] = React.useState('')
       const [url, setUrl] = React.useState('')
       const [draft, setDraft] = React.useState('')
       const [editing, setEditing] = React.useState(false)
@@ -263,13 +357,48 @@ window.__ModuleLoader__.load({
       React.useEffect(() => {
         let alive = true
         let dropped = false
+        /* The tab is still in this chat's column, so this chat may say the
+           mirror is its own: a reload forgets the owner, and a pane that only
+           waited would stay dark until some tool ran. */
+        const reclaim = () => {
+          const id = String(props.sessionId ?? '')
+          if (id === '') return
+          void fetch(`${ROUTE}/sidecar/claim`, { // ui-copy-ignore
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ session: id }),
+          })
+            .then((reply) => (reply.ok === true ? reply.json() : null))
+            .then((info) => {
+              if (alive !== true) return
+              if (info?.ok === true) {
+                setOwner(id)
+                /* The owner was just named, so the next poll may adopt the
+                   browser: ask now instead of up to a poll later. */
+                setTimeout(read, 0)
+              }
+            })
+            .catch(() => {})
+        }
         const read = () => {
-          void fetch(`${ROUTE}/sidecar/state`, { cache: 'no-store' }) // ui-copy-ignore
+          const who = String(props.sessionId ?? '')
+          /* Naming the chat lets a browser that outlived a reload be picked
+             up for us; an anonymous poll cannot, and the column would sit on
+             an empty stage with the browser running behind it. */
+          void fetch(`${ROUTE}/sidecar/state?session=${encodeURIComponent(who)}`, { cache: 'no-store' }) // ui-copy-ignore
             .then((reply) => (reply.ok === true ? reply.json() : null))
             .then((info) => {
               if (alive !== true) return
               const next = String(info?.owner ?? '')
+              const asked = String(props.sessionId ?? '')
+              /* Nobody owns it, or this chat does but the note was lost: ask
+                 back instead of showing a note for a browser this column shows. */
+              if (asked !== '' && next !== asked) reclaim()
               setOwner((prev) => (prev === next ? prev : next))
+              /* A browser that is gone still remembers where this chat was:
+                 keep the address so the pane can offer to reopen it. */
+              const was = String(info?.chat?.remembered ?? '')
+              if (was !== '') setBack((prev) => (prev === was ? prev : was))
               /* Another chat holds the browser now: this tab goes away instead
                  of sitting here as a note. */
               if (dropped !== true && next !== '' && next !== String(props.sessionId ?? '')) {
@@ -297,9 +426,15 @@ window.__ModuleLoader__.load({
          this chat keeps only a note. // ui-copy-ignore */
       const unknown = owner === null
       const mine = unknown !== true && owner === asked
+      /* A picture that stops arriving has to come back by itself: the pane
+         re-opens its stream instead of sitting on an empty stage until the
+         person reloads the page. */
+      const [attempt, setAttempt] = React.useState(0)
+      const drawnAt = React.useRef(0)
 
       React.useEffect(() => {
         if (mine !== true) return undefined
+        drawnAt.current = Date.now()
         const who = encodeURIComponent(String(props.sessionId ?? ''))
         const source = new EventSource(`${ROUTE}/sidecar/frames?session=${who}`)
         /* Bursts arrive faster than a picture can decode: only the newest frame
@@ -315,15 +450,25 @@ window.__ModuleLoader__.load({
           pending = null
           setFrame(message)
           setPtr(message.pointer ?? null)
+          if (Number.isFinite(Number(message.w)) && Number.isFinite(Number(message.h))) {
+            setView({ w: Number(message.w), h: Number(message.h) })
+          }
           setPhase('live')
+          drawnAt.current = Date.now()
           if (typeof message.url === 'string' && message.url !== '') setUrl(message.url)
         }
         const draw = (message) => {
+          hearHold(message)
           pending = message
           if (raf !== 0) return
           if (typeof requestAnimationFrame === 'function') raf = requestAnimationFrame(paint)
           else paint()
         }
+        const stuck = setInterval(() => {
+          /* Hello alone is not a picture: six quiet seconds means the stream is
+             dead, so ask for a new one. */
+          if (Date.now() - drawnAt.current > 6000) setAttempt((n) => n + 1)
+        }, 3000)
         source.onmessage = (event) => {
           let message
           try {
@@ -333,13 +478,16 @@ window.__ModuleLoader__.load({
           }
           if (message.type === 'hello') {
             setPhase('live')
+            drawnAt.current = Date.now()
             setUrl(String(message.url ?? ''))
+            setBack(String(message.chat?.remembered ?? ''))
           } else if (message.type === 'failed') {
             setPhase('failed')
             setNote(String(message.text ?? ''))
           } else if (message.type === 'pointer') {
             /* The arrow is drawn the moment the agent moves, not when the page
                next repaints: it stays honest even on a page that is idle. */
+            hearHold(message)
             setPtr(message.pointer ?? null)
           } else if (typeof message.jpeg === 'string') {
             draw(message)
@@ -347,10 +495,13 @@ window.__ModuleLoader__.load({
         }
         source.onerror = () => setPhase('lost')
         return () => {
+          clearInterval(stuck)
+          clearTimeout(personTimer.current)
+          clearTimeout(handTimer.current)
           if (raf !== 0 && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(raf)
           source.close()
         }
-      }, [props.sessionId, mine])
+      }, [props.sessionId, mine, attempt])
 
       /* The address field follows the page except while the person is editing it. */
       React.useEffect(() => {
@@ -370,9 +521,49 @@ window.__ModuleLoader__.load({
         return () => observer.disconnect()
       }, [])
 
-      const scale = size.w > 0 && size.h > 0 ? Math.min(size.w / SIDE_VIEW.width, size.h / SIDE_VIEW.height) : 0
-      const padX = (size.w - SIDE_VIEW.width * scale) / 2
-      const padY = (size.h - SIDE_VIEW.height * scale) / 2
+      const scale = size.w > 0 && size.h > 0 ? Math.min(size.w / view.w, size.h / view.h) : 0
+      const padX = (size.w - view.w * scale) / 2
+      const padY = (size.h - view.h * scale) / 2
+
+      /* The column tells the page how big it is, a beat after the resize stops:
+         a page that relayouts on every pointer step would never settle. */
+      React.useEffect(() => {
+        if (mine !== true || size.w < 200 || size.h < 200) return undefined
+        /* The page already has that shape: a resize that lands between two
+           viewport sizes would only cost a relayout and another frame. */
+        if (Math.abs(Number(view?.w ?? 0) - size.w) < 1 && Math.abs(Number(view?.h ?? 0) - size.h) < 1) return undefined
+        /* The page is told the column's size a beat after the resize stops, and
+           again until the browser says it took it: a request that arrives while
+           the page is still starting is refused, and a pane that gives up then
+           keeps a letterboxed picture for as long as it stays open. */
+        let live = true
+        let tries = 0
+        let timer = 0
+        const send = () => {
+          if (!live) return
+          fetch(`${ROUTE}/sidecar/viewport`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ session: String(props.sessionId ?? ''), w: Math.round(size.w), h: Math.round(size.h) }),
+          })
+            .then((answer) => (answer.ok === true ? answer.json() : { ok: false }))
+            .then((said) => {
+              if (!live || said?.ok === true || tries >= 5) return
+              tries += 1
+              timer = setTimeout(send, 400)
+            })
+            .catch(() => {
+              if (!live || tries >= 5) return
+              tries += 1
+              timer = setTimeout(send, 600)
+            })
+        }
+        timer = setTimeout(send, 250)
+        return () => {
+          live = false
+          clearTimeout(timer)
+        }
+      }, [mine, size.w, size.h, view?.w, view?.h])
 
       const who = String(props.sessionId ?? '')
       const post = (path, body) => {
@@ -409,7 +600,7 @@ window.__ModuleLoader__.load({
         const box = el.getBoundingClientRect()
         const x = (event.clientX - box.left - padX) / scale
         const y = (event.clientY - box.top - padY) / scale
-        if (x < 0 || y < 0 || x > SIDE_VIEW.width || y > SIDE_VIEW.height) return null
+        if (x < 0 || y < 0 || x > view.w || y > view.h) return null
         return { x: Math.round(x), y: Math.round(y) }
       }
       const ime = React.useRef(null)
@@ -425,6 +616,7 @@ window.__ModuleLoader__.load({
       }
       const stageRef = stage
       const onPointerDown = (event) => {
+        touched()
         const point = toView(event)
         if (point === null) return
         const field = ime.current
@@ -437,6 +629,7 @@ window.__ModuleLoader__.load({
       }
       const movedAt = React.useRef(0)
       const onPointerMove = (event) => {
+        touched()
         const point = toView(event)
         if (point === null) return
         /* Hover is part of a page: menus open under the hand, so the movement
@@ -448,24 +641,46 @@ window.__ModuleLoader__.load({
         hover(point)
       }
       const onWheel = (event) => {
+        touched()
         event.preventDefault()
-        const point = toView(event) ?? { x: Math.round(SIDE_VIEW.width / 2), y: Math.round(SIDE_VIEW.height / 2) }
+        const point = toView(event) ?? { x: Math.round(view.w / 2), y: Math.round(view.h / 2) }
         post('/sidecar/input', { kind: 'wheel', x: point.x, y: point.y, dx: event.deltaX, dy: event.deltaY })
       }
+      /* The page's keys are the person's keys: shift makes a capital, a
+         shortcut stays a shortcut so Ctrl+V pastes and Ctrl+A selects, and the
+         key that goes down also goes up so a game can hold it. */
+      const modsOf = (event) => (event.altKey === true ? 1 : 0)
+        | (event.ctrlKey === true ? 2 : 0)
+        | (event.metaKey === true ? 4 : 0)
+        | (event.shiftKey === true ? 8 : 0)
+      const MODIFIER_KEYS = ['Alt', 'Control', 'Meta', 'Shift', 'AltGraph', 'OS', 'Super', 'Hyper']
+      const keyBody = (event, down) => {
+        const modifiers = modsOf(event)
+        const shortcut = (modifiers & 7) !== 0
+        const typing = down === true && event.key.length === 1 && (modifiers & 7) === 0 && event.repeat !== true
+        return {
+          kind: 'key',
+          key: event.key,
+          code: event.code || event.key,
+          keyCode: event.keyCode || 0,
+          modifiers,
+          ...(typing ? { text: event.key } : {}),
+          ...(down === false ? { down: false } : {}),
+        }
+      }
       const onKeyDown = (event) => {
+        touched()
         /* A key still being composed belongs to the IME, not to the page. */
         if (event.isComposing === true) return
-        const named = ['Enter', 'Tab', 'Escape', 'Backspace', 'Delete', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown']
-        if (named.includes(event.key) === true) {
-          event.preventDefault()
-          post('/sidecar/input', { kind: 'key', key: event.key, code: event.code || event.key, keyCode: event.keyCode || 0 }) // ui-copy-ignore
-          return
-        }
-        if (event.metaKey === true || event.ctrlKey === true || event.altKey === true) return
-        if (event.key != null && event.key.length === 1) {
-          event.preventDefault()
-          post('/sidecar/input', { kind: 'text', text: event.key })
-        }
+        if (event.key == null || MODIFIER_KEYS.includes(event.key) === true) return
+        event.preventDefault()
+        post('/sidecar/input', event.repeat === true ? { ...keyBody(event, true), repeat: true } : keyBody(event, true))
+      }
+      const onKeyUp = (event) => {
+        if (event.isComposing === true) return
+        if (event.key == null || MODIFIER_KEYS.includes(event.key) === true) return
+        event.preventDefault()
+        post('/sidecar/input', keyBody(event, false))
       }
       const goto = () => {
         const address = String(draft ?? '').trim()
@@ -479,7 +694,7 @@ window.__ModuleLoader__.load({
         return h('div', { className: 'dshib-side' },
           h('div', { className: 'dshib-side-note' }, L('side.foreign')))
       }
-      const pointer = ptr
+      const pointer = person === true || hand === true ? null : ptr
       const noteText = phase === 'failed' ? note || L('side.failed') : phase === 'live' ? L('side.empty') : L('side.connecting')
       return h('div', { className: 'dshib-side' },
         h('div', { className: 'dshib-side-bar' },
@@ -509,8 +724,26 @@ window.__ModuleLoader__.load({
           onPointerMove,
           onWheel,
           onKeyDown,
+          onKeyUp,
         },
-          frame === null ? h('div', { className: 'dshib-side-note' }, noteText) : null,
+          frame === null && back !== ''
+            ? h('button', {
+              className: 'dshib-side-back',
+              type: 'button', // ui-copy-ignore
+              onClick: () => { // ui-copy-ignore
+                void fetch(`${ROUTE}/sidecar/open`, { // ui-copy-ignore
+                  method: 'POST',
+                  headers: { 'content-type': 'application/json' },
+                  body: JSON.stringify({ session: who, url: back }), // ui-copy-ignore
+                })
+                  .then((reply) => (reply.ok === true ? reply.json() : null))
+                  .then((info) => {
+                    if (info?.ok === true) setAttempt((n) => n + 1)
+                  })
+                  .catch(() => {})
+              },
+            }, L('side.restore'))
+            : frame === null ? h('div', { className: 'dshib-side-note' }, noteText) : null,
           h('textarea', {
             className: 'dshib-side-ime',
             ref: ime,
@@ -532,12 +765,13 @@ window.__ModuleLoader__.load({
               clearIme()
             },
             onKeyDown,
+            onKeyUp,
           }),
           frame === null ? null : h('img', {
             className: 'dshib-side-frame',
             src: `data:image/jpeg;base64,${frame.jpeg}`,
-            width: Math.max(1, Math.round(SIDE_VIEW.width * scale)),
-            height: Math.max(1, Math.round(SIDE_VIEW.height * scale)),
+            width: Math.max(1, Math.round(view.w * scale)),
+            height: Math.max(1, Math.round(view.h * scale)),
             alt: '', // ui-copy-ignore
             draggable: false,
           }),

package/docs/ARCHITECTURE.md

@@ -4,7 +4,7 @@ Two halves in two processes, and a Chrome that neither of them is.
 
 ```
 server side  (index.js, in the DSH process)
-  sidecar_* tools ──> Sidecar ── CDP over a socket ──> headless Chrome
+  browser_* tools ──> Sidecar ── CDP over a socket ──> headless Chrome
                          │
   HTTP + SSE routes <────┘
         │
@@ -41,7 +41,7 @@ Other launch flags:
 | `--use-mock-keychain`, `--password-store=basic` | No keychain prompt on macOS. |
 | `--remote-allow-origins=*` | The CDP client connects over a plain WebSocket. |
 | `--disable-blink-features=AutomationControlled` | Sites that sniff for automation get the ordinary path. |
-| `--window-size=1440,900`, `--lang=zh-CN` | The viewport the pane mirrors, and a Chinese page locale. |
+| `--window-size=1440,900`, `--lang=zh-CN` | The window the browser starts in, and a Chinese page locale; the layout viewport is set to the column instead. |
 
 The binary comes from a fixed list: Google Chrome, Chromium or Canary under `/Applications`,
 then `/usr/bin/google-chrome` and `/usr/bin/chromium`. Nothing else is probed and there is no
@@ -58,7 +58,7 @@ The browser outlives the plugin:
    `/json/new?about:blank` as a fallback) and a client connects to it.
 
 One page per browser. `apply()` only constructs the `Sidecar`; no process exists until the
-first tool call, and `sidecar_state` reports a stopped browser without starting one.
+first tool call, and `browser_state` reports a stopped browser without starting one.
 
 Shutdown asks Chrome to close (`Browser.close`), waits briefly, then sends `SIGTERM`, which is
 the point where Chrome flushes cookies. An idle timer closes the browser after 15 minutes; a
@@ -85,13 +85,16 @@ the CDP socket stays in the server half.
 ## Mirror
 
 The server half starts `Page.startScreencast` with JPEG quality 72, `maxWidth` and `maxHeight`
-at 1440×900, `optimizeForSpeed`, `everyNthFrame: 1`, and acknowledges every frame it receives
+at the pane's size, `optimizeForSpeed`, `everyNthFrame: 1`, and acknowledges every frame it receives
 so Chrome keeps sending. Frames are never queued: with two frames in flight, further frames
 are dropped and the next one that fits takes their place. A slow reader loses frames, never
 freshness.
 
-The viewport is pinned with `Emulation.setDeviceMetricsOverride` to the same 1440×900, so a
-frame is the whole page as laid out, not a crop.
+The layout viewport follows the column: the pane measures itself, posts the size to
+`/sidecar/viewport` a beat after the resize settles, and the server pins
+`Emulation.setDeviceMetricsOverride` to that size and restarts the screencast at it. So a frame
+is the whole page as laid out at the shape it is shown in — no letterbox bands, no crop. Sizes
+below 320 px or above 1920×1600 are ignored rather than applied as a sliver.
 
 If `Browser.getVersion` reports `HeadlessChrome`, the user agent is overridden with an ordinary
 Chrome string, `acceptLanguage: 'zh-CN,zh;q=0.9,en;q=0.8'` and `platform: 'MacIntel'`, so a site
@@ -133,7 +136,7 @@ browser without pulling the column away from the person reading it.
 
 `sidecarTools()` in `tools.js` builds the 28 definitions and `index.js` registers them on the
 plugin's tool scope. All of them return one text block. A page read numbers the controls and
-keeps those numbers across later reads, so `sidecar_click` by ref means the element the model
+keeps those numbers across later reads, so `browser_click` by ref means the element the model
 last saw; navigation drops them and the model gets `REF_GONE` rather than a wrong click.
 
 Before a ref click or a ref focus, one page-side probe asks what is on top of that control.
@@ -145,7 +148,7 @@ reported, never accepted on the person's behalf. The whole exchange is one `Runt
 and a possible `mousePressed`/`mouseReleased` pair on an already-open CDP connection, so an
 uncovered click pays nothing.
 
-`sidecar_do` runs the same probe before a step that names a control — by `ref`, by
+`browser_do` runs the same probe before a step that names a control — by `ref`, by
 text, or by field label — so a banner the first step clears is gone for the rest of
 the batch, and the step's own line says it in one clause (`after Accept on a banner,`).
 A batch therefore pays for one overlay, not one per step.
@@ -154,7 +157,7 @@ An action answers with one line — address, title, focused field — and reads
 `read: true` is passed. That is what keeps a long batch cheap (see `BENCH.md`).
 
 Calls that touch the browser are marked not concurrency-safe; reading state, console and failed
-requests is. `sidecar_open`, `sidecar_view`, `sidecar_wait` and `sidecar_shot` carry longer
+requests is. `browser_open`, `browser_view`, `browser_wait` and `browser_shot` carry longer
 timeouts than the rest.
 
 Sign-in state lives in the profile, and session cookies — the kind a sign-in usually sets,
@@ -169,7 +172,7 @@ without asking first when someone wants something done on a site.
 `Network.enable` is already on for the mirror. A request is kept when it is
 sent and settled when its response arrives, so the list holds method, status,
 type and address of what the page actually got — 120 rows, oldest dropped.
-`sidecar_network` reads that list without touching the page, which is why it
+`browser_network` reads that list without touching the page, which is why it
 can answer while a dialog is open.
 
 ## Downloads
@@ -177,7 +180,7 @@ can answer while a dialog is open.
 Chrome is pointed at `<profile>/downloads` when the page starts, so a click
 that saves a file writes it there instead of nowhere. The folder belongs to
 the profile: it is the same one on the next launch, and nothing outside the
-profile is touched. `sidecar_downloads` lists what is on disk, newest first;
+profile is touched. `browser_downloads` lists what is on disk, newest first;
 a `.crdownload` still in flight is not listed.
 
 ## Frames and popups
@@ -215,4 +218,4 @@ and there is still one page to drive.
 | `locale/*.json` | Page: pane labels. |
 
 Data on disk is confined to `~/.dsh/inner-browser-use/`: `chrome/<profile>` for the browser,
-`screenshots/` for `sidecar_shot`.
+`screenshots/` for `browser_shot`.

package/docs/ARTIFACTS.md

@@ -0,0 +1,19 @@
+# 文件落在哪里
+
+浏览器产生的东西——截图、抓下来的图、打印的 PDF——不落在项目根目录，也不散在 home 下。固定规则：
+
+```
+~/.dsh-inner-browser-use/artifacts/<项目>/<会话>/<种类>/
+```
+
+- **项目**：会话工作目录的文件夹名，加路径哈希前 6 位，例如 `dsh-inner-browser-use-a1b2c3`。同名文件夹、不同路径不会混。
+- **会话**：会话 id 去掉 `session-` 后的前 8 位，例如 `72557d6e`。同一项目里两个会话各存各的。
+- **种类**：`shots/` 是 `browser_shot` 的截图，`pictures/` 是 `browser_grab` 抓的图，`pdf/` 是 `browser_pdf` 打印的文档。
+
+文件名默认带时间戳（`shot-20261028-124500.png`），给了 `name` 就用它；名字里的分隔符、连续点、开头点都会被去掉，跳不出这个目录。
+
+每个种类保留最新 40 个文件，旧的自动删，免得跑一天的会话留下一个没人翻得动的文件夹。开着的文件不会被删掉（尽力删除，失败就留着）。
+
+调用环境里没有项目或会话信息时，落到 `no-project/no-chat/<种类>/`，不猜。
+
+测试里用 `DSH_INNER_BROWSER_ARTIFACTS` 指向临时目录，不写真实 home。