@stone-js/starters 0.8.9 → 0.8.10

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.9",
-    "@stone-js/use-react": "^0.8.9",
-    "@stone-js/browser-adapter": "^0.8.9"
+    "@stone-js/core": "^0.8.10",
+    "@stone-js/use-react": "^0.8.10",
+    "@stone-js/browser-adapter": "^0.8.10"
   },
   "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.9",
-    "@stone-js/testing": "^0.8.9",
+    "@stone-js/cli": "^0.8.10",
+    "@stone-js/testing": "^0.8.10",
     "@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.9",
-    "@stone-js/use-react": "^0.8.9",
-    "@stone-js/browser-adapter": "^0.8.9"
+    "@stone-js/core": "^0.8.10",
+    "@stone-js/use-react": "^0.8.10",
+    "@stone-js/browser-adapter": "^0.8.10"
   },
   "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.9",
-    "@stone-js/testing": "^0.8.9",
+    "@stone-js/cli": "^0.8.10",
+    "@stone-js/testing": "^0.8.10",
     "@types/node": "^24.0.7",
     "@types/react": "^19.0.7",
     "@types/react-dom": "^19.0.3",

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

@@ -0,0 +1,192 @@
+import { stoneApp } from '@stone-js/core'
+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'
+
+/**
+ * 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.
+ *
+ * @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.
+ */
+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
+
+  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>
+  )
+}
+
+/**
+ * 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/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.

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

@@ -0,0 +1,35 @@
+# Stone.js · Basic React Native starter (declarative API)
+
+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.
+
+## What this starter demonstrates
+
+- 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`.
+
+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.
+
+## 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)
+```
+
+## Test it
+
+The whole chain (domain, router, adapter) is pure JavaScript, so the exact modules the application boots are also tested under Node:
+
+```bash
+npm test
+npm run typecheck
+```
+
+## What is shared with your other platforms
+
+Domain, routing, services and data loading. Not the UI components: native screens are React Native components, browser pages are DOM components.

package/basic-react-native-declarative/adapter/NativeAdapter.ts

@@ -0,0 +1,108 @@
+import { RawResponseWrapper } from './RawResponseWrapper'
+import { NativeAdapterContext, NativeResponse, RawNativeResponseOptions } from './declarations'
+import { NativeEventSource, NativeNavigationEvent, nativeEventSource } from './NativeEventSource'
+import { Adapter, AdapterEventBuilder, AdapterEventHandlerType, IBlueprint } from '@stone-js/core'
+import { IncomingBrowserEvent, IncomingBrowserEventOptions, OutgoingBrowserResponse } from '@stone-js/browser-core'
+
+/**
+ * Native proof-of-concept adapter for Stone.js.
+ *
+ * Captures navigation intents from the in-memory event source, normalizes them
+ * into `IncomingBrowserEvent` instances, sends them through the kernel and
+ * executes the deferred render effect. It is the exact native counterpart of
+ * `BrowserAdapter`, with the event source replacing `window`.
+ *
+ * Temporary by design: it prefigures `@stone-js/react-native-adapter`, which
+ * will capture real deep links (`Linking`) and app-state changes on top of the
+ * same skeleton.
+ */
+export class NativeAdapter extends Adapter<
+NativeNavigationEvent,
+NativeResponse,
+NativeEventSource,
+IncomingBrowserEvent,
+IncomingBrowserEventOptions,
+OutgoingBrowserResponse,
+NativeAdapterContext
+> {
+  private unsubscribe?: () => void
+
+  /**
+   * Creates an instance of the `NativeAdapter`.
+   *
+   * @param blueprint - The application blueprint.
+   * @returns A new instance of `NativeAdapter`.
+   */
+  static create (blueprint: IBlueprint): NativeAdapter {
+    return new this(blueprint)
+  }
+
+  /**
+   * Executes the adapter: subscribes to navigation intents and dispatches the
+   * initial event, exactly like the browser adapter dispatches its synthetic
+   * first navigation on startup.
+   *
+   * Idempotent: running again tears down the previous subscription first.
+   */
+  public async run<ExecutionResultType = undefined>(): Promise<ExecutionResultType> {
+    await this.executeHooks('onStart')
+
+    const eventHandler = this.resolveEventHandler()
+
+    await this.executeEventHandlerHooks('onInit', eventHandler)
+
+    this.unsubscribe?.()
+    this.unsubscribe = nativeEventSource.subscribe((rawEvent) => {
+      void this.eventListener(eventHandler, rawEvent)
+    })
+
+    await this.eventListener(eventHandler, { url: nativeEventSource.initialUrl })
+
+    return undefined as ExecutionResultType
+  }
+
+  /**
+   * Tear down the adapter: remove the navigation subscription and run the
+   * `onStop` hooks. Safe to call multiple times.
+   */
+  public async stop (): Promise<void> {
+    if (this.unsubscribe === undefined) { return }
+    this.unsubscribe()
+    this.unsubscribe = undefined
+    await this.executeHooks('onStop')
+  }
+
+  /**
+   * Processes one navigation intent through the kernel.
+   *
+   * @param eventHandler - The resolved kernel event handler.
+   * @param rawEvent - The raw navigation event.
+   * @returns The platform response.
+   */
+  protected async eventListener (
+    eventHandler: AdapterEventHandlerType<IncomingBrowserEvent, OutgoingBrowserResponse>,
+    rawEvent: NativeNavigationEvent
+  ): Promise<NativeResponse> {
+    const incomingEventBuilder = AdapterEventBuilder.create<IncomingBrowserEventOptions, IncomingBrowserEvent>({
+      resolver: (options) => IncomingBrowserEvent.create(options)
+    })
+
+    const rawResponseBuilder = AdapterEventBuilder.create<RawNativeResponseOptions, RawResponseWrapper>({
+      resolver: (options) => RawResponseWrapper.create(options)
+    })
+
+    const context: NativeAdapterContext = {
+      rawEvent,
+      executionContext: nativeEventSource,
+      rawResponseBuilder,
+      incomingEventBuilder
+    }
+
+    try {
+      return await this.sendEventThroughDestination(context, eventHandler)
+    } catch (error: any) {
+      const builder = await this.handleError(error, context)
+      return await this.buildRawResponse({ ...context, rawResponseBuilder: builder })
+    }
+  }
+}

package/basic-react-native-declarative/adapter/NativeErrorHandler.ts

@@ -0,0 +1,53 @@
+import { emitNativeError } from './renderSink'
+import { NativeResponse } from './declarations'
+import { NativeEventSource, NativeNavigationEvent } from './NativeEventSource'
+import {
+  ILogger,
+  IBlueprint,
+  LoggerResolver,
+  AdapterErrorContext,
+  IAdapterErrorHandler,
+  defaultLoggerResolver,
+  AdapterEventBuilderType
+} from '@stone-js/core'
+
+/**
+ * NativeErrorHandler options.
+ */
+export interface NativeErrorHandlerOptions {
+  blueprint: IBlueprint
+}
+
+/**
+ * Adapter-level error handler: logs the error and surfaces it on screen
+ * through the render sink, so a broken chain is visible instead of silent.
+ */
+export class NativeErrorHandler implements IAdapterErrorHandler<NativeNavigationEvent, NativeResponse, NativeEventSource> {
+  private readonly logger: ILogger
+
+  /**
+   * Create a NativeErrorHandler.
+   *
+   * @param options - NativeErrorHandler options.
+   */
+  constructor ({ blueprint }: NativeErrorHandlerOptions) {
+    this.logger = blueprint.get<LoggerResolver>('stone.logger.resolver', defaultLoggerResolver)(blueprint)
+  }
+
+  /**
+   * Handle an error.
+   *
+   * @param error - The error to handle.
+   * @param context - The context of the adapter.
+   * @returns The raw response builder.
+   */
+  public handle (
+    error: Error,
+    context: AdapterErrorContext<NativeNavigationEvent, NativeResponse, NativeEventSource>
+  ): AdapterEventBuilderType<NativeResponse> {
+    this.logger.error(error.message, { error })
+    emitNativeError(error)
+
+    return context.rawResponseBuilder
+  }
+}

package/basic-react-native-declarative/adapter/NativeEventSource.ts

@@ -0,0 +1,58 @@
+/**
+ * The native cause captured by the adapter: an intent to show a URL.
+ *
+ * On a real device this is what a deep link, a push-notification tap or an
+ * in-app navigation collapses to. The proof-of-concept models all of them as
+ * one tiny in-memory event source; the future `@stone-js/react-native-adapter`
+ * will plug `Linking` and `AppState` into the exact same shape.
+ */
+export interface NativeNavigationEvent {
+  /** The URL to resolve, e.g. `stone://app/hello/Noowow`. */
+  url: string
+  /** Optional navigation metadata, mirroring the browser's `history.state`. */
+  metadata?: unknown
+}
+
+/**
+ * A navigation listener registered by the adapter.
+ */
+export type NativeNavigationListener = (event: NativeNavigationEvent) => void
+
+/**
+ * The in-memory navigation event source: the native counterpart of `window`
+ * for the browser adapter. It is pure JavaScript, so the same code runs under
+ * React Native, Node (tests) and anywhere else.
+ */
+export class NativeEventSource {
+  /** The synthetic first event, dispatched when the adapter starts. */
+  public readonly initialUrl = 'stone://app/'
+
+  private readonly listeners = new Set<NativeNavigationListener>()
+
+  /**
+   * Register a navigation listener.
+   *
+   * @param listener - The listener to register.
+   * @returns A teardown function removing the listener.
+   */
+  subscribe (listener: NativeNavigationListener): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /**
+   * Emit a navigation intent, exactly like the router does in the browser
+   * through the `@stonejs/router.navigate` custom event.
+   *
+   * @param url - The URL to navigate to.
+   * @param metadata - Optional navigation metadata.
+   */
+  navigate (url: string, metadata?: unknown): void {
+    this.listeners.forEach((listener) => listener({ url, metadata }))
+  }
+}
+
+/**
+ * The application-wide event source instance.
+ */
+export const nativeEventSource = new NativeEventSource()

package/basic-react-native-declarative/adapter/RawResponseWrapper.ts

@@ -0,0 +1,30 @@
+import { IRawResponseWrapper } from '@stone-js/core'
+import { NativeResponse, RawNativeResponseOptions } from './declarations'
+
+/**
+ * Wraps the raw native response: the platform effect is the deferred `render`
+ * closure contributed by the response middleware, executed once the kernel has
+ * resolved the outgoing response.
+ */
+export class RawResponseWrapper implements IRawResponseWrapper<NativeResponse> {
+  /**
+   * Factory method to create an instance of `RawResponseWrapper`.
+   *
+   * @param options - The raw response options.
+   * @returns A new instance of `RawResponseWrapper`.
+   */
+  static create (options: RawNativeResponseOptions): RawResponseWrapper {
+    return new this(options)
+  }
+
+  private constructor (private readonly options: RawNativeResponseOptions) {}
+
+  /**
+   * Execute the deferred render effect and return its result.
+   *
+   * @returns The platform response.
+   */
+  async respond (): Promise<NativeResponse> {
+    return await this.options?.render?.()
+  }
+}

package/basic-react-native-declarative/adapter/declarations.ts

@@ -0,0 +1,40 @@
+import { RawResponseWrapper } from './RawResponseWrapper'
+import { NativeEventSource, NativeNavigationEvent } from './NativeEventSource'
+import { AdapterContext, IAdapterEventBuilder, RawResponseOptions } from '@stone-js/core'
+import { IncomingBrowserEvent, IncomingBrowserEventOptions, OutgoingBrowserResponse } from '@stone-js/browser-core'
+
+/**
+ * The platform identifier exposed on every incoming event's source.
+ */
+export const NATIVE_PLATFORM = 'react-native'
+
+/**
+ * The raw platform response. The native platform has no transport response:
+ * the effect is a render, so the raw response is whatever the renderer returns.
+ */
+export type NativeResponse = unknown
+
+/**
+ * Raw response options carrying the deferred `render` effect, mirroring the
+ * browser adapter's contract.
+ */
+export interface RawNativeResponseOptions extends RawResponseOptions {
+  render?: () => NativeResponse | Promise<NativeResponse>
+}
+
+/**
+ * The adapter context for the native proof-of-concept adapter.
+ */
+export type NativeAdapterContext = AdapterContext<
+NativeNavigationEvent,
+NativeResponse,
+NativeEventSource,
+IncomingBrowserEvent,
+IncomingBrowserEventOptions,
+OutgoingBrowserResponse
+>
+
+/**
+ * The response builder used by the native adapter middleware.
+ */
+export type NativeAdapterResponseBuilder = IAdapterEventBuilder<RawNativeResponseOptions, RawResponseWrapper>

package/basic-react-native-declarative/adapter/middleware.ts

@@ -0,0 +1,73 @@
+import { emitNativeRender } from './renderSink'
+import { NextMiddleware } from '@stone-js/core'
+import { CookieCollection } from '@stone-js/browser-core'
+import { NATIVE_PLATFORM, NativeAdapterContext, NativeAdapterResponseBuilder } from './declarations'
+
+/**
+ * Transforms the raw navigation event into the intention: an
+ * `IncomingBrowserEvent`, reused as-is from `@stone-js/browser-core`.
+ *
+ * This is the native mirror of the browser adapter's IncomingEventMiddleware:
+ * `location` comes from the event's URL instead of `window.location`, and the
+ * cookie collection is purely in memory (no `document`).
+ */
+export class IncomingEventMiddleware {
+  /**
+   * Handle the incoming raw event.
+   *
+   * @param context - The adapter context.
+   * @param next - The next middleware.
+   * @returns The response builder.
+   */
+  async handle (
+    context: NativeAdapterContext,
+    next: NextMiddleware<NativeAdapterContext, NativeAdapterResponseBuilder>
+  ): Promise<NativeAdapterResponseBuilder> {
+    const url = new URL(context.rawEvent.url)
+
+    context
+      .incomingEventBuilder
+      .add('url', url)
+      .add('queryString', url.search)
+      .add('protocol', url.protocol.replace(':', ''))
+      .add('metadata', context.rawEvent.metadata ?? {})
+      .add('cookies', CookieCollection.create(undefined, {}))
+      .add('source', {
+        rawEvent: context.rawEvent,
+        platform: NATIVE_PLATFORM,
+        rawContext: context.executionContext
+      })
+
+    return await next(context)
+  }
+}
+
+/**
+ * Contributes the deferred render effect: once the kernel has produced the
+ * outgoing response, hand it to the registered render target.
+ *
+ * This is the native mirror of the role `BrowserResponseMiddleware` plays for
+ * the browser platform in `@stone-js/use-react`.
+ */
+export class ResponseMiddleware {
+  /**
+   * Handle the outgoing response.
+   *
+   * @param context - The adapter context.
+   * @param next - The next middleware.
+   * @returns The response builder.
+   */
+  async handle (
+    context: NativeAdapterContext,
+    next: NextMiddleware<NativeAdapterContext, NativeAdapterResponseBuilder>
+  ): Promise<NativeAdapterResponseBuilder> {
+    context.rawResponseBuilder.add('render', () => {
+      if (context.outgoingResponse !== undefined) {
+        emitNativeRender(context.outgoingResponse)
+      }
+      return context.outgoingResponse
+    })
+
+    return await next(context)
+  }
+}