@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.1

package/docs-md/screen-ui/top-bar.md

@@ -0,0 +1,247 @@
+# Top bar
+
+The bar at the top of a stack: the title and the subtitle, the large title, the background and the border, hiding the bar, a component in place of the title, and the title menu.
+
+Every screen of a stack has a bar at the top: it names the screen and holds the way back and the actions. A screen fills the bar through its options, and the title is the one most apps set:
+
+```tsx
+import { defineScreen } from '@apexnative/navigation';
+
+export const InboxScreen = defineScreen({
+  component: Inbox,
+  options: (s) => s.title('Inbox'),
+});
+```
+
+The bar shows "Inbox" as the screen comes in, before React renders it. This page answers:
+
+1. [What the top bar is](#what), and its parts.
+2. [The title](#title) and the subtitle.
+3. [The large title](#large-title).
+4. [The background and the border](#background).
+5. [Hiding the bar](#hide).
+6. [A component in place of the title](#title-component), and [the title menu](#title-menu).
+7. [The bar on iPhone Duo](#iphone-duo).
+
+The buttons of the bar have a page of their own: [Bar buttons](./bar-buttons). So do the back button ([Back and gestures](./back-and-gestures)) and the search field ([Search](./search)).
+
+## What the top bar is
+
+The top bar belongs to **the stack, not to a screen**: one bar for all the screens of the [stack](../containers/stack). Each screen gives it its title and buttons through its [options](../fundamentals/screen-options), and the bar changes with the screen as it comes in, as in any native app. The back button shows by itself on every screen but the first.
+
+The platform draws the bar: `UINavigationBar` on (iOS), with Liquid Glass on iOS 26, and the Material 3 top app bar on (Android). Its colors come from the [theme](../architecture/theme-and-context) until a screen sets its own.
+
+## The title
+
+The title is the name of the screen. The subtitle is a second line under it, such as a status or a count. Both can come from the props of the screen:
+
+```ts
+export const ChatScreen = defineScreen({
+  component: Chat,
+  options: (s, props) => s.title(props.name).subtitle('online'),
+});
+```
+
+A title can change while the screen shows, such as when its data has loaded: see [Changing the options of a shown screen](../fundamentals/screen-options#change).
+
+The look of the text goes in an object instead of the string:
+
+```ts
+s.title({ text: 'Chat', color: '#1E2A44', fontFamily: 'Righteous' });
+```
+
+`fontSize`, `fontWeight` and `fontStyle` go in the same object, and the subtitle takes the same keys.
+
+| Platform | The title |
+| --- | --- |
+| (iOS) | In the middle of the bar. On iOS 26, `glass: 'regular'` or `'clear'` puts it on a capsule of Liquid Glass, as the buttons are, with the subtitle as a second line. |
+| (Android) | At the leading edge, next to the back arrow. `alignment: 'center'` puts it in the middle. |
+
+## The large title
+
+(iOS) A large title is big at the top of the screen, under the row of the bar. It goes into the bar as the content scrolls, so a long list keeps its room:
+
+```ts
+s.title('Inbox').largeTitle();
+```
+
+`largeTitle()` shows it on this screen. A screen pushed from it usually has a small title, so it sets its own `displayMode`:
+
+```ts
+s.title('Details').largeTitle({ displayMode: 'never' });
+```
+
+| `displayMode` | The large title |
+| --- | --- |
+| `'always'` | Shows on this screen. The default of `largeTitle()`. |
+| `'never'` | Doesn't show on this screen. |
+| `'automatic'` | As on the screen under it; the first screen of a stack shows it. |
+| `'inline'` | iOS 17+: in the row of the bar instead of under it. Only on a screen without a back button, such as the first of a stack or of a modal: next to a back button UIKit shows it as `'always'`. |
+
+`collapseOnScroll: false` keeps the large title where it is: the list scrolls under the bar and the title stays.
+
+(Android) The same option shows the large top app bar of Material 3: the title big under the row of the bar, fading into the row as the content scrolls. The screen goes under the bar, so its list keeps its first rows clear with `useSafeAreaInsets().top` (see [The safe area](./system-ui#safe-area)). `'inline'` keeps the title in the row, as `'never'` does. Under a large title `hideOnScroll` doesn't work.
+
+## The background and the border
+
+On iOS 26 the bar is Liquid Glass, and the content shows through it as it scrolls under. **A color takes the glass away**, so set one only when the design needs it:
+
+```ts
+s.topBar({ background: { color: '#F3E9D2' }, noBorder: true });
+```
+
+`background.color` colors the bar on both platforms. With a large title on iOS 26 the color goes behind the title in the list, and fills the bar once the title collapses. Under a bar with a color the list has no edge effect at the top: see [The edge of the scroll](./system-ui#scroll-edge).
+
+The other keys of the background are rarer:
+
+| Option | What it does |
+| --- | --- |
+| `background.component` | A component of `screens` drawn behind the bar, such as a gradient. It is registered as the [title component](#title-component) is. |
+| `background.translucent` | (iOS) `true`: the content shows through; Liquid Glass on iOS 26, where it is the default. `false`: a solid bar, white in the light theme and black in the dark one. |
+| `background.blur` | (iOS) The system's frosted blur, plainer than the glass. A `color` wins over it, and it wins over `translucent`. |
+| `scrollEdgeAppearance` | (iOS) The look of the bar while the content is at its top, with `active: true`. The bar takes its usual look once the content scrolls under it. |
+
+The line under the bar:
+
+| Option | What it does |
+| --- | --- |
+| `noBorder` | (iOS) No line under the bar. |
+| `borderColor` | The color of the line. |
+| `elevation`, `borderHeight` | (Android) The shadow and the line under the bar, in dp. `elevation: 0` takes the shadow away. |
+
+## Hiding the bar
+
+A screen without a bar, such as a photo or a sign-in, hides it in its options. The bar comes back when the user goes back, because the screen under it has its own options:
+
+```ts
+s.hideTopBar();
+```
+
+`hideTopBar(hidden)` takes a value too, so the state can decide, as in a viewer that hides its bar on a tap:
+
+```tsx
+useScreenOptions((s) => s.hideTopBar(fullScreen));
+```
+
+The bar can also hide and show by itself:
+
+| Option | The bar |
+| --- | --- |
+| `hideOnScroll` | Hides while the content scrolls down, and comes back as it scrolls up. |
+| `hideOnTap` | (iOS) Hides and shows on a tap on the screen. |
+| `hideOnKeyboard` | (iOS) Hides while the keyboard shows. |
+| `animate` | `false`: hides and shows at once, without the animation. |
+
+With `hideOnScroll` the screen goes under the bar, so its rows show where the bar was. Its list keeps its first rows clear: on (iOS) with `contentInsetAdjustmentBehavior="automatic"`, on (Android) with `paddingTop: useSafeAreaInsets().top`.
+
+`drawBehind: true` keeps the bar and puts the content under it, as a map or a photo under a glass bar.
+
+## A component in place of the title
+
+A chat shows an avatar, a name and a status where the title is. Text can't do that, so a React component takes the place of the title. It takes three steps.
+
+**1. The component**, a plain React component with its props:
+
+```tsx
+import { Image, Text, View } from 'react-native';
+
+type Props = { name: string; avatar: string };
+
+export function ChatTitle(props: Props) {
+  return (
+    <View style={{ flexDirection: 'row', gap: 8 }}>
+      <Image
+        source={{ uri: props.avatar }}
+        style={{ width: 28, height: 28, borderRadius: 14 }}
+      />
+      <View>
+        <Text style={{ fontWeight: '600' }}>{props.name}</Text>
+        <Text style={{ fontSize: 12, opacity: 0.6 }}>online</Text>
+      </View>
+    </View>
+  );
+}
+```
+
+**2. Its registration** in `screens`, as any screen. The bar renders it in a React root of its own, so it needs a name:
+
+```ts
+export const Navigation = createNavigation({
+  screens: { Inbox: InboxScreen, Chat: ChatScreen, ChatTitle },
+  root: 'Inbox',
+});
+```
+
+**3. The options of the screen** name it in `title.component`, with its props:
+
+```ts
+export const ChatScreen = defineScreen({
+  component: Chat,
+  options: (s, props) =>
+    s.title({
+      component: {
+        name: 'ChatTitle',
+        passProps: { name: props.name, avatar: props.avatar },
+      },
+    }),
+});
+```
+
+The screen comes in with the avatar and the name in the bar: it waits for the component to draw, so the title doesn't pop in after it.
+
+`alignment: 'fill'` in `component` gives the component all the room between the side buttons, from the back button on, so its content can start at the leading edge. Without it the component sits in the middle.
+
+The same three steps give the bar a background of its own, with `background.component`, and a button: see [A component as a button](./bar-buttons#component).
+
+## The title menu
+
+(iOS) 16+ A tap on the title can open a menu, as the title of a document does in system apps; UIKit shows a chevron next to the title. A pick sends a button press with the id of the item:
+
+```tsx
+export const DraftScreen = defineScreen({
+  component: Draft,
+  options: (s) =>
+    s.title({
+      text: 'Draft',
+      menu: { items: [{ id: 'duplicate', title: 'Duplicate' }] },
+    }),
+});
+
+function Draft() {
+  useNavigationButton('duplicate', () => duplicateDraft()); // your own
+  // …
+}
+```
+
+`rename: true` adds Rename to the menu: the title turns into a field in the bar, and the new title comes as the event `titleRenamed`:
+
+```tsx
+useScreenEvent('titleRenamed', ({ text }) => renameDraft(text));
+```
+
+`document: { url }` heads the menu with a file: its icon, name and type. A large title shows no chevron and opens no menu. On (Android) the title has no menu: put the same actions in [the overflow menu](./bar-buttons#overflow).
+
+## The layout of the bar
+
+This section is rarely needed: most apps keep the platform's layout.
+
+(iOS) 16+ `style` lays the bar out. `'navigator'`, the default, centers the title, as a stack of screens does. `'browser'` and `'editor'` put it next to the back button, as an app of documents does, and leave room for [center buttons](./bar-buttons#center) on iPad.
+
+(Android) `height` and `topMargin`, of the bar and of its title, size the bar for a design of its own.
+
+## The bar on iPhone Duo
+
+(iOS) 27.1 On iPhone Duo, folded and open, the title stays in the row at the top, and the large title too. The system moves the buttons into a vertical bar at the trailing edge, with the status bar and the tab bar: see [Buttons on iPhone Duo](./bar-buttons#iphone-duo). The app's options stay the same; a screen that needs its bars at the top asks for them:
+
+```ts
+s.verticalBars(false); // the bars at the top, as on any iPhone
+```
+
+Set it once for a screen: Apple asks apps not to switch it with the state of the screen. In a [pair](../containers/arrangement) the bar is the primary's, so is this option.
+
+The screen goes under the vertical bar, as under the top bar, and its list keeps its rows clear: see [The vertical bar of iPhone Duo](./system-ui#vertical-bar). Two things UIKit does there, which an app sees as they are:
+
+- **The bar goes away on a scroll down.** iOS 27 minimizes the navigation bar as the content scrolls down: the whole bar, its title and its blur, leaves, and comes back on a scroll up (UIKit's `navigationItem.navigationBarMinimization`). The library has no option for it yet.
+- **Folded, a bar with a background of its own leaves a band above it.** UIKit puts the bar about 24 points below the top of the outer display, so with `topBar.background` a band of about 24 points shows above the bar's color.
+
+## API

package/docs-md/start/installation.md

@@ -0,0 +1,233 @@
+# Installation
+
+Start a new app with the navigation or add it to the app you have, run it, and check the setup with doctor.
+
+This page adds the navigation to an app: a new one made by `init`, or the app you have, set up by `setup`. At the end, the app starts with its first screen in a native stack, and `doctor` reports no problems.
+
+## Requirements
+
+- **React Native**: 0.85 or newer; checked on 0.87. The **New Architecture** only.
+- **iOS and iPadOS**: Xcode 26 or newer, CocoaPods. iOS 15.1 or newer, the minimum of React Native.
+- **Android**: JDK 17, the Android SDK the app builds with. minSdk 24 or higher.
+- **Not yet**: Expo apps: the config plugin is planned. The web is not a target.
+
+## Two ways to start
+
+- A new app — **init**: A React Native app with the navigation already set up: Home and Details in a stack, dependencies and pods installed.
+- The app you have — **install and setup**: Add the package; setup changes the native entry points and installs the pods.
+
+## A new app
+
+`init` makes a React Native app at the version the navigation is checked with, adds the package, runs `setup` and puts a starter in place of the template's `App`. Then it installs the dependencies and the pods.
+
+```bash
+npx @apexnative/navigation init MyApp
+```
+
+Run the app from its folder:
+
+```bash
+cd MyApp
+npx react-native run-ios
+npx react-native run-android
+```
+
+Home opens with an Open Details button. A tap pushes Details with the system transition; the swipe back or the back button returns to Home.
+
+The starter is the app of the [Quick start](./quick-start):
+
+| File | What it is |
+| --- | --- |
+| `Navigation.ts` | `createNavigation` with Home and Details in a stack. |
+| `src/screens/Home.tsx` | The first screen, with a button that pushes Details. |
+| `src/screens/Details.tsx` | The screen Home pushes. |
+| `navigation-env.d.ts` | Types of the commands, from `screens`: see [Typed commands](#typed-commands). |
+
+`init` removes the template's `App.tsx` and its test. The screens render inside the navigation, and a test that renders one component alone doesn't start it.
+
+### The starters
+
+`--template` picks what the new app starts with. Each starter is a working app to grow, not a demo to delete.
+
+```bash
+npx @apexnative/navigation init MyApp --template tabs
+```
+
+| Template | What the app starts with |
+| --- | --- |
+| `stack` | The default, above: Home in a stack, with a button that pushes Details. |
+| `tabs` | Tabs of Home, Profile and Settings, each in a stack of its own; Home pushes Details. The tab icons are SF Symbols on iOS (`house`, `person`, `gearshape`), and on Android vector drawables of Material Symbols, written to `android/app/src/main/res/drawable/`. |
+| `auth` | Login first. Sign in puts the user into the app's context and switches to the tabs above, where Profile shows the user's name; Sign out in Settings switches back to Login. |
+
+`auth` writes these files besides the screens:
+
+| File | What it is |
+| --- | --- |
+| `Navigation.ts` | The roots `signedOut` (Login) and `signedIn` (the tabs), the context `{ user }` with its type exported as `AppContext`, and `initialRoot`, which picks the first root from the context. |
+| `src/session.ts` | `signIn(name)` and `signOut()`: each sets the context and switches the root. |
+| `navigation-env.d.ts` | With the `context` line, as `Navigation.ts` exports `AppContext`: see [Typed commands](#typed-commands). |
+
+Login takes a name only. Your own sign-in goes where the comment in `src/session.ts` says, and the session you keep is read in `willMount`, so a user who signed in before starts on the tabs; until then each launch starts on Login. The whole flow, with links that wait for the sign-in: [Sign in and sign out](../flows/sign-in-and-sign-out).
+
+### The options of init
+
+The app it makes:
+
+| Option | What it does |
+| --- | --- |
+| `--template name` | The starter: `stack` (the default), `tabs` or `auth`. See [The starters](#templates). |
+| `--version v` | The React Native of the app: a version or a tag. By default, the one the navigation is checked with. |
+| `--pm name` | `npm`, `yarn` or `bun`. By default, the one the command runs with. |
+| `--directory path` | The folder of the app; its name by default. |
+| `--package-name id` | The Android package and the iOS bundle id, such as `com.example.app`. |
+| `--title text` | The name the app shows. |
+
+The steps it skips:
+
+| Option | What it does |
+| --- | --- |
+| `--skip-install` | Makes the app without installing dependencies and pods. |
+| `--skip-pods` | Installs the dependencies, not the pods. |
+| `--skip-git-init` | No git repository. |
+
+## The app you have
+
+1. Add the package.
+
+2. Set the app up for the navigation. `setup` shows each change and asks before it writes. On a Mac it then installs the pods, when it changed a file of the iOS app or the pods don't have the navigation yet: `pod install`, or `bundle install` and `bundle exec pod install` when the app has a `Gemfile`. On Linux and Windows it says to run `pod install` on a Mac.
+
+   ```bash
+   npx apex-navigation setup
+   ```
+
+3. Run the app.
+
+   ```bash
+   npx react-native run-ios
+   npx react-native run-android
+   ```
+
+   Your `App` shows as before, now as the first screen of a native stack, named Home in the new `Navigation.ts`.
+
+> **Tip**
+>
+>
+> `--dry-run` shows the changes and writes nothing; `--yes` applies them without asking; `--skip-pods` leaves the pods for later and prints the line to run. A file changed by hand stays as it is, and `setup` prints what to change in it. Every option of every command: [The CLI](../guides/cli#setup).
+>
+
+### What setup changes, and why
+
+In an app as the React Native template makes it, the window shows **one React view**, and all the navigation happens inside React. With this library the window shows **the containers of the platform**: a stack, tabs, modals, overlays. Every screen is a React view inside them. So the app hands its window and its startup to the navigation, and that is all the changes do.
+
+- The template — **One React view**
+- With the navigation — **Containers of the platform**
+
+#### Android files
+
+| File | What setup does | Why |
+| --- | --- | --- |
+| `MainApplication.kt` | Extends `NavigationApplication`. | It loads React Native itself and keeps one React host for all screens. Native screens made by `codegen` are registered there, before JS opens them. |
+| `MainActivity.kt` | Extends `NavigationActivity`. | The activity holds the containers of the navigation instead of one React view. It gets the back press, edge-to-edge and configuration changes first. |
+| `AndroidManifest.xml` | Adds `android:enableOnBackInvokedCallback="true"` to `<application>`. | On the first screen the system plays its own animation back to the home screen as the user swipes back (predictive back). Android 16 turns it on for apps that target API 36; an app that targets less opts in here. A value the app set itself stays. See [Back to the home screen](../screen-ui/back-and-gestures#system-animation). |
+| `styles.xml` | `AppTheme` inherits `Theme.ApexNavigation`. | The bars, tabs and search are Material 3 views and take their colors from the app's theme. This one is Material 3 in neutral grays, light and dark; change any color in the same file. A theme of the app's own stays as it is. See [Android's colors](../architecture/theme-and-context#android). |
+
+#### iOS files
+
+| File | What setup does | Why |
+| --- | --- | --- |
+| `AppDelegate.swift` | Extends `ANNAppDelegate`. | It creates the window, puts the root of the navigation in it and starts React Native. Deep links that come before JS is ready wait for it. |
+| `Info.plist` | Sets `UIViewControllerBasedStatusBarAppearance` to `true`. | Each screen sets its own status bar from its options; with `false`, only the app as a whole can. |
+
+#### JavaScript files
+
+These files are the same on both platforms.
+
+| File | What setup does | Why |
+| --- | --- | --- |
+| `index.js` | Starts the app through the navigation. | `AppRegistry` of the package starts `createNavigation` instead of mounting one root component. |
+| `Navigation.ts` | New: shows `App` as the first screen. | The app keeps working as it was, now as the first screen of a stack. |
+| `App.tsx` | Takes out the template's ``. | React Native's `StatusBar` logs an error on iOS once the screens set the status bar. |
+| `navigation-env.d.ts` | New: ties the commands to the screens of `Navigation.ts`. | The commands come from the package and can't see the app's screens. This declaration links them, so names and props are checked. See [Typed commands](#typed-commands). |
+
+### Typed commands
+
+`navigation.push('Details', { props })` comes from the package, and the package doesn't know the screens of your app. One declaration links them: `setup` and `init` write it in `navigation-env.d.ts` at the root of the app.
+
+```ts
+// Made by apex-navigation setup: the types of the app's screens
+// for the navigation's commands. Don't edit.
+declare module '@apexnative/navigation' {
+  interface Register {
+    app: typeof import('./Navigation').Navigation;
+  }
+}
+export {};
+```
+
+- **It doesn't change with the screens.** It holds no list of screens, only `typeof Navigation`: a screen added to `screens` is typed the moment the file is saved, with no command and no build.
+- **The context too.** When `Navigation.ts` exports a type or an interface named `AppContext`, the file registers it next to `app`, with the line `context: import('./Navigation').AppContext;`: see [Typing it](../architecture/theme-and-context#types). A type of another name isn't picked up.
+- **`setup` keeps it up to date.** It writes the file again when it no longer fits: `Navigation.ts` began to export `AppContext`, or `index.js` imports the navigation from another module or under another name. A renamed module or export is an error of TypeScript in this file, not a silent loss of the types; `doctor` warns about such a file under Typed commands, and `--fix` runs `setup`.
+- **Don't edit it, and commit it.** `setup` knows its own file by the first line, the comment. A file without that line is yours: `setup` leaves it as it is and prints what it would write.
+- **`export {}` matters.** It makes the file a module, so the declaration adds to the types of the package instead of replacing them.
+- **A `tsconfig.json` with its own `include`** gets the file added to it by `setup`, as one of the changes it shows. One that lists its `files` instead: `setup` prints the line to add.
+- **No `tsconfig.json`** (a JavaScript app): the file isn't made. Everything works; screen names are plain strings and props aren't checked. `doctor` checks the names the commands give instead: see [Check everything with doctor](#doctor).
+
+> **Note**
+>
+>
+> This is how TypeScript links a package to the code of an app: the commands are imported from the package, so the app has to tell it about its screens once. Other libraries do the same with a file their tools generate.
+>
+
+## Check everything with doctor
+
+`doctor` checks what the navigation needs **in the app and on the machine**, and gives a fix for each problem. Run it after setup, after an upgrade, and whenever a build fails for no clear reason.
+
+- React Native 0.87.1
+- navigation 1.0.0-alpha.0
+- **App**
+- **React Native**
+- **Navigation**
+- **Native files**
+- **Entry point**
+- **Typed commands**
+- **Navigation**
+- **Screens**
+- **Links**
+- **Android**
+- **JDK 17**
+- **Android SDK**
+- **minSdk**
+- **Edge-to-edge**
+- **iOS**
+- **Xcode**
+- **CocoaPods**
+- **Pods**
+- **iOS version**
+- **Devices**
+- **iOS simulator**
+- **adb**
+- **Conflicts**
+- **None**
+- **1 warning · 16 checks passed**
+
+| Group | What it checks |
+| --- | --- |
+| App | React Native and the New Architecture, the package, the files `setup` sets up, the entry point, React Native loaded twice, the status bar of the template, the generated code of native screens. Typed commands: `navigation-env.d.ts` there, pointing to the navigation, with its `context` line, and read by `tsconfig.json`. The splash screen made from its settings, with its logo inside the circle of Android's splash icon, and an iOS launch screen made with `UILaunchScreen` and no storyboard, which the navigation can't keep on screen. The app icon made from its settings, and an iOS icon set with no image, which the App Store refuses. |
+| Navigation | From the app's code. Screens: no name given twice in `screens` and the groups, and no file of the screens' folder with a `defineScreen` or `nativeScreen` that no file imports, a screen made and never added. Links: each prefix of `linking` declared on both platforms, the declarations no prefix has, a main activity that isn't `singleTask`. Screen names, in a JavaScript app only: a name that `push`, `replace`, `showModal` or `showInColumn` gives and no screen has, with its file and line. |
+| (Android) | JDK 17 in use, the Android SDK, `minSdk`, how edge-to-edge works in the app. |
+| (iOS) | Xcode 26 or newer, CocoaPods, the pods of the navigation and whether they are out of date, the iOS version of the Podfile. |
+| Devices | A simulator and `adb` to run the app on. |
+| Conflicts | Another navigation in the app, an Expo app. |
+
+> **Tip**
+>
+>
+> `--fix` makes the fixes the CLI has, for errors and for warnings: `setup`, `links`, `icons`, `codegen` and `pod install`, asking before each. `--json` prints the result as one JSON document, for CI, tools and AI agents. The command exits with 1 when a check finds an error; warnings leave it at 0.
+>
+
+## Next
+
+- **The first screens:** the [Quick start](./quick-start) defines two screens, puts them in a stack and pushes one from the other.
+- **A native screen:** a screen in SwiftUI, UIKit or Compose is added with `npx apex-navigation screen`. More: [Native screens](../architecture/native-screens).
+- **Coming from another library:** [From React Navigation](../migration/from-react-navigation), [From Expo Router](../migration/from-expo-router) and [From react-native-navigation](../migration/from-react-native-navigation) move an app screen by screen.
+- **Every command:** [The CLI](../guides/cli) lists them all, with their options, the links, the app icon and the server for AI agents.

package/docs-md/start/introduction.md

@@ -0,0 +1,46 @@
+# Introduction
+
+What @apexnative/navigation is, how it differs from a router in the React tree, and which apps it fits.
+
+`@apexnative/navigation` gives a React Native app the navigation of the platform itself: the stacks, tabs, sheets and gestures of iOS and Android. You describe the screens and how they are arranged in TypeScript; the native side shows them and reports back.
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+// your own components
+import { Details, Home } from './src/screens';
+
+export const Navigation = createNavigation({
+  screens: { Home, Details },
+  root: 'Home',
+});
+```
+
+Home opens in a native stack. When Home calls `navigation.push('Details')`, Details slides in with the system transition, and the swipe back (iOS) or the back button (Android) returns to Home. The [Quick start](./quick-start) builds this app step by step.
+
+> **Info**
+>
+>
+> The package is a pre-release: the banner at the top of each page says which one and how to install it, and the API can still change before 1.0.
+>
+
+## Three ways to build navigation
+
+Navigation for React Native is built in one of three ways. They answer two questions differently: **who owns the navigation state**, and **how your code speaks to it**.
+
+All three can show native screens. The difference is not in how a screen is drawn, but in where the state lives, who decides what the user sees, and what your code has to say to change it.
+
+- Model A — **A router in the React tree**
+- Model B — **Native navigation by commands**
+- Model C · this library — **Native navigation, described in React**
+- **The platform leads**: Native stacks, tabs, sheets and gestures, not a web-style router. A URL is one entry point among push notifications, widgets and shortcuts.
+- **Native is the source of truth**: Navigation state, screen lifecycle, safe areas, keyboard and theme come from the OS.
+- **App lifecycle is first-class**: Cold start, splash, session restore, background and process death are explicit steps.
+- **New OS features, fast**: Support for new iOS and Android releases lands with the betas.
+- **Customization without losing native behavior**: Options of system components first, your own native components inside native containers next, custom JS UI last.
+- **Performance is a requirement**: Transitions and gestures run natively. JavaScript stays off the critical path.
+- **Rendering and logic apart**: React renders screens. The logic of the app (a socket, a session, services) lives outside the render tree: <code>navigation</code> works outside React, <code>willMount</code> prepares the app, and the app's context is a set of services, not a store. push
+- A screen of your app asks for the next one. `navigation.push('Details')`
+- The engine turns it into a layout and sends it to the native side.
+- The platform creates the container and the React root of the screen.
+- The transition runs natively, with the system's gestures.
+- Events come back, and hooks render again. `screenDidAppear · stateChanged`

package/docs-md/start/quick-start.md

@@ -0,0 +1,124 @@
+# Quick start
+
+Build two screens in a native stack: Home, and Details that Home pushes with a title.
+
+In this tutorial you build an app with two screens. Home opens in a native stack and has a button; the button pushes Details, which shows the title Home gave it. You write three files and run the app.
+
+You start from an app set up for the navigation by `setup`, as in [The app you have](./installation#existing-app). An app made by `init` already has exactly these files: read along to see what they do.
+
+## 1. Write the first screen
+
+A screen is a React component. `defineScreen` puts its options next to it; here the option is the title that the native top bar shows.
+
+Create `src/screens/Home.tsx`:
+
+```tsx
+import { Button, View } from 'react-native';
+import { defineScreen, useNavigation } from '@apexnative/navigation';
+
+function Home() {
+  const navigation = useNavigation();
+  const open = () =>
+    navigation.push('Details', { props: { title: 'Details' } });
+  return (
+    <View>
+      <Button title="Open Details" onPress={open} />
+    </View>
+  );
+}
+
+export const HomeScreen = defineScreen({
+  component: Home,
+  options: (s) => s.title('Home'),
+});
+```
+
+`useNavigation` gives the screen its commands. `push` shows the screen named `Details` on top of Home, with the props after the name.
+
+## 2. Write the screen it opens
+
+Details gets its props from the command that shows it. Its options read the same props, so the top bar shows the title Home passed.
+
+Create `src/screens/Details.tsx`:
+
+```tsx
+import { Text, View } from 'react-native';
+import { defineScreen } from '@apexnative/navigation';
+
+export interface DetailsProps {
+  title?: string;
+}
+
+function Details(props: DetailsProps) {
+  return (
+    <View>
+      <Text>{props.title ?? 'Details'}</Text>
+    </View>
+  );
+}
+
+export const DetailsScreen = defineScreen({
+  component: Details,
+  options: (s, props) => s.title(props.title ?? 'Details'),
+});
+```
+
+## 3. Create the navigation
+
+`createNavigation` takes the screens by name and the root, what takes the window first. A screen name alone as the root shows that screen in a native stack, so Home can push Details.
+
+Replace the `Navigation.ts` that `setup` made:
+
+```ts
+import { createNavigation } from '@apexnative/navigation';
+import { DetailsScreen } from './src/screens/Details';
+import { HomeScreen } from './src/screens/Home';
+
+export const Navigation = createNavigation({
+  screens: { Home: HomeScreen, Details: DetailsScreen },
+  root: 'Home',
+});
+```
+
+The names in `screens` are the names the commands use. They are typed: `navigation.push('Detail')` or a prop Details doesn't take is an error in the editor, not at run time. The file `navigation-env.d.ts` that `setup` wrote ties the commands to `screens`, and you don't edit it. More: [Typed commands](./installation#typed-commands).
+
+## 4. Check the entry point
+
+`setup` already changed `index.js`. It registers the navigation with `AppRegistry` from the package, not from `react-native`: this one takes the navigation instead of a root component, and starts it when the native side launches the app.
+
+```js
+import { AppRegistry } from '@apexnative/navigation';
+import { name } from './app.json';
+import { Navigation } from './Navigation';
+
+AppRegistry.registerComponent(name, Navigation);
+```
+
+## 5. Run the app
+
+```bash
+npx react-native run-ios
+npx react-native run-android
+```
+
+Home opens in a native stack, with Home in the top bar. Tap Open Details: Details slides in with the system transition, and the top bar shows Details with a back button. The swipe from the left edge (iOS) or the back button (Android) returns to Home.
+
+## What a root can be
+
+The app you built has one stack. `root` also takes a layout made of builders, and each builder is a real platform container:
+
+| Root | What you get |
+| --- | --- |
+| `'Home'` | A native stack with Home: push, pop and swipe back. |
+| `Stack('Home', 'Details')` | A stack that starts with more than one screen. |
+| `Tabs(Tab(Stack('Home')), …)` | The system tab bar; each tab keeps its own stack. |
+| `SideMenu(…)` | A side menu next to a center screen. |
+| `SplitView(…)` | Columns for the large iPad screen. |
+
+An app that switches between roots, such as signed out and signed in, uses `roots` instead. More: [Switching roots](../fundamentals/switching-roots) and the flow [Sign in and sign out](../flows/sign-in-and-sign-out).
+
+## Where to go next
+
+- **How the app starts:** [Starting the app](../fundamentals/starting-the-app) covers everything `createNavigation` takes.
+- **More about screens:** [Screens and props](../fundamentals/screens-and-props), then [Moving between screens](../fundamentals/moving-between-screens).
+- **Coming from another library:** [From React Navigation](../migration/from-react-navigation), [From Expo Router](../migration/from-expo-router) and [From react-native-navigation](../migration/from-react-native-navigation) map what you use now to this API.