@restregular/dsh-visual-browser 0.1.0 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@restregular/dsh-visual-browser",
-  "version": "0.1.0",
-  "description": "Visual browser for DeepSeek Harness: the Agent drives a real Chrome through a token-light numbered view of interactive elements (never the raw DOM), while the Web UI streams the live page frame, the click point of every action, and a replayable operation timeline the user can also take over by clicking the picture.",
+  "version": "0.2.0",
+  "description": "Visual browser for DeepSeek Harness: a right-sidebar tab under the built-in Browser that streams Chrome live as a binary JPEG frame stream (no screenshot polling, no per-frame request) while the Agent drives it through a token-light numbered view of interactive elements, never the raw DOM. Clicks, drags, wheel and typing are forwarded straight to the DevTools input domain, and every action stays in a collapsible, scrollable operation log.",
   "icon": "./icon.svg",
   "type": "module",
   "main": "index.js",
@@ -21,7 +21,8 @@
     "cordis.patch.yml",
     "icon.svg",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "test/"
   ],
   "dsh": {
     "bundle": {
@@ -32,8 +33,7 @@
       "immediately": true,
       "inject": [
         "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-layout",
-        "@deepseek-ai/dsh-client-ui-sidebar"
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
       ]
     }
   },
@@ -66,6 +66,6 @@
   "license": "MIT",
   "author": "RestRegular",
   "scripts": {
-    "test": "node --check index.js && node --check client.js && node --check lib/browser.js && node test/snapshot.test.mjs && node test/scripts.test.mjs && node test/package.test.mjs"
+    "test": "node --check index.js && node --check client.js && node --check lib/browser.js && node test/format.test.mjs && node test/scripts.test.mjs && node test/routes.test.mjs && node test/package.test.mjs"
   }
 }

package/test/format.test.mjs

@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict';
+import { formatSnapshot, describeAction, scrollProgress } from '../lib/format.js';
+
+const snapshot = {
+  url: 'https://demo.test/login',
+  title: '登录 - Demo',
+  viewport: { width: 1280, height: 800 },
+  scrollY: 400,
+  docHeight: 2400,
+  elements: [
+    { ref: 1, role: 'textbox', name: '手机号', value: '13800000000' },
+    { ref: 2, role: 'textbox', name: '密码', value: '••••••' },
+    { ref: 3, role: 'button', name: '登录', state: ['disabled'] },
+    { ref: 4, role: 'link', name: '忘记密码', href: '/forgot' },
+  ],
+  total: 6,
+  headings: ['用户登录', '没有账号?'],
+  text: '用户登录 手机号 密码 登录 忘记密码',
+  active: { ref: 2, role: 'textbox', name: '密码' },
+  frames: 1,
+};
+
+const text = formatSnapshot(snapshot, { maxElements: 100 });
+const lines = text.split('\n');
+assert.equal(lines[0], 'URL: https://demo.test/login');
+assert.equal(lines[1], 'TITLE: 登录 - Demo');
+assert.equal(lines[2], 'VIEW: 1280x800 scroll 400/2400 · 4/6 interactive');
+assert.ok(lines.includes('[1] textbox "手机号" value=13800000000'));
+assert.ok(lines.includes('[3] button "登录" (disabled)'));
+assert.ok(lines.includes('[4] link "忘记密码" → /forgot'));
+assert.ok(text.includes('ELEMENTS') === false, 'elements exist, so no placeholder line');
+assert.ok(text.includes('… 2 more interactive elements below the fold'), 'beyond-the-fold hint');
+assert.ok(text.includes('HEADINGS: 用户登录 | 没有账号?'));
+assert.ok(text.includes('TEXT: 用户登录 手机号 密码 登录 忘记密码'));
+assert.ok(text.includes('ACTIVE: [2] textbox "密码"'));
+assert.ok(text.includes('IFRAMES: 1'));
+
+// Empty page
+const empty = formatSnapshot({ url: 'about:blank', title: '', viewport: { width: 800, height: 600 }, elements: [], total: 0 });
+assert.ok(empty.includes('ELEMENTS: none visible in the viewport'));
+
+// maxElements clips and reports the remainder
+const clipped = formatSnapshot(snapshot, { maxElements: 2 });
+assert.equal(clipped.split('\n').filter((line) => line.startsWith('[')).length, 2);
+assert.ok(clipped.includes('… 4 more interactive elements'));
+
+// Guard against junk input
+assert.equal(formatSnapshot(null), 'No page snapshot available.');
+assert.ok(formatSnapshot({}).startsWith('URL: about:blank'));
+assert.ok(formatSnapshot({ url: 'x' }).startsWith('URL: x'));
+
+// Action descriptions for the timeline
+assert.equal(describeAction({ kind: 'click', target: '[3]', detail: 'click [3] “登录”' }), 'click [3] “登录”');
+assert.equal(describeAction({ kind: 'click', target: '[3]' }), 'click [3]');
+assert.equal(describeAction('hello'), 'hello');
+assert.equal(describeAction(null), '');
+
+// Scroll progress
+assert.equal(scrollProgress(snapshot), Math.round((400 / (2400 - 800)) * 100));
+assert.equal(scrollProgress({ scrollY: 0, docHeight: 700, viewport: { height: 800 } }), 0);
+
+console.log('format.test.mjs ok');

package/test/package.test.mjs

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const readJson = async (name) => JSON.parse(await readFile(join(root, name), 'utf8'));
+
+const pkg = await readJson('package.json');
+assert.equal(pkg.name, '@restregular/dsh-visual-browser');
+assert.match(pkg.version, /^\d+\.\d+\.\d+$/);
+assert.equal(pkg.type, 'module');
+assert.ok(pkg.description.length > 80, 'description explains the capability');
+assert.equal(pkg.icon, './icon.svg');
+assert.equal(pkg.dsh.bundle.patch, './cordis.patch.yml');
+assert.equal(pkg.dsh.client.platform, 'web');
+assert.ok(Array.isArray(pkg.dsh.client.inject) && pkg.dsh.client.inject.length > 0);
+assert.ok(pkg.dsh.client.inject.includes('@deepseek-ai/dsh-client-ui-sidebar-right'), 'the right Sidebar must load first');
+assert.deepEqual(pkg.exports['./client'], './client.js');
+assert.ok(pkg.files.includes('client.js'));
+assert.ok(pkg.files.includes('index.js'));
+assert.ok(pkg.files.includes('lib/'));
+assert.ok(pkg.files.includes('cordis.patch.yml'));
+assert.ok(pkg.files.includes('icon.svg'));
+assert.ok(pkg.files.includes('locale/*.json'));
+
+const patch = await readFile(join(root, 'cordis.patch.yml'), 'utf8');
+assert.ok(patch.includes(`name: '${pkg.name}'`), 'patch row name must equal the package name');
+assert.ok(patch.includes('- insert:'));
+assert.ok(patch.includes('id: dsh-visual-browser'));
+
+for (const locale of ['en', 'zh']) {
+  const dict = await readJson(`locale/${locale}.json`);
+  assert.ok(dict.meta && dict.meta.title, `${locale} meta title`);
+  assert.ok(dict.meta.description && dict.meta.description.length > 40, `${locale} meta description`);
+}
+assert.notEqual((await readJson('locale/en.json')).meta.title, (await readJson('locale/zh.json')).meta.title);
+
+const icon = await readFile(join(root, 'icon.svg'), 'utf8');
+assert.ok(icon.startsWith('<svg'), 'icon is an SVG');
+assert.ok(icon.includes('viewBox="0 0 256 256"'));
+assert.ok(icon.includes('</svg>'));
+
+// The Host half must be importable and expose the Loader surface.
+const host = await import(pathToFileURL(join(root, 'index.js')).href);
+assert.equal(host.name, 'dsh-visual-browser');
+assert.equal(typeof host.apply, 'function');
+
+// The client bundle is not a module: it registers through the module loader.
+const client = await readFile(join(root, 'client.js'), 'utf8');
+assert.ok(client.includes('__ModuleLoader__.load'), 'client registers with the module loader');
+assert.ok(client.includes(`id: MODULE_ID`));
+assert.ok(client.includes(`'sidebar.right.pane.tab'`), 'right-sidebar tab body');
+assert.ok(client.includes(`'sidebar.right.pane.tab.title'`), 'right-sidebar tab title');
+assert.ok(client.includes(`'sidebar.right.tab.guide.entry'`), 'guide card seat');
+assert.ok(client.includes('@deepseek-ai/dsh-client-ui-sidebar-browser'), 'extends the built-in browser guide card');
+assert.ok(!client.includes(`'sidebar.panellist'`), 'the left sidebar entry is gone');
+assert.ok(!client.includes(`'main'`), 'the left main panel page is gone');
+assert.ok(client.includes(`ctx.inject(['sidebarRightTabs']`), 'the tab registry is waited for, not sampled');
+assert.ok(!client.includes('data-ds-dark-theme'), 'theme switching comes from --dsw-alias-* tokens alone');
+assert.ok(client.includes('createImageBitmap'), 'frames decode off the main thread');
+assert.ok(client.includes('/stream?r='), 'the panel reads the binary frame stream');
+assert.ok(!client.includes('previewSeq'), 'no frame replay is left in the panel');
+assert.ok(client.includes("'dvb-log-body'"), 'the operation log is a scroll container');
+assert.ok(client.includes('--dsw-alias-interactive-bg-hover'), 'hover uses the interactive token, not a surface token');
+assert.ok(!/(^|\n)\s*(const|let)\s+[A-Za-z_$][\w$]*\s*=/.test(client.replace(/^\s*\/\/.*$/gm, '')) || client.trimStart().startsWith('(function'), 'client file is wrapped in an IIFE');
+
+console.log('package.test.mjs ok');

package/test/routes.test.mjs

@@ -0,0 +1,248 @@
+import assert from 'node:assert/strict';
+import { BrowserError } from '../lib/browser.js';
+import { handle } from '../lib/routes.js';
+
+const PREFIX = '/visual-browser/api';
+
+function makeRes() {
+  const handlers = new Map();
+  return {
+    statusCode: 200,
+    headers: {},
+    chunks: [],
+    ended: false,
+    flushed: false,
+    setHeader(name, value) {
+      this.headers[String(name).toLowerCase()] = value;
+    },
+    flushHeaders() {
+      this.flushed = true;
+    },
+    write(chunk) {
+      this.chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+      return true;
+    },
+    end(data) {
+      if (data !== undefined) this.chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(String(data)));
+      this.ended = true;
+      this.emit('close');
+    },
+    on(event, callback) {
+      const bucket = handlers.get(event) ?? [];
+      bucket.push(callback);
+      handlers.set(event, bucket);
+      return this;
+    },
+    once(event, callback) {
+      return this.on(event, callback);
+    },
+    emit(event) {
+      for (const callback of handlers.get(event) ?? []) callback();
+    },
+    get body() {
+      return Buffer.concat(this.chunks).toString('utf8');
+    },
+    get json() {
+      return JSON.parse(this.body);
+    },
+  };
+}
+
+function makeReq(method, url, body) {
+  if (body === undefined) return { method, url };
+  return {
+    method,
+    url,
+    async *[Symbol.asyncIterator]() {
+      yield Buffer.from(JSON.stringify(body));
+    },
+  };
+}
+
+function makeManager({ running = true } = {}) {
+  const manager = {
+    calls: {},
+    running,
+    state() {
+      return { running, url: 'https://demo.test/', startedAt: 12, actionSeq: 3, actions: [] };
+    },
+    framesListener: null,
+    subscribeFrames(listener) {
+      this.framesListener = listener;
+      this.calls.subscribed = (this.calls.subscribed ?? 0) + 1;
+      return () => {
+        this.framesListener = null;
+        this.calls.unsubscribed = true;
+      };
+    },
+    refreshLiveView() {
+      this.calls.refreshed = true;
+    },
+    async dispatchInput(events) {
+      this.calls.input = events;
+      return { applied: events.length };
+    },
+    async open(url) {
+      this.calls.open = url;
+    },
+    async ensureStarted() {
+      this.calls.started = true;
+    },
+    async close() {
+      this.calls.closed = true;
+    },
+    async act(input) {
+      this.calls.act = input;
+    },
+    noteError(error) {
+      this.calls.error = error;
+    },
+  };
+  return manager;
+}
+
+async function request(manager, method, path, body) {
+  const res = makeRes();
+  await handle(manager, PREFIX, makeReq(method, PREFIX + path, body), res);
+  return res;
+}
+
+// state
+{
+  const manager = makeManager();
+  const res = await request(manager, 'GET', '/state');
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.headers['content-type'], 'application/json; charset=utf-8');
+  assert.equal(res.json.ok, true);
+  assert.equal(res.json.state.startedAt, 12);
+}
+
+// live picture stream: binary framing, then frames pushed through subscribeFrames
+{
+  const manager = makeManager();
+  const res = makeRes();
+  await handle(manager, PREFIX, makeReq('GET', PREFIX + '/stream'), res);
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.headers['content-type'], 'application/x-dsh-visual-browser-frames');
+  assert.match(res.headers['cache-control'], /no-transform/, 'the host gzip middleware must stay out of a live picture');
+  assert.equal(res.flushed, true);
+  assert.equal(manager.calls.subscribed, 1);
+  assert.equal(typeof manager.framesListener, 'function');
+
+  manager.framesListener(Buffer.from('jpeg-bytes'));
+  const body = Buffer.concat(res.chunks);
+  assert.equal(body.length, 8 + 10);
+  assert.equal(body.readUInt32LE(0), 10, 'frame length prefix');
+  assert.equal(body.readUInt32LE(4), 1, 'frame sequence');
+  assert.equal(body.subarray(8).toString('utf8'), 'jpeg-bytes');
+
+  res.emit('close');
+  assert.equal(manager.calls.unsubscribed, true, 'the stream releases its subscription when the panel goes away');
+}
+
+// no multipart: the panel parses frames itself
+{
+  const routes = await import('node:fs/promises').then((fs) => fs.readFile(new URL('../lib/routes.js', import.meta.url), 'utf8'));
+  assert.ok(!routes.includes('multipart/x-mixed-replace'), 'binary framing replaced MJPEG');
+}
+
+// stream without a running browser is an empty answer, not a hang
+{
+  const manager = makeManager({ running: false });
+  const res = await request(manager, 'GET', '/stream');
+  assert.equal(res.statusCode, 204);
+  assert.equal(manager.calls.subscribed, undefined);
+}
+
+// start with and without a URL
+{
+  const manager = makeManager();
+  const started = await request(manager, 'POST', '/start', { url: 'example.com' });
+  assert.equal(started.statusCode, 200);
+  assert.equal(manager.calls.open, 'example.com');
+  assert.equal(manager.calls.refreshed, true);
+
+  const plain = await request(manager, 'POST', '/start', {});
+  assert.equal(plain.statusCode, 200);
+  assert.equal(manager.calls.started, true);
+}
+
+// one input batch, one round trip
+{
+  const manager = makeManager();
+  const events = [
+    { t: 'pointer', type: 'down', x: 0.5, y: 0.25, button: 0, buttons: 1 },
+    { t: 'pointer', type: 'up', x: 0.5, y: 0.25, button: 0, buttons: 0 },
+    { t: 'wheel', x: 0.5, y: 0.5, dx: 0, dy: 240 },
+    { t: 'key', type: 'down', key: 'Enter', code: 'Enter', keyCode: 13 },
+  ];
+  const res = await request(manager, 'POST', '/input', { events });
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.json.ok, true);
+  assert.equal(res.json.applied, 4);
+  assert.deepEqual(manager.calls.input, events);
+
+  const nav = await request(manager, 'POST', '/nav', { action: 'back' });
+  assert.equal(nav.statusCode, 200);
+  assert.deepEqual(manager.calls.act, { action: 'back' });
+
+  const stop = await request(manager, 'POST', '/stop', {});
+  assert.equal(stop.statusCode, 200);
+  assert.equal(manager.calls.closed, true);
+}
+
+// failures
+{
+  const manager = makeManager();
+  const badNav = await request(manager, 'POST', '/nav', { action: 'teleport' });
+  assert.equal(badNav.statusCode, 400);
+  assert.equal(badNav.json.error.code, 'BAD_ACTION');
+
+  const unknown = await request(manager, 'GET', '/nope');
+  assert.equal(unknown.statusCode, 404);
+  assert.equal(unknown.json.error.code, 'NOT_FOUND');
+
+  const res = makeRes();
+  const badReq = {
+    method: 'POST',
+    url: PREFIX + '/input',
+    async *[Symbol.asyncIterator]() {
+      yield Buffer.from('{not json');
+    },
+  };
+  await handle(manager, PREFIX, badReq, res);
+  assert.equal(res.statusCode, 400);
+  assert.equal(res.json.error.code, 'BAD_JSON');
+
+  const toobig = makeRes();
+  const huge = {
+    method: 'POST',
+    url: PREFIX + '/input',
+    async *[Symbol.asyncIterator]() {
+      yield Buffer.alloc(200 * 1024, 0x20);
+    },
+  };
+  await handle(manager, PREFIX, huge, toobig);
+  assert.equal(toobig.statusCode, 413);
+}
+
+// manager failures keep their code and status
+{
+  const manager = makeManager();
+  manager.act = async () => {
+    throw new BrowserError('TARGET_NOT_FOUND', 'no such element');
+  };
+  const res = await request(manager, 'POST', '/nav', { action: 'reload' });
+  assert.equal(res.statusCode, 409);
+  assert.equal(res.json.error.code, 'TARGET_NOT_FOUND');
+  assert.ok(manager.calls.error instanceof BrowserError, 'the failure is remembered for the panel');
+
+  manager.act = async () => {
+    throw new BrowserError('NOT_RUNNING', 'browser is not running');
+  };
+  const offline = await request(manager, 'POST', '/nav', { action: 'reload' });
+  assert.equal(offline.statusCode, 500);
+  assert.equal(offline.json.error.code, 'NOT_RUNNING');
+}
+
+console.log('routes.test.mjs ok');

package/test/scripts.test.mjs

@@ -0,0 +1,214 @@
+import assert from 'node:assert/strict';
+import {
+  prepareTypingExpression,
+  readTextExpression,
+  resolveExpression,
+  selectOptionExpression,
+  snapshotExpression,
+} from '../lib/page-scripts.js';
+
+// ---------------------------------------------------------------------------
+// A deliberately small DOM double: enough of the browser surface that the
+// serialized page scripts run for real and their output can be asserted.
+// ---------------------------------------------------------------------------
+
+function makeElement(options = {}) {
+  const attributes = new Map(Object.entries(options.attrs || {}));
+  const rect = { x: 0, y: 0, width: 120, height: 24, ...(options.rect || {}) };
+  const element = {
+    tagName: String(options.tag || 'div').toUpperCase(),
+    type: options.type,
+    value: options.value,
+    checked: options.checked,
+    disabled: options.disabled,
+    readOnly: false,
+    required: false,
+    isContentEditable: options.editable === true,
+    labels: [],
+    innerText: options.text || '',
+    textContent: options.text || '',
+    options: options.options || [],
+    selectedOptions: options.selectedOptions || [],
+    getAttribute(name) {
+      return attributes.has(name) ? attributes.get(name) : null;
+    },
+    setAttribute(name, value) {
+      attributes.set(name, String(value));
+    },
+    removeAttribute(name) {
+      attributes.delete(name);
+    },
+    hasAttribute(name) {
+      return attributes.has(name);
+    },
+    getBoundingClientRect() {
+      return {
+        left: rect.x,
+        top: rect.y,
+        width: rect.width,
+        height: rect.height,
+        right: rect.x + rect.width,
+        bottom: rect.y + rect.height,
+      };
+    },
+    checkVisibility() {
+      return options.visible !== false;
+    },
+    scrollIntoView() {},
+    focus() {
+      document.activeElement = element;
+    },
+    setSelectionRange() {},
+    dispatchEvent() {
+      return true;
+    },
+  };
+  return element;
+}
+
+const phone = makeElement({ tag: 'input', type: 'text', attrs: { placeholder: '手机号' }, value: '13800000000', rect: { x: 10, y: 10, width: 200, height: 32 } });
+const password = makeElement({ tag: 'input', type: 'password', attrs: { 'aria-label': '密码' }, value: 'secret' });
+const submit = makeElement({ tag: 'button', text: '登录', rect: { x: 10, y: 100, width: 80, height: 32 } });
+const hiddenButton = makeElement({ tag: 'button', text: '隐藏按钮', visible: false });
+const checkbox = makeElement({ tag: 'input', type: 'checkbox', checked: true, attrs: { 'aria-label': '记住我' } });
+const select = makeElement({
+  tag: 'select',
+  options: [
+    { value: 'a', text: '选项一', textContent: '选项一' },
+    { value: 'b', text: '选项二', textContent: '选项二' },
+  ],
+  selectedOptions: [{ text: '选项一', textContent: '选项一' }],
+});
+const link = makeElement({ tag: 'a', text: '忘记密码', attrs: { href: '/forgot' } });
+
+const heading = { tagName: 'H1', innerText: '用户登录', textContent: '用户登录' };
+const elements = [phone, password, submit, hiddenButton, checkbox, select, link];
+
+const document = {
+  title: '登录 - Demo',
+  readyState: 'complete',
+  activeElement: null,
+  body: { innerText: '用户登录 手机号 密码 登录 忘记密码', scrollHeight: 2400 },
+  documentElement: { innerText: '用户登录 手机号 密码 登录 忘记密码', scrollHeight: 2400 },
+  querySelectorAll(selector) {
+    if (selector === '[data-dsh-vb-ref]') return elements.filter((element) => element.hasAttribute('data-dsh-vb-ref'));
+    if (selector === 'h1,h2,h3') return [heading];
+    if (selector === 'iframe') return [];
+    return elements;
+  },
+  querySelector(selector) {
+    const match = /^\[data-dsh-vb-ref="(\d+)"\]$/.exec(selector);
+    if (match) return elements.find((element) => element.getAttribute('data-dsh-vb-ref') === match[1]) || null;
+    return null;
+  },
+  getElementById() {
+    return null;
+  },
+  querySelectorAllCount: 0,
+};
+
+const window = {
+  innerWidth: 1280,
+  innerHeight: 800,
+  scrollY: 0,
+  getComputedStyle() {
+    return { visibility: 'visible', display: 'block', opacity: '1' };
+  },
+  getSelection() {
+    return { removeAllRanges() {}, addRange() {} };
+  },
+};
+
+const location = { href: 'https://demo.test/login' };
+
+function run(expression, extra = {}) {
+  const factory = new Function(
+    'document',
+    'window',
+    'location',
+    'HTMLInputElement',
+    'HTMLTextAreaElement',
+    'Event',
+    `return ${expression}`,
+  );
+  return factory(document, window, location, { prototype: {} }, { prototype: {} }, function Event() {}, ...(extra.args || []));
+}
+
+// ---------------------------------------------------------------------------
+// snapshot
+// ---------------------------------------------------------------------------
+
+const snapshot = run(snapshotExpression({ maxElements: 50, maxNameChars: 20, maxTextChars: 40 }));
+assert.equal(snapshot.url, 'https://demo.test/login');
+assert.equal(snapshot.title, '登录 - Demo');
+assert.equal(snapshot.viewport.width, 1280);
+assert.equal(snapshot.docHeight, 2400);
+assert.equal(snapshot.readyState, 'complete');
+assert.ok(!snapshot.elements.some((element) => element.name === '隐藏按钮'), 'invisible element excluded');
+assert.equal(snapshot.total, 6);
+assert.equal(snapshot.elements.length, 6);
+assert.deepEqual(
+  snapshot.elements.map((element) => element.role),
+  ['textbox', 'textbox', 'button', 'checkbox', 'combobox', 'link'],
+);
+assert.equal(snapshot.elements[0].name, '手机号');
+assert.equal(snapshot.elements[0].value, '13800000000');
+assert.equal(snapshot.elements[1].value, '••••••', 'password value is masked');
+assert.equal(snapshot.elements[2].ref, 3);
+assert.deepEqual(snapshot.elements[3].state, ['checked']);
+assert.equal(snapshot.elements[4].value, '选项一', 'select shows its selected option');
+assert.equal(snapshot.elements[5].href, '/forgot');
+assert.deepEqual(snapshot.headings, ['用户登录']);
+assert.ok(snapshot.text.length <= 40);
+assert.equal(snapshot.frames, 0);
+assert.equal(snapshot.truncated, false);
+assert.equal(phone.getAttribute('data-dsh-vb-ref'), '1');
+assert.equal(link.getAttribute('data-dsh-vb-ref'), '6');
+
+// A second snapshot clears old refs before renumbering.
+const again = run(snapshotExpression({ maxElements: 2 }));
+assert.equal(again.elements.length, 2);
+assert.equal(again.truncated, true);
+assert.equal(again.total, 6);
+assert.equal(link.getAttribute('data-dsh-vb-ref'), null, 'stale refs are cleared');
+
+// ---------------------------------------------------------------------------
+// resolve / typing / select / text
+// ---------------------------------------------------------------------------
+
+// Restore a full numbered view: the clipped snapshot above cleared the refs.
+run(snapshotExpression({ maxElements: 50 }));
+const resolved = run(resolveExpression({ ref: 3 }));
+assert.equal(resolved.ok, true);
+assert.equal(resolved.name, '登录');
+assert.equal(resolved.x, 50);
+assert.equal(resolved.y, 116);
+
+const stale = run(resolveExpression({ ref: 99 }));
+assert.deepEqual(stale, { ok: false, reason: 'stale-ref' });
+
+const focused = run(prepareTypingExpression({ ref: 3, mode: 'replace' }));
+assert.equal(focused.ok, true);
+assert.equal(focused.tag, 'button');
+assert.equal(document.activeElement, submit);
+
+const picked = run(selectOptionExpression({ ref: 5, value: 'b' }));
+assert.equal(picked.ok, true);
+assert.equal(picked.text, '选项二');
+assert.equal(select.value, 'b');
+
+const pageText = run(readTextExpression({ maxChars: 30 }));
+assert.equal(pageText.ok, true);
+assert.equal(pageText.kind, 'page');
+assert.ok(pageText.text.length <= 30);
+assert.equal(pageText.url, 'https://demo.test/login');
+
+const linkText = run(readTextExpression({ ref: 6 }));
+assert.equal(linkText.ok, true);
+assert.equal(linkText.kind, 'element');
+assert.equal(linkText.href, '/forgot');
+
+const missing = run(readTextExpression({ ref: 42 }));
+assert.deepEqual(missing, { ok: false, reason: 'stale-ref' });
+
+console.log('scripts.test.mjs ok');