Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(AST-082): FR19 logic-core wire and host contract (canary) (#8237)

Cindy Zhang6ead9726a1fe
diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md
index 79eae190ff..400622a080 100644
--- a/docs/specs/AST-082-native-first-surfaces/spec.md
+++ b/docs/specs/AST-082-native-first-surfaces/spec.md
@@ -338,6 +338,35 @@ depends only on runtimes it can maintain.
parts with content, it reports each one in development as having no native
meaning rather than dropping it silently; native component theming comes from
platform entries (FR10), and native icons follow FR17.
+- **FR19 — A logic core drives native views through one wire.** For the
+ candidate in which component logic runs in TypeScript inside a native app
+ (FR12), `@astryxdesign/native` defines one wire, generated from the same
+ contracts as every binding (FR5). The wire is a canary surface of that
+ candidate (FR15).
+ - **Nodes.** A screen is a tree of nodes. A node names its component, has a
+ `key` unique among its siblings, may carry shared base props (FR7), carries
+ its data props as that platform's contract defines them, and lists in
+ `events` the callbacks the logic handles. A content slot (FR4) carries
+ child nodes. A native view receives only the callbacks listed in `events`.
+ - **Actions.** When a view calls a listed callback, the host sends one action:
+ the node's `key`, its component, the callback's name, and the callback's
+ portable arguments in order.
+ - **Compatibility.** A host draws every node it can read. A node it cannot
+ read, because the component is unknown to it, a value lies outside its
+ closed set, or a prop it requires is missing, renders as unsupported in its
+ place, and its siblings still render. Props a host does not know are
+ ignored.
+ - **Bridge.** The host loads the logic bundle and calls its global
+ `astryxStart(host)`, passing two calls in: `connected(version)` and
+ `changed(tree)`. It gets back a bridge it reads the current tree from and
+ dispatches actions to. Trees and actions cross as JSON, and the bridge has
+ a version.
+ - **Failure.** A missing entry, a JavaScript error, a bridge version that
+ differs from the host's, or a tree the host cannot read at all stops the
+ host: it reports the failure, draws no tree, ignores any later tree, and
+ sends no action. The logic core refuses input that is not an action.
+ - **Engine.** The logic core uses ECMAScript built-ins only, so it runs in any
+ engine FR13 allows.
### Platform support
@@ -365,8 +394,14 @@ depends only on runtimes it can maintain.
`DefinedTheme` are unchanged for web callers.
- The `theme` and `cli` consumer docs and every component's documentation gain
platform marking when the first native contract ships.
-- `@astryxdesign/native` does not exist yet, and `@astryxdesign/core` has no
- portable entry yet. Core peer-depends on `react-dom` and StyleX, and its theme entry includes
+- `@astryxdesign/native` ships on the canary channel with the FR19 wire: the
+ generated node and action types, the logic core and bridge, and a Swift logic
+ host. Its contract model still types FR4 open string sets as closed sets, so
+ the generated node types for each platform and the Swift binding both reject
+ a theme-added name, such as a Button `variant`; the TypeScript types refuse
+ it, and a Swift host renders the node as unsupported instead of drawing the
+ component's base look.
+- `@astryxdesign/core` has no portable entry yet. Core peer-depends on `react-dom` and StyleX, and its theme entry includes
the web theme compiler.
- Built-in icon names are defined beside the web icon registry, which maps them to
React elements; the portable entry carries the names only when it ships.
@@ -375,23 +410,24 @@ depends only on runtimes it can maintain.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR3 | Component documentation metadata check, plus type and build tests importing a platform-specific component | a shared component; a web-only component; a component on some native platforms; an unsupported platform | A component declares no platforms, claims an unsupported native platform, or an unsupported import type-checks, builds, or renders a substitute |
-| FR4 | Contract generation to TypeScript, Swift, and Kotlin, compiled in each language | every core prop kind; a boolean combined with a closed string set; an open string set with a built-in name, a theme-declared name, and a name the platform has no rule for; a projected prop at each portable value and at a web-only value; a text, icon, and content slot, and a web call site passing a wider form; a free-form content or render-function prop in the core | A core prop has no Swift or Kotlin form, a non-portable prop enters the core, a named state collapses into `true` or `false`, a theme-declared name is rejected by a platform type, an unknown open-set name fails instead of drawing the base look, a wire value differs from the web value, a projected value maps to a different web value or a web-only value reaches a native type, or a slot accepts a wider form on a platform that cannot render it |
-| FR5, FR6 | Type checks of fixture apps against each package and condition | core default (web); each native condition; `shared`; a platform prop in another platform's file and in a shared file | A platform prop type-checks under another platform's condition or under `shared`, a core prop is missing under any condition, or web types change |
-| FR7 | Generated base-prop surfaces per platform, plus runtime targeting tests | shared base props; a core-owned concept; a core prop that reuses a base name; each targeted part | A shared base prop differs by platform, an owned concept's base prop overrides the core prop, or base props reach a different part on another platform |
-| FR8 | Contract name check over every component | core prop vs platform prop; Swift and Kotlin keywords; platform toolkit names; reclaimed names; one name in two platform contracts | A collision passes, a reclaimed name is undeclared, or a same-named platform prop appears in a merged type |
-| FR9 | Documentation and CLI output checks | core only; each platform selection; native package absent | Output for one platform lists another platform's prop, or a prop is unmarked |
-| FR10 | `defineNativeTheme` unit and type tests, plus a resolution test per platform | durable `material` only; entry with and without a range; overlapping entries; platform `components`; native theme extension; a token in native configuration; platform term outside its entry or range | A token can be set, a platform term type-checks outside its entry or range, an entry applies outside its platform or range, overlap order is ignored, or extension drops members |
-| FR11 | FR12 experience scores per scenario step, oldest and newest supported OS | navigation, sheet, menu, picker, switch, text entry, scrolling, keyboard shortcut, large text; a capability newer than the running OS | A step draws a custom control where the platform provides one, misses the touch-target minimum, ignores the text-size setting, or breaks on the oldest supported OS |
-| FR12 | Scenario replay on candidates and reference, on real release builds and devices | each scenario on each candidate and the toolkit reference; oldest and newest supported OS; a lower-end device per platform | A candidate is scored without the reference, on a debug build, on emulation only, on one OS version, or on a different scenario set, or a visual score is given without device captures |
-| FR13 | Dependency manifest audit of each native platform package | platform SDK; first-party project; a React Native out-of-tree desktop platform; third-party optional integration; third-party fork | A third-party library or fork is required to install, build, or render on the platform |
-| FR14 | Compiler and render output comparison, core dependency graph check, and a web type surface diff | each maintained theme with and without the native package installed; runtime-mounted and built CSS; components; web types before and after; an existing web prop that renders a string as text becomes an icon slot | Any byte of CSS, mounted rules, or rendered web markup differs, core depends on native, or a web prop disappears outside a planned minor, or an existing web prop that renders a string as text becomes an icon slot in a patch rather than a planned minor |
-| FR15 | Package metadata and release-channel checks | native package manifest; a stable release; a canary release | The native package is publishable as a stable release before a platform is supported |
-| FR16 | Package-boundary check, plus a native fixture app installed and bundled without `react-dom` or StyleX | an import of the portable entry; an import of a core component or the web theme entry from native; a listed build-time read from a native build script; an unlisted one; a core import of native; a core contract change | Native resolves a DOM type, `react-dom`, StyleX, or a web module; either direction of the boundary is crossed, an unlisted build-time read passes; or a core contract change does not reach native contracts on the next build |
-| FR17 | Icon map coverage check per native platform, plus override resolution tests | every built-in name; a namespaced name; a theme platform icon with and without a version range; an app-registered icon; an icon slot given an unknown name in a development and a release build | A built-in name has no platform default, a theme or app icon fails to replace the default, a scoped icon applies outside its range, a web icon is substituted, or an unknown name draws something in a release build or does not stop a development build with its name |
-| FR18 | Type tests over `PortableTheme` and `DefinedTheme`, token resolution tests per color mode, and `defineNativeTheme` reporting tests | each maintained theme; a theme with component overrides, icons, indicators, media surfaces, and adaptations; light and dark; a length, a color, and a font token | `DefinedTheme` changes for a web caller, a portable token needs CSS to resolve, `PortableTheme` references a React or DOM type, or a web part with content is dropped without a report |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR3 | Component documentation metadata check, plus type and build tests importing a platform-specific component | a shared component; a web-only component; a component on some native platforms; an unsupported platform | A component declares no platforms, claims an unsupported native platform, or an unsupported import type-checks, builds, or renders a substitute |
+| FR4 | Contract generation to TypeScript, Swift, and Kotlin, compiled in each language | every core prop kind; a boolean combined with a closed string set; an open string set with a built-in name, a theme-declared name, and a name the platform has no rule for; a projected prop at each portable value and at a web-only value; a text, icon, and content slot, and a web call site passing a wider form; a free-form content or render-function prop in the core | A core prop has no Swift or Kotlin form, a non-portable prop enters the core, a named state collapses into `true` or `false`, a theme-declared name is rejected by a platform type, an unknown open-set name fails instead of drawing the base look, a wire value differs from the web value, a projected value maps to a different web value or a web-only value reaches a native type, or a slot accepts a wider form on a platform that cannot render it |
+| FR5, FR6 | Type checks of fixture apps against each package and condition | core default (web); each native condition; `shared`; a platform prop in another platform's file and in a shared file | A platform prop type-checks under another platform's condition or under `shared`, a core prop is missing under any condition, or web types change |
+| FR7 | Generated base-prop surfaces per platform, plus runtime targeting tests | shared base props; a core-owned concept; a core prop that reuses a base name; each targeted part | A shared base prop differs by platform, an owned concept's base prop overrides the core prop, or base props reach a different part on another platform |
+| FR8 | Contract name check over every component | core prop vs platform prop; Swift and Kotlin keywords; platform toolkit names; reclaimed names; one name in two platform contracts | A collision passes, a reclaimed name is undeclared, or a same-named platform prop appears in a merged type |
+| FR9 | Documentation and CLI output checks | core only; each platform selection; native package absent | Output for one platform lists another platform's prop, or a prop is unmarked |
+| FR10 | `defineNativeTheme` unit and type tests, plus a resolution test per platform | durable `material` only; entry with and without a range; overlapping entries; platform `components`; native theme extension; a token in native configuration; platform term outside its entry or range | A token can be set, a platform term type-checks outside its entry or range, an entry applies outside its platform or range, overlap order is ignored, or extension drops members |
+| FR11 | FR12 experience scores per scenario step, oldest and newest supported OS | navigation, sheet, menu, picker, switch, text entry, scrolling, keyboard shortcut, large text; a capability newer than the running OS | A step draws a custom control where the platform provides one, misses the touch-target minimum, ignores the text-size setting, or breaks on the oldest supported OS |
+| FR12 | Scenario replay on candidates and reference, on real release builds and devices | each scenario on each candidate and the toolkit reference; oldest and newest supported OS; a lower-end device per platform | A candidate is scored without the reference, on a debug build, on emulation only, on one OS version, or on a different scenario set, or a visual score is given without device captures |
+| FR13 | Dependency manifest audit of each native platform package | platform SDK; first-party project; a React Native out-of-tree desktop platform; third-party optional integration; third-party fork | A third-party library or fork is required to install, build, or render on the platform |
+| FR14 | Compiler and render output comparison, core dependency graph check, and a web type surface diff | each maintained theme with and without the native package installed; runtime-mounted and built CSS; components; web types before and after; an existing web prop that renders a string as text becomes an icon slot | Any byte of CSS, mounted rules, or rendered web markup differs, core depends on native, or a web prop disappears outside a planned minor, or an existing web prop that renders a string as text becomes an icon slot in a patch rather than a planned minor |
+| FR15 | Package metadata and release-channel checks | native package manifest; a stable release; a canary release | The native package is publishable as a stable release before a platform is supported |
+| FR16 | Package-boundary check, plus a native fixture app installed and bundled without `react-dom` or StyleX | an import of the portable entry; an import of a core component or the web theme entry from native; a listed build-time read from a native build script; an unlisted one; a core import of native; a core contract change | Native resolves a DOM type, `react-dom`, StyleX, or a web module; either direction of the boundary is crossed, an unlisted build-time read passes; or a core contract change does not reach native contracts on the next build |
+| FR17 | Icon map coverage check per native platform, plus override resolution tests | every built-in name; a namespaced name; a theme platform icon with and without a version range; an app-registered icon; an icon slot given an unknown name in a development and a release build | A built-in name has no platform default, a theme or app icon fails to replace the default, a scoped icon applies outside its range, a web icon is substituted, or an unknown name draws something in a release build or does not stop a development build with its name |
+| FR18 | Type tests over `PortableTheme` and `DefinedTheme`, token resolution tests per color mode, and `defineNativeTheme` reporting tests | each maintained theme; a theme with component overrides, icons, indicators, media surfaces, and adaptations; light and dark; a length, a color, and a font token | `DefinedTheme` changes for a web caller, a portable token needs CSS to resolve, `PortableTheme` references a React or DOM type, or a web part with content is dropped without a report |
+| FR19 | Wire type tests per platform condition, Swift decoding tests, host tests in a JavaScript engine, and a logic core run with no host globals | a tree with a content slot; a listed and an unlisted callback; an unknown component; an unknown closed-set value; a missing required prop; a node carrying a prop the host does not know; input that is not an action; a bundle with no entry; a JavaScript error; a bridge version mismatch; a tree the host cannot read at all; a tree sent after a failure | A view gets an unlisted callback, an action carries a different key or arguments, one unreadable node blanks its siblings, a prop the host does not know makes its node unsupported, the logic core accepts input that is not an action, or a failed host draws a tree or sends an action |
## Decision log
@@ -577,6 +613,16 @@ Rejected: a native name per component for the same values, because one value
would have two names. Rejected: changing core to a closed string set, because
it breaks web callers outside a planned minor release.
+### DEC-15 — A logic-core tree degrades per node, and a failed host stays failed
+
+**Reference:** `spec:AST-082/DEC-15`
+**Decider:** cixzhang, 2026-10-23
+
+A newer logic core can reach an older app, so a host draws what it can read and
+marks only the node it cannot read as unsupported, rather than failing the whole
+screen. A host that cannot trust the bridge at all stops instead, and stays
+stopped, so a person never sees controls that do nothing.
+
## Open questions
- **OQ1 — What thresholds make a candidate supported?** (`human-design`)