dsh-local-link 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,54 @@
2
2
 
3
3
  All notable changes to this project are documented here.
4
4
 
5
+ ## 0.2.1 — 2026-08-29
6
+
7
+ ### Fixed
8
+
9
+ - Quoted the `trustedHosts` JavaScript expression in the bundled Cordis overlay so a clean npm installation parses and boots with the strict DSH patch-list YAML schema.
10
+
11
+ ## 0.2.0 — 2026-08-29
12
+
13
+ ### Added
14
+
15
+ - Phone and tablet Mobile View with drawer navigation, safe-area support, and automatic viewport activation through the native Harness client.
16
+ - Current session drawer with context usage and breakdown, model, workspace access, agent preset, session activity, and native session-log download.
17
+ - Touch-friendly subagent status chip and bottom sheet built from Harness session catalogs and actions.
18
+ - Visible total/active subagent counts mirrored in the compact control's accessible name.
19
+ - Mobile appearance control driven by the Harness theme service.
20
+ - Shared mobile-dialog focus lifecycle with initial focus, keyboard containment, Escape handling, and focus restoration.
21
+ - English and Chinese copy for the pre-Harness automatic pairing page, selected from the browser language.
22
+ - A dedicated Mobile View guide and release acceptance matrix.
23
+
24
+ ### Changed
25
+
26
+ - Reworked the stock Web client's cramped desktop-oriented narrow-screen presentation into touch-friendly navigation, session details, subagent controls, and conversation geometry without introducing a replacement client.
27
+ - Mobile View now enhances the shipped Harness AppFrame without replacing the root layout, preserving dynamic conversation views, overlays, composer extensions, and third-party registrations.
28
+ - The subagent duration clock now runs only while a visible catalog contains active work; it observes no network or session data itself.
29
+ - Authenticated gateway authorities now enter the official connection `trustedHosts` contract while privileged settings, credential, Host, and preset-authoring RPCs remain loopback-only.
30
+ - The gateway preserves the browser's original Host and origin headers instead of impersonating the loopback origin.
31
+ - Remote gateway boot omits the host directory-picker capability, so `Add workspace` is not offered while existing workspaces and sessions remain available.
32
+ - Plugin-owned controls use Harness button/input primitives, semantic tokens, and one shared Local Link hairline border variable.
33
+ - Left navigation, details, and Current session surfaces use the same compact drawer width.
34
+
35
+ ### Fixed
36
+
37
+ - Prevented the mobile keyboard from opening automatically after switching sessions.
38
+ - Restored immediate access to native session and active-workspace overflow actions on touch devices.
39
+ - Separated the DeepSeek Harness brand and appearance-control hit areas.
40
+ - Kept Cordis panels viewport-bound and readable in the responsive mobile presentation.
41
+ - Removed QR-panel overflow artifacts and normalized Local access, diagnostics, device, and mobile border weight.
42
+ - Matched the documented Mobile View activation boundary at `834` CSS pixels.
43
+ - Rejected public listener addresses, loopback-lookalike Host/Origin values, and malformed device cookies without widening access or destabilizing the gateway.
44
+ - Allowed device-state persistence to recover after a transient filesystem failure instead of poisoning every later write until restart.
45
+ - Kept background diagnostics fail-soft while making an explicit `Clear` report persistence errors honestly and recover on the next attempt.
46
+
47
+ ### Compatibility notes
48
+
49
+ - Mobile View targets DeepSeek Harness `0.1.1-rc.2`; responsive layout and several stock-DOM presentation hooks remain version-sensitive.
50
+ - A remote browser inherits the selected Harness session permissions. Hiding `Add workspace` is a mobile UX constraint, not an authorization boundary.
51
+ - In the supported Harness release, a remote light/dark choice is memory-backed and resets on reload to the host preference resolved against the remote device's system theme.
52
+
5
53
  ## 0.1.0 — 2026-08-28
6
54
 
7
55
  ### Added
package/README.md CHANGED
@@ -4,11 +4,13 @@
4
4
  [![npm](https://img.shields.io/npm/v/dsh-local-link.svg)](https://www.npmjs.com/package/dsh-local-link)
5
5
  [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
6
 
7
- Lightweight local-network access to the complete [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web interface.
7
+ Lightweight, self-hosted [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin for paired LAN access and a practical Mobile View of the complete DSH Web interface.
8
8
 
9
9
  Open `Local access`, scan one QR code, and continue the desktop's currently selected Harness session from a phone, tablet, or another computer on the same private network. There is no hosted relay, tunnel provider, native application, account, replacement chat UI, or second workspace picker.
10
10
 
11
- > **Preview security boundary:** the `0.1.x` gateway uses plain HTTP and is intended only for a trusted private network. Do not expose its port to the internet or use it on public Wi-Fi.
11
+ Version `0.2.0` also addresses the stock Web client's desktop-first behavior on narrow touch screens. It reorganizes the existing Harness interface into responsive drawers, compact session controls, and touch-friendly actions while keeping the same client, session, plugin slots, permissions, and live agent stream.
12
+
13
+ > **Preview security boundary:** the gateway uses plain HTTP and is intended only for a trusted private network. Do not expose its port to the internet or use it on public Wi-Fi.
12
14
 
13
15
  ## Install
14
16
 
@@ -21,8 +23,6 @@ dsh plugin --profile web add dsh-local-link
21
23
  dsh web
22
24
  ```
23
25
 
24
- This command becomes installable with the first public npm release. Until then, use the source checkout below.
25
-
26
26
  ### Git clone — development checkout
27
27
 
28
28
  Requirements: Git, Node.js 22.19+ or 24+, Corepack, and a global `dsh` installation running DeepSeek Harness `0.1.1-rc.2`.
@@ -49,10 +49,49 @@ The profile points at the checkout, so rebuild after changing client code and re
49
49
 
50
50
  The invitation is one-use, expires after five minutes by default, and is replaced immediately when `Generate another code` is selected.
51
51
 
52
+ Phone and tablet browsers automatically receive Mobile View when the viewport is at most 834 CSS pixels wide. The same responsive behavior can be previewed with browser device emulation; no URL parameter, user-agent switch, or second client is involved.
53
+
52
54
  <p align="center">
53
55
  <img src="docs/images/local-access-qr.jpg" width="960" alt="DeepSeek Harness with the Local access QR panel, one-time link, and Paired devices shortcut">
54
56
  </p>
55
57
 
58
+ ## Mobile View
59
+
60
+ The stock Harness Web interface is difficult to operate on a phone: persistent desktop navigation consumes the viewport, session controls compete with the conversation title, several actions depend on hover or long press, and subagent information is too dense for a narrow screen. Mobile View makes that existing interface usable without introducing a second client or duplicating Harness business logic.
61
+
62
+ | Stock narrow-screen behavior | Mobile View in `0.2.0` |
63
+ | --- | --- |
64
+ | Desktop navigation competes with the conversation | Workspace and session navigation opens as a dismissible left drawer |
65
+ | Session metadata crowds the header | Context, model, access, preset, activity, and export move into a compact right drawer |
66
+ | Subagent details are difficult to scan or reach | Total/active status stays near the composer and the native catalog opens as a bottom sheet |
67
+ | Hover-oriented session and workspace actions | Overflow actions remain visible and touch-accessible |
68
+ | Session changes can summon the software keyboard | Automatic composer focus is suppressed while intentional input focus still works |
69
+ | Desktop spacing ignores phone safe areas | Header, composer, tabs, media, overlays, and scrolling adapt to narrow viewports |
70
+
71
+ The implementation changes presentation, not Harness ownership or behavior:
72
+
73
+ - the native workspace/session browser becomes a left drawer;
74
+ - dynamic Chat, Trajectory, composer, overlay, and third-party plugin slots remain intact;
75
+ - Current session opens from the header with context breakdown, model, workspace access, preset, activity, and session-log download;
76
+ - child-agent status shows total and active counts, then opens the native nested catalog as a touch-friendly bottom sheet;
77
+ - the Harness theme service powers a compact sun/moon action;
78
+ - session and active-workspace menus stay immediately available on touch screens;
79
+ - safe areas, scrollable tabs, bounded media, and virtual-keyboard behavior are adapted for narrow viewports;
80
+ - plugin-owned modal drawers contain keyboard focus and return it to the invoking control when closed;
81
+ - existing workspaces remain available, while the misleading remote `Add workspace` directory picker is omitted.
82
+
83
+ These previews are captured from the running Harness client at a `430 × 932` viewport with non-persistent sample content; the thin rounded frame is presentation-only.
84
+
85
+ | Navigation | Current session | Subagents | Conversation |
86
+ | :---: | :---: | :---: | :---: |
87
+ | <img src="docs/images/mobile-navigation.png" width="210" alt="Live Mobile View left navigation drawer with native workspace and session actions"> | <img src="docs/images/mobile-session-info.png" width="210" alt="Live Mobile View Current session drawer with context, model, workspace access, preset, activity, and session log"> | <img src="docs/images/mobile-subagents.png" width="210" alt="Live Mobile View nested subagent sheet with activity, tokens, and duration"> | <img src="docs/images/mobile-chat.png" width="210" alt="Live Mobile View Harness conversation, composer, and visible total and active subagent counts"> |
88
+
89
+ ### Permissions
90
+
91
+ The remote browser inherits the selected Harness session's **Read only**, **Workspace write**, or **Full access** authority. Mobile View displays that value but does not create or weaken a permission layer. Hiding `Add workspace` is a usability constraint, not an authorization boundary.
92
+
93
+ The responsive enhancements target viewports from 360 through 834 CSS pixels wide. The release matrix covers `360 × 800`, `390 × 844`, `430 × 932`, and `768 × 1024`, plus portrait/landscape checks on a real phone. See [Mobile View](docs/MOBILE_VIEW.md) for behavior, theme persistence, compatibility surfaces, and the complete acceptance checklist.
94
+
56
95
  ### Manage trusted browsers
57
96
 
58
97
  Use `Paired devices` in the QR panel or open `Settings → Local access`. Each new browser starts as `My device`; its subtitle is detected automatically, for example `Phone · Chrome`, `Tablet · Safari`, or `Computer · Edge`.
@@ -80,6 +119,7 @@ Expand `Diagnostics` on the same Settings page to inspect the most recent local
80
119
  - **Two runtime dependencies:** configuration schema support and QR generation.
81
120
  - **No fingerprinting:** access is a random per-browser credential, not a device identity guess.
82
121
  - **Native extension points:** sidebar and Settings content use Harness slots and locale services.
122
+ - **Native responsive enhancement:** the shipped Harness AppFrame stays mounted; registered conversation views and overlays remain dynamic.
83
123
  - **JSON localization:** all visible plugin copy lives in matching locale dictionaries.
84
124
  - **Local diagnostics:** a bounded, redacted event history helps debug installs without analytics or an external collector.
85
125
 
@@ -100,6 +140,8 @@ The gateway does not create a second Harness session. During first connection it
100
140
 
101
141
  Authorization uses a 256-bit random cookie credential. Only its SHA-256 hash is stored. The editable name and detected device/browser text never grant access.
102
142
 
143
+ The LAN authority is declared through Harness's official connection `trustedHosts` contract. This enables ordinary session API and WebSocket traffic without pretending that the phone is loopback; Settings, credentials, native Host actions, and agent-preset authoring remain loopback-only.
144
+
103
145
  ## Configuration
104
146
 
105
147
  The bundled profile patch installs conservative defaults:
@@ -116,6 +158,8 @@ The bundled profile patch installs conservative defaults:
116
158
  | `diagnosticsMaxEntries` | `15` | Maximum retained events (`5`–`200`). |
117
159
  | `diagnosticsFile` | next to `stateFile` | Local JSON event store; the bundled profile uses `~/.dsh/local-link/diagnostics.json`. |
118
160
 
161
+ `listenHost` accepts only `0.0.0.0` or an explicit private/loopback IP literal. Public listener addresses are rejected during startup; this configuration guard complements, rather than replaces, the operating-system firewall.
162
+
119
163
  `trusted-lan` disables per-device authorization and should be reserved for isolated development networks. `pairing` is the supported default because a connected Harness browser can read files, submit prompts, approve actions, and trigger commands.
120
164
 
121
165
  The plugin never creates firewall rules. If Windows prompts for network access, allow only the **Private** network profile and never forward port `3088` on the router.
@@ -138,12 +182,14 @@ The report never includes secrets, addresses, IDs, names, URLs, paths, prompts,
138
182
 
139
183
  Harness's active language selects the plugin dictionary; the plugin has no separate language switch.
140
184
 
185
+ The minimal automatic pairing page loads before Harness locale services are available. It reuses the same dictionaries and selects English or Chinese from the connecting browser's language list; English is the fallback.
186
+
141
187
  | Language | Dictionary | Status |
142
188
  | --- | --- | --- |
143
189
  | English | `src/locales/en.json` | Included |
144
190
  | Chinese | `src/locales/zh.json` | Included |
145
191
 
146
- Dictionary keys are checked for parity in tests. To add a locale, copy `en.json`, translate values without changing keys, register the locale ID in `src/client.tsx`, and run `npm test`.
192
+ Dictionary keys are checked for parity in tests. To add a locale, copy `en.json`, translate values without changing keys, register the locale ID in `src/client.tsx`, extend the pre-client pairing-page language map in `src/gateway/pair-page.ts`, and run `npm test`.
147
193
 
148
194
  ## Development
149
195
 
@@ -158,6 +204,7 @@ npm run verify
158
204
  Project documentation:
159
205
 
160
206
  - [Architecture and compatibility boundaries](docs/ARCHITECTURE.md)
207
+ - [Mobile View behavior and release matrix](docs/MOBILE_VIEW.md)
161
208
  - [Local diagnostics and event codes](docs/DIAGNOSTICS.md)
162
209
  - [Security model](docs/SECURITY.md)
163
210
  - [Contributing](CONTRIBUTING.md)
@@ -165,16 +212,24 @@ Project documentation:
165
212
 
166
213
  ## Known limitations
167
214
 
168
- - LAN traffic is not encrypted in `0.1.x`.
215
+ - LAN traffic is not encrypted in the current preview gateway.
169
216
  - Revocation blocks new requests and reconnects but does not yet terminate an already-open WebSocket.
170
217
  - The shortcut that opens a specific Settings section uses a small semantic compatibility bridge because Harness `0.1.1-rc.2` exposes `openSection` only to onboarding.
171
218
  - Harness's footer-action container needs a compatibility layout rule when the full-width Cordis action is present.
172
219
  - Compatibility is currently pinned to DeepSeek Harness `0.1.1-rc.2` and must be retested for each supported Harness release.
220
+ - Mobile View targets viewports from 360 CSS pixels wide, but third-party fixed-width views, virtual keyboards, orientation changes, split-screen browsers, and operating-system text scaling still require real-device acceptance.
221
+ - Plugin-owned buttons and text inputs use Harness `Button` and `Input` primitives and their semantic variants. Harness `0.1.1-rc.2` still has no public responsive-shell, spacing, or radius contract, so mobile geometry, responsive compositions, and the few missing primitive icons remain documented design-system compatibility risks.
173
222
 
174
223
  ## Development disclosure
175
224
 
176
225
  The initial implementation and documentation were developed collaboratively with OpenAI Codex. Changes remain subject to maintainer review, automated tests, security review, and the same contribution requirements as human-authored changes. No runtime AI service, telemetry, or generated-code dependency is included in the package.
177
226
 
227
+ ## Acknowledgements
228
+
229
+ The mobile UX research included the MIT-licensed [DSH Mobile](https://github.com/sorsama/deepseek-harness-mobile) project by its contributors. Its mobile navigation, session-details, subagent, and activity-status presentation helped inform the interaction direction used here.
230
+
231
+ No DSH Mobile source code or assets are included in this package. Local Link implements its Mobile View independently in TypeScript and React, using the stock Harness client, design primitives, services, and plugin slots instead of shipping a replacement Android client.
232
+
178
233
  ## License
179
234
 
180
235
  [MIT](LICENSE) © 2026 dsh-local-link contributors.
package/cordis.patch.yml CHANGED
@@ -1,5 +1,12 @@
1
1
  # Adds one Host gateway and one Web client settings page without replacing any
2
- # stock DeepSeek Harness module.
2
+ # stock DeepSeek Harness module. The stock connection receives the gateway's
3
+ # LAN authorities through its public trustedHosts contract. Harness still keeps
4
+ # settings, credentials, native Host actions, and preset authoring loopback-only.
5
+ - id: connection
6
+ inject: [webRuntime, localLinkGateway]
7
+ config:
8
+ trustedHosts: !!js "[...ctx.webRuntime.trustedHosts, ...ctx.localLinkGateway.trustedHosts]"
9
+
3
10
  - insert:
4
11
  - id: dsh-local-link
5
12
  name: dsh-local-link
@@ -15,15 +15,38 @@ The architecture follows six constraints:
15
15
 
16
16
  ## Components
17
17
 
18
+ ### Responsibility map
19
+
20
+ | Module | Single owned boundary |
21
+ | --- | --- |
22
+ | `src/plugin.ts` | Cordis lifecycle and loopback administration routing |
23
+ | `src/gateway/admin-auth.ts` | Structural loopback source, Host, and Origin validation |
24
+ | `src/gateway/local-gateway.ts` | LAN listener and authenticated HTTP/WebSocket transport orchestration |
25
+ | `src/auth/*` | Pairing-token and persisted device-credential state |
26
+ | `src/diagnostics.ts` | Bounded, privacy-filtered failure history |
27
+ | `src/client.tsx` | Desktop Local access/Settings surfaces and client registration |
28
+ | `src/mobile-layout.tsx` | Responsive activation and stock AppFrame composition |
29
+ | `src/mobile-session-info.tsx` | Current-session projection and drawer |
30
+ | `src/mobile-subagents.tsx` | Native subagent catalog projection and sheet |
31
+ | `src/mobile-dialog.ts` | Shared modal focus, keyboard, and focus-restoration lifecycle |
32
+
33
+ State stores, transport, diagnostics, responsive orchestration, and individual mobile features remain separate. The larger TSX modules are feature compositions plus scoped CSS; they do not own gateway state, duplicate Harness session state, or perform their own transport.
34
+
18
35
  ### Host plugin
19
36
 
20
37
  `src/plugin.ts` owns lifecycle integration. It starts the gateway, registers a loopback-only administration route on the existing Harness Web server, and closes both registrations with the Cordis effect.
21
38
 
39
+ `src/gateway/admin-auth.ts` owns the administration route's source, Host, and Origin boundary. It parses authorities structurally and accepts only actual loopback IP literals or `localhost`; DNS names that merely begin with `127.` or `localhost` fail closed.
40
+
22
41
  ### LAN gateway
23
42
 
24
43
  `src/gateway/local-gateway.ts` owns the only non-loopback listener. It performs request-boundary validation, pairing, device-cookie authorization, and HTTP/WebSocket proxying.
25
44
 
26
- The gateway changes upstream `Host`, `Origin`, and fetch-site headers to the loopback Harness origin. This is safe only after the gateway has authenticated the device. It lets Harness retain its own loopback request fence rather than configuring the primary server for every LAN address.
45
+ Configuration accepts only the wildcard `0.0.0.0` or an explicit private/loopback listener address. The gateway independently rechecks the request source and exact IP-literal Host authority, so an unsafe public bind cannot be introduced accidentally through configuration.
46
+
47
+ After authentication, the gateway forwards the browser's original `Host`, `Origin`, referrer, and fetch-site headers to the loopback Harness listener. The Cordis profile patch supplies the gateway's current LAN authorities to the official connection module through its public `trustedHosts` option. Ordinary Harness API and WebSocket traffic can therefore pass the declared origin check without pretending to be loopback.
48
+
49
+ The connection module separately rechecks privileged configuration, credential, native Host-action, and agent-preset-authoring methods with an empty trust extension. Those operations remain loopback-only. `tests/trust-boundary.test.ts` exercises this split against the real connection package: a trusted gateway authority reaches ordinary dispatch while every privileged method returns `403`.
27
50
 
28
51
  ### Authentication state
29
52
 
@@ -39,7 +62,7 @@ The loopback administration route exposes list, clear, and a narrow allowlisted
39
62
 
40
63
  ### Client plugin
41
64
 
42
- `src/client.tsx` registers two normal Harness contributions: a compact desktop `sidebar.footer.action` that shows a QR code and copyable one-time link, and a desktop-only `settings.section` that manages paired devices and the local diagnostic report. It does not replace the root layout or mutate generated CSS-module class names.
65
+ `src/client.tsx` registers two normal Harness contributions: a compact desktop `sidebar.footer.action` that shows a QR code and copyable one-time link, and a desktop-only `settings.section` that manages paired devices and the local diagnostic report. It does not replace the root layout. The desktop surfaces use plugin-owned classes and semantic selectors; version-sensitive stock-DOM hooks are isolated in `src/mobile-layout.tsx` and documented below.
43
66
 
44
67
  The Harness `sidebar.footer.action` contract is a list, but `0.1.1-rc.2` renders that list as a horizontal flex row while the stock Cordis action reserves `width: 100%` with `flex: none`. Without a compatibility rule, Cordis reduces later actions to zero width. Local Link orders its entry first and changes only the footer container that semantically contains `.dsh-local-link-footer` into a vertical stack. The same scoped rule normalizes the list gap and removes the following action's private top margin so Local access, Cordis, and Settings keep one visual rhythm. The selector is anchored on the plugin-owned class and accounts for the slot renderer's `display: contents` wrapper; it never names a generated Harness class.
45
68
 
@@ -47,15 +70,49 @@ The connection card is fixed to the viewport and positioned from the rendered Lo
47
70
 
48
71
  Harness `0.1.1-rc.2` keeps settings open state and section selection private inside its shell; the public `openSection` callback is only projected to onboarding steps. The popover's `Paired devices` shortcut therefore uses one bounded compatibility bridge: it clicks the semantic settings dialog trigger and then the nav row matching this plugin's own localized section label. The bridge uses no generated class names, mutates no DOM, and can be removed when Harness exposes a general settings-navigation service.
49
72
 
50
- On an authenticated gateway page, the client contributes the trust hint required by the Harness client connection. The proxied index makes the Settings package depend on this contribution so configuration surfaces do not initialize against the unauthenticated page classification.
73
+ The Host plugin exposes the running gateway authorities as a Cordis service. `cordis.patch.yml` merges that service with `webRuntime.trustedHosts` before the stock connection module starts. Trust is therefore declared once on the Host; client code neither mutates `connection.isLoopback` nor carries an authentication marker.
51
74
 
52
75
  Plain HTTP on a private IP is not a browser secure context, while the stock Harness RPC client calls `crypto.randomUUID()` during connection startup. The rewritten index therefore installs a small RFC 4122 v4 fallback backed by `crypto.getRandomValues()` before the stock boot manifest executes. This avoids certificate installation while keeping the LAN-only setup functional.
53
76
 
77
+ ### Responsive Harness AppFrame
78
+
79
+ `src/mobile-layout.tsx` is mounted through the normal client plugin and activated by `matchMedia('(max-width: 834px)')`. Crossing the viewport boundary mounts or disposes one scoped set of enhancements. The gateway does not inspect user agents, parse `view` parameters, set layout cookies, load a second bundle, or alter the root-layout boot entry.
80
+
81
+ The shipped Harness root and AppFrame continue to own `sidebar`, `conversation`, `details`, and `shell.overlay`. Local Link contributes only additive overlay, session-information, and subagent surfaces, then applies scoped responsive geometry to the existing frame. It never enumerates Chat, Trajectory, composer, dock, node, or third-party registrations, so those continue to resolve through the native dynamic slots.
82
+
83
+ The existing `layout` controller opens and closes the stock sidebar. Responsive styles project that sidebar and the plugin's details surface as dismissible drawers, preserve overlay contributions, apply safe-area insets, and keep dynamic tab lists horizontally scrollable. At wider viewports the enhancement fiber is disposed and the untouched desktop presentation remains.
84
+
85
+ Plugin-owned modal drawers share `src/mobile-dialog.ts`: opening moves focus into the surface, Tab and Shift+Tab remain inside it, Escape closes it, and closing restores focus to the invoking Harness control. This behavior is isolated from session and gateway state.
86
+
87
+ The stock Settings dialog is intentionally not exposed inside the narrow mobile drawer. The responsive enhancement shadows the official single `sidebar.settings` occupant with one compact sun/moon button. Its icon and accessible label describe the next action. It reads the resolved `ctx.theme.getTheme().active.colorScheme`, so a `system` preference follows the operating-system theme on first render, subscribes to the normal `theme/change` event, and writes an explicit choice only through `ctx.theme.setTheme('light' | 'dark')`.
88
+
89
+ The compact appearance button is visually placed in the stock sidebar brand row without becoming part of the Harness brand action. A scoped mobile geometry rule changes the stock flexible brand button to a content-sized hit area and leaves the remaining row space to the separate appearance and sidebar-toggle controls. This keeps all three hit areas disjoint while preserving Harness's own buttons, actions, focus behavior, and tap highlight. Harness exposes no sibling slot in this row, so the compatibility rule identifies the stock CSS-module button by its semantic `_brand` class suffix; Harness upgrades must verify that hook.
90
+
91
+ Theme persistence remains entirely owned by Harness SettingsScope. In Harness `0.1.1-rc.2`, the client Settings binder selects durable `host` storage only for loopback connections and `memory` storage for non-loopback connections. A phone can therefore change the theme for its current page, but reload creates a new remote SettingsScope and returns to the durable host preference—often `system`, which is then resolved using the phone's own color scheme. Local Link does not impersonate a loopback client and does not add a competing cookie or browser-storage preference. Persistent per-device theme selection requires a safe client/device preference scope from Harness.
92
+
93
+ The authenticated gateway manifest omits Harness's host directory-picker client capability. The stock WorkspaceBrowser already treats `sidebar.workspaces.directoryFlow` as optional, so it naturally keeps Search, View options, existing workspaces, and sessions while withholding `Add workspace` from every remote gateway viewport. Loopback desktop boot entries are unchanged; no DOM selector or duplicated workspace browser is involved.
94
+
95
+ Subagent controls also stay inside the native graph. A mobile-only list entry in `conversation.input.dock` projects the existing `useSessions` catalog into a compact status chip above the composer. The sheet itself is an additive `shell.overlay` entry, while a higher-priority mobile occupant of `conversation.session.header.lineage` removes the desktop dropdown without replacing the session header. Opening and expanding the sheet uses `ctx.sessions.setSubagentCatalogOpen`; selecting a row uses `ctx.sessions.openSubagent`. Closing the sheet or a tree branch releases every corresponding catalog observation. There is no second session store, WebSocket, or data-polling loop. While the sheet is visible, one one-second presentation clock updates displayed activity durations from the already-observed catalog and is cleared when the sheet closes.
96
+
54
97
  ### Localization
55
98
 
56
99
  JSON dictionaries under `src/locales/` are registered with Harness `LocaleRuntime`. The slot declares its locale namespace and receives the framework translation function. The application locale remains the single source of truth.
57
100
 
58
- English and Chinese dictionaries intentionally contain the same key set. `tests/locales.test.ts` makes this a release invariant. Adding a language means adding one matching dictionary and registering that locale ID in `src/client.tsx`; component code remains unchanged.
101
+ The automatic pairing page runs before the Harness client and locale service load. Its small copy subset is sourced from those same JSON dictionaries at build time and selects English or Chinese from `navigator.languages`; it has no separate translation files or network request.
102
+
103
+ ### Design-system boundary
104
+
105
+ Local Link uses Harness semantic color, state, border, background, elevation, and typography variables wherever the supported client exports an applicable token. Icons are imported from `@deepseek-ai/dsh-client-ui-primitives` when that package exposes the required glyph, and stock Harness menus, dialogs, conversation actions, Settings surfaces, and session operations that Local Link does not replace remain their native components. Literal colors following a `var(--dsw-*, fallback)` expression are defensive fallbacks and are not selected in the supported Harness build. The context breakdown's purple tools segment intentionally matches the stock Harness `ContextMeter` implementation exactly.
106
+
107
+ Harness `0.1.1-rc.2` does not expose a public responsive-shell or Drawer component, spacing scale, radius scale, or mobile component recipes. Mobile geometry—safe-area placement, drawer widths, tap-target dimensions, spacing, radii, and transition timing—therefore remains plugin-owned CSS. One plugin-scoped `--dllm-side-drawer-width` value keeps the stock sidebar projection, the right details surface, and Current session visually identical instead of duplicating width literals. A small set of concepts also has no exported Harness primitive: Local access/device, navigation, current-session information, permission variants, and the subagent group glyph. The compact feedback-note affordance is a scoped presentation adapter because the stock feedback action accepts text only and exposes no icon-mode contract.
108
+
109
+ All plugin-owned button and text-input controls use the exported Harness `Button` and `Input` primitives. Their semantic variants (`primary`, `outline`, `ghost`, and `toolbar`) remain owned by Harness; Local Link adds only the geometry required by its composed surfaces, such as a full-width sidebar row, a segmented copy action, a scrim, or a tree row. A source-level test rejects new raw `<button>` and `<input>` elements in the plugin UI.
110
+
111
+ Component-level alignment remains bounded by the contracts Harness actually exports. The responsive shell, side drawer, bottom sheet, QR composition, context card, and diagnostics disclosure have no equivalent public responsive component contract in `0.1.1-rc.2`, so their structure remains semantic HTML plus scoped CSS. They use Harness tokens and primitive controls internally and should migrate if Harness later publishes compatible responsive components.
112
+
113
+ These are compatibility surfaces, not an independent theme. Every Harness upgrade must compare them against the current token vocabulary, primitive icon catalog, slot contracts, and stock mobile behavior. They should be deleted in favor of upstream tokens or components as soon as equivalent public contracts exist.
114
+
115
+ English and Chinese dictionaries intentionally contain the same key set. `tests/locales.test.ts` makes this a release invariant. Adding a language means adding one matching dictionary, registering that locale ID in `src/client.tsx`, and mapping its small pre-client subset in `src/gateway/pair-page.ts`; feature component code remains unchanged.
59
116
 
60
117
  ## Stable UI contract
61
118
 
@@ -113,15 +170,19 @@ No service discovery, certificate generator, tunnel client, native application,
113
170
 
114
171
  ## Compatibility strategy
115
172
 
116
- The plugin targets DeepSeek Harness `0.1.1-rc.2`. Most integration uses declared package contracts, but three adapters are intentionally version-sensitive:
173
+ The plugin targets DeepSeek Harness `0.1.1-rc.2`. Most integration uses declared package contracts, but several adapters are intentionally version-sensitive:
117
174
 
118
175
  | Adapter | Why it exists | Failure behavior | Removal condition |
119
176
  | --- | --- | --- | --- |
120
- | Boot-manifest dependency adjustment | Authenticated non-loopback pages must load the Local Link trust hint before Settings initializes. | Fails closed when the expected plugin or Settings entry is absent. | Harness exposes a supported authenticated-gateway boot contract. |
177
+ | Connection `trustedHosts` profile patch | Authenticated non-loopback pages need an explicitly declared LAN authority for ordinary API and WebSocket traffic. | An undeclared authority is rejected; privileged RPCs remain loopback-only independently. | Harness exposes a first-class authenticated-gateway registration contract. |
178
+ | Remote boot capability filter | The native directory picker targets the Host filesystem and is misleading from a remote browser. | If the known picker entries change, `Add workspace` can reappear; server authorization remains unchanged. | Harness exposes a remote-client capability policy. |
121
179
  | Settings navigation bridge | The shell keeps `openSection` private outside onboarding. | The shortcut does nothing; ordinary `Settings → Local access` remains available. | Harness exposes general settings navigation. |
122
180
  | Footer stack rule | Cordis reserves a full-width cell inside a horizontal list container. | Without it, Local access has zero width while Cordis is mounted. | Harness stacks full-width footer actions or gives entries an explicit layout contract. |
181
+ | Remote theme persistence | Harness `0.1.1-rc.2` gives non-loopback clients a memory-backed SettingsScope. | An explicit mobile light/dark choice resets on reload to the host preference, commonly `system`. | Harness exposes a safe per-client or per-device preference scope. |
182
+ | Responsive AppFrame adapter | Harness exposes its root, layout controller, semantic tokens, and button/input primitives, but no public responsive-shell recipe, spacing/radius scale, several required glyphs, or icon mode for the feedback note action. | Token, component, or stock DOM/action changes can degrade mobile presentation while business operations remain intact. | Harness publishes responsive contracts and glyphs for the remaining plugin-owned surfaces. |
183
+ | Mobile stock-DOM touch adapters | Harness has no touch-visible contract for session/workspace overflow actions, a separately slotted brand-row action, or compact feedback-note mode. | A CSS-module or stock DOM change can hide an action or enlarge its hit area while the underlying Harness operation remains available. | Harness exposes mobile action visibility and brand-row/feedback extension contracts. |
123
184
 
124
- The manifest transformation has direct tests. The two presentation adapters are verified during browser acceptance against the supported Harness build; release screenshots are also taken from that real composition with Cordis mounted.
185
+ The manifest transformation and scoped adapter invariants have source-level tests. Presentation behavior is verified during browser acceptance against the supported Harness build. Release screenshots come from the live composition with private workspace and conversation content excluded from the frame. Screenshots do not replace live pairing and real-device checks.
125
186
 
126
187
  ## Known pressure points
127
188
 
@@ -129,7 +190,9 @@ The manifest transformation has direct tests. The two presentation adapters are
129
190
  - **Socket revocation:** the credential is checked before an upgrade; an already-upgraded socket survives until it disconnects or Harness restarts.
130
191
  - **Browser metadata:** category and browser are coarse display hints supplied during pairing, not trusted identity. Laptop versus desktop is intentionally reported as `Computer`.
131
192
  - **Interface selection:** the first private IPv4 address is used in invitations. Multi-interface selection is not exposed yet.
132
- - **Harness upgrades:** boot graph names, shell semantics, or client connection assumptions may change even when TypeScript package contracts still compile.
193
+ - **Harness upgrades:** directory-picker boot IDs, AppFrame DOM semantics, or connection contracts may change even when TypeScript package contracts still compile.
194
+ - **Mobile acceptance:** the responsive AppFrame enhancement preserves dynamic slots by construction, but virtual keyboards, orientation changes, and third-party conversation views still require real-device checks.
195
+ - **Design-system drift:** plugin-owned mobile geometry, responsive compositions without exported equivalents, and the few concepts without primitive icons must be visually compared with every supported Harness release.
133
196
  - **Process lifecycle:** Host-side updates require a Harness restart. Client artifacts may be read from disk on reload, which can temporarily create a mixed-version UI; compatibility normalization prevents old device records from rendering blank.
134
197
 
135
198
  These are documented constraints, not hidden fallback modes. Release readiness requires the automated gate plus a real browser check of pairing, live conversation streaming, Cordis coexistence, settings navigation, rename, and revoke.
@@ -27,7 +27,7 @@ The QR popover separately checks every two seconds whether its visible one-time
27
27
  - Repeated identical events inside a five-second burst are stored once.
28
28
  - Opening `Settings → Local access` reads the report once. `Refresh` is the only repeated UI read.
29
29
  - The file is written only for a retained failure, an explicit clear, or migration away from unreadable/obsolete entries.
30
- - Writes use an atomic temporary-file replacement and fail soft; diagnostics cannot take down pairing or proxy traffic.
30
+ - Background event writes use an atomic temporary-file replacement and fail soft; diagnostics cannot take down pairing or proxy traffic. The explicit `Clear` action reports a persistence failure instead of claiming that the on-disk report was removed.
31
31
 
32
32
  Set `diagnosticsEnabled: false` to stop retaining new events. `Clear` immediately removes the retained history.
33
33
 
@@ -0,0 +1,73 @@
1
+ # Mobile View
2
+
3
+ Mobile View is a compact presentation of the existing DeepSeek Harness Web client. It is not a second chat application: the same Host, workspace catalog, sessions, live events, conversation views, tool approvals, and plugin slots remain in use.
4
+
5
+ ## Activation
6
+
7
+ The client enables Mobile View through `matchMedia('(max-width: 834px)')`. It reacts when the viewport crosses that boundary, so phones, portrait tablets, split-screen windows, and desktop browser device emulation all exercise the same code path. There are no `view` URL parameters, user-agent branches, cookies, or separate mobile bundle.
8
+
9
+ Presentation remains independent of authorization: changing the viewport never grants or removes Harness permissions.
10
+
11
+ ## Features
12
+
13
+ - **Compact navigation:** the stock Harness workspace and session browser opens as a left drawer over the conversation.
14
+ - **Existing sessions:** Search, View options, workspaces, sessions, rename, archive, and the active-workspace actions stay native Harness operations.
15
+ - **Dynamic views:** Chat, Trajectory, composer extensions, overlays, and third-party conversation tabs continue to resolve from Harness plugin slots.
16
+ - **Current session:** a right drawer shows context usage and its System prompt / Tools / Messages breakdown, model, workspace access, agent preset, activity statistics, and session-log download.
17
+ - **Subagents:** a compact status chip exposes total and active counts with the native activity state, then opens the nested subagent catalog as a touch-friendly bottom sheet.
18
+ - **Appearance:** a sun/moon action uses the Harness theme service. In Harness `0.1.1-rc.2`, remote theme storage is page-memory-backed, so reload returns to the host preference and resolves `system` against the phone or tablet.
19
+ - **Touch behavior:** native session and active-workspace overflow actions remain visible without a long press, and switching sessions does not automatically focus the composer or open the software keyboard.
20
+ - **Keyboard accessibility:** plugin-owned modal drawers receive and contain focus, close with Escape, and restore focus to their invoking control.
21
+ - **Responsive AppFrame:** safe-area insets, full-viewport scrims, scrollable tab groups, media bounds, and matching left/right drawers enhance the shipped Harness layout only while the media query matches.
22
+
23
+ The remote boot deliberately omits the host directory-picker capability. Existing workspaces remain available, but `Add workspace` is not shown because selecting a directory on the Harness computer from a remote phone is misleading.
24
+
25
+ ## Permissions
26
+
27
+ Mobile View does not introduce a second permission system. The remote browser receives the same current Harness session and uses its selected workspace access:
28
+
29
+ - **Read only** — project reads without workspace writes.
30
+ - **Workspace write** — writes inside the selected workspace.
31
+ - **Full access** — the broader authority configured for that Harness session.
32
+
33
+ The Current session drawer displays the active value but does not change it. Removing `Add workspace` is a usability measure, not an authorization boundary. A paired browser can still read project data, submit prompts, approve actions, and run every operation allowed by the current Harness session.
34
+
35
+ ## Supported sizes and release checks
36
+
37
+ The responsive enhancements target viewports from **360 through 834 CSS pixels wide**. Wider viewports keep the stock desktop presentation. The supported lower bound is a release target, not a forced minimum page width.
38
+
39
+ The release browser matrix is:
40
+
41
+ | Viewport | Acceptance focus |
42
+ | --- | --- |
43
+ | `360 × 800` | Minimum width, long labels, keyboard, drawers |
44
+ | `390 × 844` | Typical phone composition and safe areas |
45
+ | `430 × 932` | Large phone, session details, subagents |
46
+ | `768 × 1024` | Tablet drawer proportions and dynamic tabs |
47
+
48
+ Landscape phones, split-screen browsers, virtual keyboards, third-party fixed-width views, and operating-system text scaling remain real-device acceptance surfaces. A green unit-test gate proves contracts and source invariants, not every browser layout.
49
+
50
+ ## Harness integration boundary
51
+
52
+ Mobile View keeps the official Harness root and AppFrame mounted. It contributes controls through overlay, conversation, theme, session, locale, button, and input contracts wherever Harness exposes them. The stock desktop presentation is unchanged when the media query does not match.
53
+
54
+ Harness `0.1.1-rc.2` does not expose a public responsive shell, drawer recipe, spacing/radius scale, or every required glyph. The plugin therefore owns mobile geometry and a small number of scoped presentation adapters for stock brand, workspace, session-action, and feedback elements. Those hooks are documented in [Architecture and compatibility boundaries](ARCHITECTURE.md) and must be retested for each supported Harness version.
55
+
56
+ ## Security
57
+
58
+ Mobile View uses the same one-use invitation, paired-browser credential, private-network validation, HTTP/WebSocket gateway, and revocation behavior as desktop-shaped remote access. It adds no relay, account, analytics, fingerprinting, polling loop, or duplicate conversation store.
59
+
60
+ LAN traffic remains plain HTTP in this preview, and an already-open WebSocket is not immediately terminated by revoke. See the full [security model](SECURITY.md) before enabling the gateway.
61
+
62
+ ## Release acceptance checklist
63
+
64
+ - Pair from a clean browser and arrive at the desktop's selected session.
65
+ - Verify live streamed conversation updates and tool approvals.
66
+ - Exercise the left drawer, Current session drawer, theme action, session actions, and active-workspace actions.
67
+ - Keyboard through each plugin-owned modal and confirm focus enters, loops, closes with Escape, and returns to its trigger.
68
+ - Open nested subagents and return to their parent session.
69
+ - Confirm the keyboard stays closed when changing sessions.
70
+ - Confirm `Add workspace` is absent on every authenticated remote gateway page and remains available on the loopback desktop.
71
+ - Check a third-party conversation tab and Cordis panel if installed.
72
+ - Test the four viewport sizes above plus one real phone in portrait and landscape.
73
+ - Revoke the device and verify subsequent requests and reconnects are rejected.
package/docs/SECURITY.md CHANGED
@@ -11,9 +11,12 @@
11
11
 
12
12
  A connected Harness browser may read project data, submit prompts, approve actions, and trigger commands. A gateway credential therefore grants powerful access to the current Harness instance.
13
13
 
14
+ Mobile View does not reduce that authority. It inherits the selected Harness session's Read only, Workspace write, or Full access mode. Omitting the remote `Add workspace` directory picker is a usability constraint, not an authorization boundary.
15
+
14
16
  ## Implemented controls
15
17
 
16
18
  - Source-address classification for loopback, RFC1918 IPv4, link-local IPv4, IPv6 ULA, and IPv6 link-local ranges.
19
+ - Startup rejection for listener addresses outside `0.0.0.0`, private ranges, and loopback ranges.
17
20
  - IP-literal Host allowlist derived from current private interfaces.
18
21
  - One-use, expiring pairing tokens.
19
22
  - 256-bit device credentials.
@@ -22,6 +25,9 @@ A connected Harness browser may read project data, submit prompts, approve actio
22
25
  - Device expiry and explicit revocation.
23
26
  - Authentication before HTTP proxying and WebSocket upgrade.
24
27
  - Gateway-side block for desktop administration paths.
28
+ - Structural loopback source, Host, and Origin validation for every desktop administration request; lookalike DNS names fail closed.
29
+ - Gateway authorities declared through the stock connection `trustedHosts` contract without claiming loopback identity.
30
+ - Independent loopback enforcement for Settings, credentials, native Host actions, and agent-preset authoring.
25
31
  - Bounded local diagnostics with an explicit context allowlist and no credentials, addresses, identifiers, names, paths, or user content.
26
32
  - No external relay, telemetry, analytics, or remote log collector.
27
33
 
@@ -43,7 +49,7 @@ Revoking a device blocks subsequent requests and reconnects, but an already-upgr
43
49
 
44
50
  ### Version-sensitive Harness integration
45
51
 
46
- Authenticated LAN boot, direct Settings navigation, and coexistence with the stock Cordis footer action currently need small compatibility adapters for Harness `0.1.1-rc.2`. They do not expand network authority, but a Harness upgrade can break presentation or fail closed. Before declaring another Harness version supported, manually retest pairing, live conversation streaming, Settings navigation, rename, revoke, and coexistence with Cordis.
52
+ Authenticated LAN trust, remote boot capability filtering, direct Settings navigation, coexistence with the stock Cordis footer action, and responsive AppFrame presentation currently need small compatibility adapters for Harness `0.1.1-rc.2`. They do not grant privileged loopback methods, but a Harness upgrade can break presentation or fail closed. Before declaring another Harness version supported, rerun the trust-boundary suite and manually retest pairing, live conversation streaming, Settings navigation, rename, revoke, Cordis coexistence, mobile workspace/session actions, Current session, subagents, theme switching, and third-party conversation tabs.
47
53
 
48
54
  ### Firewall automation
49
55
 
@@ -58,6 +64,7 @@ Pairing establishes device possession, not user identity. Anyone controlling a p
58
64
  - Internet exposure.
59
65
  - Multi-user accounts or workspace isolation.
60
66
  - Authorization inside a Harness session.
67
+ - A lower-authority mobile mode distinct from the selected Harness session.
61
68
  - Protection against malware already executing as the desktop user.
62
69
  - A replacement for TLS, VPN access control, or operating-system firewall policy.
63
70
 
Binary file
Binary file
Binary file