# AI execution

Run installed Claude/Codex tools or use the optional macOS Codex supervisor.

Source: https://legend.so/spark/ai/

## [Installed command-line tools](https://legend.so/spark/ai/#installed-command-line-tools)

`@legendapp/spark/ai` owns execution helpers for installed Claude and Codex CLIs. It uses Spark processes and requires a desktop process host. Installation, login, prompts, provider policy, and data validation remain application/user responsibilities. Importing helpers does not run a prompt.

```ts
import { getAICommandAvailability, runAITool, parseAIJson } from '@legendapp/spark/ai';

const availability = await getAICommandAvailability({ preferredTool: 'codex' });
if (availability.preferredTool) {
  const result = await runAITool({
    tool: availability.preferredTool,
    prompt: 'Return a JSON object containing a greeting.',
    timeoutMs: 30_000,
  });
  if (result.exit.type === 'exited' && result.exit.code === 0) {
    const value = parseAIJson(result.output);
    console.log(value);
  }
}
```

Availability is an advisory installed-command probe, not authenticated access. `runAITool` retains the process result, including raw stdout/stderr bytes, discriminated exit, timeout/abort, and truncation. `output` is trimmed UTF-8 stdout, falling back to stderr if stdout is empty. Nonzero exit and termination are results; operational failures reject.

`signal`, `cwd`, and `timeoutMs` follow the process contract. Codex model/reasoning settings go in `invocationOptions.codex`. The Codex exec recipe uses ephemeral execution and ignores user config/exec-policy rule files while retaining the CLI's sandbox/approval mechanism. Protocol/flags depend on the installed tool version.

`buildAIInvocation` returns the argument recipe without execution. JSON helpers extract raw/fenced/prose-wrapped content and return unknown/null; validate application schemas before using it. `formatAIErrorOutput(output, { maxLength })` bounds error previews. No React mount is required.

## [Native Codex app-server](https://legend.so/spark/ai/#native-codex-app-server)

`@legendapp/spark/ai/codex` supplies an optional **macOS** native supervisor, with exec fallback when its app-server protocol is unavailable. `getCodexAvailability()` safely reports unsupported hosts/missing modules and installed-command information. A consuming app needs the matching native capability and rebuilt host.

```ts
import { runCodexPrompt, shutdownCodex } from '@legendapp/spark/ai/codex';

const result = await runCodexPrompt('Return a greeting as JSON.', {
  outputSchema: {
    type: 'object',
    properties: { greeting: { type: 'string' } },
    required: ['greeting'],
    additionalProperties: false,
  },
  reasoningEffort: 'low',
  timeoutMs: 120_000,
});
console.log(result.output);
await shutdownCodex();
```

The final line represents application-owned shutdown. The supervisor is process-wide. `cancelActiveCodexRuns()` cancels all accepted runs, including startup, and returns a count. `shutdownCodex()` cancels active runs and stops the server; later execution restarts it. These are not per-component or per-request cleanup operations. This backend does not promise a per-request AbortSignal.

`timeoutMs` is a whole number from 1,000 to 86,400,000 milliseconds. The isolated Codex home reuses existing authentication; the library does not acquire credentials. Pre-ack notification buffering is bounded at 16 MiB and excessive buffering fails explicitly.

See [the AI guide](https://github.com/LegendApp/legend-spark/blob/main/docs/ai.md).

[View Markdown](https://legend.so/spark/ai.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+AI+execution&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fai%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Camera

VisionCamera previews, permissions, and automatic native compatibility patches.

Source: https://legend.so/spark/camera/

`@legendapp/spark/camera` exposes VisionCamera components, device/permission hooks, photo/video outputs, and session APIs with upstream semantics. It also exports `NitroImage` and its `Image` type. Advanced APIs remain available from `react-native-vision-camera` directly.

## [Camera preview](https://legend.so/spark/camera/#camera-preview)

```tsx
import {
  Camera, useCameraDevices, useCameraPermission, usePhotoOutput,
} from '@legendapp/spark/camera';
import { Button } from 'react-native';

export function PhotoCamera() {
  const devices = useCameraDevices();
  const { hasPermission, requestPermission } = useCameraPermission();
  const photoOutput = usePhotoOutput({ containerFormat: 'jpeg' });

  if (!hasPermission) {
    return <Button title="Allow camera" onPress={() => void requestPermission()} />;
  }
  return devices[0] ? <Camera device={devices[0]} isActive outputs={[photoOutput]} /> : null;
}
```

## [Installation and permissions](https://legend.so/spark/camera/#installation-and-permissions)

Spark installs VisionCamera 5.2.3, Nitro Image 0.15.2, and Nitro Modules 0.37.0. Compatibility patches apply automatically, including when install scripts were disabled. No separate camera install is needed. Production builds can remove unused camera code.

iOS and Android use upstream implementations; Spark adds macOS 14+ AppKit patches. Windows and web are unsupported. Live capture and mobile acceptance remain unverified; see the [prototype evidence and limits](https://github.com/LegendApp/legend-spark/blob/main/docs/camera-prototype.md).

On macOS, set `NSCameraUsageDescription` in `desktop.config.json` under `macos.infoPlist`; audio recording also needs `NSMicrophoneUsageDescription`. Set iOS usage descriptions and Android permissions through Expo/native configuration. Ask for permission when the user starts using the camera.

See Spark's [camera integration](https://github.com/LegendApp/legend-spark/blob/main/docs/camera.md) for imperative APIs, resource lifetimes, and patch details.

[View Markdown](https://legend.so/spark/camera.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Camera&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fcamera%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Application configuration

Own desktop configuration, compose Expo projects, and preserve native identity.

Source: https://legend.so/spark/configuration/

## [Spark-owned projects](https://legend.so/spark/configuration/#spark-owned-projects)

Edit `desktop.config.json`; generated `app.json` is Expo's transport configuration. Universal projects use a generated `app.config.js` resolver. Retain the generated stable `projectId`: it scopes storage and runtime identity across app renames and builds.

```json
{
  "$schema": "./node_modules/@legendapp/spark/schema.json",
  "projectId": "f478dff4-f9a1-4ff2-8096-64df89e1c470",
  "name": "MyApp",
  "version": "0.0.1",
  "platforms": ["macos"],
  "window": {
    "size": { "width": 1000, "height": 700 },
    "minSize": { "width": 500, "height": 300 },
    "restoreBounds": true
  },
  "macos": { "bundleIdentifier": "com.example.myapp" }
}
```

Sizes are outer-frame logical dimensions. AppKit-specific chrome is grouped under `window.macos`, including `titleBar.trafficLights` and `backgroundMaterial`. Portable defaults stay in `window`; native startup behavior stays in `macos.lifecycle`.

Spark owns identity, windows, document associations, update signing, helper bundles, and desktop lifecycle policy. Expo settings/plugins go in `expo` or `expoByPlatform.<target>`. Custom native settings may require an app-specific binary.

`@legendapp/spark/config` exports typed configuration/readers. `toExpo` validates untrusted Spark JSON. The schema supports editor checks; runtime validation also checks target, size, helper-path, and update relationships.

## [Existing Expo apps](https://legend.so/spark/configuration/#existing-expo-apps)

From a prepared local SDK checkout:

```sh
bun run spark add desktop --project /absolute/path/to/ExistingExpoApp
```

The integration checks the installed Expo `54.0.37`, React Native `0.81.6`, and React `19.1.4` baseline before editing. Upgrading an incompatible app is separate work. It preserves the entry point, source, existing mobile/web scripts, and mobile native projects. Existing desktop script names are preserved, using `spark:macos`/`spark:windows` when needed.

Expo remains the source for app name/version and shared settings. The sidecar declares `extends: "expo"`, stable identity, desktop platforms, and desktop options. `withSparkExpo` from `/expo-config` composes the existing config; ordinary Expo commands retain their mobile/web meaning. Spark commands select the desktop/shared session environment automatically.

Review generated integration files and run the app's existing checks. Automatic config composition has restrictions on export shapes, module format, and Metro/native config filenames. Existing desktop projects need explicit host composition. See [the integration guide](https://github.com/LegendApp/legend-spark/blob/main/docs/add-desktop.md); preserving an Expo Router entry does not establish desktop Router support.

## [Metro and native discovery](https://legend.so/spark/configuration/#metro-and-native-discovery)

Retain the generated wrappers and apply application customizations through them. For a Spark-owned project:

```js
// metro.config.js
const { metroConfig } = require('@legendapp/spark/metro');
module.exports = metroConfig(__dirname);
```

```js
// react-native.config.js
module.exports = require('@legendapp/spark/native').nativeConfig(__dirname);
```

For an existing Expo project, compose its configuration:

```js
const { getDefaultConfig, withSparkMetro } = require('@legendapp/spark/metro');
const config = getDefaultConfig(__dirname);
module.exports = withSparkMetro(config);
```

`withSparkNative(existingConfig, __dirname)` preserves app assets and native settings. `withSparkMetro` accepts asynchronous wrappers as well.

## [Native lifecycle](https://legend.so/spark/configuration/#native-lifecycle)

The standard Spark AppDelegate owns React bootstrap and app event dispatch. `macos.lifecycle.mainWindow` can configure initial visibility, close behavior, and reopen policy. Native packages can opt into startup plugins and asynchronous quit handlers without replacing the app delegate. Link/include a plugin that must survive production pruning.

A hidden main window keeps the runtime alive; it does not make the app menu-bar-only. Runtime close/quit guards and [document coordination](https://legend.so/spark/documents/) own asynchronous application decisions. See [native lifecycle](https://github.com/LegendApp/legend-spark/blob/main/docs/host-migration.md) and [configuration details](https://github.com/LegendApp/legend-spark/blob/main/docs/configuration.md).

[View Markdown](https://legend.so/spark/configuration.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Application+configuration&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fconfiguration%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Development and runtimes

Use Expo CLI, select Spark Runner or custom binaries, and rebuild native changes.

Source: https://legend.so/spark/development/

`npm run dev`, `npm start`, and the generated desktop scripts enter one managed Expo CLI development session. Expo owns Metro, logs, reload, debugging, and mobile/web actions; Spark adds desktop runtime selection and compatibility checks.

## [Terminal actions](https://legend.so/spark/development/#terminal-actions)

| Key | Action |
| --- | --- |
| `d` | Open the host desktop target |
| `g` | Switch Spark Runner/custom development build without compiling |
| `b` | Build and open a required custom development binary |
| `r`, `j`, `m` | Expo reload, debugger, and development menu |
| `i`, `a`, `w` | Declared iOS, Android, and web targets |
| `s` | Mobile Expo Go/development-client selection |
| `?` | Current command table |
| Ctrl+C | Exit the session and close its owned native app |

Expo Go is a mobile runtime; it is separate from Spark Runner. Switching binaries or restarting Metro can reset React state. Desktop selection is remembered in `.spark/settings.json`.

A universal session serves all declared targets. A missing/incompatible desktop binary blocks that desktop bundle while mobile/web remain available. `--platform` chooses an initial launch; it does not add a platform to the project.

```sh
npx --no-install spark dev --no-open
npx --no-install spark dev --platform ios
npx --no-install spark dev --port 8082 --localhost
```

Expo start flags such as `--clear`, `--offline`, `--lan`, `--tunnel`, and `--max-workers` pass through. Use `spark dev --help` for the full list. Desktop launch uses the port Expo reports.

## [Native changes](https://legend.so/spark/development/#native-changes)

Extra native modules, URL/document associations, helper binaries, or native settings/plugins can require an app-specific build. Spark checks native requirements before loading JavaScript; it does not automatically compile every edit.

```sh
npx --no-install spark build --dev --platform macos
# On Windows:
npx --no-install spark build --dev --platform windows
```

`build --dev --force` forces regeneration and compilation. Author durable native changes in packages/config plugins; generated native directories are disposable. Run native generation/build operations sequentially in one checkout.

To select Intel macOS from a consumer project:

```sh
SPARK_MACOS_ARCH=x64 npx --no-install spark build --dev
SPARK_MACOS_ARCH=x64 npx --no-install spark dev
```

`SPARK_MACOS_ARCH=arm64|x64` and `SPARK_WINDOWS_ARCH=x64|arm64` select build targets. The matching architecture is part of runtime compatibility. Intel macOS and Windows native builds and runtime behavior still need validation. No hosted Windows Runner exists; build one locally.

## [Production selection](https://legend.so/spark/development/#production-selection)

```sh
npx --no-install spark analyze
npm run build
```

Analysis records production reachability in `.spark/selection-report.json`. SDK native modules can be pruned; unknown third-party native dependencies are retained. Keep native-only requirements in configuration. `build --preview` uses the production native selection in Debug; it is distinct from the standalone embedded-bundle build.

## [SDK iteration and diagnostics](https://legend.so/spark/development/#sdk-iteration-and-diagnostics)

After SDK source changes, run `node scripts/refresh-consumer.ts /path/to/app` from the framework checkout to refresh a test app. Rebuild/register its Runner when the native signature changes.

Use `spark doctor` to check native prerequisites and dependency pins. Preview upgrades before applying them:

```sh
npx --no-install spark doctor
npx --no-install spark upgrade --dry-run
npx --no-install spark upgrade
```

Upgrade stays on your current release channel and applies versioned migrations. See [Upgrading Spark](https://legend.so/spark/migration/) to move from a preview to 0.0.1. Keep React and Expo on Spark's tested pins. Doctor also reports outdated Enriched HTML web dependencies; upgrade repairs their pins.

Build logs and diagnostic reports live under `.spark/`. Keep generated diagnostics out of version control.

See [configuration](https://legend.so/spark/configuration/), [examples and validation](https://legend.so/spark/examples/), and the [SDK development guide](https://github.com/LegendApp/legend-spark/blob/main/docs/development.md).

[View Markdown](https://legend.so/spark/development.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Development+and+runtimes&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fdevelopment%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Packaging and updates

Standalone macOS binaries, signed archives, native app updates, and SDK transfer.

Source: https://legend.so/spark/distribution/

## [Build and package a macOS app](https://legend.so/spark/distribution/#build-and-package-a-macos-app)

From the generated app:

```sh
npm run build
npx --no-install spark open
npm run package
```

`build` embeds JavaScript and the production-selected native graph in a local ad-hoc-signed `.app`. `package` signs a staging copy with Developer ID, notarizes it with your Keychain profile, and validates the distribution ZIP. It does not publish the application.

Signing requires installed credentials, full Xcode tooling, and a notarization profile. First use can configure credentials. Keep signed archives and submission state until Apple's outcome is known. Resume/recover a pending submission through the documented packaging commands rather than starting a duplicate submission.

Intel targeting uses `SPARK_MACOS_ARCH=x64` for build/package, with matching native dependencies and helper binaries. Intel native builds, runtime behavior, and signed distribution still need validation. Windows production/preview builds, signing/MSIX, Linux, and the Mac App Store workflow remain unsupported.

See [packaging details](https://github.com/LegendApp/legend-spark/blob/main/docs/packaging.md).

## [Whole-app updates](https://legend.so/spark/distribution/#whole-app-updates)

`@legendapp/spark/updates` supplies native macOS whole-app update integration. It is not Expo-style JavaScript OTA updates. Runner/development/unconfigured hosts report explicit unavailability through `getUpdateStatus()`.

```ts
import { getUpdateStatus, checkForUpdates, onUpdateEvent } from '@legendapp/spark/updates';

const subscription = onUpdateEvent(event => {
  if (event.state === 'error') console.error(event.message);
  else if ('version' in event) console.log(event.state, event.version);
});
const status = await getUpdateStatus();
if (status.available && status.canCheck) {
  await checkForUpdates({ mode: 'interactive' });
}
subscription.remove();
```

Retain the subscription for the app/UI lifetime; the last line illustrates teardown. Checking resolves when initiated. Progress/completion arrives as typed events: checking/notAvailable, version-bearing available/downloading/downloaded/installing, or error with message.

`startUpdates` starts a configured updater. `configureUpdates({ automaticallyChecks?, checkIntervalSeconds? })` changes preferences; an empty object starts the configured updater without changing preferences. Feed/key configuration belongs to the native app and can require rebuilding.

Update build numbers must increase. The CLI validates a new build against the feed and earlier local artifact; equal or lower numbers reject. Test signed installation, relaunch, and rejection of older builds with your app and feed.

See [update configuration](https://github.com/LegendApp/legend-spark/blob/main/docs/desktop-integrations.md) and [status and limitations](https://legend.so/spark/limitations/).

## [Transfer a local SDK](https://legend.so/spark/distribution/#transfer-a-local-sdk)

From the framework checkout:

```sh
bun run spark sdk export /path/to/SparkSDK --runtime /path/to/SparkRunner.app
```

The transferable directory contains immutable package archives, checksums, an installer, and optional runtimes. `--runtime` can repeat. A Windows export includes the entire product directory with its DLLs. Exports refuse existing destinations and only publish output after validation.

On the recipient, preserve bytes, permissions, and symlinks, then:

```sh
cd /path/to/SparkSDK
node install.mjs
```

Use the installed CLI command printed by the installer. Installation verifies archives before installing/registering the SDK. Network access is still needed for third-party dependencies; checksums detect corruption but are not publisher signatures.

Keep the installed directory/runtime locations stable. Relocate before installation; moving an installed SDK requires reinstalling/refreshing app references. This workflow is useful for current-source testing and does not require public npm publication.

## [Matching SDK runtimes](https://legend.so/spark/distribution/#matching-sdk-runtimes)

Use a Runner that matches your SDK and native dependencies. Rebuild or register a matching local Runner after SDK/native changes. Source packing, registration, and export do not publish artifacts. See [SDK transfer](https://github.com/LegendApp/legend-spark/blob/main/docs/sdk-distribution.md).

[View Markdown](https://legend.so/spark/distribution.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Packaging+and+updates&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fdistribution%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Documents and application lifecycle

Quit decisions, replayable open requests, recent documents, and owned controllers.

Source: https://legend.so/spark/documents/

## [Application lifecycle](https://legend.so/spark/documents/#application-lifecycle)

`@legendapp/spark/app` supplies `getAppContext`, `activate`, `hide`, `quit`, `beforeQuit`, and typed app listeners. Context includes stable identity, native runtime information, and initial process arguments. `getAppAvailability()` is safe without the optional module.

```ts
import { beforeQuit } from '@legendapp/spark/app';
import { settings } from '@legendapp/spark/settings';

const guard = await beforeQuit(async () => {
  await settings.set('lastSession', { closedCleanly: true });
  return true;
}, { onError: console.error });

await guard.remove();
```

Keep the guard registered for the app-owned lifetime; the final line illustrates teardown. Register before enabling work that needs protection. Save/flush inside the guard. An approved quit can stop JavaScript before an awaiting continuation runs.

Every guard must approve. False, rejection, the native 30-second deadline, or guard changes during a decision vetoes that attempt. `quit()` joins a pending request and reports `quitRequested`, with `reason: 'vetoed'` on refusal. Forced process termination cannot be vetoed. `willQuit` is a live notification, not an asynchronous cleanup boundary.

App listeners report activation/deactivation, reopen, second-instance arguments, and logical window registry changes. They return synchronous subscriptions. Use `/windows` listeners for one native window lifetime. `finishWindowRestoration()` completes the macOS startup-shell restoration coordinator after restored roots are opened.

## [Open requests and recent history](https://legend.so/spark/documents/#open-requests-and-recent-history)

Use `@legendapp/spark/app/documents` for file/URL launch requests and recent documents:

```ts
import {
  subscribeToOpenRequests,
  noteRecentDocument,
  getRecentDocuments,
} from '@legendapp/spark/app/documents';

const subscription = await subscribeToOpenRequests(request => {
  if (request.type === 'file') console.log(request.path);
  else console.log(request.url);
});
await noteRecentDocument('/absolute/path/to/Notes.txt');
const recent = await getRecentDocuments();
subscription.remove();
```

`OpenRequest` discriminates `{ type: 'file', id, path }` from `{ type: 'url', id, url }`. File paths are decoded once; avoid manually interpreting them as URLs. Recent history is project-scoped; native OS history integration depends on the host.

Registration installs the live listener before replaying up to 100 retained native requests and deduplicates replay/live overlap. Each new subscription can replay requests again. Exactly-once import policy across controller lifetimes belongs to the app.

`/links` separately retains Expo-shaped URL methods and live URL events. Those listeners exclude file-open events and launch replay.

## [Document coordination](https://legend.so/spark/documents/#document-coordination)

`createDocumentAppController` owns menu/listener setup, initial opening, reopen requests, document delivery, and selected logical-window state. Its handle exists immediately; await `ready` for setup. Use `onOpenDocument(path, controller)` for file requests, and `reportError` for application callbacks. `updateMenus`, state getters/setters, and `subscribe` support application services outside React.

Await `controller.remove()` at its ownership boundary, including after setup failure. Removal waits for setup/native cleanup, but does not cancel application callbacks already running. Failed cleanup remains retryable.

`useDocumentAppController` returns loading/ready/error state, keeps callbacks current, and owns removal on unmount. `onCleanupError(error, controller)` exposes failed cleanup for retry.

`watchDocumentReload` owns a debounced file watcher, serializes reloads, and waits for an active reload during removal. Its React adapter is `useWatchedDocumentReload`. Supply `onError`; do not await watcher removal inside the reload it is waiting for.

See [app lifecycle](https://github.com/LegendApp/legend-spark/blob/main/docs/app.md) and [document coordination](https://github.com/LegendApp/legend-spark/blob/main/docs/links-and-documents.md).

[View Markdown](https://legend.so/spark/documents.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Documents+and+application+lifecycle&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fdocuments%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Drag and drop

Native drag sources and drop destinations for files, text, URLs, and custom data.

Source: https://legend.so/spark/drag-drop/

Use `DragDropView` from `@legendapp/spark/drag-drop` to drag or receive files, text, URLs, and custom data. It accepts ordinary React Native view props.

Native drag behavior on macOS and Windows still needs validation.

## [Sources and destinations](https://legend.so/spark/drag-drop/#sources-and-destinations)

```tsx
import { Text } from 'react-native';
import { DragDropView } from '@legendapp/spark/drag-drop';

export function DragExample() {
  return (
    <>
      <DragDropView
        source={{ data: { 'application/x-my-item': JSON.stringify({ id: '42' }) } }}
        sourceOperations={['copy', 'move']}
        onDragEnd={event => console.log(event.accepted, event.operation)}
        onError={console.error}
      >
        <Text>Drag this item</Text>
      </DragDropView>
      <DragDropView
        acceptedTypes={['files', 'application/x-my-item']}
        acceptedOperations={['copy', 'move']}
        onDrop={({ files, data, operation, x, y }) => {
          console.log({ files, data, operation, x, y });
        }}
        onError={console.error}
      >
        <Text>Drop here</Text>
      </DragDropView>
    </>
  );
}
```

## [Payloads and negotiation](https://legend.so/spark/drag-drop/#payloads-and-negotiation)

`DragPayload` can contain several representations at once:

| Field | Value |
| --- | --- |
| `files` | Array of absolute native paths. Local file URLs in a source are normalized. |
| `text` | A string. |
| `urls` | Array of absolute URLs. Windows sources allow one URL; multiple URLs reject with `E_UNSUPPORTED_OPTION`. |
| `data` | Map of lowercase custom MIME names to UTF-8 strings. The app owns JSON schemas and validation. |

A source must contain at least one representation. `text/plain`, `text/uri-list`, and `application/x-spark-drag` are reserved; use the built-in fields for text and URLs.

`sourceOperations` and `acceptedOperations` accept `copy`, `move`, and `link`, and each defaults to `['copy']`. Destinations default to `acceptedTypes={['files', 'text', 'urls']}`; custom MIME types require explicit opt-in. The first mutually supported target operation wins. Empty accepted operations or types reject all drops; `disabled` disables both directions.

Accepted types determine drop eligibility. A payload may still include coexisting built-in representations, while custom data is restricted to requested custom types.

## [Events](https://legend.so/spark/drag-drop/#events)

| Callback | Payload |
| --- | --- |
| `onDragEnter`, `onDrop` | `DropEvent`: payload fields plus `x`, `y`, and `operation`. |
| `onDragOver` | `DragOverEvent`: only `x`, `y`, and `operation`. |
| `onDragLeave` | No payload. |
| `onDragEnd` | `{ accepted: true, operation: 'copy' | 'move' | 'link' }` or `{ accepted: false, operation: 'none' }`. |

Coordinates are logical units from the destination's top-left corner. For a move, save the dropped data before deleting it at the source. An accepted drop does not confirm that saving succeeded.

## [Availability and errors](https://legend.so/spark/drag-drop/#availability-and-errors)

`getDragDropAvailability()` synchronously reports an unsupported platform or a missing native component. An unavailable host renders an ordinary `View` with the children intact. Remount after repairing the host to retry.

Handle `onError` to show unavailable-host and native errors; it defaults to `console.error`. Invalid props throw during render. Invalid native events report through `onError` and skip their callback.

See the [drag-and-drop source guide](https://github.com/LegendApp/legend-spark/blob/main/docs/drag-drop.md) and [shared error contracts](https://legend.so/spark/reference/#shared-contracts).

[View Markdown](https://legend.so/spark/drag-drop.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Drag+and+drop&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fdrag-drop%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Examples and validation

Explore Kitchen Sink, generate focused apps, and run source and platform checks.

Source: https://legend.so/spark/examples/

## [Kitchen Sink](https://legend.so/spark/examples/#kitchen-sink)

From the current source checkout:

```sh
bun run kitchen-sink
```

[Prepare the source SDK](https://legend.so/spark/getting-started/#contributing-build-spark-from-source) and register a matching Runner first. To build a custom runtime for Kitchen Sink:

```sh
cd examples/kitchen-sink
bun run rebuild:macos
bun run macos
# On Windows:
# bun run rebuild:windows
# bun run windows
```

Kitchen Sink demonstrates desktop APIs, camera, rich text, and native controls. Results and errors appear inline. Filesystem demos create and recycle test data.

`bun run kitchen-sink:prepare /absolute/path/to/KitchenSinkCheck` packs the SDK and creates a separate copied consumer for integration testing. It preserves that consumer's generated identity/configuration rather than changing the checked-in app.

## [Smaller applications](https://legend.so/spark/examples/#smaller-applications)

Create a focused app with npm:

```sh
npm create @legendapp/spark MyNotes -- --example notes-lite
npm create @legendapp/spark MyMusic -- --example music-lite
npm create @legendapp/spark MyDiff -- --example diff-lite
npm create @legendapp/spark MyEditor -- --example document-editor
```

Then run the generated app, for example:

```sh
cd MyNotes
npm run macos
```

For local SDK development, [prepare the source SDK](https://legend.so/spark/getting-started/#contributing-build-spark-from-source) and run `bun run spark create /absolute/path/to/MyNotes --example notes-lite` from its checkout.

Notes Lite covers local notes, search, import/export, recovery, and session restoration. Music Lite covers playback/queue ownership. Diff Lite covers text comparison. Document Editor covers file operations, menus, document requests, and desktop lifecycle. These examples are distinct from the full Legend Apps products.

The [helper example](https://github.com/LegendApp/legend-spark/tree/main/examples/sidecar) demonstrates an app-supplied executable without a Node runtime in Hermes. The universal Settings starter uses native controls plus platform adapters.

## [Source checks](https://legend.so/spark/examples/#source-checks)

From the SDK checkout:

```sh
bun run typecheck
bun run test
bun run test:templates
```

`bun run test` uses Vitest, not Bun's test runner. Source checks cover APIs, lifetimes, and tooling. Template checks create real apps; packed consumer checks verify distributed dependencies and types.

## [Native and platform checks](https://legend.so/spark/examples/#native-and-platform-checks)

Native suites need their toolchains and disposable consumer projects. Read prerequisites before running them. Relevant commands include:

| Command | Purpose |
| --- | --- |
| `bun run test:native` | Native API probes |
| `bun run test:ui` | Packed native UI consumer |
| `bun run test:platform --platform <target>` | Shared contract catalog on a target |
| `bun run test:windows` | Windows Runner → Fast Refresh → added module → custom build |
| `bun run test:windows:prepare` | Generation/bundles without Windows native execution |
| `bun run test:runtimes:all` | Runner/dev/release background runtimes and pruning |
| `bun run test:universal` / `bun run test:universal:dev` | Universal generation/bundles and shared sessions |
| `bun run test:add-desktop` | Existing Expo app preservation/composition |

Run your app on each target OS and architecture to check native behavior as well as generation and bundling.

See the [platform testing guide](https://github.com/LegendApp/legend-spark/blob/main/docs/platform-testing.md), [manual testing checklist](https://github.com/LegendApp/legend-spark/blob/main/docs/desktop-manual-acceptance.md), and [platform limits](https://legend.so/spark/limitations/).

[View Markdown](https://legend.so/spark/examples.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Examples+and+validation&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fexamples%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Files and dialogs

Explicit dialog results, native paths, byte streams, watches, and scans.

Source: https://legend.so/spark/files/

## [Dialogs](https://legend.so/spark/files/#dialogs)

`@legendapp/spark/dialogs` contains open/save panels, `showMessage`, and `confirm`. File panels use `defaultPath` and labeled extension filters:

```ts
import { openFileDialog } from '@legendapp/spark/dialogs';
import { readText } from '@legendapp/spark/files';

const result = await openFileDialog({
  windowId: 'main',
  selection: 'files',
  multiple: false,
  defaultPath: '/absolute/path/to/documents',
  filters: [{ name: 'Text documents', extensions: ['txt', 'md'] }],
});
if (!result.canceled) {
  const text = await readText(result.paths[0]);
  console.log(text);
}
```

An owner is optional; a supplied `windowId` must identify a live window. Open returns `{ canceled: true }` or `{ canceled: false, paths }`. Save returns the same cancellation discriminant with one `path`; it can accept `defaultName`. Extensions omit dots; MIME types/UTIs are unsupported. Windows displays labeled groups; macOS combines extensions and ignores group labels. Mixed file/directory selection is explicitly macOS-specific.

Message buttons have stable IDs and labels. `showMessage` returns `buttonId` (null on host dismissal), and includes `checked` only when a checkbox was supplied. `confirm` returns a boolean. Missing modules, bad options, and native failures are errors rather than fabricated cancellation.

## [Native file IO](https://legend.so/spark/files/#native-file-io)

`@legendapp/spark/files` owns asynchronous desktop operations. Paths are absolute native paths or local `file://` URLs decoded once. Nonlocal file URLs, query strings, and fragments reject. Bytes use `Uint8Array`.

Use `getDirectory('data')` for project-scoped storage, `list` for immediate children, `stat` for metadata, `readText`/`writeText` for UTF-8, and `readBytes`/`writeBytes` for binary content. `stat` describes a symlink itself; invalid UTF-8 and permission failures reject.

`copy(source, destination, { overwrite? })` and `move` reject existing destinations by default. Explicit overwrite replaces them. Directory copy is recursive; cross-volume move may copy then delete. Neither is a transaction across multiple files.

Whole-file writes replace atomically on supported backends. `writeTextIfUnchanged` compares observed text and returns `{ written: false }` on conflict; it is not a cross-process compare-and-swap. `remove` defaults to nonrecursive removal; missing paths succeed. `trash` rejects if recycling is unavailable and never falls back to permanent deletion. `revealInFileManager` is distinct from `/links` opening a file in its associated application.

## [Bounded streams and handles](https://legend.so/spark/files/#bounded-streams-and-handles)

```ts
import { getDirectory, readChunks } from '@legendapp/spark/files';

const path = `${await getDirectory('data')}/large.bin`;
for await (const bytes of readChunks(path)) {
  console.log(bytes.byteLength);
}
```

`readChunks`/`writeChunks` avoid loading an entire file. Iteration closes ownership on completion, error, cancellation, or an early loop exit. `openFile` exposes positional read/write, `flush`, and `close`. Streaming/positional writes can be partial; inspect the [streaming contract](https://github.com/LegendApp/legend-spark/blob/main/docs/file-streams.md).

Close stops accepting new work, joins pending cleanup, and permits retry after native cleanup failure. File cleanup errors can expose retained handles rather than losing ownership.

## [Watching and scanning](https://legend.so/spark/files/#watching-and-scanning)

`watch(path, listener, { recursive })` resolves an async registration. Notifications invalidate cached data; re-read the path. They can coalesce and do not form an exact add/delete journal. Recursive watches require a directory. Await removal.

`scanFiles(paths, options)` is operation-scoped and currently macOS-only. Batches/progress belong to that invocation; concurrent scans do not share singleton callbacks. Results include totals and partial traversal errors. Abort stops between filesystem operations and rejects with `E_ABORTED` after native work stops; a pending OS call is not interrupted. Check `getFileScanAvailability()` when presenting this feature.

All file helpers, scanning, and watching share `/files`. See [the complete file guide](https://github.com/LegendApp/legend-spark/blob/main/docs/files.md).

[View Markdown](https://legend.so/spark/files.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Files+and+dialogs&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Ffiles%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Getting started

Create a macOS app from npm, edit it with Fast Refresh, and build a standalone app.

Source: https://legend.so/spark/getting-started/

## [Prerequisites](https://legend.so/spark/getting-started/#prerequisites)

Use macOS **14 or newer** on **Apple Silicon** with Node **24.19.0 or newer**.

Creating an app and running it with Spark Runner does not require Xcode or CocoaPods. You need those tools when compiling a standalone app or a custom native development build.

## [Create an app](https://legend.so/spark/getting-started/#create-an-app)

```bash
npm create @legendapp/spark@next MyApp
```

The creator installs the app's dependencies, including the `spark` CLI. Commit the generated lockfile and `spark-packages/` archives so other machines can reinstall the same dependencies.

### [Choose a release](https://legend.so/spark/getting-started/#choose-a-release)

The creator uses its own bundled Spark release by default. Pass `--latest` for the current stable release or `--spark-version <version|tag>` for a specific release. If the selected release differs from the creator's version, it prints the exact matching creator command to run.

## [Run and edit](https://legend.so/spark/getting-started/#run-and-edit)

Move into the app and start it:

```sh
cd MyApp
```

```bash
npm run macos
```

The first launch downloads and verifies the matching macOS ARM64 Spark Runner. Later sessions reuse it. Expo CLI starts Metro and opens your app.

Open `App.tsx`, change the `Hello, Legend Spark` text, and save. JavaScript changes appear through Fast Refresh. Extra native dependencies or native configuration can require a [custom development build](https://legend.so/spark/development/#native-changes).

The generated app includes these scripts:

| Command | Purpose |
| --- | --- |
| `npm run macos`, `npm run dev`, `npm start` | Start the development session |
| `npm run build` | Compile a standalone macOS app |
| `npm run package` | Sign and notarize a distribution archive |
| `npm run doctor` | Check native build prerequisites and dependency pins |

## [Build a standalone app](https://legend.so/spark/getting-started/#build-a-standalone-app)

Install full Xcode, complete its first-launch setup, and select it in the Xcode command-line tools settings. Install CocoaPods and ensure `pod` is on your PATH. Command Line Tools alone cannot compile the app.

Stop the development session with Ctrl+C, then run:

```bash
npm run build
```

```sh
npx --no-install spark open
```

The build prints the location of an ad-hoc-signed `.app` with embedded JavaScript. It runs without Metro. `spark open` launches the last standalone build.

To prepare a signed, notarized archive with your Developer ID credentials, use `npm run package`. See [packaging and updates](https://legend.so/spark/distribution/) for signing setup and distribution.

## [Contributing: build Spark from source](https://legend.so/spark/getting-started/#contributing-build-spark-from-source)

For framework development, install Git and the checkout's pinned Bun **1.3.14**, in addition to Node and the native build tools above:

```sh
git clone https://github.com/LegendApp/legend-spark.git
cd legend-spark
bun install --frozen-lockfile
bun run spark sdk pack
bun run spark sdk build-runner
bun run spark create /absolute/path/to/MyApp
cd /absolute/path/to/MyApp
npm run macos
```

`sdk pack` creates local SDK archives and registers their manifest. `sdk build-runner` compiles and registers a matching Runner. To reuse an existing matching Runner, run `bun run spark sdk register /absolute/path/to/SparkRunner.app` from the checkout instead of building it. Keep the registered Runner app at that path.

For Windows 11 source development, follow the [Windows guide](https://github.com/LegendApp/legend-spark/blob/main/docs/windows-slice.md). Use `--platform windows` with `sdk pack`, `sdk build-runner`, and `create`, then run the generated `windows` script. Windows native compilation and runtime behavior still need validation; production distribution is unsupported.

See [SDK iteration](https://legend.so/spark/development/#sdk-iteration-and-diagnostics) for refreshing local apps after source changes.

[View Markdown](https://legend.so/spark/getting-started.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Getting+started&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fgetting-started%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Legend Spark

React Native on desktop.

Source: https://legend.so/spark/

![](https://legend.so/assets/legend-spark.png)Legend SparkExperimental — not for production

## React Native on desktop.

Spark gives React Native apps real windows, menus, dialogs, and files on the Mac. Start in a prebuilt runner with Fast Refresh, then ship a standalone `.app`.

[Get started](https://legend.so/spark/overview/) [GitHub](https://github.com/LegendApp/legend-spark)

App.tsx

```
import { AppRegistry, Text } from 'react-native'
import { createMenu } from '@legendapp/spark/menus'
import { openWindow } from '@legendapp/spark/windows'

AppRegistry.registerComponent('Inspector', () => () => <Text>Inspector</Text>)

createMenu({
  id: 'editor',
  items: [{
    type: 'submenu', id: 'view', label: 'View',
    items: [{ type: 'action', id: 'inspector',
              label: 'Show Inspector', shortcut: 'CmdOrCtrl+I' }],
  }],
  onAction: ({ itemId }) => {
    if (itemId === 'inspector') {
      // A second native window, rendering a React Native root
      openWindow({
        id: 'inspector',
        component: 'Inspector',
        title: 'Inspector',
        size: { width: 480, height: 640 },
      })
    }
  },
}).catch(console.error)
```

Spark 0.0.1 API · [see Getting started](https://legend.so/spark/overview/)

## One package, the whole desktop.

Import each capability from `@legendapp/spark`. Typed and async, with explicit ownership and cleanup.

[All capabilities](https://legend.so/spark/reference/)

**Windows`/windows`**

Named windows, displays, geometry, close guards, and native macOS chrome.

**Menus`/menus`**

The app menu bar, context menus, tray items, and Dock menus.

**Shortcuts`/shortcuts`**

Local and global accelerators, with command routing.

**Files and dialogs`/files`**

Open and save panels, atomic writes, streams, watching, and Trash.

**Settings`/settings`**

JSON settings, Legend State persistence, and secure storage.

**Updates`/updates`**

Native whole-app updates for the apps you ship.

## One project, three ways to run it.

Move from a shared runner to your own build only when the project needs it. Spark checks native requirements before loading JavaScript.

1.  01 / SPARK RUNNER
    
    ### Start without Xcode
    
    A prebuilt development app. Create a project, run it, and edit App.tsx with Fast Refresh.
    
    ```
    $ npm create @legendapp/spark MyApp$ cd MyApp$ npm run macos
    ```
    
2.  02 / CUSTOM DEVELOPMENT BUILD
    
    ### Add native when you need it
    
    Extra native modules or helper executables need an app-specific build. JavaScript changes still use Fast Refresh.
    
    ```
    $ npx --no-install spark build --dev --platform macos
    ```
    
3.  03 / STANDALONE APP
    
    ### Ship a real Mac app
    
    Build a .app with embedded JavaScript, then sign and notarize it with your own Developer ID.
    
    ```
    $ npm run build$ npm run package
    ```
    

## No browser inside.

React Native all the way downScreens are React Native views and your JavaScript runs in Hermes. Node runs the tooling and is never bundled into the app.

The Expo workflow you knowExpo Desktop generates the native host and Expo CLI owns Metro, logs, and reload. Spark adds desktop APIs and runtime selection.

![Layer diagram: Legend Spark on top of Expo Desktop, which builds on Expo, which builds on React Native](https://legend.so/assets/spark/spark-expo-desktop-react-native-stack.webp)

## Where it stands

macOS 14+ on Apple Silicon is the primary target. Intel Mac builds and Windows development still need native validation.

Spark 0.0.1 downloads a matching macOS Apple Silicon Runner on first launch. Test signed distribution with your own app and credentials.

[Status and limitations](https://legend.so/spark/limitations/)


---

# Desktop and shared integrations

Clipboard, notifications, system APIs, processes, databases, WebView, audio, auth, camera, and rich text.

Source: https://legend.so/spark/integrations/

## [Clipboard, links, and drag/drop](https://legend.so/spark/integrations/#clipboard-links-and-dragdrop)

`/clipboard` retains selected Expo-shaped `getStringAsync`, `setStringAsync`, and `hasStringAsync` methods. `setStringAsync` returns the actual boolean write result. Rich `readClipboard`/`writeClipboard` use owned payloads; file lists are separate from text/image alternatives. Raw format identifiers come from `getClipboardFormats`.

`/links` supplies `openURL`, `canOpenURL`, `getInitialURL`, and `addEventListener('url', listener)`. Desktop `openPath` opens a native file with its associated application. File/URL launch replay and recent history live under [/app/documents](https://legend.so/spark/documents/).

Use [Drag and drop](https://legend.so/spark/drag-drop/) for files, text, URLs, and custom MIME data.

## [Local notifications](https://legend.so/spark/integrations/#local-notifications)

```ts
import { requestNotificationPermission, showNotification } from '@legendapp/spark/notifications';

const permission = await requestNotificationPermission();
if (permission.granted) {
  await showNotification({
    id: 'import-complete',
    content: {
      title: 'Import complete',
      body: 'Your files are ready.',
      sound: 'message',
      actions: [{ id: 'view', label: 'View files' }],
    },
  });
}
```

Request permission from an explicit user action. Windows reads OS settings without an in-app permission prompt. The OS may accept a notification without displaying it.

`showNotification` is immediate; `scheduleNotification` adds `{ type: 'delay', delaySeconds }`. Content supports silent/default sound or portable `message`, `mail`, `reminder`, `call`, and `error` tones. One to four action buttons report their IDs through responses. macOS banners show the first two; Notification Center can show the rest.

`onNotificationResponse` installs live delivery and drains retained launch responses. Await setup; the returned subscription removes synchronously. Responses identify the notification and `open`, `dismiss`, or a custom action. New subscriptions can replay retained responses.

`cancelNotification`/`cancelAllNotifications` remove pending delivery. `dismissNotification`/`dismissAllNotifications` remove already delivered notifications. List APIs distinguish those sets. These are local notifications, not push tokens or background tasks.

## [System integration](https://legend.so/spark/integrations/#system-integration)

`/system` supplies system information, events, login startup, badges, attention, sleep prevention, and explicit Dock/taskbar menu registration. Events are invalidations: query `getSystemInfo()` again for current values. `requestAttention` and `preventSleep` return owned async registrations. Remove them when the application no longer needs the effect. Unsupported options reject; menu trees follow [surface restrictions](https://legend.so/spark/menus/).

## [Processes and helper executables](https://legend.so/spark/integrations/#processes-and-helper-executables)

```ts
import { runCommand } from '@legendapp/spark/processes';

const result = await runCommand({
  target: { type: 'command', name: 'git' },
  args: ['--version'],
  timeoutMs: 10_000,
});
if (result.exit.type === 'exited' && result.exit.code === 0) {
  console.log(new TextDecoder().decode(result.stdout));
}
```

Targets discriminate PATH commands, absolute executables, and configured helper references. Arguments bypass a shell. Input/output use strings or byte arrays; output callbacks carry `Uint8Array` with arbitrary chunk boundaries. Results retain stdout/stderr, exit/termination, timeout, abort, and truncation. Nonzero exit is a result; an operational failure rejects.

`spawn` returns an owned handle with write, closeInput, terminate, and exited. Await writes for backpressure. Termination joins concurrent calls and waits for the process tree/output streams. It can be retried after native cleanup failure.

Helpers are target-specific executables supplied by the app under `desktop.config.json.helpers`. Spark packages their assets/dependencies but does not compile them or supply Node. Helpers require a custom binary. Keep shared process ownership in an application service, rather than each window. They are not persistent OS services; abrupt macOS app death does not guarantee cleanup. See [helper processes](https://github.com/LegendApp/legend-spark/blob/main/docs/sidecars.md).

## [SQLite](https://legend.so/spark/integrations/#sqlite)

```ts
import { openDatabase } from '@legendapp/spark/sqlite';

const database = await openDatabase('notes.sqlite');
try {
  await database.transaction(async tx => {
    await tx.run('CREATE TABLE IF NOT EXISTS notes (title TEXT NOT NULL)');
    await tx.run('INSERT INTO notes (title) VALUES (?)', ['Hello']);
  });
  const note = await database.getFirst('SELECT title FROM notes LIMIT 1');
  console.log(note);
} finally {
  await database.close();
}
```

The project-scoped filename must be a simple `.sqlite` name. Spark owns `Database`, `SqlExecutor`, row/value types, and run results; it does not expose OP-SQLite's raw DB. Use `tx` inside transactions. Success commits, rejection rolls back; direct connection operations during a transaction and nested transactions reject.

Blobs are `Uint8Array`; SQL NULL is null. Default integer mode rejects unsafe integer reads. `{ integers: 'text' }` permits out-of-range values as text, but an already rounded native number cannot recover exact digits. Use SQL `CAST(column AS TEXT)` when exact large integers matter. Close waits for accepted work and blocks new work.

## [WebView](https://legend.so/spark/integrations/#webview)

`/webview` exports an owned `WebView` component, props, events, and ref subset. Source is a URI with optional headers **or** inline HTML with optional `baseUri`. Normal React Native view props are supported; document content comes from source, not children.

Refs request reload/back/forward, string messaging, or script injection; they do not promise navigation completion. Load/HTTP errors and navigation/message payloads are typed. Navigation interception is synchronous where emitted and is not a network security boundary. Consult platform limits for origins, headers, scripts, cookies, and popup behavior; this is not the whole `react-native-webview` API.

## [Audio and browser authentication](https://legend.so/spark/integrations/#audio-and-browser-authentication)

`createAudioPlayer(source, options?)` waits for readiness and returns async play/pause/seek/volume/metadata/status commands. Positions use seconds; creation supports timeout/abort. `useAudioPlayer` returns loading/ready/error state, with a player only when ready. Removal owns disposal; hooks handle replacement and late completion.

`createMediaSession` lets desktop/web publish controls for an external engine. One session owns system controls; stale handles cannot clear a newer session. Command callbacks request operations rather than confirming playback. Standalone external-engine sessions are unsupported on mobile, where Expo Audio owns its player controls. Browser playback may require a gesture. See [audio](https://github.com/LegendApp/legend-spark/blob/main/docs/audio.md).

`/auth-session` provides prepared state/redirect sessions, browser callback transport, and explicit dismissal. Success, cancellation, dismissal, and timeout remain distinct outcomes. Provider SDKs, token exchange, and credential policy belong to the app. This is not complete `expo-auth-session` compatibility. See [authentication](https://github.com/LegendApp/legend-spark/blob/main/docs/auth-session.md).

## [Camera](https://legend.so/spark/integrations/#camera)

`@legendapp/spark/camera` exposes VisionCamera with upstream semantics and automatic native compatibility patches. See [Camera](https://legend.so/spark/camera/) for a preview example, permissions, and platform limits.

## [Rich text](https://legend.so/spark/integrations/#rich-text)

Use `@legendapp/spark/markdown` and `@legendapp/spark/html` to read and edit rich text. Spark installs and patches both Enriched backends. See [Rich text](https://legend.so/spark/rich-text/) for components, formatting, and build settings.

## [Independent Hermes runtimes](https://legend.so/spark/integrations/#independent-hermes-runtimes)

Use `@react-native-runtimes/core` directly for background work in independent Hermes heaps inside the application process. Serialization, cleanup, native-module limits, and production reachability follow its integration guide. It is not Node or a persistent worker service. See [Runtimes](https://github.com/LegendApp/legend-spark/blob/main/docs/runtimes.md).

[View Markdown](https://legend.so/spark/integrations.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Desktop+and+shared+integrations&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fintegrations%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Keyboard shortcuts

Local and global accelerators, command routing, customizable bindings, and keyboard events.

Source: https://legend.so/spark/keyboard-shortcuts/

Choose a shortcut surface according to its owner:

| Import | Purpose |
| --- | --- |
| `@legendapp/spark/shortcuts` | Shortcuts in the focused application, optionally scoped to a window. |
| `@legendapp/spark/global-shortcuts` | System-wide shortcuts, including when the app is unfocused. |
| `@legendapp/spark/shortcuts/commands` | Named commands, routing, capture controls, and persisted bindings. |
| `@legendapp/spark/shortcuts/keyboard` | Low-level observation of keydown and keyup. |

Local and global shortcuts have macOS and Windows backends. Command routing and low-level keyboard events require macOS. Test key layouts and focus changes on your target host.

## [Accelerator strings](https://legend.so/spark/keyboard-shortcuts/#accelerator-strings)

Menus and registered shortcuts share named accelerators such as `CmdOrCtrl+S`, `Alt+Left`, `Shift+Up`, and `F5`. `CmdOrCtrl` means Command on macOS and Control on Windows. Character shortcuts require a modifier on these surfaces. Use `Plus` for the plus key, for example `CmdOrCtrl+Plus`.

Commands additionally allow unmodified character keys, `Home`, `End`, `PageUp`, `PageDown`, `MediaPlayPause`, `MediaNext`, and `MediaPrevious`, with explicit `Fn` and `CapsLock` modifiers. Other shortcut surfaces reject those extensions. Bindings use named strings; physical codes belong to low-level events.

## [Local and global registrations](https://legend.so/spark/keyboard-shortcuts/#local-and-global-registrations)

```ts
import { registerShortcut } from '@legendapp/spark/shortcuts';
import { registerGlobalShortcut } from '@legendapp/spark/global-shortcuts';

const local = await registerShortcut('CmdOrCtrl+S', () => {
  console.log('Save requested');
}, { windowId: 'main' });

const global = await registerGlobalShortcut('CmdOrCtrl+Shift+K', () => {
  console.log('Global shortcut requested');
});

// When the owner ends:
await local.remove();
await global.remove();
```

Local shortcuts are consumed before insertion into text fields. Options are `windowId` and `repeat`; repeat defaults to `false`. Global options contain only `repeat`. Windows supports global repeat; requesting `repeat: true` on macOS rejects `E_UNSUPPORTED_OPTION`. Conflicting or reserved global shortcuts reject with `E_BUSY`.

`getShortcutAvailability()` and `getGlobalShortcutAvailability()` report host/module availability from their respective imports. Registration failures reject. Await removal and retain a failed handle for cleanup retry; removal stops JavaScript callbacks immediately.

To display a shortcut in an application menu, use the menu item's `shortcut` field; see [menus](https://legend.so/spark/menus/).

## [Named commands and routing](https://legend.so/spark/keyboard-shortcuts/#named-commands-and-routing)

```ts
import { createHotkeyRouter } from '@legendapp/spark/shortcuts/commands';

const definitions = [
  { id: 'save', title: 'Save', defaultBindings: ['CmdOrCtrl+S'] },
] as const;
const router = createHotkeyRouter();
const registration = await router.register({
  definitions,
  scope: { kind: 'window', windowId: 'editor' },
  handlers: { save: () => { console.log('Save requested'); } },
});

await registration.setEnabled(false);
await registration.setEnabled(true);
const suspension = await router.suspend({ kind: 'window', windowId: 'editor' });
await suspension.remove();
await registration.remove();
```

`defaultBindings` and per-command `bindings` overrides are arrays. An empty override disables a command; an omitted override uses its defaults. Registrations snapshot their configuration. Higher priority runs first: defaults are 100 for window scope and 0 for application scope. Equal priorities favor the newest registration.

A synchronous handler returning `false` lets dispatch continue to the next Spark handler. Other synchronous results stop routing. Native consumption is decided before JavaScript runs, so returning `false` cannot send the key back to AppKit. Launch asynchronous work explicitly and handle its errors. Only definitions with `repeat: true` run on repeated keydowns; `allowExtraModifiers` opts into subset modifier matching.

The event's window ID determines ownership. Window changes reset pressed keys; `setActiveWindowId` can reset them on focus changes too. Await `setEnabled(boolean)` before relying on the new state.

`router.suspend(scope?)` returns an async registration; await its `remove()` to resume. Window suspension also blocks application handlers in that window. The final command registration releases shared native observers and consumption rules. Setup, updates, and cleanup reject on failure, and cleanup can be retried on the same handle.

### [React ownership and capture](https://legend.so/spark/keyboard-shortcuts/#react-ownership-and-capture)

`useRoutedHotkeys({ router, definitions, bindings, handlers, ... })` manages registration for a component. It returns loading/ready/error state and keeps handlers current. Use `onError` for setup/update failures and `onCleanupError(error, registration)` to retry failed cleanup.

`useHotkeySuspension({ active, router, scope?, onError?, onCleanupError? })` owns suspension for an effect lifetime. Both hooks share the commands import.

`HotkeyCapture` takes `value`, `onChange`, and optional capture/error callbacks. It owns native capture only while recording, commits a named accelerator on key release, and cancels on Escape. Capture temporarily consumes monitored keys. `HotkeyBindingsSettingsContent` and `HotkeyBindingsSettingsPage` edit arrays of bindings through `definitions`, `values`, and `onChange(id, values)`; `maxBindingsPerCommand` can limit the number per command.

## [Persisting bindings](https://legend.so/spark/keyboard-shortcuts/#persisting-bindings)

`createHotkeyStore({ definitions, path, maxBindingsPerCommand?, storage?, debounceMs? })` comes from the commands import. Await the factory before using its Legend State `value$`, `error$`, `flush()`, and `close()`. The parent directory must exist; follow [observable persistence](https://legend.so/spark/settings/#observable-persistence).

The file format is:

```json
{ "version": 1, "bindings": { "save": ["CmdOrCtrl+S"] } }
```

Serialization preserves portable `CmdOrCtrl`. Missing commands acquire defaults, removed IDs are discarded, and empty arrays stay empty. Invalid versions, scalar bindings, or malformed accelerators reject and preserve existing file bytes. A nonnegative integer `maxBindingsPerCommand` keeps the first N bindings. Conflicts remain visible through `getHotkeyBindingConflicts` and the settings UI rather than silently replacing another command.

Await `flush()` to persist the current snapshot and `close()` when its owner ends. The store persists bindings; supply them to a router registration or `useRoutedHotkeys` to apply them.

## [Low-level keyboard events](https://legend.so/spark/keyboard-shortcuts/#low-level-keyboard-events)

```ts
import { addKeyboardListener } from '@legendapp/spark/shortcuts/keyboard';

const listener = await addKeyboardListener('down', event => {
  console.log(event.key, event.keyCode, event.consumed);
}, { windowIds: ['editor'] });
await listener.remove();
```

Use `'down'` or `'up'`. Events include `windowId` (or `null`), a layout-derived unmodified `key`, physical `keyCode`, a numeric `modifiers` mask, and `repeated`, `consumed`, and `captured` booleans. Window filtering applies to both event kinds. `KeyCodes`, `KeyText`, `hasModifier`, and `createModifierMask` are exported from the same path.

Callbacks observe the native decision; returning a value cannot consume a key. Check `getKeyboardAvailability()` before registering. Await removal when the owner ends; retry the same handle if cleanup fails.

See the [commands source guide](https://github.com/LegendApp/legend-spark/blob/main/docs/commands.md) for routing and persistence details.

[View Markdown](https://legend.so/spark/keyboard-shortcuts.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Keyboard+shortcuts&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fkeyboard-shortcuts%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Status and limitations

Platform support, feature restrictions, and distribution limits.

Source: https://legend.so/spark/limitations/

Spark 0.0.1 primarily targets macOS 14+ on Apple Silicon.

## [What works where](https://legend.so/spark/limitations/#what-works-where)

| Target | Available workflow | Limits |
| --- | --- | --- |
| macOS 14+, Apple Silicon | Spark Runner, custom development builds, standalone apps, signing/notarization, and whole-app updates | Check feature availability in your app |
| macOS 14+, Intel x64 | Source tooling targets builds, Runner registration/downloads, and packaging | Native compilation, runtime behavior, and signed distribution still need validation; the published Runner is ARM64 only |
| Windows 11, x64/ARM64 | Local source Runner and custom development builds | Native compilation and runtime behavior still need validation; no hosted Runner or production packaging workflow |
| iOS / Android / web | Expo workflows and selected shared API/UI adapters | Desktop windows, files, menus, and processes are not universal capabilities |
| Linux / Mac App Store | No supported workflow | Unsupported |

## [Feature restrictions](https://legend.so/spark/limitations/#feature-restrictions)

-   Common UI controls use different platform implementations. Windows `SegmentedControl` is unsupported.
-   Search, sidebar, split-view, settings-window composition, and SF Symbols are macOS capabilities. `GlassView`'s native effect requires macOS 26.
-   Command routing and low-level keyboard APIs require macOS. The native Codex supervisor is also macOS-only.
-   Standalone media sessions for an external playback engine are unsupported on mobile.
-   Secure storage is unavailable on web.

Check feature-specific availability and permissions before offering a capability. See [native UI](https://legend.so/spark/ui/), [integrations](https://legend.so/spark/integrations/), and [known Windows issues](https://github.com/LegendApp/legend-spark/blob/main/docs/windows-issues.md) for details.

## [Standalone apps and updates](https://legend.so/spark/limitations/#standalone-apps-and-updates)

macOS build, Developer ID signing, notarization, and whole-app update tooling are available. Test installation, startup, update/relaunch, and rejection of older builds with your signed app and update feed. See [packaging and updates](https://legend.so/spark/distribution/).

Windows production builds, signing, and MSIX packaging are unsupported.

## [Architecture limits](https://legend.so/spark/limitations/#architecture-limits)

-   Application JavaScript runs in Hermes. Node built-ins and Electron main-process APIs are unavailable.
-   Helpers are app-supplied, target-specific executables requiring a custom binary. They are not persistent OS services.
-   Spark SQLite/WebView/audio/UI contracts expose supported subsets, not complete backend APIs.
-   Expo Router integration, declarative route-based window navigation, and a broad universal UI catalog are not supported. `createWindowsNavigator` provides named-window component coordination.
-   Frame → Spark migration requires rebuilding matching native runtimes. Old prototype data, credentials, and OS registrations are not automatically migrated. See [migration](https://legend.so/spark/migration/).

[View Markdown](https://legend.so/spark/limitations.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Status+and+limitations&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Flimitations%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Menus and shortcuts

Owned native menus, portable accelerators, command routing, and tray items.

Source: https://legend.so/spark/menus/

Create menus with typed items and stable IDs. Each surface supports the item types listed below.

## [Application menus](https://legend.so/spark/menus/#application-menus)

```ts
import { createMenu } from '@legendapp/spark/menus';

const menu = await createMenu({
  id: 'editor',
  items: [{
    type: 'submenu', id: 'file', label: 'File', target: { menu: 'file' },
    items: [{ type: 'action', id: 'open', label: 'Open...', shortcut: 'CmdOrCtrl+O' }],
  }],
  onAction: event => { console.log(event.itemId); },
});
await menu.update({ items: [] });
await menu.remove();
```

Top-level items are submenus. Contributions merge by IDs, never translated labels. Later owners take precedence; removal restores earlier contributions/native items. Updates replace the owner's contribution. Native publication is acknowledged before create/update resolves. Failed publication retains the previous state; failed removal retains retryable ownership.

Targets bind native root menus, IDs, or macOS semantic roles. Role items dispatch through native responders; ordinary actions targeting roles dispatch to JavaScript. `useMenu` owns the same lifetime and exposes loading/ready/error state plus cleanup-error callbacks. Keep unchanged item structure stable; callback changes do not require republishing.

## [Checked items](https://legend.so/spark/menus/#checked-items)

Use `type: 'checkbox'` with a boolean `checked` for selectable state. The shared contract also defines `radio`, but the surfaces below reject it with `E_UNSUPPORTED_OPTION`; `/menus` excludes it from its exported `MenuItem` type.

## [Surface support](https://legend.so/spark/menus/#surface-support)

| Surface | Supported item shapes | Limits |
| --- | --- | --- |
| App menu | Recursive actions, checkboxes, separators, submenus; macOS roles | Windows role/icon requests reject |
| Context menu | Flat actions, checkboxes, separators | No submenus, roles, icons, shortcuts, or sliders |
| Tray menu | Actions, checkboxes, separators, recursive submenus | No roles, icons, shortcuts, or sliders |
| macOS toolbar popup | Actions, checkboxes, separators, numeric sliders | No submenus, roles, or shortcuts |
| macOS Dock | Recursive actions, checkboxes, separators, submenus | Restricted presentation/targeting fields |
| Windows taskbar | Flat actions and checkboxes | Disabled entries omitted; restricted fields |

`showContextMenu({ windowId, position, items })` requires an explicit owner. Position is logical top-left **content** coordinates, rather than display/outer-frame coordinates. Cancellation returns `{ canceled: true }`; selection returns `{ canceled: false, itemId }`. A concurrent popup rejects `E_BUSY`.

`createTray` returns a handle with `update` and async `remove`. Images distinguish SF Symbol names from local files; symbol images are macOS-specific. Dock/taskbar menu registrations live in `/system` and have separate native availability.

## [Shortcuts](https://legend.so/spark/menus/#shortcuts)

Set an item's `shortcut`, such as `CmdOrCtrl+O`, to show and register its accelerator. Use [Keyboard shortcuts](https://legend.so/spark/keyboard-shortcuts/) for local/global registrations, named commands, customizable bindings, and raw key events.

See [menu details](https://github.com/LegendApp/legend-spark/blob/main/docs/menus.md) for targeting and ownership.

[View Markdown](https://legend.so/spark/menus.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Menus+and+shortcuts&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fmenus%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Upgrading Spark

Update Spark, review migrations, and move older prototypes to the current APIs.

Source: https://legend.so/spark/migration/

## [Upgrade an app](https://legend.so/spark/migration/#upgrade-an-app)

Commit your app and lockfile first. Record the old version from `.spark/version`, or the installed Spark package if that file is missing.

```sh
npx --no-install spark upgrade --dry-run
npx --no-install spark upgrade
npx --no-install spark doctor
```

The dry run lists dependency pins, file changes, and manual steps. Upgrade installs matching SDK archives and applies migrations in version order. It keeps your package manager and updates its settings and overrides. Keep `spark-packages/` and those settings in version control; do not replace patched archives with upstream packages.

Read `node_modules/@legendapp/spark/skills/spark/UPGRADING.md` from the newly installed package for every version between the old and new releases. Complete `.spark/upgrade-notes.md`, then run your app's typecheck and tests. Rebuild custom development runtimes after native changes. If installation fails, fix the cause and retry; partial edits may remain.

### [Move from a preview to 0.0.1](https://legend.so/spark/migration/#move-from-a-preview-to-001)

`spark upgrade` stays on the installed release's channel: previews use `next`, stable releases use `latest`. To switch an npm app to 0.0.1 after it is published:

```sh
npm install --save-exact @legendapp/spark@0.0.1
```

Use your package manager's equivalent install command, then run the upgrade and doctor commands above. Preserve the old version record until migration finishes. Review the installed notes and test your app. For a new release with pnpm 12, see the [release-age option](https://legend.so/spark/getting-started/#install-just-after-a-release).

### [Changes since next.5](https://legend.so/spark/migration/#changes-since-next5)

-   next.6 repaired the creator package; existing apps need no source migration.
-   next.7 added creator release-selection flags. These apply when creating apps, not to `spark upgrade`.
-   Yarn PnP can run the creator; generated native apps use `node_modules`.
-   Dependency fixes preserve pnpm settings and patched Nitro peers, repair Enriched HTML web dependencies, and keep Fast Refresh working when imports are removed and re-added.

## [Older prototypes](https://legend.so/spark/migration/#older-prototypes)

Older prototypes need import and contract changes. Removed exports have no aliases. Rebuild matching native runtimes after updating.

## [Import changes](https://legend.so/spark/migration/#import-changes)

| Removed path | Current path |
| --- | --- |
| `/message-dialog` | `/dialogs` |
| `/windows/react`, `/windows/managed`, `/windows/controls` | `/windows` |
| `/app/exit` | `/app` |
| `/app/recent-documents` | `/app/documents` |
| `/files/scanner`, `/files/watchers`, general `/settings/paths` helpers | `/files` |
| `/shortcuts/commands/storage` | `/shortcuts/commands` |
| `/settings/window/options` | `/settings/window` |
| `/processes/commands` | `/processes` |
| `/drag-drop/views` | `/drag-drop` |
| `/ui/select-controls` | `/ui` |
| `/expo-metro`, `/universal` | `/metro` |

All paths use the `@legendapp/spark` prefix. The singleton `/global-shortcuts/hotkeys` interface was removed; use owned accelerator registrations or explicit keyboard APIs. Application-specific music drag payloads and chrome presets belong in app code.

## [Behavior changes to review](https://legend.so/spark/migration/#behavior-changes-to-review)

-   **Windows:** pass explicit IDs; use unified open options/results, display-relative outer-frame geometry, instance-bound listeners/guards, and grouped `macos` chrome. Animate through `setWindowBounds` in `/windows`.
-   **Documents/app:** use typed file/URL requests with bounded replay; quit/close approval belongs in async guards. Save before approving shutdown.
-   **Dialogs/files:** branch on cancellation discriminants; message buttons use IDs and checkbox state is optional. File dialogs use `defaultPath` and extension filters. Copy/move require explicit overwrite; file watches invalidate rather than report an exact change journal.
-   **Settings:** validate persisted values with decoders. Observable factories are async and expose readiness, `value$`, `error$`, flush and close. General paths/IO moved to files.
-   **Clipboard/secure storage:** use selected Expo-shaped methods; duplicate facades were removed. Clipboard string writes return a boolean, secure missing reads return null.
-   **Menus/system/tray:** use typed items appropriate to each surface and owned create/update/remove registrations. Unsupported item shapes reject before publication.
-   **Notifications/updates:** separate content/trigger and pending/delivered operations. Native update checking acknowledges initiation; typed events report later progress.
-   **Processes/audio/auth:** retain owned resource handles, explicit result states, byte IO, cleanup and supported cancellation. Audio hooks return loading/ready/error, not an immediate backend player.
-   **SQLite/WebView:** use Spark-owned database/component/ref types rather than raw OP-SQLite/WebView backend types.
-   **UI:** controlled `TextInput.value` is supported; `value`/`defaultValue` are exclusive. Select/SegmentedControl share controlled values. Split panes are named, Sidebar selection requires its callback, and glass/symbol components have explicit native limits.

Check feature availability on each target platform. Unknown options reject. Await async cleanup and retain failed handles for retry; a global clear-all operation is not a substitute for ownership.

## [Configuration and tooling](https://legend.so/spark/migration/#configuration-and-tooling)

Use Node 24.19.0+. Run `npx --no-install spark ...` in apps and `bun run spark ...` in the [source checkout](https://legend.so/spark/getting-started/#contributing-build-spark-from-source). Runner commands are `sdk build-runner`, `build --runner`, and `dev --runner-binary`. Expo's `dev --go` selects mobile Expo Go.

Author Spark-owned desktop settings in `desktop.config.json`, preserve `projectId`, and compose existing Expo projects through `/expo-config`, `/metro`, and `/native`. Review generated templates/wrappers when updating local consumers. Old Frame native identities/data are not automatically migrated.

See the [rename guide](https://github.com/LegendApp/legend-spark/blob/main/docs/legend-spark-migration.md) for more migration details.

[View Markdown](https://legend.so/spark/migration.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Upgrading+Spark&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fmigration%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Overview

How Legend Spark builds on React Native, Expo, and Expo Desktop, and how Spark Runner gets you developing.

Source: https://legend.so/spark/overview/

Build desktop apps with React Native screens, native windows, menus, dialogs, and files. Edit JavaScript with Fast Refresh.

Install `@legendapp/spark` for the APIs and `spark` CLI. Import features from paths such as `@legendapp/spark/files`.

## [How the pieces fit](https://legend.so/spark/overview/#how-the-pieces-fit)

![Layer diagram: Legend Spark on top of Expo Desktop, which builds on Expo, which builds on React Native](https://legend.so/assets/spark/spark-expo-desktop-react-native-stack.webp)

-   **[React Native](https://github.com/facebook/react-native)** renders native interfaces. Application JavaScript runs in Hermes.
-   **[Expo](https://github.com/expo/expo)** supplies mobile/web tooling and selected library backends.
-   **[Expo Desktop](https://github.com/shirakaba/expo-desktop)** creates projects and generates native desktop hosts.
-   **[Legend Spark](https://legend.so/spark/)** supplies desktop APIs, native compatibility checks, runtime selection, and build/packaging orchestration. Expo CLI owns Metro and the development terminal.

Node 24.19.0+ runs the tooling. Use npm, pnpm, Yarn, or Bun to manage dependencies. Neither Node nor Bun runs inside the app.

## [Spark Runner](https://legend.so/spark/overview/#spark-runner)

Spark Runner is a prebuilt desktop app that runs your JavaScript from Metro with Fast Refresh, so you can start developing without Xcode or compiling native code. The first launch downloads a matching Runner and later sessions reuse it. JavaScript changes never need a rebuild.

When your app adds native dependencies, helper executables, or native configuration such as URL/document associations, Spark asks for a [custom development build](https://legend.so/spark/development/#native-changes) instead. It works the same way, with your native code included.

## [Platform scope](https://legend.so/spark/overview/#platform-scope)

macOS 14+ on Apple Silicon is the primary target today. Windows and Intel Mac support are in progress; see [status and limitations](https://legend.so/spark/limitations/) for details.

Spark 0.0.1 targets Expo SDK 54, React Native 0.81, and Expo Desktop `1.0.0`.

## [Application architecture](https://legend.so/spark/overview/#application-architecture)

For Electron migrations, replace DOM/CSS screens with React Native screens and browser/main-process integrations with supported capabilities. Spark has no Electron compatibility layer. An optional [WebView](https://legend.so/spark/integrations/) can host selected web content.

[Helper processes](https://legend.so/spark/integrations/) run app-supplied executables. Independent background Hermes heaps use `@react-native-runtimes/core` directly; they remain inside the app process and end when it quits.

## [Explore](https://legend.so/spark/overview/#explore)

-   [Getting started](https://legend.so/spark/getting-started/): create, run, and build a macOS app from npm.
-   [Development](https://legend.so/spark/development/) and [configuration](https://legend.so/spark/configuration/): Spark Runner, custom development builds, Expo integration, and native changes.
-   [API guide](https://legend.so/spark/reference/): every public capability and shared contracts.
-   [Native UI](https://legend.so/spark/ui/), [AI execution](https://legend.so/spark/ai/), and [examples](https://legend.so/spark/examples/).
-   [Packaging and updates](https://legend.so/spark/distribution/) and [migration](https://legend.so/spark/migration/).

[LLM documentation index](https://legend.so/spark/llms.txt) · [Complete LLM documentation](https://legend.so/spark/llms-full.txt)

[View Markdown](https://legend.so/spark/overview.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Overview&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Foverview%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# API guide

Public capability imports, ownership, errors, and resource lifetimes.

Source: https://legend.so/spark/reference/

Import APIs and types from `@legendapp/spark/<feature>`. Use these public paths rather than internal packages.

## [Capability entry points](https://legend.so/spark/reference/#capability-entry-points)

| Public path | Responsibility | Guide |
| --- | --- | --- |
| `/app` | App context, events, activation, quit guards | [Documents and lifecycle](https://legend.so/spark/documents/) |
| `/app/documents` | File/URL requests, recent history, document controllers and reload watches | [Documents](https://legend.so/spark/documents/) |
| `/windows`, `/windows/macos` | Windows, displays, cursor, geometry, React roots, native macOS chrome | [Windows](https://legend.so/spark/windows/) |
| `/menus`, `/context-menu`, `/tray` | Owned app menus, native popups and tray items | [Menus](https://legend.so/spark/menus/) |
| `/shortcuts`, `/global-shortcuts`, `/shortcuts/commands`, `/shortcuts/keyboard` | Accelerators, command routing, persisted bindings and low-level keyboard events | [Keyboard shortcuts](https://legend.so/spark/keyboard-shortcuts/) |
| `/dialogs` | Open/save panels, message dialogs and confirmation | [Files and dialogs](https://legend.so/spark/files/) |
| `/files` | Paths, directories, byte/stream/positional IO, watches, scanning, Trash | [Files](https://legend.so/spark/files/) |
| `/settings`, `/settings/observable`, `/secure-storage` | JSON settings, Legend State persistence and selected SecureStore methods | [Settings](https://legend.so/spark/settings/) |
| `/settings/window` | Normal/virtualized settings-window composition and options | [Native UI](https://legend.so/spark/ui/) |
| `/clipboard`, `/links` | Clipboard formats and external URLs/paths | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/drag-drop` | Native drag sources and drop destinations with generic payloads | [Drag and drop](https://legend.so/spark/drag-drop/) |
| `/notifications`, `/system` | Permissions/local notifications, Dock/taskbar, login startup and power | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/processes` | Child processes and app-supplied helper executables | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/sqlite`, `/webview` | Spark-owned database and embedded browser contracts | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/audio`, `/auth-session` | Async players/media sessions and prepared browser-auth sessions | [Desktop integrations](https://legend.so/spark/integrations/) |
| `/camera` | VisionCamera components, hooks, outputs and sessions; Nitro Image integration | [Camera](https://legend.so/spark/camera/) |
| `/updates` | Native whole-app update status, initiation, preferences and events | [Packaging and updates](https://legend.so/spark/distribution/) |
| `/ui`, `/ui/uniwind`, `/ui/classnames` | Common native controls and optional styling integrations | [Native UI](https://legend.so/spark/ui/) |
| `/markdown`, `/html` | Read-only rich text, controlled inputs, and editable previews | [Rich text](https://legend.so/spark/rich-text/) |
| `/ui/search`, `/ui/sidebar`, `/ui/split-view`, `/ui/swipe`, `/ui/glass`, `/ui/symbol` | Specialized macOS views | [Native UI](https://legend.so/spark/ui/) |
| `/ai`, `/ai/codex` | Installed AI CLI execution and optional macOS Codex supervisor | [AI execution](https://legend.so/spark/ai/) |
| `/customize` | Optional macOS app customization: generate, review, preview, and apply edits | [Customization guide](https://github.com/LegendApp/legend-spark/blob/main/docs/customize-apps.md) |
| `/contracts`, `/diagnostics` | Shared error/availability/resource types and explicit diagnostic utilities | [Shared contracts](https://legend.so/spark/reference/#shared-contracts) |

Support varies by platform. Check feature-specific availability, permissions, and [platform limits](https://legend.so/spark/limitations/).

## [Shared contracts](https://legend.so/spark/reference/#shared-contracts)

Spark-owned commands generally resolve `void`; data has explicit result types. Expected cancellation, veto, and nonzero process exit are results. Operational failures reject with `SparkError`; branch on `code` rather than parsing messages. `cause` retains underlying failures. Availability is advisory and separate from permissions.

Unknown option keys reject with `E_UNSUPPORTED_OPTION`, including unknown keys whose value is `undefined`. Promise operations reject validation failures; synchronous utilities throw. Omission leaves update fields unchanged; `null` only clears declared nullable fields. Check each operation's merge/replace rules.

Subscriptions expose synchronous `remove()`. Async registrations resolve to a handle with asynchronous `remove()`. Resource-specific cleanup uses `close()`, `remove()`, `terminate()`, or `dismiss()` according to its meaning. Stop observing when the owner ends, await required cleanup, and retain failed handles for supported retry. Concurrent cleanup joins rather than starting duplicate removals. Hooks handle late setup completions and expose cleanup-error callbacks where applicable.

Time is explicit: `timeoutMs`/Unix timestamps use milliseconds; audio positions and notification delays use seconds. File/process bytes are `Uint8Array`. Native paths, URLs, and base64 are distinct data forms.

## [Ecosystem boundaries](https://legend.so/spark/reference/#ecosystem-boundaries)

Spark owns the supported SQLite, WebView, audio, UI, and desktop contracts. Their backend objects stay private. Selected Clipboard, Linking, and SecureStore methods follow Expo semantics; that does not promise complete Expo-package compatibility.

Legend State observables, React Native, Runtimes, Uniwind, and other ecosystem libraries retain their own APIs. Use upstream imports for capabilities beyond Spark's subset and define resource ownership when mixing integrations.

## [Tooling and metadata exports](https://legend.so/spark/reference/#tooling-and-metadata-exports)

These are not application runtime capabilities:

| Paths | Use |
| --- | --- |
| `/config`, `/schema.json`, `/config-plugin`, `/expo-config` | Typed configuration, schema and Expo composition |
| `/metro`, `/native` | Metro and native discovery |
| `/runtime-entry`, `/metro-gate`, `/init-template` | Generated-project runtime/bootstrap integration |
| `/cli` | CLI executable entry |
| `/package.json` | Package metadata |

For changes to older imports and contracts, see [migration](https://legend.so/spark/migration/).

Contributors should follow the repository's [API design rules](https://github.com/LegendApp/legend-spark/blob/main/docs/api-design.md) when adding APIs or replacing backends.

[View Markdown](https://legend.so/spark/reference.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+API+guide&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Freference%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Rich text

Read and edit Markdown and HTML with native text views.

Source: https://legend.so/spark/rich-text/

Use `@legendapp/spark/markdown` for Markdown and `@legendapp/spark/html` for HTML. Both include readers, controlled inputs, and click-to-edit previews.

Rich text is unsupported on Windows. See [backend limits](https://legend.so/spark/rich-text/#backend-limits) for macOS restrictions.

## [Display rich text](https://legend.so/spark/rich-text/#display-rich-text)

```tsx
import { Markdown } from '@legendapp/spark/markdown';
import { Html } from '@legendapp/spark/html';

export function Readers() {
  return (
    <>
      <Markdown
        value={'# Hello\n\nRead **Spark** and [Legend](https://legendapp.com).'}
        onLinkPress={({ url }) => console.log(url)}
      />
      <Html selectable={false}>
        {'<h1>Hello</h1><p>Read <strong>Spark</strong>.</p>'}
      </Html>
    </>
  );
}
```

Both readers accept these props:

| Prop | Behavior |
| --- | --- |
| `value?: string`, `children?: string` | `value` takes precedence, including an empty string. With neither, the reader is empty. |
| `selectable?: boolean` | Enables native text selection; defaults to `true`. |
| `style` | React Native text style or style array. Markdown applies it to its container; HTML passes it to its text view. |
| `onLinkPress({ url })` | The application owns link navigation. The example logs the URL. |
| View props | Ordinary view accessibility and test props are accepted. |

`Markdown` also accepts `markdownStyle` for text and block formatting. It renders headings, lists, links, code, and images; task checkboxes stay read-only. `Html` accepts `htmlStyle`, with element and style support determined by the backend.

## [Controlled inputs](https://legend.so/spark/rich-text/#controlled-inputs)

`MarkdownInput` and `HtmlInput` stay in editor mode. `EditableMarkdown` and `EditableHtml` show rendered content while unfocused: click to edit, then blur or press Escape to finish.

```tsx
import { useState } from 'react';
import { EditableMarkdown } from '@legendapp/spark/markdown';

export function Editor() {
  const [value, setValue] = useState('Hello **Spark**');
  return (
    <EditableMarkdown
      value={value}
      onChangeText={setValue}
      placeholder="Write a note"
      style={{ backgroundColor: '#fff' }}
    />
  );
}
```

All four require `value: string` and `onChangeText(value: string)`. They also accept `placeholder`, `autoFocus`, `onFocus`, `onBlur`, React Native `style`, `accessibilityLabel`, and `testID`. Changes arrive while typing as Markdown or HTML strings, including whitespace. A ref exposes `focus()` and `blur()` through `MarkdownInputRef` or `HtmlInputRef`, exported from the corresponding capability path.

`MarkdownInput` and `EditableMarkdown` also accept `markdownStyle`. Reader props such as `selectable`, `htmlStyle`, and `onLinkPress` are not input props.

### [Formatting](https://legend.so/spark/rich-text/#formatting)

Set `formatting` to show Bold, Italic, Link, Bullets, and Numbers buttons. Supply a synchronous `onRequestLink={() => url}` returning a string or `undefined` to enable Link. On macOS, formatting also enables Cmd-B, Cmd-I, Cmd-K, Cmd-Shift-7, and Cmd-Shift-8 for those actions while the input is focused.

### [Selection and controlled values](https://legend.so/spark/rich-text/#selection-and-controlled-values)

Echoing an edit through `value` preserves selection and undo. Replacing or rejecting it may reset selection. Inputs expose no controlled selection prop. Editors preserve supported formatting, but may change the original Markdown or HTML spelling.

Use an opaque `style.backgroundColor` for editable previews; it defaults to white. Check reader/editor alignment when using custom block styles or line heights.

## [Installation and build settings](https://legend.so/spark/rich-text/#installation-and-build-settings)

Spark installs Enriched Markdown and Enriched HTML 1.1.1 and applies compatibility patches automatically. No separate backend install is needed. Existing apps can run `spark doctor` and `spark upgrade` to repair outdated web dependency pins.

Math and syntax highlighting need per-app build settings and can download large assets. To disable them in `package.json`:

```json
{
  "enriched-markdown": {
    "enableCodeHighlight": false,
    "enableMath": false
  }
}
```

## [Backend limits](https://legend.so/spark/rich-text/#backend-limits)

-   The macOS HTML backend supports basic inline formatting, paragraphs, headings, links, and lists.
-   Editing HTML flattens nested lists. Remote image URLs round-trip without loading their images; readers show placeholders.
-   The macOS backend does not apply custom `htmlStyle`, including HTML block styles.
-   Markdown math and syntax highlighting depend on application Enriched build settings.

See the [rich-text source guide](https://github.com/LegendApp/legend-spark/blob/main/docs/rich-text.md) for backend configuration and native validation details.

[View Markdown](https://legend.so/spark/rich-text.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Rich+text&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Frich-text%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Settings and persistence

Project-scoped JSON, validated reads, Legend State files, and secure values.

Source: https://legend.so/spark/settings/

## [JSON settings](https://legend.so/spark/settings/#json-settings)

`@legendapp/spark/settings` exports the default project-scoped `settings` store and `createSettingsStore({ storage })`. Missing reads return `undefined`; stored JSON null stays null. Corrupt data is preserved and reported rather than silently repaired.

```ts
import { settings } from '@legendapp/spark/settings';

await settings.set('theme', 'dark');
const theme = await settings.get('theme', {
  decode(value) {
    if (value !== 'system' && value !== 'light' && value !== 'dark') {
      throw new Error('Invalid theme preference');
    }
    return value;
  },
});
```

A decoder validates persisted data before returning an application type. Sets snapshot finite JSON values. Operations serialize per key within one store, without cross-process or cross-store locking. An update callback must not await another operation on its own key/store.

Custom `SettingsStorage` adapters implement async `read`, `write`, and `remove`; keys and storage choice are explicit. General directories/path helpers live in `/files`, not `/settings/paths`.

## [Observable persistence](https://legend.so/spark/settings/#observable-persistence)

`@legendapp/spark/settings/observable` is explicitly a Legend State integration. Legend State owns its observable model and React subscriptions.

```ts
import { createObservableFile } from '@legendapp/spark/settings/observable';
import { getDirectory, mkdir } from '@legendapp/spark/files';

const directory = `${await getDirectory('data')}/preferences`;
await mkdir(directory);
const preferences = await createObservableFile({
  path: `${directory}/count.json`,
  initialValue: 0,
  decode(value) {
    if (typeof value !== 'number') throw new Error('Expected a number');
    return value;
  },
  debounceMs: 300,
});
preferences.value$.set(1);
await preferences.flush();
await preferences.close();
```

Await the factory for loaded/decoded readiness. Missing files use the initial value; corruption/read/decode errors reject. Parent directories must exist, and the path includes its extension. `saveDefault: true` persists a missing default before readiness.

`flush` snapshots synchronously, including changes made in a Legend State batch, and acknowledges that snapshot behind earlier writes. Later mutations need another save. Automatic failures appear in `error$`; explicit flush/close rejects. Successful saves clear the error; retry policy belongs to the app.

`close` stops observing and flushes a final snapshot. Concurrent closes join; failed closes retry that snapshot. Later observable mutations are valid but no longer persisted. Await close inside a quit guard.

`createObservableSettings({ path, fields, ...options })` uses field defaults and required decoders. Defaults apply only to absent fields, present null reaches the decoder, and unknown fields are omitted. These integrations retain Legend State Date/Map/Set serialization; basic JSON settings do not acquire that larger contract. Multiple handles writing one file can overwrite each other.

## [Secure storage](https://legend.so/spark/settings/#secure-storage)

`@legendapp/spark/secure-storage` exposes the selected Expo SecureStore-shaped API, including `getItemAsync`, `setItemAsync`, `deleteItemAsync`, and `isAvailableAsync`. Missing values are null. Supported option/result semantics follow that subset; unsupported options reject.

Native storage remains project-scoped; it is not an OS sandbox. Web secure storage is explicitly unavailable. Check availability and platform constraints rather than treating ordinary web storage as an equivalent secure backend.

See [settings details](https://github.com/LegendApp/legend-spark/blob/main/docs/settings.md) and [API contracts](https://github.com/LegendApp/legend-spark/blob/main/docs/api-contracts.md).

[View Markdown](https://legend.so/spark/settings.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Settings+and+persistence&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fsettings%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Native UI and styling

Controlled inputs, native selectors, macOS composition, settings windows, and Uniwind.

Source: https://legend.so/spark/ui/

## [Common controls](https://legend.so/spark/ui/#common-controls)

For Markdown and HTML readers, inputs, and editable previews, see [Rich text](https://legend.so/spark/rich-text/).

Import `Button`, `TextInput`, `Select`, and `SegmentedControl` from `@legendapp/spark/ui`:

```tsx
import { useState } from 'react';
import { View } from 'react-native';
import { Button, TextInput, Select } from '@legendapp/spark/ui';

export function Preferences() {
  const [name, setName] = useState('');
  const [theme, setTheme] = useState('system');
  return (
    <View>
      <TextInput value={name} onChangeText={setName} accessibilityLabel="Name" />
      <Select
        options={[
          { label: 'System', value: 'system' },
          { label: 'Light', value: 'light' },
          { label: 'Dark', value: 'dark' },
        ]}
        value={theme}
        onValueChange={setTheme}
        accessibilityLabel="Appearance"
      />
      <Button onPress={() => console.log({ name, theme })}>Save</Button>
    </View>
  );
}
```

Controls share `disabled`, `accessibilityLabel`, `testID`, layout `style`, `onError`, and a `ControlRef` supporting `measureInWindow`. Shared refs do not expose backend objects or a universal focus/text mutation API.

TextInput is single-line and supports either controlled `value` or uncontrolled `defaultValue`. Those modes are mutually exclusive; remount to switch modes/reset an uncontrolled field. Defaults initialize once. Controlled desktop edits acknowledge native event counts; mobile controlled editing uses React Native TextInput.

Select and SegmentedControl share unique string-valued options and controlled `value`/`onValueChange`. Labels may repeat; a missing selected value does not implicitly select the first option. A parent that declines a choice retains its current selection.

| Control | macOS | Windows | iOS | Android | Web |
| --- | --- | --- | --- | --- | --- |
| Button | AppKit | WinUI | Expo SwiftUI | Expo Compose | HTML button |
| TextInput | AppKit | WinUI | RN TextInput | RN TextInput | HTML input |
| Select | Popup | ComboBox | Menu picker | Inline choices | HTML select |
| SegmentedControl | Segmented control | Unsupported | Segmented picker | Inline choices | Button group |

`getControlAvailability` is synchronous. Missing/unsupported native controls report through `onError` (default console logging) and render a disabled fallback with current label/text. Invalid props throw during render. A fallback is not a functioning native control.

Mobile Button/Select use optional `@expo/ui@0.2.0-beta.9` with Expo 54; Compose requires a development build. Windows native controls still need validation.

## [Specialized macOS views](https://legend.so/spark/ui/#specialized-macos-views)

| Import | Contract |
| --- | --- |
| `/ui/search` | `TextInputSearch`, controlled/default input, explicit appearance, focus/blur/measurement ref |
| `/ui/sidebar` | Controlled nullable `selectedId`, required `onSelectionChange`, item-array or `SidebarItem` composition, typed context-menu coordinates |
| `/ui/split-view` | `SidebarSplitView` with named `sidebar`/`content` panes, an optional `list` column, grouped title-bar options and provisional/ready layout events |
| `/ui/swipe` | `SwipeActions` with `leadingActions`/`trailingActions`, required `onAction`, and `getSwipeActionsAvailability`; `SwipeAction`/`SwipeActionsProps` types |
| `/ui/glass` | `GlassView`, regular/clear styles and RN color tint; native effect requires macOS 26 |
| `/ui/symbol` | `SFSymbol`, Apple-specific symbol names, layout/accessibility props and missing-symbol errors |

These views have safe synchronous availability queries and `onError`. Unsupported hosts preserve ordinary layout/content and report the limitation. Split layout readiness comes from native events; initial metrics are hints. Zero pane dimensions remain zero. Older macOS retains GlassView children without the effect.

```tsx
import { SidebarSplitView } from '@legendapp/spark/ui/split-view';
import { View, Text } from 'react-native';

<SidebarSplitView
  sidebar={<View><Text>Navigation</Text></View>}
  list={<View><Text>Documents</Text></View>}
  content={<View><Text>Editor</Text></View>}
  titleBar={{ content: { height: 52, material: 'glass' } }}
  onResize={event => console.log(event.phase, event.contentX)}
/>
```

`SidebarSplitView.list` adds a content-list column between the sidebar and detail content. Omit it for a two-pane layout.

`SwipeActions` wraps a row with trackpad actions. Each `SwipeAction` has a unique `id`, `title`, SF Symbol `symbol`, and `color` (`#RRGGBB` or `#RRGGBBAA`). Swipe right to reveal `leadingActions` or left for `trailingActions`; a full swipe runs the first action. `onAction` receives its ID. In recycling lists, key the view by the logical row ID. Optional `dismisses` slides the row away; remove or remount it to recover after failure or undo.

```tsx
import { SwipeActions } from '@legendapp/spark/ui/swipe';
import { Text } from 'react-native';

<SwipeActions
  trailingActions={[{ id: 'archive', title: 'Archive', symbol: 'archivebox', color: '#007AFF' }]}
  onAction={id => console.log(id)}
>
  <Text>Project notes</Text>
</SwipeActions>
```

## [Settings windows](https://legend.so/spark/ui/#settings-windows)

`/settings/window` exports `SettingsWindow`, `VirtualizedSettingsWindow`, named props/pages, and `createSettingsWindowOptions`. Both use `{ id, title, render }` pages and an explicit `windowId`. Use controlled `selectedPageId`/`onSelectionChange` or mount-time `defaultPageId`, with one selection owner.

This composition requires `@legendapp/list` and macOS split-view support. It shows a hidden window only after layout/initial-scroll readiness. When native split view is unavailable, the fallback has no readiness event and the settings window stays hidden. Handle `onError`; check availability before selecting this composition for a target.

## [Styling](https://legend.so/spark/ui/#styling)

`/ui/uniwind` exports the same four common controls with optional `className` integration. Classes shape layout around native controls; arbitrary OS chrome styling is not promised. Explicit style takes precedence. `/ui/classnames` is a library-specific `clsx`/`tailwind-merge` convenience.

Use ordinary React Native views/text for surrounding screens. Uniwind supports application theme choices `system`, `light`, and `dark`; theme persistence belongs to the app. Windows Appearance overrides update mounted WinUI controls through the native theme module.

See [UI contracts](https://github.com/LegendApp/legend-spark/blob/main/docs/ui.md) and [styling setup](https://github.com/LegendApp/legend-spark/blob/main/docs/styling.md). Router integration and a broad cross-platform component catalog remain outside the supported scope.

[View Markdown](https://legend.so/spark/ui.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Native+UI+and+styling&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fui%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)


---

# Windows and displays

Explicit window identity, geometry, React roots, and macOS chrome.

Source: https://legend.so/spark/windows/

Import imperative operations, React helpers, and types from `@legendapp/spark/windows`. Every command addresses an explicit logical window ID. `'main'` identifies the host-created main window; `openWindow` cannot recreate it.

```ts
import { openWindow, getWindow, showWindow, closeWindow } from '@legendapp/spark/windows';

await openWindow({
  id: 'inspector',
  component: 'Inspector',
  title: 'Inspector',
  size: { width: 480, height: 640 },
  show: false,
});
await showWindow('inspector', { focus: true });
const inspector = await getWindow('inspector');
const result = await closeWindow('inspector');
if (!result.closed) console.log('Close was vetoed');
```

Register `Inspector` with React Native's `AppRegistry` before this fragment runs. Window props must be JSON-serializable. Named windows are singletons: opening a live ID rejects `E_ALREADY_EXISTS`. Show/focus the existing window explicitly. IDs may be reused after closure; commands address the current live instance.

## [Geometry and state](https://legend.so/spark/windows/#geometry-and-state)

`getDisplays()` returns IDs, logical screen sizes, work areas, scale factors, and optional persistent identity. `getCursorPoint()` returns `{ displayId, x, y }`. `WindowBounds` is the **outer frame**, measured in logical units from the identified display's top-left corner. Work areas use that same coordinate system.

Use `setWindowBounds(id, bounds, options?)`, `centerWindow`, `setWindowOptions`, minimize/maximize/unmaximize, and `setWindowFullscreen` on the explicit owner. `WindowInfo` includes visibility, focus, minimized, **maximized**, fullscreen, and bounds. Maximized means macOS zoomed/Windows `IsZoomed`; bounds events can prompt a fresh state query.

On macOS, animated geometry uses the portable setter:

```ts
import { getWindow, setWindowBounds } from '@legendapp/spark/windows';

const window = await getWindow('inspector');
await setWindowBounds('inspector', {
  ...window.bounds,
  width: 600,
  height: 700,
}, { macos: { durationMs: 200 } });
```

Omitted update fields stay unchanged; nullable min/max constraints clear to supported defaults. Creation-only identity, component, kind, parent/modal settings, props, position, and restoration policy are not general updates.

## [Events and close guards](https://legend.so/spark/windows/#events-and-close-guards)

`addWindowListener(id, type, listener, options?)` and `beforeWindowClose(id, handler, options?)` resolve async registrations. Their lifetime binds to the native instance, so a later window reusing the logical ID cannot inherit old listeners/guards. Await `remove()` on disposal. A guard permits closure only by returning `true`; rejection/false vetoes it. `closeWindow` reports `{ closed: true }` or `{ closed: false, reason: 'vetoed' }`.

`getWindowAvailability()` is a synchronous, safe capability query. It does not create a window or guarantee a subsequent operation succeeds.

## [React roots and navigation](https://legend.so/spark/windows/#react-roots-and-navigation)

`WindowProvider` supplies ownership; `useWindowId()` reads it and throws outside a provider. `withWindowProvider` wraps an ordinary registered root. `useWindowFocusEffect` observes the owning root after React commits.

`createWindowsNavigator` registers named window components/loaders and returns typed `open`, `close`, `show`, `getId`, and `prefetch` operations. Lazy components load before native creation; failed loads remain retryable. A stable configured ID is shared by eager and lazy roots. This navigator is window coordination, not Expo Router integration.

`createPrimaryWindowLifecycle` is the imperative initial-open/reopen coordinator; `usePrimaryWindowLifecycle` owns it in an effect. [Document controllers](https://legend.so/spark/documents/) add menus and file-open requests.

## [macOS chrome](https://legend.so/spark/windows/#macos-chrome)

Use `macos.titleBar`, `macos.toolbar`, represented URI, window level, and startup split-view options for AppKit-specific presentation. Toolbar item kinds include buttons, popup menus, labels, search, and segmented controls. A symbol without a declared label stays icon-only.

`@legendapp/spark/windows/macos` exposes blur, toolbar text/search operations, and `addMacOSWindowListener` for title-bar/toolbar events. Toolbar popup events contain an `action` discriminating ordinary selection from `valueChanged`. Geometry animation stays in `/windows`.

See the [window contract](https://github.com/LegendApp/legend-spark/blob/main/docs/api-window-contract.md) for all option/event types and platform restrictions.

[View Markdown](https://legend.so/spark/windows.md)[Report a documentation correction](https://github.com/LegendApp/legend-docs/issues/new?title=Docs%3A+Windows+and+displays&body=Page%3A+https%3A%2F%2Flegend.so%2Fspark%2Fwindows%0A%0AWhat+is+incorrect+or+missing%3F%0A%0AExpected+behavior+or+supporting+source%3A%0A)