Changelog

All notable changes to Hyperbolic Gateway are documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Versioning during the 1.4 line: changes ship as 1.4.x patches — including new features — and the minor number is reserved for milestones worth naming. For small increments (documentation, a one-line fix) the git tag and release title take a fourth number — v1.4.2.1, v1.4.2.2, … — so a docs-only release does not consume a patch number. For an ordinary follow-up that should not consume the next patch either, append a sub-counter to the patch instead of moving to 1.4.7: 1.4.6 → 1.4.71, 1.4.72, … (still three-part and valid semver, and still ordered after 1.4.6). Once a sub-counter is in use, the next numbered patch is 1.5.0, never 1.4.7 — 1.4.7 sorts before 1.4.71. package.json and APP_VERSION stay three-part, because npm and electron-builder require valid semver; a release tagged v1.4.2.1 therefore reports 1.4.2 in /health. This is a deliberate, temporary deviation from strict semver; each increment still gets its own Added/Fixed/Changed section here.

[1.6.2] - 2026-10-28

The experimental remote access release. It exposes the browser MCP surface through a loopback Streamable HTTP gateway and an optional named Cloudflare Tunnel, with bearer or OAuth authentication.

Remote MCP is explicitly experimental: the protocol path is implemented and tested, but third-party client behaviour varies. Gemini Connected Apps in particular can lose its connector context or fail to re-inject tools between turns. Keep remote access off unless you are actively testing it, and never expose it unattended.

Added

• Remote MCP gateway at 127.0.0.1:4112/mcp/browser, with bearer-token or OAuth 2.0 authentication. The gateway has no route to the raw local bridge.
• Named Cloudflare Tunnel support in Settings → Remote, including managed cloudflared download/update and a public-hostname handoff. Quick Tunnels are not supported.
• OAuth 2.0 discovery, PKCE authorization-code flow, explicit consent, access/refresh tokens, refresh rotation, and revocation using app-generated client credentials.
• Stateless MCP transport by default for remote clients. This avoids stale Mcp-Session-Id values and session-cap failures; stateful sessions remain available with HB_REMOTE_STATEFUL=1.
• Human-takeover controls for remote agents: get_human_activity reports the passive pause, resume_agent clears it after confirmation, and a RESUME AGENT button appears in the header during a takeover.
• Local development log MCP (hb-devlogs) with allowlisted, redacted, read-only access. It is local stdio only and is not part of the remote gateway.

Changed

• The Remote panel now saves the tunnel hostname/token before starting the tunnel and can auto-start the gateway.
• OAuth clients use pre-registered client credentials; dynamic client registration is deliberately not advertised.
• A remote startup/restart invalidates in-memory OAuth tokens, so clients must reconnect after the gateway restarts.

Fixed

• Session-cap failures no longer return a hard 429 in stateful mode; the least-recently-used idle session is reclaimed.
• Unknown/expired session IDs are logged with their MCP method, making client reconnect failures diagnosable.

Known limitations

• Gemini Connected Apps is flaky. It may show the custom app as connected without injecting its tools into a conversation, and may reuse a stale session. Reconnect the app and start a new chat after a gateway restart.
• Cloudflare Bot Fight Mode / WAF can block the server-to-server OAuth token exchange. A skip rule for /oauth/token is required on some zones.
• Remote access is not a hosted service. The app, tunnel and machine must stay running, and the bearer token/OAuth client secret must remain private.

Compatibility

• The app identity, appId, macOS bundle identity, package directory, userData path, wrapper storage, and update feed remain unchanged for in-place upgrades.
• The legacy kuang / kuang-wrap MCP labels and KUANG_* environment aliases remain available.

[1.6.1] - 2026-10-27

The documentation and presentation release. It carries the refreshed in-app start page, the new icon, and the first developer/API guide published in the standard Open Knowledge Format.

Added

• Developer documentation as a standard OKF v0.2 bundle under developer/: MCP setup, runtime architecture, security model, browser and REST APIs, bridge routes, wrapper and recipe formats, error codes, and worked examples.
• Developer and Docs links in the in-app start page navigation.
• The Pages site now publishes both readable HTML and the raw OKF Markdown.
• The transparent HyperGateway3 mark is wired into the app and installer icon configuration.

Changed

• The public documentation set is curated to actual documentation. Internal field notes, plans, handoffs, and TODO documents are no longer published as manual pages; links to them go back to the repository.
• The in-app manual is the concise one-page start page, with developer details and the legacy Kuang section kept at the bottom.

Compatibility

• The app identity, appId, macOS bundle identity, package directory, userData path, wrapper storage, and update feed remain unchanged for in-place upgrades.
• The legacy kuang / kuang-wrap MCP labels and KUANG_* environment aliases remain available.

[1.6.0] - 2026-10-27

The rebrand release. The desktop application is now Hyperbolic Gateway, with Hyperbolic Browser (hb-browser) and Hyperbolic Rest (hb-rest) as its two MCP surfaces.

Changed

• Product and UI branding now use Hyperbolic Gateway, Hyperbolic Browser, and Hyperbolic Rest.
• New MCP client snippets generated by Settings → MCP Clients use hb-browser / hb-rest, HB_BRIDGE_URL, and HB_WRAP_TOKEN_FILE.
• Documentation now uses the new names, with compatibility stubs for old links.

Compatibility

• The old MCP labels kuang and kuang-wrap remain available in the MCP Clients tab.
• The server binaries accept both HB_* and legacy KUANG_* environment variables.
• The Windows appId, macOS bundle identity, package directory, userData path, wrapper token path, and update feed are intentionally unchanged in this release so existing installs upgrade in place. The old technical identifiers are retained as compatibility aliases.

[1.5.9] - 2026-10-26

Fixed

• Auto-update installs now use electron-updater's silent + force-run path. The update applies without a separate installer window and relaunches the app, including when installation starts from the quit handler. The header badge and Restart action remain the manual path.

[1.5.8] - 2026-10-26

Added

• Visible update indicators. A header badge now shows CHECKING UPDATE, UPDATE vX, DOWNLOADING N%, RESTART vX, or UPDATE FAILED; the existing bottom banner still shows the longer messages and Restart action. Clicking the ready header badge restarts and installs.

Changed

• Updates now relaunch the app after installation. Explicit Restart uses autoRunAppAfterInstall; if the app is quit while an update is ready, a before-quit handler installs it and launches the new version instead of leaving the user on the old build.

[1.5.7] - 2026-10-26

Added

• Wrappers can allow multiple HTTP methods. In the wrapper editor, Ctrl/Cmd-click the Method list to select more than one method. The first/primary method remains the default; callers can pass method: "POST" (or any allowed method) in args. A method enum is added to the wrapper's effective input schema automatically, so generated MCP tools expose it. Existing single-method wrappers are unchanged.
• request.methods accepts an array, and request.method accepts an array as shorthand.

Fixed

• The header version badge was hardcoded CHASSIS v1.0. It now reads the real APP_VERSION from the main process and shows e.g. CHASSIS v1.5.7. The About dialog shows the same version, and the window title includes it. /health remains the machine-readable source.

Notes

• If npm is used instead of pnpm, optional native dependencies can be skipped (npm issue #4828), producing errors such as Cannot find native binding. Use pnpm install --frozen-lockfile; the packaging and development docs already require pnpm.

[1.5.6] - 2026-10-26

Added

• Raw multi-segment URL paths in Kuang Wrap. A wrapper can now use {{path|raw}} in request.url:

  "url": "http://localhost:3000/api/proxy/{{path|raw}}"
  

  The value keeps / as path separators and encodes each segment, so my path/v1/items becomes my%20path/v1/items rather than one %2F-encoded segment. Normal {{name}} interpolation is unchanged. Raw paths are URL-only, must be relative, and reject ./.., empty segments, backslashes, and control characters. The Settings → Wrappers URL help and the advanced template docs describe the modifier.

[1.5.5] - 2026-10-26

Fixed

• Installed app crashed when the working directory was not writable with an error creating data/downloads. Runtime data is now resolved through one helper: packaged builds use Electron’s userData directory, development keeps the repo-local data/, and KUANG_DATA_DIR overrides both. Existing packaged data is copied from the old working-directory location on first launch when possible.
• Moved downloads, Cortex/LanceDB, recipes, sessions, scripts, screenshots, HAR/logs, decision and input settings, the action ledger, and Shadow Walk settings onto that writable root. A read-only install or shortcut working directory can no longer crash the main process before the window opens.
• The helper also works inside the bundled CommonJS MCP servers (esbuild cannot use import.meta.url). Standalone MCP processes launched from a read-only cwd fall back to the system temp directory instead of failing during import.
• Added test:data-paths and a CI step covering the writable data path.

[1.5.4] - 2026-10-26

Fixed

• The Windows installer carried a duplicate 184 MB LanceDB embedding tree and the pnpm virtual-store model cache. electron-builder re-adds that optional tree even after scripts/prune-pack.cjs; files now excludes node_modules/@lancedb/lancedb/node_modules/** and **/.cache/**. The unpacked payload drops from ~596 MB to ~412 MB, and the installer no longer leaves a long-path file behind on uninstall.

[1.5.3] - 2026-10-26

Fixed

• The installed app failed to start Cortex with Cannot find module 'apache-arrow'. apache-arrow is a peer of LanceDB, so pnpm's isolated linker never placed it in the production tree electron-builder packages. The app now declares it directly and the workspace uses nodeLinker: hoisted, which keeps the LanceDB peer closure (apache-arrow, @opentelemetry/api, reflect-metadata) inside app.asar.
• Native runtimes were unpacked incompletely. asarUnpack now covers the whole @lancedb, onnxruntime-node, sharp, and @img directories (.node, .dll, .dylib, .so*), not just the top-level .node files.
• Broken installers can no longer be published. scripts/verify-pack.cjs runs after every package and fails the build if a critical JS dependency, LanceDB/ONNX/sharp native binary, or the unpacked MCP server is missing.

Changed

• Packaging prunes the build machine's Hugging Face model cache and duplicate optional ONNX/sharp/LanceDB trees before electron-builder runs. The Windows unpacked payload dropped from ~1.1 GB to ~0.8 GB, and a downloaded model can never be shipped by accident.
• macOS builds are Apple Silicon (arm64) only. LanceDB 0.40 does not publish a darwin-x64 native package; Intel Mac builds would install and then crash in Cortex. The CI macOS job now uses an arm64 runner.
• CI prunes native dependencies for each target explicitly before packaging, then runs the same afterPack verifier used locally.

[1.5.2] - 2026-10-26

Added

• URL-bar history suggestions. Typing in the address bar opens a keyboard-navigable dropdown backed by Cortex: lexical matches over history/bookmarks immediately, then a debounced semantic recall pass. Entries show title, URL and a saved/semantic/history badge. ↑/↓, Enter and Escape work; recent entries appear on focus.
• Cortex is prewarmed at startup so the first suggestion does not pay table initialization.
• GET /cortex/suggest?q=&semantic=false|true and IPC cortex:suggest-urls for the same hybrid ranking.

Fixed

• Bookmark star is now a proper SVG with filled/unfilled state, aria-pressed, and a request-sequence guard so a slow check cannot overwrite the current page's state. The previous text-glyph version was fragile across themes/fonts.

[1.5.1] - 2026-10-25

Fixed

• Settings → Shadow Walk failed to load with Cannot set properties of null (setting 'checked'). The Part outlines control was missing from index.html while the renderer still looked it up. Restored the toggle.
• Added scripts/test-settings-dom.mjs (npm run test:settings:dom) and the same step in the guard workflow: every static Settings/Shadow Walk getElementById target must exist in index.html.

[1.5.0] - 2026-10-25

The Shadow Walk milestone. The 1.4.9x series built the subsystem; this release calls the plan complete and makes iframe content first-class end to end. No breaking API changes.

Highlights

• Closed roots: AX discovery, coordinate acts, trusted Tab entry, offscreen sealed tokens, cache/rate limits, no value leakage.
• Iframes: same-site and OOPIF discovery, geometry, controls, screenshots, 100+ frame mark ids, and frame-aware observe/extract.
• Components: stable host signatures on main, sealed and frame results; recipe anchors with SIGNATURE_MISMATCH retirement.
• Settings: Shadow Walk panel with enforced tiers, structured refusals, and bridge_health.shadowWalk.
• Force-open: the one detectably risky lever, off by default, confirmed, chipped, and detectable by design.
• Polish: partHighlight, cdpStyleMatch, and target-text resolution on hidden windows.

Verification

• All live suites green: test:dom, test:sealed, test:framemarks, test:component, test:tabwalk, test:forceopen, test:shadow, test:primitives, test:recipes.
• Unit suites green: component signatures, settings, part-highlight, recipe compile.
• tsc --noEmit, test:mcp:contract, and check:no-local-paths pass.
• Real-world smoke: Mobalytics (SPA/controls), Polymer Shop and lit.dev (signatures), lit.dev sealed scan (no false positives).

The only remaining Shadow Walk item is the Clone Lab proposal (docs/TODO.md item 18), parked by decision — design-only, no code planned.

[1.4.103] - 2026-10-25

Added

• Frame-aware extract. extract(include_frames:true) runs the same extraction script in each child frame. The main result is unchanged; frames[] carries per-frame {frameId,url,oopif,ok,value|error}. For table/tables, frameRecords[] merges records with frameId/frameUrl while leaving the main rows intact.
• Same-site and OOPIF frames both work through evaluateInFrames; each frame keeps its own timeout/row limit. Main-frame mark refs are not used inside frames — the selector (or best container) is.
• HTTP/MCP extract expose include_frames, max_frames, timeout_ms; MCP text appends a per-frame summary.
• test:framemarks now 13 checks (tables and JSON-LD in both frame types).

[1.4.102] - 2026-10-25

Added

• Frame-aware observe. observe(as:"som"|"components", include_frames:true) merges child-frame controls into the main results. Frame rows carry their 100+ mark ids, frame identity and host signature, so the decision loop can see and act on iframe affordances with the same model.
• POST /observe and MCP observe accept include_frames; find without it and extract remain main-frame only.
• test:framemarks now proves both projections (10 checks).

[1.4.101] - 2026-10-25

Added

• partHighlight (VISIBLE, off). Before each capture, collect the exported parts of open custom-element hosts, inject tag::part(name){outline:…}, take the screenshot, then remove the style. Closed roots are not page-enumerable; force-open is the separate path. A pure rule builder is unit-tested; a live shot verifies the capture path.
• cdpStyleMatch (COST, off). Captures CSS.styleSheetAdded headers and runs CSS.getMatchedStylesForNode for sealed controls. Sealed results may carry style: {sourceUrl, constructed}. Best-effort: bundled apps often expose no URL.
• Settings → Shadow Walk exposes both levers with VISIBLE/COST badges; /health.shadowWalk reports them.
• Tests: npm run test:parthighlight (2), test:sealed now 21 (constructed stylesheet provenance), test:component 12 (part-highlight capture path).

[1.4.100] - 2026-10-25

Fixed

• deepOpenRoots now matches its label. The lever previously blocked /dom/facts?deep and frame deep scans, but the marks scanner still traversed every open shadow root. The marks overlay now takes deepOpenRoots from Settings; when off, find/observe marks stay in the light DOM, while sealed discovery (a separate lever) is unaffected. test:component asserts both directions (open-root control found with the lever on, absent with it off).

Real-world smoke (read-only)

• Mobalytics (https://mobalytics.gg/): 80 controls, 0 custom-element signatures (React app), 5 blank same-site frames, consent dialog in the main document. Good SPA/control smoke; not a closed-root or component-surface target.
• Polymer Shop (https://shop.polymer-project.org/): 16 controls, 16/16 with signatures, 2 distinct hosts.
• lit.dev: 66 controls, 6/16 with signatures, 5 distinct hosts.
• lit.dev sealed scan: 0 closed controls, 439 ms, 7 CDP commands; no false positives.
• Force-open remained off in every smoke run.

[1.4.99] - 2026-10-25

Added

• Offscreen sealed controls are actionable. find(sealed:true) now issues a short-lived token (st_…, 2 minutes) for each result, included in JSON and the text output. Pass it as act(sealed_token) (HTTP sealed_token, MCP sealed_token): the browser resolves the backend node in its frame, calls DOM.scrollIntoViewIfNeeded, re-measures the box model, composes the frame offset, and only then clicks/types. No stale coordinate is clicked.
• Tokens are per tab, cleared by a fresh full sealed scan, and fail with STALE_REF after navigation/expiry. sealed.tokens is counted in metrics.
• test:sealed now includes a far-down closed-root button: inViewport:false, token issued, act(sealed_token) scrolls and clicks it (20 checks).

[1.4.98] - 2026-10-25

Added

• Component signatures on sealed and frame results. The host surface is now attached to closed shadow-root controls (read from the light-DOM host through the pierced tree + CSS.getComputedStyleForNode) and to frames / find(include_frames:true) controls (read in the frame). Recipes can therefore anchor on components regardless of whether the control is in the main document, a closed root, or an iframe.
• The page-side signature helper uses :defined instead of customElements.get, so it works in the isolated world used by frame evaluation; a defined custom element reports defined:true there too.

Tests

• test:sealed now asserts the host signature (host-one, part, exportparts, --brand) and is 18 checks.
• test:framemarks now asserts the frame host signature and is 8 checks.
• test:component / unit remain 9/9 and 3/3.

[1.4.97] - 2026-10-25

Added

• Frame control mark ids. find {include_frames:true} now stamps child-frame controls with 100+ ids (100 + child_index * 100, 99 per frame) and returns them alongside main-frame marks. act(mark_id) / type_mark resolve a frame mark live: find the element in its frame, scroll it into view, measure, add the frame's top-level rect, then click/type.
  • Same-site and cross-site (OOPIF) frames both work through evaluateInFrames.
  • frames exposes the same id on each control.
  • Main marks stay 1–99; the blocks never collide.
  • find without include_frames is unchanged.
• scripts/test-frame-marks.mjs (npm run test:framemarks, 7 checks): default main-only, both frame types with 100+ ids, frame identity, mark clicks in each, typing in an OOPIF, and frames exposing the same ids.

Notes

• The test target question: Mobalytics is useful as a read-only real-world SPA smoke, but it is not a reliable closed-root fixture. Keep correctness on the local closed/OOPIF fixtures; use a controlled page for closed roots and an open-component site for signature smoke tests.

[1.4.96] - 2026-10-25

Fixed

• Force-open panel no longer overflows the Settings viewport. The daisyUI .fieldset grid track used 1fr, whose automatic minimum is min-content; the long force-open copy pushed it to ~1100px inside a 768px panel. The Shadow Walk fieldsets now use minmax(0,1fr) with min-w-0, and the explanatory paragraph is a normal block with whitespace-normal (daisyUI's .label sets nowrap). The text wraps in place and the red box stays within the panel.

[1.4.95] - 2026-10-25

Added

• Force-open (RISKY, off by default). A Settings → Shadow Walk lever that patches Element.prototype.attachShadow at document start so {mode:"closed"} becomes {mode:"open"}. Injected with Page.addScriptToEvaluateOnNewDocument; applies on the next navigation, never to the document already running.
  • Deliberately detectable: no toString forgery. The page can see host.shadowRoot !== null and the non-native function source. A RUN DETECTION TEST button reports armed/applied/detectable with evidence; a red SHADOW PATCH chip shows while armed.
  • Enabling requires a confirm in the panel. Disabling removes the script for future documents; the current document stays patched until it reloads (stated in the UI).
  • KUANG_FORCE_OPEN_SHADOW=1 arms it for a one-off run; KUANG_SHADOW_WALK=off still wins.
  • New tabs created while armed are patched before their first document (or reloaded once if the CDP arm lands late). Existing tabs are armed immediately; their next navigation is patched.
• scripts/test-force-open.mjs (npm run test:forceopen, 10 checks): closed by default, marks cannot see the inner button, force-open after reload, page-side detection, marks reach the button, disarm restores the boundary, and master-off disarms.

Notes

• partHighlight and cdpStyleMatch remain off/unbuilt.
• Sealed and iframe results still do not carry component signatures.
• The Shadow Walk plan is complete through P5; frame-control mark ids and Clone Lab remain future work.

[1.4.94] - 2026-10-25

Added

• Component signatures. find marks and observe(as:"components") now carry the nearest custom-element host's exported surface: {tag, defined, part[], exportparts[], cssVars[], signature}. Attributes are normalised and sorted before a short djb2 hash, so attribute order and re-renders do not change the identity; a renamed part or changed export mapping does. Read from the host only — page-visible by design. Controlled by componentSurface in Settings → Shadow Walk; off removes the field.
• Recipe anchors. DriveStep and RecipeStep carry an optional signature; drive → save_recipe preserves it and replay verifies it before acting.
  • Matching surface: the step proceeds as before.
  • Changed surface: 409 SIGNATURE_MISMATCH and immediate retirement (not three silent retries).
  • componentSurface off: 409 SIGNATURE_UNAVAILABLE, no click and no retirement.
• scripts/test-component-signature-live.mjs (npm run test:component, 9 checks) covers observe/ find attachment, replay, structural mismatch/retirement and the disabled-surface case; npm run test:component:unit covers normalisation and hash stability (3 checks).
• The recipe compiler test now asserts a signature is carried into the recipe and omitted when the target has no host.

Fixed

• Target-text resolves on a hidden/occluded window. textTargetExpression clipped candidate rects to window.innerWidth/innerHeight; a hidden tab reports 0, so act(target_text) returned NO_TARGET even though marks resolved. It now falls back to the document box, like the mark scanner. This was caught by the recipe replay suite after a restart.

Not built yet

• partHighlight and cdpStyleMatch remain off. Force-open is the last phase (1.4.95).
• Sealed and iframe results do not carry component signatures yet; the host surface is available only for page-visible targets.

[1.4.93] - 2026-10-25

Added

• Settings → SHADOW WALK. A master switch, the implemented Shadow DOM levers (sealed discovery, deep open roots, Tab walk with max steps and focus restore), and the iframe levers (geometry, controls, screenshots, max frames, max controls, screenshot side). Tier badges are explicit: SAFE for read-only paths, VISIBLE for the Tab walk, RISKY reserved for the not-yet-built force-open.
  • Stored in data/shadow-walk.json, read on every guarded call, written atomically over IPC only. RESET DEFAULTS restores the shipped policy. No HTTP write route exists.
  • Numeric levers are clamped at the store boundary; a corrupt file falls back to safe defaults.
• Structured refusals before work starts. SHADOW_WALK_DISABLED (master), SEALED_DISABLED, TAB_WALK_DISABLED, FRAMES_DISABLED, DEEP_OPEN_ROOTS_DISABLED — 400 with a code instead of a silent no-op. The sealed guard now runs before marks are injected, so a refused call does not mutate the page.
• bridge_health.shadowWalk mirrors the active policy (enabled, sealed, Tab walk + limits, deep open roots, frame limits, forceOpen reported but not built).
• Enforced caps: tabWalkMaxSteps, frames.maxFrames, frames.maxControls, screenshots.maxSide. Turning frame controls or screenshots off returns frames without those fields plus a notes line.
• scripts/test-shadow-settings.mjs (npm run test:shadow, 11 checks) and scripts/test-shadow-settings-unit.mjs (npm run test:shadow:unit, 7 checks) cover defaults, clamping, corrupt files, the environment kill switch, every structured refusal, the master switch, output suppression and cap enforcement.

[1.4.92] - 2026-10-25

Added

• focus_walk — enter a closed shadow root like a keyboard user. POST /focus_walk (MCP focus_walk) focuses a light-DOM host, sends trusted Tab/Shift+Tab steps, and reads the accessibility tree after each step to confirm which inner control actually has focus.
  • Stops on left-host, max-steps, no-focus, or not-focusable; reports landed, restored and medianStepGapMs.
  • One real key event per step with a 90-140 ms dwell; no bursts, no page-side focus injection in the normal path. A delegatesFocus host appears as the initial (index: 0) step.
  • DOM.focus with a page-side focus() fallback for hosts that reject the CDP command; focus returns to the host when the walk fails.
  • RootWebArea also claims focused:true; it is filtered so the result names the control the user is actually on.
  • Works with the existing act(action:"press", text:"Enter") to activate the landed control.
• scripts/test-tabwalk.mjs (npm run test:tabwalk): closed root entry, stop conditions, Enter activation, Shift+Tab failure + restore, delegatesFocus, and human cadence.

Fixed

• pressKey now carries Shift and text. Shift+Tab sends the Shift modifier; without it Chromium performs a forward Tab. Enter/Space include their text payload so a focused button is actually activated.
• collect_all no longer throws Assignment to constant variable. The injected collector declared rows as const and reassigned it after each scroll (introduced in 1.4.78); it is a let again. test:primitives is back to 37/37.

[1.4.91] - 2026-10-25

Added

• find {sealed:true} — closed shadow roots become nameable. The result gains a sealed array alongside the normal marks. Each entry has a role, accessible name, viewport rect and action list, so act(x, y) can click it or type into it. Closed-root controls were previously addressable only if you already knew their pixels.
  • Discovery is Accessibility.getFullAXTree for names + DOM.getDocument({pierce:true}) / DOM.describeNode (frame owner contentDocument) to prove the node lives under a shadowRootType:"closed" root. DOM.getBoxModel supplies the rect. The page's own shadowRoot probe still returns null.
  • Per frame: same-process children use getFullAXTree({frameId}); cross-site children use their OOPIF session and the target root's top-level rect composes the coordinates.
  • Hidden semantics come from AX: display:none, visibility:hidden and aria-hidden are absent. Zero-size controls are dropped; offscreen ones are returned with inViewport:false.
  • Input values are never returned. AX exposes them; the sealed result omits them.
  • Quiet by default: no AX or pierce work on navigation, observe, plain find, screenshot or idle. Identities are cached by document revision for 5 seconds, repeat calls re-measure only the matches, and six full scans per minute per tab return 429 SEALED_RATE_LIMITED with retry_after. The AX domain is enabled for the scan and disabled immediately after.
  • POST /find {sealed:true} and MCP find(sealed:true) expose sealed_total, sealed_cached and sealed_notes; refresh:true forces a fresh scan.
• scripts/test-sealed.mjs (npm run test:sealed): closed root, nested closed root, same-site closed frame, cross-site (OOPIF) closed frame, hidden/aria-hidden absence, page JS still blind, coordinate click, clear_first typing, cache hit, quiet-by-default metrics and a real 429.

Fixed

• Typing into a closed-root field no longer duplicates the text. The input probe could not read the value behind a closed root, so a successful keystroke attempt looked like a no-op and the insertText/paste fallback appended the text again. The probe now reports observable:false, the verdict is landed:null with unobservable:true, and no fallback runs.

[1.4.90] - 2026-10-25

Fixed

• Cross-site iframes are visible. Chromium omits an out-of-process (OOPIF) iframe from the tab's Page.getFrameTree. 1.4.89 derived the frame list from that tree only, so frames, frame evaluation, in-frame controls and frame screenshots silently skipped cross-site children. The 1.4.89 suite did not catch it because its "cross-origin" fixture used two ports on 127.0.0.1 — cross-origin, but same-site, so Chromium kept it in-process.
• src/main/browser/frame-tree.ts now merges the parent tree with detached iframe targets: attach with Target.attachToTarget({flatten:true}), read the target's frame tree, keep only targets whose parent is a frame in this tab, and resolve nested OOPIFs to a fixpoint. Sessions are detached in finally; the page is never paused and sees nothing.
• Geometry still comes from the parent: DOM.getFrameOwner on the parent session, then a getBoundingClientRect measurement of the <iframe> owner. Offsets compose for nested frames, and the result is unchanged for same-site frames.
• FrameInfo gains oopif and targetId; FrameEvalResult gains oopif so a caller can tell which path produced the value.

Changed

• Frame evaluation creates its isolated world and runs Runtime.evaluate on the frame's own session. OOPIF context ids are not cached across scans because the session is per call; same-site frames keep the existing document-scoped cache.
• The live DOM suite now serves the child on 127.0.0.2 while the page stays on 127.0.0.1, so every frame check exercises a real OOPIF: frame eval, in-frame controls, consent, the offset click and the cropped screenshot (25 checks).

[1.4.89] - 2026-10-25

Added

• frames — iframes as first-class content. POST /frames (MCP frames) returns the frame tree with each frame's content-box rect in top-level viewport pixels, the controls inside it with rects already offset into the page, and — with screenshots: true — one cropped image per visible frame. A cross-origin checkout, widget or consent wall stops being a blank box: the agent can see it, read its controls, and click them with act(x, y).
  • Geometry comes from DOM.getFrameOwner + a measurement in the parent document, so a cross-origin child is measurable even though it is unreadable; parents precede children in the frame tree, so nested frames compose.
  • Offset correctness is asserted live: the fixture clicks the reported centre of a control inside a cross-origin child and the child document confirms the click.
  • Screenshots are one viewport capture cropped per frame, with the device-pixel ratio derived from the image rather than assumed (400×200 frame → 600×300 crop at 1.5×).
  • The MCP tool returns multiple image content blocks, one per visible frame, each labelled.
  • GET /frames is the cheaper inventory (geometry only, no content scan).
• Deep control facts. POST /dom/facts {deep:true} walks open shadow roots like the marks scanner, and fixes the two things that silently break inside a root: the hit-test descends via shadowRoot.elementFromPoint, and containment uses a composed walk instead of el.contains().

Docs

• docs/SHADOW_DOM_AND_FRAMES.md now carries a capability matrix that includes frames, a worked geometry/screenshot example, the transform and clear_first limits, and an explicit design note for the two cells that are still ❌ (frame-scoped mark ids; closed roots via DOM.getDocument with pierce:true).
• src/main/browser/README.md documents listFrames(); docs/CONTROL_LAYER.md links frames from the evaluation section.

[1.4.88] - 2026-10-24

Added

• Ops metrics. Small counters — cdp.input, cdp.frame, action.click, action.type, action.scroll, nav — exposed at GET /metrics (full map) and summarised in bridge_health as metrics: {cdp, actions, navigations}. POST /metrics/reset clears them. The point is the metric jev-ultrafast reports: CDP commands per task, the honest measure of whether a change actually reduced round trips.
• Stale MCP server guard. The MCP server process is spawned once per client session, so rebuilding the app leaves yesterday's tool schemas running against today's bridge — which is exactly how target_text and recipe looked broken during development. On the first tool result the server now compares its bundled APP_VERSION with the live app version and, on a mismatch, prefixes one result with ⚠ STALE MCP SERVER — this server is vX, the running app is vY … restart the MCP client session.
• Live verification backlog in docs/TODO.md item 17, scheduled 2026-10-25: drive → save → replay end-to-end, a real CMP iframe, takeover mid-action, and recipe retirement.

Added

• Recipe learning from drive. drive {save_recipe: true} compiles a successful run into a replayable recipe (recipe_name optional). Only verified steps are compiled — failed steps, dry-run plans and non-replayable operations (scroll/wait/done) are dropped, and a type_text step is only kept when its value can be recovered from the values passed to drive. A step with no target name is skipped rather than guessed.
• compileDriveSteps is a pure function (src/main/recipes/compile.ts) with an offline suite: npm run test:recipe:compile → 9 checks.
• Recipes README documents the learning rules and their rationale.

Notes

• End-to-end (drive → save → replay) is not verified live: on the test fixture drive returned needs_agent (the guard rejected every option), so the run never reached done. The compiler and the replay engine are each covered by their own suites; the wiring between them is the untested seam.

Added

• Navigation recipes (Phase 5). A page path is compiled into descriptor steps and replayed with zero model calls: recipe {action:"save"|"replay"|"list"|"delete"}.
  • a step names a control by visible text (or a form field's aria-label / placeholder / name), with an optional expect — never a mark id or a selector
  • scope is origin + path (trailing * = prefix); stored locally in data/recipes.json
  • metrics (attempts, successes, consecutiveFailures, lastVerified); a recipe retires after 3 consecutive failed replays instead of being retried forever
  • a replay stops at the first step whose control cannot be resolved or whose expectation fails and reports the index — a half-applied recipe is worse than a refusal
  • measured on the fixture: 3 steps in ~2 s, 0 model calls (click → type → click + expect)
• act(target_text) now also matches form fields by aria-label / placeholder / name, so a typed step can be anchored the same way a click is.
• Documentation: new docs/CONTROL_LAYER.md (targeting, consent, takeover, pacing) plus subsystem pages for src/main/input, src/main/browser and src/main/recipes, and rewrites of the shield and primitives pages. Linked from docs/README.md and the root README index.
• npm run test:recipes — 11 checks: save, validation, replay, real end-state, metrics, stale step, delete.

Fixed

• Text targeting threw when the candidate selector string was built (querySelectorAll(NodeList + ',input,…')), so target_text silently found nothing. Found by the recipe replay test.

Added

• Human takeover detection and arbitration. The page reports trusted pointer/key/wheel/touch activity over a console channel; the agent's own CDP input is bracketed by a synthetic marker so the two can be told apart. While a person is active, synthetic input is refused with HUMAN_IN_PROGRESS instead of fighting them for the cursor.
  • window: every human event extends a 2 s quiet period; the agent may act again after it lapses
  • GET /human/status → {active, activeForMs, last:{kind,at,url,target}}
  • POST /human/resume clears it explicitly (HUD/manual hand-back)
  • bridge_health gains human.paused + the same status
  • AgentStatus gains HUMAN_INPUT, shown as a pulsing info badge in the HUD with the takeover description in the action line
• npm run test:human — 7 offline checks of the predicate (untrusted events, grace window boundary, no-dispatch case).
• /dom/facts, /evaluate{frames} tests extended: npm run test:dom → 20 checks, including "synthetic input never counts as human" and "untrusted page events never count as human".

Verified live (real OS input, not synthetic)

• a physical click at (400, 400) → active: true, last: {kind:"pointer", url:"https://example.com/", target:"body \"This domain is for use in documentation \""}
• an act attempt during that window → 500 HUMAN_IN_PROGRESS: the human is using the browser — synthetic input is paused…

Notes

• Detection is timing-based by necessity: CDP and human input are both trusted in the DOM. A human event arriving inside the 180 ms synthetic grace window is indistinguishable and is treated as the agent's — the alternative (blocking our own clicks) is worse.
• The listener re-arms on every document load; it is idempotent per page.

Added

• Consent walls inside child frames are now answerable. When the top document offers no control and the page embeds any <iframe>, the same scan runs in every frame's isolated world (the 1.4.82 helper). The chosen control is clicked at its top-level coordinates — the iframe's rect plus the control's local centre — so it is still a trusted CDP click, not a synthetic element.click().
  • the result reports frame: "main" | "child" and delivery: "cdp" | "in-frame"
  • if the offset cannot be derived (nested frame, dynamic src), the fallback activates the marked control in-frame and says so, rather than silently pretending it clicked
  • frame traversal only runs when the top document embeds something, so pages without iframes pay nothing extra

Verified

• npm run test:dom → 17 checks, including a cross-origin consent iframe: answered with reject, frame=child, delivery=cdp, and the child's DOM confirms the click landed.

Notes

• Isolated worlds share the DOM but not page globals: window.__x set by the page is invisible to frame evaluation, while attributes and DOM state are readable. Tests and any future frame work should assert on DOM, not on page variables.
• The 1.4.81 limitation ("CMPs inside a cross-origin iframe are left for a human") no longer holds for the common single-level embed.

Added

• act(target_text: "…") — anchor by visible text. Some of the most-clickable things on the web have no semantics: React cards are a <div> with a handler three levels up, no role, no href, no onclick attribute. The resolver picks the deepest visible element whose own text matches, clicks the centre of its visible box, and lets the event bubble to whatever handler the framework attached. Ambiguous matches are refused with AMBIGUOUS plus the candidate list instead of clicking something arbitrary. Verified live on Mobalytics: clicking "Harp Crossbow Ranged Build" navigated to the build guide (urlChanged: true).
• find reports live control facts. Each match gets facts: {visible, occluded, disabled, region} from one injected expression for the whole match set, and the text projection appends {occluded} / {hidden} when the marks table alone would look identical to a clickable match.

Fixed

• Tall elements were being discarded as "occluded". The hit-test used the rect's geometric centre clamped to the viewport edge; for a card taller than the viewport (872 px card in a 600 px viewport) that point landed on a sticky element, so the element was dropped from Set-of-Marks. Marks, control facts and kqSafePoint now hit-test the centre of the visible portion. This is why the Mobalytics build cards never received a mark.
• Disabled controls vanished from /dom/facts. They were filtered out because they accept no action — exactly the ones the guard needs to see. They are now described with actions: [] and disabled: true.

Added

• Control facts — one description of an element, shared. src/main/primitives/control-facts.ts builds a single injected expression that answers the questions marks, find, the decision guard and recipes all need: role, accessible name, value, state, accepted actions, visibility, occlusion (real hit-test), disabled, landmark region and rect. Exposed read-only at POST /dom/facts. Deliberately not wired into any hot path yet — that is Phase 2, and it lands once, in one place, instead of four slightly different copies.
• Frame-scoped evaluation. src/main/browser/frame-eval.ts walks the CDP frame tree and evaluates an expression in each frame's own isolated world, so cross-origin children (Sourcepoint consent, embedded checkouts) become reachable. POST /evaluate with {frames:true} returns {frameId,url,ok,value,error} per frame.
  • opt-in only; two CDP commands per frame
  • frame budget defaults to 8 (max 32), per-command timeout 1500 ms
  • isolated-world context ids cached per frame and invalidated on did-start-loading
  • blank frames skipped unless asked for; failures reported per frame, never thrown
• npm run test:dom — 10 live checks against a local fixture: onclick-only card, covered button (occlusion), hidden input, typed input, main-frame read, cross-origin child read, per-frame failure reporting, blank-frame skipping.

Changed

• Consent walls are answered like a person would, not stripped. The automatic path now clicks the least-invasive real control the banner offers — "Reject all" / "Only necessary" before "Accept all" — with the visible cursor, once. Policy is KUANG_CONSENT_POLICY=essential|accept|reject (default essential). Auto-removal (force_remove) is reachable only through an explicit dismiss_consent call, never from the background sweep.
• One answer per origin per session. After a wall is answered — or deliberately left — the origin is remembered, so later navigations do not re-click it.
• dismiss_consent reports what happened: which intent won (reject/accept), the control text, coordinates, and whether the wall was left for a human.

Fixed

• The consent form flickering on/off. The old sweep ran three timed attempts and passed any "Accept"-looking button to a click, so a CMP that re-rendered got clicked again (and the second click could land on whatever replaced it). Now there is one attempt, it is verified by the origin guard, and a wall that comes back is left alone.

Known limitation

• CMPs rendered inside a cross-origin iframe (Sourcepoint on the Guardian, some Quantcast setups) cannot be reached by the main-frame DOM scan. Those are now reported as blocked: "consent wall detected, no usable control — left for a human" instead of being force-removed or clicked blind. Answering them needs frame-scoped CDP evaluation, which is not wired up yet.

Added

• A decision that needs a human now raises HIL. When a guarded decide returns accepted:false — confidence under the threshold, or every option eliminated — Kuang raises the human-intervention request itself (banner, notification, window to front) listing the candidate options and why the guard rejected them, and answers the caller with 409 HUMAN_DECISION_REQUIRED plus hil_id, options and reasons. The agent is told not to guess and not to lower the threshold; it waits for the human, then re-observes. Previously this path returned fallback: "agent", which is exactly an invitation to answer with a coin flip.

Fixed

• scroll_page silently did nothing when the wheel was swallowed. On pages with a fixed header, a consent layer or a custom inner scroller, the wheel lands on something that does not scroll while the call still reported success (Mobalytics: document 2 783 px tall, scrollY stuck at 0). The scroll is now verified, and if the position did not change it scrolls the real container under the viewport centre and says so in the result. On the page that exposed it: scrollY 0 → 700, with (wheel was swallowed — scrolled the active scroll container instead).

Added

• Settings → INPUT: human pacing knobs. Pointer speed (px/s), typing speed (wpm) and click dwell (ms), persisted to data/input-profile.json and applied live over IPC — no restart. Env overrides exist for one-off runs: KUANG_MOUSE_SPEED_PX_S, KUANG_TYPING_WPM, KUANG_CLICK_DWELL_MS (plus the existing absolute KUANG_CURSOR_BUDGET_MS).
• Speculative fan-out guidance for decide. The OKF guide and the decide description now say to ask the operation head and every plausible target head (click_target, type_text_target, select_target, done) in the same call, then execute only the head matching the chosen operation — one round trip per step instead of operation-then-target. This mirrors the jev-ultrafast/TypeSafe loop, using the same jev-1.13 backend we already call.

Changed

• Mouse pacing is distance-based. The glide budget is now distance / pointer speed (default 1400 px/s, clamped 70–800 ms) instead of the previous fixed budget, and the path is sampled at most 12 times with the in-page trail drawn every third sample. A fast human crosses 500 px in ~350 ms; a gaming mouse quicker. Measured on Skyscanner: click 4 094 ms → 1 700–2 000 ms (originally 40 000–49 000 ms before the budget existed).
• Typing cadence follows the WPM setting (12000 / wpm ms per character, with extra pauses on spaces and punctuation) instead of a fixed 60–140 ms per key. Default 220 wpm ≈ 55 ms/char.
• wait_for polls every 120 ms by default (was 250 ms). Sites settle in tens of milliseconds, so the old interval added up to a quarter second of dead time per wait.

Added

• Browser history controls. ← / → / ⟳ in the header, wired to the same methods the MCP navigate_history tool and the right-click menu use; Alt+←/→ and F5 work when the shell has focus. ChassisState now carries canGoBack / canGoForward, read at broadcast time because SPAs navigate with pushState and tab switches swap the history stack, so the buttons disable at either end instead of silently no-oping.
• Icon-only toolbar. CORTEX, HARVEST, SETTINGS, ABOUT and REC became square icon buttons with daisyUI tooltips; the URL field lost its max-w-2xl cap and now takes the reclaimed width. REC's elapsed time moved into its tooltip, and the harvest spinner replaces the icon in place.
• observe(as:"components") returns the machine table. The MCP tool now emits a second text block with {components:[{id,role,name,actions}]} so it can be fed straight to decide(state, guard:{components}) instead of being re-typed out of the prose projection.
• When to use the decision model. The OKF guide, the recommended-order resource and the act description now state the trade-off explicitly: ask decide when two or more controls plausibly match, the page is unfamiliar, or the question is a judgement ("is it done?"); use find/act/navigate when exactly one control matches. Every decision must be verified — decide chooses, it does not act or prove.

Fixed

• The floating Cyberdeck panel covered the page's scrollbar. The browsing view spans the full window width, so a panel flush to the right edge sat on the scrollbar track. The panel (and the collapsed rail) is now inset by PAGE_SCROLLBAR_GUTTER = 16 px, leaving the track draggable.
• Tooltips rendered under the tab bar. #app-header and #tab-bar-container were both z-30; the header is now z-40 and every tooltip wrapper z-50, with tooltip-end on the two rightmost buttons so they do not run off the window edge.
• extract(kind:"list") returned JavaScript source. The container heuristic scored exact sibling-signature repeats, so a wall of inline <script> tags won on script-heavy pages (Skyscanner). Rows are now scored by content density, non-content subtrees (script, style, template, svg, iframe, …) are never scored or descended into, and the deepest winning container is preferred so one sponsored card cannot break the match. collect_all shares the fix.
• act(mark_id) reported <ELEMENT> "". When a mark outlived the cached table the resolver fabricated an anonymous element. It now reads the live tag, accessible name and rect, so logs and deltas name what was actually clicked.
• Clicks took 40–50 s on heavy pages. moveMouseTo awaited one CDP dispatchMouseEvent per trajectory sample — up to 140 round trips to a busy renderer. The organic path is now sampled (max 28 points) with a hard KUANG_CURSOR_BUDGET_MS budget (default 900 ms) that jumps to the target when exceeded. Measured on Skyscanner: 4 094 ms → 1 010 ms for a near click, 40 000–49 000 ms → 3 188 ms for the first far click (the remainder is one-time ghost-cursor injection).

Added

• KUANG_WRAP_MAX_TOOLS now controls the generated-tool cap (default 40, max 200, 0 disables generated tools). It is a model-context budget, not an MCP limit — the protocol has no tool cap.
• The cap is visible. wrap_list reports generated X/cap and marks an exposed wrapper that is not registered (tool (over cap: call wrap_run) or tool (disabled: KUANG_WRAP_MAX_TOOLS=0)), and wrap_create/wrap_update append a warning naming the variable when a wrapper asks to be a tool but does not fit.

Tests

• npm run test:wrap:mcp → 15: a second server with KUANG_WRAP_MAX_TOOLS=1 registers the first exposed wrapper, warns about the second, exposes only one generated tool, and marks the over-cap wrapper in wrap_list.

[1.4.76] - 2026-10-24

Release scope since v1.4.5

This is the first release since v1.4.5. It carries the LLM-surface fix and the entire Kuang Wrap server.

• llm_surface / llm_fetch + read_url — "rendered" is no longer a representation (recommended is null with a machine-readable next), results carry scope / scope_mismatch, and read_url reads any URL as Markdown (site-provided or a detached render, paged). Page-level Markdown alternates are also discovered from real <a href="….md"> links. Fixes #1.
• kuang-wrap — a second, separate MCP server (slices S0–S5): wrapper store/executor/ recipes, host-bound safeStorage credentials (static and OAuth2 client credentials), pagination (offset/cursor/link), wrap_derive, opt-in Cortex indexing, generated wrap_<id> tools with tools/list_changed, AUTH_REQUIRED handling, and lastVerified.
• Settings — lowercase hints on credential names, and an OAuth2 credential type.
• Docs — docs/KUANG_WRAP.md, including its blunt honest-limits section, plus a README section for the wrapper server.

Fixed

• read_url exposes its paging cursor machine-readably. The formatted result only mentioned the next offset in prose ("continue with 36000"), so a caller had to regex the presentation text. It now reports a next_cursor=<offset> fact when truncated (matching observe), plus a copy-ready continue: line. Follow-up papercut from #1.

Tests

• npm run test:mcp:surface gained two checks: read_url reports next_cursor=N, and passing that cursor advances the offset by the requested budget.

[1.4.75] - 2026-10-24

Added

• OAuth2 client credentials (S5). A credential can now be a static value or an OAuth2 client_credentials client (tokenUrl, clientId, write-only client secret, optional scope/audience). Main mints a token with a policy-checked form-encoded POST, caches it encrypted until 60 s before expires_in, and re-mints on demand.
• Expiry handling. A call rejected with 401/403 triggers exactly one forced re-mint and a single retry. If it still fails the result is AUTH_REQUIRED (non-retryable) with a hint to update the credential or raise request_human_intervention — no silent 401 loop.
• lastVerified. A successful live run writes an ISO timestamp into the wrapper; wrap_list shows verified YYYY-MM-DD or never verified.
• Settings → Credentials gains a credential-type selector with the OAuth2 fields.
• wrap_list also marks generated tools (· tool), and wrap_secret_list marks OAuth2 credentials.
• A blunt "Honest status: what works, what doesn't, what is untested, what is risky" section in docs/KUANG_WRAP.md, plus a new README section for the wrapper server that points at it.

Changed

• SecretStore.resolve() is async and accepts { forceRefresh }.

Not implemented (documented)

• Human approval for mutating calls; OAuth2 grants beyond client credentials; wrap-side HIL notification; per-wrapper secret scope; retries/backoff; a Settings control for exposeAsTool.

Tests

• npm run test:wrap → 50 (OAuth2 mint/cache/expiry/failure/validation, 401 refresh+retry, AUTH_REQUIRED, static-no-retry, lastVerified).
• The existing 11 MCP lifecycle and 46 live checks still pass.

Slices S0–S5 are complete.

[1.4.74] - 2026-10-24

Added

• Generated tools (S4). A wrapper with exposeAsTool: true now appears as its own wrap_<id> tool in the kuang-wrap server, taking the wrapper's declared arguments as a typed Zod schema converted from its JSON Schema (strings, numbers/integers, booleans, arrays, nested objects, enums, bounds, patterns, defaults, nullable, required/optional). Names are MCP-safe (dummyjson.auth.me → wrap_dummyjson_auth_me) and collision-free. Capped at 40 (first by id); the rest stay callable through wrap_run.
• Create/update/delete (and wrap_reload) reconcile the generated set; the MCP SDK emits tools/list_changed, so a connected client sees the change without a restart.
• Generated tools live only in kuang-wrap; the browser server's tool list is untouched.

Tests

• New npm run test:wrap:mcp (11 checks): the generated tool appears after wrap_create, advertises the typed schema, executes the wrapper, rejects an out-of-range argument, disappears after wrap_delete, and emits tools/list_changed on both changes.
• npm run test:wrap extended to 41 (7 schema-conversion and tool-naming cases).

[1.4.73] - 2026-10-24

Added

• Opt-in Cortex indexing for wrap recipes (S3 complete). A recipe with index: "cortex" stores its rendered output in the local Cortex after a successful, non-dry run, so recall_memory can find it later. Documents mode indexes one page per rendered document; any other mode indexes one page for the whole result, so a 50-row table does not become 50 embeddings. Capped at 50 documents per run.
• Indexing is best-effort: if Cortex is unavailable the call still succeeds and indexed.error is reported (the footer says index failed: … instead of indexed N docs). A dry run, an HTTP error, or a recipe without index writes nothing.
• WrapRunResult.indexed { documents, chunks, error? }; the executor's indexDocuments dependency is wired in main to CortexDB.indexPage, so chunks share the chunker/embedder used for browsed pages.

Docs and tests

• KUANG_WRAP.md: S3 marked complete, a "Cortex indexing (opt-in)" section, open question 4 resolved, and the test counts updated.
• npm run test:wrap gained 5 cases (per-document indexing, single-page table indexing, no opt-in, no indexing on dry run or an upstream error, and a non-fatal indexer failure) → 34/34.

S3 is complete: derived recipes, documents mode, pagination, and Cortex indexing.

[1.4.72] - 2026-10-24

Added

• wrap_derive (S3) — infer a first-draft response recipe from a JSON sample or a live URL. It picks the first array it recognises (items, results, data, …), takes up to max_fields primitive fields from the first item, and returns { source, recipe }; pass the recipe to wrap_create as response. The URL form is fetched through the executor, so it obeys the same outbound policy and never attaches a secret. The kuang-wrap surface is now ten meta-tools, with bridge route POST /wrap/derive.
• The executor's test() accepts includeRaw, so the derive route reuses the fetched JSON instead of issuing a second request.

Tests

• npm run test:wrap:live extended to 46 checks: inline-sample derive, URL derive, and a non-JSON sample rejection.

[1.4.71] - 2026-10-24

Added

• Recipe pagination (S3). A wrapper whose recipe declares pagination now follows pages and merges them into one render. offset (limit/skip), cursor (a next token) and link (a next URL) are supported; none stays a single request. maxPages defaults to 10 (hard max 25) and wrap_run { max_pages } overrides it per call; limits.maxItems (default 50) bounds the merged result and stops paging once reached. Pages are concatenated and rendered once, so a 25-row result is one table, not three. One audit row per page, and link pages must stay on the wrapper's origin — every page URL still passes assertSafeUrl, so a hostile next cannot move the credential to another host.
• npm run test:wrap:live — a live integration suite (43 checks) against DummyJSON, covering request building, the outbound policy, argument validation, reads, documents mode, pagination, upstream errors, timeouts and writes. It runs inline wrappers through POST /wrap/test, so it never writes to the saved store; credential-dependent checks skip when no secret is bound to dummyjson.com.

Changed

• wrap_run accepts max_pages; its footer now reports pages n/cap (+more).

Fixed

• The "credential-shaped query key" validation error claimed "secrets are not enabled in this build", which stopped being true in S2. It now says query strings end up in logs and proxies and points at request.auth.

Tests

• npm run test:wrap 29/29 (8 new pagination cases: offset/cursor/link, item cap, page cap, hasMore:false, non-list selections, and a failing second page).
• npm run test:wrap:live 43/43.

[1.4.6] - 2026-10-24

Added

• read_url — read any URL as Markdown in one call. It probes the site's own LLM-friendly surface and reads it when one is advertised, otherwise it renders the URL in a detached view (your active tab is never hijacked) and distils it to Markdown. It always returns Markdown text, so a caller never has to branch on llm_surface.recommended, and it reports via (llm_fetch|render), scope (origin|page), scope_mismatch and — when it rendered — reason. Paged with max_chars + next_cursor, because a ToS-style page exceeds one call.
• Page-level Markdown alternates are also discovered from real anchors. llm_surface now reads not only a declared <link rel="alternate"> but any real <a href="….md|.txt"> on the page (a "View as Markdown" link, or the page's own .md sibling that a site links to itself), ranked so a declared link or a same-page sibling wins. Anchors are read from the page, never guessed, and each alternate carries source (link|anchor) and page_level.

Changed

• llm_surface no longer reports "rendered" as a representation. "rendered" sat in the same union as the fetchable kinds, so callers read it as "fetch the rendered variant" and got an HTTP 400 from llm_fetch. recommended is now null when the site advertises nothing — a representation is fetchable, a strategy is not — and llm_surface returns a machine-readable next ({tool:"llm_fetch", as} or {tool:"observe", as:"markdown"}), so any caller that plans from tools/list can act without trial and error. Fixes issue #1.
• scope + scope_mismatch. llm_surface and llm_fetch now say whether a representation covers the whole site (origin) or the requested page (page), prefer a page-level alternate when one exists, and flag scope_mismatch: true when a page request can only be answered with a site-wide /llms.txt index — so a caller never silently summarises the wrong document.
• llm_fetch error classes are unchanged (NO_LLM_SURFACE, FETCH_BLOCKED); the gate message now names the render path explicitly.

Fixed

• A page URL could be answered with the site-wide index without saying so. With both an /llms.txt and a page-level alternate present, recommended returned llms_txt first; a page now resolves to its own markdown alternate, and the origin index is returned (flagged) only when it is the only option.
• read_url never answers a page with a site-wide index. When the only surface for a page URL is an origin index (the issue's core.telegram.org case), it renders the page and reports reason: "only the site-wide llms_txt index is available for this page", rather than handing back a different document. An explicit as still wins.

Docs

• Descriptions, the OKF guide and the mark-eleven://tools/recommended resource, the default-tab Manual (regenerated), README.md, docs/TOOL_CATALOG_REVIEW.md, docs/DECISION_MODELS.md, TODO_RESEARCH_CRAWL.md §5, src/mcp/README.md and the plugin skill updated for the new shape. 63 advertised tools.

Tests

• npm run test:llm extended: recommended: null + next, scope/scope_mismatch, anchor discovery, and read_url fetch + render + paging. npm run test:mcp:surface now lists read_url.

[1.4.5] - 2026-10-22

Added

• Timelapse recorder. The REC button records the Cyberdeck window itself; Settings → Recording holds enable/disable, an output directory (with BROWSE), capture interval, playback fps, max width and bitrate. A frame is captured every intervalMs but stamped as if it were 1000/fps apart, so a 10-minute session becomes a ~20-second video at the defaults — MediaRecorder cannot re-time frames, so this uses WebCodecs VideoEncoder + webm-muxer (VP9/WebM, no ffmpeg dependency).
• record_start, record_stop, list_recordings. record_stop returns the absolute .webm path (plus bytes, frames, video seconds and speed-up), and list_recordings lists recent files newest-first. The path is an ordinary string, so an agent can type it into a file-upload field that accepts a value — or hand it to a human when the field only opens a native picker.
• Settings is now a full-viewport, tabbed view — Decision Model, Recording and MCP Clients — instead of a small modal. The REC button shows the elapsed time while recording and opens the Recording tab when the feature is off; it sits where the static STATEFUL badge used to (that badge was a label for session persistence, not a control).
• Human-only switch for the recording tools. "Let agents use the recording tools" is stored in the recording config but has no tool or HTTP writer: only the Settings panel can flip it. While off, the three recording tools are not registered in tools/list (the MCP server probes /recording/status at startup), and the bridge refuses them with RECORDING_TOOLS_DISABLED — so an already-connected agent loses access too.
• Settings → MCP Clients, a copy-ready config generator for OpenCode, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Google Antigravity, Gemini CLI, Atomic Chat, Zed and a generic mcpServers block. It fills in the absolute server path and bridge port, and can emit either the bundled runtime (ELECTRON_RUN_AS_NODE=1, no Node install required) or system Node.

Fixed

• Installed builds could not run bin/mcp-server.cjs from the asar. electron-builder now unpacks bin/**/*, and the app copies the server to userData/bin/mcp-server.cjs (refreshed on update) so the path generated by the MCP Clients tab stays valid for portable and AppImage builds, whose resources/ is temporary.
• The update feed did not match the uploaded asset names. electron-builder writes hyphens where the file name has spaces (Kuang-Grade-Mark-Eleven-Setup-1.4.5.exe), but GitHub stores those spaces as dots (Kuang.Grade.Mark.Eleven.Setup.1.4.5.exe), so every updater download would have 404'd. The 1.4.5 latest*.yml files now name the real assets, and the CI publish job renames spaced files to hyphens before upload so future releases match by construction. Verified with HTTP 200 on the Windows, Linux and macOS feed URLs.

Changed

• The tool surface is now 62 always-advertised tools (+2 optional decision tools); 82 registered entries. The README table, the generated Manual list and the counts in both were regenerated with npm run manual:tools.

Notes

• webm-muxer@5.1.4 is deprecated upstream in favour of Mediabunny (≈11 MB unpacked). It is kept because it is ~147 kB unpacked and the API is contained to src/renderer/recording.ts, making a later swap mechanical.
• Capture rate is best-effort: software VP9 encoding of a 1280px window can take a few hundred milliseconds per frame, so the interval is a floor rather than a guarantee.

[1.4.4] - 2026-10-22

Added

• Auto-update from GitHub Releases (Windows and Linux). electron-updater checks 30 s after startup and every 6 h, downloads in the background (sha512-verified against the published latest.yml), installs on quit, and the HUD shows "Update v… found — downloading…" followed by a RESTART action. Deliberately conservative: off in dev builds (app.isPackaged false) and off on unsigned macOS, where Squirrel.Mac refuses to apply updates — it comes back on when the Developer ID arrives. electron-builder now declares a GitHub publish provider so the feed metadata points at this repository.
• KUANG_BRIDGE_PORT — the HTTP bridge port is configurable (still 4111 by default), so a dev build and an installed build can run side by side. Point the second MCP server at it with KUANG_BRIDGE_URL.

Fixed

• A port collision used to fail silently. Dev and installed builds shared 4111 and have separate single-instance locks, so both could run: the second bridge logged EADDRINUSE and kept going without a bridge, while the MCP tools drove the other window. The log now names the cause and the fix, and the README documents running two instances.

[1.4.3] - 2026-10-21

First release with downloadable installers, built by CI on GitHub runners.

Added

• Windows — …-Setup-1.4.3.exe (NSIS, choose install directory), …-Portable-1.4.3.exe, …-1.4.3-win.zip.
• macOS — …-1.4.3.dmg and .zip, x64 and arm64. Unsigned: Gatekeeper blocks the first launch; right-click → Open, or xattr -dr com.apple.quarantine "/Applications/Kuang Grade Mark Eleven.app". No macOS auto-update until a Developer ID is borrowed (Squirrel.Mac refuses unsigned bundles).
• Linux — …-1.4.3.AppImage (the only self-updating format), .deb, .tar.gz.

Fixed

• electron-builder needs author.email for the .deb maintainer field — that was the only Linux build failure; package.json now carries a proper author.
• The host-pinned electronDist is gone. It pointed at node_modules/electron/dist, which does not exist on a pnpm checkout, and broke packaging on every platform including Windows.

Notes

• Windows is unsigned for now (SmartScreen warning, install works). macOS is unsigned as decided — see above.
• portable never self-updates; deb/tar.gz are manual upgrades.
• Builds are artefacts of .github/workflows/build.yml; publishing them to a release is a deliberate step (see docs/BUILDING.md §4).

1.4.2.4 - 2026-10-21

Added

• Cross-platform build pipeline (scoped + phase 1). docs/BUILDING.md covers installers for all three platforms, signing (macOS ships unsigned first), GitHub Releases, and electron-updater — with the key interaction that four-part tags are documentation-only: the updater compares the three-part app version, so anything shipping binaries must bump package.json and tag exactly. .github/workflows/build.yml builds on windows-latest / ubuntu-latest / macos-latest (artefacts only, unsigned), dropping the host-pinned electronDist on non-Windows so the correct Electron is packaged. scripts/check-release-tag.mjs fails a release build when a tag is four-part or does not match package.json.
• The manual now documents the decision layer. A new section in the default-tab manual covers the optional decide / drive tools, the split (model picks the component, the agent supplies text, Kuang verifies), guard + elimination, gate hand-offs, the screenshot limitation on the OpenCode gateway, and the measured bench numbers. The manual's tool heading and paragraph state 59 advertised · +2 optional, matching the shaded rows.

Fixed

• UTF-8 BOMs removed from package.json, kuang_docs/okf.json and three TypeScript files (left by earlier PowerShell writes). Strict JSON parsers — including the new release-tag check — rejected package.json until this was fixed.

[1.4.2.3] - 2026-10-21

Small increment: the optional tools are rows in the tool table, not a footnote.

Changed

• drive and decide now appear in the README tool table — marked ⌥, listed first, with a one-line description saying they are the primary tools when a decision model is configured and absent otherwise. The separate "+2 optional" blurb is down to a single sentence.
• The manual generator understands the ⌥ marker: optional rows are excluded from the advertised count (still 59, so the guard holds), rendered first, and shaded amber with a legend ("rows shaded amber are optional: they appear only when a decision model is configured, and are then listed first").

[1.4.2.2] - 2026-10-21

Small increment: the optional decision tools are advertised first when active, and the docs say so.

Changed

• drive and decide are registered at the top of tools/list when a decision model is configured — the goal-driven loop is the most interesting thing on the surface when it is available, and it was buried among 59 browser tools. When no model is configured they are still absent entirely. Verified through the real stdio server: tools: 61, first 5: drive, decide, navigate_to, press_key, scroll_page.
• README states the surface honestly: badge is 59 +2 optional, the tools section heading is 59 advertised · +2 optional, and a note explains that the two appear only when configured and are listed first. The **59 advertised tools** claim is unchanged for the default surface, so the manual generator's guard still holds.

[1.4.2.1] - 2026-10-21

Documentation-only increment: the README navigation index, and the versioning rule for four-part tags.

Changed

• README index moved to the top. It now sits directly under the logo/badge block instead of after the intro, the release notes and the architecture principles — i.e. where you actually start reading. All 24 links resolve (explicit <a id> anchors, not GitHub heading slugs).
• Versioning: small increments take a fourth number in the tag/release (v1.4.2.1); package.json and APP_VERSION stay three-part because npm and electron-builder require semver.

1.4.2 - 2026-10-21

Added

• drive — the observe → decide → act loop, in code. Optional (like decide): with a decision model configured, drive({ goal, values }) repeats observe(as:"components") → guarded decide → verified act until the goal is reached or it must stop, with one decision call per step instead of an agent turn per step. Plumbing, not policy: fixed questions, no goal interpretation, and no text generation — a type_text step without a supplied value returns status:"needs_input" naming the field. Typed stops: done · blocked (no deterministic gate matched → the agent decides) · human_required (age/CAPTCHA, hand-off raised) · needs_agent (guard rejected everything / contradiction) · failed · max_steps, with a per-step transcript and dry_run. Measured on the Skyscanner London→Maldives form: 4 steps in 18 s (destination, autocomplete commit, both dates), then an honest needs_agent.

• scripts/drive-example.mjs — the same loop in ~80 lines against the plain HTTP API, for runners that want their own retries, logging or policy. Both paths share the guard, verification and the ledger. npm run drive -- --url … --goal … --values '{…}' runs it.

• decide(include_screenshot: true) — the model can see the page. The viewport is captured, scaled into TypeSafe's image limits (longest side ≤ 1568, shortest ≥ 280) and attached as an image asset referenced from the state, with the TypeSafe-Danger-Zone-Images header. Useful where text and the component table are not enough: a CAPTCHA, an age gate, or a modal that looks like a form. The OpenCode gateway does not forward headers (verified with a direct request: identical 400 with and without it), so images are disabled up front when the configured endpoint is opencode.ai — the result says screenshot: "disabled: the OpenCode gateway does not forward TypeSafe headers — images only work against api.typesafe.ai" and no call is wasted. Screenshots work against api.typesafe.ai with a TypeSafe key; the local ONNX models are text-only and say so. (A 400 mentioning "Images are experimental" from any other gateway is still retried once without the image, as a safety net.)

• act warns when a click target sits behind a gate. It does not refuse — a human may have resolved the hand-off and asked for exactly that click — but the result carries warning naming the wall, so an agent cannot claim it was not told.

Changed

• A sensitive gate now raises the human hand-off itself. decide returning 409 HUMAN_REQUIRED used to end with advice ("call request_human_intervention") and nothing else — nothing was actually asked. Kuang now opens a HIL request for the page (reason + the matched lines) as part of the gate, skipped while another request is already open, and without blocking the 409 (the intervention's promise resolves when the human acts, which can take minutes). On /r/petite the banner appears with "Verify your birthday to continue" attached; the decision still spends no model call.
• An undetermined wall goes to the agent, not the human. If the model answers blocked but no gate copy matches, the result is a normal decision carrying a hint ("if this is a compliance boundary — age, CAPTCHA, payment, identity — call request_human_intervention; otherwise choose the next step yourself"). Human attention is spent only on a boundary Kuang can name and quote.

Fixed

• The HUD could not select text. The shell's <html> carried Tailwind's select-none, so nothing could be highlighted and right-click Copy had nothing to copy. Removed for the shell (the tab strip keeps it). Page content was never affected — the Set-of-Marks overlay and the phosphor cursor canvas are both pointer-events: none, and agent input goes over CDP.

1.4.1 - 2026-10-21

Fixed

• dismiss_consent never worked. Its injected scan script contained a TypeScript cast ((el as HTMLInputElement).value) inside the string that is evaluated in the page — a syntax error, so every call failed with "Script failed to execute" and no consent wall was ever dismissed by the dedicated tool. Replaced with plain el.value.
• Consent walls that appear after the page loads were missed. Navigation armed a single dismissal at 1.8 s; walls that mount later (hydration, redirect, or post-login — Reddit's cookie dialog arrives after sign-in) were never seen. navigate_to and new_tab now arm a sweep at 0.9 s / 2.6 s / 6 s, each attempt gated by a consent-only DOM check so an automatic sweep can never close an ordinary dialog.
• The HIL banner covered the tab strip. It was anchored top-right, exactly where the panel tabs and their COPY buttons live, so clicks and right-clicks there hit the banner. It now sits at the bottom-right, above the footer, still clear of the browsing viewport.

Added

• Right-click menu on the shell itself. The context menu was only attached to browsing tabs, so copy/paste/select-all/inspect did nothing anywhere in the HUD. The Cyberdeck window now has the same menu (copy, paste, cut, select all, inspect element, DevTools), acting on the shell's own renderer.
• npm run test:consent — local fixture proving a consent wall injected 1.5 s after load is dismissed, and that an ordinary "session expiring" dialog is left alone (2 checks).

1.4.0 - 2026-10-21

Added

• Age verification and CAPTCHA are hard human hand-offs. Before any model call, decide scans the state — and, for guarded calls, the live page text (include_page_text, on by default with guard/eliminate) — for age-gate copy ("verify your age/birthday", "birthday to continue", "18 or older", "adult content", "mature content", …) and for CAPTCHA / "verify you are human" copy. It returns HTTP 409 HUMAN_REQUIRED with the gate kind and the matched lines — no model call, no elimination, no retry. A confident answer cannot out-vote it, because the rule is "do not decide at all", and a Date of birth signup field does not match (tested both ways). New: src/main/decide/sensitive-gate.ts. The /r/petite run is the worked example: the component table exposed only "Not Now" / "Verify", the page said "Verify your birthday to continue. This page may contain mature content.", and the gate now stops there in 1 ms without asking the model — after an earlier run had wavered at click 0.44.
• DECISIONS is the first tab whenever a decision model is active, and is selected on reveal, so the live view of what the model is choosing is the default panel instead of something to hunt for.
• The HIL banner no longer covers the page. It was centred across the app with alert-warning; it is now anchored to the side panel (top-right, max 420 px), so a human being asked to act can still see the browser. It is also built with textContent instead of innerHTML — the reason can quote page copy (the sensitive-gate rule puts matched lines in it), and page copy is attacker-controlled.
• Input-method ladder for typing — fixes the field that ignored keystrokes. When real keystrokes provably reached the page and changed nothing, act(type) now retries the same text through CDP Input.insertText (no key events, but beforeinput/input fire — accepted by components that filter keydown), then through a real clipboard paste (restoring the previous clipboard afterwards), and re-verifies each rung. The outcome reports typing.channel (keys / insertText / paste) and typing.attempted; the ledger records them. A field that swallows keydown is now filled (verified in test:act: channel=insertText, value 740106); a control that rejects every channel still returns TYPE_NO_EFFECT, but the hint now says "rejected every input channel — keystrokes, CDP text insertion and clipboard paste… call request_human_intervention" instead of blaming focus.
• Docs: who writes the typed text, and HIL as a decision. Jev never generates text — it decides that an operation is type_text and which field; the agent supplies the string. Kuang ships no generation model (jev-ultrafast embeds one because it owns the loop; ours is the caller). Human-in-the-loop is documented as a pair of questions (handoff noul + handoff_for choice) that the runner turns into request_human_intervention, with a roadmap note for an optional small text helper behind the same off-by-default config.
• decide guard + elimination — the fallback ladder. A decision is now checked before it is trusted: confidence below guard.threshold, a target that was not in the offered guard.components, a target whose actions do not include the operation, or a done answer contradicting the operation are all rejected. With eliminate:{max_attempts}, the rejected option is removed from that question and the model is asked again with what's left (capped at 5). When everything is eliminated the call returns accepted:false, exhausted:true, fallback:"agent" with reasons, rejections and removed — no action is taken and the agent decides. Ladder: model → eliminate + retry → agent. Covered by six new checks in npm run test:decide (17 total), including "the retry no longer offers the eliminated option".
• DECISIONS tab in the HUD — shown only when a decision model is configured. Mirrors every call to the decision model as it happens: backend + model, latency, each question with its type, the answers (choice + confidence, noul as yes/no with probability, score + level) or the typed failure, and a truncated state preview. It appears when a backend is saved in Settings and disappears when the backend is set to Off, so the panel never advertises something that isn't there. Backed by a ring buffer (last 50 calls) in the main process, exposed as GET /decisions so an agent can inspect what the model decided without scraping the UI.
• Native right-click menu in browsing tabs. A WebContentsView has no default context menu, so copy/paste/select-all, link and image actions, reload and inspect element were unreachable by hand even though the API had them. Each right-click now builds a menu from the click's own context: Undo/Redo/ Cut/Copy/Paste/Paste-as-plain-text/Select-all in editable fields, Copy + "Search the web for …" over a selection, Open-in-new-tab / Open-in-system-browser / Copy-link-address over a link, Copy image / Copy image address / Save image as… over an image, plus Back/Forward/Reload, Copy page URL, Copy as Markdown link, Inspect element (opens DevTools at that pixel) and Open DevTools. Actions are issued against the tab's own webContents, because Electron menu roles target the focused window — which here is the shell, not the tab. Spellcheck suggestions are included when Chromium has them.
• Settings tab (HUD) for the decision model. A ⚙️ SETTINGS button opens a dialog with the backend (off / typesafe / d1-onnx), model, endpoint, key, revision and device, a status badge showing what the app will actually use, and Test connection — which runs a real one-question decide and shows either the answer with its latency or the typed failure (NOT_CONFIGURED, UPSTREAM_ERROR, TIMEOUT). Saving writes data/decision.json, the same file the bridge and the MCP server read, so there is one source of truth; the key is stored locally and never logged. IPC: settings:get-decision / settings:save-decision / settings:test-decision.
• decide — an optional decision-model surface, off unless configured. One tool (and POST /decide on the bridge) that forwards state + typed questions to a decision model and returns the answers verbatim: no prompt assembly, no rewritten retries, no synthesis, and UPSTREAM_ERROR/TIMEOUT with no answers when the upstream fails. When nothing is configured the tool is not registered at all (POST /decide still answers NOT_CONFIGURED with setup instructions, and /health.decision reports the state). The MCP tool list is built when the stdio server starts, so a newly saved backend appears after the MCP server reconnects; the bridge picks it up on the next call. Two backends, chosen by config rather than code: hosted Jev (protocol:"typesafe", e.g. jev-1.13) and in-process ONNX (protocol:"local-onnx", via open-jev). Config lives in env vars or data/decision.json (gitignored). See docs/DECISION_MODELS.md.
• npm run bench:decision — measures a local model on four page states (goal + component table, targets restricted by actions) and prints field accuracy + latency. Measured: kev-0.6b 5/12 (p50 1,118 ms), open-jev 7/12 (p50 750 ms) — both mechanically sound, both out of domain. That is why the local path is labelled experimental rather than recommended. (LiquidAI's d1-3B is not loadable by open-jev: its detectFamily() only understands open_jev/kev configs and d1 is lfm2_vl; the model card's snippet does not work against the published library.)
• npm run test:decide — offline contract test with a mock upstream (11 checks): unconfigured is loud, state/questions reach the model byte-for-byte, the bearer key is sent, answers and latency come back untouched, and an upstream 500 surfaces as UPSTREAM_ERROR with no fabricated answers.
• observe(as:"components") — a decision-ready component table. Instead of a flat mark list, each component carries its role, accessible name, current value, state, region (the nearest landmark: form, dialog, nav, main, …) and the actions it actually accepts (click / type / select; empty when disabled). Components are grouped by landmark in the text rendering, collected through open shadow roots like the rest of Set-of-Marks, and their ids are mark ids, so a decision ("click [8]") executes through act(mark_id) with no translation layer.

  ## form · Signup
  [7] input    "Email"       {type}
  [8] input    "Password"    {type}
  [9] button   "Create account" {click}
  

  The affordance partition is the point: a target head for click is only ever offered clickable components, so the model cannot pick a textbox for a click. Inspired by the dynamic action space in browser-use/jev-ultrafast — with one difference: their element table explicitly excludes shadow roots, ours includes them.

Fixed

• The age-gate rule fired on pages that merely mentioned a gate. The patterns included bare captcha, 18+, 18 or older, adult content and mature content, and guarded calls scan the page text — so documentation, forum posts and our own manual (which documents reCAPTCHA) tripped it. The rule is now verb-anchored gate copy only ("verify your age/birthday", "birthday to continue", "are you 18", "must be 18", "adults only", "age-restricted", "18+ only/required/content", "reCAPTCHA/hCaptcha/Turnstile", "verify you are human", "I'm not a robot", "human verification"), scans only the first 1200 characters, and ignores app-internal pages (mark-eleven:, about:, …). Verified: github.com/login answers 200 with no gate; /r/petite still stops at 409 in 1 ms.

• Copying out of the HUD was unreliable. The right-click Copy used wc.copy(), which acts on whatever has focus in the tab — and opening a native menu can move focus to the shell, so the clipboard stayed empty. It now writes the click's own selectionText when there is one, and focuses the tab before Cut/Paste/Undo/Redo/Select-all. MATRIX LOGS and DECISIONS also gained a COPY button that writes their content through the main process (app:copy-text), so copying never depends on selection or focus.

• Submit inputs were labelled with their name attribute instead of their visible label. GitHub's <input type="submit" name="commit" value="Sign in"> appeared in marks and the component table as "commit" — a meaningless identifier to any reader, human or model. Accessible-name computation now prefers value for submit/button/reset inputs before falling back to name.

Changed

• Decision-model docs corrected: TypeSafe choice takes criteria, not options. The docs and the decide parameter example used options: [...], which the OpenCode gateway rejects with 422 "Upstream request failed: Endpoint is unavailable." — an error that reads like an auth failure or an outage and cost an afternoon of credential hunting. criteria is an option → description map; noul and score are unaffected. open-jev (the local path) still takes options.
• Measured on the four-case page bench (npm run bench:decision -- --bridge), with real criteria descriptions and the same information given to each model: Jev 1.13 10/10 at 376 ms p50, versus kev-0.6b 7/10 at 830 ms and open-jev 6/10 at 1,252 ms. The descriptions matter — kev-0.6b scored 5/10 with bare option keys, and Jev's only earlier miss (CAPTCHA → click) disappeared once the blocked criterion described a wall. Jev is now the recommended backend; the local ONNX path stays experimental.

1.3.0 - 2026-10-20

Fixed

• Punctuation was silently swallowed while typing — . and ' especially. keyDescriptor() in input-simulator.ts used the character's ASCII code as its Windows virtual-key code, and ASCII collides with real VKs: '.' is 46 = VK_DELETE, "'" is 39 = VK_RIGHT. Chromium honours those as editing/navigation commands rather than inserting the character, so act(action:"type") typed gmail.com as gmailcom and corrupted any password containing ' — with no error, no failed post-condition and no delta to give it away (the same silent-no-op shape as the clear_first bug below). Punctuation now maps to its real US-layout VK (Period 190, Quote 222, Semicolon 186, Digit1–Digit0 for the shifted symbols, …). Covered by a new npm run test:primitives check that types all 32 printable punctuation characters and asserts an exact round-trip (37 checks total).

• clear_first was a dead parameter — typing silently appended. act(action:"type") had no way to replace an existing value, and the older type_mark(clear_first) flag was advertised but dropped by the bridge before it ever reached the chassis. Typing into a pre-filled field (e.g. an origin/airport box already reading Exeter (EXT)) therefore appended, corrupting the value and making the form look broken — which in turn masqueraded as "dropped clicks" when the invalid form refused to submit. act now takes clear_first: true, wired end-to-end (catalog → bridge → primitives → chassis → simulator) and implemented as a trusted Ctrl+A + Backspace (so React/Vue controlled inputs still update and isTrusted stays true — no synthetic el.value writes).

• Guidance for the failure mode. The act description, the OKF guide and SKILL.md now state that typing appends by default; a new OKF recipe R6 — pre-filled fields & autocompletes (comboboxes) covers committing an autocomplete by clicking the option mark, and warns against blindly re-clicking: a form silently rejected by validation looks exactly like a dropped click, and input is CDP-delivered (focus-independent), so a "lost focus" window is rarely the real cause.

• Covered by a new npm run test:primitives check: append by default, replace with clear_first.

• observe(as:"markdown") was blind to shadow DOM, so web-component pages harvested as empty. The harvester was fed document.documentElement.outerHTML, which stops at the shadow boundary: a <faceplate-text-input>-style control serialised as an empty host tag, and a live signup form (the exact flow in docs/FIELD_NOTES_2026-10-20_SIGNUP.md) came back as a skip-link, a heading and chars=460/460 while the page held 331 KB of DOM. Serialisation now walks the composed tree (src/main/harvester/dom-serializer.ts): light children plus every open shadow root, recursively, with live form state baked in as attributes (value, checked, selected are properties, so outerHTML never showed them) and password values reduced to a length. Unrendered controls are dropped rather than harvested: a hidden CSRF input or a display:none recaptcha response textarea used to arrive as multi-kilobyte token text — on reddit.com/register the construct is 391 characters of real content instead of 2,752 characters of which ~2,300 were one Google token. shadow_roots in the envelope reports what was pierced.

• The markdown cut at 25,000 characters was unreachable — budget/next_cursor paging was a dead end. The truncation happened inside the harvester, so the remainder was already gone before observe could page it. Truncation now happens in pageText: the construct is whole, total is honest, and paging walks to the true end (a 167,000-character fixture pages in 18 calls). Markdown gets a 25,000-character default view; budget: 0 returns everything.

• <select> lost its current value, and every control rendered as a stray quoted string. A <select> showed no selection (the selected attribute was stripped during serialisation and never rebaked), and inputs rendered as <input type="text" "Email">. Controls now render with stable labels — <input type="text" label="Email" value="a@b.com">, <select label="Day" value="2" options="1,2,3">, <textarea label="Notes">…</textarea> — read from attributes rather than DOM properties, because Turndown parses with domino, which does not implement select.value or selectedOptions. Relative links and image sources are resolved to absolute URLs so they can be followed without knowing the page URL.

• act could not reach a control inside a web component — and reported success anyway. A CSS selector cannot cross a shadow boundary, so act({selector:"faceplate-text-input"}) resolved the host, clicked its centre (often a label), then applied el.focus() to the host — which either did nothing or moved focus off the inner <input>. The value never changed and the call returned a cheerful success (the exact failure in docs/FIELD_NOTES_2026-10-20_SIGNUP.md §2.2). Targeting now lives in src/main/primitives/dom-targeting.ts: selectors are searched through open shadow roots, a custom-element host resolves to the control a mouse would actually hit (deepest control at the host's centre, else the first control inside), and the focus nudge is applied to that control and its result reported, not assumed. A selector may also now name an element inside a shadow root (#email), which previously could only be reached by coordinates.

• Typing is verified — a silent no-op is now a structured failure. act(action:"type") used to return Typed text (N chars) with variable human cadence whether or not a character landed. It now installs a one-shot in-page probe (the control's value plus counters for trusted keydown / beforeinput / input events), reads it back after typing, and returns ok:false with error.code: "TYPE_NO_EFFECT", a typing evidence object (beforeLength, afterLength, changed, keydowns, beforeinputs, inputs, landed) and a hint. The counters separate the two causes that used to look identical: keydowns: 0 means the input never arrived (occluded click, unfocused window, 0×0 viewport), while events-with-an-unchanged-value means the control rejects synthetic input — one-time-code/OTP fields, which is what happened in §2.3 of the field notes. The hint names request_human_intervention for that case. Only lengths and counters leave the page, so secret typing stays secret.

• Field facts now resolve through shadow roots. act's target.field returned null for any web-component control (the host is not input-like), so the typed-facts feature was silent exactly where forms are most common. It now reports the inner control, its real value length, and inShadowRoot: true.

• A 0×0 viewport no longer produces a confident click at the wrong place. A freshly-created tab can report a 0×0 viewport before layout settles; geometry resolved then is meaningless — during testing this clicked (31, 0) on a fixture whose button sat at (231, 90) and still returned success. Both act and the chassis now refuse to act on a 0×0 viewport and say why (NO_TARGET / an explicit error), rather than clicking a point derived from nothing.

• The failure diagnostic reads the deepest focused element. The act triage hint compared document.activeElement (the host) against the target tag, which false-positived on shadow controls; it now descends shadowRoot.activeElement chains, so "focus is on , not the target" is true when it is said.

• Set-of-Marks and find were blind to shadow DOM. Candidate collection used document.querySelectorAll(SEMANTIC), so a web-component form produced 0 marks while its buttons were plainly visible; even when a shadow control was reached, the occlusion check (document.elementFromPoint returns the host for shadow content) would have discarded it as covered, closest() stopped at the shadow boundary for popup/visibility classification, and stamped ids were resolved with document.querySelector('[data-mark-id]'), which cannot see inside a shadow root. Marks now walk every open shadow root, hit-test the deepest element, use composed containment for occlusion, composed ancestor walks for aria-hidden/popup/static classification, and resolve marked elements through shadow roots — so find, act(mark_id) and the inline [#id] badges in observe(as:"markdown") all work on shadow controls. On the field-notes signup fixture the mark list went from empty to #1 <INPUT> "Email" plus the shadow button, and act(mark_id=#1, type) lands in the inner input.

Added

• npm run test:act — live fixture for the interaction path (19 checks): typing through a custom-element host lands in the inner input, a selector inside a shadow root actuates a shadow button, a reverting one-time-code field returns TYPE_NO_EFFECT with the right hint, the ledger records landed:false, clear_first works inside a shadow control, an identical retype is not mistaken for a no-op, Set-of-Marks badges the shadow controls and find returns them, act(mark_id) types through a mark into a shadow input, observe(as:"markdown") carries the [#id] badge, and an unresolvable selector fails loudly.
• OKF recipes R7 (web components: the host is not the control) and R8 (read it back) in kuang_docs/partitions/primitives_and_workflows.md.
• npm run test:markdown — live fixture covering the composed-DOM harvest (shadow text, shadow controls, value baking, password redaction, select state, absolute links), envelope minimalism, harvest stability across two calls, paging to the end of a 167 KB construct, and the text-free-page message (20 checks).
• Action ledger — a local dataset for a decision layer (src/main/telemetry/action-ledger.ts). Every executed action now appends one JSON line to data/transitions.jsonl (gitignored, local-only): the page-state signature before/after (url, revision, mark count), the resolved target, the delta, the await_conditions result, the rule-based triage hints, and the duration. Typed text is recorded as a character count only — never the string, plus the secret flag. Writes are queued and non-blocking and errors are swallowed, so a ledger failure can never break an action; the file rotates to transitions.1.jsonl past 5 MB. Rationale and usage: docs/DECISION_MODELS.md.
• Typed field facts on act. The act result's target.field now reports { tag, type, role, name, valueLength, isEmpty, prefilled, editable, required, disabled } for the addressed form control — including on dry_run, so a decision layer (or an agent) can pre-flight "is this field already filled? should I pass clear_first?" from data instead of guessing. act also returns durationMs.
• docs/DECISION_MODELS.md — where a Jev-style ("System One") decision model fits: Kuang surfaces typed facts and evidence; the decision maker belongs in the runner, not inside the browser server.

Changed

• The construct envelope is minimal, stable and honest. The old front-matter spent nine lines on constants and vanity: designation (a fixed string), raw_bytes, construct_bytes, estimated_tokens and a compression_ratio computed against raw HTML bytes — which read 0.0% on exactly the pages where markdown was empty, i.e. it was worst where it mattered most — plus a harvested_at timestamp that made two harvests of one unchanged page differ, which quietly broke diffing and paging across calls. It is now url / title / reader / extracted_chars / page_chars / shadow_roots. reader names the extraction path that produced the body (readability or full-body), and extracted_chars is measured on the same unit as page_chars (characters of page text) so the coverage claim is checkable rather than decorative. A partly-visible page now says so — "the extracted region holds 3,200 of the page's 41,000 characters…" — and names the alternates (observe(as:"text"), observe(as:"ax")) instead of looking short; a page with no text explains why instead of returning an empty body. Token counts and byte sizes still reach the caller through the response object and the MCP header line, which now reads chars=25034 of 167063 · ~41766 tokens · next_cursor=25034 instead of the ambiguous chars=460/460.

• mouse_move telemetry fires once per glide, not once per step. The humanlike cursor reports position/velocity from moveMouseTo, which loops over a 38–140-step Bézier trajectory — and it was emitting a mouse_move telemetry event per step, so a single click flooded the Cyberdeck telemetry feed with up to 140 rows and inflated the pulse counter. Events are now emitted once per glide (final position + velocity); the in-page phosphor trail is unaffected, because it is drawn per step by window.__kuangMoveCursor. (The HUD panel's own fading polyline is correspondingly coarser — a one-line revert if that denser look is preferred.) Note this is display-only telemetry: it never reached the agent, and it doubles as a signal that act (rather than synthetic JS input) was used, since synthetic clicks emit no mouse_move at all.

1.2.0 - 2026-10-19

Fixed

• 9 MCP tools returned HTTP 404: Endpoint not found because their catalog endpoint/method had drifted from the HTTP bridge's routes: navigate_history, recall_memory, get_history, clear_history, list_bookmarks, save_session, restore_session, list_sessions, and get_console_logs (wrong HTTP method).
  • get_history and list_bookmarks now use GET with query parameters, and list_bookmarks sends q (the bridge's parameter name) — previously the filter parameters were silently dropped, and the tools themselves 404'd.
• Selector clicks could actuate twice. browser-chassis.ts#clickElement ran a second, untrusted el.click() in page JS after the trusted CDP click, which double-submitted forms and double-opened links. The synthetic click was removed; the trusted CDP click alone actuates (the focus() nudge for non-link/button controls remains).
• list_bookmarks didn't actually filter. Its query parameter ran a vector search with no threshold, so with fewer bookmarks than limit it returned every bookmark (ranked) — identical output to no query at all. query is now a real filter: a bookmark matches when every query term appears (case-insensitively) in its title, notes, URL, or tags, and matches are then ranked by embedding similarity. Covered by npm run test:cortex:bookmarks.
• Detached WebContentsView reads were flaky. Off-screen reads (llm_fetch per-page alternates, search_web SERPs, deep_crawl page renders) created and destroyed a view per call and trusted did-finish-load — which the view's initial about:blank document also fires — so reads would intermittently return an empty DOM (missed search results, missing crawl links). All detached operations now share one reusable off-screen view (serialized), await the loadURL() promise for the navigation they started, and poll the live DOM before reading.

Added

• npm run test:mcp:contract (scripts/test-mcp-contract.mjs) — parses src/mcp/tools-catalog.ts and src/main/http-bridge.ts and fails if any catalog entry maps to a {method, path} the bridge does not serve. No running Cyberdeck required, so it can run in CI. It caught a ninth broken tool (get_console_logs) on its first run.
• npm run test:mcp:surface (scripts/test-mcp-surface.mjs) — asserts deprecated names are absent from tools/list yet still callable, canonical names are present, a deprecated call returns its notice, and the merged take_screenshot modes behave.
• docs/TOOL_CATALOG_REVIEW.md — catalog duplication/overlap analysis with a phased consolidation plan (correctness → de-duplicate → consolidate → tier).
• docs/HIDDEN_ALIAS_REMOVAL_V1.2.md — the concrete plan to remove all 23 hidden aliases in v1.2 (inventory, removal steps, bridge-route decision, risk).
• mark-eleven://tools/recommended — a new MCP resource (also help(category:"recommended")) giving the canonical order for the five common jobs: read → observe, find → find, act → act, wait → wait_for, harvest → collect_all.
• Pluggable Cortex embedding providers (src/main/cortex/embedder.ts). Embedding now sits behind an EmbeddingProvider interface (id + dim + async embed). The deterministic hash-128 embedder stays as the zero-dependency default; a real model (e.g. EmbeddingGemma-2 via ONNX) can be registered and selected via KUANG_EMBEDDING_PROVIDER. CortexDB records the active provider in embedding-provider.json and warns when it changes, so vectors from different models are never silently compared. See docs/EMBEDDING_PROVIDERS.md.
• npm run test:cortex:bookmarks (scripts/test-bookmarks-search.mjs) — adds tagged bookmarks, asserts query filters (exact hit, empty on no match, AND across terms, composition with tag), and cleans up. SKIPs when the bridge is down.
• Phase 7 surface checks in npm run test:mcp:surface — the new hidden aliases (recall_script, focus_window, clear_network_traffic, clear_stream_messages) still execute and return a notice pointing at their canonical tool; list_scripts(query) searches; clear_capture clears; and observe no longer advertises the structured list|table|app_data modes (which now live on extract).
• llm_surface + llm_fetch — LLM-friendly site discovery (Feature 6). Many sites publish a Markdown/Text representation (/llms.txt, /llms-full.txt, a <link rel="alternate">, or content negotiation). llm_surface({ url? }) probes for those; llm_fetch({ url?, as? }) reads the advertised one (~5–10× cheaper than a render). Gated: llm_fetch refuses (NO_LLM_SURFACE) unless the site advertises a surface, and never fetches arbitrary URLs or guesses paths. Well-known paths (/llms.txt, /llms-full.txt, /sitemap.xml) are net.fetched on Chromium's network stack and cached per origin; a page's advertised alternate is loaded via a real document navigation, not a synthetic fetch. A text/html response is never mislabelled as Markdown. New: src/main/llm/llm-surface.ts, routes POST /llm/surface + POST /llm/fetch, and npm run test:llm (local-fixture regression).
• search_web — configurable multi-engine search (Feature 5). Runs each query in a detached WebContentsView (real Chromium; the active tab is never hijacked) and falls back across engines when one returns a bot-check/consent wall: google | duckduckgo | bing | brave | startpage | custom (default chain google → duckduckgo → brave). The custom engine takes a {query} URL template (e.g. SearXNG, or KUANG_SEARCH_URL). Returns ranked {rank, title, url, snippet} — plain URLs to feed navigate_to / collect_all. Unwraps Google /url?q=, DDG /l/?uddg= and Bing /ck/a redirects. New: src/main/search/search-engine.ts, route POST /search/web, and npm run test:search.
• deep_crawl — autonomous multi-page crawl (Feature 1). Breadth-first crawl from a seed URL, bounded by max_depth / max_pages, same-origin by default and scoped by match_patterns (glob or /regex/). Each page takes the cheap path first — content-negotiated Markdown/Text when the site advertises it (see llm_surface), otherwise a detached render — and is distilled to Markdown and indexed into LanceDB Cortex. Returns a per-page summary (depth, via, bytes, links, indexed). New: src/main/crawl/crawler.ts, route POST /crawl/deep, and npm run test:crawl.
• research_topic — autonomous research mode (Feature 3). Runs search_web → gathers the top sources (cheap Markdown path first, else a detached render) → distills them to Markdown → indexes them into LanceDB Cortex. Returns extractive, cited evidence: every per-source highlight is a real paragraph that mentions the query terms, plus the ranked source list. It deliberately does not synthesize prose (Kuang has no LLM) — the calling agent writes the answer, and can follow up with recall_memory over the indexed pages. New: src/main/research/researcher.ts, route POST /research/topic, and npm run test:research.

Changed

• extract gained two kinds (Feature 2 — structured data). kind:"schema_org" parses <script type="application/ld+json"> into typed items (flattens @graph; type filters to e.g. "Recipe" / "Product" / "FAQPage" / "HowTo"), and kind:"tables" returns every table on the page (the existing table kind reads only one). The rest of Feature 2 already existed and is unchanged: the clean article body is observe(as:"markdown") (Mozilla Readability, with an aggregator fallback), and kind:"app_data" already returned parsed JSON-LD / __NEXT_DATA__. No new tool was added.
• Advertised tool surface trimmed from 74 to 54 with no capability removed. Deprecated names are hidden from tools/list but still callable by name; calling one returns a ⚠ deprecated tool name — use "…" notice.
  • Phase 2 (de-duplicate): go_to_url → navigate_to; harvest_markdown → get_page_markdown/observe; send_desktop_notification → send_notification; save_session / restore_session / list_sessions → context_save / context_open / context_list.
  • Phase 3 (consolidate): merged take_annotated_screenshot / take_economy_screenshot / list_marks into one take_screenshot({ marks, detail: "full"|"economy"|"markdown" }); folded get_page_markdown → observe(as:"markdown"), list_marks → observe(as:"som"), get_api_payload / get_stream_messages → query_json_data, get_page_info → bridge_health.
  • Phase 5 (unify interaction): click_element / click_mark / type_text / type_mark folded into act, which now accepts mark_id | selector | x+y. See below.
  • Phase 7 (overlap sweep): recall_script → list_scripts({ query?, tag?, limit? }) (the vault list/search were one call); focus_window → set_window_visibility({ visible?, focus? }) (the bridge already focused on show); clear_network_traffic / clear_stream_messages → clear_capture({ scope }); observe's enum narrowed to markdown|text|ax|som with the structured list|table|app_data reads living on extract (the implementation was already a thin wrapper).
• take_screenshot is now the single screenshot tool. marks=false (default) returns a plain viewport image; marks=true returns Set-of-Marks with detail:"full" (PNG), "economy" (640px JPEG), or "markdown" (marks table, no image). It fronts both /screenshot and /marks/screenshot per call via the new endpointFor catalog field, and the image-return path is unified.
• Renamed the ambiguous Cortex history pair: get_history → browsing_history and clear_history → browsing_history_clear (old names kept as hidden aliases). navigate_history keeps its name — it really is page-navigation history.
• act is now the single interaction entry point. It addresses one target three ways — mark_id (preferred: a Set-of-Marks badge, re-resolved against the live DOM), selector, or x+y viewport coordinates — and performs action: "click" | "focus" | "hover" | "type" | "press" with the same delta report, await_conditions, dry_run, and secret as before. The four old front doors (click_element, click_mark, type_text, type_mark) are hidden aliases. press_key remains a visible tool. The tool name stays generic on purpose (a click_* name would lie once it also types/hovers); the advertised description leads with the concrete verbs, enumerates the three address modes, and says explicitly what it is not for (navigation, scrolling).
• The help categories and the mark-eleven://skills/guide OKF guide now reference canonical names only.
• Descriptions now carry discoverability guidance. A TOOL_TIERS map drives an auto-generated prefix on the 13 tools that have a preferred alternative — [TIER 1 · prefer] (observe, act, wait_for, expect, find, extract, collect_all, page_state, diff), [TIER 2 · fallback] (take_screenshot, snapshot_rendered_page, press_key), [TIER 3 · use deliberately] (evaluate_javascript). Hidden aliases show [DEPRECATED → use "X"]; tools that are the only way to do their job stay unprefixed.

Removed

• Dead MCP code. Deleted src/mcp/server.ts — a 45-tool in-process server that src/main/index.ts imported but never invoked (superseded by bridge-server.ts) — and its now-unused import. Deleted the orphaned scripts/mcp-server.cjs bundle, which npm run build:mcp no longer produces (it emits bin/mcp-server.cjs + scripts/mcp-server.js) and which still carried pre-Phase-7 tool names.

1.1.1 — 2026-10-19

Fixed

• MCP stdio server could vanish mid-session ("kuang goes away"). The server wrote ~500 bytes of diagnostics to stderr on every tool call. A client that pipes stderr but never drains it fills the OS pipe buffer (~64 KiB ≈ ~125 calls) and the child stops answering JSON-RPC while the Cyberdeck stays healthy — so the whole kuang tool namespace disappeared.
  • Per-call diagnostics now go to the file log only (data/logs/mcp-server.log), written through a bounded asynchronous queue (no appendFileSync in the hot path).
  • stderr carries a short boot banner by default. Writes are backpressure-aware: if a write returns false the channel goes quiet until drain, lines are dropped rather than queued, and total stderr is hard-capped at 16 KiB.
  • The verbose tools/call dump was moved off console.error.
• A wedged Cyberdeck could hang a tool call forever. Every http://127.0.0.1:4111 round-trip now has a timeout ceiling (KUANG_BRIDGE_TIMEOUT_MS, default 300000 ms — above any legitimate HIL / navigation wait) and returns a clear error instead of blocking indefinitely.
• Orphaned stdio children. Closing stdin (end / close) now triggers a logged, clean exit(0) with a synchronous log flush, so the child can no longer linger and compete for the single browser session.

Added

• Diagnostics controls: KUANG_MCP_LOG=0 (disable the file log), KUANG_MCP_STDERR=0 (disable stderr), KUANG_MCP_STDERR=verbose (per-call stderr, debugging only).
• KUANG_BRIDGE_TIMEOUT_MS to tune the per-round-trip bridge ceiling.
• docs/HANDOFF_ORCHA_MCP_STDERR.md — full root-cause write-up, the live reproduction, and the conformance checklist for MCP clients.

Changed

• npm run build:mcp now emits both bin/mcp-server.cjs (canonical) and scripts/mcp-server.js (used by the test harnesses) so the two bundles can no longer drift out of sync.

Verification

Live Cyberdeck, bridge_health driven 600× through the bundled stdio server:

npx tsc --noEmit clean.

1.1.0 — 2026-10-18

Added

• Orthogonal primitive layer: observe, act, wait_for, expect, find, extract, collect_all, page_state/diff, export_har, and context_save/open/list/delete (replace blind sleeps and guessy selectors). 16 new tools, 1 new OKF playbook partition.
• Focus-independent CDP input: clicks, typing, and wheel scrolling are delivered over the tab's attached debugger (Input.dispatchMouseEvent / dispatchKeyEvent / mouseWheel) with focus emulation, so input lands even when another application owns the OS foreground. bridge_health reports input.transport (cdp | native).
• Background-render hardening: backgroundThrottling: false plus --disable-backgrounding-occluded-windows / --disable-renderer-backgrounding / --disable-background-timer-throttling, so occluded windows still hydrate, scroll, and fire IntersectionObserver callbacks.

See docs/PROPOSED_ABSTRACTIONS.md for the design and status.