@botiverse/porthole 0.14.15 → 0.14.17
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.
- package/CHANGELOG.md +50 -0
- package/dist/annotate/types.d.ts +10 -1
- package/dist/annotate/validate.d.ts +9 -2
- package/dist/annotate/validate.js +9 -2
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +11 -8
- package/dist/host/types.d.ts +13 -6
- package/dist/isolation/served.d.ts +8 -0
- package/dist/isolation/served.js +16 -0
- package/dist/react/frame.d.ts +9 -1
- package/dist/react/frame.js +23 -3
- package/dist/server/host.d.ts +14 -1
- package/dist/server/host.js +8 -3
- package/dist/server/nested.d.ts +5 -4
- package/dist/server/nested.js +8 -6
- package/dist/server/pages.d.ts +16 -2
- package/dist/server/pages.js +51 -16
- package/dist/server/server.js +26 -2
- package/dist/server/types.d.ts +8 -0
- package/dist/shell/annotate.d.ts +5 -3
- package/dist/shell/annotate.js +36 -16
- package/dist/shell/frame.d.ts +6 -0
- package/dist/shell/frame.js +16 -3
- package/dist/shell/runtime.d.ts +10 -0
- package/dist/shell/runtime.js +72 -26
- package/docs/ADOPTING.md +40 -22
- package/docs/DECISIONS.md +318 -3
- package/docs/DESIGN.md +19 -10
- package/docs/THREAT_MODEL.md +39 -7
- package/package.json +1 -1
- package/src/annotate/types.ts +10 -1
- package/src/annotate/validate.ts +15 -3
- package/src/host/create-host.ts +13 -14
- package/src/host/types.ts +13 -6
- package/src/isolation/served.ts +21 -0
- package/src/react/frame.tsx +36 -5
- package/src/server/host.ts +22 -4
- package/src/server/nested.ts +13 -5
- package/src/server/pages.ts +72 -18
- package/src/server/server.ts +32 -1
- package/src/server/types.ts +8 -0
- package/src/shell/annotate.ts +36 -16
- package/src/shell/frame.ts +22 -3
- package/src/shell/runtime.ts +73 -26
package/docs/DECISIONS.md
CHANGED
|
@@ -2740,7 +2740,7 @@ artifact's display, not one sent eleven seconds before the load, and never for a
|
|
|
2740
2740
|
Porthole supports lacks the Navigation API (then `frame-src` is the wall, and a set's pages restart
|
|
2741
2741
|
the display).
|
|
2742
2742
|
|
|
2743
|
-
## P085 · 2026-10-18 · The capability runtime: one global, `porthole.use(name)`, under a contract pinned per artifact · Accepted; amended by P091
|
|
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
|
|
|
2745
2745
|
Task #124 (contract §7): a page published as an artifact is an app, and an app needs more of its host
|
|
2746
2746
|
than 0.6's host functions: who is viewing, its comments, a new version of itself, an asset library,
|
|
@@ -4376,7 +4376,7 @@ aren't offered.
|
|
|
4376
4376
|
the issue); a host needs image blocks (show them, then offer `image`); or a host's composer is the
|
|
4377
4377
|
common surface (the React binding could offer a chip there).
|
|
4378
4378
|
|
|
4379
|
-
## P099 · 2026-10-19 · A served page carries its frame's sandbox in its own CSP; on a tab the shell opens no window · Accepted
|
|
4379
|
+
## P099 · 2026-10-19 · A served page carries its frame's sandbox in its own CSP; on a tab the shell opens no window · Accepted; amended by P139
|
|
4380
4380
|
|
|
4381
4381
|
The 2026-10-19 review of value and scenarios, S4 and its first P0 (baseline 264b12f): a served
|
|
4382
4382
|
page opened on a tab of its own (a public link, "open in a new tab", a bookmark, a frame's address
|
|
@@ -8288,7 +8288,7 @@ of the host's, like the rest of the exception. No code changes.
|
|
|
8288
8288
|
seen moving on inside 100 ms; a platform gives frames a clock that is shared and monotonic; or the
|
|
8289
8289
|
parked word's own age should count.
|
|
8290
8290
|
|
|
8291
|
-
## P138 · 2026-11-08 · The selection followed: a composer stays beside what it is for, and what was picked stays lit · Accepted
|
|
8291
|
+
## P138 · 2026-11-08 · The selection followed: a composer stays beside what it is for, and what was picked stays lit · Accepted; amended by P140
|
|
8292
8292
|
|
|
8293
8293
|
Amends P112 (`track` follows the selection too) and P118 (`trackedSelection`). From a Raft user's
|
|
8294
8294
|
report, Kirby's design.
|
|
@@ -8450,3 +8450,318 @@ selection inside a page's own scrolling box (its `inView` there is the viewport'
|
|
|
8450
8450
|
Escape in the frame should end a composer by itself; `inView` on a followed mark's `tracked` too; or
|
|
8451
8451
|
an older host's people are seen confused by a pick's outline that stays.
|
|
8452
8452
|
|
|
8453
|
+
|
|
8454
|
+
## P139 · 2026-11-08 · On a tab the shell asks no host, and says how its handshake ended · Accepted
|
|
8455
|
+
|
|
8456
|
+
Amends P085 (the handshake's give-up) and P099 (a page on a tab). From Raft's publish check (task
|
|
8457
|
+
#proj-workspace:#232): its Worker opens each version's ticket top-level in a headless browser and
|
|
8458
|
+
waits a fixed 10.5 s before it shoots, for the shell to give up.
|
|
8459
|
+
|
|
8460
|
+
**Context.** The shell asks its host `ui/initialize` up to 40 times, 250 ms apart, before the
|
|
8461
|
+
runtime is told there is nothing to offer (`runtimeOffer(null)`), since a host may start listening
|
|
8462
|
+
after the frame's shell runs. It did that on a tab of its own too (`window.top === window`), where
|
|
8463
|
+
its parent is the window itself: `post` sends nothing there (`window.parent !== window` is false),
|
|
8464
|
+
so 40 requests sat unanswered in `pending` and the handshake ended 10 s after the page started,
|
|
8465
|
+
every time. `porthole.use` was null at once on a tab already (P085: it checks the window itself),
|
|
8466
|
+
so a page drew the same either way; but a tool that shoots a page on a tab can't know when the
|
|
8467
|
+
shell has settled, and waited for the worst case.
|
|
8468
|
+
|
|
8469
|
+
**Decision.**
|
|
8470
|
+
1. **On a tab the shell asks nothing.** `HANDSHAKE` (`shell/runtime.ts`, spliced into the runtime
|
|
8471
|
+
as `HELD_BACK` is) is the handshake as it was, with one first step: given `window.top === window`
|
|
8472
|
+
(read as the shell starts, before any content runs; `top` is unforgeable), it ends at once with
|
|
8473
|
+
no host (`runtimeOffer(null)`), no request and no timer. In a frame it is as before, unchanged:
|
|
8474
|
+
40 tries, 250 ms apart, the first answer taken once, a refusal no answer, and an answer after
|
|
8475
|
+
the give-up still taken.
|
|
8476
|
+
2. **The shell says how its handshake ended**, on the document's root element (`<html>`):
|
|
8477
|
+
`data-porthole-host="none"` once no host will
|
|
8478
|
+
answer (on a tab, as the shell starts, so before the page's own scripts run; in a frame after
|
|
8479
|
+
the 40th try), `"answered"` once one has (a late answer after `"none"` changes it). A tool that
|
|
8480
|
+
shoots a page on a tab waits for it instead of a fixed time, and a shell without it (before this
|
|
8481
|
+
version) is told apart by its absence: such a tool keeps its fixed wait as the fallback and as
|
|
8482
|
+
the most it waits. The attribute is set through `setAttribute` kept before content runs, on the
|
|
8483
|
+
root as the shell starts. A whole document (an artifact page) replaces the shell's body once the
|
|
8484
|
+
shell's document has loaded, the shell's own script with it, but keeps the root: the render adds
|
|
8485
|
+
the page's own `<html>` attributes to it and removes none (a page whose `<html>` carries
|
|
8486
|
+
`data-porthole-host` itself says its own word, as it can from a script).
|
|
8487
|
+
|
|
8488
|
+
**Not a loosening.** No CSP, sandbox flag, egress, gate or allowlist changes, and no message
|
|
8489
|
+
changes:
|
|
8490
|
+
- *Egress.* On a tab the shell sent nothing before either: `post` goes nowhere when the parent is
|
|
8491
|
+
the window itself. Now it builds no request either. In a frame every message is as it was.
|
|
8492
|
+
- *The runtime.* On a tab `porthole.use` was null at once already, and every capability with it;
|
|
8493
|
+
`runtimeOffer(null)` now comes at the start instead of 10 s in, which wakes nothing on a tab
|
|
8494
|
+
(`use` never waits there). The host functions a page reaches are the bridge's, which a tab has
|
|
8495
|
+
none of: nothing was offered there, and nothing is.
|
|
8496
|
+
- *The attribute.* It is the page's own word and decides nothing: the shell reads it nowhere, and
|
|
8497
|
+
no host or gate trusts it. A page can set, change or remove it, as it can any element's
|
|
8498
|
+
attribute; all that changes is when a tool that reads it shoots the page, which the page could
|
|
8499
|
+
already decide by when it draws. It says nothing the page couldn't learn already (`window.top`,
|
|
8500
|
+
and in a frame the host's answer, which the page shares the shell's realm to hear, P053).
|
|
8501
|
+
- *A frame that claims to be a tab* can't: `window.top` is the browser's own (unforgeable), and a
|
|
8502
|
+
frame that reads itself as a tab is one.
|
|
8503
|
+
|
|
8504
|
+
**Rejected.**
|
|
8505
|
+
- *An event (`porthole:standalone`)*: a tool that attaches after it fired misses it; an attribute
|
|
8506
|
+
can be read at any time, and its absence says "an older shell" at once.
|
|
8507
|
+
- *On the shell's own script element*, where it says which locks didn't take
|
|
8508
|
+
(`data-porthole-unfixed`), as this entry first had it: a whole document's render replaces the
|
|
8509
|
+
body, and the script in it, once the shell's document has loaded, so the word was gone by the
|
|
8510
|
+
time a tool reads a page that has loaded (porthole#118's CI: a probe that read it at
|
|
8511
|
+
`DOMContentLoaded` read nothing, at the event the shell fires again after the page's scripts).
|
|
8512
|
+
The root is the page's too, and frameworks change its attributes, but none removes another's.
|
|
8513
|
+
- *Shortening the frame's retries too*: a host that mounts the frame before it listens is the reason
|
|
8514
|
+
for them, and no tool waits on a frame's handshake.
|
|
8515
|
+
|
|
8516
|
+
**Tested.** `test/shell.test.ts` "the shell's handshake with its host (P085, P139)": `HANDSHAKE` run
|
|
8517
|
+
with its effects recorded and its timers by hand: on a tab, nothing asked, no timer, no host at
|
|
8518
|
+
once; in a frame, 40 asks 250 ms apart then no host; the first answer once and no more asks; a
|
|
8519
|
+
refusal no answer, and an answer after the give-up taken; the runtime splices it, gives it
|
|
8520
|
+
`window.top === window`, asks `ui/initialize` in one place and marks the root (with the setAttribute
|
|
8521
|
+
kept before the locks; the render removes no root attribute). `leak/served/tab.spec.ts` "the shell
|
|
8522
|
+
fixes each of its walls in place…": in a frame nothing until the test answers the shell's
|
|
8523
|
+
`ui/initialize` as a host does (the reference host page answers nothing by itself), then
|
|
8524
|
+
`"answered"`; `"none"` on a tab once its document is parsed; `leak/served/runtime.spec.ts` "on a
|
|
8525
|
+
tab, with no host, use resolves null at once, and the shell says so before the page loaded":
|
|
8526
|
+
`"none"` at the parser's `DOMContentLoaded`, and still after the page's document replaced the
|
|
8527
|
+
shell's body. No negative
|
|
8528
|
+
control: it is no defense.
|
|
8529
|
+
|
|
8530
|
+
**Revisit when** a tab gets a host of its own (an opener that answers, a web view's native bridge),
|
|
8531
|
+
which would need it asked; or a tool needs to know more of the shell's state than its handshake
|
|
8532
|
+
(the page drawn, its scripts run), for which this attribute is no model.
|
|
8533
|
+
|
|
8534
|
+
|
|
8535
|
+
## P140 · 2026-11-09 · A pick stays lit, and a selection kept, only for a host that follows it (`keepSelection`) · Accepted
|
|
8536
|
+
|
|
8537
|
+
Amends P138 (its decision 2 and Tenny's "no gap at pick time"). From Ferryman's audit of 0.14.15.
|
|
8538
|
+
|
|
8539
|
+
**Context.** P138 changed what every host's people see, not only a host that follows the selection.
|
|
8540
|
+
After a pick the shell kept the element outlined until the next pick or selection,
|
|
8541
|
+
`clearSelection`, `start`, `stop`, `clear`, Escape or the element leaving the page, and kept every
|
|
8542
|
+
`selected` (the element, or a copy of the range) in memory until the next. A host that never calls
|
|
8543
|
+
`track({ selection: true })` got that too: on Chromium and Firefox the outline was still there 2 s
|
|
8544
|
+
after the pick, where 0.14.14 took it away with the pick. The outline is in the layer's closed
|
|
8545
|
+
shadow root and takes no pointer, so the page could neither read it nor be clicked through it; but
|
|
8546
|
+
it is a change to the default path that a host didn't ask for, which CHANGELOG, ADOPTING and P138
|
|
8547
|
+
named and THREAT_MODEL §7 didn't. Two smaller findings with it: a host that follows no selection
|
|
8548
|
+
parsed a page's `selectionTracked` before dropping it, so a malformed one became an
|
|
8549
|
+
`annotate:invalid` refusal where 0.14.14 ignored the method unread; and ADOPTING said in one
|
|
8550
|
+
place that a pick's outline goes with it and later that it stays.
|
|
8551
|
+
|
|
8552
|
+
The outline and the kept selection exist for one thing: a follow that comes after `selected`
|
|
8553
|
+
(the host opens its composer on the report, then asks). The shell can't tell at pick time whether
|
|
8554
|
+
that follow will come, and the host can: it knows whether it follows selections at all.
|
|
8555
|
+
|
|
8556
|
+
**Decision.**
|
|
8557
|
+
|
|
8558
|
+
1. **`start` says whether the host follows what is selected:** `annotations.start({ ...,
|
|
8559
|
+
keepSelection: true })`, on the wire `porthole/annotate.start` with `keepSelection: true` (absent
|
|
8560
|
+
when false; `annotateMode` throws for a value that isn't a boolean). It holds until the next
|
|
8561
|
+
`start`, and is kept with the mode for a frame that runs later and past a pick that leaves text
|
|
8562
|
+
selection on. A `stop` leaves it, so a stop sent as a composer opens doesn't take the selection
|
|
8563
|
+
away before the follow arrives.
|
|
8564
|
+
2. **The shell keeps a selection only while the host follows the selection, or said at its last
|
|
8565
|
+
`start` that it will.** Otherwise a `selected` keeps nothing (P138's `held` stays null), a pick's
|
|
8566
|
+
outline goes with the pick (`picked` is set only under `keepSelection`), and the end of a
|
|
8567
|
+
following lets the kept selection go. That is 0.14.14's behaviour, exactly: the same draw at the
|
|
8568
|
+
pick, nothing in memory after it. Under `keepSelection` everything is as P138 has it: the
|
|
8569
|
+
outline until the follow takes it over or the pick ends as a selection does, the selection kept
|
|
8570
|
+
for a follow asked after `selected`.
|
|
8571
|
+
3. **A follow asked before the pick needs no option.** While the host follows the selection, each
|
|
8572
|
+
`selected` is kept and followed from the next frame, as P138 has it; the highlight is drawn at
|
|
8573
|
+
the pick, in the same draw, so there is no gap either.
|
|
8574
|
+
4. **React** starts the mode with `keepSelection` while `trackedSelection` is given (true or false),
|
|
8575
|
+
from the first render: `trackedSelection={composerOpen}` is the shape it documents. Read at each
|
|
8576
|
+
start, never a reason for one (after Ferryman's review, below). A host that
|
|
8577
|
+
gives `annotating` a `keepSelection` of its own keeps it too.
|
|
8578
|
+
5. **`createHost` drops `selectionTracked` unread while it follows no selection**, before parsing
|
|
8579
|
+
it: no report, no refusal, as 0.14.14 dropped a method it didn't know. While it follows, a
|
|
8580
|
+
malformed one is refused as before.
|
|
8581
|
+
|
|
8582
|
+
**Versions.** A newer host with a 0.14.15 shell: the shell ignores `keepSelection` and keeps every
|
|
8583
|
+
pick lit, as it does now. A newer host with an older shell: nothing changes (no follow there). A
|
|
8584
|
+
0.14.15 host that follows the selection after `selected`, with a newer shell: it never says
|
|
8585
|
+
`keepSelection`, so the shell has nothing to follow and answers `orphaned`. The composer stays
|
|
8586
|
+
where `selected` put it, as with an older shell, until the host upgrades (or asks for the follow
|
|
8587
|
+
before the pick). 0.14.15 is a day old; the CHANGELOG says to upgrade the host with the content
|
|
8588
|
+
server.
|
|
8589
|
+
|
|
8590
|
+
**Not a loosening.** It narrows P138: less is drawn and less is kept for a host that doesn't follow,
|
|
8591
|
+
and a page's word is read by fewer hosts. No CSP, sandbox, egress or gate change. The page reads
|
|
8592
|
+
`keepSelection` (it shares the shell's realm, P053), so it learns at every `start` that the host
|
|
8593
|
+
will follow the selection: before any pick, and earlier than the first `track` would tell it. That
|
|
8594
|
+
is a property of the host's UI, not of anything the person did or wrote. What the shell keeps (a
|
|
8595
|
+
reference to the picked element, a copy of the range) is in the shell's script's memory, not in
|
|
8596
|
+
its layer: only the outline is in the closed shadow root. Negative control `track-selection-checks` now also takes out the unread drop,
|
|
8597
|
+
with the rate.
|
|
8598
|
+
|
|
8599
|
+
**Rejected.**
|
|
8600
|
+
- *Tying it to the following alone* (keep and outline only while `track({ selection: true })` is
|
|
8601
|
+
on, and no option): the host's documented order, P138's sample and React's `trackedSelection`
|
|
8602
|
+
ask for the follow after `selected`, which would then always find nothing. Every following host
|
|
8603
|
+
would have to follow from before the pick, and get `orphaned` reports while nothing is picked:
|
|
8604
|
+
a change to how 0.14.15's hosts call it, where `keepSelection` is one field at `start`. Point 3
|
|
8605
|
+
keeps that order working for a host that prefers it.
|
|
8606
|
+
- *A timer* (keep the pick for a second): P138 chose no timer, and the auditor's 2 s measure would
|
|
8607
|
+
still see it.
|
|
8608
|
+
- *The anchor sent back with `track`, found again by the shell*: no state in the frame, but the
|
|
8609
|
+
gap at pick time returns, and a found anchor can be another element than the one picked.
|
|
8610
|
+
- *`keepPick`* (the auditor's name): what is kept is the words selected too.
|
|
8611
|
+
|
|
8612
|
+
**Tested.** `test/annotate.test.ts`: `annotateMode` with `keepSelection` (only where true, a
|
|
8613
|
+
non-boolean throws); through `createHost`, `start` sends it only where asked and keeps it for a
|
|
8614
|
+
later frame past a pick; "not following the selection, a selectionTracked is dropped unread…": five
|
|
8615
|
+
malformed reports and a good one, no refusal and no report, again after a following ended, and a
|
|
8616
|
+
refusal for the same malformed one while followed; in the shell's runtime, kept only while
|
|
8617
|
+
followed or kept (`keeps()`), `start` setting it and letting go, `holdSelected` keeping nothing
|
|
8618
|
+
otherwise, the outline set only under it, a following's end letting go, `stop` leaving it.
|
|
8619
|
+
`leak/annotate.spec.ts` "without keepSelection or a follow, a pick's outline goes with the pick and
|
|
8620
|
+
nothing is kept…" (Chromium and Firefox here): no outline at the pick and 2 s on; a page's
|
|
8621
|
+
malformed `selectionTracked` no refusal; a follow asked after the pick `orphaned`, nothing drawn; a
|
|
8622
|
+
follow asked before the pick attached and lit, and let go with its end; words selected without it
|
|
8623
|
+
`orphaned` too. P138's browser tests now start with `keepSelection` where they follow after
|
|
8624
|
+
`selected` (the outline, the follow, the scroll, the focus), and React's `trackedSelection` test
|
|
8625
|
+
gives it false from the first render.
|
|
8626
|
+
|
|
8627
|
+
*After Ferryman's review of porthole#119, one change and one correction:*
|
|
8628
|
+
|
|
8629
|
+
- **React restarts no mode for `trackedSelection`.** Decision 4 first put "`trackedSelection` is
|
|
8630
|
+
given" into the mode's key, so the prop appearing or going restarted the mode: a host that keeps
|
|
8631
|
+
`annotating` on and gives `trackedSelection` as its composer opens (0.14.15's prop docs allow it)
|
|
8632
|
+
sent `start` again, element picking came back on after the pick had ended it, and the person's
|
|
8633
|
+
next click in the frame picked again and sent another `selected`. Now the key is the mode alone
|
|
8634
|
+
(`elements`, `text`, and the host's own `keepSelection`), and whether `trackedSelection` is given
|
|
8635
|
+
is read at each start: it rides with the next one, and is never a reason for one. So it counts
|
|
8636
|
+
from the mode's start: given (false is enough) when the mode started, the pick is kept and a
|
|
8637
|
+
follow after it is `attached`; given only after the pick, nothing was kept and the follow is
|
|
8638
|
+
`orphaned`, which is decision 2 for a host that hadn't said it follows (0.14.15 was `attached`
|
|
8639
|
+
there because it kept every host's pick). No shell change, and no message between starts: the
|
|
8640
|
+
shell needs the word before the pick, and a start is where React has it, given from the first
|
|
8641
|
+
render as documented.
|
|
8642
|
+
- **Where things are.** Only the outline is in the layer's closed shadow root; the kept selection
|
|
8643
|
+
(a reference to the element, a copy of the range) is in the shell's script's memory, and it is
|
|
8644
|
+
the page's own DOM. `keepSelection` tells the page at every `start` that the host will follow the
|
|
8645
|
+
selection, before any pick and earlier than the first `track`. THREAT_MODEL §7 now says both.
|
|
8646
|
+
|
|
8647
|
+
*Tested.* `leak/react.spec.ts` "trackedSelection given or left out while annotating stays on
|
|
8648
|
+
restarts no mode…" (Chromium and Firefox here): with the mode left on, `trackedSelection` given after
|
|
8649
|
+
the pick restarts nothing (the next click is no second `selected`) and the follow is `orphaned`, and
|
|
8650
|
+
taking it away restarts nothing either; given as false from the first render, the follow after the
|
|
8651
|
+
pick is `attached` and the next click again no second `selected`. With "is given" back in the key,
|
|
8652
|
+
it fails at the second pick.
|
|
8653
|
+
|
|
8654
|
+
**Revisit when** a host needs the pick kept without following it (a host that draws its own
|
|
8655
|
+
highlight from `selected`), or a host is seen confused by `orphaned` after an upgrade.
|
|
8656
|
+
|
|
8657
|
+
|
|
8658
|
+
## P141 · 2026-11-09 · An app framed by another: its outer page may be an ancestor of its frames, never their host (`framedBy`) · Accepted
|
|
8659
|
+
|
|
8660
|
+
From Raft (task #botiverse-raft-deployment:#245, Tenny): Deck (`https://deck.raft.build`, and
|
|
8661
|
+
`https://deck-aws-dev.raft.build` on staging) frames the Raft app (`app.raft.build`) in an iframe.
|
|
8662
|
+
|
|
8663
|
+
**Context.** `frame-ancestors` is checked against every ancestor, not only the parent: a frame the
|
|
8664
|
+
app shows inside Deck has Deck above the app, and every policy Porthole sends names the host
|
|
8665
|
+
origins alone (`appOrigins`, `hostOrigins`), so each of the app's frames went blank inside Deck.
|
|
8666
|
+
The same list is also who a frame hears and tells: the shell's and the nested shell's message
|
|
8667
|
+
origins, the pages' and doors' `data-porthole-hosts`, the host kit's checks for redirect entry and
|
|
8668
|
+
the handoff. Adding Deck to `appOrigins` would let it frame content *and* speak to it as its host:
|
|
8669
|
+
answer a shell's `ui/initialize`, call host functions on the bridge's word, hear what a frame says
|
|
8670
|
+
to its host. The app frames content; Deck frames the app. Only the first is a host.
|
|
8671
|
+
|
|
8672
|
+
**Decision.**
|
|
8673
|
+
|
|
8674
|
+
1. **`framedBy: readonly string[]`**, on `createServer` and `createContentHost` (and on the helpers
|
|
8675
|
+
a content Worker of its own answers with: `statusPage`, `doorResponse`, `doorStatusResponse`
|
|
8676
|
+
and `nestedShellResponse` take it too), names origins that may be an **ancestor** of every
|
|
8677
|
+
frame Porthole serves, above a host origin's page. Default none: every response is as before,
|
|
8678
|
+
byte for byte.
|
|
8679
|
+
2. **They are in every `frame-ancestors` and nowhere else**: after the host origins, in each
|
|
8680
|
+
policy `/server` sends (a shell, an artifact page, a file set's pages and files and their own
|
|
8681
|
+
frames, a nested page's shell, page and files, the MCP Apps proxy, a door and a door that doesn't
|
|
8682
|
+
open, the status, entry and tab-only pages, assets, a renewal, a url-mode app's answers: one
|
|
8683
|
+
list in `createServer`, `frameAncestors`) and in
|
|
8684
|
+
the host kit's authorize route's pages. Never a message origin of a shell, a nested shell, a
|
|
8685
|
+
door or a page; never in `data-porthole-hosts` or a shell's plan; never a host origin for
|
|
8686
|
+
`entry.authorizeUrl`, the handoff's `Origin` check (still `appOrigins` alone) or the content
|
|
8687
|
+
domain's clash rules, which they are checked against apart.
|
|
8688
|
+
3. **They are checked as host origins are, more narrowly**: exact origins, `https://host[:port]`
|
|
8689
|
+
(`http://` on loopback alone, for development), lowercase, no path, no wildcard, no keyword, never
|
|
8690
|
+
`"null"` or a desktop scheme (an outer page is a web page); none a host origin (one origin is a
|
|
8691
|
+
host or an outer page, never both); none on, or maybe the same site as, the content domain.
|
|
8692
|
+
A bad one throws (`framedBy: …`), as a bad host origin does, before anything goes into a header;
|
|
8693
|
+
the host kit's fallback makes it a lasting `misconfigured`, as it does a bad app origin.
|
|
8694
|
+
4. **The direct parent must still be a host origin, and Porthole holds it so where it can.**
|
|
8695
|
+
`frame-ancestors` can't say "an ancestor but not the parent": with `framedBy`, an outer page
|
|
8696
|
+
that frames content directly is let in by the browser. Such a frame gets no host:
|
|
8697
|
+
- *Heard:* the shell, the nested shell and a door take a message only from a host origin
|
|
8698
|
+
(`event.origin` in its plan's `origins`): the outer page's `ui/initialize` answer is dropped,
|
|
8699
|
+
the handshake ends with no host (`data-porthole-host="none"`, P139), `porthole.use` is null,
|
|
8700
|
+
and the bridge never runs: no host function is called on its word.
|
|
8701
|
+
- *Told:* Porthole's own words go to each web host origin by name, so only a host origin as the
|
|
8702
|
+
parent receives them. The one exception was the `*` fallback where a desktop scheme is a host
|
|
8703
|
+
origin (P070, its item 6), whose premise ("these pages are framable only by the host origins,
|
|
8704
|
+
so their parent is one") `framedBy` breaks. Now, where a page's `frame-ancestors` names anyone
|
|
8705
|
+
beyond its host origins (`data-porthole-strict-parent` on the status, entry and door pages;
|
|
8706
|
+
`strictParent` in a nested shell's plan), `*` goes only to a parent the engine names
|
|
8707
|
+
(`location.ancestorOrigins[0]`, not masked as `"null"`) as one of the host origins: an outer
|
|
8708
|
+
page as the parent, or a parent the engine doesn't name, is never told. Without `framedBy`
|
|
8709
|
+
the rule is P070's, unchanged.
|
|
8710
|
+
|
|
8711
|
+
**What it re-opens (PRINCIPLE 1).** An outer page may now be an ancestor of content, which no
|
|
8712
|
+
origin but the host's could be.
|
|
8713
|
+
- *Clickjacking and framing the app's content from another app*: bounded to the origins the host
|
|
8714
|
+
names, each exact; the host's own page between them stays the host's (its `frame-ancestors` is
|
|
8715
|
+
the app's to set: Raft's in Terraform, not Porthole's).
|
|
8716
|
+
- *An outer page framing content directly*: it needs an address to frame. Tickets come from the
|
|
8717
|
+
host's issue endpoint and are used once; a clean address in a frame is the tab-only page (P125);
|
|
8718
|
+
a sealed address is in the frame's own document. If it has one, the frame loads, but as above it
|
|
8719
|
+
is no host. It hears what content says to its parent with `*` itself: the content shell's own
|
|
8720
|
+
notices (its runtime posts to `*`, P053: the content shares that realm and could post anything
|
|
8721
|
+
itself), annotation and find reports. That is the content's word, which any parent of a frame
|
|
8722
|
+
could always hear, and which the outer page must treat as untrusted; on a nested page the shell
|
|
8723
|
+
passes the page's words to host origins alone, by name, so an outer parent hears none of them.
|
|
8724
|
+
- *Partitioned cookies*: a frame below the outer page is keyed to the top-level site, the outer
|
|
8725
|
+
page's (CHIPS), as any embedding is. Where the outer page is another site than the app, a
|
|
8726
|
+
session made inside it is that partition's alone; where it is the same site (Deck at
|
|
8727
|
+
`deck.raft.build`, the app at `app.raft.build`: both `raft.build`), it is the partition the app's
|
|
8728
|
+
own tab uses too, as for any page of that site. No sharing is added across sites.
|
|
8729
|
+
|
|
8730
|
+
**Rejected.**
|
|
8731
|
+
- *Adding the outer page to `appOrigins`*: it would be a host: heard, told, an origin for entry
|
|
8732
|
+
and the handoff. Exactly what Tenny ruled out.
|
|
8733
|
+
- *A wildcard, or any https origin*: an outer page is one product's, named.
|
|
8734
|
+
- *Refusing an outer page as the parent outright*: no header can, and a shell that refused to draw
|
|
8735
|
+
where `ancestorOrigins[0]` is an outer page would decide nothing on Firefox's masked `"null"`
|
|
8736
|
+
(measured: Firefox masks a `no-referrer` frame's ancestors, Chromium names them), while it is no
|
|
8737
|
+
host already.
|
|
8738
|
+
- *The outer origins in the pages' bodies, for the `*` check*: one boolean (`strict`) says enough
|
|
8739
|
+
(the parent must be named, and a host origin), and keeps them out of everything but the header.
|
|
8740
|
+
|
|
8741
|
+
**Tested.** `test/framed-by.test.ts`: `framedBy` taken (https, loopback http) and refused (a
|
|
8742
|
+
wildcard, a path, uppercase, `*`, `'self'`, a list, a CSP injection, `"null"`, a desktop scheme,
|
|
8743
|
+
plain http, a host origin, the content domain and its site), in `createServer`, the helpers and
|
|
8744
|
+
the host kit; **the bound**: every answer of 23 (a shell and its used ticket, a 404, a door and a
|
|
8745
|
+
used door, an artifact page, the MCP Apps proxy, two file sets' tickets, pages, scripts, files and
|
|
8746
|
+
refused renewals, one of them with its own frames, a nested page's shell, page, script and ended
|
|
8747
|
+
access, a url-mode app's entry page and answer), under host origins with a desktop scheme and one
|
|
8748
|
+
`framedBy`, names it in `frame-ancestors` after the host origins, every
|
|
8749
|
+
framed document has `frame-ancestors`, and none says the outer origin in another header or its body
|
|
8750
|
+
(not in `data-porthole-hosts`, not in a plan's `origins`); without `framedBy` none is strict and
|
|
8751
|
+
none names it; the helpers' defaults are as before; the host kit's content and authorize route's pages name it,
|
|
8752
|
+
and the handoff refuses its `Origin` (403) where the app's own is taken. Assets and the tab-only
|
|
8753
|
+
page take the same one list (`frameAncestors`), untested apart. **The negative controls**: the status script, strict, says `*` only
|
|
8754
|
+
to a parent named as a host origin (desktop: yes; the outer page, `"null"`, unnamed: no), and not
|
|
8755
|
+
strict says it as before; the nested shell's script, given `framedBy`, says no `*` to an outer
|
|
8756
|
+
parent and passes none of its words to the page, while a host's word passes. Taking the strict
|
|
8757
|
+
condition out fails both. `leak/served/framed-by.spec.ts` (Chromium and Firefox here; WebKit not
|
|
8758
|
+
run on this machine): below the outer page, the app's frame shows and is answered by the app; below
|
|
8759
|
+
a foreign page it is refused; the outer page framing content itself sees the frame load and its
|
|
8760
|
+
`ui/initialize` answer refused, the handshake ending `"none"`; a door framed by the app tells it
|
|
8761
|
+
`open`, framed by the outer page says nothing to it (with the strict condition taken out it says
|
|
8762
|
+
`*`, and the probe fails). No weakening in `leak/weakenings.ts`: the probes above are the
|
|
8763
|
+
control, run as mutations.
|
|
8764
|
+
|
|
8765
|
+
**Revisit when** an outer page needs to speak to a frame (then it is a host, and needs
|
|
8766
|
+
`appOrigins`), browsers give a policy for the parent alone, or a host wants an outer page to frame
|
|
8767
|
+
content without its own page between them.
|
package/docs/DESIGN.md
CHANGED
|
@@ -684,6 +684,10 @@ the bridge, `ui/message` and `ui/open-link` into the bridge, `ui/resource-teardo
|
|
|
684
684
|
Content may also use the official App SDK directly; the adapter answers a second
|
|
685
685
|
`ui/initialize` from the same frame, and the shell numbers its own requests with
|
|
686
686
|
strings (`porthole-shell-1`) so neither takes the other's answers.
|
|
687
|
+
The shell asks `ui/initialize` up to 40 times, 250 ms apart (the host may listen after it runs);
|
|
688
|
+
on a tab of its own it asks nothing, since no host can hear it, and its runtime has nothing to
|
|
689
|
+
offer from the start. The document's root says how the handshake ended (`data-porthole-host`:
|
|
690
|
+
`"answered"`, or `"none"`), for a tool that shoots a page to wait on (P139).
|
|
687
691
|
|
|
688
692
|
The host context carries in `styles.variables` only the names MCP Apps defines
|
|
689
693
|
(`MCP_APPS_STYLE_VARIABLES`): the official SDK refuses any other name there and fails
|
|
@@ -1043,7 +1047,7 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1043
1047
|
|
|
1044
1048
|
| Direction | Message | Params |
|
|
1045
1049
|
|-----------|---------|--------|
|
|
1046
|
-
| host → frame | `porthole/annotate.start` | `{ elements, text }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects) |
|
|
1050
|
+
| host → frame | `porthole/annotate.start` | `{ elements, text, keepSelection? }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects); `keepSelection: true` (absent otherwise): the host follows what is selected, so the frame keeps it, and a pick's outline, for a follow asked after `selected` (P140) |
|
|
1047
1051
|
| host → frame | `porthole/annotate.stop` | — |
|
|
1048
1052
|
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999; the host clamps a larger one, P116) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
|
|
1049
1053
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
@@ -1056,7 +1060,7 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1056
1060
|
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, lastLineDocumentRect?, order? }], scroll? }` (a newer shell's `documentRect` and `scroll`: P132, below; `lastLineDocumentRect`: P133, never without `scroll`, P137): every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
|
|
1057
1061
|
| host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112); `{ id: null, selection: true }`: follow the selection last reported as `selected` instead, and highlight it while followed (P138; an older shell reads it as none) |
|
|
1058
1062
|
| frame → host | `porthole/annotate.tracked` | `{ id, rect, documentRect?, lastLineDocumentRect?, scroll? }`: the followed mark's box at an animation frame where it moved, at most one every 16 ms; the host takes 60 a second, for that mark only (P112); a newer shell adds its place in the document and the document's scroll (P132), and its last line's (P133, never without the scroll, P137) |
|
|
1059
|
-
| frame → host | `porthole/annotate.selectionTracked` | `{ state: "attached", rect, documentRect, lastLineDocumentRect?, scroll, inView }` or `{ state: "orphaned" }`: the followed selection's boxes, as `tracked`'s, at an animation frame where it moved or the viewport changed size, at most one every 16 ms, the first at the frame after the host asks; `orphaned` once while it isn't in the page (or the frame has no selection), found again by its anchor at most twice a second; the host takes it only while it follows the selection, 60 a second with `tracked`, its `rect` clamped, `inView` false unless its box as read reaches the viewport (P138) |
|
|
1063
|
+
| frame → host | `porthole/annotate.selectionTracked` | `{ state: "attached", rect, documentRect, lastLineDocumentRect?, scroll, inView }` or `{ state: "orphaned" }`: the followed selection's boxes, as `tracked`'s, at an animation frame where it moved or the viewport changed size, at most one every 16 ms, the first at the frame after the host asks; `orphaned` once while it isn't in the page (or the frame has no selection), found again by its anchor at most twice a second; the host takes it only while it follows the selection (otherwise dropped unread, no refusal, P140), 60 a second with `tracked`, its `rect` clamped, `inView` false unless its box as read reaches the viewport (P138) |
|
|
1060
1064
|
| frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker, or pressed Enter or Space on it (P133); `rect` is the marker's (P104); taken only while the host's page has transient activation (P105) |
|
|
1061
1065
|
|
|
1062
1066
|
- **Anchors** are W3C Web Annotation selectors, at most one of each:
|
|
@@ -1094,7 +1098,8 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1094
1098
|
of the words' client rects, the box a text marker's place starts from; an element,
|
|
1095
1099
|
which has no lines of its own, gives its whole box. Its place in the frame's viewport
|
|
1096
1100
|
is it less `scroll`. Absent from an older shell, and where nothing of it is drawn.
|
|
1097
|
-
- **The selection followed** (P138).
|
|
1101
|
+
- **The selection followed** (P138, P140). For a host that follows the selection, or said at
|
|
1102
|
+
`start` that it will (`keepSelection`), the shell keeps what each `selected` reported: the
|
|
1098
1103
|
element picked (a click, or a block held), or a copy of the selection's range (the
|
|
1099
1104
|
DOM's own `cloneRange`, taken before content runs), which the page's changes keep up to
|
|
1100
1105
|
date and which stays when the page's own selection goes (the host's `clearSelection`
|
|
@@ -1106,13 +1111,17 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1106
1111
|
the viewport). Taken out of the page, it is `orphaned` once, and found again by its
|
|
1107
1112
|
anchor as a mark is. It reads boxes only: no focus moves, no selection changes, no
|
|
1108
1113
|
listener is added, and nothing about the words goes with it (they went with
|
|
1109
|
-
`selected`). A newer `selected` replaces it, followed from the next frame.
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
+
`selected`). A newer `selected` replaces it, followed from the next frame. For any other host
|
|
1115
|
+
nothing is kept and a pick's outline goes with the pick, as before P138; the end of a following
|
|
1116
|
+
lets the kept selection go unless `keepSelection` holds (P140). Under `keepSelection`, before the
|
|
1117
|
+
host follows it, the element just picked keeps an outline drawn the same way, so nothing changes
|
|
1118
|
+
on screen when the follow takes over; until a follow it ends as a selection does (the next pick
|
|
1119
|
+
or selection, `clearSelection`, `start`, `stop`, `clear`, Escape, the element leaving the page),
|
|
1120
|
+
on no timer (Tenny's review). While followed, a scroll re-sends no `selected` (P105's follow-up):
|
|
1114
1121
|
once the following ends, it does again. The React binding sends the following before a mode
|
|
1115
|
-
change made in the same render
|
|
1122
|
+
change made in the same render, and starts the mode with `keepSelection` while
|
|
1123
|
+
`trackedSelection` is given (P140), read at each start and never a reason for one. The host drops a `selectionTracked` unread, before parsing
|
|
1124
|
+
it, while it follows no selection (P140).
|
|
1116
1125
|
- **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
|
|
1117
1126
|
above 99; 0 the bubble alone), a real button (P133, below), on an element's top right
|
|
1118
1127
|
corner, inside the frame's width, and at the end of a text anchor's paragraph (P133):
|
|
@@ -1606,7 +1615,7 @@ control the tables above name to the registry):
|
|
|
1606
1615
|
| `comments-in-frame` | `served/runtime.spec.ts` | `comments.open while the person types in the host's composer reaches no handler, by the page's own call or the shell's; from a press in the frame it does` | — | — |
|
|
1607
1616
|
| `cancel-any-mode` | `annotate.spec.ts` | `Escape while selecting text is cancelled, and stays the page's key; with no mode on, a page's own cancel isn't heard (P112)`, `a hostile page fakes reports: the host takes none it didn't ask for, nothing malformed, and not a flood` | — | — |
|
|
1608
1617
|
| `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
|
|
1609
|
-
| `track-selection-checks` | `annotate.spec.ts` | `a followed selection's place comes as it moves, highlighted, out of view and back, gone and found again, only while the host follows it, at most 60 a second (P138)` | — | — |
|
|
1618
|
+
| `track-selection-checks` | `annotate.spec.ts` | `a followed selection's place comes as it moves, highlighted, out of view and back, gone and found again, only while the host follows it, at most 60 a second (P138)`, `without keepSelection or a follow, a pick's outline goes with the pick and nothing is kept: a follow asked after it has nothing, one asked before it follows it; a page's malformed word is no refusal (P140)` | — | — |
|
|
1610
1619
|
| `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
|
|
1611
1620
|
| `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
|
|
1612
1621
|
| `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -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.
|
|
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
|
|
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
|
|
@@ -41,7 +41,13 @@ in the frame's document by then; a call on a calm page is unchanged. 0.14.14: P1
|
|
|
41
41
|
through a nested page's shell with a new host-to-shell word no page can say; P137 applies P135's check to a
|
|
42
42
|
word 100 ms old or more; no wall moves. 0.14.15: P138 lets the host follow the current selection
|
|
43
43
|
(`selectionTracked`, the same boxes as `tracked`, on its budget, only while asked) and keeps what was
|
|
44
|
-
picked lit; no wall moves.
|
|
44
|
+
picked lit; no wall moves. 0.14.16: P139 has a shell on a tab of its own ask no host; P140 narrows P138: a pick stays lit, and a
|
|
45
|
+
selection is kept in the frame, only for a host that follows the selection (`keepSelection`), and a
|
|
46
|
+
host that follows none drops `selectionTracked` unread (§7). 0.14.17: P141 lets a host name the
|
|
47
|
+
origins of an outer page that frames its app (`framedBy`): each may be an ancestor of every frame,
|
|
48
|
+
above the host's own page, so it is in every `frame-ancestors`, and nowhere else; it is never a
|
|
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).
|
|
45
51
|
|
|
46
52
|
## 1. Two layers
|
|
47
53
|
|
|
@@ -264,7 +270,16 @@ Whatever the use:
|
|
|
264
270
|
`display.focus()` inside a key's own handler moves nothing: call it from a task (measured on a
|
|
265
271
|
nested page). Nothing leaks either way: the keyboard stays out of the page.
|
|
266
272
|
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
267
|
-
and only those are checked against the content
|
|
273
|
+
only those are a frame's host (heard and told), and only those are checked against the content
|
|
274
|
+
domain for a shared site.
|
|
275
|
+
- Where another app frames yours (P141), name its origins in `framedBy`, never in `appOrigins`: it
|
|
276
|
+
may then be an ancestor of your frames, above your own page, and is never their host. Your page
|
|
277
|
+
must still be the frame's parent: an outer page that frames content directly (with an address it
|
|
278
|
+
got from somewhere) is let in by the browser, but the frame takes nothing from it (no handshake,
|
|
279
|
+
no host function), Porthole's own pages and a nested page's shell tell it nothing, and what it
|
|
280
|
+
can hear is the content's own word to its parent (`*`), which it must treat as untrusted. Your
|
|
281
|
+
app page's own `frame-ancestors` is yours to set; Porthole never sends it. Name exact origins of
|
|
282
|
+
that one product, and drop them when it stops framing you.
|
|
268
283
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
269
284
|
|
|
270
285
|
### S1. Inline widgets in a conversation
|
|
@@ -417,7 +432,8 @@ encrypted into the path, since WebKit keeps no cookie in a frame (P083).
|
|
|
417
432
|
another label's session is never read as this one's, under https or on loopback (P101).
|
|
418
433
|
- Pages, files and status pages carry their CSP in headers and `X-Robots-Tag: noindex`, and
|
|
419
434
|
`frame-ancestors` names the app's origins only (with `nestedFrames: "own"`, P128, a file set's
|
|
420
|
-
files below its base name the page's own origin too, so its pages frame them)
|
|
435
|
+
files below its base name the page's own origin too, so its pages frame them), then the host's
|
|
436
|
+
`framedBy`, if any (P141): ancestors above the app's page, never its host.
|
|
421
437
|
- Files: from the version's manifest only, typed by Porthole's table, `nosniff`; files other than
|
|
422
438
|
pages are `Cross-Origin-Resource-Policy: same-origin`; a file set never registers a service
|
|
423
439
|
worker; a page's CSP opens its own version's path, not its whole origin.
|
|
@@ -863,9 +879,25 @@ own frame, below the shell, P111), so:
|
|
|
863
879
|
(`selectionTracked`, P138) are the same boxes, checked and clamped the same way, taken only while
|
|
864
880
|
the host follows the selection and within `tracked`'s 60 a second (control
|
|
865
881
|
`track-selection-checks`); their `inView` is false unless the box reaches the frame's viewport as
|
|
866
|
-
the host reads it. They carry nothing of the page's words
|
|
867
|
-
|
|
868
|
-
|
|
882
|
+
the host reads it. They carry nothing of the page's words; a host that follows no selection
|
|
883
|
+
drops them unread, so a malformed one is no refusal either (P140). The page reads the host's word
|
|
884
|
+
that starts and ends the following, so it learns when a composer is open on its selection, as it
|
|
885
|
+
learns which card is open from `track` (P112): end it on every close, kept or dismissed. The
|
|
886
|
+
outline the frame draws over what was picked, or over the followed selection, is in the shell's
|
|
887
|
+
layer, a closed shadow root that takes no pointer: the page can't read it, and its clicks reach
|
|
888
|
+
the page as before. What the frame keeps for a follow (a reference to the element picked, or a
|
|
889
|
+
copy of the selected range) is not in that layer: it is held in the shell's own script, in
|
|
890
|
+
memory, in a variable no page script can name. It is the page's own DOM all the same (the
|
|
891
|
+
element is the page's, and the range's copy moves with the page's nodes), so it tells the page
|
|
892
|
+
nothing it can't read itself, and the page can change or remove what it points at, which is
|
|
893
|
+
`orphaned`. In 0.14.15 every host's frame kept both after a pick, the outline until the next
|
|
894
|
+
pick or selection, `clearSelection`, `start`, `stop`, `clear`, Escape or the element leaving the
|
|
895
|
+
page, and the kept selection until the next `selected`; since P140 only a host that follows the
|
|
896
|
+
selection (`track({ selection: true })`) or said at `start` that it will (`keepSelection`) gets
|
|
897
|
+
them, and any other host's frame draws and keeps nothing after a pick, as in 0.14.14. The page
|
|
898
|
+
reads `keepSelection` in every `start`, so it learns at each one that the host will follow the
|
|
899
|
+
selection: before any pick, and earlier than the first `track` would tell it. That is a property
|
|
900
|
+
of the host's UI, not of anything the person did or wrote.
|
|
869
901
|
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
870
902
|
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
871
903
|
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.17",
|
|
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": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -84,12 +84,21 @@ export interface AnnotateMode {
|
|
|
84
84
|
readonly elements?: boolean | "hold";
|
|
85
85
|
/** Text, by selecting it: each settled selection is reported, and its clearing. */
|
|
86
86
|
readonly text?: boolean;
|
|
87
|
+
/**
|
|
88
|
+
* That you follow what is selected (P140): `annotations.track({ selection: true })` once
|
|
89
|
+
* `selected` comes (React sets it while `trackedSelection` is given). Only then does the frame
|
|
90
|
+
* keep it for you to follow, the element just picked outlined until the follow takes over. Without
|
|
91
|
+
* it the frame keeps nothing and a pick's outline goes with the pick, as before 0.14.15; a follow
|
|
92
|
+
* asked before the pick still follows each selection reported while it lasts.
|
|
93
|
+
*/
|
|
94
|
+
readonly keepSelection?: boolean;
|
|
87
95
|
}
|
|
88
96
|
|
|
89
97
|
/**
|
|
90
98
|
* What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
|
|
91
99
|
* last reported as `selected` (the element picked, or the words selected), highlighted in the
|
|
92
|
-
* frame while followed
|
|
100
|
+
* frame while followed, and kept for a follow asked after `selected` only under `start`'s
|
|
101
|
+
* `keepSelection` (P140); or nothing (`null`). One at a time: each replaces the last.
|
|
93
102
|
*/
|
|
94
103
|
export type AnnotationTrackTarget = string | { readonly selection: true } | null;
|
|
95
104
|
|
package/src/annotate/validate.ts
CHANGED
|
@@ -339,10 +339,19 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
339
339
|
}
|
|
340
340
|
}
|
|
341
341
|
|
|
342
|
-
/**
|
|
343
|
-
export
|
|
342
|
+
/** A mode as the frame gets it: `keepSelection` only where it is true (P140). */
|
|
343
|
+
export type StartedMode = Required<Omit<AnnotateMode, "keepSelection">> & {
|
|
344
|
+
readonly keepSelection?: true;
|
|
345
|
+
};
|
|
346
|
+
|
|
347
|
+
/**
|
|
348
|
+
* What the host may start with: elements, text, or both (default both); and whether it follows
|
|
349
|
+
* what is selected (`keepSelection`, P140).
|
|
350
|
+
*/
|
|
351
|
+
export function annotateMode(mode: AnnotateMode | undefined): StartedMode {
|
|
344
352
|
const elements = mode?.elements ?? true;
|
|
345
353
|
const words = mode?.text ?? true;
|
|
354
|
+
const keep = mode?.keepSelection ?? false;
|
|
346
355
|
if (
|
|
347
356
|
(typeof elements !== "boolean" && elements !== "hold") ||
|
|
348
357
|
typeof words !== "boolean" ||
|
|
@@ -350,7 +359,10 @@ export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateM
|
|
|
350
359
|
) {
|
|
351
360
|
throw new TypeError("annotations.start: elements, text, or both");
|
|
352
361
|
}
|
|
353
|
-
|
|
362
|
+
if (typeof keep !== "boolean") {
|
|
363
|
+
throw new TypeError("annotations.start: keepSelection is true or false");
|
|
364
|
+
}
|
|
365
|
+
return { elements, text: words, ...(keep ? { keepSelection: true } : {}) };
|
|
354
366
|
}
|
|
355
367
|
|
|
356
368
|
/**
|