React Native foundation system spec¶
Intent¶
A developer builds an iOS and Android app with React Native and Astryx by
installing one package, @astryxdesign/react-native: a component library
written in JavaScript over a platform layer that holds every line of native
code. Command-line tools create, check, and preview the app. The app gets Astryx's components,
themes, and icons, and native capabilities (storage, files, camera, media, web
content, documents, native controls) through one consistent API. The app
itself holds no hand-written native code, builds in a generated native
project, and links only the native capabilities it opts in.
Two apps work with these packages: the Astryx app on iOS and Android, for previewing projects and browsing the components, and Astryx Stage, the desktop app for macOS, Linux, and Windows, which renders an app built with these packages with iOS and Android looks for development (FR12).
These packages are the React Native candidate of spec:AST-082/FR12 for the
ios and android platforms. They follow spec:AST-082: dependencies under
FR13, the canary channel under FR15, the one-way read of core under FR16, and
shared icon names under FR17.
Non-goals¶
- Which candidate wins a platform.
spec:AST-082/FR12decides that by measurement. - The contract of any one component. Each component's own record and
spec:AST-082/FR3own it; this record owns where the React Native implementation lives and how its packages relate. - macOS and Windows as targets for apps built with these packages.
- The design of each capability's methods beyond the shared rules in FR6 to FR9. Each capability documents its own methods, options, and reasons.
- The internals of Astryx Stage (FR12), beyond what an app and the CLI depend on.
- The Astryx app's design, features, and distribution.
- Equivalent internal implementations remain valid when they satisfy this contract.
Requirements¶
- FR1 — Two package families. The public set is:
@astryxdesign/react-native: the one package an app installs. It holds two layers and a configuration plugin:- The library layer: components, the app root (
AstryxAppRoot), theming, the hooks an app uses, and the Astryx router (DEC-9). JavaScript and TypeScript only. - The platform layer, which holds every line of native code. Its core is
always present: the result vocabulary (FR6), the capability shape
(FR7), the types of every capability, the registry seams the
capabilities plug into, the generic capabilities (storage, secure
storage, files, network, cookies, permissions, haptics, clipboard,
client identity), the gesture owner, gesture root, touch shield,
presentation, menu, and action-sheet hosts, system symbols, system
materials, and safe-area insets. Its optional capabilities are opt-in
modules (FR3):
camera(camera view, live code scanning, and code decoding from still images),media(audio and video playback),web(web view and sign-in session),pdf(document view),controls(native button, text field, date pickers, and the swipe-row, drag-snap, and zoom-pager views), andnavigation(the native stack and tab hosts, DEC-9).
- The library layer: components, the app root (
@astryxdesign/react-native-cli: the React Native experiment CLI, which installs theastryx-rncommand (FR13).
- FR2 — Dependencies point one way.
- The library layer calls the platform layer directly. The platform layer imports nothing from the library layer, in source or in tests.
- A capability uses the platform's core only. Apart from its loader
(
AstryxPlatform.capability(name)), the core imports no capability; the loader is the one place that names the capability modules. A need that crosses capabilities goes through a registration hook in the core, never through an import between capabilities. - The library layer reaches an optional capability only through that
loader. The loader answers the capability's module whenever its
JavaScript loads, opted in or not, and
nullonly when the module cannot load. When the app did not opt the capability in, the module's probes answer false and its calls resolvenot-linked(FR3); on a binary that records no list of linked capabilities, they resolveno-modulewhere the native module is missing. - The package depends on no other Astryx package at run time, other than
the reads of
@astryxdesign/corethatspec:AST-082/FR16allows and@astryxdesign/native(FR10, OQ2, OQ3).@astryxdesign/coreand@astryxdesign/clinever depend on it (spec:AST-082/FR14). - The Astryx router (the
navigationentry) holds the routing state and drives the platform'snavigationhosts. Astryx also owns the native stack and tab containers, transitions, gestures, insets, and every bar, header, button, and search field, rendered by the system through the platform's hosts or drawn by the library (DEC-9). - The package takes no third-party navigation dependency, a router,
react-native-screens, and react-native-safe-area-context included: its
only peer dependencies outside Astryx are React and React Native. The one exception is the optional peers of the
./navigation-legacyentry (FR5). Apart from that entry, a React Navigation adapter may exist only as a separate optional package, never as a dependency of the set; it drives the platform'snavigationhosts and depends on no package that ships native navigation code, react-native-screens and react-native-safe-area-context included. - React Native command-line tools are development dependencies. An app's
runtime never imports them, and
@astryxdesign/clinever depends on them.
- FR3 — An app opts in to each capability. Each optional capability
carries its own native module, system frameworks, dependencies, manifest
components, and services, and the app's native build links them only when
the app opts the capability in: on iOS a Podfile helper adds the
capability's subspec, and on Android a Gradle property enables its source
set. The configuration plugin writes both from the
capabilitiesoption the app passes to the plugin (FR4); an empty list links the core only. The native build records the list of capabilities it links, which the core reads.- An app that does not opt a capability in links none of its native code,
frameworks, or dependencies. The capability's
isAvailable()andis<View>Available()answer false, and each of its calls resolvesnot-linked. not-linkedapplies to a capability missing from the build's list.no-moduleapplies to a module that is missing although its capability is on the list, or on a binary that records no list (FR8).- The package's manifests declare no permission. The configuration plugin writes every permission the app needs (FR4).
- An app that does not opt a capability in links none of its native code,
frameworks, or dependencies. The capability's
- FR4 — Native code lives only in the platform layer.
- The library layer contains no native code, and the package has no
runtime dependency beyond
react,react-native, the Astryx packages FR2 allows, and the optional peers of./navigation-legacy(FR5). - An app holds no hand-written native code. Its iOS and Android projects are generated from the app's configuration. The package ships one configuration plugin. It always writes the core's host declarations (on Android, the network-state permission), and from the app's list of capabilities it writes the opt-in (FR3) and the host declarations each listed capability needs (permissions, usage descriptions, manifest entries, background modes), from data the package provides per capability. Every usage description has a default that the app can override, and the plugin writes nothing for a capability the app does not list.
- An app-level native setting is configuration that a plugin writes into the generated project. JavaScript cannot read or change it at run time.
- The platform layer ships its native code as source that the app's native build compiles; the core and each opted-in capability register through autolinking and React Native's code generation.
@astryxdesign/nativeis the single cross-platform contracts package ofspec:AST-082(DEC-7). The React Native platform ships inside@astryxdesign/react-nativewith capabilities an app opts in (FR3), because each capability carries its own native code, permissions, and size, so an app links only what it uses. The package may consume@astryxdesign/native's generated contracts (OQ2).
- The library layer contains no native code, and the package has no
runtime dependency beyond
- FR5 — The public surface is deliberate. Each package declares its entries
in its
exportsmap, and an import outside the map is unsupported..is the app API: the library layer's components, themes, and hooks, and the platform core's always-present objects, views, and result vocabulary. It holds no router and no optional capability's objects or views../storage(storage, secure storage, files) and./network(network, cookies, client identity, and the installers below) hold the rest of the core../theme,./styles, and./i18nhold the theme objects, the style helpers, and the strings../camera,./media,./web,./pdf, and./controlsare the optional capabilities' entries../navigationis reserved for thenavigationcapability and the Astryx router and its navigators (FR2): the name is held, and the package exports the entry only once it holds them.- Apart from the Jest setup file, no entry installs a global when it is
imported (DEC-10).
./networkexports two installer functions that an app calls when it wants the globals below:- One installs each of
crypto.getRandomValuesandcrypto.randomUUIDthat the runtime lacks, from the system's secure random generator, and leaves an existing one in place. Without that generator it installs nothing and reportsno-module; it never fills them from a non-secure source. It reports which of the two it installed. - The other makes the global
fetchhonorredirect: 'error'andredirect: 'manual'. It reports false when the runtime has no globalfetch. - Calling an installer again changes nothing.
- One installs each of
- Apart from the crypto installer, the package's own code reads no global
cryptoand does not depend onfetch'sredirect: 'error'orredirect: 'manual'modes. - The Astryx app's preview host calls both installers before a previewed project's code runs, so a project in preview has these globals without importing anything for them. Outside the preview host, the package installs them only when the app calls the installers.
./navigation-legacy(with its./navigation-legacy/core) is the React Navigation binding, the one inside the package: a transitional entry that binds React Navigation's navigators. Its peer dependencies on React Navigation, react-native-screens, react-native-safe-area-context, and@callstack/liquid-glassare optional, so an app that does not import it installs none of them, and no other entry imports it. It is removed before the package joins the stable channel (FR14)../testingis the testing surface: mocks of every native module in its absent, older, and current shapes, event emitters, and a Jest setup file (./testing/jest-setup), the package's only module with side effects. It is public and documented.- Internal entries hold the plumbing Astryx's own tools need (the host plumbing, the preview host of the Astryx app, Astryx Stage's simulation, and the documentation site's examples and coverage data). They have the status
spec:AST-017FR21 gives Core's./internal/*: undocumented for apps, versioned with the package (FR14), limited by a package-boundary check, and outside the compatibility promise. ./app.plugin.jsis the configuration plugin (FR4), and./declarations/*holds the per-capability host declarations it writes..exports nothing named*ForTesting,reset*,SIMULATED_*, or*_NAME.- A renamed or removed public name or entry stays exported, marked
@deprecated, for one minor version.
- FR6 — One result vocabulary. Every asynchronous call in the platform resolves
AstryxResult<T, R>:{ok: true, …}with its data, or{ok: false, reason, message?}. It never rejects.reasoncomes from a closed set per capability plus the common reasonsno-module,not-linked,unsupported,cancelled,not-allowed, anderror.no-modulemeans the platform's native side is absent;not-linkedmeans the app did not opt the capability's native code in (FR3);unsupportedmeans the binary predates the method or one of its options;not-allowedmeans the Astryx app's policy refused the capability for the project that called it. A capability may add reasons of its own, such asunsupported-optionwhere a platform cannot honor an option.cancelledis the one failure that is not an error: the person declined or dismissed something. A caller branches on it and shows no error.messageis platform text for logs. It never carries a URL's query, a cookie, a key, or a token.
- FR7 — One capability shape.
- Every capability object has
isAvailable(): boolean(synchronous, cheap, cached) andversion(): number | null, andsupports(feature)where the capability has optional features. Every view has anis<View>Available()probe. A capability the app did not opt in answers false, and its calls answernot-linked. - A path a platform or an older binary does not support answers
unsupported, or the capability's own reason for an option the platform cannot honor. It is never a silent no-op and never a quietly weaker behavior. - Permissions are explicit:
AstryxPermissions.getandrequest, and ause<Capability>Permission()hook. Mounting a view never prompts. - Hooks own lifecycle: they cancel their work on unmount and return stable
callbacks. Module handles and native versions never appear in app-facing types. A
request that presents system UI (sign-in, the file picker) may take an
optional
rootTagthat names the presenting surface. - Names follow React Native's own conventions:
source={{uri}},ref,on<Event>(event)with one object argument,isandhasbooleans, and string unions for closed sets. A call takes its subject first and one options object, with defaults for every option.
- Every capability object has
- FR8 — Native interfaces evolve additively. Every TurboModule and native
component spec in the platform follows these rules, and a check in the
package enforces them:
- A module is read with
TurboModuleRegistry.get, nevergetEnforcing; an absent module answersno-module, ornot-linkedwhen the app did not opt its capability in (FR3). - Each module's handle is read only by its own wrapper.
- New behavior is a new optional method or prop. A shipped method's arguments and result never change.
- A new method takes one request object and resolves one result object with
status(ok,cancelled, orerror),reason, andmessage. A domain outcome, such as "not found", is a field of anokresult. - Every module reports
getConstants().version, its behavior revision. - A member that exists on one platform only says so in its name or tag.
- Every spec file has a header with its owner, platforms, first version, and stability, and every component spec has a version history.
- A module is read with
- FR9 — The library speaks Astryx; the platform speaks the platform. The
platform's public types use platform vocabulary, except the native controls,
whose appearance is Astryx's design language. The library maps Astryx
vocabulary onto the platform: icon names onto system symbols
(
spec:AST-082/FR17), feedback moments onto haptic kinds, and the theme onto native appearance.AstryxAppRootwires the platform's hosts by default and takesnativeHostsoptions;NativeHostsProvidercomposes the same hosts for an app that builds its own root. - FR10 — The packages build on core and on the shared native code.
- Tokens, themes, and icon names come from
@astryxdesign/core's one theme definition (spec:AST-082/FR10), read underspec:AST-082/FR16. The React Native packages never define a second token set. - Components keep core's names and core contracts (
spec:AST-082/FR3). - Where
@astryxdesign/native's Swift package provides a native control or view for a component, the platform wraps that shared control instead of drawing a second one.
- Tokens, themes, and icon names come from
- FR11 — Expo builds are supported; Expo Go is not a target. The platform builds in a prebuild or development-build project and in EAS Build
through the package's configuration plugin (FR4), with no manual native
edits. It does
not run in Expo Go, and no package requires an Expo runtime library
(
spec:AST-082/FR13). Expo's API shapes do not limit the platform's API. - FR12 — Astryx Stage is the contract developers build against. Astryx
Stage runs on macOS, Linux, and Windows. It renders an app
built with these packages with iOS and Android looks, headless or in a
window, for previews, scripted checks, and agent loops.
- Every public platform API has an implementation in Astryx Stage whose behavior matches iOS and Android. A missing or divergent path is a defect, and the capability's documentation names it until it is fixed.
- Each capability's documentation states its behavior in Astryx Stage as the contract and notes where iOS and Android differ.
- Astryx Stage is a development tool. An app never depends on it at run time.
- FR13 — React Native commands live in an experiment CLI.
@astryxdesign/react-native-cliinstalls theastryx-rncommand, the experiment space for React Native commands. It is canary-only, and its commands may change or disappear in any canary. The released command-line shape for React Native is OQ5.- Commands:
create(a new app),doctor(the toolchain, the project, and the installed Astryx Stage),generate(the native projects from configuration), and commands that install, select, open, and run the desktop app, capture and inspect a rendering, and run scripted checks. Their names are proposals under OQ5 (for examplestage install | update | use | list | open | run | shot | inspect | test | sweep).
- Commands:
- Astryx Stage's version is pinned per project in a configuration file the React
Native command-line tool owns, never in
astryx.config, whose keys@astryxdesign/clivalidates. The install command verifies each binary's checksum and signature, and the first command that needs Astryx Stage installs the pinned version. --remoteruns an Astryx Stage command on a remote runner and returns the same result as a local run.- Its commands follow the output and exit-code rules of
architecture:cli-surface: no question is ever asked, every--jsonemission is one envelope, codes are stable and append-only, and exit codes do not depend on the output mode. It shares flag style with@astryxdesign/cliand writes no key intoastryx.config. A command therefore keeps its contract whichever released shape OQ5 settles. @astryxdesign/clicontains no React Native commands, so a web project installs nothing for them.- FR14 — One React Native release train.
@astryxdesign/react-nativereleases on one version; its capabilities are opted in, never versioned apart. The experiment CLI versions on its own.- The package versions on its own, outside the repository's fixed package
group (
spec:AST-017FR46): the version in itspackage.jsonis its own next planned release, not core's. - A release starts as release candidates,
<version>-rc.<n>, each cut from a tagged commit. A fix after a release candidate ships as the next release candidate, and a fix after the release ships as a patch release. - While it is canary-only, the package publishes only on the canary channel, under
spec:AST-082/FR15: its release candidates and releases, and canaries that carry its own declared version with-canary.<commit>. It joins the stable channel in a planned minor once a platform is supported. - Before 1.0, a minor version may change the API. Each release has a changelog with migration steps for every rename and removal, and a release records the packed tarball with its hash.
- The package versions on its own, outside the repository's fixed package
group (
- FR15 — Evidence matches the claim.
- Evidence for native behavior comes from the iOS Simulator, the Android emulator, devices, and Astryx Stage. The Simulator and the emulator are the source of truth during development; every change to native behavior is checked there and in Astryx Stage.
- A passing build is not evidence of behavior. A claim about camera, haptic feel, or performance needs a real device.
- The platform's tests cover each native module in its absent,
older, and current shapes through
./testing. - API blocks in each package's documentation are generated from source, and a check fails when they drift.
Platform support¶
- Supported feature/engine floor: iOS at React Native's own minimum and Android API level 24, on React Native's New Architecture (Fabric and TurboModules) only, with the React and React Native versions each package declares as peers.
- Unsupported behavior: a capability a binary lacks answers
not-linked,no-module, orunsupported(FR3, FR6, FR7); a view a binary lacks reports itself unavailable and the library draws its fallback; Expo Go and the old architecture are not supported (FR11). - Browser evidence: none. Native claims are proven on the Simulator, the emulator, devices, and Astryx Stage (FR15).
Current-state impact¶
- New packages under
packages/:@astryxdesign/react-nativeand the experiment CLI, each canary-only (FR14). @astryxdesign/cliis unchanged. The released command-line shape for React Native (OQ5) may changearchitecture:cli-surfacewhen it is decided.@astryxdesign/react-nativeversions on its own, outside the fixed package group ofspec:AST-017FR46, and the repository's canary release gives it its own declared version (FR14); the experiment CLI versions on its own.spec:AST-017FR21 extends the status of Core's./internal/*to the package's internal entries (FR5).spec:AST-082DEC-7 gains one sentence: the React Native candidate's native code lives in the platform layer of@astryxdesign/react-native(spec:AST-112FR4), and@astryxdesign/nativestays the single cross-platform contracts package.- The package-boundary check gains the FR2 rules: no import from the library layer in
the platform layer, no import of a capability from the platform's core outside its loader or from another capability, no dependency on a third-party navigation package (react-native-screens and react-native-safe-area-context included) other than the optional peers of
./navigation-legacy, no peer dependency outside Astryx other than React, React Native, and the optional peers of./navigation-legacy, and no dependency on these packages from core or the CLI.
Verification¶
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1 | Package manifest check of names and entries; the canary release's package list | each package in the public set; each capability entry | A package missing from the set, a set package missing from the canary release, or a capability without its entry |
| FR2 | Package-boundary, source, and dependency check | the platform's source and tests; the library and platform layers; the core and each capability; the package's dependencies | An import from the library in the platform, a capability import in the core outside its loader, an import between capabilities, a dependency on a third-party navigation package (react-native-screens and react-native-safe-area-context included) other than the optional peers of ./navigation-legacy, or a peer dependency outside Astryx other than React, React Native, and the optional peers of ./navigation-legacy |
| FR3 | Built app with the core only, compared with one per opted-in capability: binary symbols and the merged manifest; unit tests of each capability's isAvailable() and a call's reason |
a capability's native module, frameworks, dependencies, permissions; an opted-out capability; a missing module of an opted-in one; a binary that records no list | An app that did not opt a capability in links any of its native code or declarations, isAvailable() answers true for it, a call resolves a reason other than not-linked, or a missing module of an opted-in capability, or one on a binary that records no list, resolves a reason other than no-module |
| FR4 | npm pack file list; a generated sample app's project from configuration with a capability list |
the package's files; the sample's iOS and Android projects; a default and an overridden usage description | Native code outside the platform layer, the package manifests declare a permission, the sample needs a manual native edit, the generated project lacks the core's declarations, or it writes a usage description other than the default or the app's override |
| FR5 | exports map and public-entry name check; package-boundary check of the internal entries' imports; source check of global reads; unit tests of the installers; a previewed project's runtime |
., ./storage, ./network, ./theme, ./styles, ./i18n, each capability entry, ./navigation-legacy, ./testing, ./testing/jest-setup, the internal entries, ./app.plugin.js, ./declarations/*; a runtime without the secure random generator; a runtime with only one of the two crypto functions; a runtime without a global fetch; an installer called twice; a previewed project |
A private name on ., a deep import resolving, an app importing an internal entry, a router or optional capability exported from ., another entry importing ./navigation-legacy, a ./navigation entry that does not hold the router, a module with side effects other than the Jest setup, an import other than the Jest setup that installs a global, package code other than the crypto installer that reads the global crypto, package code that depends on fetch's redirect modes, a non-secure random fill, a crypto installer that replaces a crypto function the runtime provides, an installer that reports nothing or changes anything on a second call, a fetch that follows a redirect under redirect: 'error' or 'manual' after its installer ran, or a previewed project that starts without the globals |
| FR6 | Unit tests of every asynchronous call through ./testing mocks |
absent, older, and current module; a missing option; a native throw; cancel | A call rejects, or answers a reason outside its set |
| FR7 | Unit tests of each capability's probes, permissions, and hook cleanup | an older binary; a view mounted without permission; unmount | A silent no-op, a prompt on mount, or work that outlives its component |
| FR8 | Spec rules check in the platform | a new method; a component spec; a platform-only member | A changed shipped method, a missing header, or a new method without status |
| FR9 | Source check of platform public types; library tests of the mappings and the default hosts | an icon name; a feedback moment; a theme change | Astryx vocabulary in a generic capability type, or the app root without hosts |
| FR10 | Token comparison between the library and core's theme; review of shared native controls | every token; each component with a shared native control | A token value that differs from core's, or a second native control drawn beside a shared one |
| FR11 | Prebuild and EAS Build of the sample app | the sample with every capability opted in | The build needs a manual native edit, or a package requires an Expo runtime library |
| FR12 | Scripted checks of each capability in Astryx Stage, the simulator, and the emulator | each public API | An Astryx Stage result differs from iOS and Android and the documentation does not name it |
| FR13 | CLI contract tests of each astryx-rn command: JSON envelopes, exit codes, Astryx Stage's checksum and signature refusal, --remote parity; a dependency check of @astryxdesign/cli |
each command; a tampered binary; a web project | An exit code that depends on --json, a tampered binary runs, or @astryxdesign/cli contains or depends on React Native commands |
| FR14 | Canary and release-candidate dry run | a release of the package | A release without a changelog or the tarball's hash, a capability versioned apart, or a release candidate or canary that carries a version other than the package's own |
| FR15 | Review of each native change's evidence; documentation drift check | a native behavior change; a renamed API | A native claim backed only by a build or by anything other than the Simulator, the emulator, a device, or Astryx Stage, or documentation that no longer matches |
Decision log¶
DEC-1 — The platform is a layer for Astryx, below the library¶
Reference: spec:AST-112/DEC-1
Decider: imdreamrunner, 2026-11-09
The platform layer owns the native contract and first-class capability objects; the library layer calls them directly and keeps the Astryx mapping. Apps call the same objects for capabilities the library does not cover. Dependencies point from the library layer to the platform layer only, so the native API stays clean and the library can change without touching native code.
Rejected: a design-system-neutral platform built for standalone use, because it would duplicate the mapping the library owns.
DEC-2 — One package with opt-in capabilities¶
Reference: spec:AST-112/DEC-2
Decider: imdreamrunner, 2026-11-09
An app installs one package and imports everything from it: the components, the native platform layer, and the configuration plugin. An app that stores data does not ship a camera permission, a media service, or their frameworks: it links only the capabilities it opts in, and the plugin writes the opt-in and the declarations, so an app never edits a native project by hand.
Rejected: a separate platform package, or one package per capability, because the packages could be installed at different versions and each app would track several packages that only work together.
DEC-3 — Apps hold no native code¶
Reference: spec:AST-112/DEC-3
Decider: imdreamrunner, 2026-11-09
The platform brings all native code; an app's native projects are generated from configuration with the package's plugin. An Astryx upgrade then reaches every app through its dependencies, and no app carries native code that drifts from the platform.
Rejected: app-owned native shell code, because each app would maintain native code the platform cannot update.
DEC-4 — Results, never rejections¶
Reference: spec:AST-112/DEC-4
Decider: imdreamrunner, 2026-11-09
Every failure is data in one shape with a closed reason, so a caller handles it with a type-checked branch, and a cancel is told apart from an error.
Rejected: rejecting promises for failures, because an unhandled rejection is easy to miss and its reason is not typed.
DEC-5 — Expo builds, not Expo Go¶
Reference: spec:AST-112/DEC-5
Decider: imdreamrunner, 2026-11-09
Cloud and prebuild builds are a goal, so the platform carries a configuration plugin. Expo Go cannot load the packages' native code, and an API limited to what every Expo module offers would cap the platform.
Rejected: an adapter package for Expo's module system, because it adds a second interface to keep in step without enabling any build.
DEC-6 — React Native commands start in an experiment CLI¶
Reference: spec:AST-112/DEC-6
Decider: imdreamrunner, 2026-11-09
React Native commands change quickly while the packages are canary-only, so they
start in astryx-rn, a separate experiment program, and stay out of
@astryxdesign/cli. The released command-line shape is OQ5.
DEC-7 — Astryx Stage's behavior is the contract developers read¶
Reference: spec:AST-112/DEC-7
Decider: imdreamrunner, 2026-11-09
Developers build against Astryx Stage, so its behavior is what they rely on. Astryx's own development checks the simulator and emulator as the source of truth and keeps Astryx Stage matched to them. A missing or divergent path is a defect.
DEC-8 — One release train, canary first¶
Reference: spec:AST-112/DEC-8
Decider: imdreamrunner, 2026-11-09
The library and platform layers change together, so they ship in one package
on one version of its own, released through release candidates. It stays on
the canary channel until a platform is supported under spec:AST-082/FR15.
Rejected: core's version in the repository's fixed package group, because every core release would move the package without a change in it, and the package's pre-1.0 API changes would follow core's minor versions.
DEC-9 — Astryx owns navigation, routing included¶
Reference: spec:AST-112/DEC-9
Decider: imdreamrunner, 2026-11-09
Gestures, bars, safe areas, and routing meet in the native stack, so Astryx
owns all of it: the package's navigation entry holds the router, the
platform's navigation capability holds the native stack and tab containers
with their transitions and gestures, the core holds safe-area insets, and
every bar, header, button, and search field is the system's, through the
platform's hosts, or drawn by the library. The packages take no third-party navigation dependency outside one
transitional entry, and an app that navigates with Astryx's router runs no
third-party native code for navigation.
Rejected: building on React Navigation, react-native-screens, and react-native-safe-area-context, because their gesture handling couples to the platform's and their state model would bound Astryx's.
DEC-10 — Importing the package changes no globals outside its Jest setup¶
Reference: spec:AST-112/DEC-10
Decider: imdreamrunner, 2026-11-10
An app's behavior does not depend on the order of its imports, and the package
runs in a runtime whose globals it does not control. The package's own code
calls its platform directly instead of relying on the global crypto or on
fetch's redirect modes. The preview host installs these globals for the
projects it hosts; any other app calls the exported installers when it wants
them.
Rejected: a side-effect ./polyfills entry that an app imports first in its
entry file, because every app must remember the step and its effect depends on
import order.
Open questions¶
- OQ2 — When do the library's component props come from
@astryxdesign/native's platform contracts? (human-api) Options: now, under theiosandandroidconditions; or once core's portable entry ships. Recommendation: once the portable entry ships, with a check until then that the library's props match the generated contracts. - OQ3 — How does an app receive
@astryxdesign/native's Swift code? (checkable) Options: the platform vendors the Swift sources it wraps; or the platform's native build depends on the Swift package directly. - OQ4 — Where are Astryx Stage's binaries published? (
human-design) Options: per OS and architecture packages on npm that the CLI installs; or release assets that the CLI downloads and verifies. Recommendation: release assets with checksums and signatures, because the binaries are large and npm's optional dependencies install every architecture's metadata. - OQ5 — What is the released command-line shape for React Native?
(
human-api; owners: imdreamrunner and josephfarina) Options:- An extension of the core CLI. An optional integration package (name
proposed:
@astryxdesign/cli-react-native) contributes anrncommand group to@astryxdesign/cli(astryx rn …) through a newcommandscontribution in the integration manifest, loaded like other contributions: from the project's integrations inside a project, and from computer-level integrations outside one (spec:AST-081/FR12). Gains: one command, one help, output, and error-code contract, enforced by the core CLI. Costs: the core CLI needs a command extension point (the manifest'scliCommandkey names the printed command prefix only), and React Native commands release on the core CLI's peer range. - A separate CLI.
astryx-rnitself becomes the released program, optionally withastryx rnforwarding to it. Gains: no change to the core CLI, and an independent release cadence. Costs: a second help, output, and error-code surface to keep in step, and two command names in documentation. - Commands inside
@astryxdesign/cli. Gains: one package, no extension point. Costs: every web project installs React Native commands.
- An extension of the core CLI. An optional integration package (name
proposed:
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx