@ascendenceai/cortena-extensions-e2e-kit 0.1.0

package/dist/fixtures/consent.js

@@ -0,0 +1,220 @@
+import { expect } from '@playwright/test';
+import { CONSENT } from '../locators.js';
+import { readCredentials } from '../env.js';
+/**
+ * The MCP consent page (§23.4, rules P-08 and P-16).
+ *
+ * This is the one screen of the six that **no extension renders**. The OAuth
+ * flow lands on cortena-auth's own hosted page — a different deployment, a
+ * different repository, and today not built from cortena-ui at all. So it is
+ * located by what a consent page *is* rather than by a `data-slot` this
+ * repository could promise: a page that names the client and the resource,
+ * lists the scopes being asked for, and offers a way to allow and a way to
+ * refuse. `ConsentScreen`'s slots are tried first, so the day cortena-auth
+ * adopts the shared composition this stops being heuristic and nothing here
+ * changes.
+ *
+ * The whole request is **discovered**, not written down: RFC 9728
+ * `/.well-known/oauth-protected-resource` on the extension's own host gives the
+ * resource identifier, the authorisation server and the scopes; the server's
+ * metadata gives the endpoints. That is exactly the sequence an MCP client
+ * performs, so a deployment whose metadata is wrong fails here rather than
+ * passing against values a test file remembered.
+ *
+ * It is asserted **without accepting**. Pressing Allow mints a real grant for
+ * the test user against a real resource, and a suite that does that on every
+ * run leaves a trail of grants nobody revokes. What the protocol requires is
+ * that the page exists, says what is being asked for, and can be refused.
+ */
+export async function consent(page, options) {
+    const resource = await discoverProtectedResource(page, options.host);
+    const issuer = resource.authorization_servers[0];
+    expect(issuer, `${options.host} advertises no authorization server (RFC 9728)`).toBeTruthy();
+    const server = await discoverAuthorizationServer(page, issuer);
+    const scopes = options.scopes ?? resource.scopes_supported?.slice(0, 1) ?? [];
+    const redirectUri = options.redirectUri ?? `${resource.resource.replace(/\/+$/, '')}/callback`;
+    /*
+     * A client registered here is a record on a real authorisation server, and
+     * this suite runs on every deploy in two theme projects. Left behind, that is
+     * two `dcr-…` clients per deploy for as long as nobody looks — the same
+     * litter the refusal below exists to avoid on the grant side. So the
+     * registration is remembered and deleted in the `finally`, and a client
+     * supplied by the caller is never touched.
+     */
+    const registration = options.clientId
+        ? undefined
+        : await registerClient(page, server, redirectUri);
+    const clientId = options.clientId ?? registration.clientId;
+    try {
+        await page.goto(authorizeUrl({ server, clientId, redirectUri, resource: resource.resource, scopes }));
+        // The authorisation request lands on the server's own sign-in first. That
+        // is correct — consent is a *user's* decision — so it is walked, not
+        // skipped.
+        await signInAtAuthorizationServer(page);
+        const shared = page.locator(CONSENT.screen);
+        if (await shared.isVisible().catch(() => false)) {
+            await expect(page.locator(CONSENT.scopes)).toBeVisible();
+        }
+        const allow = page.getByRole('button', { name: CONSENT.byForm.allow });
+        const deny = page.getByRole('button', { name: CONSENT.byForm.deny });
+        await expect(allow.first(), 'the consent page must offer a way to allow').toBeVisible();
+        await expect(deny.first(), 'a consent page with no way to refuse is not consent').toBeVisible();
+        // It has to say what is being asked for, or the user is consenting to a word.
+        for (const scope of scopes) {
+            await expect(page.getByText(scope, { exact: false }).first()).toBeVisible();
+        }
+        // Refused, never accepted. The flow ends here and no grant exists.
+        await deny.first().click();
+    }
+    finally {
+        if (registration)
+            await deleteClient(page, registration);
+    }
+}
+/** RFC 9728, from the extension's own host. */
+export async function discoverProtectedResource(page, host) {
+    const url = `${host.replace(/\/+$/, '')}/.well-known/oauth-protected-resource`;
+    const res = await page.request.get(url);
+    expect(res.status(), `${url} must serve the protected-resource metadata (P-16)`).toBe(200);
+    return (await res.json());
+}
+export async function discoverAuthorizationServer(page, issuer) {
+    const url = `${issuer.replace(/\/+$/, '')}/.well-known/oauth-authorization-server`;
+    const res = await page.request.get(url);
+    expect(res.status(), `${url} must serve the authorization-server metadata`).toBe(200);
+    return (await res.json());
+}
+/**
+ * Dynamic client registration — RFC 7591, and what every MCP client that has
+ * never met this server does on first use. A suite that needs a client id
+ * provisioned by hand is a suite that stops working the day the environment is
+ * rebuilt, which is the day it is most needed.
+ */
+export async function registerClient(page, server, redirectUri) {
+    expect(server.registration_endpoint, 'the authorization server offers no registration endpoint, so the suite needs a client id '
+        + 'in CORTENA_E2E_MCP_CLIENT_ID').toBeTruthy();
+    const res = await page.request.post(server.registration_endpoint, {
+        data: {
+            client_name: 'cortena-e2e',
+            redirect_uris: [redirectUri],
+            grant_types: ['authorization_code'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+        },
+    });
+    expect(res.status(), 'dynamic client registration failed').toBeLessThan(300);
+    const body = (await res.json());
+    expect(body.client_id, 'the registration response carried no client_id').toBeTruthy();
+    /*
+     * RFC 7591 §3.2.1: a server that supports management hands back the token
+     * and the URI for it right here, and this is the only moment they exist —
+     * the token is not re-issuable, so a registration whose response was thrown
+     * away is a client nobody can delete.
+     */
+    return {
+        clientId: body.client_id,
+        registrationAccessToken: body.registration_access_token,
+        registrationClientUri: body.registration_client_uri
+            ?? `${server.registration_endpoint.replace(/\/+$/, '')}/${encodeURIComponent(body.client_id)}`,
+    };
+}
+/**
+ * Deletes the client this run registered — RFC 7592.
+ *
+ * Best effort, and deliberately so. Client management is optional: a server
+ * that does not implement it answers 404, 405 or 501, and failing the consent
+ * spec because the *cleanup* was not supported would report the product broken
+ * over a housekeeping detail. It says what happened and moves on; what it must
+ * never do is silently skip cleanup on a server that does support it, which is
+ * why the outcome is always logged.
+ */
+export async function deleteClient(page, registration) {
+    const { clientId, registrationAccessToken, registrationClientUri } = registration;
+    if (!registrationClientUri) {
+        process.stdout.write(`[e2e-kit] client ${clientId} was registered but the server gave no management URI, so it `
+            + 'cannot be deleted. It will accumulate one per run.\n');
+        return;
+    }
+    try {
+        const res = await page.request.delete(registrationClientUri, {
+            headers: registrationAccessToken
+                ? { authorization: `Bearer ${registrationAccessToken}` }
+                : {},
+            failOnStatusCode: false,
+        });
+        const status = res.status();
+        if (status === 204 || status === 200)
+            return;
+        process.stdout.write(`[e2e-kit] could not delete the registered client ${clientId}: ${status}. RFC 7592 client `
+            + 'management is optional, so this is a note rather than a failure.\n');
+    }
+    catch (err) {
+        process.stdout.write(`[e2e-kit] could not delete the registered client ${clientId}: `
+            + `${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * The authorisation request, with PKCE.
+ *
+ * The verifier is fixed and public on purpose: no code is ever exchanged — the
+ * suite refuses the grant — so there is nothing for a secret to protect, and a
+ * generated one would only make the failure harder to reproduce.
+ */
+export const PKCE_VERIFIER = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
+export const PKCE_CHALLENGE = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM';
+export function authorizeUrl(input) {
+    const url = new URL(input.server.authorization_endpoint);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', input.clientId);
+    url.searchParams.set('redirect_uri', input.redirectUri);
+    // RFC 8707. Without it the token is for the server rather than for this
+    // extension, which is the confused-deputy the MCP spec's audience rule closes.
+    url.searchParams.set('resource', input.resource);
+    if (input.scopes.length)
+        url.searchParams.set('scope', input.scopes.join(' '));
+    url.searchParams.set('state', 'cortena-e2e');
+    url.searchParams.set('code_challenge', PKCE_CHALLENGE);
+    url.searchParams.set('code_challenge_method', 'S256');
+    return url.toString();
+}
+/**
+ * cortena-auth's own sign-in, which the authorisation request lands on before
+ * it will show a consent page. Its markup is the server's, not cortena-ui's,
+ * so this is by accessible name and nothing else. Already signed in, there is
+ * no form and this returns.
+ */
+export async function signInAtAuthorizationServer(page) {
+    const credentials = readCredentials();
+    // The organisation first. cortena-auth asks which org is signing in before
+    // it asks for a credential, for the same reason an extension's login does:
+    // the org decides whether this is a password, Google, or both.
+    const org = page.getByLabel(CONSENT.signIn.org);
+    if (await org.isVisible({ timeout: 15_000 }).catch(() => false)) {
+        await org.fill(credentials.orgId);
+        await page.getByRole('button', { name: CONSENT.signIn.orgSubmit }).first().click();
+    }
+    const password = page.getByLabel(CONSENT.signIn.password);
+    if (!(await password.isVisible({ timeout: 15_000 }).catch(() => false))) {
+        // Already signed in at the authorisation server: straight to consent.
+        await pickOrganisation(page, credentials.orgId);
+        return;
+    }
+    if (!credentials.email || !credentials.password) {
+        throw new Error('The consent page needs CORTENA_E2E_USER_EMAIL and CORTENA_E2E_USER_PASSWORD: consent is a '
+            + 'user\'s decision, so the authorisation server asks who is deciding, and a pre-minted '
+            + 'CORTENA_E2E_TOKEN is not a session on that host.');
+    }
+    await page.getByLabel(CONSENT.signIn.email).fill(credentials.email);
+    await password.fill(credentials.password);
+    await page.getByRole('button', { name: CONSENT.signIn.submit }).first().click();
+    await pickOrganisation(page, credentials.orgId);
+}
+/** The org step, for a user who is a member of more than one. */
+async function pickOrganisation(page, orgId) {
+    const picker = page.locator(CONSENT.byForm.orgPick);
+    if (!(await picker.first().isVisible({ timeout: 3_000 }).catch(() => false)))
+        return;
+    const mine = picker.filter({ hasText: orgId });
+    await ((await mine.count()) > 0 ? mine.first() : picker.first()).click();
+}
+//# sourceMappingURL=consent.js.map

package/dist/fixtures/consent.js.map

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

package/dist/fixtures/embedded.d.ts

@@ -0,0 +1,47 @@
+import { type Page } from '@playwright/test';
+export interface EmbeddedOptions {
+    /** The route inside the extension the tile opens. Defaults to `/`. */
+    route?: string;
+    /** Overrides `CORTENA_E2E_TOKEN`. */
+    token?: string;
+    /**
+     * The theme CortenaWeb posts in after the frame loads. Left unset, no message
+     * is posted and the extension keeps whatever it decided for itself.
+     */
+    hostTheme?: 'light' | 'dark';
+}
+/**
+ * Launches the extension the way CortenaWeb does.
+ *
+ * CortenaWeb puts the extension in an iframe and hands it an **access token on
+ * the URL and no refresh token**: `?token=<jwt>&refreshToken=none`. The host
+ * holds the real refresh token, and the placeholder is what tells the
+ * extension the session is not its to rotate — Tasks reads exactly this and
+ * mounts `SessionGuard` only when the session is its own, because a guard
+ * counting down to a refresh it cannot perform drops the user on a login
+ * screen inside the iframe at about 75% of the token's life (§10.4).
+ *
+ * So the check is not "does it render". It is: with a token and `none`, the
+ * app renders its shell and shows **no login screen** (P-04). An extension
+ * that quietly falls through to its own login page inside the frame is the
+ * failure this catches, and it is invisible to every other layer.
+ *
+ * The frame itself is not reproduced here — a cross-origin iframe would only
+ * add a frame handle to every locator, and CortenaWeb's contract with the
+ * extension is the URL and the theme message, both of which are driven
+ * directly.
+ */
+export declare function embedded(page: Page, options?: EmbeddedOptions): Promise<void>;
+/**
+ * The message CortenaWeb posts into the frame on load and on every theme
+ * change. `useCortenaTheme` listens for it and applies the *mode* — never the
+ * host's raw colours, which would override the design tokens.
+ */
+export declare function postHostTheme(page: Page, mode: 'light' | 'dark'): Promise<void>;
+/**
+ * The token is on the URL for exactly one navigation. The app replaces the
+ * history entry as soon as it has read it, so a screenshot, a trace and a
+ * shared link do not carry a live credential — and if it does not, this is
+ * where that leak is caught.
+ */
+export declare function expectTokenStrippedFromUrl(page: Page): Promise<void>;

package/dist/fixtures/embedded.js

@@ -0,0 +1,60 @@
+import { expect } from '@playwright/test';
+import { SHELL, THEME } from '../locators.js';
+import { isSignInScreen, withToken } from './sign-in.js';
+import { readCredentials } from '../env.js';
+/**
+ * Launches the extension the way CortenaWeb does.
+ *
+ * CortenaWeb puts the extension in an iframe and hands it an **access token on
+ * the URL and no refresh token**: `?token=<jwt>&refreshToken=none`. The host
+ * holds the real refresh token, and the placeholder is what tells the
+ * extension the session is not its to rotate — Tasks reads exactly this and
+ * mounts `SessionGuard` only when the session is its own, because a guard
+ * counting down to a refresh it cannot perform drops the user on a login
+ * screen inside the iframe at about 75% of the token's life (§10.4).
+ *
+ * So the check is not "does it render". It is: with a token and `none`, the
+ * app renders its shell and shows **no login screen** (P-04). An extension
+ * that quietly falls through to its own login page inside the frame is the
+ * failure this catches, and it is invisible to every other layer.
+ *
+ * The frame itself is not reproduced here — a cross-origin iframe would only
+ * add a frame handle to every locator, and CortenaWeb's contract with the
+ * extension is the URL and the theme message, both of which are driven
+ * directly.
+ */
+export async function embedded(page, options = {}) {
+    const token = options.token ?? readCredentials().token;
+    if (!token) {
+        throw new Error('embedded() needs CORTENA_E2E_TOKEN: the launch it reproduces IS the token handoff, and '
+            + 'signing in through the form first would prove something else.');
+    }
+    await page.goto(withToken(options.route ?? '/', token, 'none'));
+    // The shell first: it is what proves the app rendered at all, and it is what
+    // makes the short timeout below an answer rather than a race.
+    await expect(page.locator(SHELL.root)).toBeVisible({ timeout: 30_000 });
+    expect(await isSignInScreen(page, { timeout: 1_000 }), 'launched with a token and refreshToken=none, the extension must not show a login screen (§7.3, P-04)').toBe(false);
+    if (options.hostTheme)
+        await postHostTheme(page, options.hostTheme);
+}
+/**
+ * The message CortenaWeb posts into the frame on load and on every theme
+ * change. `useCortenaTheme` listens for it and applies the *mode* — never the
+ * host's raw colours, which would override the design tokens.
+ */
+export async function postHostTheme(page, mode) {
+    await page.evaluate((theme) => {
+        window.postMessage({ type: 'cortena-theme', theme }, '*');
+    }, mode);
+    await expect(page.locator('html')).toHaveAttribute(THEME.attribute, mode);
+}
+/**
+ * The token is on the URL for exactly one navigation. The app replaces the
+ * history entry as soon as it has read it, so a screenshot, a trace and a
+ * shared link do not carry a live credential — and if it does not, this is
+ * where that leak is caught.
+ */
+export async function expectTokenStrippedFromUrl(page) {
+    await expect(page).not.toHaveURL(/[?&]token=/);
+}
+//# sourceMappingURL=embedded.js.map

package/dist/fixtures/embedded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded.js","sourceRoot":"","sources":["../../src/fixtures/embedded.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAc5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAU,EAAE,UAA2B,EAAE;IACtE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,eAAe,EAAE,CAAC,KAAK,CAAC;IACvD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,yFAAyF;cACvF,+DAA+D,CAClE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,IAAI,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAEhE,6EAA6E;IAC7E,8DAA8D;IAC9D,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACxE,MAAM,CACJ,MAAM,cAAc,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAC9C,sGAAsG,CACvG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEd,IAAI,OAAO,CAAC,SAAS;QAAE,MAAM,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAU,EAAE,IAAsB;IACpE,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE;QAC5B,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC;IAC5D,CAAC,EAAE,IAAI,CAAC,CAAC;IACT,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,IAAU;IACzD,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;AACjD,CAAC"}

package/dist/fixtures/list-state.d.ts

@@ -0,0 +1,43 @@
+import { type Page } from '@playwright/test';
+export interface ListStateFilter {
+    /** The query parameter that holds the filter. URL-first is the whole rule (§9). */
+    param: string;
+    value: string;
+}
+export interface ListStateOptions {
+    /** The list route, without a query. */
+    route: string;
+    filter: ListStateFilter;
+    /**
+     * How to open a row, and how to know one is open. `open` is given the page
+     * and does whatever the extension's list does — a click, usually.
+     */
+    detail: {
+        open: (page: Page) => Promise<void>;
+        /** A URL the detail must be at. A detail that is not a route has no Back. */
+        urlPattern: RegExp;
+        close: (page: Page) => Promise<void>;
+    };
+}
+/**
+ * The five-way check of §9 / rule P-09.
+ *
+ * A list's view, filter, sort, page and selection belong in the URL. Not for
+ * neatness: state held in a component is state the user loses on every single
+ * interaction that leaves the screen, and the loss is invisible to every test
+ * that does not use a real browser with real history.
+ *
+ * So: set the filter, then do the five things that destroy component state and
+ * assert the filter survived all five.
+ *
+ *   1. open a detail            (a route change)
+ *   2. close it                 (back to the list)
+ *   3. Back                     (the browser's, not the app's)
+ *   4. reload                   (no memory at all)
+ *   5. the URL in a new page    (no memory and no history)
+ *
+ * Five separate mechanisms, and an implementation can pass four of them by
+ * accident. Copying the URL into a second page is the one that cannot be
+ * faked: if the filter is not in the URL, the new page cannot know it.
+ */
+export declare function listState(page: Page, options: ListStateOptions): Promise<void>;

package/dist/fixtures/list-state.js

@@ -0,0 +1,58 @@
+import { expect } from '@playwright/test';
+/**
+ * The five-way check of §9 / rule P-09.
+ *
+ * A list's view, filter, sort, page and selection belong in the URL. Not for
+ * neatness: state held in a component is state the user loses on every single
+ * interaction that leaves the screen, and the loss is invisible to every test
+ * that does not use a real browser with real history.
+ *
+ * So: set the filter, then do the five things that destroy component state and
+ * assert the filter survived all five.
+ *
+ *   1. open a detail            (a route change)
+ *   2. close it                 (back to the list)
+ *   3. Back                     (the browser's, not the app's)
+ *   4. reload                   (no memory at all)
+ *   5. the URL in a new page    (no memory and no history)
+ *
+ * Five separate mechanisms, and an implementation can pass four of them by
+ * accident. Copying the URL into a second page is the one that cannot be
+ * faked: if the filter is not in the URL, the new page cannot know it.
+ */
+export async function listState(page, options) {
+    const { route, filter, detail } = options;
+    const separator = route.includes('?') ? '&' : '?';
+    const filtered = `${route}${separator}${filter.param}=${encodeURIComponent(filter.value)}`;
+    const expected = new RegExp(`[?&]${escapeRegExp(filter.param)}=${escapeRegExp(filter.value)}`);
+    await page.goto(filtered);
+    await expect(page, 'the filter must be in the URL before anything else is asserted (§9)').toHaveURL(expected);
+    // 1 — into the detail.
+    await detail.open(page);
+    await expect(page).toHaveURL(detail.urlPattern);
+    // 2 — and back out. The list must return to the filter it was left on.
+    await detail.close(page);
+    await expect(page, 'closing the detail lost the filter').toHaveURL(expected);
+    // 3 — the browser's Back, which is the one an app's own "back" button hides.
+    await page.goBack();
+    await page.goForward();
+    await expect(page, 'Back and Forward lost the filter').toHaveURL(expected);
+    // 4 — a reload has no memory of anything but the URL.
+    await page.reload();
+    await expect(page, 'reload lost the filter').toHaveURL(expected);
+    // 5 — a second page has no memory and no history either. This is the check
+    // that cannot be passed by holding state anywhere but the URL.
+    const url = page.url();
+    const copy = await page.context().newPage();
+    try {
+        await copy.goto(url);
+        await expect(copy, 'the URL did not carry the filter into a new tab').toHaveURL(expected);
+    }
+    finally {
+        await copy.close();
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=list-state.js.map

package/dist/fixtures/list-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-state.js","sourceRoot":"","sources":["../../src/fixtures/list-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAa,MAAM,kBAAkB,CAAC;AAwBrD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAU,EAAE,OAAyB;IACnE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC1C,MAAM,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAClD,MAAM,QAAQ,GAAG,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,CAAC,KAAK,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC3F,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,OAAO,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAE/F,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1B,MAAM,MAAM,CAAC,IAAI,EAAE,qEAAqE,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE9G,uBAAuB;IACvB,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAEhD,uEAAuE;IACvE,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,MAAM,MAAM,CAAC,IAAI,EAAE,oCAAoC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE7E,6EAA6E;IAC7E,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;IACpB,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;IACvB,MAAM,MAAM,CAAC,IAAI,EAAE,kCAAkC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE3E,sDAAsD;IACtD,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;IACpB,MAAM,MAAM,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAEjE,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,MAAM,MAAM,CAAC,IAAI,EAAE,iDAAiD,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5F,CAAC;YAAS,CAAC;QACT,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC"}

package/dist/fixtures/popup.d.ts

@@ -0,0 +1,44 @@
+import { type Locator, type Page } from '@playwright/test';
+export interface Popup {
+    pill: Locator;
+    panel: Locator;
+    input: Locator;
+    send: Locator;
+    stop: Locator;
+    turns: Locator;
+    userMessages: Locator;
+    assistantMessages: Locator;
+    a2ui: Locator;
+    toolCards: Locator;
+    open: () => Promise<void>;
+    close: () => Promise<void>;
+    /** Types and sends. Does not wait for the reply. */
+    send_: (text: string) => Promise<void>;
+    /** Sends and waits for the turn to finish streaming. */
+    ask: (text: string, options?: {
+        timeout?: number;
+    }) => Promise<void>;
+    /** Waits for a run to start and then finish. */
+    awaitStream: (options?: {
+        timeout?: number;
+    }) => Promise<void>;
+}
+/**
+ * `AgentChatPopup` — the extension's agent, in the corner of every screen
+ * (§19, rule P-25).
+ *
+ * Four things have to be true and only a browser can see any of them: it
+ * opens, a turn **streams** rather than arriving in one piece, the session
+ * **survives a reload**, and a tool that answers with a block of A2UI draws it
+ * rather than printing JSON. The third is the one extensions get wrong: a chat
+ * held in component state looks perfect until the user refreshes, and then the
+ * conversation they were having is gone.
+ */
+export declare function popup(page: Page): Popup;
+/**
+ * The reload half of P-25: the conversation is a session on the server, not a
+ * list in a React state hook. After a reload the pop-up is closed again — that
+ * is the shell's correct behaviour — so it is reopened and the turn that was
+ * sent before the reload has to still be there.
+ */
+export declare function expectSessionResumes(page: Page, sent: string): Promise<void>;

package/dist/fixtures/popup.js

@@ -0,0 +1,81 @@
+import { expect } from '@playwright/test';
+import { AGENT } from '../locators.js';
+/**
+ * `AgentChatPopup` — the extension's agent, in the corner of every screen
+ * (§19, rule P-25).
+ *
+ * Four things have to be true and only a browser can see any of them: it
+ * opens, a turn **streams** rather than arriving in one piece, the session
+ * **survives a reload**, and a tool that answers with a block of A2UI draws it
+ * rather than printing JSON. The third is the one extensions get wrong: a chat
+ * held in component state looks perfect until the user refreshes, and then the
+ * conversation they were having is gone.
+ */
+export function popup(page) {
+    const pill = page.locator(AGENT.pill);
+    const panel = page.locator(AGENT.panel);
+    const input = page.locator(AGENT.input);
+    const send = page.locator(AGENT.send);
+    const stop = page.locator(AGENT.stop);
+    const streaming = page.locator(AGENT.streaming);
+    const sendText = async (text) => {
+        await input.fill(text);
+        await send.click();
+    };
+    const awaitStream = async (options = {}) => {
+        const timeout = options.timeout ?? 90_000;
+        /*
+         * The stop button is the run. It is rendered while a run is in flight and
+         * replaced by send when it ends, so "the turn streamed" is: stop appeared,
+         * then stop went away. Waiting on message text instead would pass for a
+         * reply that arrived whole, which is the thing being ruled out.
+         */
+        await expect(stop.or(streaming).first()).toBeVisible({ timeout: 20_000 });
+        await expect(stop).toHaveCount(0, { timeout });
+        await expect(streaming).toHaveCount(0, { timeout });
+    };
+    return {
+        pill,
+        panel,
+        input,
+        send,
+        stop,
+        turns: page.locator(AGENT.turn),
+        userMessages: page.locator(AGENT.userMessage),
+        assistantMessages: page.locator(AGENT.assistantMessage),
+        a2ui: page.locator(AGENT.a2ui),
+        toolCards: page.locator(AGENT.toolCard),
+        async open() {
+            await expect(pill).toBeVisible();
+            await pill.click();
+            await expect(panel).toBeVisible();
+            await expect(input).toBeVisible();
+        },
+        async close() {
+            await page.locator(AGENT.collapse).click();
+            await expect(panel).toHaveCount(0);
+        },
+        send_: sendText,
+        async ask(text, options = {}) {
+            await sendText(text);
+            await expect(page.locator(AGENT.userMessage).filter({ hasText: text })).toBeVisible();
+            await awaitStream(options);
+        },
+        awaitStream,
+    };
+}
+/**
+ * The reload half of P-25: the conversation is a session on the server, not a
+ * list in a React state hook. After a reload the pop-up is closed again — that
+ * is the shell's correct behaviour — so it is reopened and the turn that was
+ * sent before the reload has to still be there.
+ */
+export async function expectSessionResumes(page, sent) {
+    await page.reload();
+    const resumed = popup(page);
+    await resumed.open();
+    await expect(resumed.userMessages.filter({ hasText: sent }).first()).toBeVisible({
+        timeout: 30_000,
+    });
+}
+//# sourceMappingURL=popup.js.map

package/dist/fixtures/popup.js.map

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

package/dist/fixtures/shell.d.ts

@@ -0,0 +1,63 @@
+import { type Locator, type Page } from '@playwright/test';
+/**
+ * What the extension claims its shell says. The kit knows the *shape* of the
+ * chrome; only the extension knows its own name and its own destinations.
+ */
+export interface ShellExpectations {
+    /** The words beside the mark, top-left. */
+    brandName: string;
+    /** Nav item labels that must be present. A subset: an extension may have more. */
+    navItems: string[];
+    /** Ids of the extension's own avatar-menu rows, beyond profile/settings/logout. */
+    menuItems?: string[];
+}
+/**
+ * Every part of `AppShell`, as locators.
+ *
+ * Written as a bundle rather than six helper functions because the assertions
+ * a spec makes about the shell are almost always several at once, and a spec
+ * that reaches for `page.locator('[data-slot="…"]')` itself is a spec that
+ * survives a rename the kit was supposed to catch.
+ */
+export interface Shell {
+    root: Locator;
+    header: Locator;
+    brand: Locator;
+    brandName: Locator;
+    brandSquare: Locator;
+    brandMark: Locator;
+    nav: Locator;
+    navItems: Locator;
+    navItem: (label: string) => Locator;
+    navItemById: (id: string) => Locator;
+    /** The row marked `aria-current="page"`. */
+    currentNavItem: Locator;
+    navToggle: Locator;
+    navDrawer: Locator;
+    navDrawerClose: Locator;
+    main: Locator;
+    avatarTrigger: Locator;
+    menuItem: (id: string) => Locator;
+    cluster: Locator;
+    themeToggle: Locator;
+    helpButton: Locator;
+    helpPanel: Locator;
+    /** Opens the avatar menu and waits for it. */
+    openAvatarMenu: () => Promise<void>;
+    /** Opens the help panel and waits for the shell's aside. */
+    openHelp: () => Promise<void>;
+    /** Narrows the viewport until the drawer is the navigation, then opens it. */
+    openNavDrawer: () => Promise<void>;
+}
+export declare function shell(page: Page): Shell;
+/**
+ * §10 / P-10, in one call: the mark and the name top-left, the destinations in
+ * the sidebar, **Settings under the avatar and nowhere else**, and the theme
+ * and help controls in the bottom-right cluster.
+ *
+ * The "and nowhere else" half is the one that decays. An extension adds a
+ * settings link to its sidebar because it is convenient, and the fleet stops
+ * having one place settings lives; asserting the absence is the only way that
+ * gets noticed.
+ */
+export declare function expectShellChrome(page: Page, expectations: ShellExpectations): Promise<void>;