Proposal: `browser.documents` namespace

[carlosjeurissen]

Intro

Now documentIds are getting common in browsers and APIs like tabGroups are getting their own namespace, it seems odd for documents not to have the same. Turns out by moving many APIs to browser.documents you end up with much more semantic and elegant APIs. This issue explores how such namespace could look like.

Design

namespace documents {
    // replacing `browser.webNavigation.getFrame`
    function get(documentId: string): Promise<Document>;

    // see https://github.com/w3c/webextensions/issues/77
    function sendMessage(
          documentId: string,
          message: any,
        ): Promise<any>;
    };

    // replacing https://github.com/w3c/webextensions/pull/586
    // replacing webNavigation.getAllFrames()
    function query(queryInfo: {
      documentIds?: string[];
      tabIds?: number[];
      frameIds?: number[];
      windowIds?: number[];
      url?: string;
      documentLifecycle?: DocumentLifecycle;
      status?: DocumentStatus;
      frameType?: FrameType;
    }): Promise<Document[]>;

    // replacing runtime.getDocumentId()
    // see https://github.com/w3c/webextensions/issues/800
    function getId(context: Window | HTMLIFrameElement): Promise<string>;

    // focus management see https://github.com/w3c/webextensions/pull/817
    function focus(documentId: string): Promise<string>;
}

In addition, lifecycle events from webNavigation can be moved to browser.documents. With the exception of onTabReplaced, which seems to sit best under browser.tabs. These events would only be available with the webNavigation API. Effectively deprecating the webNavigation namespace (but not the webNavigation permission).

As for permissions, it seems for many of these APIs, the webNavigation permission is too dramatic, with the exception of the lifecycle events and potentially parts of the browser.documents.query method.

[tophf]

document and DOM elements of a web page are cross-origin to the extension's process and can't be returned by or sent to the API. The only case where it could work is inside the content script and only for the same-origin documents.

A window mini-wrapper that's already exposed to cross-origin frames by the web platform, would obviously work in an extension process's tabs/frames but not in the service worker in chromium's MV3. However this mini-wrapper doesn't allow reading anything meaningful anyway, so it doesn't seem useful either.

Regarding get/focus/sendMessage, they assume that documentId is globally unique, but that's not so in chromium's implementation judging by the fact that documentId also requires tabId. I wonder if this is something they can change...

IIRC chromium wants the API to be minimalistic, so we can use the existing chrome.tabs.sendMessage with a documentId. After chrome.tabs.query gets documentId support we'll be able to use it to get a tab id and then focus/communicate/close it.

As for chrome.webNavigation.getFrame, the problem is that it adds a permission warning, which is unnecessary in case the extension already has host permissions both for the tab's host and for the iframe's host. Maybe an acceptable solution would be to add frames object to the Tab object returned from chrmoe.tabs.query e.g. a dictionary keyed on documentId an array with values like {url: '.....', frameId: 123, documentId: 'foo'}

[carlosjeurissen]

document and DOM elements of a web page are cross-origin to the extension's process and can't be returned by or sent to the API. The only case where it could work is inside the content script and only for the same-origin documents.

Not proposing to return an actual DOM or window object. But an object which states generic info on a specific document like the id, frameId, tabId, windowId which can be used in other APIs.

Regarding get/focus/sendMessage, they assume that documentId is globally unique, but that's not so in chromium's implementation judging by the fact that documentId also requires tabId. I wonder if this is something they can change...

As far as I know documentIds are unique in the whole browser. @oliverdunk can you confirm?

IIRC chromium wants the API to be minimalistic, so we can use the existing chrome.tabs.sendMessage with a documentId. After chrome.tabs.query gets documentId support we'll be able to use it to get a tab id and then focus/communicate/close it.

There are cases in which you want to use sendMessage without documents being in an actual tab.

As for chrome.webNavigation.getFrame, the problem is that it adds a permission warning, which is unnecessary in case the extension already has host permissions both for the tab's host and for the iframe's host. Maybe an acceptable solution would be to add frames object to the Tab object returned from chrmoe.tabs.query e.g. a dictionary keyed on documentId an array with values like {url: '.....', frameId: 123, documentId: 'foo'}

Active discussion in the tabs.query documentId support is if documents not being part of a specific tab should be returned. Having these return with tabs.query seems very counter intuitive.

@Rob--W I don't think contexts requires a specific separate namespace. The proposal is to actually resolve the webNavigation namespace, so I do not think the issue is for too many namespaces to exist side by side. The point is to actually not pollute other namespaces like the tabs and runtime namespaces with methods which don't necessary belong there (like getFrameId, getDocumentId, and others). In similar fashion as the scripting namespace has been eating some of the methods away from the tabs namespace.

[Rob--W]

During the meeting we agreed to close the issue. @carlosjeurissen I see that you added comments thereafter, if there is still anything left unresolved to discuss, please let me know.