From 89d239fdd0d7c1ffbbf0cdb95326038f85ad2c58 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:12:21 -0800 Subject: [PATCH 01/32] spec(AST-130): React Native platform system modules: results, events, named features and Stage simulation --- .../spec.md | 553 ++++++++++++++++++ 1 file changed, 553 insertions(+) create mode 100644 docs/specs/AST-130-react-native-system-modules/spec.md diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md new file mode 100644 index 0000000000000..2b8e34f72c615 --- /dev/null +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -0,0 +1,553 @@ +--- +schema_version: 4 +template_version: 2 +kind: system-spec +id: spec:AST-130 +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: System modules system spec + + + +## Intent + +An app built with `@astryxdesign/react-native` reads and changes the system +around it through a small set of native modules with no view: the app's light +or dark choice, the system's display and accessibility settings, haptic +feedback, the pasteboard, what the binary contains, runtime permissions, the +network path, Android's back press at the root, and Android's cold launch. +A developer calls one typed object per module, gets an answer on the first +render where the system already knows it, and handles every failure as data. +A person sees the app start in the right appearance, feels feedback that +matches the platform's own controls, sees drawn chrome follow Reduce +Transparency and Reduce Motion, and gets the system's back-to-home animation +and launch screen where the platform plays them. + +This record details the system modules of the platform layer that +`spec:AST-112` defines. They are core modules (`spec:AST-112/FR1`): every app +links them. Every asynchronous call resolves the result vocabulary of +`spec:AST-112/FR6`, every module has the capability shape of +`spec:AST-112/FR7`, every interface evolves additively under +`spec:AST-112/FR8`, and Astryx Stage implements each module as the contract +developers build against (`spec:AST-112/FR12`). + +## Why this exists + +React Native and its community already cover most of these needs. Astryx owns +a module where the ecosystem leaves a specific gap, or where the module is a +thin, dependency-free wrapper that gives the library one result shape, one +Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, +`spec:AST-082/FR13`). + +| Module | What the ecosystem does well | The gap Astryx fills | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxAppearance` | React Native's `Appearance` reports the scheme and can override it while JavaScript runs; `expo-system-ui` sets the root background. | A saved choice that the native shell applies before the first frame of every launch, a run-only override, and an opt-in launch link. A choice that JavaScript applies arrives after the first frame, so the window and status bar cross-fade. | +| `AstryxAccessibilitySettings` | `AccessibilityInfo` reads Reduce Motion, Reduce Transparency, Bold Text, darker system colours and cross-fade transitions, with change events for most. | One synchronous snapshot for the first frame, a change event for every key, and the iOS settings `AccessibilityInfo` does not read (Reduce Bright Effects, Show Borders). Android uses `AccessibilityInfo` itself (FR5). | +| `AstryxHaptics` | `Vibration` plays patterns; `expo-haptics` plays UIKit's feedback kinds and Android effects well. | Little capability gap. The module plays Android's `HapticFeedbackConstants` on the view with an API-level chain, needs no Expo runtime library (`spec:AST-112/FR11`), and lets the theme map moments to kinds (FR6). Scope: OQ1. | +| `AstryxClipboard` | `expo-clipboard` and `@react-native-clipboard/clipboard` read and write text and test for content without reading it. | No real capability gap. The module exists for the result vocabulary, the Preview read and write policy (`not-allowed`), and Astryx Stage parity. Scope: OQ1. | +| `AstryxPlatformInfo` | `expo-device`, `expo-application` and `react-native-device-info` report the device, the app's version and install time. | The binary's own contract facts no library can know: each native component's revision, the linked capabilities, the named contract features, per-platform feature rows, and self-checks. Its app constants overlap the ecosystem with no gap. | +| `AstryxPermissions` | `PermissionsAndroid` asks on Android; `react-native-permissions` covers many permissions with `blocked` and `denied` states. | Little gap. A closed set tied to the opted-in capabilities, `not-declared` instead of a system crash, the Preview consent policy, and no extra dependency. Scope: OQ1. | +| `AstryxNetwork` | `@react-native-community/netinfo` reports the connection and its changes; cookie libraries read the native jar. | For state, little gap: one meaning of "connected" on every platform and a constrained flag (FR10). Cookies per runtime and a request with no identity have no ecosystem equivalent; they belong with data and security (OQ2). | +| `AstryxBack` | `BackHandler` delivers Android back presses to JavaScript, and navigators consume them. | React Native's activity always takes the back press, so Android's predictive back-to-home animation never plays at the root. The gate gives the press to the system when JavaScript has nothing to consume (FR11). | +| `AstryxLaunch` | `expo-splash-screen` holds the splash until the app hides it; `Linking.getInitialURL()` reads the launch link. | The library ends the Android launch hold at its first content with no app code and no Expo runtime library, and the router reads the launch link synchronously, so a cold deep link draws its screen in the first frame (FR12). | + +## Who uses it + +| Native piece | Kind | Astryx components that use it | What a person sees | +| ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxAppearance` | native module (Turbo Native Module) | No Astryx component; app API only (`.` entry). The theme follows its effect through React Native's colour scheme (OQ3). | The app opens in the saved light or dark appearance, with no flash of the system's. | +| `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | +| `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | +| `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | +| `AstryxPlatformInfo` | native module (Turbo Native Module) | `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), the zoom pager gesture, and `useComponentRevision`; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | +| `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) and the audio recorder (`./microphone` entry) read it; app API `useCameraPermission` (OQ3) | The system prompt appears only when the app asks, never when a view mounts. | +| `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component calls the module; app API (`./network` entry: `useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2, OQ3) | An offline banner or a sign-out that the app draws. | +| `AstryxBack` | native module (Turbo Native Module) | Through the library's back registry: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | +| `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | + +## Non-goals + +- The data and security modules (storage, files, secure storage, client + identity, crypto) and their records. This record names only the parts of + `AstryxNetwork` the library depends on (OQ2). +- The design of the theme's appearance model and its scopes; this record owns + only the native appearance override. +- Haptic intensities per moment. The theme's haptic tokens own them + (`spec:AST-112/FR9`). +- Each component's use of these modules beyond what "Who uses it" names; the + component's own record owns it. +- 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 — The group is nine core native modules.** Every app links them + (`spec:AST-112/FR1`). Each module is read with `TurboModuleRegistry.get`, + only by its own wrapper (`spec:AST-112/FR8`), and its wrapper answers + `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` have + no public object: the library is their one caller. + + | Contract | Kind | Methods | Platforms | + | ----------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | + | `AstryxAppearance` | native module (Turbo Native Module) | `getConstants` (`initialOverride`), `setOverride`, `getRunOverride` | iOS, Android | + | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `getConstants` (`initialSettings`), `getSettings`, `onSettingsChange` (event) | iOS | + | `AstryxHaptics` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `play`, `prepare` | iOS, Android | + | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `setString`, `detectPatterns` | iOS, Android | + | `AstryxPlatformInfo` | native module (Turbo Native Module) | `getConstants` (`app`, `capabilities`, `components`, `contractFeatures`, `launch`), `getInfo`, `getMemory`, `getBundleSize` | iOS, Android | + | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | + | `AstryxNetwork` | native module (Turbo Native Module) | `getConstants`, `getState`, `onNetworkChange` (event), `getCookies`, `listCookies`, `setCookie`, `removeCookie`, `clearCookies`, `getDomainInfo`, `redirectModes`, `fetchUntrusted` | iOS, Android | + | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | + | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | + +- **FR2 — Constants are synchronous; everything else is a result.** + - What the system knows at launch is a constant that the wrapper reads once + per module and keeps: the saved appearance and the run's override, the + accessibility snapshot, the app's version, build, identifier and install + time, the linked capabilities, the component revisions, the named contract + features, and the process start. Synchronous members (`isAvailable()`, + `version()`, `getOverride()`, `getRunOverride()`, `current()`, `app`, + `capabilities`, `launch`, `componentRevision(name)`) never throw; they + answer `null`, `'system'`, or all-false where the module or the constant is + absent. + - Every asynchronous call resolves `AstryxResult` and never rejects + (`spec:AST-112/FR6`). Each module adds only these reasons to the common + ones: + + | Module | Module reasons | + | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `AstryxAppearance` | `invalid` (not `light`, `dark` or `system`) | + | `AstryxAccessibilitySettings` | `unavailable` (the module is torn down during a reload) | + | `AstryxClipboard` | `unavailable` (no pasteboard on this device) | + | `AstryxPlatformInfo` | `unavailable` (the system did not answer a measure) | + | `AstryxPermissions` | `unknown-permission`, `busy`, `no-activity` (Android), `not-declared` | + | `AstryxNetwork` | `unavailable`, `invalid-url`, `invalid-host`, `invalid-cookie`; for `fetchUntrusted`: `invalid-request`, `redirect-refused`, `timeout`, `too-large`, `network`, `aborted` | + + - `AstryxHaptics.play` and `prepare` return nothing: they play or do nothing, + and `isAvailable()` says which. `AstryxBack` and `AstryxLaunch` calls + return nothing either; they are hints that the native side may ignore. + - In a Preview project's runtime, a call that acts for the host app + (`setOverride`, `fetchUntrusted`, `getMemory`, `getBundleSize`) answers + `not-allowed`, and a refused clipboard read or write or camera consent + answers `not-allowed` too. `AstryxBack` and `AstryxLaunch` change nothing + there. + +- **FR3 — Change events start with the first subscriber and stop after the + last.** + - `AstryxAccessibilitySettings.subscribe` and `AstryxNetwork.subscribe` call + the listener with each real change, never with the current value, and + return the unsubscribe function. A native event that repeats an unchanged + value is not delivered. + - One process-wide store per module listens to the native event while at + least one subscriber exists. After the last unsubscribe it removes the + native subscription, and the next read starts again from the constants. + - On its first subscriber, the accessibility store reads `getSettings` once + to resync. An event that arrives before that answer wins, because it is + newer. + - Hooks (`useAccessibilitySettings`, `useNetworkState`, `useCameraPermission`) + subscribe on mount, remove the subscription on unmount, and return stable + callbacks (`spec:AST-112/FR7`). `useNetworkState` reports `loading`, + `ready` or `unavailable`. `useCameraPermission` reads again when the app + returns to the foreground, because the person may change the permission in + Settings. + - `AstryxPermissions.subscribe` delivers each state change the package + learns from a `get` or a `request` anywhere in the app. + +- **FR4 — `AstryxAppearance` keeps the app's light or dark choice natively.** + - `setOverride('light' | 'dark' | 'system')` applies the choice to every + window of the app at once and saves it; `system` removes the saved choice. + `getOverride()` answers the saved choice synchronously. + - The native shell applies the saved choice before the app's first frame: on + iOS as the window's user interface style before the window shows, on + Android as AppCompat's default night mode at process start. React Native's + `Appearance` and `useColorScheme` then report the chosen scheme, so the + theme follows it. The launch screen and the splash follow the system's + choice, because the system draws them before app code runs; the Android 12 + and later splash follows the saved choice through the night mode the system + keeps per app. + - `setOverride(value, {persist: false})` (feature `persist-false`) applies the + choice for this run only and saves nothing. `getOverride()` and the next + launch keep the saved choice, and `setOverride(getOverride())` restores + it. + - `getRunOverride()` (feature `run-override`) answers the run's own override + synchronously, or `null` when the saved choice is in force, so the first + render matches the first frame. + - With the configuration plugin's `appearance.launchLinkParameter` set + (default: off), a link on one of the app's own schemes whose named query + parameter is `light`, `dark` or `system` applies that appearance natively + as a run-only override: before the first frame on a cold launch, and on + arrival on a warm one (feature `launch-link`). Nothing is saved. + - In a Preview project's runtime, `getOverride()` answers `'system'`, + `getRunOverride()` answers `null`, and `setOverride` answers `not-allowed`: + the host app's appearance is not a project's to change. + +- **FR5 — `AstryxAccessibilitySettings` publishes one settings snapshot.** + - The snapshot has seven booleans, each always present and false where the + OS version lacks the setting: `isReduceTransparency`, + `isIncreaseContrast`, `isReduceMotion`, `prefersCrossFadeTransitions`, + `isBoldText`, `isReduceBrightEffects` (iOS 26.4 and later), and + `isShowBorders` (Show Borders on iOS 26.1 and later, Button Shapes before). + - `current()` answers the snapshot synchronously from the constants, so the + first frame is drawn with it; `getSettings()` reads it again. + - Where the module is absent (Android, an older binary, Jest), `isAvailable()` + is false, `getSettings()` answers `no-module`, and the snapshot comes from + React Native's `AccessibilityInfo`: Reduce Motion everywhere, high text + contrast as `isIncreaseContrast` on Android, and the iOS settings it reads. + Keys `AccessibilityInfo` cannot read stay false. + - The snapshot does not report Liquid Glass's Clear or Tinted appearance: no + public API reads it, so native glass follows it and drawn chrome does not. + +- **FR6 — `AstryxHaptics` plays the platform's feedback kinds.** + - `play(kind)` plays one of UIKit's nine kinds: `selection`, `impactLight`, + `impactMedium`, `impactHeavy`, `impactSoft`, `impactRigid`, + `notificationSuccess`, `notificationWarning`, `notificationError`. iOS plays + it with a prepared feedback generator; `prepare(kind)` warms the generator + so the next `play` has no delay. + - Android plays a chain of `HapticFeedbackConstants` names, preferred first, + on the current activity's root view: the first name the device's API level + has. Each kind has a default chain; `play(kind, {android})` passes another. + - `isAvailable()` is false where the module is absent or `isSupported()` is + false (no haptic hardware, or no window). `play` and `prepare` do nothing + then. + - The library maps its moments (select, toggle, edge, threshold arm and + disarm, commit and others) to kinds through the theme's haptic tokens, each + matched to the iOS control that plays it. A theme's `native.haptics` + overrides a token, and `'none'` silences it. + +- **FR7 — `AstryxClipboard` reads and writes plain text.** + - `write({text})` replaces the pasteboard's content and answers `ok` once the + text is there. `setString(text)` is its deprecated alias. + - `getString()` answers `{value}`, with `null` for an empty or non-text + pasteboard. A read shows the system's paste notice on iOS 16 and later and + Android 12 and later, so the library reads only on the person's action + (`PasteButton`); copy buttons never read. + - `detectPatterns(['webURL' | 'webSearch' | 'number'])` answers whether the + pasteboard probably holds each pattern, without reading the content and + without a paste notice. A key the platform cannot tell is left out: Android + has no web-search or number test, and has none before Android 12. + - `isAvailable()` is false where the module is absent or `isSupported()` is + false; calls then answer `no-module` or `unavailable`. + +- **FR8 — `AstryxPlatformInfo` says what this binary has.** + - Constants: `app` (version, build, identifier, and `installedAt` in ISO + 8601 UTC: the bundle container's creation date on iOS, + `PackageInfo.lastUpdateTime` on Android), `capabilities` (the opted-in + capabilities this binary links; `[]` for core only), `components` (each + native component's revision), `contractFeatures` (the named contract + features, FR15), and `launch` (`processStartedAt` in epoch milliseconds, + and `isPrewarmed`, always false on Android). `packageVersion` is the + JavaScript package's version. + - `get()` answers the platform, the calling runtime's namespace (`app` or a + Preview project's), the components, the per-platform feature rows + (`.`, with `isSupported` and a note), and the + self-checks of the platform internals the package relies on (`compat`). + `supports(name)` reads a feature row from the last answer and is `null` + while it is unknown. + - `memory()` answers the process's memory in bytes, each platform's own + measure (iOS `phys_footprint`, Android total PSS), not comparable across + platforms. `bundleSize()` answers the installed app's size on disk, read + off the main thread. + - A Preview project's runtime gets no `launch`, an empty `installedAt`, and + `not-allowed` from `memory()` and `bundleSize()`: the host's process and + install are not a project's to read. + +- **FR9 — `AstryxPermissions` reads and asks explicitly.** + - `get(name)` never prompts. `request(name)` shows the system prompt only for + `undetermined` (and Android `denied`), then answers the state; otherwise it + answers the current state at once. Mounting a view never prompts + (`spec:AST-112/FR7`). + - `name` is a closed set (`camera`). The states are `granted`, + `undetermined`, `denied` (refused; the app may ask again) and `blocked` + (only Settings changes it: iOS `denied` or `restricted`, Android "don't ask + again"). + - `hasHardware` says whether the device has the hardware: false on the iOS + Simulator and an emulator without a camera; `null` where the platform does + not say. + - A permission the app did not declare answers `not-declared` and shows no + prompt; the configuration plugin declares it when the app opts the + capability in (`spec:AST-112/FR4`). + - Where the module is absent, Android answers through React Native's + `PermissionsAndroid` (which reads `undetermined` until a `request` in this + run learns of a refusal), and iOS answers `no-module`. + +- **FR10 — `AstryxNetwork` reports the network path.** + - `getState()` answers `isConnected`, `type` (`wifi`, `cellular`, + `ethernet`, `other`, `none`, `unknown`), `isMetered`, and `isConstrained` + (iOS Low Data Mode, Android Data Saver for this app). `connected`, + `expensive` and `constrained` are deprecated aliases. + - `isConnected` has one meaning on every platform: a default route to the + internet exists (iOS: the path monitor's path is satisfied; Android: the + default network has INTERNET). It is not validated connectivity: a captive + portal before sign-in reads connected, and a request can still fail. + - On Android the reads need `ACCESS_NETWORK_STATE`, which the configuration + plugin writes for the core; without it, `getState()` answers `unavailable` + and names the permission. + - The module also carries the calling runtime's cookie jar (`AstryxCookies`: + `get`, `set`, `remove`, `clear`; an `httpOnly` cookie's value never reaches + JavaScript), a host's public suffix and registrable domain + (`getDomainInfo`), whether the runtime's request handler honours `fetch`'s + redirect modes (`redirectModes`), and one HTTPS request from a client with + no identity, cookies or cache that follows no redirect natively + (`fetchUntrusted`; `supports('fetchUntrusted')`). Their contracts belong with + the data and security modules (OQ2). + +- **FR11 — `AstryxBack` gives Android's root back press to the system when + JavaScript cannot use it.** + - The library's back registry tells the native side whether JavaScript can + consume a back press at the root: a registered consumer (an open + sheet, menu or search field), a `BackHandler` listener, or a navigator that + can go back. The shell activity enables its one back callback only then. + - With nothing to consume, the system takes the press and plays its + back-to-home animation (Android 16 predictive back). + - Before the first call, and after the runtime ends, the activity sends every + press to React Native, as React Native's own activity does. + - The registry sends a value only when it changes. A Preview project's + runtime changes nothing. iOS has no module: back is native there. + +- **FR12 — `AstryxLaunch` hands Android's cold launch to the first content.** + - The shell activity keeps the system's launch window (the splash screen on + API 31 and later, the window background before) until the library calls + `firstContent()`, instead of drawing an empty root while the bundle loads. + It lets go after a time bound (2.5 seconds) when no call arrives. + - The library calls it once per runtime: from the router's first focused + screen's first content layout, or from `AstryxPerformance.markFirstFrame`, + whichever comes first. Later calls do nothing. + - `initialURL()` answers the launch link synchronously (what + `Linking.getInitialURL()` answers), or `null` when the app launched + without one. The router builds its first state from it, so a cold deep + link draws its own screen first. Where the platform cannot answer + synchronously (iOS, an absent module, a Preview project's runtime), the + router reads `Linking.getInitialURL()`. + - iOS has no module: its launch screen stays until the first frame. + +- **FR13 — Threads and lifecycle.** + - Constants are read on the JavaScript thread once per module, at the first + call that needs them. Asynchronous calls do their native work off the + JavaScript thread, and a measure that walks files (`bundleSize()`) runs off + the main thread. + - The appearance override and the root back gate act on the UI thread at + once; neither waits for a JavaScript round trip per frame. + - Native events reach JavaScript on the JavaScript thread, once per real + change. + - A module torn down during a reload answers `unavailable` until its runtime + is back; a subscription made before the reload is removed with its store. + +- **FR14 — Accessibility.** + - The library's drawn chrome follows the snapshot of FR5: Reduce + Transparency makes drawn glass and materials opaque, Increase Contrast and + Show Borders strengthen edges, Bold Text reaches drawn text and symbols, + and Reduce Motion with `prefersCrossFadeTransitions` replaces motion with + cross-fades within the limits of `spec:AST-108`. The theme's style helper + gives every key to component styles. + - Haptic feedback is never the only signal: each moment goes with a visual + change, and a copy also announces "Copied" through the status + announcements of `spec:AST-086`. + - These modules expose nothing to VoiceOver or TalkBack themselves; they have + no view. + +- **FR15 — Every contract is at revision 1; later behaviour is a named + feature.** + - Every contract in the group reports revision 1. A behaviour added after + revision 1 is a named feature, `.`, that the binary + lists in `AstryxPlatformInfo`'s `contractFeatures` constant. JavaScript + checks it with `hasContractFeature` before it uses the behaviour. + - The group's named features are `AstryxAppearance.persist-false`, + `AstryxAppearance.run-override` and `AstryxAppearance.launch-link`. The + `contractFeatures` constant is the list itself and adds no behaviour. + - Without a feature, JavaScript keeps the revision-1 behaviour or answers + `unsupported`, never a silently weaker path: `setOverride` with + `persist: false` answers `unsupported` and saves nothing, + `getRunOverride()` answers `null` (such a binary has no run-only override), + and a missing feature is reported once with a development warning. + - Astryx Stage pairs with the package through the library's Stage version + floor: the package names the oldest Astryx Stage that implements its + contract set, and an older Astryx Stage refuses the project with the gaps + listed. + +- **FR16 — Astryx Stage simulates each module.** + - `AstryxAppearance`: the saved choice per app in Astryx Stage's data folder, + applied before the first frame; a run-only override in memory, which a new + run forgets. + - `AstryxAccessibilitySettings`: the run's device settings, set by + arguments and changed live, delivered as the same snapshot and event. + - `AstryxHaptics`: present and supported; each `play` is a trace entry that + names the kind or the Android constant, and plays nothing. + - `AstryxClipboard`: an in-memory string; `detectPatterns` classifies it + without handing it back; Preview reads ask as on a device. + - `AstryxPlatformInfo`: Astryx Stage's own app identity, its component + revisions, linked capabilities, feature rows, launch, memory and size. + - `AstryxPermissions`: `undetermined` until `request`, which draws a prompt; + an argument starts it granted; `hasHardware` is false, as on the + Simulator. + - `AstryxNetwork`: a default route exists and the path is never metered; + cookies in a jar per namespace; `fetchUntrusted` from a client of its own + with no identity and no redirect following. + - `AstryxBack` and `AstryxLaunch` are absent, as on iOS: the library takes + its no-module path, every back press goes to React Native, and the first + frame draws with no launch hold (OQ4). + +### Platform support + +| Contract | iOS | Android | Astryx Stage | +| ----------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | Saved file and in-memory run override (FR16) | +| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | Device settings from the run (FR16) | +| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | Trace entries; no feedback | +| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | In-memory string | +| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | Astryx Stage's own identity and tables | +| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | Drawn prompt; `undetermined` until asked | +| `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the web profile's `CookieManager`; a separate HTTP client | Default route; per-namespace jar; its own client | +| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | Absent (FR16) | +| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | Absent (FR16) | + +- FR16 gap: Astryx Stage reports no `contractFeatures` list, and its + `AstryxAppearance` has no `getRunOverride` and no launch link. +- Supported feature/engine floor: the platform floor of `spec:AST-112` + (iOS at React Native's minimum, Android API level 24, the New Architecture + only). Settings that newer OS versions add (Reduce Bright Effects, Show + Borders, Android 12 pattern detection, Android 16 predictive back) read + false, stay out of an answer, or keep the older behaviour below them. +- Unsupported behavior: an absent module answers `no-module` and its + synchronous members answer their empty values (FR2); a missing named feature + answers `unsupported` or keeps the revision-1 behaviour (FR15); a + platform-only module is absent on the other platform, and the library takes + the path FR5, FR11 and FR12 name. +- Browser evidence: none. Claims are proven on the iOS Simulator, the Android + emulator, devices, and Astryx Stage (`spec:AST-112/FR15`); haptic feel needs + a real device. + +## Current-state impact + +- None beyond `spec:AST-112`. This record details its FR1 (the core's system + modules), FR6 and FR7 for each module's results and probes, FR8 for the + revision-1 baseline and named features, FR9 for the haptic moment mapping, + and FR12 for Astryx Stage's simulation. +- The group is entirely core, so the capability model's split between core and + opt-in capabilities in `spec:AST-112/FR1` and FR3 does not change for it. + +## Verification + +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | +| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw; a Preview runtime | A synchronous member throws, a call rejects, or answers a reason outside its set | +| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | +| FR4 | Unit tests; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link | saved `dark` under a light system; `persist: false`; launch link cold and warm; Preview runtime | The first frame shows the system's style, a run-only change survives a relaunch, or a Preview project changes the host's appearance | +| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting; Astryx Stage settings suites | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | +| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | +| FR7 | Unit tests; Simulator and emulator copy and paste; Astryx Stage clipboard suites | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | +| FR8 | Unit tests; Astryx Stage platform-info suites; Simulator and emulator reads | constants; `get()`; memory and size; Preview runtime | A Preview project reads the host's launch, memory or size, or a constant throws | +| FR9 | Unit tests; Simulator and emulator prompts; Astryx Stage permission suites | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | +| FR10 | Unit tests; emulator and Simulator network changes; Astryx Stage network suites | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | +| FR11 | Unit tests of the registry; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | +| FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports; a Preview runtime | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | +| FR13 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | +| FR14 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | +| FR15 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent; an older Astryx Stage | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | +| FR16 | Astryx Stage contract suites against the Simulator and emulator results | each module's suite | An Astryx Stage answer differs from iOS and Android and its documentation does not name it | + +## Decision log + +### DEC-1 — The appearance choice is native, applied before the first frame + +**Reference:** `spec:AST-130/DEC-1` +**Decider:** imdreamrunner, 2026-11-17 + +A choice that JavaScript applies arrives after the first frame, so a saved +choice opposite the system shows the system's style first and then +cross-fades. The native shell saves the choice and applies it to the window +before it shows; run-only changes and the launch link use the same path and +save nothing. + +Rejected: applying the choice from JavaScript at start, because the first +frame cannot follow it. + +### DEC-2 — Accessibility settings are one snapshot with a fallback + +**Reference:** `spec:AST-130/DEC-2` +**Decider:** imdreamrunner, 2026-11-17 + +Drawn chrome needs every setting that native glass and system bars follow, in +the first frame, so the module publishes them together as constants and one +event. Where the module is absent, React Native's `AccessibilityInfo` answers +the keys it can, so the library never needs two code paths. + +### DEC-3 — Android's root back press belongs to the system unless JavaScript can use it + +**Reference:** `spec:AST-130/DEC-3` +**Decider:** imdreamrunner, 2026-11-17 + +Predictive back plays only when the activity does not intercept the press. +The library knows whether anything can consume it, so it publishes that fact +and the activity follows; the system then plays its own back-to-home +animation at the root. + +Rejected: a JavaScript handler that exits the app, because the system's +animation cannot play from it. + +### DEC-4 — The library ends the Android launch hold + +**Reference:** `spec:AST-130/DEC-4` +**Decider:** imdreamrunner, 2026-11-17 + +The router knows when the first screen has content, so it releases the launch +window with no app code, and a time bound keeps a broken launch visible. The +launch link is read synchronously so the router's first state is the linked +screen. + +Rejected: an app-called hide, because every app would need the step and a +missed call holds the splash. + +### DEC-5 — Thin modules stay dependency-free wrappers + +**Reference:** `spec:AST-130/DEC-5` +**Decider:** imdreamrunner, 2026-11-17 + +Haptics, the clipboard, permissions and network state are small wrappers +where the ecosystem has good libraries. They stay in the core because the +package takes no runtime dependency outside React and React Native +(`spec:AST-112/FR2`), and because each needs the result vocabulary, the +Preview policy and an Astryx Stage simulation. OQ1 keeps the scope open. + +## Open questions + +- **OQ1 — Do the thin system modules stay Astryx modules?** (`human-design`) + `AstryxHaptics`, `AstryxClipboard`, `AstryxPermissions` and the network + state of `AstryxNetwork` fill little capability gap. Options: keep them as + core modules (one dependency set, one result shape, Astryx Stage parity); or + replace their native side with adapters over community libraries + (`expo-haptics`, `expo-clipboard`, `react-native-permissions`, + `@react-native-community/netinfo`), keeping the wrappers' API. +- **OQ2 — Do cookies, domain info, redirect modes and `fetchUntrusted` move to + the data and security group?** (`human-design`) They are methods + of `AstryxNetwork`, no Astryx component calls them, and their rules + (per-runtime jars, values that stay native, requests with no identity) + are data and security contracts. The library's marker for content-chosen + image and media URLs belongs to the same question. Options: a separate + module in that group, with `AstryxNetwork` keeping only the path state; or + one module whose contract this record shares with that group's record. +- **OQ3 — Do the app-API-only modules stay in this group and the core?** + (`human-design`) No Astryx component calls `AstryxAppearance`, + `AstryxPermissions` (used by the `./camera` and `./microphone` entries) or + `AstryxNetwork`. Options: keep them in the core with this record; or move + each to the entry that uses it. +- **OQ4 — Does Astryx Stage simulate the Android root back gate and launch + hold?** (`checkable`) Options: keep both absent, as FR16 states; or simulate + the back-to-home animation at the root and a launch window held until the + first content. From 74f2ecefaa0da730569e81911f49ff4de54152eb Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:16:46 -0800 Subject: [PATCH 02/32] spec(AST-130): PlatformInfo users include the Icon, system menu and presentation host probes --- docs/specs/AST-130-react-native-system-modules/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 2b8e34f72c615..7974c0dcc3935 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -70,7 +70,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | | `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | | `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | -| `AstryxPlatformInfo` | native module (Turbo Native Module) | `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), the zoom pager gesture, and `useComponentRevision`; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | +| `AstryxPlatformInfo` | native module (Turbo Native Module) | Its revision and feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), the zoom pager gesture, and `useComponentRevision`; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | | `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) and the audio recorder (`./microphone` entry) read it; app API `useCameraPermission` (OQ3) | The system prompt appears only when the app asks, never when a view mounts. | | `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component calls the module; app API (`./network` entry: `useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2, OQ3) | An offline banner or a sign-out that the app draws. | | `AstryxBack` | native module (Turbo Native Module) | Through the library's back registry: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | From 85fa8a146c80c67ff62d1b3b2ef66834284b90a0 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:24:33 -0800 Subject: [PATCH 03/32] spec(AST-130): the file pickers, the key-value store and secure random bytes join the system modules --- .../spec.md | 178 ++++++++++++++---- 1 file changed, 137 insertions(+), 41 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 7974c0dcc3935..e0f66319e243b 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -26,13 +26,16 @@ An app built with `@astryxdesign/react-native` reads and changes the system around it through a small set of native modules with no view: the app's light or dark choice, the system's display and accessibility settings, haptic feedback, the pasteboard, what the binary contains, runtime permissions, the -network path, Android's back press at the root, and Android's cold launch. +network path, Android's back press at the root, Android's cold launch, the +system's file and photo pickers, a string key-value store, and secure random +bytes. A developer calls one typed object per module, gets an answer on the first render where the system already knows it, and handles every failure as data. A person sees the app start in the right appearance, feels feedback that matches the platform's own controls, sees drawn chrome follow Reduce Transparency and Reduce Motion, and gets the system's back-to-home animation -and launch screen where the platform plays them. +and launch screen where the platform plays them. A file field opens the +system's own picker, and the app's navigation state survives a cold start. This record details the system modules of the platform layer that `spec:AST-112` defines. They are core modules (`spec:AST-112/FR1`): every app @@ -50,17 +53,20 @@ thin, dependency-free wrapper that gives the library one result shape, one Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, `spec:AST-082/FR13`). -| Module | What the ecosystem does well | The gap Astryx fills | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxAppearance` | React Native's `Appearance` reports the scheme and can override it while JavaScript runs; `expo-system-ui` sets the root background. | A saved choice that the native shell applies before the first frame of every launch, a run-only override, and an opt-in launch link. A choice that JavaScript applies arrives after the first frame, so the window and status bar cross-fade. | -| `AstryxAccessibilitySettings` | `AccessibilityInfo` reads Reduce Motion, Reduce Transparency, Bold Text, darker system colours and cross-fade transitions, with change events for most. | One synchronous snapshot for the first frame, a change event for every key, and the iOS settings `AccessibilityInfo` does not read (Reduce Bright Effects, Show Borders). Android uses `AccessibilityInfo` itself (FR5). | -| `AstryxHaptics` | `Vibration` plays patterns; `expo-haptics` plays UIKit's feedback kinds and Android effects well. | Little capability gap. The module plays Android's `HapticFeedbackConstants` on the view with an API-level chain, needs no Expo runtime library (`spec:AST-112/FR11`), and lets the theme map moments to kinds (FR6). Scope: OQ1. | -| `AstryxClipboard` | `expo-clipboard` and `@react-native-clipboard/clipboard` read and write text and test for content without reading it. | No real capability gap. The module exists for the result vocabulary, the Preview read and write policy (`not-allowed`), and Astryx Stage parity. Scope: OQ1. | -| `AstryxPlatformInfo` | `expo-device`, `expo-application` and `react-native-device-info` report the device, the app's version and install time. | The binary's own contract facts no library can know: each native component's revision, the linked capabilities, the named contract features, per-platform feature rows, and self-checks. Its app constants overlap the ecosystem with no gap. | -| `AstryxPermissions` | `PermissionsAndroid` asks on Android; `react-native-permissions` covers many permissions with `blocked` and `denied` states. | Little gap. A closed set tied to the opted-in capabilities, `not-declared` instead of a system crash, the Preview consent policy, and no extra dependency. Scope: OQ1. | -| `AstryxNetwork` | `@react-native-community/netinfo` reports the connection and its changes; cookie libraries read the native jar. | For state, little gap: one meaning of "connected" on every platform and a constrained flag (FR10). Cookies per runtime and a request with no identity have no ecosystem equivalent; they belong with data and security (OQ2). | -| `AstryxBack` | `BackHandler` delivers Android back presses to JavaScript, and navigators consume them. | React Native's activity always takes the back press, so Android's predictive back-to-home animation never plays at the root. The gate gives the press to the system when JavaScript has nothing to consume (FR11). | -| `AstryxLaunch` | `expo-splash-screen` holds the splash until the app hides it; `Linking.getInitialURL()` reads the launch link. | The library ends the Android launch hold at its first content with no app code and no Expo runtime library, and the router reads the launch link synchronously, so a cold deep link draws its screen in the first frame (FR12). | +| Module | What the ecosystem does well | The gap Astryx fills | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxAppearance` | React Native's `Appearance` reports the scheme and can override it while JavaScript runs; `expo-system-ui` sets the root background. | A saved choice that the native shell applies before the first frame of every launch, a run-only override, and an opt-in launch link. A choice that JavaScript applies arrives after the first frame, so the window and status bar cross-fade. | +| `AstryxAccessibilitySettings` | `AccessibilityInfo` reads Reduce Motion, Reduce Transparency, Bold Text, darker system colours and cross-fade transitions, with change events for most. | One synchronous snapshot for the first frame, a change event for every key, and the iOS settings `AccessibilityInfo` does not read (Reduce Bright Effects, Show Borders). Android uses `AccessibilityInfo` itself (FR5). | +| `AstryxHaptics` | `Vibration` plays patterns; `expo-haptics` plays UIKit's feedback kinds and Android effects well. | Little capability gap. The module plays Android's `HapticFeedbackConstants` on the view with an API-level chain, needs no Expo runtime library (`spec:AST-112/FR11`), and lets the theme map moments to kinds (FR6). Scope: OQ1. | +| `AstryxClipboard` | `expo-clipboard` and `@react-native-clipboard/clipboard` read and write text and test for content without reading it. | No real capability gap. The module exists for the result vocabulary, the Preview read and write policy (`not-allowed`), and Astryx Stage parity. Scope: OQ1. | +| `AstryxPlatformInfo` | `expo-device`, `expo-application` and `react-native-device-info` report the device, the app's version and install time. | The binary's own contract facts no library can know: each native component's revision, the linked capabilities, the named contract features, per-platform feature rows, and self-checks. Its app constants overlap the ecosystem with no gap. | +| `AstryxPermissions` | `PermissionsAndroid` asks on Android; `react-native-permissions` covers many permissions with `blocked` and `denied` states. | Little gap. A closed set tied to the opted-in capabilities, `not-declared` instead of a system crash, the Preview consent policy, and no extra dependency. Scope: OQ1. | +| `AstryxNetwork` | `@react-native-community/netinfo` reports the connection and its changes; cookie libraries read the native jar. | For state, little gap: one meaning of "connected" on every platform and a constrained flag (FR10). Cookies per runtime and a request with no identity have no ecosystem equivalent; they belong with data and security (OQ2). | +| `AstryxBack` | `BackHandler` delivers Android back presses to JavaScript, and navigators consume them. | React Native's activity always takes the back press, so Android's predictive back-to-home animation never plays at the root. The gate gives the press to the system when JavaScript has nothing to consume (FR11). | +| `AstryxLaunch` | `expo-splash-screen` holds the splash until the app hides it; `Linking.getInitialURL()` reads the launch link. | The library ends the Android launch hold at its first content with no app code and no Expo runtime library, and the router reads the launch link synchronously, so a cold deep link draws its screen in the first frame (FR12). | +| `AstryxFilePicker` | `expo-image-picker`, `expo-document-picker`, `react-native-image-picker` and `@react-native-documents/picker` present the system photo, camera and document pickers well. | Little gap: one call over photos, camera and files with the result vocabulary (`cancelled` is not an error), no permission for the out-of-process photo picker, `unsupported-source` instead of a crash where the camera's usage string is missing, and no extra dependency. Scope: OQ1. | +| `AstryxStorage` | `@react-native-async-storage/async-storage` and `react-native-mmkv` store strings and JSON well. | Little gap: the namespace is the calling runtime's, decided natively, so a Preview project never reads the app's data or another project's, and the app's runtime clears a project's data in one call. Scope: OQ1. | +| `AstryxCrypto` | `react-native-get-random-values`, `expo-crypto` and `react-native-quick-crypto` give secure random bytes and Web Crypto shapes. | No real capability gap. The module gives synchronous bytes from the system's secure generator with no non-secure fallback, for the package's own code and its crypto installer (`spec:AST-112/FR5`), with no extra dependency. Scope: OQ1. | ## Who uses it @@ -75,12 +81,15 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component calls the module; app API (`./network` entry: `useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2, OQ3) | An offline banner or a sign-out that the app draws. | | `AstryxBack` | native module (Turbo Native Module) | Through the library's back registry: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | | `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | +| `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo, camera or document picker; backing out changes nothing. | +| `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the update check's "Not now" (`./updates` entry); app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | +| `AstryxCrypto` | native module (Turbo Native Module) | No Astryx component; the public crypto installer (`./network` entry) and app API `AstryxCrypto` (OQ3) | Nothing directly: identifiers and sign-in nonces an app makes come from the system's secure generator. | ## Non-goals -- The data and security modules (storage, files, secure storage, client - identity, crypto) and their records. This record names only the parts of - `AstryxNetwork` the library depends on (OQ2). +- The data and security modules (files, secure storage, client identity) and + their records. This record names only the parts of `AstryxNetwork` the + library depends on (OQ2). - The design of the theme's appearance model and its scopes; this record owns only the native appearance override. - Haptic intensities per moment. The theme's haptic tokens own them @@ -98,7 +107,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, ## Requirements -- **FR1 — The group is nine core native modules.** Every app links them +- **FR1 — The group is twelve core native modules.** Every app links them (`spec:AST-112/FR1`). Each module is read with `TurboModuleRegistry.get`, only by its own wrapper (`spec:AST-112/FR8`), and its wrapper answers `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` have @@ -114,6 +123,9 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | | `AstryxNetwork` | native module (Turbo Native Module) | `getConstants`, `getState`, `onNetworkChange` (event), `getCookies`, `listCookies`, `setCookie`, `removeCookie`, `clearCookies`, `getDomainInfo`, `redirectModes`, `fetchUntrusted` | iOS, Android | | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | + | `AstryxFilePicker` | native module (Turbo Native Module) | `getConstants`, `getSources`, `pick` | iOS, Android | + | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo`, `clearProjectData` | iOS, Android | + | `AstryxCrypto` | native module (Turbo Native Module) | `getConstants`, `randomBytes` (synchronous) | iOS, Android | | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | - **FR2 — Constants are synchronous; everything else is a result.** @@ -137,13 +149,18 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxClipboard` | `unavailable` (no pasteboard on this device) | | `AstryxPlatformInfo` | `unavailable` (the system did not answer a measure) | | `AstryxPermissions` | `unknown-permission`, `busy`, `no-activity` (Android), `not-declared` | + | `AstryxFilePicker` | `unsupported-source`, `no-window`, `busy`, `permission-denied`, `restricted`; `cancelled` when the person backs out | + | `AstryxStorage` | `invalid-key`, `invalid-value`, `invalid-json`, `no-space`, `io`, `no-namespace`; `invalid-url` for `clearProjectData` | | `AstryxNetwork` | `unavailable`, `invalid-url`, `invalid-host`, `invalid-cookie`; for `fetchUntrusted`: `invalid-request`, `redirect-refused`, `timeout`, `too-large`, `network`, `aborted` | + - `AstryxCrypto` is the one synchronous exception: its methods return + bytes or throw, as Web Crypto's do (FR15). - `AstryxHaptics.play` and `prepare` return nothing: they play or do nothing, and `isAvailable()` says which. `AstryxBack` and `AstryxLaunch` calls return nothing either; they are hints that the native side may ignore. - In a Preview project's runtime, a call that acts for the host app - (`setOverride`, `fetchUntrusted`, `getMemory`, `getBundleSize`) answers + (`setOverride`, `fetchUntrusted`, `getMemory`, `getBundleSize`, + `clearProjectData`) answers `not-allowed`, and a refused clipboard read or write or camera consent answers `not-allowed` too. `AstryxBack` and `AstryxLaunch` change nothing there. @@ -250,7 +267,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, `PackageInfo.lastUpdateTime` on Android), `capabilities` (the opted-in capabilities this binary links; `[]` for core only), `components` (each native component's revision), `contractFeatures` (the named contract - features, FR15), and `launch` (`processStartedAt` in epoch milliseconds, + features, FR18), and `launch` (`processStartedAt` in epoch milliseconds, and `isPrewarmed`, always false on Android). `packageVersion` is the JavaScript package's version. - `get()` answers the platform, the calling runtime's namespace (`app` or a @@ -336,7 +353,70 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, router reads `Linking.getInitialURL()`. - iOS has no module: its launch screen stays until the first frame. -- **FR13 — Threads and lifecycle.** +- **FR13 — `AstryxFilePicker` presents the system's pickers.** + - `sources()` lists what the device offers, in menu order: `photos`, + `camera` (iOS, where a camera exists and the app declares + `NSCameraUsageDescription`) and `files`. It is empty where the module is + absent. + - `pick({source, isMultiple?, limit?, media?, accept?})` presents one picker + over the calling surface and resolves `{ok: true, files}` (never an empty + list), `cancelled` when the person backs out, or a reason: a source the + device does not offer answers `unsupported-source` at once with the + platform's message, and a second picker while one is open answers `busy`. + Each file has `uri`, `name`, `size` (`-1` when the provider does not say) + and `type`. + - iOS: `photos` is `PHPickerViewController` (out of process, so no photo + library permission), `camera` is `UIImagePickerController`, and `files` + is `UIDocumentPickerViewController`. Each picked file is copied into the + app's temporary directory and returned as a `file://` URL; the photo + picker closes before it loads and copies, and `events.onLoading` reports + that loading step. + - Android: `photos` is the Photo Picker (the document picker on devices + without it) and `files` is the Storage Access Framework; the `content://` + URIs the pickers grant are returned as they are. Android offers no + `camera` source. + - Defaults: one file, the platform's limit, the media `accept` allows (else + all), and any file type. + - The library's `FileInput` reaches it through `useFilePicker()`, which + fills in the calling surface and waits for a leaving sheet before it + presents. + +- **FR14 — `AstryxStorage` is the runtime's string key-value store.** + - `get(key)` answers `{value}`, with `null` for a missing key; `set`, + `remove`, `keys({prefix?})` and `clear({prefix?})` complete the store; + `getJSON` and `setJSON` parse and serialize (`invalid-json`). `info()` + answers the namespace, the key count, the bytes the store takes on disk, + and the free space (`null` when the platform does not say). + - Every call works in the calling runtime's namespace, decided natively and + never by JavaScript: `app` for the app's own runtime, and a namespace of + its own for each Preview project, so a project never reads the app's data + or another project's. + - Values are kept across launches: one file per key in Application Support + on iOS and in the app's internal files directory on Android. No size limit + is the package's own: free space bounds a value. + - `clearProjectData(bundleUrl)` is for the app's runtime only: it removes + everything one Preview project stored, in every store that registers for + it, and answers the cleared namespace and whether the project's web view + data went too. A Preview project's call, or the app's own bundle URL, + answers `not-allowed`; a value that is not a URL answers `invalid-url`. + - The router's state persistence uses it as its default store, and the + update check keeps its "Not now" in the app's namespace. + +- **FR15 — `AstryxCrypto` gives secure random bytes synchronously.** + - `randomBytes(byteLength)`, `getRandomValues(array)` and `randomUUID()` + take their bytes from the system's secure generator (iOS + `SecRandomCopyBytes`, Android `java.security.SecureRandom`). They are + synchronous, because portable code calls `crypto.getRandomValues` inline. + - They follow Web Crypto's rules and errors: at most 65,536 bytes per call + (`QuotaExceededError`), integer typed arrays only (`TypeMismatchError`). + Where the module is absent they throw `NotSupportedError`; there is never + a non-secure fallback. + - The crypto installer of `spec:AST-112/FR5` (`./network` entry) installs + `crypto.getRandomValues` and `crypto.randomUUID` from this module where + the runtime lacks them, and installs nothing and reports `no-module` + without it. + +- **FR16 — Threads and lifecycle.** - Constants are read on the JavaScript thread once per module, at the first call that needs them. Asynchronous calls do their native work off the JavaScript thread, and a measure that walks files (`bundleSize()`) runs off @@ -348,7 +428,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - A module torn down during a reload answers `unavailable` until its runtime is back; a subscription made before the reload is removed with its store. -- **FR14 — Accessibility.** +- **FR17 — Accessibility.** - The library's drawn chrome follows the snapshot of FR5: Reduce Transparency makes drawn glass and materials opaque, Increase Contrast and Show Borders strengthen edges, Bold Text reaches drawn text and symbols, @@ -361,7 +441,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - These modules expose nothing to VoiceOver or TalkBack themselves; they have no view. -- **FR15 — Every contract is at revision 1; later behaviour is a named +- **FR18 — Every contract is at revision 1; later behaviour is a named feature.** - Every contract in the group reports revision 1. A behaviour added after revision 1 is a named feature, `.`, that the binary @@ -380,7 +460,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, contract set, and an older Astryx Stage refuses the project with the gaps listed. -- **FR16 — Astryx Stage simulates each module.** +- **FR19 — Astryx Stage simulates each module.** - `AstryxAppearance`: the saved choice per app in Astryx Stage's data folder, applied before the first frame; a run-only override in memory, which a new run forgets. @@ -398,6 +478,11 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - `AstryxNetwork`: a default route exists and the path is never metered; cookies in a jar per namespace; `fetchUntrusted` from a client of its own with no identity and no redirect following. + - `AstryxFilePicker`: the photo and document pickers; no camera, as on the + Simulator. + - `AstryxStorage`: one store per namespace in Astryx Stage's data folder, + counted the same way as on a device; a headless run starts empty. + - `AstryxCrypto`: the operating system's secure generator. - `AstryxBack` and `AstryxLaunch` are absent, as on iOS: the library takes its no-module path, every back press goes to React Native, and the first frame draws with no launch hold (OQ4). @@ -406,17 +491,20 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | Contract | iOS | Android | Astryx Stage | | ----------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | -| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | Saved file and in-memory run override (FR16) | -| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | Device settings from the run (FR16) | +| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | Saved file and in-memory run override (FR19) | +| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | Device settings from the run (FR19) | | `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | Trace entries; no feedback | | `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | In-memory string | | `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | Astryx Stage's own identity and tables | | `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | Drawn prompt; `undetermined` until asked | | `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the web profile's `CookieManager`; a separate HTTP client | Default route; per-namespace jar; its own client | -| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | Absent (FR16) | -| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | Absent (FR16) | +| `AstryxFilePicker` | `PHPickerViewController`, `UIImagePickerController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework; no camera source | Photos and files pickers; no camera | +| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | One store per namespace in its data folder | +| `AstryxCrypto` | `SecRandomCopyBytes` | `java.security.SecureRandom` | The operating system's generator | +| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | Absent (FR19) | +| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | Absent (FR19) | -- FR16 gap: Astryx Stage reports no `contractFeatures` list, and its +- FR19 gap: Astryx Stage reports no `contractFeatures` list, and its `AstryxAppearance` has no `getRunOverride` and no launch link. - Supported feature/engine floor: the platform floor of `spec:AST-112` (iOS at React Native's minimum, Android API level 24, the New Architecture @@ -425,7 +513,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, false, stay out of an answer, or keep the older behaviour below them. - Unsupported behavior: an absent module answers `no-module` and its synchronous members answer their empty values (FR2); a missing named feature - answers `unsupported` or keeps the revision-1 behaviour (FR15); a + answers `unsupported` or keeps the revision-1 behaviour (FR18); a platform-only module is absent on the other platform, and the library takes the path FR5, FR11 and FR12 name. - Browser evidence: none. Claims are proven on the iOS Simulator, the Android @@ -435,7 +523,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, ## Current-state impact - None beyond `spec:AST-112`. This record details its FR1 (the core's system - modules), FR6 and FR7 for each module's results and probes, FR8 for the + modules), FR5 for the crypto installer's module, FR6 and FR7 for each + module's results and probes, FR8 for the revision-1 baseline and named features, FR9 for the haptic moment mapping, and FR12 for Astryx Stage's simulation. - The group is entirely core, so the capability model's split between core and @@ -457,10 +546,13 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | FR10 | Unit tests; emulator and Simulator network changes; Astryx Stage network suites | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | | FR11 | Unit tests of the registry; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | | FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports; a Preview runtime | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | -| FR13 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | -| FR14 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | -| FR15 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent; an older Astryx Stage | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | -| FR16 | Astryx Stage contract suites against the Simulator and emulator results | each module's suite | An Astryx Stage answer differs from iOS and Android and its documentation does not name it | +| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks; Astryx Stage picker suites | each source; multiple; cancel; a missing camera usage string; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a crash for a missing usage string, or two pickers at once | +| FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs; Astryx Stage storage suites | the app's runtime and a Preview project's; a full disk; a project removed | One namespace reads another's data, a Preview project clears a project, or a cleared project leaves data | +| FR15 | Unit tests of the bytes, errors and installer; Simulator and emulator reads | 0 and 65,536 bytes; above the ceiling; module absent; an existing `crypto` | A non-secure fill, a call that does not throw Web Crypto's error, or an installer that replaces an existing function | +| FR16 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | +| FR17 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | +| FR18 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent; an older Astryx Stage | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | +| FR19 | Astryx Stage contract suites against the Simulator and emulator results | each module's suite | An Astryx Stage answer differs from iOS and Android and its documentation does not name it | ## Decision log @@ -519,7 +611,8 @@ missed call holds the splash. **Reference:** `spec:AST-130/DEC-5` **Decider:** imdreamrunner, 2026-11-17 -Haptics, the clipboard, permissions and network state are small wrappers +Haptics, the clipboard, permissions, the file pickers, storage, secure random +bytes and network state are small wrappers where the ecosystem has good libraries. They stay in the core because the package takes no runtime dependency outside React and React Native (`spec:AST-112/FR2`), and because each needs the result vocabulary, the @@ -528,12 +621,15 @@ Preview policy and an Astryx Stage simulation. OQ1 keeps the scope open. ## Open questions - **OQ1 — Do the thin system modules stay Astryx modules?** (`human-design`) - `AstryxHaptics`, `AstryxClipboard`, `AstryxPermissions` and the network - state of `AstryxNetwork` fill little capability gap. Options: keep them as + `AstryxHaptics`, `AstryxClipboard`, `AstryxPermissions`, `AstryxFilePicker`, + `AstryxStorage`, `AstryxCrypto` and the network state of `AstryxNetwork` + fill little capability gap. Options: keep them as core modules (one dependency set, one result shape, Astryx Stage parity); or replace their native side with adapters over community libraries (`expo-haptics`, `expo-clipboard`, `react-native-permissions`, - `@react-native-community/netinfo`), keeping the wrappers' API. + `expo-document-picker`, `@react-native-async-storage/async-storage`, + `react-native-get-random-values`, `@react-native-community/netinfo`), + keeping the wrappers' API. - **OQ2 — Do cookies, domain info, redirect modes and `fetchUntrusted` move to the data and security group?** (`human-design`) They are methods of `AstryxNetwork`, no Astryx component calls them, and their rules @@ -544,10 +640,10 @@ Preview policy and an Astryx Stage simulation. OQ1 keeps the scope open. one module whose contract this record shares with that group's record. - **OQ3 — Do the app-API-only modules stay in this group and the core?** (`human-design`) No Astryx component calls `AstryxAppearance`, - `AstryxPermissions` (used by the `./camera` and `./microphone` entries) or - `AstryxNetwork`. Options: keep them in the core with this record; or move + `AstryxPermissions` (used by the `./camera` and `./microphone` entries), + `AstryxNetwork` or `AstryxCrypto` (used by the crypto installer). Options: keep them in the core with this record; or move each to the entry that uses it. - **OQ4 — Does Astryx Stage simulate the Android root back gate and launch - hold?** (`checkable`) Options: keep both absent, as FR16 states; or simulate + hold?** (`checkable`) Options: keep both absent, as FR19 states; or simulate the back-to-home animation at the root and a launch window held until the first content. From 092892a4286ca38b4186f761500d92b9ed6d2b9c Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:28:45 -0800 Subject: [PATCH 04/32] spec(AST-130): public API only, no web engine in the core, camera capture outside the core picker, scope notes --- .../spec.md | 172 ++++++++++-------- 1 file changed, 98 insertions(+), 74 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index e0f66319e243b..dff7ea9e6f857 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -53,20 +53,20 @@ thin, dependency-free wrapper that gives the library one result shape, one Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, `spec:AST-082/FR13`). -| Module | What the ecosystem does well | The gap Astryx fills | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxAppearance` | React Native's `Appearance` reports the scheme and can override it while JavaScript runs; `expo-system-ui` sets the root background. | A saved choice that the native shell applies before the first frame of every launch, a run-only override, and an opt-in launch link. A choice that JavaScript applies arrives after the first frame, so the window and status bar cross-fade. | -| `AstryxAccessibilitySettings` | `AccessibilityInfo` reads Reduce Motion, Reduce Transparency, Bold Text, darker system colours and cross-fade transitions, with change events for most. | One synchronous snapshot for the first frame, a change event for every key, and the iOS settings `AccessibilityInfo` does not read (Reduce Bright Effects, Show Borders). Android uses `AccessibilityInfo` itself (FR5). | -| `AstryxHaptics` | `Vibration` plays patterns; `expo-haptics` plays UIKit's feedback kinds and Android effects well. | Little capability gap. The module plays Android's `HapticFeedbackConstants` on the view with an API-level chain, needs no Expo runtime library (`spec:AST-112/FR11`), and lets the theme map moments to kinds (FR6). Scope: OQ1. | -| `AstryxClipboard` | `expo-clipboard` and `@react-native-clipboard/clipboard` read and write text and test for content without reading it. | No real capability gap. The module exists for the result vocabulary, the Preview read and write policy (`not-allowed`), and Astryx Stage parity. Scope: OQ1. | -| `AstryxPlatformInfo` | `expo-device`, `expo-application` and `react-native-device-info` report the device, the app's version and install time. | The binary's own contract facts no library can know: each native component's revision, the linked capabilities, the named contract features, per-platform feature rows, and self-checks. Its app constants overlap the ecosystem with no gap. | -| `AstryxPermissions` | `PermissionsAndroid` asks on Android; `react-native-permissions` covers many permissions with `blocked` and `denied` states. | Little gap. A closed set tied to the opted-in capabilities, `not-declared` instead of a system crash, the Preview consent policy, and no extra dependency. Scope: OQ1. | -| `AstryxNetwork` | `@react-native-community/netinfo` reports the connection and its changes; cookie libraries read the native jar. | For state, little gap: one meaning of "connected" on every platform and a constrained flag (FR10). Cookies per runtime and a request with no identity have no ecosystem equivalent; they belong with data and security (OQ2). | -| `AstryxBack` | `BackHandler` delivers Android back presses to JavaScript, and navigators consume them. | React Native's activity always takes the back press, so Android's predictive back-to-home animation never plays at the root. The gate gives the press to the system when JavaScript has nothing to consume (FR11). | -| `AstryxLaunch` | `expo-splash-screen` holds the splash until the app hides it; `Linking.getInitialURL()` reads the launch link. | The library ends the Android launch hold at its first content with no app code and no Expo runtime library, and the router reads the launch link synchronously, so a cold deep link draws its screen in the first frame (FR12). | -| `AstryxFilePicker` | `expo-image-picker`, `expo-document-picker`, `react-native-image-picker` and `@react-native-documents/picker` present the system photo, camera and document pickers well. | Little gap: one call over photos, camera and files with the result vocabulary (`cancelled` is not an error), no permission for the out-of-process photo picker, `unsupported-source` instead of a crash where the camera's usage string is missing, and no extra dependency. Scope: OQ1. | -| `AstryxStorage` | `@react-native-async-storage/async-storage` and `react-native-mmkv` store strings and JSON well. | Little gap: the namespace is the calling runtime's, decided natively, so a Preview project never reads the app's data or another project's, and the app's runtime clears a project's data in one call. Scope: OQ1. | -| `AstryxCrypto` | `react-native-get-random-values`, `expo-crypto` and `react-native-quick-crypto` give secure random bytes and Web Crypto shapes. | No real capability gap. The module gives synchronous bytes from the system's secure generator with no non-secure fallback, for the package's own code and its crypto installer (`spec:AST-112/FR5`), with no extra dependency. Scope: OQ1. | +| Module | What the ecosystem does well | The gap Astryx fills | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `AstryxAppearance` | React Native's `Appearance` reports the scheme and can override it while JavaScript runs; `expo-system-ui` sets the root background. | A saved choice that the native shell applies before the first frame of every launch, a run-only override, and an opt-in launch link. A choice that JavaScript applies arrives after the first frame, so the window and status bar cross-fade. | +| `AstryxAccessibilitySettings` | `AccessibilityInfo` reads Reduce Motion, Reduce Transparency, Bold Text, darker system colours and cross-fade transitions, with change events for most. | One synchronous snapshot for the first frame, a change event for every key, and the iOS settings `AccessibilityInfo` does not read (Reduce Bright Effects, Show Borders). Android uses `AccessibilityInfo` itself (FR5). | +| `AstryxHaptics` | `Vibration` plays patterns; `expo-haptics` plays UIKit's feedback kinds and Android effects well. | Little capability gap. The module plays Android's `HapticFeedbackConstants` on the view with an API-level chain, needs no Expo runtime library (`spec:AST-112/FR11`), and lets the theme map moments to kinds (FR6). Scope: OQ1. | +| `AstryxClipboard` | `expo-clipboard` and `@react-native-clipboard/clipboard` read and write text and test for content without reading it. | No real capability gap. The module exists for the result vocabulary, the Preview read and write policy (`not-allowed`), and Astryx Stage parity. Scope: OQ1. | +| `AstryxPlatformInfo` | `expo-device`, `expo-application` and `react-native-device-info` report the device, the app's version and install time. | The binary's own contract facts no library can know: each native component's revision, the linked capabilities, the named contract features, per-platform feature rows, and self-checks. Its app constants overlap the ecosystem with no gap. | +| `AstryxPermissions` | `PermissionsAndroid` asks on Android; `react-native-permissions` covers many permissions with `blocked` and `denied` states. | Little gap. A closed set tied to the opted-in capabilities, `not-declared` instead of a system crash, the Preview consent policy, and no extra dependency. Scope: OQ1. | +| `AstryxNetwork` | `@react-native-community/netinfo` reports the connection and its changes; cookie libraries read the native jar. | For state, little gap: one meaning of "connected" on every platform and a constrained flag (FR10). Cookies per runtime and a request with no identity have no ecosystem equivalent; they belong with data and security (OQ2). | +| `AstryxBack` | `BackHandler` delivers Android back presses to JavaScript, and navigators consume them. | React Native's activity always takes the back press, so Android's predictive back-to-home animation never plays at the root. The gate gives the press to the system when JavaScript has nothing to consume (FR11). | +| `AstryxLaunch` | `expo-splash-screen` holds the splash until the app hides it; `Linking.getInitialURL()` reads the launch link. | The library ends the Android launch hold at its first content with no app code and no Expo runtime library, and the router reads the launch link synchronously, so a cold deep link draws its screen in the first frame (FR12). | +| `AstryxFilePicker` | `expo-image-picker`, `expo-document-picker`, `react-native-image-picker` and `@react-native-documents/picker` present the system photo, camera and document pickers well. | Little gap: one call over photos and files with the result vocabulary (`cancelled` is not an error), no permission for the out-of-process photo picker, and no extra dependency. Camera capture belongs to the `camera` capability (FR13). Scope: OQ1. | +| `AstryxStorage` | `@react-native-async-storage/async-storage` and `react-native-mmkv` store strings and JSON well. | Little gap: the namespace is the calling runtime's, decided natively, so a Preview project never reads the app's data or another project's, and the app's runtime clears a project's data in one call. Scope: OQ1. | +| `AstryxCrypto` | `react-native-get-random-values`, `expo-crypto` and `react-native-quick-crypto` give secure random bytes and Web Crypto shapes. | No real capability gap. The module gives synchronous bytes from the system's secure generator with no non-secure fallback, for the package's own code and its crypto installer (`spec:AST-112/FR5`), with no extra dependency. Scope: OQ1. | ## Who uses it @@ -81,15 +81,22 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component calls the module; app API (`./network` entry: `useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2, OQ3) | An offline banner or a sign-out that the app draws. | | `AstryxBack` | native module (Turbo Native Module) | Through the library's back registry: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | | `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | -| `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo, camera or document picker; backing out changes nothing. | +| `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | | `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the update check's "Not now" (`./updates` entry); app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | | `AstryxCrypto` | native module (Turbo Native Module) | No Astryx component; the public crypto installer (`./network` entry) and app API `AstryxCrypto` (OQ3) | Nothing directly: identifiers and sign-in nonces an app makes come from the system's secure generator. | ## Non-goals -- The data and security modules (files, secure storage, client identity) and - their records. This record names only the parts of `AstryxNetwork` the - library depends on (OQ2). +- The data and security modules (files, secure storage) and their records. + This record names only the parts of `AstryxNetwork` the library depends on + (OQ2). +- Modules outside the core: client identity, crash reports, daily metrics, + the frame recorder, and image markup. Their own records own them. +- Camera capture. The `camera` capability owns it, the camera source of a + picker included. +- Sharing, opening links and Settings, keep-awake, and orientation lock. None + is a core module; each one is an opt-in capability of its own when Astryx + provides it. - The design of the theme's appearance model and its scopes; this record owns only the native appearance override. - Haptic intensities per moment. The theme's haptic tokens own them @@ -149,7 +156,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxClipboard` | `unavailable` (no pasteboard on this device) | | `AstryxPlatformInfo` | `unavailable` (the system did not answer a measure) | | `AstryxPermissions` | `unknown-permission`, `busy`, `no-activity` (Android), `not-declared` | - | `AstryxFilePicker` | `unsupported-source`, `no-window`, `busy`, `permission-denied`, `restricted`; `cancelled` when the person backs out | + | `AstryxFilePicker` | `unsupported-source`, `no-window`, `busy`; `cancelled` when the person backs out | | `AstryxStorage` | `invalid-key`, `invalid-value`, `invalid-json`, `no-space`, `io`, `no-namespace`; `invalid-url` for `clearProjectData` | | `AstryxNetwork` | `unavailable`, `invalid-url`, `invalid-host`, `invalid-cookie`; for `fetchUntrusted`: `invalid-request`, `redirect-refused`, `timeout`, `too-large`, `network`, `aborted` | @@ -354,10 +361,10 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - iOS has no module: its launch screen stays until the first frame. - **FR13 — `AstryxFilePicker` presents the system's pickers.** - - `sources()` lists what the device offers, in menu order: `photos`, - `camera` (iOS, where a camera exists and the app declares - `NSCameraUsageDescription`) and `files`. It is empty where the module is - absent. + - `sources()` lists what the device offers, in menu order: `photos` and + `files`. It is empty where the module is absent. Camera capture is the + `camera` capability's (`./camera` entry), never a source of the core + picker, so the core needs no camera permission or usage string. - `pick({source, isMultiple?, limit?, media?, accept?})` presents one picker over the calling surface and resolves `{ok: true, files}` (never an empty list), `cancelled` when the person backs out, or a reason: a source the @@ -366,20 +373,21 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, Each file has `uri`, `name`, `size` (`-1` when the provider does not say) and `type`. - iOS: `photos` is `PHPickerViewController` (out of process, so no photo - library permission), `camera` is `UIImagePickerController`, and `files` - is `UIDocumentPickerViewController`. Each picked file is copied into the + library permission) and `files` is `UIDocumentPickerViewController`. Each picked file is copied into the app's temporary directory and returned as a `file://` URL; the photo picker closes before it loads and copies, and `events.onLoading` reports that loading step. - Android: `photos` is the Photo Picker (the document picker on devices without it) and `files` is the Storage Access Framework; the `content://` - URIs the pickers grant are returned as they are. Android offers no - `camera` source. + URIs the pickers grant are returned as they are. - Defaults: one file, the platform's limit, the media `accept` allows (else all), and any file type. - The library's `FileInput` reaches it through `useFilePicker()`, which fills in the calling surface and waits for a leaving sheet before it presents. + - FR13 gap: on iOS the core picker offers a `camera` source + (`UIImagePickerController`) and answers its `permission-denied` and + `restricted` reasons. - **FR14 — `AstryxStorage` is the runtime's string key-value store.** - `get(key)` answers `{value}`, with `null` for a missing key; `set`, @@ -395,9 +403,10 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, on iOS and in the app's internal files directory on Android. No size limit is the package's own: free space bounds a value. - `clearProjectData(bundleUrl)` is for the app's runtime only: it removes - everything one Preview project stored, in every store that registers for - it, and answers the cleared namespace and whether the project's web view - data went too. A Preview project's call, or the app's own bundle URL, + everything one Preview project stored, in every store that registers a + clearer with the core, and answers the cleared namespace. A project's web + view data goes through the `web` capability's own clearer where that + capability is linked, and `isWebDataCleared` says whether it went. A Preview project's call, or the app's own bundle URL, answers `not-allowed`; a value that is not a URL answers `invalid-url`. - The router's state persistence uses it as its default store, and the update check keeps its "Not now" in the app's namespace. @@ -478,8 +487,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - `AstryxNetwork`: a default route exists and the path is never metered; cookies in a jar per namespace; `fetchUntrusted` from a client of its own with no identity and no redirect following. - - `AstryxFilePicker`: the photo and document pickers; no camera, as on the - Simulator. + - `AstryxFilePicker`: the photo and document pickers. - `AstryxStorage`: one store per namespace in Astryx Stage's data folder, counted the same way as on a device; a headless run starts empty. - `AstryxCrypto`: the operating system's secure generator. @@ -487,22 +495,33 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, its no-module path, every back press goes to React Native, and the first frame draws with no launch hold (OQ4). +- **FR20 — Public platform API only, and no web engine in the core.** + - The native code of every module in the group uses public platform API + only; the group needs no exception. + - No core module links WebKit (iOS) or androidx.webkit (Android). Web view + data and the web view's cookie store belong to the `web` capability + (`spec:AST-112/FR3`), which registers what the core needs through the + core's registration hooks (`spec:AST-112/FR2`). + - FR20 gap: on iOS the core's project-data clear removes web view data + through WebKit, and on Android the core's cookie API reaches the cookie + store through androidx.webkit. + ### Platform support -| Contract | iOS | Android | Astryx Stage | -| ----------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | -| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | Saved file and in-memory run override (FR19) | -| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | Device settings from the run (FR19) | -| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | Trace entries; no feedback | -| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | In-memory string | -| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | Astryx Stage's own identity and tables | -| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | Drawn prompt; `undetermined` until asked | -| `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the web profile's `CookieManager`; a separate HTTP client | Default route; per-namespace jar; its own client | -| `AstryxFilePicker` | `PHPickerViewController`, `UIImagePickerController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework; no camera source | Photos and files pickers; no camera | -| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | One store per namespace in its data folder | -| `AstryxCrypto` | `SecRandomCopyBytes` | `java.security.SecureRandom` | The operating system's generator | -| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | Absent (FR19) | -| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | Absent (FR19) | +| Contract | iOS | Android | Astryx Stage | +| ----------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | Saved file and in-memory run override (FR19) | +| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | Device settings from the run (FR19) | +| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | Trace entries; no feedback | +| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | In-memory string | +| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | Astryx Stage's own identity and tables | +| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | Drawn prompt; `undetermined` until asked | +| `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the runtime's cookie store; a separate HTTP client | Default route; per-namespace jar; its own client | +| `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | Photos and files pickers | +| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | One store per namespace in its data folder | +| `AstryxCrypto` | `SecRandomCopyBytes` | `java.security.SecureRandom` | The operating system's generator | +| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | Absent (FR19) | +| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | Absent (FR19) | - FR19 gap: Astryx Stage reports no `contractFeatures` list, and its `AstryxAppearance` has no `getRunOverride` and no launch link. @@ -522,37 +541,42 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, ## Current-state impact -- None beyond `spec:AST-112`. This record details its FR1 (the core's system - modules), FR5 for the crypto installer's module, FR6 and FR7 for each - module's results and probes, FR8 for the - revision-1 baseline and named features, FR9 for the haptic moment mapping, - and FR12 for Astryx Stage's simulation. -- The group is entirely core, so the capability model's split between core and - opt-in capabilities in `spec:AST-112/FR1` and FR3 does not change for it. +- This record details `spec:AST-112`: its FR1 (the core's system modules), FR5 + for the crypto installer's module, FR6 and FR7 for each module's results and + probes, FR8 for the revision-1 baseline and named features, FR9 for the + haptic moment mapping, and FR12 for Astryx Stage's simulation. +- It changes `spec:AST-112/FR1` in two places: client identity leaves the + list of generic core capabilities, and the `camera` capability gains camera + capture, the camera source of the file picker included (FR13). +- `spec:AST-112/FR1` and FR3 gain one rule: the core links no web engine, and + the `web` capability carries web view data and its cookie store (FR20). +- The rest of the split between core and opt-in capabilities does not change + for this group: every module in it is core. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | -| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw; a Preview runtime | A synchronous member throws, a call rejects, or answers a reason outside its set | -| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | -| FR4 | Unit tests; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link | saved `dark` under a light system; `persist: false`; launch link cold and warm; Preview runtime | The first frame shows the system's style, a run-only change survives a relaunch, or a Preview project changes the host's appearance | -| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting; Astryx Stage settings suites | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | -| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | -| FR7 | Unit tests; Simulator and emulator copy and paste; Astryx Stage clipboard suites | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | -| FR8 | Unit tests; Astryx Stage platform-info suites; Simulator and emulator reads | constants; `get()`; memory and size; Preview runtime | A Preview project reads the host's launch, memory or size, or a constant throws | -| FR9 | Unit tests; Simulator and emulator prompts; Astryx Stage permission suites | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | -| FR10 | Unit tests; emulator and Simulator network changes; Astryx Stage network suites | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | -| FR11 | Unit tests of the registry; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | -| FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports; a Preview runtime | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | -| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks; Astryx Stage picker suites | each source; multiple; cancel; a missing camera usage string; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a crash for a missing usage string, or two pickers at once | -| FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs; Astryx Stage storage suites | the app's runtime and a Preview project's; a full disk; a project removed | One namespace reads another's data, a Preview project clears a project, or a cleared project leaves data | -| FR15 | Unit tests of the bytes, errors and installer; Simulator and emulator reads | 0 and 65,536 bytes; above the ceiling; module absent; an existing `crypto` | A non-secure fill, a call that does not throw Web Crypto's error, or an installer that replaces an existing function | -| FR16 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | -| FR17 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | -| FR18 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent; an older Astryx Stage | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | -| FR19 | Astryx Stage contract suites against the Simulator and emulator results | each module's suite | An Astryx Stage answer differs from iOS and Android and its documentation does not name it | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | +| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw; a Preview runtime | A synchronous member throws, a call rejects, or answers a reason outside its set | +| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | +| FR4 | Unit tests; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link | saved `dark` under a light system; `persist: false`; launch link cold and warm; Preview runtime | The first frame shows the system's style, a run-only change survives a relaunch, or a Preview project changes the host's appearance | +| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting; Astryx Stage settings suites | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | +| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | +| FR7 | Unit tests; Simulator and emulator copy and paste; Astryx Stage clipboard suites | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | +| FR8 | Unit tests; Astryx Stage platform-info suites; Simulator and emulator reads | constants; `get()`; memory and size; Preview runtime | A Preview project reads the host's launch, memory or size, or a constant throws | +| FR9 | Unit tests; Simulator and emulator prompts; Astryx Stage permission suites | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | +| FR10 | Unit tests; emulator and Simulator network changes; Astryx Stage network suites | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | +| FR11 | Unit tests of the registry; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | +| FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports; a Preview runtime | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | +| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks; Astryx Stage picker suites | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | +| FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs; Astryx Stage storage suites | the app's runtime and a Preview project's; a full disk; a project removed | One namespace reads another's data, a Preview project clears a project, or a cleared project leaves data | +| FR15 | Unit tests of the bytes, errors and installer; Simulator and emulator reads | 0 and 65,536 bytes; above the ceiling; module absent; an existing `crypto` | A non-secure fill, a call that does not throw Web Crypto's error, or an installer that replaces an existing function | +| FR16 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | +| FR17 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | +| FR18 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent; an older Astryx Stage | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | +| FR19 | Astryx Stage contract suites against the Simulator and emulator results | each module's suite | An Astryx Stage answer differs from iOS and Android and its documentation does not name it | +| FR20 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | ## Decision log From 1e0ec3ef1f5ce2065c50839f26e6c5785d8230ed Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:36:55 -0800 Subject: [PATCH 05/32] spec(AST-130): own wording throughout; the other platform modules each have their own record --- .../spec.md | 85 ++++++++++--------- 1 file changed, 43 insertions(+), 42 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index dff7ea9e6f857..213cb23cb7748 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -90,8 +90,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - The data and security modules (files, secure storage) and their records. This record names only the parts of `AstryxNetwork` the library depends on (OQ2). -- Modules outside the core: client identity, crash reports, daily metrics, - the frame recorder, and image markup. Their own records own them. +- Client identity, crash reports, daily metrics, the frame recorder, and + image markup. Each is part of the platform package and has its own record. - Camera capture. The `camera` capability owns it, the camera source of a picker included. - Sharing, opening links and Settings, keep-awake, and orientation lock. None @@ -201,10 +201,10 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, iOS as the window's user interface style before the window shows, on Android as AppCompat's default night mode at process start. React Native's `Appearance` and `useColorScheme` then report the chosen scheme, so the - theme follows it. The launch screen and the splash follow the system's - choice, because the system draws them before app code runs; the Android 12 - and later splash follows the saved choice through the night mode the system - keeps per app. + theme follows it. The system draws the iOS launch screen before any of the + app's code runs, so it keeps the system's appearance; on Android 12 and + later the splash uses the night mode the system stores for the app, which + is the saved choice. - `setOverride(value, {persist: false})` (feature `persist-false`) applies the choice for this run only and saves nothing. `getOverride()` and the next launch keep the saved choice, and `setOverride(getOverride())` restores @@ -219,11 +219,11 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, arrival on a warm one (feature `launch-link`). Nothing is saved. - In a Preview project's runtime, `getOverride()` answers `'system'`, `getRunOverride()` answers `null`, and `setOverride` answers `not-allowed`: - the host app's appearance is not a project's to change. + a project cannot change the appearance of the app that hosts it. - **FR5 — `AstryxAccessibilitySettings` publishes one settings snapshot.** - - The snapshot has seven booleans, each always present and false where the - OS version lacks the setting: `isReduceTransparency`, + - The snapshot has seven booleans. Every answer carries all seven, and a key + reads false on an OS version without that setting: `isReduceTransparency`, `isIncreaseContrast`, `isReduceMotion`, `prefersCrossFadeTransitions`, `isBoldText`, `isReduceBrightEffects` (iOS 26.4 and later), and `isShowBorders` (Show Borders on iOS 26.1 and later, Button Shapes before). @@ -234,8 +234,9 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, React Native's `AccessibilityInfo`: Reduce Motion everywhere, high text contrast as `isIncreaseContrast` on Android, and the iOS settings it reads. Keys `AccessibilityInfo` cannot read stay false. - - The snapshot does not report Liquid Glass's Clear or Tinted appearance: no - public API reads it, so native glass follows it and drawn chrome does not. + - The snapshot has no key for Liquid Glass's Clear or Tinted look, because the + system gives apps no way to read that setting. Native glass follows it; + drawn chrome does not. - **FR6 — `AstryxHaptics` plays the platform's feedback kinds.** - `play(kind)` plays one of UIKit's nine kinds: `selection`, `impactLight`, @@ -243,9 +244,9 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, `notificationSuccess`, `notificationWarning`, `notificationError`. iOS plays it with a prepared feedback generator; `prepare(kind)` warms the generator so the next `play` has no delay. - - Android plays a chain of `HapticFeedbackConstants` names, preferred first, - on the current activity's root view: the first name the device's API level - has. Each kind has a default chain; `play(kind, {android})` passes another. + - Android plays a chain of `HapticFeedbackConstants` names, in order of + preference, on the root view of the activity in front: the first name the + device's API level knows. Each kind has a default chain; `play(kind, {android})` passes another. - `isAvailable()` is false where the module is absent or `isSupported()` is false (no haptic hardware, or no window). `play` and `prepare` do nothing then. @@ -263,8 +264,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, (`PasteButton`); copy buttons never read. - `detectPatterns(['webURL' | 'webSearch' | 'number'])` answers whether the pasteboard probably holds each pattern, without reading the content and - without a paste notice. A key the platform cannot tell is left out: Android - has no web-search or number test, and has none before Android 12. + without a paste notice. The answer omits every pattern the platform cannot + test: Android tests only for a web URL, and only from Android 12. - `isAvailable()` is false where the module is absent or `isSupported()` is false; calls then answer `no-module` or `unavailable`. @@ -283,13 +284,13 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, self-checks of the platform internals the package relies on (`compat`). `supports(name)` reads a feature row from the last answer and is `null` while it is unknown. - - `memory()` answers the process's memory in bytes, each platform's own - measure (iOS `phys_footprint`, Android total PSS), not comparable across - platforms. `bundleSize()` answers the installed app's size on disk, read + - `memory()` answers the process's memory in bytes, counted the way each + platform counts it (iOS `phys_footprint`, Android total PSS); the iOS and + Android numbers do not compare. `bundleSize()` answers the installed app's size on disk, read off the main thread. - A Preview project's runtime gets no `launch`, an empty `installedAt`, and - `not-allowed` from `memory()` and `bundleSize()`: the host's process and - install are not a project's to read. + `not-allowed` from `memory()` and `bundleSize()`: a project cannot read + facts about the app that hosts it. - **FR9 — `AstryxPermissions` reads and asks explicitly.** - `get(name)` never prompts. `request(name)` shows the system prompt only for @@ -298,8 +299,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, (`spec:AST-112/FR7`). - `name` is a closed set (`camera`). The states are `granted`, `undetermined`, `denied` (refused; the app may ask again) and `blocked` - (only Settings changes it: iOS `denied` or `restricted`, Android "don't ask - again"). + (the person can change it in Settings only: iOS `denied` or `restricted`, + Android "don't ask again"). - `hasHardware` says whether the device has the hardware: false on the iOS Simulator and an emulator without a camera; `null` where the platform does not say. @@ -315,10 +316,11 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, `ethernet`, `other`, `none`, `unknown`), `isMetered`, and `isConstrained` (iOS Low Data Mode, Android Data Saver for this app). `connected`, `expensive` and `constrained` are deprecated aliases. - - `isConnected` has one meaning on every platform: a default route to the - internet exists (iOS: the path monitor's path is satisfied; Android: the - default network has INTERNET). It is not validated connectivity: a captive - portal before sign-in reads connected, and a request can still fail. + - `isConnected` is true when the device has a default route to the + internet: on iOS a satisfied path from the path monitor, on Android a + default network with the INTERNET capability. It says nothing about whether + a server answers: it is true behind a captive portal, where requests still + fail. - On Android the reads need `ACCESS_NETWORK_STATE`, which the configuration plugin writes for the core; without it, `getState()` answers `unavailable` and names the permission. @@ -339,16 +341,17 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, can go back. The shell activity enables its one back callback only then. - With nothing to consume, the system takes the press and plays its back-to-home animation (Android 16 predictive back). - - Before the first call, and after the runtime ends, the activity sends every - press to React Native, as React Native's own activity does. + - Until the library reports for the first time, and after its runtime stops, + back presses go to React Native unchanged. - The registry sends a value only when it changes. A Preview project's runtime changes nothing. iOS has no module: back is native there. - **FR12 — `AstryxLaunch` hands Android's cold launch to the first content.** - The shell activity keeps the system's launch window (the splash screen on API 31 and later, the window background before) until the library calls - `firstContent()`, instead of drawing an empty root while the bundle loads. - It lets go after a time bound (2.5 seconds) when no call arrives. + `firstContent()`, so no blank frame appears between the launch window and + the first screen. When no call arrives within 2.5 seconds, it shows the app + anyway. - The library calls it once per runtime: from the router's first focused screen's first content layout, or from `AstryxPerformance.markFirstFrame`, whichever comes first. Later calls do nothing. @@ -366,8 +369,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, `camera` capability's (`./camera` entry), never a source of the core picker, so the core needs no camera permission or usage string. - `pick({source, isMultiple?, limit?, media?, accept?})` presents one picker - over the calling surface and resolves `{ok: true, files}` (never an empty - list), `cancelled` when the person backs out, or a reason: a source the + over the calling surface and resolves `{ok: true, files}` with at least + one file, `cancelled` when the person backs out, or a reason: a source the device does not offer answers `unsupported-source` at once with the platform's message, and a second picker while one is open answers `busy`. Each file has `uri`, `name`, `size` (`-1` when the provider does not say) @@ -382,9 +385,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, URIs the pickers grant are returned as they are. - Defaults: one file, the platform's limit, the media `accept` allows (else all), and any file type. - - The library's `FileInput` reaches it through `useFilePicker()`, which - fills in the calling surface and waits for a leaving sheet before it - presents. + - The library's `FileInput` reaches it through `useFilePicker()`. - FR13 gap: on iOS the core picker offers a `camera` source (`UIImagePickerController`) and answers its `permission-denied` and `restricted` reasons. @@ -400,8 +401,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, its own for each Preview project, so a project never reads the app's data or another project's. - Values are kept across launches: one file per key in Application Support - on iOS and in the app's internal files directory on Android. No size limit - is the package's own: free space bounds a value. + on iOS and in the app's internal files directory on Android. The package + sets no size limit; only the device's free space limits a value. - `clearProjectData(bundleUrl)` is for the app's runtime only: it removes everything one Preview project stored, in every store that registers a clearer with the core, and answers the cleared namespace. A project's web @@ -415,7 +416,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - `randomBytes(byteLength)`, `getRandomValues(array)` and `randomUUID()` take their bytes from the system's secure generator (iOS `SecRandomCopyBytes`, Android `java.security.SecureRandom`). They are - synchronous, because portable code calls `crypto.getRandomValues` inline. + synchronous, because Web Crypto's `getRandomValues` is, and code written for + it expects the bytes at once. - They follow Web Crypto's rules and errors: at most 65,536 bytes per call (`QuotaExceededError`), integer typed arrays only (`TypeMismatchError`). Where the module is absent they throw `NotSupportedError`; there is never @@ -545,9 +547,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, for the crypto installer's module, FR6 and FR7 for each module's results and probes, FR8 for the revision-1 baseline and named features, FR9 for the haptic moment mapping, and FR12 for Astryx Stage's simulation. -- It changes `spec:AST-112/FR1` in two places: client identity leaves the - list of generic core capabilities, and the `camera` capability gains camera - capture, the camera source of the file picker included (FR13). +- It changes `spec:AST-112/FR1` in one place: the `camera` capability gains + camera capture, the camera source of the file picker included (FR13). - `spec:AST-112/FR1` and FR3 gain one rule: the core links no web engine, and the `web` capability carries web view data and its cookie store (FR20). - The rest of the split between core and opt-in capabilities does not change From 437f1a982996e6b2a370844d360c568b02bad78b Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 19:12:17 -0800 Subject: [PATCH 06/32] spec(AST-130): Astryx Stage described by what it shows and answers --- .../spec.md | 72 +++++++++---------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 213cb23cb7748..e950ab728e1ff 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -42,8 +42,8 @@ This record details the system modules of the platform layer that links them. Every asynchronous call resolves the result vocabulary of `spec:AST-112/FR6`, every module has the capability shape of `spec:AST-112/FR7`, every interface evolves additively under -`spec:AST-112/FR8`, and Astryx Stage implements each module as the contract -developers build against (`spec:AST-112/FR12`). +`spec:AST-112/FR8`, and Astryx Stage answers each module's calls as iOS and +Android do, as the contract developers build against (`spec:AST-112/FR12`). ## Why this exists @@ -58,7 +58,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxAppearance` | React Native's `Appearance` reports the scheme and can override it while JavaScript runs; `expo-system-ui` sets the root background. | A saved choice that the native shell applies before the first frame of every launch, a run-only override, and an opt-in launch link. A choice that JavaScript applies arrives after the first frame, so the window and status bar cross-fade. | | `AstryxAccessibilitySettings` | `AccessibilityInfo` reads Reduce Motion, Reduce Transparency, Bold Text, darker system colours and cross-fade transitions, with change events for most. | One synchronous snapshot for the first frame, a change event for every key, and the iOS settings `AccessibilityInfo` does not read (Reduce Bright Effects, Show Borders). Android uses `AccessibilityInfo` itself (FR5). | | `AstryxHaptics` | `Vibration` plays patterns; `expo-haptics` plays UIKit's feedback kinds and Android effects well. | Little capability gap. The module plays Android's `HapticFeedbackConstants` on the view with an API-level chain, needs no Expo runtime library (`spec:AST-112/FR11`), and lets the theme map moments to kinds (FR6). Scope: OQ1. | -| `AstryxClipboard` | `expo-clipboard` and `@react-native-clipboard/clipboard` read and write text and test for content without reading it. | No real capability gap. The module exists for the result vocabulary, the Preview read and write policy (`not-allowed`), and Astryx Stage parity. Scope: OQ1. | +| `AstryxClipboard` | `expo-clipboard` and `@react-native-clipboard/clipboard` read and write text and test for content without reading it. | No real capability gap. The module exists for the result vocabulary, the Preview read and write policy (`not-allowed`), and the same answers in Astryx Stage. Scope: OQ1. | | `AstryxPlatformInfo` | `expo-device`, `expo-application` and `react-native-device-info` report the device, the app's version and install time. | The binary's own contract facts no library can know: each native component's revision, the linked capabilities, the named contract features, per-platform feature rows, and self-checks. Its app constants overlap the ecosystem with no gap. | | `AstryxPermissions` | `PermissionsAndroid` asks on Android; `react-native-permissions` covers many permissions with `blocked` and `denied` states. | Little gap. A closed set tied to the opted-in capabilities, `not-declared` instead of a system crash, the Preview consent policy, and no extra dependency. Scope: OQ1. | | `AstryxNetwork` | `@react-native-community/netinfo` reports the connection and its changes; cookie libraries read the native jar. | For state, little gap: one meaning of "connected" on every platform and a constrained flag (FR10). Cookies per runtime and a request with no identity have no ecosystem equivalent; they belong with data and security (OQ2). | @@ -467,18 +467,18 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, `getRunOverride()` answers `null` (such a binary has no run-only override), and a missing feature is reported once with a development warning. - Astryx Stage pairs with the package through the library's Stage version - floor: the package names the oldest Astryx Stage that implements its - contract set, and an older Astryx Stage refuses the project with the gaps - listed. + floor: the package names the oldest Astryx Stage that answers every + contract in its set, and an older Astryx Stage refuses the project and + lists the contracts it lacks. - **FR19 — Astryx Stage simulates each module.** - - `AstryxAppearance`: the saved choice per app in Astryx Stage's data folder, - applied before the first frame; a run-only override in memory, which a new - run forgets. + - `AstryxAppearance`: the saved choice per app, kept across runs and + applied before the first frame; a run-only override, which a new run + forgets. - `AstryxAccessibilitySettings`: the run's device settings, set by arguments and changed live, delivered as the same snapshot and event. - - `AstryxHaptics`: present and supported; each `play` is a trace entry that - names the kind or the Android constant, and plays nothing. + - `AstryxHaptics`: present and supported; each `play` shows in Astryx + Stage's trace with the kind or the Android constant, and plays nothing. - `AstryxClipboard`: an in-memory string; `detectPatterns` classifies it without handing it back; Preview reads ask as on a device. - `AstryxPlatformInfo`: Astryx Stage's own app identity, its component @@ -490,8 +490,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, cookies in a jar per namespace; `fetchUntrusted` from a client of its own with no identity and no redirect following. - `AstryxFilePicker`: the photo and document pickers. - - `AstryxStorage`: one store per namespace in Astryx Stage's data folder, - counted the same way as on a device; a headless run starts empty. + - `AstryxStorage`: one store per namespace, kept across runs and counted + the same way as on a device; a headless run starts empty. - `AstryxCrypto`: the operating system's secure generator. - `AstryxBack` and `AstryxLaunch` are absent, as on iOS: the library takes its no-module path, every back press goes to React Native, and the first @@ -510,20 +510,20 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, ### Platform support -| Contract | iOS | Android | Astryx Stage | -| ----------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------ | -| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | Saved file and in-memory run override (FR19) | -| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | Device settings from the run (FR19) | -| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | Trace entries; no feedback | -| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | In-memory string | -| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | Astryx Stage's own identity and tables | -| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | Drawn prompt; `undetermined` until asked | -| `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the runtime's cookie store; a separate HTTP client | Default route; per-namespace jar; its own client | -| `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | Photos and files pickers | -| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | One store per namespace in its data folder | -| `AstryxCrypto` | `SecRandomCopyBytes` | `java.security.SecureRandom` | The operating system's generator | -| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | Absent (FR19) | -| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | Absent (FR19) | +| Contract | iOS | Android | Astryx Stage | +| ----------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | Saved choice and run-only override (FR19) | +| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | Device settings from the run (FR19) | +| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | Trace entries; no feedback | +| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | In-memory string | +| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | Astryx Stage's own identity, revisions and feature rows | +| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | Drawn prompt; `undetermined` until asked | +| `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the runtime's cookie store; a separate HTTP client | Default route; per-namespace jar; its own client | +| `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | Photos and files pickers | +| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | One store per namespace, kept across runs | +| `AstryxCrypto` | `SecRandomCopyBytes` | `java.security.SecureRandom` | The operating system's generator | +| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | Absent (FR19) | +| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | Absent (FR19) | - FR19 gap: Astryx Stage reports no `contractFeatures` list, and its `AstryxAppearance` has no `getRunOverride` and no launch link. @@ -562,21 +562,21 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw; a Preview runtime | A synchronous member throws, a call rejects, or answers a reason outside its set | | FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | | FR4 | Unit tests; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link | saved `dark` under a light system; `persist: false`; launch link cold and warm; Preview runtime | The first frame shows the system's style, a run-only change survives a relaunch, or a Preview project changes the host's appearance | -| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting; Astryx Stage settings suites | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | +| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting; Astryx Stage contract checks | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | | FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | -| FR7 | Unit tests; Simulator and emulator copy and paste; Astryx Stage clipboard suites | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | -| FR8 | Unit tests; Astryx Stage platform-info suites; Simulator and emulator reads | constants; `get()`; memory and size; Preview runtime | A Preview project reads the host's launch, memory or size, or a constant throws | -| FR9 | Unit tests; Simulator and emulator prompts; Astryx Stage permission suites | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | -| FR10 | Unit tests; emulator and Simulator network changes; Astryx Stage network suites | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | +| FR7 | Unit tests; Simulator and emulator copy and paste; Astryx Stage contract checks | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | +| FR8 | Unit tests; Astryx Stage contract checks; Simulator and emulator reads | constants; `get()`; memory and size; Preview runtime | A Preview project reads the host's launch, memory or size, or a constant throws | +| FR9 | Unit tests; Simulator and emulator prompts; Astryx Stage contract checks | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | +| FR10 | Unit tests; emulator and Simulator network changes; Astryx Stage contract checks | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | | FR11 | Unit tests of the registry; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | | FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports; a Preview runtime | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | -| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks; Astryx Stage picker suites | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | -| FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs; Astryx Stage storage suites | the app's runtime and a Preview project's; a full disk; a project removed | One namespace reads another's data, a Preview project clears a project, or a cleared project leaves data | +| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks; Astryx Stage contract checks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | +| FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs; Astryx Stage contract checks | the app's runtime and a Preview project's; a full disk; a project removed | One namespace reads another's data, a Preview project clears a project, or a cleared project leaves data | | FR15 | Unit tests of the bytes, errors and installer; Simulator and emulator reads | 0 and 65,536 bytes; above the ceiling; module absent; an existing `crypto` | A non-secure fill, a call that does not throw Web Crypto's error, or an installer that replaces an existing function | | FR16 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | | FR17 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | | FR18 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent; an older Astryx Stage | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | -| FR19 | Astryx Stage contract suites against the Simulator and emulator results | each module's suite | An Astryx Stage answer differs from iOS and Android and its documentation does not name it | +| FR19 | Astryx Stage contract checks against the Simulator and emulator results | each module's checks | An Astryx Stage answer differs from iOS and Android and its documentation does not name it | | FR20 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | ## Decision log @@ -649,7 +649,7 @@ Preview policy and an Astryx Stage simulation. OQ1 keeps the scope open. `AstryxHaptics`, `AstryxClipboard`, `AstryxPermissions`, `AstryxFilePicker`, `AstryxStorage`, `AstryxCrypto` and the network state of `AstryxNetwork` fill little capability gap. Options: keep them as - core modules (one dependency set, one result shape, Astryx Stage parity); or + core modules (one dependency set, one result shape, the same answers in Astryx Stage); or replace their native side with adapters over community libraries (`expo-haptics`, `expo-clipboard`, `react-native-permissions`, `expo-document-picker`, `@react-native-async-storage/async-storage`, From c79000c1a894bb7520a49b6a51499fb4d0a4bd95 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:10:57 -0800 Subject: [PATCH 07/32] spec(AST-130): short Why, no aliases, relies on the amended AST-112, review consistency fixes, Light/Dark question --- .../spec.md | 209 ++++++++++-------- 1 file changed, 113 insertions(+), 96 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index e950ab728e1ff..989b93b924cd5 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -47,43 +47,54 @@ Android do, as the contract developers build against (`spec:AST-112/FR12`). ## Why this exists -React Native and its community already cover most of these needs. Astryx owns -a module where the ecosystem leaves a specific gap, or where the module is a -thin, dependency-free wrapper that gives the library one result shape, one -Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, -`spec:AST-082/FR13`). - -| Module | What the ecosystem does well | The gap Astryx fills | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `AstryxAppearance` | React Native's `Appearance` reports the scheme and can override it while JavaScript runs; `expo-system-ui` sets the root background. | A saved choice that the native shell applies before the first frame of every launch, a run-only override, and an opt-in launch link. A choice that JavaScript applies arrives after the first frame, so the window and status bar cross-fade. | -| `AstryxAccessibilitySettings` | `AccessibilityInfo` reads Reduce Motion, Reduce Transparency, Bold Text, darker system colours and cross-fade transitions, with change events for most. | One synchronous snapshot for the first frame, a change event for every key, and the iOS settings `AccessibilityInfo` does not read (Reduce Bright Effects, Show Borders). Android uses `AccessibilityInfo` itself (FR5). | -| `AstryxHaptics` | `Vibration` plays patterns; `expo-haptics` plays UIKit's feedback kinds and Android effects well. | Little capability gap. The module plays Android's `HapticFeedbackConstants` on the view with an API-level chain, needs no Expo runtime library (`spec:AST-112/FR11`), and lets the theme map moments to kinds (FR6). Scope: OQ1. | -| `AstryxClipboard` | `expo-clipboard` and `@react-native-clipboard/clipboard` read and write text and test for content without reading it. | No real capability gap. The module exists for the result vocabulary, the Preview read and write policy (`not-allowed`), and the same answers in Astryx Stage. Scope: OQ1. | -| `AstryxPlatformInfo` | `expo-device`, `expo-application` and `react-native-device-info` report the device, the app's version and install time. | The binary's own contract facts no library can know: each native component's revision, the linked capabilities, the named contract features, per-platform feature rows, and self-checks. Its app constants overlap the ecosystem with no gap. | -| `AstryxPermissions` | `PermissionsAndroid` asks on Android; `react-native-permissions` covers many permissions with `blocked` and `denied` states. | Little gap. A closed set tied to the opted-in capabilities, `not-declared` instead of a system crash, the Preview consent policy, and no extra dependency. Scope: OQ1. | -| `AstryxNetwork` | `@react-native-community/netinfo` reports the connection and its changes; cookie libraries read the native jar. | For state, little gap: one meaning of "connected" on every platform and a constrained flag (FR10). Cookies per runtime and a request with no identity have no ecosystem equivalent; they belong with data and security (OQ2). | -| `AstryxBack` | `BackHandler` delivers Android back presses to JavaScript, and navigators consume them. | React Native's activity always takes the back press, so Android's predictive back-to-home animation never plays at the root. The gate gives the press to the system when JavaScript has nothing to consume (FR11). | -| `AstryxLaunch` | `expo-splash-screen` holds the splash until the app hides it; `Linking.getInitialURL()` reads the launch link. | The library ends the Android launch hold at its first content with no app code and no Expo runtime library, and the router reads the launch link synchronously, so a cold deep link draws its screen in the first frame (FR12). | -| `AstryxFilePicker` | `expo-image-picker`, `expo-document-picker`, `react-native-image-picker` and `@react-native-documents/picker` present the system photo, camera and document pickers well. | Little gap: one call over photos and files with the result vocabulary (`cancelled` is not an error), no permission for the out-of-process photo picker, and no extra dependency. Camera capture belongs to the `camera` capability (FR13). Scope: OQ1. | -| `AstryxStorage` | `@react-native-async-storage/async-storage` and `react-native-mmkv` store strings and JSON well. | Little gap: the namespace is the calling runtime's, decided natively, so a Preview project never reads the app's data or another project's, and the app's runtime clears a project's data in one call. Scope: OQ1. | -| `AstryxCrypto` | `react-native-get-random-values`, `expo-crypto` and `react-native-quick-crypto` give secure random bytes and Web Crypto shapes. | No real capability gap. The module gives synchronous bytes from the system's secure generator with no non-secure fallback, for the package's own code and its crypto installer (`spec:AST-112/FR5`), with no extra dependency. Scope: OQ1. | +The package takes no runtime dependency outside React and React Native +(`spec:AST-112/FR2`). Each module exists for one concrete gap; where the gap is +small, OQ1 keeps the scope open. + +- `AstryxAppearance`: the saved light or dark choice is in force from the first + frame of every launch. A choice that JavaScript applies arrives a frame late, + so the window and the status bar change after the app appears. +- `AstryxAccessibilitySettings`: one snapshot that is ready for the first + frame, a change event for every key, and the iOS settings that React + Native's accessibility API does not read. +- `AstryxHaptics`: a small gap. The theme maps moments to feedback kinds, and + Android plays the view feedback its API level has (OQ1). +- `AstryxClipboard`: no capability gap. The module gives the result + vocabulary, the Preview policy, and the same answers in Astryx Stage (OQ1). +- `AstryxPlatformInfo`: the binary's own contract facts (component revisions, + linked capabilities, named features), which only the binary can report. +- `AstryxPermissions`: a small gap. A closed set of permissions tied to the + capabilities, with `not-declared` where the system would end the app (OQ1). +- `AstryxNetwork`: for the network path, a small gap (OQ1). Cookies per + runtime and requests with no identity belong with data and security (OQ2). +- `AstryxBack`: React Native's activity takes every back press, so Android's + back-to-home animation never plays at the root without this gate. +- `AstryxLaunch`: the library ends Android's launch hold at its first content + with no app code, and the router reads the launch link synchronously. +- `AstryxFilePicker`: a small gap. One call over photos and files with the + result vocabulary (OQ1). +- `AstryxStorage`: the namespace belongs to the calling runtime, so a Preview + project never reads the app's data (OQ1 for the rest). +- `AstryxCrypto`: no capability gap. Synchronous secure bytes with no + non-secure fallback, for the package's own code and its crypto installer + (OQ1). ## Who uses it | Native piece | Kind | Astryx components that use it | What a person sees | | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxAppearance` | native module (Turbo Native Module) | No Astryx component; app API only (`.` entry). The theme follows its effect through React Native's colour scheme (OQ3). | The app opens in the saved light or dark appearance, with no flash of the system's. | +| `AstryxAppearance` | native module (Turbo Native Module) | No Astryx component; app API (`.` entry). The theme follows its effect through React Native's colour scheme. | The app opens in the saved light or dark appearance, with no flash of the system's. | | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | | `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | | `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | | `AstryxPlatformInfo` | native module (Turbo Native Module) | Its revision and feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), the zoom pager gesture, and `useComponentRevision`; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | -| `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) and the audio recorder (`./microphone` entry) read it; app API `useCameraPermission` (OQ3) | The system prompt appears only when the app asks, never when a view mounts. | -| `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component calls the module; app API (`./network` entry: `useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2, OQ3) | An offline banner or a sign-out that the app draws. | -| `AstryxBack` | native module (Turbo Native Module) | Through the library's back registry: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | +| `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) reads it; app API `useCameraPermission` | The system prompt appears only when the app asks, never when a view mounts. | +| `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component calls the module; app API (`./network` entry: `useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2) | An offline banner or a sign-out that the app draws. | +| `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | | `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | | `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | -| `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the update check's "Not now" (`./updates` entry); app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | -| `AstryxCrypto` | native module (Turbo Native Module) | No Astryx component; the public crypto installer (`./network` entry) and app API `AstryxCrypto` (OQ3) | Nothing directly: identifiers and sign-in nonces an app makes come from the system's secure generator. | +| `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the app update check's "Not now"; app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | +| `AstryxCrypto` | native module (Turbo Native Module) | No Astryx component; the public crypto installer (`./network` entry) and app API `AstryxCrypto` | Nothing directly: identifiers and sign-in nonces an app makes come from the system's secure generator. | ## Non-goals @@ -125,7 +136,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxAppearance` | native module (Turbo Native Module) | `getConstants` (`initialOverride`), `setOverride`, `getRunOverride` | iOS, Android | | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `getConstants` (`initialSettings`), `getSettings`, `onSettingsChange` (event) | iOS | | `AstryxHaptics` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `play`, `prepare` | iOS, Android | - | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `setString`, `detectPatterns` | iOS, Android | + | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `detectPatterns` | iOS, Android | | `AstryxPlatformInfo` | native module (Turbo Native Module) | `getConstants` (`app`, `capabilities`, `components`, `contractFeatures`, `launch`), `getInfo`, `getMemory`, `getBundleSize` | iOS, Android | | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | | `AstryxNetwork` | native module (Turbo Native Module) | `getConstants`, `getState`, `onNetworkChange` (event), `getCookies`, `listCookies`, `setCookie`, `removeCookie`, `clearCookies`, `getDomainInfo`, `redirectModes`, `fetchUntrusted` | iOS, Android | @@ -136,8 +147,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | - **FR2 — Constants are synchronous; everything else is a result.** - - What the system knows at launch is a constant that the wrapper reads once - per module and keeps: the saved appearance and the run's override, the + - What the system knows at launch is a launch value, read once and then + answered synchronously: the saved appearance and the run's override, the accessibility snapshot, the app's version, build, identifier and install time, the linked capabilities, the component revisions, the named contract features, and the process start. Synchronous members (`isAvailable()`, @@ -178,12 +189,11 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, the listener with each real change, never with the current value, and return the unsubscribe function. A native event that repeats an unchanged value is not delivered. - - One process-wide store per module listens to the native event while at - least one subscriber exists. After the last unsubscribe it removes the - native subscription, and the next read starts again from the constants. - - On its first subscriber, the accessibility store reads `getSettings` once - to resync. An event that arrives before that answer wins, because it is - newer. + - A module follows native changes only while at least one listener is + subscribed. After the last unsubscribe it stops, and the next read starts + again from the launch value. + - On the first subscribe, the accessibility snapshot is read once more. A + change that arrives before that answer wins, because it is newer. - Hooks (`useAccessibilitySettings`, `useNetworkState`, `useCameraPermission`) subscribe on mount, remove the subscription on unmount, and return stable callbacks (`spec:AST-112/FR7`). `useNetworkState` reports `loading`, @@ -257,7 +267,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - **FR7 — `AstryxClipboard` reads and writes plain text.** - `write({text})` replaces the pasteboard's content and answers `ok` once the - text is there. `setString(text)` is its deprecated alias. + text is there. - `getString()` answers `{value}`, with `null` for an empty or non-text pasteboard. A read shows the system's paste notice on iOS 16 and later and Android 12 and later, so the library reads only on the person's action @@ -314,8 +324,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - **FR10 — `AstryxNetwork` reports the network path.** - `getState()` answers `isConnected`, `type` (`wifi`, `cellular`, `ethernet`, `other`, `none`, `unknown`), `isMetered`, and `isConstrained` - (iOS Low Data Mode, Android Data Saver for this app). `connected`, - `expensive` and `constrained` are deprecated aliases. + (iOS Low Data Mode, Android Data Saver for this app). - `isConnected` is true when the device has a default route to the internet: on iOS a satisfied path from the path monitor, on Android a default network with the INTERNET capability. It says nothing about whether @@ -335,16 +344,14 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - **FR11 — `AstryxBack` gives Android's root back press to the system when JavaScript cannot use it.** - - The library's back registry tells the native side whether JavaScript can - consume a back press at the root: a registered consumer (an open - sheet, menu or search field), a `BackHandler` listener, or a navigator that - can go back. The shell activity enables its one back callback only then. + - A back press at the root goes to JavaScript only while something in the + app can consume it: an open sheet, menu or search field, a `BackHandler` + listener, or a navigator that can go back. - With nothing to consume, the system takes the press and plays its back-to-home animation (Android 16 predictive back). - Until the library reports for the first time, and after its runtime stops, back presses go to React Native unchanged. - - The registry sends a value only when it changes. A Preview project's - runtime changes nothing. iOS has no module: back is native there. + - A Preview project's runtime changes nothing. iOS has no module: back is native there. - **FR12 — `AstryxLaunch` hands Android's cold launch to the first content.** - The shell activity keeps the system's launch window (the splash screen on @@ -368,7 +375,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, `files`. It is empty where the module is absent. Camera capture is the `camera` capability's (`./camera` entry), never a source of the core picker, so the core needs no camera permission or usage string. - - `pick({source, isMultiple?, limit?, media?, accept?})` presents one picker + - `pick({source, isMultiple?, limit?, media?, accept?}, events?)` presents one picker over the calling surface and resolves `{ok: true, files}` with at least one file, `cancelled` when the person backs out, or a reason: a source the device does not offer answers `unsupported-source` at once with the @@ -378,8 +385,8 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - iOS: `photos` is `PHPickerViewController` (out of process, so no photo library permission) and `files` is `UIDocumentPickerViewController`. Each picked file is copied into the app's temporary directory and returned as a `file://` URL; the photo - picker closes before it loads and copies, and `events.onLoading` reports - that loading step. + picker closes before it loads and copies, and `events.onLoading()` (no + argument) is called once when that loading step starts. - Android: `photos` is the Photo Picker (the document picker on devices without it) and `files` is the Storage Access Framework; the `content://` URIs the pickers grant are returned as they are. @@ -403,13 +410,13 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - Values are kept across launches: one file per key in Application Support on iOS and in the app's internal files directory on Android. The package sets no size limit; only the device's free space limits a value. - - `clearProjectData(bundleUrl)` is for the app's runtime only: it removes - everything one Preview project stored, in every store that registers a - clearer with the core, and answers the cleared namespace. A project's web + - `clearProjectData(bundleUrl)` is the Preview host's call in the app's + runtime: it removes everything one Preview project stored, in every store + of the package, and answers the cleared namespace. A project's web view data goes through the `web` capability's own clearer where that capability is linked, and `isWebDataCleared` says whether it went. A Preview project's call, or the app's own bundle URL, answers `not-allowed`; a value that is not a URL answers `invalid-url`. - - The router's state persistence uses it as its default store, and the + - The router's state persistence uses it as its default store, and the app update check keeps its "Not now" in the app's namespace. - **FR15 — `AstryxCrypto` gives secure random bytes synchronously.** @@ -436,8 +443,9 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, once; neither waits for a JavaScript round trip per frame. - Native events reach JavaScript on the JavaScript thread, once per real change. - - A module torn down during a reload answers `unavailable` until its runtime - is back; a subscription made before the reload is removed with its store. + - A call made while its module is torn down during a reload answers + `unavailable` where FR2 gives the module that reason, and `error` + otherwise. A subscription made before the reload ends with it. - **FR17 — Accessibility.** - The library's drawn chrome follows the snapshot of FR5: Reduce @@ -452,24 +460,18 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - These modules expose nothing to VoiceOver or TalkBack themselves; they have no view. -- **FR18 — Every contract is at revision 1; later behaviour is a named - feature.** - - Every contract in the group reports revision 1. A behaviour added after - revision 1 is a named feature, `.`, that the binary - lists in `AstryxPlatformInfo`'s `contractFeatures` constant. JavaScript - checks it with `hasContractFeature` before it uses the behaviour. - - The group's named features are `AstryxAppearance.persist-false`, - `AstryxAppearance.run-override` and `AstryxAppearance.launch-link`. The - `contractFeatures` constant is the list itself and adds no behaviour. - - Without a feature, JavaScript keeps the revision-1 behaviour or answers - `unsupported`, never a silently weaker path: `setOverride` with - `persist: false` answers `unsupported` and saves nothing, - `getRunOverride()` answers `null` (such a binary has no run-only override), - and a missing feature is reported once with a development warning. - - Astryx Stage pairs with the package through the library's Stage version - floor: the package names the oldest Astryx Stage that answers every - contract in its set, and an older Astryx Stage refuses the project and - lists the contracts it lacks. +- **FR18 — The group's named features.** + - Every contract in the group is at revision 1 (`spec:AST-112/FR8`). Its + named features are `AstryxAppearance.persist-false`, + `AstryxAppearance.run-override` and `AstryxAppearance.launch-link`, and + `AstryxPlatformInfo`'s `contractFeatures` constant is the list a binary + reports; the list itself adds no behaviour. + - Without a feature: `setOverride` with `persist: false` answers + `unsupported` and saves nothing, `getRunOverride()` answers `null` (such a + binary has no run-only override), and the launch link does nothing. A + missing feature is reported once with a development warning. + - Astryx Stage pairs with the package through the version floor of + `spec:AST-112/FR12`. - **FR19 — Astryx Stage simulates each module.** - `AstryxAppearance`: the saved choice per app, kept across runs and @@ -495,15 +497,14 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, - `AstryxCrypto`: the operating system's secure generator. - `AstryxBack` and `AstryxLaunch` are absent, as on iOS: the library takes its no-module path, every back press goes to React Native, and the first - frame draws with no launch hold (OQ4). + frame draws with no launch hold (OQ3). - **FR20 — Public platform API only, and no web engine in the core.** - The native code of every module in the group uses public platform API only; the group needs no exception. - No core module links WebKit (iOS) or androidx.webkit (Android). Web view data and the web view's cookie store belong to the `web` capability - (`spec:AST-112/FR3`), which registers what the core needs through the - core's registration hooks (`spec:AST-112/FR2`). + (`spec:AST-112/FR3`). - FR20 gap: on iOS the core's project-data clear removes web view data through WebKit, and on Android the core's cookie API reaches the cookie store through androidx.webkit. @@ -543,16 +544,23 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, ## Current-state impact -- This record details `spec:AST-112`: its FR1 (the core's system modules), FR5 - for the crypto installer's module, FR6 and FR7 for each module's results and - probes, FR8 for the revision-1 baseline and named features, FR9 for the - haptic moment mapping, and FR12 for Astryx Stage's simulation. -- It changes `spec:AST-112/FR1` in one place: the `camera` capability gains - camera capture, the camera source of the file picker included (FR13). -- `spec:AST-112/FR1` and FR3 gain one rule: the core links no web engine, and - the `web` capability carries web view data and its cookie store (FR20). -- The rest of the split between core and opt-in capabilities does not change - for this group: every module in it is core. +- Relies on `spec:AST-112` FR3 (amended): the core links in every app, and + every module of this group is core. +- Relies on `spec:AST-112` FR8 (amended): every contract is at revision 1, and + later behaviour is a named feature that the platform info module reports. +- Relies on `spec:AST-112` FR12 (amended): the Astryx Stage version floor. +- Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform + API only. +- Changes `spec:AST-112/FR1`: the core's list gains appearance, accessibility + settings, platform info, the Android back gate and launch hold, the file + picker, and secure random bytes; the `camera` capability gains camera + capture, the camera source of a picker included (FR13). +- Changes `spec:AST-112/FR1` and FR3: the core links no web engine, and the + `web` capability carries web view data and its cookie store (FR20). +- Departs from `spec:AST-112/FR7` ("never a silent no-op") for the calls that + return nothing (FR2); OQ4 asks whether the exception stands. +- Details `spec:AST-112` FR5 (the crypto installer's module), FR6 and FR7 + (each module's results and probes), and FR9 (the haptic moment mapping). ## Verification @@ -568,7 +576,7 @@ Preview policy, and one Astryx Stage simulation (`spec:AST-112/FR2`, | FR8 | Unit tests; Astryx Stage contract checks; Simulator and emulator reads | constants; `get()`; memory and size; Preview runtime | A Preview project reads the host's launch, memory or size, or a constant throws | | FR9 | Unit tests; Simulator and emulator prompts; Astryx Stage contract checks | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | | FR10 | Unit tests; emulator and Simulator network changes; Astryx Stage contract checks | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | -| FR11 | Unit tests of the registry; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | +| FR11 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | | FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports; a Preview runtime | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | | FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks; Astryx Stage contract checks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | | FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs; Astryx Stage contract checks | the app's runtime and a Preview project's; a full disk; a project removed | One namespace reads another's data, a Preview project clears a project, or a cleared project leaves data | @@ -650,11 +658,8 @@ Preview policy and an Astryx Stage simulation. OQ1 keeps the scope open. `AstryxStorage`, `AstryxCrypto` and the network state of `AstryxNetwork` fill little capability gap. Options: keep them as core modules (one dependency set, one result shape, the same answers in Astryx Stage); or - replace their native side with adapters over community libraries - (`expo-haptics`, `expo-clipboard`, `react-native-permissions`, - `expo-document-picker`, `@react-native-async-storage/async-storage`, - `react-native-get-random-values`, `@react-native-community/netinfo`), - keeping the wrappers' API. + replace their native side with adapters over community libraries, keeping + the wrappers' API. - **OQ2 — Do cookies, domain info, redirect modes and `fetchUntrusted` move to the data and security group?** (`human-design`) They are methods of `AstryxNetwork`, no Astryx component calls them, and their rules @@ -663,12 +668,24 @@ Preview policy and an Astryx Stage simulation. OQ1 keeps the scope open. image and media URLs belongs to the same question. Options: a separate module in that group, with `AstryxNetwork` keeping only the path state; or one module whose contract this record shares with that group's record. -- **OQ3 — Do the app-API-only modules stay in this group and the core?** - (`human-design`) No Astryx component calls `AstryxAppearance`, - `AstryxPermissions` (used by the `./camera` and `./microphone` entries), - `AstryxNetwork` or `AstryxCrypto` (used by the crypto installer). Options: keep them in the core with this record; or move - each to the entry that uses it. -- **OQ4 — Does Astryx Stage simulate the Android root back gate and launch +- **OQ3 — Does Astryx Stage simulate the Android root back gate and launch hold?** (`checkable`) Options: keep both absent, as FR19 states; or simulate the back-to-home animation at the root and a launch window held until the first content. +- **OQ4 — Do the calls that return nothing keep doing nothing where they + cannot act?** (`human-api`) `AstryxHaptics.play` and `prepare`, and the + back and launch hints, do nothing where the module is absent or + unsupported, which `spec:AST-112/FR7` forbids as a silent no-op. Options: + `spec:AST-112/FR7` names them as an exception, with `isAvailable()` saying + when they do nothing; or each gains a result that answers why it did not + act. +- **OQ5 — Light and dark: does the platform resolve theme colours natively at + the trait change, or does JavaScript re-resolve the tokens and re-render on + each flip?** (`human-design`) Options: + - Native resolution (iOS dynamic colour providers, Android night-mode + resources): no JavaScript work or re-render per flip, and the first frame + after a flip is already right. Tokens must be dynamic native colours, + which is harder for custom or computed tokens and for web parity. + - Tokens resolved in JavaScript: one token pipeline shared with the web, and + any computed token works. Each flip costs a JavaScript re-resolve and a + re-render. From b471f8d0942a22efd083fa436860fc72bf5a37d4 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:41:36 -0800 Subject: [PATCH 08/32] spec(AST-130): no version() probe; DEC-5 holds until OQ1; OQ5 named in Non-goals --- docs/specs/AST-130-react-native-system-modules/spec.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 989b93b924cd5..3b60f2d028a34 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -108,8 +108,9 @@ small, OQ1 keeps the scope open. - Sharing, opening links and Settings, keep-awake, and orientation lock. None is a core module; each one is an opt-in capability of its own when Astryx provides it. -- The design of the theme's appearance model and its scopes; this record owns - only the native appearance override. +- The design of the theme's appearance model and its scopes. This record owns + the native appearance override, and OQ5 asks how theme colours resolve when + the appearance flips. - Haptic intensities per moment. The theme's haptic tokens own them (`spec:AST-112/FR9`). - Each component's use of these modules beyond what "Who uses it" names; the @@ -152,7 +153,7 @@ small, OQ1 keeps the scope open. accessibility snapshot, the app's version, build, identifier and install time, the linked capabilities, the component revisions, the named contract features, and the process start. Synchronous members (`isAvailable()`, - `version()`, `getOverride()`, `getRunOverride()`, `current()`, `app`, + `getOverride()`, `getRunOverride()`, `current()`, `app`, `capabilities`, `launch`, `componentRevision(name)`) never throw; they answer `null`, `'system'`, or all-false where the module or the constant is absent. @@ -649,7 +650,8 @@ bytes and network state are small wrappers where the ecosystem has good libraries. They stay in the core because the package takes no runtime dependency outside React and React Native (`spec:AST-112/FR2`), and because each needs the result vocabulary, the -Preview policy and an Astryx Stage simulation. OQ1 keeps the scope open. +Preview policy and an Astryx Stage simulation. DEC-5 holds until OQ1 is +answered. ## Open questions From 27f76d9a8934e2c177ee0646f63ff9c4385fe4b7 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:45:24 -0800 Subject: [PATCH 09/32] spec(AST-130): Astryx Stage conforms to these contracts and never defines them --- docs/specs/AST-130-react-native-system-modules/spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 3b60f2d028a34..d743374b679ba 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -43,7 +43,8 @@ links them. Every asynchronous call resolves the result vocabulary of `spec:AST-112/FR6`, every module has the capability shape of `spec:AST-112/FR7`, every interface evolves additively under `spec:AST-112/FR8`, and Astryx Stage answers each module's calls as iOS and -Android do, as the contract developers build against (`spec:AST-112/FR12`). +Android do; it conforms to these contracts and never defines them +(`spec:AST-112/FR12`). ## Why this exists From 45858dcedca6b7b48b57a53b3fd35a2f751078fc Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:50:20 -0800 Subject: [PATCH 10/32] spec(AST-130): Astryx Stage and Preview behaviour moves to AST-139; the record stays neutral --- .../spec.md | 185 ++++++------------ 1 file changed, 64 insertions(+), 121 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index d743374b679ba..94f1fa27bb0ae 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -41,16 +41,15 @@ This record details the system modules of the platform layer that `spec:AST-112` defines. They are core modules (`spec:AST-112/FR1`): every app links them. Every asynchronous call resolves the result vocabulary of `spec:AST-112/FR6`, every module has the capability shape of -`spec:AST-112/FR7`, every interface evolves additively under -`spec:AST-112/FR8`, and Astryx Stage answers each module's calls as iOS and -Android do; it conforms to these contracts and never defines them -(`spec:AST-112/FR12`). +`spec:AST-112/FR7`, and every interface evolves additively under +`spec:AST-112/FR8`. ## Why this exists The package takes no runtime dependency outside React and React Native -(`spec:AST-112/FR2`). Each module exists for one concrete gap; where the gap is -small, OQ1 keeps the scope open. +(`spec:AST-112/FR2`); apps may use third-party libraries, haptics libraries +included, beside these modules without conflict. Each module exists for one +concrete gap; where the gap is small, OQ1 keeps the scope open. - `AstryxAppearance`: the saved light or dark choice is in force from the first frame of every launch. A choice that JavaScript applies arrives a frame late, @@ -61,7 +60,7 @@ small, OQ1 keeps the scope open. - `AstryxHaptics`: a small gap. The theme maps moments to feedback kinds, and Android plays the view feedback its API level has (OQ1). - `AstryxClipboard`: no capability gap. The module gives the result - vocabulary, the Preview policy, and the same answers in Astryx Stage (OQ1). + vocabulary with no extra dependency (OQ1). - `AstryxPlatformInfo`: the binary's own contract facts (component revisions, linked capabilities, named features), which only the binary can report. - `AstryxPermissions`: a small gap. A closed set of permissions tied to the @@ -74,8 +73,8 @@ small, OQ1 keeps the scope open. with no app code, and the router reads the launch link synchronously. - `AstryxFilePicker`: a small gap. One call over photos and files with the result vocabulary (OQ1). -- `AstryxStorage`: the namespace belongs to the calling runtime, so a Preview - project never reads the app's data (OQ1 for the rest). +- `AstryxStorage`: a small gap. One string store with the result vocabulary + and no extra dependency (OQ1). - `AstryxCrypto`: no capability gap. Synchronous secure bytes with no non-secure fallback, for the package's own code and its crypto installer (OQ1). @@ -110,12 +109,14 @@ small, OQ1 keeps the scope open. is a core module; each one is an opt-in capability of its own when Astryx provides it. - The design of the theme's appearance model and its scopes. This record owns - the native appearance override, and OQ5 asks how theme colours resolve when + the native appearance override, and OQ4 asks how theme colours resolve when the appearance flips. - Haptic intensities per moment. The theme's haptic tokens own them (`spec:AST-112/FR9`). - Each component's use of these modules beyond what "Who uses it" names; the component's own record owns it. +- Astryx Stage and the Astryx app's Preview are specified in `spec:AST-139`; + they conform to this record's contracts. - Equivalent internal implementations remain valid when they satisfy this contract. - Internal modules, files, function names, algorithms, data structures, storage @@ -144,7 +145,7 @@ small, OQ1 keeps the scope open. | `AstryxNetwork` | native module (Turbo Native Module) | `getConstants`, `getState`, `onNetworkChange` (event), `getCookies`, `listCookies`, `setCookie`, `removeCookie`, `clearCookies`, `getDomainInfo`, `redirectModes`, `fetchUntrusted` | iOS, Android | | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | | `AstryxFilePicker` | native module (Turbo Native Module) | `getConstants`, `getSources`, `pick` | iOS, Android | - | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo`, `clearProjectData` | iOS, Android | + | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo` | iOS, Android | | `AstryxCrypto` | native module (Turbo Native Module) | `getConstants`, `randomBytes` (synchronous) | iOS, Android | | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | @@ -170,7 +171,7 @@ small, OQ1 keeps the scope open. | `AstryxPlatformInfo` | `unavailable` (the system did not answer a measure) | | `AstryxPermissions` | `unknown-permission`, `busy`, `no-activity` (Android), `not-declared` | | `AstryxFilePicker` | `unsupported-source`, `no-window`, `busy`; `cancelled` when the person backs out | - | `AstryxStorage` | `invalid-key`, `invalid-value`, `invalid-json`, `no-space`, `io`, `no-namespace`; `invalid-url` for `clearProjectData` | + | `AstryxStorage` | `invalid-key`, `invalid-value`, `invalid-json`, `no-space`, `io`, `no-namespace` | | `AstryxNetwork` | `unavailable`, `invalid-url`, `invalid-host`, `invalid-cookie`; for `fetchUntrusted`: `invalid-request`, `redirect-refused`, `timeout`, `too-large`, `network`, `aborted` | - `AstryxCrypto` is the one synchronous exception: its methods return @@ -178,12 +179,6 @@ small, OQ1 keeps the scope open. - `AstryxHaptics.play` and `prepare` return nothing: they play or do nothing, and `isAvailable()` says which. `AstryxBack` and `AstryxLaunch` calls return nothing either; they are hints that the native side may ignore. - - In a Preview project's runtime, a call that acts for the host app - (`setOverride`, `fetchUntrusted`, `getMemory`, `getBundleSize`, - `clearProjectData`) answers - `not-allowed`, and a refused clipboard read or write or camera consent - answers `not-allowed` too. `AstryxBack` and `AstryxLaunch` change nothing - there. - **FR3 — Change events start with the first subscriber and stop after the last.** @@ -229,9 +224,6 @@ small, OQ1 keeps the scope open. parameter is `light`, `dark` or `system` applies that appearance natively as a run-only override: before the first frame on a cold launch, and on arrival on a warm one (feature `launch-link`). Nothing is saved. - - In a Preview project's runtime, `getOverride()` answers `'system'`, - `getRunOverride()` answers `null`, and `setOverride` answers `not-allowed`: - a project cannot change the appearance of the app that hosts it. - **FR5 — `AstryxAccessibilitySettings` publishes one settings snapshot.** - The snapshot has seven booleans. Every answer carries all seven, and a key @@ -290,8 +282,7 @@ small, OQ1 keeps the scope open. features, FR18), and `launch` (`processStartedAt` in epoch milliseconds, and `isPrewarmed`, always false on Android). `packageVersion` is the JavaScript package's version. - - `get()` answers the platform, the calling runtime's namespace (`app` or a - Preview project's), the components, the per-platform feature rows + - `get()` answers the platform, the calling runtime's namespace, the components, the per-platform feature rows (`.`, with `isSupported` and a note), and the self-checks of the platform internals the package relies on (`compat`). `supports(name)` reads a feature row from the last answer and is `null` @@ -300,9 +291,6 @@ small, OQ1 keeps the scope open. platform counts it (iOS `phys_footprint`, Android total PSS); the iOS and Android numbers do not compare. `bundleSize()` answers the installed app's size on disk, read off the main thread. - - A Preview project's runtime gets no `launch`, an empty `installedAt`, and - `not-allowed` from `memory()` and `bundleSize()`: a project cannot read - facts about the app that hosts it. - **FR9 — `AstryxPermissions` reads and asks explicitly.** - `get(name)` never prompts. `request(name)` shows the system prompt only for @@ -353,7 +341,7 @@ small, OQ1 keeps the scope open. back-to-home animation (Android 16 predictive back). - Until the library reports for the first time, and after its runtime stops, back presses go to React Native unchanged. - - A Preview project's runtime changes nothing. iOS has no module: back is native there. + - iOS has no module: back is native there. - **FR12 — `AstryxLaunch` hands Android's cold launch to the first content.** - The shell activity keeps the system's launch window (the splash screen on @@ -368,7 +356,7 @@ small, OQ1 keeps the scope open. `Linking.getInitialURL()` answers), or `null` when the app launched without one. The router builds its first state from it, so a cold deep link draws its own screen first. Where the platform cannot answer - synchronously (iOS, an absent module, a Preview project's runtime), the + synchronously (iOS, an absent module), the router reads `Linking.getInitialURL()`. - iOS has no module: its launch screen stays until the first frame. @@ -406,18 +394,10 @@ small, OQ1 keeps the scope open. answers the namespace, the key count, the bytes the store takes on disk, and the free space (`null` when the platform does not say). - Every call works in the calling runtime's namespace, decided natively and - never by JavaScript: `app` for the app's own runtime, and a namespace of - its own for each Preview project, so a project never reads the app's data - or another project's. + never by JavaScript; `info()` names it. - Values are kept across launches: one file per key in Application Support on iOS and in the app's internal files directory on Android. The package sets no size limit; only the device's free space limits a value. - - `clearProjectData(bundleUrl)` is the Preview host's call in the app's - runtime: it removes everything one Preview project stored, in every store - of the package, and answers the cleared namespace. A project's web - view data goes through the `web` capability's own clearer where that - capability is linked, and `isWebDataCleared` says whether it went. A Preview project's call, or the app's own bundle URL, - answers `not-allowed`; a value that is not a URL answers `invalid-url`. - The router's state persistence uses it as its default store, and the app update check keeps its "Not now" in the app's namespace. @@ -472,64 +452,34 @@ small, OQ1 keeps the scope open. `unsupported` and saves nothing, `getRunOverride()` answers `null` (such a binary has no run-only override), and the launch link does nothing. A missing feature is reported once with a development warning. - - Astryx Stage pairs with the package through the version floor of - `spec:AST-112/FR12`. - -- **FR19 — Astryx Stage simulates each module.** - - `AstryxAppearance`: the saved choice per app, kept across runs and - applied before the first frame; a run-only override, which a new run - forgets. - - `AstryxAccessibilitySettings`: the run's device settings, set by - arguments and changed live, delivered as the same snapshot and event. - - `AstryxHaptics`: present and supported; each `play` shows in Astryx - Stage's trace with the kind or the Android constant, and plays nothing. - - `AstryxClipboard`: an in-memory string; `detectPatterns` classifies it - without handing it back; Preview reads ask as on a device. - - `AstryxPlatformInfo`: Astryx Stage's own app identity, its component - revisions, linked capabilities, feature rows, launch, memory and size. - - `AstryxPermissions`: `undetermined` until `request`, which draws a prompt; - an argument starts it granted; `hasHardware` is false, as on the - Simulator. - - `AstryxNetwork`: a default route exists and the path is never metered; - cookies in a jar per namespace; `fetchUntrusted` from a client of its own - with no identity and no redirect following. - - `AstryxFilePicker`: the photo and document pickers. - - `AstryxStorage`: one store per namespace, kept across runs and counted - the same way as on a device; a headless run starts empty. - - `AstryxCrypto`: the operating system's secure generator. - - `AstryxBack` and `AstryxLaunch` are absent, as on iOS: the library takes - its no-module path, every back press goes to React Native, and the first - frame draws with no launch hold (OQ3). - -- **FR20 — Public platform API only, and no web engine in the core.** + +- **FR19 — Public platform API only, and no web engine in the core.** - The native code of every module in the group uses public platform API only; the group needs no exception. - No core module links WebKit (iOS) or androidx.webkit (Android). Web view data and the web view's cookie store belong to the `web` capability (`spec:AST-112/FR3`). - - FR20 gap: on iOS the core's project-data clear removes web view data - through WebKit, and on Android the core's cookie API reaches the cookie + - FR19 gap: on iOS the core's storage module links WebKit to remove web + view data, and on Android the core's cookie API reaches the cookie store through androidx.webkit. ### Platform support -| Contract | iOS | Android | Astryx Stage | -| ----------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | Saved choice and run-only override (FR19) | -| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | Device settings from the run (FR19) | -| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | Trace entries; no feedback | -| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | In-memory string | -| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | Astryx Stage's own identity, revisions and feature rows | -| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | Drawn prompt; `undetermined` until asked | -| `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the runtime's cookie store; a separate HTTP client | Default route; per-namespace jar; its own client | -| `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | Photos and files pickers | -| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | One store per namespace, kept across runs | -| `AstryxCrypto` | `SecRandomCopyBytes` | `java.security.SecureRandom` | The operating system's generator | -| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | Absent (FR19) | -| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | Absent (FR19) | - -- FR19 gap: Astryx Stage reports no `contractFeatures` list, and its - `AstryxAppearance` has no `getRunOverride` and no launch link. +| Contract | iOS | Android | +| ----------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | +| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | +| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | +| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | +| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | +| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | +| `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the runtime's cookie store; a separate HTTP client | +| `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | +| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | +| `AstryxCrypto` | `SecRandomCopyBytes` | `java.security.SecureRandom` | +| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | +| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | + - Supported feature/engine floor: the platform floor of `spec:AST-112` (iOS at React Native's minimum, Android API level 24, the New Architecture only). Settings that newer OS versions add (Reduce Bright Effects, Show @@ -541,7 +491,7 @@ small, OQ1 keeps the scope open. platform-only module is absent on the other platform, and the library takes the path FR5, FR11 and FR12 name. - Browser evidence: none. Claims are proven on the iOS Simulator, the Android - emulator, devices, and Astryx Stage (`spec:AST-112/FR15`); haptic feel needs + emulator, and devices (`spec:AST-112/FR15`); haptic feel needs a real device. ## Current-state impact @@ -550,7 +500,6 @@ small, OQ1 keeps the scope open. every module of this group is core. - Relies on `spec:AST-112` FR8 (amended): every contract is at revision 1, and later behaviour is a named feature that the platform info module reports. -- Relies on `spec:AST-112` FR12 (amended): the Astryx Stage version floor. - Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform API only. - Changes `spec:AST-112/FR1`: the core's list gains appearance, accessibility @@ -558,36 +507,35 @@ small, OQ1 keeps the scope open. picker, and secure random bytes; the `camera` capability gains camera capture, the camera source of a picker included (FR13). - Changes `spec:AST-112/FR1` and FR3: the core links no web engine, and the - `web` capability carries web view data and its cookie store (FR20). + `web` capability carries web view data and its cookie store (FR19). - Departs from `spec:AST-112/FR7` ("never a silent no-op") for the calls that - return nothing (FR2); OQ4 asks whether the exception stands. + return nothing (FR2); OQ3 asks whether the exception stands. - Details `spec:AST-112` FR5 (the crypto installer's module), FR6 and FR7 (each module's results and probes), and FR9 (the haptic moment mapping). ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | -| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw; a Preview runtime | A synchronous member throws, a call rejects, or answers a reason outside its set | -| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | -| FR4 | Unit tests; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link | saved `dark` under a light system; `persist: false`; launch link cold and warm; Preview runtime | The first frame shows the system's style, a run-only change survives a relaunch, or a Preview project changes the host's appearance | -| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting; Astryx Stage contract checks | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | -| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | -| FR7 | Unit tests; Simulator and emulator copy and paste; Astryx Stage contract checks | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | -| FR8 | Unit tests; Astryx Stage contract checks; Simulator and emulator reads | constants; `get()`; memory and size; Preview runtime | A Preview project reads the host's launch, memory or size, or a constant throws | -| FR9 | Unit tests; Simulator and emulator prompts; Astryx Stage contract checks | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | -| FR10 | Unit tests; emulator and Simulator network changes; Astryx Stage contract checks | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | -| FR11 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | -| FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports; a Preview runtime | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | -| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks; Astryx Stage contract checks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | -| FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs; Astryx Stage contract checks | the app's runtime and a Preview project's; a full disk; a project removed | One namespace reads another's data, a Preview project clears a project, or a cleared project leaves data | -| FR15 | Unit tests of the bytes, errors and installer; Simulator and emulator reads | 0 and 65,536 bytes; above the ceiling; module absent; an existing `crypto` | A non-secure fill, a call that does not throw Web Crypto's error, or an installer that replaces an existing function | -| FR16 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | -| FR17 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | -| FR18 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent; an older Astryx Stage | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | -| FR19 | Astryx Stage contract checks against the Simulator and emulator results | each module's checks | An Astryx Stage answer differs from iOS and Android and its documentation does not name it | -| FR20 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | +| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw | A synchronous member throws, a call rejects, or answers a reason outside its set | +| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | +| FR4 | Unit tests; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link | saved `dark` under a light system; `persist: false`; launch link cold and warm | The first frame shows the system's style, a run-only change survives a relaunch | +| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | +| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | +| FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | +| FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | +| FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | +| FR10 | Unit tests; emulator and Simulator network changes | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | +| FR11 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | +| FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | +| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | +| FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | +| FR15 | Unit tests of the bytes, errors and installer; Simulator and emulator reads | 0 and 65,536 bytes; above the ceiling; module absent; an existing `crypto` | A non-secure fill, a call that does not throw Web Crypto's error, or an installer that replaces an existing function | +| FR16 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | +| FR17 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | +| FR18 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | +| FR19 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | ## Decision log @@ -650,8 +598,7 @@ Haptics, the clipboard, permissions, the file pickers, storage, secure random bytes and network state are small wrappers where the ecosystem has good libraries. They stay in the core because the package takes no runtime dependency outside React and React Native -(`spec:AST-112/FR2`), and because each needs the result vocabulary, the -Preview policy and an Astryx Stage simulation. DEC-5 holds until OQ1 is +(`spec:AST-112/FR2`), and because each needs the result vocabulary. DEC-5 holds until OQ1 is answered. ## Open questions @@ -660,7 +607,7 @@ answered. `AstryxHaptics`, `AstryxClipboard`, `AstryxPermissions`, `AstryxFilePicker`, `AstryxStorage`, `AstryxCrypto` and the network state of `AstryxNetwork` fill little capability gap. Options: keep them as - core modules (one dependency set, one result shape, the same answers in Astryx Stage); or + core modules (one dependency set, one result shape); or replace their native side with adapters over community libraries, keeping the wrappers' API. - **OQ2 — Do cookies, domain info, redirect modes and `fetchUntrusted` move to @@ -671,18 +618,14 @@ answered. image and media URLs belongs to the same question. Options: a separate module in that group, with `AstryxNetwork` keeping only the path state; or one module whose contract this record shares with that group's record. -- **OQ3 — Does Astryx Stage simulate the Android root back gate and launch - hold?** (`checkable`) Options: keep both absent, as FR19 states; or simulate - the back-to-home animation at the root and a launch window held until the - first content. -- **OQ4 — Do the calls that return nothing keep doing nothing where they +- **OQ3 — Do the calls that return nothing keep doing nothing where they cannot act?** (`human-api`) `AstryxHaptics.play` and `prepare`, and the back and launch hints, do nothing where the module is absent or unsupported, which `spec:AST-112/FR7` forbids as a silent no-op. Options: `spec:AST-112/FR7` names them as an exception, with `isAvailable()` saying when they do nothing; or each gains a result that answers why it did not act. -- **OQ5 — Light and dark: does the platform resolve theme colours natively at +- **OQ4 — Light and dark: does the platform resolve theme colours natively at the trait change, or does JavaScript re-resolve the tokens and re-render on each flip?** (`human-design`) Options: - Native resolution (iOS dynamic colour providers, Android night-mode From 6be1f46ef2c26caf7734214f5a128627b1751a8b Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:53:43 -0800 Subject: [PATCH 11/32] spec(AST-130): AstryxNetwork and AstryxCrypto are part of the optional add-on package, not core --- .../spec.md | 49 +++++++++++-------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 94f1fa27bb0ae..470e8aa58e1e6 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -38,8 +38,9 @@ and launch screen where the platform plays them. A file field opens the system's own picker, and the app's navigation state survives a cold start. This record details the system modules of the platform layer that -`spec:AST-112` defines. They are core modules (`spec:AST-112/FR1`): every app -links them. Every asynchronous call resolves the result vocabulary of +`spec:AST-112` defines. Ten of them are core modules (`spec:AST-112/FR1`): +every app links them. `AstryxNetwork` and `AstryxCrypto` are part of the +optional add-on package, not core. Every asynchronous call resolves the result vocabulary of `spec:AST-112/FR6`, every module has the capability shape of `spec:AST-112/FR7`, and every interface evolves additively under `spec:AST-112/FR8`. @@ -65,7 +66,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. linked capabilities, named features), which only the binary can report. - `AstryxPermissions`: a small gap. A closed set of permissions tied to the capabilities, with `not-declared` where the system would end the app (OQ1). -- `AstryxNetwork`: for the network path, a small gap (OQ1). Cookies per +- `AstryxNetwork` (optional add-on package): for the network path, a small + gap (OQ1). Cookies per runtime and requests with no identity belong with data and security (OQ2). - `AstryxBack`: React Native's activity takes every back press, so Android's back-to-home animation never plays at the root without this gate. @@ -75,9 +77,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. result vocabulary (OQ1). - `AstryxStorage`: a small gap. One string store with the result vocabulary and no extra dependency (OQ1). -- `AstryxCrypto`: no capability gap. Synchronous secure bytes with no - non-secure fallback, for the package's own code and its crypto installer - (OQ1). +- `AstryxCrypto` (optional add-on package): no capability gap. Synchronous + secure bytes with no non-secure fallback, for its crypto installer (OQ1). ## Who uses it @@ -89,12 +90,12 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | | `AstryxPlatformInfo` | native module (Turbo Native Module) | Its revision and feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), the zoom pager gesture, and `useComponentRevision`; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | | `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) reads it; app API `useCameraPermission` | The system prompt appears only when the app asks, never when a view mounts. | -| `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component calls the module; app API (`./network` entry: `useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2) | An offline banner or a sign-out that the app draws. | +| `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component; part of the optional add-on package, not core. App API (`useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2) | An offline banner or a sign-out that the app draws. | | `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | | `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | | `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | | `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the app update check's "Not now"; app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | -| `AstryxCrypto` | native module (Turbo Native Module) | No Astryx component; the public crypto installer (`./network` entry) and app API `AstryxCrypto` | Nothing directly: identifiers and sign-in nonces an app makes come from the system's secure generator. | +| `AstryxCrypto` | native module (Turbo Native Module) | No Astryx component; part of the optional add-on package, not core. Its crypto installer and app API `AstryxCrypto` | Nothing directly: identifiers and sign-in nonces an app makes come from the system's secure generator. | ## Non-goals @@ -128,8 +129,11 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. ## Requirements -- **FR1 — The group is twelve core native modules.** Every app links them - (`spec:AST-112/FR1`). Each module is read with `TurboModuleRegistry.get`, +- **FR1 — The group is twelve native modules: ten core, two in the optional + add-on package.** Every app links the ten core modules + (`spec:AST-112/FR1`). `AstryxNetwork` and `AstryxCrypto` are part of the + optional add-on package, not core: an app links them only when it installs + that package, and without it their wrappers answer as an absent module. Each module is read with `TurboModuleRegistry.get`, only by its own wrapper (`spec:AST-112/FR8`), and its wrapper answers `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` have no public object: the library is their one caller. @@ -312,6 +316,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. run learns of a refusal), and iOS answers `no-module`. - **FR10 — `AstryxNetwork` reports the network path.** + - `AstryxNetwork` is part of the optional add-on package, not core. - `getState()` answers `isConnected`, `type` (`wifi`, `cellular`, `ethernet`, `other`, `none`, `unknown`), `isMetered`, and `isConstrained` (iOS Low Data Mode, Android Data Saver for this app). @@ -321,7 +326,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. a server answers: it is true behind a captive portal, where requests still fail. - On Android the reads need `ACCESS_NETWORK_STATE`, which the configuration - plugin writes for the core; without it, `getState()` answers `unavailable` + plugin writes when the add-on package is installed; without it, `getState()` answers `unavailable` and names the permission. - The module also carries the calling runtime's cookie jar (`AstryxCookies`: `get`, `set`, `remove`, `clear`; an `httpOnly` cookie's value never reaches @@ -402,6 +407,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. update check keeps its "Not now" in the app's namespace. - **FR15 — `AstryxCrypto` gives secure random bytes synchronously.** + - `AstryxCrypto` is part of the optional add-on package, not core. - `randomBytes(byteLength)`, `getRandomValues(array)` and `randomUUID()` take their bytes from the system's secure generator (iOS `SecRandomCopyBytes`, Android `java.security.SecureRandom`). They are @@ -411,7 +417,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. (`QuotaExceededError`), integer typed arrays only (`TypeMismatchError`). Where the module is absent they throw `NotSupportedError`; there is never a non-secure fallback. - - The crypto installer of `spec:AST-112/FR5` (`./network` entry) installs + - The crypto installer of `spec:AST-112/FR5` installs `crypto.getRandomValues` and `crypto.randomUUID` from this module where the runtime lacks them, and installs nothing and reports `no-module` without it. @@ -460,8 +466,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. data and the web view's cookie store belong to the `web` capability (`spec:AST-112/FR3`). - FR19 gap: on iOS the core's storage module links WebKit to remove web - view data, and on Android the core's cookie API reaches the cookie - store through androidx.webkit. + view data. ### Platform support @@ -489,22 +494,24 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. synchronous members answer their empty values (FR2); a missing named feature answers `unsupported` or keeps the revision-1 behaviour (FR18); a platform-only module is absent on the other platform, and the library takes - the path FR5, FR11 and FR12 name. + the path FR5, FR11 and FR12 name; an app without the optional add-on + package has neither `AstryxNetwork` nor `AstryxCrypto` (FR1, FR15). - Browser evidence: none. Claims are proven on the iOS Simulator, the Android emulator, and devices (`spec:AST-112/FR15`); haptic feel needs a real device. ## Current-state impact -- Relies on `spec:AST-112` FR3 (amended): the core links in every app, and - every module of this group is core. +- Relies on `spec:AST-112` FR3 (amended): the core links in every app; ten + modules of this group are core. - Relies on `spec:AST-112` FR8 (amended): every contract is at revision 1, and later behaviour is a named feature that the platform info module reports. - Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform API only. - Changes `spec:AST-112/FR1`: the core's list gains appearance, accessibility - settings, platform info, the Android back gate and launch hold, the file - picker, and secure random bytes; the `camera` capability gains camera + settings, platform info, the Android back gate and launch hold, and the + file picker; network and cookies leave the core for the optional add-on + package, with secure random bytes; the `camera` capability gains camera capture, the camera source of a picker included (FR13). - Changes `spec:AST-112/FR1` and FR3: the core links no web engine, and the `web` capability carries web view data and its cookie store (FR19). @@ -596,7 +603,7 @@ missed call holds the splash. Haptics, the clipboard, permissions, the file pickers, storage, secure random bytes and network state are small wrappers -where the ecosystem has good libraries. They stay in the core because the +where the ecosystem has good libraries. They stay Astryx modules because the package takes no runtime dependency outside React and React Native (`spec:AST-112/FR2`), and because each needs the result vocabulary. DEC-5 holds until OQ1 is answered. @@ -607,7 +614,7 @@ answered. `AstryxHaptics`, `AstryxClipboard`, `AstryxPermissions`, `AstryxFilePicker`, `AstryxStorage`, `AstryxCrypto` and the network state of `AstryxNetwork` fill little capability gap. Options: keep them as - core modules (one dependency set, one result shape); or + Astryx modules (one dependency set, one result shape); or replace their native side with adapters over community libraries, keeping the wrappers' API. - **OQ2 — Do cookies, domain info, redirect modes and `fetchUntrusted` move to From 2c6b83b5d7d01d3623cf107ec40939649a6eaaa5 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:05:13 -0800 Subject: [PATCH 12/32] spec(AST-130): the shared platform rules cite AST-140 --- .../spec.md | 29 ++++++++++--------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 470e8aa58e1e6..923910a926538 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -40,16 +40,17 @@ system's own picker, and the app's navigation state survives a cold start. This record details the system modules of the platform layer that `spec:AST-112` defines. Ten of them are core modules (`spec:AST-112/FR1`): every app links them. `AstryxNetwork` and `AstryxCrypto` are part of the -optional add-on package, not core. Every asynchronous call resolves the result vocabulary of -`spec:AST-112/FR6`, every module has the capability shape of -`spec:AST-112/FR7`, and every interface evolves additively under -`spec:AST-112/FR8`. +optional add-on package, not core. The shared platform rules are +`spec:AST-140`'s: every asynchronous call resolves the result vocabulary of +`spec:AST-140/FR3`, every interface evolves additively under +`spec:AST-140/FR5`, and every module has the capability shape of +`spec:AST-112/FR7`. ## Why this exists The package takes no runtime dependency outside React and React Native (`spec:AST-112/FR2`); apps may use third-party libraries, haptics libraries -included, beside these modules without conflict. Each module exists for one +included, beside these modules without conflict (`spec:AST-140/FR9`). Each module exists for one concrete gap; where the gap is small, OQ1 keeps the scope open. - `AstryxAppearance`: the saved light or dark choice is in force from the first @@ -134,7 +135,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. (`spec:AST-112/FR1`). `AstryxNetwork` and `AstryxCrypto` are part of the optional add-on package, not core: an app links them only when it installs that package, and without it their wrappers answer as an absent module. Each module is read with `TurboModuleRegistry.get`, - only by its own wrapper (`spec:AST-112/FR8`), and its wrapper answers + only by its own wrapper (`spec:AST-140/FR1`, FR2), and its wrapper answers `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` have no public object: the library is their one caller. @@ -164,7 +165,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. answer `null`, `'system'`, or all-false where the module or the constant is absent. - Every asynchronous call resolves `AstryxResult` and never rejects - (`spec:AST-112/FR6`). Each module adds only these reasons to the common + (`spec:AST-140/FR3`). Each module adds only these reasons to the common ones: | Module | Module reasons | @@ -422,7 +423,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. the runtime lacks them, and installs nothing and reports `no-module` without it. -- **FR16 — Threads and lifecycle.** +- **FR16 — Threads and lifecycle.** The threading rules of + `spec:AST-140/FR6` apply; for this group: - Constants are read on the JavaScript thread once per module, at the first call that needs them. Asynchronous calls do their native work off the JavaScript thread, and a measure that walks files (`bundleSize()`) runs off @@ -449,7 +451,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. no view. - **FR18 — The group's named features.** - - Every contract in the group is at revision 1 (`spec:AST-112/FR8`). Its + - Every contract in the group is at revision 1 (`spec:AST-140/FR5`). Its named features are `AstryxAppearance.persist-false`, `AstryxAppearance.run-override` and `AstryxAppearance.launch-link`, and `AstryxPlatformInfo`'s `contractFeatures` constant is the list a binary @@ -504,8 +506,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - Relies on `spec:AST-112` FR3 (amended): the core links in every app; ten modules of this group are core. -- Relies on `spec:AST-112` FR8 (amended): every contract is at revision 1, and - later behaviour is a named feature that the platform info module reports. +- Relies on `spec:AST-140` FR5: every contract is at revision 1, and later + behaviour is a named feature that the platform info module reports. - Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform API only. - Changes `spec:AST-112/FR1`: the core's list gains appearance, accessibility @@ -517,8 +519,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. `web` capability carries web view data and its cookie store (FR19). - Departs from `spec:AST-112/FR7` ("never a silent no-op") for the calls that return nothing (FR2); OQ3 asks whether the exception stands. -- Details `spec:AST-112` FR5 (the crypto installer's module), FR6 and FR7 - (each module's results and probes), and FR9 (the haptic moment mapping). +- Details `spec:AST-112` FR5 (the crypto installer's module), FR7 (each + module's probes) and FR9 (the haptic moment mapping), and `spec:AST-140/FR3` + (each module's results). ## Verification From 00dc0c37c83e0ef0f3f9a53fb0cc34df11d32dcc Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:19:43 -0800 Subject: [PATCH 13/32] spec(AST-130): Astryx Stage and Preview are separate products (AST-139, AST-141) --- docs/specs/AST-130-react-native-system-modules/spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 923910a926538..6341628fd4e0f 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -117,8 +117,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. (`spec:AST-112/FR9`). - Each component's use of these modules beyond what "Who uses it" names; the component's own record owns it. -- 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. - Equivalent internal implementations remain valid when they satisfy this contract. - Internal modules, files, function names, algorithms, data structures, storage From d9a2eccd7749c0c69fd13051f693ddd76393ccc1 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:25:00 -0800 Subject: [PATCH 14/32] spec(AST-130): ten core modules; the core owns the app cache location --- .../spec.md | 247 +++++++----------- 1 file changed, 93 insertions(+), 154 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 6341628fd4e0f..160d4a28461d6 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -25,10 +25,9 @@ affects_consumer_docs: [] An app built with `@astryxdesign/react-native` reads and changes the system around it through a small set of native modules with no view: the app's light or dark choice, the system's display and accessibility settings, haptic -feedback, the pasteboard, what the binary contains, runtime permissions, the -network path, Android's back press at the root, Android's cold launch, the -system's file and photo pickers, a string key-value store, and secure random -bytes. +feedback, the pasteboard, what the binary contains, runtime permissions, +Android's back press at the root, Android's cold launch, the system's file and +photo pickers, a string key-value store, and the app's cache location. A developer calls one typed object per module, gets an answer on the first render where the system already knows it, and handles every failure as data. A person sees the app start in the right appearance, feels feedback that @@ -38,9 +37,8 @@ and launch screen where the platform plays them. A file field opens the system's own picker, and the app's navigation state survives a cold start. This record details the system modules of the platform layer that -`spec:AST-112` defines. Ten of them are core modules (`spec:AST-112/FR1`): -every app links them. `AstryxNetwork` and `AstryxCrypto` are part of the -optional add-on package, not core. The shared platform rules are +`spec:AST-112` defines. They are core modules (`spec:AST-112/FR1`): every app +links them. The shared platform rules are `spec:AST-140`'s: every asynchronous call resolves the result vocabulary of `spec:AST-140/FR3`, every interface evolves additively under `spec:AST-140/FR5`, and every module has the capability shape of @@ -67,9 +65,6 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. linked capabilities, named features), which only the binary can report. - `AstryxPermissions`: a small gap. A closed set of permissions tied to the capabilities, with `not-declared` where the system would end the app (OQ1). -- `AstryxNetwork` (optional add-on package): for the network path, a small - gap (OQ1). Cookies per - runtime and requests with no identity belong with data and security (OQ2). - `AstryxBack`: React Native's activity takes every back press, so Android's back-to-home animation never plays at the root without this gate. - `AstryxLaunch`: the library ends Android's launch hold at its first content @@ -78,8 +73,6 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. result vocabulary (OQ1). - `AstryxStorage`: a small gap. One string store with the result vocabulary and no extra dependency (OQ1). -- `AstryxCrypto` (optional add-on package): no capability gap. Synchronous - secure bytes with no non-secure fallback, for its crypto installer (OQ1). ## Who uses it @@ -91,18 +84,16 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | | `AstryxPlatformInfo` | native module (Turbo Native Module) | Its revision and feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), the zoom pager gesture, and `useComponentRevision`; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | | `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) reads it; app API `useCameraPermission` | The system prompt appears only when the app asks, never when a view mounts. | -| `AstryxNetwork` | native module (Turbo Native Module) | No Astryx component; part of the optional add-on package, not core. App API (`useNetworkState`, `AstryxCookies`, `fetchUntrusted`) (OQ2) | An offline banner or a sign-out that the app draws. | | `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | | `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | | `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | | `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the app update check's "Not now"; app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | -| `AstryxCrypto` | native module (Turbo Native Module) | No Astryx component; part of the optional add-on package, not core. Its crypto installer and app API `AstryxCrypto` | Nothing directly: identifiers and sign-in nonces an app makes come from the system's secure generator. | ## Non-goals - The data and security modules (files, secure storage) and their records. - This record names only the parts of `AstryxNetwork` the library depends on - (OQ2). +- Capabilities that no Astryx component uses. They are outside the core + package. - Client identity, crash reports, daily metrics, the frame recorder, and image markup. Each is part of the platform package and has its own record. - Camera capture. The `camera` capability owns it, the camera source of a @@ -111,7 +102,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. is a core module; each one is an opt-in capability of its own when Astryx provides it. - The design of the theme's appearance model and its scopes. This record owns - the native appearance override, and OQ4 asks how theme colours resolve when + the native appearance override, and OQ3 asks how theme colours resolve when the appearance flips. - Haptic intensities per moment. The theme's haptic tokens own them (`spec:AST-112/FR9`). @@ -130,29 +121,24 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. ## Requirements -- **FR1 — The group is twelve native modules: ten core, two in the optional - add-on package.** Every app links the ten core modules - (`spec:AST-112/FR1`). `AstryxNetwork` and `AstryxCrypto` are part of the - optional add-on package, not core: an app links them only when it installs - that package, and without it their wrappers answer as an absent module. Each module is read with `TurboModuleRegistry.get`, +- **FR1 — The group is ten core native modules.** Every app links them + (`spec:AST-112/FR1`). Each module is read with `TurboModuleRegistry.get`, only by its own wrapper (`spec:AST-140/FR1`, FR2), and its wrapper answers `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` have no public object: the library is their one caller. - | Contract | Kind | Methods | Platforms | - | ----------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | - | `AstryxAppearance` | native module (Turbo Native Module) | `getConstants` (`initialOverride`), `setOverride`, `getRunOverride` | iOS, Android | - | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `getConstants` (`initialSettings`), `getSettings`, `onSettingsChange` (event) | iOS | - | `AstryxHaptics` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `play`, `prepare` | iOS, Android | - | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `detectPatterns` | iOS, Android | - | `AstryxPlatformInfo` | native module (Turbo Native Module) | `getConstants` (`app`, `capabilities`, `components`, `contractFeatures`, `launch`), `getInfo`, `getMemory`, `getBundleSize` | iOS, Android | - | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | - | `AstryxNetwork` | native module (Turbo Native Module) | `getConstants`, `getState`, `onNetworkChange` (event), `getCookies`, `listCookies`, `setCookie`, `removeCookie`, `clearCookies`, `getDomainInfo`, `redirectModes`, `fetchUntrusted` | iOS, Android | - | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | - | `AstryxFilePicker` | native module (Turbo Native Module) | `getConstants`, `getSources`, `pick` | iOS, Android | - | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo` | iOS, Android | - | `AstryxCrypto` | native module (Turbo Native Module) | `getConstants`, `randomBytes` (synchronous) | iOS, Android | - | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | + | Contract | Kind | Methods | Platforms | + | ----------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------ | + | `AstryxAppearance` | native module (Turbo Native Module) | `getConstants` (`initialOverride`), `setOverride`, `getRunOverride` | iOS, Android | + | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `getConstants` (`initialSettings`), `getSettings`, `onSettingsChange` (event) | iOS | + | `AstryxHaptics` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `play`, `prepare` | iOS, Android | + | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `detectPatterns` | iOS, Android | + | `AstryxPlatformInfo` | native module (Turbo Native Module) | `getConstants` (`app`, `capabilities`, `components`, `contractFeatures`, `launch`), `getInfo`, `getMemory`, `getBundleSize` | iOS, Android | + | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | + | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | + | `AstryxFilePicker` | native module (Turbo Native Module) | `getConstants`, `getSources`, `pick` | iOS, Android | + | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo` | iOS, Android | + | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | - **FR2 — Constants are synchronous; everything else is a result.** - What the system knows at launch is a launch value, read once and then @@ -168,27 +154,23 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. (`spec:AST-140/FR3`). Each module adds only these reasons to the common ones: - | Module | Module reasons | - | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `AstryxAppearance` | `invalid` (not `light`, `dark` or `system`) | - | `AstryxAccessibilitySettings` | `unavailable` (the module is torn down during a reload) | - | `AstryxClipboard` | `unavailable` (no pasteboard on this device) | - | `AstryxPlatformInfo` | `unavailable` (the system did not answer a measure) | - | `AstryxPermissions` | `unknown-permission`, `busy`, `no-activity` (Android), `not-declared` | - | `AstryxFilePicker` | `unsupported-source`, `no-window`, `busy`; `cancelled` when the person backs out | - | `AstryxStorage` | `invalid-key`, `invalid-value`, `invalid-json`, `no-space`, `io`, `no-namespace` | - | `AstryxNetwork` | `unavailable`, `invalid-url`, `invalid-host`, `invalid-cookie`; for `fetchUntrusted`: `invalid-request`, `redirect-refused`, `timeout`, `too-large`, `network`, `aborted` | - - - `AstryxCrypto` is the one synchronous exception: its methods return - bytes or throw, as Web Crypto's do (FR15). + | Module | Module reasons | + | ----------------------------- | -------------------------------------------------------------------------------- | + | `AstryxAppearance` | `invalid` (not `light`, `dark` or `system`) | + | `AstryxAccessibilitySettings` | `unavailable` (the module is torn down during a reload) | + | `AstryxClipboard` | `unavailable` (no pasteboard on this device) | + | `AstryxPlatformInfo` | `unavailable` (the system did not answer a measure) | + | `AstryxPermissions` | `unknown-permission`, `busy`, `no-activity` (Android), `not-declared` | + | `AstryxFilePicker` | `unsupported-source`, `no-window`, `busy`; `cancelled` when the person backs out | + | `AstryxStorage` | `invalid-key`, `invalid-value`, `invalid-json`, `no-space`, `io`, `no-namespace` | + - `AstryxHaptics.play` and `prepare` return nothing: they play or do nothing, and `isAvailable()` says which. `AstryxBack` and `AstryxLaunch` calls return nothing either; they are hints that the native side may ignore. - **FR3 — Change events start with the first subscriber and stop after the last.** - - `AstryxAccessibilitySettings.subscribe` and `AstryxNetwork.subscribe` call - the listener with each real change, never with the current value, and + - `AstryxAccessibilitySettings.subscribe` calls the listener with each real change, never with the current value, and return the unsubscribe function. A native event that repeats an unchanged value is not delivered. - A module follows native changes only while at least one listener is @@ -196,10 +178,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. again from the launch value. - On the first subscribe, the accessibility snapshot is read once more. A change that arrives before that answer wins, because it is newer. - - Hooks (`useAccessibilitySettings`, `useNetworkState`, `useCameraPermission`) + - Hooks (`useAccessibilitySettings`, `useCameraPermission`) subscribe on mount, remove the subscription on unmount, and return stable - callbacks (`spec:AST-112/FR7`). `useNetworkState` reports `loading`, - `ready` or `unavailable`. `useCameraPermission` reads again when the app + callbacks (`spec:AST-112/FR7`). `useCameraPermission` reads again when the app returns to the foreground, because the person may change the permission in Settings. - `AstryxPermissions.subscribe` delivers each state change the package @@ -284,7 +265,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. `PackageInfo.lastUpdateTime` on Android), `capabilities` (the opted-in capabilities this binary links; `[]` for core only), `components` (each native component's revision), `contractFeatures` (the named contract - features, FR18), and `launch` (`processStartedAt` in epoch milliseconds, + features, FR17), and `launch` (`processStartedAt` in epoch milliseconds, and `isPrewarmed`, always false on Android). `packageVersion` is the JavaScript package's version. - `get()` answers the platform, the calling runtime's namespace, the components, the per-platform feature rows @@ -316,29 +297,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. `PermissionsAndroid` (which reads `undetermined` until a `request` in this run learns of a refusal), and iOS answers `no-module`. -- **FR10 — `AstryxNetwork` reports the network path.** - - `AstryxNetwork` is part of the optional add-on package, not core. - - `getState()` answers `isConnected`, `type` (`wifi`, `cellular`, - `ethernet`, `other`, `none`, `unknown`), `isMetered`, and `isConstrained` - (iOS Low Data Mode, Android Data Saver for this app). - - `isConnected` is true when the device has a default route to the - internet: on iOS a satisfied path from the path monitor, on Android a - default network with the INTERNET capability. It says nothing about whether - a server answers: it is true behind a captive portal, where requests still - fail. - - On Android the reads need `ACCESS_NETWORK_STATE`, which the configuration - plugin writes when the add-on package is installed; without it, `getState()` answers `unavailable` - and names the permission. - - The module also carries the calling runtime's cookie jar (`AstryxCookies`: - `get`, `set`, `remove`, `clear`; an `httpOnly` cookie's value never reaches - JavaScript), a host's public suffix and registrable domain - (`getDomainInfo`), whether the runtime's request handler honours `fetch`'s - redirect modes (`redirectModes`), and one HTTPS request from a client with - no identity, cookies or cache that follows no redirect natively - (`fetchUntrusted`; `supports('fetchUntrusted')`). Their contracts belong with - the data and security modules (OQ2). - -- **FR11 — `AstryxBack` gives Android's root back press to the system when +- **FR10 — `AstryxBack` gives Android's root back press to the system when JavaScript cannot use it.** - A back press at the root goes to JavaScript only while something in the app can consume it: an open sheet, menu or search field, a `BackHandler` @@ -349,7 +308,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. back presses go to React Native unchanged. - iOS has no module: back is native there. -- **FR12 — `AstryxLaunch` hands Android's cold launch to the first content.** +- **FR11 — `AstryxLaunch` hands Android's cold launch to the first content.** - The shell activity keeps the system's launch window (the splash screen on API 31 and later, the window background before) until the library calls `firstContent()`, so no blank frame appears between the launch window and @@ -366,7 +325,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. router reads `Linking.getInitialURL()`. - iOS has no module: its launch screen stays until the first frame. -- **FR13 — `AstryxFilePicker` presents the system's pickers.** +- **FR12 — `AstryxFilePicker` presents the system's pickers.** - `sources()` lists what the device offers, in menu order: `photos` and `files`. It is empty where the module is absent. Camera capture is the `camera` capability's (`./camera` entry), never a source of the core @@ -380,7 +339,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. and `type`. - iOS: `photos` is `PHPickerViewController` (out of process, so no photo library permission) and `files` is `UIDocumentPickerViewController`. Each picked file is copied into the - app's temporary directory and returned as a `file://` URL; the photo + app's cache location (FR14) and returned as a `file://` URL; the photo picker closes before it loads and copies, and `events.onLoading()` (no argument) is called once when that loading step starts. - Android: `photos` is the Photo Picker (the document picker on devices @@ -389,11 +348,11 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - Defaults: one file, the platform's limit, the media `accept` allows (else all), and any file type. - The library's `FileInput` reaches it through `useFilePicker()`. - - FR13 gap: on iOS the core picker offers a `camera` source + - FR12 gap: on iOS the core picker offers a `camera` source (`UIImagePickerController`) and answers its `permission-denied` and `restricted` reasons. -- **FR14 — `AstryxStorage` is the runtime's string key-value store.** +- **FR13 — `AstryxStorage` is the runtime's string key-value store.** - `get(key)` answers `{value}`, with `null` for a missing key; `set`, `remove`, `keys({prefix?})` and `clear({prefix?})` complete the store; `getJSON` and `setJSON` parse and serialize (`invalid-json`). `info()` @@ -407,23 +366,15 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - The router's state persistence uses it as its default store, and the app update check keeps its "Not now" in the app's namespace. -- **FR15 — `AstryxCrypto` gives secure random bytes synchronously.** - - `AstryxCrypto` is part of the optional add-on package, not core. - - `randomBytes(byteLength)`, `getRandomValues(array)` and `randomUUID()` - take their bytes from the system's secure generator (iOS - `SecRandomCopyBytes`, Android `java.security.SecureRandom`). They are - synchronous, because Web Crypto's `getRandomValues` is, and code written for - it expects the bytes at once. - - They follow Web Crypto's rules and errors: at most 65,536 bytes per call - (`QuotaExceededError`), integer typed arrays only (`TypeMismatchError`). - Where the module is absent they throw `NotSupportedError`; there is never - a non-secure fallback. - - The crypto installer of `spec:AST-112/FR5` installs - `crypto.getRandomValues` and `crypto.randomUUID` from this module where - the runtime lacks them, and installs nothing and reports `no-module` - without it. - -- **FR16 — Threads and lifecycle.** The threading rules of +- **FR14 — The core package owns the app's cache location.** + - The core package owns one cache location for the app. Core pieces that + produce files, such as the camera view's photos and the photos that + `FileInput`'s picker returns, write them there and return `file://` URIs. + - The system may reclaim the location under storage pressure. A caller that + needs a file to last copies it elsewhere. + - Deleting files in the location is outside the core package. + +- **FR15 — Threads and lifecycle.** The threading rules of `spec:AST-140/FR6` apply; for this group: - Constants are read on the JavaScript thread once per module, at the first call that needs them. Asynchronous calls do their native work off the @@ -437,7 +388,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. `unavailable` where FR2 gives the module that reason, and `error` otherwise. A subscription made before the reload ends with it. -- **FR17 — Accessibility.** +- **FR16 — Accessibility.** - The library's drawn chrome follows the snapshot of FR5: Reduce Transparency makes drawn glass and materials opaque, Increase Contrast and Show Borders strengthen edges, Bold Text reaches drawn text and symbols, @@ -450,7 +401,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - These modules expose nothing to VoiceOver or TalkBack themselves; they have no view. -- **FR18 — The group's named features.** +- **FR17 — The group's named features.** - Every contract in the group is at revision 1 (`spec:AST-140/FR5`). Its named features are `AstryxAppearance.persist-false`, `AstryxAppearance.run-override` and `AstryxAppearance.launch-link`, and @@ -461,31 +412,30 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. binary has no run-only override), and the launch link does nothing. A missing feature is reported once with a development warning. -- **FR19 — Public platform API only, and no web engine in the core.** +- **FR18 — Public platform API only, and no web engine in the core.** - The native code of every module in the group uses public platform API only; the group needs no exception. - No core module links WebKit (iOS) or androidx.webkit (Android). Web view data and the web view's cookie store belong to the `web` capability (`spec:AST-112/FR3`). - - FR19 gap: on iOS the core's storage module links WebKit to remove web + - FR18 gap: on iOS the core's storage module links WebKit to remove web view data. ### Platform support -| Contract | iOS | Android | -| ----------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | -| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | -| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | -| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | -| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | -| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | -| `AstryxNetwork` | `NWPathMonitor`; `NSHTTPCookieStorage`; an ephemeral `NSURLSession` for `fetchUntrusted` | `ConnectivityManager` default network callback; the runtime's cookie store; a separate HTTP client | -| `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | -| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | -| `AstryxCrypto` | `SecRandomCopyBytes` | `java.security.SecureRandom` | -| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | -| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | +| Contract | iOS | Android | +| ----------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| `AstryxAppearance` | `overrideUserInterfaceStyle` on every window of the app's scenes | AppCompat default night mode at process start | +| `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | +| `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | +| `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | +| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | +| `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | +| `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | +| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | +| Cache location (FR14) | The app's Caches directory | The app's cache directory | +| `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | +| `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | - Supported feature/engine floor: the platform floor of `spec:AST-112` (iOS at React Native's minimum, Android API level 24, the New Architecture @@ -494,33 +444,32 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. false, stay out of an answer, or keep the older behaviour below them. - Unsupported behavior: an absent module answers `no-module` and its synchronous members answer their empty values (FR2); a missing named feature - answers `unsupported` or keeps the revision-1 behaviour (FR18); a + answers `unsupported` or keeps the revision-1 behaviour (FR17); a platform-only module is absent on the other platform, and the library takes - the path FR5, FR11 and FR12 name; an app without the optional add-on - package has neither `AstryxNetwork` nor `AstryxCrypto` (FR1, FR15). + the path FR5, FR10 and FR11 name. - Browser evidence: none. Claims are proven on the iOS Simulator, the Android emulator, and devices (`spec:AST-112/FR15`); haptic feel needs a real device. ## Current-state impact -- Relies on `spec:AST-112` FR3 (amended): the core links in every app; ten - modules of this group are core. +- Relies on `spec:AST-112` FR3 (amended): the core links in every app, and + every module of this group is core. - Relies on `spec:AST-140` FR5: every contract is at revision 1, and later behaviour is a named feature that the platform info module reports. - Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform API only. - Changes `spec:AST-112/FR1`: the core's list gains appearance, accessibility settings, platform info, the Android back gate and launch hold, and the - file picker; network and cookies leave the core for the optional add-on - package, with secure random bytes; the `camera` capability gains camera - capture, the camera source of a picker included (FR13). + file picker; network, cookies and secure random bytes leave the core, since + capabilities that no Astryx component uses are outside the core package; the + `camera` capability gains camera + capture, the camera source of a picker included (FR12). - Changes `spec:AST-112/FR1` and FR3: the core links no web engine, and the - `web` capability carries web view data and its cookie store (FR19). + `web` capability carries web view data and its cookie store (FR18). - Departs from `spec:AST-112/FR7` ("never a silent no-op") for the calls that - return nothing (FR2); OQ3 asks whether the exception stands. -- Details `spec:AST-112` FR5 (the crypto installer's module), FR7 (each - module's probes) and FR9 (the haptic moment mapping), and `spec:AST-140/FR3` + return nothing (FR2); OQ2 asks whether the exception stands. +- Details `spec:AST-112` FR7 (each module's probes) and FR9 (the haptic moment mapping), and `spec:AST-140/FR3` (each module's results). ## Verification @@ -536,16 +485,15 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | | FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | | FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | -| FR10 | Unit tests; emulator and Simulator network changes | Wi-Fi, cellular, none; captive portal; Low Data Mode; missing Android permission | `isConnected` differs between platforms for the same route, or a missing permission answers anything but `unavailable` | -| FR11 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | -| FR12 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | -| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | -| FR14 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | -| FR15 | Unit tests of the bytes, errors and installer; Simulator and emulator reads | 0 and 65,536 bytes; above the ceiling; module absent; an existing `crypto` | A non-secure fill, a call that does not throw Web Crypto's error, or an installer that replaces an existing function | -| FR16 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | -| FR17 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | -| FR18 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | -| FR19 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | +| FR10 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | +| FR11 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | +| FR12 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | +| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | +| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, a URI that is not a `file://` URI, or a core piece that deletes files there | +| FR15 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | +| FR16 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | +| FR17 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | +| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | ## Decision log @@ -604,8 +552,8 @@ missed call holds the splash. **Reference:** `spec:AST-130/DEC-5` **Decider:** imdreamrunner, 2026-11-17 -Haptics, the clipboard, permissions, the file pickers, storage, secure random -bytes and network state are small wrappers +Haptics, the clipboard, permissions, the file pickers and storage are small +wrappers where the ecosystem has good libraries. They stay Astryx modules because the package takes no runtime dependency outside React and React Native (`spec:AST-112/FR2`), and because each needs the result vocabulary. DEC-5 holds until OQ1 is @@ -615,27 +563,18 @@ answered. - **OQ1 — Do the thin system modules stay Astryx modules?** (`human-design`) `AstryxHaptics`, `AstryxClipboard`, `AstryxPermissions`, `AstryxFilePicker`, - `AstryxStorage`, `AstryxCrypto` and the network state of `AstryxNetwork` - fill little capability gap. Options: keep them as + and `AstryxStorage` fill little capability gap. Options: keep them as Astryx modules (one dependency set, one result shape); or replace their native side with adapters over community libraries, keeping the wrappers' API. -- **OQ2 — Do cookies, domain info, redirect modes and `fetchUntrusted` move to - the data and security group?** (`human-design`) They are methods - of `AstryxNetwork`, no Astryx component calls them, and their rules - (per-runtime jars, values that stay native, requests with no identity) - are data and security contracts. The library's marker for content-chosen - image and media URLs belongs to the same question. Options: a separate - module in that group, with `AstryxNetwork` keeping only the path state; or - one module whose contract this record shares with that group's record. -- **OQ3 — Do the calls that return nothing keep doing nothing where they +- **OQ2 — Do the calls that return nothing keep doing nothing where they cannot act?** (`human-api`) `AstryxHaptics.play` and `prepare`, and the back and launch hints, do nothing where the module is absent or unsupported, which `spec:AST-112/FR7` forbids as a silent no-op. Options: `spec:AST-112/FR7` names them as an exception, with `isAvailable()` saying when they do nothing; or each gains a result that answers why it did not act. -- **OQ4 — Light and dark: does the platform resolve theme colours natively at +- **OQ3 — Light and dark: does the platform resolve theme colours natively at the trait change, or does JavaScript re-resolve the tokens and re-render on each flip?** (`human-design`) Options: - Native resolution (iOS dynamic colour providers, Android night-mode From 38cdf214dd7ba9c2a1c028b839a25fb0c9128cff Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:42:23 -0800 Subject: [PATCH 15/32] spec(AST-130): named features instead of component revisions; initialURL is synchronous; storage states what persists --- .../spec.md | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 160d4a28461d6..df60a28a5784a 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -61,8 +61,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. Android plays the view feedback its API level has (OQ1). - `AstryxClipboard`: no capability gap. The module gives the result vocabulary with no extra dependency (OQ1). -- `AstryxPlatformInfo`: the binary's own contract facts (component revisions, - linked capabilities, named features), which only the binary can report. +- `AstryxPlatformInfo`: the binary's own contract facts (linked capabilities + and named features), which only the binary can report. - `AstryxPermissions`: a small gap. A closed set of permissions tied to the capabilities, with `not-declared` where the system would end the app (OQ1). - `AstryxBack`: React Native's activity takes every back press, so Android's @@ -82,7 +82,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | | `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | | `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | -| `AstryxPlatformInfo` | native module (Turbo Native Module) | Its revision and feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), the zoom pager gesture, and `useComponentRevision`; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | +| `AstryxPlatformInfo` | native module (Turbo Native Module) | Its named-feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), and the zoom pager gesture; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | | `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) reads it; app API `useCameraPermission` | The system prompt appears only when the app asks, never when a view mounts. | | `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | | `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | @@ -127,27 +127,28 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` have no public object: the library is their one caller. - | Contract | Kind | Methods | Platforms | - | ----------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------ | - | `AstryxAppearance` | native module (Turbo Native Module) | `getConstants` (`initialOverride`), `setOverride`, `getRunOverride` | iOS, Android | - | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `getConstants` (`initialSettings`), `getSettings`, `onSettingsChange` (event) | iOS | - | `AstryxHaptics` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `play`, `prepare` | iOS, Android | - | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `detectPatterns` | iOS, Android | - | `AstryxPlatformInfo` | native module (Turbo Native Module) | `getConstants` (`app`, `capabilities`, `components`, `contractFeatures`, `launch`), `getInfo`, `getMemory`, `getBundleSize` | iOS, Android | - | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | - | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | - | `AstryxFilePicker` | native module (Turbo Native Module) | `getConstants`, `getSources`, `pick` | iOS, Android | - | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo` | iOS, Android | - | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | + | Contract | Kind | Methods | Platforms | + | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------ | + | `AstryxAppearance` | native module (Turbo Native Module) | `getConstants` (`initialOverride`), `setOverride`, `getRunOverride` | iOS, Android | + | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `getConstants` (`initialSettings`), `getSettings`, `onSettingsChange` (event) | iOS | + | `AstryxHaptics` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `play`, `prepare` | iOS, Android | + | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `detectPatterns` | iOS, Android | + | `AstryxPlatformInfo` | native module (Turbo Native Module) | `getConstants` (`app`, `capabilities`, `contractFeatures`, `launch`), `getInfo`, `getMemory`, `getBundleSize` | iOS, Android | + | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | + | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | + | `AstryxFilePicker` | native module (Turbo Native Module) | `getConstants`, `getSources`, `pick` | iOS, Android | + | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo` | iOS, Android | + | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | - **FR2 — Constants are synchronous; everything else is a result.** - What the system knows at launch is a launch value, read once and then answered synchronously: the saved appearance and the run's override, the accessibility snapshot, the app's version, build, identifier and install - time, the linked capabilities, the component revisions, the named contract - features, and the process start. Synchronous members (`isAvailable()`, + time, the linked capabilities, the named contract features, and the + process start. Synchronous members (`isAvailable()`, `getOverride()`, `getRunOverride()`, `current()`, `app`, - `capabilities`, `launch`, `componentRevision(name)`) never throw; they + `capabilities`, `launch`, and `AstryxLaunch`'s `initialURL()`) never + throw; they answer `null`, `'system'`, or all-false where the module or the constant is absent. - Every asynchronous call resolves `AstryxResult` and never rejects @@ -165,7 +166,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | `AstryxStorage` | `invalid-key`, `invalid-value`, `invalid-json`, `no-space`, `io`, `no-namespace` | - `AstryxHaptics.play` and `prepare` return nothing: they play or do nothing, - and `isAvailable()` says which. `AstryxBack` and `AstryxLaunch` calls + and `isAvailable()` says which. `setRootBackEnabled` and `firstContent` return nothing either; they are hints that the native side may ignore. - **FR3 — Change events start with the first subscriber and stop after the @@ -263,12 +264,11 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - Constants: `app` (version, build, identifier, and `installedAt` in ISO 8601 UTC: the bundle container's creation date on iOS, `PackageInfo.lastUpdateTime` on Android), `capabilities` (the opted-in - capabilities this binary links; `[]` for core only), `components` (each - native component's revision), `contractFeatures` (the named contract + capabilities this binary links; `[]` for core only), `contractFeatures` (the named contract features, FR17), and `launch` (`processStartedAt` in epoch milliseconds, and `isPrewarmed`, always false on Android). `packageVersion` is the JavaScript package's version. - - `get()` answers the platform, the calling runtime's namespace, the components, the per-platform feature rows + - `get()` answers the platform, the calling runtime's namespace, the per-platform feature rows (`.`, with `isSupported` and a note), and the self-checks of the platform internals the package relies on (`compat`). `supports(name)` reads a feature row from the last answer and is `null` @@ -360,9 +360,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. and the free space (`null` when the platform does not say). - Every call works in the calling runtime's namespace, decided natively and never by JavaScript; `info()` names it. - - Values are kept across launches: one file per key in Application Support - on iOS and in the app's internal files directory on Android. The package - sets no size limit; only the device's free space limits a value. + - Values are kept across launches in storage the system keeps for the app. + The package sets no size limit; only the device's free space limits a + value. - The router's state persistence uses it as its default store, and the app update check keeps its "Not now" in the app's namespace. @@ -432,7 +432,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | | `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | | `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | -| `AstryxStorage` | One file per key in Application Support | One file per key in the internal files directory | +| `AstryxStorage` | Application Support | The app's internal files directory | | Cache location (FR14) | The app's Caches directory | The app's cache directory | | `AstryxBack` | No module (native back) | `OnBackPressedCallback` on the shell activity, enabled by the gate | | `AstryxLaunch` | No module (the launch screen stays until the first frame) | The shell activity holds the launch window; synchronous launch intent data | From aa74791fde384bba990c20466402f8be38e76175 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:23:22 -0800 Subject: [PATCH 16/32] spec(AST-130): picker files land in the cache location on both platforms; cookies leave the amended core; Appearance scope question --- .../spec.md | 40 ++++++++++++------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index df60a28a5784a..9067942c9d7ba 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -93,7 +93,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - The data and security modules (files, secure storage) and their records. - Capabilities that no Astryx component uses. They are outside the core - package. + package; OQ4 asks whether `AstryxAppearance` is an exception. - Client identity, crash reports, daily metrics, the frame recorder, and image markup. Each is part of the platform package and has its own record. - Camera capture. The `camera` capability owns it, the camera source of a @@ -175,8 +175,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. return the unsubscribe function. A native event that repeats an unchanged value is not delivered. - A module follows native changes only while at least one listener is - subscribed. After the last unsubscribe it stops, and the next read starts - again from the launch value. + subscribed. After the last unsubscribe it stops; until the next subscribe, + a read answers the last value it followed, and the next first subscriber + reads the settings again. - On the first subscribe, the accessibility snapshot is read once more. A change that arrives before that answer wins, because it is newer. - Hooks (`useAccessibilitySettings`, `useCameraPermission`) @@ -262,8 +263,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - **FR8 — `AstryxPlatformInfo` says what this binary has.** - Constants: `app` (version, build, identifier, and `installedAt` in ISO - 8601 UTC: the bundle container's creation date on iOS, - `PackageInfo.lastUpdateTime` on Android), `capabilities` (the opted-in + 8601 UTC: when this binary was installed or last updated, the bundle + container's creation date on iOS and `PackageInfo.lastUpdateTime` on + Android), `capabilities` (the opted-in capabilities this binary links; `[]` for core only), `contractFeatures` (the named contract features, FR17), and `launch` (`processStartedAt` in epoch milliseconds, and `isPrewarmed`, always false on Android). `packageVersion` is the @@ -343,11 +345,14 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. picker closes before it loads and copies, and `events.onLoading()` (no argument) is called once when that loading step starts. - Android: `photos` is the Photo Picker (the document picker on devices - without it) and `files` is the Storage Access Framework; the `content://` - URIs the pickers grant are returned as they are. + without it) and `files` is the Storage Access Framework. Each picked file + is copied into the app's cache location (FR14) and returned as a `file://` + URL. - Defaults: one file, the platform's limit, the media `accept` allows (else all), and any file type. - The library's `FileInput` reaches it through `useFilePicker()`. + - FR12 gap: on Android the core picker returns the `content://` URIs the + pickers grant instead of `file://` URIs in the cache location. - FR12 gap: on iOS the core picker offers a `camera` source (`UIImagePickerController`) and answers its `permission-denied` and `restricted` reasons. @@ -367,9 +372,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. update check keeps its "Not now" in the app's namespace. - **FR14 — The core package owns the app's cache location.** - - The core package owns one cache location for the app. Core pieces that - produce files, such as the camera view's photos and the photos that - `FileInput`'s picker returns, write them there and return `file://` URIs. + - The core package owns one cache location for the app. Pieces that produce + files write them there and return `file://` URIs: the core's file picker + (FR12), which `FileInput` uses, and the `camera` capability's camera view. - The system may reclaim the location under storage pressure. A caller that needs a file to last copies it elsewhere. - Deleting files in the location is outside the core package. @@ -461,10 +466,11 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. API only. - Changes `spec:AST-112/FR1`: the core's list gains appearance, accessibility settings, platform info, the Android back gate and launch hold, and the - file picker; network, cookies and secure random bytes leave the core, since - capabilities that no Astryx component uses are outside the core package; the - `camera` capability gains camera - capture, the camera source of a picker included (FR12). + file picker; the `camera` capability gains camera capture, the camera source + of a picker included (FR12). +- Changes `spec:AST-112` FR1 and FR5 (amended): cookies leave the core's list + and the `./network` entry, since no Astryx component uses them; the network + state and secure random bytes are already outside the amended core. - Changes `spec:AST-112/FR1` and FR3: the core links no web engine, and the `web` capability carries web view data and its cookie store (FR18). - Departs from `spec:AST-112/FR7` ("never a silent no-op") for the calls that @@ -584,3 +590,9 @@ answered. - Tokens resolved in JavaScript: one token pipeline shared with the web, and any computed token works. Each flip costs a JavaScript re-resolve and a re-render. +- **OQ4 — Does `AstryxAppearance` stay in the core?** (`human-design`) No + Astryx component or create template calls it; the theme follows its effect + through React Native's colour scheme. Options: keep it in the core as a + named exception, because the native shell applies the saved choice before + the first frame (DEC-1); or move it outside the core package with the other + capabilities no Astryx component uses. From ef5c6efdff938c976fb81fcc577d7ce1f29daaab Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:25:38 -0800 Subject: [PATCH 17/32] spec(AST-130): AstryxAppearance is core: the theme provider applies the override through it --- .../spec.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 9067942c9d7ba..0be609c18a49f 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -78,7 +78,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | Native piece | Kind | Astryx components that use it | What a person sees | | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxAppearance` | native module (Turbo Native Module) | No Astryx component; app API (`.` entry). The theme follows its effect through React Native's colour scheme. | The app opens in the saved light or dark appearance, with no flash of the system's. | +| `AstryxAppearance` | native module (Turbo Native Module) | `AstryxProvider`, the theme provider every Astryx component renders under, which applies the app's light or dark override through it; app API (`.` entry) | The app opens in the saved light or dark appearance, with no flash of the system's. | | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | | `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | | `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | @@ -93,7 +93,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - The data and security modules (files, secure storage) and their records. - Capabilities that no Astryx component uses. They are outside the core - package; OQ4 asks whether `AstryxAppearance` is an exception. + package. - Client identity, crash reports, daily metrics, the frame recorder, and image markup. Each is part of the platform package and has its own record. - Camera capture. The `camera` capability owns it, the camera source of a @@ -189,6 +189,10 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. learns from a `get` or a `request` anywhere in the app. - **FR4 — `AstryxAppearance` keeps the app's light or dark choice natively.** + - `AstryxAppearance` is core: the library's theme provider, which every + Astryx component renders under, reads the system appearance and applies + the app's light or dark override through this module, so it is native code + Astryx itself uses (`spec:AST-112/FR20`). - `setOverride('light' | 'dark' | 'system')` applies the choice to every window of the app at once and saves it; `system` removes the saved choice. `getOverride()` answers the saved choice synchronously. @@ -200,6 +204,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. app's code runs, so it keeps the system's appearance; on Android 12 and later the splash uses the night mode the system stores for the app, which is the saved choice. + - FR4 gap: the theme provider follows React Native's colour scheme and does + not call `AstryxAppearance`; an app calls `setOverride` itself. - `setOverride(value, {persist: false})` (feature `persist-false`) applies the choice for this run only and saves nothing. `getOverride()` and the next launch keep the saved choice, and `setOverride(getOverride())` restores @@ -464,6 +470,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. behaviour is a named feature that the platform info module reports. - Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform API only. +- Relies on `spec:AST-112` FR20 (amended): the package covers the native code + Astryx itself uses; every module of this group is such code. - Changes `spec:AST-112/FR1`: the core's list gains appearance, accessibility settings, platform info, the Android back gate and launch hold, and the file picker; the `camera` capability gains camera capture, the camera source @@ -590,9 +598,3 @@ answered. - Tokens resolved in JavaScript: one token pipeline shared with the web, and any computed token works. Each flip costs a JavaScript re-resolve and a re-render. -- **OQ4 — Does `AstryxAppearance` stay in the core?** (`human-design`) No - Astryx component or create template calls it; the theme follows its effect - through React Native's colour scheme. Options: keep it in the core as a - named exception, because the native shell applies the saved choice before - the first frame (DEC-1); or move it outside the core package with the other - capabilities no Astryx component uses. From 6be3e8edd2e4ca9c4ee718f4b210f5d076e789f6 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:49:23 -0800 Subject: [PATCH 18/32] spec(AST-130): one appearance model with preference, session and screen scopes; app-shell and diagnostics pieces outside the core --- .../spec.md | 71 +++++++++++-------- 1 file changed, 42 insertions(+), 29 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 0be609c18a49f..3390f95e822b7 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -95,15 +95,14 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - Capabilities that no Astryx component uses. They are outside the core package. - Client identity, crash reports, daily metrics, the frame recorder, and - image markup. Each is part of the platform package and has its own record. + image markup. They are outside the core package; each has its own record. - Camera capture. The `camera` capability owns it, the camera source of a picker included. -- Sharing, opening links and Settings, keep-awake, and orientation lock. None - is a core module; each one is an opt-in capability of its own when Astryx - provides it. -- The design of the theme's appearance model and its scopes. This record owns - the native appearance override, and OQ3 asks how theme colours resolve when - the appearance flips. +- Sharing, opening links and Settings, keep-awake, and orientation lock. No + Astryx component uses them, so they are outside the core package. +- The theme's tokens and how they change between light and dark. This record + owns the appearance model of FR4, and OQ3 asks how theme colours resolve + when the appearance flips. - Haptic intensities per moment. The theme's haptic tokens own them (`spec:AST-112/FR9`). - Each component's use of these modules beyond what "Who uses it" names; the @@ -204,8 +203,20 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. app's code runs, so it keeps the system's appearance; on Android 12 and later the splash uses the night mode the system stores for the app, which is the saved choice. + - The appearance is one model with three scopes, from the widest: + - preference: the saved choice, kept across launches; + - session: the run-only override (`persist: false`, or the launch link), + which a new process forgets; + - screen: a screen's own light or dark choice, through the router's screen + options (`spec:AST-125`), in force while that screen is in front. + - The library owns the precedence: a screen's choice wins over the session's, + the session's over the preference, and the preference over the system's + appearance. The theme provider resolves the scopes in one place and gives + every component and the app one resolved read of the appearance in force. - FR4 gap: the theme provider follows React Native's colour scheme and does - not call `AstryxAppearance`; an app calls `setOverride` itself. + not call `AstryxAppearance`; an app calls `setOverride` itself and writes + the precedence across the saved choice, the run's override, a screen's + option and the system's scheme. - `setOverride(value, {persist: false})` (feature `persist-false`) applies the choice for this run only and saves nothing. `getOverride()` and the next launch keep the saved choice, and `setOverride(getOverride())` restores @@ -488,26 +499,26 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | -| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw | A synchronous member throws, a call rejects, or answers a reason outside its set | -| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | -| FR4 | Unit tests; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link | saved `dark` under a light system; `persist: false`; launch link cold and warm | The first frame shows the system's style, a run-only change survives a relaunch | -| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | -| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | -| FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | -| FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | -| FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | -| FR10 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | -| FR11 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | -| FR12 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | -| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | -| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, a URI that is not a `file://` URI, or a core piece that deletes files there | -| FR15 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | -| FR16 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | -| FR17 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | -| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | +| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw | A synchronous member throws, a call rejects, or answers a reason outside its set | +| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | +| FR4 | Unit tests of the scope precedence; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link; a screen with its own choice | saved `dark` under a light system; `persist: false`; launch link cold and warm; a screen choice over a session override | The first frame shows the system's style, a run-only change survives a relaunch, or a narrower scope loses to a wider one | +| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | +| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | +| FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | +| FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | +| FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | +| FR10 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | +| FR11 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | +| FR12 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | +| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | +| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, a URI that is not a `file://` URI, or a core piece that deletes files there | +| FR15 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | +| FR16 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | +| FR17 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | +| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | ## Decision log @@ -520,7 +531,9 @@ A choice that JavaScript applies arrives after the first frame, so a saved choice opposite the system shows the system's style first and then cross-fades. The native shell saves the choice and applies it to the window before it shows; run-only changes and the launch link use the same path and -save nothing. +save nothing. The preference, session and screen scopes form one model whose +precedence the library owns, so an app reads one resolved appearance instead +of combining the inputs itself. Rejected: applying the choice from JavaScript at start, because the first frame cannot follow it. From efbe1dad13f5e123c6aac13dab716671f80e5978 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:51:26 -0800 Subject: [PATCH 19/32] spec(AST-130): links, Settings and sharing go through React Native Linking and Share; keep-awake and orientation lock stay outside the core --- .../spec.md | 34 +++++++++++-------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 3390f95e822b7..be1bc19478971 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -76,18 +76,20 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. ## Who uses it -| Native piece | Kind | Astryx components that use it | What a person sees | -| ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxAppearance` | native module (Turbo Native Module) | `AstryxProvider`, the theme provider every Astryx component renders under, which applies the app's light or dark override through it; app API (`.` entry) | The app opens in the saved light or dark appearance, with no flash of the system's. | -| `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | -| `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | -| `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | -| `AstryxPlatformInfo` | native module (Turbo Native Module) | Its named-feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), and the zoom pager gesture; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | -| `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) reads it; app API `useCameraPermission` | The system prompt appears only when the app asks, never when a view mounts. | -| `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | -| `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | -| `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | -| `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the app update check's "Not now"; app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | +| Native piece | Kind | Astryx components that use it | What a person sees | +| ----------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxAppearance` | native module (Turbo Native Module) | `AstryxProvider`, the theme provider every Astryx component renders under, which applies the app's light or dark override through it; app API (`.` entry) | The app opens in the saved light or dark appearance, with no flash of the system's. | +| `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | +| `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | +| `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | +| `AstryxPlatformInfo` | native module (Turbo Native Module) | Its named-feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), and the zoom pager gesture; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | +| `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) reads it; app API `useCameraPermission` | The system prompt appears only when the app asks, never when a view mounts. | +| `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | +| `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | +| `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | +| `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the app update check's "Not now"; app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | +| React Native `Linking` | React Native core API (no Astryx native module) | Every `href` the library renders, through its link helper and host services: `Link`, `Button`, `Chip`, `ClickableCard`, `Item`, `Avatar`, `Breadcrumbs`, `Citation`, `ContextMenu` and `DropdownMenu` items, `Markdown` and `RichText` links, `SideNav`, `NavMenu` and `Tab`; the router's external links; the `camera` template's "open Settings" | A tapped link opens in the system's browser or the app that owns it; a blocked camera permission opens the app's Settings. | +| React Native `Share` | React Native core API (no Astryx native module) | The library's host services (`useHostServices().share`), which the `create` templates' share actions use (assistant, camera, gallery, maps, text feed) | The system share sheet opens with the item's text or link. | ## Non-goals @@ -98,8 +100,12 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. image markup. They are outside the core package; each has its own record. - Camera capture. The `camera` capability owns it, the camera source of a picker included. -- Sharing, opening links and Settings, keep-awake, and orientation lock. No - Astryx component uses them, so they are outside the core package. +- A native module of the package's own for opening links, opening Settings, + or sharing. Astryx components and `create` templates use React Native's own + `Linking` and `Share` for them (see "Who uses it"), so these stay part of what + the core relies on and need no Astryx native code. +- Keep-awake and orientation lock. No Astryx component or `create` template + uses them, so they are outside the core package. - The theme's tokens and how they change between light and dark. This record owns the appearance model of FR4, and OQ3 asks how theme colours resolve when the appearance flips. From 74abac7b470a89235baf5e5b8dbd7ba548eb5a4d Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:21:28 -0800 Subject: [PATCH 20/32] spec(AST-130): a saving setOverride ends the run-only override --- docs/specs/AST-130-react-native-system-modules/spec.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index be1bc19478971..46e078e3f4277 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -88,7 +88,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | | `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | | `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the app update check's "Not now"; app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | -| React Native `Linking` | React Native core API (no Astryx native module) | Every `href` the library renders, through its link helper and host services: `Link`, `Button`, `Chip`, `ClickableCard`, `Item`, `Avatar`, `Breadcrumbs`, `Citation`, `ContextMenu` and `DropdownMenu` items, `Markdown` and `RichText` links, `SideNav`, `NavMenu` and `Tab`; the router's external links; the `camera` template's "open Settings" | A tapped link opens in the system's browser or the app that owns it; a blocked camera permission opens the app's Settings. | +| React Native `Linking` | React Native core API (no Astryx native module) | Every `href` the library renders, through its link helper and host services: `Link`, `Button`, `Chip`, `ClickableCard`, `Item`, `Avatar`, `Breadcrumbs`, `Citation`, `ContextMenu` and `DropdownMenu` items, `Markdown` links, `SideNav`, `NavMenu` and `Tab`; the router's external links; the `camera` template's "open Settings" | A tapped link opens in the system's browser or the app that owns it; a blocked camera permission opens the app's Settings. | | React Native `Share` | React Native core API (no Astryx native module) | The library's host services (`useHostServices().share`), which the `create` templates' share actions use (assistant, camera, gallery, maps, text feed) | The system share sheet opens with the item's text or link. | ## Non-goals @@ -225,8 +225,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. option and the system's scheme. - `setOverride(value, {persist: false})` (feature `persist-false`) applies the choice for this run only and saves nothing. `getOverride()` and the next - launch keep the saved choice, and `setOverride(getOverride())` restores - it. + launch keep the saved choice. A saving `setOverride` ends the run-only + override, so `setOverride(getOverride())` restores the saved choice and + `getRunOverride()` then answers `null`. - `getRunOverride()` (feature `run-override`) answers the run's own override synchronously, or `null` when the saved choice is in force, so the first render matches the first frame. From ba703ee3625758138a83a89012d0ca84be86d709 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 00:41:46 -0800 Subject: [PATCH 21/32] spec(AST-130): each contract's baseline is its first release's shape; FR20 cited as amended --- .../spec.md | 50 ++++++++++--------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 46e078e3f4277..07b52874f1fdc 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -197,7 +197,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - `AstryxAppearance` is core: the library's theme provider, which every Astryx component renders under, reads the system appearance and applies the app's light or dark override through this module, so it is native code - Astryx itself uses (`spec:AST-112/FR20`). + Astryx itself uses (`spec:AST-112/FR20`, amended). - `setOverride('light' | 'dark' | 'system')` applies the choice to every window of the app at once and saves it; `system` removes the saved choice. `getOverride()` answers the saved choice synchronously. @@ -431,7 +431,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. no view. - **FR17 — The group's named features.** - - Every contract in the group is at revision 1 (`spec:AST-140/FR5`). Its + - Each contract's baseline is its first release's shape + (`spec:AST-140/FR5`). The group's named features are `AstryxAppearance.persist-false`, `AstryxAppearance.run-override` and `AstryxAppearance.launch-link`, and `AstryxPlatformInfo`'s `contractFeatures` constant is the list a binary @@ -473,7 +474,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. false, stay out of an answer, or keep the older behaviour below them. - Unsupported behavior: an absent module answers `no-module` and its synchronous members answer their empty values (FR2); a missing named feature - answers `unsupported` or keeps the revision-1 behaviour (FR17); a + answers `unsupported` or keeps the baseline behaviour (FR17); a platform-only module is absent on the other platform, and the library takes the path FR5, FR10 and FR11 name. - Browser evidence: none. Claims are proven on the iOS Simulator, the Android @@ -484,7 +485,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - Relies on `spec:AST-112` FR3 (amended): the core links in every app, and every module of this group is core. -- Relies on `spec:AST-140` FR5: every contract is at revision 1, and later +- Relies on `spec:AST-140` FR5: each contract's baseline is its first + release's shape, and later behaviour is a named feature that the platform info module reports. - Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform API only. @@ -506,26 +508,26 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | -| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw | A synchronous member throws, a call rejects, or answers a reason outside its set | -| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | -| FR4 | Unit tests of the scope precedence; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link; a screen with its own choice | saved `dark` under a light system; `persist: false`; launch link cold and warm; a screen choice over a session override | The first frame shows the system's style, a run-only change survives a relaunch, or a narrower scope loses to a wider one | -| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | -| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | -| FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | -| FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | -| FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | -| FR10 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | -| FR11 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | -| FR12 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | -| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | -| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, a URI that is not a `file://` URI, or a core piece that deletes files there | -| FR15 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | -| FR16 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | -| FR17 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the revision-1 path or `unsupported`, or no warning | -| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | +| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw | A synchronous member throws, a call rejects, or answers a reason outside its set | +| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | +| FR4 | Unit tests of the scope precedence; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link; a screen with its own choice | saved `dark` under a light system; `persist: false`; launch link cold and warm; a screen choice over a session override | The first frame shows the system's style, a run-only change survives a relaunch, or a narrower scope loses to a wider one | +| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | +| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | +| FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | +| FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | +| FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | +| FR10 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | +| FR11 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | +| FR12 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | +| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | +| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, a URI that is not a `file://` URI, or a core piece that deletes files there | +| FR15 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | +| FR16 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | +| FR17 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the baseline path or `unsupported`, or no warning | +| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | ## Decision log From 75f817987c69a63e8d17435b4dc7142ab1c3d88e Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:02:10 -0800 Subject: [PATCH 22/32] spec(AST-130): AST-112 citations name the amended text --- docs/specs/AST-130-react-native-system-modules/spec.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 07b52874f1fdc..e6f1f6b628f9f 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -478,11 +478,13 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. platform-only module is absent on the other platform, and the library takes the path FR5, FR10 and FR11 name. - Browser evidence: none. Claims are proven on the iOS Simulator, the Android - emulator, and devices (`spec:AST-112/FR15`); haptic feel needs + emulator, and devices (`spec:AST-112/FR15`, amended); haptic feel needs a real device. ## Current-state impact +- Every `spec:AST-112` clause this record cites is that record's amended + text. - Relies on `spec:AST-112` FR3 (amended): the core links in every app, and every module of this group is core. - Relies on `spec:AST-140` FR5: each contract's baseline is its first From 3ae826e98e85dfde67c6e116da9e099c475ad40f Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:03:10 -0800 Subject: [PATCH 23/32] spec(AST-130): clearing web view data has no Astryx call; web data rules are AST-131s --- .../specs/AST-130-react-native-system-modules/spec.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index e6f1f6b628f9f..617620c871b9a 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -445,9 +445,10 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - **FR18 — Public platform API only, and no web engine in the core.** - The native code of every module in the group uses public platform API only; the group needs no exception. - - No core module links WebKit (iOS) or androidx.webkit (Android). Web view - data and the web view's cookie store belong to the `web` capability - (`spec:AST-112/FR3`). + - The core reaches neither WebKit (iOS) nor androidx.webkit (Android). + Clearing web view data has no Astryx call and is outside the core package; + an app that needs it uses its host platform's implementation + (`spec:AST-112/FR20`). The web view's own data rules are `spec:AST-131`'s. - FR18 gap: on iOS the core's storage module links WebKit to remove web view data. @@ -501,8 +502,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - Changes `spec:AST-112` FR1 and FR5 (amended): cookies leave the core's list and the `./network` entry, since no Astryx component uses them; the network state and secure random bytes are already outside the amended core. -- Changes `spec:AST-112/FR1` and FR3: the core links no web engine, and the - `web` capability carries web view data and its cookie store (FR18). +- Changes `spec:AST-112/FR1` and FR3: the core links no web engine, and + clearing web view data has no Astryx call (FR18). - Departs from `spec:AST-112/FR7` ("never a silent no-op") for the calls that return nothing (FR2); OQ2 asks whether the exception stands. - Details `spec:AST-112` FR7 (each module's probes) and FR9 (the haptic moment mapping), and `spec:AST-140/FR3` From 3a555bbfa381dc7126c9f99d35ce0acfb42be1f8 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:17:46 -0800 Subject: [PATCH 24/32] spec(AST-130): the launch-link appearance applies at cold launch only --- .../spec.md | 51 ++++++++++--------- 1 file changed, 28 insertions(+), 23 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 617620c871b9a..381058499889d 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -211,7 +211,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. is the saved choice. - The appearance is one model with three scopes, from the widest: - preference: the saved choice, kept across launches; - - session: the run-only override (`persist: false`, or the launch link), + - session: the run-only override (`persist: false`, or the cold-launch link), which a new process forgets; - screen: a screen's own light or dark choice, through the router's screen options (`spec:AST-125`), in force while that screen is in front. @@ -234,8 +234,13 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - With the configuration plugin's `appearance.launchLinkParameter` set (default: off), a link on one of the app's own schemes whose named query parameter is `light`, `dark` or `system` applies that appearance natively - as a run-only override: before the first frame on a cold launch, and on - arrival on a warm one (feature `launch-link`). Nothing is saved. + as a run-only override at cold launch only: when the first activity is + created on Android, and when the scene connects on iOS, before the first + frame (feature `launch-link`). Nothing is saved. A link that arrives later + (a new intent, or a scene URL) never changes the appearance; navigation + from it uses the screen's own `appearance` option (`spec:AST-125/FR7`). + - FR4 gap: a link that arrives while the app runs applies its appearance as + a run-only override too. - **FR5 — `AstryxAccessibilitySettings` publishes one settings snapshot.** - The snapshot has seven booleans. Every answer carries all seven, and a key @@ -511,26 +516,26 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. ## Verification -| Contract | Verification | Representative states | Mutation or failure expectation | -| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | -| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw | A synchronous member throws, a call rejects, or answers a reason outside its set | -| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | -| FR4 | Unit tests of the scope precedence; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link; a screen with its own choice | saved `dark` under a light system; `persist: false`; launch link cold and warm; a screen choice over a session override | The first frame shows the system's style, a run-only change survives a relaunch, or a narrower scope loses to a wider one | -| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | -| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | -| FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | -| FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | -| FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | -| FR10 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | -| FR11 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | -| FR12 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | -| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | -| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, a URI that is not a `file://` URI, or a core piece that deletes files there | -| FR15 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | -| FR16 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | -| FR17 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the baseline path or `unsupported`, or no warning | -| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | +| Contract | Verification | Representative states | Mutation or failure expectation | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| FR1 | The platform's spec rules check; the contracts list | each module's spec; a platform-only module | A module read with `getEnforcing`, read outside its wrapper, or missing from the contracts list | +| FR2 | Unit tests through the `./testing` doubles in absent, older and current shapes | each synchronous member; each call; a native throw | A synchronous member throws, a call rejects, or answers a reason outside its set | +| FR3 | Unit tests of each store and hook | first subscriber; last unsubscribe; an event before the resync answer; unmount; foreground | A listener hears the current value, a repeat, or a change after unsubscribe; a native subscription outlives the last subscriber | +| FR4 | Unit tests of the scope precedence; Simulator and emulator launches with a saved choice opposite the system; a run-only change and a relaunch; a launch link; a screen with its own choice | saved `dark` under a light system; `persist: false`; launch link cold, and a later link that changes nothing; a screen choice over a session override | The first frame shows the system's style, a run-only change survives a relaunch, or a narrower scope loses to a wider one | +| FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | +| FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | +| FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | +| FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | +| FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | +| FR10 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | +| FR11 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | +| FR12 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | +| FR13 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | +| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, a URI that is not a `file://` URI, or a core piece that deletes files there | +| FR15 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | +| FR16 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | +| FR17 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the baseline path or `unsupported`, or no warning | +| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | ## Decision log From c839f3be49dd8b8cd6b5f33bd021ca8101f8f004 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 01:43:46 -0800 Subject: [PATCH 25/32] spec(AST-130): shell-bound steps without the generated shell; contractFeatures never throws; cold launch is the first window scene --- .../AST-130-react-native-system-modules/spec.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 381058499889d..39b4147ba6de3 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -131,6 +131,11 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. only by its own wrapper (`spec:AST-140/FR1`, FR2), and its wrapper answers `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` have no public object: the library is their one caller. + - The native appearance step (FR4), the back gate (FR10) and the launch hold + (FR11) act in the package's generated native shell. In an app whose shell + lacks them, the saved appearance applies only once JavaScript sets it, + after the first frame; every back press goes to React Native; and there is + no launch hold. | Contract | Kind | Methods | Platforms | | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------ | @@ -148,11 +153,12 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - **FR2 — Constants are synchronous; everything else is a result.** - What the system knows at launch is a launch value, read once and then answered synchronously: the saved appearance and the run's override, the - accessibility snapshot, the app's version, build, identifier and install - time, the linked capabilities, the named contract features, and the + accessibility snapshot, the app's version, build, identifier and install or + last update time, the linked capabilities, the named contract features, and the process start. Synchronous members (`isAvailable()`, `getOverride()`, `getRunOverride()`, `current()`, `app`, - `capabilities`, `launch`, and `AstryxLaunch`'s `initialURL()`) never + `capabilities`, `contractFeatures`, `launch`, and `AstryxLaunch`'s + `initialURL()`) never throw; they answer `null`, `'system'`, or all-false where the module or the constant is absent. @@ -235,7 +241,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. (default: off), a link on one of the app's own schemes whose named query parameter is `light`, `dark` or `system` applies that appearance natively as a run-only override at cold launch only: when the first activity is - created on Android, and when the scene connects on iOS, before the first + created on Android, and when the app's first window scene connects on iOS, + before the first frame (feature `launch-link`). Nothing is saved. A link that arrives later (a new intent, or a scene URL) never changes the appearance; navigation from it uses the screen's own `appearance` option (`spec:AST-125/FR7`). From 1b4b13a010048107936a45f8171de1a9f10ecf16 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 02:21:30 -0800 Subject: [PATCH 26/32] spec(AST-130): the app's configuration and the generated native project carry the launch link and permissions --- docs/specs/AST-130-react-native-system-modules/spec.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 39b4147ba6de3..cb803be4062b0 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -237,8 +237,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - `getRunOverride()` (feature `run-override`) answers the run's own override synchronously, or `null` when the saved choice is in force, so the first render matches the first frame. - - With the configuration plugin's `appearance.launchLinkParameter` set - (default: off), a link on one of the app's own schemes whose named query + - With `appearance.launchLinkParameter` set in the app's configuration + (default: off), which the generated native project carries + (`spec:AST-112/FR4`), a link on one of the app's own schemes whose named query parameter is `light`, `dark` or `system` applies that appearance natively as a run-only override at cold launch only: when the first activity is created on Android, and when the app's first window scene connects on iOS, @@ -329,7 +330,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. Simulator and an emulator without a camera; `null` where the platform does not say. - A permission the app did not declare answers `not-declared` and shows no - prompt; the configuration plugin declares it when the app opts the + prompt. The generated native project declares it when the app opts the capability in (`spec:AST-112/FR4`). - Where the module is absent, Android answers through React Native's `PermissionsAndroid` (which reads `undetermined` until a `request` in this From 9e833c445dd29757c043cd7f3a3d0c96889047d0 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 03:01:39 -0800 Subject: [PATCH 27/32] spec(AST-130): current-state impact against the amended AST-112 FR5 and FR7 --- .../AST-130-react-native-system-modules/spec.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index cb803be4062b0..d6debf4854ba8 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -508,15 +508,14 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. API only. - Relies on `spec:AST-112` FR20 (amended): the package covers the native code Astryx itself uses; every module of this group is such code. -- Changes `spec:AST-112/FR1`: the core's list gains appearance, accessibility - settings, platform info, the Android back gate and launch hold, and the - file picker; the `camera` capability gains camera capture, the camera source - of a picker included (FR12). -- Changes `spec:AST-112` FR1 and FR5 (amended): cookies leave the core's list - and the `./network` entry, since no Astryx component uses them; the network - state and secure random bytes are already outside the amended core. -- Changes `spec:AST-112/FR1` and FR3: the core links no web engine, and - clearing web view data has no Astryx call (FR18). +- Is the System modules group record that `spec:AST-112/FR7` names: it lists + the group's ten core modules and the core cache location (FR1, FR14). +- Changes `spec:AST-112/FR5`: the `./network` entry and its cookies leave the + package's app API, since no Astryx component uses them. +- Camera capture, the camera source of a picker included, is the `camera` + capability's (`spec:AST-112/FR7`; FR12). +- The core links no web engine, and clearing web view data has no Astryx call + (FR18). - Departs from `spec:AST-112/FR7` ("never a silent no-op") for the calls that return nothing (FR2); OQ2 asks whether the exception stands. - Details `spec:AST-112` FR7 (each module's probes) and FR9 (the haptic moment mapping), and `spec:AST-140/FR3` From d6680ecc3693d635b11af577e9072960988186ec Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 11:37:45 -0800 Subject: [PATCH 28/32] spec(AST-130: system modules describe current behaviour; drop memory, bundle size and update-check storage) --- .../spec.md | 312 ++++++++---------- 1 file changed, 129 insertions(+), 183 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index d6debf4854ba8..704a37bbc9772 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -46,7 +46,7 @@ links them. The shared platform rules are ## Why this exists -The package takes no runtime dependency outside React and React Native +The package depends on React and React Native alone at run time (`spec:AST-112/FR2`); apps may use third-party libraries, haptics libraries included, beside these modules without conflict (`spec:AST-140/FR9`). Each module exists for one concrete gap; where the gap is small, OQ1 keeps the scope open. @@ -55,100 +55,73 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. frame of every launch. A choice that JavaScript applies arrives a frame late, so the window and the status bar change after the app appears. - `AstryxAccessibilitySettings`: one snapshot that is ready for the first - frame, a change event for every key, and the iOS settings that React - Native's accessibility API does not read. + frame, a change event for every key, and the iOS settings beyond those + React Native's accessibility API reads. - `AstryxHaptics`: a small gap. The theme maps moments to feedback kinds, and Android plays the view feedback its API level has (OQ1). -- `AstryxClipboard`: no capability gap. The module gives the result - vocabulary with no extra dependency (OQ1). +- `AstryxClipboard`: the pasteboard with the result vocabulary, from the + package's own native code (OQ1). - `AstryxPlatformInfo`: the binary's own contract facts (linked capabilities and named features), which only the binary can report. - `AstryxPermissions`: a small gap. A closed set of permissions tied to the - capabilities, with `not-declared` where the system would end the app (OQ1). -- `AstryxBack`: React Native's activity takes every back press, so Android's - back-to-home animation never plays at the root without this gate. + camera and photo capabilities, with `not-declared` where the system would + end the app (OQ1). +- `AstryxBack`: React Native's activity takes every back press; this gate + hands the root press to the system, so Android plays its back-to-home + animation. - `AstryxLaunch`: the library ends Android's launch hold at its first content with no app code, and the router reads the launch link synchronously. - `AstryxFilePicker`: a small gap. One call over photos and files with the result vocabulary (OQ1). -- `AstryxStorage`: a small gap. One string store with the result vocabulary - and no extra dependency (OQ1). +- `AstryxStorage`: a small gap. One string store with the result vocabulary, + from the package's own native code, where the router keeps its state (OQ1). ## Who uses it -| Native piece | Kind | Astryx components that use it | What a person sees | -| ----------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `AstryxAppearance` | native module (Turbo Native Module) | `AstryxProvider`, the theme provider every Astryx component renders under, which applies the app's light or dark override through it; app API (`.` entry) | The app opens in the saved light or dark appearance, with no flash of the system's. | -| `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | -| `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | -| `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | -| `AstryxPlatformInfo` | native module (Turbo Native Module) | Its named-feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), and the zoom pager gesture; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | -| `AstryxPermissions` | native module (Turbo Native Module) | No library component. `CameraView` (`./camera` entry) reads it; app API `useCameraPermission` | The system prompt appears only when the app asks, never when a view mounts. | -| `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | -| `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | -| `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | -| `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store) and the app update check's "Not now"; app API (`./storage` entry) | After a cold start the app opens on the screen it showed last; a dismissed update stays dismissed. | -| React Native `Linking` | React Native core API (no Astryx native module) | Every `href` the library renders, through its link helper and host services: `Link`, `Button`, `Chip`, `ClickableCard`, `Item`, `Avatar`, `Breadcrumbs`, `Citation`, `ContextMenu` and `DropdownMenu` items, `Markdown` links, `SideNav`, `NavMenu` and `Tab`; the router's external links; the `camera` template's "open Settings" | A tapped link opens in the system's browser or the app that owns it; a blocked camera permission opens the app's Settings. | -| React Native `Share` | React Native core API (no Astryx native module) | The library's host services (`useHostServices().share`), which the `create` templates' share actions use (assistant, camera, gallery, maps, text feed) | The system share sheet opens with the item's text or link. | +| Native piece | Kind | Astryx components that use it | What a person sees | +| ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `AstryxAppearance` | native module (Turbo Native Module) | `AstryxProvider`, the theme provider every Astryx component renders under, which applies the app's light or dark override through it; app API (`.` entry) | The app opens in the saved light or dark appearance, with no flash of the system's. | +| `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `AstryxProvider` and every component styled with `createStyles` (`./styles` entry); through the library's system-settings hook also `BottomSheet`, `Popover`, `Overlay`, `HoverCard`, `ContextMenu`, `Switch`, `SegmentedControl`, `ProgressBar`, `Carousel`, `TabBar`, `TopNav`, `Header`, `Toolbar`, `Table`, `Item`, `Markdown`, `SearchField`, `BarButton`, `Button` and the glass and material surfaces; app API `useAccessibilitySettings` | Drawn bars, sheets and menus turn opaque under Reduce Transparency, show borders under Show Borders, and cross-fade under Reduce Motion. | +| `AstryxHaptics` | native module (Turbo Native Module) | Through the library's moment table (`useHaptics`): `Button`, `Switch`, `Slider`, `SegmentedControl`, `Selector`, `TabList`, `ToggleButton`, `Toast`, `BottomSheet`, `InlineSheet`, `ContextMenu`, `ReorderableList`, `Item` swipe actions, `Calendar`'s picker field, `DonutChart` and the charts | A tick on a selection change, a click on a toggle, a bump at a slider's end, a threshold tick in a swipe. | +| `AstryxClipboard` | native module (Turbo Native Module) | `PasteButton` (reads on the person's press); `CodeBlock`, `Chat` message actions and `Timestamp` through the library's copy hook (`useCopy`) | A copy button shows its check glyph and announces "Copied"; a paste fills the field. | +| `AstryxPlatformInfo` | native module (Turbo Native Module) | Its named-feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), and the zoom pager gesture; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | +| `AstryxPermissions` | native module (Turbo Native Module) | `CameraView` (`./camera` entry) reads camera access through it; app API `useCameraPermission` | The system prompt appears only when the app asks. | +| `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | +| `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | +| `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | +| `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store); app API (`./storage` entry) | After a cold start the app opens on the screen it showed last. | +| React Native `Linking` | React Native core API | Every `href` the library renders, through its link helper and host services: `Link`, `Button`, `Chip`, `ClickableCard`, `Item`, `Avatar`, `Breadcrumbs`, `Citation`, `ContextMenu` and `DropdownMenu` items, `Markdown` links, `SideNav`, `NavMenu` and `Tab`; the router's external links; the `camera` template's "open Settings" | A tapped link opens in the system's browser or the app that owns it; a blocked camera permission opens the app's Settings. | +| React Native `Share` | React Native core API | The library's host services (`useHostServices().share`), which the `create` templates' share actions use (assistant, camera, gallery, maps, text feed) | The system share sheet opens with the item's text or link. | ## Non-goals -- The data and security modules (files, secure storage) and their records. -- Capabilities that no Astryx component uses. They are outside the core - package. -- Client identity, crash reports, daily metrics, the frame recorder, and - image markup. They are outside the core package; each has its own record. -- Camera capture. The `camera` capability owns it, the camera source of a - picker included. -- A native module of the package's own for opening links, opening Settings, - or sharing. Astryx components and `create` templates use React Native's own - `Linking` and `Share` for them (see "Who uses it"), so these stay part of what - the core relies on and need no Astryx native code. -- Keep-awake and orientation lock. No Astryx component or `create` template - uses them, so they are outside the core package. -- The theme's tokens and how they change between light and dark. This record - owns the appearance model of FR4, and OQ3 asks how theme colours resolve - when the appearance flips. -- Haptic intensities per moment. The theme's haptic tokens own them - (`spec:AST-112/FR9`). -- Each component's use of these modules beyond what "Who uses it" names; the - component's own record owns it. -- Astryx Stage (`spec:AST-139`) and Preview in the Astryx app (`spec:AST-141`) - are separate products; they conform to this record's contracts. -- 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 — The group is ten core native modules.** Every app links them (`spec:AST-112/FR1`). Each module is read with `TurboModuleRegistry.get`, only by its own wrapper (`spec:AST-140/FR1`, FR2), and its wrapper answers - `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` have - no public object: the library is their one caller. + `no-module` where the module is absent. `AstryxBack` and `AstryxLaunch` are + internal: the library is their one caller. - The native appearance step (FR4), the back gate (FR10) and the launch hold (FR11) act in the package's generated native shell. In an app whose shell - lacks them, the saved appearance applies only once JavaScript sets it, - after the first frame; every back press goes to React Native; and there is - no launch hold. - - | Contract | Kind | Methods | Platforms | - | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------ | - | `AstryxAppearance` | native module (Turbo Native Module) | `getConstants` (`initialOverride`), `setOverride`, `getRunOverride` | iOS, Android | - | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `getConstants` (`initialSettings`), `getSettings`, `onSettingsChange` (event) | iOS | - | `AstryxHaptics` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `play`, `prepare` | iOS, Android | - | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `detectPatterns` | iOS, Android | - | `AstryxPlatformInfo` | native module (Turbo Native Module) | `getConstants` (`app`, `capabilities`, `contractFeatures`, `launch`), `getInfo`, `getMemory`, `getBundleSize` | iOS, Android | - | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | - | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | - | `AstryxFilePicker` | native module (Turbo Native Module) | `getConstants`, `getSources`, `pick` | iOS, Android | - | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo` | iOS, Android | - | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | + lacks them, the saved appearance applies once JavaScript sets it, after + the first frame; every back press goes to React Native; and the app shows + as soon as its window is ready. + + | Contract | Kind | Methods | Platforms | + | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ | ------------ | + | `AstryxAppearance` | native module (Turbo Native Module) | `getConstants` (`initialOverride`), `setOverride`, `getRunOverride` | iOS, Android | + | `AstryxAccessibilitySettings` | native module (Turbo Native Module) | `getConstants` (`initialSettings`), `getSettings`, `onSettingsChange` (event) | iOS | + | `AstryxHaptics` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `play`, `prepare` | iOS, Android | + | `AstryxClipboard` | native module (Turbo Native Module) | `getConstants`, `isSupported`, `write`, `getString`, `detectPatterns` | iOS, Android | + | `AstryxPlatformInfo` | native module (Turbo Native Module) | `getConstants` (`app`, `capabilities`, `contractFeatures`, `launch`), `getInfo` | iOS, Android | + | `AstryxPermissions` | native module (Turbo Native Module) | `getConstants`, `get`, `request` | iOS, Android | + | `AstryxBack` | native module (Turbo Native Module) | `getConstants`, `setRootBackEnabled` | Android | + | `AstryxFilePicker` | native module (Turbo Native Module) | `getConstants`, `getSources`, `pick` | iOS, Android | + | `AstryxStorage` | native module (Turbo Native Module) | `getConstants`, `getItem`, `setItem`, `removeItem`, `getAllKeys`, `clear`, `getInfo` | iOS, Android | + | `AstryxLaunch` | native module (Turbo Native Module) | `getConstants`, `firstContent`, `initialURL` | Android | - **FR2 — Constants are synchronous; everything else is a result.** - What the system knows at launch is a launch value, read once and then @@ -158,33 +131,31 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. process start. Synchronous members (`isAvailable()`, `getOverride()`, `getRunOverride()`, `current()`, `app`, `capabilities`, `contractFeatures`, `launch`, and `AstryxLaunch`'s - `initialURL()`) never - throw; they - answer `null`, `'system'`, or all-false where the module or the constant is - absent. - - Every asynchronous call resolves `AstryxResult` and never rejects - (`spec:AST-140/FR3`). Each module adds only these reasons to the common - ones: + `initialURL()`) always return: they answer `null`, `'system'`, or + all-false where the module or the constant is absent. + - Every asynchronous call resolves an `AstryxResult`, failures included + (`spec:AST-140/FR3`). Each module adds these reasons to the common ones: | Module | Module reasons | | ----------------------------- | -------------------------------------------------------------------------------- | | `AstryxAppearance` | `invalid` (not `light`, `dark` or `system`) | | `AstryxAccessibilitySettings` | `unavailable` (the module is torn down during a reload) | | `AstryxClipboard` | `unavailable` (no pasteboard on this device) | - | `AstryxPlatformInfo` | `unavailable` (the system did not answer a measure) | + | `AstryxPlatformInfo` | `unavailable` (the system did not answer a read) | | `AstryxPermissions` | `unknown-permission`, `busy`, `no-activity` (Android), `not-declared` | | `AstryxFilePicker` | `unsupported-source`, `no-window`, `busy`; `cancelled` when the person backs out | | `AstryxStorage` | `invalid-key`, `invalid-value`, `invalid-json`, `no-space`, `io`, `no-namespace` | - - `AstryxHaptics.play` and `prepare` return nothing: they play or do nothing, - and `isAvailable()` says which. `setRootBackEnabled` and `firstContent` - return nothing either; they are hints that the native side may ignore. + - `AstryxHaptics.play` and `prepare` return no value: they play where the + device can, and `isAvailable()` says whether it can. `setRootBackEnabled` + and `firstContent` return no value either; they are hints the native side + follows where it can. - **FR3 — Change events start with the first subscriber and stop after the last.** - - `AstryxAccessibilitySettings.subscribe` calls the listener with each real change, never with the current value, and - return the unsubscribe function. A native event that repeats an unchanged - value is not delivered. + - `AstryxAccessibilitySettings.subscribe` calls the listener with each real + change and returns the unsubscribe function. The listener hears changed + values only; `current()` answers the value in force. - A module follows native changes only while at least one listener is subscribed. After the last unsubscribe it stops; until the next subscribe, a read answers the last value it followed, and the next first subscriber @@ -225,13 +196,13 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. the session's over the preference, and the preference over the system's appearance. The theme provider resolves the scopes in one place and gives every component and the app one resolved read of the appearance in force. - - FR4 gap: the theme provider follows React Native's colour scheme and does - not call `AstryxAppearance`; an app calls `setOverride` itself and writes + - FR4 gap: the theme provider follows React Native's colour scheme alone; + an app calls `setOverride` itself and writes the precedence across the saved choice, the run's override, a screen's option and the system's scheme. - `setOverride(value, {persist: false})` (feature `persist-false`) applies the - choice for this run only and saves nothing. `getOverride()` and the next - launch keep the saved choice. A saving `setOverride` ends the run-only + choice for this run only; the saved choice stays as it was, and + `getOverride()` and the next launch keep it. A saving `setOverride` ends the run-only override, so `setOverride(getOverride())` restores the saved choice and `getRunOverride()` then answers `null`. - `getRunOverride()` (feature `run-override`) answers the run's own override @@ -244,9 +215,10 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. as a run-only override at cold launch only: when the first activity is created on Android, and when the app's first window scene connects on iOS, before the first - frame (feature `launch-link`). Nothing is saved. A link that arrives later - (a new intent, or a scene URL) never changes the appearance; navigation - from it uses the screen's own `appearance` option (`spec:AST-125/FR7`). + frame (feature `launch-link`). The saved choice stays as it was. A link + that arrives later (a new intent, or a scene URL) navigates, and the + screen it opens sets its look through its own `appearance` option + (`spec:AST-125/FR7`). - FR4 gap: a link that arrives while the app runs applies its appearance as a run-only override too. @@ -262,10 +234,9 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. is false, `getSettings()` answers `no-module`, and the snapshot comes from React Native's `AccessibilityInfo`: Reduce Motion everywhere, high text contrast as `isIncreaseContrast` on Android, and the iOS settings it reads. - Keys `AccessibilityInfo` cannot read stay false. - - The snapshot has no key for Liquid Glass's Clear or Tinted look, because the - system gives apps no way to read that setting. Native glass follows it; - drawn chrome does not. + Every other key reads false. + - Native glass follows the system's Clear or Tinted Liquid Glass look + itself; drawn chrome follows the seven keys of the snapshot. - **FR6 — `AstryxHaptics` plays the platform's feedback kinds.** - `play(kind)` plays one of UIKit's nine kinds: `selection`, `impactLight`, @@ -276,8 +247,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - Android plays a chain of `HapticFeedbackConstants` names, in order of preference, on the root view of the activity in front: the first name the device's API level knows. Each kind has a default chain; `play(kind, {android})` passes another. - - `isAvailable()` is false where the module is absent or `isSupported()` is - false (no haptic hardware, or no window). `play` and `prepare` do nothing + - `isAvailable()` is true where the module is present and `isSupported()` + is true (haptic hardware and a window); `play` and `prepare` play feedback then. - The library maps its moments (select, toggle, edge, threshold arm and disarm, commit and others) to kinds through the theme's haptic tokens, each @@ -290,11 +261,12 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - `getString()` answers `{value}`, with `null` for an empty or non-text pasteboard. A read shows the system's paste notice on iOS 16 and later and Android 12 and later, so the library reads only on the person's action - (`PasteButton`); copy buttons never read. + (`PasteButton`), and copy buttons only write. - `detectPatterns(['webURL' | 'webSearch' | 'number'])` answers whether the - pasteboard probably holds each pattern, without reading the content and - without a paste notice. The answer omits every pattern the platform cannot - test: Android tests only for a web URL, and only from Android 12. + pasteboard probably holds each pattern. It reads only the pasteboard's + metadata, so the system shows its paste notice for reads alone. The answer + carries the patterns the platform tests: all three on iOS, and a web URL + on Android 12 and later. - `isAvailable()` is false where the module is absent or `isSupported()` is false; calls then answer `no-module` or `unavailable`. @@ -312,16 +284,12 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. self-checks of the platform internals the package relies on (`compat`). `supports(name)` reads a feature row from the last answer and is `null` while it is unknown. - - `memory()` answers the process's memory in bytes, counted the way each - platform counts it (iOS `phys_footprint`, Android total PSS); the iOS and - Android numbers do not compare. `bundleSize()` answers the installed app's size on disk, read - off the main thread. - **FR9 — `AstryxPermissions` reads and asks explicitly.** - - `get(name)` never prompts. `request(name)` shows the system prompt only for - `undetermined` (and Android `denied`), then answers the state; otherwise it - answers the current state at once. Mounting a view never prompts - (`spec:AST-112/FR7`). + - `get(name)` reads the state silently. `request(name)` shows the system + prompt for `undetermined` (and Android `denied`), then answers the state; + otherwise it answers the current state at once. The prompt comes only from + `request` (`spec:AST-112/FR7`). - `name` is a closed set (`camera`). The states are `granted`, `undetermined`, `denied` (refused; the app may ask again) and `blocked` (the person can change it in Settings only: iOS `denied` or `restricted`, @@ -329,8 +297,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - `hasHardware` says whether the device has the hardware: false on the iOS Simulator and an emulator without a camera; `null` where the platform does not say. - - A permission the app did not declare answers `not-declared` and shows no - prompt. The generated native project declares it when the app opts the + - A permission the app has not declared answers `not-declared` at once. The generated native project declares it when the app opts the capability in (`spec:AST-112/FR4`). - Where the module is absent, Android answers through React Native's `PermissionsAndroid` (which reads `undetermined` until a `request` in this @@ -345,30 +312,29 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. back-to-home animation (Android 16 predictive back). - Until the library reports for the first time, and after its runtime stops, back presses go to React Native unchanged. - - iOS has no module: back is native there. + - On iOS back is native, so the module is Android-only. - **FR11 — `AstryxLaunch` hands Android's cold launch to the first content.** - The shell activity keeps the system's launch window (the splash screen on API 31 and later, the window background before) until the library calls `firstContent()`, so no blank frame appears between the launch window and - the first screen. When no call arrives within 2.5 seconds, it shows the app - anyway. + the first screen. After 2.5 seconds without a call, it shows the app. - The library calls it once per runtime: from the router's first focused screen's first content layout, or from `AstryxPerformance.markFirstFrame`, - whichever comes first. Later calls do nothing. + whichever comes first; that first call ends the hold. - `initialURL()` answers the launch link synchronously (what `Linking.getInitialURL()` answers), or `null` when the app launched without one. The router builds its first state from it, so a cold deep - link draws its own screen first. Where the platform cannot answer - synchronously (iOS, an absent module), the - router reads `Linking.getInitialURL()`. - - iOS has no module: its launch screen stays until the first frame. + link draws its own screen first. On iOS, and where the module is absent, + the router reads `Linking.getInitialURL()`. + - On iOS the launch screen stays until the first frame, so the module is + Android-only. - **FR12 — `AstryxFilePicker` presents the system's pickers.** - `sources()` lists what the device offers, in menu order: `photos` and - `files`. It is empty where the module is absent. Camera capture is the - `camera` capability's (`./camera` entry), never a source of the core - picker, so the core needs no camera permission or usage string. + `files`. It is empty where the module is absent. Camera capture belongs to + the `camera` capability (`./camera` entry); the core picker's two sources + work without a camera permission or usage string. - `pick({source, isMultiple?, limit?, media?, accept?}, events?)` presents one picker over the calling surface and resolves `{ok: true, files}` with at least one file, `cancelled` when the person backs out, or a reason: a source the @@ -376,8 +342,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. platform's message, and a second picker while one is open answers `busy`. Each file has `uri`, `name`, `size` (`-1` when the provider does not say) and `type`. - - iOS: `photos` is `PHPickerViewController` (out of process, so no photo - library permission) and `files` is `UIDocumentPickerViewController`. Each picked file is copied into the + - iOS: `photos` is `PHPickerViewController` (out of process, so it works + without photo library permission) and `files` is `UIDocumentPickerViewController`. Each picked file is copied into the app's cache location (FR14) and returned as a `file://` URL; the photo picker closes before it loads and copies, and `events.onLoading()` (no argument) is called once when that loading step starts. @@ -400,13 +366,11 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. `getJSON` and `setJSON` parse and serialize (`invalid-json`). `info()` answers the namespace, the key count, the bytes the store takes on disk, and the free space (`null` when the platform does not say). - - Every call works in the calling runtime's namespace, decided natively and - never by JavaScript; `info()` names it. + - Every call works in the calling runtime's namespace. Native code decides + the namespace, and `info()` names it. - Values are kept across launches in storage the system keeps for the app. - The package sets no size limit; only the device's free space limits a - value. - - The router's state persistence uses it as its default store, and the app - update check keeps its "Not now" in the app's namespace. + The device's free space bounds a value's size. + - The router's state persistence uses it as its default store. - **FR14 — The core package owns the app's cache location.** - The core package owns one cache location for the app. Pieces that produce @@ -414,16 +378,15 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. (FR12), which `FileInput` uses, and the `camera` capability's camera view. - The system may reclaim the location under storage pressure. A caller that needs a file to last copies it elsewhere. - - Deleting files in the location is outside the core package. - **FR15 — Threads and lifecycle.** The threading rules of `spec:AST-140/FR6` apply; for this group: - Constants are read on the JavaScript thread once per module, at the first call that needs them. Asynchronous calls do their native work off the - JavaScript thread, and a measure that walks files (`bundleSize()`) runs off - the main thread. - - The appearance override and the root back gate act on the UI thread at - once; neither waits for a JavaScript round trip per frame. + JavaScript thread. + - The appearance override and the root back gate act natively on the UI + thread at once, so each frame follows them without a JavaScript round + trip. - Native events reach JavaScript on the JavaScript thread, once per real change. - A call made while its module is torn down during a reload answers @@ -437,33 +400,28 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. and Reduce Motion with `prefersCrossFadeTransitions` replaces motion with cross-fades within the limits of `spec:AST-108`. The theme's style helper gives every key to component styles. - - Haptic feedback is never the only signal: each moment goes with a visual - change, and a copy also announces "Copied" through the status - announcements of `spec:AST-086`. - - These modules expose nothing to VoiceOver or TalkBack themselves; they have - no view. + - Every haptic moment goes with a visual change, and a copy also announces + "Copied" through the status announcements of `spec:AST-086`. - **FR17 — The group's named features.** - - Each contract's baseline is its first release's shape - (`spec:AST-140/FR5`). The group's - named features are `AstryxAppearance.persist-false`, + - Contracts grow by named features (`spec:AST-140/FR5`). The group's named + features are `AstryxAppearance.persist-false`, `AstryxAppearance.run-override` and `AstryxAppearance.launch-link`, and `AstryxPlatformInfo`'s `contractFeatures` constant is the list a binary - reports; the list itself adds no behaviour. - - Without a feature: `setOverride` with `persist: false` answers - `unsupported` and saves nothing, `getRunOverride()` answers `null` (such a - binary has no run-only override), and the launch link does nothing. A - missing feature is reported once with a development warning. - -- **FR18 — Public platform API only, and no web engine in the core.** - - The native code of every module in the group uses public platform API - only; the group needs no exception. - - The core reaches neither WebKit (iOS) nor androidx.webkit (Android). - Clearing web view data has no Astryx call and is outside the core package; - an app that needs it uses its host platform's implementation - (`spec:AST-112/FR20`). The web view's own data rules are `spec:AST-131`'s. - - FR18 gap: on iOS the core's storage module links WebKit to remove web - view data. + reports. + - In a binary without a feature: `setOverride` with `persist: false` + answers `unsupported` and the saved choice stays; `getRunOverride()` + answers `null`; and the app opens in the saved appearance whatever the + launch link says. A missing feature is reported once with a development + warning. + +- **FR18 — The group's native code uses public platform API.** + - The native code of every module in the group uses public platform API. + - Each module links the system frameworks the platform support table names + for it. The web engine and the web view's data belong to the `web` + capability (`spec:AST-131`). + - FR18 gap: on iOS the core's storage module also links WebKit, to remove + web view data. ### Platform support @@ -473,7 +431,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | `AstryxAccessibilitySettings` | UIKit accessibility status and notifications; the Accessibility framework for 26.1 and later keys | No module; `AccessibilityInfo` fallback (FR5) | | `AstryxHaptics` | `UIFeedbackGenerator` subclasses, prepared and cached | `HapticFeedbackConstants` on the activity's root view, by API level | | `AstryxClipboard` | `UIPasteboard`, with pattern detection | `ClipboardManager`; the clip description's URL confidence on Android 12 and later | -| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm`, `task_vm_info` | `PackageInfo`, `Process.getStartElapsedRealtime()`, `Debug.MemoryInfo`, APK sizes | +| `AstryxPlatformInfo` | Bundle info, `sysctl` process start, `ActivePrewarm` | `PackageInfo`, `Process.getStartElapsedRealtime()` | | `AstryxPermissions` | `AVCaptureDevice` authorization | Runtime permission with its "don't ask again" state; `PermissionsAndroid` without the module | | `AstryxFilePicker` | `PHPickerViewController`, `UIDocumentPickerViewController` | Photo Picker, Storage Access Framework | | `AstryxStorage` | Application Support | The app's internal files directory | @@ -501,9 +459,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. text. - Relies on `spec:AST-112` FR3 (amended): the core links in every app, and every module of this group is core. -- Relies on `spec:AST-140` FR5: each contract's baseline is its first - release's shape, and later - behaviour is a named feature that the platform info module reports. +- Relies on `spec:AST-140` FR5: contracts grow by named features, which the + platform info module reports. - Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform API only. - Relies on `spec:AST-112` FR20 (amended): the package covers the native code @@ -514,10 +471,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. package's app API, since no Astryx component uses them. - Camera capture, the camera source of a picker included, is the `camera` capability's (`spec:AST-112/FR7`; FR12). -- The core links no web engine, and clearing web view data has no Astryx call - (FR18). -- Departs from `spec:AST-112/FR7` ("never a silent no-op") for the calls that - return nothing (FR2); OQ2 asks whether the exception stands. +- Details an exception to `spec:AST-112/FR7` for the hint calls that return + no value (FR2); OQ2 asks whether the exception stands. - Details `spec:AST-112` FR7 (each module's probes) and FR9 (the haptic moment mapping), and `spec:AST-140/FR3` (each module's results). @@ -532,17 +487,17 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | FR5 | Unit tests of the snapshot and the fallback; Simulator runs per setting | each key on and off; Android; module absent | A key missing, an unchanged snapshot delivered, or the first frame drawn before the snapshot | | FR6 | Unit tests of the moment table and the Android chain; a device check of feel | each kind; an API level without the preferred constant; no hardware; a theme token `'none'` | A kind plays the wrong constant, plays where unavailable, or a silenced token plays | | FR7 | Unit tests; Simulator and emulator copy and paste | write; empty read; non-text read; pattern detection on Android 11 and 12 | A copy button reads, a detection reads the content, or an unknown key is answered | -| FR8 | Unit tests; Simulator and emulator reads | constants; `get()`; memory and size | A constant throws, or a measure answers in another unit | +| FR8 | Unit tests; Simulator and emulator reads | constants; `get()` | A constant throws, or `get()` answers a feature row the binary does not report | | FR9 | Unit tests; Simulator and emulator prompts | each state; undeclared permission; a busy prompt; module absent on each platform | A mount prompts, a `blocked` permission prompts, or an undeclared permission crashes | | FR10 | Unit tests of the back gate; emulator runs on Android 16 | an open sheet; a navigator that can go back; the root; before the first call | The back-to-home animation does not play at the root, or a press with a consumer reaches the system | | FR11 | Unit tests of the once-per-runtime report and the synchronous link; emulator cold launches | a launch with and without a link; a launch that never reports | An empty root frame shows before the first content, the hold never ends, or a cold deep link draws another screen first | | FR12 | Unit tests through the `./testing` doubles; Simulator and emulator picks | each source; multiple; cancel; a source the device does not offer; a second pick while one is open | A cancel reads as an error, an empty `ok` list, a camera source in the core picker, or two pickers at once | | FR13 | Unit tests through the `./testing` doubles; Simulator and emulator runs | two runtimes; a full disk | One runtime reads another runtime's data, or a full disk answers anything but `no-space` | -| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, a URI that is not a `file://` URI, or a core piece that deletes files there | +| FR14 | Unit tests of each piece that produces files; Simulator and emulator runs | a picked photo; a camera photo; storage pressure | A file written outside the cache location, or a URI that is not a `file://` URI | | FR15 | UI-thread frame checks during an appearance change; reload tests | appearance change while scrolling; a reload with subscribers | JavaScript runs per frame for the change, or a subscription survives a reload | | FR16 | Simulator runs per accessibility setting; announcement tests | Reduce Transparency; Show Borders; Reduce Motion; a copy | Drawn chrome ignores a setting, or a copy confirms with haptics alone | | FR17 | The platform's spec rules check; unit tests with a binary that lacks each feature | each named feature present and absent | A behaviour runs without its feature, a missing feature answers anything but the baseline path or `unsupported`, or no warning | -| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | WebKit or androidx.webkit linked into a core-only build, or a private API call in the group's native code | +| FR18 | Binary symbol and linked-framework check of a core-only build; review of each native change for private API | a core-only iOS and Android build | A framework outside the platform support table linked by the group's native code, or a private API call in it | ## Decision log @@ -559,9 +514,6 @@ save nothing. The preference, session and screen scopes form one model whose precedence the library owns, so an app reads one resolved appearance instead of combining the inputs itself. -Rejected: applying the choice from JavaScript at start, because the first -frame cannot follow it. - ### DEC-2 — Accessibility settings are one snapshot with a fallback **Reference:** `spec:AST-130/DEC-2` @@ -570,7 +522,7 @@ frame cannot follow it. Drawn chrome needs every setting that native glass and system bars follow, in the first frame, so the module publishes them together as constants and one event. Where the module is absent, React Native's `AccessibilityInfo` answers -the keys it can, so the library never needs two code paths. +the keys it can, so the library has one code path. ### DEC-3 — Android's root back press belongs to the system unless JavaScript can use it @@ -582,9 +534,6 @@ The library knows whether anything can consume it, so it publishes that fact and the activity follows; the system then plays its own back-to-home animation at the root. -Rejected: a JavaScript handler that exits the app, because the system's -animation cannot play from it. - ### DEC-4 — The library ends the Android launch hold **Reference:** `spec:AST-130/DEC-4` @@ -595,9 +544,6 @@ window with no app code, and a time bound keeps a broken launch visible. The launch link is read synchronously so the router's first state is the linked screen. -Rejected: an app-called hide, because every app would need the step and a -missed call holds the splash. - ### DEC-5 — Thin modules stay dependency-free wrappers **Reference:** `spec:AST-130/DEC-5` @@ -606,7 +552,7 @@ missed call holds the splash. Haptics, the clipboard, permissions, the file pickers and storage are small wrappers where the ecosystem has good libraries. They stay Astryx modules because the -package takes no runtime dependency outside React and React Native +package depends on React and React Native alone at run time (`spec:AST-112/FR2`), and because each needs the result vocabulary. DEC-5 holds until OQ1 is answered. @@ -621,7 +567,7 @@ answered. - **OQ2 — Do the calls that return nothing keep doing nothing where they cannot act?** (`human-api`) `AstryxHaptics.play` and `prepare`, and the back and launch hints, do nothing where the module is absent or - unsupported, which `spec:AST-112/FR7` forbids as a silent no-op. Options: + unsupported, which `spec:AST-112/FR7` counts as a silent no-op. Options: `spec:AST-112/FR7` names them as an exception, with `isAvailable()` saying when they do nothing; or each gains a result that answers why it did not act. From d1726c11b44b66af246171a77eccfcb2a6701f15 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:04:03 -0800 Subject: [PATCH 29/32] spec(AST-130): keep the template's standing Non-goals bullets --- docs/specs/AST-130-react-native-system-modules/spec.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 704a37bbc9772..22d76937e2f5e 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -95,7 +95,14 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. ## 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 cdd7955b60247af52a6181975eb55625dea40372 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:32:51 -0800 Subject: [PATCH 30/32] spec(AST-130): Permissions serves the camera; restore the FR7 departure; drop the network line --- .../specs/AST-130-react-native-system-modules/spec.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 22d76937e2f5e..43bc07afeac5f 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -64,8 +64,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. - `AstryxPlatformInfo`: the binary's own contract facts (linked capabilities and named features), which only the binary can report. - `AstryxPermissions`: a small gap. A closed set of permissions tied to the - camera and photo capabilities, with `not-declared` where the system would - end the app (OQ1). + camera capability, with `not-declared` where the system would end the app + (OQ1). - `AstryxBack`: React Native's activity takes every back press; this gate hands the root press to the system, so Android plays its back-to-home animation. @@ -474,12 +474,11 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. Astryx itself uses; every module of this group is such code. - Is the System modules group record that `spec:AST-112/FR7` names: it lists the group's ten core modules and the core cache location (FR1, FR14). -- Changes `spec:AST-112/FR5`: the `./network` entry and its cookies leave the - package's app API, since no Astryx component uses them. - Camera capture, the camera source of a picker included, is the `camera` capability's (`spec:AST-112/FR7`; FR12). -- Details an exception to `spec:AST-112/FR7` for the hint calls that return - no value (FR2); OQ2 asks whether the exception stands. +- Departs from `spec:AST-112/FR7` ("never a silent no-op") for the hint calls + that return no value (FR2); OQ2 asks whether FR7 names them as an + exception. - Details `spec:AST-112` FR7 (each module's probes) and FR9 (the haptic moment mapping), and `spec:AST-140/FR3` (each module's results). From 46f5d11ff31918a770a7bc5402d6d4e463c5074f Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:02:46 -0800 Subject: [PATCH 31/32] spec(AST-130): define the app call that ends Android's launch hold --- .../specs/AST-130-react-native-system-modules/spec.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 43bc07afeac5f..3e4b54118d04e 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -87,7 +87,7 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. | `AstryxPlatformInfo` | native module (Turbo Native Module) | Its named-feature probes: every component that renders an `Icon` (where icon images load), the system menu of `ContextMenu`, `DropdownMenu` and `Selector`, the native presentation host of `BottomSheet` and modal windows, `Item` (native swipe-row support), the router's stack navigator (modal presentation kinds, header search field, stack host), and the zoom pager gesture; app API | Nothing directly: each component picks the native path the binary has, or its drawn fallback. | | `AstryxPermissions` | native module (Turbo Native Module) | `CameraView` (`./camera` entry) reads camera access through it; app API `useCameraPermission` | The system prompt appears only when the app asks. | | `AstryxBack` | native module (Turbo Native Module) | Through the library's back handling: `AppShell`, `SearchField`, the router's stack navigator (back, modals, header search field), and the dismissible layers `BottomSheet`, `Drawer`, `Popover`, `HoverCard`, `ContextMenu`, `DropdownMenu`, `Selector`, `SplitView`, `TabMenu`, `TopNav` menus | Back closes the open sheet or menu first; at the root, Android plays its back-to-home animation. | -| `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout) and `AstryxPerformance.markFirstFrame` | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | +| `AstryxLaunch` | native module (Turbo Native Module) | The router (its root's first state and its first focused screen's layout); app API `AstryxPerformance.markFirstFrame` for an app on another router | On Android the launch screen stays until the first screen is drawn, and a cold deep link opens on its own screen. | | `AstryxFilePicker` | native module (Turbo Native Module) | `FileInput` through the library's file picker hook (`useFilePicker`); app API `AstryxFilePicker` | Choosing a file opens the system's photo or document picker; backing out changes nothing. | | `AstryxStorage` | native module (Turbo Native Module) | The router's state persistence (its default store); app API (`./storage` entry) | After a cold start the app opens on the screen it showed last. | | React Native `Linking` | React Native core API | Every `href` the library renders, through its link helper and host services: `Link`, `Button`, `Chip`, `ClickableCard`, `Item`, `Avatar`, `Breadcrumbs`, `Citation`, `ContextMenu` and `DropdownMenu` items, `Markdown` links, `SideNav`, `NavMenu` and `Tab`; the router's external links; the `camera` template's "open Settings" | A tapped link opens in the system's browser or the app that owns it; a blocked camera permission opens the app's Settings. | @@ -326,9 +326,14 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. API 31 and later, the window background before) until the library calls `firstContent()`, so no blank frame appears between the launch window and the first screen. After 2.5 seconds without a call, it shows the app. - - The library calls it once per runtime: from the router's first focused - screen's first content layout, or from `AstryxPerformance.markFirstFrame`, + - The library calls it once per runtime: from the Astryx router's first + focused screen's first content layout, or from `AstryxPerformance.markFirstFrame()`, whichever comes first; that first call ends the hold. + - `AstryxPerformance.markFirstFrame()` (`.` entry) is the app API for an app whose first + screen comes from another router: the app calls it from its first + screen's first content layout, and the library passes it to + `firstContent()`. An app on the Astryx router makes no call. On iOS, and + where the module is absent, it returns at once. - `initialURL()` answers the launch link synchronously (what `Linking.getInitialURL()` answers), or `null` when the app launched without one. The router builds its first state from it, so a cold deep From 7d9eccb0c5f627ecc1e50158c32f21843b738c84 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Thu, 19 Nov 2026 15:37:46 -0800 Subject: [PATCH 32/32] spec(AST-130): public platform API cites AST-140 FR9 and DEC-9 --- docs/specs/AST-130-react-native-system-modules/spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specs/AST-130-react-native-system-modules/spec.md b/docs/specs/AST-130-react-native-system-modules/spec.md index 3e4b54118d04e..3e0c1a768c8f9 100644 --- a/docs/specs/AST-130-react-native-system-modules/spec.md +++ b/docs/specs/AST-130-react-native-system-modules/spec.md @@ -473,8 +473,8 @@ concrete gap; where the gap is small, OQ1 keeps the scope open. every module of this group is core. - Relies on `spec:AST-140` FR5: contracts grow by named features, which the platform info module reports. -- Relies on `spec:AST-112` DEC-15 (amended): native code uses public platform - API only. +- Relies on `spec:AST-140/FR9` and `spec:AST-140/DEC-9`: native code uses + public platform API only. - Relies on `spec:AST-112` FR20 (amended): the package covers the native code Astryx itself uses; every module of this group is such code. - Is the System modules group record that `spec:AST-112/FR7` names: it lists