@botiverse/porthole 0.14.17 → 0.14.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -24,7 +24,9 @@ export interface FileSetRef {
24
24
  * A notice (`porthole/navigating`, from the frame's window and content origin: the transport
25
25
  * takes nothing else) names a page and the version its files are. The leaving page's notice is
26
26
  * taken for the next load within `PAGE_OF_SET_MS`; the arriving page's (`arrived`) too, or for the
27
- * load it came after. A load no notice explained waits `LATE_NOTICE_MS`, holding the frame
27
+ * load it came after. A page whose document stayed (`same`, a navigation within it: WebKit fires
28
+ * the frame's load for one, P142) is taken for the load it came after, or for the next one within
29
+ * `LATE_NOTICE_MS` only. A load no notice explained waits `LATE_NOTICE_MS`, holding the frame
28
30
  * (`HELD_MOST` messages each way at most; past them, started again): nothing it says reaches the
29
31
  * display (no call is answered, no report taken), nothing is sent to it, and once the wait is
30
32
  * over without a notice for the
@@ -21,6 +21,7 @@ function noticeOf(raw, mounted) {
21
21
  return {
22
22
  url: typeof params.url === "string" ? params.url : "",
23
23
  arrived: params.arrived === true,
24
+ same: params.same === true,
24
25
  set: named === undefined
25
26
  ? "none"
26
27
  : isRecord(named) && named.id === mounted.id && named.version === mounted.version
@@ -37,7 +38,9 @@ const isHello = (raw) => isRecord(raw) && raw.method === MCP_APPS_METHODS.initia
37
38
  * A notice (`porthole/navigating`, from the frame's window and content origin: the transport
38
39
  * takes nothing else) names a page and the version its files are. The leaving page's notice is
39
40
  * taken for the next load within `PAGE_OF_SET_MS`; the arriving page's (`arrived`) too, or for the
40
- * load it came after. A load no notice explained waits `LATE_NOTICE_MS`, holding the frame
41
+ * load it came after. A page whose document stayed (`same`, a navigation within it: WebKit fires
42
+ * the frame's load for one, P142) is taken for the load it came after, or for the next one within
43
+ * `LATE_NOTICE_MS` only. A load no notice explained waits `LATE_NOTICE_MS`, holding the frame
41
44
  * (`HELD_MOST` messages each way at most; past them, started again): nothing it says reaches the
42
45
  * display (no call is answered, no report taken), nothing is sent to it, and once the wait is
43
46
  * over without a notice for the
@@ -105,15 +108,17 @@ export function pagesOfSet(options) {
105
108
  }
106
109
  const notice = noticeOf(message, set);
107
110
  if (notice !== null) {
108
- if (notice.set === "other" || (notice.arrived && notice.set !== "ok")) {
111
+ if (notice.set === "other" || ((notice.arrived || notice.same) && notice.set !== "ok")) {
109
112
  // Another version's page, or one that won't say which: never this display's.
110
113
  if (waiting > 0) {
111
114
  leave();
112
115
  }
113
116
  return;
114
117
  }
115
- if (waiting === 0 && notice.url === current) {
118
+ if (waiting === 0 && notice.url === current && !notice.same) {
116
119
  // A late copy for the page the frame is on (its leaving page's, or its own): no new page.
120
+ // (A document that stayed says so for each navigation within it, the same address again
121
+ // too: each may come with a load.)
117
122
  return;
118
123
  }
119
124
  if (waiting > 0) {
@@ -121,6 +126,15 @@ export function pagesOfSet(options) {
121
126
  taken(notice.url);
122
127
  }
123
128
  }
129
+ else if (notice.same) {
130
+ // A document that stayed is no page to come: its word is for a load at hand (WebKit fires
131
+ // it with the navigation within the document, before or after the frame's word, P142),
132
+ // and never shortens a page's word already given.
133
+ if (grantUntil <= Date.now()) {
134
+ grantUntil = Date.now() + LATE_NOTICE_MS;
135
+ grantFor = notice.url;
136
+ }
137
+ }
124
138
  else {
125
139
  // Either page's notice, for the next load within P084's ten seconds: the host hears the
126
140
  // frame's load only once its images and modules have loaded, which can be seconds after
@@ -79,9 +79,11 @@ export declare const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
79
79
  /**
80
80
  * Porthole's own notification from the shell (P084): a page that came with files is opening
81
81
  * another page of its set, `{ url }`, in the frame; and, as it arrives, the page a navigation
82
- * opened says so, `{ url, arrived: true }` (P098). The host takes the frame's next load (or the
83
- * load it came after, within `LATE_NOTICE_MS`) for that page rather than for content that left
84
- * (P031). The content's word: it only spares a restart.
82
+ * opened says so, `{ url, arrived: true }` (P098), with or without the Navigation API (P142); and a
83
+ * navigation within a page's document, `{ url, same: true }` (P142: WebKit fires the frame's load
84
+ * for one). The host takes the frame's next load (or the load it came after, within
85
+ * `LATE_NOTICE_MS`) for that page rather than for content that left (P031). The content's word: it
86
+ * only spares a restart.
85
87
  */
86
88
  export declare const NAVIGATING_METHOD = "porthole/navigating";
87
89
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
@@ -126,9 +126,11 @@ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
126
126
  /**
127
127
  * Porthole's own notification from the shell (P084): a page that came with files is opening
128
128
  * another page of its set, `{ url }`, in the frame; and, as it arrives, the page a navigation
129
- * opened says so, `{ url, arrived: true }` (P098). The host takes the frame's next load (or the
130
- * load it came after, within `LATE_NOTICE_MS`) for that page rather than for content that left
131
- * (P031). The content's word: it only spares a restart.
129
+ * opened says so, `{ url, arrived: true }` (P098), with or without the Navigation API (P142); and a
130
+ * navigation within a page's document, `{ url, same: true }` (P142: WebKit fires the frame's load
131
+ * for one). The host takes the frame's next load (or the load it came after, within
132
+ * `LATE_NOTICE_MS`) for that page rather than for content that left (P031). The content's word: it
133
+ * only spares a restart.
132
134
  */
133
135
  export const NAVIGATING_METHOD = "porthole/navigating";
134
136
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
@@ -249,6 +249,11 @@ export const shellAdapter = {
249
249
  calls.unwatch(params);
250
250
  return;
251
251
  case NAVIGATING_METHOD:
252
+ // A navigation within the page's document (P142): the page, its calls and what it
253
+ // follows stay.
254
+ if (params.same === true) {
255
+ return;
256
+ }
252
257
  // Another page of the set opens in the frame (P084): its next load is that page, which
253
258
  // follows nothing yet.
254
259
  forget();
@@ -318,10 +318,11 @@ export const SHELL_RUNTIME = String.raw `(() => {
318
318
  // A page of a set that a navigation opened (not its ticket's answer) says so as it arrives
319
319
  // (P098), below, once the shell can speak: the notice its last page sent as it left can reach
320
320
  // the host after this page's load, or never (Chromium forwards a cross-process message from a
321
- // task of the sending document's, which a navigation that commits first drops).
322
- let arrived = false;
321
+ // task of the sending document's, which a navigation that commits first drops). With or without
322
+ // the Navigation API (P142): where there is none, the leaving page sends nothing, and this is the
323
+ // page's only word.
324
+ const arrived = filesBase !== null && typeof plan.files.address !== "string";
323
325
  if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
324
- arrived = filesBase !== null && typeof plan.files.address !== "string";
325
326
  navigationApi.addEventListener("navigate", (event) => {
326
327
  const destination = applyOf(destinationOf, event, []);
327
328
  if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
@@ -1632,6 +1633,15 @@ export const SHELL_RUNTIME = String.raw `(() => {
1632
1633
  if (arrived) {
1633
1634
  notice(location.href, { arrived: true });
1634
1635
  }
1636
+ // A navigation within the document (a fragment, history between its entries) says the page
1637
+ // stayed (P142): WebKit fires the frame's load for one (measured, 18.2 and 26.6: a link to
1638
+ // #bottom, the first in a document), which the host would otherwise take for content that left.
1639
+ // Listened for now, before any content runs; each is the content's word, as every notice is.
1640
+ if (filesSet !== null && filesBase !== null) {
1641
+ const stayed = () => notice(location.href, { same: true });
1642
+ window.addEventListener("popstate", stayed, true);
1643
+ window.addEventListener("hashchange", stayed, true);
1644
+ }
1635
1645
  // A sealed files' address opens the page's files on its own for a while (P083): renewed before
1636
1646
  // it ends, the page moved to the new one in place (the same page, the same history entry). Its
1637
1647
  // modules keep the address they loaded from; the server serves their own loads till the session
package/docs/DECISIONS.md CHANGED
@@ -2703,7 +2703,7 @@ moved 56 minutes on, and the page goes on loading its files), on Chromium, WebKi
2703
2703
  **Revisit when** WebKit keeps partitioned cookies in frames (then the cookie, stable addresses and
2704
2704
  the shared cache), or hosts need a version's files cached across sessions (a seal per day).
2705
2705
 
2706
- ## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted; amended by P098
2706
+ ## P084 · 2026-10-18 · A served page with files opens its set's other pages in its frame · Accepted; amended by P098, P142
2707
2707
 
2708
2708
  **Decision.** Amends P079 (no navigation to another document) and P031 (a navigated frame is
2709
2709
  started again) for served pages with files. The shell's plan names the version's files' address
@@ -2738,7 +2738,7 @@ subscriptions a page left keep running until the display ends.
2738
2738
  artifact's display, not one sent eleven seconds before the load, and never for a widget's).
2739
2739
  **Revisit when** hosts annotate multi-page artifacts (give the marks to each page), or an engine
2740
2740
  Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
2741
- the display).
2741
+ the display; since P142 they don't: the arriving page's word is sent without the API).
2742
2742
 
2743
2743
  ## P085 · 2026-10-18 · The capability runtime: one global, `porthole.use(name)`, under a contract pinned per artifact · Accepted; amended by P091, P139
2744
2744
 
@@ -4061,7 +4061,7 @@ origin check stays, for frames on one host page); when an engine stops sending `
4061
4061
  metadata where this relies on them; or when a previewed app needs a write from another site (an
4062
4062
  opt-in per display, with its test).
4063
4063
 
4064
- ## P098 · 2026-10-19 · A set's page is taken as one when its notice is late or lost; tests that measure, not wait · Accepted
4064
+ ## P098 · 2026-10-19 · A set's page is taken as one when its notice is late or lost; tests that measure, not wait · Accepted; amended by P142
4065
4065
 
4066
4066
  The 2026-10-19 audit's flaky tests (baseline 264b12fa), which a release that waits for all of CI
4067
4067
  (P097) can no longer shrug off. Amends P084 (the notice) and P025 (how the suite knows which
@@ -4084,7 +4084,8 @@ browsers keep a framed cookie).
4084
4084
  the access the page is served for; not secret);
4085
4085
  - the shell of a page a navigation opened (a page of files that is not its ticket's answer)
4086
4086
  says `porthole/navigating` with `arrived: true` as it starts. Set inside the guard's own
4087
- block, so `navigate-guard` (the guard taken out) removes it with every other notice;
4087
+ block, so `navigate-guard` (the guard taken out) removes it with every other notice (since
4088
+ P142 set outside it, with or without the Navigation API; `navigate-guard` still removes it);
4088
4089
  - which loads are the set's own pages is decided by `pagesOfSet` (`host/pages-of-set.ts`) on
4089
4090
  the frame's surface, before anything the frame says reaches the display. The leaving page's
4090
4091
  notice is taken for the next load within ten seconds, as before; the arriving page's too (the
@@ -8765,3 +8766,96 @@ control, run as mutations.
8765
8766
  **Revisit when** an outer page needs to speak to a frame (then it is a host, and needs
8766
8767
  `appOrigins`), browsers give a policy for the parent alone, or a host wants an outer page to frame
8767
8768
  content without its own page between them.
8769
+
8770
+ ## P142 · 2026-11-09 · A set's pages without the Navigation API, and a page that stays at a link within it · Accepted
8771
+
8772
+ From Raft (task #proj-workspace:#251, InNOut): on staging, in a multi-page served artifact, WebKit
8773
+ 18.2 (Playwright 1.49.1, Safari 18's engine, no Navigation API) started the display again at its
8774
+ entry on every link to another page of the set, and on a link to `#bottom` in the same page. Then
8775
+ on WebKit 26.6 (Playwright 1.63, with the API): pages fine, `#bottom` started it again about 2.5 s
8776
+ after the click. Chromium: both fine. Amends P084 and P098 (its "Revisit when": an engine without
8777
+ the Navigation API).
8778
+
8779
+ **Measured** (the leak harness; WebKit r2104 = 18.2 run with Playwright 1.49.1 and Ubuntu 24.04's
8780
+ libraries, WebKit 26.6, Chromium and Firefox 155 with Playwright 1.63; "without the API" is the
8781
+ frame with `navigation` and every `Navigat*` interface deleted before the shell runs, and WebKit
8782
+ 18.2 itself):
8783
+ - *A link to another page, without the API.* The shell said nothing. The leaving page's notice
8784
+ comes from the guard's `navigate` listener (P084), and the arriving page's `arrived: true` was
8785
+ set inside the guard's own block (P098, so `navigate-guard` would take it out). Neither exists
8786
+ without the API. The frame's click handler still opens the page (`location.assign`). The new
8787
+ page's load reached `pagesOfSet` with no notice, and its `ui/initialize` ended the wait at once
8788
+ ("a hello before any notice"): started again at once (failed on Chromium without the API and on
8789
+ WebKit 18.2).
8790
+ - *A link to `#bottom`.* Not a navigate event the shell announces: the guard passes a
8791
+ same-document navigation without a word, and the frame's click handler leaves a `#` link to the
8792
+ browser. Not the shell treating `hashchange` as navigation: nothing listened for it. It is a
8793
+ `load`. **WebKit fires the `<iframe>` element's `load` for the first navigation within the
8794
+ frame's document**: a listener on the host page's iframe saw it, no request reached the server,
8795
+ and the document stayed (its globals, its scroll, `location.hash`). On 18.2 the load comes before
8796
+ the frame's `popstate` and `hashchange`; on 26.6 after them. Chromium and Firefox fire none. The
8797
+ web platform takes any load after the first as the content navigating away (P031), and
8798
+ `pagesOfSet` waited `LATE_NOTICE_MS` (2 s) for a notice. None came, so the display started
8799
+ again: the 2.5 s InNOut saw. With the API or without it.
8800
+
8801
+ **Decision.**
8802
+ 1. **A set's page that a navigation opened says `arrived: true` as it starts, with or without the
8803
+ Navigation API.** `arrived` is set outside the guard's block, from the plan alone (files, and
8804
+ no ticket's address). Without the API it is the page's only word, and P098 already takes it on
8805
+ either side of the load. No click fallback for the leaving notice: P098 takes the arriving
8806
+ page's word without one, and a click handler would cover links only, not `location`. So
8807
+ `arrived` alone covers it, and the tests show it does. `navigate-guard` (P079's control) also
8808
+ takes `arrived` out, so it still takes out every notice of a set's pages.
8809
+ 2. **A navigation within a page's document says the page stayed**: `porthole/navigating
8810
+ { url, same: true, set }` on each `popstate` and `hashchange` (window listeners the shell adds
8811
+ before content runs), in a set's page (files and their version), with or without the API. It is
8812
+ never a page change. `pagesOfSet` takes it for the load it came after, or for the next one within
8813
+ `LATE_NOTICE_MS` only (not P084's ten seconds: it is no page to come). It never shortens a
8814
+ page's notice already given, and is taken however often the same address comes again. Like
8815
+ `arrived`, it must name the mounted version: another version's, or none, ends a wait at once,
8816
+ started again. The shell adapter forgets nothing for it (the page's watches and subscriptions go
8817
+ on). A display whose pages never come with files is as before: every load after the first starts
8818
+ it again at once.
8819
+
8820
+ **What stays the accepted limit** (P079, P099, unchanged). Without the Navigation API the guard
8821
+ gets no events. A served frame can navigate itself to another content origin (`frame-src` lets it
8822
+ in), and a page on a tab can navigate itself away, or to a `blob:` document of its own. Every
8823
+ other navigation without the API is as before. Another path of its origin, a file that isn't a
8824
+ page, an outside site (`frame-src` stops it): the display starts again (or, on Firefox, an outside
8825
+ site leaves the document as it was). A single-document served artifact (no files, so no version in
8826
+ its notices), and every display that isn't an artifact with files, still starts again at a load
8827
+ after the first. On WebKit that includes the first link within the page. A frame can't tell the host
8828
+ a load is no new document without a version to name, and none of those waits for a notice
8829
+ (P031).
8830
+
8831
+ **Threat (PRINCIPLE 1): nothing loosened.** No CSP, sandbox, guard rule, gate or origin changed;
8832
+ the guard stops what it stopped, where it has events. The host takes a notice as before: only for
8833
+ a display whose pages may come with files, from the frame's window and origin, naming the mounted
8834
+ version, within its window. Both notices are the content's word. Content could always send
8835
+ `porthole/navigating` itself (P084: it only spares a restart, which P031 says is no wall).
8836
+ `arrived` without the API, or `same` from a listener, gives it nothing it lacked. A `same`
8837
+ notice's grant is shorter than the one content could already ask for. The wall against a
8838
+ navigated document running is the embedding page's `frame-src`, as P031 has it.
8839
+
8840
+ **Tested.** `leak/served/files.spec.ts`:
8841
+ - with the API: a link down the entry page and down a page a link opened. The page scrolls, the
8842
+ document stays, the display goes on, the frame announces no page change (only `same`), and the
8843
+ host blocks nothing.
8844
+ - without the API: a link to another page and back (one outcome, nothing blocked), and the link
8845
+ down the page as above.
8846
+ - the negative controls: a file that isn't a page and another path of the origin still start the
8847
+ display again at its entry, and an outside site hears nothing.
8848
+
8849
+ All pass on Chromium, WebKit 26.6 and Firefox 155, and on WebKit 18.2 itself. Before the fix, the
8850
+ page link failed on Chromium without the API and on WebKit 18.2, and the link down the page failed
8851
+ on WebKit 18.2 and 26.6 (started again). `test/pages-of-set.test.ts`: `same` before or after its
8852
+ load; again at the same address; no grant past `LATE_NOTICE_MS`; a page's grant kept; another
8853
+ version, or none, ends the wait; nothing for displays without files. `test/runtime-review.test.ts`:
8854
+ a `same` notice ends no watch (it failed before). Controls: `same-document-notice` (the listeners
8855
+ out) fails both link-down cases on all three engines (the frame says nothing; on WebKit the display
8856
+ starts again too). `navigate-guard` now also fails the page link without the API and both link-down
8857
+ cases, whose second page is opened by a link.
8858
+
8859
+ **Revisit when** an engine stops firing a frame's load for a navigation within its document
8860
+ (the `same` notice then has no load to explain), single-document served artifacts need it (give
8861
+ their notices the version), or hosts need Safari before 26 on a tab (P099's limit stands).
package/docs/DESIGN.md CHANGED
@@ -1590,7 +1590,8 @@ control the tables above name to the registry):
1590
1590
  | `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved`, `every attached mark's place in the document comes with the scroll it was read at, offscreen ones too, and the followed mark's as the document scrolls (P132)`, `a selection's and a mark's last line come in the document's coordinates with the scroll, offscreen ones too; rect stays clamped (P133)` | — | — |
1591
1591
  | `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host` | — |
1592
1592
  | `url-permissions` | `served/permissions.spec.ts` | `a url-mode frame gets no clipboard writes or full screen unless the host delegates them` | — | — |
1593
- | `navigate-guard` | `served/live.spec.ts`, `served/files.spec.ts`, `served/served.spec.ts`, `served/tab.spec.ts` | `served.domain.self-navigation`, `served.domain.tab-navigation`, `served.domain.tab-links`, `can't navigate itself away (location): to a site, or to another content origin`, `can't navigate itself away (replace): to a site, or to another content origin`, `can't navigate itself away (open-self): to a site, or to another content origin`, `can't navigate itself away (navigation-api): to a site, or to another content origin`, `a link to another page of the set opens it in the frame; the display goes on`, `a link to another page of the set opens it in the frame when the leaving page's notice is dropped (P098)`, `a link to another page of the set opens it in the frame when the leaving page's notice is late (P098)`, `a page opens nothing else: not a file that isn't a page, not another path of its origin`, `no report, content error or blocked navigation names the frame's sealed address (P083)` | — | — |
1593
+ | `navigate-guard` | `served/live.spec.ts`, `served/files.spec.ts`, `served/served.spec.ts`, `served/tab.spec.ts` | `served.domain.self-navigation`, `served.domain.tab-navigation`, `served.domain.tab-links`, `can't navigate itself away (location): to a site, or to another content origin`, `can't navigate itself away (replace): to a site, or to another content origin`, `can't navigate itself away (open-self): to a site, or to another content origin`, `can't navigate itself away (navigation-api): to a site, or to another content origin`, `a link to another page of the set opens it in the frame; the display goes on`, `a link to another page of the set opens it in the frame when the leaving page's notice is dropped (P098)`, `a link to another page of the set opens it in the frame when the leaving page's notice is late (P098)`, `without the Navigation API, a link to another page of the set opens it in the frame; the display goes on`, `a link down the page scrolls it; the document stays, and so does the display`, `without the Navigation API, a link down the page scrolls it; the document stays, and so does the display`, `a page opens nothing else: not a file that isn't a page, not another path of its origin`, `no report, content error or blocked navigation names the frame's sealed address (P083)` | — | — |
1594
+ | `same-document-notice` | `served/files.spec.ts` | `a link down the page scrolls it; the document stays, and so does the display`, `without the Navigation API, a link down the page scrolls it; the document stays, and so does the display` | — | — |
1594
1595
  | `tab-sandbox` | `served/tab.spec.ts` | `served.domain.tab-escapes`, `served.domain.tab-opener`, `a file set's page on a tab of its own opens its own pages, and no window, link in a new window or download`, `a frame's sealed address opened on a tab of its own is sandboxed as its frame is` | — | — |
1595
1596
  | `window-open` | `served/tab.spec.ts` | nothing | — | the CSP's sandbox stops a window first (`tab-sandbox,window-open`) |
1596
1597
  | `tab-sandbox,window-open` | `served/tab.spec.ts` | `served.domain.tab-escapes`, `served.domain.tab-opener`, `a file set's page on a tab of its own opens its own pages, and no window, link in a new window or download`, `a frame's sealed address opened on a tab of its own is sandboxed as its frame is`, `served.domain.tab-window-open` | — | — |
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
5
5
  guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
6
  [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
7
 
8
- **Status.** This describes Porthole 0.14.17 (2026-11-09). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.14.18 (2026-11-09). A review on 2026-10-19 found gaps, and every decision it led to
9
9
  has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
10
  and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
11
  annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
@@ -47,7 +47,10 @@ host that follows none drops `selectionTracked` unread (§7). 0.14.17: P141 lets
47
47
  origins of an outer page that frames its app (`framedBy`): each may be an ancestor of every frame,
48
48
  above the host's own page, so it is in every `frame-ancestors`, and nowhere else; it is never a
49
49
  host a frame hears or tells, and a page's `*` fallback is held to a parent named as a host origin
50
- (§6 "What every host must do", S3).
50
+ (§6 "What every host must do", S3). 0.14.18: P142 keeps a set's pages and links within a page from
51
+ starting the display again where there is no Navigation API, and where WebKit fires a frame's load
52
+ for a link within its document: the arriving page's notice is sent without the API, and a page
53
+ says it stayed; no wall moves, and the limit without the API is P079's, unchanged.
51
54
 
52
55
  ## 1. Two layers
53
56
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.14.17",
3
+ "version": "0.14.18",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -26,6 +26,8 @@ export interface FileSetRef {
26
26
  interface Notice {
27
27
  readonly url: string;
28
28
  readonly arrived: boolean;
29
+ /** The page is where it was: a navigation within its document (P142). */
30
+ readonly same: boolean;
29
31
  /** Whether it names the mounted version (`ok`), another (`other`), or none (a shell before P098). */
30
32
  readonly set: "ok" | "other" | "none";
31
33
  }
@@ -42,6 +44,7 @@ function noticeOf(raw: unknown, mounted: FileSetRef): Notice | null {
42
44
  return {
43
45
  url: typeof params.url === "string" ? params.url : "",
44
46
  arrived: params.arrived === true,
47
+ same: params.same === true,
45
48
  set:
46
49
  named === undefined
47
50
  ? "none"
@@ -62,7 +65,9 @@ const isHello = (raw: unknown): boolean =>
62
65
  * A notice (`porthole/navigating`, from the frame's window and content origin: the transport
63
66
  * takes nothing else) names a page and the version its files are. The leaving page's notice is
64
67
  * taken for the next load within `PAGE_OF_SET_MS`; the arriving page's (`arrived`) too, or for the
65
- * load it came after. A load no notice explained waits `LATE_NOTICE_MS`, holding the frame
68
+ * load it came after. A page whose document stayed (`same`, a navigation within it: WebKit fires
69
+ * the frame's load for one, P142) is taken for the load it came after, or for the next one within
70
+ * `LATE_NOTICE_MS` only. A load no notice explained waits `LATE_NOTICE_MS`, holding the frame
66
71
  * (`HELD_MOST` messages each way at most; past them, started again): nothing it says reaches the
67
72
  * display (no call is answered, no report taken), nothing is sent to it, and once the wait is
68
73
  * over without a notice for the
@@ -137,21 +142,31 @@ export function pagesOfSet(options: {
137
142
  }
138
143
  const notice = noticeOf(message, set);
139
144
  if (notice !== null) {
140
- if (notice.set === "other" || (notice.arrived && notice.set !== "ok")) {
145
+ if (notice.set === "other" || ((notice.arrived || notice.same) && notice.set !== "ok")) {
141
146
  // Another version's page, or one that won't say which: never this display's.
142
147
  if (waiting > 0) {
143
148
  leave();
144
149
  }
145
150
  return;
146
151
  }
147
- if (waiting === 0 && notice.url === current) {
152
+ if (waiting === 0 && notice.url === current && !notice.same) {
148
153
  // A late copy for the page the frame is on (its leaving page's, or its own): no new page.
154
+ // (A document that stayed says so for each navigation within it, the same address again
155
+ // too: each may come with a load.)
149
156
  return;
150
157
  }
151
158
  if (waiting > 0) {
152
159
  if (notice.set === "ok") {
153
160
  taken(notice.url);
154
161
  }
162
+ } else if (notice.same) {
163
+ // A document that stayed is no page to come: its word is for a load at hand (WebKit fires
164
+ // it with the navigation within the document, before or after the frame's word, P142),
165
+ // and never shortens a page's word already given.
166
+ if (grantUntil <= Date.now()) {
167
+ grantUntil = Date.now() + LATE_NOTICE_MS;
168
+ grantFor = notice.url;
169
+ }
155
170
  } else {
156
171
  // Either page's notice, for the next load within P084's ten seconds: the host hears the
157
172
  // frame's load only once its images and modules have loaded, which can be seconds after
@@ -150,9 +150,11 @@ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
150
150
  /**
151
151
  * Porthole's own notification from the shell (P084): a page that came with files is opening
152
152
  * another page of its set, `{ url }`, in the frame; and, as it arrives, the page a navigation
153
- * opened says so, `{ url, arrived: true }` (P098). The host takes the frame's next load (or the
154
- * load it came after, within `LATE_NOTICE_MS`) for that page rather than for content that left
155
- * (P031). The content's word: it only spares a restart.
153
+ * opened says so, `{ url, arrived: true }` (P098), with or without the Navigation API (P142); and a
154
+ * navigation within a page's document, `{ url, same: true }` (P142: WebKit fires the frame's load
155
+ * for one). The host takes the frame's next load (or the load it came after, within
156
+ * `LATE_NOTICE_MS`) for that page rather than for content that left (P031). The content's word: it
157
+ * only spares a restart.
156
158
  */
157
159
  export const NAVIGATING_METHOD = "porthole/navigating";
158
160
 
@@ -301,6 +301,11 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
301
301
  calls.unwatch(params);
302
302
  return;
303
303
  case NAVIGATING_METHOD:
304
+ // A navigation within the page's document (P142): the page, its calls and what it
305
+ // follows stay.
306
+ if (params.same === true) {
307
+ return;
308
+ }
304
309
  // Another page of the set opens in the frame (P084): its next load is that page, which
305
310
  // follows nothing yet.
306
311
  forget();
@@ -323,10 +323,11 @@ export const SHELL_RUNTIME = String.raw`(() => {
323
323
  // A page of a set that a navigation opened (not its ticket's answer) says so as it arrives
324
324
  // (P098), below, once the shell can speak: the notice its last page sent as it left can reach
325
325
  // the host after this page's load, or never (Chromium forwards a cross-process message from a
326
- // task of the sending document's, which a navigation that commits first drops).
327
- let arrived = false;
326
+ // task of the sending document's, which a navigation that commits first drops). With or without
327
+ // the Navigation API (P142): where there is none, the leaving page sends nothing, and this is the
328
+ // page's only word.
329
+ const arrived = filesBase !== null && typeof plan.files.address !== "string";
328
330
  if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
329
- arrived = filesBase !== null && typeof plan.files.address !== "string";
330
331
  navigationApi.addEventListener("navigate", (event) => {
331
332
  const destination = applyOf(destinationOf, event, []);
332
333
  if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
@@ -1637,6 +1638,15 @@ export const SHELL_RUNTIME = String.raw`(() => {
1637
1638
  if (arrived) {
1638
1639
  notice(location.href, { arrived: true });
1639
1640
  }
1641
+ // A navigation within the document (a fragment, history between its entries) says the page
1642
+ // stayed (P142): WebKit fires the frame's load for one (measured, 18.2 and 26.6: a link to
1643
+ // #bottom, the first in a document), which the host would otherwise take for content that left.
1644
+ // Listened for now, before any content runs; each is the content's word, as every notice is.
1645
+ if (filesSet !== null && filesBase !== null) {
1646
+ const stayed = () => notice(location.href, { same: true });
1647
+ window.addEventListener("popstate", stayed, true);
1648
+ window.addEventListener("hashchange", stayed, true);
1649
+ }
1640
1650
  // A sealed files' address opens the page's files on its own for a while (P083): renewed before
1641
1651
  // it ends, the page moved to the new one in place (the same page, the same history entry). Its
1642
1652
  // modules keep the address they loaded from; the server serves their own loads till the session