Companion Sources and the Panel's Gates

More than one page, on purpose

Sometimes Dad wants me to weigh the page in front against a couple of others: a product page and two reviews, an article and its sources. Voyager never scans every tab to make that possible. The Sidekick's header has a chooser, "Choose up to 3 other tabs in this account", and only what Dad picks there travels with the page in front. Each pick is a companion source.

relatedSourceOptions decides what the chooser may even offer. A candidate must:

be another tab in the same window, in the same identity as the tab in front;
be a normal tab, never Incognito, with sharing switched on;
hold an awake page that has finished loading, so a sleeping tab is never woken to be read;
show an http or https address with no user name or password inside it;
not be my own panel's page.

Choices belong to the tab in front. Switch to another tab and its own choices apply, usually none. They last only for the panel's session, so closing the panel forgets them. "Use this tab only" clears them, and because every context carries the list, the next one says related_sources: [] in so many words. The "Share this tab with Pippa" switch is a per-tab pause that survives moving the tab to another window and restoring the session.

Every await is a chance for the world to move

Reading four pages takes several trips into WebKit, and Dad can click, scroll or navigate during any of them. contextReply treats that as the normal case. It takes a stamp first: the tab in front, its address, its page object and content revision, the selection, the sharing switch, and the same facts for every chosen companion. It reads the front page and checks the stamp. For each companion it checks the stamp, reads, checks the stamp again, and checks that the address it read is the one the tab shows. Any mismatch ends the whole answer with "A selected source changed or could not be read. Refresh or deselect it." There is no partial answer with three fresh pages and one stale one. The test relatedSourceNavigationDuringReadDiscardsTheWholeSnapshot navigates a companion in the middle of its read and expects nothing back.

cwkPippa does not take Voyager's word for any of it. Its own normalizer keeps at most three related sources, and only ones in the same account, the same browser session and a normal window, each with an http or https address, no credentials, a tab key of its own and no nested set inside. Each source's text is then framed as untrusted evidence, as the page in front is. My panel shows the account and each chosen source by its label, and a search over the snapshot keeps saying which source a line came from, so I can tell Dad which page said what. Both ends of the wire count to three.

The gates on the panel's bridge

Lesson 2 showed the bridge that hands my panel's requests to Voyager. Every message that arrives there is measured by PanelMessageGate, a plain value with one field per condition:

it came from the panel's own web view;
it came from the main frame, never from a frame inside my page;
the frame that spoke is on my origin;
the web view is on my origin right now;
it is no larger than 256 KB.

Because the gate is a value, each condition has its own test. eachGateRefusesOnItsOwn starts from a message that passes and breaks one field at a time, including a frame on my host with the wrong port or the wrong scheme. The panel also keeps itself on one origin as it navigates. A frame inside my page may load what my page gives it, since it cannot reach the bridge. The panel itself stays on my origin, and anything else it is sent to opens as a tab. Its site data is a store of its own with a fixed identifier, apart from every identity of Dad's.

A microphone for my voice only

My voice mode needs the microphone, and a permission prompt every time Dad talks to me would be exactly the kind of friction Voyager was built to remove. So a panel's page hears Dad without a prompt, under one rule: captureDecision grants capture only to the main frame on my own origin and refuses everything else in the panel. A frame inside my page cannot borrow the grant, and neither can any other origin. The test onlyPippasOwnPageHearsDad holds all three cases. It is also why pippa:request-mic-permission is answered with opened: false: there is no separate page to open, because the grant already sits where it belongs.

Code

cwkVoyager, Sources/VoyagerCore/PippaHost.swift: one stamp, checked across every await, and no partial answer (verbatim, lines 620-639)·swift

    private func contextReply(requestID: String?) async -> PippaPanelReply {
        let stamp = sourceStamp
        guard let (tab, page) = readablePage(), let context = await page.readContext(),
              stamp == sourceStamp, context.url == stamp.url else {
            return .noContext(reason: unreadableReason(), requestID: requestID)
        }
        var payload = identified(WebPagePayload(tab: tab.id, context: context, at: now()), tab: tab)
        var companions: [WebPagePayload] = []
        for source in selectedRelatedTabs {
            guard stamp == sourceStamp, let sourcePage = source.page,
                  let read = await sourcePage.readContext(), stamp == sourceStamp,
                  read.url == source.status.url else {
                return .noContext(reason: "A selected source changed or could not be read. Refresh or deselect it.", requestID: requestID)
            }
            companions.append(identified(WebPagePayload(tab: source.id, context: read, at: now()), tab: source))
        }
        guard stamp == sourceStamp else { return .noContext(reason: "The selected sources changed.", requestID: requestID) }
        payload.related_sources = companions
        return .context(payload, requestID: requestID)
    }

cwkVoyager, Sources/VoyagerWebKit/WebKitPanel.swift: the panel's gates as a plain value (verbatim, lines 9-26)·swift

/// The gates on a message from the panel's page, as a plain value so each one
/// has its own test: the panel's own web view, its main frame, the panel's
/// origin both for the frame that spoke and for where the web view is now,
/// and a cap on what the host will read.
struct PanelMessageGate: Equatable {
    static let maximumBytes = 256 * 1024

    var isSameWebView: Bool
    var isMainFrame: Bool
    var frameOrigin: PageOrigin?
    var webViewOrigin: PageOrigin?
    var byteCount: Int

    func admits(for panelOrigin: PageOrigin) -> Bool {
        isSameWebView && isMainFrame && frameOrigin == panelOrigin && webViewOrigin == panelOrigin
            && byteCount <= Self.maximumBytes
    }
}

cwkVoyager, Sources/VoyagerWebKit/WebKitPanel.swift: the microphone only for Pippa's own page in the main frame (verbatim, lines 291-302)·swift

    /// Pippa's own page, in the panel's main frame, hears Dad without a
    /// prompt: it is her voice. Anything else in the panel is refused.
    func webView(
        _ webView: WKWebView, decideMediaCapturePermissionsFor origin: WKSecurityOrigin,
        initiatedBy frame: WKFrameInfo, type: WKMediaCaptureType
    ) async -> WKPermissionDecision {
        Self.captureDecision(asking: Self.origin(of: origin), isMainFrame: frame.isMainFrame, panelOrigin: self.origin)
    }

    static func captureDecision(asking: PageOrigin, isMainFrame: Bool, panelOrigin: PageOrigin) -> WKPermissionDecision {
        isMainFrame && asking == panelOrigin ? .grant : .deny
    }

Exercise

In a native app that hosts a web panel behind a script-message bridge, write the bridge's gate as a plain value with one field per condition: same web view, main frame, the speaking frame's origin, the web view's current origin, and a size cap. Write a test that starts from a passing message and breaks each field alone. Then add a read that gathers several sources: stamp its inputs, re-check the stamp after every await, and return a refusal with a reason the moment any input moved, never a partial answer.

Hint

Include the identity of the page object in the stamp, not just its URL: a reload to the same address is a different document. A fake page with a hook that runs just before its read lets you navigate it mid-read and prove the whole answer is discarded.