Skip to content

v2.5.0 — tab-targeting-v2

Choose a tag to compare

View all tags
@kiki830621 kiki830621 released this 17 Apr 16:10
v2.5.0
68a64bc

What's new

tab-targeting-v2 — Resolver convergence + new human-emulation design principle + 6 issue #28 reliability gaps fixed.

Breaking changes

  • open <url> default changed from "navigate front tab" to "focus-existing → else new-tab" — matching tab is focused via the spatial interaction gradient (noop / tab-switch / window raise / cross-Space new-tab). Use open --replace-tab <url> for legacy behavior.
  • .urlContains multi-match unified fail-closed across all subcommands — js --url plaud now exits with ambiguousWindowMatch when multiple tabs match, same as upload --native. Use --first-match to opt back into first-match (with stderr warning listing all candidates).
  • --tab N deprecated (removed in v3.0) — emits stderr warning. Migrate to --document N (same semantics) or --window M --tab-in-window N (window-scoped).
  • documents output format changed to tab-level — one line per tab (was one line per window). New columns w{window}.t{tab} + current-tab * marker. --json adds window / tab_in_window / is_current fields.

New features

  • --window M --tab-in-window N composite flag — structured addressing for duplicate-URL tabs (issue #28 escape hatch).
  • --first-match — opt-in first-match with stderr warning enumerating all candidates.
  • --replace-tab — open opt-out back to v2.4 navigate-front-tab semantics.
  • Spatial interaction gradient — 4-layer policy for focusExistingTab: noop (same tab), tab-switch (same window), raise (same Space), new-tab-in-current-Space (cross-Space). Uses private CGS SPI (CGSGetActiveSpace / CGSGetWindowWorkspace); falls back to Layer 3 raise when SPI unavailable.
  • New human-emulation design principle — co-equal with non-interference. Four derived rules: tab bar is ground truth / ambiguity fails-closed / known URLs focus instead of reopen / spatial interaction is gradient-based. See openspec/specs/human-emulation/spec.md.

Bug fixes

Issue #28 six reliability gaps:

  1. documents and upload --native now agree on tab enumeration (shared flattenWindowsToDocuments / pickNativeTarget source).
  2. Same-URL duplicate tabs addressable via --window M --tab-in-window N.
  3. close --url multi-match fails-closed instead of silently killing multiple tabs.
  4. Repeated open <url> no longer accumulates duplicate tabs (focus-existing default).
  5. js --url plaud and upload --native --url plaud apply identical ambiguous-match policy.
  6. (Deferred) Gap 6 — upload --native modal orphan recovery — tracked as separate future change per proposal Non-Goals.

Tests

238/238 pass. 193 new unit tests added across 9 new test files (ResolverConvergenceTests, DocumentsCommandTests, TargetOptionsTests, FirstMatchTests, OpenCommandTests, TabDeprecationTests, SpatialGradientTests, Issue28RegressionTests, plus 1 updated fixture).

Migration

See README ## Migrating from v2.4 to v2.5 (tab-targeting-v2) for the full migration table.

Assets 3
Loading