@stacksjs/mobile 0.75.156 → 0.75.158

package/README.md

@@ -266,3 +266,57 @@ The phone-native behaviour a screen expects, kept out of STX templates:
 
 The framework's `NativeNavBar`, `NativePullToRefresh`, `NativeSegmentedControl`
 and `NativeSheet` components are built on these.
+
+## Native source ownership
+
+Stacks applications author TypeScript and STX. Craft distributes reusable Swift
+shells inside its package, and `buddy build:ios` generates them under
+`storage/framework/mobile/ios`. Generated Swift is ignored by the project's
+generated `.gitignore`, including optional watch and widget sources. Application
+configuration belongs in typed `config/mobile.ts`, rather than generated Swift.
+
+The build also generates executable `ci_scripts/ci_post_clone.sh`. Keep that hook,
+Xcode metadata, `craft.config.json`, assets, compiled native bundles and `bun.lock`
+in Git when using Xcode Cloud. The hook installs frozen dependencies and restores
+Swift from the installed Craft package without changing project metadata. It
+installs Bun when unavailable, using `ios.shell.bunVersion` or the Bun version
+that generated the project. Another CI can call `restoreIosShell(output)` after
+installing dependencies. Rebuild metadata and bundles when config or Craft changes.
+Existing apps must remove previously tracked Swift with `git rm --cached`; ignore
+rules do not untrack files already committed.
+
+When the app's root `.gitignore` excludes the whole mobile directory, unignore
+`/storage/framework/mobile/`, ignore its children with
+`/storage/framework/mobile/*`, then unignore `/storage/framework/mobile/ios/`.
+Keep build products and `xcuserdata` ignored. This admits cloud metadata while
+the generated iOS `.gitignore` excludes Swift.
+
+## Bun-only test tooling
+
+```ts
+import { prepareIosSimulatorDriver, serializeSimulatorSteps } from '@stacksjs/mobile/testing'
+import mobile from './config/mobile'
+
+const { output, projectName } = prepareIosSimulatorDriver(mobile.ios)
+const script = serializeSimulatorSteps([
+  { command: 'launch' },
+  { command: 'expect', text: 'Today', seconds: 10 },
+])
+```
+
+The generated test host defaults to `storage/framework/mobile/ios-driver`, targets
+`ios.bundleId`, and derives tab labels from `ios.tabs`. Customize its output,
+project name, bundle prefix, iOS deployment target (17+), and control URL through
+`ios.simulator`. Generate with xcodegen and run with xcodebuild against an installed
+app. Serve the serialized journey at `/script` and accept `/note` and `/save` on
+the control server. `TEST_RUNNER_CRAFT_TEST_CONTROL` overrides the URL per run.
+Legacy line-based scripts remain supported; failed checks also fail XCTest.
+
+`createNativeMutationValidator()` validates captured STX messages against the
+package's real Swift mutation host on macOS. It returns a disposable validator
+whose `validate(messages)` reports `exitCode`, `stdout` and `stderr`.
+
+The `/testing` entrypoint is for Bun build/test tools and is excluded from browser
+exports. The ordinary `@stacksjs/mobile` entrypoint stays browser-safe. Extend
+Craft's shared host and typed APIs for new platform features instead of editing
+generated sources.

package/dist/testing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bundled TypeScript declarations
+ * Generated from 1 source files
+ */
+
+import { IosMobileConfig } from '@stacksjs/types';
+
+// From: src/testing.ts
+/** Bun-only build/test entrypoint. The browser runtime never imports the iOS builder. */
+declare function prepareIosSimulatorDriver(config: IosMobileConfig, root?: string): { output: string, projectName: string };
+
+export { prepareIosSimulatorDriver };
+export { NativeMutationValidator } from 'craft-native/ios';
+export { NativeValidationResult } from 'craft-native/ios';
+export { SimulatorStep } from 'craft-native/ios';
+export { createNativeMutationValidator } from 'craft-native/ios';
+export { restoreShell as restoreIosShell } from 'craft-native/ios';
+export { serializeSimulatorSteps } from 'craft-native/ios';

package/dist/testing.js

@@ -0,0 +1,24 @@
+// @bun
+// src/testing.ts
+import { resolve } from "path";
+import { initSimulatorDriver } from "craft-native/ios";
+import { createNativeMutationValidator, restoreShell, serializeSimulatorSteps } from "craft-native/ios";
+function prepareIosSimulatorDriver(config, root = process.cwd()) {
+  const simulator = config.simulator ?? {};
+  const output = resolve(root, simulator.output ?? "storage/framework/mobile/ios-driver");
+  const projectName = simulator.projectName ?? "CraftDriver";
+  initSimulatorDriver({
+    ...simulator,
+    output,
+    projectName,
+    bundleId: config.bundleId,
+    tabs: config.tabs?.map((tab) => tab.title)
+  });
+  return { output, projectName };
+}
+export {
+  createNativeMutationValidator,
+  prepareIosSimulatorDriver,
+  restoreShell as restoreIosShell,
+  serializeSimulatorSteps
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/mobile",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.156",
+  "version": "0.75.158",
   "description": "Craft-powered native mobile runtime for Stacks and STX applications",
   "author": "Chris Breuer",
   "license": "MIT",
@@ -18,6 +18,12 @@
       "bun": "./dist/index.js",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "browser": null,
+      "types": "./dist/testing.d.ts",
+      "bun": "./dist/testing.js",
+      "import": "./dist/testing.js"
     }
   },
   "module": "dist/index.js",
@@ -32,10 +38,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "craft-native": ">=0.0.152"
+    "@stacksjs/types": "0.75.158",
+    "craft-native": ">=0.0.158"
   },
   "devDependencies": {
-    "@stacksjs/build": "0.75.156",
+    "@stacksjs/build": "0.75.158",
     "better-dx": "^0.2.24"
   }
 }