# Xplat docs

> Build shared TypeScript screens for web, iOS, and Android. macOS, Windows, and Linux are experimental targets with separate setup and narrower verification; consult the target guide before choosing a release platform.

Xplat lets one TypeScript app write shared screens from a small component vocabulary. The web build renders them to the DOM; the iOS/Android build renders NativeScript views. Packages: `@octane-xplat/ui` (components, styled(), route table, theme), `@octane-xplat/cli` (`xplat` dev/build/doctor/typecheck/clean), `@octane-xplat/platform` (device services), `create-octane-xplat` (project starter).

Rules for shared app code: one element vocabulary per file — platform divergence happens at file boundaries using `.web` for browser code, `.mobile` for shared iOS/Android variants, and OS suffixes such as `.ios`/`.android`; the unsuffixed module is the native default. Static styles go in `className`; values that change at runtime go in `style` objects. Shared code never touches DOM globals — device capabilities come from `@octane-xplat/platform`. Hook-calling code lives in `.tsx`/`.tsrx` files. Every app bundles exactly one copy of `octane`.

```tsx
import { useState } from 'octane'
import { View, Text, Pressable } from '@octane-xplat/ui'

export function Counter() {
  const [count, setCount] = useState(0)
  return <View className="counter" style={{ opacity: count === 0 ? 0.6 : 1 }}>
    <Text>{count} items packed</Text>
    <Pressable onPress={() => setCount(count + 1)}><Text>Pack an item</Text></Pressable>
  </View>
}
```

## Guides

### Start here

- [Octane Xplat](https://octane-xplat.goddardai.org/): Build apps for the web, iOS, and Android from ==one project==.
- [What you can build with Xplat](https://octane-xplat.goddardai.org/spec): Share your app's screens and behavior between the web and phones, with room to customize each platform.
- [Create your first app](https://octane-xplat.goddardai.org/toolchain): Open a starter app in your browser, then make a small change and try it.
- [How an Xplat app fits together](https://octane-xplat.goddardai.org/architecture): Your screens use shared building blocks. Platform files handle the parts that need to work differently in a browser or on a phone.
- [Add actions and choices to a menu](https://octane-xplat.goddardai.org/menus)

### Build your app

- [Building screens](https://octane-xplat.goddardai.org/primitives): Combine text, buttons, fields, and containers to make a screen.
- [Component index](https://octane-xplat.goddardai.org/components): Components exported by `@octane-xplat/ui`, grouped by job.
- [Enter and submit text](https://octane-xplat.goddardai.org/text-entry): Add a text field, keep what someone types, and choose how they submit it.
- [Action controls and interactive cards](https://octane-xplat.goddardai.org/interactive-actions): Add buttons, action menus, and cards someone can select or open.
- [Content display](https://octane-xplat.goddardai.org/content-display): Show formatted text, code, progress, dates, or a table of contents.
- [Moving between screens](https://octane-xplat.goddardai.org/navigation): Open another screen and let someone return with Back.
- [Build a navigation shell and resizable workspace](https://octane-xplat.goddardai.org/navigation-ui): Add a top bar, sidebar, mobile menu, or resizable panel around your screens.
- [Search, select, and enter tokens](https://octane-xplat.goddardai.org/search-selection): Let someone choose from a list or find options by typing.
- [Search commands across targets](https://octane-xplat.goddardai.org/command-palette): Use one command search contract with a keyboard palette on web and macOS and a touch-first search sheet on iOS and Android.
- [Structured search](https://octane-xplat.goddardai.org/power-search): Add filters such as “Title contains travel” or “Year is greater than 2020.”
- [Fetching data](https://octane-xplat.goddardai.org/data): Load information from a server and show what's happening while you wait.
- [Styling screens](https://octane-xplat.goddardai.org/styling): Change colors, spacing, fonts, and layout with styles that work on the web and phones.
- [Localizing an app](https://octane-xplat.goddardai.org/localization): Show your app's text in another language with Lingui.
- [Motion and gestures](https://octane-xplat.goddardai.org/animation-gestures): Move, fade, or resize a screen element, and respond to dragging.
- [VirtualList](https://octane-xplat.goddardai.org/virtual-list): Show a long scrolling list while creating only the rows near the screen.
- [Rich text editing](https://octane-xplat.goddardai.org/rich-text): Let someone edit formatted text, such as paragraphs with bold words or links.

### Device features

- [Sharing files across platforms](https://octane-xplat.goddardai.org/module-resolution): Give a component different files when it needs to work differently in a browser or on a phone, while keeping one name in the rest of your app.
- [Using device features](https://octane-xplat.goddardai.org/platform-services): Save a setting, attach a photo, share a link, or use another device feature.
- [Audio and haptics](https://octane-xplat.goddardai.org/media-services): Play a sound, add vibration feedback, or play a queue of audio tracks.
- [Send a local notification](https://octane-xplat.goddardai.org/local-notifications): Ask for permission, then let the operating system show a message from your app.
- [Push notifications](https://octane-xplat.goddardai.org/push-notifications): Receive messages sent to your app with Firebase Cloud Messaging.
- [Platform pickers](https://octane-xplat.goddardai.org/native-picker): Choose an option with an iOS picker, Android dropdown, or browser select.
- [Date and file entry](https://octane-xplat.goddardai.org/date-picker): Let someone choose a date, time, date range, or file in a form.
- [Platform context menus](https://octane-xplat.goddardai.org/context-menu): Show actions for an item when someone holds or right-clicks it.
- [Platform modal bottom sheets](https://octane-xplat.goddardai.org/sheet): Open a panel above the current screen using the platform's own presentation.
- [Run a macOS app in WKWebView](https://octane-xplat.goddardai.org/macos-webview): Display your web screens inside an experimental macOS desktop app.
- [Ship native code in a macOS leaf](https://octane-xplat.goddardai.org/macos-native): Add a macOS feature written in C, Objective-C, Swift, or Zig and call it from your app's JavaScript code.
- [Package a Linux WebKitGTK app](https://octane-xplat.goddardai.org/linux-package): Package your web screens as an experimental Linux desktop app.
- [Set up a Windows test host](https://octane-xplat.goddardai.org/windows-setup)

### Check your app

- [Checking an Xplat app](https://octane-xplat.goddardai.org/testing): Try the actions your app supports, then use code checks to catch problems you might miss while using it.
- [Test phone journeys with Maestro](https://octane-xplat.goddardai.org/maestro): Repeat a tap-and-check journey on Android and iOS, and save the result so you can catch regressions after changing your app.
- [Probe one platform case](https://octane-xplat.goddardai.org/probing)
- [Verify release navigation](https://octane-xplat.goddardai.org/navigation-checks): Exercise router state and rendered text in release builds without screenshots.
- [Known limits](https://octane-xplat.goddardai.org/known-limits): Check which features are available, different, or still unfinished on the platforms you plan to use.
- [Check an app with Argent](https://octane-xplat.goddardai.org/argent): Let a coding agent find controls and exercise a small, repeatable journey on your local browser or test phone.
- [Debug native image performance](https://octane-xplat.goddardai.org/image-performance): Diagnose scroll jank, memory spikes, and slow-loading images on iOS and Android.
- [Give controls stable test names](https://octane-xplat.goddardai.org/test-identifiers): Name the controls a test or coding agent needs to find without changing what a screen reader says.

## Optional

- [All guides, one file](https://octane-xplat.goddardai.org/llms-full.txt): every guide inlined in reading order.
- [Design notes](https://octane-xplat.goddardai.org/notes): the design record — status, decisions, open questions, per-topic implementation notes. Consult when debugging framework internals or checking why a constraint exists; not needed for app work.
- [Changelog](https://github.com/octane-xplat/octane-xplat/blob/main/CHANGELOG.md): per-release changes and upgrading notes.
- [Repository](https://github.com/octane-xplat/octane-xplat)
- [npm: @octane-xplat/ui](https://www.npmjs.com/package/@octane-xplat/ui)