fix(native): share the host signal runtime with app module imports

Author: chrisbbreuer

docs/guide/native.md

@@ -639,6 +639,14 @@ When the host advertises the `fetch` capability (Craft's iOS host does), the bun
 
 Native screens use the ordinary stx signal primitives. A binding effect runs when a signal it reads changes; there is no second native-only redraw or reactivity model.
 
+Shared TypeScript helpers imported by the native app lifecycle may import runtime
+functions such as `state`, `derived` and `effect` from `@stacksjs/stx` or `stx`.
+The native bundler forwards those functions to the host's existing runtime,
+sharing its signal graph instead of loading server rendering and filesystem
+modules. Keep initialization inside the app module's default lifecycle function:
+its imports are evaluated before the host starts the runtime. Screen client
+scripts continue to use their usual auto-imports.
+
 ```stx
 <script client lang="ts">
 import { sportStyle } from '../functions/mobile'

packages/stx/src/native/compiler/bundle.ts

@@ -33,6 +33,7 @@ import { shareComponentScripts, type SharedScripts } from './shared-scripts'
 import { compactDocument, compactManifest } from '../runtime/compact-document'
 import { buildSharedModuleRegistries, registeredModuleIdsIn, registeredModuleNamesIn, type SharedRegistries } from '../../client-module-registry'
 import type { BrowserScreenOptions } from '../runtime/browser-screen'
+import { STX_RUNTIME_GLOBALS } from '../../runtime-globals'
 
 export interface CompileNativeBundleOptions {
   /** Screen name to `.stx` path, relative to `root`. */
@@ -207,6 +208,30 @@ function nativeRuntimeModule(name: 'jsc-globals' | 'shared-screen' | 'browser-sc
   return resolved
 }
 
+/**
+ * Imported app helpers use the host's existing signal graph, just like screen
+ * scripts. Resolving the server package root here would pull filesystem and
+ * build tools into a JavaScriptCore/browser bundle. Forward lazily: app module
+ * imports run before the host installs its runtime; their default function runs
+ * after it. Module bodies must keep work inside that lifecycle function.
+ */
+function nativeAuthoringRuntime(): BunPlugin {
+  return {
+    name: 'stx-native-authoring-runtime',
+    setup(builder) {
+      builder.onResolve({ filter: /^(?:stx|@stacksjs\/stx)$/ }, () => ({ path: 'api', namespace: 'stx-native-authoring-runtime' }))
+      builder.onLoad({ filter: /.*/, namespace: 'stx-native-authoring-runtime' }, () => ({
+        loader: 'js',
+        contents: STX_RUNTIME_GLOBALS.map(name => `export function ${name}(...args) {
+  const runtime = globalThis.stx;
+  if (typeof runtime?.${name} !== 'function') throw new Error('STX native runtime is not ready for ${name}');
+  return runtime.${name}(...args);
+}`).join('\n'),
+      }))
+    },
+  }
+}
+
 /**
  * Bun takes the first `onLoad` that matches a file, so the inputs are
  * tracked, and a module's stand-in (`substitutes`, by absolute path) handed
@@ -225,7 +250,7 @@ async function build(entry: string, plugins: BunPlugin[], minify: boolean, depen
     target: 'browser',
     format: 'iife',
     minify,
-    plugins: [track, ...plugins],
+    plugins: [track, nativeAuthoringRuntime(), ...plugins],
     define: { 'process.env.NODE_ENV': JSON.stringify(minify ? 'production' : 'development') },
   })
   if (!result.success) {

packages/stx/test/native/native-app.test.ts

@@ -15,11 +15,19 @@ async function generate(): Promise<string> {
   bundle ??= (async () => {
     const root = createTempDir('stx-native-app-')
     await Bun.write(path.join(root, 'Home.stx'), '<script client></script><View><Text>Home</Text></View>')
-    await Bun.write(path.join(root, 'helper.ts'), 'export function where(craft: any): string { return craft.app.url + "/api" }\n')
+    await Bun.write(path.join(root, 'helper.ts'), `import { state, effect } from '@stacksjs/stx'
+export function where(craft: any): string { return craft.app.url + "/api" }
+export function reactiveWords() {
+  const locale = state('en')
+  effect(() => { globalThis.__appLocaleWord = locale() === 'de' ? 'Bestätigt' : 'Verified' })
+  locale.set('de')
+}\n`)
     await Bun.write(path.join(root, 'app.ts'), `
-import { where } from './helper'
+import { where, reactiveWords } from './helper'
+import { batch } from 'stx'
 globalThis.__appModuleLoaded = (globalThis.__appModuleLoaded || 0) + 1
 export default function app(craft: any) {
+  batch(reactiveWords)
   globalThis.__appRan = { route: craft.route.name, api: where(craft), version: craft.app.version }
   const opened = (event: any) => craft.navigation.open(event.detail.href)
   globalThis.addEventListener('craftNotificationResponse', opened)
@@ -63,6 +71,7 @@ async function run(route: string | undefined, capabilities: string[] = ['backgro
 describe('the app script', () => {
   it('runs its default export with craft, and draws nothing', async () => {
     const { scope, sent } = await run(NATIVE_APP_ROUTE)
+    expect(scope.__appLocaleWord).toBe('Bestätigt')
     expect(scope.__appRan).toEqual({ route: NATIVE_APP_ROUTE, api: 'https://app.example/api', version: '1.2.0' })
     expect(sent.some(message => message.type === 'RENDER')).toBe(false)
     expect(scope.craft.app).toEqual({ url: 'https://app.example', version: '1.2.0', build: '7' })