@fkn/lib 0.9.41 → 0.9.42

package/{index-D2CA-NX5.d.ts → index-BtFiGoVQ.d.ts}

@@ -47,6 +47,20 @@ type OperationModule = {
    * from `args[1]`, so it declares `options => [undefined, options]`.
    */
   ensureArgs?: (options: Record<string, unknown>) => unknown[];
+  /**
+   * Maps the arguments a caller passes to the ones the wire carries, on the calling side, before the
+   * gate and the executor see them, and gives the chain method its parameter types. It lets a public
+   * option take a new name while every backend keeps reading the old one, since a backend resolves
+   * options by its own copy. Throw to refuse a call before anything is gated or sent. Absent, the
+   * arguments travel verbatim.
+   */
+  send?: (...args: any[]) => unknown[];
+  /**
+   * `false` leaves the operation off the chain types, so a call every backend refuses on a chain is a
+   * compile error. Types only: the chain still carries it and the backend still refuses it by name,
+   * for a caller the compiler does not see. A surface that serves it declares it itself.
+   */
+  typed?: false;
 };
 type KindModules = {
   selectors: Record<string, SelectorModule>;
@@ -56,6 +70,22 @@ type Modules = {
   element: KindModules;
   frame: KindModules;
 };
+/**
+ * A chain method answered on the calling side by rewriting the parts collected so far into parts every
+ * executor already resolves, rather than by appending a part of its own name. An executor resolves
+ * selector names by its own copy of the registry and refuses one it lacks, so a member added this way
+ * reaches an older executor with a meaning it already has. `to` is the kind of chain it returns.
+ * Throw to refuse a chain the rewrite cannot express. The executor never sees it.
+ */
+type ChainRewrite = {
+  to: ChainKind;
+  rewrite: (parts: SelectorPart[], ...args: any[]) => SelectorPart[];
+};
+/** Rewrites per kind. One named as a selector of its kind takes that selector's place on the chain. */
+type Rewrites = {
+  element?: Record<string, ChainRewrite>;
+  frame?: Record<string, ChainRewrite>;
+};
 type OperationOptions = {
   timeout?: number;
 };
@@ -320,24 +350,33 @@ type Extended<B extends Modules, S extends ModulesSpec> = {
 type ArgsOf<M> = M extends {
   resolve: (context: never, ...args: infer A) => unknown;
 } ? A : never;
+type SendArgsOf<M> = M extends {
+  send: (...args: infer A) => unknown[];
+} ? A : ArgsOf<M>;
+type RewriteArgsOf<W> = W extends {
+  rewrite: (parts: never, ...args: infer A) => unknown;
+} ? A : never;
 type ResultOf<M> = M extends {
   resolve: (...args: never[]) => infer R;
 } ? Awaited<R> : never;
 type ToOf<M> = M extends {
   to: infer K extends ChainKind;
 } ? K : 'element';
-type ChainOf<M extends Modules, K extends ChainKind> = K extends 'frame' ? FrameLocator<M> : Locator$1<M>;
+type KindRewrites<R, K extends ChainKind> = K extends keyof R ? (R[K] extends Record<string, ChainRewrite> ? R[K] : {}) : {};
+type ChainOf<M extends Modules, K extends ChainKind, R extends Rewrites> = K extends 'frame' ? FrameLocator$1<M, R> : Locator$1<M, R>;
 /**
  * What `ensure` may carry. An option no gate reads is accepted and ignored rather than refused:
  * `subtree` is the one apps still pass, and the scope it once narrowed is now decided per site by
  * the gate, so passing it changes nothing.
  */
 type EnsureOptions = OperationOptions & Record<string, unknown>;
-type Chain<M extends Modules, K extends ChainKind> = { [N in keyof M[K]['selectors']]: (...args: ArgsOf<M[K]['selectors'][N]>) => ChainOf<M, ToOf<M[K]['selectors'][N]>>; } & { [N in keyof M[K]['operations']]: (...args: ArgsOf<M[K]['operations'][N]>) => Promise<ResultOf<M[K]['operations'][N]>>; } & {
+type Chain<M extends Modules, K extends ChainKind, R extends Rewrites = {}> = { [N in Exclude<keyof M[K]['selectors'], keyof KindRewrites<R, K>>]: (...args: ArgsOf<M[K]['selectors'][N]>) => ChainOf<M, ToOf<M[K]['selectors'][N]>, R>; } & { [N in keyof M[K]['operations'] as M[K]['operations'][N] extends {
+  typed: false;
+} ? never : N]: (...args: SendArgsOf<M[K]['operations'][N]>) => Promise<ResultOf<M[K]['operations'][N]>>; } & { [N in keyof KindRewrites<R, K>]: (...args: RewriteArgsOf<KindRewrites<R, K>[N]>) => ChainOf<M, ToOf<KindRewrites<R, K>[N]>, R>; } & {
   ensure: (operation: Extract<keyof M[K]['operations'], string>, options?: EnsureOptions) => Promise<void>;
 };
-type Locator$1<M extends Modules = DefaultModules> = Chain<M, 'element'>;
-type FrameLocator<M extends Modules = DefaultModules> = Chain<M, 'frame'>;
+type Locator$1<M extends Modules = DefaultModules, R extends Rewrites = {}> = Chain<M, 'element', R>;
+type FrameLocator$1<M extends Modules = DefaultModules, R extends Rewrites = {}> = Chain<M, 'frame', R>;
 declare namespace video_d_exports {
   export { BoxedVideoElement, RemoteVideoElement, VideoElementState, box, createVideoElementHandle, isType, revive, type };
 }
@@ -446,7 +485,20 @@ declare const handleRevivableModules: (defaults: DefaultRevivableModules) => rea
 type LocatorOptions = OperationOptions & {
   reason?: string;
 };
+/** `click` and `hover`'s options. */
 type PositionOptions = LocatorOptions & {
+  /**
+   * Where the pointer lands, as a 0..1 fraction of the element's box from its top-left corner: `x`
+   * across, `y` down, each 0.5 when left out, so the centre when absent. FKN's name, since
+   * Playwright's `position` is in pixels, which no backend serves yet: passing `position` is a
+   * TypeError, before anything is sent.
+   */
+  relativePosition?: {
+    x?: number;
+    y?: number;
+  };
+};
+type WirePositionOptions = LocatorOptions & {
   position?: {
     x?: number;
     y?: number;
@@ -588,10 +640,12 @@ declare const locatorModules: Extended<{
   readonly element: {
     operations: {
       click: {
-        resolve: (context: LocatorContext, options?: PositionOptions) => void;
+        resolve: (context: LocatorContext, options?: WirePositionOptions) => void;
+        send: (options?: PositionOptions) => unknown[];
       };
       hover: {
-        resolve: (context: LocatorContext, options?: PositionOptions) => void;
+        resolve: (context: LocatorContext, options?: WirePositionOptions) => void;
+        send: (options?: PositionOptions) => unknown[];
       };
       fill: {
         resolve: (context: LocatorContext, value: string, options?: LocatorOptions) => void;
@@ -628,6 +682,7 @@ declare const locatorModules: Extended<{
       };
       readonly evaluate: {
         readonly kind: "frame";
+        readonly typed: false;
         readonly resolve: (_context: LocatorContext, _source: string, _arg?: unknown) => never;
       };
     };
@@ -635,6 +690,31 @@ declare const locatorModules: Extended<{
 }>;
 type LocatorModules = typeof locatorModules;
 //#endregion
+//#region ../web-extension/lib/lib/locator-rewrites.d.ts
+declare const locatorRewrites: {
+  readonly element: {
+    readonly last: {
+      readonly to: 'element';
+      readonly rewrite: (parts: SelectorPart[]) => SelectorPart[];
+    };
+    readonly contentFrame: {
+      readonly to: 'frame';
+      readonly rewrite: (parts: SelectorPart[]) => SelectorPart[];
+    };
+  };
+  readonly frame: {
+    readonly owner: {
+      readonly to: 'element';
+      readonly rewrite: (parts: SelectorPart[]) => SelectorPart[];
+    };
+    readonly getByTestId: {
+      readonly to: 'element';
+      readonly rewrite: (parts: SelectorPart[], testId: string) => SelectorPart[];
+    };
+  };
+};
+type LocatorRewrites = typeof locatorRewrites;
+//#endregion
 //#region ../web-extension/lib/permission/shared/permission.d.ts
 /**
  * The four categories a grant is asked and stored under. Every descriptor names one, so a key
@@ -654,7 +734,7 @@ type CategoryMeta = {
   heading: string;
   summary: string;
   title: (site: string) => string;
-  /** `signedIn` is false when the frame was attached with `syncCookies: false` */
+  /** `signedIn` is false when the attach's wire carried `syncCookies: false`, which only a library that predates `cookies` sends; `cookies: 'native'` sends true */
   description: (site: string, signedIn: boolean) => string;
   cloudTitle: (site: string) => string;
   cloudDescription: (site: string) => string;
@@ -888,7 +968,20 @@ declare const permissions: {
 };
 //#endregion
 //#region ../web-extension/lib/lib/frame-core.d.ts
-type Locator = Locator$1<LocatorModules>;
+/**
+ * Elements in an attached frame, found again on every call. Playwright's members where FKN has
+ * Playwright's meaning, plus `exists`, `videoElement` and the `reason` option. `last()` is the last
+ * match; `contentFrame()` enters the iframe a trailing `locator(selector)` matches, as
+ * `frameLocator(selector)` would, and is a TypeError on a locator that ends in anything else.
+ */
+type Locator = Locator$1<LocatorModules, LocatorRewrites>;
+/**
+ * A frame inside an attached frame, entered with `frameLocator(selector)`. Its document is read
+ * as the attached frame's is. `owner()` is Playwright's: a `Locator` on the iframe it entered, whose
+ * `contentFrame()` comes back here. `getByTestId` searches from its document root. `evaluate` and
+ * `addScriptTag` run on the attached frame only, so neither is offered here.
+ */
+type FrameLocator = FrameLocator$1<LocatorModules, LocatorRewrites>;
 declare const attachFramePermission: {
   readonly scope: 'embed.iframe';
   readonly category: 'interaction';
@@ -903,28 +996,81 @@ declare const gotoPermission: {
   readonly title: 'Open a website inside this app';
   readonly description: 'Lets the app navigate to another site without leaving its window.';
 };
+/**
+ * `frame.goto`'s options. Refused with a TypeError before anything is sent: a `waitUntil` other than
+ * `'load'` or `'commit'` (Playwright's `'domcontentloaded'` and `'networkidle'` are not served, and
+ * `'documentstart'` is now `'commit'`), a `timeout` of 0 or below or not finite, and `timeoutMs`.
+ */
 type GotoOptions = {
   /**
-   * When `goto` resolves: `'load'`, the default, once the document it brings fired load;
-   * `'documentstart'` once that document has started, possibly before the page's own scripts ran.
-   * Either way a call made after it runs on the document the goto brought, never on the one it
-   * replaced. On the cloud backend a `'documentstart'` goto resolves before its document commits: an
-   * `evaluate` or `postMessage` made after it waits for that document, and a locator call retries
-   * until it comes, each within its own timeout. If that document has not come by the goto's deadline,
-   * `evaluate` and `postMessage` reject, and a locator call runs on whatever document the frame holds,
-   * since the goto itself already resolved; on the extension the goto rejects instead.
+   * When `goto` resolves: `'load'`, the default, once the document it brings fired load; `'commit'`,
+   * Playwright's, once that document holds the frame, possibly before the page's own scripts ran and
+   * whether or not it ever fires load. Either way a call made after it runs on the document the goto
+   * brought, never on the one it replaced, and the goto rejects with `TimeoutError` when that
+   * document has not come by its deadline.
    *
    * A goto that changes only the fragment of the url the page is at keeps its document. On the cloud
-   * backend one awaited to `'load'` resolves once the page reports the new fragment, and a call made
-   * after one awaited to `'documentstart'` waits only until then. Two pages are the exception there,
-   * where such a goto brings a new document like any other: one reached through a redirect, and one
-   * that followed a link onto another origin. On the extension (measured on Chromium) one awaited to
-   * `'load'` resolves, since the frame fires load for it, and one awaited to `'documentstart'` runs
-   * out at its timeout, since no new document starts.
+   * backend it resolves, either way, once the page reports the new fragment. Two pages are the
+   * exception there, where such a goto brings a new document like any other: one reached through a
+   * redirect, and one that followed a link onto another origin. On the extension (measured on
+   * Chromium) one awaited to `'load'` resolves, since the frame fires load for it, and one awaited to
+   * `'commit'` runs out at its timeout, since no new document starts.
+   */
+  waitUntil?: 'commit' | 'load';
+  /**
+   * How long the goto may take, in milliseconds: 30000 when absent. Past it the goto rejects with
+   * `TimeoutError`. A positive number: 0 is a TypeError, since every call ends by its deadline and
+   * so does not take Playwright's "0 disables the timeout".
    */
-  waitUntil?: 'documentstart' | 'load';
+  timeout?: number;
   domains?: string[];
 };
+/** `frame.addScriptTag`'s options, Playwright's `content` and FKN's `sourceUrl`. */
+type AddScriptTagOptions = {
+  /** The script's source text. */
+  content: string;
+  /** Names the script in stack traces through `//# sourceURL`. Absent, its frames name the document. */
+  sourceUrl?: string;
+};
+/**
+ * `frame.clearCookies`' options, Playwright's `browserContext.clearCookies` names with its string
+ * semantics: each matches exactly. A cookie is removed when it matches every option given; an
+ * option left out, or `undefined`, matches every cookie. Playwright also takes a RegExp for each,
+ * which FKN refuses for now (`Frame.clearCookies` says why).
+ */
+type ClearCookiesOptions = {
+  /** Only cookies with this name. */
+  name?: string;
+  /**
+   * Only cookies with this domain, in the form Playwright reports it: `.youtube.com` for a cookie
+   * its subdomains also receive, `www.youtube.com` for a host-only one, so `'youtube.com'` matches
+   * neither of those. It must be on a site this attachment reaches.
+   */
+  domain?: string;
+  /** Only cookies with this path, exactly as the cookie carries it. */
+  path?: string;
+};
+/**
+ * One `clearCookies` option as it crosses a channel, in the shapes Playwright's own wire carries: a
+ * string as `equals`, a RegExp as its source and flags. The library sends `equals` only for now and
+ * the middle page refuses a pattern; the render proxy shell still reads one.
+ */
+type CookieMatchWire = {
+  equals: string;
+} | {
+  pattern: string;
+  flags: string;
+};
+/**
+ * `frame.clearCookies`' options as `createFrame` hands them to `FrameBackend.clearCookies`, already
+ * checked, and as the cloud's channels carry them. Only the options given are present, so no options
+ * at all are `{}`; an absent one matches every cookie.
+ */
+type ClearCookiesWire = {
+  name?: CookieMatchWire;
+  domain?: CookieMatchWire;
+  path?: CookieMatchWire;
+};
 /** `frame.postMessage`'s options form, as `Window.postMessage` takes it. */
 type FramePostMessageOptions = {
   /** The page's origin as the site knows it, or `'*'`, the default. */
@@ -976,16 +1122,30 @@ type FrameEventListener<K extends keyof FrameEventMap> = (event: FrameEventMap[K
  * window or a new one, a popup). A document with nothing of the page's own to run it in, such as an
  * error page or a file that is not HTML, cannot be read, and a call on it waits to its deadline.
  */
-type Frame = Omit<FrameLocator<LocatorModules>, 'evaluate'> & {
+type Frame = Omit<FrameLocator, 'owner'> & {
+  /**
+   * Navigates the frame to `url`, which must pass the rules an iframe src does, and adds its host
+   * to the attachment. Resolves at `options.waitUntil`, and rejects with `TimeoutError` past
+   * `options.timeout` (`GotoOptions`).
+   */
   goto(url: string, options?: GotoOptions): Promise<void>;
   /** The url last given to `attachFrame` or `goto`, never the frame's live location: a page that moves itself does not change it. */
   url(): string;
+  /**
+   * Which backend serves this attachment, fixed for its life. The same call can draw a card on one
+   * backend and not the other, and spends a different identity on each, so an app must be able to
+   * tell. A method, as Playwright's scalar facts are (`frame.url()`, `frame.name()`,
+   * `page.isClosed()`). Undefined only for a Frame an app built itself with `createFrame` from a
+   * backend that names none.
+   */
+  backend(): 'cloud' | 'extension' | undefined;
   /**
    * Asks for whole categories on this attachment's hosts, before any call. Resolves per request, in
    * the order they were asked; a refusal is `allow: false`, never a rejection. An ask naming a
    * category or key the registry cannot place on a row is a `TypeError`, thrown before it is sent.
+   * Not Playwright's `page.request`, which is an HTTP client; the app asks here and the user grants.
    */
-  request(requests: CategoryRequest[]): Promise<CategoryGrant[]>;
+  requestPermissions(requests: CategoryRequest[]): Promise<CategoryGrant[]>;
   /**
    * Runs `pageFunction` inside the attached site's OWN page realm, as a script of that page would:
    * it sees the site's `window`, its globals and its DOM. The function is sent as source
@@ -994,21 +1154,26 @@ type Frame = Omit<FrameLocator<LocatorModules>, 'evaluate'> & {
    * does, and is not called. A promise, returned by the function or produced by the expression, is
    * awaited.
    *
-   * `arg` and the result cross by structured clone, so an `ArrayBuffer` or a typed array of bytes
-   * survives the round trip. A thrown error or a rejected promise comes back as an `Error` carrying
+   * `arg` is structured-cloned at the call, in the app's realm, on both backends, and the result
+   * comes back by structured clone, so an `ArrayBuffer` or a typed array of bytes survives the round
+   * trip. A value structured clone refuses in `arg` (a function, a DOM node, an untransferred port)
+   * rejects with the platform's `DataCloneError` before anything is sent; a port goes to the page
+   * with `postMessage`. A thrown error or a rejected promise comes back as an `Error` carrying
    * the page's own name and message. A result that cannot be cloned (a function, a DOM node) is a
    * `LocatorInvalidError`, never a silent `undefined` and never a live handle into the page.
    *
-   * Every limit is a `LocatorInvalidError` that names it, never a call left pending:
-   * - time, both backends: the code has 30 seconds to settle, counted after any consent card. Only
-   *   the wait ends there; code that never settles keeps running in the page.
-   * - size, extension only: the source with its `arg`, and the result, each carry at most 32 MiB
-   *   (binary data by its bytes, text by its UTF-8 size), the most its message relay carries.
-   * - `Blob`, extension only: the relay cannot carry one, so pass or return `await blob.arrayBuffer()`.
-   *   The cloud backend has neither limit, and returns a `Blob` as a `Blob`.
+   * Every limit is refused by name, never a call left pending:
+   * - time, both backends: the code has 30 seconds to settle, counted after any consent card, and
+   *   then the call rejects with `TimeoutError`. Only the wait ends there; code that never settles
+   *   keeps running in the page.
+   * - size, extension only, a `LocatorInvalidError`: the source with its `arg`, and the result, each
+   *   carry at most 32 MiB (binary data by its bytes, text by its UTF-8 size), the most its message
+   *   relay carries.
+   * - `Blob`, extension only, a `LocatorInvalidError`: the relay cannot carry one, so pass or return
+   *   `await blob.arrayBuffer()`. The cloud backend has neither limit, and returns a `Blob` as a `Blob`.
    *
    * Needs the Evaluation grant on both backends; an app without it is refused by name. It runs on the
-   * attached frame only: a chain into a nested frame (`frameLocator(...).evaluate`) is refused.
+   * attached frame only: a nested `FrameLocator` does not offer it, and a call there anyway is refused.
    *
    * Called after `goto` resolved, whichever `waitUntil`, it runs once on the document that goto
    * brought, never on the one it replaced. On the cloud backend the call waits for that document when
@@ -1020,10 +1185,118 @@ type Frame = Omit<FrameLocator<LocatorModules>, 'evaluate'> & {
    * with `ExtensionOperationUnsupportedError`), and it runs where the page's content security policy
    * allows it: a frame whose host the app declared has its CSP replaced, so code runs; an undeclared
    * frame keeps its CSP, and a page that forbids `eval` refuses with a named error. On the cloud
-   * backend the code runs in the proxied document's realm, which mirage virtualizes, so there is no
-   * such limit.
+   * backend the code runs in the proxied document's realm, which mirage virtualizes: the page's own
+   * eval refusal and Trusted Types requirement do not refuse the source `evaluate` compiles, and every
+   * string that code compiles itself (`eval`, `Function`, a string timer) is held to them, as the
+   * page's own are.
    */
   evaluate<R = unknown, A = undefined>(pageFunction: ((arg: A) => R | Promise<R>) | string, arg?: A): Promise<Awaited<R>>;
+  /**
+   * Runs `content` as a classic inline script of the attached document, as one of that page's own
+   * scripts would run: its top-level declarations stay on the page's global for later scripts and
+   * `evaluate` calls, `document.currentScript` is the script while it runs, and the page's own error
+   * listeners see its top-level error. Mirage rewrites it as it rewrites the page's scripts, and the
+   * page's eval refusal and Trusted Types requirement do not refuse it, as for `evaluate`.
+   * Playwright's name and its `content` option; its `url`, `path` and `type` are not served, and FKN's
+   * `sourceUrl` names the script rather than loading one.
+   *
+   * Resolves `undefined` once the script ran; what it installed lives as long as the document, and the
+   * `document` event says when that is gone. Same grant, limit and timing as `evaluate`: the
+   * Evaluation grant (one card covers both), 30000 ms counted after any consent card, the attached
+   * frame only, and after a `goto` the document that goto brought, waited for as `evaluate` waits. It
+   * runs once: it never rides the locator retry loop, and a call whose document left before it
+   * answered rejects and is not run again. Cloud only for now: the extension refuses it by name.
+   *
+   * Refused:
+   * - TypeError, before anything is sent, in this order: `frame.addScriptTag: options must be an
+   *   object { content }`; for Playwright's `url`, `path` and `type`, `frame.addScriptTag: "<key>" is
+   *   not served; it runs content as a classic inline script`; `frame.addScriptTag: unknown option
+   *   "<key>"`; `frame.addScriptTag: content must be a string`; `frame.addScriptTag: sourceUrl must
+   *   be a non-empty string with no line break`.
+   * - an `Error` carrying the page's own name and message: the script's top-level throw, after it ran.
+   * - `LocatorDeniedError`: no Evaluation grant, the frame holds no page, or its document is outside
+   *   the attachment. Against an FKN page that predates `addScriptTag` the call arrives with no proof
+   *   of a grant and the render proxy refuses it: `frame.addScriptTag: the call arrived without an
+   *   Evaluation grant, so it was not run`.
+   * - cloud, `LocatorUnsupportedError` `frame.addScriptTag: this render proxy predates addScriptTag;
+   *   reload the app`.
+   * - cloud, `LocatorError`: the document of the goto before it had not come by that goto's deadline,
+   *   or the app started another goto first, so the script was not run.
+   * - extension, `ExtensionOperationUnsupportedError` (operation `'addScriptTag'`)
+   *   `frame.addScriptTag: an extension frame does not run scripts through mirage yet; attach with
+   *   cloud.attachFrame`, before anything is dispatched.
+   * - `TimeoutError` `frame.addScriptTag: no answer within 30000ms; the script may or may not have
+   *   run`.
+   * - the terminal detach error once the attachment ended.
+   */
+  addScriptTag(options: AddScriptTagOptions): Promise<void>;
+  /**
+   * Removes cookies from this attachment's cookie jar, as Playwright's
+   * `browserContext.clearCookies` removes them from a context. With no options it removes every
+   * cookie of the sites this attachment reaches; with options, only the ones that match every option
+   * given (`ClearCookiesOptions`). Each option is a string for now: a RegExp is refused.
+   *
+   * For signing out of a site the user signed in to inside an FKN frame: that session lives in FKN's
+   * jar, never in the app, so the app cannot remove it any other way.
+   *
+   * Which jar: with `cookies: 'persistent'`, the default, the cloud jar of the app's top-level site,
+   * which every app of that site shares (every fkn.app app shares one), so a removal there signs
+   * every one of those apps out of that site. With `'ephemeral'` the attachment's own jar.
+   *
+   * Which cookies: only those of a site this attachment reaches, a site being a host's registered
+   * domain under the Public Suffix List, private section included: the attach url's host (the empty
+   * page's, for `blank`), each goto target's host from the goto's send, and `domains`.
+   * `www.youtube.com` reaches every `*.youtube.com` cookie and no `google.com` one, the rule browsers
+   * follow for `Clear-Site-Data: "cookies"`. A host under the same name is still another site when a
+   * suffix lies between: `amazonaws.com` reaches no `mybucket.s3.amazonaws.com` cookie, since
+   * `s3.amazonaws.com` is a suffix. A host that is itself a public suffix (`com`, `co.uk`,
+   * `github.io`) is no site, and reaches only the cookies set for exactly that host. A Partitioned
+   * cookie matches in every partition.
+   *
+   * Once it resolves: no request a document of this attachment starts carries a removed cookie, its
+   * documents' `document.cookie` lists none, and the removal is committed to the jar, so an
+   * attachment created afterwards never sees one. Another live attachment on the same jar (another
+   * tab, another app's frame) drops them when it hears the commit, normally within milliseconds; a
+   * request it started before then may still carry one. A request already in flight keeps what it
+   * was sent with, and a later response may set cookies again, as in any browser.
+   *
+   * It resolves `undefined` and never says what or how much it removed, so it cannot tell an app
+   * whether the user had a session on a site. It takes the same steps and the same store write
+   * whether or not a cookie matched, so neither how long it takes nor which refusal it meets says so
+   * either. That is why a RegExp is refused before anything is sent: it would be tested in the render
+   * proxy against cookies the app cannot read, and a pattern slow on some of them would make the
+   * call's duration, or a `TimeoutError`, say whether the jar holds one. Calling it again is
+   * harmless. It does not tell the site: the session stays valid there until it lapses, and FKN no
+   * longer holds it.
+   *
+   * No consent card on either jar, and a frame holding no page is served. Cloud only. It runs once,
+   * never inside the locator retry loop, and waits at most 30000 ms.
+   *
+   * Refused:
+   * - TypeError, before anything is sent, in this order: `frame.clearCookies: options must be an
+   *   object`; `frame.clearCookies: unknown option "<key>"`; `frame.clearCookies: <key> is a RegExp,
+   *   and clearCookies takes strings for name, domain and path for now`; `frame.clearCookies: <key>
+   *   must be a string`; `frame.clearCookies: <key> must not be empty; leave it out to match every
+   *   <key>`.
+   * - `LocatorDeniedError` `frame.clearCookies: this attachment reaches no site yet; attach a url,
+   *   goto one, or declare it in domains`.
+   * - `LocatorDeniedError` `frame.clearCookies: <domain> is not on a site this attachment reaches;
+   *   goto it or declare it in domains`, for a string `domain`.
+   * - cloud, `LocatorUnsupportedError` `frame.clearCookies: this FKN page predates clearCookies;
+   *   reload the app to load the current one`, with nothing sent.
+   * - cloud, `LocatorUnsupportedError` `frame.clearCookies: this render proxy predates clearCookies;
+   *   reload the app`.
+   * - cloud, `Error` `frame.clearCookies: the cookies are gone from this attachment, but its jar did
+   *   not take the removal, so other attachments may still send them; call it again`.
+   * - cloud, `TimeoutError` `frame.clearCookies: the render proxy did not answer within 30000ms; the
+   *   cookies may or may not be gone, and calling it again is safe`.
+   * - extension, `ExtensionOperationUnsupportedError` (operation `'clearCookies'`)
+   *   `frame.clearCookies: an extension frame runs on the browser's own cookies (cookies: 'native'),
+   *   which FKN does not clear; attach with cookies: 'persistent' to clear the app's jar`, before
+   *   anything is dispatched.
+   * - the terminal detach error once the attachment ended.
+   */
+  clearCookies(options?: ClearCookiesOptions): Promise<void>;
   /**
    * Delivers `message` to the page in the frame as a real `message` event, the way
    * `iframe.contentWindow.postMessage` would. The page sees a trusted event: `data` is the message,
@@ -1080,22 +1353,69 @@ type Frame = Omit<FrameLocator<LocatorModules>, 'evaluate'> & {
    * and not for the document the frame already held when the first listener was added. Extension:
    * fires on every load of the frame, with `origin` `''`.
    *
-   * Listeners stay on the Frame across navigations and end with the attachment. A listener that throws
-   * is reported and does not stop the others. An unknown `type` is a `TypeError`. On the cloud backend,
-   * against an FKN page that predates messaging, nothing arrives and the console says so once.
+   * Listeners stay on the Frame across navigations and end with the attachment, or when `signal`
+   * aborts, FKN's addition to Playwright's `on`. A listener added twice is called once, and one whose
+   * signal already aborted is not added. A listener that throws is reported and does not stop the
+   * others. An unknown `type`, or a listener that is not a function, is a `TypeError`. On the cloud
+   * backend, against an FKN page that predates messaging, nothing arrives and the console says so once.
    */
-  addEventListener<K extends keyof FrameEventMap>(type: K, listener: FrameEventListener<K>, options?: {
+  on<K extends keyof FrameEventMap>(type: K, listener: FrameEventListener<K>, options?: {
     signal?: AbortSignal;
   }): void;
-  removeEventListener<K extends keyof FrameEventMap>(type: K, listener: FrameEventListener<K>): void;
+  /** Removes a listener `on` added; one that is not on the Frame is ignored. An unknown `type` is a `TypeError`. */
+  off<K extends keyof FrameEventMap>(type: K, listener: FrameEventListener<K>): void;
 };
+/**
+ * Which cookie jar an attachment runs on, and with it which backend serves it. One attachment, one
+ * jar: no value unions two jars, so which cookie a request carries always has one answer. HttpOnly
+ * values never reach app code on any value.
+ *
+ * - `'persistent'`, the default: the cloud render proxy's jar of the app's top-level site
+ *   (https://fkn.app for every fkn.app app), which every app of that site shares, the same jar its
+ *   inline frames and its windows use, kept across visits. Always the cloud backend, whatever is
+ *   installed, so `frame.backend()` answers `'cloud'`. Its requests leave through WebVPN, which
+ *   keeps the cookies their answers set.
+ * - `'ephemeral'`: a fresh jar of the attachment's own, with site storage under a namespace of its
+ *   own, both gone with it. Always the cloud backend: the browser keeps a partition's cookies after
+ *   its frame goes, so no extension jar ends with the attachment. Its requests leave through WebVPN.
+ * - `'native'`: the person's own browser cookies for `domains` and every goto's host, copied into
+ *   the browser's partition for the app's top-level site on the attach and on every goto. Extension
+ *   backend only, so `frame.backend()` answers `'extension'`. Without the extension the top-level
+ *   `attachFrame` shows the install prompt, as every extension-only call does; `cloud.attachFrame`
+ *   refuses it.
+ *
+ * Refused by name before anything is attached, opened, waited for or dispatched, in this order:
+ * - any `syncCookies` key, true and false alike: TypeError `attachFrame: syncCookies was replaced
+ *   by cookies. true is cookies: 'persistent', or 'native' for the person's own browser cookies on
+ *   the extension; false is cookies: 'ephemeral'`
+ * - an unknown value: TypeError `attachFrame: cookies must be 'persistent', 'ephemeral' or
+ *   'native', not "<value>"`
+ * - any `storageState` key: TypeError `attachFrame: storageState is not available yet`
+ * - then the shape of the attachment: `iframe` and `window` at once, and `lockdown` or `blank` with
+ *   a window, each a TypeError
+ * - `lockdown` with anything but `'native'`: TypeError `attachFrame: lockdown runs on the
+ *   extension, which serves only cookies: 'native'`
+ * - `cloud.attachFrame` with `'native'`: TypeError `cloud.attachFrame: cookies: 'native' needs the
+ *   FKN browser extension; the cloud render proxy has no browser cookies`
+ * - `extension.attachFrame` with `'persistent'` or `'ephemeral'`, so also with no `cookies` at all:
+ *   `ExtensionOperationUnsupportedError` (operation `'cookies'`) `attachFrame: cookies: '<value>'
+ *   runs on the cloud render proxy; call cloud.attachFrame or the top-level attachFrame`
+ * - a window on `'native'`, through the top-level `attachFrame` or `extension.attachFrame`:
+ *   `ExtensionOperationUnsupportedError` (operation `'attachWindow'`) `attachFrame: a window on
+ *   cookies: 'native' is not served yet; a window runs on the cloud render proxy, which has no
+ *   browser cookies`, with no install prompt, so the click's activation is left for the app's
+ *   fallback
+ */
+type AttachCookies = 'persistent' | 'ephemeral' | 'native';
 type AttachFrameOptions = {
   iframe: HTMLIFrameElement;
   domains?: string[];
-  syncCookies?: boolean;
+  /** Which jar, and with it which backend: `'persistent'` when absent. See `AttachCookies`. */
+  cookies?: AttachCookies;
   /**
    * Replace the embedded site's CSP with a lockdown policy: the frame cannot fetch, connect, or load
-   * any resource. Extension backend only. It needs an extension that announces an ABI: an older one
+   * any resource. Extension backend only, so it takes `cookies: 'native'`; beside any other value it
+   * is a TypeError (see `AttachCookies`). It needs an extension that announces an ABI: an older one
    * may not serve it, so the attach is refused with `ExtensionOperationUnsupportedError` (operation
    * `'lockdown'`) before anything is attached.
    */
@@ -1105,6 +1425,67 @@ type AttachFrameOptions = {
    * refusal does not reject the attach: it surfaces on the first refused operation.
    */
   permissions?: CategoryRequest[];
+  /**
+   * Starts the frame on an empty page presented at `blank.url`, with nothing requested from that
+   * site for it. For running the app's own code (an attestation VM, a session client) in the origin
+   * it needs, without loading or running the site's page.
+   *
+   * The document is exactly
+   * `<!doctype html><html><head><meta charset="utf-8"></head><body></body></html>`, served 200 with
+   * `content-type: text/html; charset=utf-8` and `cache-control: no-store`: no content security
+   * policy, no Set-Cookie. Its `location`, `origin`, `document.URL`, `document.domain` and
+   * `baseURI` read `blank.url`, and `document.referrer` reads `''` on the first load (after a reload
+   * it reads the page's own url, as on any proxied page). `url()` returns it. `evaluate`,
+   * `postMessage` and the `message` and `document` events work as on any page. Requests the page's
+   * code makes later go out as that page's would, through WebVPN, on the attachment's jar: with
+   * `cookies: 'persistent'`, the default, the cloud jar of the app's top-level site, which every app
+   * of that site shares (HttpOnly values are never readable in the page); with `'ephemeral'` a jar
+   * of the attachment's own, and site storage under a namespace of its own, both gone with it.
+   *
+   * With `cookies: 'ephemeral'` nothing of the user's is reachable, so calls the Evaluation grant
+   * covers ask no card while the frame shows the empty page: until the attachment's first `goto`,
+   * or until code in the page moves it to another url, even on the same host, after which they ask
+   * as on any page. With `'persistent'` the Evaluation card names the url's host, as for any page.
+   *
+   * The empty page answers its url until the first `goto`: a reload of the page, or a replacement
+   * of the render proxy's own document, brings it back and fires `document`, so an installer must
+   * be idempotent. After the first `goto` the url loads from the site like any other.
+   *
+   * Always the cloud render proxy, with or without the extension: only it can present an origin
+   * without loading it. `frame.backend()` then answers `'cloud'`, and the jar is the cloud's, never
+   * the browser's.
+   *
+   * Refused, in this order, before anything is attached, and after the refusals of `cookies`
+   * (`AttachCookies`), so through `cloud.attachFrame` lockdown and `'native'` meet those first:
+   * - TypeError `attachFrame: blank must be an object { url }` (null, a string)
+   * - TypeError `attachFrame: blank takes { url }, not "<key>"` (an unknown key)
+   * - TypeError `attachFrame: blank.url must be an absolute http or https url, not "<value>"`
+   * - TypeError `attachFrame: blank needs an iframe with no src; this one has "<src>"`
+   * - TypeError `attachFrame: blank does not combine with lockdown`
+   * - TypeError `attachFrame: blank runs on the cloud render proxy, which has no browser cookies;
+   *   pass cookies: 'persistent' or 'ephemeral'` (with `cookies: 'native'`)
+   * - Error `attachFrame: refusing to target the extension's own pages or an FKN platform origin`,
+   *   the scope check every attach url meets
+   * - Error `attachFrame: a blank page is served by the cloud render proxy, which this build does
+   *   not configure`
+   *
+   * After the handshake, with the iframe put back on about:blank and nothing requested from the
+   * site: the terminal `LocatorUnsupportedError` `cloud.attachFrame: this FKN page predates blank
+   * pages; reload the app to load the current one`. The handshake and ready limits are every cloud
+   * attach's, 20000 ms and 65000 ms.
+   *
+   * Also refused, before anything opens or is dispatched: with `window`, the TypeError
+   * `attachFrame: blank does not apply to a window`, since a window opened with no `url` is already
+   * called blank there; and through `extension.attachFrame` with `cookies: 'native'`,
+   * `ExtensionOperationUnsupportedError` (operation `'blank'`) `attachFrame: a blank page is served
+   * by the cloud render proxy only; call cloud.attachFrame`.
+   */
+  blank?: BlankPage;
+};
+/** Where `attachFrame`'s `blank` option presents its empty page. */
+type BlankPage = {
+  /** Absolute http or https url the empty page is presented at. The fragment is ignored for matching. */
+  url: string;
 };
 /** Where an attachment's window opens and how big it asks to be. */
 type FrameWindowOptions = {
@@ -1130,12 +1511,14 @@ type AttachWindowOptions = {
   window: FrameWindowOptions;
   domains?: string[];
   /**
-   * Cloud, true by default: the window uses the cookie jar of the app that opened it, the same jar
-   * as that app's inline frames. A window whose app is on another site shares cookies only with
-   * those frames; its site storage stays its own. False: a jar of the window's own that ends with
-   * it. Extension: false is a TypeError, since the window is the site's own first-party tab.
+   * The window's jar, with an iframe's values (`AttachCookies`). `'persistent'`, the default: the
+   * jar of the app that opened it, the same as that app's inline frames; a window whose app is on
+   * another site shares cookies only with those frames, and its site storage stays its own.
+   * `'ephemeral'`: a jar of the window's own that ends with it. Both run on the cloud backend
+   * whatever is installed. `'native'` is refused by name: a window runs on the cloud render proxy,
+   * and no backend serves a window on the browser's own cookies yet.
    */
-  syncCookies?: boolean;
+  cookies?: AttachCookies;
   /** Whole categories asked for once the window has connected, drawn in the window on the cloud backend. */
   permissions?: CategoryRequest[];
 };
@@ -1182,15 +1565,41 @@ declare class FrameWindowRefusedError extends Error {
 type FrameBackend = {
   executor: Executor;
   gate?: Gate;
+  /**
+   * The backend's name, which `Frame.backend()` answers. Optional so a caller of `createFrame` that
+   * builds its own backend keeps compiling; absent, `Frame.backend()` answers `undefined`.
+   */
+  backend?: 'cloud' | 'extension';
+  /**
+   * Navigates, `options` already checked by `Frame.goto`: the backend maps `waitUntil: 'commit'` and
+   * `timeout` to its own wire's names, rejects with `TimeoutError` at the deadline, and is never
+   * handed `'documentstart'`.
+   */
   goto(url: string, options?: GotoOptions): Promise<void>;
   url(): string;
-  request?(requests: CategoryRequest[]): Promise<CategoryGrant[]>;
+  requestPermissions?(requests: CategoryRequest[]): Promise<CategoryGrant[]>;
   /**
    * Runs already-stringified source in the attached site's own realm and answers the cloned result.
    * The backend gates it (Evaluation) and runs it where the site's globals live. Optional so a
    * backend that cannot run code refuses `Frame.evaluate` by name rather than answering as if it had.
    */
   evaluate?(source: string, arg: unknown): Promise<unknown>;
+  /**
+   * Runs `content` as a classic inline script of the attached document and resolves once it ran,
+   * `options` already checked by `Frame.addScriptTag`. The backend gates it (Evaluation), runs it once
+   * and never through the locator retry loop. Optional so a backend that cannot run scripts refuses
+   * `Frame.addScriptTag` by name.
+   */
+  addScriptTag?(content: string, options: {
+    sourceUrl?: string;
+  }): Promise<void>;
+  /**
+   * Removes the cookies `filter` matches from the attachment's jar, `filter` already checked and
+   * serialized by `Frame.clearCookies`, and resolves `undefined` whatever was removed. Called once,
+   * never through the locator retry loop and never gated. Optional so a backend with no jar of its
+   * own refuses `Frame.clearCookies` by name.
+   */
+  clearCookies?(filter: ClearCookiesWire): Promise<void>;
   /**
    * Delivers a message to the page, `targetOrigin` already normalized (`'*'` or a serialized origin)
    * and `transfer` an array. Called synchronously by `Frame.postMessage`, so transfers detach at the
@@ -1224,6 +1633,11 @@ type AttachFrameFunction = {
 //#endregion
 //#region ../web-extension/lib/lib/frame.d.ts
 declare const ATTACH_FRAME_EVENT_KEY = "FKN_WEB_EXTENSION_ATTACH_FRAME_EVENT_KEY";
+/**
+ * Attaches through the extension, on `cookies: 'native'` only: the other values, the default
+ * among them, are the cloud render proxy's, refused here with `ExtensionOperationUnsupportedError`
+ * (operation `'cookies'`) before any exposure wait (`AttachCookies`).
+ */
 declare const attachFrame: AttachFrameFunction;
 //#endregion
-export { CATEGORIES as A, revive as B, gotoPermission as C, PermissionGrant as D, LegacyPermissionRequest as E, RemoteVideoElement as F, OperationRequest as G, Executor as H, VideoElementState as I, SelectorPart as K, box as L, PermissionCategory as M, handleRevivableModules as N, PermissionRequest as O, BoxedVideoElement as P, createVideoElementHandle as R, createFrame as S, CategoryRequest as T, Gate as U, type as V, GateTools as W, FrameWindowRefusedError as _, AttachWindowOptions as a, WindowFrame as b, FrameBackendEvent as c, FrameEventMap as d, FrameMessageEvent as f, FrameWindowRefusal as g, FrameWindowOptions as h, AttachFrameOptions as i, CategoryMeta as j, permissions as k, FrameDocumentEvent as l, FrameWindowBlockedError as m, attachFrame as n, Frame as o, FramePostMessageOptions as p, AttachFrameFunction as r, FrameBackend as s, ATTACH_FRAME_EVENT_KEY as t, FrameEventListener as u, GotoOptions as v, CategoryGrant as w, attachFramePermission as x, Locator as y, isType as z };
+export { SelectorPart as $, gotoPermission as A, handleRevivableModules as B, FrameWindowRefusal as C, WindowFrame as D, Locator as E, PermissionRequest as F, createVideoElementHandle as G, RemoteVideoElement as H, permissions as I, type as J, isType as K, CATEGORIES as L, CategoryRequest as M, LegacyPermissionRequest as N, attachFramePermission as O, PermissionGrant as P, OperationRequest as Q, CategoryMeta as R, FrameWindowOptions as S, GotoOptions as T, VideoElementState as U, BoxedVideoElement as V, box as W, Gate as X, Executor as Y, GateTools as Z, FrameEventMap as _, AttachCookies as a, FramePostMessageOptions as b, BlankPage as c, CookieMatchWire as d, Frame as f, FrameEventListener as g, FrameDocumentEvent as h, AddScriptTagOptions as i, CategoryGrant as j, createFrame as k, ClearCookiesOptions as l, FrameBackendEvent as m, attachFrame as n, AttachFrameOptions as o, FrameBackend as p, revive as q, AttachFrameFunction as r, AttachWindowOptions as s, ATTACH_FRAME_EVENT_KEY as t, ClearCookiesWire as u, FrameLocator as v, FrameWindowRefusedError as w, FrameWindowBlockedError as x, FrameMessageEvent as y, PermissionCategory as z };