diff --git a/content/guide/pathways.md b/content/guide/pathways.md
new file mode 100644
index 00000000..4b28299e
--- /dev/null
+++ b/content/guide/pathways.md
@@ -0,0 +1,37 @@
+---
+title: 'Development options: TypeScript or SwiftUI'
+description: NativeScript is your development runtime, not your production runtime. Write SwiftUI and develop it live, or write TypeScript and compile the release to native code.
+contributors:
+  - NathanWalker
+---
+
+NativeScript has always run your app on a JavaScript runtime with direct access to every platform API. It now offers
+two development options that keep that experience and ship **no JavaScript runtime at all**:
+
+|                      | 1. SwiftUI, live                                                                                  | 2. TypeScript, compiled                                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **You write**        | SwiftUI, in an Xcode project                                                                      | TypeScript with `@nativescript/core` and the framework you like (Angular, Vue, React, Svelte, Solid, plain TypeScript) |
+| **While developing** | NativeScript runs your SwiftUI views live: each save is on screen in about 0.15–0.5 s, state kept | `ns run`: the JavaScript runtime with HMR, Chrome DevTools and the whole npm ecosystem, exactly as today               |
+| **What ships**       | Your Swift, built by Xcode as usual                                                               | Your app compiled to Swift (iOS) and Kotlin (Android) by `ns build --compiled`                                         |
+| **Platforms**        | iOS; Android live development, rendered by Jetpack Compose                                        | iOS and Android                                                                                                        |
+| **Status**           | [Preview](/guide/swiftui-live)                                                                    | [Alpha](/guide/publishing/compiled)                                                                                    |
+
+Both rest on the same idea: **develop live, ship native.** The development runtime gives you instant feedback; the
+release is the native code a platform developer would have shipped.
+
+## Which one fits
+
+- **You know SwiftUI, or you are starting an iOS-first app in Swift**: take [SwiftUI, live](/guide/swiftui-live).
+  You keep Xcode, Swift and your project as they are; NativeScript only shortens the edit-to-screen loop.
+- **You know web development, or you already have a NativeScript app**: take
+  [TypeScript, compiled](/guide/publishing/compiled). Nothing changes while you develop. The release build is
+  compiled instead of bundled.
+
+The two meet at the release: both ship native code with no engine inside, and both are checked the same way,
+pixel by pixel against the build they replace.
+
+## The JavaScript runtime is not going anywhere
+
+A release on the JavaScript runtime (`ns build --release`) remains the default and is fully supported. Compiled
+releases are opt-in, per build or per platform, and you can switch back with `--no-compiled` at any time. See
+[Publishing](/guide/publishing/).
diff --git a/content/guide/publishing/compiled-android.md b/content/guide/publishing/compiled-android.md
new file mode 100644
index 00000000..14f7a6ca
--- /dev/null
+++ b/content/guide/publishing/compiled-android.md
@@ -0,0 +1,75 @@
+---
+title: 'Compiled releases: Android'
+description: Requirements, signing, threading annotations, R8 and mapping crashes back to TypeScript in a compiled Android release.
+contributors:
+  - NathanWalker
+---
+
+## Requirements
+
+- **JDK 17** or newer and the **Android SDK**. The compiler ships its own Gradle wrapper.
+- macOS or Linux. Windows is not supported yet.
+- The app runs on **Android 7 (API 24)** and later.
+
+## Build, sign, run
+
+A compiled build is a release build, and Android signs every release, so all four `--key-store-*` options are
+required:
+
+```bash
+ns build android --compiled --key-store-path release.keystore --key-store-password … \
+  --key-store-alias … --key-store-alias-password …     # signed .apk; add --aab for a bundle
+ns run android --compiled --key-store-path …           # build, install and launch
+```
+
+They sign as Android Studio does. To try a build before you have your upload key, make a throwaway keystore (see
+[Getting started](/guide/publishing/compiled-getting-started#_2-build-and-run)).
+
+Android installs an app over another only when both are signed with the same key. Moving between a debug build
+(signed with the SDK's debug key) and a release signed with another key fails with "a previously installed package
+of the same name has a different signature": uninstall first (`adb uninstall <app id>`).
+
+## The Gradle project
+
+`platforms/compiled/android` is a Gradle project, regenerated on every build. App_Resources carry over as the CLI
+carries them: `res/`, `AndroidManifest.xml` (merged with plugins'), `app.gradle` and `before-plugins.gradle`, and
+fonts. Plugins' Java, Kotlin and Gradle dependencies are linked unchanged.
+
+The kit marks main-thread code `@UiThread` and code that may run on any thread `@AnyThread`, and Android lint
+checks calls against them.
+
+`fetch` and `XMLHttpRequest` are not available on Android yet. They are on iOS.
+
+## Minification (R8)
+
+Members reached by name at run time (a method called on an `any` value, `typeof x.getFoo`, `'getFoo' in x`) are
+kept from R8's renaming by a scan of the compiled code. A name computed at run time (`x[name]()` with `name` built
+from strings) isn't found by the scan: keep such members with a ProGuard rule in
+`App_Resources/Android/app.gradle`, and check the minified release on a device.
+
+By default every class and member of the kit is kept. `android: { release: { narrowKitKeeps: true } }` keeps only
+what the kit's reflection needs and lets R8 remove the rest: on Recipes (Vue) the kit's dex goes from 3.3 to 2.0 MB
+and the APK from 2.44 to 1.92 MB. It is opt-in until it has been checked on larger apps; under it, a kit member
+reached only through a computed name is removed.
+
+## Crashes and debugging
+
+Kotlin has no source-location directive, so the build writes a line table (`source-lines.json`) beside the Gradle
+project. `ns-native-retrace` reads a stack trace in your TypeScript lines: it runs R8's retrace with the build's
+`mapping.txt`, then maps your app's frames to your files and the kit's frames to `@nativescript/core` files.
+
+```bash
+adb logcat -d -s AndroidRuntime | npx ns-native-retrace platforms/compiled/android
+npx ns-native-retrace platforms/compiled/android crash.txt    # a trace saved from your crash reporter
+```
+
+Keep `mapping.txt` and `source-lines.json` with each release you upload. When the Kotlin compile fails, `ns build`
+prints each error at the TypeScript line it came from.
+
+`error.stack` lists native frames, such as `class.method(File.kt:line)`, which `ns-native-retrace` maps. Uncaught
+errors go to `Application.uncaughtErrorEvent` and are logged as `***** Fatal JavaScript exception *****` (logcat
+tag `JS`). Debug a compiled release in Android Studio, as a native app.
+
+## Build times
+
+Measured on a blank app with R8, 2026-10-13: the first build takes a minute or two, a one-line change about 45 s.
diff --git a/content/guide/publishing/compiled-configuration.md b/content/guide/publishing/compiled-configuration.md
new file mode 100644
index 00000000..279a5512
--- /dev/null
+++ b/content/guide/publishing/compiled-configuration.md
@@ -0,0 +1,66 @@
+---
+title: 'Compiled releases: configuration'
+description: The release options in nativescript.config.ts, how the flag and the config combine, and what an app may need to add.
+contributors:
+  - NathanWalker
+---
+
+## Turning it on
+
+`--compiled` on `ns build`, `ns run` or `ns deploy` compiles that release, and implies `--release`. To make it the
+default, set `release.compiled` in `nativescript.config.ts`:
+
+```ts
+// nativescript.config.ts
+export default {
+  id: 'org.example.app',
+  release: {
+    compiled: true, // every release build is compiled
+  },
+  android: {
+    release: { compiled: false }, // except Android's
+  },
+} as NativeScriptConfig
+```
+
+- `--compiled` and `--no-compiled` win over the config.
+- `ios.release` and `android.release` merge over the top-level `release`; object options merge by key.
+- Debug builds always run on the JavaScript runtime.
+
+The compiler reads `nativescript.config.ts` without running it: it takes the object literal after `export default`
+(an `as` or `satisfies` is fine). A value computed in code, or a config exported through a variable, isn't seen.
+
+## Options
+
+All of them go in `release`, or in a platform's `release`.
+
+| Option                         | What it does                                                                                                                                                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `compiled`                     | Release builds are compiled instead of bundled for the JavaScript runtime.                                                                                                                   |
+| `pluginReplacements`           | `{ 'package': './path.ts' }`: replaces a package with a module of yours that has the same exports. For plugins that only make sense with a JavaScript runtime, such as over-the-air updates. |
+| `pluginSources`                | `{ 'package': '../checkout' }`: compiles a plugin from a local checkout of its source instead of fetching the published revision.                                                            |
+| `allowUnimplementedProperties` | Builds even when the app sets a core property the compiled build doesn't apply, with a warning for each.                                                                                     |
+| `allowCoreMismatch`            | Builds with a `@nativescript/core` other than the one the compiler was made from, with a warning.                                                                                            |
+| `allowUntestedFrameworks`      | Builds with a framework version outside the [tested ones](/guide/publishing/compiled-differences#tested-framework-versions), with a warning.                                                 |
+| `narrowKitKeeps`               | Android: R8 keeps only what the kit's reflection needs. See [Android](/guide/publishing/compiled-android#minification-r8).                                                                   |
+| `generatedKit`                 | Android: `false` builds on the older hand-written kit instead of the one generated from core.                                                                                                |
+
+## What your app may need
+
+Most apps need nothing but the flag. Of the apps compiled so far, none changed their own source; some added
+configuration:
+
+| Situation                                                                       | What to do                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A plugin that only makes sense with a JavaScript runtime (over-the-air updates) | `pluginReplacements: { '@norrix/client-sdk': './release/norrix.ts' }`                                                                                                                                  |
+| A plugin whose published source can't be found, or doesn't match its JavaScript | `pluginSources: { 'some-plugin': '../some-plugin' }`                                                                                                                                                   |
+| You patch a plugin with patch-package                                           | Write the same patch against the plugin's TypeScript source, in `native-release/patches/<package>+<version>.patch`. The compiler compiles the source, not the published JavaScript your patch changes. |
+| You patch `@nativescript/core` with patch-package                               | The compiler recognizes common core patches and applies their effect. One it doesn't recognize stops the build.                                                                                        |
+| An `Info.plist` with no `UIApplicationSceneManifest` (older templates)          | Nothing: the build adds the template's and says so.                                                                                                                                                    |
+
+## Hooks
+
+Your project's hooks run as they do for a JavaScript build: `before-prepare`/`after-prepare` and
+`before-buildIOS`/`after-buildIOS` (`buildAndroid` on Android), with the same arguments. In a compiled build
+`projectRoot` is `platforms/compiled/<platform>`, so a hook that edits the Xcode or Gradle project under
+`platforms/ios` or `platforms/android` has nothing to change.
diff --git a/content/guide/publishing/compiled-differences.md b/content/guide/publishing/compiled-differences.md
new file mode 100644
index 00000000..5eebe4da
--- /dev/null
+++ b/content/guide/publishing/compiled-differences.md
@@ -0,0 +1,316 @@
+---
+title: 'Compiled releases: what works'
+description: The frameworks, apps, plugins and JavaScript a compiled release supports, what the build refuses, and where it still behaves differently from the JavaScript release.
+contributors:
+  - NathanWalker
+---
+
+<!-- The tables come from SUPPORT.md in NativeScript/swiftui-live, which tools/support-table.py generates from the compiler's test results (test262, the differential cases, the semantics list and the milestone runs). Regenerate and copy rather than editing a row by hand. -->
+
+A [compiled release](/guide/publishing/compiled) runs your TypeScript as Swift and Kotlin, against a runtime that
+reproduces JavaScript's semantics. This page lists what is checked, what the build refuses, and where a compiled
+release still behaves differently from the JavaScript release. The status is as of 2026-10-15.
+
+## Frameworks and apps
+
+Each app is compared with its own JavaScript release build, screenshot by screenshot.
+
+| App                                           | iOS                                                                       | Android                                                         |
+| --------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| XML + TypeScript gallery                      | Identical (0 px)                                                          | Identical (0 px, minified)                                      |
+| Vue gallery                                   | 189 of 191 shots identical; a text caret (timing) and one HtmlView differ | Identical (0 px, minified)                                      |
+| Angular gallery                               | Identical (0 px)                                                          | Identical (0 px, minified)                                      |
+| Svelte 5 gallery                              | Identical (0 px)                                                          | Identical (0 px, minified)                                      |
+| OpenJS app (Angular, eight plugins)           | Builds and launches                                                       | 47 of 49 shots identical; the other two are run-to-run variance |
+| ns-duo-guitar (Angular, WebGPU, audio worker) | On the App Store                                                          | On Google Play                                                  |
+
+React, Solid and Octane compile with the same pipeline and are supported; they are not in the comparison runs above.
+
+### Tested framework versions
+
+The build stops on a framework version outside these (`release.allowUntestedFrameworks: true` builds anyway, with a
+warning).
+
+| Framework                 | Packages and versions                                                                                           |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Vue                       | `nativescript-vue` 3.1 and later 3.x                                                                            |
+| Angular                   | `@nativescript/angular` and `@angular/core` 22.x                                                                |
+| React                     | `react-nativescript` 5.x with `react` 18.2 or later 18.x                                                        |
+| Solid                     | `@nativescript-community/solid-js` and `solid-js` 2.x (from 2.0.0-rc.0)                                         |
+| Svelte                    | `@nativescript-community/svelte-native` 1.x with `svelte` 4.2+, or 5.x (from 5.0.0-alpha.0) with `svelte` 5.50+ |
+| Octane                    | `@nativescript-community/octane` 0.2.4 and later 0.2.x                                                          |
+| Plain TypeScript with XML | Core's own Builder: `{{ }}` bindings, code-behind, custom components and ListView templates                     |
+
+Framework features not supported yet stop the build with a message. The main ones:
+
+- **Angular:** under zone.js, a component that doesn't set `changeDetection: ChangeDetectionStrategy.Default`;
+  pipes other than `async`; a pipe inside `*ngFor`/`@for`; more than one `@Component` in a file. RxJS is a subset.
+- **React:** a component body may hold function declarations, variable declarations and the `return`; a bare
+  statement such as `useEffect(() => …, [])` on its own line is refused. JSX spread attributes are refused.
+- **Vue:** `<style module>`, `<style src>`, a prop `default`, and Options API keys other than `name`, `components`,
+  `props`, `emits`, `data`, `computed`, `methods`, `watch` and `setup`.
+
+## Plugins and platform APIs
+
+| Kind of plugin                                                       | In a compiled release                                                   |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| TypeScript over native APIs (most plugins)                           | Compiled from the plugin's source, as part of your app                  |
+| Native code in `platforms/ios` / `platforms/android`                 | Linked unchanged                                                        |
+| Installs objects into the JavaScript engine (`@nativescript/canvas`) | Needs a native counterpart in the kit; canvas has one on both platforms |
+| Only meaningful with a JavaScript runtime (over-the-air updates)     | Replace it with `release.pluginReplacements`                            |
+
+Plugin native packaging not carried yet stops the build: a prebuilt `.framework` or `.a` (an `.xcframework` is
+fine), a resource `.bundle`, a `.podspec`; on Android, `jniLibs/`, `.so` files, `assets/` and `cpp/` in a plugin's
+`platforms/android`, and its `buildscript.gradle`, `rootbuildscript.gradle`, `include-settings.gradle` or
+`before-plugins.gradle`.
+
+The web globals the NativeScript runtime provides are there on both platforms: `crypto` (`randomUUID`,
+`getRandomValues`, and `subtle` with SHA digests, HMAC and RSA-OAEP), `TextEncoder`/`TextDecoder`, `atob`/`btoa`,
+timers, `queueMicrotask` and `console`. `fetch`, `XMLHttpRequest`, `FormData`, `Blob` and `AbortController` are
+available on iOS only.
+
+## What the build refuses
+
+Before anything is compiled, the compiler checks the app and the plugin code it reaches, and reports each of these
+with the file, the line and what to write instead, all at once.
+
+| Construct                                                                         | Why                                          | Instead                                                                                |
+| --------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `new Proxy(…)`                                                                    | No traps without a JavaScript engine         | A class with explicit getters and setters, or a `Map` for dynamic keys                 |
+| `Reflect.*`                                                                       | Not provided by the runtime                  | The operation itself: `obj[key]`, `key in obj`, `Object.keys(obj)`, `new Cls(...args)` |
+| `eval(…)`, `new Function(…)`                                                      | There is no engine to evaluate code          | A lookup of known functions, or keep this app on the JavaScript release                |
+| `FinalizationRegistry`                                                            | Finalizers don't run                         | Release the resource explicitly (`dispose()`, `unloaded`, `disposeNativeView`)         |
+| `SharedArrayBuffer`, `Atomics`                                                    | No shared memory between workers             | An `ArrayBuffer`, with copies posted between workers                                   |
+| `with (obj) { … }`                                                                |                                              | Name the object explicitly                                                             |
+| `import(expr)`, `require(expr)` with a computed specifier                         | Every module is linked when the app is built | Import each module by a literal path, and choose among them at run time                |
+| `arguments.callee`, `__proto__`                                                   |                                              | A named function; `Object.getPrototypeOf`                                              |
+| A bundler constant nothing defines (`declare const __API_URL__`, `process.env.X`) | It would read as undefined                   | Define it: Vite's `define` and webpack's `DefinePlugin` values are compiled in         |
+
+The build also stops when:
+
+- **`@nativescript/core` isn't the core the compiler was made from.** Install the version the message names
+  (`release.allowCoreMismatch: true` builds anyway, with a warning).
+- **The toolchain is missing or too old:** Xcode 26 for iOS; JDK 17 and the Android SDK for Android.
+- **A language construct isn't supported yet**, such as a class declared inside a function that reads the function's
+  own variables, and on iOS a `default` clause before other cases or a `return` or `throw` in a `finally` block.
+- **A library member isn't provided yet:** `Object.create`, `String.prototype.normalize`, `Intl.Collator`,
+  `Intl.PluralRules`, `Intl.RelativeTimeFormat`, a class expression (`const Mixin = (B) => class extends B {}`) and
+  an array literal with holes (`[1, , 3]`). `Intl.NumberFormat`, `Intl.DateTimeFormat`, `toLocaleString` and the
+  ES2023 array and grouping methods are provided.
+
+A few valid constructs still fail later, in the Swift or Kotlin compile, reported at your TypeScript line. The ones
+known today are listed in [Not fixed yet](#not-fixed-yet).
+
+## JavaScript coverage
+
+The compiler is also run against [test262](https://github.com/tc39/test262), the JavaScript conformance suite.
+"Behaves as Node" is the share of the tests the compiler accepts whose output matches Node. "Refused" are tests
+stopped at build time, most of them by constructs above or by code no typed app contains. test262 exercises edge
+cases far more than apps do: read this as a map of where differences live, not as how much of an app works.
+
+| Area                             | Tests | iOS behaves as Node | Android behaves as Node | iOS refused | Android refused |
+| -------------------------------- | ----: | ------------------: | ----------------------: | ----------: | --------------: |
+| String                           |   916 |                 58% |                     52% |         276 |             269 |
+| Template literals                |    84 |                 54% |                     48% |           0 |               1 |
+| Array                            |  2687 |                 34% |                     27% |        1378 |            1338 |
+| Number                           |   294 |                 77% |                     82% |          81 |              87 |
+| Math                             |   169 |                 83% |                     87% |          11 |              11 |
+| JSON                             |   136 |                 73% |                     76% |           7 |               7 |
+| Object                           |   549 |                 73% |                     61% |          56 |              85 |
+| Map                              |   165 |                 82% |                     78% |          71 |              70 |
+| Set                              |   162 |                 63% |                     83% |          94 |              94 |
+| Promise                          |   675 |                 19% |                     55% |         160 |             173 |
+| Date                             |   327 |                 64% |                     66% |          85 |              88 |
+| RegExp                           |   830 |                 56% |                     55% |          41 |             137 |
+| Destructuring                    |   651 |                 23% |                     35% |          55 |              57 |
+| Classes                          |   666 |                 20% |                     19% |         109 |              94 |
+| Getters and setters              |    64 |                  4% |                      2% |           3 |               2 |
+| Closures and scope               |   366 |                 30% |                     42% |           9 |               7 |
+| Optional chaining and nullish    |   140 |                 52% |                     73% |           2 |               3 |
+| typeof and equality              |   161 |                 47% |                     68% |           3 |               4 |
+| Exceptions                       |   295 |                 45% |                     37% |          15 |              10 |
+| **Total** (with 5 harness tests) |  9342 |                 50% |                     50% |        2456 |            2537 |
+
+test262 `d53ebc8b19`, compiler 2026-10-14. App-shaped code is held to a stricter bar: 271 differential cases, each
+run under Node and compiled, all matching except those under [Not fixed yet](#not-fixed-yet).
+
+## Known differences at run time
+
+These compile and run, and behave differently from the JavaScript release. The most likely to affect an app come
+first.
+
+### `null` and `undefined` are one value in a typed optional (iOS and Android)
+
+Where a type admits both (`name?: string | null`), `=== null` and `=== undefined` don't tell them apart: depending
+on where the value is held, an explicit `null` reads as `undefined`, or as both, and `undefined` passed to a
+parameter `x?: string | null` can read as `null`. A destructuring default applies to `null`. Where the value is held
+typed, `JSON.stringify` leaves the key out instead of writing `null`.
+
+**Instead:** test with `== null`, which is true for both. Where an API needs an explicit `null` in JSON, build that
+JSON by hand.
+
+### A value of the wrong type throws a `TypeError` (iOS and Android)
+
+JavaScript keeps a value of the wrong type and carries on. In your app's code, a compiled release throws a
+`TypeError` you can catch: when an untyped value (`any`, parsed JSON) is assigned where a class, a string, a number
+or a boolean is declared, and on a downcast to the wrong subclass (`shape as Circle` holding a `Square`). Core's own
+untyped paths, such as XML attributes and bindings, convert as JavaScript does (a binding's `5` for a string is
+`"5"`).
+
+Parsed JSON typed as an interface reads a missing string field as `''` and a missing number as `NaN`, where
+JavaScript has `undefined`.
+
+**Instead:** validate parsed data before you type it, and mark fields that may be missing optional (`age?: number`).
+
+### A class's getters, setters and methods are not found by name (iOS)
+
+In an app built with a framework, a member a class declares as a getter, a setter or a method is undefined when
+read through `any` or a computed key: `(order as any).total`, `order[key]`, `'total' in order`. An assignment
+through `any` doesn't run the setter. Fields are found. Android finds all of them, and so does iOS in an XML app,
+where core's bindings read them.
+
+**Instead:** read members through a typed reference. For duck typing, test a field, or use `instanceof`.
+
+### Functions in arrays, `Set`s and `Map`s are not found again (iOS; Android for methods)
+
+A function read twice is `===` to itself, so `obj.off('tap', handler)` works. But on iOS a function stored in an
+array, a `Set` or as a `Map` key isn't found by `indexOf`, `includes`, `has`, `delete` or `get`. On Android this
+applies to a method read as a value (`[this.onTap].indexOf(this.onTap)`).
+
+**Instead:** have `on()` return a subscription object or an id, and remove by that.
+
+### Pages and views can stay in memory (iOS)
+
+iOS frees objects by reference counting. A closure that a page's view holds and that captures the page
+(`button.on('tap', () => this.save())`) is a cycle, so a page you navigated away from can stay in memory. Core's own
+references don't cause this. A `WeakMap` value that refers to its own key keeps both alive; on Android, a
+`WeakRef`'s target is held until memory runs low.
+
+**Instead:** remove the listeners you add in `unloaded` or `navigatedFrom`, or reach the page through a `WeakRef`.
+
+### Native callbacks from other threads run on the main thread (iOS and Android)
+
+A callback a native API calls on a background thread runs on the main thread. One that returns nothing runs later,
+as a task. One that returns a value runs while the calling thread waits, so it deadlocks if the main thread is
+waiting for that thread.
+
+**Instead:** don't block the main thread on a native thread that calls back into your code. Do heavy work in a
+[worker](/guide/multithreading) or in native code.
+
+### Regular expressions (iOS and Android)
+
+On iOS, a capture group that took no part in the match reads `''`, not `undefined` (`/(a)|(b)/.exec('b')[1]`), and
+a capture inside a repeated group keeps an earlier iteration's value. On both platforms, a `replace` callback's
+group parameter declared `string` isn't `=== undefined` for such a group.
+
+**Instead:** test with `!m[1]` or `m[1] || fallback`, and declare `replace` callback groups optional
+(`(all, x?: string) => …`).
+
+### Arrays with holes (iOS and Android)
+
+An array with holes (written past its end, or `new Array(n)` not filled) doesn't behave as in JavaScript: writing
+past the end of an array of objects can stop the app on iOS, and iteration and `Object.keys` treat holes
+differently.
+
+**Instead:** `push`, or create the array at its length with values (`new Array(n).fill(0)`).
+
+### Missing values on iOS can stop the app
+
+A member of `undefined` or `null` read, set or called, and a module constant read before its declaration runs, stop
+the app on iOS instead of throwing a `TypeError` or `ReferenceError`. Deep mutual recursion (two functions calling
+each other) also stops it; a single recursive function throws a `RangeError`.
+
+### Strings (iOS and Android)
+
+- `str[i]` past the end is `undefined`, but a call on it doesn't throw: `str[9].toUpperCase()` gives `''` on iOS and
+  `'UNDEFINED'` on Android.
+- On iOS, cutting inside a surrogate pair (`'a😀b'.slice(0, 2)`) gives U+FFFD, and `JSON.stringify('\ud83d')` writes
+  U+FFFD. A circular structure's `TypeError` from `JSON.stringify` has an empty message.
+- `'ΑΣ'.toLowerCase()` ends in `σ`, not `ς` (iOS).
+
+### Other differences
+
+- `error.stack` lists native frames, not JavaScript ones (see [iOS](/guide/publishing/compiled-ios#crashes-and-debugging)
+  and [Android](/guide/publishing/compiled-android#crashes-and-debugging)).
+- An object literal's own `valueOf` isn't called by `<` or `Math.max`, and its `[Symbol.toPrimitive]` is ignored
+  (iOS). A `Date` held as `any` gives `NaN` in arithmetic. Call `.valueOf()` or `.getTime()`.
+- Subclass fields are set before the base constructor runs (iOS). The build warns where an app's class relies on
+  this.
+- `typeof new String('x')` is `'string'`, not `'object'`.
+- `String(Symbol('s'))` gives `@@s#1` (iOS). `JSON.stringify` writes a symbol value, where JavaScript leaves it out.
+- `new RegExp('a/b').source` is `a/b`, not `a\/b` (iOS).
+- A `TypeError`'s `constructor.name` is `JSTypeError` (Android). `new Array(-1)` and an over-long `padStart` throw an
+  `Error`, not a `RangeError` (Android).
+- `new Date(y, m, d, h)` in the hour a daylight-saving change skips lands an hour early (iOS).
+- `Object.assign(target, …)` with a literal `null` among the sources stops the app (iOS).
+- A `var` declared in a loop head or a branch, and read through a closure before it is set, reads `0`, `''` or
+  `false`, not `undefined` (Android). So does a `let x: boolean;` declared without a value.
+- On Android, minification can remove a member reached only by a name computed at run time
+  ([R8](/guide/publishing/compiled-android#minification-r8)).
+
+## Not fixed yet
+
+The open items in the compiler's test suites, by what you would see.
+
+**Doesn't build yet** (reported at your TypeScript line):
+
+| Pattern                                                                                                              | Platform                  |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| Untyped callbacks called with JavaScript's arity, and `thisArg`                                                      | iOS, Android              |
+| A prototype method called on another receiver (`Array.prototype.slice.call(list, 1)`, `X.prototype.m.call(r)`)       | iOS (some forms), Android |
+| Destructuring assignment to existing variables in some forms; a rest element in one (`[first, ...others] = list`)    | iOS, Android              |
+| Properties given to a function value (`fn.tag = …`)                                                                  | iOS                       |
+| Top-level names declared by several modules (an enum, files of the same name in two folders)                         | iOS                       |
+| `null as string \| null` in a template or a concatenation                                                            | iOS                       |
+| A `sort` comparator declared with fewer parameters than `sort` passes                                                | iOS                       |
+| `RegExp(…)` without `new`, and indexing an `exec()` result without `!`                                               | Android                   |
+| A built-in error constructor held as a value (`const E: ErrorConstructor = TypeError`), and `error.constructor.name` | Android                   |
+| A function with a rest parameter passed to `then` (`then(log)`)                                                      | Android                   |
+
+**Builds, behaves differently:**
+
+| Pattern                                                                                                                                         | Platform     |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `Object.defineProperty` on a class instance, an array or a function is dropped                                                                  | iOS, Android |
+| `delete arr[i]`, and `delete` of a declared member                                                                                              | iOS          |
+| A `string` parameter given `undefined` reads `''`; a `void` promise's value isn't `undefined`                                                   | iOS          |
+| An object literal an `async` function returns isn't made as its declared type                                                                   | iOS          |
+| An optional member set after the object is made is listed in declaration order, not last                                                        | iOS          |
+| `Object.keys` lists the holes of `new Array(n)`                                                                                                 | iOS          |
+| A native class's own method declared with a non-optional result throws when it returns `undefined`                                              | iOS          |
+| `typeof` of a function read from an optional member, or of a narrowed `string \| string[]` parameter, is decided at build time and can be wrong | Android      |
+| `JSON.parse` and `JSON.stringify` edges: number forms, escapes, `toJSON` and replacer order, syntax error messages                              | Android      |
+
+## Checking a compiled release
+
+You develop on the JavaScript runtime and ship compiled code, so a difference shows only in the release. Compare
+each compiled release with its JavaScript release before you ship it:
+
+1. Build both, `ns build ios --release` and `ns build ios --compiled`, with the same `@nativescript/core`. They
+   share the app id, so install them on separate simulators or uninstall between them.
+2. Walk the same screens and taps in both, focusing and typing in every input, and watch for crashes as well as
+   pixels.
+
+`ns compiled verify` does this on an iOS Simulator. It builds both releases, runs the same steps on each (from the
+project's `verify.json`: taps, swipes, typing, waits and shots, each screen from a fresh launch), compares every
+shot pixel by pixel, and fails on a difference or on an app that stops running. The screenshots and a
+`report.json` go to `platforms/compiled/verify`.
+
+```json
+{
+  "screens": [
+    {
+      "name": "home",
+      "steps": [
+        ["shot", "start"],
+        ["tap", 200, 400],
+        ["wait", 1],
+        ["type", "Ada"],
+        ["shot", "typed"]
+      ]
+    }
+  ]
+}
+```
+
+Found a difference that isn't listed here? [Report it](/guide/publishing/compiled-report).
diff --git a/content/guide/publishing/compiled-faq.md b/content/guide/publishing/compiled-faq.md
new file mode 100644
index 00000000..9c6f9e76
--- /dev/null
+++ b/content/guide/publishing/compiled-faq.md
@@ -0,0 +1,84 @@
+---
+title: 'Compiled releases: FAQ'
+description: Common questions about compiled releases.
+contributors:
+  - NathanWalker
+---
+
+## Do I have to change my app?
+
+Usually not. The compiler reads the TypeScript, templates and CSS you already have. None of the apps compiled so far
+changed their own source; some added a few lines of [configuration](/guide/publishing/compiled-configuration#what-your-app-may-need).
+What the compiler knows it can't run stops the build with the file and line. Some differences only show at run time:
+see [What works](/guide/publishing/compiled-differences).
+
+## Will it behave exactly like the JavaScript release?
+
+That is the goal, and it is checked rather than assumed: the compiler's tests run each case under Node and as
+compiled Swift and Kotlin and require the same output, and the proof apps are compared with their JavaScript
+releases screen by screen. It isn't there yet: the [known differences](/guide/publishing/compiled-differences#known-differences-at-run-time)
+are listed. You develop on one engine and ship another, so check each release before you ship it.
+
+## Can I keep over-the-air updates?
+
+No. Over-the-air updates replace the JavaScript bundle, and a compiled release has none. Ship updates through the
+stores, and replace the update plugin with a no-op module through `release.pluginReplacements`. If over-the-air
+updates are essential to you, keep releasing on the JavaScript runtime.
+
+## Can I use any npm package?
+
+Packages are compiled with your app from their source, so what matters is what they do: code that uses `eval`,
+`new Function` or loads code at run time can't be compiled. Widely used libraries are not yet systematically
+verified; a construct the compiler doesn't support stops the build with its location.
+
+## What if a plugin doesn't compile?
+
+The build names the plugin and what stopped it. Depending on the cause: point `release.pluginSources` at its source,
+replace it with `release.pluginReplacements`, or raise it with the plugin's author. Plugins that install objects
+into the JavaScript engine (such as `@nativescript/canvas`) need a native counterpart in the kit; canvas has one.
+
+## Can I still write native code?
+
+Yes. Swift in `App_Resources/iOS/src` is compiled into the app and called from your TypeScript as before. Plugins'
+native code links unchanged. See [iOS](/guide/publishing/compiled-ios) and [Android](/guide/publishing/compiled-android).
+
+## How do I debug a compiled release, or map a crash to my TypeScript?
+
+As a native app, in Xcode or Android Studio. On iOS, crash reports and the debugger show your TypeScript lines
+through the dSYM. On Android, `ns-native-retrace` maps a stack trace to them. `ns debug` and Chrome DevTools stay with
+development builds. Details: [iOS](/guide/publishing/compiled-ios#crashes-and-debugging),
+[Android](/guide/publishing/compiled-android#crashes-and-debugging).
+
+## What does the generated Swift and Kotlin look like?
+
+It is build output in `platforms/compiled/<platform>`, regenerated on every build; your TypeScript stays the source
+of truth. It is JavaScript's semantics compiled to native code, not a port to idiomatic Swift or Kotlin. A Swift or
+Kotlin developer reading it will find:
+
+- **Formatted code that names its source.** The kit is laid out by swift-format and ktfmt, and compiled statements
+  carry the TypeScript line they came from.
+- **Real classes and typed calls.** Core's classes are Swift and Kotlin classes, and most calls into UIKit and the
+  Android SDK are direct, typed calls.
+- **Checked threading.** Swift builds in the Swift 6 language mode, isolated to the main actor. Kotlin marks code
+  `@UiThread` or `@AnyThread`, checked by lint.
+- **Few force unwraps.** A value its type promises but that is missing throws a catchable `TypeError`, not a trap.
+- **JavaScript's types where TypeScript has no better one.** Numbers are `Double`; untyped values are `Any?` and
+  are often read by name, through tables classes carry for that. Async code is written as callbacks, not
+  `async`/`await` or coroutines. Some names are generated.
+
+Treat it like any compiler's output: something you ship and profile, not something you maintain.
+
+## How long does a build take?
+
+The compile step takes seconds to tens of seconds, then Xcode or Gradle builds. The first build also compiles
+NativeScriptKit: about three minutes on iOS for a blank app, a minute or two on Android. A rebuild after a small
+change takes most of a minute, because release builds optimize the whole program.
+
+## Which platforms?
+
+iOS 17 and later, and Android 7 (API 24) and later. visionOS and other platforms build on the JavaScript runtime.
+
+## Can I go back?
+
+Any time: `--no-compiled` builds one release on the JavaScript runtime, and removing `release.compiled` makes it the
+default again. Nothing in your project depends on the compiled build.
diff --git a/content/guide/publishing/compiled-getting-started.md b/content/guide/publishing/compiled-getting-started.md
new file mode 100644
index 00000000..f8e1b4f0
--- /dev/null
+++ b/content/guide/publishing/compiled-getting-started.md
@@ -0,0 +1,91 @@
+---
+title: 'Compiled releases: getting started'
+description: Install the alpha, build and run a compiled release on iOS and Android, and report what fails.
+contributors:
+  - NathanWalker
+---
+
+::: warning Alpha
+Compiled releases are in alpha. Develop as usual, and check each compiled build against the JavaScript release
+before you ship it.
+:::
+
+## 1. Install the alpha
+
+The CLI, `@nativescript/core` and `@nativescript/compiler` must be the same alpha:
+
+```bash
+npm install -g nativescript@alpha
+
+# in your project
+npm install @nativescript/core@alpha
+npm install --save-dev @nativescript/compiler@alpha
+```
+
+::: tip webpack 5.112
+Until `@nativescript/webpack` 5.0.39 is out, a new webpack-based project needs `npm install -D webpack@5.111.1` for `ns run` (the JavaScript dev loop). Compiled builds aren't affected.
+:::
+
+The CLI runs the compiler from your project's `node_modules`. The build stops if your `@nativescript/core` is not
+the version the compiler was made from, or if your framework is outside the
+[tested versions](/guide/publishing/compiled-differences#tested-framework-versions).
+
+You need Node.js 22 or newer, and:
+
+- **iOS:** macOS with Xcode 26 or newer.
+- **Android:** JDK 17 or newer and the Android SDK, on macOS or Linux. Windows is not supported yet.
+- **git and network access** the first time a plugin is compiled: its source is fetched once and cached.
+
+## 2. Build and run
+
+`--compiled` implies `--release`. `ns run` and `ns debug` without it stay on the JavaScript runtime, with HMR.
+
+**iOS:**
+
+```bash
+ns run ios --compiled                                # build, install and launch on a simulator; streams the log until Ctrl+C
+ns build ios --compiled --for-device --team-id <id>  # signed archive and .ipa
+```
+
+**Android:** a release always needs a keystore, so pass all four `--key-store-*` options. To try it before you have
+your upload key, make a throwaway one:
+
+```bash
+keytool -genkeypair -keystore test.keystore -storepass testpass -keypass testpass -alias test \
+  -keyalg RSA -keysize 2048 -validity 365 -dname "CN=Test"
+
+ns run android --compiled --key-store-path test.keystore --key-store-password testpass \
+  --key-store-alias test --key-store-alias-password testpass
+```
+
+Add `--aab` to `ns build android` for an App Bundle. If a debug build of the app is installed, uninstall it first
+(`adb uninstall <app id>`): Android won't install over an app signed with another key.
+
+## 3. Make it the default (optional)
+
+```ts
+// nativescript.config.ts
+export default {
+  id: 'org.example.app',
+  release: { compiled: true },
+} as NativeScriptConfig
+```
+
+Now `ns build ios --release` is compiled too, and `--no-compiled` builds one release on the JavaScript runtime. See
+[Configuration](/guide/publishing/compiled-configuration).
+
+## 4. Find the output
+
+The compiled projects are in `platforms/compiled/ios` (an Xcode project) and `platforms/compiled/android` (a Gradle
+project). `platforms/ios` and `platforms/android` aren't touched. The build prints where the `.app`, `.ipa`, `.apk`
+or `.aab` is; `--copy-to <path>` copies it out.
+
+## 5. When something fails
+
+- **The build stops with a message.** Most messages name your TypeScript file and line, and say what to write
+  instead. Check [What works](/guide/publishing/compiled-differences) for the construct.
+- **It looks like a NativeScript problem.** Run `ns compiled report ios` (or `android`). It shows you the report and
+  asks before sending anything. See [Reporting issues](/guide/publishing/compiled-report).
+- **The app throws at run time.** Uncaught errors are logged as `***** Fatal JavaScript exception *****` in the
+  device log. Save the error to a file and run `ns compiled report ios --error crash.txt`.
+- **You need to ship now.** Build that release with `--no-compiled`.
diff --git a/content/guide/publishing/compiled-ios.md b/content/guide/publishing/compiled-ios.md
new file mode 100644
index 00000000..61a127e6
--- /dev/null
+++ b/content/guide/publishing/compiled-ios.md
@@ -0,0 +1,74 @@
+---
+title: 'Compiled releases: iOS'
+description: Requirements, signing, the generated Xcode project, Swift 6 isolation, and mapping crashes back to TypeScript in a compiled iOS release.
+contributors:
+  - NathanWalker
+---
+
+## Requirements
+
+- macOS with **Xcode 26** or newer.
+- **XcodeGen** generates the Xcode project. Yours is used if it is installed; otherwise the compiler downloads a
+  pinned release once into `~/Library/Caches/nativescript`, checked against its published checksum.
+- The app runs on **iOS 17** and later. A lower deployment target in `build.xcconfig` is raised, and the build says
+  so. Compiled releases are checked on iOS 26.
+
+## Build, sign, run
+
+```bash
+ns build ios --compiled                     # simulator .app
+ns build ios --compiled --for-device        # archive and .ipa
+ns run ios --compiled                       # build, install and launch
+```
+
+`--team-id` signs automatically and `--provision` signs with a profile. Without either, the archive and `.ipa` are
+unsigned, with a warning. The app id is your project's `id`, so the [store steps](/guide/publishing/) are the same as
+for a JavaScript release.
+
+Simulator builds compile only your Mac's architecture. Installing a compiled build over a JavaScript build of the
+same app on a simulator keeps stale files from the old bundle: uninstall first, or use another simulator.
+
+## The Xcode project
+
+`platforms/compiled/ios` is an ordinary Xcode project you can open, build, run, profile and debug in Xcode.
+It is regenerated on every build, so don't edit it.
+
+- **Swift 6, main-actor isolated.** The kit and your compiled code build in the Swift 6 language mode with
+  `MainActor` as the default isolation. Native code that calls into your code from another thread goes through
+  entry points that hand the call to the main thread.
+- **Your own Swift.** Swift in `App_Resources/iOS/src` is compiled into the app and called from your TypeScript as
+  before. An app that has its own Swift builds in the Swift 5 language mode, still main-actor isolated and with the
+  Swift 6 checks the generated code needs, so your code doesn't have to be Swift 6 ready.
+- **App_Resources carry over** as the CLI carries them: `Info.plist` and entitlements merged with plugins', asset
+  catalogs, the launch screen, `build.xcconfig`, `PrivacyInfo.xcprivacy`, fonts, Podfiles and Swift packages.
+  Widgets and Live Activities in `App_Resources/iOS/extensions` become their own targets.
+- **Plugins' native code** (Swift, Objective-C, `.xcframework`s, CocoaPods, Swift packages) is linked unchanged.
+
+## Crashes and debugging
+
+Every compiled statement carries the TypeScript file and line it came from (a Swift `#sourceLocation`). So:
+
+- the archive's dSYM symbolicates crash reports to your `.ts`, `.vue`, `.tsx` or `.svelte` lines. Upload it to
+  your crash reporter (Sentry, Crashlytics, App Store Connect) as for any iOS app;
+- Xcode's debugger shows and steps through the same lines.
+
+`error.stack` lists native frames, such as `symbol (App+0x1a2b3c)`. Resolve one with the dSYM:
+
+```bash
+atos -o App.app.dSYM/Contents/Resources/DWARF/App -l 0x100000000 0x1001a2b3c
+```
+
+Uncaught errors go to `Application.uncaughtErrorEvent` and are logged as `***** Fatal JavaScript exception *****`.
+With `uncaughtErrorPolicy: 'throw'` the app then ends with a native exception that crash reporters record.
+
+`ns debug` and Chrome DevTools need the JavaScript runtime, so they stay with development builds.
+
+## Build times
+
+Measured on a blank app, 2026-10-13. The first build compiles NativeScriptKit as well.
+
+| Build           | iOS simulator |
+| --------------- | ------------- |
+| First build     | about 170 s   |
+| One-line change | about 55 s    |
+| Nothing changed | about 14 s    |
diff --git a/content/guide/publishing/compiled-report.md b/content/guide/publishing/compiled-report.md
new file mode 100644
index 00000000..aefb9529
--- /dev/null
+++ b/content/guide/publishing/compiled-report.md
@@ -0,0 +1,58 @@
+---
+title: 'Compiled releases: reporting issues'
+description: Report a failed compiled build or a compiled app's runtime error to NativeScript with ns compiled report.
+contributors:
+  - NathanWalker
+---
+
+`ns compiled report` turns a `--compiled` problem into a GitHub issue on
+[NativeScript/NativeScript](https://github.com/NativeScript/NativeScript/issues), or finds the existing one.
+
+```bash
+ns compiled report [ios|android]                 # the last failed --compiled build
+ns compiled report <ios|android> --error <file>  # a runtime error a compiled app threw
+ns compiled report ios --dry-run                 # print the report and send nothing
+```
+
+## When to use it
+
+- **A compiled build failed**: the compiler refused a construct, or Xcode, Swift, Gradle or Kotlin failed on the
+  generated code. The build keeps what went wrong in `platforms/compiled/<platform>/report.json` and prints the
+  command to run. Without a platform, the command reports the one whose build failed last.
+- **A compiled app threw at run time**: save the error, from the device log or your crash reporter, to a file and
+  pass it with `--error <file>`. `--error=-` reads it from stdin.
+
+## What it collects
+
+- The versions of the CLI, `@nativescript/compiler` and `@nativescript/core`; the framework and its version; the
+  platform; Xcode, or Gradle, the Android Gradle Plugin and Kotlin; the OS and Node.js; your project's dependencies.
+- The diagnostic and the source location it names.
+- A **signature**: a short hash of the kind of failure and its message, with names and numbers abstracted, so the
+  same problem in different apps finds the same issue.
+
+Paths are made relative to the project. Your home folder, user names, tokens and passwords are removed.
+
+## Consent
+
+Nothing leaves your machine until you have seen the report and agreed.
+
+- **Your code** (the three lines either side of the location) is added only if you agree a second time. `--yes`
+  skips the first question, never this one.
+- **`--dry-run`** prints the title, labels, body and issue URL, and sends nothing.
+- In a terminal that can't answer, the command prints the report and the issue URL and sends nothing.
+
+## Where it goes
+
+The command searches open and closed issues for the signature:
+
+- **Already reported:** it offers to add a 👍, plus a comment with your environment when no earlier report has the
+  same platform, framework, compiler and core versions. Or it opens the issue for you.
+- **New:** it files the issue with `gh` if it is installed and signed in. Otherwise it opens the `--compiled` issue
+  form in your browser, filled in.
+
+Each issue is labeled `compiled`, `platform:<ios|android>`, `framework:<name>` and `kind:<kind>`, where the kind is
+`compile-refused` (the compiler stopped), `native-compile` (Xcode or Gradle failed on the generated code) or
+`runtime`.
+
+Each report becomes a test case in the compiler, then a fix, and the [What works](/guide/publishing/compiled-differences)
+table is updated.
diff --git a/content/guide/publishing/compiled.md b/content/guide/publishing/compiled.md
new file mode 100644
index 00000000..2810015f
--- /dev/null
+++ b/content/guide/publishing/compiled.md
@@ -0,0 +1,131 @@
+---
+title: Compiled releases
+description: Build a release of your NativeScript app compiled to Swift and Kotlin, with no JavaScript runtime inside.
+contributors:
+  - NathanWalker
+---
+
+<!-- Keep in step with the compiler's docs/CLI.md and the support table (SUPPORT.md) in NativeScript/swiftui-live. -->
+
+::: warning Alpha
+Compiled releases are in alpha: `nativescript`, `@nativescript/core` and `@nativescript/compiler` are published with
+the `alpha` tag. Check each compiled build against your JavaScript release before you ship it.
+:::
+
+A compiled release is how the TypeScript option ships (see [TypeScript or SwiftUI](/guide/pathways)). You develop with
+`ns run` and `ns debug` exactly as today: on the JavaScript runtime, with HMR and Chrome DevTools. When you build the
+release with `--compiled`, your app, its framework, its plugins and `@nativescript/core` are compiled to **Swift on
+iOS and Kotlin on Android**. The app ships no JavaScript engine, no bundle and no NativeScript runtime.
+
+```bash
+ns build ios --compiled
+```
+
+Start with [Getting started](/guide/publishing/compiled-getting-started). Then:
+
+- [Configuration](/guide/publishing/compiled-configuration): the `release` options in `nativescript.config.ts`.
+- [iOS](/guide/publishing/compiled-ios) and [Android](/guide/publishing/compiled-android): requirements, signing,
+  the generated projects, crashes and debugging.
+- [What works](/guide/publishing/compiled-differences): frameworks, plugins, what the build refuses, and the known
+  differences.
+- [Reporting issues](/guide/publishing/compiled-report) with `ns compiled report`.
+- [FAQ](/guide/publishing/compiled-faq).
+
+## Before you choose `--compiled`
+
+What you gain:
+
+- **No JavaScript engine in the app.** Your TypeScript, your framework and `@nativescript/core` ship as Swift and
+  Kotlin.
+- **Smaller apps that use less memory** (measurements below).
+- **What the compiler can't run faithfully, it refuses.** Before compiling, a check reports every construct outside
+  the supported subset with the file, the line and what to write instead.
+
+What you give up:
+
+- **Some JavaScript semantics.** Most are reproduced; the [known differences](/guide/publishing/compiled-differences#known-differences-at-run-time)
+  are not, and they show only when the app runs.
+- **Code made or loaded at run time.** `eval`, `new Function`, `Proxy`, `Reflect` and a computed `import()` are
+  refused.
+- **Over-the-air updates.** There is no JavaScript bundle to replace. Updates go through the stores.
+- **Speed in some code.** Launch is no faster. Typed class code is faster on iOS, but JavaScript's library (JSON,
+  regular expressions, sorting, `Map` and `Set`, `async`) is several times slower than on V8 today, and on Android
+  so are string `+=` and list scrolling. Measure data-heavy screens.
+- **Build time.** The first build compiles NativeScriptKit, about three minutes on iOS. A rebuild after a small
+  change takes most of a minute.
+- **JavaScript debugging.** A compiled release is debugged as a native app in Xcode or Android Studio.
+
+## Measured on real apps
+
+| App                                                                | JavaScript release | Compiled release |
+| ------------------------------------------------------------------ | ------------------ | ---------------- |
+| Recipes (Vue), first frame, iPhone 16 Pro                          | 190 ms             | 191 ms           |
+| Recipes (Vue), memory footprint after launch, iPhone 16 Pro        | 47.3 MB            | 18.9 MB          |
+| Recipes (Vue), `.ipa`                                              | 14 MB              | 2.35 MB          |
+| ns-duo-guitar (Angular, WebGPU), Play download, arm64              | 28.1 MB            | 14.6 MB          |
+| openjs-app (Angular, eight plugins), Play download, arm64, 420 dpi | 28.6 MB            | 15.2 MB          |
+| openjs-app, `.ipa`                                                 | 27.8 MB            | 17.3 MB          |
+| openjs-app, installed on iOS                                       | 79.9 MB            | 40.0 MB          |
+
+iOS: 2026-10-09, cold launch to first frame from screen recordings, median of 5 runs; memory is the physical
+footprint; the `.ipa` is unsigned, arm64. Android: 2026-10-10, sizes from the App Bundle for one device
+configuration (arm64-v8a, 420 dpi, English). openjs-app on iOS: 2026-10-13. The scripts are in the compiler's
+`bench/` folder.
+
+## How it works
+
+```text
+your app (TypeScript, templates, CSS)            plugins (their TypeScript source)
+                     │                                        │
+                     └──── one TypeScript program, type-checked against @nativescript/core ────┘
+                                                │
+                              compiler: Swift (iOS) / Kotlin (Android)
+                                                │
+                            + NativeScriptKit: @nativescript/core as native code
+                            + plugins' native code (platforms/ios, platforms/android), linked unchanged
+                                                │
+                               Xcode / Gradle ──▶ .app .ipa / .apk .aab
+```
+
+1. **Your framework's own parser reads your templates.** Angular, Vue, React, Svelte, Solid and Octane templates are
+   parsed by each framework's own compiler, so what you write means what it means in the framework.
+2. **Your styles go through your own build.** Your CSS pipeline (Tailwind, PostCSS, Sass) runs as your app's build
+   runs it, and the result is applied as core applies CSS. Components' own styles are scoped as their framework
+   scopes them.
+3. **Everything is type-checked as one program**, then translated. JavaScript semantics (numbers, promises and
+   microtasks, closures, `Map`/`Set`, iteration order) are reproduced by a runtime that the compiler's tests hold to
+   Node's output.
+4. **Core becomes NativeScriptKit**: core's views, layouts, styling, property system and platform APIs as Swift and
+   Kotlin, generated from core's own TypeScript by the same compiler. It follows core release by release.
+5. **Plugins compile from their own TypeScript.** For each plugin the compiler fetches the exact source its
+   published version was built from, checks it against the published JavaScript, and compiles it with your app. Its
+   native code is linked unchanged.
+6. **`App_Resources` carry over** as the CLI carries them.
+
+## Under the hood
+
+| Piece                                                                                            | What it is                                                                                | Who uses it                                 |
+| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------- |
+| The CLI (`nativescript`)                                                                         | `--compiled`, the `release` config, building, signing and installing the compiled project | App developers                              |
+| `@nativescript/compiler`                                                                         | The compiler, and NativeScriptKit for Swift and Kotlin                                    | App developers, as a devDependency          |
+| NativeScriptKit                                                                                  | `@nativescript/core` as native code, linked by every compiled app                         | Nobody directly; it comes with the compiler |
+| Core's kit generator (`tools/native-kit` and `packages/compiler` in the NativeScript repository) | Compiles core's TypeScript into NativeScriptKit, once per core release, checked by CI     | Core maintainers                            |
+
+The compiler is published at core's version and carries the kit generated from that core release, which is why the
+two must match.
+
+## What is still open
+
+- The [differences and unsupported patterns](/guide/publishing/compiled-differences#not-fixed-yet) listed today.
+- The speed of the runtime library and of typed member access.
+- Plugins: `.framework` and static libraries, resource bundles, and a way for plugin authors to ship native
+  counterparts of engine-bound code; a corpus of widely used plugins and npm libraries, built in CI.
+- Android: `fetch` and `XMLHttpRequest`; R8's narrow kit keeps by default.
+- `Intl.Collator`, `Intl.PluralRules` and `Intl.RelativeTimeFormat`.
+- One upload of TypeScript line maps to Android crash reporters.
+
+## See also
+
+- [TypeScript or SwiftUI](/guide/pathways)
+- [SwiftUI, live](/guide/swiftui-live): the other direction: write Swift, develop it live.
+- [Publishing overview](/guide/publishing/)
diff --git a/content/guide/publishing/index.md b/content/guide/publishing/index.md
index 0c1c33ed..96c365c6 100644
--- a/content/guide/publishing/index.md
+++ b/content/guide/publishing/index.md
@@ -1,13 +1,37 @@
 ---
 title: Publishing Overview
-description: When building an app, there comes a point where it needs to be published
+description: Build a release of your app, on the JavaScript runtime or compiled to native code, and publish it to the stores.
 contributors:
   - rigor789
+  - NathanWalker
 breadcrumbs:
   - name: 'Publishing'
 ---
 
-## [Publishing to Google Play](/guide/publishing/android-google-play)
-## [Publishing to Apple App Store](/guide/publishing/apple-app-store)
-## [Publishing iOS updated using ns publish ios](/guide/publishing/ns-publish)
-## [Publishing with Fastlane](https://blog.nativescript.org/automatic-nativescript-app-deployments-with-fastlane/)
+Publishing takes two steps: build a release of the app, then submit that build to a store.
+
+## 1. Build a release
+
+NativeScript builds a release in one of two ways.
+
+|                | JavaScript runtime release                                                   | Compiled release                                                                                                                  |
+| -------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **Command**    | `ns build ios --release`                                                     | `ns build ios --compiled`                                                                                                         |
+| **What ships** | Your bundled JavaScript and the NativeScript runtime (V8 on Android and iOS) | Swift (iOS) and Kotlin (Android) compiled from your TypeScript; no JavaScript engine                                              |
+| **Status**     | Stable, the default                                                          | [Alpha](/guide/publishing/compiled)                                                                                               |
+| **Plugins**    | Every NativeScript plugin                                                    | Plugins compiled from their TypeScript source; see [what works](/guide/publishing/compiled-differences#plugins-and-platform-apis) |
+
+A compiled release is opt-in. It can be the default for every release build through `nativescript.config.ts`, per
+platform, and `--no-compiled` builds one release on the JavaScript runtime whatever the config says. Read
+[Compiled releases](/guide/publishing/compiled) for how it works, and
+[Getting started](/guide/publishing/compiled-getting-started) to try it.
+
+## 2. Publish it
+
+- [Publishing to the Apple App Store](/guide/publishing/apple-app-store)
+- [Publishing to Google Play](/guide/publishing/android-google-play)
+- [Publishing iOS updates with `ns publish ios`](/guide/publishing/ns-publish)
+- [Publishing with Fastlane](https://blog.nativescript.org/automatic-nativescript-app-deployments-with-fastlane/)
+
+The store steps are the same for both kinds of release: a compiled release produces the same signed `.ipa`, `.apk`
+or `.aab`, under the same app id.
diff --git a/content/guide/swiftui-live.md b/content/guide/swiftui-live.md
new file mode 100644
index 00000000..9ba67b3e
--- /dev/null
+++ b/content/guide/swiftui-live.md
@@ -0,0 +1,115 @@
+---
+title: SwiftUI, live
+description: Edit a SwiftUI app's Swift while it runs and see each save in about a third of a second, with the app's state kept. NativeScript is the development runtime; what ships is your Swift.
+contributors:
+  - NathanWalker
+---
+
+<!-- Keep in step with the swiftui-live repository's README and docs/BRIEF.md. -->
+
+::: warning Preview
+SwiftUI Live is in preview and not yet publicly available. This page describes it as it works today, so the
+option is clear before it opens up.
+:::
+
+This is one of NativeScript's [development options](/guide/pathways). You write SwiftUI, in an ordinary Xcode project,
+and NativeScript runs it **live** while you develop: save a Swift file and the running app shows the change in
+about 0.15–0.5 seconds, at the screen and state you were on. Nothing of NativeScript ships. The App Store build is
+your Swift, compiled by Xcode as usual.
+
+It is the inverse of the [TypeScript option](/guide/publishing/compiled): there, you write TypeScript and the
+release is compiled to Swift and Kotlin. Here, you write Swift and the development session runs it on a JavaScript
+engine for speed.
+
+## What a session is like
+
+In your app's folder:
+
+```bash
+swiftui-live            # reads the .xcodeproj, builds, launches on a simulator, watches
+swiftui-live doctor     # checks the machine; lists which views go live on save, and why the rest do not
+swiftui-live down       # stops the session
+```
+
+There is nothing to add or configure in the project: no `#Preview` blocks, mocks or annotations. The command
+reads the project's targets, packages and build settings and builds a development copy of the app (about 22 s the
+first time, 10 s after that). The development build lives in `~/Library/Caches/swiftui-live`; your project is not
+modified.
+
+Each save reports one line:
+
+```
+[live] ● Backyards/BackyardGridItem.swift: on screen in 368 ms
+[live]   swiftc agrees (0.7 s)
+[live] ✗ Backyards/BackyardGridItem.swift:37:31: value of type 'Backyard' has no member 'nam' (swiftc); the last version it accepted is back on screen
+[live] ○ Donut/TopDonutSalesChart.swift: line 36: modifier `.chartXAxis` is not in the compiled runtime yet; taking the library path (state kept, about a second)
+```
+
+## How it works
+
+```text
+your .swift file ── swift-js ──▶ JavaScript for the view's body ──▶ engine in the running app
+                                                                     │
+                                       the body builds real SwiftUI views; the rest of the app
+                                       is untouched compiled Swift
+          └── swiftc type-checks the same save against the app's module; a rejected save is rolled back
+```
+
+- **Fast path.** Each view's `body` is compiled from Swift to JavaScript and run by an engine inside the app:
+  JavaScriptCore in a plain Xcode project, or NativeScript's V8 in a NativeScript host. The body builds a tree of
+  real SwiftUI views. Swift that the compiler cannot express stays compiled Swift (an _island_) and runs in place.
+- **Library path.** A save that changes code outside view bodies, or uses SwiftUI the fast path does not cover yet,
+  is built as a replacement library, the mechanism Xcode Previews uses: about a second, state kept.
+- **Swift stays the judge.** Every save is also type-checked by `swiftc` against the app's own module. Anything the
+  compiler rejects is taken back off the screen.
+
+## What is measured
+
+- **Real apps, unmodified.** Apple's Food Truck and Backyard Birds (SwiftData, three packages) run live from their
+  own sources.
+- **Pixel conformance.** Views rendered live and compiled in the same process are compared pixel by pixel: the
+  fixture app 16 of 16 (on both JavaScriptCore and V8), Food Truck 6 of 6, Backyard Birds 6 of 6, checked nightly
+  in CI.
+- **Coverage.** Of every SwiftUI view in ten open-source apps (1,684), 1,068 (63%) go live in 0.15–0.5 s; the rest
+  take the library path in about a second, still with state kept.
+
+## Android: the same SwiftUI source, live
+
+The same SwiftUI source also runs live on an Android emulator. View bodies are compiled to JavaScript as on iOS and
+rendered by **Jetpack Compose** (Material 3), and the app's models are compiled for Android by the official Swift
+SDK for Android. One save updates an iOS simulator and an Android emulator at once.
+
+What this proves, and what it does not yet:
+
+|                                    | iOS                           | Android                                                         |
+| ---------------------------------- | ----------------------------- | --------------------------------------------------------------- |
+| Live development of SwiftUI        | Yes                           | Yes, rendered by Compose                                        |
+| The app's non-UI Swift             | Compiled Swift                | Compiled by the Swift SDK for Android                           |
+| Views the fast path cannot express | Islands of compiled SwiftUI   | A placeholder (there is no SwiftUI on Android to fall back to)  |
+| Look                               | SwiftUI                       | Material 3: SwiftUI's vocabulary mapped onto Compose components |
+| A release build                    | Your Xcode project, as always | Not yet: there is no release path for SwiftUI on Android today  |
+
+## Limits today
+
+None of these is architectural; each is breadth or polish with a known path.
+
+- **37% of views take the library path** (about a second instead of a third of one). The missing SwiftUI
+  vocabulary is ranked by how often real apps use it (`.onReceive`, `.focused`, gestures, Charts modifiers).
+- **New stored properties, types or model changes need a rebuild**, as with Previews and every hot-reload tool:
+  Swift cannot add stored properties to a running binary. `swiftui-live rebuild` relaunches into the saved state.
+- **Simulator and emulator only.**
+- **Some Swift semantics differ on the fast path**: integer overflow traps, `Dictionary` order, number formatting.
+  `swiftc` still checks every save.
+- **Fidelity is proven on still frames in light mode.** Animation, dark mode, Dynamic Type and right-to-left are not
+  yet in the conformance harness.
+
+## Requirements
+
+- macOS with Xcode 26 or later, and Node 22.
+- For Android: the Android SDK with an arm64 emulator image, NDK r30, and the Swift 6.4 toolchain with the Swift SDK
+  for Android.
+
+## See also
+
+- [TypeScript or SwiftUI](/guide/pathways): choosing between the two.
+- [Compiled releases](/guide/publishing/compiled): the TypeScript option's release, with no JavaScript runtime.
diff --git a/content/index.md b/content/index.md
index 9ad08e39..241016e5 100644
--- a/content/index.md
+++ b/content/index.md
@@ -7,7 +7,7 @@ contributors:
 
 ## What is NativeScript?
 
-NativeScript provides platform APIs directly to the JavaScript runtime (_with strong types_) for a rich TypeScript development experience. 
+NativeScript provides platform APIs directly to the JavaScript runtime (_with strong types_) for a rich TypeScript development experience. It can also be used to provide a faster SwiftUI development experience, [read more here](/guide/pathways).
 
 Some popular use cases:
 
diff --git a/content/sidebar.ts b/content/sidebar.ts
index ac2cd10e..ade8d5a2 100644
--- a/content/sidebar.ts
+++ b/content/sidebar.ts
@@ -50,6 +50,11 @@ export default [
       {
         text: 'Publishing',
         link: '/guide/publishing/',
+        items: [
+          { text: 'Apple App Store', link: '/guide/publishing/apple-app-store' },
+          { text: 'Google Play', link: '/guide/publishing/android-google-play' },
+          { text: 'ns publish ios', link: '/guide/publishing/ns-publish' },
+        ],
       },
       {
         text: 'Plugins',
@@ -71,6 +76,27 @@ export default [
       },
     ],
   },
+  {
+    text: 'Dev Options',
+    items: [
+      { text: 'TypeScript or SwiftUI', link: '/guide/pathways' },
+      {
+        text: 'TypeScript, Compiled',
+        collapsed: false,
+        items: [
+          { text: 'Overview', link: '/guide/publishing/compiled' },
+          { text: 'Getting Started', link: '/guide/publishing/compiled-getting-started' },
+          { text: 'Configuration', link: '/guide/publishing/compiled-configuration' },
+          { text: 'iOS', link: '/guide/publishing/compiled-ios' },
+          { text: 'Android', link: '/guide/publishing/compiled-android' },
+          { text: 'What Works', link: '/guide/publishing/compiled-differences' },
+          { text: 'Reporting Issues', link: '/guide/publishing/compiled-report' },
+          { text: 'FAQ', link: '/guide/publishing/compiled-faq' },
+        ],
+      },
+      { text: 'SwiftUI, Live (Preview)', link: '/guide/swiftui-live' },
+    ],
+  },
   {
     text: 'Project Structure',
     type: 'filetree',