@stone-js/starters 0.8.11 → 0.8.13

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

@@ -0,0 +1,146 @@
+import { JSX } from 'react'
+import { PortalMark } from './PortalMark'
+import { useStoneTheme } from './theme'
+import { Linking, Platform, Pressable, StyleSheet, Text, View } from 'react-native'
+
+const DOCS = 'https://stonejs.dev/docs'
+const GITHUB = 'https://github.com/stone-foundation/stone-js-framework'
+
+/**
+ * The welcome screen.
+ *
+ * The native twin of the web starters' welcome page: the same mark, the same palette, the same
+ * words. What differs is only what a phone does differently, which is the whole point of the
+ * framework: `View` instead of `div`, a `StyleSheet` instead of a stylesheet, `Linking` instead of
+ * an anchor, and a glow drawn as a circle because there is no `radial-gradient`.
+ *
+ * @param props.message - What the handler returned.
+ * @returns The screen.
+ */
+export function WelcomeView ({ message }: { message?: string }): JSX.Element {
+  const theme = useStoneTheme()
+
+  const open = (url: string): void => { void Linking.openURL(url) }
+
+  return (
+    <View style={[styles.screen, { backgroundColor: theme.ink }]}>
+      <View style={[styles.glow, { backgroundColor: theme.inkGlow }]} pointerEvents='none' />
+
+      <View style={styles.hero}>
+        <PortalMark size={104} />
+
+        <Text style={[styles.eyebrow, { color: theme.creamDim }]}>WELCOME TO</Text>
+        <Text style={[styles.title, { color: theme.ember2 }]}>Stone.js</Text>
+        <Text style={[styles.lead, { color: theme.cream }]}>{message}</Text>
+        <Text style={[styles.tagline, { color: theme.creamDim }]}>
+          Your app is running. Write your domain once, Stone.js is the context that runs it
+          anywhere: server, serverless, browser, CLI and the edge.
+        </Text>
+
+        <View style={styles.links}>
+          <Pressable
+            accessibilityRole='link'
+            onPress={() => open(DOCS)}
+            style={[styles.pill, { borderColor: theme.line, backgroundColor: theme.card }]}
+          >
+            <Text style={[styles.pillText, { color: theme.cream }]}>Documentation</Text>
+          </Pressable>
+          <Pressable
+            accessibilityRole='link'
+            onPress={() => open(GITHUB)}
+            style={[styles.pill, { borderColor: theme.line, backgroundColor: theme.card }]}
+          >
+            <Text style={[styles.pillText, { color: theme.cream }]}>GitHub</Text>
+          </Pressable>
+        </View>
+
+        <Text style={[styles.edit, { color: theme.creamDim }]}>
+          Edit <Text style={[styles.editFile, { color: theme.ember1 }]}>app/HomeScreen.tsx</Text>
+        </Text>
+      </View>
+
+      <Text style={[styles.brand, { color: theme.creamDim }]}>
+        <Text style={{ color: theme.ember2 }}>●</Text> Stone.js · the continuum framework
+      </Text>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  screen: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 24,
+    paddingVertical: 48,
+    overflow: 'hidden'
+  },
+  // The web starter's ember glow, as the only shape a phone can draw it with.
+  glow: {
+    position: 'absolute',
+    top: '4%',
+    width: 420,
+    height: 420,
+    borderRadius: 210,
+    opacity: 0.55
+  },
+  hero: {
+    width: '100%',
+    maxWidth: 420,
+    alignItems: 'center'
+  },
+  eyebrow: {
+    marginTop: 22,
+    fontSize: 12,
+    fontWeight: '600',
+    letterSpacing: 3.4
+  },
+  title: {
+    marginTop: 6,
+    fontSize: 52,
+    fontWeight: '800',
+    letterSpacing: -1.6
+  },
+  lead: {
+    marginTop: 16,
+    fontSize: 20,
+    fontWeight: '600',
+    textAlign: 'center'
+  },
+  tagline: {
+    marginTop: 10,
+    fontSize: 15,
+    lineHeight: 24,
+    textAlign: 'center'
+  },
+  links: {
+    marginTop: 30,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    justifyContent: 'center',
+    gap: 12
+  },
+  pill: {
+    borderWidth: 1,
+    borderRadius: 12,
+    paddingVertical: 11,
+    paddingHorizontal: 18
+  },
+  pillText: {
+    fontSize: 14,
+    fontWeight: '600'
+  },
+  edit: {
+    marginTop: 18,
+    fontSize: 13,
+    fontFamily: Platform.select({ ios: 'Menlo', android: 'monospace', default: 'monospace' })
+  },
+  editFile: {
+    fontWeight: '700'
+  },
+  brand: {
+    position: 'absolute',
+    bottom: 32,
+    fontSize: 13
+  }
+})

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

@@ -0,0 +1,66 @@
+import { useColorScheme } from 'react-native'
+
+/**
+ * The Stone.js brand, "Obsidienne & Braise", as values a StyleSheet can use.
+ *
+ * The same palette the web starters paint in CSS custom properties. A native application has no
+ * cascade, so the tokens are plain values and the screen reads them through `useStoneTheme`.
+ */
+export interface StoneTheme {
+  /** The page ground. */
+  ink: string
+  /** The glow at the top of the ground, behind the mark. */
+  inkGlow: string
+  /** Primary text. */
+  cream: string
+  /** Secondary text. */
+  creamDim: string
+  /** The ember gradient, light end. Also the accent for small text. */
+  ember1: string
+  /** The ember gradient, dark end. */
+  ember2: string
+  /** Hairlines and card borders. */
+  line: string
+  /** Card and pill surfaces. */
+  card: string
+  /** The mark's two arcs. */
+  mark: string
+}
+
+const dark: StoneTheme = {
+  ink: '#14110F',
+  inkGlow: '#241C17',
+  cream: '#F4EFE6',
+  creamDim: '#A69A8C',
+  ember1: '#FFC46B',
+  ember2: '#FF5A1F',
+  line: 'rgba(244, 239, 230, 0.10)',
+  card: 'rgba(244, 239, 230, 0.05)',
+  mark: '#E2D9CC'
+}
+
+const light: StoneTheme = {
+  ink: '#F4EFE6',
+  inkGlow: '#FFFFFF',
+  cream: '#1B1613',
+  creamDim: '#6B6154',
+  // On a light ground the ember needs the darker end to stay readable, per the brand's
+  // contrast notes: `braise.clair` for large elements, `braise.texte` for small text.
+  ember1: '#E04E10',
+  ember2: '#A83A08',
+  line: 'rgba(27, 22, 19, 0.12)',
+  card: 'rgba(27, 22, 19, 0.04)',
+  mark: '#1B1613'
+}
+
+/**
+ * The palette matching the device's appearance.
+ *
+ * Dark is the default, as in the web starters: `useColorScheme` returns `null` when the platform
+ * expresses no preference, and the brand's ground is obsidian.
+ *
+ * @returns The active theme.
+ */
+export function useStoneTheme (): StoneTheme {
+  return useColorScheme() === 'light' ? light : dark
+}

package/basic-react-native-declarative/app.json

@@ -1,17 +1,24 @@
 {
   "expo": {
-    "name": "basic-react-native-declarative",
+    "name": "Stone.js",
     "slug": "basic-react-native-declarative",
+    "scheme": "stone",
     "version": "1.0.0",
     "orientation": "portrait",
     "icon": "./assets/icon.png",
-    "userInterfaceStyle": "light",
+    "userInterfaceStyle": "automatic",
+    "backgroundColor": "#14110F",
+    "splash": {
+      "image": "./assets/splash-icon.png",
+      "resizeMode": "contain",
+      "backgroundColor": "#14110F"
+    },
     "ios": {
       "supportsTablet": true
     },
     "android": {
       "adaptiveIcon": {
-        "backgroundColor": "#E6F4FE",
+        "backgroundColor": "#14110F",
         "foregroundImage": "./assets/android-icon-foreground.png",
         "backgroundImage": "./assets/android-icon-background.png",
         "monochromeImage": "./assets/android-icon-monochrome.png"

package/basic-react-native-declarative/index.ts

@@ -1,10 +1,9 @@
 /**
  * Platform polyfills come first, before anything from Stone.js loads.
  *
- * - React Native's built-in `URL` is a stub (no `pathname`, no `searchParams`);
- *   Stone.js relies on the full WHATWG URL API, so the polyfill is required.
- * - `TextEncoder` is installed only when the JS engine does not provide it
- *   (older Hermes versions).
+ * - React Native's built-in `URL` is a stub (no `pathname`, no `searchParams`), and the router
+ *   reads `pathname` on every event, so the polyfill is required rather than nice to have.
+ * - `TextEncoder` is installed only when the engine does not provide it (older Hermes).
  */
 import 'react-native-url-polyfill/auto'
 
@@ -12,11 +11,20 @@ if (typeof globalThis.TextEncoder === 'undefined') {
   require('fast-text-encoding')
 }
 
+import { stoneApp } from '@stone-js/core'
 import { registerRootComponent } from 'expo'
-
 import App from './App'
 
-// registerRootComponent calls AppRegistry.registerComponent('main', () => App);
-// It also ensures that whether you load the app in Expo Go or in a native build,
-// the environment is set up appropriately
+/**
+ * Every module under `app/`, collected at build time.
+ *
+ * Generated by `withStone` in `metro.config.js`, because collecting modules is a bundler question
+ * and Metro has no `import.meta.glob`. Never edit it, never commit it.
+ */
+import { modules } from './.stone/modules'
+
+// Boot the framework, then hand the root component to Expo. `registerRootComponent` works the same
+// in Expo Go and in a native build.
+void stoneApp({ modules }).run()
+
 registerRootComponent(App)

package/basic-react-native-declarative/metro.config.js

@@ -1,7 +1,13 @@
 const { getDefaultConfig } = require('expo/metro-config')
+const { withStone } = require('@stone-js/use-react-native/metro')
 
 /**
- * Pinning the project root keeps Metro scoped to this starter, even when the
- * starter lives inside a larger workspace (as it does in the Stone.js monorepo).
+ * `withStone` collects every module under `app/` and writes `.stone/modules.ts` before Metro
+ * bundles, because Metro resolves imports statically and has no `import.meta.glob`. It hooks in
+ * here rather than in a command on purpose: Metro loads this file whatever started it, so
+ * `expo start`, `expo run:ios` and an EAS build all get the generation without anyone asking.
+ *
+ * Pinning the project root also keeps Metro scoped to this starter, even when it lives inside a
+ * larger workspace, as it does in the Stone.js monorepo.
  */
-module.exports = getDefaultConfig(__dirname)
+module.exports = withStone(getDefaultConfig(__dirname), __dirname)

package/basic-react-native-declarative/package.json

@@ -15,14 +15,17 @@
     "ios": "expo start --ios",
     "web": "expo start --web",
     "export": "expo export",
-    "typecheck": "tsc --noEmit",
+    "modules": "node -e \"require('@stone-js/use-react-native/metro').writeManifest(process.cwd())\"",
+    "typecheck": "npm run modules && tsc --noEmit",
     "test": "vitest run",
     "test:cvg": "npm run test -- --coverage"
   },
   "dependencies": {
-    "@stone-js/browser-core": "^0.8.11",
-    "@stone-js/core": "^0.8.11",
-    "@stone-js/router": "^0.8.11",
+    "@stone-js/browser-core": "^0.8.13",
+    "@stone-js/core": "^0.8.13",
+    "@stone-js/react-native-adapter": "^0.8.13",
+    "@stone-js/router": "^0.8.13",
+    "@stone-js/use-react-native": "^0.8.13",
     "expo": "~57.0.14",
     "expo-status-bar": "~57.0.1",
     "fast-text-encoding": "^1.0.6",
@@ -32,6 +35,8 @@
   },
   "devDependencies": {
     "@babel/plugin-proposal-decorators": "^7.28.0",
+    "@stone-js/cli": "^0.8.13",
+    "@stone-js/testing": "^0.8.13",
     "@types/react": "~19.2.2",
     "@vitest/coverage-v8": "^3.0.9",
     "babel-preset-expo": "^57.0.7",

package/basic-react-native-declarative/tests/Application.spec.ts

@@ -1,65 +1,63 @@
 import { stoneApp } from '@stone-js/core'
-import { describe, it, expect, beforeAll } from 'vitest'
 import { Application } from '../app/Application'
-import { OutgoingBrowserResponse } from '@stone-js/browser-core'
-import { nativeEventSource } from '../adapter/NativeEventSource'
-import { WelcomeData, WelcomeController } from '../app/WelcomeController'
-import { onNativeError, onNativeRender } from '../adapter/renderSink'
+import { HomeScreen } from '../app/HomeScreen'
+import { ScreenStack } from '@stone-js/use-react-native'
+import { NavigationSource } from '@stone-js/react-native-adapter'
 
 /**
- * Behavioral test of the full continuum chain: the exact modules the native
- * application boots (domain + router + native adapter) are booted here under
- * Node, navigation intents are emitted, and the rendered payloads asserted.
+ * The whole application, booted under Node and asked real questions.
  *
- * The adapter is pure JavaScript, so what passes here is what runs on device;
- * only the platform checks (URL polyfill, Hermes) need the real application.
+ * Nothing is mocked. The kernel, the router, the adapter and the renderer are the ones a phone
+ * runs; what a device adds is a screen to draw on, and this asserts what the framework resolved
+ * before drawing. Two things are supplied rather than discovered, both through documented
+ * configuration: the navigation source, so the test can send a deep link, and the screen stack, so
+ * it can read what landed on it.
  *
- * The application boots ONCE for the whole suite, like on a device: default
- * blueprints are shared module-level objects, so booting the same modules
- * twice in one process would accumulate route definitions.
+ * Screens are listed here because the generated manifest (`.stone/modules.ts`) is Metro's, written
+ * when Metro starts. Under a test runner the modules are imported directly, which is the same set.
  */
-describe('Stone.js native proof of concept', () => {
-  const rendered: OutgoingBrowserResponse[] = []
-  const errors: Error[] = []
+describe('Screens', () => {
+  const screens = ScreenStack.create()
+  const navigation = NavigationSource.create({ baseUrl: 'stone://app' })
 
+  // Booted once for the whole suite, as on a device: the default blueprints are shared module
+  // objects, so booting the same modules twice in one process would accumulate route definitions.
   beforeAll(async () => {
-    onNativeRender((response) => rendered.push(response))
-    onNativeError((error) => errors.push(error))
-    await stoneApp({ modules: [Application, WelcomeController] }).run()
+    await stoneApp({
+      modules: [
+        Application,
+        HomeScreen,
+        { stone: { reactNative: { navigationSource: navigation }, useReactNative: { screenStack: screens } } }
+      ]
+    }).run()
   })
 
-  it('boots and renders the landing route on startup', () => {
-    expect(errors).toHaveLength(0)
-    expect(rendered).toHaveLength(1)
+  const settle = async (): Promise<void> => { await new Promise((resolve) => setImmediate(resolve)) }
 
-    const payload = rendered[0].content as WelcomeData
-    expect(payload.route).toBe('/')
-    expect(payload.message).toContain('Welcome to Stone.js on React Native!')
-    expect(payload.framework.name).toBe('Stone.js')
+  it('puts the home screen on the stack at launch', () => {
+    expect(screens.size()).toBe(1)
+    expect(screens.top()?.path).toBe('/')
+    expect(screens.top()?.title).toBe('World · Welcome to Stone.js')
   })
 
-  it('routes a navigation intent with a parameter to the same domain', async () => {
-    nativeEventSource.navigate('stone://app/hello/Noowow')
-    await new Promise((resolve) => setImmediate(resolve))
+  it('routes a deep link to the screen that owns it, parameters included', async () => {
+    navigation.navigate('stone://app/?name=Ada')
+    await settle()
 
-    const payload = rendered.at(-1)?.content as WelcomeData
-    expect(payload.route).toBe('/hello/Noowow')
-    expect(payload.message).toContain('Hello Noowow!')
+    expect(screens.top()?.title).toBe('Ada · Welcome to Stone.js')
   })
 
-  it('decodes encoded route parameters', async () => {
-    nativeEventSource.navigate('stone://app/hello/Mr.%20Stone')
-    await new Promise((resolve) => setImmediate(resolve))
-
-    const payload = rendered.at(-1)?.content as WelcomeData
-    expect(payload.message).toContain('Hello Mr. Stone!')
+  it('re-resolving the current route replaces it instead of stacking a duplicate', () => {
+    // The deep link above resolved `/` again with fresh data. A user walking back must not find
+    // two identical screens, so the stack swaps the top rather than growing.
+    expect(screens.size()).toBe(1)
   })
 
-  it('surfaces unknown routes through the error chain instead of crashing', async () => {
-    nativeEventSource.navigate('stone://app/nowhere')
-    await new Promise((resolve) => setImmediate(resolve))
+  it('surfaces an unknown route instead of crashing', async () => {
+    navigation.navigate('stone://app/nowhere')
+    await settle()
 
-    const lastPayload = rendered.at(-1)?.content as WelcomeData | undefined
-    expect(lastPayload?.route).not.toBe('/nowhere')
+    // An error page is still a screen: the application stays up and shows something.
+    expect(screens.top()?.path).not.toBe('/')
   })
 })

package/basic-react-native-declarative/tests/stubs/react-native.ts

@@ -0,0 +1,42 @@
+/**
+ * What `react-native` is under a Node test runner: absent.
+ *
+ * The screen imports `View`, `Text` and friends at module scope, so the specifier has to resolve to
+ * something for the application to even load. It resolves to this: the primitives as inert
+ * identifiers, which is enough because a resolved screen is a React element that has been *built*,
+ * not mounted. React never calls these components here, so there is nothing for them to do.
+ *
+ * That is the line this test draws, and it is the honest one. What runs under Node is the domain:
+ * the kernel, the router, the loader, the head. What a `View` looks like is React Native's business,
+ * and the way to see it is to run the application, either on a device or in a browser tab through
+ * `npx expo start --web`.
+ */
+const component = (name: string): string => name
+
+export const View = component('View')
+export const Text = component('Text')
+export const Image = component('Image')
+export const Pressable = component('Pressable')
+export const ScrollView = component('ScrollView')
+
+export const StyleSheet = {
+  create: <T>(styles: T): T => styles,
+  flatten: (style: unknown): unknown => style
+}
+
+export const Platform = {
+  OS: 'ios',
+  select: <T>(spec: Record<string, T>): T | undefined => spec.ios ?? spec.default
+}
+
+export const Linking = {
+  openURL: async (): Promise<void> => {},
+  getInitialURL: async (): Promise<string | null> => null,
+  addEventListener: () => ({ remove: () => {} })
+}
+
+export const useColorScheme = (): string | null => null
+
+export default {
+  View, Text, Image, Pressable, ScrollView, StyleSheet, Platform, Linking, useColorScheme
+}

package/basic-react-native-declarative/tsconfig.json

@@ -7,7 +7,6 @@
   },
   "include": [
     "app",
-    "adapter",
     "tests",
     "App.tsx",
     "index.ts",

package/basic-react-native-declarative/vitest.config.ts

@@ -1,10 +1,18 @@
+import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
-  // `experimentalDecorators` is enabled in tsconfig.json for tsc TYPING only
-  // (the framework types its decorators with the legacy signatures). At
-  // RUNTIME Stone.js requires standard 2023-11 decorators, so esbuild must
-  // ignore that flag and emit the standard semantics, `Symbol.metadata`
+  // Under Node there is no React Native, and the screen imports its primitives at module scope, so
+  // the specifier has to resolve somewhere. `tests/stubs/react-native.ts` explains what it stands
+  // for and where the line is drawn.
+  resolve: {
+    alias: {
+      'react-native': fileURLToPath(new URL('./tests/stubs/react-native.ts', import.meta.url))
+    }
+  },
+  // `experimentalDecorators` is enabled in tsconfig.json for tsc TYPING only (the framework types
+  // its decorators with the legacy signatures). At RUNTIME Stone.js requires standard 2023-11
+  // decorators, so esbuild must ignore that flag and emit the standard semantics, `Symbol.metadata`
   // included (esbuild 0.25+ implements them correctly on its own).
   esbuild: {
     tsconfigRaw: {
@@ -19,7 +27,7 @@ export default defineConfig({
     include: ['./tests/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
     coverage: {
       provider: 'v8',
-      include: ['app/**/*.ts', 'adapter/**/*.ts'],
+      include: ['app/**/*.{ts,tsx}'],
       reporter: ['text', 'html'],
       reportsDirectory: './coverage'
     }

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

@@ -0,0 +1,26 @@
+import { JSX } from 'react'
+import { View } from 'react-native'
+import { StatusBar } from 'expo-status-bar'
+import { useStoneTheme } from './app/theme'
+import { StoneNativeApp } from '@stone-js/use-react-native'
+
+/**
+ * The root component.
+ *
+ * `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 (): JSX.Element {
+  const theme = useStoneTheme()
+
+  return (
+    <View style={{ flex: 1, backgroundColor: theme.ink }}>
+      <StatusBar style='auto' />
+      <StoneNativeApp />
+    </View>
+  )
+}

package/basic-react-native-imperative/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.