From 8e9ece9331673fe6a82841a90893d507907a24e3 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:10:23 -0800 Subject: [PATCH 01/23] spec(AST-131): the React Native web view keeps navigation, sessions, and bundled pages under declared native policy --- .../AST-131-react-native-web-view/spec.md | 470 ++++++++++++++++++ 1 file changed, 470 insertions(+) create mode 100644 docs/specs/AST-131-react-native-web-view/spec.md diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md new file mode 100644 index 0000000000000..cd04678f577fc --- /dev/null +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -0,0 +1,470 @@ +--- +schema_version: 4 +template_version: 2 +kind: system-spec +id: spec:AST-131 +authority: draft +archive_reason: null +superseded_by: null +approved_by: null +approved_at: null +phase: proposed +owners: [imdreamrunner] +affects_architecture: [] +affects_families: [] +affects_contributing: [] +affects_consumer_docs: [] +--- + +# React Native platform: Web (WebView and its modules) system spec + + + +## Intent + +An app shows web content inside a screen: a help page, a terms page, a sign-in +or payment page in place, an HTML document the app built, or a small web app +bundled with the app that works offline. The developer gets one web view that +is safe by default: links to other sites open in the system browser, the page +cannot reach the device's files or open pop-up windows, the page follows the +app's light or dark mode and text size, and the app and the page talk over one +message channel. The person sees the page as part of the screen, and a screen +reader reads the page's own content. + +This record details the `web` capability of `spec:AST-112`: the platform layer +and its opt-in capabilities (`spec:AST-112/FR1`, `spec:AST-112/FR3`), the +result vocabulary (`spec:AST-112/FR6`), the capability shape +(`spec:AST-112/FR7`), additive evolution (`spec:AST-112/FR8`), and Astryx +Stage (`spec:AST-112/FR12`). It specifies the native web view +(`AstryxWebView`) and its feature report (`AstryxWebViewInfo`), which the +library's `WebView` and `WebContent` use. The capability's other modules are +listed in "Who uses it" with their scope questions. + +## Why this exists + +| Piece | What the ecosystem already does well | Why Astryx owns it | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | react-native-webview is mature and widely used. It covers iOS, Android, macOS, and Windows, has a large API (injected scripts, `onShouldStartLoadWithRequest`, `postMessage`/`onMessage`, cookies, file access, downloads, incognito mode), and handles most apps' needs well. | The gaps are specific. A bundled folder served from a private origin with no network, plus a byte route from the page to the app, instead of file access. Origin and path pinning that holds across redirects, decided natively from declared data, not by a JavaScript callback per navigation. Per-view session handles whose cookies never cross as props, and a page-storage-off mode. A message event whose sender origin comes from the engine. Results with closed reasons, never a throw. One dependency set (`spec:AST-112/FR2`). Theme colour scheme and text size wired by the library. Astryx Stage parity. | +| `AstryxWebViewInfo` | react-native-webview reports no per-binary feature list; an app reads the package version. | An app and the library ask the binary whether it keeps a guarantee (page storage off, a bundled origin, a frame-safe channel) before they rely on it, so a missing guarantee refuses loudly instead of loading a weaker page (DEC-5). | +| `AstryxAuthSession` | expo-web-browser opens the system's authentication session (ASWebAuthenticationSession, Custom Tabs) and expo-auth-session builds OAuth on it, PKCE and discovery included. Both are well maintained. | The gap is narrow: results with closed reasons, no Expo runtime library (`spec:AST-112/FR11`), and a redirect URI per runtime. No Astryx component uses it (OQ4). | +| `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, `AstryxPageSnapshots` | react-native-webview shares or isolates cookies per app (`sharedCookiesEnabled`, `incognito`) and loads local files through file access. No common library draws an inert page snapshot. | They serve the web view's sessions, stores, bundled folders, and thumbnails. No Astryx component calls them; they are app API (OQ1, OQ2, OQ3, OQ5). | + +## Who uses it + +| Native piece | Kind | Astryx components that use it | What a person sees | +| --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | +| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | +| `AstryxWebSessions` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`). `WebView`'s `session={{sessionId}}` carries a handle the app created | A signed-in embedded page | +| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`) | Web pages that keep nothing after sign-out | +| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`, a `NativeWebView` with a `{bundle}` source) | A bundled web app that works offline and opens at once when warmed up | +| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component; app API through the library's `useAuthSession` hook and `./web` | The system's sign-in sheet | +| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`) | A thumbnail of an HTML document | + +Notes on the app-only modules (their contracts are outside this record): + +- `AstryxWebSessions` holds an embedded page's cookies, store, and pin natively + under an opaque handle that the view's `sessionId` prop names (FR8). +- `AstryxWebData` clears the runtime's shared web store and sets when it clears + itself. +- `AstryxWebBundles` registers bundled folders, answers the page's byte route, + and keeps a pool of warm pages; the view side is FR7. +- `AstryxAuthSession` runs web sign-in in the system's authentication session. +- `AstryxPageSnapshots` draws an HTML document inert in an offscreen web view + and writes a PNG to the app's file cache. + +## Non-goals + +- The contract of the library's `WebView` and `WebContent` components beyond + how they use the platform (FR15, FR16). Each component's own record and + `spec:AST-082/FR3` own it. +- The full contracts of `AstryxWebSessions`, `AstryxWebData`, + `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots` + (OQ1 to OQ5). +- The Astryx app's preview host and the policies it applies to a previewed + project's web views (its link gate, its client identity). +- Browser features the view does not offer: downloads, file upload pickers, + geolocation, WebRTC, pop-up windows, and pull-to-refresh. +- Equivalent internal implementations remain valid when they satisfy this + contract. +- Internal modules, files, function names, algorithms, data structures, storage + layouts, manifests, journals, locks, transaction protocols, and CI job/workflow + topology belong in architecture or implementation unless callers or + interoperating systems intentionally depend on that exact mechanism as a public + protocol. In that case, state who depends on it and why an equivalent + implementation would not satisfy the contract. + +## Requirements + +- **FR1 — `web` is an opt-in capability.** The web view and its modules belong + to the `web` capability, which an app opts in (`spec:AST-112/FR3`): opting in + links WebKit on iOS, and the AndroidX Browser library and the sign-in + redirect activity on Android. The `./web` entry exports `NativeWebView`, + `isNativeWebViewAvailable()`, `AstryxWebViewInfo`, and the app-only modules. + The library reaches the capability only through + `AstryxPlatform.capability('web')` (`spec:AST-112/FR2`). +- **FR2 — `NativeWebView` is the platform's web view.** Its props: + - `source`, one of `{uri}` (an http or https page), `{html, baseUrl?, +grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled + folder, FR7). + - Navigation: `allowedOrigins`, `externalNavigation`, `allowedExternalSchemes` + (FR5); sessions: `session` (FR8). + - Appearance and layout: `colorScheme`, `textScale`, `isScrollEnabled`, + `layerTypeAndroid` (`software` by default, or `hardware` for WebGL and + hardware video), `applicationNameForUserAgent`, and `userAgent` (FR10). + - `preventsCapture` and `linkMenu` with `onLinkMenuAction` (FR12); `warm` + (FR7); `reloadsOnContentProcessEnd` (FR11). + - Events, each with one object argument: `onLoadStart({url})`, + `onLoad({url, title})`, `onProgress({progress})` (0 to 1), + `onError(failure)`, `onContentHeight({height})`, `onMessage(event)`, + `onOpenExternal({url})`, `onNavigationBlocked({url, reason})`, and + `onContentProcessEnded(event)`. + - `ref`, a handle with `postMessage(data)` and `reload()`; `fallback`, drawn + where the view is absent (FR16); `style` and `testID`. + - With no allowed origins, every link a person follows to another origin + opens outside the view. +- **FR3 — The native contract.** + + | Contract | Kind | Props | Commands | Events | Platforms | + | --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | + | `AstryxWebView` | native component (Fabric Native Component) | `html`, `baseUrl`, `url`, `grantsOrigin`, `bundleName`, `bundlePath`, `warm`, `allowedOrigins`, `externalNavigation`, `allowedExternalSchemes`, `noExternalSchemes`, `pinnedOrigin`, `pinnedPathPrefix`, `sessionId`, `sessionCookies`, `ephemeral`, `allowsPageStorage`, `colorScheme`, `textScale`, `scrollEnabled`, `layerTypeAndroid`, `applicationNameForUserAgent`, `userAgent`, `preventsCapture`, `linkMenu`, `reloadsOnContentProcessEnd` | `postMessage`, `reload` | `onWebLoadStart`, `onWebLoad`, `onWebError`, `onWebProgress`, `onWebContentHeight`, `onWebMessage`, `onWebOpenExternal`, `onWebNavigationBlocked`, `onWebLinkMenuAction`, `onWebContentProcessEnded` | iOS, Android | + + | Contract | Kind | Methods | Platforms | + | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- | ------------ | + | `AstryxWebViewInfo` | native module (Turbo Native Module) | `getConstants()` (`version`, and the device's `channelIsolation` and `pageProfile` constants) | iOS, Android | + - The JavaScript maps its props onto the host's flat props and leaves absent + keys absent. An empty `allowedExternalSchemes` crosses as + `noExternalSchemes`, because codegen cannot tell an empty array from an + absent one. + +- **FR4 — Safe defaults.** The view has no file or content access, opens no + pop-up window, offers no geolocation, and blocks mixed content. A script at + document start in every frame removes WebRTC (`RTCPeerConnection` and + `navigator.mediaDevices`), turns DNS prefetching off, and removes + ``; on iOS the system's own switches for these are off + as well. The view injects no script besides this one and the message + channel's (FR9). There is no prop that injects JavaScript. +- **FR5 — Navigation follows declared policy, decided natively.** + - The first load and every main-frame navigation to the page's own origin + or to an origin in `allowedOrigins` stay in the view. Subresources and + frames follow the page's own rules. + - Any other main-frame navigation a person starts (a link, a form, + `target=_blank`, `window.open`) follows `externalNavigation`: `allow` (the + default) opens it in the system browser and sends `onOpenExternal`; + `report` opens nothing and sends `onNavigationBlocked` with `external` or + `newWindow`; `block` opens nothing and sends nothing. + - A non-web scheme opens outside the view only when it is in + `allowedExternalSchemes` (default `mailto`, `tel`, `sms`; an empty list + allows none). Any other scheme is cancelled and reported as + `onNavigationBlocked` with reason `scheme`. + - A pin (`session.pin`: `origin` and an optional `pathPrefix` of whole path + segments, default `/`) keeps every main-frame navigation, redirects + included, under that origin and path. Any other is cancelled and reported + with reason `pin`. + - The native view decides each navigation on the UI thread from these props. + No navigation waits on JavaScript; the events reach JavaScript after the + decision. +- **FR6 — An HTML string has an opaque origin unless granted one.** With + `{html}` the page has an opaque origin: no site's cookies or storage, and + relative links do not resolve. With `grantsOrigin: true` and an http or + https `baseUrl`, the page takes that origin. `html` wins over `url` when both + are set. +- **FR7 — Bundled folders load from a private origin with no network.** + - `{bundle: {name, path?}}` loads a folder the app's runtime registered with + `AstryxWebBundles` under `name` (a DNS label). The page is `path` (default + `/index.html`) under the bundle's origin: `astryx-bundle:///` on iOS, + an https origin on a host that never resolves on Android. + - Every file the page names loads from the folder. Nothing reaches a network, + and the view's store keeps nothing: no cookies, credentials, or client + identity. Requests under `/_app/` go to the app over `AstryxWebBundles`' + byte route. + - The bundle's origin is the view's only origin: `html`, `url`, `baseUrl`, + `grantsOrigin`, `ephemeral`, and `allowedOrigins` do not apply. A bundle + source with `session.pin` or session cookies, a name that is not a DNS + label, or a path with `..`, `.`, a hidden, or an empty segment loads + nothing and reports `invalid-config`. + - A bundle page needs a message channel that tells frames apart (FR9). Where + the device's channel cannot, nothing loads and `onError` reports + `unsupported`. + - Warm-up: with `warm`, a bundle view adopts a loaded page from + `AstryxWebBundles`' warm pool for its bundle and path on mount. It sends + `onLoad` at once and then the messages the page sent while it waited, in + order. A page is adopted by one view and never reused. With no page ready, + or with a custom user agent, page storage off, or session cookies, the view + loads its own page with no error. +- **FR8 — Sessions and page storage.** + - `session` is `{sessionId}` (a handle `AstryxWebSessions.create` answered) + or options: `isEphemeral`, `pin` (FR5), `allowsPageStorage`, and + `cookies`. A handle wins over the options. The view resolves the handle + natively, so the session's cookies never cross as props. An empty or + unknown handle loads nothing and reports `invalid-config`. + - `cookies` are set in the view's store before the page loads, each + HttpOnly, Secure, a session cookie, and host-only for the page's https + host. They require `isEphemeral`; new code passes a handle instead. + - `isEphemeral` gives the view a store of its own that keeps nothing: + iOS's non-persistent data store; on Android a throwaway profile whose + cookies, storage, and HTTP cache go when the view goes, with no Cache API + or service workers. It is fixed at the first render. + - `allowsPageStorage: false` gives the page no `localStorage`, + `sessionStorage`, IndexedDB, Cache API, or service workers, and its loads + do not read the HTTP cache; what a load writes to the HTTP cache goes when + the view goes. A change reloads the page. + - Views without an ephemeral store share the runtime's page store, which is + apart from the runtime's network cookie jar where the device can keep them + apart (the `pageProfile` constant: Android WebView with multiple profiles, + iOS 17 and later). Where it cannot, those views run with no page storage, + and clearing the page store never clears the app's network cookies. +- **FR9 — One message channel.** + - The page sends with `window.astryx.postMessage(string)`. The view accepts a + message only from the main frame of the page's own origin or an allowed + origin, and sends `onMessage({data, origin, isMainFrame})`. `origin` and + `isMainFrame` come from the engine, never from the page's data. + - The app sends with `ref.postMessage(data)` (the `postMessage` command). The + page receives it through `window.astryx.addListener` and as a `message` + event on `window` (`event.data`, a string). + - Where the device's channel cannot tell frames apart (an Android WebView + without document-start scripts and a message listener), the binary reports + `channelIsolation` false and the sender as `origin: "null"`, + `isMainFrame: false`. A strict app drops those messages. +- **FR10 — The page follows the app's appearance.** + - `colorScheme` (`light`, `dark`, or `system`) sets the page's + `prefers-color-scheme`: on iOS through the view's interface style, on + Android through the CSS `color-scheme` the page script sets, with + algorithmic darkening off. `NativeWebView` takes the platform appearance's + scheme when the prop is absent, else `system`. + - `textScale` (React Native's font scale; default 1) scales the page's text: + `-webkit-text-size-adjust` on iOS, `textZoom` on Android. + - `onContentHeight` reports the document's height in dp whenever it changes, + so a caller lays the page out at its height with `isScrollEnabled: false` + inside an outer scroll view. + - `applicationNameForUserAgent` is appended to the user agent, and + `userAgent` replaces it (and wins). Each takes printable ASCII only; + otherwise the view keeps the default and reports `invalid-config`. +- **FR11 — A content process end is reported, and the app picks the + recovery.** When the page's content process ends, the view sends + `onContentProcessEnded({reason, willReload, url})` with `reason` + `terminated`, `crashed`, `killed-for-memory`, or `unknown`. It is not a load + failure and never reaches `onError`. With `reloadsOnContentProcessEnd` true + (the default) the view loads the page again by itself; on Android it loads it + in a fresh engine view. With false, the view stays empty until + `ref.reload()` or a remount, so the screen shows its own card. A content + process end never ends the app. +- **FR12 — Capture prevention and the link menu.** + - `preventsCapture` keeps screenshots, screen recordings, and the recents + image out while the view is in a window (Android's `FLAG_SECURE`, counted + across views). iOS has no view-level equivalent: it ignores the prop and + does not report the feature. + - `linkMenu` describes the menu a long press on a link shows: actions + (`id`, `title`, an optional icon, `destructive`) with declarative matchers + (`schemes`, `hosts` with `*.` patterns that never match a public + suffix, and whole-segment `pathPrefix`), and a title of the link or none. + Only http, https, `mailto`, `tel`, and `sms` links get a menu; a matcher + narrows, never widens. Choosing an action sends + `onLinkMenuAction({id, href})`, and the view opens nothing. No link preview + is shown or loaded. A link no action fits gets no menu. `href` comes from + the page and is untrusted input. +- **FR13 — Loads report results in a closed set.** `onError` receives + `{ok: false, reason, message, url}` with `reason` from `offline`, `timeout`, + `ssl`, `invalid-url`, `invalid-config`, `unsupported`, `no-native-view`, and + `error`; a reason the JavaScript does not know reads `error` + (`spec:AST-112/FR6`). `message` never carries a URL's query or a cookie. The + JavaScript refuses a session or source it knows the view cannot honour before + anything crosses: it renders no host view and reports the reason once per + refusal and page. +- **FR14 — The binary reports what it honours.** + `AstryxWebViewInfo.isAvailable()`, `version()`, and `supports(feature)` + answer for this binary (`spec:AST-112/FR7`). The features are `session`, + `userAgent`, `hardening`, `externalNavigation`, `sessionHandle`, + `externalSchemes`, `grantsOrigin`, `channelIsolation`, `preventsCapture`, + `pageStorage`, `bundledOrigin`, `pageProfile`, `linkMenu`, `messageOrigin`, + `warmBundle`, and `contentProcessEnd`. + - A feature one platform implements answers false on the other: + `preventsCapture` on Android only; `linkMenu` and `warmBundle` on iOS only. + - `channelIsolation` and `pageProfile` also follow the device's constants + (FR8, FR9). + - Without the module (not opted in, Jest, the web), nothing is claimed. The + library's `useWebViewSupports(feature)` answers the same, and false without + a web view. +- **FR15 — The library's components wire the theme.** `WebView` renders + `NativeWebView` with the theme's mode as `colorScheme` and the theme's text + scale as `textScale`, and hands every event through unchanged, with stable + handlers so a parent's new callbacks never re-render the native view. It + passes the session, user agent, navigation, layer type, and content-process + props it receives. `WebContent` builds on `WebView`: `height: 'auto'` grows + to the page's height inside the screen's scroll view, `fill` takes the + parent's space and scrolls, a spinner shows until the first load ends, and a + failure line with Try again shows when the page does not load. +- **FR16 — Fallbacks when `web` is not linked or the view is absent.** + - Not opted in: the capability's module still loads; `isNativeWebViewAvailable()` + and `AstryxWebViewInfo.isAvailable()` answer false, and module calls + resolve `not-linked` (`spec:AST-112/FR3`). A missing view of an opted-in + capability reports `no-native-view`. + - `NativeWebView` where the view is absent renders `fallback` (nothing by + default) and reports `onError` with `no-native-view` once. + - `WebView` and `WebContent` where there is no web view (not opted in, Jest, + the web, or the platform switched off through the capabilities provider) + render their fallback: the page's text for `html`, or an "Open in browser" + button for `url` that opens the address through the app's link handling. + The region keeps its label. `postMessage` does nothing. + - `useAuthSession()` answers `isAvailable: false`, and its calls resolve + `no-module`. +- **FR17 — Accessibility.** `WebView` and `WebContent` take a required + `label`, the region's accessible name. Inside the region, VoiceOver and + TalkBack read the page's own content through the engine's accessibility + tree, and the platform adds nothing to it. The page's text follows the + system text size through `textScale` (FR10). `WebContent`'s loading and + failure states use the library's `Spinner`, `Text`, and `Button`, so they are + announced as those are. The link menu is the system's context menu. The + fallback's text and button are ordinary library content. +- **FR18 — Contract baseline.** Every contract in the group is at revision 1. + A behaviour added after revision 1 is a named feature + (`AstryxWebView.`) that the binary lists and the JavaScript checks + with `hasContractFeature` before it uses it. Without the feature the + JavaScript keeps the revision-1 behaviour or answers `unsupported`, never a + silent weaker path (DEC-5). Compatibility with Astryx Stage goes through the + library's Stage version floor: the package names the oldest Stage that + implements its contract set, and an older Stage refuses the project with the + gaps listed. + +### Platform support + +| Contract | iOS | Android | Astryx Stage | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AstryxWebView` | `WKWebView` (WebKit): `WKURLSchemeHandler` for bundled folders, `WKWebsiteDataStore` (non-persistent, or by identifier on iOS 17 and later) for stores, `WKUIDelegate` context menus for the link menu, a warm pool for bundle pages. `preventsCapture` ignored. | `android.webkit.WebView` with AndroidX WebKit: document-start scripts and a web message listener for the channel, profiles for stores, request interception for bundled folders, `FLAG_SECURE` for capture, `onRenderProcessGone` for a content process end (Android 8.0 and later). `linkMenu` and `warm` ignored. | On macOS, the system's `WKWebView`, with the device's navigation, session, page-storage, bundle, message, and content-process behaviour. `preventsCapture` ignored, as on iOS. | +| `AstryxWebViewInfo` | Reports `version` and the device constants; `channelIsolation` always true | Reports `version` and the device constants; `channelIsolation` false on a WebView without document-start scripts and a message listener; `pageProfile` false without multiple profiles | Reports what its web view implements | + +- FR18 gap: Astryx Stage renders `AstryxWebView` only on macOS; on Linux and + Windows the view reports absent, and `WebView` and `WebContent` draw their + fallback. +- FR18 gap: Astryx Stage keeps no warm pages: a `warm` bundle view loads its + own page, and Stage does not report `warmBundle`. +- Supported feature/engine floor: the floor of `spec:AST-112` (iOS at React + Native's minimum, Android API level 24, the New Architecture only), with the + system web engine the device carries. +- Unsupported behavior: a feature the binary lacks answers false from + `supports(feature)`, and a load that needs it refuses with `unsupported` + (FR13, FR14); a view the binary lacks reports itself unavailable and the + library draws its fallback (FR16). +- Browser evidence: none. Native claims are proven on the iOS Simulator, the + Android emulator, devices, and Astryx Stage (`spec:AST-112/FR15`). + +## Current-state impact + +- None beyond `spec:AST-112`. This record details its FR3 (the `web` + capability stays opt-in), FR6 (the web view's closed load reasons), FR7 (the + web view's probes and features), FR8 (the group's revision-1 baseline), and + FR12 (the web view in Astryx Stage). +- `spec:AST-093/FR5` (every native component is tested and validated the same + way) applies to `WebView` and `WebContent` unchanged. + +## Verification + +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader | `web` opted out; opted in | An opted-out app links WebKit or the redirect activity, or the library imports the capability outside its loader | +| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | +| FR3 | The platform's spec rules check; `contracts.json` against the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, or a shipped member changes | +| FR4 | Simulator and emulator checks with a hostile page; tests that keep the document-start scripts equal on every platform | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside an iframe | Any of them succeeds | +| FR5 | Simulator, emulator, and Astryx Stage scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason | +| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | +| FR7 | Unit tests of the refusals; Simulator, emulator, and Astryx Stage scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | +| FR8 | Unit tests of the session refusals; Simulator and emulator checks of stores | a handle; an empty handle; an ephemeral view; page storage off; a device without separate page profiles | A cookie crosses as a prop, an empty handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | +| FR9 | Unit tests through the doubles; Simulator, emulator, and Astryx Stage scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | +| FR10 | Simulator, emulator, and Astryx Stage renders | light, dark, and system schemes; text scale 1 and 2; auto height; a custom user agent | The page ignores the scheme or text scale, the height is stale, or a non-ASCII user agent is applied | +| FR11 | Device-level termination checks on the Simulator and emulator; Astryx Stage scripted process end | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | +| FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | +| FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | +| FR14 | Unit tests of `supports` per platform and device constant | each feature on iOS and Android; no module | A one-platform feature answers true on the other platform, or a device constant is ignored | +| FR15 | Library tests of `WebView` and `WebContent` | a theme change; a parent re-render; auto and fill heights; a failed load | The native view re-renders on a parent's new callback, or the scheme does not follow the theme | +| FR16 | Library and platform tests with the module absent, not linked, and switched off | `html` and `url` sources without a web view | A fallback is missing, `no-native-view` is reported more than once, or a call rejects | +| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings and links; the largest text size | The region has no name, the page's content is not read, or the text does not scale | +| FR18 | Contract baseline check; Astryx Stage contract suites; Stage version floor check | a binary without a named feature; an older Stage | The JavaScript uses a feature the binary does not list, or an older Stage runs the project | + +## Decision log + +### DEC-1 — Navigation policy is declared data the native view enforces + +**Reference:** `spec:AST-131/DEC-1` +**Decider:** imdreamrunner, 2026-11-17 + +Allowed origins, the pin, external navigation, and external schemes are props, +and the native view decides each navigation on the UI thread. A pin holds +across redirects, and no navigation waits on JavaScript or races a load. + +Rejected: a JavaScript callback per navigation, because it blocks the UI thread +or lets the load run ahead of the answer. + +### DEC-2 — One message channel; the sender comes from the engine + +**Reference:** `spec:AST-131/DEC-2` +**Decider:** imdreamrunner, 2026-11-17 + +The page and the app talk only through `window.astryx` and the `postMessage` +command. The view accepts only the main frame of the page's own or an allowed +origin, and reports the sender's origin from the engine, so a frame cannot +forge it. + +Rejected: an injected-script prop, because any script then runs with the +page's full rights and the channel's rules no longer hold. + +### DEC-3 — Sessions cross as native handles + +**Reference:** `spec:AST-131/DEC-3` +**Decider:** imdreamrunner, 2026-11-17 + +An embedded page's cookies, store, and pin are created natively once and +named by an opaque handle that the view's props carry. Cookie values never +appear in props, development tools, or logs. + +### DEC-4 — Bundled web content loads from a private origin + +**Reference:** `spec:AST-131/DEC-4` +**Decider:** imdreamrunner, 2026-11-17 + +A bundled folder loads from an origin of its own, with no network and a store +that keeps nothing; the page reads the app's data over a byte route the app +answers. The view keeps file access off on every path. + +Rejected: loading bundled files through file URLs, because the page would then +need file access. + +### DEC-5 — A guarantee the binary cannot keep refuses the load + +**Reference:** `spec:AST-131/DEC-5` +**Decider:** imdreamrunner, 2026-11-17 + +When a caller asks for a privacy or isolation guarantee (page storage off, a +bundled origin, a frame-safe channel) and the binary or device cannot keep it, +nothing loads and `onError` reports `unsupported`. A caller checks +`supports(feature)` first and picks its own path. + +Rejected: loading the page without the guarantee, because the person would see +a working page that leaks what the app meant to keep. + +## Open questions + +- **OQ1 — Does `AstryxWebSessions` stay in the `web` capability's public + scope when no Astryx component calls it?** (`human-api`) Options: keep it + public as the handle source for `WebView`'s `session`; or give `WebView` a + session option that creates and removes the handle itself. +- **OQ2 — Does `AstryxWebData` stay in this group's scope?** (`human-api`) + Options: keep it in `web` as app API; or move it to the core's storage and + sign-out surface. +- **OQ3 — Does `AstryxWebBundles` stay in this group's scope, and do + `WebView` and `WebContent` take a bundle source?** (`human-api`) Options: + app API through `NativeWebView` only; or a `bundle` prop on the library's + components. +- **OQ4 — Does `AstryxAuthSession` stay in the `web` capability when no + Astryx component uses it?** (`human-api`) Options: keep it beside the web + view with the `useAuthSession` hook; or make sign-in a capability of its + own. +- **OQ5 — Does `AstryxPageSnapshots` stay in this group's scope?** + (`human-api`) Options: keep it as app API in `web`; or remove it from the + public surface. +- **OQ6 — Do `WebView` and `WebContent` expose `preventsCapture`, + `linkMenu`, and `allowedExternalSchemes`, which only `NativeWebView` takes?** + (`human-api`) +- **OQ7 — Does Android build the link menu and warm pages, or do they stay + iOS-only features?** (`human-design`) +- **OQ8 — Does the page's `prefers-reduced-motion` follow the system's Reduce + Motion setting on both engines?** (`checkable`) From b3c5d61d0b6c8bea81e66459e4385bd1fefb7201 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:17:16 -0800 Subject: [PATCH 02/23] spec(AST-131): WebView depends on the session registry through the view --- .../AST-131-react-native-web-view/spec.md | 31 +++++++++++-------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index cd04678f577fc..6883a3d7c7621 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -47,19 +47,19 @@ listed in "Who uses it" with their scope questions. | `AstryxWebView` | react-native-webview is mature and widely used. It covers iOS, Android, macOS, and Windows, has a large API (injected scripts, `onShouldStartLoadWithRequest`, `postMessage`/`onMessage`, cookies, file access, downloads, incognito mode), and handles most apps' needs well. | The gaps are specific. A bundled folder served from a private origin with no network, plus a byte route from the page to the app, instead of file access. Origin and path pinning that holds across redirects, decided natively from declared data, not by a JavaScript callback per navigation. Per-view session handles whose cookies never cross as props, and a page-storage-off mode. A message event whose sender origin comes from the engine. Results with closed reasons, never a throw. One dependency set (`spec:AST-112/FR2`). Theme colour scheme and text size wired by the library. Astryx Stage parity. | | `AstryxWebViewInfo` | react-native-webview reports no per-binary feature list; an app reads the package version. | An app and the library ask the binary whether it keeps a guarantee (page storage off, a bundled origin, a frame-safe channel) before they rely on it, so a missing guarantee refuses loudly instead of loading a weaker page (DEC-5). | | `AstryxAuthSession` | expo-web-browser opens the system's authentication session (ASWebAuthenticationSession, Custom Tabs) and expo-auth-session builds OAuth on it, PKCE and discovery included. Both are well maintained. | The gap is narrow: results with closed reasons, no Expo runtime library (`spec:AST-112/FR11`), and a redirect URI per runtime. No Astryx component uses it (OQ4). | -| `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, `AstryxPageSnapshots` | react-native-webview shares or isolates cookies per app (`sharedCookiesEnabled`, `incognito`) and loads local files through file access. No common library draws an inert page snapshot. | They serve the web view's sessions, stores, bundled folders, and thumbnails. No Astryx component calls them; they are app API (OQ1, OQ2, OQ3, OQ5). | +| `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, `AstryxPageSnapshots` | react-native-webview shares or isolates cookies per app (`sharedCookiesEnabled`, `incognito`) and loads local files through file access. No common library draws an inert page snapshot. | They serve the web view's sessions, stores, bundled folders, and thumbnails. No Astryx component calls them; they are app API. `WebView` depends on one part of `AstryxWebSessions`: the view resolves its handles natively (FR8) (OQ1, OQ2, OQ3, OQ5). | ## Who uses it -| Native piece | Kind | Astryx components that use it | What a person sees | -| --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | -| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | -| `AstryxWebSessions` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`). `WebView`'s `session={{sessionId}}` carries a handle the app created | A signed-in embedded page | -| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`) | Web pages that keep nothing after sign-out | -| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`, a `NativeWebView` with a `{bundle}` source) | A bundled web app that works offline and opens at once when warmed up | -| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component; app API through the library's `useAuthSession` hook and `./web` | The system's sign-in sheet | -| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`) | A thumbnail of an HTML document | +| Native piece | Kind | Astryx components that use it | What a person sees | +| --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | +| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | +| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` (its `session={{sessionId}}` prop: the native view resolves the handle, FR8); no component calls the module; creating a handle is app API (`./web`) | A signed-in embedded page | +| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`) | Web pages that keep nothing after sign-out | +| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`, a `NativeWebView` with a `{bundle}` source) | A bundled web app that works offline and opens at once when warmed up | +| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component; app API through the library's `useAuthSession` hook and `./web` | The system's sign-in sheet | +| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`) | A thumbnail of an HTML document | Notes on the app-only modules (their contracts are outside this record): @@ -195,9 +195,14 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - **FR8 — Sessions and page storage.** - `session` is `{sessionId}` (a handle `AstryxWebSessions.create` answered) or options: `isEphemeral`, `pin` (FR5), `allowsPageStorage`, and - `cookies`. A handle wins over the options. The view resolves the handle - natively, so the session's cookies never cross as props. An empty or - unknown handle loads nothing and reports `invalid-config`. + `cookies`. A handle wins over the options. An empty or unknown handle + loads nothing and reports `invalid-config`. + - The part of `AstryxWebSessions` the view depends on: the view resolves a + handle natively, in the registry of the runtime that created it, so the + session's cookies never cross as props. The registered session supplies + the view's cookies, its ephemeral store, `allowsPageStorage`, and its pin. + The view resolves a handle once per value: a view that loaded with a + session keeps it after `AstryxWebSessions.remove`. - `cookies` are set in the view's store before the page loads, each HttpOnly, Secure, a session cookie, and host-only for the page's https host. They require `isEphemeral`; new code passes a handle instead. From 9975079fa71425350b3df12077d199c2879fea95 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:28:18 -0800 Subject: [PATCH 03/23] spec(AST-131): web view features are named; native code uses public API with one opt-in exception --- .../AST-131-react-native-web-view/spec.md | 50 ++++++++++++++----- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 6883a3d7c7621..5a4d2d06aa852 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -141,9 +141,8 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled pop-up window, offers no geolocation, and blocks mixed content. A script at document start in every frame removes WebRTC (`RTCPeerConnection` and `navigator.mediaDevices`), turns DNS prefetching off, and removes - ``; on iOS the system's own switches for these are off - as well. The view injects no script besides this one and the message - channel's (FR9). There is no prop that injects JavaScript. + ``. The view injects no script besides this one and the + message channel's (FR9). There is no prop that injects JavaScript. - **FR5 — Navigation follows declared policy, decided natively.** - The first load and every main-frame navigation to the page's own origin or to an origin in `allowedOrigins` stay in the view. Subresources and @@ -276,15 +275,21 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled JavaScript refuses a session or source it knows the view cannot honour before anything crosses: it renders no host view and reports the reason once per refusal and page. -- **FR14 — The binary reports what it honours.** - `AstryxWebViewInfo.isAvailable()`, `version()`, and `supports(feature)` - answer for this binary (`spec:AST-112/FR7`). The features are `session`, +- **FR14 — The web view's behaviour beyond the baseline is named features.** + `AstryxWebView`'s baseline is loading a page or an HTML string, the safe + defaults (FR4), navigation to the page's own and allowed origins, the + colour scheme, text scale, and content height (FR10), the message channel + without sender fields, and the load events (FR13). Every other behaviour is + a named contract feature, `AstryxWebView.`: `session`, `userAgent`, `hardening`, `externalNavigation`, `sessionHandle`, `externalSchemes`, `grantsOrigin`, `channelIsolation`, `preventsCapture`, `pageStorage`, `bundledOrigin`, `pageProfile`, `linkMenu`, `messageOrigin`, - `warmBundle`, and `contentProcessEnd`. - - A feature one platform implements answers false on the other: - `preventsCapture` on Android only; `linkMenu` and `warmBundle` on iOS only. + `warmBundle`, and `contentProcessEnd`. The binary of each platform lists the + features it implements (FR18); there are no counters. + - `AstryxWebViewInfo.isAvailable()` and `supports(feature)` answer from that + list for this binary (`spec:AST-112/FR7`). + - A feature one platform implements is listed only there: + `preventsCapture` on Android; `linkMenu` and `warmBundle` on iOS. - `channelIsolation` and `pageProfile` also follow the device's constants (FR8, FR9). - Without the module (not opted in, Jest, the web), nothing is claimed. The @@ -330,6 +335,17 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled library's Stage version floor: the package names the oldest Stage that implements its contract set, and an older Stage refuses the project with the gaps listed. +- **FR19 — Native code uses public platform API only.** The web view and its + modules use only the public API of WebKit, the Android SDK, and AndroidX. + One exception exists, and it is off by default: an app may opt in (the + configuration plugin's `web.privateHardening` option) to WebKit's private + preference switches that turn peer connections, media devices, and DNS + prefetching off in every frame on iOS. WebKit has no public setting for + them, so the switches are the only way to cover a frame the document-start + script cannot reach. The view uses each switch only when the running WebKit + answers to it, and the app that opts in takes the review risk of private + API. Without the opt-in, the document-start script is the layer on both + platforms. ### Platform support @@ -384,6 +400,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled | FR16 | Library and platform tests with the module absent, not linked, and switched off | `html` and `url` sources without a web view | A fallback is missing, `no-native-view` is reported more than once, or a call rejects | | FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings and links; the largest text size | The region has no name, the page's content is not read, or the text does not scale | | FR18 | Contract baseline check; Astryx Stage contract suites; Stage version floor check | a binary without a named feature; an older Stage | The JavaScript uses a feature the binary does not list, or an older Stage runs the project | +| FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | ## Decision log @@ -459,10 +476,12 @@ a working page that leaks what the app meant to keep. `WebView` and `WebContent` take a bundle source?** (`human-api`) Options: app API through `NativeWebView` only; or a `bundle` prop on the library's components. -- **OQ4 — Does `AstryxAuthSession` stay in the `web` capability when no - Astryx component uses it?** (`human-api`) Options: keep it beside the web - view with the `useAuthSession` hook; or make sign-in a capability of its - own. +- **OQ4 — Is web sign-in (`AstryxAuthSession`) an opt-in capability of its + own?** (`human-api`) It needs no embedded web view and no Astryx component + uses it. Options: keep it in `web` beside the web view with the + `useAuthSession` hook; or make sign-in its own opt-in, so an app that signs + in links no WebKit web view and an app with a web view links no redirect + activity. - **OQ5 — Does `AstryxPageSnapshots` stay in this group's scope?** (`human-api`) Options: keep it as app API in `web`; or remove it from the public surface. @@ -473,3 +492,8 @@ a working page that leaks what the app meant to keep. iOS-only features?** (`human-design`) - **OQ8 — Does the page's `prefers-reduced-motion` follow the system's Reduce Motion setting on both engines?** (`checkable`) +- **OQ9 — Does `AstryxWebViewInfo` fold into the platform info's named + features?** (`human-api`) Options: keep a web-view feature report in the + `web` capability; or list `AstryxWebView.` in the platform info's + contract features with every other contract, and keep `supports(feature)` + as a reader of that list. From 28cda491a39663491348663ff557dc8488a9d978 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:37:49 -0800 Subject: [PATCH 04/23] spec(AST-131): native contracts only, own wording, and the web modules as parts of the capability --- .../AST-131-react-native-web-view/spec.md | 249 +++++++++--------- 1 file changed, 124 insertions(+), 125 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 5a4d2d06aa852..d29ac3add78f6 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -38,30 +38,31 @@ result vocabulary (`spec:AST-112/FR6`), the capability shape Stage (`spec:AST-112/FR12`). It specifies the native web view (`AstryxWebView`) and its feature report (`AstryxWebViewInfo`), which the library's `WebView` and `WebContent` use. The capability's other modules are -listed in "Who uses it" with their scope questions. +part of the same platform package; "Who uses it" lists them, and each has its +own record. ## Why this exists -| Piece | What the ecosystem already does well | Why Astryx owns it | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | react-native-webview is mature and widely used. It covers iOS, Android, macOS, and Windows, has a large API (injected scripts, `onShouldStartLoadWithRequest`, `postMessage`/`onMessage`, cookies, file access, downloads, incognito mode), and handles most apps' needs well. | The gaps are specific. A bundled folder served from a private origin with no network, plus a byte route from the page to the app, instead of file access. Origin and path pinning that holds across redirects, decided natively from declared data, not by a JavaScript callback per navigation. Per-view session handles whose cookies never cross as props, and a page-storage-off mode. A message event whose sender origin comes from the engine. Results with closed reasons, never a throw. One dependency set (`spec:AST-112/FR2`). Theme colour scheme and text size wired by the library. Astryx Stage parity. | -| `AstryxWebViewInfo` | react-native-webview reports no per-binary feature list; an app reads the package version. | An app and the library ask the binary whether it keeps a guarantee (page storage off, a bundled origin, a frame-safe channel) before they rely on it, so a missing guarantee refuses loudly instead of loading a weaker page (DEC-5). | -| `AstryxAuthSession` | expo-web-browser opens the system's authentication session (ASWebAuthenticationSession, Custom Tabs) and expo-auth-session builds OAuth on it, PKCE and discovery included. Both are well maintained. | The gap is narrow: results with closed reasons, no Expo runtime library (`spec:AST-112/FR11`), and a redirect URI per runtime. No Astryx component uses it (OQ4). | -| `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, `AstryxPageSnapshots` | react-native-webview shares or isolates cookies per app (`sharedCookiesEnabled`, `incognito`) and loads local files through file access. No common library draws an inert page snapshot. | They serve the web view's sessions, stores, bundled folders, and thumbnails. No Astryx component calls them; they are app API. `WebView` depends on one part of `AstryxWebSessions`: the view resolves its handles natively (FR8) (OQ1, OQ2, OQ3, OQ5). | +| Piece | What the ecosystem already does well | Why Astryx owns it | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AstryxWebView` | react-native-webview is mature and widely used. It covers iOS, Android, macOS, and Windows, has a large API (injected scripts, `onShouldStartLoadWithRequest`, `postMessage`/`onMessage`, cookies, file access, downloads, incognito mode), and handles most apps' needs well. | The gaps are specific. A bundled folder served from a private origin with no network, plus a byte route from the page to the app, instead of file access. Origin and path pinning that holds across redirects, decided natively from declared data, not by a JavaScript callback per navigation. Per-view session handles whose cookies never appear in props, and a page-storage-off mode. A message event whose sender origin comes from the engine. Results with closed reasons, never a throw. One dependency set (`spec:AST-112/FR2`). Theme colour scheme and text size wired by the library. Astryx Stage parity. | +| `AstryxWebViewInfo` | react-native-webview reports no per-binary feature list; an app reads the package version. | An app and the library ask the binary whether it keeps a guarantee (page storage off, a bundled origin, a frame-safe channel) before they rely on it, so a missing guarantee refuses loudly instead of loading a weaker page (DEC-5). | +| `AstryxAuthSession` | expo-web-browser opens the system's authentication session (ASWebAuthenticationSession, Custom Tabs) and expo-auth-session builds OAuth on it, PKCE and discovery included. Both are well maintained. | The gap is narrow: results with closed reasons, no Expo runtime library (`spec:AST-112/FR11`), and a redirect URI per runtime. No Astryx component uses it (OQ3). | +| `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, `AstryxPageSnapshots` | react-native-webview shares or isolates cookies per app (`sharedCookiesEnabled`, `incognito`) and loads local files through file access. No common library draws an inert page snapshot. | They serve the web view's sessions, stores, bundled folders, and thumbnails. Each is part of the `web` capability with its own record. No Astryx component calls them; `WebView` depends on one part of `AstryxWebSessions`: the view resolves its handles natively (FR8). | ## Who uses it -| Native piece | Kind | Astryx components that use it | What a person sees | -| --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | -| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | -| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` (its `session={{sessionId}}` prop: the native view resolves the handle, FR8); no component calls the module; creating a handle is app API (`./web`) | A signed-in embedded page | -| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`) | Web pages that keep nothing after sign-out | -| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`, a `NativeWebView` with a `{bundle}` source) | A bundled web app that works offline and opens at once when warmed up | -| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component; app API through the library's `useAuthSession` hook and `./web` | The system's sign-in sheet | -| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component; app API only (`./web`) | A thumbnail of an HTML document | +| Native piece | Kind | Astryx components that use it | What a person sees | +| --------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | +| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | +| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` (its `session={{sessionId}}` prop: the native view resolves the handle, FR8); no component calls the module itself; part of the platform package's `web` capability, with its own record | A signed-in embedded page | +| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it; part of the platform package's `web` capability, with its own record | Web pages that keep nothing after sign-out | +| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it; part of the platform package's `web` capability, with its own record (a `NativeWebView` with a `{bundle}` source shows its folders) | A bundled web app that works offline and opens at once when warmed up | +| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it; the library's `useAuthSession` hook reaches it; part of the platform package's `web` capability, with its own record | The system's sign-in sheet | +| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it; part of the platform package's `web` capability, with its own record | A thumbnail of an HTML document | -Notes on the app-only modules (their contracts are outside this record): +Notes on the `web` capability's other modules, each part of the platform package with its own record: - `AstryxWebSessions` holds an embedded page's cookies, store, and pin natively under an opaque handle that the view's `sessionId` prop names (FR8). @@ -75,12 +76,12 @@ Notes on the app-only modules (their contracts are outside this record): ## Non-goals -- The contract of the library's `WebView` and `WebContent` components beyond - how they use the platform (FR15, FR16). Each component's own record and - `spec:AST-082/FR3` own it. +- The contract of the library's `WebView` and `WebContent` components: their + props, layout, loading and failure states, and fallback content. Each + component's own record and `spec:AST-082/FR3` own it. - The full contracts of `AstryxWebSessions`, `AstryxWebData`, - `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots` - (OQ1 to OQ5). + `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots`. Each is + part of the platform package's `web` capability and has its own record. - The Astryx app's preview host and the policies it applies to a previewed project's web views (its link gate, its client identity). - Browser features the view does not offer: downloads, file upload pickers, @@ -100,7 +101,8 @@ Notes on the app-only modules (their contracts are outside this record): to the `web` capability, which an app opts in (`spec:AST-112/FR3`): opting in links WebKit on iOS, and the AndroidX Browser library and the sign-in redirect activity on Android. The `./web` entry exports `NativeWebView`, - `isNativeWebViewAvailable()`, `AstryxWebViewInfo`, and the app-only modules. + `isNativeWebViewAvailable()`, `AstryxWebViewInfo`, and the capability's other + modules. The library reaches the capability only through `AstryxPlatform.capability('web')` (`spec:AST-112/FR2`). - **FR2 — `NativeWebView` is the platform's web view.** Its props: @@ -121,8 +123,8 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `onContentProcessEnded(event)`. - `ref`, a handle with `postMessage(data)` and `reload()`; `fallback`, drawn where the view is absent (FR16); `style` and `testID`. - - With no allowed origins, every link a person follows to another origin - opens outside the view. + - Without `allowedOrigins`, the view keeps only the first page's origin + (FR5). - **FR3 — The native contract.** | Contract | Kind | Props | Commands | Events | Platforms | @@ -133,22 +135,26 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- | ------------ | | `AstryxWebViewInfo` | native module (Turbo Native Module) | `getConstants()` (`version`, and the device's `channelIsolation` and `pageProfile` constants) | iOS, Android | - The JavaScript maps its props onto the host's flat props and leaves absent - keys absent. An empty `allowedExternalSchemes` crosses as - `noExternalSchemes`, because codegen cannot tell an empty array from an - absent one. - -- **FR4 — Safe defaults.** The view has no file or content access, opens no - pop-up window, offers no geolocation, and blocks mixed content. A script at - document start in every frame removes WebRTC (`RTCPeerConnection` and - `navigator.mediaDevices`), turns DNS prefetching off, and removes - ``. The view injects no script besides this one and the - message channel's (FR9). There is no prop that injects JavaScript. + keys absent. Codegen gives an absent array and an empty one the same + value, so an empty `allowedExternalSchemes` is sent as the separate + `noExternalSchemes` flag. + +- **FR4 — Safe defaults.** A page in the view cannot read local files or + content URIs, cannot open a second window, cannot ask for the device's + location, and cannot load http content into an https page. Before the + page's own script runs, a hardening script in each frame takes WebRTC + (`RTCPeerConnection`, `navigator.mediaDevices`) away from the page, stops + DNS prefetching, and strips the `preconnect` relation from links. Apart + from that script and the message channel's (FR9), the view adds no script + to a page, and no prop lets a caller add one. - **FR5 — Navigation follows declared policy, decided natively.** - - The first load and every main-frame navigation to the page's own origin - or to an origin in `allowedOrigins` stay in the view. Subresources and - frames follow the page's own rules. - - Any other main-frame navigation a person starts (a link, a form, - `target=_blank`, `window.open`) follows `externalNavigation`: `allow` (the + - The view shows the first page, and any top-level page on that page's + origin or on an origin listed in `allowedOrigins`. The policy covers + top-level navigation only; images, scripts, and frames load as the + page's own rules allow. + - A top-level navigation to any other origin that a person causes (tapping + a link, sending a form, a `target=_blank` link, `window.open`) follows + `externalNavigation`: `allow` (the default) opens it in the system browser and sends `onOpenExternal`; `report` opens nothing and sends `onNavigationBlocked` with `external` or `newWindow`; `block` opens nothing and sends nothing. @@ -156,10 +162,10 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `allowedExternalSchemes` (default `mailto`, `tel`, `sms`; an empty list allows none). Any other scheme is cancelled and reported as `onNavigationBlocked` with reason `scheme`. - - A pin (`session.pin`: `origin` and an optional `pathPrefix` of whole path - segments, default `/`) keeps every main-frame navigation, redirects - included, under that origin and path. Any other is cancelled and reported - with reason `pin`. + - A pin (`session.pin`: `origin`, and `pathPrefix` matched by whole path + segments, `/` when absent) limits every top-level navigation to that + origin and path, and a redirect counts as a navigation. The view stops a + navigation outside the pin and reports it with reason `pin`. - The native view decides each navigation on the UI thread from these props. No navigation waits on JavaScript; the events reach JavaScript after the decision. @@ -172,10 +178,11 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - `{bundle: {name, path?}}` loads a folder the app's runtime registered with `AstryxWebBundles` under `name` (a DNS label). The page is `path` (default `/index.html`) under the bundle's origin: `astryx-bundle:///` on iOS, - an https origin on a host that never resolves on Android. - - Every file the page names loads from the folder. Nothing reaches a network, - and the view's store keeps nothing: no cookies, credentials, or client - identity. Requests under `/_app/` go to the app over `AstryxWebBundles`' + on Android an https origin whose host is a reserved `.invalid` name that + no DNS lookup answers. + - The page and every file it references come from the folder, and no + request leaves the device. The view's store is discarded with the view, + and the page gets no cookies, credentials, or client identity. Requests under `/_app/` go to the app over `AstryxWebBundles`' byte route. - The bundle's origin is the view's only origin: `html`, `url`, `baseUrl`, `grantsOrigin`, `ephemeral`, and `allowedOrigins` do not apply. A bundle @@ -188,9 +195,10 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - Warm-up: with `warm`, a bundle view adopts a loaded page from `AstryxWebBundles`' warm pool for its bundle and path on mount. It sends `onLoad` at once and then the messages the page sent while it waited, in - order. A page is adopted by one view and never reused. With no page ready, - or with a custom user agent, page storage off, or session cookies, the view - loads its own page with no error. + order. Each warm page goes to at most one view. When the pool has no page + for it, or the view sets a custom user agent, turns page storage off, or + carries session cookies, the view loads the page itself and reports no + error. - **FR8 — Sessions and page storage.** - `session` is `{sessionId}` (a handle `AstryxWebSessions.create` answered) or options: `isEphemeral`, `pin` (FR5), `allowsPageStorage`, and @@ -198,17 +206,19 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled loads nothing and reports `invalid-config`. - The part of `AstryxWebSessions` the view depends on: the view resolves a handle natively, in the registry of the runtime that created it, so the - session's cookies never cross as props. The registered session supplies + session's cookie values are never part of the view's props. The registered session supplies the view's cookies, its ephemeral store, `allowsPageStorage`, and its pin. The view resolves a handle once per value: a view that loaded with a session keeps it after `AstryxWebSessions.remove`. - - `cookies` are set in the view's store before the page loads, each - HttpOnly, Secure, a session cookie, and host-only for the page's https - host. They require `isEphemeral`; new code passes a handle instead. - - `isEphemeral` gives the view a store of its own that keeps nothing: - iOS's non-persistent data store; on Android a throwaway profile whose - cookies, storage, and HTTP cache go when the view goes, with no Cache API - or service workers. It is fixed at the first render. + - `cookies` go into the view's store before the first request. Each one is + HttpOnly and Secure, has no expiry, and applies to the page's https host + alone. They need `isEphemeral`; a caller that has a handle uses it + instead. + - `isEphemeral` gives the view a private store that leaves no data behind: + a non-persistent data store on iOS; on Android a profile of its own whose + cookies, storage, and HTTP cache are deleted with the view, with no Cache + API or service workers. The view reads the option once, when it first + renders. - `allowsPageStorage: false` gives the page no `localStorage`, `sessionStorage`, IndexedDB, Cache API, or service workers, and its loads do not read the HTTP cache; what a load writes to the HTTP cache goes when @@ -229,12 +239,13 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - Where the device's channel cannot tell frames apart (an Android WebView without document-start scripts and a message listener), the binary reports `channelIsolation` false and the sender as `origin: "null"`, - `isMainFrame: false`. A strict app drops those messages. + `isMainFrame: false`. An app that must know the sender ignores those + messages. - **FR10 — The page follows the app's appearance.** - `colorScheme` (`light`, `dark`, or `system`) sets the page's `prefers-color-scheme`: on iOS through the view's interface style, on - Android through the CSS `color-scheme` the page script sets, with - algorithmic darkening off. `NativeWebView` takes the platform appearance's + Android by setting the document's CSS `color-scheme` and turning the + engine's automatic darkening off. `NativeWebView` takes the platform appearance's scheme when the prop is absent, else `system`. - `textScale` (React Native's font scale; default 1) scales the page's text: `-webkit-text-size-adjust` on iOS, `textZoom` on Android. @@ -242,17 +253,18 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled so a caller lays the page out at its height with `isScrollEnabled: false` inside an outer scroll view. - `applicationNameForUserAgent` is appended to the user agent, and - `userAgent` replaces it (and wins). Each takes printable ASCII only; - otherwise the view keeps the default and reports `invalid-config`. + `userAgent` replaces it (and wins over the appended name). A value with + anything other than printable ASCII is not applied: the default user agent + stays, and `onError` reports `invalid-config`. - **FR11 — A content process end is reported, and the app picks the recovery.** When the page's content process ends, the view sends `onContentProcessEnded({reason, willReload, url})` with `reason` - `terminated`, `crashed`, `killed-for-memory`, or `unknown`. It is not a load - failure and never reaches `onError`. With `reloadsOnContentProcessEnd` true - (the default) the view loads the page again by itself; on Android it loads it - in a fresh engine view. With false, the view stays empty until - `ref.reload()` or a remount, so the screen shows its own card. A content - process end never ends the app. + `terminated`, `crashed`, `killed-for-memory`, or `unknown`. `onError` does + not fire for it, because the page loaded. With `reloadsOnContentProcessEnd` + true (the default) the view reloads the page on its own; on Android it + creates a new engine view for the reload. With false, the view shows + nothing until the app calls `ref.reload()` or mounts it again, so the + screen can show its own message. The app keeps running in every case. - **FR12 — Capture prevention and the link menu.** - `preventsCapture` keeps screenshots, screen recordings, and the recents image out while the view is in a window (Android's `FLAG_SECURE`, counted @@ -262,19 +274,20 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled (`id`, `title`, an optional icon, `destructive`) with declarative matchers (`schemes`, `hosts` with `*.` patterns that never match a public suffix, and whole-segment `pathPrefix`), and a title of the link or none. - Only http, https, `mailto`, `tel`, and `sms` links get a menu; a matcher - narrows, never widens. Choosing an action sends - `onLinkMenuAction({id, href})`, and the view opens nothing. No link preview - is shown or loaded. A link no action fits gets no menu. `href` comes from - the page and is untrusted input. + A menu appears only for http, https, `mailto`, `tel`, and `sms` links; a + matcher can exclude links but cannot add a scheme. When a person picks an + action, the view sends `onLinkMenuAction({id, href})` and does not follow + the link. The menu never loads or shows a preview of the target. When no + action matches, the long press shows no menu. The page controls `href`, + so the app validates it before acting on it. - **FR13 — Loads report results in a closed set.** `onError` receives `{ok: false, reason, message, url}` with `reason` from `offline`, `timeout`, `ssl`, `invalid-url`, `invalid-config`, `unsupported`, `no-native-view`, and `error`; a reason the JavaScript does not know reads `error` (`spec:AST-112/FR6`). `message` never carries a URL's query or a cookie. The - JavaScript refuses a session or source it knows the view cannot honour before - anything crosses: it renders no host view and reports the reason once per - refusal and page. + JavaScript checks the session and the source first. When it knows the view + cannot honour them, it does not render the host view and reports the reason + through `onError` one time for that page. - **FR14 — The web view's behaviour beyond the baseline is named features.** `AstryxWebView`'s baseline is loading a page or an HTML string, the safe defaults (FR4), navigation to the page's own and allowed origins, the @@ -295,15 +308,11 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - Without the module (not opted in, Jest, the web), nothing is claimed. The library's `useWebViewSupports(feature)` answers the same, and false without a web view. -- **FR15 — The library's components wire the theme.** `WebView` renders - `NativeWebView` with the theme's mode as `colorScheme` and the theme's text - scale as `textScale`, and hands every event through unchanged, with stable - handlers so a parent's new callbacks never re-render the native view. It - passes the session, user agent, navigation, layer type, and content-process - props it receives. `WebContent` builds on `WebView`: `height: 'auto'` grows - to the page's height inside the screen's scroll view, `fill` takes the - parent's space and scrolls, a spinner shows until the first load ends, and a - failure line with Try again shows when the page does not load. +- **FR15 — The caller supplies the appearance.** `NativeWebView` has no + theme of its own. Its caller passes the colour scheme and text scale to use + (the library passes its theme's), and the view applies a new value to the + loaded page. The view's events are the same one-object shapes the library + hands to its own callers. - **FR16 — Fallbacks when `web` is not linked or the view is absent.** - Not opted in: the capability's module still loads; `isNativeWebViewAvailable()` and `AstryxWebViewInfo.isAvailable()` answer false, and module calls @@ -311,21 +320,18 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled capability reports `no-native-view`. - `NativeWebView` where the view is absent renders `fallback` (nothing by default) and reports `onError` with `no-native-view` once. - - `WebView` and `WebContent` where there is no web view (not opted in, Jest, - the web, or the platform switched off through the capabilities provider) - render their fallback: the page's text for `html`, or an "Open in browser" - button for `url` that opens the address through the app's link handling. - The region keeps its label. `postMessage` does nothing. + - Where there is no web view (not opted in, Jest, the web, or the platform + switched off through the capabilities provider), the library's components + draw their own fallback; their records own its content. The handle's + `postMessage` does nothing there. - `useAuthSession()` answers `isAvailable: false`, and its calls resolve `no-module`. -- **FR17 — Accessibility.** `WebView` and `WebContent` take a required - `label`, the region's accessible name. Inside the region, VoiceOver and - TalkBack read the page's own content through the engine's accessibility - tree, and the platform adds nothing to it. The page's text follows the - system text size through `textScale` (FR10). `WebContent`'s loading and - failure states use the library's `Spinner`, `Text`, and `Button`, so they are - announced as those are. The link menu is the system's context menu. The - fallback's text and button are ordinary library content. +- **FR17 — Accessibility.** The engine exposes the page's own structure + (headings, links, form fields, text) to VoiceOver and TalkBack, and the + platform neither adds to it nor hides it. The view has no accessible name of + its own: the caller names the region on a containing view (the library's + components require a label). The page's text follows the system text size + through `textScale` (FR10). The link menu is the system's context menu. - **FR18 — Contract baseline.** Every contract in the group is at revision 1. A behaviour added after revision 1 is a named feature (`AstryxWebView.`) that the binary lists and the JavaScript checks @@ -396,9 +402,9 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled | FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | | FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | | FR14 | Unit tests of `supports` per platform and device constant | each feature on iOS and Android; no module | A one-platform feature answers true on the other platform, or a device constant is ignored | -| FR15 | Library tests of `WebView` and `WebContent` | a theme change; a parent re-render; auto and fill heights; a failed load | The native view re-renders on a parent's new callback, or the scheme does not follow the theme | -| FR16 | Library and platform tests with the module absent, not linked, and switched off | `html` and `url` sources without a web view | A fallback is missing, `no-native-view` is reported more than once, or a call rejects | -| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings and links; the largest text size | The region has no name, the page's content is not read, or the text does not scale | +| FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | +| FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | +| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | | FR18 | Contract baseline check; Astryx Stage contract suites; Stage version floor check | a binary without a named feature; an older Stage | The JavaScript uses a feature the binary does not list, or an older Stage runs the project | | FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | @@ -443,9 +449,9 @@ appear in props, development tools, or logs. **Reference:** `spec:AST-131/DEC-4` **Decider:** imdreamrunner, 2026-11-17 -A bundled folder loads from an origin of its own, with no network and a store -that keeps nothing; the page reads the app's data over a byte route the app -answers. The view keeps file access off on every path. +A bundled folder loads from an origin of its own, with no network access and a +store that is discarded with the view; the page reads the app's data over a +byte route the app answers. The view keeps file access off on every path. Rejected: loading bundled files through file URLs, because the page would then need file access. @@ -465,34 +471,27 @@ a working page that leaks what the app meant to keep. ## Open questions -- **OQ1 — Does `AstryxWebSessions` stay in the `web` capability's public - scope when no Astryx component calls it?** (`human-api`) Options: keep it - public as the handle source for `WebView`'s `session`; or give `WebView` a - session option that creates and removes the handle itself. -- **OQ2 — Does `AstryxWebData` stay in this group's scope?** (`human-api`) - Options: keep it in `web` as app API; or move it to the core's storage and - sign-out surface. -- **OQ3 — Does `AstryxWebBundles` stay in this group's scope, and do - `WebView` and `WebContent` take a bundle source?** (`human-api`) Options: - app API through `NativeWebView` only; or a `bundle` prop on the library's - components. -- **OQ4 — Is web sign-in (`AstryxAuthSession`) an opt-in capability of its +- **OQ1 — Does `WebView` create and remove its session handle itself?** + (`human-api`) Options: the caller creates the handle with + `AstryxWebSessions` and passes `session={{sessionId}}`; or `WebView` takes + the session's options and manages the handle for the caller. +- **OQ2 — Do `WebView` and `WebContent` take a bundle source?** + (`human-api`) Options: bundled folders show only through `NativeWebView`; + or the library's components take a `bundle` source too. +- **OQ3 — Is web sign-in (`AstryxAuthSession`) an opt-in capability of its own?** (`human-api`) It needs no embedded web view and no Astryx component uses it. Options: keep it in `web` beside the web view with the `useAuthSession` hook; or make sign-in its own opt-in, so an app that signs in links no WebKit web view and an app with a web view links no redirect activity. -- **OQ5 — Does `AstryxPageSnapshots` stay in this group's scope?** - (`human-api`) Options: keep it as app API in `web`; or remove it from the - public surface. -- **OQ6 — Do `WebView` and `WebContent` expose `preventsCapture`, +- **OQ4 — Do `WebView` and `WebContent` expose `preventsCapture`, `linkMenu`, and `allowedExternalSchemes`, which only `NativeWebView` takes?** (`human-api`) -- **OQ7 — Does Android build the link menu and warm pages, or do they stay +- **OQ5 — Does Android build the link menu and warm pages, or do they stay iOS-only features?** (`human-design`) -- **OQ8 — Does the page's `prefers-reduced-motion` follow the system's Reduce +- **OQ6 — Does the page's `prefers-reduced-motion` follow the system's Reduce Motion setting on both engines?** (`checkable`) -- **OQ9 — Does `AstryxWebViewInfo` fold into the platform info's named +- **OQ7 — Does `AstryxWebViewInfo` fold into the platform info's named features?** (`human-api`) Options: keep a web-view feature report in the `web` capability; or list `AstryxWebView.` in the platform info's contract features with every other contract, and keep `supports(feature)` From adcf5a0457fd1b0854de1789090316ff52fd8e3c Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:12:30 -0800 Subject: [PATCH 05/23] spec(AST-131): Astryx Stage described by what it shows and refuses --- docs/specs/AST-131-react-native-web-view/spec.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index d29ac3add78f6..66c7ac5cf68b5 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -338,9 +338,9 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled with `hasContractFeature` before it uses it. Without the feature the JavaScript keeps the revision-1 behaviour or answers `unsupported`, never a silent weaker path (DEC-5). Compatibility with Astryx Stage goes through the - library's Stage version floor: the package names the oldest Stage that - implements its contract set, and an older Stage refuses the project with the - gaps listed. + library's Stage version floor: the package names the oldest Astryx Stage + that supports its contracts, and an older Stage refuses the project and + lists the contracts it lacks. - **FR19 — Native code uses public platform API only.** The web view and its modules use only the public API of WebKit, the Android SDK, and AndroidX. One exception exists, and it is off by default: an app may opt in (the @@ -355,10 +355,10 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled ### Platform support -| Contract | iOS | Android | Astryx Stage | -| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `AstryxWebView` | `WKWebView` (WebKit): `WKURLSchemeHandler` for bundled folders, `WKWebsiteDataStore` (non-persistent, or by identifier on iOS 17 and later) for stores, `WKUIDelegate` context menus for the link menu, a warm pool for bundle pages. `preventsCapture` ignored. | `android.webkit.WebView` with AndroidX WebKit: document-start scripts and a web message listener for the channel, profiles for stores, request interception for bundled folders, `FLAG_SECURE` for capture, `onRenderProcessGone` for a content process end (Android 8.0 and later). `linkMenu` and `warm` ignored. | On macOS, the system's `WKWebView`, with the device's navigation, session, page-storage, bundle, message, and content-process behaviour. `preventsCapture` ignored, as on iOS. | -| `AstryxWebViewInfo` | Reports `version` and the device constants; `channelIsolation` always true | Reports `version` and the device constants; `channelIsolation` false on a WebView without document-start scripts and a message listener; `pageProfile` false without multiple profiles | Reports what its web view implements | +| Contract | iOS | Android | Astryx Stage | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | `WKWebView` (WebKit): `WKURLSchemeHandler` for bundled folders, `WKWebsiteDataStore` (non-persistent, or by identifier on iOS 17 and later) for stores, `WKUIDelegate` context menus for the link menu, a warm pool for bundle pages. `preventsCapture` ignored. | `android.webkit.WebView` with AndroidX WebKit: document-start scripts and a web message listener for the channel, profiles for stores, request interception for bundled folders, `FLAG_SECURE` for capture, `onRenderProcessGone` for a content process end (Android 8.0 and later). `linkMenu` and `warm` ignored. | On macOS, shows the page in the system's web engine (WebKit) and behaves as the device does for navigation, sessions, page storage, bundled folders, messages, and content process end. Ignores `preventsCapture`, as iOS does. | +| `AstryxWebViewInfo` | Reports `version` and the device constants; `channelIsolation` always true | Reports `version` and the device constants; `channelIsolation` false on a WebView without document-start scripts and a message listener; `pageProfile` false without multiple profiles | Lists the web view features it shows | - FR18 gap: Astryx Stage renders `AstryxWebView` only on macOS; on Linux and Windows the view reports absent, and `WebView` and `WebContent` draw their @@ -405,7 +405,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled | FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | | FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | | FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | -| FR18 | Contract baseline check; Astryx Stage contract suites; Stage version floor check | a binary without a named feature; an older Stage | The JavaScript uses a feature the binary does not list, or an older Stage runs the project | +| FR18 | Contract baseline check; Astryx Stage contract checks; Stage version floor check | a binary without a named feature; an older Stage | The JavaScript uses a feature the binary does not list, or an older Stage runs the project | | FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | ## Decision log From 0369f4c5f67dd70146a17b431deefea197e1c34c Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:10:33 -0800 Subject: [PATCH 06/23] spec(AST-131): short rationale, named features through the platform info, textScale follows the system, Stage gaps under their own requirement --- .../AST-131-react-native-web-view/spec.md | 337 +++++++++--------- 1 file changed, 172 insertions(+), 165 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 66c7ac5cf68b5..5add0ecec8575 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -36,19 +36,31 @@ and its opt-in capabilities (`spec:AST-112/FR1`, `spec:AST-112/FR3`), the result vocabulary (`spec:AST-112/FR6`), the capability shape (`spec:AST-112/FR7`), additive evolution (`spec:AST-112/FR8`), and Astryx Stage (`spec:AST-112/FR12`). It specifies the native web view -(`AstryxWebView`) and its feature report (`AstryxWebViewInfo`), which the +(`AstryxWebView`) and its device report (`AstryxWebViewInfo`), which the library's `WebView` and `WebContent` use. The capability's other modules are part of the same platform package; "Who uses it" lists them, and each has its own record. ## Why this exists -| Piece | What the ecosystem already does well | Why Astryx owns it | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `AstryxWebView` | react-native-webview is mature and widely used. It covers iOS, Android, macOS, and Windows, has a large API (injected scripts, `onShouldStartLoadWithRequest`, `postMessage`/`onMessage`, cookies, file access, downloads, incognito mode), and handles most apps' needs well. | The gaps are specific. A bundled folder served from a private origin with no network, plus a byte route from the page to the app, instead of file access. Origin and path pinning that holds across redirects, decided natively from declared data, not by a JavaScript callback per navigation. Per-view session handles whose cookies never appear in props, and a page-storage-off mode. A message event whose sender origin comes from the engine. Results with closed reasons, never a throw. One dependency set (`spec:AST-112/FR2`). Theme colour scheme and text size wired by the library. Astryx Stage parity. | -| `AstryxWebViewInfo` | react-native-webview reports no per-binary feature list; an app reads the package version. | An app and the library ask the binary whether it keeps a guarantee (page storage off, a bundled origin, a frame-safe channel) before they rely on it, so a missing guarantee refuses loudly instead of loading a weaker page (DEC-5). | -| `AstryxAuthSession` | expo-web-browser opens the system's authentication session (ASWebAuthenticationSession, Custom Tabs) and expo-auth-session builds OAuth on it, PKCE and discovery included. Both are well maintained. | The gap is narrow: results with closed reasons, no Expo runtime library (`spec:AST-112/FR11`), and a redirect URI per runtime. No Astryx component uses it (OQ3). | -| `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, `AstryxPageSnapshots` | react-native-webview shares or isolates cookies per app (`sharedCookiesEnabled`, `incognito`) and loads local files through file access. No common library draws an inert page snapshot. | They serve the web view's sessions, stores, bundled folders, and thumbnails. Each is part of the `web` capability with its own record. No Astryx component calls them; `WebView` depends on one part of `AstryxWebSessions`: the view resolves its handles natively (FR8). | +- `AstryxWebView`: an app cannot add these guarantees from outside an + ecosystem web view component, so Astryx owns the view. A bundled folder + loads from a private origin with no network (FR7). A pin holds across + redirects and is decided natively (FR5, DEC-1). A session's cookie values + never appear in props (FR8, DEC-3). Pages can run with no storage (FR8). The + message sender comes from the engine (FR9, DEC-2). Loads report closed + reasons (FR13). The package keeps one dependency set (`spec:AST-112/FR2`), + and Astryx Stage shows the view as the device does (FR20). +- `AstryxWebViewInfo`: it answers what the device can keep (a frame-safe + channel, separate page data), so a caller that needs a guarantee is refused + loudly instead of getting a weaker page (DEC-5). OQ7 asks whether it folds + into the platform info. +- `AstryxAuthSession`: the gap is narrow: closed result reasons, no Expo + library (`spec:AST-112/FR11`), and a redirect URI per runtime. OQ3 asks + whether sign-in is its own opt-in. +- `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, and + `AstryxPageSnapshots` serve the web view's sessions, page data, bundled + folders, and thumbnails; each has its own record. ## Who uses it @@ -98,12 +110,11 @@ Notes on the `web` capability's other modules, each part of the platform package ## Requirements - **FR1 — `web` is an opt-in capability.** The web view and its modules belong - to the `web` capability, which an app opts in (`spec:AST-112/FR3`): opting in - links WebKit on iOS, and the AndroidX Browser library and the sign-in - redirect activity on Android. The `./web` entry exports `NativeWebView`, + to the `web` capability, which an app opts in (`spec:AST-112/FR3`). An app + that does not opt it in links no web engine and no sign-in redirect + handling. The `./web` entry exports `NativeWebView`, `isNativeWebViewAvailable()`, `AstryxWebViewInfo`, and the capability's other - modules. - The library reaches the capability only through + modules. The library reaches the capability only through `AstryxPlatform.capability('web')` (`spec:AST-112/FR2`). - **FR2 — `NativeWebView` is the platform's web view.** Its props: - `source`, one of `{uri}` (an http or https page), `{html, baseUrl?, @@ -127,26 +138,28 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled (FR5). - **FR3 — The native contract.** - | Contract | Kind | Props | Commands | Events | Platforms | - | --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | - | `AstryxWebView` | native component (Fabric Native Component) | `html`, `baseUrl`, `url`, `grantsOrigin`, `bundleName`, `bundlePath`, `warm`, `allowedOrigins`, `externalNavigation`, `allowedExternalSchemes`, `noExternalSchemes`, `pinnedOrigin`, `pinnedPathPrefix`, `sessionId`, `sessionCookies`, `ephemeral`, `allowsPageStorage`, `colorScheme`, `textScale`, `scrollEnabled`, `layerTypeAndroid`, `applicationNameForUserAgent`, `userAgent`, `preventsCapture`, `linkMenu`, `reloadsOnContentProcessEnd` | `postMessage`, `reload` | `onWebLoadStart`, `onWebLoad`, `onWebError`, `onWebProgress`, `onWebContentHeight`, `onWebMessage`, `onWebOpenExternal`, `onWebNavigationBlocked`, `onWebLinkMenuAction`, `onWebContentProcessEnded` | iOS, Android | + | Contract | Kind | Props | Commands | Events | Platforms | + | --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | + | `AstryxWebView` | native component (Fabric Native Component) | `html`, `baseUrl`, `url`, `grantsOrigin`, `bundleName`, `bundlePath`, `warm`, `allowedOrigins`, `externalNavigation`, `allowedExternalSchemes`, `noExternalSchemes`, `pinnedOrigin`, `pinnedPathPrefix`, `sessionId`, `ephemeral`, `allowsPageStorage`, `colorScheme`, `textScale`, `scrollEnabled`, `layerTypeAndroid`, `applicationNameForUserAgent`, `userAgent`, `preventsCapture`, `linkMenu`, `reloadsOnContentProcessEnd` | `postMessage`, `reload` | `onWebLoadStart`, `onWebLoad`, `onWebError`, `onWebProgress`, `onWebContentHeight`, `onWebMessage`, `onWebOpenExternal`, `onWebNavigationBlocked`, `onWebLinkMenuAction`, `onWebContentProcessEnded` | iOS, Android | - | Contract | Kind | Methods | Platforms | - | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- | ------------ | - | `AstryxWebViewInfo` | native module (Turbo Native Module) | `getConstants()` (`version`, and the device's `channelIsolation` and `pageProfile` constants) | iOS, Android | - - The JavaScript maps its props onto the host's flat props and leaves absent - keys absent. Codegen gives an absent array and an empty one the same - value, so an empty `allowedExternalSchemes` is sent as the separate - `noExternalSchemes` flag. + | Contract | Kind | Methods | Platforms | + | ------------------- | ----------------------------------- | -------------------------------------------------------------------------------------- | ------------ | + | `AstryxWebViewInfo` | native module (Turbo Native Module) | `getConstants()`: the device constants `channelIsolation` and `pageProfile` (FR8, FR9) | iOS, Android | + - `noExternalSchemes` is the host's form of an empty + `allowedExternalSchemes` (FR5). + - Both contracts are at revision 1. The web view's named features + (FR14) are listed with every other contract's by the platform info + module (`spec:AST-112/FR8`); `AstryxWebViewInfo` carries no feature list + and no revision counter. - **FR4 — Safe defaults.** A page in the view cannot read local files or content URIs, cannot open a second window, cannot ask for the device's location, and cannot load http content into an https page. Before the - page's own script runs, a hardening script in each frame takes WebRTC - (`RTCPeerConnection`, `navigator.mediaDevices`) away from the page, stops - DNS prefetching, and strips the `preconnect` relation from links. Apart - from that script and the message channel's (FR9), the view adds no script - to a page, and no prop lets a caller add one. + page's own script runs, each frame loses WebRTC (`RTCPeerConnection`, + `navigator.mediaDevices`), DNS prefetching, and the `preconnect` relation on + links. The view's only other script in a page is its own page script, which + carries the message channel (FR9), the colour scheme and text scale (FR10), + and the content height. No prop lets a caller add a script. - **FR5 — Navigation follows declared policy, decided natively.** - The view shows the first page, and any top-level page on that page's origin or on an origin listed in `allowedOrigins`. The policy covers @@ -154,10 +167,10 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled page's own rules allow. - A top-level navigation to any other origin that a person causes (tapping a link, sending a form, a `target=_blank` link, `window.open`) follows - `externalNavigation`: `allow` (the - default) opens it in the system browser and sends `onOpenExternal`; - `report` opens nothing and sends `onNavigationBlocked` with `external` or - `newWindow`; `block` opens nothing and sends nothing. + `externalNavigation`: `allow` (the default) opens it in the system browser + and sends `onOpenExternal`; `report` opens nothing and sends + `onNavigationBlocked` with `external` or `newWindow`; `block` opens + nothing and sends nothing. - A non-web scheme opens outside the view only when it is in `allowedExternalSchemes` (default `mailto`, `tel`, `sms`; an empty list allows none). Any other scheme is cancelled and reported as @@ -166,9 +179,8 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled segments, `/` when absent) limits every top-level navigation to that origin and path, and a redirect counts as a navigation. The view stops a navigation outside the pin and reports it with reason `pin`. - - The native view decides each navigation on the UI thread from these props. - No navigation waits on JavaScript; the events reach JavaScript after the - decision. + - No navigation waits on JavaScript: the view decides from these props, and + the events reach JavaScript after the decision. - **FR6 — An HTML string has an opaque origin unless granted one.** With `{html}` the page has an opaque origin: no site's cookies or storage, and relative links do not resolve. With `grantsOrigin: true` and an http or @@ -177,57 +189,50 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - **FR7 — Bundled folders load from a private origin with no network.** - `{bundle: {name, path?}}` loads a folder the app's runtime registered with `AstryxWebBundles` under `name` (a DNS label). The page is `path` (default - `/index.html`) under the bundle's origin: `astryx-bundle:///` on iOS, - on Android an https origin whose host is a reserved `.invalid` name that - no DNS lookup answers. + `/index.html`) under the bundle's origin, which the page reads as + `astryx-bundle://` on iOS and as an https origin on a reserved + `.invalid` host on Android. - The page and every file it references come from the folder, and no - request leaves the device. The view's store is discarded with the view, - and the page gets no cookies, credentials, or client identity. Requests under `/_app/` go to the app over `AstryxWebBundles`' - byte route. + request leaves the device. The page's storage is discarded with the + view, and the page gets no cookies, credentials, or client identity. + Requests under `/_app/` go to the app, which answers them through + `AstryxWebBundles`. - The bundle's origin is the view's only origin: `html`, `url`, `baseUrl`, `grantsOrigin`, `ephemeral`, and `allowedOrigins` do not apply. A bundle - source with `session.pin` or session cookies, a name that is not a DNS - label, or a path with `..`, `.`, a hidden, or an empty segment loads - nothing and reports `invalid-config`. + source with `session.pin`, a name that is not a DNS label, or a path with + `..`, `.`, a hidden, or an empty segment loads nothing and reports + `invalid-config`. - A bundle page needs a message channel that tells frames apart (FR9). Where - the device's channel cannot, nothing loads and `onError` reports - `unsupported`. - - Warm-up: with `warm`, a bundle view adopts a loaded page from - `AstryxWebBundles`' warm pool for its bundle and path on mount. It sends - `onLoad` at once and then the messages the page sent while it waited, in - order. Each warm page goes to at most one view. When the pool has no page - for it, or the view sets a custom user agent, turns page storage off, or - carries session cookies, the view loads the page itself and reports no - error. + the device cannot, nothing loads and `onError` reports `unsupported`. + - Warm-up: with `warm`, a bundle view shows a page that `AstryxWebBundles` + loaded ahead of time for its bundle and path. It sends `onLoad` at once, + then the messages that page sent before it appeared, in order. Each page + loaded ahead of time goes to at most one view. When none is ready, or the + view sets a custom user agent or turns page storage off, the view loads + the page itself and reports no error. - **FR8 — Sessions and page storage.** - `session` is `{sessionId}` (a handle `AstryxWebSessions.create` answered) - or options: `isEphemeral`, `pin` (FR5), `allowsPageStorage`, and - `cookies`. A handle wins over the options. An empty or unknown handle - loads nothing and reports `invalid-config`. - - The part of `AstryxWebSessions` the view depends on: the view resolves a - handle natively, in the registry of the runtime that created it, so the - session's cookie values are never part of the view's props. The registered session supplies - the view's cookies, its ephemeral store, `allowsPageStorage`, and its pin. - The view resolves a handle once per value: a view that loaded with a - session keeps it after `AstryxWebSessions.remove`. - - `cookies` go into the view's store before the first request. Each one is - HttpOnly and Secure, has no expiry, and applies to the page's https host - alone. They need `isEphemeral`; a caller that has a handle uses it - instead. + or options: `isEphemeral`, `pin` (FR5), and `allowsPageStorage`. A handle + wins over the options. An empty or unknown handle loads nothing and + reports `invalid-config`. + - The part of `AstryxWebSessions` the view depends on: a handle works only + in the runtime that created it, and the session's cookies, ephemeral + store, page-storage setting, and pin apply to the view without their + values appearing in its props. A view that loaded with a session keeps + it after `AstryxWebSessions.remove`. - `isEphemeral` gives the view a private store that leaves no data behind: - a non-persistent data store on iOS; on Android a profile of its own whose - cookies, storage, and HTTP cache are deleted with the view, with no Cache - API or service workers. The view reads the option once, when it first - renders. + its cookies, storage, and HTTP cache are gone when the view goes, and the + page has no Cache API or service workers. The view reads the option once, + when it first renders. - `allowsPageStorage: false` gives the page no `localStorage`, `sessionStorage`, IndexedDB, Cache API, or service workers, and its loads - do not read the HTTP cache; what a load writes to the HTTP cache goes when - the view goes. A change reloads the page. - - Views without an ephemeral store share the runtime's page store, which is - apart from the runtime's network cookie jar where the device can keep them - apart (the `pageProfile` constant: Android WebView with multiple profiles, - iOS 17 and later). Where it cannot, those views run with no page storage, - and clearing the page store never clears the app's network cookies. + do not use cached responses; what a load caches is gone when the view + goes. A change reloads the page. + - Pages in views without an ephemeral store share the runtime's page data. + Where the device can keep it apart from the app's network cookies (the + `pageProfile` constant), clearing page data never signs the app's own + requests out. Where it cannot, those pages run with no page storage, and + clearing page data still leaves the app's network cookies. - **FR9 — One message channel.** - The page sends with `window.astryx.postMessage(string)`. The view accepts a message only from the main frame of the page's own origin or an allowed @@ -236,19 +241,17 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - The app sends with `ref.postMessage(data)` (the `postMessage` command). The page receives it through `window.astryx.addListener` and as a `message` event on `window` (`event.data`, a string). - - Where the device's channel cannot tell frames apart (an Android WebView - without document-start scripts and a message listener), the binary reports + - Where the device's web engine cannot tell frames apart, the binary reports `channelIsolation` false and the sender as `origin: "null"`, `isMainFrame: false`. An app that must know the sender ignores those messages. - **FR10 — The page follows the app's appearance.** - - `colorScheme` (`light`, `dark`, or `system`) sets the page's - `prefers-color-scheme`: on iOS through the view's interface style, on - Android by setting the document's CSS `color-scheme` and turning the - engine's automatic darkening off. `NativeWebView` takes the platform appearance's - scheme when the prop is absent, else `system`. - - `textScale` (React Native's font scale; default 1) scales the page's text: - `-webkit-text-size-adjust` on iOS, `textZoom` on Android. + - `colorScheme` (`light`, `dark`, or `system`) sets what the page reads from + `prefers-color-scheme`, and the engine does not darken the page by + itself. Without the prop, `NativeWebView` takes the platform appearance's + scheme, else `system`. + - `textScale` scales the page's text. Without the prop, it is the system's + font scale, so the page's text follows the person's text size. - `onContentHeight` reports the document's height in dp whenever it changes, so a caller lays the page out at its height with `isScrollEnabled: false` inside an outer scroll view. @@ -261,15 +264,16 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `onContentProcessEnded({reason, willReload, url})` with `reason` `terminated`, `crashed`, `killed-for-memory`, or `unknown`. `onError` does not fire for it, because the page loaded. With `reloadsOnContentProcessEnd` - true (the default) the view reloads the page on its own; on Android it - creates a new engine view for the reload. With false, the view shows - nothing until the app calls `ref.reload()` or mounts it again, so the - screen can show its own message. The app keeps running in every case. + true (the default) the view reloads the page on its own. With false, the + view shows nothing until the app calls `ref.reload()` or mounts it again, so + the screen can show its own message. The app keeps running in every case. - **FR12 — Capture prevention and the link menu.** - - `preventsCapture` keeps screenshots, screen recordings, and the recents - image out while the view is in a window (Android's `FLAG_SECURE`, counted - across views). iOS has no view-level equivalent: it ignores the prop and - does not report the feature. + - `preventsCapture` keeps screenshots, screen recordings, and the app + switcher's image of the window out while the view is on screen, however + many views ask for it. iOS has no view-level equivalent: it ignores the + prop, shows the page, and does not list the feature, so capture + prevention there is best effort. A caller that requires it checks + `supports('preventsCapture')` first. - `linkMenu` describes the menu a long press on a link shows: actions (`id`, `title`, an optional icon, `destructive`) with declarative matchers (`schemes`, `hosts` with `*.` patterns that never match a public @@ -294,20 +298,19 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled colour scheme, text scale, and content height (FR10), the message channel without sender fields, and the load events (FR13). Every other behaviour is a named contract feature, `AstryxWebView.`: `session`, - `userAgent`, `hardening`, `externalNavigation`, `sessionHandle`, + `userAgent`, `externalNavigation`, `sessionHandle`, `externalSchemes`, `grantsOrigin`, `channelIsolation`, `preventsCapture`, `pageStorage`, `bundledOrigin`, `pageProfile`, `linkMenu`, `messageOrigin`, - `warmBundle`, and `contentProcessEnd`. The binary of each platform lists the - features it implements (FR18); there are no counters. - - `AstryxWebViewInfo.isAvailable()` and `supports(feature)` answer from that - list for this binary (`spec:AST-112/FR7`). - - A feature one platform implements is listed only there: - `preventsCapture` on Android; `linkMenu` and `warmBundle` on iOS. - - `channelIsolation` and `pageProfile` also follow the device's constants - (FR8, FR9). - - Without the module (not opted in, Jest, the web), nothing is claimed. The - library's `useWebViewSupports(feature)` answers the same, and false without - a web view. + `warmBundle`, and `contentProcessEnd` (`spec:AST-112/FR8`). + - The binary of each platform lists the features it implements. A feature + one platform implements is listed only there: `preventsCapture` on + Android; `linkMenu` and `warmBundle` on iOS. + - `AstryxWebViewInfo.supports(feature)` answers true when the binary lists + the feature and, for `channelIsolation` and `pageProfile`, the device's + constant is not false. `isAvailable()` answers whether the module is + linked. Without it (not opted in, Jest, the web), nothing is claimed. + - The library's `useWebViewSupports(feature)` answers the same, and false + without a web view. - **FR15 — The caller supplies the appearance.** `NativeWebView` has no theme of its own. Its caller passes the colour scheme and text scale to use (the library passes its theme's), and the view applies a new value to the @@ -324,47 +327,44 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled switched off through the capabilities provider), the library's components draw their own fallback; their records own its content. The handle's `postMessage` does nothing there. - - `useAuthSession()` answers `isAvailable: false`, and its calls resolve - `no-module`. - **FR17 — Accessibility.** The engine exposes the page's own structure (headings, links, form fields, text) to VoiceOver and TalkBack, and the platform neither adds to it nor hides it. The view has no accessible name of its own: the caller names the region on a containing view (the library's components require a label). The page's text follows the system text size through `textScale` (FR10). The link menu is the system's context menu. -- **FR18 — Contract baseline.** Every contract in the group is at revision 1. - A behaviour added after revision 1 is a named feature - (`AstryxWebView.`) that the binary lists and the JavaScript checks - with `hasContractFeature` before it uses it. Without the feature the - JavaScript keeps the revision-1 behaviour or answers `unsupported`, never a - silent weaker path (DEC-5). Compatibility with Astryx Stage goes through the - library's Stage version floor: the package names the oldest Astryx Stage - that supports its contracts, and an older Stage refuses the project and - lists the contracts it lacks. +- **FR18 — Contract baseline.** Every contract in the group is at revision 1 + (`spec:AST-112/FR8`). JavaScript checks a named feature (FR14) before it + uses the behaviour; without it, JavaScript keeps the revision-1 behaviour + or answers `unsupported`, never a silent weaker path (DEC-5). - **FR19 — Native code uses public platform API only.** The web view and its - modules use only the public API of WebKit, the Android SDK, and AndroidX. - One exception exists, and it is off by default: an app may opt in (the - configuration plugin's `web.privateHardening` option) to WebKit's private - preference switches that turn peer connections, media devices, and DNS - prefetching off in every frame on iOS. WebKit has no public setting for - them, so the switches are the only way to cover a frame the document-start - script cannot reach. The view uses each switch only when the running WebKit - answers to it, and the app that opts in takes the review risk of private - API. Without the opt-in, the document-start script is the layer on both - platforms. + modules use only public platform API (`spec:AST-112/FR4`). One exception + exists, and it is off by default: an app may opt in through its + configuration (`web.privateHardening`) to private WebKit settings that turn + peer connections, media devices, and DNS prefetching off in every frame on + iOS. WebKit has no public setting for them, and they cover frames that the + page-level protection of FR4 cannot reach. The view uses each setting only + when the running WebKit has it, and the app that opts in takes the review + risk of private API. Without the opt-in, FR4's protection is the same on + both platforms. +- **FR20 — Astryx Stage shows the web view as the device does.** Astryx + Stage answers every contract of this record as iOS and Android do + (`spec:AST-112/FR12`): navigation, sessions, page storage, bundled folders, + messages, and content process end. A project whose contracts or named + features the Stage lacks is refused by that Stage, which lists what it + lacks (the version floor of `spec:AST-112/FR12`). ### Platform support -| Contract | iOS | Android | Astryx Stage | -| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | `WKWebView` (WebKit): `WKURLSchemeHandler` for bundled folders, `WKWebsiteDataStore` (non-persistent, or by identifier on iOS 17 and later) for stores, `WKUIDelegate` context menus for the link menu, a warm pool for bundle pages. `preventsCapture` ignored. | `android.webkit.WebView` with AndroidX WebKit: document-start scripts and a web message listener for the channel, profiles for stores, request interception for bundled folders, `FLAG_SECURE` for capture, `onRenderProcessGone` for a content process end (Android 8.0 and later). `linkMenu` and `warm` ignored. | On macOS, shows the page in the system's web engine (WebKit) and behaves as the device does for navigation, sessions, page storage, bundled folders, messages, and content process end. Ignores `preventsCapture`, as iOS does. | -| `AstryxWebViewInfo` | Reports `version` and the device constants; `channelIsolation` always true | Reports `version` and the device constants; `channelIsolation` false on a WebView without document-start scripts and a message listener; `pageProfile` false without multiple profiles | Lists the web view features it shows | +| Contract | iOS | Android | Astryx Stage | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | WebKit (`WKWebView`). Every named feature except `preventsCapture`, which iOS ignores because it has no view-level capture protection. | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature except `linkMenu` and `warmBundle`, which Android ignores. A content process end is reported on Android 8.0 and later. | On macOS, shows the page in the system's web engine (WebKit) and behaves as the device does for navigation, sessions, page storage, bundled folders, messages, and content process end. Ignores `preventsCapture`, as iOS does. | +| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | Answers as the device it shows. | -- FR18 gap: Astryx Stage renders `AstryxWebView` only on macOS; on Linux and - Windows the view reports absent, and `WebView` and `WebContent` draw their - fallback. -- FR18 gap: Astryx Stage keeps no warm pages: a `warm` bundle view loads its - own page, and Stage does not report `warmBundle`. +- FR20 gap: Astryx Stage shows `AstryxWebView` only on macOS; on Linux and + Windows the view reports absent, and the library draws its fallback. +- FR20 gap: Astryx Stage loads no page ahead of time: a `warm` bundle view + loads its own page, and Stage does not list `warmBundle`. - Supported feature/engine floor: the floor of `spec:AST-112` (iOS at React Native's minimum, Android API level 24, the New Architecture only), with the system web engine the device carries. @@ -377,36 +377,43 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled ## Current-state impact -- None beyond `spec:AST-112`. This record details its FR3 (the `web` - capability stays opt-in), FR6 (the web view's closed load reasons), FR7 (the - web view's probes and features), FR8 (the group's revision-1 baseline), and - FR12 (the web view in Astryx Stage). +- Relies on `spec:AST-112` FR3 (amended): the `web` capability is a device + feature an app opts in; Astryx's components link by default. +- Relies on `spec:AST-112` FR4 (amended): native code uses public platform + API only, and a record names any exception (FR19). +- Relies on `spec:AST-112` FR8 (amended): every contract is at revision 1, + later behaviour is a named feature the platform info module lists, and no + contract carries a revision counter (FR3, FR14, FR18). +- Relies on `spec:AST-112` FR12 (amended): Astryx Stage matches the device, + and a Stage below the project's version floor refuses it and lists what it + lacks (FR20). - `spec:AST-093/FR5` (every native component is tested and validated the same way) applies to `WebView` and `WebContent` unchanged. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader | `web` opted out; opted in | An opted-out app links WebKit or the redirect activity, or the library imports the capability outside its loader | -| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | -| FR3 | The platform's spec rules check; `contracts.json` against the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, or a shipped member changes | -| FR4 | Simulator and emulator checks with a hostile page; tests that keep the document-start scripts equal on every platform | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside an iframe | Any of them succeeds | -| FR5 | Simulator, emulator, and Astryx Stage scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason | -| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | -| FR7 | Unit tests of the refusals; Simulator, emulator, and Astryx Stage scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | -| FR8 | Unit tests of the session refusals; Simulator and emulator checks of stores | a handle; an empty handle; an ephemeral view; page storage off; a device without separate page profiles | A cookie crosses as a prop, an empty handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | -| FR9 | Unit tests through the doubles; Simulator, emulator, and Astryx Stage scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | -| FR10 | Simulator, emulator, and Astryx Stage renders | light, dark, and system schemes; text scale 1 and 2; auto height; a custom user agent | The page ignores the scheme or text scale, the height is stale, or a non-ASCII user agent is applied | -| FR11 | Device-level termination checks on the Simulator and emulator; Astryx Stage scripted process end | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | -| FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | -| FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | -| FR14 | Unit tests of `supports` per platform and device constant | each feature on iOS and Android; no module | A one-platform feature answers true on the other platform, or a device constant is ignored | -| FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | -| FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | -| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | -| FR18 | Contract baseline check; Astryx Stage contract checks; Stage version floor check | a binary without a named feature; an older Stage | The JavaScript uses a feature the binary does not list, or an older Stage runs the project | -| FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader | `web` opted out; opted in | An opted-out app links WebKit or the redirect activity, or the library imports the capability outside its loader | +| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | +| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | +| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside an iframe | Any of them succeeds | +| FR5 | Simulator, emulator, and Astryx Stage scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason | +| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | +| FR7 | Unit tests of the refusals; Simulator, emulator, and Astryx Stage scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | +| FR8 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | +| FR9 | Unit tests through the doubles; Simulator, emulator, and Astryx Stage scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | +| FR10 | Simulator, emulator, and Astryx Stage renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | +| FR11 | Device-level termination checks on the Simulator and emulator; Astryx Stage scripted process end | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | +| FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | +| FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | +| FR14 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary does not list it, a one-platform feature is listed on the other platform, or a device constant is ignored | +| FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | +| FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | +| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | +| FR18 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | +| FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | +| FR20 | Astryx Stage contract checks beside the same scripts on the Simulator and emulator; Stage version floor check | each requirement of this record; a Stage below the floor | A Stage result differs from the device and is not a named gap, or a Stage below the floor runs the project | ## Decision log @@ -491,8 +498,8 @@ a working page that leaks what the app meant to keep. iOS-only features?** (`human-design`) - **OQ6 — Does the page's `prefers-reduced-motion` follow the system's Reduce Motion setting on both engines?** (`checkable`) -- **OQ7 — Does `AstryxWebViewInfo` fold into the platform info's named - features?** (`human-api`) Options: keep a web-view feature report in the - `web` capability; or list `AstryxWebView.` in the platform info's - contract features with every other contract, and keep `supports(feature)` - as a reader of that list. +- **OQ7 — Do the device constants of `AstryxWebViewInfo` move into the + platform info?** (`human-api`) The named features already live in the + platform info's list (FR3, FR18). Options: keep `AstryxWebViewInfo` for + `channelIsolation` and `pageProfile`; or report both through the platform + info and remove the module. From acbd7201eb97ccab542635572f56c22d100f2b3a Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:49:41 -0800 Subject: [PATCH 07/23] spec(AST-131): Astryx Stage and Preview move to their own record; the web record stays neutral --- .../AST-131-react-native-web-view/spec.md | 46 +++++++------------ 1 file changed, 16 insertions(+), 30 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 5add0ecec8575..758df9661b70e 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -34,8 +34,7 @@ reader reads the page's own content. This record details the `web` capability of `spec:AST-112`: the platform layer and its opt-in capabilities (`spec:AST-112/FR1`, `spec:AST-112/FR3`), the result vocabulary (`spec:AST-112/FR6`), the capability shape -(`spec:AST-112/FR7`), additive evolution (`spec:AST-112/FR8`), and Astryx -Stage (`spec:AST-112/FR12`). It specifies the native web view +(`spec:AST-112/FR7`), and additive evolution (`spec:AST-112/FR8`). It specifies the native web view (`AstryxWebView`) and its device report (`AstryxWebViewInfo`), which the library's `WebView` and `WebContent` use. The capability's other modules are part of the same platform package; "Who uses it" lists them, and each has its @@ -49,8 +48,9 @@ own record. redirects and is decided natively (FR5, DEC-1). A session's cookie values never appear in props (FR8, DEC-3). Pages can run with no storage (FR8). The message sender comes from the engine (FR9, DEC-2). Loads report closed - reasons (FR13). The package keeps one dependency set (`spec:AST-112/FR2`), - and Astryx Stage shows the view as the device does (FR20). + reasons (FR13). The package keeps one dependency set (`spec:AST-112/FR2`). + Astryx takes no third-party native dependency for the web view; an app may + use react-native-webview beside these components without conflict. - `AstryxWebViewInfo`: it answers what the device can keep (a frame-safe channel, separate page data), so a caller that needs a guarantee is refused loudly instead of getting a weaker page (DEC-5). OQ7 asks whether it folds @@ -94,8 +94,8 @@ Notes on the `web` capability's other modules, each part of the platform package - The full contracts of `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots`. Each is part of the platform package's `web` capability and has its own record. -- The Astryx app's preview host and the policies it applies to a previewed - project's web views (its link gate, its client identity). +- Astryx Stage and the Astryx app's Preview are specified in `spec:AST-139`; + they conform to this record's contracts. - Browser features the view does not offer: downloads, file upload pickers, geolocation, WebRTC, pop-up windows, and pull-to-refresh. - Equivalent internal implementations remain valid when they satisfy this @@ -347,24 +347,14 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled when the running WebKit has it, and the app that opts in takes the review risk of private API. Without the opt-in, FR4's protection is the same on both platforms. -- **FR20 — Astryx Stage shows the web view as the device does.** Astryx - Stage answers every contract of this record as iOS and Android do - (`spec:AST-112/FR12`): navigation, sessions, page storage, bundled folders, - messages, and content process end. A project whose contracts or named - features the Stage lacks is refused by that Stage, which lists what it - lacks (the version floor of `spec:AST-112/FR12`). ### Platform support -| Contract | iOS | Android | Astryx Stage | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | WebKit (`WKWebView`). Every named feature except `preventsCapture`, which iOS ignores because it has no view-level capture protection. | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature except `linkMenu` and `warmBundle`, which Android ignores. A content process end is reported on Android 8.0 and later. | On macOS, shows the page in the system's web engine (WebKit) and behaves as the device does for navigation, sessions, page storage, bundled folders, messages, and content process end. Ignores `preventsCapture`, as iOS does. | -| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | Answers as the device it shows. | +| Contract | iOS | Android | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AstryxWebView` | WebKit (`WKWebView`). Every named feature except `preventsCapture`, which iOS ignores because it has no view-level capture protection. | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature except `linkMenu` and `warmBundle`, which Android ignores. A content process end is reported on Android 8.0 and later. | +| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | -- FR20 gap: Astryx Stage shows `AstryxWebView` only on macOS; on Linux and - Windows the view reports absent, and the library draws its fallback. -- FR20 gap: Astryx Stage loads no page ahead of time: a `warm` bundle view - loads its own page, and Stage does not list `warmBundle`. - Supported feature/engine floor: the floor of `spec:AST-112` (iOS at React Native's minimum, Android API level 24, the New Architecture only), with the system web engine the device carries. @@ -373,7 +363,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled (FR13, FR14); a view the binary lacks reports itself unavailable and the library draws its fallback (FR16). - Browser evidence: none. Native claims are proven on the iOS Simulator, the - Android emulator, devices, and Astryx Stage (`spec:AST-112/FR15`). + Android emulator, and devices (`spec:AST-112/FR15`). ## Current-state impact @@ -384,9 +374,6 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - Relies on `spec:AST-112` FR8 (amended): every contract is at revision 1, later behaviour is a named feature the platform info module lists, and no contract carries a revision counter (FR3, FR14, FR18). -- Relies on `spec:AST-112` FR12 (amended): Astryx Stage matches the device, - and a Stage below the project's version floor refuses it and lists what it - lacks (FR20). - `spec:AST-093/FR5` (every native component is tested and validated the same way) applies to `WebView` and `WebContent` unchanged. @@ -398,13 +385,13 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled | FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | | FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | | FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside an iframe | Any of them succeeds | -| FR5 | Simulator, emulator, and Astryx Stage scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason | +| FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason | | FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | -| FR7 | Unit tests of the refusals; Simulator, emulator, and Astryx Stage scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | +| FR7 | Unit tests of the refusals; Simulator and emulator scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | | FR8 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | -| FR9 | Unit tests through the doubles; Simulator, emulator, and Astryx Stage scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | -| FR10 | Simulator, emulator, and Astryx Stage renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | -| FR11 | Device-level termination checks on the Simulator and emulator; Astryx Stage scripted process end | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | +| FR9 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | +| FR10 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | +| FR11 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | | FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | | FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | | FR14 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary does not list it, a one-platform feature is listed on the other platform, or a device constant is ignored | @@ -413,7 +400,6 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled | FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | | FR18 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | | FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | -| FR20 | Astryx Stage contract checks beside the same scripts on the Simulator and emulator; Stage version floor check | each requirement of this record; a Stage below the floor | A Stage result differs from the device and is not a named gap, or a Stage below the floor runs the project | ## Decision log From 48ea2eff61e7f1e054f0195503e091058cf10f6b Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:04:51 -0800 Subject: [PATCH 08/23] spec(AST-131): cite the shared platform rules of AST-140 --- .../AST-131-react-native-web-view/spec.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 758df9661b70e..aa3579bc94190 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -32,9 +32,10 @@ message channel. The person sees the page as part of the screen, and a screen reader reads the page's own content. This record details the `web` capability of `spec:AST-112`: the platform layer -and its opt-in capabilities (`spec:AST-112/FR1`, `spec:AST-112/FR3`), the -result vocabulary (`spec:AST-112/FR6`), the capability shape -(`spec:AST-112/FR7`), and additive evolution (`spec:AST-112/FR8`). It specifies the native web view +and its opt-in capabilities (`spec:AST-112/FR1`, `spec:AST-112/FR3`), and +the capability shape (`spec:AST-112/FR7`). It follows the shared platform rules +of `spec:AST-140`: the result vocabulary (`spec:AST-140/FR3`) and additive +evolution (`spec:AST-140/FR5`). It specifies the native web view (`AstryxWebView`) and its device report (`AstryxWebViewInfo`), which the library's `WebView` and `WebContent` use. The capability's other modules are part of the same platform package; "Who uses it" lists them, and each has its @@ -50,7 +51,8 @@ own record. message sender comes from the engine (FR9, DEC-2). Loads report closed reasons (FR13). The package keeps one dependency set (`spec:AST-112/FR2`). Astryx takes no third-party native dependency for the web view; an app may - use react-native-webview beside these components without conflict. + use react-native-webview beside these components without conflict + (`spec:AST-140/FR9`). - `AstryxWebViewInfo`: it answers what the device can keep (a frame-safe channel, separate page data), so a caller that needs a guarantee is refused loudly instead of getting a weaker page (DEC-5). OQ7 asks whether it folds @@ -149,7 +151,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `allowedExternalSchemes` (FR5). - Both contracts are at revision 1. The web view's named features (FR14) are listed with every other contract's by the platform info - module (`spec:AST-112/FR8`); `AstryxWebViewInfo` carries no feature list + module (`spec:AST-140/FR5`); `AstryxWebViewInfo` carries no feature list and no revision counter. - **FR4 — Safe defaults.** A page in the view cannot read local files or @@ -288,7 +290,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `{ok: false, reason, message, url}` with `reason` from `offline`, `timeout`, `ssl`, `invalid-url`, `invalid-config`, `unsupported`, `no-native-view`, and `error`; a reason the JavaScript does not know reads `error` - (`spec:AST-112/FR6`). `message` never carries a URL's query or a cookie. The + (`spec:AST-140/FR3`). `message` never carries a URL's query or a cookie. The JavaScript checks the session and the source first. When it knows the view cannot honour them, it does not render the host view and reports the reason through `onError` one time for that page. @@ -301,7 +303,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `userAgent`, `externalNavigation`, `sessionHandle`, `externalSchemes`, `grantsOrigin`, `channelIsolation`, `preventsCapture`, `pageStorage`, `bundledOrigin`, `pageProfile`, `linkMenu`, `messageOrigin`, - `warmBundle`, and `contentProcessEnd` (`spec:AST-112/FR8`). + `warmBundle`, and `contentProcessEnd` (`spec:AST-140/FR5`). - The binary of each platform lists the features it implements. A feature one platform implements is listed only there: `preventsCapture` on Android; `linkMenu` and `warmBundle` on iOS. @@ -319,7 +321,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - **FR16 — Fallbacks when `web` is not linked or the view is absent.** - Not opted in: the capability's module still loads; `isNativeWebViewAvailable()` and `AstryxWebViewInfo.isAvailable()` answer false, and module calls - resolve `not-linked` (`spec:AST-112/FR3`). A missing view of an opted-in + resolve `not-linked` (`spec:AST-112/FR3`, `spec:AST-140/FR2`). A missing view of an opted-in capability reports `no-native-view`. - `NativeWebView` where the view is absent renders `fallback` (nothing by default) and reports `onError` with `no-native-view` once. @@ -334,7 +336,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled components require a label). The page's text follows the system text size through `textScale` (FR10). The link menu is the system's context menu. - **FR18 — Contract baseline.** Every contract in the group is at revision 1 - (`spec:AST-112/FR8`). JavaScript checks a named feature (FR14) before it + (`spec:AST-140/FR5`). JavaScript checks a named feature (FR14) before it uses the behaviour; without it, JavaScript keeps the revision-1 behaviour or answers `unsupported`, never a silent weaker path (DEC-5). - **FR19 — Native code uses public platform API only.** The web view and its @@ -371,7 +373,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled feature an app opts in; Astryx's components link by default. - Relies on `spec:AST-112` FR4 (amended): native code uses public platform API only, and a record names any exception (FR19). -- Relies on `spec:AST-112` FR8 (amended): every contract is at revision 1, +- Relies on `spec:AST-140` FR5: every contract is at revision 1, later behaviour is a named feature the platform info module lists, and no contract carries a revision counter (FR3, FR14, FR18). - `spec:AST-093/FR5` (every native component is tested and validated the same From cd3412012e34fefff7ad9a25cf439005940341ce Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:19:48 -0800 Subject: [PATCH 09/23] spec(AST-131): Astryx Stage and Preview are separate products with their own records --- docs/specs/AST-131-react-native-web-view/spec.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index aa3579bc94190..09d09abbbf75a 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -96,8 +96,7 @@ Notes on the `web` capability's other modules, each part of the platform package - The full contracts of `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots`. Each is part of the platform package's `web` capability and has its own record. -- Astryx Stage and the Astryx app's Preview are specified in `spec:AST-139`; - they conform to this record's contracts. +- Astryx Stage (`spec:AST-139`) and Preview in the Astryx app (`spec:AST-141`) are separate products; they conform to this record's contracts. - Browser features the view does not offer: downloads, file upload pickers, geolocation, WebRTC, pop-up windows, and pull-to-refresh. - Equivalent internal implementations remain valid when they satisfy this From ae974a8f368491ea27c5303f284b9f4ffe625116 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:23:20 -0800 Subject: [PATCH 10/23] spec(AST-131): the web modules no Astryx component uses are outside the core package --- .../AST-131-react-native-web-view/spec.md | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 09d09abbbf75a..80673bc05d380 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -38,8 +38,7 @@ of `spec:AST-140`: the result vocabulary (`spec:AST-140/FR3`) and additive evolution (`spec:AST-140/FR5`). It specifies the native web view (`AstryxWebView`) and its device report (`AstryxWebViewInfo`), which the library's `WebView` and `WebContent` use. The capability's other modules are -part of the same platform package; "Who uses it" lists them, and each has its -own record. +outside the core package, because no Astryx component uses them; "Who uses it" lists them. ## Why this exists @@ -62,21 +61,21 @@ own record. whether sign-in is its own opt-in. - `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, and `AstryxPageSnapshots` serve the web view's sessions, page data, bundled - folders, and thumbnails; each has its own record. + folders, and thumbnails; they are outside the core package, because no Astryx component uses them. ## Who uses it -| Native piece | Kind | Astryx components that use it | What a person sees | -| --------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | -| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | -| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` (its `session={{sessionId}}` prop: the native view resolves the handle, FR8); no component calls the module itself; part of the platform package's `web` capability, with its own record | A signed-in embedded page | -| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it; part of the platform package's `web` capability, with its own record | Web pages that keep nothing after sign-out | -| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it; part of the platform package's `web` capability, with its own record (a `NativeWebView` with a `{bundle}` source shows its folders) | A bundled web app that works offline and opens at once when warmed up | -| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it; the library's `useAuthSession` hook reaches it; part of the platform package's `web` capability, with its own record | The system's sign-in sheet | -| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it; part of the platform package's `web` capability, with its own record | A thumbnail of an HTML document | +| Native piece | Kind | Astryx components that use it | What a person sees | +| --------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | +| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | +| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` carries its handle (`session={{sessionId}}`, FR8), and the native view resolves it; no component calls the module itself, so the module is outside the core package | A signed-in embedded page | +| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | Web pages that keep nothing after sign-out | +| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package (a `NativeWebView` with a `{bundle}` source shows its folders) | A bundled web app that works offline and opens at once when warmed up | +| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it (the library's `useAuthSession` hook reaches it), so it is outside the core package | The system's sign-in sheet | +| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | A thumbnail of an HTML document | -Notes on the `web` capability's other modules, each part of the platform package with its own record: +Notes on the `web` capability's other modules, which are outside the core package, because no Astryx component uses them: - `AstryxWebSessions` holds an embedded page's cookies, store, and pin natively under an opaque handle that the view's `sessionId` prop names (FR8). @@ -94,8 +93,8 @@ Notes on the `web` capability's other modules, each part of the platform package props, layout, loading and failure states, and fallback content. Each component's own record and `spec:AST-082/FR3` own it. - The full contracts of `AstryxWebSessions`, `AstryxWebData`, - `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots`. Each is - part of the platform package's `web` capability and has its own record. + `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots`. They + are outside the core package, because no Astryx component uses them. - Astryx Stage (`spec:AST-139`) and Preview in the Astryx app (`spec:AST-141`) are separate products; they conform to this record's contracts. - Browser features the view does not offer: downloads, file upload pickers, geolocation, WebRTC, pop-up windows, and pull-to-refresh. From ce93babf03ab976c579de4956ad3a3e4a06e27e8 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:25:06 -0800 Subject: [PATCH 11/23] spec(AST-131): the session registry stays core; four web modules are outside the core package --- .../AST-131-react-native-web-view/spec.md | 55 +++++++++++-------- 1 file changed, 32 insertions(+), 23 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 80673bc05d380..63db28e0bba25 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -36,9 +36,10 @@ and its opt-in capabilities (`spec:AST-112/FR1`, `spec:AST-112/FR3`), and the capability shape (`spec:AST-112/FR7`). It follows the shared platform rules of `spec:AST-140`: the result vocabulary (`spec:AST-140/FR3`) and additive evolution (`spec:AST-140/FR5`). It specifies the native web view -(`AstryxWebView`) and its device report (`AstryxWebViewInfo`), which the -library's `WebView` and `WebContent` use. The capability's other modules are -outside the core package, because no Astryx component uses them; "Who uses it" lists them. +(`AstryxWebView`), its device report (`AstryxWebViewInfo`), and the part of +the session registry (`AstryxWebSessions`) the view depends on, which the +library's `WebView` and `WebContent` use; the three are core, within the +opt-in `web` capability. The capability's four other modules are outside the core package, because no Astryx component uses them; "Who uses it" lists them. ## Why this exists @@ -59,26 +60,30 @@ outside the core package, because no Astryx component uses them; "Who uses it" l - `AstryxAuthSession`: the gap is narrow: closed result reasons, no Expo library (`spec:AST-112/FR11`), and a redirect URI per runtime. OQ3 asks whether sign-in is its own opt-in. -- `AstryxWebSessions`, `AstryxWebData`, `AstryxWebBundles`, and - `AstryxPageSnapshots` serve the web view's sessions, page data, bundled - folders, and thumbnails; they are outside the core package, because no Astryx component uses them. +- `AstryxWebSessions`: it holds an embedded page's session natively, so + `WebView` passes a handle instead of cookie values (FR8, DEC-3). OQ8 asks + whether its create and remove calls belong in this record. +- `AstryxWebData`, `AstryxWebBundles`, and `AstryxPageSnapshots` serve the + web view's page data, bundled folders, and thumbnails; they are outside the core package, because no Astryx component uses them. ## Who uses it -| Native piece | Kind | Astryx components that use it | What a person sees | -| --------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | -| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | -| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` carries its handle (`session={{sessionId}}`, FR8), and the native view resolves it; no component calls the module itself, so the module is outside the core package | A signed-in embedded page | -| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | Web pages that keep nothing after sign-out | -| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package (a `NativeWebView` with a `{bundle}` source shows its folders) | A bundled web app that works offline and opens at once when warmed up | -| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it (the library's `useAuthSession` hook reaches it), so it is outside the core package | The system's sign-in sheet | -| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | A thumbnail of an HTML document | - -Notes on the `web` capability's other modules, which are outside the core package, because no Astryx component uses them: - -- `AstryxWebSessions` holds an embedded page's cookies, store, and pin natively - under an opaque handle that the view's `sessionId` prop names (FR8). +| Native piece | Kind | Astryx components that use it | What a person sees | +| --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | +| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | +| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` uses it through its session handle (`session={{sessionId}}`, FR8): the native view resolves the handle; core, within the `web` capability | A signed-in embedded page | +| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | Web pages that keep nothing after sign-out | +| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package (a `NativeWebView` with a `{bundle}` source shows its folders) | A bundled web app that works offline and opens at once when warmed up | +| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it (the library's `useAuthSession` hook reaches it), so it is outside the core package | The system's sign-in sheet | +| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | A thumbnail of an HTML document | + +Notes on the `web` capability's other modules: + +- `AstryxWebSessions` (core) holds an embedded page's cookies, store, and pin + natively under an opaque handle that the view's `sessionId` prop names + (FR8). +- The four below are outside the core package, because no Astryx component uses them. - `AstryxWebData` clears the runtime's shared web store and sets when it clears itself. - `AstryxWebBundles` registers bundled folders, answers the page's byte route, @@ -92,9 +97,9 @@ Notes on the `web` capability's other modules, which are outside the core packag - The contract of the library's `WebView` and `WebContent` components: their props, layout, loading and failure states, and fallback content. Each component's own record and `spec:AST-082/FR3` own it. -- The full contracts of `AstryxWebSessions`, `AstryxWebData`, - `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots`. They - are outside the core package, because no Astryx component uses them. +- The contracts of `AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, + and `AstryxPageSnapshots`. The four are outside the core package, because no Astryx component uses them. +- `AstryxWebSessions` beyond the handle the view depends on (FR8; OQ8). - Astryx Stage (`spec:AST-139`) and Preview in the Astryx app (`spec:AST-141`) are separate products; they conform to this record's contracts. - Browser features the view does not offer: downloads, file upload pickers, geolocation, WebRTC, pop-up windows, and pull-to-refresh. @@ -489,3 +494,7 @@ a working page that leaks what the app meant to keep. platform info's list (FR3, FR18). Options: keep `AstryxWebViewInfo` for `channelIsolation` and `pageProfile`; or report both through the platform info and remove the module. +- **OQ8 — Do `AstryxWebSessions`' create and remove calls belong in this + record?** (`human-api`) FR8 holds the handle part the view depends on. + Options: specify the module's calls here beside the view; or keep this + record to the handle and give the calls a record of their own. From dcc932fa0294c0c96ae9ee8b1e4bd8a5cd1bbe73 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:42:22 -0800 Subject: [PATCH 12/23] spec(AST-131): frame scope and gap for the page protection, pinned sessions refused for bundles, AST-112 FR1 and FR7 reliance --- .../AST-131-react-native-web-view/spec.md | 61 +++++++++++-------- 1 file changed, 36 insertions(+), 25 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 63db28e0bba25..70eba551cf610 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -160,11 +160,19 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - **FR4 — Safe defaults.** A page in the view cannot read local files or content URIs, cannot open a second window, cannot ask for the device's location, and cannot load http content into an https page. Before the - page's own script runs, each frame loses WebRTC (`RTCPeerConnection`, - `navigator.mediaDevices`), DNS prefetching, and the `preconnect` relation on - links. The view's only other script in a page is its own page script, which + page's own script runs, every frame that runs script, the main frame and + iframes alike, loses WebRTC (`RTCPeerConnection`, `navigator.mediaDevices`), + DNS prefetching, and the `preconnect` relation on links; a same-origin + frame the page creates is covered when the page reaches it. The view's only + other script in a page is its own page script, which carries the message channel (FR9), the colour scheme and text scale (FR10), and the content height. No prop lets a caller add a script. + + FR4 gap: without the opt-in of FR19, a `preconnect` link that the HTML + parser inserts, or one in a frame that runs no script, can still open a + connection, and a new blank frame can reach WebRTC before the protection + covers it. + - **FR5 — Navigation follows declared policy, decided natively.** - The view shows the first page, and any top-level page on that page's origin or on an origin listed in `allowedOrigins`. The policy covers @@ -204,7 +212,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `AstryxWebBundles`. - The bundle's origin is the view's only origin: `html`, `url`, `baseUrl`, `grantsOrigin`, `ephemeral`, and `allowedOrigins` do not apply. A bundle - source with `session.pin`, a name that is not a DNS label, or a path with + source with a pinned session, from options or a handle, a name that is not a DNS label, or a path with `..`, `.`, a hidden, or an empty segment loads nothing and reports `invalid-config`. - A bundle page needs a message channel that tells frames apart (FR9). Where @@ -372,6 +380,9 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled ## Current-state impact +- Relies on `spec:AST-112` FR1 (amended): the `web` capability holds the web view and its modules. +- Relies on `spec:AST-112` FR7 (amended): each group of the platform has its + own record, and this is the web group's. - Relies on `spec:AST-112` FR3 (amended): the `web` capability is a device feature an app opts in; Astryx's components link by default. - Relies on `spec:AST-112` FR4 (amended): native code uses public platform @@ -384,27 +395,27 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader | `web` opted out; opted in | An opted-out app links WebKit or the redirect activity, or the library imports the capability outside its loader | -| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | -| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | -| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside an iframe | Any of them succeeds | -| FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason | -| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | -| FR7 | Unit tests of the refusals; Simulator and emulator scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | -| FR8 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | -| FR9 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | -| FR10 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | -| FR11 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | -| FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | -| FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | -| FR14 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary does not list it, a one-platform feature is listed on the other platform, or a device constant is ignored | -| FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | -| FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | -| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | -| FR18 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | -| FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader | `web` opted out; opted in | An opted-out app links WebKit or the redirect activity, or the library imports the capability outside its loader | +| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | +| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | +| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR19's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | +| FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason | +| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | +| FR7 | Unit tests of the refusals; Simulator and emulator scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | +| FR8 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | +| FR9 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | +| FR10 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | +| FR11 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | +| FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | +| FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | +| FR14 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary does not list it, a one-platform feature is listed on the other platform, or a device constant is ignored | +| FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | +| FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | +| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | +| FR18 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | +| FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | ## Decision log From 6914c0fe9782d7c25f85578296508ba98ac73851 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:23:14 -0800 Subject: [PATCH 13/23] spec(AST-131): ./web exports the core web pieces; features reported on both platforms; non-person navigation and the first page origin stated --- .../AST-131-react-native-web-view/spec.md | 125 +++++++++--------- 1 file changed, 65 insertions(+), 60 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 70eba551cf610..5a888742b7ca1 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -57,14 +57,13 @@ opt-in `web` capability. The capability's four other modules are outside the cor channel, separate page data), so a caller that needs a guarantee is refused loudly instead of getting a weaker page (DEC-5). OQ7 asks whether it folds into the platform info. -- `AstryxAuthSession`: the gap is narrow: closed result reasons, no Expo - library (`spec:AST-112/FR11`), and a redirect URI per runtime. OQ3 asks - whether sign-in is its own opt-in. - `AstryxWebSessions`: it holds an embedded page's session natively, so `WebView` passes a handle instead of cookie values (FR8, DEC-3). OQ8 asks whether its create and remove calls belong in this record. -- `AstryxWebData`, `AstryxWebBundles`, and `AstryxPageSnapshots` serve the - web view's page data, bundled folders, and thumbnails; they are outside the core package, because no Astryx component uses them. +- `AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, and + `AstryxPageSnapshots` serve page data, bundled folders, sign-in, and + thumbnails; they are outside the core package, because no Astryx component + uses them (`spec:AST-112/FR20`). ## Who uses it @@ -75,7 +74,7 @@ opt-in `web` capability. The capability's four other modules are outside the cor | `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` uses it through its session handle (`session={{sessionId}}`, FR8): the native view resolves the handle; core, within the `web` capability | A signed-in embedded page | | `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | Web pages that keep nothing after sign-out | | `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package (a `NativeWebView` with a `{bundle}` source shows its folders) | A bundled web app that works offline and opens at once when warmed up | -| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it (the library's `useAuthSession` hook reaches it), so it is outside the core package | The system's sign-in sheet | +| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | The system's sign-in sheet | | `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | A thumbnail of an HTML document | Notes on the `web` capability's other modules: @@ -114,13 +113,13 @@ Notes on the `web` capability's other modules: ## Requirements -- **FR1 — `web` is an opt-in capability.** The web view and its modules belong - to the `web` capability, which an app opts in (`spec:AST-112/FR3`). An app - that does not opt it in links no web engine and no sign-in redirect - handling. The `./web` entry exports `NativeWebView`, - `isNativeWebViewAvailable()`, `AstryxWebViewInfo`, and the capability's other - modules. The library reaches the capability only through - `AstryxPlatform.capability('web')` (`spec:AST-112/FR2`). +- **FR1 — `web` is an opt-in capability.** The web view, its device report, + and the session registry belong to the `web` capability, which an app opts + in (`spec:AST-112/FR3`). An app that does not opt it in links no web engine. + The `./web` entry exports `NativeWebView`, `isNativeWebViewAvailable()`, + `AstryxWebViewInfo`, and `AstryxWebSessions`. The library reaches the + capability only through `AstryxPlatform.capability('web')` + (`spec:AST-112/FR2`). - **FR2 — `NativeWebView` is the platform's web view.** Its props: - `source`, one of `{uri}` (an http or https page), `{html, baseUrl?, grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled @@ -175,7 +174,9 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - **FR5 — Navigation follows declared policy, decided natively.** - The view shows the first page, and any top-level page on that page's - origin or on an origin listed in `allowedOrigins`. The policy covers + origin or on an origin listed in `allowedOrigins`. The first page's origin + is the origin of the source the caller passed (`url`, or `baseUrl` with + `grantsOrigin`), whatever the first load's redirects reach. The policy covers top-level navigation only; images, scripts, and frames load as the page's own rules allow. - A top-level navigation to any other origin that a person causes (tapping @@ -184,6 +185,9 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled and sends `onOpenExternal`; `report` opens nothing and sends `onNavigationBlocked` with `external` or `newWindow`; `block` opens nothing and sends nothing. + - A top-level navigation that no person caused (a server redirect, a + script, a meta refresh) stays in the view whatever its origin, and sends + no event; only a pin limits it. - A non-web scheme opens outside the view only when it is in `allowedExternalSchemes` (default `mailto`, `tel`, `sms`; an empty list allows none). Any other scheme is cancelled and reported as @@ -247,9 +251,9 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled requests out. Where it cannot, those pages run with no page storage, and clearing page data still leaves the app's network cookies. - **FR9 — One message channel.** - - The page sends with `window.astryx.postMessage(string)`. The view accepts a - message only from the main frame of the page's own origin or an allowed - origin, and sends `onMessage({data, origin, isMainFrame})`. `origin` and + - The page sends with `window.astryx.postMessage(string)`. On a device with + channel isolation, the view accepts a message only from the main frame of + the page's own origin or an allowed origin, and sends `onMessage({data, origin, isMainFrame})`. `origin` and `isMainFrame` come from the engine, never from the page's data. - The app sends with `ref.postMessage(data)` (the `postMessage` command). The page receives it through `window.astryx.addListener` and as a `message` @@ -284,7 +288,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - `preventsCapture` keeps screenshots, screen recordings, and the app switcher's image of the window out while the view is on screen, however many views ask for it. iOS has no view-level equivalent: it ignores the - prop, shows the page, and does not list the feature, so capture + prop, shows the page, and reports the feature as not supported, so capture prevention there is best effort. A caller that requires it checks `supports('preventsCapture')` first. - `linkMenu` describes the menu a long press on a link shows: actions @@ -315,11 +319,12 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `externalSchemes`, `grantsOrigin`, `channelIsolation`, `preventsCapture`, `pageStorage`, `bundledOrigin`, `pageProfile`, `linkMenu`, `messageOrigin`, `warmBundle`, and `contentProcessEnd` (`spec:AST-140/FR5`). - - The binary of each platform lists the features it implements. A feature - one platform implements is listed only there: `preventsCapture` on - Android; `linkMenu` and `warmBundle` on iOS. - - `AstryxWebViewInfo.supports(feature)` answers true when the binary lists - the feature and, for `channelIsolation` and `pageProfile`, the device's + - The binary of each platform reports every feature by the same name, with + `isSupported` false and a note on a platform that lacks it + (`spec:AST-140/FR5`): `preventsCapture` on iOS; `linkMenu` and + `warmBundle` on Android. + - `AstryxWebViewInfo.supports(feature)` answers true when the binary reports + the feature as supported and, for `channelIsolation` and `pageProfile`, the device's constant is not false. `isAvailable()` answers whether the module is linked. Without it (not opted in, Jest, the web), nothing is claimed. - The library's `useWebViewSupports(feature)` answers the same, and false @@ -351,15 +356,17 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled uses the behaviour; without it, JavaScript keeps the revision-1 behaviour or answers `unsupported`, never a silent weaker path (DEC-5). - **FR19 — Native code uses public platform API only.** The web view and its - modules use only public platform API (`spec:AST-112/FR4`). One exception - exists, and it is off by default: an app may opt in through its - configuration (`web.privateHardening`) to private WebKit settings that turn - peer connections, media devices, and DNS prefetching off in every frame on - iOS. WebKit has no public setting for them, and they cover frames that the - page-level protection of FR4 cannot reach. The view uses each setting only - when the running WebKit has it, and the app that opts in takes the review - risk of private API. Without the opt-in, FR4's protection is the same on - both platforms. + core modules (`AstryxWebViewInfo`, `AstryxWebSessions`) use only public + platform API (`spec:AST-112/FR4`). One exception exists, and it is off by + default: an app may opt in through its configuration + (`web.privateHardening`) to private `WKPreferences` setters and WebKit + feature flags that turn peer connections, media devices, DNS prefetching, + and link preconnect off in every frame on iOS. WebKit has no public setting + for them, and they cover frames that the page-level protection of FR4 + cannot reach. The view checks that the running WebKit answers to each + setting before it uses it, and the app that opts in takes the review risk + of private API. Without the opt-in, FR4's protection is the same on both + platforms. ### Platform support @@ -380,7 +387,11 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled ## Current-state impact -- Relies on `spec:AST-112` FR1 (amended): the `web` capability holds the web view and its modules. +- Relies on `spec:AST-112` FR1 (amended): the `web` capability holds the web + view, its device report, and the session registry. +- Relies on `spec:AST-112` FR20 (amended): native capabilities no Astryx + component uses are outside the core package; the four web modules of + "Who uses it" are. - Relies on `spec:AST-112` FR7 (amended): each group of the platform has its own record, and this is the web group's. - Relies on `spec:AST-112` FR3 (amended): the `web` capability is a device @@ -395,27 +406,27 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader | `web` opted out; opted in | An opted-out app links WebKit or the redirect activity, or the library imports the capability outside its loader | -| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | -| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | -| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR19's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | -| FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason | -| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | -| FR7 | Unit tests of the refusals; Simulator and emulator scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | -| FR8 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | -| FR9 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | -| FR10 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | -| FR11 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | -| FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | -| FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | -| FR14 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary does not list it, a one-platform feature is listed on the other platform, or a device constant is ignored | -| FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | -| FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | -| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | -| FR18 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | -| FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader; the `./web` export list | `web` opted out; opted in | An opted-out app links WebKit, `./web` exports a module outside the core package, or the library imports the capability outside its loader | +| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | +| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | +| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR19's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | +| FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out; a script navigation and a server redirect to another origin; a first load that redirects | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason; a navigation no person caused leaves the view or sends an event; or the first page's origin follows its redirects | +| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | +| FR7 | Unit tests of the refusals; Simulator and emulator scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | +| FR8 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | +| FR9 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | +| FR10 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | +| FR11 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | +| FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | +| FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | +| FR14 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary reports it as not supported, a feature a platform lacks is reported supported there or missing from the report, or a device constant is ignored | +| FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | +| FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | +| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | +| FR18 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | +| FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | ## Decision log @@ -487,12 +498,6 @@ a working page that leaks what the app meant to keep. - **OQ2 — Do `WebView` and `WebContent` take a bundle source?** (`human-api`) Options: bundled folders show only through `NativeWebView`; or the library's components take a `bundle` source too. -- **OQ3 — Is web sign-in (`AstryxAuthSession`) an opt-in capability of its - own?** (`human-api`) It needs no embedded web view and no Astryx component - uses it. Options: keep it in `web` beside the web view with the - `useAuthSession` hook; or make sign-in its own opt-in, so an app that signs - in links no WebKit web view and an app with a web view links no redirect - activity. - **OQ4 — Do `WebView` and `WebContent` expose `preventsCapture`, `linkMenu`, and `allowedExternalSchemes`, which only `NativeWebView` takes?** (`human-api`) From f7597e219400af431affaa66f48192f55d739917 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:26:50 -0800 Subject: [PATCH 14/23] spec(AST-131): bundled web content leaves the record; the web view keeps what Astryx components use --- .../AST-131-react-native-web-view/spec.md | 199 +++++++----------- 1 file changed, 77 insertions(+), 122 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 5a888742b7ca1..13566a4ae3dba 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -23,8 +23,7 @@ affects_consumer_docs: [] ## Intent An app shows web content inside a screen: a help page, a terms page, a sign-in -or payment page in place, an HTML document the app built, or a small web app -bundled with the app that works offline. The developer gets one web view that +or payment page in place, or an HTML document the app built. The developer gets one web view that is safe by default: links to other sites open in the system browser, the page cannot reach the device's files or open pop-up windows, the page follows the app's light or dark mode and text size, and the app and the page talk over one @@ -44,21 +43,20 @@ opt-in `web` capability. The capability's four other modules are outside the cor ## Why this exists - `AstryxWebView`: an app cannot add these guarantees from outside an - ecosystem web view component, so Astryx owns the view. A bundled folder - loads from a private origin with no network (FR7). A pin holds across + ecosystem web view component, so Astryx owns the view. A pin holds across redirects and is decided natively (FR5, DEC-1). A session's cookie values - never appear in props (FR8, DEC-3). Pages can run with no storage (FR8). The - message sender comes from the engine (FR9, DEC-2). Loads report closed - reasons (FR13). The package keeps one dependency set (`spec:AST-112/FR2`). + never appear in props (FR7, DEC-3). Pages can run with no storage (FR7). The + message sender comes from the engine (FR8, DEC-2). Loads report closed + reasons (FR12). The package keeps one dependency set (`spec:AST-112/FR2`). Astryx takes no third-party native dependency for the web view; an app may use react-native-webview beside these components without conflict (`spec:AST-140/FR9`). - `AstryxWebViewInfo`: it answers what the device can keep (a frame-safe channel, separate page data), so a caller that needs a guarantee is refused - loudly instead of getting a weaker page (DEC-5). OQ7 asks whether it folds + loudly instead of getting a weaker page (DEC-4). OQ5 asks whether it folds into the platform info. - `AstryxWebSessions`: it holds an embedded page's session natively, so - `WebView` passes a handle instead of cookie values (FR8, DEC-3). OQ8 asks + `WebView` passes a handle instead of cookie values (FR7, DEC-3). OQ6 asks whether its create and remove calls belong in this record. - `AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots` serve page data, bundled folders, sign-in, and @@ -71,9 +69,9 @@ opt-in `web` capability. The capability's four other modules are outside the cor | --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | | `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | -| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` uses it through its session handle (`session={{sessionId}}`, FR8): the native view resolves the handle; core, within the `web` capability | A signed-in embedded page | +| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` uses it through its session handle (`session={{sessionId}}`, FR7): the native view resolves the handle; core, within the `web` capability | A signed-in embedded page | | `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | Web pages that keep nothing after sign-out | -| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package (a `NativeWebView` with a `{bundle}` source shows its folders) | A bundled web app that works offline and opens at once when warmed up | +| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | A bundled web app that works offline | | `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | The system's sign-in sheet | | `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | A thumbnail of an HTML document | @@ -81,12 +79,11 @@ Notes on the `web` capability's other modules: - `AstryxWebSessions` (core) holds an embedded page's cookies, store, and pin natively under an opaque handle that the view's `sessionId` prop names - (FR8). + (FR7). - The four below are outside the core package, because no Astryx component uses them. - `AstryxWebData` clears the runtime's shared web store and sets when it clears itself. -- `AstryxWebBundles` registers bundled folders, answers the page's byte route, - and keeps a pool of warm pages; the view side is FR7. +- `AstryxWebBundles` serves an app's bundled web content. - `AstryxAuthSession` runs web sign-in in the system's authentication session. - `AstryxPageSnapshots` draws an HTML document inert in an offscreen web view and writes a PNG to the app's file cache. @@ -98,7 +95,7 @@ Notes on the `web` capability's other modules: component's own record and `spec:AST-082/FR3` own it. - The contracts of `AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, and `AstryxPageSnapshots`. The four are outside the core package, because no Astryx component uses them. -- `AstryxWebSessions` beyond the handle the view depends on (FR8; OQ8). +- `AstryxWebSessions` beyond the handle the view depends on (FR7; OQ6). - Astryx Stage (`spec:AST-139`) and Preview in the Astryx app (`spec:AST-141`) are separate products; they conform to this record's contracts. - Browser features the view does not offer: downloads, file upload pickers, geolocation, WebRTC, pop-up windows, and pull-to-refresh. @@ -121,38 +118,37 @@ Notes on the `web` capability's other modules: capability only through `AstryxPlatform.capability('web')` (`spec:AST-112/FR2`). - **FR2 — `NativeWebView` is the platform's web view.** Its props: - - `source`, one of `{uri}` (an http or https page), `{html, baseUrl?, -grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - folder, FR7). + - `source`, one of `{uri}` (an http or https page) or `{html, baseUrl?, +grantsOrigin?}` (an HTML string). - Navigation: `allowedOrigins`, `externalNavigation`, `allowedExternalSchemes` - (FR5); sessions: `session` (FR8). + (FR5); sessions: `session` (FR7). - Appearance and layout: `colorScheme`, `textScale`, `isScrollEnabled`, `layerTypeAndroid` (`software` by default, or `hardware` for WebGL and - hardware video), `applicationNameForUserAgent`, and `userAgent` (FR10). - - `preventsCapture` and `linkMenu` with `onLinkMenuAction` (FR12); `warm` - (FR7); `reloadsOnContentProcessEnd` (FR11). + hardware video), `applicationNameForUserAgent`, and `userAgent` (FR9). + - `preventsCapture` and `linkMenu` with `onLinkMenuAction` (FR11); + `reloadsOnContentProcessEnd` (FR10). - Events, each with one object argument: `onLoadStart({url})`, `onLoad({url, title})`, `onProgress({progress})` (0 to 1), `onError(failure)`, `onContentHeight({height})`, `onMessage(event)`, `onOpenExternal({url})`, `onNavigationBlocked({url, reason})`, and `onContentProcessEnded(event)`. - `ref`, a handle with `postMessage(data)` and `reload()`; `fallback`, drawn - where the view is absent (FR16); `style` and `testID`. + where the view is absent (FR15); `style` and `testID`. - Without `allowedOrigins`, the view keeps only the first page's origin (FR5). - **FR3 — The native contract.** - | Contract | Kind | Props | Commands | Events | Platforms | - | --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | - | `AstryxWebView` | native component (Fabric Native Component) | `html`, `baseUrl`, `url`, `grantsOrigin`, `bundleName`, `bundlePath`, `warm`, `allowedOrigins`, `externalNavigation`, `allowedExternalSchemes`, `noExternalSchemes`, `pinnedOrigin`, `pinnedPathPrefix`, `sessionId`, `ephemeral`, `allowsPageStorage`, `colorScheme`, `textScale`, `scrollEnabled`, `layerTypeAndroid`, `applicationNameForUserAgent`, `userAgent`, `preventsCapture`, `linkMenu`, `reloadsOnContentProcessEnd` | `postMessage`, `reload` | `onWebLoadStart`, `onWebLoad`, `onWebError`, `onWebProgress`, `onWebContentHeight`, `onWebMessage`, `onWebOpenExternal`, `onWebNavigationBlocked`, `onWebLinkMenuAction`, `onWebContentProcessEnded` | iOS, Android | + | Contract | Kind | Props | Commands | Events | Platforms | + | --------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | + | `AstryxWebView` | native component (Fabric Native Component) | `html`, `baseUrl`, `url`, `grantsOrigin`, `allowedOrigins`, `externalNavigation`, `allowedExternalSchemes`, `noExternalSchemes`, `pinnedOrigin`, `pinnedPathPrefix`, `sessionId`, `ephemeral`, `allowsPageStorage`, `colorScheme`, `textScale`, `scrollEnabled`, `layerTypeAndroid`, `applicationNameForUserAgent`, `userAgent`, `preventsCapture`, `linkMenu`, `reloadsOnContentProcessEnd` | `postMessage`, `reload` | `onWebLoadStart`, `onWebLoad`, `onWebError`, `onWebProgress`, `onWebContentHeight`, `onWebMessage`, `onWebOpenExternal`, `onWebNavigationBlocked`, `onWebLinkMenuAction`, `onWebContentProcessEnded` | iOS, Android | | Contract | Kind | Methods | Platforms | | ------------------- | ----------------------------------- | -------------------------------------------------------------------------------------- | ------------ | - | `AstryxWebViewInfo` | native module (Turbo Native Module) | `getConstants()`: the device constants `channelIsolation` and `pageProfile` (FR8, FR9) | iOS, Android | + | `AstryxWebViewInfo` | native module (Turbo Native Module) | `getConstants()`: the device constants `channelIsolation` and `pageProfile` (FR7, FR8) | iOS, Android | - `noExternalSchemes` is the host's form of an empty `allowedExternalSchemes` (FR5). - Both contracts are at revision 1. The web view's named features - (FR14) are listed with every other contract's by the platform info + (FR13) are listed with every other contract's by the platform info module (`spec:AST-140/FR5`); `AstryxWebViewInfo` carries no feature list and no revision counter. @@ -164,10 +160,10 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled DNS prefetching, and the `preconnect` relation on links; a same-origin frame the page creates is covered when the page reaches it. The view's only other script in a page is its own page script, which - carries the message channel (FR9), the colour scheme and text scale (FR10), + carries the message channel (FR8), the colour scheme and text scale (FR9), and the content height. No prop lets a caller add a script. - FR4 gap: without the opt-in of FR19, a `preconnect` link that the HTML + FR4 gap: without the opt-in of FR18, a `preconnect` link that the HTML parser inserts, or one in a frame that runs no script, can still open a connection, and a new blank frame can reach WebRTC before the protection covers it. @@ -203,31 +199,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled relative links do not resolve. With `grantsOrigin: true` and an http or https `baseUrl`, the page takes that origin. `html` wins over `url` when both are set. -- **FR7 — Bundled folders load from a private origin with no network.** - - `{bundle: {name, path?}}` loads a folder the app's runtime registered with - `AstryxWebBundles` under `name` (a DNS label). The page is `path` (default - `/index.html`) under the bundle's origin, which the page reads as - `astryx-bundle://` on iOS and as an https origin on a reserved - `.invalid` host on Android. - - The page and every file it references come from the folder, and no - request leaves the device. The page's storage is discarded with the - view, and the page gets no cookies, credentials, or client identity. - Requests under `/_app/` go to the app, which answers them through - `AstryxWebBundles`. - - The bundle's origin is the view's only origin: `html`, `url`, `baseUrl`, - `grantsOrigin`, `ephemeral`, and `allowedOrigins` do not apply. A bundle - source with a pinned session, from options or a handle, a name that is not a DNS label, or a path with - `..`, `.`, a hidden, or an empty segment loads nothing and reports - `invalid-config`. - - A bundle page needs a message channel that tells frames apart (FR9). Where - the device cannot, nothing loads and `onError` reports `unsupported`. - - Warm-up: with `warm`, a bundle view shows a page that `AstryxWebBundles` - loaded ahead of time for its bundle and path. It sends `onLoad` at once, - then the messages that page sent before it appeared, in order. Each page - loaded ahead of time goes to at most one view. When none is ready, or the - view sets a custom user agent or turns page storage off, the view loads - the page itself and reports no error. -- **FR8 — Sessions and page storage.** +- **FR7 — Sessions and page storage.** - `session` is `{sessionId}` (a handle `AstryxWebSessions.create` answered) or options: `isEphemeral`, `pin` (FR5), and `allowsPageStorage`. A handle wins over the options. An empty or unknown handle loads nothing and @@ -250,7 +222,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `pageProfile` constant), clearing page data never signs the app's own requests out. Where it cannot, those pages run with no page storage, and clearing page data still leaves the app's network cookies. -- **FR9 — One message channel.** +- **FR8 — One message channel.** - The page sends with `window.astryx.postMessage(string)`. On a device with channel isolation, the view accepts a message only from the main frame of the page's own origin or an allowed origin, and sends `onMessage({data, origin, isMainFrame})`. `origin` and @@ -262,7 +234,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `channelIsolation` false and the sender as `origin: "null"`, `isMainFrame: false`. An app that must know the sender ignores those messages. -- **FR10 — The page follows the app's appearance.** +- **FR9 — The page follows the app's appearance.** - `colorScheme` (`light`, `dark`, or `system`) sets what the page reads from `prefers-color-scheme`, and the engine does not darken the page by itself. Without the prop, `NativeWebView` takes the platform appearance's @@ -276,7 +248,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled `userAgent` replaces it (and wins over the appended name). A value with anything other than printable ASCII is not applied: the default user agent stays, and `onError` reports `invalid-config`. -- **FR11 — A content process end is reported, and the app picks the +- **FR10 — A content process end is reported, and the app picks the recovery.** When the page's content process ends, the view sends `onContentProcessEnded({reason, willReload, url})` with `reason` `terminated`, `crashed`, `killed-for-memory`, or `unknown`. `onError` does @@ -284,7 +256,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled true (the default) the view reloads the page on its own. With false, the view shows nothing until the app calls `ref.reload()` or mounts it again, so the screen can show its own message. The app keeps running in every case. -- **FR12 — Capture prevention and the link menu.** +- **FR11 — Capture prevention and the link menu.** - `preventsCapture` keeps screenshots, screen recordings, and the app switcher's image of the window out while the view is on screen, however many views ask for it. iOS has no view-level equivalent: it ignores the @@ -301,7 +273,7 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled the link. The menu never loads or shows a preview of the target. When no action matches, the long press shows no menu. The page controls `href`, so the app validates it before acting on it. -- **FR13 — Loads report results in a closed set.** `onError` receives +- **FR12 — Loads report results in a closed set.** `onError` receives `{ok: false, reason, message, url}` with `reason` from `offline`, `timeout`, `ssl`, `invalid-url`, `invalid-config`, `unsupported`, `no-native-view`, and `error`; a reason the JavaScript does not know reads `error` @@ -309,32 +281,31 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled JavaScript checks the session and the source first. When it knows the view cannot honour them, it does not render the host view and reports the reason through `onError` one time for that page. -- **FR14 — The web view's behaviour beyond the baseline is named features.** +- **FR13 — The web view's behaviour beyond the baseline is named features.** `AstryxWebView`'s baseline is loading a page or an HTML string, the safe defaults (FR4), navigation to the page's own and allowed origins, the - colour scheme, text scale, and content height (FR10), the message channel - without sender fields, and the load events (FR13). Every other behaviour is + colour scheme, text scale, and content height (FR9), the message channel + without sender fields, and the load events (FR12). Every other behaviour is a named contract feature, `AstryxWebView.`: `session`, `userAgent`, `externalNavigation`, `sessionHandle`, `externalSchemes`, `grantsOrigin`, `channelIsolation`, `preventsCapture`, - `pageStorage`, `bundledOrigin`, `pageProfile`, `linkMenu`, `messageOrigin`, - `warmBundle`, and `contentProcessEnd` (`spec:AST-140/FR5`). + `pageStorage`, `pageProfile`, `linkMenu`, `messageOrigin`, and + `contentProcessEnd` (`spec:AST-140/FR5`). - The binary of each platform reports every feature by the same name, with `isSupported` false and a note on a platform that lacks it - (`spec:AST-140/FR5`): `preventsCapture` on iOS; `linkMenu` and - `warmBundle` on Android. + (`spec:AST-140/FR5`): `preventsCapture` on iOS; `linkMenu` on Android. - `AstryxWebViewInfo.supports(feature)` answers true when the binary reports the feature as supported and, for `channelIsolation` and `pageProfile`, the device's constant is not false. `isAvailable()` answers whether the module is linked. Without it (not opted in, Jest, the web), nothing is claimed. - The library's `useWebViewSupports(feature)` answers the same, and false without a web view. -- **FR15 — The caller supplies the appearance.** `NativeWebView` has no +- **FR14 — The caller supplies the appearance.** `NativeWebView` has no theme of its own. Its caller passes the colour scheme and text scale to use (the library passes its theme's), and the view applies a new value to the loaded page. The view's events are the same one-object shapes the library hands to its own callers. -- **FR16 — Fallbacks when `web` is not linked or the view is absent.** +- **FR15 — Fallbacks when `web` is not linked or the view is absent.** - Not opted in: the capability's module still loads; `isNativeWebViewAvailable()` and `AstryxWebViewInfo.isAvailable()` answer false, and module calls resolve `not-linked` (`spec:AST-112/FR3`, `spec:AST-140/FR2`). A missing view of an opted-in @@ -345,17 +316,17 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled switched off through the capabilities provider), the library's components draw their own fallback; their records own its content. The handle's `postMessage` does nothing there. -- **FR17 — Accessibility.** The engine exposes the page's own structure +- **FR16 — Accessibility.** The engine exposes the page's own structure (headings, links, form fields, text) to VoiceOver and TalkBack, and the platform neither adds to it nor hides it. The view has no accessible name of its own: the caller names the region on a containing view (the library's components require a label). The page's text follows the system text size - through `textScale` (FR10). The link menu is the system's context menu. -- **FR18 — Contract baseline.** Every contract in the group is at revision 1 - (`spec:AST-140/FR5`). JavaScript checks a named feature (FR14) before it + through `textScale` (FR9). The link menu is the system's context menu. +- **FR17 — Contract baseline.** Every contract in the group is at revision 1 + (`spec:AST-140/FR5`). JavaScript checks a named feature (FR13) before it uses the behaviour; without it, JavaScript keeps the revision-1 behaviour - or answers `unsupported`, never a silent weaker path (DEC-5). -- **FR19 — Native code uses public platform API only.** The web view and its + or answers `unsupported`, never a silent weaker path (DEC-4). +- **FR18 — Native code uses public platform API only.** The web view and its core modules (`AstryxWebViewInfo`, `AstryxWebSessions`) use only public platform API (`spec:AST-112/FR4`). One exception exists, and it is off by default: an app may opt in through its configuration @@ -370,18 +341,18 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled ### Platform support -| Contract | iOS | Android | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `AstryxWebView` | WebKit (`WKWebView`). Every named feature except `preventsCapture`, which iOS ignores because it has no view-level capture protection. | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature except `linkMenu` and `warmBundle`, which Android ignores. A content process end is reported on Android 8.0 and later. | -| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | +| Contract | iOS | Android | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | WebKit (`WKWebView`). Every named feature except `preventsCapture`, which iOS ignores because it has no view-level capture protection. | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature except `linkMenu`, which Android ignores. A content process end is reported on Android 8.0 and later. | +| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | - Supported feature/engine floor: the floor of `spec:AST-112` (iOS at React Native's minimum, Android API level 24, the New Architecture only), with the system web engine the device carries. - Unsupported behavior: a feature the binary lacks answers false from `supports(feature)`, and a load that needs it refuses with `unsupported` - (FR13, FR14); a view the binary lacks reports itself unavailable and the - library draws its fallback (FR16). + (FR12, FR13); a view the binary lacks reports itself unavailable and the + library draws its fallback (FR15). - Browser evidence: none. Native claims are proven on the iOS Simulator, the Android emulator, and devices (`spec:AST-112/FR15`). @@ -397,10 +368,10 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled - Relies on `spec:AST-112` FR3 (amended): the `web` capability is a device feature an app opts in; Astryx's components link by default. - Relies on `spec:AST-112` FR4 (amended): native code uses public platform - API only, and a record names any exception (FR19). + API only, and a record names any exception (FR18). - Relies on `spec:AST-140` FR5: every contract is at revision 1, later behaviour is a named feature the platform info module lists, and no - contract carries a revision counter (FR3, FR14, FR18). + contract carries a revision counter (FR3, FR13, FR17). - `spec:AST-093/FR5` (every native component is tested and validated the same way) applies to `WebView` and `WebContent` unchanged. @@ -411,22 +382,21 @@ grantsOrigin?}` (an HTML string), or `{bundle: {name, path?}}` (a bundled | FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader; the `./web` export list | `web` opted out; opted in | An opted-out app links WebKit, `./web` exports a module outside the core package, or the library imports the capability outside its loader | | FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | | FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | -| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR19's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | +| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR18's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | | FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out; a script navigation and a server redirect to another origin; a first load that redirects | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason; a navigation no person caused leaves the view or sends an event; or the first page's origin follows its redirects | | FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | -| FR7 | Unit tests of the refusals; Simulator and emulator scripts of a bundled folder | a valid bundle; a bad name or path; a bundle with a pin; a device without channel isolation; `warm` with and without a ready page | A bundle page reaches a network, loads with a refused config, or a warm view loads twice or loses an early message | -| FR8 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | -| FR9 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | -| FR10 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | -| FR11 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | -| FR12 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | -| FR13 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | -| FR14 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary reports it as not supported, a feature a platform lacks is reported supported there or missing from the report, or a device constant is ignored | -| FR15 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | -| FR16 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | -| FR17 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | -| FR18 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | -| FR19 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | +| FR7 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | +| FR8 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | +| FR9 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | +| FR10 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | +| FR11 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | +| FR12 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | +| FR13 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary reports it as not supported, a feature a platform lacks is reported supported there or missing from the report, or a device constant is ignored | +| FR14 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | +| FR15 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | +| FR16 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | +| FR17 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | +| FR18 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | ## Decision log @@ -464,25 +434,13 @@ An embedded page's cookies, store, and pin are created natively once and named by an opaque handle that the view's props carry. Cookie values never appear in props, development tools, or logs. -### DEC-4 — Bundled web content loads from a private origin +### DEC-4 — A guarantee the binary cannot keep refuses the load **Reference:** `spec:AST-131/DEC-4` **Decider:** imdreamrunner, 2026-11-17 -A bundled folder loads from an origin of its own, with no network access and a -store that is discarded with the view; the page reads the app's data over a -byte route the app answers. The view keeps file access off on every path. - -Rejected: loading bundled files through file URLs, because the page would then -need file access. - -### DEC-5 — A guarantee the binary cannot keep refuses the load - -**Reference:** `spec:AST-131/DEC-5` -**Decider:** imdreamrunner, 2026-11-17 - When a caller asks for a privacy or isolation guarantee (page storage off, a -bundled origin, a frame-safe channel) and the binary or device cannot keep it, +frame-safe channel) and the binary or device cannot keep it, nothing loads and `onError` reports `unsupported`. A caller checks `supports(feature)` first and picks its own path. @@ -495,22 +453,19 @@ a working page that leaks what the app meant to keep. (`human-api`) Options: the caller creates the handle with `AstryxWebSessions` and passes `session={{sessionId}}`; or `WebView` takes the session's options and manages the handle for the caller. -- **OQ2 — Do `WebView` and `WebContent` take a bundle source?** - (`human-api`) Options: bundled folders show only through `NativeWebView`; - or the library's components take a `bundle` source too. -- **OQ4 — Do `WebView` and `WebContent` expose `preventsCapture`, +- **OQ2 — Do `WebView` and `WebContent` expose `preventsCapture`, `linkMenu`, and `allowedExternalSchemes`, which only `NativeWebView` takes?** (`human-api`) -- **OQ5 — Does Android build the link menu and warm pages, or do they stay - iOS-only features?** (`human-design`) -- **OQ6 — Does the page's `prefers-reduced-motion` follow the system's Reduce +- **OQ3 — Does Android build the link menu, or does it stay an iOS-only + feature?** (`human-design`) +- **OQ4 — Does the page's `prefers-reduced-motion` follow the system's Reduce Motion setting on both engines?** (`checkable`) -- **OQ7 — Do the device constants of `AstryxWebViewInfo` move into the +- **OQ5 — Do the device constants of `AstryxWebViewInfo` move into the platform info?** (`human-api`) The named features already live in the - platform info's list (FR3, FR18). Options: keep `AstryxWebViewInfo` for + platform info's list (FR3, FR17). Options: keep `AstryxWebViewInfo` for `channelIsolation` and `pageProfile`; or report both through the platform info and remove the module. -- **OQ8 — Do `AstryxWebSessions`' create and remove calls belong in this - record?** (`human-api`) FR8 holds the handle part the view depends on. +- **OQ6 — Do `AstryxWebSessions`' create and remove calls belong in this + record?** (`human-api`) FR7 holds the handle part the view depends on. Options: specify the module's calls here beside the view; or keep this record to the handle and give the calls a record of their own. From c328fa25de36219b65ec3730737e19981de27421 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:02:24 -0800 Subject: [PATCH 15/23] spec(AST-131): one outcome for navigations no person caused; the four non-core web pieces are left to the app --- .../AST-131-react-native-web-view/spec.md | 110 +++++++++--------- 1 file changed, 56 insertions(+), 54 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 13566a4ae3dba..0014382596829 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -38,7 +38,9 @@ evolution (`spec:AST-140/FR5`). It specifies the native web view (`AstryxWebView`), its device report (`AstryxWebViewInfo`), and the part of the session registry (`AstryxWebSessions`) the view depends on, which the library's `WebView` and `WebContent` use; the three are core, within the -opt-in `web` capability. The capability's four other modules are outside the core package, because no Astryx component uses them; "Who uses it" lists them. +opt-in `web` capability. Web data, bundled web content, web sign-in, and page snapshots are not part of +the `web` capability: no Astryx component uses them, so they are outside the +core package, and an app uses its host platform's implementation or an open-source library for them (`spec:AST-112/FR20`); "Who uses it" lists them. ## Why this exists @@ -58,10 +60,9 @@ opt-in `web` capability. The capability's four other modules are outside the cor - `AstryxWebSessions`: it holds an embedded page's session natively, so `WebView` passes a handle instead of cookie values (FR7, DEC-3). OQ6 asks whether its create and remove calls belong in this record. -- `AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, and - `AstryxPageSnapshots` serve page data, bundled folders, sign-in, and - thumbnails; they are outside the core package, because no Astryx component - uses them (`spec:AST-112/FR20`). +- Web data, bundled web content, web sign-in, and page snapshots: no Astryx + component uses them, so they are outside the core package and the `web` + capability, and an app uses its host platform's implementation or an open-source library for them (`spec:AST-112/FR20`). ## Who uses it @@ -70,31 +71,26 @@ opt-in `web` capability. The capability's four other modules are outside the cor | `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | | `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | | `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` uses it through its session handle (`session={{sessionId}}`, FR7): the native view resolves the handle; core, within the `web` capability | A signed-in embedded page | -| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | Web pages that keep nothing after sign-out | -| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | A bundled web app that works offline | -| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | The system's sign-in sheet | -| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it, so it is outside the core package | A thumbnail of an HTML document | - -Notes on the `web` capability's other modules: - -- `AstryxWebSessions` (core) holds an embedded page's cookies, store, and pin - natively under an opaque handle that the view's `sessionId` prop names - (FR7). -- The four below are outside the core package, because no Astryx component uses them. -- `AstryxWebData` clears the runtime's shared web store and sets when it clears - itself. -- `AstryxWebBundles` serves an app's bundled web content. -- `AstryxAuthSession` runs web sign-in in the system's authentication session. -- `AstryxPageSnapshots` draws an HTML document inert in an offscreen web view - and writes a PNG to the app's file cache. +| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it; outside the core package and the `web` capability (`spec:AST-112/FR20`) | Web pages that keep nothing after sign-out | +| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it; outside the core package and the `web` capability (`spec:AST-112/FR20`) | A bundled web app that works offline | +| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it; outside the core package and the `web` capability (`spec:AST-112/FR20`) | The system's sign-in sheet | +| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it; outside the core package and the `web` capability (`spec:AST-112/FR20`) | A thumbnail of an HTML document | + +Note: `AstryxWebSessions` (core) holds an embedded page's cookies, store, and +pin natively under an opaque handle that the view's `sessionId` prop names +(FR7). The other four rows name native pieces that Astryx does not ship as +part of this capability; an app that needs them uses its host platform's +implementation or an open-source library (`spec:AST-112/FR20`). ## Non-goals - The contract of the library's `WebView` and `WebContent` components: their props, layout, loading and failure states, and fallback content. Each component's own record and `spec:AST-082/FR3` own it. -- The contracts of `AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, - and `AstryxPageSnapshots`. The four are outside the core package, because no Astryx component uses them. +- Web data, bundled web content, web sign-in, and page snapshots + (`AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, + `AstryxPageSnapshots`): outside the core package and the `web` capability, + because no Astryx component uses them (`spec:AST-112/FR20`). - `AstryxWebSessions` beyond the handle the view depends on (FR7; OQ6). - Astryx Stage (`spec:AST-139`) and Preview in the Astryx app (`spec:AST-141`) are separate products; they conform to this record's contracts. - Browser features the view does not offer: downloads, file upload pickers, @@ -134,8 +130,8 @@ grantsOrigin?}` (an HTML string). `onContentProcessEnded(event)`. - `ref`, a handle with `postMessage(data)` and `reload()`; `fallback`, drawn where the view is absent (FR15); `style` and `testID`. - - Without `allowedOrigins`, the view keeps only the first page's origin - (FR5). + - Without `allowedOrigins`, the view's own origin is the first page's + origin alone (FR5). - **FR3 — The native contract.** | Contract | Kind | Props | Commands | Events | Platforms | @@ -183,7 +179,10 @@ grantsOrigin?}` (an HTML string). nothing and sends nothing. - A top-level navigation that no person caused (a server redirect, a script, a meta refresh) stays in the view whatever its origin, and sends - no event; only a pin limits it. + no event; only a pin limits it. A page reached that way does not change + the view's own origin: a person's link or form there to an origin that is + neither the first page's nor allowed follows `externalNavigation`, and + the message channel does not accept that page's messages (FR8). - A non-web scheme opens outside the view only when it is in `allowedExternalSchemes` (default `mailto`, `tel`, `sms`; an empty list allows none). Any other scheme is cancelled and reported as @@ -224,8 +223,9 @@ grantsOrigin?}` (an HTML string). clearing page data still leaves the app's network cookies. - **FR8 — One message channel.** - The page sends with `window.astryx.postMessage(string)`. On a device with - channel isolation, the view accepts a message only from the main frame of - the page's own origin or an allowed origin, and sends `onMessage({data, origin, isMainFrame})`. `origin` and + channel isolation, the view accepts a message only from the main frame, + and only when that frame is on the first page's origin (FR5) or an allowed + origin, and sends `onMessage({data, origin, isMainFrame})`. `origin` and `isMainFrame` come from the engine, never from the page's data. - The app sends with `ref.postMessage(data)` (the `postMessage` command). The page receives it through `window.astryx.addListener` and as a `message` @@ -361,8 +361,10 @@ grantsOrigin?}` (an HTML string). - Relies on `spec:AST-112` FR1 (amended): the `web` capability holds the web view, its device report, and the session registry. - Relies on `spec:AST-112` FR20 (amended): native capabilities no Astryx - component uses are outside the core package; the four web modules of - "Who uses it" are. + component uses are outside the core package, and an app uses its host + platform's implementation or an open-source library for them; web data, + bundled web content, web sign-in, and page snapshots are such + capabilities. - Relies on `spec:AST-112` FR7 (amended): each group of the platform has its own record, and this is the web group's. - Relies on `spec:AST-112` FR3 (amended): the `web` capability is a device @@ -377,26 +379,26 @@ grantsOrigin?}` (an HTML string). ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader; the `./web` export list | `web` opted out; opted in | An opted-out app links WebKit, `./web` exports a module outside the core package, or the library imports the capability outside its loader | -| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | -| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | -| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR18's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | -| FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out; a script navigation and a server redirect to another origin; a first load that redirects | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason; a navigation no person caused leaves the view or sends an event; or the first page's origin follows its redirects | -| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | -| FR7 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | -| FR8 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation | An iframe's message is delivered as the main frame's, or an origin comes from the page's data | -| FR9 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | -| FR10 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | -| FR11 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | -| FR12 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | -| FR13 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary reports it as not supported, a feature a platform lacks is reported supported there or missing from the report, or a device constant is ignored | -| FR14 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | -| FR15 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | -| FR16 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | -| FR17 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | -| FR18 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader; the `./web` export list | `web` opted out; opted in | An opted-out app links WebKit, `./web` exports a module outside the core package, or the library imports the capability outside its loader | +| FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | +| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | +| FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR18's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | +| FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out; a script navigation and a server redirect to another origin; a first load that redirects; a person's form on a page a redirect reached on another origin | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason; a navigation no person caused leaves the view or sends an event; or the first page's origin follows its redirects; or that form stays in the view | +| FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | +| FR7 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | +| FR8 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation; a page a redirect reached on another origin | An iframe's message is delivered as the main frame's, an origin comes from the page's data, or a message from a page outside the first page's and allowed origins is delivered | +| FR9 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | +| FR10 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | +| FR11 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | +| FR12 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | +| FR13 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary reports it as not supported, a feature a platform lacks is reported supported there or missing from the report, or a device constant is ignored | +| FR14 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | +| FR15 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | +| FR16 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | +| FR17 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | +| FR18 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | ## Decision log @@ -418,9 +420,9 @@ or lets the load run ahead of the answer. **Decider:** imdreamrunner, 2026-11-17 The page and the app talk only through `window.astryx` and the `postMessage` -command. The view accepts only the main frame of the page's own or an allowed -origin, and reports the sender's origin from the engine, so a frame cannot -forge it. +command. On a device with channel isolation, the view accepts only the main +frame of the first page's or an allowed origin, and reports the sender's +origin from the engine, so a frame cannot forge it. Rejected: an injected-script prop, because any script then runs with the page's full rights and the channel's rules no longer hold. From 2328306a445a5caf6623aad5e23bbfbc01c46e42 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:23:30 -0800 Subject: [PATCH 16/23] spec(AST-131): a contract baseline is its first release shape --- .../AST-131-react-native-web-view/spec.md | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 0014382596829..edc2d9998d89a 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -143,10 +143,10 @@ grantsOrigin?}` (an HTML string). | `AstryxWebViewInfo` | native module (Turbo Native Module) | `getConstants()`: the device constants `channelIsolation` and `pageProfile` (FR7, FR8) | iOS, Android | - `noExternalSchemes` is the host's form of an empty `allowedExternalSchemes` (FR5). - - Both contracts are at revision 1. The web view's named features - (FR13) are listed with every other contract's by the platform info - module (`spec:AST-140/FR5`); `AstryxWebViewInfo` carries no feature list - and no revision counter. + - Each contract's baseline is its first release's shape + (`spec:AST-140/FR5`). The web view's named features (FR13) are listed with + every other contract's by the platform info module; `AstryxWebViewInfo` + carries no feature list and no revision number. - **FR4 — Safe defaults.** A page in the view cannot read local files or content URIs, cannot open a second window, cannot ask for the device's @@ -322,10 +322,11 @@ grantsOrigin?}` (an HTML string). its own: the caller names the region on a containing view (the library's components require a label). The page's text follows the system text size through `textScale` (FR9). The link menu is the system's context menu. -- **FR17 — Contract baseline.** Every contract in the group is at revision 1 - (`spec:AST-140/FR5`). JavaScript checks a named feature (FR13) before it - uses the behaviour; without it, JavaScript keeps the revision-1 behaviour - or answers `unsupported`, never a silent weaker path (DEC-4). +- **FR17 — Contract baseline.** Each contract's baseline is its first + release's shape (`spec:AST-140/FR5`). JavaScript checks a named feature + (FR13) before it uses the behaviour; without it, JavaScript keeps the + baseline behaviour or answers `unsupported`, never a silent weaker path + (DEC-4). - **FR18 — Native code uses public platform API only.** The web view and its core modules (`AstryxWebViewInfo`, `AstryxWebSessions`) use only public platform API (`spec:AST-112/FR4`). One exception exists, and it is off by @@ -371,9 +372,9 @@ grantsOrigin?}` (an HTML string). feature an app opts in; Astryx's components link by default. - Relies on `spec:AST-112` FR4 (amended): native code uses public platform API only, and a record names any exception (FR18). -- Relies on `spec:AST-140` FR5: every contract is at revision 1, - later behaviour is a named feature the platform info module lists, and no - contract carries a revision counter (FR3, FR13, FR17). +- Relies on `spec:AST-140` FR5: each contract's baseline is its first + release's shape, later behaviour is a named feature the platform info + module lists, and a contract has no revision number (FR3, FR13, FR17). - `spec:AST-093/FR5` (every native component is tested and validated the same way) applies to `WebView` and `WebContent` unchanged. @@ -383,7 +384,7 @@ grantsOrigin?}` (an HTML string). | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader; the `./web` export list | `web` opted out; opted in | An opted-out app links WebKit, `./web` exports a module outside the core package, or the library imports the capability outside its loader | | FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | -| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision counter or a feature list of its own | +| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision number or a feature list of its own | | FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR18's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | | FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out; a script navigation and a server redirect to another origin; a first load that redirects; a person's form on a page a redirect reached on another origin | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason; a navigation no person caused leaves the view or sends an event; or the first page's origin follows its redirects; or that form stays in the view | | FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | @@ -397,7 +398,7 @@ grantsOrigin?}` (an HTML string). | FR14 | Platform tests through the `./testing` doubles | a colour scheme or text scale change on a loaded page | The new value does not reach the page, or an event's shape differs from the library's | | FR15 | Platform tests with the module absent, not linked, and switched off | a `NativeWebView` with and without `fallback`; a module call | `fallback` is not drawn, `no-native-view` is reported more than once, or a call rejects | | FR16 | VoiceOver and TalkBack checks on the Simulator, emulator, and device; text-size checks | a page with headings, links, and a form; the largest text size | The page's content is not read, the platform hides part of it, or the text does not scale | -| FR17 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the revision-1 behaviour or answering `unsupported` | +| FR17 | Unit tests through `./testing` doubles of a binary without a named feature | each named feature absent | The JavaScript uses a feature the binary does not list, or falls back silently instead of keeping the baseline behaviour or answering `unsupported` | | FR18 | Source check of the native code's symbols on both platforms; Simulator check with the opt-in on and off | the default app; an app that opts in to `web.privateHardening` | A private symbol is used without the opt-in, or on Android at all | ## Decision log From a7e3fdde52b1845a9c40ffe3ac6d31107a92cd20 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:01:41 -0800 Subject: [PATCH 17/23] spec(AST-131): no clear call for shared page data; content process end from Android 8.0 --- .../AST-131-react-native-web-view/spec.md | 25 +++++++++++++------ 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index edc2d9998d89a..93c867671ccfd 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -145,7 +145,8 @@ grantsOrigin?}` (an HTML string). `allowedExternalSchemes` (FR5). - Each contract's baseline is its first release's shape (`spec:AST-140/FR5`). The web view's named features (FR13) are listed with - every other contract's by the platform info module; `AstryxWebViewInfo` + every other contract's by the platform info module (`spec:AST-130`); + `AstryxWebViewInfo` carries no feature list and no revision number. - **FR4 — Safe defaults.** A page in the view cannot read local files or @@ -168,7 +169,9 @@ grantsOrigin?}` (an HTML string). - The view shows the first page, and any top-level page on that page's origin or on an origin listed in `allowedOrigins`. The first page's origin is the origin of the source the caller passed (`url`, or `baseUrl` with - `grantsOrigin`), whatever the first load's redirects reach. The policy covers + `grantsOrigin`), whatever the first load's redirects reach. An HTML string + without `grantsOrigin` has an opaque origin, which no web origin matches, + so only `allowedOrigins` keep a navigation in the view. The policy covers top-level navigation only; images, scripts, and frames load as the page's own rules allow. - A top-level navigation to any other origin that a person causes (tapping @@ -182,7 +185,8 @@ grantsOrigin?}` (an HTML string). no event; only a pin limits it. A page reached that way does not change the view's own origin: a person's link or form there to an origin that is neither the first page's nor allowed follows `externalNavigation`, and - the message channel does not accept that page's messages (FR8). + on a device with channel isolation the message channel does not accept + that page's messages (FR8). - A non-web scheme opens outside the view only when it is in `allowedExternalSchemes` (default `mailto`, `tel`, `sms`; an empty list allows none). Any other scheme is cancelled and reported as @@ -218,9 +222,10 @@ grantsOrigin?}` (an HTML string). goes. A change reloads the page. - Pages in views without an ephemeral store share the runtime's page data. Where the device can keep it apart from the app's network cookies (the - `pageProfile` constant), clearing page data never signs the app's own - requests out. Where it cannot, those pages run with no page storage, and - clearing page data still leaves the app's network cookies. + `pageProfile` constant), it is kept apart. Where it cannot, those pages + run with no page storage. The `web` capability has no call that clears + the shared page data; an app that needs one uses its host platform's + implementation (`spec:AST-112/FR20`). - **FR8 — One message channel.** - The page sends with `window.astryx.postMessage(string)`. On a device with channel isolation, the view accepts a message only from the main frame, @@ -256,6 +261,9 @@ grantsOrigin?}` (an HTML string). true (the default) the view reloads the page on its own. With false, the view shows nothing until the app calls `ref.reload()` or mounts it again, so the screen can show its own message. The app keeps running in every case. + Android reports a content process end from Android 8.0; before it, the + binary reports `contentProcessEnd` as not supported, and a content process + end can end the app. - **FR11 — Capture prevention and the link menu.** - `preventsCapture` keeps screenshots, screen recordings, and the app switcher's image of the window out while the view is on screen, however @@ -296,7 +304,8 @@ grantsOrigin?}` (an HTML string). (`spec:AST-140/FR5`): `preventsCapture` on iOS; `linkMenu` on Android. - `AstryxWebViewInfo.supports(feature)` answers true when the binary reports the feature as supported and, for `channelIsolation` and `pageProfile`, the device's - constant is not false. `isAvailable()` answers whether the module is + constant is not false; `contentProcessEnd` also needs Android 8.0 or + later (FR10). `isAvailable()` answers whether the module is linked. Without it (not opted in, Jest, the web), nothing is claimed. - The library's `useWebViewSupports(feature)` answers the same, and false without a web view. @@ -391,7 +400,7 @@ grantsOrigin?}` (an HTML string). | FR7 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | | FR8 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation; a page a redirect reached on another origin | An iframe's message is delivered as the main frame's, an origin comes from the page's data, or a message from a page outside the first page's and allowed origins is delivered | | FR9 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | -| FR10 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()` | The app ends, the event reaches `onError`, or a view with reload off reloads by itself | +| FR10 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()`; Android 7.x | The app ends, the event reaches `onError`, or a view with reload off reloads by itself, or Android 7.x reports `contentProcessEnd` as supported | | FR11 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | | FR12 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | | FR13 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary reports it as not supported, a feature a platform lacks is reported supported there or missing from the report, or a device constant is ignored | From ad1477892cacf25e45237153f3d3a749e5db4fd2 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:41:08 -0800 Subject: [PATCH 18/23] spec(AST-131): the app keeps running on devices that report a content process end --- docs/specs/AST-131-react-native-web-view/spec.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 93c867671ccfd..0946388d482aa 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -171,7 +171,8 @@ grantsOrigin?}` (an HTML string). is the origin of the source the caller passed (`url`, or `baseUrl` with `grantsOrigin`), whatever the first load's redirects reach. An HTML string without `grantsOrigin` has an opaque origin, which no web origin matches, - so only `allowedOrigins` keep a navigation in the view. The policy covers + so only `allowedOrigins` keep a person's navigation in the view; the + channel accepts that document's own messages (FR8). The policy covers top-level navigation only; images, scripts, and frames load as the page's own rules allow. - A top-level navigation to any other origin that a person causes (tapping @@ -260,10 +261,10 @@ grantsOrigin?}` (an HTML string). not fire for it, because the page loaded. With `reloadsOnContentProcessEnd` true (the default) the view reloads the page on its own. With false, the view shows nothing until the app calls `ref.reload()` or mounts it again, so - the screen can show its own message. The app keeps running in every case. - Android reports a content process end from Android 8.0; before it, the - binary reports `contentProcessEnd` as not supported, and a content process - end can end the app. + the screen can show its own message. On a device that reports + `contentProcessEnd` (iOS, and Android 8.0 and later), the app keeps running + in every case. Before Android 8.0 the binary reports `contentProcessEnd` as + not supported, and a content process end can end the app. - **FR11 — Capture prevention and the link menu.** - `preventsCapture` keeps screenshots, screen recordings, and the app switcher's image of the window out while the view is on screen, however @@ -400,7 +401,7 @@ grantsOrigin?}` (an HTML string). | FR7 | Unit tests of the session refusals; Simulator and emulator checks of page data | a handle; an empty handle; a handle from another runtime; an ephemeral view; page storage off; a device without separate page data | A cookie value appears in props, an empty or foreign handle loads the page, an ephemeral view leaves data behind, or a page-storage-off page keeps storage | | FR8 | Unit tests through the doubles; Simulator and emulator scripts | both directions; a message from an iframe; a device without channel isolation; a page a redirect reached on another origin | An iframe's message is delivered as the main frame's, an origin comes from the page's data, or a message from a page outside the first page's and allowed origins is delivered | | FR9 | Simulator and emulator renders | light, dark, and system schemes; no `textScale` at the largest system text size; text scale 2; auto height; a custom user agent | The page ignores the scheme or text scale, unscaled text without the prop, a stale height, or a non-ASCII user agent applied | -| FR10 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()`; Android 7.x | The app ends, the event reaches `onError`, or a view with reload off reloads by itself, or Android 7.x reports `contentProcessEnd` as supported | +| FR10 | Device-level termination checks on the Simulator and emulator | reload on; reload off then `reload()`; Android 7.x | On a device that reports `contentProcessEnd`, the app ends, the event reaches `onError`, or a view with reload off reloads by itself; or Android 7.x reports `contentProcessEnd` as supported | | FR11 | Emulator check of capture; unit tests of the link-menu matchers shared by every platform; Simulator long press | a protected view; matchers with schemes, hosts, `*.` over a public suffix, prefixes | A screenshot captures a protected view on Android, a `javascript:` link gets a menu, or a menu loads a preview | | FR12 | Unit tests through the doubles in their absent, older, and current shapes | each reason; an unknown native reason; a refusal | A call throws, a reason falls outside the set, or a refusal crosses to the host | | FR13 | Unit tests of `supports` through `./testing` doubles of binaries with and without each feature, per platform and device constant | each feature on iOS and Android; no module | A feature answers true when the binary reports it as not supported, a feature a platform lacks is reported supported there or missing from the report, or a device constant is ignored | From ca838ff1e77062a80972478446ad4690d32863e0 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 11:37:49 -0800 Subject: [PATCH 19/23] spec(AST-131: WebView is the public face of an internal native view; positive sweep) --- .../AST-131-react-native-web-view/spec.md | 276 ++++++++---------- 1 file changed, 120 insertions(+), 156 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 0946388d482aa..ba3443c29c45f 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -23,11 +23,11 @@ affects_consumer_docs: [] ## Intent An app shows web content inside a screen: a help page, a terms page, a sign-in -or payment page in place, or an HTML document the app built. The developer gets one web view that -is safe by default: links to other sites open in the system browser, the page -cannot reach the device's files or open pop-up windows, the page follows the -app's light or dark mode and text size, and the app and the page talk over one -message channel. The person sees the page as part of the screen, and a screen +or payment page in place, or an HTML document the app built. The developer +gets one web view that is safe by default: links to other sites open in the +system browser, the page runs in one window sandboxed from the device's files, +the page follows the app's light or dark mode and text size, and the app and +the page talk over one message channel. The person sees the page as part of the screen, and a screen reader reads the page's own content. This record details the `web` capability of `spec:AST-112`: the platform layer @@ -38,82 +38,59 @@ evolution (`spec:AST-140/FR5`). It specifies the native web view (`AstryxWebView`), its device report (`AstryxWebViewInfo`), and the part of the session registry (`AstryxWebSessions`) the view depends on, which the library's `WebView` and `WebContent` use; the three are core, within the -opt-in `web` capability. Web data, bundled web content, web sign-in, and page snapshots are not part of -the `web` capability: no Astryx component uses them, so they are outside the -core package, and an app uses its host platform's implementation or an open-source library for them (`spec:AST-112/FR20`); "Who uses it" lists them. +opt-in `web` capability. `WebView` is the web view's public face; the native +view is internal implementation behind it (`spec:AST-112/FR5`, +`spec:AST-112/FR21`). ## Why this exists -- `AstryxWebView`: an app cannot add these guarantees from outside an - ecosystem web view component, so Astryx owns the view. A pin holds across - redirects and is decided natively (FR5, DEC-1). A session's cookie values - never appear in props (FR7, DEC-3). Pages can run with no storage (FR7). The +- `AstryxWebView`: these guarantees live inside the view itself, so Astryx + owns the view. A pin holds across redirects and is decided natively (FR5, + DEC-1). A session crosses as a handle, so its cookie values stay native + (FR7, DEC-3). Pages can run with page storage off (FR7). The message sender comes from the engine (FR8, DEC-2). Loads report closed reasons (FR12). The package keeps one dependency set (`spec:AST-112/FR2`). Astryx takes no third-party native dependency for the web view; an app may use react-native-webview beside these components without conflict (`spec:AST-140/FR9`). - `AstryxWebViewInfo`: it answers what the device can keep (a frame-safe - channel, separate page data), so a caller that needs a guarantee is refused - loudly instead of getting a weaker page (DEC-4). OQ5 asks whether it folds + channel, separate page data), so a caller that needs a guarantee learns up + front whether the device keeps it (DEC-4). OQ5 asks whether it folds into the platform info. - `AstryxWebSessions`: it holds an embedded page's session natively, so `WebView` passes a handle instead of cookie values (FR7, DEC-3). OQ6 asks whether its create and remove calls belong in this record. -- Web data, bundled web content, web sign-in, and page snapshots: no Astryx - component uses them, so they are outside the core package and the `web` - capability, and an app uses its host platform's implementation or an open-source library for them (`spec:AST-112/FR20`). ## Who uses it -| Native piece | Kind | Astryx components that use it | What a person sees | -| --------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | native component (Fabric Native Component) | `WebView`; `WebContent` (through `WebView`); apps through the `./web` entry's `NativeWebView` | A web page or an HTML document inside the screen, in the app's colour scheme and text size | -| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through `NativeWebView`'s checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; a page that needs a guarantee the device lacks does not load, and the screen says why | -| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` uses it through its session handle (`session={{sessionId}}`, FR7): the native view resolves the handle; core, within the `web` capability | A signed-in embedded page | -| `AstryxWebData` | native module (Turbo Native Module) | No Astryx component uses it; outside the core package and the `web` capability (`spec:AST-112/FR20`) | Web pages that keep nothing after sign-out | -| `AstryxWebBundles` | native module (Turbo Native Module) | No Astryx component uses it; outside the core package and the `web` capability (`spec:AST-112/FR20`) | A bundled web app that works offline | -| `AstryxAuthSession` | native module (Turbo Native Module) | No Astryx component uses it; outside the core package and the `web` capability (`spec:AST-112/FR20`) | The system's sign-in sheet | -| `AstryxPageSnapshots` | native module (Turbo Native Module) | No Astryx component uses it; outside the core package and the `web` capability (`spec:AST-112/FR20`) | A thumbnail of an HTML document | +| Native piece | Kind | Astryx components that use it | What a person sees | +| ------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | native component (Fabric Native Component) | `WebView`, its public face; `WebContent` (through `WebView`) | A web page or an HTML document inside the screen, in the app's colour scheme and text size | +| `AstryxWebViewInfo` | native module (Turbo Native Module) | `WebView` and `WebContent` (through the checks before a load); the `useWebViewSupports` hook and the capability status of `useCapabilities` | Nothing directly; where the device lacks a guarantee a page needs, the screen explains it in the page's place | +| `AstryxWebSessions` | native module (Turbo Native Module) | `WebView` uses it through its session handle (`session={{sessionId}}`, FR7): the native view resolves the handle; core, within the `web` capability | A signed-in embedded page | Note: `AstryxWebSessions` (core) holds an embedded page's cookies, store, and pin natively under an opaque handle that the view's `sessionId` prop names -(FR7). The other four rows name native pieces that Astryx does not ship as -part of this capability; an app that needs them uses its host platform's -implementation or an open-source library (`spec:AST-112/FR20`). +(FR7). ## Non-goals -- The contract of the library's `WebView` and `WebContent` components: their - props, layout, loading and failure states, and fallback content. Each - component's own record and `spec:AST-082/FR3` own it. -- Web data, bundled web content, web sign-in, and page snapshots - (`AstryxWebData`, `AstryxWebBundles`, `AstryxAuthSession`, - `AstryxPageSnapshots`): outside the core package and the `web` capability, - because no Astryx component uses them (`spec:AST-112/FR20`). -- `AstryxWebSessions` beyond the handle the view depends on (FR7; OQ6). -- Astryx Stage (`spec:AST-139`) and Preview in the Astryx app (`spec:AST-141`) are separate products; they conform to this record's contracts. -- Browser features the view does not offer: downloads, file upload pickers, - geolocation, WebRTC, pop-up windows, and pull-to-refresh. -- Equivalent internal implementations remain valid when they satisfy this - contract. -- Internal modules, files, function names, algorithms, data structures, storage - layouts, manifests, journals, locks, transaction protocols, and CI job/workflow - topology belong in architecture or implementation unless callers or - interoperating systems intentionally depend on that exact mechanism as a public - protocol. In that case, state who depends on it and why an equivalent - implementation would not satisfy the contract. +None. ## Requirements - **FR1 — `web` is an opt-in capability.** The web view, its device report, and the session registry belong to the `web` capability, which an app opts - in (`spec:AST-112/FR3`). An app that does not opt it in links no web engine. - The `./web` entry exports `NativeWebView`, `isNativeWebViewAvailable()`, - `AstryxWebViewInfo`, and `AstryxWebSessions`. The library reaches the + in (`spec:AST-112/FR3`); an app links the web engine when it opts `web` in. + The `./web` entry exports `WebView`, `WebContent`, `AstryxWebViewInfo`, and + `AstryxWebSessions`. The native view stays internal behind `WebView` + (`spec:AST-112/FR5`). The library reaches the capability only through `AstryxPlatform.capability('web')` (`spec:AST-112/FR2`). -- **FR2 — `NativeWebView` is the platform's web view.** Its props: +- **FR2 — `NativeWebView` is the platform's web view behind `WebView`.** + `NativeWebView` is the library's internal wrapper of the native view; + `WebView` renders it, and `WebContent` reaches it through `WebView`. Its + props: - `source`, one of `{uri}` (an http or https page) or `{html, baseUrl?, grantsOrigin?}` (an HTML string). - Navigation: `allowedOrigins`, `externalNavigation`, `allowedExternalSchemes` @@ -143,22 +120,20 @@ grantsOrigin?}` (an HTML string). | `AstryxWebViewInfo` | native module (Turbo Native Module) | `getConstants()`: the device constants `channelIsolation` and `pageProfile` (FR7, FR8) | iOS, Android | - `noExternalSchemes` is the host's form of an empty `allowedExternalSchemes` (FR5). - - Each contract's baseline is its first release's shape - (`spec:AST-140/FR5`). The web view's named features (FR13) are listed with - every other contract's by the platform info module (`spec:AST-130`); - `AstryxWebViewInfo` - carries no feature list and no revision number. - -- **FR4 — Safe defaults.** A page in the view cannot read local files or - content URIs, cannot open a second window, cannot ask for the device's - location, and cannot load http content into an https page. Before the - page's own script runs, every frame that runs script, the main frame and - iframes alike, loses WebRTC (`RTCPeerConnection`, `navigator.mediaDevices`), - DNS prefetching, and the `preconnect` relation on links; a same-origin - frame the page creates is covered when the page reaches it. The view's only - other script in a page is its own page script, which - carries the message channel (FR8), the colour scheme and text scale (FR9), - and the content height. No prop lets a caller add a script. + - Contracts grow by named features (`spec:AST-140/FR5`). The platform info + module (`spec:AST-130`) lists the web view's named features (FR13) with + every other contract's. + +- **FR4 — Safe defaults.** A page in the view sees web content only: local + files and content URIs, a second window, the device's location, and http + content inside an https page stay closed to it. Before the page's own + script runs, every frame that runs script, the main frame and iframes + alike, has WebRTC (`RTCPeerConnection`, `navigator.mediaDevices`), DNS + prefetching, and the `preconnect` relation on links switched off; a + same-origin frame the page creates is covered when the page reaches it. The + view adds one script to a page, its own page script, which carries the + message channel (FR8), the colour scheme and text scale (FR9), and the + content height (DEC-2). FR4 gap: without the opt-in of FR18, a `preconnect` link that the HTML parser inserts, or one in a frame that runs no script, can still open a @@ -178,16 +153,16 @@ grantsOrigin?}` (an HTML string). - A top-level navigation to any other origin that a person causes (tapping a link, sending a form, a `target=_blank` link, `window.open`) follows `externalNavigation`: `allow` (the default) opens it in the system browser - and sends `onOpenExternal`; `report` opens nothing and sends - `onNavigationBlocked` with `external` or `newWindow`; `block` opens - nothing and sends nothing. + and sends `onOpenExternal`; `report` keeps the person on the page and + sends `onNavigationBlocked` with `external` or `newWindow`; `block` keeps + the person on the page silently. - A top-level navigation that no person caused (a server redirect, a - script, a meta refresh) stays in the view whatever its origin, and sends - no event; only a pin limits it. A page reached that way does not change - the view's own origin: a person's link or form there to an origin that is - neither the first page's nor allowed follows `externalNavigation`, and - on a device with channel isolation the message channel does not accept - that page's messages (FR8). + script, a meta refresh) stays in the view whatever its origin, silently; + a pin is what limits it. A page reached that way leaves the view's own + origin as it was: a person's link or form there to an origin outside the + first page's and the allowed ones follows `externalNavigation`, and on a + device with channel isolation the message channel accepts messages only + from the first page's and allowed origins (FR8). - A non-web scheme opens outside the view only when it is in `allowedExternalSchemes` (default `mailto`, `tel`, `sms`; an empty list allows none). Any other scheme is cancelled and reported as @@ -196,8 +171,8 @@ grantsOrigin?}` (an HTML string). segments, `/` when absent) limits every top-level navigation to that origin and path, and a redirect counts as a navigation. The view stops a navigation outside the pin and reports it with reason `pin`. - - No navigation waits on JavaScript: the view decides from these props, and - the events reach JavaScript after the decision. + - The view decides each navigation natively from these props, and the + events reach JavaScript after the decision. - **FR6 — An HTML string has an opaque origin unless granted one.** With `{html}` the page has an opaque origin: no site's cookies or storage, and relative links do not resolve. With `grantsOrigin: true` and an http or @@ -206,12 +181,12 @@ grantsOrigin?}` (an HTML string). - **FR7 — Sessions and page storage.** - `session` is `{sessionId}` (a handle `AstryxWebSessions.create` answered) or options: `isEphemeral`, `pin` (FR5), and `allowsPageStorage`. A handle - wins over the options. An empty or unknown handle loads nothing and - reports `invalid-config`. + wins over the options. An empty or unknown handle reports + `invalid-config` in place of a load. - The part of `AstryxWebSessions` the view depends on: a handle works only in the runtime that created it, and the session's cookies, ephemeral - store, page-storage setting, and pin apply to the view without their - values appearing in its props. A view that loaded with a session keeps + store, page-storage setting, and pin apply to the view while their values + stay native, out of its props. A view that loaded with a session keeps it after `AstryxWebSessions.remove`. - `isEphemeral` gives the view a private store that leaves no data behind: its cookies, storage, and HTTP cache are gone when the view goes, and the @@ -224,26 +199,23 @@ grantsOrigin?}` (an HTML string). - Pages in views without an ephemeral store share the runtime's page data. Where the device can keep it apart from the app's network cookies (the `pageProfile` constant), it is kept apart. Where it cannot, those pages - run with no page storage. The `web` capability has no call that clears - the shared page data; an app that needs one uses its host platform's - implementation (`spec:AST-112/FR20`). + run with page storage off. - **FR8 — One message channel.** - The page sends with `window.astryx.postMessage(string)`. On a device with channel isolation, the view accepts a message only from the main frame, and only when that frame is on the first page's origin (FR5) or an allowed origin, and sends `onMessage({data, origin, isMainFrame})`. `origin` and - `isMainFrame` come from the engine, never from the page's data. + `isMainFrame` come from the engine, so a page cannot forge them. - The app sends with `ref.postMessage(data)` (the `postMessage` command). The page receives it through `window.astryx.addListener` and as a `message` event on `window` (`event.data`, a string). - Where the device's web engine cannot tell frames apart, the binary reports `channelIsolation` false and the sender as `origin: "null"`, - `isMainFrame: false`. An app that must know the sender ignores those - messages. + `isMainFrame: false`. An app that must know the sender acts only on + messages with a known sender. - **FR9 — The page follows the app's appearance.** - `colorScheme` (`light`, `dark`, or `system`) sets what the page reads from - `prefers-color-scheme`, and the engine does not darken the page by - itself. Without the prop, `NativeWebView` takes the platform appearance's + `prefers-color-scheme`, and the page's own styles draw its dark look. Without the prop, `NativeWebView` takes the platform appearance's scheme, else `system`. - `textScale` scales the page's text. Without the prop, it is the system's font scale, so the page's text follows the person's text size. @@ -251,16 +223,16 @@ grantsOrigin?}` (an HTML string). so a caller lays the page out at its height with `isScrollEnabled: false` inside an outer scroll view. - `applicationNameForUserAgent` is appended to the user agent, and - `userAgent` replaces it (and wins over the appended name). A value with - anything other than printable ASCII is not applied: the default user agent - stays, and `onError` reports `invalid-config`. + `userAgent` replaces it (and wins over the appended name). A value is + applied when it is printable ASCII; for any other value the default user + agent stays, and `onError` reports `invalid-config`. - **FR10 — A content process end is reported, and the app picks the recovery.** When the page's content process ends, the view sends `onContentProcessEnded({reason, willReload, url})` with `reason` - `terminated`, `crashed`, `killed-for-memory`, or `unknown`. `onError` does - not fire for it, because the page loaded. With `reloadsOnContentProcessEnd` + `terminated`, `crashed`, `killed-for-memory`, or `unknown`. It goes to this + event alone, because the page loaded. With `reloadsOnContentProcessEnd` true (the default) the view reloads the page on its own. With false, the - view shows nothing until the app calls `ref.reload()` or mounts it again, so + view stays empty until the app calls `ref.reload()` or mounts it again, so the screen can show its own message. On a device that reports `contentProcessEnd` (iOS, and Android 8.0 and later), the app keeps running in every case. Before Android 8.0 the binary reports `contentProcessEnd` as @@ -268,28 +240,28 @@ grantsOrigin?}` (an HTML string). - **FR11 — Capture prevention and the link menu.** - `preventsCapture` keeps screenshots, screen recordings, and the app switcher's image of the window out while the view is on screen, however - many views ask for it. iOS has no view-level equivalent: it ignores the - prop, shows the page, and reports the feature as not supported, so capture - prevention there is best effort. A caller that requires it checks + many views ask for it. On iOS the page shows and the binary reports the + feature with `isSupported` false, so capture prevention there is best + effort. A caller that requires it checks `supports('preventsCapture')` first. - `linkMenu` describes the menu a long press on a link shows: actions (`id`, `title`, an optional icon, `destructive`) with declarative matchers - (`schemes`, `hosts` with `*.` patterns that never match a public - suffix, and whole-segment `pathPrefix`), and a title of the link or none. - A menu appears only for http, https, `mailto`, `tel`, and `sms` links; a - matcher can exclude links but cannot add a scheme. When a person picks an - action, the view sends `onLinkMenuAction({id, href})` and does not follow - the link. The menu never loads or shows a preview of the target. When no - action matches, the long press shows no menu. The page controls `href`, - so the app validates it before acting on it. + (`schemes`, `hosts` with `*.` patterns that match only below a + public suffix, and whole-segment `pathPrefix`), and an optional title of + the link. A menu appears for http, https, `mailto`, `tel`, and `sms` + links, and a matcher narrows that set. When a person picks an action, the + view sends `onLinkMenuAction({id, href})` and stays on the page. The menu + shows its actions and title and loads nothing from the target. A long + press shows a menu when at least one action matches. The page controls + `href`, so the app validates it before acting on it. - **FR12 — Loads report results in a closed set.** `onError` receives `{ok: false, reason, message, url}` with `reason` from `offline`, `timeout`, `ssl`, `invalid-url`, `invalid-config`, `unsupported`, `no-native-view`, and `error`; a reason the JavaScript does not know reads `error` - (`spec:AST-140/FR3`). `message` never carries a URL's query or a cookie. The - JavaScript checks the session and the source first. When it knows the view - cannot honour them, it does not render the host view and reports the reason - through `onError` one time for that page. + (`spec:AST-140/FR3`). `message` names the failure and leaves out URL queries + and cookies. The JavaScript checks the session and the source first. When + the view cannot honour them, the JavaScript reports the reason through + `onError` once for that page in place of rendering the host view. - **FR13 — The web view's behaviour beyond the baseline is named features.** `AstryxWebView`'s baseline is loading a page or an HTML string, the safe defaults (FR4), navigation to the page's own and allowed origins, the @@ -306,18 +278,18 @@ grantsOrigin?}` (an HTML string). - `AstryxWebViewInfo.supports(feature)` answers true when the binary reports the feature as supported and, for `channelIsolation` and `pageProfile`, the device's constant is not false; `contentProcessEnd` also needs Android 8.0 or - later (FR10). `isAvailable()` answers whether the module is - linked. Without it (not opted in, Jest, the web), nothing is claimed. + later (FR10). `isAvailable()` answers whether the module is linked; + without it (not opted in, Jest, the web), every feature answers false. - The library's `useWebViewSupports(feature)` answers the same, and false without a web view. -- **FR14 — The caller supplies the appearance.** `NativeWebView` has no - theme of its own. Its caller passes the colour scheme and text scale to use +- **FR14 — The caller supplies the appearance.** `NativeWebView` takes its + appearance from its caller: the caller passes the colour scheme and text scale to use (the library passes its theme's), and the view applies a new value to the loaded page. The view's events are the same one-object shapes the library hands to its own callers. - **FR15 — Fallbacks when `web` is not linked or the view is absent.** - - Not opted in: the capability's module still loads; `isNativeWebViewAvailable()` - and `AstryxWebViewInfo.isAvailable()` answer false, and module calls + - Not opted in: the capability's module still loads; the library's internal + view probe and `AstryxWebViewInfo.isAvailable()` answer false, and module calls resolve `not-linked` (`spec:AST-112/FR3`, `spec:AST-140/FR2`). A missing view of an opted-in capability reports `no-native-view`. - `NativeWebView` where the view is absent renders `fallback` (nothing by @@ -328,15 +300,14 @@ grantsOrigin?}` (an HTML string). `postMessage` does nothing there. - **FR16 — Accessibility.** The engine exposes the page's own structure (headings, links, form fields, text) to VoiceOver and TalkBack, and the - platform neither adds to it nor hides it. The view has no accessible name of - its own: the caller names the region on a containing view (the library's - components require a label). The page's text follows the system text size + platform passes it through as the page builds it. The caller names the + region on a containing view, and the library's components take a required + label. The page's text follows the system text size through `textScale` (FR9). The link menu is the system's context menu. -- **FR17 — Contract baseline.** Each contract's baseline is its first - release's shape (`spec:AST-140/FR5`). JavaScript checks a named feature - (FR13) before it uses the behaviour; without it, JavaScript keeps the - baseline behaviour or answers `unsupported`, never a silent weaker path - (DEC-4). +- **FR17 — Named features are checked before use.** Contracts grow by named + features (`spec:AST-140/FR5`). JavaScript checks a named feature (FR13) + before it uses the behaviour; in a binary without it, JavaScript keeps the + baseline behaviour or answers `unsupported` (DEC-4). - **FR18 — Native code uses public platform API only.** The web view and its core modules (`AstryxWebViewInfo`, `AstryxWebSessions`) use only public platform API (`spec:AST-112/FR4`). One exception exists, and it is off by @@ -352,10 +323,10 @@ grantsOrigin?}` (an HTML string). ### Platform support -| Contract | iOS | Android | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | WebKit (`WKWebView`). Every named feature except `preventsCapture`, which iOS ignores because it has no view-level capture protection. | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature except `linkMenu`, which Android ignores. A content process end is reported on Android 8.0 and later. | -| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | +| Contract | iOS | Android | +| ------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | WebKit (`WKWebView`). Every named feature; `preventsCapture` is best effort (FR11). | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature but `linkMenu`. A content process end is reported on Android 8.0 and later. | +| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | - Supported feature/engine floor: the floor of `spec:AST-112` (iOS at React Native's minimum, Android API level 24, the New Architecture only), with the @@ -371,20 +342,17 @@ grantsOrigin?}` (an HTML string). - Relies on `spec:AST-112` FR1 (amended): the `web` capability holds the web view, its device report, and the session registry. -- Relies on `spec:AST-112` FR20 (amended): native capabilities no Astryx - component uses are outside the core package, and an app uses its host - platform's implementation or an open-source library for them; web data, - bundled web content, web sign-in, and page snapshots are such - capabilities. +- Relies on `spec:AST-112` FR5 and FR21 (amended): native views are internal + implementation behind components, and `WebView` is the web view's public + face (FR1, FR2). - Relies on `spec:AST-112` FR7 (amended): each group of the platform has its own record, and this is the web group's. - Relies on `spec:AST-112` FR3 (amended): the `web` capability is a device feature an app opts in; Astryx's components link by default. - Relies on `spec:AST-112` FR4 (amended): native code uses public platform API only, and a record names any exception (FR18). -- Relies on `spec:AST-140` FR5: each contract's baseline is its first - release's shape, later behaviour is a named feature the platform info - module lists, and a contract has no revision number (FR3, FR13, FR17). +- Relies on `spec:AST-140` FR5: contracts grow by named features, which the + platform info module lists (FR3, FR13, FR17). - `spec:AST-093/FR5` (every native component is tested and validated the same way) applies to `WebView` and `WebContent` unchanged. @@ -392,9 +360,9 @@ grantsOrigin?}` (an HTML string). | Contract | Verification | Representative states | Mutation or failure expectation | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader; the `./web` export list | `web` opted out; opted in | An opted-out app links WebKit, `./web` exports a module outside the core package, or the library imports the capability outside its loader | +| FR1 | Built app with the core only compared with one that opts `web` in; unit tests of the loader; the `./web` export list | `web` opted out; opted in | An opted-out app links WebKit, `./web` exports the native view, or the library imports the capability outside its loader | | FR2 | Unit tests of `NativeWebView` through the `./testing` doubles | each source kind; each event; the `ref` handle | An event arrives with more than one argument, or a prop does not reach the host | -| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, a shipped member changes, or a contract carries a revision number or a feature list of its own | +| FR3 | The platform's spec rules check of the codegen specs | the view's props, commands, and events; the module's constants | A listed member is missing, or a shipped member changes | | FR4 | Simulator and emulator checks with a hostile page; tests that keep the page protection equal on every platform; the same checks with FR18's opt-in on iOS | a page that opens WebRTC, a pop-up, a file URL, mixed content, a preconnect link, inside a scripted iframe; a parser-inserted preconnect link and a new blank frame (the named gap) | Any of them succeeds in a frame that runs script, or the named gap is not closed on iOS with the opt-in | | FR5 | Simulator and emulator scripts | an allowed origin; another origin under `allow`, `report`, `block`; a blocked scheme; a pin with a redirect out; a script navigation and a server redirect to another origin; a first load that redirects; a person's form on a page a redirect reached on another origin | A navigation outside policy stays in the view, opens without its event, or sends the wrong reason; a navigation no person caused leaves the view or sends an event; or the first page's origin follows its redirects; or that form stays in the view | | FR6 | Simulator and emulator checks | `html` with and without `grantsOrigin` | An ungranted page reads the base origin's cookies or storage | @@ -420,10 +388,8 @@ grantsOrigin?}` (an HTML string). Allowed origins, the pin, external navigation, and external schemes are props, and the native view decides each navigation on the UI thread. A pin holds -across redirects, and no navigation waits on JavaScript or races a load. - -Rejected: a JavaScript callback per navigation, because it blocks the UI thread -or lets the load run ahead of the answer. +across redirects, and each navigation is decided before its load starts, +with no JavaScript round trip on the UI thread. ### DEC-2 — One message channel; the sender comes from the engine @@ -433,10 +399,9 @@ or lets the load run ahead of the answer. The page and the app talk only through `window.astryx` and the `postMessage` command. On a device with channel isolation, the view accepts only the main frame of the first page's or an allowed origin, and reports the sender's -origin from the engine, so a frame cannot forge it. - -Rejected: an injected-script prop, because any script then runs with the -page's full rights and the channel's rules no longer hold. +origin from the engine, so a frame cannot forge it. The view adds one +script to a page, its own, because any other script would run with the +page's full rights outside the channel's rules. ### DEC-3 — Sessions cross as native handles @@ -444,8 +409,8 @@ page's full rights and the channel's rules no longer hold. **Decider:** imdreamrunner, 2026-11-17 An embedded page's cookies, store, and pin are created natively once and -named by an opaque handle that the view's props carry. Cookie values never -appear in props, development tools, or logs. +named by an opaque handle that the view's props carry. Cookie values stay +native, out of props, development tools, and logs. ### DEC-4 — A guarantee the binary cannot keep refuses the load @@ -453,13 +418,11 @@ appear in props, development tools, or logs. **Decider:** imdreamrunner, 2026-11-17 When a caller asks for a privacy or isolation guarantee (page storage off, a -frame-safe channel) and the binary or device cannot keep it, -nothing loads and `onError` reports `unsupported`. A caller checks +frame-safe channel) and the binary or device cannot keep it, `onError` +reports `unsupported` in place of the load, because a working page without +the guarantee would leak what the app meant to keep. A caller checks `supports(feature)` first and picks its own path. -Rejected: loading the page without the guarantee, because the person would see -a working page that leaks what the app meant to keep. - ## Open questions - **OQ1 — Does `WebView` create and remove its session handle itself?** @@ -467,7 +430,8 @@ a working page that leaks what the app meant to keep. `AstryxWebSessions` and passes `session={{sessionId}}`; or `WebView` takes the session's options and manages the handle for the caller. - **OQ2 — Do `WebView` and `WebContent` expose `preventsCapture`, - `linkMenu`, and `allowedExternalSchemes`, which only `NativeWebView` takes?** + `linkMenu`, and `allowedExternalSchemes`, which the internal + `NativeWebView` takes?** (`human-api`) - **OQ3 — Does Android build the link menu, or does it stay an iOS-only feature?** (`human-design`) From b0d0449e8767abbf058be07534af596f65129526 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:02:05 -0800 Subject: [PATCH 20/23] spec(AST-131): cite the foundation's FR5 for internal native views --- docs/specs/AST-131-react-native-web-view/spec.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index ba3443c29c45f..c4e00f180871e 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -39,8 +39,7 @@ evolution (`spec:AST-140/FR5`). It specifies the native web view the session registry (`AstryxWebSessions`) the view depends on, which the library's `WebView` and `WebContent` use; the three are core, within the opt-in `web` capability. `WebView` is the web view's public face; the native -view is internal implementation behind it (`spec:AST-112/FR5`, -`spec:AST-112/FR21`). +view is internal implementation behind it (`spec:AST-112/FR5`). ## Why this exists @@ -296,7 +295,7 @@ grantsOrigin?}` (an HTML string). default) and reports `onError` with `no-native-view` once. - Where there is no web view (not opted in, Jest, the web, or the platform switched off through the capabilities provider), the library's components - draw their own fallback; their records own its content. The handle's + draw their own fallback. The handle's `postMessage` does nothing there. - **FR16 — Accessibility.** The engine exposes the page's own structure (headings, links, form fields, text) to VoiceOver and TalkBack, and the @@ -323,10 +322,10 @@ grantsOrigin?}` (an HTML string). ### Platform support -| Contract | iOS | Android | -| ------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxWebView` | WebKit (`WKWebView`). Every named feature; `preventsCapture` is best effort (FR11). | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature but `linkMenu`. A content process end is reported on Android 8.0 and later. | -| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | +| Contract | iOS | Android | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxWebView` | WebKit (`WKWebView`). Every named feature but `preventsCapture`, which it reports as not supported (FR11); capture prevention there is best effort. | Android System WebView (`android.webkit.WebView`) with AndroidX WebKit. Every named feature but `linkMenu`. A content process end is reported on Android 8.0 and later. | +| `AstryxWebViewInfo` | `channelIsolation` is true; `pageProfile` is true on iOS 17 and later. | Both constants follow the installed WebView: `channelIsolation` needs its frame-aware message support, `pageProfile` its support for separate profiles. | - Supported feature/engine floor: the floor of `spec:AST-112` (iOS at React Native's minimum, Android API level 24, the New Architecture only), with the @@ -342,7 +341,7 @@ grantsOrigin?}` (an HTML string). - Relies on `spec:AST-112` FR1 (amended): the `web` capability holds the web view, its device report, and the session registry. -- Relies on `spec:AST-112` FR5 and FR21 (amended): native views are internal +- Relies on `spec:AST-112` FR5 (amended): native views are internal implementation behind components, and `WebView` is the web view's public face (FR1, FR2). - Relies on `spec:AST-112` FR7 (amended): each group of the platform has its From ab79f647981732c8ded76bda32c4b265bcfbc75a Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:04:07 -0800 Subject: [PATCH 21/23] spec(AST-131): keep the template's standing Non-goals bullets --- docs/specs/AST-131-react-native-web-view/spec.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index c4e00f180871e..d1e19d6b4c417 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -74,7 +74,14 @@ pin natively under an opaque handle that the view's `sessionId` prop names ## Non-goals -None. +- Equivalent internal implementations remain valid when they satisfy this + contract. +- Internal modules, files, function names, algorithms, data structures, storage + layouts, manifests, journals, locks, transaction protocols, and CI job/workflow + topology belong in architecture or implementation unless callers or + interoperating systems intentionally depend on that exact mechanism as a public + protocol. In that case, state who depends on it and why an equivalent + implementation would not satisfy the contract. ## Requirements From e8860c3894c15932b4e840a36bdadff83eb1d7fc Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:33:02 -0800 Subject: [PATCH 22/23] spec(AST-131): leave WebView's label to its own contract --- docs/specs/AST-131-react-native-web-view/spec.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index d1e19d6b4c417..43763cd36132e 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -307,8 +307,7 @@ grantsOrigin?}` (an HTML string). - **FR16 — Accessibility.** The engine exposes the page's own structure (headings, links, form fields, text) to VoiceOver and TalkBack, and the platform passes it through as the page builds it. The caller names the - region on a containing view, and the library's components take a required - label. The page's text follows the system text size + region on a containing view. The page's text follows the system text size through `textScale` (FR9). The link menu is the system's context menu. - **FR17 — Named features are checked before use.** Contracts grow by named features (`spec:AST-140/FR5`). JavaScript checks a named feature (FR13) From a9fe32c302e42486670901066279db84adbc37b0 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Thu, 19 Nov 2026 15:37:59 -0800 Subject: [PATCH 23/23] spec(AST-131): public platform API cites AST-140 FR9 and DEC-9 --- docs/specs/AST-131-react-native-web-view/spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specs/AST-131-react-native-web-view/spec.md b/docs/specs/AST-131-react-native-web-view/spec.md index 43763cd36132e..47615cf0b2d03 100644 --- a/docs/specs/AST-131-react-native-web-view/spec.md +++ b/docs/specs/AST-131-react-native-web-view/spec.md @@ -315,7 +315,7 @@ grantsOrigin?}` (an HTML string). baseline behaviour or answers `unsupported` (DEC-4). - **FR18 — Native code uses public platform API only.** The web view and its core modules (`AstryxWebViewInfo`, `AstryxWebSessions`) use only public - platform API (`spec:AST-112/FR4`). One exception exists, and it is off by + platform API (`spec:AST-140/FR9`). One exception exists, and it is off by default: an app may opt in through its configuration (`web.privateHardening`) to private `WKPreferences` setters and WebKit feature flags that turn peer connections, media devices, DNS prefetching, @@ -354,8 +354,8 @@ grantsOrigin?}` (an HTML string). own record, and this is the web group's. - Relies on `spec:AST-112` FR3 (amended): the `web` capability is a device feature an app opts in; Astryx's components link by default. -- Relies on `spec:AST-112` FR4 (amended): native code uses public platform - API only, and a record names any exception (FR18). +- Relies on `spec:AST-140/FR9` and `spec:AST-140/DEC-9`: native code uses + public platform API only, and a record names any exception (FR18). - Relies on `spec:AST-140` FR5: contracts grow by named features, which the platform info module lists (FR3, FR13, FR17). - `spec:AST-093/FR5` (every native component is tested and validated the same