@stone-js/starters 0.8.11 → 0.8.13

package/basic-react-declarative/package.json

@@ -20,16 +20,16 @@
   "dependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@stone-js/core": "^0.8.11",
-    "@stone-js/use-react": "^0.8.11",
-    "@stone-js/browser-adapter": "^0.8.11"
+    "@stone-js/core": "^0.8.13",
+    "@stone-js/use-react": "^0.8.13",
+    "@stone-js/browser-adapter": "^0.8.13"
   },
   "devDependencies": {
     "@babel/plugin-proposal-decorators": "^7.25.9",
     "@babel/preset-env": "^7.26.9",
     "@babel/preset-typescript": "^7.27.0",
-    "@stone-js/cli": "^0.8.11",
-    "@stone-js/testing": "^0.8.11",
+    "@stone-js/cli": "^0.8.13",
+    "@stone-js/testing": "^0.8.13",
     "@types/node": "^24.0.7",
     "@types/react": "^19.0.7",
     "@types/react-dom": "^19.0.3",

package/basic-react-imperative/package.json

@@ -20,16 +20,16 @@
   "dependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@stone-js/core": "^0.8.11",
-    "@stone-js/use-react": "^0.8.11",
-    "@stone-js/browser-adapter": "^0.8.11"
+    "@stone-js/core": "^0.8.13",
+    "@stone-js/use-react": "^0.8.13",
+    "@stone-js/browser-adapter": "^0.8.13"
   },
   "devDependencies": {
     "@babel/plugin-proposal-decorators": "^7.25.9",
     "@babel/preset-env": "^7.26.9",
     "@babel/preset-typescript": "^7.27.0",
-    "@stone-js/cli": "^0.8.11",
-    "@stone-js/testing": "^0.8.11",
+    "@stone-js/cli": "^0.8.13",
+    "@stone-js/testing": "^0.8.13",
     "@types/node": "^24.0.7",
     "@types/react": "^19.0.7",
     "@types/react-dom": "^19.0.3",

package/basic-react-native-declarative/App.tsx

@@ -1,192 +1,26 @@
-import { stoneApp } from '@stone-js/core'
+import { JSX } from 'react'
+import { View } from 'react-native'
 import { StatusBar } from 'expo-status-bar'
-import { useEffect, useState } from 'react'
-import { Application } from './app/Application'
-import { WelcomeData, WelcomeController } from './app/WelcomeController'
-import { nativeEventSource } from './adapter/NativeEventSource'
-import { onNativeError, onNativeRender } from './adapter/renderSink'
-import { Pressable, ScrollView, StyleSheet, Text, View } from 'react-native'
+import { useStoneTheme } from './app/theme'
+import { StoneNativeApp } from '@stone-js/use-react-native'
 
 /**
- * One platform self-check, shown as a green or red row on screen.
- */
-interface PlatformCheck {
-  label: string
-  passed: boolean
-  detail: string
-}
-
-/**
- * A minimal stage-3 decorator writing into `context.metadata`: if Babel emits
- * the 2023-11 semantics correctly under Metro/Hermes, the value is readable
- * back through `Symbol.metadata` (or its `Symbol.for` fallback, the one
- * Stone.js core uses).
- */
-const probe: any = (_value: unknown, context: { metadata: Record<PropertyKey, unknown> }): undefined => {
-  context.metadata.stonePoc = 'ok'
-}
-
-@probe
-class MetadataProbe {}
-
-/**
- * Run the runtime platform checks Stone.js depends on.
+ * The root component.
  *
- * @returns The list of checks with their outcome.
- */
-function runPlatformChecks (): PlatformCheck[] {
-  const checks: PlatformCheck[] = []
-
-  const metadataSymbol: symbol = (Symbol as any).metadata ?? Symbol.for('Symbol.metadata')
-  const probeMetadata = (MetadataProbe as any)[metadataSymbol]
-  checks.push({
-    label: 'Decorators 2023-11 + Symbol.metadata',
-    passed: probeMetadata?.stonePoc === 'ok',
-    detail: probeMetadata?.stonePoc === 'ok' ? 'context.metadata readable' : 'metadata missing'
-  })
-
-  let urlPassed = false
-  let urlDetail = 'URL API incomplete'
-  try {
-    const url = new URL('stone://app/hello/Noowow?from=poc')
-    urlPassed = url.pathname === '/hello/Noowow' && url.searchParams.get('from') === 'poc'
-    urlDetail = urlPassed ? 'pathname + searchParams OK' : `pathname=${String(url.pathname)}`
-  } catch (error: any) {
-    urlDetail = String(error?.message ?? error)
-  }
-  checks.push({ label: 'WHATWG URL (polyfill)', passed: urlPassed, detail: urlDetail })
-
-  const encoderPassed = typeof globalThis.TextEncoder !== 'undefined' &&
-    new TextEncoder().encode('stone').byteLength === 5
-  checks.push({
-    label: 'TextEncoder',
-    passed: encoderPassed,
-    detail: encoderPassed ? 'available' : 'missing'
-  })
-
-  return checks
-}
-
-/**
- * The proof-of-concept screen: boots the Stone.js application through the
- * native adapter, shows the platform checks and lets you navigate between
- * routes of the same domain you would deploy on any other platform.
+ * `StoneNativeApp` shows the screen on top of the stack, which is all a first run needs, and it
+ * needs nothing installed to do it. When the application grows a real navigator, this is the
+ * component it replaces: the stack is public state, so `@react-navigation/native-stack` drives
+ * itself from the same object through `useScreens()`. The README shows that wiring.
+ *
+ * @returns The application.
  */
-export default function App (): React.JSX.Element {
-  const [checks, setChecks] = useState<PlatformCheck[]>([])
-  const [payload, setPayload] = useState<WelcomeData>()
-  const [error, setError] = useState<string>()
-  const [booted, setBooted] = useState(false)
-
-  useEffect(() => {
-    setChecks(runPlatformChecks())
-
-    onNativeRender((response) => {
-      setError(undefined)
-      setBooted(true)
-      setPayload(response.content as WelcomeData)
-    })
-
-    onNativeError((err) => {
-      setError(String(err?.message ?? err))
-    })
-
-    stoneApp({ modules: [Application, WelcomeController] })
-      .run()
-      .catch((err: Error) => setError(String(err?.message ?? err)))
-  }, [])
-
-  const allPassed = checks.every((check) => check.passed) && booted && error === undefined
+export default function App (): JSX.Element {
+  const theme = useStoneTheme()
 
   return (
-    <View style={styles.container}>
-      <StatusBar style='light' />
-      <ScrollView contentContainerStyle={styles.content}>
-        <Text style={styles.title}>Stone.js × React Native</Text>
-        <Text style={styles.subtitle}>Continuum proof of concept</Text>
-
-        <View style={[styles.banner, allPassed ? styles.bannerOk : styles.bannerKo]}>
-          <Text style={styles.bannerText}>
-            {allPassed ? 'ALL CHECKS GREEN' : (booted ? 'CHECKS FAILING' : 'BOOTING…')}
-          </Text>
-        </View>
-
-        {checks.map((check) => (
-          <View key={check.label} style={styles.checkRow}>
-            <Text style={check.passed ? styles.checkOk : styles.checkKo}>
-              {check.passed ? '✓' : '✗'} {check.label}
-            </Text>
-            <Text style={styles.checkDetail}>{check.detail}</Text>
-          </View>
-        ))}
-
-        <View style={styles.checkRow}>
-          <Text style={booted ? styles.checkOk : styles.checkKo}>
-            {booted ? '✓' : '…'} Kernel boot + router dispatch
-          </Text>
-          <Text style={styles.checkDetail}>
-            {booted ? `matched ${String(payload?.route)}` : 'waiting for the first render'}
-          </Text>
-        </View>
-
-        {error !== undefined && (
-          <View style={styles.errorBox}>
-            <Text style={styles.errorText}>{error}</Text>
-          </View>
-        )}
-
-        {payload !== undefined && (
-          <View style={styles.payloadBox}>
-            <Text style={styles.payloadMessage}>{payload.message}</Text>
-            <Text style={styles.payloadMeta}>
-              {payload.framework.name} · {payload.framework.tagline}
-            </Text>
-          </View>
-        )}
-
-        <Text style={styles.sectionTitle}>Navigate the same domain</Text>
-        <View style={styles.buttons}>
-          <NavButton label='Home' url='stone://app/' />
-          <NavButton label='Hello Noowow' url='stone://app/hello/Noowow' />
-          <NavButton label='Hello Mr. Stone' url='stone://app/hello/Mr.%20Stone' />
-          <NavButton label='Unknown route' url='stone://app/nowhere' />
-        </View>
-      </ScrollView>
+    <View style={{ flex: 1, backgroundColor: theme.ink }}>
+      <StatusBar style='auto' />
+      <StoneNativeApp />
     </View>
   )
 }
-
-/**
- * A navigation button emitting an intent into the native event source.
- */
-function NavButton ({ label, url }: { label: string, url: string }): React.JSX.Element {
-  return (
-    <Pressable style={styles.button} onPress={() => nativeEventSource.navigate(url)}>
-      <Text style={styles.buttonText}>{label}</Text>
-    </Pressable>
-  )
-}
-
-const styles = StyleSheet.create({
-  container: { flex: 1, backgroundColor: '#141210' },
-  content: { padding: 24, paddingTop: 72 },
-  title: { color: '#f5f1ea', fontSize: 26, fontWeight: '700' },
-  subtitle: { color: '#b8b0a4', fontSize: 14, marginTop: 4, marginBottom: 20 },
-  banner: { borderRadius: 8, paddingVertical: 10, alignItems: 'center', marginBottom: 20 },
-  bannerOk: { backgroundColor: '#1f5130' },
-  bannerKo: { backgroundColor: '#5e2b1e' },
-  bannerText: { color: '#f5f1ea', fontWeight: '700', letterSpacing: 1 },
-  checkRow: { marginBottom: 12 },
-  checkOk: { color: '#7fd39a', fontSize: 15, fontWeight: '600' },
-  checkKo: { color: '#e88d70', fontSize: 15, fontWeight: '600' },
-  checkDetail: { color: '#8d8578', fontSize: 12, marginLeft: 18, marginTop: 2 },
-  errorBox: { backgroundColor: '#3a1f18', borderRadius: 8, padding: 12, marginTop: 8 },
-  errorText: { color: '#e88d70', fontSize: 13 },
-  payloadBox: { backgroundColor: '#221e1a', borderRadius: 8, padding: 16, marginTop: 16 },
-  payloadMessage: { color: '#f5f1ea', fontSize: 16, fontWeight: '600' },
-  payloadMeta: { color: '#b8b0a4', fontSize: 12, marginTop: 6 },
-  sectionTitle: { color: '#f5f1ea', fontSize: 16, fontWeight: '700', marginTop: 28, marginBottom: 12 },
-  buttons: { gap: 10 },
-  button: { backgroundColor: '#2e2823', borderRadius: 8, paddingVertical: 12, alignItems: 'center' },
-  buttonText: { color: '#f5f1ea', fontSize: 15, fontWeight: '600' }
-})

package/basic-react-native-declarative/README.md

@@ -1,49 +1,150 @@
-# Stone.js · Basic React Native starter (declarative API)
+# Stone.js - Basic React Native starter
 
-The same Stone.js domain you deploy on Node, serverless, edge or the browser, running as a **native mobile application** with React Native and Expo.
+Stone.js's basic starter to create a React Native (Expo) app using the declarative API.
 
-## What this starter demonstrates
+The same welcome screen the web starters show, on a phone. Same mark, same palette, same words,
+because it is the same domain: `app/HomeScreen.tsx` is a page, with `handle`, `head` and `render`,
+and only `render` knows it is native.
 
-- A Stone.js domain (`app/`) written with the declarative API: `@StoneApp`, `@Routing`, `@Controller`, `@Match`. The domain never knows it runs inside a native application.
-- The canonical activation paths: modules are enabled by their decorator, and the local adapter blueprint is activated through `@StoneApp(options, [blueprints])`.
-- Stage-3 decorators (2023-11) with `Symbol.metadata`, transformed by Babel under Metro (see `babel.config.js`: the semantics are set through `babel-preset-expo`'s `decorators` option).
-- The universal Stone router matching navigation intents (`stone://app/hello/:name`) exactly like it matches URLs in a browser SPA or paths behind an HTTP adapter.
-- A minimal native adapter (`adapter/`): it captures navigation intents, normalizes them into `IncomingBrowserEvent` and executes the render effect. It prefigures `@stone-js/react-native-adapter` and will be replaced by it once published.
-- The platform polyfills React Native needs (`index.ts`): the WHATWG `URL` API and, on older Hermes versions, `TextEncoder`.
+## Project Setup
 
-The start screen is a live self-check: decorators, URL API, TextEncoder, kernel boot and router dispatch are verified at runtime and shown as green or red rows.
+```sh
+npm install
+```
 
-## Run it
+### Run it
 
-```bash
-npm install
-npm run ios      # opens the iOS simulator directly
-npm start        # or the interactive way: then press i (iOS) or a (Android)
+```sh
+npm start           # Expo dev server: press i for iOS, a for Android
+npm run ios         # straight to the iOS simulator
+npm run android     # straight to an Android emulator
 ```
 
-## Develop it in a browser
+### Run it in a browser
 
-Faster than a simulator, with Fast Refresh, and the same code runs on a device afterwards. Two
-dependencies the web target needs, and one command:
+The fastest loop is often a browser tab: Fast Refresh, and the same code then runs on a device
+untouched. It is opt-in, because the web target needs two dependencies a native-only app has no
+reason to carry.
 
-```bash
+```sh
 npx expo install react-dom react-native-web
-npx expo start --web
+npm run web
 ```
 
-Your routes resolve, your loaders run, your screens render. What a browser cannot do it still
-cannot do: `react-native-web` covers the core primitives, not every native module, so a screen
-built on the camera or on secure storage has to be tried on a device.
+Use it for the domain, the navigation and most of the interface. Use a device before believing
+anything about the parts that are actually native: `react-native-web` covers the core primitives,
+not the camera, secure storage or a native gesture handler.
 
-## Test it
+### Bundle for production
+
+```sh
+npm run export      # a Hermes bytecode bundle, per platform
+```
+
+An installable build is `npx expo run:ios` or an [EAS build](https://docs.expo.dev/build/setup/):
+both need a native toolchain, and they are better commands than a wrapper would be.
+
+### Run tests
+
+```sh
+npm run test
+npm run test:cvg
+```
 
-The whole chain (domain, router, adapter) is pure JavaScript, so the exact modules the application boots are also tested under Node:
+The tests boot the real kernel, router, adapter and renderer under Node, send a deep link, and
+assert what landed on the navigation stack. No device, no simulator, no Metro.
 
-```bash
-npm test
+### Type-check
+
+```sh
 npm run typecheck
 ```
 
-## What is shared with your other platforms
+## What is where
+
+| File | What it does |
+|---|---|
+| `app/Application.ts` | Enables the router, the adapter and the renderer. Four decorators. |
+| `app/HomeScreen.tsx` | The page answering `/`. Adding a screen is adding a file like it. |
+| `app/WelcomeView.tsx` | What the screen draws, in React Native components. |
+| `app/theme.ts` | The Stone.js palette, following the device's light or dark appearance. |
+| `index.ts` | Polyfills, boot, and `registerRootComponent`. |
+| `metro.config.js` | `withStone`: collects `app/` into `.stone/modules.ts` before Metro bundles. |
+
+## Nothing lists your screens
+
+A web application never lists its pages, and this one does not either. `withStone` collects
+everything under `app/` and writes `.stone/modules.ts` whenever Metro starts, so `expo start`,
+`expo run:ios` and an EAS build all get it without anyone remembering to ask.
+
+It runs when Metro starts, not while it runs: **adding** a screen to a running dev server means
+restarting it. **Editing** one needs nothing, Fast Refresh was never involved.
+
+`.stone/` is generated. It is in `.gitignore`, and there is no reason to open it.
+
+## Navigating
+
+```tsx
+import { useNavigate, useGoBack } from '@stone-js/use-react-native'
+
+const navigate = useNavigate()
+
+navigate('/tasks/42')                  // push a screen
+navigate('/tasks/42', 'replace')       // swap the current one
+navigate('/sign-in', 'reset')          // start again, leaving no history
+```
+
+Navigation goes through the router, so a screen never renders another screen itself. `useGoBack()`
+returns `{ goBack, canGoBack }`: wire `goBack` to your header button and to Android's hardware back
+button, and let the platform leave the application when `canGoBack` is false.
+
+Deep links arrive the same way. This starter's scheme is `stone`, so `stone://app/?name=Ada` reaches
+the page that owns `/`, with `name` readable through `event.get('name')`. Change `scheme` in
+`app.json` to your own.
+
+## Using a native navigator
+
+`App.tsx` renders `StoneNativeApp`, which shows the screen on top of the stack. That is the floor,
+not the ceiling: it is what makes the first run work with nothing installed. The platform's
+transitions, the swipe-back gesture, and a screen keeping its own state while another covers it are
+things only a native navigator gives you.
+
+The stack is public state, so a navigator drives itself from it:
+
+```tsx
+import { useScreens } from '@stone-js/use-react-native'
+import { NavigationContainer } from '@react-navigation/native'
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+export default function App () {
+  const screens = useScreens()
+
+  return (
+    <NavigationContainer>
+      <Stack.Navigator>
+        {screens.map((screen) => (
+          <Stack.Screen key={screen.key} name={screen.key} options={{ title: screen.title }}>
+            {() => screen.element}
+          </Stack.Screen>
+        ))}
+      </Stack.Navigator>
+    </NavigationContainer>
+  )
+}
+```
+
+Nothing about your pages changes.
+
+## The imperative twin
+
+The same application, written with values instead of decorators, is
+[`basic-react-native-imperative`](../basic-react-native-imperative). Neither paradigm wraps the
+other; both write to the same manifest.
+
+## Learn more
 
-Domain, routing, services and data loading. Not the UI components: native screens are React Native components, browser pages are DOM components.
+- [Stone.js documentation](https://stonejs.dev/docs)
+- [`@stone-js/use-react-native`](https://www.npmjs.com/package/@stone-js/use-react-native)
+- [`@stone-js/react-native-adapter`](https://www.npmjs.com/package/@stone-js/react-native-adapter)

package/basic-react-native-declarative/app/Application.ts

@@ -1,17 +1,28 @@
 import { Routing } from '@stone-js/router'
 import { LogLevel, StoneApp } from '@stone-js/core'
-import { nativeAdapterBlueprint } from '../adapter/nativeAdapterBlueprint'
+import { ReactNative } from '@stone-js/react-native-adapter'
+import { UseReactNative } from '@stone-js/use-react-native'
 
 /**
  * Application
  *
  * This is the main application entry point.
  *
- * @Routing() enables the Stone router: incoming navigation events are matched
- * against the route definitions declared by the controllers.
- * @StoneApp() enables the Stone application (required). Extra blueprints are
- * activated through its second argument: here, the native adapter.
+ * @Routing() is used to enable the router.
+ * @ReactNative() is used to enable the React Native adapter, which turns deep links and
+ *   in-app navigation into events.
+ * @UseReactNative() is used to enable the React Native renderer, which turns what a page
+ *   resolves into a screen.
+ * @StoneApp() is used to enable the Stone application, it is required.
+ *
+ * The web starter's Application carries the same decorators with two swapped: `@Browser()` for
+ * `@ReactNative()`, `@UseReact()` for `@UseReactNative()`. That is the promise, in four lines:
+ * the domain is written once, and what changes is the context it runs in.
+ *
+ * Screens live in their own files, one route each. See `app/HomeScreen.tsx`.
  */
 @Routing()
-@StoneApp({ name: 'Stone.js Native', logger: { level: LogLevel.INFO } }, [nativeAdapterBlueprint])
+@ReactNative()
+@UseReactNative()
+@StoneApp({ logger: { level: LogLevel.INFO } })
 export class Application {}

package/basic-react-native-declarative/app/HomeScreen.tsx

@@ -0,0 +1,80 @@
+import { JSX } from 'react'
+import { WelcomeView } from './WelcomeView'
+import { ILogger, Promiseable } from '@stone-js/core'
+import { HeadContext, IPage, Page, PageHeadContext, PageRenderContext, ReactIncomingEvent } from '@stone-js/use-react-native'
+
+/**
+ * The home screen.
+ *
+ * A page, exactly as on the web: `@Page` binds it to a route, `handle` answers, `head` names it and
+ * `render` draws it. The only native thing here is what `render` returns, and it returns React
+ * Native components instead of DOM ones.
+ *
+ * Adding a screen is adding a file like this one. Nothing lists it: `withStone` collects everything
+ * under `app/` before Metro bundles.
+ */
+@Page('/')
+export class HomeScreen implements IPage<ReactIncomingEvent> {
+  /**
+   * Logger is a service for logging.
+   */
+  private readonly logger: ILogger
+
+  /**
+   * Create a new instance of HomeScreen.
+   * At this point, all the dependencies are resolved and injected.
+   *
+   * @param logger - Logger service.
+   */
+  constructor ({ logger }: { logger: ILogger }) {
+    this.logger = logger
+  }
+
+  /**
+   * Handle incoming events.
+   *
+   * A deep link carries its parameters here: `stone://app/?name=Ada` arrives as an event, and
+   * `event.get` reads from it the same way an HTTP request would be read.
+   *
+   * @param event - Incoming event.
+   * @returns The screen's data.
+   */
+  handle (event: ReactIncomingEvent): ResponseData {
+    const message = `Hello ${String(event.get<string>('name', 'World'))}!`
+
+    this.logger.info(message)
+
+    return { message }
+  }
+
+  /**
+   * Set the screen's head.
+   *
+   * A phone has no meta tags, so the title is what a navigator shows in its header. The same `head`
+   * a web page declares, read by a different renderer.
+   *
+   * @returns The head context.
+   */
+  head ({ event }: PageHeadContext): Promiseable<HeadContext> {
+    return {
+      title: `${String(event.get<string>('name', 'World'))} · Welcome to Stone.js`,
+      description: 'A universal Stone.js application. Write your domain once; Stone.js is the context that runs it anywhere.'
+    }
+  }
+
+  /**
+   * Render the screen.
+   *
+   * @returns The rendered screen.
+   */
+  render ({ data }: PageRenderContext<ResponseData>): JSX.Element {
+    return <WelcomeView message={data?.message} />
+  }
+}
+
+/**
+ * Response data
+ */
+export interface ResponseData {
+  message: string
+}

package/basic-react-native-declarative/app/PortalMark.tsx

@@ -0,0 +1,32 @@
+import { JSX } from 'react'
+import { Image, useColorScheme } from 'react-native'
+
+/**
+ * Le Portail, the Stone.js mark.
+ *
+ * The same three arcs as `public/logo.svg` in the web starters: two stone segments rising, and the
+ * keystone lit in ember. Two files rather than one, because the segments have to contrast with the
+ * ground the screen paints, exactly as the brand ships a dark-ground and a light-ground Portal.
+ *
+ * Shipped as an image on purpose. Drawing it would mean `react-native-svg`, a native module, and
+ * a starter's first job is to run on a device the moment it is installed, with nothing to link
+ * and no version to match against Expo Go's.
+ *
+ * @param props.size - Side length in points.
+ * @returns The mark.
+ */
+export function PortalMark ({ size = 104 }: { size?: number }): JSX.Element {
+  const scheme = useColorScheme()
+
+  return (
+    <Image
+      accessibilityRole='image'
+      accessibilityLabel='Stone.js'
+      source={scheme === 'light'
+        ? require('../assets/logo-light.png')
+        : require('../assets/logo-dark.png')}
+      style={{ width: size, height: size }}
+      resizeMode='contain'
+    />
+  )
+}