teamshare-bridge 0.26.20 → 0.26.21

package/dist/lib/browser/session-pool.d.ts

@@ -41,4 +41,44 @@ export declare function pickDebugProfileDir(opts: {
     sessionKey: string;
     usedDirs: Iterable<string>;
     namedDir?: string;
+    /** Force an isolated per-session profile, never the shared one (2026-11). */
+    forceIsolated?: boolean;
 }): ProfileChoice;
+/** Normalize a test-account label for comparison (2026-11). */
+export declare function normalizeActor(raw: unknown): string | null;
+/**
+ * Resolve the session a no-sessionId command runs against (2026-11).
+ *
+ * Explicit > the caller's remembered names > the derived identity default.
+ * Only the CALLER's windows count: another agent's Chrome on the same machine
+ * must never make my action ambiguous. With two or more of MY live windows
+ * and no name, the command is AMBIGUOUS — acting on "whichever was touched
+ * last" would drive the wrong Chrome.
+ */
+export declare function resolveSessionForCommand(input: {
+    explicit?: string | null;
+    remembered: string[];
+    derived: string;
+    live: Array<{
+        id: string;
+        actor?: string | null;
+    }>;
+}): {
+    sessionId: string;
+} | {
+    ambiguous: Array<{
+        id: string;
+        actor?: string | null;
+    }>;
+};
+/**
+ * Actor gate for tagged windows (2026-11). A window never changes hands:
+ * a login in the Admin window can only be the Admin.
+ */
+export declare function assertActorForLogin(input: {
+    sessionActor?: string | null;
+    callActor?: string | null;
+}): null | {
+    code: 'ACTOR_REQUIRED' | 'WRONG_SESSION_ACTOR';
+    message: string;
+};

package/dist/lib/browser/session-pool.js

@@ -6,6 +6,9 @@ exports.deriveSessionKey = deriveSessionKey;
 exports.sessionSlug = sessionSlug;
 exports.pickDebugPort = pickDebugPort;
 exports.pickDebugProfileDir = pickDebugProfileDir;
+exports.normalizeActor = normalizeActor;
+exports.resolveSessionForCommand = resolveSessionForCommand;
+exports.assertActorForLogin = assertActorForLogin;
 /**
  * Browser session identity + port/profile allocation (2026-10).
  *
@@ -116,7 +119,7 @@ function pickDebugProfileDir(opts) {
         }
         return { dir: opts.namedDir, shared: false };
     }
-    if (!used.has(key(opts.baseDir))) {
+    if (!used.has(key(opts.baseDir)) && !opts.forceIsolated) {
         return { dir: opts.baseDir, shared: true };
     }
     const dir = (0, node_path_1.join)((0, node_path_1.dirname)(opts.baseDir), `${(0, node_path_1.basename)(opts.baseDir)}-sessions`, sessionSlug(opts.sessionKey));
@@ -125,4 +128,62 @@ function pickDebugProfileDir(opts) {
     }
     return { dir, shared: false };
 }
+/** Normalize a test-account label for comparison (2026-11). */
+function normalizeActor(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    return trimmed ? trimmed.toLowerCase() : null;
+}
+/**
+ * Resolve the session a no-sessionId command runs against (2026-11).
+ *
+ * Explicit > the caller's remembered names > the derived identity default.
+ * Only the CALLER's windows count: another agent's Chrome on the same machine
+ * must never make my action ambiguous. With two or more of MY live windows
+ * and no name, the command is AMBIGUOUS — acting on "whichever was touched
+ * last" would drive the wrong Chrome.
+ */
+function resolveSessionForCommand(input) {
+    if (input.explicit)
+        return { sessionId: input.explicit };
+    const liveById = new Map(input.live.map((s) => [s.id, s]));
+    const owned = input.remembered.filter((id) => liveById.has(id));
+    if (owned.length >= 2) {
+        return { ambiguous: owned.map((id) => liveById.get(id)) };
+    }
+    if (owned.length === 1)
+        return { sessionId: owned[0] };
+    // None of my remembered windows is live: fall back to my derived default.
+    // When it is not live either, the action fails with "No active browser
+    // session <derived>" — which is the correct answer, never another agent's
+    // window and never a guess.
+    return { sessionId: input.derived };
+}
+/**
+ * Actor gate for tagged windows (2026-11). A window never changes hands:
+ * a login in the Admin window can only be the Admin.
+ */
+function assertActorForLogin(input) {
+    const session = normalizeActor(input.sessionActor);
+    const call = normalizeActor(input.callActor);
+    if (!session)
+        return null;
+    if (!call) {
+        return {
+            code: 'ACTOR_REQUIRED',
+            message: `ACTOR_REQUIRED: this browser window is tagged for "${input.sessionActor}". ` +
+                `Pass actor:"${input.sessionActor}" on login (and sessionId on every action).`,
+        };
+    }
+    if (session !== call) {
+        return {
+            code: 'WRONG_SESSION_ACTOR',
+            message: `WRONG_SESSION_ACTOR: this window belongs to "${input.sessionActor}" — ` +
+                `it cannot sign in as "${input.callActor}". Open that account's own window ` +
+                `with browser_open({ sessionId, actor:"${input.callActor}" }) instead.`,
+        };
+    }
+    return null;
+}
 //# sourceMappingURL=session-pool.js.map

package/dist/lib/browser/session-pool.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-pool.js","sourceRoot":"","sources":["../../../src/lib/browser/session-pool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-pool.js","sourceRoot":"","sources":["../../../src/lib/browser/session-pool.ts"],"names":[],"mappings":"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"}

package/dist/lib/browser/session.d.ts

@@ -45,6 +45,10 @@ export interface BrowserSessionOptions {
     headless?: boolean;
     /** Persistent user-data-dir when auto-launching (default the debug profile). */
     profileDir?: string;
+    /** Test-account label this window belongs to (2026-11, one window per identity). */
+    actor?: string | null;
+    /** Force an isolated per-session profile, never shared (2026-11). */
+    isolated?: boolean;
     /** Extra Chrome args for auto-launch. */
     chromeArgs?: string[];
     /**
@@ -94,6 +98,8 @@ export declare class BrowserSession {
      * started (or the auto-answer browser) is never killed by us.
      */
     private _ownedByBridge;
+    /** Test-account label this window is tagged for (2026-11). Never changes hands. */
+    private _actor;
     /**
      * Request/response + console evidence for the whole session (QA). Attached
      * on both connect paths; the agent reads it with `browser_action
@@ -112,6 +118,10 @@ export declare class BrowserSession {
     get sessionKey(): string;
     /** The user-data-dir this session launches Chrome with. */
     get profileDir(): string;
+    /** The test-account label this window is tagged for (2026-11). */
+    get actor(): string | null;
+    /** Tag an untagged window. A tagged window never changes hands. */
+    setActor(actor: string | null | undefined): void;
     /**
      * Reconfigure a DISCONNECTED session before reconnecting it (2026-10).
      *
@@ -259,6 +269,19 @@ export declare class BrowserSession {
         stoppedBecause: string;
     }>;
     navigate(url: string): Promise<PageInfo>;
+    /**
+     * Set the browser viewport before a design-verification screenshot
+     * (2026-11): the design's viewport IS the contract — a pixel diff at any
+     * other size measures the window, not the design. Applies
+     * Emulation.setDeviceMetricsOverride on the live target and reads the
+     * viewport back, so the caller knows what the page actually reports
+     * (a clamped value is still a successful, truthful set).
+     */
+    setViewport(width: number, height: number, deviceScaleFactor?: number): Promise<{
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+    }>;
     /**
      * Capture a screenshot. Returns base64-encoded data.
      */
@@ -339,12 +362,18 @@ export declare class BrowserSession {
      * role, accessible name, state and CSS-pixel centre. Includes elements
      * inside portalled menus/popovers/dialogs, which is the whole point: a kebab
      * menu that just opened is findable without guessing a selector.
+     *
+     * `filter` (2026-11) narrows by substring over role + name + tag, so
+     * `getRefs {filter:"button"}` answers "all buttons" without a second scan.
+     * Refs are ALWAYS the full-scan numbering — a filtered view never renumbers,
+     * or a ref from the list would not resolve.
      */
-    getRefs(): Promise<{
+    getRefs(filter?: string): Promise<{
         at: number;
         count: number;
         refs: RefElement[];
         lines: string[];
+        filter?: string;
     }>;
     /**
      * Resolve a ref to a clickable point. A ref whose node left the DOM is
@@ -626,14 +655,28 @@ export declare class BrowserSession {
         nativeDialog: NativeDialogState | null;
     }>;
     /**
-     * Is the page actually usable right now? (2026-10)
+     * Wait for the screen to settle after an action (2026-11, qaVision only).
      *
-     * `connected` only says the CDP socket is open, but the TAB can be dead
-     * while the socket lives (renderer crash / "Aw, Snap!" after Chrome was
-     * killed externally). One cheap evaluate distinguishes the two, so a batch
-     * can re-attach instead of failing every step with raw CDP errors.
-     */
-    probeAlive(): Promise<boolean>;
+     * The auto-answer loop re-captures context + screenshot on every iteration
+     * and aborts its vision call on material change; the QA browser used to
+     * return the screen MID-TRANSITION (click → compactSnapshot immediately).
+     * This waits for a real navigation, an SPA route change, or a material DOM
+     * change, then for a short quiet window (no new mutations, network idle-ish)
+     * before the caller reads the screen. Bounded (~4 s default) and
+     * best-effort: a timeout resolves with what is known, never a failure.
+     */
+    waitForScreenSettle(opts?: {
+        since?: number;
+        quietMs?: number;
+        timeoutMs?: number;
+        fromUrl?: string;
+    }): Promise<{
+        changed: boolean;
+        navigated: boolean;
+        fromUrl: string | null;
+        toUrl: string | null;
+        elapsedMs: number;
+    }>;
     /**
      * Re-attach to the debug Chrome after the page died (2026-10).
      *

package/dist/lib/browser/session.js

@@ -115,6 +115,8 @@ class BrowserSession {
      * started (or the auto-answer browser) is never killed by us.
      */
     _ownedByBridge = false;
+    /** Test-account label this window is tagged for (2026-11). Never changes hands. */
+    _actor;
     /**
      * Request/response + console evidence for the whole session (QA). Attached
      * on both connect paths; the agent reads it with `browser_action
@@ -134,6 +136,10 @@ class BrowserSession {
         this._autoLaunch = opts?.autoLaunch ?? true;
         this._headless = opts?.headless ?? false;
         this._profileDir = opts?.profileDir ?? exports.DEBUG_PROFILE_DIR;
+        this._actor =
+            typeof opts?.actor === 'string' && opts.actor.trim()
+                ? opts.actor.trim()
+                : null;
         this._chromeArgs = opts?.chromeArgs ?? [];
         this._allowCredentials = opts?.allowCredentials ?? false;
         this._qaVision = opts?.qaVision ?? false;
@@ -146,6 +152,17 @@ class BrowserSession {
     get profileDir() {
         return this._profileDir;
     }
+    /** The test-account label this window is tagged for (2026-11). */
+    get actor() {
+        return this._actor;
+    }
+    /** Tag an untagged window. A tagged window never changes hands. */
+    setActor(actor) {
+        if (this._actor)
+            return;
+        if (typeof actor === 'string' && actor.trim())
+            this._actor = actor.trim();
+    }
     /**
      * Reconfigure a DISCONNECTED session before reconnecting it (2026-10).
      *
@@ -166,6 +183,8 @@ class BrowserSession {
             this._headless = opts.headless;
         if (opts.profileDir)
             this._profileDir = opts.profileDir;
+        if (opts.actor !== undefined)
+            this.setActor(opts.actor);
         if (opts.chromeArgs)
             this._chromeArgs = opts.chromeArgs;
         if (opts.allowCredentials !== undefined) {
@@ -383,8 +402,12 @@ class BrowserSession {
         (0, cdp_1.onCdpEvent)(page, 'Page.frameNavigated', (params) => {
             if (!(0, screen_change_1.isMainFrameNavigation)(params))
                 return;
+            // Stamp the load on the observer record (2026-11): the full-load half of
+            // the settle signal. The stamp lands after the new document exists, so a
+            // settle that started before the navigation still sees it.
             setTimeout(() => {
                 void install();
+                void (0, cdp_1.evaluateJs)(page, '(() => { try { const o = window.__tsScreenObs; if (o) { o.navAt = Date.now(); o.url = location.href; o.urlAt = Date.now(); } } catch {} return true; })()').catch(() => undefined);
             }, 600);
         });
     }
@@ -700,6 +723,32 @@ class BrowserSession {
         this.ensureConnected();
         return (0, cdp_1.navigateTo)(this.page, url);
     }
+    /**
+     * Set the browser viewport before a design-verification screenshot
+     * (2026-11): the design's viewport IS the contract — a pixel diff at any
+     * other size measures the window, not the design. Applies
+     * Emulation.setDeviceMetricsOverride on the live target and reads the
+     * viewport back, so the caller knows what the page actually reports
+     * (a clamped value is still a successful, truthful set).
+     */
+    async setViewport(width, height, deviceScaleFactor = 1) {
+        this.ensureConnected();
+        const w = Math.max(320, Math.min(8192, Math.floor(width)));
+        const h = Math.max(320, Math.min(8192, Math.floor(height)));
+        const dpr = Math.max(1, Math.min(3, deviceScaleFactor || 1));
+        await (0, cdp_1.cdpSend)(this.page, 'Emulation.setDeviceMetricsOverride', {
+            width: w,
+            height: h,
+            deviceScaleFactor: dpr,
+            mobile: false,
+        });
+        const actual = await (0, cdp_1.viewportOf)(this.page);
+        return {
+            width: actual?.width ?? w,
+            height: actual?.height ?? h,
+            deviceScaleFactor: actual?.dpr ?? dpr,
+        };
+    }
     /**
      * Capture a screenshot. Returns base64-encoded data.
      */
@@ -834,12 +883,28 @@ class BrowserSession {
      * role, accessible name, state and CSS-pixel centre. Includes elements
      * inside portalled menus/popovers/dialogs, which is the whole point: a kebab
      * menu that just opened is findable without guessing a selector.
+     *
+     * `filter` (2026-11) narrows by substring over role + name + tag, so
+     * `getRefs {filter:"button"}` answers "all buttons" without a second scan.
+     * Refs are ALWAYS the full-scan numbering — a filtered view never renumbers,
+     * or a ref from the list would not resolve.
      */
-    async getRefs() {
+    async getRefs(filter) {
         this.ensureConnected();
         const { at, list } = await (0, refs_1.scanRefs)(this.page);
         this._lastRefs = list;
-        return { at, count: list.length, refs: list, lines: (0, refs_1.formatRefs)(list) };
+        const needle = (filter ?? '').trim().toLowerCase();
+        if (!needle) {
+            return { at, count: list.length, refs: list, lines: (0, refs_1.formatRefs)(list) };
+        }
+        const kept = list.filter((r) => `${r.role} ${r.name} ${r.tag}`.toLowerCase().includes(needle));
+        return {
+            at,
+            count: kept.length,
+            refs: kept,
+            lines: (0, refs_1.formatRefs)(kept),
+            filter,
+        };
     }
     /**
      * Resolve a ref to a clickable point. A ref whose node left the DOM is
@@ -1571,22 +1636,86 @@ class BrowserSession {
         };
     }
     /**
-     * Is the page actually usable right now? (2026-10)
+     * Wait for the screen to settle after an action (2026-11, qaVision only).
      *
-     * `connected` only says the CDP socket is open, but the TAB can be dead
-     * while the socket lives (renderer crash / "Aw, Snap!" after Chrome was
-     * killed externally). One cheap evaluate distinguishes the two, so a batch
-     * can re-attach instead of failing every step with raw CDP errors.
+     * The auto-answer loop re-captures context + screenshot on every iteration
+     * and aborts its vision call on material change; the QA browser used to
+     * return the screen MID-TRANSITION (click → compactSnapshot immediately).
+     * This waits for a real navigation, an SPA route change, or a material DOM
+     * change, then for a short quiet window (no new mutations, network idle-ish)
+     * before the caller reads the screen. Bounded (~4 s default) and
+     * best-effort: a timeout resolves with what is known, never a failure.
      */
-    async probeAlive() {
-        try {
-            this.ensureConnected();
-            await (0, cdp_1.evaluateJs)(this.page, '1');
-            return true;
-        }
-        catch {
-            return false;
+    async waitForScreenSettle(opts) {
+        const started = Date.now();
+        const since = opts?.since ?? started;
+        const quietMs = Math.min(Math.max(opts?.quietMs ?? 300, 100), 2_000);
+        const timeout = Math.min(Math.max(opts?.timeoutMs ?? 4_000, 500), 15_000);
+        const deadline = started + timeout;
+        const fromUrl = opts?.fromUrl ?? null;
+        let toUrl = null;
+        let navigated = false;
+        let changed = false;
+        let quietSince = Date.now();
+        let lastMutated = 0;
+        while (Date.now() < deadline) {
+            if (this._nativeDialog)
+                break;
+            let seen = null;
+            let href = null;
+            try {
+                const raw = (await (0, cdp_1.evaluateJs)(this.page, '(() => { const o = window.__tsScreenObs; const h = location.href; return { obs: o ? { mutated: o.mutated || 0, changed: o.changed || 0, url: o.url || null, urlAt: o.urlAt || 0, navAt: o.navAt || 0 } : null, href: h }; })()'));
+                seen = raw?.obs ?? null;
+                href = raw?.href ?? null;
+            }
+            catch {
+                // Navigation destroyed the execution context: the page IS changing.
+                // Wait for it to come back instead of reporting a settled screen.
+                await new Promise((resolve) => setTimeout(resolve, 250));
+                continue;
+            }
+            if (href)
+                toUrl = href;
+            const frameNav = (seen?.navAt ?? 0) >= since;
+            const spaNav = (seen?.urlAt ?? 0) >= since ||
+                (fromUrl !== null && href !== null && href !== fromUrl);
+            if (frameNav || spaNav)
+                navigated = true;
+            if ((seen?.changed ?? 0) >= since || (seen?.mutated ?? 0) >= since) {
+                changed = true;
+            }
+            const mutated = seen?.mutated ?? 0;
+            if (mutated > lastMutated) {
+                lastMutated = mutated;
+                quietSince = Date.now();
+            }
+            const quietFor = Date.now() - quietSince;
+            const networkQuiet = this.network.pendingCount() === 0;
+            // Resolve when SOMETHING happened and the page went quiet — or when
+            // nothing happened at all for the quiet window (a no-op click settles
+            // immediately instead of burning the full timeout).
+            if ((navigated || changed) && quietFor >= quietMs && networkQuiet)
+                break;
+            // Minimum observation window (2026-11): the observer debounces at
+            // 500 ms and a click's mutations take a moment to arrive, so exiting on
+            // the first quiet poll (~300 ms in) reported "settled" while the page
+            // was still mid-transition. A genuinely idle page still exits after
+            // ~700 ms, not the full timeout.
+            if (!navigated &&
+                !changed &&
+                quietFor >= quietMs &&
+                networkQuiet &&
+                Date.now() - started >= Math.max(quietMs, 700))
+                break;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(120, Math.max(0, deadline - Date.now()))));
         }
+        return {
+            changed,
+            navigated,
+            fromUrl,
+            toUrl,
+            elapsedMs: Date.now() - started,
+        };
     }
     /**
      * Re-attach to the debug Chrome after the page died (2026-10).