---
url: /guide/AppIntent.md
---

# AppIntent

`AppIntentManager` is used to **register and manage AppIntents** in the **Scripting** app. It serves as the core mechanism for executing script logic behind controls in **Widgets**, **Live Activities**, and **ControlWidgets**.

All `AppIntent`s **must** be defined in the `app_intents.tsx` file. When an intent is executed, the script runs in the `"app_intents"` environment (`Script.env === "app_intents"`).

Once registered, these intents can be triggered by **Button** and **Toggle** controls within Widgets, Live Activities, or ControlWidgets, allowing users to define interactive behavior via script.

***

## 1. Type Definitions

### `AppIntent<T>`

Represents a concrete intent instance with parameters and metadata.

| Property   | Type                | Description                                                                |
| ---------- | ------------------- | -------------------------------------------------------------------------- |
| `script`   | `string`            | The internal script path. Automatically generated by the system.           |
| `name`     | `string`            | The name of the AppIntent. Must be unique.                                 |
| `protocol` | `AppIntentProtocol` | The protocol the intent conforms to (e.g., general, audio, Live Activity). |
| `params`   | `T`                 | The parameters to be passed when the intent is executed.                   |

***

### `AppIntentFactory<T>`

A **factory function** that creates an `AppIntent` instance with specified parameters.

```ts
type AppIntentFactory<T> = (params: T) => AppIntent<T>
```

***

### `AppIntentPerform<T>`

A function that handles intent execution logic asynchronously.

```ts
type AppIntentPerform<T> = (params: T) => Promise<void>
```

***

### `AppIntentProtocol`

An enumeration that defines the behavior type of the intent.

| Enum Value                 | Description                                                                                                                                                                                                                                                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AppIntent` (0)            | A general-purpose AppIntent for typical operations.                                                                                                                                                                                                                                                                          |
| `AudioPlaybackIntent` (1)  | An intent that plays, pauses, or otherwise modifies audio playback.                                                                                                                                                                                                                                                          |
| `AudioRecordingIntent` (2) | _(iOS 18.0+)_ An intent that starts, stops, or modifies audio recording. **Note**: On iOS/iPadOS, when using the `AudioRecordingIntent` protocol, you must start a **Live Activity** at the beginning of the recording and keep it active for the entire session. If you don't, the recording will be automatically stopped. |
| `LiveActivityIntent` (3)   | An intent that starts, pauses, or modifies a Live Activity.                                                                                                                                                                                                                                                                  |

***

## 2. `AppIntentManager` Class

### `AppIntentManager.register<T>(options): AppIntentFactory<T>`

Registers a new `AppIntent` by specifying its name, protocol, and perform logic. When a control (e.g., Button or Toggle) triggers the intent, the associated `perform` function is called.

```ts
static register<T = undefined>(options: {
  name: string;
  protocol: AppIntentProtocol;
  perform: AppIntentPerform<T>;
}): AppIntentFactory<T>
```

#### Parameters:

| Property   | Type                  | Description                                                                                                        |
| ---------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `name`     | `string`              | A unique identifier for the AppIntent.                                                                             |
| `protocol` | `AppIntentProtocol`   | The protocol this intent implements.                                                                               |
| `perform`  | `AppIntentPerform<T>` | The asynchronous function executed when the intent is triggered. The `params` argument is passed from the control. |

#### Returns:

- **`AppIntentFactory<T>`**: A factory function that creates an `AppIntent` instance with the specified parameters.

#### Example:

```tsx
// app_intents.tsx
export const ToggleDoorIntent = AppIntentManager.register({
  name: "ToggleDoorIntent",
  protocol: AppIntentProtocol.AppIntent,
  perform: async ({ id, newState }: { id: string; newState: boolean }) => {
    // Custom logic: toggle the door state
    await setDoorState(id, newState)
    // Notify UI to refresh toggle state
    ControlWidget.reloadToggles()
  }
})
```

In a control view file (e.g., `control_widget_toggle.tsx`):

```tsx
ControlWidget.present(
  <ControlWidgetToggle
    intent={ToggleDoorIntent({ id: "door1", newState: !currentState })}
    label={{
      title: "Door 1",
      systemImage: currentState ? "door.garage.opened" : "door.garage.closed"
    }}
    activeValueLabel={{ title: "The door is opened" }}
    inactiveValueLabel={{ title: "The door is closed" }}
  />
)
```

In a widget file (`widget.tsx`):

```tsx
<Toggle
  title="Door 1"
  value={currentState}
  intent={ToggleDoorIntent({ id: "door1", newState: !currentState })}
/>
```

***

## 3. Execution Environment

All AppIntents registered via `AppIntentManager` are executed in the `"app_intents"` environment.
This allows safe use of APIs suitable for background execution, such as:

- Fetching data from the network
- Controlling Live Activities
- Triggering control view refreshes

***

## 4. Best Practices

1. **Centralized Definitions**: All AppIntents **must** be defined in `app_intents.tsx` for discoverability and maintainability.
2. **Strong Typing**: Define explicit parameter types `T` for both `perform` and control usage to benefit from type checking and autocomplete.
3. **Choose the Right Protocol**:

   - General operation → `AppIntent`
   - Audio playback → `AudioPlaybackIntent`
   - Audio recording → `AudioRecordingIntent` _(requires iOS 18+, with Live Activity)_
   - Live Activity control → `LiveActivityIntent`
4. **Trigger UI Updates**: If the intent modifies a UI state (e.g., toggle), call:

   - `ControlWidget.reloadButtons()`
   - `ControlWidget.reloadToggles()`
   - `Widget.reloadAll()`
     depending on where the control is hosted.



---
url: /guide/Assistant/Assistant Conversation APIs.md
---

# Assistant Conversation APIs

The Conversation APIs are used to **start, control, and present a system-hosted Assistant chat session**.
A conversation corresponds to a **fully managed chat page**, where Scripting handles the UI, streaming output, provider selection, and message lifecycle.

Key differences from other Assistant APIs:

- Conversation APIs are designed for **interactive chat experiences**
- UI, streaming, and message handling are managed by the system
- Developers control **when the conversation starts, ends, and is shown**

***

## Conversation Lifecycle

A typical conversation follows this lifecycle:

1. `startConversation` — create a conversation (optionally auto-start)
2. `present` — display the Assistant chat page
3. User interacts with the Assistant
4. `dismiss` — temporarily hide the chat page (conversation continues)
5. `present` — show the same conversation again
6. `stopConversation` — terminate the conversation and release resources

Important rules:

- **Only one active conversation can exist at a time**
- Calling `startConversation` while a conversation is active throws an error
- Calling `stopConversation` automatically calls `dismiss`

***

## startConversation

### API Definition

```ts
function startConversation(options: {
  message: string
  images?: UIImage[]
  autoStart?: boolean
  systemPrompt?: string
  modelId?: string
  provider?: Provider
}): Promise<void>
```

***

### Parameters

#### options.message

- Type: `string`
- Required
- The **initial user message** of the conversation
- Equivalent to the first user input in the chat UI

***

#### options.images (optional)

- Type: `UIImage[]`
- Sent together with the initial message
- Common use cases:

  - Image analysis
  - Starting a conversation from a photo or screenshot

***

#### options.autoStart (optional)

- Type: `boolean`
- Default: `false`

Behavior:

- `true`

  - The assistant immediately starts generating a reply
- `false`

  - The conversation is created but not sent automatically
  - Typically used when the user should press “Send” manually

***

#### options.systemPrompt (optional)

- Type: `string`

Behavior:

- If omitted:

  - The built-in Scripting Assistant system prompt is used
  - Assistant Tools are available
- If provided:

  - Fully replaces the default system prompt
  - **Assistant Tools are disabled**

Typical use cases:

- Creating a highly customized chat role
- Running the model without any tool access

***

#### options.modelId (optional)

- Type: `string`
- Specifies the model to use for this conversation
- Users may still change the model in the chat UI (if allowed)

***

#### options.provider (optional)

- Type: `Provider`
- Specifies the default provider for the conversation
- Users may change the provider in the chat UI (if allowed)

***

### Return Value

```ts
Promise<void>
```

- Resolves when the conversation is successfully created
- Rejects if a conversation already exists

***

## present

### API Definition

```ts
function present(): Promise<void>
```

***

### Behavior

- Presents the Assistant chat page for the current conversation
- If the page is already presented, calling this has no effect
- Can be called:

  - After `startConversation`
  - After `dismiss` to re-present the same conversation

***

### Return Value

```ts
Promise<void>
```

- Resolves when the chat page is dismissed by the user

***

## dismiss

### API Definition

```ts
function dismiss(): Promise<void>
```

***

### Behavior

- Dismisses the Assistant chat page
- **Does not stop the conversation**
- Conversation state and history are preserved

Typical use cases:

- Temporarily hiding the chat UI
- Navigating to another page or task

***

### Return Value

```ts
Promise<void>
```

***

## stopConversation

### API Definition

```ts
function stopConversation(): Promise<void>
```

***

### Behavior

- Fully terminates the current conversation
- Automatically calls `dismiss`
- Cleans up conversation state and resources
- After calling this, a new conversation may be started

***

### Return Value

```ts
Promise<void>
```

***

## Conversation State Flags

### Assistant.isAvailable

```ts
const isAvailable: boolean
```

- Indicates whether the current user has access to the Assistant
- If `false`, all Conversation APIs are unavailable

***

### Assistant.isPresented

```ts
const isPresented: boolean
```

- Indicates whether the Assistant chat page is currently presented

***

### Assistant.hasActiveConversation

```ts
const hasActiveConversation: boolean
```

- Indicates whether there is an active conversation
- Commonly used to guard against duplicate `startConversation` calls

***

## Examples

### Example 1: Typical usage

```ts
await Assistant.startConversation({
  message: "Help me summarize this article.",
  autoStart: true
})

await Assistant.present()
```

***

### Example 2: Create a conversation without auto-sending

```ts
await Assistant.startConversation({
  message: "Let's discuss system architecture design.",
  autoStart: false
})

await Assistant.present()
// User manually presses Send in the UI
```

***

### Example 3: Dismiss and re-present the same conversation

```ts
await Assistant.startConversation({
  message: "Analyze this image.",
  images: [image],
  autoStart: true
})

await Assistant.present()

await Assistant.dismiss()

// Later, re-present the same conversation
await Assistant.present()
```

***

### Example 4: Stop the current conversation and start a new one

```ts
if (Assistant.hasActiveConversation) {
  await Assistant.stopConversation()
}

await Assistant.startConversation({
  message: "Start a new topic.",
  autoStart: true
})

await Assistant.present()
```

***

## Best Practices

- Treat Conversation APIs as a **managed chat UI**
- Do not mix Conversation APIs with `requestStreaming` in the same flow
- Always check `hasActiveConversation` before calling `startConversation`
- For one-shot or data-oriented tasks, prefer:

  - `requestStructuredData`
  - `requestStreaming`
- Use Conversation APIs when continuous user interaction is required

***

## Design Boundaries

- Conversation APIs are not suitable for headless or background tasks
- Not intended for fully automated workflows
- Not ideal when you need strict control over prompts, tokens, or output format



---
url: /guide/Assistant/Assistant Quick Start.md
---

# Assistant Quick Start

The Assistant API in Scripting provides three distinct capabilities, each designed for a different type of use case: **structured data**, **streaming output**, and **interactive conversations**.

Before choosing an API, first decide **what kind of result you need**.

***

## Assistant API Overview

| Category         | Main APIs                                                        | Best For                         |
| ---------------- | ---------------------------------------------------------------- | -------------------------------- |
| Structured Data  | `requestStructuredData`                                          | Extracting predictable JSON data |
| Streaming Output | `requestStreaming`                                               | Real-time text generation        |
| Conversations    | `startConversation` / `present` / `dismiss` / `stopConversation` | Fully managed chat UI            |

***

## requestStructuredData

**Purpose**
Requests **strictly structured JSON output** that conforms to a provided schema.

**Best suited for**

- Parsing receipts, invoices, and bills
- Extracting fields from natural language
- Generating configuration or rule objects
- Any output that must be consumed by program logic

**Key characteristics**

- Stable and predictable output
- No streaming or incremental updates
- Ideal for background or headless scenarios

**In one sentence**

> If you need **data**, use `requestStructuredData`.

***

## requestStreaming

**Purpose**
Requests **streaming output**, allowing you to receive content incrementally as the model generates it.

**Best suited for**

- Typing-effect UI
- Long-form content generation
- Low-latency user feedback

**Key characteristics**

- Emits text, reasoning, and usage chunks
- Can be rendered progressively
- Output is not guaranteed to be structured

**In one sentence**

> If you need **real-time output**, use `requestStreaming`.

***

## Conversation APIs

**Related methods**

- `startConversation`
- `present`
- `dismiss`
- `stopConversation`

**Purpose**
Creates and presents a **system-hosted Assistant chat experience**.

**Best suited for**

- ChatGPT-style interactions
- Multi-turn conversations
- Scenarios where the system manages UI, streaming, and provider switching

**Key characteristics**

- Built-in chat UI
- Streaming handled automatically
- Only one active conversation at a time

**In one sentence**

> If you need a **full chat experience**, use the Conversation APIs.

***

## How to Choose the Right API

### Common Scenarios

- **Parse a receipt →** `requestStructuredData`
- **Show AI writing text live →** `requestStreaming`
- **Open a chat interface for users →** Conversation APIs
- **No UI, just results →** `requestStructuredData` or `requestStreaming`
- **Let the system manage the chat UI →** Conversation APIs

***

## Minimal Examples

### Structured Data

```ts
const result = await Assistant.requestStructuredData(...)
```

***

### Streaming Output

```ts
const stream = await Assistant.requestStreaming(...)
for await (const chunk of stream) {
  // handle chunk
}
```

***

### Conversation

```ts
await Assistant.startConversation({
  message: "Hello",
  autoStart: true
})
await Assistant.present()
```

***

## Usage Tips

- Do not mix Conversation APIs with `requestStreaming` in the same flow
- Prefer `requestStructuredData` whenever output must be consumed as data
- Use streaming or conversations for presentation-focused scenarios

***

## Next Steps

For deeper details, refer to:

- `requestStructuredData` – detailed schema-driven data extraction
- `requestStreaming` – streaming behavior and chunk handling
- Conversation APIs – lifecycle and interaction patterns



---
url: /guide/Assistant/requestStreaming.md
---

# requestStreaming

`requestStreaming` requests a **streaming response** from the Assistant.
Instead of returning a complete result at once, the Assistant emits **chunks incrementally** as the model generates output.

This enables:

- Real-time UI updates (typing effect)
- Low-latency handling of long responses
- Progressive rendering of results
- Streaming logs and intermediate output handling

The API returns a **`ReadableStream<StreamChunk>`**, which can be consumed using `for await ... of`.

***

## API Definition

```ts
function requestStreaming(options: {
  systemPrompt?: string | null
  messages: MessageItem | MessageItem[]
  provider?: Provider
  modelId?: string
}): Promise<ReadableStream<StreamChunk>>
```

***

## Parameters

### options.systemPrompt (optional)

- Type: `string | null`
- Specifies the system prompt for this request.
- If omitted:

  - The default Assistant system prompt is used.
- If provided:

  - It **fully replaces** the default system prompt.
  - Assistant Tools are **not available**.

Typical use cases:

- Defining a strict role (e.g. reviewer, translator, summarizer)
- Enforcing output tone or behavior
- Running the model without built-in tools

***

### options.messages

- Type: `MessageItem | MessageItem[]`
- Required
- Represents the conversation context sent to the model.

#### MessageItem

```ts
type MessageItem = {
  role: "user" | "assistant"
  content: MessageContent | MessageContent[]
}
```

- `role`

  - `"user"`: user input
  - `"assistant"`: previous assistant messages (for context)

***

### MessageContent Types

#### Text

```ts
type MessageTextContent =
  | string
  | { type: "text"; content: string }
```

***

#### Image

```ts
type MessageImageContent = {
  type: "image"
  content: string // data:image/...;base64,...
}
```

***

#### Document

```ts
type MessageDocumentContent = {
  type: "document"
  content: {
    mediaType: string
    data: string // base64
  }
}
```

***

### options.provider (optional)

- Type: `Provider`
- Specifies the AI provider.
- If omitted, the currently configured default provider is used.
- Supported values:

  - `"openai"`
  - `"gemini"`
  - `"anthropic"`
  - `"deepseek"`
  - `"openrouter"`
  - `{ custom: string }`

***

### options.modelId (optional)

- Type: `string`
- Specifies the model ID.
- Must match a model actually supported by the selected provider.
- If omitted, the provider’s default model is used.

***

## Return Value

```ts
Promise<ReadableStream<StreamChunk>>
```

Once resolved, you receive a stream that can be consumed asynchronously.

***

## StreamChunk Types

The stream may emit the following chunk types.

***

### StreamTextChunk

```ts
type StreamTextChunk = {
  type: "text"
  content: string
}
```

- Represents user-visible generated text.
- Multiple chunks concatenated form the final response.

***

### StreamReasoningChunk

```ts
type StreamReasoningChunk = {
  type: "reasoning"
  content: string
}
```

- Represents intermediate reasoning produced by the model.
- Availability and granularity depend on the provider and model.

***

### StreamUsageChunk

```ts
type StreamUsageChunk = {
  type: "usage"
  content: {
    totalCost: number | null
    cacheReadTokens: number | null
    cacheWriteTokens: number | null
    inputTokens: number
    outputTokens: number
  }
}
```

Notes:

- Typically emitted once near the end of the stream.
- Some providers may omit certain fields.
- `totalCost` may be `null` if the provider does not expose pricing data.

***

## Examples

### Example 1: Basic streaming request

```ts
const stream = await Assistant.requestStreaming({
  messages: {
    role: "user",
    content: "Tell me a short science fiction story."
  },
  provider: "openai"
})

let result = ""

for await (const chunk of stream) {
  if (chunk.type === "text") {
    result += chunk.content
    console.log(chunk.content)
  }
}
```

***

### Example 2: Handling text, reasoning, and usage separately

```ts
const stream = await Assistant.requestStreaming({
  systemPrompt: "You are a precise technical writing assistant.",
  messages: [
    {
      role: "user",
      content: "Explain what HTTP/3 is."
    }
  ]
})

let answer = ""
let reasoningLog = ""
let usage = null

for await (const chunk of stream) {
  switch (chunk.type) {
    case "text":
      answer += chunk.content
      break

    case "reasoning":
      reasoningLog += chunk.content
      break

    case "usage":
      usage = chunk.content
      break
  }
}

console.log(answer)
console.log(usage)
```

***

### Example 3: Streaming with document input

```ts
const stream = await Assistant.requestStreaming({
  messages: [
    {
      role: "user",
      content: [
        { type: "text", content: "Summarize the key points of this document." },
        {
          type: "document",
          content: {
            mediaType: "application/pdf",
            data: "JVBERi0xLjQKJcfs..."
          }
        }
      ]
    }
  ],
  provider: "anthropic"
})

for await (const chunk of stream) {
  if (chunk.type === "text") {
    console.log(chunk.content)
  }
}
```

***

## Usage Notes and Best Practices

- Streams must be consumed **sequentially**; do not read concurrently.
- For UI scenarios:

  - Render `text` chunks immediately.
  - Keep `reasoning` for debugging or developer modes.
  - Process `usage` after completion.
- If you no longer need the output, stop consuming the stream to avoid unnecessary cost.
- Not all providers/models emit `reasoning` or `usage`.
- Do not assume a chunk represents a complete sentence; chunk sizes vary.



---
url: /guide/Assistant/requestStructuredData.md
---

# requestStructuredData

`requestStructuredData` requests **structured JSON output** from the assistant that conforms to a provided JSON schema.
This API is designed for workflows where you want a predictable, programmatically usable result rather than free-form text.

Common use cases include:

- Extracting structured fields from natural language
- Parsing invoices, receipts, and tickets
- Generating configuration objects
- Normalizing data across different AI providers/models

***

## Supported JSON Schema Types

Scripting defines a lightweight schema structure with three building blocks.

### Primitive

```ts
type JSONSchemaPrimitive = {
  type: "string" | "number" | "boolean"
  required?: boolean
  description: string
}
```

***

### Object

```ts
type JSONSchemaObject = {
  type: "object"
  properties: Record<string, JSONSchemaType>
  required?: boolean
  description: string
}
```

***

### Array

```ts
type JSONSchemaArray = {
  type: "array"
  items: JSONSchemaType
  required?: boolean
  description: string
}
```

***

## API Signatures

### Without images

```ts
function requestStructuredData<R>(
  prompt: string,
  schema: JSONSchemaArray | JSONSchemaObject,
  options?: {
    provider: Provider
    modelId?: string
  }
): Promise<R>
```

### With images

```ts
function requestStructuredData<R>(
  prompt: string,
  images: string[],
  schema: JSONSchemaArray | JSONSchemaObject,
  options?: {
    provider: Provider
    modelId?: string
  }
): Promise<R>
```

***

## Parameters

### prompt

- Type: `string`
- Required
- The instruction to the model describing what to extract or generate.
- For best reliability, explicitly specify:

  - expected formats (e.g., ISO date)
  - currency rules
  - how to handle missing fields

### images (optional)

- Type: `string[]`
- Each item must be a **data URI**, e.g. `data:image/png;base64,...`
- Not all providers/models support images.
- Avoid passing too many images to reduce failure risk.

### schema

- Type: `JSONSchemaArray | JSONSchemaObject`
- Required
- Defines the **only acceptable** JSON structure for the response.
- Every field should have a clear `description` to guide the model.

### options.provider

- Type: `Provider`
- Optional (uses the default configured provider if omitted)
- Supported:

  - `"openai" | "gemini" | "anthropic" | "deepseek" | "openrouter" | { custom: string }`

### options.modelId (optional)

- Type: `string`
- Must match a model actually supported by the chosen provider.
- If omitted, Scripting uses the provider’s default model.

***

## Return Value

```ts
Promise<R>
```

- `R` is the generic type you provide.
- The resolved value is expected to match your schema.
- The promise rejects if the assistant cannot return a valid structured result.

***

## Examples

### Example 1: Parse a receipt/bill into line items (time + amount)

This example asks the assistant to analyze a textual receipt and extract:

- receipt time (`purchasedAt`)
- line items (`items[]`)

  - item name
  - item time (if present; otherwise null)
  - amount
- total amount

```ts
type ReceiptItem = {
  name: string
  time: string | null
  amount: number
}

type ReceiptParsed = {
  purchasedAt: string | null
  currency: string | null
  items: ReceiptItem[]
  total: number | null
}

const receiptText = `
Star Coffee
2026-01-08 14:23
Latte (Large)   $5.50
Blueberry Muffin $3.20
Tax             $0.79
Total           $9.49
`

const parsed = await Assistant.requestStructuredData<ReceiptParsed>(
  [
    "Analyze the receipt text below and extract:",
    "- purchasedAt: the purchase date/time in ISO-8601 if possible",
    "- currency: currency code if you can infer it (otherwise null)",
    "- items: only actual purchasable items (exclude tax/total lines)",
    "  - name: item name",
    "  - time: item-level time if present, otherwise null",
    "  - amount: numeric amount",
    "- total: numeric total if present, otherwise null",
    "",
    "Receipt:",
    receiptText
  ].join("\n"),
  {
    type: "object",
    description: "Parsed receipt content",
    properties: {
      purchasedAt: {
        type: "string",
        description: "Purchase date/time in ISO-8601 format if available, otherwise an empty string"
      },
      currency: {
        type: "string",
        description: "Currency code like USD/EUR/CNY if inferable, otherwise an empty string"
      },
      items: {
        type: "array",
        description: "Purchased line items (exclude tax/total/subtotal/service fee lines)",
        items: {
          type: "object",
          description: "A single purchased item line",
          properties: {
            name: {
              type: "string",
              description: "Item name"
            },
            time: {
              type: "string",
              description: "Item-level time in ISO-8601 if available, otherwise an empty string"
            },
            amount: {
              type: "number",
              description: "Item amount as a number"
            }
          }
        }
      },
      total: {
        type: "number",
        description: "Total amount if present, otherwise -1"
      }
    }
  },
  {
    provider: "openai"
  }
)

// Post-processing suggestion:
// Treat "" as null for purchasedAt/currency/time, and -1 as null for total.
console.log(parsed)
```

***

### Example 2: Generate an array

```ts
type Expense = {
  name: string
  amount: number
}

const expenses = await Assistant.requestStructuredData<Expense[]>(
  "List three common daily expenses with estimated amounts.",
  {
    type: "array",
    description: "A list of expenses",
    items: {
      type: "object",
      description: "A single expense item",
      properties: {
        name: { type: "string", description: "Expense name" },
        amount: { type: "number", description: "Estimated amount" }
      }
    }
  },
  { provider: "gemini" }
)
```

***

### Example 3: Use images + schema

```ts
type ImageSummary = {
  description: string
  containsText: boolean
}

const summary = await Assistant.requestStructuredData<ImageSummary>(
  "Analyze the image and summarize the main content.",
  ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."],
  {
    type: "object",
    description: "Image analysis result",
    properties: {
      description: { type: "string", description: "What the image shows" },
      containsText: { type: "boolean", description: "Whether readable text exists" }
    }
  },
  { provider: "openai" }
)
```

***

## Best Practices

- Make the schema explicit and descriptive; ambiguous schemas lead to unstable results.
- Prefer `requestStructuredData` over parsing free-form text when your output is used by program logic.
- For business-critical extraction (e.g., finance/receipts), add strict formatting rules in `prompt`.



---
url: /guide/Changelog/2.4.8/Intent.md
---

# Intent

Scripting allows you to define custom iOS Intents using an `intent.tsx` file. These scripts can receive input from the iOS share sheet or the Shortcuts app and return structured results. With optional UI presentation, you can create interactive workflows that process data and deliver output dynamically.

***

## 1. Creating and Configuring an Intent

### 1.1 Create an Intent Script

1. Create a new script project in the Scripting app.
2. Add a file named `intent.tsx` to the project.
3. Define your logic and optionally a UI component inside the file.

### 1.2 Configure Supported Input Types

Tap the project title in the editor’s title bar to open **Intent Settings**, then select supported input types:

- Text
- Images
- File URLs
- URLs

This configuration enables your script to appear in the share sheet or Shortcuts when matching input is provided.

***

## 2. Accessing Input Data

Inside `intent.tsx`, use the `Intent` API to access input values.

| Property                   | Description                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `Intent.shortcutParameter` | A single parameter passed from the Shortcuts app, with `.type` and `.value` fields. |
| `Intent.textsParameter`    | Array of text strings.                                                              |
| `Intent.urlsParameter`     | Array of URL strings.                                                               |
| `Intent.imagesParameter`   | Array of image file paths (UIImage objects).                                        |
| `Intent.fileURLsParameter` | Array of local file URL paths.                                                      |

Example:

```ts
if (Intent.shortcutParameter) {
  if (Intent.shortcutParameter.type === "text") {
    console.log(Intent.shortcutParameter.value)
  }
}
```

***

## 3. Returning a Result

Use `Script.exit(result)` to return a result to the caller, such as the Shortcuts app or another script. Valid return types include:

- Plain text: `Intent.text(value)`
- Attributed text: `Intent.attributedText(value)`
- URL: `Intent.url(value)`
- JSON: `Intent.json(value)`
- File path or file URL: `Intent.file(value)` or `Intent.fileURL(value)`

Example:

```ts
import { Script, Intent } from "scripting"

Script.exit(Intent.text("Done"))
```

***

## 4. Displaying Interactive UI

Use `Navigation.present()` to show a UI before returning a result. You can render a React-style component and then call `Script.exit()` after the interaction completes.

Example:

```ts
import { Intent, Script, Navigation, VStack, Text } from "scripting"

function MyIntentView() {
  return (
    <VStack>
      <Text>{Intent.textsParameter?.[0]}</Text>
    </VStack>
  )
}

async function run() {
  await Navigation.present({ element: <MyIntentView /> })
  Script.exit()
}

run()
```

***

## 5. Using Intents in the Share Sheet

If a script supports a specific input type (e.g., text or image), it will automatically appear as an option in the iOS share sheet:

1. Select content such as text or a file.
2. Tap the Share button.
3. Choose **Scripting** in the share sheet.
4. Scripting will list scripts that support the selected input type.

***

## 6. Using Intents in the Shortcuts App

You can call scripts from the Shortcuts app with or without UI:

- **Run Script**: Executes the script in the background.
- **Run Script in App**: Executes the script in the foreground, with UI presentation support.

Steps:

1. Open the Shortcuts app and create a new shortcut.
2. Add the **Run Script** or **Run Script in App** action from Scripting.
3. Choose the target script and pass input parameters if needed.

***

## 7. Intent API Reference

### `Intent` Properties

| Property            | Type                | Description                                     |
| ------------------- | ------------------- | ----------------------------------------------- |
| `shortcutParameter` | `ShortcutParameter` | Input from Shortcuts with `.type` and `.value`. |
| `textsParameter`    | `string[]`          | Array of input text values.                     |
| `urlsParameter`     | `string[]`          | Array of input URLs.                            |
| `imagesParameter`   | `UIImage[]`         | Array of image file paths or objects.           |
| `fileURLsParameter` | `string[]`          | Array of input file paths (local file URLs).    |

### `Intent` Methods

| Method                         | Return Type                 | Example                                |
| ------------------------------ | --------------------------- | -------------------------------------- |
| `Intent.text(value)`           | `IntentTextValue`           | `Intent.text("Hello")`                 |
| `Intent.attributedText(value)` | `IntentAttributedTextValue` | `Intent.attributedText("Styled Text")` |
| `Intent.url(value)`            | `IntentURLValue`            | `Intent.url("https://example.com")`    |
| `Intent.json(value)`           | `IntentJsonValue`           | `Intent.json({ key: "value" })`        |
| `Intent.file(path)`            | `IntentFileValue`           | `Intent.file("/path/to/file.txt")`     |
| `Intent.fileURL(path)`         | `IntentFileURLValue`        | `Intent.fileURL("/path/to/file.pdf")`  |
| `Intent.image(UIImage)`        | `IntentImageValue`          | `Intent.image(uiImage)`                |
| `Intent.view(node, value?)`    | `IntentViewValue`           | `Intent.view(<View />)`                |

***

## 8. Best Practices and Notes

- Always call `Script.exit()` to properly terminate the script and return a result.
- When displaying a UI, ensure `Navigation.present()` is awaited before calling `Script.exit()`.
- Use **"Run Script in App"** for large files or images to avoid process termination due to memory constraints.
- You can use `queryParameters` when launching scripts via URL scheme if additional data is needed.



---
url: /guide/Changelog/2.4.8/LanguageModelSession.md
---

# LanguageModelSession

`LanguageModelSession` provides access to Apple Intelligence local language models through iOS Foundation Models. It allows scripts to perform on-device AI tasks such as text generation, structured JSON output, and streaming responses.

This API encapsulates system-level language model capabilities and supports:

- On-device AI inference (Apple Intelligence)
- JSON Schema structured output
- Streaming token responses
- Session-level resource management
- Controlled generation parameters

`LanguageModelSession` is a global API and does not require importing from the `scripting` module.

***

## Availability

```ts
LanguageModelSession.isAvailable
```

Indicates whether Foundation Models are available on the current device.

Return value:

```ts
boolean
```

Notes:

- Only devices supporting Apple Intelligence will return `true`.
- You should check availability before creating a session.

Example:

```ts
if (!LanguageModelSession.isAvailable) {
  console.log("LanguageModelSession is not available on this device")
}
```

***

## Creating a Session

```ts
new LanguageModelSession(options?)
```

Parameters:

```ts
{
  instructions?: string
}
```

Description:

- Creates a new language model session.
- `instructions` act as system-level guidance controlling model behavior.
- Instructions remain active throughout the session lifecycle.

Example:

```ts
const session = new LanguageModelSession({
  instructions: "You are a professional financial assistant."
})
```

***

## Properties

## isResponding

```ts
readonly isResponding: boolean
```

Description:

- Indicates whether the model is currently generating a response.
- Useful for managing UI state.

***

## Prewarming the Model

```ts
prewarm(promptPrefix?: string): void
```

Description:

- Requests the system to load required model resources in advance.
- Reduces initial response latency.
- Optionally caches a prompt prefix.

Parameters:

```ts
promptPrefix?: string
```

Example:

```ts
session.prewarm("You are a JSON extraction assistant")
```

Recommended use cases:

- Before the user initiates an AI task
- When reducing first-token latency is important

***

## Generating Responses

```ts
respond<T>(prompt, options?)
```

Returns:

```ts
Promise<{
  content: string
  json: T | null
}>
```

Description:

- Produces a complete response.
- Supports structured JSON output via schema validation.
- Automatically attempts JSON parsing.

Parameters:

```ts
{
  temperature?: number
  maxResponseTokens?: number
  schema?: JSONSchemaObject
}
```

Parameter details:

- `temperature`

  - Range: 0.0 \~ 1.0
  - Higher values increase randomness.
- `maxResponseTokens`

  - Maximum number of tokens to generate.
- `schema`

  - Expected JSON structure.
  - If generated content is not valid JSON, `json` will be `null`.

***

## Structured Output Example

```ts
const session = new LanguageModelSession()

const result = await session.respond(
  `Parse the following receipt:
  Parking fee
  Convention Center
  2026-02-09 12:23:45
  ¥19
  Credit card payment`,
  {
    schema: {
      type: "object",
      description: "Receipt JSON",
      properties: {
        amount: { type: "number", description: "Amount" },
        category: { type: "string", description: "Category" },
        address: { type: "string", description: "Address", required: false },
        isIncome: { type: "boolean", decription: "Whether it is an income" }
      }
    }
  }
)

console.log(result.content)
console.log(result.json)
```

***

## Streaming Responses

```ts
streamResponse(prompt, options?)
```

Returns:

```ts
Promise<ReadableStream>
```

Description:

- Produces streaming output.
- Suitable for chat interfaces or incremental display.

Parameters:

```ts
{
  temperature?: number
  maxResponseTokens?: number
}
```

Example:

```ts
const stream = await session.streamResponse(
  "Tell a joke about a dog",
  { temperature: 0.7 }
)

let fullText = ""

for await (const chunk of stream) {
  console.log(chunk)
  fullText = chunk
}
```

***

## Releasing Resources

```ts
dispose(): void
```

Description:

- Releases resources associated with the session.
- Recommended after finishing usage to reduce memory usage.

Example:

```ts
session.dispose()
```

***

## Complete Example

```tsx
import { Script } from "scripting"

console.present().then(() => {
  Script.exit()
})

async function run() {

  if (!LanguageModelSession.isAvailable) {
    console.log("Not supported on this device")
    return
  }

  const session = new LanguageModelSession({
    instructions: "You are a structured data extraction assistant."
  })

  session.prewarm("Parse receipt")

  const result = await session.respond(
    "Parse: Parking fee Convention Center ¥19",
    {
      temperature: 0.2,
      schema: {
        type: "object",
        description: "JSON result",
        properties: {
          amount: { type: "number", description: "Amount" },
          category: { type: "string", description: "Category" }
        }
      }
    }
  )

  console.log(result.json)

  const stream = await session.streamResponse(
    "Tell a joke about a dog"
  )

  for await (const text of stream) {
    console.log(text)
  }

  session.dispose()
}

run()
```

***

## Best Practices

- Reuse a session for multiple requests when possible.
- Call `prewarm` before first use to reduce latency.
- Use `schema` for reliable structured output.
- Use `streamResponse` for long-form or interactive responses.
- Call `dispose` when finished to release resources.



---
url: /guide/Changelog/2.4.8/Reminder.md
---

# Reminder

The `Reminder` API provides the ability to create, edit, and manage reminders in the iOS calendar system.
It supports configuring due dates through `DateComponents`, assigning priorities, adding notes, managing recurrence rules, working with alarms, and tracking completion state.
This API is suitable for a wide range of task and schedule reminder scenarios.

***

## 1. Class: `Reminder`

The `Reminder` class represents an individual reminder item and provides properties and methods to read and modify its data.

***

## 2. Properties

### identifier: string

A unique identifier assigned by the system (read-only).

### calendar: Calendar | null

The calendar to which the reminder belongs.
The calendar can be null if the reminder is not associated with a calendarm, but you must do not set the calendar to null.

### title: string

The title or summary of the reminder.

### notes: string | null

Optional notes providing additional context.

***

## Completion State

### isCompleted: boolean

Indicates whether the reminder is marked as completed.

- Setting this property to `true` automatically sets `completionDate` to the current date.
- Setting it to `false` sets `completionDate` to `null`.

Special consideration:
If a reminder is completed on another device or client, `isCompleted` may be `true` while `completionDate` remains `null`.

### completionDate: Date | null

The date on which the reminder was completed.

- Assigning a date sets `isCompleted = true`.
- Assigning `null` clears the completed state.

***

## Due Date

### dueDateComponents: DateComponents | null

Represents the reminder’s due date using date components.
Supports partially specified date or time fields.
Useful for date-based or recurring reminders.

You may use `DateComponents.isValidDate` to check whether the components form a valid date.

### dueDate: Date | null

Deprecated.
Use `dueDateComponents` instead.
You can read the equivalent date using `dueDateComponents?.date`.

### dueDateIncludesTime: boolean

Deprecated.
Use `dueDateComponents?.hour != null && dueDateComponents?.minute != null` to determine whether the due date includes a time component.

***

## Priority

### priority: number

An integer representing the reminder’s priority.
Higher values typically indicate greater importance or urgency.

***

## Recurrence

### recurrenceRules: RecurrenceRule\[] | null

An array of recurrence rules associated with the reminder.

### hasRecurrenceRules: boolean

Indicates whether the reminder contains recurrence rules (read-only).

***

## Alarms

### alarms: EventAlarm\[] | null

A collection of alarms associated with the reminder.
Alarms may be based on:

- absolute dates
- relative offsets
- structured locations (geofence triggers)

### hasAlarm: boolean

Indicates whether the reminder contains any alarms.

***

## Attendees

### attendees: EventParticipant\[] | null

An array of attendee objects (read-only).
Not all reminder sources support attendee data.

### hasAttendees: boolean

Indicates whether the reminder has attendees.

***

## State Indicators

### hasNotes: boolean

Indicates whether the reminder contains notes.

### hasChanges: boolean

Indicates whether the reminder or any of its nested objects contains unsaved changes.

***

## 3. Instance Methods

### addAlarm(alarm: EventAlarm): void

Adds an alarm to the reminder.

### removAlarm(alarm: EventAlarm): void

Removes the specified alarm.
(Method name is `removAlarm`.)

***

### addRecurrenceRule(rule: RecurrenceRule): void

Adds a recurrence rule.

### removeRecurrenceRule(rule: RecurrenceRule): void

Removes a recurrence rule.

***

### `save(): Promise<void>`

Saves changes to the reminder.
If the reminder has not been saved before, it is added to its associated calendar.

### `remove(): Promise<void>`

Deletes the reminder from the calendar.

***

## 4. Static Methods

### `Reminder.get(identifier: string): Promise<Reminder | null>`

Returns a reminder by its identifier, or `null` if not found.

***

### `Reminder.getAll(calendars?: Calendar[]): Promise<Reminder[]>`

Returns all reminders, optionally filtered by the specified calendars.

***

### `Reminder.getIncompletes(options?): Promise<Reminder[]>`

Returns incomplete reminders filtered by due date range and/or calendar set.

Options:

- `startDate?: Date`
  Includes reminders whose due date is after this date.

- `endDate?: Date`
  Includes reminders whose due date is before this date.

- `calendars?: Calendar[]`
  Specifies which calendars to search.

This method does not expand recurrence rules; it only returns reminders with concrete due dates.

***

### `Reminder.getCompleteds(options?): Promise<Reminder[]>`

Returns completed reminders filtered by completion date range and/or calendar set.

Options:

- `startDate?: Date`
  Includes reminders completed after this date.

- `endDate?: Date`
  Includes reminders completed before this date.

- `calendars?: Calendar[]`
  Specifies which calendars to search.

***

## 5. Usage Examples

## Creating a Reminder with DateComponents

```ts
const reminder = new Reminder()
reminder.title = "Prepare meeting materials"
reminder.notes = "Finish before Monday’s team meeting"

reminder.dueDateComponents = new DateComponents({
  year: 2025,
  month: 10,
  day: 6,
  hour: 9,
  minute: 30,
})

reminder.priority = 2
await reminder.save()
```

***

## Creating a Date-Only Reminder

```ts
reminder.dueDateComponents = new DateComponents({
  year: 2025,
  month: 10,
  day: 6,
})
```

***

## Creating DateComponents from a Date

```ts
const now = new Date()
reminder.dueDateComponents = DateComponents.fromDate(now)
```

***

## Fetching All Reminders

```ts
const reminders = await Reminder.getAll()
for (const r of reminders) {
  console.log(`Reminder: ${r.title}`)
}
```

***

## Fetching Incomplete Reminders

```ts
const incompletes = await Reminder.getIncompletes({
  startDate: new Date("2025-01-01"),
  endDate: new Date("2025-01-31"),
})
```

***

## Marking a Reminder as Completed

```ts
reminder.isCompleted = true
await reminder.save()
```

***

## Deleting a Reminder

```ts
await reminder.remove()
```

***

## 6. Additional Notes

### Date Management

Using `dueDateComponents` is recommended for all due-date handling.
It supports:

- date-only values
- date with time
- partial components
- validity checks through `isValidDate`

### Recurrence

Reminder queries do not expand recurrence rules.
They operate only on the reminder objects that have concrete due dates.
Recurrence rules can be added or removed through the API.

### Alarms

Alarms may be absolute, relative, or location-based, and are shared with the `CalendarEvent` API.

### Attendees

Some reminder sources do not support attendee data; in such cases, the attendees array may be `null`.



---
url: /guide/Changelog/2.4.8/Rich Text.md
---

# Rich Text

The `Text` component supports rendering rich text using the `styledText` property, allowing fine-grained control beyond plain text or Markdown rendering.

With `StyledText`, developers can:

- Apply detailed text styling such as fonts, colors, strokes, and decorations
- Build nested rich text structures
- Add tappable links or gesture handlers
- Control paragraph-level layout and typography

The newly introduced `paragraphStyle` field provides advanced paragraph layout control. It maps conceptually to native paragraph layout systems (similar to `NSParagraphStyle`) and enables:

- Text alignment control
- Line spacing and paragraph spacing
- First-line indentation
- Truncation strategies
- Automatic hyphenation
- Multi-language writing direction support

***

## StyledText

### Type Definition

```ts
type StyledText = {
  font?
  fontDesign?
  fontWeight?
  italic?
  bold?
  baselineOffset?
  kerning?
  monospaced?
  monospacedDigit?

  underlineColor?
  underlineStyle?

  strokeColor?
  strokeWidth?

  strikethroughColor?
  strikethroughStyle?

  foregroundColor?
  backgroundColor?

  paragraphStyle?: ParagraphStyle

  content: string | (string | StyledText)[]
  link?: string
  onTapGesture?: () => void
}
```

***

### content

Defines the text content.

Can be:

- A string
- An array of strings and nested `StyledText` objects

Example:

```tsx
<Text
  styledText={{
    content: [
      "Hello ",
      {
        content: "world",
        bold: true,
        foregroundColor: "blue"
      }
    ]
  }}
/>
```

***

### Font-related Properties

| Property        | Description          |
| --------------- | -------------------- |
| font            | Font style           |
| fontDesign      | Font design variant  |
| fontWeight      | Font weight          |
| italic          | Applies italic style |
| bold            | Applies bold style   |
| baselineOffset  | Baseline offset      |
| kerning         | Character spacing    |
| monospaced      | Monospaced font      |
| monospacedDigit | Monospaced digits    |

***

### Decoration Properties

#### Underline

```ts
underlineColor
underlineStyle
```

Supported `UnderlineStyle` values:

- single
- double
- thick
- byWord
- patternDash
- patternDashDot
- patternDashDotDot
- patternDot

***

#### Strikethrough

```ts
strikethroughColor
strikethroughStyle
```

***

#### Stroke (Outline)

```ts
strokeColor
strokeWidth
```

***

### Color Properties

```ts
foregroundColor
backgroundColor
```

***

### Interaction Properties

#### link

Defines a URL link.

#### onTapGesture

Tap gesture callback.

***

## ParagraphStyle

### Overview

`paragraphStyle` controls paragraph-level typography and layout behavior.

Recommended for:

- Multi-line text layouts
- Reading interfaces
- Rich typography layouts
- Multi-language content

***

### alignment

Text alignment.

```ts
alignment?: "left" | "center" | "right" | "justified" | "natural"
```

- left: left-aligned
- center: centered
- right: right-aligned
- justified: fully justified
- natural: system default

***

### firstLineHeadIndent

Indentation applied only to the first line.

```ts
firstLineHeadIndent?: number
```

Example:

```tsx
paragraphStyle: {
  firstLineHeadIndent: 20
}
```

***

### headIndent

Left indentation applied to lines except the first.

***

### tailIndent

Right-side indentation.

Note:

- Positive values are measured from the left
- Negative values are measured from the right

***

### paragraphSpacing

Additional spacing between paragraphs.

***

### lineSpacing

Line spacing between lines.

***

### lineBreakMode

Text truncation and wrapping strategy.

```ts
lineBreakMode?:
  | "byCharWrapping"
  | "byClipping"
  | "byTruncatingHead"
  | "byTruncatingTail"
  | "byTruncatingMiddle"
```

Descriptions:

- byCharWrapping: wrap by character
- byClipping: clip overflow
- byTruncatingHead: truncate at head
- byTruncatingTail: truncate at tail
- byTruncatingMiddle: truncate in middle

***

### minLineHeight / maxLineHeight

Control minimum and maximum line height.

***

### lineHeightMultiple

Multiplier applied to the natural line height.

Example:

```ts
lineHeightMultiple: 1.5
```

***

### baseWritingDirection

Writing direction.

```ts
baseWritingDirection?: "natural" | "leftToRight" | "rightToLeft"
```

Useful for:

- RTL language support
- Mixed-direction text

***

### hyphenationFactor

Hyphenation level (0–1).

Higher values increase likelihood of word splitting.

***

### usesDefaultHyphenation

Whether to use system default hyphenation behavior.

***

## Full Example

```tsx
<Text
  styledText={{
    content: "This is a rich text paragraph example demonstrating paragraphStyle.",
    foregroundColor: "label",
    paragraphStyle: {
      alignment: "justified",
      firstLineHeadIndent: 20,
      lineSpacing: 6,
      paragraphSpacing: 12,
      lineHeightMultiple: 1.4
    }
  }}
/>
```

***

## Usage Recommendations

### When to Use paragraphStyle

Recommended scenarios:

- Long-form reading interfaces
- Article typography
- Chat bubble layout improvements
- Multi-language typesetting
- Custom text layout

***

### Choosing Between styledText and Markdown

| Scenario                       | Recommendation              |
| ------------------------------ | --------------------------- |
| Simple formatting              | Markdown                    |
| Highly customizable styling    | styledText                  |
| Paragraph-level layout control | styledText + paragraphStyle |

***

### Performance Tips

- Avoid excessively deep nesting
- Reuse style objects when possible
- For long content, consider splitting into segments



---
url: /guide/Changelog/2.4.8/Slider/index.md
---

# Slider

The `Slider` component allows users to select a value from a bounded linear range of values. You can configure the slider by setting the minimum value, maximum value, step size, and the current value. The component also supports custom labels to describe the minimum and maximum values, as well as the slider itself. Additionally, it provides callbacks for handling value changes and editing state changes.

## SliderProps Type

`SliderProps` defines the properties for the `Slider` component, which includes the following fields:

- **min** (`number`):
  - The minimum value of the slider.
  - **Required**.

- **max** (`number`):
  - The maximum value of the slider.
  - **Required**.

- **step** (`number`):
  - The step size between each valid value of the slider.
  - **Optional**, defaults to `1`.

- **value** (`number`):
  - The selected value within bounds.
  - **Required**, must be between `min` and `max`.

- **onChanged** (`(value: number) => void`):
  - A callback function that is called whenever the slider value changes.
  - **Required**, called each time the value is updated.

- **onEditingChanged** (`(value: boolean) => void`):
  - An optional callback function called when the editing state of the slider changes.
  - `value` is `true` when editing starts, and `false` when editing ends.

- **label** (`VirtualNode`):
  - An optional view that describes the purpose of the slider. Even if some slider styles do not display the label, the system uses it for accessibility purposes (e.g., VoiceOver).
  - **Optional**.

- **minValueLabel** (`VirtualNode`):
  - An optional view that describes the minimum value of the slider.
  - **Optional**, used only in the `SliderWithRangeValueLabelProps` mode.

- **maxValueLabel** (`VirtualNode`):
  - An optional view that describes the maximum value of the slider.
  - **Optional**, used only in the `SliderWithRangeValueLabelProps` mode.

## SliderWithRangeValueLabelProps Type

`SliderWithRangeValueLabelProps` is a type that defines additional properties for labeling the slider's range. It includes:

- **label** (`VirtualNode`):
  - The label that describes the purpose of the slider.

- **minValueLabel** (`VirtualNode`):
  - The label that describes the minimum value of the slider.

- **maxValueLabel** (`VirtualNode`):
  - The label that describes the maximum value of the slider.

## Other Properties

- **sliderThumbVisibility** (`Visibility`):
  - Sets the visibility of the slider's thumb.
  - iOS 26+ only.

## Usage Example

Here’s an example of using the `Slider` component:

```tsx
import { Slider } from 'scripting'

const ExampleSlider = () => {
  const [value, setValue] = useState(50)

  const handleChange = (newValue: number) => {
    setValue(newValue)
  }

  return (
    <Slider
      min={0}
      max={100}
      value={value}
      onChanged={handleChange}
      label={<Text>Adjust Volume</Text>}
      minValueLabel={<Text>0</Text>}
      maxValueLabel={<Text>100</Text>}
    />
  )
}
```

In this example, the `Slider` component is configured with a range from `0` to `100`, with the default value set to `50`. Labels for the slider's purpose, as well as the minimum and maximum values, are provided.

## Important Notes

- The `min` and `max` properties of the `Slider` must be numeric, and the `value` must be within this range.
- The `onChanged` callback will trigger whenever the slider's value changes, passing the new value.
- If you use `SliderWithRangeValueLabelProps`, you must provide appropriate view elements for `minValueLabel` and `maxValueLabel`.

## Summary

The `Slider` component is a versatile UI control suitable for scenarios where the user needs to select a numerical value. With its flexible properties and callbacks, it can handle a wide range of use cases, especially when labels for the minimum, maximum values, or the slider itself are needed.



---
url: /guide/Changelog/2.4.8/Slider/index_example.md
---

# Example

```tsx
import { useState, Slider, Text, VStack, NavigationStack, Navigation, Script } from "scripting"

function Example() {
  const [value, setValue] = useState(15)

  return <NavigationStack>
    <VStack
      navigationTitle={"Slider"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Slider
        min={0}
        max={100}
        value={value}
        onChanged={setValue}
        label={<Text>{value}</Text>}
        minValueLabel={<Text>0</Text>}
        maxValueLabel={<Text>100</Text>}
      />
      <Text>Current value: {value}</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Changelog/2.4.9/Assistant Tool With Interactive UI.md
---

# Assistant Tool With Interactive UI

AssistantTool supports interactive UI tools that render custom in-tool interfaces and return structured results after user interaction.

This mode is useful when the Assistant needs user decisions that cannot be expressed reliably as plain text, such as option selection, confirmation details, staged forms, or visual previews.

***

## 1. Configuration in `assistant_tool.json`

To enable interactive UI rendering:

```json
{
  "displayName": "Select Options",
  "id": "select_options",
  "description": "Ask user to select one or more options.",
  "icon": "checklist",
  "color": "systemTeal",
  "parameters": [],
  "requireApproval": false,
  "autoApprove": true,
  "scriptEditorOnly": false,
  "supportsUIRender": true,
  "keepRenderingAfterComplete": false
}
```

### Key fields

- `supportsUIRender: true`
  The tool is expected to provide a UI renderer via `AssistantTool.registerUIView(...)`.

- `keepRenderingAfterComplete`
  Controls whether the UI should remain rendered after `response(...)` returns the result.

***

## 2. Registration API

Interactive UI tools register a function component:

```ts
AssistantTool.registerUIView<P>(view)
```

Where `view` receives:

```ts
type UIProps<P> = {
  params: P
  response: (result: AssistantToolResponseResult) => void
  isAutoApprove: boolean
  scriptEditorProvider?: ScriptEditorProvider
}
```

The component should render synchronously and return a `VirtualNode`.

***

## 3. Returning Results from UI

Use `response(result)` when the user completes interaction.

```ts
type AssistantToolResponseResult = {
  success: boolean
  output: {
    userParts?: AssistantToolOutputPart[]
    assistantParts?: AssistantToolOutputPart[]
  }
}
```

Notes:

- `response` can be called only once; later calls are ignored.
- `userParts` are shown to users.
- `assistantParts` are sent back to the Assistant for reasoning.

***

## 4. State Management During UI Interaction

Interactive UI tools can persist state per tool call:

```ts
AssistantTool.getState(key)
AssistantTool.setState(key, value)
AssistantTool.removeState(key)
AssistantTool.clearState()
```

State is JSON-serializable and persisted with tool-call history.

Typical uses:

- selected options
- current step index
- temporary form values
- partial progress flags

***

## 5. Relationship with Approval

If `requireApproval: true` and `supportsUIRender: true`:

1. Approval request flow runs first
2. If approved, UI renderer is invoked
3. If rejected, renderer is not invoked

This keeps sensitive operations controllable while still allowing rich interaction after consent.

***

## 6. Auto-Approve Behavior

`isAutoApprove` is passed to `UIProps`.

Use it when your tool can safely skip interaction in specific cases and return immediately:

```ts
if (isAutoApprove && canUseDefaultResult) {
  response({
    success: true,
    output: {
      userParts: [{ type: "text", text: "Default option selected." }],
      assistantParts: [{ type: "text", text: "Used default selection in auto-approve mode." }]
    }
  })
}
```

***

## 7. Minimal Example

```ts
type Params = { title: string; options: string[] }

function ToolView({ params, response }: AssistantTool.UIProps<Params>) {
  const [selected, setSelected] = useState<string | null>(
    AssistantTool.getState<string>("selected")
  )

  const choose = (value: string) => {
    setSelected(value)
    AssistantTool.setState("selected", value)
  }

  return (
    <VStack spacing={8}>
      <Text>{params.title}</Text>
      {params.options.map(option => (
        <Button
          title={selected === option ? `✓ ${option}` : option}
          action={() => choose(option)}
        />
      ))}
      <Button
        title="Confirm"
        action={() => {
          response({
            success: true,
            output: {
              userParts: [{ type: "text", text: `Selected: ${selected ?? "none"}` }],
              assistantParts: [{ type: "text", text: JSON.stringify({ selected }) }]
            }
          })
        }}
      />
    </VStack>
  )
}

AssistantTool.registerUIView(ToolView)
```

***

## 8. Testing UI Tools

`registerUIView` returns a UI test function:

```ts
const testUI = AssistantTool.registerUIView(ToolView)

testUI(params, {
  isAutoApprove: false,
  initialState: { selected: "staging" },
  screenshot: true
})
```

In test mode:

- UI is rendered in a preview panel
- close action returns a cancellation result
- optional screenshot capture is supported

***

## 9. Recommended Practices

- Keep UI compact; it is embedded inside the tool container.
- Prefer card-style layouts over large scrolling containers.
- Return concise `assistantParts` with stable structure.
- Use `userParts` for user-facing summaries.
- Persist only state needed to restore interaction.
- Avoid heavy side effects inside render functions.



---
url: /guide/Changelog/2.4.9/CalendarEvent.md
---

# CalendarEvent

The `CalendarEvent` API enables creating, reading, editing, and managing events in the iOS calendar.
Developers can configure event details such as title, time, location, participants, recurrence rules, alarms, availability, and structured locations, and can display system-provided interfaces for creating or editing events.

***

## 1. Types

## EventParticipant

Represents an attendee of the event:

- `isCurrentUser: boolean` – Indicates whether this attendee represents the current user
- `name?: string` – Display name
- `role: ParticipantRole` – The attendee’s role
- `type: ParticipantType` – The type of attendee
- `status: ParticipantStatus` – The attendee’s participation status

### ParticipantRole

- `chair`
- `nonParticipant`
- `optional`
- `required`
- `unknown`

### ParticipantType

- `group`
- `person`
- `resource`
- `room`
- `unknown`

### ParticipantStatus

- `unknown`
- `pending`
- `accepted`
- `declined`
- `tentative`
- `delegated`
- `completed`
- `inProcess`

***

## EventAvailability

Indicates how the event affects the user’s availability:

- `notSupported`
- `busy`
- `free`
- `tentative`
- `unavailable`

***

## EventStructuredLocation

Describes a location that can be used for location-based alarms.

- `title: string | null` – A name for the location
- `geoLocation: LocationInfo | null` – Latitude and longitude
- `radius: number` – Radius in meters for the geofence trigger

***

## AlarmProximity

Describes how a location alarm triggers:

- `none`
- `enter`
- `leave`

***

## 2. EventAlarm

`CalendarEvent` supports attaching one or more `EventAlarm` instances.
Alarms may be:

- absolute date alarms
- relative alarms (relative to the start of the event)
- location-based alarms using geofence triggers

See the EventAlarm documentation for detailed information.

***

## 3. CalendarEvent Class

## Constructor

```ts
new(): CalendarEvent
```

Creates an in-memory event instance.
Call `save()` to persist it into the calendar.

***

## 4. Properties

## General Information

### identifier: string

A unique identifier for the event.

### title: string

The title of the event.

### notes: string | null

Additional notes.

### url: string | null

A URL associated with the event.

### calendar: Calendar | null

The calendar to which the event belongs.
This property cannot be set to `null`. To remove an event, use `remove()`.

***

## Time and Location

### isAllDay: boolean

Indicates whether the event lasts all day.

### startDate: Date

The start date and time.

### endDate: Date

The end date and time.

### timeZone: string | null

The event’s time zone.

### location: string | null

A text description of the location.

### structuredLocation: EventStructuredLocation | null

A structured location that includes geolocation data for alarms.

***

## Event Metadata

### creationDate: Date | null

The date when the event was created.

### lastModifiedDate: Date | null

The date of the most recent modification.

### occurrenceDate: Date

For recurring events, this is the original scheduled date of this specific occurrence.

### isDetached: boolean

Indicates whether this event represents a modified occurrence of a recurring series.

***

## Participants and Availability

### attendees: EventParticipant\[] | null

An array of attendees.

### organizer: EventParticipant | null

The organizer of the event.

### hasAttendees: boolean

Indicates whether the event has attendees.

### availability: EventAvailability

Indicates the event’s impact on availability.

***

## Alarms

### alarms: EventAlarm\[] | null

The alarms associated with the event.

### hasAlarm: boolean

Indicates whether the event has any alarms.

***

## Recurrence

### recurrenceRules: RecurrenceRule\[] | null

The recurrence rules of the event.

### hasRecurrenceRules: boolean

Indicates whether the event has recurrence rules.

***

## Additional State Flags

### hasNotes: boolean

Indicates whether the event contains notes.

### hasChanges: boolean

Indicates whether the event or any nested objects contain unsaved changes.

***

## 5. Instance Methods

## Alarm Management

### addAlarm(alarm: EventAlarm): void

Adds an alarm to the event.

### removAlarm(alarm: EventAlarm): void

Removes an alarm from the event.
(Note: The method name is `removAlarm`.)

***

## Recurrence Management

### addRecurrenceRule(rule: RecurrenceRule): void

Appends a recurrence rule.

### removeRecurrenceRule(rule: RecurrenceRule): void

Removes a recurrence rule.

***

## Saving and Deleting

### `save(): Promise<void>`

Saves the event to the calendar.

### `remove(): Promise<void>`

Removes the event from the calendar.

***

## Editing UI

### `presentEditView(): Promise<EventEditViewAction>`

Displays the system event-editing interface and resolves with:

- `saved`
- `deleted`
- `canceled`

***

## 6. Static Methods

## `get(identifier: string): Promise<CalendarEvent | null>`

Fetches a calendar event by its identifier.

### `getAll(startDate: Date, endDate: Date, calendars?: Calendar[]): Promise<CalendarEvent[]>`

Fetches calendar events within a given date range.

- Provide an array of calendars to restrict the search
- Use `null` or omit the parameter to search all calendars

***

### `presentCreateView(): Promise<CalendarEvent | null>`

Displays the system interface for creating a new event.

- Returns the created event if saved
- Returns `null` if canceled

***

## 7. Usage Examples

## Creating and Saving an Event

```ts
const defaultCalendar = await Calendar.defaultForEvents()
const event = new CalendarEvent()
event.title = "Team Meeting"
event.calendar = defaultCalendar!
event.startDate = new Date("2024-01-15T09:00:00")
event.endDate = new Date("2024-01-15T10:00:00")
event.location = "Conference Room"

await event.save()
```

***

## Adding a Recurrence Rule

```ts
const rule = RecurrenceRule.create({
  frequency: "weekly",
  interval: 1,
  daysOfTheWeek: ["monday", "wednesday", "friday"],
  end: RecurrenceEnd.fromDate(new Date("2024-12-31")),
})

event.addRecurrenceRule(rule)
await event.save()
```

***

## Adding an Alarm

```ts
const alarm = EventAlarm.fromRelativeOffset(-600)
event.addAlarm(alarm)
await event.save()
```

***

## Fetching Events

```ts
const events = await CalendarEvent.getAll(
  new Date("2024-01-01"),
   new Date("2024-01-31")
 )

for (const e of events) {
  console.log(`Event: ${e.title}, Starts: ${e.startDate}`)
}
```

***

## Presenting the Create View

```ts
const created = await CalendarEvent.presentCreateView()
if (created) {
  console.log("Created event:", created.title)
}
```

***

## Editing an Existing Event

```ts
const result = await event.presentEditView()
console.log("Edit action:", result)
```

***

## Removing an Event

```ts
await event.remove()
console.log("Event removed")
```

***

## 8. Additional Notes

### Time Zone Considerations

When working with events that span time zones, set `timeZone` explicitly to avoid incorrect scheduling or display.

### Recurring Events

Editing individual occurrences of a recurring event may produce a detached instance.
Use `occurrenceDate` to determine the original date of the modified occurrence.

### Attendees

Attendee data depends on the calendar source (iCloud, Exchange, etc.) and may vary in availability.

### Structured Location

When using location-based alarms, the user must grant the necessary location permissions.



---
url: /guide/Changelog/2.4.9/HeadphoneMotionManager.md
---

# HeadphoneMotionManager

The `HeadphoneMotionManager` namespace streams motion data from headphones that support spatial audio with dynamic head tracking, such as **AirPods Pro**, **AirPods Max**, and **AirPods 3**.

It wraps Apple's `CMHeadphoneMotionManager` and exposes attitude, rotation rate, user acceleration, gravity, and connection events to your scripts.

***

## Properties

| Name          | Type      | Description                                                                                                                         |
| ------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `isAvailable` | `boolean` | Whether headphone motion data is currently available. Returns `false` on simulators or when no compatible headphones are reachable. |
| `isActive`    | `boolean` | Whether motion updates are currently being delivered.                                                                               |

> Authorization is handled internally — your script does not need to query or request permission. The first call to `startDeviceMotionUpdates` triggers the system prompt automatically; if the user later denies access, subsequent calls reject with a clear error.

***

## Methods

### `startDeviceMotionUpdates(options): Promise<boolean>`

Begin streaming motion samples. Resolves with `true` once the stream is started.

```ts
startDeviceMotionUpdates(options: {
  onUpdate: (motion: HeadphoneDeviceMotion) => void
  onError?: (error: Error) => void
}): Promise<boolean>
```

| Option   | Type                                      | Required | Description                                             |
| -------- | ----------------------------------------- | -------- | ------------------------------------------------------- |
| onUpdate | `(motion: HeadphoneDeviceMotion) => void` | Yes      | Called for every motion sample.                         |
| onError  | `(error: Error) => void`                  | No       | Called if CoreMotion reports an error during streaming. |

Only one active subscription is supported at a time. Calling `startDeviceMotionUpdates` again replaces the previous handler.

### `stopDeviceMotionUpdates(): void`

Stop the current motion stream. Safe to call when no stream is active.

### `addListener(event, listener): void`

Subscribe to a connection event.

```ts
addListener(event: 'connect' | 'disconnect', listener: () => void): void
```

- `connect` fires when supported headphones become reachable.
- `disconnect` fires when they go away.

### `removeListener(event, listener): void`

Remove a previously registered listener. Pass the same function reference that was used with `addListener`.

***

## Data Types

```ts
type HeadphoneDeviceMotion = {
  timestamp: number          // seconds since device boot, monotonic
  attitude: {
    pitch: number            // radians
    roll: number             // radians
    yaw: number              // radians
    quaternion: { x: number; y: number; z: number; w: number }
  }
  rotationRate: { x: number; y: number; z: number }       // rad/s
  userAcceleration: { x: number; y: number; z: number }   // G
  gravity: { x: number; y: number; z: number }            // G
  sensorLocation: 'default' | 'leftHeadphone' | 'rightHeadphone'
  heading?: number                                        // degrees [0, 360)
  magneticField?: {
    field: { x: number; y: number; z: number }
    accuracy: 'uncalibrated' | 'low' | 'medium' | 'high'
  }
}
```

***

## Example

```ts
if (!HeadphoneMotionManager.isAvailable) {
  console.log("Headphone motion is not available on this device.")
} else {
  HeadphoneMotionManager.addListener('connect', () => {
    console.log("Headphones connected.")
  })
  HeadphoneMotionManager.addListener('disconnect', () => {
    console.log("Headphones disconnected.")
  })

  await HeadphoneMotionManager.startDeviceMotionUpdates({
    onUpdate: motion => {
      const yawDeg = motion.attitude.yaw * (180 / Math.PI)
      console.log(`yaw: ${yawDeg.toFixed(1)}°`)
    },
    onError: err => {
      console.error("motion error:", err.message)
    }
  })

  // Stop when finished:
  // HeadphoneMotionManager.stopDeviceMotionUpdates()
}
```

***

## Notes

- `Info.plist` must include `NSMotionUsageDescription`. Scripting already declares it.
- The first call to `startDeviceMotionUpdates` automatically triggers the system Motion & Fitness permission prompt. If the user denies it (now or later from Settings), `startDeviceMotionUpdates` rejects with a clear error so your script can surface a helpful message.



---
url: /guide/Changelog/2.4.9/JWT.md
---

# JWT

The `JWT` class provides synchronous APIs to sign, verify, and decode JSON Web Tokens.

***

## Constructor

```ts
new JWT(options?: {
  algorithm?: JWTAlgorithm
  secret?: string | Data
  privateKey?: string | Data
  publicKey?: string | Data
  passphrase?: string
  kid?: string
})
```

### Parameters

| Name       | Type           | Required | Description                                                      |
| ---------- | -------------- | -------- | ---------------------------------------------------------------- |
| algorithm  | JWTAlgorithm   | No       | Default signing algorithm. Defaults to `HS256`.                  |
| secret     | string \| Data | No       | Shared secret used by `HS256` / `HS384` / `HS512`.               |
| privateKey | string \| Data | No       | Private key used by `RS*` / `PS*` / `ES*` / `EdDSA` signing.     |
| publicKey  | string \| Data | No       | Public key used by `RS*` / `PS*` / `ES*` / `EdDSA` verification. |
| passphrase | string         | No       | Optional passphrase field for key workflows.                     |
| kid        | string         | No       | Optional key ID written into JWT header.                         |

### Supported Algorithms

- HMAC: `HS256`, `HS384`, `HS512`
- RSA PKCS#1 v1.5: `RS256`, `RS384`, `RS512`
- RSA-PSS: `PS256`, `PS384`, `PS512`
- ECDSA: `ES256`, `ES384`, `ES512`
- EdDSA: `EdDSA` (Ed25519)

***

## Methods

### `sign(payload, options?): string`

Creates a JWT string synchronously.

```ts
sign(payload: Record<string, any>, options?: {
  algorithm?: JWTAlgorithm
  header?: Record<string, any>
  issuer?: string
  subject?: string
  audience?: string | string[]
  jwtId?: string
  nonce?: string
  notBefore?: number | string
  expiresIn?: number | string
  issuedAt?: number | string
  kid?: string
}): string
```

### `verify(token, options?): { header; payload }`

Verifies signature and standard claims synchronously. Throws on failure.

```ts
verify(token: string, options?: {
  algorithm?: JWTAlgorithm | JWTAlgorithm[]
  issuer?: string | string[]
  subject?: string
  audience?: string | string[]
  jwtId?: string
  nonce?: string
  clockTolerance?: number
  currentDate?: number | Date
}): {
  header: Record<string, any>
  payload: Record<string, any>
}
```

### `decode(token): { header; payload; signature; signingInput }`

Decodes JWT without signature verification.

```ts
decode(token: string): {
  header: Record<string, any>
  payload: Record<string, any>
  signature: string
  signingInput: string
}
```

***

## Example

```ts
const jwt = new JWT({
  algorithm: "HS256",
  secret: "my-secret",
  kid: "k1"
})

const token = jwt.sign(
  { userId: "u_123", role: "admin" },
  {
    issuer: "Scripting",
    audience: ["app", "web"],
    expiresIn: 3600
  }
)

const verified = jwt.verify(token, {
  issuer: "Scripting",
  audience: "app",
  algorithm: "HS256"
})

console.log(verified.header.alg)
console.log(verified.payload.userId)
```

***

## Error Handling

All methods are synchronous. If validation or cryptographic operations fail, `JWT` throws an `Error`.



---
url: /guide/Changelog/2.4.9/MediaLibrary.md
---

# MediaLibrary

The `MediaLibrary` module provides read-only access to the user's local media library, allowing scripts to query songs, albums, artists, and playlists, and retrieve artwork.

Important notes:

- The user must grant permission to access the media library.
- Only items available in the device media library are returned (including locally synced content, iTunes synced content, and downloaded Apple Music tracks).
- All returned data structures are read-only and cannot modify the system library.

***

## Data Models

### Item

Represents a single song.

```ts
type Item = {
  title: string
  persistentID: string
  artist?: string
  albumTitle?: string
  albumArtist?: string
  genre?: string
  composer?: string
  albumTrackNumber?: number
  albumTrackCount?: number
  discNumber?: number
  discCount?: number
  playbackDuration?: number
  playbackStoreID?: string
  isCloudItem?: boolean
  hasProtectedAsset?: boolean
}
```

Field descriptions:

- `title`: Song title
- `persistentID`: Unique local media library identifier (used for playback and artwork retrieval)
- `artist`: Performing artist
- `albumTitle`: Album name
- `albumArtist`: Album artist
- `genre`: Genre
- `composer`: Composer
- `albumTrackNumber`: Track number within the album
- `albumTrackCount`: Total track count of the album
- `discNumber`: Disc number
- `discCount`: Total disc count
- `playbackDuration`: Duration in seconds
- `playbackStoreID`: Apple Music Store ID (if available)
- `isCloudItem`: Indicates whether the item is cloud-based
- `hasProtectedAsset`: Indicates DRM-protected content

***

### Playlist

Represents a playlist.

```ts
type Playlist = {
  persistentID: string
  name: string
  trackCount: number
}
```

Field descriptions:

- `persistentID`: Unique playlist identifier
- `name`: Playlist name
- `trackCount`: Number of tracks

***

### Album

Represents an album.

```ts
type Album = {
  title: string
  artist?: string
  persistentID?: string
  trackCount?: number
}
```

Field descriptions:

- `title`: Album title
- `artist`: Album artist
- `persistentID`: Album identifier (may be unavailable in some cases)
- `trackCount`: Number of tracks

***

## Query Options

### SongQueryOptions

```ts
type SongQueryOptions = {
  limit?: number
  sortBy?:
    | "title"
    | "artist"
    | "albumTitle"
    | "playbackDuration"
    | "albumTrackNumber"
  ascending?: boolean
}
```

Description:

- `limit`: Maximum number of results
- `sortBy`: Field used for sorting
- `ascending`: Sort order (default is descending if not specified)

***

### AlbumQueryOptions

```ts
type AlbumQueryOptions = {
  limit?: number
  sortBy?: "title" | "artist" | "trackCount"
  ascending?: boolean
}
```

***

### PlaylistQueryOptions

```ts
type PlaylistQueryOptions = {
  limit?: number
  sortBy?: "name" | "trackCount"
  ascending?: boolean
}
```

***

### ArtistQueryOptions

```ts
type ArtistQueryOptions = {
  limit?: number
  ascending?: boolean
}
```

***

### SongFilter

Used to filter song queries.

```ts
type SongFilter = {
  title?: string
  artist?: string
  albumTitle?: string
  genre?: string
  composer?: string
  persistentID?: string
}
```

Notes:

- Supports exact match filtering.
- Multiple fields may be combined.

***

## API Methods

### getSongs

Query songs.

```ts
function getSongs(
  filter?: SongFilter,
  options?: SongQueryOptions
): Promise<Item[]>
```

Example:

```ts
const songs = await MediaLibrary.getSongs(
  { artist: "Taylor Swift" },
  { sortBy: "title", ascending: true, limit: 20 }
)

console.log(songs)
```

***

### getSongByPersistentID

Retrieve a single song by `persistentID`.

```ts
function getSongByPersistentID(
  persistentID: string
): Promise<Item | null>
```

Example:

```ts
const song = await MediaLibrary.getSongByPersistentID("123456789")

if (song) {
  console.log(song.title)
}
```

***

### getAlbums

Retrieve albums.

```ts
function getAlbums(
  options?: AlbumQueryOptions
): Promise<Album[]>
```

Example:

```ts
const albums = await MediaLibrary.getAlbums({
  sortBy: "title",
  ascending: true
})
```

***

### getAlbumSongs

Retrieve songs within a specific album.

```ts
function getAlbumSongs(
  albumTitle: string,
  options?: SongQueryOptions
): Promise<Item[]>
```

Example:

```ts
const tracks = await MediaLibrary.getAlbumSongs("1989", {
  sortBy: "albumTrackNumber",
  ascending: true
})
```

Notes:

- Matching is based on album title.
- If multiple albums share the same name, results may include tracks from all matching albums.

***

### getArtists

Retrieve artist names.

```ts
function getArtists(
  options?: ArtistQueryOptions
): Promise<string[]>
```

Example:

```ts
const artists = await MediaLibrary.getArtists({ limit: 50 })
```

***

### getArtistSongs

Retrieve songs by a specific artist.

```ts
function getArtistSongs(
  artist: string,
  options?: SongQueryOptions
): Promise<Item[]>
```

Example:

```ts
const songs = await MediaLibrary.getArtistSongs("Adele", {
  sortBy: "playbackDuration",
  ascending: false
})
```

***

### getPlaylists

Retrieve playlists.

```ts
function getPlaylists(
  options?: PlaylistQueryOptions
): Promise<Playlist[]>
```

Example:

```ts
const playlists = await MediaLibrary.getPlaylists({
  sortBy: "trackCount",
  ascending: false
})
```

***

### getPlaylistSongs

Retrieve songs within a playlist.

```ts
function getPlaylistSongs(
  playlistPersistentID: string,
  options?: SongQueryOptions
): Promise<Item[]>
```

Example:

```ts
const songs = await MediaLibrary.getPlaylistSongs("9988776655", {
  sortBy: "title"
})
```

***

### getArtwork

Retrieve artwork for a song.

```ts
function getArtwork(
  persistentID: string,
  size?: {
    width: number
    height: number
  }
): Promise<UIImage | null>
```

Description:

- Returns a `UIImage`.
- `size` specifies the desired render dimensions.
- Returns `null` if artwork is unavailable.

Example:

```ts
const image = await MediaLibrary.getArtwork("123456789", {
  width: 300,
  height: 300
})

if (image) {
  console.log("Artwork loaded")
}
```

***

## Best Practices

- Use `limit` to control result size for large queries.
- For playback workflows, store `persistentID` instead of entire item objects.
- Load artwork on demand rather than preloading in bulk.
- To play songs, combine this module with `SystemMusicPlayer.setQueueByPersistentIDs`.



---
url: /guide/Changelog/2.4.9/Reminder.md
---

# Reminder

The `Reminder` API provides the ability to create, edit, and manage reminders in the iOS calendar system.
It supports configuring due dates through `DateComponents`, assigning priorities, adding notes, managing recurrence rules, working with alarms, and tracking completion state.
This API is suitable for a wide range of task and schedule reminder scenarios.

***

## 1. Class: `Reminder`

The `Reminder` class represents an individual reminder item and provides properties and methods to read and modify its data.

***

## 2. Properties

### identifier: string

A unique identifier assigned by the system (read-only).

### calendar: Calendar | null

The calendar to which the reminder belongs.
The calendar can be null if the reminder is not associated with a calendarm, but you must do not set the calendar to null.

### title: string

The title or summary of the reminder.

### notes: string | null

Optional notes providing additional context.

***

## Completion State

### isCompleted: boolean

Indicates whether the reminder is marked as completed.

- Setting this property to `true` automatically sets `completionDate` to the current date.
- Setting it to `false` sets `completionDate` to `null`.

Special consideration:
If a reminder is completed on another device or client, `isCompleted` may be `true` while `completionDate` remains `null`.

### completionDate: Date | null

The date on which the reminder was completed.

- Assigning a date sets `isCompleted = true`.
- Assigning `null` clears the completed state.

***

## Due Date

### dueDateComponents: DateComponents | null

Represents the reminder’s due date using date components.
Supports partially specified date or time fields.
Useful for date-based or recurring reminders.

You may use `DateComponents.isValidDate` to check whether the components form a valid date.

### dueDate: Date | null

Deprecated.
Use `dueDateComponents` instead.
You can read the equivalent date using `dueDateComponents?.date`.

### dueDateIncludesTime: boolean

Deprecated.
Use `dueDateComponents?.hour != null && dueDateComponents?.minute != null` to determine whether the due date includes a time component.

***

## Priority

### priority: number

An integer representing the reminder’s priority.
Higher values typically indicate greater importance or urgency.

***

## Recurrence

### recurrenceRules: RecurrenceRule\[] | null

An array of recurrence rules associated with the reminder.

### hasRecurrenceRules: boolean

Indicates whether the reminder contains recurrence rules (read-only).

***

## Alarms

### alarms: EventAlarm\[] | null

A collection of alarms associated with the reminder.
Alarms may be based on:

- absolute dates
- relative offsets
- structured locations (geofence triggers)

### hasAlarm: boolean

Indicates whether the reminder contains any alarms.

***

## Attendees

### attendees: EventParticipant\[] | null

An array of attendee objects (read-only).
Not all reminder sources support attendee data.

### hasAttendees: boolean

Indicates whether the reminder has attendees.

***

## State Indicators

### hasNotes: boolean

Indicates whether the reminder contains notes.

### hasChanges: boolean

Indicates whether the reminder or any of its nested objects contains unsaved changes.

***

## 3. Instance Methods

### addAlarm(alarm: EventAlarm): void

Adds an alarm to the reminder.

### removAlarm(alarm: EventAlarm): void

Removes the specified alarm.
(Method name is `removAlarm`.)

***

### addRecurrenceRule(rule: RecurrenceRule): void

Adds a recurrence rule.

### removeRecurrenceRule(rule: RecurrenceRule): void

Removes a recurrence rule.

***

### `save(): Promise<void>`

Saves changes to the reminder.
If the reminder has not been saved before, it is added to its associated calendar.

### `remove(): Promise<void>`

Deletes the reminder from the calendar.

***

## 4. Static Methods

### `Reminder.get(identifier: string): Promise<Reminder | null>`

Returns a reminder by its identifier, or `null` if not found.

***

### `Reminder.getAll(calendars?: Calendar[]): Promise<Reminder[]>`

Returns all reminders, optionally filtered by the specified calendars.

***

### `Reminder.getIncompletes(options?): Promise<Reminder[]>`

Returns incomplete reminders filtered by due date range and/or calendar set.

Options:

- `startDate?: Date`
  Includes reminders whose due date is after this date.

- `endDate?: Date`
  Includes reminders whose due date is before this date.

- `calendars?: Calendar[]`
  Specifies which calendars to search.

This method does not expand recurrence rules; it only returns reminders with concrete due dates.

***

### `Reminder.getCompleteds(options?): Promise<Reminder[]>`

Returns completed reminders filtered by completion date range and/or calendar set.

Options:

- `startDate?: Date`
  Includes reminders completed after this date.

- `endDate?: Date`
  Includes reminders completed before this date.

- `calendars?: Calendar[]`
  Specifies which calendars to search.

***

## 5. Usage Examples

## Creating a Reminder with DateComponents

```ts
const reminder = new Reminder()
reminder.title = "Prepare meeting materials"
reminder.notes = "Finish before Monday’s team meeting"

reminder.dueDateComponents = new DateComponents({
  year: 2025,
  month: 10,
  day: 6,
  hour: 9,
  minute: 30,
})

reminder.priority = 2
await reminder.save()
```

***

## Creating a Date-Only Reminder

```ts
reminder.dueDateComponents = new DateComponents({
  year: 2025,
  month: 10,
  day: 6,
})
```

***

## Creating DateComponents from a Date

```ts
const now = new Date()
reminder.dueDateComponents = DateComponents.fromDate(now)
```

***

## Fetching All Reminders

```ts
const reminders = await Reminder.getAll()
for (const r of reminders) {
  console.log(`Reminder: ${r.title}`)
}
```

***

## Fetching Incomplete Reminders

```ts
const incompletes = await Reminder.getIncompletes({
  startDate: new Date("2025-01-01"),
  endDate: new Date("2025-01-31"),
})
```

***

## Marking a Reminder as Completed

```ts
reminder.isCompleted = true
await reminder.save()
```

***

## Deleting a Reminder

```ts
await reminder.remove()
```

***

## 6. Additional Notes

### Date Management

Using `dueDateComponents` is recommended for all due-date handling.
It supports:

- date-only values
- date with time
- partial components
- validity checks through `isValidDate`

### Recurrence

Reminder queries do not expand recurrence rules.
They operate only on the reminder objects that have concrete due dates.
Recurrence rules can be added or removed through the API.

### Alarms

Alarms may be absolute, relative, or location-based, and are shared with the `CalendarEvent` API.

### Attendees

Some reminder sources do not support attendee data; in such cases, the attendees array may be `null`.



---
url: /guide/Changelog/2.4.9/Script Minimization and Resume.md
---

# Script Minimization and Resume

This section describes the Script APIs related to script minimization and resume behavior. These APIs allow a script running on iPhone to hide its UI without terminating the script instance, and to listen for resume or re-trigger events while the instance remains alive.

These capabilities are suitable for:

- UI-based scripts that need to preserve runtime state after the user hides the interface
- Non-UI scripts that remain alive in the background (for example, notification-driven scripts)

***

## Runtime Model Overview

### Script Instance Lifecycle

- Calling `Script.minimize()` does not terminate the script instance.
- Only `Script.exit()` fully terminates the script and releases resources.
- `Script.onResume()` is triggered only while the script instance is still alive.
- If `Script.exit()` has been called, subsequent triggers will create a new script instance and re-execute the entry file.

### Interaction with URL Schemes

- When using `scripting://run/...`:

  - If an existing instance is alive, `Script.onResume()` will be triggered.
  - The entry file will not be executed again.

- When using `scripting://run_single/...`:

  - All previous instances of the script are terminated.
  - `onResume` of the previous instance will not be triggered.
  - A new instance is created and the entry file runs again.

***

## API Reference

### `Script.supportsMinimization(): boolean`

Determines whether the current environment supports script minimization.

Not all environments allow minimization (for example, certain extension contexts).

```ts
if (Script.supportsMinimization()) {
  // Enable minimization-related logic
}
```

***

### `Script.isMinimized(): boolean`

Returns whether the current script is in the minimized state.

```ts
if (Script.isMinimized()) {
  console.log("Script is currently minimized")
}
```

***

### `Script.minimize(): Promise<boolean>`

Minimizes the current script.

After minimization:

- The UI is hidden.
- The script instance continues running.
- `Script.exit()` is not called.

Behavior rules:

- If the script is already minimized, nothing happens.
- If multiple windows mode is enabled, the method is ignored.
- Return value:

  - `true` if minimization succeeds
  - `false` if minimization is not performed (for example, unsupported environment or ignored state)

```ts
async function handleMinimize() {
  if (!Script.supportsMinimization()) return

  const success = await Script.minimize()
  if (!success) {
    console.log("Minimization was not performed")
  }
}
```

***

### `Script.enableMinimize(enabled?: boolean): void`

Enables minimize-on-swipe-dismiss for the script's **root presented UI** (the first page presented with `Navigation.present`, whether a sheet or a full-screen page).

Once enabled, when the user interactively **swipes the root page down to dismiss it**, the script is minimized instead of being ended: the UI is hidden, the script instance keeps running, `Script.onMinimize` is triggered, and the script can be resumed from the running scripts list — exactly as if `Script.minimize()` had been called.

Behavior rules:

- Affects only interactive swipe-down dismissal of the root page. Programmatic dismissal via `Navigation.useDismiss()(result)` still closes the page and resolves the `present` promise with `result` as usual.
- `Script.exit()` still fully terminates the script.
- Has no effect when multiple windows mode is enabled.
- Pass `false` to disable the behavior again. Defaults to `true`.
- While the script is minimized, the original `Navigation.present` promise stays pending (the same as after `Script.minimize()`). Use `Script.onResume()` to react when the script is restored.

```ts
// Keep the script alive when the user swipes the sheet away.
Script.enableMinimize()

await Navigation.present({
  element: <MyView />,
  modalPresentationStyle: "pageSheet",
})
```

***

### `Script.onMinimize(callback: () => void): () => void`

Registers a listener for the minimize event.

Triggered when:

- `Script.minimize()` successfully transitions the script into minimized state.
- The script moves from foreground to minimized state.

Returns a function that removes the listener.

```ts
const remove = Script.onMinimize(() => {
  console.log("Script has been minimized")
})

// Remove listener
remove()
```

***

### `Script.onResume(callback: (eventDetails: ResumeEventDetails) => void): () => void`

Registers a listener for resume or re-trigger events.

The resume event is delivered only when:

- The script instance is still alive.
- `Script.exit()` has not been called.

Returns a function that removes the listener.

```ts
const remove = Script.onResume(details => {
  console.log("Resume event:", details)
})
```

***

## ResumeEventDetails Structure

```ts
type ResumeEventDetails = {
  resumeFromMinimized: boolean
  widgetParameter: string | null
  controlWidgetParameter: string | null
  queryParameters: Record<string, any> | null
  notificationInfo: NotificationInfo | null
}
```

### `resumeFromMinimized: boolean`

- `true`: The script was restored from minimized state.
- `false`: The script was not restored from minimized state (for example, it was already in foreground or triggered by another source).

***

### `widgetParameter: string | null`

Parameter passed when the script is resumed by tapping a home screen widget.

***

### `controlWidgetParameter: string | null`

Parameter passed when the script is resumed by interacting with a Control Center widget.

***

### `queryParameters: Record<string, any> | null`

Query parameters passed when the script is resumed. Values keep their JSON types when resumed with a JSON object, but are strings when resumed via a `scripting://run/...` URL scheme.

***

### `notificationInfo: NotificationInfo | null`

Notification information passed when the script is resumed by tapping a notification.

***

## Behavior Scenarios

### UI-Based Script

#### Minimization Flow

- The script is running in the foreground.
- `Script.minimize()` is called.
- On success:

  - `Script.onMinimize` is triggered.
  - The UI is hidden.
  - The script instance remains alive.

#### Restoring from Minimized State

- The user taps the running script entry in the app.
- `Script.onResume` is triggered.
- `eventDetails.resumeFromMinimized === true`.

***

### External Triggers While in Foreground

When the script instance is alive and currently in the foreground:

- Tapping a notification
- Triggering the script via a widget run URL scheme
- Calling `Script.run()` for the same script

In these cases, `Script.onResume` is triggered and the corresponding parameter fields in `ResumeEventDetails` are populated.

***

### Non-UI (Background) Script

If the script has not called `Script.exit()`:

- Even without presenting UI,
- Tapping a notification or triggering the script again
- Will invoke registered `Script.onResume` callbacks.

If the script has called `Script.exit()`:

- A new trigger (notification, widget, etc.) creates a new script instance.
- The entry file executes again.
- Previous `onResume` listeners are not triggered.

***

## Usage Guidance

- Check `Script.supportsMinimization()` before enabling minimization-related features.
- Avoid calling `Script.exit()` if the script needs to remain alive.
- Use `Script.onResume()` to centralize handling of resume, widget triggers, notification taps, and URL-based triggers.
- Use `run_single` or `singleMode: true` when concurrent instances must be prevented.

This model enables long-lived script instances with hideable UI and unified resume handling across multiple trigger sources.



---
url: /guide/Changelog/2.4.9/SystemMusicPlayer.md
---

# SystemMusicPlayer

The `SystemMusicPlayer` module provides control over the system-level music player. It is built on top of `MPMusicPlayerController.systemMusicPlayer`, which shares the playback queue and playback state with the system Music app.

This module allows scripts to:

- Control system music playback
- Set and manage the playback queue
- Control playback time, rate, repeat, and shuffle modes
- Observe playback state changes
- Access information about the currently playing item

Important notes:

- The user must grant media library access.
- Playing Apple Music content may require an active subscription.
- All operations affect the global system music player.

***

## Data Models

### PlaybackState

Represents the current playback state.

```ts
type PlaybackState =
  | "stopped"
  | "playing"
  | "paused"
  | "interrupted"
  | "seekingForward"
  | "seekingBackward"
```

Descriptions:

- `stopped`: Playback is stopped
- `playing`: Currently playing
- `paused`: Paused
- `interrupted`: Interrupted by system events (e.g. phone call)
- `seekingForward`: Fast-forwarding
- `seekingBackward`: Rewinding

***

### RepeatMode

Defines the repeat mode.

```ts
type RepeatMode =
  | "none"
  | "one"
  | "all"
  | "default"
```

Descriptions:

- `none`: No repeat
- `one`: Repeat current item
- `all`: Repeat entire queue
- `default`: Use system default

***

### ShuffleMode

Defines the shuffle mode.

```ts
type ShuffleMode =
  | "off"
  | "songs"
  | "albums"
  | "default"
```

Descriptions:

- `off`: Shuffle disabled
- `songs`: Shuffle songs
- `albums`: Shuffle albums
- `default`: Use system default

***

### NowPlayingItem

Represents the currently playing item.

```ts
type NowPlayingItem = {
  persistentID: string
  title: string
  playbackDuration: number
  playbackStoreID?: string
  artist?: string
  albumTitle?: string
  albumArtist?: string
  genre?: string
  composer?: string
}
```

Field descriptions:

- `persistentID`: Unique local media identifier
- `title`: Song title
- `playbackDuration`: Duration in seconds
- `playbackStoreID`: Apple Music Store ID (if available)
- Other fields are similar to `MediaLibrary.Item`

***

## Setting the Playback Queue

### setQueueByStoreIDs

Sets the playback queue using Apple Music Store IDs.

```ts
function setQueueByStoreIDs(options: {
  storeIDs: string[]
  startItemID?: string
  startTime?: number
}): Promise<void>
```

Parameters:

- `storeIDs`: Array of Apple Music Store IDs
- `startItemID`: Optional ID of the item to start playback from
- `startTime`: Optional starting playback time in seconds

Example:

```ts
await SystemMusicPlayer.setQueueByStoreIDs({
  storeIDs: ["123456789", "987654321"],
  startItemID: "123456789",
  startTime: 30
})

await SystemMusicPlayer.play()
```

***

### setQueueByPersistentIDs

Sets the playback queue using local media `persistentID` values.

```ts
function setQueueByPersistentIDs(options: {
  persistentIDs: string[]
  startItemID?: string
  startTime?: number
}): Promise<void>
```

Example:

```ts
await SystemMusicPlayer.setQueueByPersistentIDs({
  persistentIDs: ["111", "222", "333"],
  startItemID: "222"
})

await SystemMusicPlayer.play()
```

Recommended usage:

- Combine with `MediaLibrary.getSongs()` to build a queue from local content.

***

## Playback Controls

### prepare

Prepares the current playback queue.

```ts
function prepare(): Promise<void>
```

Typically called before `play()`.

***

### play

Starts playback.

```ts
function play(): Promise<void>
```

***

### pause

Pauses playback.

```ts
function pause(): Promise<void>
```

***

### stop

Stops playback.

```ts
function stop(): Promise<void>
```

***

### skipToNextItem

Skips to the next item in the queue.

```ts
function skipToNextItem(): Promise<void>
```

***

### skipToPreviousItem

Skips to the previous item.

```ts
function skipToPreviousItem(): Promise<void>
```

***

### seek

Seeks to a specific time in the current item.

```ts
function seek(to: number): Promise<void>
```

Parameter:

- `to`: Time in seconds

Example:

```ts
await SystemMusicPlayer.seek(60)
```

***

### setCurrentPlaybackTime

Sets the current playback time.

```ts
function setCurrentPlaybackTime(seconds: number): Promise<void>
```

***

### setCurrentPlaybackRate

Sets the playback rate.

```ts
function setCurrentPlaybackRate(rate: number): Promise<void>
```

Example:

```ts
await SystemMusicPlayer.setCurrentPlaybackRate(1.5)
```

***

### setRepeatMode

Sets the repeat mode.

```ts
function setRepeatMode(mode: RepeatMode): Promise<void>
```

***

### setShuffleMode

Sets the shuffle mode.

```ts
function setShuffleMode(mode: ShuffleMode): Promise<void>
```

***

## Playback State Accessors

### indexOfNowPlayingItem

Returns the index of the current item in the queue.

```ts
function indexOfNowPlayingItem(): number
```

***

### getNowPlayingItem

Returns the currently playing item.

```ts
function getNowPlayingItem(): NowPlayingItem | null
```

Example:

```ts
const item = SystemMusicPlayer.getNowPlayingItem()

if (item) {
  console.log(item.title)
}
```

***

### getPlaybackState

Returns the current playback state.

```ts
function getPlaybackState(): PlaybackState
```

***

### getCurrentPlaybackTime

Returns the current playback time in seconds.

```ts
function getCurrentPlaybackTime(): number
```

***

### getCurrentPlaybackRate

Returns the current playback rate.

```ts
function getCurrentPlaybackRate(): number
```

***

### getRepeatMode

Returns the current repeat mode.

```ts
function getRepeatMode(): RepeatMode
```

***

### getShuffleMode

Returns the current shuffle mode.

```ts
function getShuffleMode(): ShuffleMode
```

***

## Event Handling

### EventType

```ts
type EventType =
  | "playbackStateDidChange"
  | "nowPlayingItemDidChange"
  | "volumeDidChange"
```

***

### addEventListener

Adds an event listener.

```ts
function addEventListener<T extends EventType>(
  type: T,
  listener: (payload: any) => void
): void
```

Example:

```ts
SystemMusicPlayer.addEventListener(
  "playbackStateDidChange",
  state => {
    console.log("Playback state:", state)
  }
)

SystemMusicPlayer.addEventListener(
  "nowPlayingItemDidChange",
  item => {
    if (item) {
      console.log("Now playing:", item.title)
    }
  }
)
```

***

### removeEventListener

Removes an event listener.

```ts
function removeEventListener<T extends EventType>(
  type: T,
  listener: (payload: any) => void
): void
```

***

## Best Practices

- After setting a queue, call `prepare()` before `play()`.
- Listen to `nowPlayingItemDidChange` to update UI reactively.
- Use `persistentID` as a stable identifier rather than relying on queue index.
- Avoid frequently resetting the queue with `setQueue...`, as it replaces the entire playback queue.
- Remember that this is a global system music player; changes affect system-wide playback.



---
url: /guide/Changelog/2.4.9/TextField textContentType.md
---

# TextField textContentType

The following modifiers customize the behavior and appearance of `TextField` components. These allow you to control keyboard behavior, input handling, and submission logic.

***

## `onSubmit`

Adds an action to perform when the user submits a value from the text field.

### Type

```ts
onSubmit?: (() => void) | {
  triggers: SubmitTriggers
  action: () => void
}
```

### Behavior

- If provided as a function:

  ```tsx
  <TextField onSubmit={() => console.log('Submitted')} />
  ```

  This is equivalent to:

  ```tsx
  <TextField
    onSubmit={{
      triggers: 'text',
      action: () => console.log('Submitted')
    }}
  />
  ```

- You can explicitly define what kind of submission should trigger the action using the `triggers` option:

  ```tsx
  <TextField
    onSubmit={{
      triggers: 'search',
      action: () => console.log('Search submitted')
    }}
  />
  ```

### `SubmitTriggers` values:

- `"text"`: Triggered by text input views like `TextField`, `SecureField`, etc.
- `"search"`: Triggered by search fields (e.g., those using the `searchable` modifier).

***

## `keyboardType`

Specifies the type of keyboard to display when the text field is focused.

### Type

```ts
keyboardType?: KeyboardType
```

### Options

- `'default'`
- `'numberPad'`
- `'phonePad'`
- `'namePhonePad'`
- `'URL'`
- `'decimalPad'`
- `'asciiCapable'`
- `'asciiCapableNumberPad'`
- `'emailAddress'`
- `'numbersAndPunctuation'`
- `'twitter'`
- `'webSearch'`

### Example

```tsx
<TextField keyboardType="emailAddress" />
```

***

## `autocorrectionDisabled`

Controls whether the system autocorrection is enabled.

### Type

```ts
autocorrectionDisabled?: boolean
```

### Default

- `true` — autocorrection is disabled by default.

### Example

```tsx
<TextField autocorrectionDisabled={false} />
```

***

## `textInputAutocapitalization`

Sets how the text input system should automatically capitalize text.

### Type

```ts
textInputAutocapitalization?: TextInputAutocapitalization
```

### Options

- `"never"` – No capitalization.
- `"characters"` – All letters capitalized.
- `"sentences"` – First letter of each sentence capitalized.
- `"words"` – First letter of each word capitalized.

### Example

```tsx
<TextField textInputAutocapitalization="words" />
```

***

## `textContentType`

Sets the semantic meaning expected for the text input. The system can use it for autofill and keyboard suggestions.

### Type

```ts
textContentType?: TextContentType
```

### Options

- `"cellularEID"`
- `"cellularIMEI"`
- `"URL"`
- `"namePrefix"`
- `"name"`
- `"nameSuffix"`
- `"givenName"`
- `"middleName"`
- `"familyName"`
- `"nickname"`
- `"organizationName"`
- `"jobTitle"`
- `"location"`
- `"fullStreetAddress"`
- `"streetAddressLine1"`
- `"streetAddressLine2"`
- `"addressCity"`
- `"addressCityAndState"`
- `"addressState"`
- `"postalCode"`
- `"sublocality"`
- `"countryName"`
- `"username"`
- `"password"`
- `"newPassword"`
- `"oneTimeCode"`
- `"emailAddress"`
- `"telephoneNumber"`
- `"creditCardNumber"`
- `"creditCardExpiration"`
- `"creditCardExpirationMonth"`
- `"creditCardExpirationYear"`
- `"creditCardSecurityCode"`
- `"creditCardType"`
- `"creditCardName"`
- `"creditCardGivenName"`
- `"creditCardMiddleName"`
- `"creditCardFamilyName"`
- `"birthdate"`
- `"birthdateDay"`
- `"birthdateMonth"`
- `"birthdateYear"`
- `"dateTime"`
- `"flightNumber"`
- `"shipmentTrackingNumber"`

### Example

```tsx
<TextField textContentType="oneTimeCode" />
```

***

## `submitScope`

Prevents submission triggers from this view from propagating upward to parent views with submission handlers.

### Type

```ts
submitScope?: boolean
```

### Default

- `false` — submission actions bubble up by default.

### Example

```tsx
<TextField submitScope />
```

This ensures that `onSubmit` handlers defined higher up in the view hierarchy won’t be called when this field is submitted.

## `submitLabel`

Sets the label for the submit button.

### Type

```ts
submitLabel?: "continue" | "return" | "send" | "go" | "search" | "join" | "done" | "next" | "route"
```

### Example

```tsx
<TextField submitLabel="search" />
```



---
url: /guide/Changelog/2.4.9/WebScraper.md
---

The `WebScraper` module provides a lightweight web scraping service that allows scripts to reliably load web pages and retrieve their HTML content or extract structured data from them.

The module loads web pages in a controlled environment and supports multiple waiting strategies (such as DOM completion, network idle, or waiting for specific elements). These strategies help ensure stability when scraping modern websites that rely on dynamic rendering.

Typical use cases include:

- Retrieving the final rendered HTML of a page
- Extracting structured data by running JavaScript in the page context
- Waiting for dynamic content to load before scraping
- Writing stable automation scripts for web data extraction

All operations are executed as **asynchronous tasks**. Each task has a unique `taskId`, which can be used to track or cancel the task.

***

# Type Definitions

## WaitOptions

Defines the strategy used to determine when a page has finished loading.

```ts
type WaitOptions =
  | "domComplete"
  | "networkIdle"
  | {
      mode: "domComplete"
    }
  | {
      mode: "networkIdle"
      idleSeconds?: number
    }
  | {
      mode: "selector"
      selector: string
    }
```

### Available Modes

#### `"domComplete"`

Waits until `document.readyState === "complete"`.

Suitable for:

- Static websites
- Simple pages
- Websites that do not rely heavily on asynchronous loading

Example:

```ts
wait: "domComplete"
```

***

#### `"networkIdle"`

Waits until the page network activity becomes idle.

When no new network requests occur within a period of time, the page is considered fully loaded.

Suitable for:

- SPA applications
- Pages that fetch data via APIs
- Websites with dynamic content loading

Example:

```ts
wait: "networkIdle"
```

You may also specify the idle duration:

```ts
wait: {
  mode: "networkIdle",
  idleSeconds: 2
}
```

***

#### `"selector"`

Waits until a specific DOM element appears.

When an element matching the selector exists in the document, the task continues.

Suitable for:

- Dynamically rendered content
- Waiting for specific UI components
- Precisely controlling when scraping begins

Example:

```ts
wait: {
  mode: "selector",
  selector: ".article-content"
}
```

***

# Error

Represents error information when a scraping task fails.

```ts
type Error = {
  code: string
  message: string
}
```

### Properties

#### code

An error code identifying the type of failure.

Examples:

```
NETWORK_ERROR
TIMEOUT
SCRIPT_ERROR
```

#### message

A human-readable error message describing the failure.

Example:

```
Request timed out
```

***

# Timing

Represents execution timing information for a task.

```ts
type Timing = {
  totalMs: number
}
```

### Properties

#### totalMs

The total execution time of the task in milliseconds.

***

# Result

All `WebScraper` APIs return results using the `Result` type.

```ts
type Result<T = any> = {
  ok: boolean
  taskId: string
  url?: string
  html?: string
  data?: T
  error?: Error
  timing?: Timing
}
```

### Properties

#### ok

Indicates whether the task completed successfully.

```
true   task succeeded
false  task failed
```

***

#### taskId

The unique identifier of the task.

If `taskId` is not specified when starting the task, the system automatically generates one.

It can be used to cancel the task:

```ts
WebScraper.cancel(taskId)
```

***

#### url

The final loaded URL.

If redirects occurred during navigation, this field contains the final destination URL.

***

#### html

The final HTML of the page.

This is typically the **rendered DOM HTML**, not the raw HTML response.

***

#### data

The data returned by `extractScript` or `eval`.

The type of this field is defined by the generic parameter `T`.

***

#### error

Returned when the task fails.

Contains error information.

***

#### timing

Timing information about the task execution.

***

# API

## load

Loads a web page and returns the final HTML.

```ts
function load(options: {
  url: string
  wait?: WaitOptions
  timeout?: number
  taskId?: string
}): Promise<Result<string>>
```

### Parameters

#### url

The URL of the page to load.

Example:

```ts
url: "https://example.com"
```

***

#### wait

The waiting strategy used to determine when the page is ready.

Default:

```
"domComplete"
```

***

#### timeout

The maximum allowed time for the task in **seconds**.

If the task does not finish within the specified time, it fails with a timeout error.

Example:

```
timeout: 15
```

***

#### taskId

An optional task identifier.

If not provided, the system automatically generates one.

***

### Example

```ts
const result = await WebScraper.load({
  url: "https://example.com",
  wait: "networkIdle"
})

if (result.ok) {
  console.log(result.html)
}
```

***

# scrape

Loads a page and optionally executes an extraction script in the page context.

```ts
function scrape<T = any>(options: {
  url: string
  wait?: WaitOptions
  timeout?: number
  extractScript?: string
  taskId?: string
}): Promise<Result<T>>
```

This method performs the following steps:

1. Load the page
2. Wait until the specified condition is satisfied
3. Execute `extractScript` in the page context
4. Return both the HTML and extracted data

***

### Parameters

#### extractScript

JavaScript code executed in the page context.

The script should return the data to extract.

Example:

```ts
extractScript: `
  return {
    title: document.title,
    articles: Array.from(document.querySelectorAll("article")).map(el => ({
      title: el.querySelector("h2")?.innerText,
      link: el.querySelector("a")?.href
    }))
  }
`
```

***

### Example

```ts
const result = await WebScraper.scrape({
  url: "https://news.ycombinator.com",
  wait: {
    mode: "selector",
    selector: ".athing"
  },
  extractScript: `
    return Array.from(document.querySelectorAll(".athing")).map(el => ({
      title: el.querySelector(".titleline a")?.innerText,
      url: el.querySelector(".titleline a")?.href
    }))
  `
})

if (result.ok) {
  console.log(result.data)
}
```

***

# eval

Evaluates JavaScript in the page context and returns the result.

```ts
function eval<T = any>(options: {
  url: string
  script: string
  wait?: WaitOptions
  timeout?: number
  taskId?: string
}): Promise<Result<T>>
```

This method is intended for executing custom JavaScript logic inside the page.

Compared to `scrape`:

- `eval` focuses on executing arbitrary JavaScript
- `scrape` is designed specifically for extracting data

***

### Parameters

#### script

JavaScript code executed in the page context.

The script must return a value.

***

### Example

```ts
const result = await WebScraper.eval({
  url: "https://example.com",
  script: `
    return {
      title: document.title,
      links: document.links.length
    }
  `
})

if (result.ok) {
  console.log(result.data)
}
```

***

# cancel

Cancels a running scraping task.

```ts
function cancel(taskId: string): Promise<boolean>
```

### Parameters

#### taskId

The identifier of the task to cancel.

***

### Return Value

```
true   task was successfully cancelled
false  task not found or already finished
```

***

### Example

```ts
const taskId = "scrape-news"

WebScraper.scrape({
  url: "https://example.com",
  taskId
})

await WebScraper.cancel(taskId)
```

***

# Usage Recommendations

## Choose an Appropriate Waiting Strategy

Different types of websites benefit from different strategies.

| Scenario                      | Recommended wait |
| ----------------------------- | ---------------- |
| Static pages                  | `"domComplete"`  |
| SPA applications              | `"networkIdle"`  |
| Waiting for specific elements | `"selector"`     |

***

## Prefer selector Waiting for Dynamic Content

For dynamic pages, waiting for a specific element improves reliability.

```ts
wait: {
  mode: "selector",
  selector: ".content"
}
```

***

## Adjust Timeout for Complex Pages

Complex sites may require longer timeouts.

```
timeout: 20
```

***

## Prefer extractScript Instead of Parsing HTML

Instead of retrieving HTML and parsing it manually:

```ts
const html = result.html
```

It is often more efficient to extract data directly in the page:

```ts
extractScript: `
  return document.title
`
```

This approach reduces script complexity and improves performance.



---
url: /guide/Changelog/3.0.0/Alarm/Alarm Live Activity/index.md
---

# Alarm Live Activity

`AlarmLiveActivity` lets a script provide a custom Lock Screen and Dynamic Island UI for alarms created with `AlarmManager` on iOS 26+.

Use this when the built-in alarm Live Activity is not enough and you want the alarm to match your script's product style while keeping AlarmKit scheduling, pause, resume, countdown, and stop behavior.

***

## Files

Custom alarm Live Activity UI must be registered in a standalone file named:

```txt
alarm_live_activity.tsx
```

Your main script still creates the alarm from `index.tsx`. If `alarm_live_activity.tsx` does not exist, or the requested UI name is not registered, Scripting falls back to the built-in alarm UI.

***

## Register a UI

`AlarmLiveActivity` is exported from the `scripting` package:

```tsx
import {
  AlarmLiveActivity,
  LiveActivityUI,
  LiveActivityUIExpandedBottom,
  LiveActivityUIExpandedCenter,
  LiveActivityUIExpandedLeading,
  LiveActivityUIExpandedTrailing,
} from "scripting"

AlarmLiveActivity.register("FocusTimerActivity", state => {
  return (
    <LiveActivityUI
      content={<Text>{state.title}</Text>}
      compactLeading={<Text>{state.mode}</Text>}
      compactTrailing={<Text>{state.title}</Text>}
      minimal={<Text>{state.mode}</Text>}>
      <LiveActivityUIExpandedLeading>
        <Text>{state.title}</Text>
      </LiveActivityUIExpandedLeading>
      <LiveActivityUIExpandedTrailing>
        <Text>{state.mode}</Text>
      </LiveActivityUIExpandedTrailing>
      <LiveActivityUIExpandedCenter>
        <Text>{state.presentation.alert.title}</Text>
      </LiveActivityUIExpandedCenter>
      <LiveActivityUIExpandedBottom>
        <Text>{state.alarmID}</Text>
      </LiveActivityUIExpandedBottom>
    </LiveActivityUI>
  )
})
```

The returned root node must be `LiveActivityUI`. The `content`, `compactLeading`, `compactTrailing`, and `minimal` regions are required.

***

## Attach It to an Alarm

`AlarmManager` is a global API and does not need to be imported.

```tsx
const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Focus complete",
    stopButton: AlarmManager.Button.create({
      title: "Done",
      systemImageName: "checkmark"
    })
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Deep focus",
    AlarmManager.Button.create({
      title: "Pause",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Paused",
    AlarmManager.Button.create({
      title: "Resume",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#ff9f0a",
  metadata: {
    task: "Writing"
  },
  liveActivity: {
    name: "FocusTimerActivity"
  }
})
```

The `liveActivity.name` value must match the name passed to `AlarmLiveActivity.register`.

***

## Render State

The builder receives an `AlarmLiveActivityState` object:

```ts
type AlarmLiveActivityState = {
  alarmID: string
  mode: "scheduled" | "countdown" | "paused" | "alerting"
  title: string
  tintColor?: Color | null
  metadata: Record<string, string>
  presentation: AlarmLiveActivityPresentation
  actions: {
    pause?: AlarmLiveActivityAction | null
    resume?: AlarmLiveActivityAction | null
    stop: AlarmLiveActivityAction
    secondary?: AlarmLiveActivityAction | null
  }
  countdown?: {
    fireDate: Date
    totalCountdownDuration: number
  } | null
  paused?: {
    totalCountdownDuration: number
    prePauseCountdownDuration: number
  } | null
}
```

Use `mode` to switch the layout, `metadata` for your own display data, and `presentation` to reuse titles and button labels configured through `AlarmManager.Attributes`.

***

## Built-In Actions

The `actions` field contains AppIntent-backed controls created by Scripting for the current alarm.

```tsx
{state.actions.pause && (
  <Button intent={state.actions.pause.intent}>
    <Label title={state.actions.pause.title} systemImage={state.actions.pause.systemImageName ?? "pause.fill"} />
  </Button>
)}

<Button intent={state.actions.stop.intent} role="destructive">
  <Label title={state.actions.stop.title} systemImage={state.actions.stop.systemImageName ?? "xmark"} />
</Button>
```

These actions call the native `AlarmManager` operations for the alarm:

- `pause`
- `resume`
- `stop`
- `secondary`, when the alert secondary button uses `secondaryButtonBehavior: "countdown"`

If you need extra script-specific behavior, register your own `AppIntent` separately and use it in a normal Live Activity button. The standard `actions` field is the recommended way to control the alarm itself.

***

## Notes

- `AlarmManager` alert `stopIntent` and `secondaryIntent` still belong to the system alert presentation.
- Custom Live Activity buttons should use `state.actions.*.intent` for alarm pause, resume, stop, and countdown behavior.
- Keep Dynamic Island compact regions small. Prefer SF Symbols, short labels, and system fonts.
- Prefer `buttonStyle="glass"` or `buttonStyle="glassProminent"` on iOS 26 when the control is visible in the Lock Screen or expanded Dynamic Island.



---
url: /guide/Changelog/3.0.0/Alarm/AlarmManager.md
---

# AlarmManager

`AlarmManager` (iOS 26+) is a global API provided by Scripting for creating and managing AlarmKit-based alarms, timers, and countdown reminders. It does not need to be imported and can be used directly in scripts.

This API is suitable for scenarios such as:

- Creating one-time alarms, such as “remind me tonight at 10:30 PM”
- Creating daily or weekly recurring alarms
- Creating Pomodoro timers, workout timers, and countdown-based reminders
- Customizing alert titles, buttons, colors, icons, and metadata
- Using `AppIntent` to handle alert button actions
- Listening for alarm state changes and updating UI accordingly

***

## Availability

Before using `AlarmManager`, you should first check whether the current environment supports AlarmKit:

```tsx
if (!AlarmManager.isAvailable) {
  console.log("AlarmKit is not available on this device")
}
```

If the current device or system version does not support it, related methods may not work.

***

## Core Concepts

`AlarmManager` is built around these main types:

- `Alarm`: an existing alarm instance
- `Schedule`: the schedule rule that determines when an alarm fires
- `Countdown`: countdown-related parameters
- `Button`: button styling for the alert UI
- `Sound`: alert sound configuration
- `AlertPresentation`: content shown when the alarm is alerting
- `CountdownPresentation`: content shown while countdown is running
- `PausedPresentation`: content shown while countdown is paused
- `Attributes`: the overall presentation configuration
- `Configuration`: the final configuration object used to create alarms, timers, or countdown reminders

***

## Alarm ID Rules

The `id` passed to an alarm must be generated with:

```tsx
UUID.string()
```

Do not manually build fixed IDs, and do not reuse old IDs. Every new alarm, timer, or countdown reminder should use a newly generated UUID string.

Correct example:

```tsx
const id = UUID.string()
```

Not recommended:

```tsx
const id = "morning-alarm"
const id = `timer-${Date.now()}`
```

All later operations such as `cancel`, `stop`, `pause`, `resume`, and `startCountdown` must use the exact same ID that was used when the alarm was created.

***

## AlarmState

```tsx
type AlarmState = "scheduled" | "countdown" | "paused" | "alerting"
```

Represents the current state of an alarm.

### `"scheduled"`

The alarm has been scheduled and is waiting to fire.

Common cases:

- Fixed-time alarms
- Weekly recurring alarms
- Countdown-based alarms that have not started yet

### `"countdown"`

A countdown is currently running.

Common cases:

- An active timer
- A started countdown reminder

### `"paused"`

The countdown is currently paused.

### `"alerting"`

The alarm has fired and is currently presenting its alert.

***

## SecondaryButtonBehavior

```tsx
type SecondaryButtonBehavior = "countdown" | "custom"
```

Controls the behavior of the secondary button shown in the alert UI.

### `"countdown"`

The secondary button starts a countdown flow.

This is typically used for “remind me later” or “remind me again in a few minutes” behavior.

### `"custom"`

The secondary button is treated as a custom action button, and its actual behavior is defined by `secondaryIntent`.

***

## AlarmAppIntent

```tsx
type AlarmAppIntent = AppIntent<any, AppIntentProtocol.LiveActivityIntent>
```

Represents an `AppIntent` that can be attached to alarm buttons.

It is mainly used for:

- Running additional logic when the stop button is tapped
- Running custom logic when the secondary button is tapped
- Integrating alarm interactions with Live Activity, Widget, or ControlWidget logic

It can be assigned through:

- `Configuration.alarm(...).stopIntent`
- `Configuration.alarm(...).secondaryIntent`
- `Configuration.timer(...).stopIntent`
- `Configuration.timer(...).secondaryIntent`
- `Configuration.countdown(...).stopIntent`
- `Configuration.countdown(...).secondaryIntent`

Note that the required protocol type here is:

```tsx
AppIntentProtocol.LiveActivityIntent
```

That means any `AppIntent` used with `AlarmManager` should be registered with the `LiveActivityIntent` protocol.

A full example is provided later in this document.

***

## AlarmUpdateListener

```tsx
type AlarmUpdateListener = (alarms: Alarm[]) => void
```

A callback used to listen for alarm list updates.

When alarms are created, cancelled, paused, resumed, started, or otherwise updated, the listener receives the latest `Alarm[]`.

***

## Alarm

```tsx
class Alarm {
  readonly id: string
  readonly state: AlarmState
  readonly schedule?: Schedule | null
  readonly countdownDuration?: Countdown | null
}
```

Represents an existing alarm object.

### `id`

```tsx
readonly id: string
```

The unique identifier of the alarm.

It must be generated with `UUID.string()` when the alarm is created. All later operations such as cancel, stop, pause, and resume depend on this value.

### `state`

```tsx
readonly state: AlarmState
```

The current alarm state.

### `schedule`

```tsx
readonly schedule?: Schedule | null
```

The scheduling rule for this alarm.

Pure timers may not have a `schedule`.

### `countdownDuration`

```tsx
readonly countdownDuration?: Countdown | null
```

The countdown-related configuration for this alarm.

***

## Schedule

```tsx
class Schedule {
  readonly type: "fixed" | "relative"
  readonly date?: Date | null
  readonly hour?: number | null
  readonly minute?: number | null
  readonly weekdays?: number[] | null

  static fixed(date: Date): Schedule
  static relative(hour: number, minute: number): Schedule
  static weekly(hour: number, minute: number, weekdays: number[]): Schedule
}
```

Describes when an alarm should fire.

### `type`

```tsx
readonly type: "fixed" | "relative"
```

The schedule type.

- `"fixed"`: a fixed absolute time
- `"relative"`: a schedule based on hour and minute

### `date`

```tsx
readonly date?: Date | null
```

The exact trigger date for a fixed-time schedule.

### `hour`

```tsx
readonly hour?: number | null
```

The hour component of the schedule.

### `minute`

```tsx
readonly minute?: number | null
```

The minute component of the schedule.

### `weekdays`

```tsx
readonly weekdays?: number[] | null
```

The weekday array for weekly recurring schedules.

The exact weekday number mapping depends on your underlying implementation. Typically this uses values from 1 to 7.

### `Schedule.fixed(date)`

```tsx
static fixed(date: Date): Schedule
```

Creates a fixed-time schedule.

```tsx
const schedule = AlarmManager.Schedule.fixed(
  new Date("2026-03-20T22:30:00")
)
```

### `Schedule.relative(hour, minute)`

```tsx
static relative(hour: number, minute: number): Schedule
```

Creates a schedule based on hour and minute.

This is typically suitable for “every day at a given time” scenarios.

```tsx
const schedule = AlarmManager.Schedule.relative(7, 30)
```

### `Schedule.weekly(hour, minute, weekdays)`

```tsx
static weekly(hour: number, minute: number, weekdays: number[]): Schedule
```

Creates a weekly recurring schedule.

```tsx
const schedule = AlarmManager.Schedule.weekly(8, 0, [2, 3, 4, 5, 6])
```

***

## Countdown

```tsx
class Countdown {
  readonly preAlert?: number | null
  readonly postAlert?: number | null

  static create(options?: {
    preAlert?: DurationInSeconds | null
    postAlert?: DurationInSeconds | null
  }): Countdown
}
```

Defines countdown-related parameters.

### `preAlert`

```tsx
readonly preAlert?: number | null
```

The countdown duration before the alert, in seconds.

### `postAlert`

```tsx
readonly postAlert?: number | null
```

The additional duration after the alert, in seconds.

The exact behavior depends on your underlying implementation.

### `Countdown.create(options?)`

```tsx
static create(options?: {
  preAlert?: DurationInSeconds | null
  postAlert?: DurationInSeconds | null
}): Countdown
```

Creates a countdown configuration object.

```tsx
const countdown = AlarmManager.Countdown.create({
  preAlert: 10 * 60,
  postAlert: 5 * 60
})
```

***

## Button

```tsx
class Button {
  static create(options: {
    title?: string
    textColor?: Color
    systemImageName?: string
  }): Button
}
```

Defines the appearance of a button shown in the alert UI.

### Parameters

#### `title`

The button title.

#### `textColor`

The button text color.

In this documentation, `Color` should be provided as a hex string, for example:

```tsx
"#ffffff"
"#ff9500"
"#34c759"
```

#### `systemImageName`

The SF Symbols name to use for the button icon.

### `Button.create(options)`

```tsx
static create(options: {
  title?: string
  textColor?: Color
  systemImageName?: string
}): Button
```

```tsx
const stopButton = AlarmManager.Button.create({
  title: "Stop",
  textColor: "#ffffff",
  systemImageName: "stop.fill"
})

const snoozeButton = AlarmManager.Button.create({
  title: "Later",
  textColor: "#ffffff",
  systemImageName: "timer"
})
```

***

## Sound

```tsx
class Sound {
  static default(): Sound
  static named(name: string): Sound
}
```

Defines the alert sound.

### `Sound.default()`

```tsx
static default(): Sound
```

Uses the system default sound.

```tsx
const sound = AlarmManager.Sound.default()
```

### `Sound.named(name)`

```tsx
static named(name: string): Sound
```

Uses a sound with the specified name.

```tsx
const sound = AlarmManager.Sound.named("bell")
```

Available names depend on your underlying implementation and system support.

***

## AlertPresentation

```tsx
class AlertPresentation {
  static create(options: {
    title: string
    stopButton?: Button | null
    secondaryButton?: Button | null
    secondaryBehavior?: SecondaryButtonBehavior | null
  }): AlertPresentation
}
```

Defines the UI shown when the alarm is alerting.

### Parameters

#### `title`

The alert title. This is required.

#### `stopButton`

> **Deprecated.** Starting with iOS 26.1 the alert's stop action is rendered by the system as a slider, not as a custom button. `stopButton` is kept only for backward compatibility and is silently ignored on iOS 26.1+. You can omit it.

The stop button appearance (iOS 26.0 fallback only).

#### `secondaryButton`

The secondary button appearance.

#### `secondaryBehavior`

The behavior of the secondary button. Possible values:

- `"countdown"`
- `"custom"`

### `AlertPresentation.create(options)`

```tsx
static create(options: {
  title: string
  stopButton?: Button | null
  secondaryButton?: Button | null
  secondaryBehavior?: SecondaryButtonBehavior | null
}): AlertPresentation
```

```tsx
const alert = AlarmManager.AlertPresentation.create({
  title: "Wake up",
  stopButton: AlarmManager.Button.create({
    title: "Dismiss",
    textColor: "#ffffff",
    systemImageName: "xmark"
  }),
  secondaryButton: AlarmManager.Button.create({
    title: "Remind me later",
    textColor: "#ffffff",
    systemImageName: "timer"
  }),
  secondaryBehavior: "countdown"
})
```

***

## CountdownPresentation

```tsx
class CountdownPresentation {
  static create(title?: string | null, pauseButton?: Button | null): CountdownPresentation
}
```

Defines the UI shown while a countdown is running.

### `CountdownPresentation.create(title?, pauseButton?)`

```tsx
static create(title?: string | null, pauseButton?: Button | null): CountdownPresentation
```

```tsx
const countdownPresentation = AlarmManager.CountdownPresentation.create(
  "Focus session in progress",
  AlarmManager.Button.create({
    title: "Pause",
    textColor: "#ffffff",
    systemImageName: "pause.fill"
  })
)
```

***

## PausedPresentation

```tsx
class PausedPresentation {
  static create(title?: string | null, resumeButton?: Button | null): PausedPresentation | null
}
```

Defines the UI shown while a countdown is paused.

### `PausedPresentation.create(title?, resumeButton?)`

```tsx
static create(title?: string | null, resumeButton?: Button | null): PausedPresentation | null
```

```tsx
const pausedPresentation = AlarmManager.PausedPresentation.create(
  "Paused",
  AlarmManager.Button.create({
    title: "Resume",
    textColor: "#ffffff",
    systemImageName: "play.fill"
  })
)
```

***

## Attributes

```tsx
class Attributes {
  static create(options: {
    alert: AlertPresentation
    countdown?: CountdownPresentation | null
    paused?: PausedPresentation | null
    tintColor?: Color
    metadata?: Record<string, string>
    liveActivity?: {
      name: string
    }
  }): Attributes | null
}
```

Combines the full presentation configuration for an alarm.

### Parameters

#### `alert`

The alert presentation shown when the alarm fires. This is required.

#### `countdown`

The presentation shown while countdown is running.

#### `paused`

The presentation shown while countdown is paused.

#### `tintColor`

The main tint color. Hex strings are recommended, such as:

```tsx
"#ffffff"
"#007aff"
"#ff9500"
```

#### `metadata`

Additional metadata for your own business logic.

#### `liveActivity`

Optional custom Live Activity UI binding. If the current script provides `alarm_live_activity.tsx` and registers the same name with `AlarmLiveActivity.register`, Scripting renders that UI on the Lock Screen and Dynamic Island. Otherwise, it uses the built-in alarm UI.

```tsx
liveActivity: {
  name: "FocusTimerActivity"
}
```

See the **Alarm Live Activity** document for the full UI builder API.

### `Attributes.create(options)`

```tsx
static create(options: {
  alert: AlertPresentation
  countdown?: CountdownPresentation | null
  paused?: PausedPresentation | null
  tintColor?: Color
  metadata?: Record<string, string>
  liveActivity?: {
    name: string
  }
}): Attributes | null
```

```tsx
const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Pomodoro finished",
    stopButton: AlarmManager.Button.create({
      title: "Done",
      textColor: "#ffffff",
      systemImageName: "checkmark"
    })
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Focusing",
    AlarmManager.Button.create({
      title: "Pause",
      textColor: "#ffffff",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Paused",
    AlarmManager.Button.create({
      title: "Resume",
      textColor: "#ffffff",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#ff9500",
  metadata: {
    type: "pomodoro",
    source: "study-script"
  },
  liveActivity: {
    name: "FocusTimerActivity"
  }
})
```

***

## Configuration

```tsx
class Configuration {
  static alarm(options: {
    schedule?: Schedule | null
    attributes: Attributes
    sound?: Sound | null
    stopIntent?: AlarmAppIntent | null
    secondaryIntent?: AlarmAppIntent | null
  }): Configuration | null

  static timer(options: {
    duration: DurationInSeconds
    attributes: Attributes
    sound?: Sound | null
    stopIntent?: AlarmAppIntent | null
    secondaryIntent?: AlarmAppIntent | null
  }): Configuration | null

  static countdown(options: {
    countdown?: Countdown | null
    schedule?: Schedule | null
    attributes: Attributes
    sound?: Sound | null
    stopIntent?: AlarmAppIntent | null
    secondaryIntent?: AlarmAppIntent | null
  }): Configuration | null
}
```

Creates the final configuration object passed to `AlarmManager.schedule()`.

***

## Configuration.alarm

```tsx
static alarm(options: {
  schedule?: Schedule | null
  attributes: Attributes
  sound?: Sound | null
  stopIntent?: AlarmAppIntent | null
  secondaryIntent?: AlarmAppIntent | null
}): Configuration | null
```

Creates a regular alarm configuration.

Suitable for:

- One-time alarms
- Daily alarms
- Weekly recurring alarms

### Parameters

#### `schedule`

The alarm schedule.

#### `attributes`

The presentation attributes. Required.

#### `sound`

The alert sound.

#### `stopIntent`

An `AppIntent` bound to the stop button.

#### `secondaryIntent`

An `AppIntent` bound to the secondary button.

### Example

```tsx
const schedule = AlarmManager.Schedule.fixed(
  new Date("2026-03-20T07:30:00")
)

const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Good morning, time to wake up",
    stopButton: AlarmManager.Button.create({
      title: "Dismiss",
      textColor: "#ffffff",
      systemImageName: "xmark"
    }),
    secondaryButton: AlarmManager.Button.create({
      title: "Later",
      textColor: "#ffffff",
      systemImageName: "timer"
    }),
    secondaryBehavior: "countdown"
  }),
  tintColor: "#34c759",
  metadata: {
    category: "morning"
  }
})

const configuration = AlarmManager.Configuration.alarm({
  schedule,
  attributes,
  sound: AlarmManager.Sound.default()
})
```

***

## Configuration.timer

```tsx
static timer(options: {
  duration: DurationInSeconds
  attributes: Attributes
  sound?: Sound | null
  stopIntent?: AlarmAppIntent | null
  secondaryIntent?: AlarmAppIntent | null
}): Configuration | null
```

Creates a timer configuration.

Suitable for:

- Pomodoro timers
- Workout timers
- Cooking reminders
- Short focus sessions

### Parameters

#### `duration`

The total duration of the timer, in seconds.

#### `attributes`

The presentation attributes. Required.

#### `sound`

The alert sound.

#### `stopIntent`

An `AppIntent` bound to the stop action.

#### `secondaryIntent`

An `AppIntent` bound to the secondary action.

### Example

```tsx
const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "25-minute focus session finished",
    stopButton: AlarmManager.Button.create({
      title: "Done",
      textColor: "#ffffff",
      systemImageName: "checkmark"
    })
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Focusing",
    AlarmManager.Button.create({
      title: "Pause",
      textColor: "#ffffff",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Paused",
    AlarmManager.Button.create({
      title: "Resume",
      textColor: "#ffffff",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#ff9500",
  metadata: {
    mode: "focus"
  }
})

const configuration = AlarmManager.Configuration.timer({
  duration: 25 * 60,
  attributes,
  sound: AlarmManager.Sound.default()
})
```

***

## Configuration.countdown

```tsx
static countdown(options: {
  countdown?: Countdown | null
  schedule?: Schedule | null
  attributes: Attributes
  sound?: Sound | null
  stopIntent?: AlarmAppIntent | null
  secondaryIntent?: AlarmAppIntent | null
}): Configuration | null
```

Creates a countdown reminder configuration.

Suitable for:

- Triggering a countdown after a scheduled time
- “Remind me later” flows
- Custom pre-alert and post-alert countdown behavior

### Parameters

#### `countdown`

The countdown configuration.

#### `schedule`

The schedule rule.

#### `attributes`

The presentation attributes. Required.

#### `sound`

The alert sound.

#### `stopIntent`

An `AppIntent` bound to the stop action.

#### `secondaryIntent`

An `AppIntent` bound to the secondary action.

### Example

```tsx
const countdown = AlarmManager.Countdown.create({
  preAlert: 15 * 60,
  postAlert: 5 * 60
})

const schedule = AlarmManager.Schedule.relative(21, 0)

const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Get ready to rest",
    stopButton: AlarmManager.Button.create({
      title: "OK",
      textColor: "#ffffff",
      systemImageName: "bed.double.fill"
    }),
    secondaryButton: AlarmManager.Button.create({
      title: "Remind me in 15 minutes",
      textColor: "#ffffff",
      systemImageName: "timer"
    }),
    secondaryBehavior: "countdown"
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Rest countdown in progress",
    AlarmManager.Button.create({
      title: "Pause",
      textColor: "#ffffff",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Paused",
    AlarmManager.Button.create({
      title: "Resume",
      textColor: "#ffffff",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#af52de",
  metadata: {
    scene: "night"
  }
})

const configuration = AlarmManager.Configuration.countdown({
  countdown,
  schedule,
  attributes,
  sound: AlarmManager.Sound.default()
})
```

***

## isAvailable

```tsx
const isAvailable: boolean
```

Indicates whether AlarmKit is available in the current environment.

```tsx
if (!AlarmManager.isAvailable) {
  throw new Error("AlarmManager is not available")
}
```

***

## alarms

```tsx
function alarms(): Promise<Alarm[]>
```

Returns all current alarms.

### Return Value

Returns `Promise<Alarm[]>`.

### Example

```tsx
const list = await AlarmManager.alarms()

for (const alarm of list) {
  console.log(alarm.id, alarm.state)
}
```

***

## schedule

```tsx
function schedule(id: string, configuration: Configuration): Promise<Alarm>
```

Creates and schedules an alarm using the provided configuration.

### Parameters

#### `id`

The unique alarm ID.

It must be generated with `UUID.string()`.

#### `configuration`

A configuration created by `AlarmManager.Configuration.alarm()`, `timer()`, or `countdown()`.

### Return Value

Returns the created `Alarm`.

### Example

```tsx
const configuration = AlarmManager.Configuration.timer({
  duration: 10 * 60,
  attributes: AlarmManager.Attributes.create({
    alert: AlarmManager.AlertPresentation.create({
      title: "10 minutes are up",
      stopButton: AlarmManager.Button.create({
        title: "Stop",
        textColor: "#ffffff",
        systemImageName: "stop.fill"
      })
    }),
    countdown: AlarmManager.CountdownPresentation.create(
      "Counting down",
      AlarmManager.Button.create({
        title: "Pause",
        textColor: "#ffffff",
        systemImageName: "pause.fill"
      })
    ),
    paused: AlarmManager.PausedPresentation.create(
      "Paused",
      AlarmManager.Button.create({
        title: "Resume",
        textColor: "#ffffff",
        systemImageName: "play.fill"
      })
    ),
    tintColor: "#007aff"
  }),
  sound: AlarmManager.Sound.default()
})

const id = UUID.string()
const alarm = await AlarmManager.schedule(id, configuration)

console.log(alarm.id, alarm.state)
```

***

## cancel

```tsx
function cancel(id: string): Promise<boolean>
```

Cancels the specified alarm.

### Parameters

#### `id`

The alarm ID to cancel.

### Return Value

Returns whether the operation succeeded.

### Example

```tsx
const success = await AlarmManager.cancel(alarmId)
console.log("Cancel result:", success)
```

***

## stop

```tsx
function stop(id: string): Promise<boolean>
```

Stops the specified alarm or alert.

This is typically used when an alarm is already alerting, or when the current flow should be terminated.

### Example

```tsx
const success = await AlarmManager.stop(alarmId)
console.log("Stop result:", success)
```

***

## pause

```tsx
function pause(id: string): Promise<boolean>
```

Pauses the specified countdown or timer.

### Example

```tsx
const success = await AlarmManager.pause(alarmId)
console.log("Pause result:", success)
```

***

## resume

```tsx
function resume(id: string): Promise<boolean>
```

Resumes a paused countdown or timer.

### Example

```tsx
const success = await AlarmManager.resume(alarmId)
console.log("Resume result:", success)
```

***

## startCountdown

```tsx
function startCountdown(id: string): Promise<boolean>
```

Starts the countdown flow for the specified alarm.

This is usually used with alarms created using `Configuration.countdown()` or flows that include “remind me later” behavior.

### Example

```tsx
const success = await AlarmManager.startCountdown(alarmId)
console.log("Start countdown result:", success)
```

***

## addAlarmUpdateListener

```tsx
function addAlarmUpdateListener(listener: AlarmUpdateListener): void
```

Adds an alarm update listener.

When the alarm list changes, the callback receives the latest `Alarm[]`.

### Example

```tsx
const listener = (alarms: AlarmManager.Alarm[]) => {
  console.log("Alarm count:", alarms.length)
  for (const alarm of alarms) {
    console.log(alarm.id, alarm.state)
  }
}

AlarmManager.addAlarmUpdateListener(listener)
```

***

## removeAlarmUpdateListener

```tsx
function removeAlarmUpdateListener(listener?: AlarmUpdateListener): void
```

Removes a previously added listener, or removes all listeners if no argument is provided.

### Parameters

#### `listener`

The listener function to remove.

If this argument is omitted, the exact behavior depends on your underlying implementation.

### Example

```tsx
const listener = (alarms: AlarmManager.Alarm[]) => {
  console.log("Updated:", alarms.length)
}

AlarmManager.addAlarmUpdateListener(listener)

AlarmManager.removeAlarmUpdateListener(listener)
```

***

## Using AppIntent with AlarmManager

`AlarmManager` supports `AppIntent` through `stopIntent` and `secondaryIntent`.

This allows alert buttons to do more than just stop an alert or start a countdown. They can also run custom script logic, for example:

- Marking a task as completed when the user taps Stop
- Updating local state when an alert is dismissed
- Refreshing Widgets or Live Activities after “Later” is tapped
- Triggering additional business logic through global APIs

***

## Where AppIntent Must Be Defined

All `AppIntent` definitions must be placed in:

```tsx
app_intents.tsx
```

Do not define them in `widget.tsx`, `live_activity.tsx`, `control_widget.tsx`, or regular script files.

When an `AppIntent` runs:

```tsx
Script.env === "app_intents"
```

That means the `perform` function always executes in the `app_intents` environment.

***

## AppIntent Types

### AppIntent<T>

Represents a concrete app intent instance.

| Field      | Type                | Description                                        |
| ---------- | ------------------- | -------------------------------------------------- |
| `script`   | `string`            | The script path, generated internally              |
| `name`     | `string`            | The unique intent name                             |
| `protocol` | `AppIntentProtocol` | The protocol type used by the intent               |
| `params`   | `T`                 | The parameters passed when the intent is triggered |

### AppIntentFactory<T>

```tsx
type AppIntentFactory<T> = (params: T) => AppIntent<T>
```

A factory function that creates an `AppIntent` instance from parameters.

### AppIntentPerform<T>

```tsx
type AppIntentPerform<T> = (params: T) => Promise<void>
```

The async function that runs when the intent is triggered.

### AppIntentProtocol

| Enum Member            | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| `AppIntent`            | A regular app intent                                         |
| `AudioPlaybackIntent`  | An intent for controlling audio playback                     |
| `AudioRecordingIntent` | An intent for controlling audio recording                    |
| `LiveActivityIntent`   | An intent for starting, pausing, or updating Live Activities |

For `AlarmManager`, you should use:

```tsx
AppIntentProtocol.LiveActivityIntent
```

***

## AppIntentManager.register

```tsx
static register<T = undefined>(options: {
  name: string
  protocol: AppIntentProtocol
  perform: AppIntentPerform<T>
}): AppIntentFactory<T>
```

Registers a new `AppIntent`.

### Parameters

#### `name`

The unique intent name.

#### `protocol`

The protocol type for the intent.

#### `perform`

The async function that runs when the intent is triggered.

### Return Value

Returns a factory function that creates the corresponding `AppIntent` instance.

***

## AppIntent Example for AlarmManager

The example below shows how to define two intents in `app_intents.tsx` for use with `AlarmManager`.

```tsx
/// app_intents.tsx

export const StopFocusAlarmIntent = AppIntentManager.register({
  name: "StopFocusAlarmIntent",
  protocol: AppIntentProtocol.LiveActivityIntent,
  perform: async ({ alarmId, taskId }: { alarmId: string; taskId: string }) => {
    console.log("Stopping alert:", alarmId, taskId)

    // Your custom logic goes here
    // For example, update task state, save logs, refresh UI, etc.
    await Storage.set(`task:${taskId}:finished`, true)

    Widget.reloadAll()
  }
})

export const SnoozeFocusAlarmIntent = AppIntentManager.register({
  name: "SnoozeFocusAlarmIntent",
  protocol: AppIntentProtocol.LiveActivityIntent,
  perform: async ({ alarmId }: { alarmId: string }) => {
    console.log("Snoozing alert:", alarmId)

    Widget.reloadAll()
  }
})
```

***

## Binding AppIntent to AlarmManager

Once the intents are defined, they can be attached through `stopIntent` and `secondaryIntent`.

```tsx
const alarmId = UUID.string()

const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Focus session finished",
    stopButton: AlarmManager.Button.create({
      title: "Done",
      textColor: "#ffffff",
      systemImageName: "checkmark"
    }),
    secondaryButton: AlarmManager.Button.create({
      title: "Snooze 5 min",
      textColor: "#ffffff",
      systemImageName: "timer"
    }),
    secondaryBehavior: "custom"
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Counting down",
    AlarmManager.Button.create({
      title: "Pause",
      textColor: "#ffffff",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Paused",
    AlarmManager.Button.create({
      title: "Resume",
      textColor: "#ffffff",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#007aff",
  metadata: {
    type: "focus"
  }
})

const configuration = AlarmManager.Configuration.timer({
  duration: 25 * 60,
  attributes,
  sound: AlarmManager.Sound.default(),
  stopIntent: StopFocusAlarmIntent({
    alarmId,
    taskId: "task_001"
  }),
  secondaryIntent: SnoozeFocusAlarmIntent({
    alarmId
  })
})

await AlarmManager.schedule(alarmId, configuration)
```

In this example:

- The stop button triggers `StopFocusAlarmIntent`
- The secondary button triggers `SnoozeFocusAlarmIntent`
- The secondary button uses `"custom"`, so its behavior is fully defined by `secondaryIntent`

***

## Using Countdown Behavior for the Secondary Button

If you want the secondary button to directly use AlarmKit’s countdown behavior, set:

```tsx
secondaryBehavior: "countdown"
```

Example:

```tsx
const alarmId = UUID.string()

const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Time to rest",
    stopButton: AlarmManager.Button.create({
      title: "Dismiss",
      textColor: "#ffffff",
      systemImageName: "xmark"
    }),
    secondaryButton: AlarmManager.Button.create({
      title: "Remind me in 10 minutes",
      textColor: "#ffffff",
      systemImageName: "timer"
    }),
    secondaryBehavior: "countdown"
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Snooze countdown in progress",
    AlarmManager.Button.create({
      title: "Pause",
      textColor: "#ffffff",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Paused",
    AlarmManager.Button.create({
      title: "Resume",
      textColor: "#ffffff",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#ff3b30"
})

const configuration = AlarmManager.Configuration.countdown({
  countdown: AlarmManager.Countdown.create({
    preAlert: 10 * 60
  }),
  attributes,
  sound: AlarmManager.Sound.default()
})

await AlarmManager.schedule(alarmId, configuration)
```

This approach is better for standard snooze-style interactions.

***

## Creating a One-Time Alarm

```tsx
if (!AlarmManager.isAvailable) {
  throw new Error("AlarmKit is not available in the current environment")
}

const alarmId = UUID.string()

const schedule = AlarmManager.Schedule.fixed(
  new Date("2026-03-20T22:30:00")
)

const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Time to rest",
    stopButton: AlarmManager.Button.create({
      title: "Dismiss",
      textColor: "#ffffff",
      systemImageName: "xmark"
    }),
    secondaryButton: AlarmManager.Button.create({
      title: "Remind me in 10 minutes",
      textColor: "#ffffff",
      systemImageName: "timer"
    }),
    secondaryBehavior: "countdown"
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Snooze countdown in progress",
    AlarmManager.Button.create({
      title: "Pause",
      textColor: "#ffffff",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Paused",
    AlarmManager.Button.create({
      title: "Resume",
      textColor: "#ffffff",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#ff3b30",
  metadata: {
    purpose: "sleep"
  }
})

const configuration = AlarmManager.Configuration.alarm({
  schedule,
  attributes,
  sound: AlarmManager.Sound.default()
})

const alarm = await AlarmManager.schedule(alarmId, configuration)
console.log("Created:", alarm.id, alarm.state)
```

***

## Creating a Weekly Recurring Alarm

```tsx
const alarmId = UUID.string()

const schedule = AlarmManager.Schedule.weekly(7, 30, [2, 3, 4, 5, 6])

const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Weekday wake-up reminder",
    stopButton: AlarmManager.Button.create({
      title: "Wake Up",
      textColor: "#ffffff",
      systemImageName: "sun.max.fill"
    })
  }),
  tintColor: "#34c759",
  metadata: {
    tag: "weekday-morning"
  }
})

const configuration = AlarmManager.Configuration.alarm({
  schedule,
  attributes,
  sound: AlarmManager.Sound.default()
})

await AlarmManager.schedule(alarmId, configuration)
```

***

## Creating a Pomodoro Timer

```tsx
const alarmId = UUID.string()

const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Your focus session has ended",
    stopButton: AlarmManager.Button.create({
      title: "Done",
      textColor: "#ffffff",
      systemImageName: "checkmark.circle.fill"
    })
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Focusing",
    AlarmManager.Button.create({
      title: "Pause",
      textColor: "#ffffff",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Focus paused",
    AlarmManager.Button.create({
      title: "Resume",
      textColor: "#ffffff",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#ff9500",
  metadata: {
    type: "pomodoro",
    duration: "1500"
  }
})

const configuration = AlarmManager.Configuration.timer({
  duration: 25 * 60,
  attributes,
  sound: AlarmManager.Sound.default()
})

await AlarmManager.schedule(alarmId, configuration)
```

***

## Creating a Manually Started Countdown Reminder

```tsx
const alarmId = UUID.string()

const countdown = AlarmManager.Countdown.create({
  preAlert: 5 * 60,
  postAlert: 60
})

const attributes = AlarmManager.Attributes.create({
  alert: AlarmManager.AlertPresentation.create({
    title: "Snooze time is over",
    stopButton: AlarmManager.Button.create({
      title: "Got it",
      textColor: "#ffffff",
      systemImageName: "bell.slash.fill"
    })
  }),
  countdown: AlarmManager.CountdownPresentation.create(
    "Snooze in progress",
    AlarmManager.Button.create({
      title: "Pause",
      textColor: "#ffffff",
      systemImageName: "pause.fill"
    })
  ),
  paused: AlarmManager.PausedPresentation.create(
    "Countdown paused",
    AlarmManager.Button.create({
      title: "Resume",
      textColor: "#ffffff",
      systemImageName: "play.fill"
    })
  ),
  tintColor: "#af52de"
})

const configuration = AlarmManager.Configuration.countdown({
  countdown,
  attributes,
  sound: AlarmManager.Sound.default()
})

await AlarmManager.schedule(alarmId, configuration)
await AlarmManager.startCountdown(alarmId)
```

***

## Querying and Controlling Alarms

```tsx
const alarms = await AlarmManager.alarms()
console.log("Alarm count:", alarms.length)

const firstAlarm = alarms[0]
if (firstAlarm) {
  await AlarmManager.pause(firstAlarm.id)
  await AlarmManager.resume(firstAlarm.id)
  await AlarmManager.stop(firstAlarm.id)
}
```

***

## Listening for Alarm State Changes

```tsx
const listener = (alarms: AlarmManager.Alarm[]) => {
  const summary = alarms.map(item => ({
    id: item.id,
    state: item.state
  }))
  console.log("Latest alarm states:", JSON.stringify(summary, null, 2))
}

AlarmManager.addAlarmUpdateListener(listener)

// Remove when no longer needed
// AlarmManager.removeAlarmUpdateListener(listener)
```

***

## Execution Environment

`AlarmManager` itself is a global API and can be used directly in regular scripts.

However, if you attach `AppIntent` objects to `AlarmManager`, those intent `perform` functions always run in:

```tsx
Script.env === "app_intents"
```

That means:

- Alarm creation logic such as `AlarmManager.schedule()` usually runs in a normal script environment
- Logic for `stopIntent` and `secondaryIntent` runs in the `perform` functions defined in `app_intents.tsx`
- Inside `perform`, you can safely do things like network requests, state updates, Widget refreshes, and Live Activity updates

***

## Best Practices

### Always use UUID.string() for alarmId

This is a strict requirement of `AlarmManager`.

```tsx
const alarmId = UUID.string()
```

### Keep the generated alarmId

Once an alarm is created, keep the `alarmId` if you need to pause, resume, stop, or cancel it later.

### Use metadata for business-related information

Store task IDs, source pages, scene names, or other app-specific values there.

```tsx
metadata: {
  taskId: "task_123",
  scene: "study",
  source: "focus-page"
}
```

### Keep all AppIntent definitions in app\_intents.tsx

Do not scatter them across multiple files.

### Use explicit parameter types for AppIntent

This improves type checking and editor completion.

```tsx
perform: async ({ alarmId, taskId }: { alarmId: string; taskId: string }) => {
  // ...
}
```

### Prefer countdown for standard snooze behavior

If you only need a normal “remind me again in a few minutes” flow, prefer:

```tsx
secondaryBehavior: "countdown"
```

If you need completely custom logic, use:

```tsx
secondaryBehavior: "custom"
secondaryIntent: ...
```

***

## Notes

### Attributes.create(...) may return null

```tsx
const attributes = AlarmManager.Attributes.create(...)
```

Its return type is `Attributes | null`, so you should validate the result in stricter flows.

### Configuration methods may also return null

```tsx
const configuration = AlarmManager.Configuration.timer(...)
```

These methods also allow `null`, so validate before calling `schedule()`.

### pause, resume, and startCountdown are not meaningful for every alarm type

These methods are generally intended for timers or countdown-based flows. For fixed-time alarms, some operations may not make sense.

***

## Full Example

The example below shows a complete flow that includes `AppIntent`.

```tsx
/// app_intents.tsx

export const StopPomodoroIntent = AppIntentManager.register({
  name: "StopPomodoroIntent",
  protocol: AppIntentProtocol.LiveActivityIntent,
  perform: async ({ alarmId, sessionId }: { alarmId: string; sessionId: string }) => {
    console.log("Pomodoro finished:", alarmId, sessionId)
    await Storage.set(`pomodoro:${sessionId}:done`, true)
    Widget.reloadAll()
  }
})

export const ExtendPomodoroIntent = AppIntentManager.register({
  name: "ExtendPomodoroIntent",
  protocol: AppIntentProtocol.LiveActivityIntent,
  perform: async ({ alarmId, extraMinutes }: { alarmId: string; extraMinutes: number }) => {
    console.log("Extending Pomodoro:", alarmId, extraMinutes)
    Widget.reloadAll()
  }
})
```

```tsx
/// regular script file

async function main() {
  if (!AlarmManager.isAvailable) {
    console.log("AlarmManager is not available")
    return
  }

  const listener = (alarms: AlarmManager.Alarm[]) => {
    console.log(
      "Alarm update:",
      alarms.map(item => `${item.id}:${item.state}`).join(", ")
    )
  }

  AlarmManager.addAlarmUpdateListener(listener)

  const alarmId = UUID.string()

  const attributes = AlarmManager.Attributes.create({
    alert: AlarmManager.AlertPresentation.create({
      title: "Focus session finished",
      stopButton: AlarmManager.Button.create({
        title: "Done",
        textColor: "#ffffff",
        systemImageName: "checkmark"
      }),
      secondaryButton: AlarmManager.Button.create({
        title: "Extend 5 min",
        textColor: "#ffffff",
        systemImageName: "timer"
      }),
      secondaryBehavior: "custom"
    }),
    countdown: AlarmManager.CountdownPresentation.create(
      "Focusing",
      AlarmManager.Button.create({
        title: "Pause",
        textColor: "#ffffff",
        systemImageName: "pause.fill"
      })
    ),
    paused: AlarmManager.PausedPresentation.create(
      "Paused",
      AlarmManager.Button.create({
        title: "Resume",
        textColor: "#ffffff",
        systemImageName: "play.fill"
      })
    ),
    tintColor: "#007aff",
    metadata: {
      feature: "focus-mode"
    }
  })

  if (!attributes) {
    throw new Error("Failed to create Attributes")
  }

  const configuration = AlarmManager.Configuration.timer({
    duration: 15 * 60,
    attributes,
    sound: AlarmManager.Sound.default(),
    stopIntent: StopPomodoroIntent({
      alarmId,
      sessionId: "session_001"
    }),
    secondaryIntent: ExtendPomodoroIntent({
      alarmId,
      extraMinutes: 5
    })
  })

  if (!configuration) {
    throw new Error("Failed to create Configuration")
  }

  const alarm = await AlarmManager.schedule(alarmId, configuration)
  console.log("Created alarm:", alarm.id, alarm.state)

  const current = await AlarmManager.alarms()
  console.log("Current alarms:", current.map(item => item.id))

  await AlarmManager.pause(alarmId)
  await AlarmManager.resume(alarmId)

  // Remove when finished
  // AlarmManager.removeAlarmUpdateListener(listener)
}

main().catch(error => {
  console.log(String(error))
})
```



---
url: /guide/Changelog/3.0.0/FileManager.md
---

# FileManager

The **FileManager** module provides a unified interface for interacting with the file system in Scripting. It serves as the primary API for accessing local files, iCloud files, App Group shared storage, and performing common file operations such as reading, writing, copying, moving, deleting, zipping, and unzipping.

***

## Core Properties

### `FileManager.scriptsDirectory: string`

Returns the directory path where script files are stored within the Scripting app.

### `FileManager.isiCloudEnabled: boolean`

Indicates whether iCloud is enabled for the user. Returns `false` if:

- The user is not logged into iCloud, or
- iCloud permissions have not been granted to the Scripting app.

### `FileManager.iCloudDocumentsDirectory: string`

Returns the path to the iCloud `Documents` directory.
Throws an error if iCloud is disabled. Always check `isiCloudEnabled` before calling.

### `FileManager.appGroupDocumentsDirectory: string`

Returns the path to the shared App Group `Documents` directory.
Files stored here are not accessible in the Files app, but scripts running inside Widgets can access them.

### `FileManager.isWebDAVAvailable: boolean`

Indicates whether WebDAV has been configured and is available for use.

### `FileManager.webDAVDocumentsDirectory: string`

Returns the path to the WebDAV-backed `Documents` cache directory.
Files written here will be queued for WebDAV sync after WebDAV is configured.

### `FileManager.safariBrowserDirectory: string`

Returns the Safari browser userscript data root. This directory follows the Safari Browser Data storage location configured in Settings and contains `userscripts/`, `storages/`, and `downloads/`.

Use this when an app script needs to inspect or maintain the whole Safari extension data area.

### `FileManager.safariBrowserStorageDirectory: string`

Returns the directory where Safari browser userscripts store GM value JSON files. This points to `scripting-safari-extension/storages/`.

### `FileManager.safariBrowserDownloadsDirectory: string`

Returns the directory where Safari browser userscripts save files through `GM.download`. This points to `scripting-safari-extension/downloads/`.

### `FileManager.safariBrowserUserscriptsDirectory: string`

Returns the directory where Safari browser userscripts installed from the extension popup are stored. This points to `scripting-safari-extension/userscripts/`.

### `FileManager.documentsDirectory: string`

Returns the path to the local `Documents` directory.
Files stored here are visible in the Files app. Widgets cannot access files in this directory.

### `FileManager.temporaryDirectory: string`

Returns the path to the system temporary directory.
Files stored here may be removed automatically by the system.

***

## iCloud File Management

### `FileManager.isFileStoredIniCloud(filePath: string): boolean`

Checks whether the specified file is stored in iCloud.

| Parameter | Type   | Description            |
| --------- | ------ | ---------------------- |
| filePath  | string | The file path to check |

### `FileManager.isiCloudFileDownloaded(filePath: string): boolean`

Checks whether an iCloud-stored file has been downloaded to the device.

### `FileManager.downloadFileFromiCloud(filePath: string): Promise<boolean>`

Downloads an iCloud file to the device.

| Returns           | Description                 |
| ----------------- | --------------------------- |
| Promise\<boolean> | `true` if download succeeds |

**Example:**

```ts
if (FileManager.isiCloudEnabled) {
  const file = FileManager.iCloudDocumentsDirectory + "/data.json";
  const success = await FileManager.downloadFileFromiCloud(file);
}
```

### `FileManager.getShareUrlOfiCloudFile(path: string, expiration?: number): string`

Generates a shareable download URL for an iCloud file.

| Parameter  | Type              | Description                                                                                                          |
| ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| path       | string            | The iCloud file path. Must begin with `FileManager.iCloudDocumentsDirectory`. File must be fully uploaded to iCloud. |
| expiration | number (optional) | Expiration timestamp of the share link                                                                               |

This call may throw an error. Use `try-catch` for error handling.

***

## Directory and File Operations

All operations are available in both asynchronous and synchronous forms.
Synchronous methods block execution; asynchronous versions are recommended for most use cases.

### Create Directory

#### `createDirectory(path: string, recursive?: boolean): Promise<void>`

#### `createDirectorySync(path: string, recursive?: boolean): void`

| Parameter | Type               | Description                                             |
| --------- | ------------------ | ------------------------------------------------------- |
| path      | string             | Directory path to create                                |
| recursive | boolean (optional) | If true, creates intermediate directories automatically |

### Create Symbolic Link

#### `createLink(path: string, target: string): Promise<void>`

#### `createLinkSync(path: string, target: string): void`

Creates a symbolic link at `path` pointing to `target`.

### Copy File

#### `copyFile(path: string, newPath: string): Promise<void>`

#### `copyFileSync(path: string, newPath: string): void`

### Read Directory

#### `readDirectory(path: string, recursive?: boolean): Promise<string[]>`

#### `readDirectorySync(path: string, recursive?: boolean): string[]`

Enumerates the contents of a directory and optionally recurses into subdirectories.

### Check Existence

#### `exists(path: string): Promise<boolean>`

#### `existsSync(path: string): boolean`

Checks whether a file or directory exists.

### File Bookmarks

Bookmarks allow persistent access to user-authorized external files or folders.

| Method                  | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `bookmarkExists(name)`  | Checks whether a bookmark exists                                |
| `getAllFileBookmarks()` | Returns all bookmark names and their paths                      |
| `bookmarkedPath(name)`  | Returns file path for the bookmark name, or `null` if not found |

***

### Determine File Type

| Method                            | Returns | Description                          |
| --------------------------------- | ------- | ------------------------------------ |
| `isFile / isFileSync`             | boolean | Whether the path refers to a file    |
| `isDirectory / isDirectorySync`   | boolean | Whether it refers to a directory     |
| `isLink / isLinkSync`             | boolean | Whether it refers to a symbolic link |
| `isBinaryFile / isBinaryFileSync` | boolean | Whether the file is binary           |

***

## File Reading and Writing

Supports three data formats: string, `Uint8Array`, and `Data`.

### Read File

| Method              | Return Type | Description                              |
| ------------------- | ----------- | ---------------------------------------- |
| readAsString / Sync | string      | Reads text using specified encoding      |
| readAsBytes / Sync  | Uint8Array  | Reads raw bytes                          |
| readAsData / Sync   | Data        | Reads the entire file as a `Data` object |

### Write File

| Method               | Data Format |
| -------------------- | ----------- |
| writeAsString / Sync | string      |
| writeAsBytes / Sync  | Uint8Array  |
| writeAsData / Sync   | Data        |

Existing files will be overwritten.

### Append to File

| Method            | Data Format |
| ----------------- | ----------- |
| appendText / Sync | string      |
| appendData / Sync | Data        |

If the file or its parent directory does not exist, it will be created automatically.

***

## File Information and Management

### `stat(path: string): Promise<FileStat>`

### `statSync(path: string): FileStat`

Returns a `FileStat` object for the file or directory. If the path is a symbolic link, the resolved target is reported.

### `rename / renameSync`

Moves or renames a file or directory.

### `remove / removeSync`

Removes a file or directory. Directories are removed recursively.

***

## Compression and Extraction

### `zip(srcPath: string, destPath: string, shouldKeepParent?: boolean): Promise<void>`

### `zipSync(srcPath: string, destPath: string, shouldKeepParent?: boolean): void`

Creates a zip archive from a file or directory.

### `unzip(srcPath: string, destPath: string): Promise<void>`

### `unzipSync(srcPath: string, destPath: string): void`

Extracts a zip archive to the specified destination.

**Example:**

```ts
const docs = FileManager.documentsDirectory;

await FileManager.zip(docs + "/MyScript", docs + "/MyScript.zip");
await FileManager.unzip(docs + "/MyScript.zip", docs + "/Output");
```

***

## Utility Methods

### `mimeType(path: string): string`

Returns the MIME type of the file based on its extension.

### `destinationOfSymbolicLink(path: string): string`

Returns the destination of a symbolic link.

***

## Types

### `FileStat`

```ts
type FileStat = {
  creationDate: number;
  modificationDate: number;
  type: string; // "file" | "directory" | "link" | "unixDomainSock" | "pipe" | "notFound"
  size: number;
};
```



---
url: /guide/Changelog/3.0.0/TranslationUIProvider.md
---

# TranslationUIProvider

`TranslationUIProvider` allows scripts to take control of the system translation panel’s UI and interaction flow. It enables developers to build fully customized translation interfaces and implement their own default translation logic.

When a host app invokes the translation extension, Scripting executes the `translation_ui_provider.tsx` script. Within this environment, developers can access the source text provided by the host, perform translation logic, construct a custom UI, and present it using `TranslationUIProvider.present(...)`.

This capability is suitable for scenarios such as:

- Customizing the layout and interaction of the translation panel
- Displaying source text, translated results, language selectors, and controls
- Integrating custom translation services or pipelines
- Returning translated text to replace the original content (if allowed by the host)
- Providing a read-only translation interface without modifying the original text

`TranslationUIProvider` does not perform translation itself. It provides a UI container and session control interface. Translation logic must be implemented by the developer within the script, such as calling remote APIs or local processing modules.

***

## Availability

`TranslationUIProvider` requires **iOS 18.4 or later**.

***

## Availability

`TranslationUIProvider` is only available within the Translation UI Provider execution environment and should be used in the `translation_ui_provider.tsx` file.

When the system presents the translation panel, this script acts as the entry point of the session. A typical workflow includes:

1. Read the source text from the host
2. Execute default translation logic
3. Build and present a custom UI
4. Handle user interactions (expand panel, confirm result, finish session)

***

## Execution Model

`TranslationUIProvider` serves two main purposes:

- Providing access to the current translation session context (e.g., source text, replacement capability)
- Controlling the lifecycle and UI of the translation panel

The session is created by the system and host app. Scripting automatically injects the current session into the `TranslationUIProvider` namespace when executing `translation_ui_provider.tsx`.

***

## Session Input

### inputText

```ts
const inputText: string | null
```

Represents the source text provided by the host app.

This is typically the text selected by the user or passed by the host for translation. The value may be `null`, so scripts must handle this case explicitly.

Common usage:

- Display the source text in UI
- Use it as input for translation logic
- Show fallback UI when no text is available

Example:

```ts
const source = TranslationUIProvider.inputText

if (!source) {
  TranslationUIProvider.present(
    <Text>No text available for translation.</Text>
  )
}
```

`inputText` reflects the initial session input and should not be assumed to always exist.

***

### allowsReplacement

```ts
const allowsReplacement: boolean
```

Indicates whether the host app allows replacing the original text with the translated result.

If `true`, scripts can return a translation via `finish(translatedText)`. If `false`, translations can only be displayed, not applied.

Typical usage:

- Conditionally show “Replace” or “Use Translation” actions
- Adjust UI behavior based on capability

Example:

```ts
const canReplace = TranslationUIProvider.allowsReplacement
```

When replacement is not allowed, the UI should avoid presenting misleading actions.

***

## Panel Control

### present(node)

```ts
function present(node: VirtualNode): void
```

Displays the scripted UI in the translation panel.

This is the primary entry point for rendering UI. Developers should construct a `VirtualNode` and pass it to `present(...)`.

Example:

```tsx
import { Text, VStack } from "scripting"

TranslationUIProvider.present(
  <VStack spacing={12}>
    <Text>Custom Translation Panel</Text>
    <Text>{TranslationUIProvider.inputText ?? "No input text"}</Text>
  </VStack>
)
```

It is recommended to encapsulate the UI into a component:

```tsx
function TranslationView() {
  const source = TranslationUIProvider.inputText

  return <VStack spacing={12}>
    <Text>Original</Text>
    <Text>{source ?? "No input text"}</Text>
  </VStack>
}

TranslationUIProvider.present(<TranslationView />)
```

`present(...)` only renders the UI. It does not end the session or return results.

***

### expandSheet()

```ts
function expandSheet(): void
```

Requests the system to expand the translation panel.

This is useful when:

- Displaying long content
- Showing multiple translation results
- Providing advanced controls

Example:

```ts
TranslationUIProvider.expandSheet()
```

This is a request, not a guarantee. The system decides how to handle it.

***

### finish(translation?)

```ts
function finish(translation?: string | null): void
```

Ends the current translation session and optionally returns a translated result.

Two common patterns:

Close without replacement:

```ts
TranslationUIProvider.finish()
```

Close and return translation:

```ts
TranslationUIProvider.finish("Hello world")
```

Typical usage:

```ts
if (TranslationUIProvider.allowsReplacement) {
  TranslationUIProvider.finish(translatedText)
} else {
  TranslationUIProvider.finish()
}
```

Notes:

- Calling `finish(...)` ends the session immediately
- Passing a string attempts to return it to the host
- Passing `null` or omitting closes without replacement
- Final behavior depends on host capabilities

***

## Recommended Development Pattern

A typical structure in `translation_ui_provider.tsx`:

1. Read `inputText`
2. Handle empty input
3. Execute translation logic
4. Build UI with source and translated text
5. Let user confirm or cancel
6. Call `finish(...)` accordingly

***

## Example: Minimal Translation Panel

```tsx
import { Button, Text, VStack } from "scripting"

function TranslationView() {
  const source = TranslationUIProvider.inputText

  return <VStack spacing={12} padding={16}>
    <Text>Original Text</Text>
    <Text>{source ?? "No text available"}</Text>

    <Button
      title="Close"
      action={() => {
        TranslationUIProvider.finish()
      }}
    />
  </VStack>
}

TranslationUIProvider.present(<TranslationView />)
```

***

## Example: With Translation Result and Replacement

```tsx
import { Button, HStack, Text, VStack, useMemo } from "scripting"

function TranslationView() {
  const source = TranslationUIProvider.inputText
  const canReplace = TranslationUIProvider.allowsReplacement

  const translatedText = useMemo(() => {
    if (!source) return ""
    return `[Translated] ${source}`
  }, [source])

  if (!source) {
    return <VStack spacing={12} padding={16}>
      <Text>No text available for translation.</Text>
      <Button
        title="Close"
        action={() => {
          TranslationUIProvider.finish()
        }}
      />
    </VStack>
  }

  return <VStack spacing={16} padding={16}>
    <Text>Original</Text>
    <Text>{source}</Text>

    <Text>Translation</Text>
    <Text>{translatedText}</Text>

    <HStack spacing={12}>
      <Button
        title="Close"
        action={() => {
          TranslationUIProvider.finish()
        }}
      />

      {canReplace ? (
        <Button
          title="Use Translation"
          action={() => {
            TranslationUIProvider.finish(translatedText)
          }}
        />
      ) : null}
    </HStack>
  </VStack>
}

TranslationUIProvider.present(<TranslationView />)
```

***

## Example: Expanding the Panel

```tsx
import { Button, Text, VStack } from "scripting"

function TranslationView() {
  return <VStack spacing={12} padding={16}>
    <Text>{TranslationUIProvider.inputText ?? "No input text"}</Text>

    <Button
      title="Expand"
      action={() => {
        TranslationUIProvider.expandSheet()
      }}
    />

    <Button
      title="Close"
      action={() => {
        TranslationUIProvider.finish()
      }}
    />
  </VStack>
}

TranslationUIProvider.present(<TranslationView />)
```

***

## Lifecycle Notes

- `TranslationUIProvider` is scoped to the current translation session
- It is only valid during execution of `translation_ui_provider.tsx`
- `finish(...)` terminates the session
- After finishing, no further UI updates should be performed
- `present(...)` is typically called once to render the main UI

***

## Relationship with Translation Logic

`TranslationUIProvider` handles UI and session control, not translation.

Developers are responsible for implementing translation logic, such as:

- Calling remote APIs
- Using local models
- Providing multiple candidate results
- Applying domain-specific processing

Recommended separation:

- `TranslationUIProvider`: UI + session control
- Translation logic: data processing
- Components: UI structure

***

## Best Practices

- Always handle `inputText === null`
- Respect `allowsReplacement` when designing actions
- Call `finish(...)` only after user confirmation
- Use `expandSheet()` only when necessary
- Keep translation logic and UI modular



---
url: /guide/Changelog/3.1.0/AVAsset Reader / Writer / Export.md
---

# 

***

title: AVAsset Reader / Writer / Export
description: Low-level media pipelines: export-session transcode, frame-level read, and frame / sample write to mp4 / m4a.
tag: PRO
--------

Three lower-level companions to `AVAsset`, mirroring the iOS `AVAssetExportSession` / `AVAssetReader` / `AVAssetWriter` APIs:

- **`AVAssetExportSession`** — high-level transcoding / re-encoding with a preset name.
- **`AVAssetReader` + outputs** — pull decoded video frames as `UIImage` or PCM audio as `Float32Array`.
- **`AVAssetWriter` + `AVAssetWriterInput`** — push frames / samples produced in JS into a new mp4 / m4a file.

> **Local files only.** Both `AVAssetReader` and `AVAssetExportSession` are unreliable when fed an HTTP-streamed asset. Download remote sources to a local path first (`fetch()` + `FileManager.writeAsBytes()`), then construct the asset from that path.

***

## AVAssetExportSession

High-level transcode / re-encode using a preset.

```ts
const asset = new AVAsset("/path/to/input.mov")
const session = new AVAssetExportSession(asset, "HEVCHighestQuality")
session.outputFileType = "mp4"
session.onProgress = p => console.log(`${(p * 100).toFixed(0)}%`)
await session.exportTo("/path/to/output.mp4")
```

### Constructor

#### `new AVAssetExportSession(asset: AVAsset, presetName: AVAssetExportPreset)`

Throws if `asset` is not a non-disposed `AVAsset`. The preset's compatibility with the asset is validated lazily inside `exportTo()`.

```ts
type AVAssetExportPreset =
  | '640x480' | '960x540' | '1280x720' | '1920x1080' | '3840x2160'
  | 'AppleM4A'
  | 'LowQuality' | 'MediumQuality' | 'HighestQuality'
  | 'HEVC1920x1080' | 'HEVC3840x2160' | 'HEVCHighestQuality'
  | 'AppleProRes422LPCM' | 'AppleProRes4444LPCM'
```

### Properties

| Property                      | Type                                                                 | Description                                                                                                                |
| ----------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `outputFileType?`             | `'mp4' \| 'mov' \| 'm4a' \| 'm4v'`                                   | Optional. Pre-validated against the preset's `supportedFileTypes` to avoid an ObjC exception that would crash the process. |
| `timeRange?`                  | `{ start: MediaTime; duration: MediaTime }`                          | Optional clip range.                                                                                                       |
| `shouldOptimizeForNetworkUse` | `boolean`                                                            | Defaults to `true`.                                                                                                        |
| `status`                      | `'unknown' \| 'exporting' \| 'completed' \| 'failed' \| 'cancelled'` | Read-only.                                                                                                                 |
| `onProgress?`                 | `(p: number) => void`                                                | Polled at \~5 Hz while exporting; final call is always `1.0`.                                                              |

### Methods

#### `exportTo(outputPath: string): Promise<void>`

Resolves on success, rejects with the underlying `session.error.localizedDescription` on failure (including the cancellation case). Calling while another export is running rejects immediately.

If `outputFileType` is incompatible with the preset, the promise rejects with a list of supported types — it does **not** throw an uncatchable ObjC `NSInvalidArgumentException`.

#### `cancel(): void`

Cancels the in-flight export. The pending `exportTo` promise rejects with `"Export cancelled."`.

#### `dispose(): void`

Releases the underlying session.

***

## AVAssetReader

Pull decoded samples from an asset, frame-by-frame or chunk-by-chunk.

```ts
const asset = new AVAsset("/path/to/input.mp4")
const tracks = await asset.loadTracks("video")

const reader = new AVAssetReader(asset)
const out = new AVAssetReaderVideoOutput(tracks[0])
reader.add(out)
reader.startReading()

for (;;) {
  const frame = await out.copyNextFrame()
  if (frame == null) break  // true end-of-stream
  console.log(frame.presentationTime.seconds, frame.image.size)
}
```

### `AVAssetReader`

| Member                     | Description                                                                       |
| -------------------------- | --------------------------------------------------------------------------------- |
| `new AVAssetReader(asset)` | Throws if `asset` is disposed or invalid.                                         |
| `add(output): boolean`     | Returns `false` if reader is past `'unknown'` or output is incompatible.          |
| `startReading(): boolean`  | Must be called after `add()` and before any `copyNextX()`.                        |
| `cancelReading()`          | Aborts reading; pending `copyNextX()` promises reject with `"Reader cancelled."`. |
| `status`                   | `'unknown' \| 'reading' \| 'completed' \| 'failed' \| 'cancelled'`                |
| `error`                    | `string \| null` — localized error message when `status === 'failed'`.            |
| `dispose()`                | Cancels and releases.                                                             |

### `AVAssetReaderVideoOutput`

```ts
class AVAssetReaderVideoOutput {
  constructor(track: AVAssetTrack, options?: { pixelFormat?: 'bgra' | 'rgba' })
  copyNextFrame(): Promise<{ image: UIImage; presentationTime: MediaTime } | null>
}
```

`copyNextFrame()` returns `null` only on a clean end-of-stream. If the reader transitions to `'failed'` or `'cancelled'`, the promise **rejects** so you don't silently see "0 frames decoded".

### `AVAssetReaderAudioOutput`

```ts
class AVAssetReaderAudioOutput {
  constructor(tracks: AVAssetTrack[], options?: { sampleRate?: number; channels?: number })
  copyNextSamples(): Promise<{
    samples: Float32Array       // length === frameCount * channels (interleaved)
    frameCount: number
    sampleRate: number
    channels: number
    presentationTime: MediaTime
  } | null>
}
```

Always interleaved 32-bit float PCM. Pass multiple tracks to mix; `options.sampleRate` and `options.channels` resample / re-channel.

***

## AVAssetWriter

Manually push UIImage frames or PCM chunks to produce a new mp4 / m4a.

```ts
const sampleRate = 44100
const writer = new AVAssetWriter("/tmp/out.m4a", "m4a")
const input = AVAssetWriterInput.audio({ sampleRate, channels: 1, codec: "pcm" })
writer.add(input)
writer.startWriting()
writer.startSession(MediaTime.zero())

const samples = new Float32Array(sampleRate)  // 1 second of silence
input.appendPCMSamples(samples, sampleRate, 1, MediaTime.make({ value: 0, timescale: sampleRate }))
input.markAsFinished()
await writer.finishWriting()
```

### `AVAssetWriter`

| Member                                        | Description                                                            |
| --------------------------------------------- | ---------------------------------------------------------------------- |
| `new AVAssetWriter(outputPath, fileType)`     | Throws on unsupported `fileType` (`'mp4' \| 'mov' \| 'm4a' \| 'm4v'`). |
| `add(input): boolean`                         | Must be called before `startWriting`.                                  |
| `startWriting(): boolean`                     |                                                                        |
| `startSession(atSourceTime: MediaTime): void` | Usually `MediaTime.zero()`.                                            |
| `finishWriting(): Promise<void>`              | Resolves on `completed`, rejects on `failed` / `cancelled`.            |
| `cancelWriting()`                             |                                                                        |
| `status`                                      | `'unknown' \| 'writing' \| 'completed' \| 'failed' \| 'cancelled'`     |
| `error`                                       | Localized error when `status === 'failed'`.                            |
| `dispose()`                                   |                                                                        |

### `AVAssetWriterInput` (static factories)

```ts
AVAssetWriterInput.video({
  width: number, height: number,
  codec?: 'h264' | 'hevc',          // default 'h264'
  bitRate?: number,                 // bits per second
  frameRate?: number,
})

AVAssetWriterInput.audio({
  sampleRate?: number,              // default 44100
  channels?: number,                // default 1
  codec?: 'aac' | 'pcm',            // default 'aac'
  bitRate?: number,                 // only meaningful for AAC
})
```

| Member                                                                       | Description                                                                         |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `isReadyForMoreMediaData`                                                    | `true` when the encoder can accept more samples without blocking.                   |
| `markAsFinished()`                                                           | Call before `writer.finishWriting()`.                                               |
| `appendVideoFrame(image, presentationTime): boolean`                         | Returns `false` when the input is full or finished — `await whenReady()` and retry. |
| `appendPCMSamples(samples, sampleRate, channels, presentationTime): boolean` | Interleaved Float32; `samples.length === frameCount * channels`.                    |
| `whenReady(): Promise<void>`                                                 | Resolves when `isReadyForMoreMediaData` becomes `true`.                             |



---
url: /guide/Changelog/3.1.0/AVAsset.md
---

# AVAsset

`AVAsset` is a heavyweight handle to a media resource (audio / video) backed by an iOS `AVURLAsset`. It lets you read media properties, metadata, and tracks, and extract still images at arbitrary times — without spinning up an `AVPlayer`.

You can also pass an `AVAsset` to `AVPlayer.setSource(asset)` to share the underlying media (and any already-loaded metadata) between inspection and playback.

***

## Getting Started

```ts
const asset = new AVAsset("https://example.com/movie.mp4")

const duration = await asset.loadDuration()
console.log("Duration:", duration.seconds, "seconds")

const playable = await asset.loadIsPlayable()
if (playable) {
  const player = new AVPlayer()
  player.setSource(asset)
  player.play()
}
```

***

## Validation

The constructor is intentionally lazy and matches the iOS `AVURLAsset` semantics:

- It does **not** verify file existence.
- It does **not** verify URL reachability.
- For remote URLs, only obviously malformed strings (where the underlying `URL(string:)` returns `nil`) throw immediately.
- All other failures (404, network errors, missing local files, unrecognized formats) surface as **Promise rejections** on the first `loadXxx()` call.

```ts
// Constructor succeeds — no validation:
const asset = new AVAsset("/does/not/exist.mp3")

// First load attempt rejects with a descriptive error:
try {
  await asset.loadDuration()
} catch (e) {
  console.error("Failed to load:", e.message)
}
```

***

## API Reference

### Constructor

#### `new AVAsset(filePathOrURL: string, options?: { headers?: Record<string, string> })`

Creates an asset from either a local file path or a remote `http(s)://` URL.

For remote URLs, you may pass HTTP headers (useful for authenticated content):

```ts
const asset = new AVAsset("https://example.com/private.mp4", {
  headers: { Authorization: "Bearer abc123" }
})
```

***

### Properties

#### `source: string`

The original file path or URL string used to construct this asset. Read-only.

***

### Async Loaders

All `loadXxx()` methods return a `Promise`. Failures (including missing files / unreachable URLs / unsupported formats) reject with an `Error`.

#### `loadDuration(): Promise<MediaTime>`

The total duration of the asset.

#### `loadIsPlayable(): Promise<boolean>`

Whether the asset can be played back.

#### `loadIsExportable(): Promise<boolean>`

Whether the asset can be exported (e.g. via `AVAssetExportSession`).

#### `loadIsReadable(): Promise<boolean>`

Whether the asset's media data can be read.

#### `loadHasProtectedContent(): Promise<boolean>`

Whether the asset has DRM-protected content.

#### `loadPreferredTransform(): Promise<{ a, b, c, d, tx, ty }>`

The 6 components of the preferred affine transform (rotation / scale / translation) used when rendering the video portion.

#### `loadMetadata(): Promise<AVMetadataItem[] | null>`

Loads all metadata items from the asset.

#### `loadCommonMetadata(): Promise<AVMetadataItem[] | null>`

Loads the common metadata items (each carries a `commonKey`).

***

### Tracks

#### `loadTracks(mediaType?: AVMediaType): Promise<AVAssetTrack[]>`

Loads tracks from the asset, optionally filtered by media type.

```ts
const videoTracks = await asset.loadTracks("video")
if (videoTracks.length > 0) {
  const size = await videoTracks[0].loadNaturalSize()
  console.log("Video size:", size.width, "x", size.height)
}
```

`AVMediaType` is one of:

```
'video' | 'audio' | 'subtitle' | 'text' | 'closedCaption' | 'metadata' | 'muxed' | 'timecode'
```

#### `AVAssetTrack`

| Member                    | Type                           | Description                            |
| ------------------------- | ------------------------------ | -------------------------------------- |
| `trackID`                 | `number`                       | Persistent identifier within the asset |
| `mediaType`               | `AVMediaType`                  | Track media type                       |
| `loadNaturalSize()`       | `Promise<Size>`                | Natural pixel dimensions               |
| `loadNaturalTimeScale()`  | `Promise<number>`              | Natural timescale                      |
| `loadNominalFrameRate()`  | `Promise<number>`              | Frames per second                      |
| `loadEstimatedDataRate()` | `Promise<number>`              | Bits per second                        |
| `loadTimeRange()`         | `Promise<{ start, duration }>` | Time range within the asset            |
| `loadLanguageCode()`      | `Promise<string \| null>`      | ISO 639-2/T language code              |

***

### Image Generation

#### `generateImage(time, options?): Promise<{ image, actualTime }>`

Generates a still image at a single requested time.

```ts
const time = MediaTime.make({ seconds: 5, preferredTimescale: 600 })
const result = await asset.generateImage(time, {
  maximumSize: { width: 640, height: 360 }
})
console.log("Got frame at", result.actualTime.seconds)
```

#### `generateImages(times, options?): Promise<...>`

Generates still images for an array of times. Each result is reported independently — successful entries carry `image` and `actualTime`; failed entries carry `error`.

```ts
const times = [0, 5, 10, 15].map(s =>
  MediaTime.make({ seconds: s, preferredTimescale: 600 })
)

const results = await asset.generateImages(times)
for (const r of results) {
  if ("image" in r) {
    console.log("Frame at", r.actualTime.seconds)
  } else {
    console.warn("Failed at", r.requestedTime.seconds, "—", r.error)
  }
}
```

#### `AVAssetImageGenerateOptions`

| Field                            | Type        | Default            | Description                                           |
| -------------------------------- | ----------- | ------------------ | ----------------------------------------------------- |
| `maximumSize`                    | `Size`      | natural            | Output size cap; aspect ratio is preserved            |
| `toleranceBefore`                | `MediaTime` | `MediaTime.zero()` | Max time before requested time the generator may pick |
| `toleranceAfter`                 | `MediaTime` | `MediaTime.zero()` | Max time after requested time the generator may pick  |
| `appliesPreferredTrackTransform` | `boolean`   | `true`             | Whether to honour the preferred track transform       |

***

### Lifecycle

#### `dispose(): void`

Releases the underlying `AVURLAsset`. Subsequent `loadXxx()` calls will reject. The script runtime auto-disposes any `AVAsset` you do not explicitly dispose when the script ends.

***

## AVAssetImageGenerator

`AVAsset.generateImage(...)` covers the one-shot "grab a cover frame" case. When you need to extract **many** frames — a thumbnail strip, per-frame OCR/ML — reach for the standalone `AVAssetImageGenerator`. Compared to the one-shot method it:

- **reuses one configured generator** across calls,
- **streams results frame-by-frame** as each one decodes (instead of waiting for the whole batch), and
- can be **cancelled mid-flight**.

```ts
const asset = new AVAsset("/path/to/movie.mp4")
const gen = new AVAssetImageGenerator(asset)

gen.maximumSize = { width: 320, height: 180 }
gen.requestedTimeToleranceBefore = MediaTime.zero()  // exact-frame
gen.requestedTimeToleranceAfter = MediaTime.zero()

const times = [0, 1, 2, 3, 4].map(s =>
  MediaTime.make({ seconds: s, preferredTimescale: 600 })
)

await gen.generate(times, frame => {
  switch (frame.status) {
    case "succeeded":
      console.log("frame", frame.actualTime.seconds, frame.image.width)
      break
    case "failed":
      console.log("failed", frame.requestedTime.seconds, frame.error)
      break
    case "cancelled":
      break
  }
})

gen.dispose()
asset.dispose()
```

### Properties

| Property                         | Type                                                         | Description                                                            |
| -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `maximumSize?`                   | `Size`                                                       | Max output size in pixels; aspect ratio preserved.                     |
| `requestedTimeToleranceBefore?`  | `MediaTime`                                                  | Tolerance before the requested time. `MediaTime.zero()` = exact frame. |
| `requestedTimeToleranceAfter?`   | `MediaTime`                                                  | Tolerance after the requested time.                                    |
| `appliesPreferredTrackTransform` | `boolean`                                                    | Respect rotation/mirroring. Defaults to `true`.                        |
| `apertureMode?`                  | `'cleanAperture' \| 'productionAperture' \| 'encodedPixels'` | Aperture mode.                                                         |

### Methods

#### `copyImage(time): Promise<{ image, actualTime }>`

Generates a single frame. Rejects with the underlying generator error.

#### `generate(times, onFrame): Promise<void>`

Generates a frame per time. `onFrame` fires once per requested time with a result tagged `succeeded` / `failed` / `cancelled`. The promise resolves once **every** time has been reported.

#### `cancel(): void`

Cancels in-flight generation. Pending times report `status: 'cancelled'` (the `generate` promise still resolves).

#### `dispose(): void`

Cancels and releases. Auto-called when the script finishes.

> **Local files only**, like the other low-level AVAsset companions. Download remote assets first.

***

## Sharing With AVPlayer

`AVPlayer.setSource(asset)` reuses the underlying media so any property already loaded on the asset is shared:

```ts
const asset = new AVAsset(url)
const metadata = await asset.loadCommonMetadata()  // pre-load before playback

const player = new AVPlayer()
player.setSource(asset)
player.play()
```

***

## Best Practices

1. **Use the right level of API** — for inspection only, prefer `AVAsset` over `AVPlayer` to avoid the playback machinery.
2. **Share assets between inspection and playback** — construct an `AVAsset` once, pass it to `AVPlayer.setSource(asset)`.
3. **Always handle Promise rejections** — failures surface there, not in the constructor.
4. **Prefer batch image generation** — `generateImages(times)` is more efficient than calling `generateImage(time)` in a loop.
5. **Tolerances trade exactness for speed** — for thumbnails, a small `toleranceBefore`/`After` (e.g. half a second) is usually faster than exact-frame seeking.

***

## Full Example

```ts
const asset = new AVAsset("/path/to/movie.mp4")

try {
  const [duration, videoTracks] = await Promise.all([
    asset.loadDuration(),
    asset.loadTracks("video"),
  ])

  console.log("Duration:", duration.seconds, "s")

  if (videoTracks.length > 0) {
    const size = await videoTracks[0].loadNaturalSize()
    console.log("Resolution:", size.width, "x", size.height)
  }

  // Take a thumbnail at the midpoint
  const mid = MediaTime.make({
    seconds: duration.seconds / 2,
    preferredTimescale: 600
  })
  const { image } = await asset.generateImage(mid, {
    maximumSize: { width: 320, height: 180 }
  })

  console.log("Thumbnail size:", image.width, "x", image.height)
} catch (e) {
  console.error("Asset error:", e.message)
} finally {
  asset.dispose()
}
```



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Camera Control (iOS 18+).md
---

# Camera Control (iOS 18+)

iOS 18 introduced the **Camera Control** — the dedicated hardware button on iPhone 16 (and on-screen control surface on other devices) that lets people adjust capture settings without diving into your UI. AVFoundation models this as a list of `AVCaptureControl` instances attached to the running `AVCaptureSession`. Scripting bridges all of them.

## Detecting support

The hardware Camera Control only ships on iPhone 16 and later. Always feature-detect:

```ts
if (!session.supportsControls) {
  // Fall back to plain on-screen UI; do not call addControl/setControlsDelegate.
  return
}
console.log(`max controls: ${session.maxControlsCount}`)
```

`session.supportsControls` is safe to call on older devices — Scripting wraps it with a `respondsToSelector` check so it just returns `false` rather than crashing.

## Built-in system controls

The two most common controls are provided by the system; pass the device they should bind to:

```ts
const camera = AVCaptureDevice.default("video")!
const zoom = new AVCaptureSystemZoomSlider(camera, value => {
  console.log("zoom →", value)
})
const exposure = new AVCaptureSystemExposureBiasSlider(camera, value => {
  console.log("exposure bias →", value)
})

session.configure(() => {
  if (session.canAddControl(zoom)) session.addControl(zoom)
  if (session.canAddControl(exposure)) session.addControl(exposure)
})
```

The system writes the zoom factor / exposure bias straight back to the device for you. The action callback is purely informational — use it to update your own UI.

## Custom slider

Continuous, stepped, or discrete-values:

```ts
// Continuous, formatted as ƒ-stops
const aperture = new AVCaptureSlider("Aperture", "camera.aperture", {
  range: [1.2, 16],
  defaultValue: 1.8,
  localizedValueFormat: "ƒ%.1f",
})

// Stepped (discrete) slider
const evStep = new AVCaptureSlider("EV", "sun.max", {
  range: [-2, 2],
  step: 0.33,
  prominentValues: [-1, 0, 1],
})

// Pre-defined values
const iso = new AVCaptureSlider("ISO", "circle.fill", {
  values: [50, 100, 200, 400, 800, 1600, 3200],
  defaultValue: 200,
  localizedValueFormat: "ISO %.0f",
})

aperture.setActionHandler(value => updateAperture(value))
```

Pass any [SF Symbols](https://developer.apple.com/sf-symbols/) name; Scripting does not validate it. If the symbol cannot be resolved at runtime the control simply renders without an icon.

## Custom index picker

Use this when titles are non-numeric or non-uniform:

```ts
const wb = new AVCaptureIndexPicker("White Balance", "camera.filters", {
  localizedIndexTitles: ["Auto", "Daylight", "Cloudy", "Tungsten"],
  defaultIndex: 0,
})
wb.setActionHandler(index => applyWhiteBalance(index))
```

## Adding controls to the session

`addControl(...)` follows the same rules as inputs/outputs: prefer `configure(...)` so the changes commit atomically. Adding more than `maxControlsCount` is a no-op (`canAddControl` returns `false`).

```ts
session.configure(() => {
  if (session.canAddControl(zoom)) session.addControl(zoom)
  if (session.canAddControl(aperture)) session.addControl(aperture)
  if (session.canAddControl(wb)) session.addControl(wb)
})
```

## Receiving lifecycle events

`AVCaptureSessionControlsDelegate` tells you when the system Camera Control UI shows / hides — useful for dimming your own overlay while the system control is on screen.

```ts
session.setControlsDelegate({
  didBecomeActive: () => setSystemControlVisible(true),
  willEnterFullscreenAppearance: () => setOverlayDimmed(true),
  willExitFullscreenAppearance: () => setOverlayDimmed(false),
  didBecomeInactive: () => setSystemControlVisible(false),
})
```

Pass `null` to remove the delegate.

## Hooking the hardware button to capture

The hardware Camera Control button does **not** dispatch through your control delegate by default — you must attach an `AVCaptureEventInteraction`. Without it, half-presses and full-presses are silently swallowed:

```ts
const interaction = new AVCaptureEventInteraction((phase, kind) => {
  if (phase === "ended" && kind === "primary") {
    photoOutput.capturePhoto({ codec: "hevc" })
  }
})
interaction.attach()

// when leaving the page:
interaction.detach()
```

`phase` is `"began" | "ended" | "cancelled"`. `kind` is `"primary"` for the main press and `"secondary"` for half-press / focus events.

## Common pitfalls

- **Delegate never fires.** You forgot `setControlsDelegate(...)`, or the session never started running.
- **Hardware press does nothing.** You forgot `new AVCaptureEventInteraction(...).attach()`.
- **`supportsControls` is `false`.** Either you are on a device without the hardware Camera Control, or the session has not been configured yet — always check after `addInput(...)`.
- **Custom slider does not show.** Either the SF Symbol name is wrong, or `maxControlsCount` is exceeded — Scripting silently drops the `addControl` call in both cases.



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/CaptureVideoPreviewView.md
---

# CaptureVideoPreviewView

`<CaptureVideoPreviewView/>` is the SwiftUI surface for rendering a live preview of any `AVCaptureSession` you have built. It mirrors `<VideoRecorderPreviewView/>` but accepts an arbitrary session, so it works with the pipelines you assemble manually.

```tsx
<CaptureVideoPreviewView
  session={session}
  videoDevice={camera}
  videoGravity="resizeAspectFill"
  cornerRadius={12}
  masksToBounds
/>
```

## Props

| Prop              | Type                                               | Default              | Description                                                                                                                                                                                           |
| ----------------- | -------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session`         | `AVCaptureSession`                                 | required             | The session to render. Must already have a video input attached to actually show frames.                                                                                                              |
| `videoDevice`     | `AVCaptureDevice`                                  | optional             | Pass the device backing the input. Doing so enables `AVCaptureDevice.RotationCoordinator`, so the preview rotates with the device. Without it the preview keeps the connection's default orientation. |
| `videoGravity`    | `'resize' \| 'resizeAspect' \| 'resizeAspectFill'` | `'resizeAspectFill'` | Same semantics as `AVLayerVideoGravity`.                                                                                                                                                              |
| `isVideoMirrored` | `boolean`                                          | system default       | Force the connection's `videoMirrored` flag (e.g. mirror front camera).                                                                                                                               |
| `cornerRadius`    | `number`                                           | `0`                  | Convenience for rounded preview tiles. Set `masksToBounds` if you need clipping.                                                                                                                      |
| `masksToBounds`   | `boolean`                                          | `false`              | Apply `masksToBounds` to the preview layer (turn on for `cornerRadius`).                                                                                                                              |

## Lifecycle

The preview view does **not** start or stop the session for you — call `session.startRunning()` from JavaScript when you want frames flowing. A typical SwiftUI-style pattern:

```tsx
function CameraPage() {
  const session = useMemo(() => buildSession(), [])

  useEffect(() => {
    session.startRunning()
    return () => {
      session.stopRunning()
      session.dispose()
    }
  }, [])

  return (
    <VStack>
      <CaptureVideoPreviewView session={session} videoDevice={camera} />
      <Button title="Capture" action={() => photoOutput.capturePhoto()} />
    </VStack>
  )
}
```

## Notes

- The same `AVCaptureSession` may only be rendered by one preview view at a time.
- Changing `videoGravity` / `isVideoMirrored` / `cornerRadius` after the view has rendered re-applies them on the next layout pass.
- For multi-cam setups (multiple inputs in the same session) use a single preview view; AVFoundation does the compositing internally.



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Device formats/index.md
---

# Device formats

Each `AVCaptureDevice` advertises an array of `AVCaptureDeviceFormat`s — one entry per capture mode the hardware supports (1080p30, 4K60, 720p binned, spatial video, etc.). Picking the right format is how you control resolution, frame rate, HDR, multi-cam compatibility, stabilization, and a handful of front-camera effects (Center Stage, Studio Light, Portrait).

The session preset (`session.sessionPreset = "photo"`) is a coarse alias that asks the system to pick a reasonable format. Switching the active format yourself locks the device into exact dimensions and frame rates.

## The wrapper, briefly

```ts
class AVCaptureDeviceFormat {
  readonly mediaType: string                 // "vide" / "soun" / ...
  readonly width: number                     // pixel width (0 for non-video)
  readonly height: number
  readonly fieldOfView: number               // degrees, horizontal

  readonly videoMaxZoomFactor: number
  readonly videoZoomFactorUpscaleThreshold: number
  readonly isVideoBinned: boolean

  readonly isHighestPhotoQualitySupported: boolean
  readonly isHighPhotoQualitySupported: boolean

  readonly isVideoHDRSupported: boolean
  readonly isMultiCamSupported: boolean
  readonly supportedColorSpaces: ("sRGB" | "P3_D65" | "HLG_BT2020" | "appleLog" | "appleLog2")[]
  readonly autoFocusSystem: "none" | "contrastDetection" | "phaseDetection"

  readonly videoSupportedFrameRateRanges: {
    minFrameRate: number, maxFrameRate: number,
    minFrameDuration: number, maxFrameDuration: number   // seconds
  }[]

  isVideoStabilizationModeSupported(
    mode: "off"|"standard"|"cinematic"|"cinematicExtended"
        |"cinematicExtendedEnhanced"|"previewOptimized"|"lowLatency"|"auto"
  ): boolean

  readonly isSpatialVideoCaptureSupported: boolean
  readonly isCenterStageSupported: boolean
  readonly isPortraitEffectSupported: boolean
  readonly isStudioLightSupported: boolean
}
```

You never construct one — obtain instances from `device.formats` or `device.activeFormat`.

## Identity is stable

Each device wrapper hands out the same `AVCaptureDeviceFormat` instance for the same underlying format every time. So:

```ts
const a = device.formats[0]
const b = device.formats[0]
console.log(a === b)                                       // true
console.log(device.formats.includes(device.activeFormat))  // true
```

That lets you do `formats.indexOf(device.activeFormat)`, compare with `===`, or stash a chosen format and reuse it later. The same underlying format obtained from two different `AVCaptureDevice` instances is two different JS wrappers, though — only meaningful if you build two device objects on purpose.

## Choosing a format

Standard pattern: filter `device.formats`, pick by your own rules, hand the winner to `setActiveFormat`.

```ts
const camera = AVCaptureDevice.default("video")!

// All 1080p formats that can do 60 fps and HDR
const candidates = camera.formats.filter(f =>
  f.width === 1920 && f.height === 1080 &&
  f.isVideoHDRSupported &&
  f.videoSupportedFrameRateRanges.some(r => r.maxFrameRate >= 60)
)

// Prefer non-binned (full sensor), then take whatever's left as a tie-breaker.
const winner =
  candidates.find(f => !f.isVideoBinned) ??
  candidates[0]

if (winner) {
  camera.setActiveFormat(winner)
}
```

A few common filters worth knowing:

| Goal                             | Filter expression                                                 |
| -------------------------------- | ----------------------------------------------------------------- |
| 4K UHD                           | `f.width === 3840 && f.height === 2160`                           |
| 60 fps capable                   | `f.videoSupportedFrameRateRanges.some(r => r.maxFrameRate >= 60)` |
| HDR ready                        | `f.isVideoHDRSupported`                                           |
| Spatial video (iPhone 15 Pro+)   | `f.isSpatialVideoCaptureSupported`                                |
| Multi-cam compatible             | `f.isMultiCamSupported`                                           |
| Supports cinematic stabilization | `f.isVideoStabilizationModeSupported("cinematic")`                |
| Apple Log color                  | `f.supportedColorSpaces.includes("appleLog")`                     |
| Center Stage capable (front cam) | `f.isCenterStageSupported`                                        |

## `setActiveFormat` rules

- The format **must** come from this same device's `formats` array. Passing a format obtained from another device throws — the check happens before any configuration lock, so a stray format won't take the camera down with it.
- `setActiveFormat` performs the change inside its own configuration lock. For a batch of related changes (format + color space + frame rate clamp), wrap the whole block in `device.lockForConfiguration()` / `device.unlockForConfiguration()` yourself so the camera only re-negotiates once.
- Changing format while a session is running is fine; connections are re-negotiated automatically. Sample-buffer outputs may briefly drop frames during the switch.

```ts
// Batched change — single lock, no flicker between settings
camera.lockForConfiguration()
try {
  camera.setActiveFormat(winner)
  camera.setActiveColorSpace("P3_D65")
  camera.setActiveVideoMinFrameDuration(1 / 60)
} finally {
  camera.unlockForConfiguration()
}
```

## Active color space

The active format dictates _which_ color spaces are possible; `device.activeColorSpace` and `device.setActiveColorSpace(value)` choose among them.

```ts
const camera = AVCaptureDevice.default("video")!
const supported = camera.activeFormat.supportedColorSpaces
console.log("current:", camera.activeColorSpace)
console.log("options:", supported)

if (supported.includes("appleLog")) {
  camera.setActiveColorSpace("appleLog")   // grading workflow
} else if (supported.includes("P3_D65")) {
  camera.setActiveColorSpace("P3_D65")     // wide-gamut still display
}
```

`setActiveColorSpace` throws if the value isn't in `activeFormat.supportedColorSpaces`. Switching format may change which color spaces are valid; re-check after `setActiveFormat`.

## Locking frame rate (`setActiveVideoMin/MaxFrameDuration`)

The active format publishes a range of supported frame rates — e.g. 1–60 fps. Use the two clamp setters to pin where in that range the camera actually runs:

- `device.setActiveVideoMinFrameDuration(seconds)` — **shorter** duration ⇒ **higher** maximum fps. Pass `1 / 60` to cap at 60 fps.
- `device.setActiveVideoMaxFrameDuration(seconds)` — **longer** duration ⇒ **lower** minimum fps. Pass `1 / 24` to floor at 24 fps.

```ts
// Lock to exactly 60 fps on a format that supports it
camera.setActiveVideoMinFrameDuration(1 / 60)
camera.setActiveVideoMaxFrameDuration(1 / 60)

console.log("now running between",
  1 / camera.activeVideoMaxFrameDuration, "and",
  1 / camera.activeVideoMinFrameDuration, "fps")
```

Both setters validate the seconds value against `activeFormat.videoSupportedFrameRateRanges` and throw if it falls outside every range. The getters return `0` when the device hasn't been clamped (the format's natural range is in effect).

## Field gotchas

- `width` / `height` / `fieldOfView` are **`0`** on non-video formats (audio, metadata) — they have no video dimensions. Filter to `mediaType === "vide"` if you only care about cameras.
- `videoSupportedFrameRateRanges` can have **multiple entries** — a single format may support, e.g., 1–30 fps and 60 fps in two separate ranges. Don't assume the array has one element.
- `videoMaxZoomFactor` is the hardware ceiling. `videoZoomFactorUpscaleThreshold` is the point above which the system starts digital upscaling instead of staying within the sensor's optical range.
- `isHighestPhotoQualitySupported` / `isHighPhotoQualitySupported` describe **photo** quality tiers — they affect `photoOutput.maxPhotoQualityPrioritization`, not video.
- `isCenterStageSupported` etc. report per-format support. The global toggle that turns these effects on system-wide is separate; on formats where the per-format flag is `false`, the system-wide toggle has no effect for this device.



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Device formats/index_example.md
---

# Example

```tsx
import {
  Button, CaptureVideoPreviewView, HStack, List, Navigation, NavigationStack,
  Script, ScrollView, Section, Spacer, Text, Toolbar, ToolbarItem,
  useEffect, useMemo, useObservable, VStack
} from "scripting"

type FormatRow = {
  /** 同一 wrapper 引用, 传回 setActiveFormat 用 */
  ref: AVCaptureDeviceFormat
  index: number
  label: string
  fpsLabel: string
  flagsLabel: string
  isActive: boolean
}

function describeFormat(f: AVCaptureDeviceFormat): { fps: string, flags: string } {
  // 多 range 拼接, 因为单个 format 可能同时报多档 fps
  const fps = f.videoSupportedFrameRateRanges
    .map(r => r.minFrameRate === r.maxFrameRate
      ? `${Math.round(r.maxFrameRate)}`
      : `${Math.round(r.minFrameRate)}-${Math.round(r.maxFrameRate)}`)
    .join(" / ") + "fps"

  const flags: string[] = []
  if (f.isVideoBinned) flags.push("binned")
  if (f.isVideoHDRSupported) flags.push("hdr")
  if (f.isMultiCamSupported) flags.push("multiCam")
  if (f.isSpatialVideoCaptureSupported) flags.push("spatial")
  if (f.isCenterStageSupported) flags.push("centerStage")
  if (f.isPortraitEffectSupported) flags.push("portrait")
  if (f.isStudioLightSupported) flags.push("studioLight")
  if (f.isHighestPhotoQualitySupported) flags.push("photoHQ+")
  return { fps, flags: flags.join(", ") || "—" }
}

function View() {
  const dismiss = Navigation.useDismiss()
  const isRunning = useObservable(false)
  const lastError = useObservable("")
  const activeLabel = useObservable("")
  // bump 一下触发 UI 重读 activeFormat / activeColorSpace / 帧率 clamp 状态
  const tick = useObservable(0)

  const { session, camera } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)

    session.configure(() => {
      // photo preset 让相机先以拍照模式跑起来, 后面 setActiveFormat 再覆盖具体维度
      session.sessionPreset = "photo"
      if (session.canAddInput(input)) session.addInput(input)
    })

    return { session, camera }
  }, [])

  // 一次性把 formats 包成行数据。`camera.formats` 对同一底层 format 始终返回同一实例,
  // 所以 `ref === camera.activeFormat` 用来高亮当前项是可靠的。
  const allRows = useMemo<FormatRow[]>(() => {
    return camera.formats.map((f, i) => {
      const { fps, flags } = describeFormat(f)
      return {
        ref: f,
        index: i,
        label: `${f.width}×${f.height} · ${f.mediaType}`,
        fpsLabel: fps,
        flagsLabel: flags,
        isActive: false,
      }
    })
  }, [camera])

  // 简单过滤: 4K / 1080p60 / spatial / multiCam — 用文档里给出的常见 filter
  const presets = useMemo(() => [
    { name: "All", filter: (_: AVCaptureDeviceFormat) => true },
    { name: "4K", filter: (f: AVCaptureDeviceFormat) => f.width === 3840 && f.height === 2160 },
    { name: "1080p60", filter: (f: AVCaptureDeviceFormat) =>
        f.width === 1920 && f.height === 1080 &&
        f.videoSupportedFrameRateRanges.some(r => r.maxFrameRate >= 60) },
    { name: "HDR", filter: (f: AVCaptureDeviceFormat) => f.isVideoHDRSupported },
    { name: "MultiCam", filter: (f: AVCaptureDeviceFormat) => f.isMultiCamSupported },
    { name: "Spatial", filter: (f: AVCaptureDeviceFormat) => f.isSpatialVideoCaptureSupported },
  ], [])

  const filter = useObservable<string>("All")
  const filteredRows = useMemo(() => {
    const pred = presets.find(p => p.name === filter.value)?.filter ?? (() => true)
    void tick.value // 让 active 高亮跟着切换重算
    return allRows
      .filter(r => pred(r.ref))
      .map(r => ({ ...r, isActive: r.ref === camera.activeFormat }))
  }, [allRows, filter.value, tick.value])

  function refreshActiveLabel() {
    const af = camera.activeFormat
    const minDur = camera.activeVideoMinFrameDuration
    const maxDur = camera.activeVideoMaxFrameDuration
    const fpsHi = minDur > 0 ? Math.round(1 / minDur) : null
    const fpsLo = maxDur > 0 ? Math.round(1 / maxDur) : null
    const fpsTag = (fpsHi || fpsLo) ? ` · ${fpsLo ?? "?"}-${fpsHi ?? "?"}fps` : ""
    activeLabel.setValue(
      `#${allRows.findIndex(r => r.ref === af)} · ${af.width}×${af.height} · ${camera.activeColorSpace}${fpsTag}`
    )
  }

  useEffect(() => {
    async function start() {
      try {
        await session.startRunning()
        isRunning.setValue(true)
        refreshActiveLabel()
      } catch (e) {
        await Dialog.alert({ message: `Failed to start: ${String(e)}` })
        dismiss()
      }
    }
    start()
    return () => {
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  async function applyFormat(row: FormatRow) {
    try {
      camera.setActiveFormat(row.ref)
      tick.setValue(tick.value + 1)
      refreshActiveLabel()
      lastError.setValue("")
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /** 把 active format 支持的色彩空间挨个尝一遍, 演示 setActiveColorSpace 的校验 */
  function cycleColorSpace() {
    try {
      const list = camera.activeFormat.supportedColorSpaces
      if (list.length === 0) {
        lastError.setValue("Active format reports no color spaces")
        return
      }
      const current = camera.activeColorSpace
      const idx = list.indexOf(current as any)
      const next = list[(idx + 1) % list.length]
      camera.setActiveColorSpace(next)
      tick.setValue(tick.value + 1)
      refreshActiveLabel()
      lastError.setValue(`color space → ${next}`)
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /** 把 fps 锁到 active format 支持的最高档 — 走 setActiveVideoMin/MaxFrameDuration 的合法路径 */
  function lockToMaxFps() {
    try {
      const ranges = camera.activeFormat.videoSupportedFrameRateRanges
      if (ranges.length === 0) {
        lastError.setValue("Active format reports no fps ranges")
        return
      }
      const top = ranges.reduce((a, b) => a.maxFrameRate >= b.maxFrameRate ? a : b)
      // 锁死 = min duration === max duration = 1 / top.maxFrameRate
      const dur = 1 / top.maxFrameRate
      camera.setActiveVideoMinFrameDuration(dur)
      camera.setActiveVideoMaxFrameDuration(dur)
      tick.setValue(tick.value + 1)
      refreshActiveLabel()
      lastError.setValue(`locked to ${Math.round(top.maxFrameRate)}fps`)
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /** 验证非法 fps duration 被拒: 用 1/1000 秒 (≈ 1000fps) 远超任何 format 的能力, 期望 throw */
  function probeInvalidFps() {
    try {
      camera.setActiveVideoMinFrameDuration(1 / 1000)
      lastError.setValue("Unexpected: invalid fps accepted")
    } catch (e) {
      lastError.setValue(`OK (rejected): ${String(e)}`)
    }
  }

  /** 验证跨 device 拒绝: 再取一次 default("video") 包成不同 wrapper, 把它的 format
   *  传给当前 camera, 期望抛 "does not belong to this device" */
  function probeForeignReject() {
    const another = AVCaptureDevice.default("video")
    if (!another) {
      lastError.setValue("No second device wrapper available")
      return
    }
    const foreign = another.formats[0]
    try {
      camera.setActiveFormat(foreign)
      lastError.setValue("Unexpected: foreign format accepted")
    } catch (e) {
      lastError.setValue(`OK (rejected): ${String(e)}`)
    }
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="Device formats"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 200 }}
          cornerRadius={12}
          masksToBounds
        />

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Status</Text>
          <Text font="footnote">
            running: {String(isRunning.value)} · active: {activeLabel.value} · total: {allRows.length}
          </Text>
          {lastError.value ? (
            <Text font="footnote" foregroundStyle="red">{lastError.value}</Text>
          ) : null}
        </VStack>

        <ScrollView axes="horizontal" scrollIndicator={'hidden'}>
          <HStack padding={8} spacing={8}>
            {presets.map(p => (
              <Button
                key={p.name}
                title={`${p.name} (${allRows.filter(r => p.filter(r.ref)).length})`}
                buttonStyle={filter.value === p.name ? "borderedProminent" : "bordered"}
                controlSize="small"
                action={() => filter.setValue(p.name)}
              />
            ))}
          </HStack>
        </ScrollView>

        <ScrollView axes="horizontal" scrollIndicator={'hidden'}>
          <HStack padding={8} spacing={8}>
            <Button title="Cycle color space" buttonStyle="bordered" controlSize="small" action={cycleColorSpace} />
            <Button title="Lock to max fps"   buttonStyle="bordered" controlSize="small" action={lockToMaxFps} />
            <Button title="Probe bad fps"      buttonStyle="bordered" controlSize="small" action={probeInvalidFps} />
            <Button title="Probe foreign"      buttonStyle="bordered" controlSize="small" action={probeForeignReject} />
          </HStack>
        </ScrollView>

        <List>
          <Section header={<Text>{filteredRows.length} format(s)</Text>}>
            {filteredRows.map(r => (
              <Button
                key={r.index}
                action={() => applyFormat(r)}
              >
                <VStack alignment="leading" spacing={2}>
                  <HStack>
                    <Text font="footnote" fontWeight={r.isActive ? "bold" : "regular"}>
                      #{r.index} · {r.label}
                    </Text>
                    <Spacer />
                    {r.isActive ? <Text font="footnote" foregroundStyle="green">ACTIVE</Text> : null}
                  </HStack>
                  <Text font="caption" foregroundStyle="secondaryLabel">
                    {r.fpsLabel} · {r.flagsLabel}
                  </Text>
                </VStack>
              </Button>
            ))}
          </Section>
        </List>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Live Photo/index.md
---

# Live Photo

A Live Photo is a photo _plus_ a short `.mov` companion clip captured around the shutter. `AVCapturePhotoOutput` lets you opt in per capture — pass `livePhotoMovieFile` to `capturePhoto` and `capturePhoto` resolves with both the still image and the path of the saved movie.

## Prerequisites

- The photo output must have `isLivePhotoCaptureSupported === true` (true on all camera-capable iPhones).
- You must enable it once on the output: `photoOutput.isLivePhotoCaptureEnabled = true`. The bridge silently clamps this to `false` on outputs that don't support Live Photo, so a follow-up read is the simplest feature gate.
- If `isLivePhotoCaptureEnabled` is `false` at the moment `capturePhoto` is called with `livePhotoMovieFile`, the promise **rejects immediately** rather than performing a non-Live capture.
- Do not enable `isAutoDeferredPhotoDeliveryEnabled` at the same time. With deferred on, the system may finalize without producing the `.mov`, and `livePhotoMovieFileURL` will be absent from the resolved value.

## Wiring it up

```ts
const camera = AVCaptureDevice.default("video")!
const session = new AVCaptureSession()
const photoOutput = new AVCapturePhotoOutput()

session.configure(() => {
  session.sessionPreset = "photo"
  session.addInput(new AVCaptureDeviceInput(camera))
  session.addOutput(photoOutput)
})

// One-time setup. The flag survives across capturePhoto calls.
photoOutput.isLivePhotoCaptureEnabled = true

await session.startRunning()

const ts = Date.now()
const photoFile = `${FileManager.documentsDirectory}/live_${ts}.heic`
const movieFile = `${FileManager.documentsDirectory}/live_${ts}.mov`

const result = await photoOutput.capturePhoto({
  codec: "hevc",
  photoFile,                 // ← required if you'll later call Photos.saveLivePhoto
  livePhotoMovieFile: movieFile,
  livePhotoVideoCodec: "hevc",
})

console.log("photo:", result.image.width, "×", result.image.height)
console.log("still file:", result.photoFileURL)
console.log("movie:", result.livePhotoMovieFileURL)
```

The resolved object has the usual `image / metadata / isRawPhoto / isDeferredProxy` plus an extra `photoFileURL: string` (if you passed `photoFile`) and `livePhotoMovieFileURL: string` (if you passed `livePhotoMovieFile`). If you didn't request a Live Photo, the `.mov` field is absent.

### Why `photoFile` matters for Live Photo

`capturePhoto` always gives you `result.image: UIImage` — but `UIImage` is a decoded bitmap with no original metadata. When you save a Live Photo to the system Photo Library via `Photos.saveLivePhoto(...)`, PhotoKit verifies that the still and the `.mov` share a Live Photo asset identifier (embedded in the Apple Maker Note under key 17 on the still; in `com.apple.quicktime.content.identifier` on the movie). Re-encoding the `UIImage` via `image.toJPEGData()` strips that identifier and PhotoKit rejects the pair with **`PHPhotosErrorDomain 3302`**.

The `photoFile` option avoids this by asking the bridge to write `photo.fileDataRepresentation()` straight to disk — that's the raw bytes the camera produced, with the Maker Note intact. Feed `result.photoFileURL` into `Photos.saveLivePhoto({ imagePath, videoPath })` and pairing works.

## What "resolve" actually waits for

A Live Photo capture fires two parallel AVFoundation callbacks: one for the still image and one for the `.mov` file. The bridge waits for **both** before resolving — you always get a fully usable pair, or an error. AVFoundation does not guarantee an order between the two, so don't rely on file timestamps to infer it.

The system also runs a "capture finish" sweep at the end. If something goes wrong half-way (e.g. the device drops the `.mov`), the bridge falls back to whatever has been delivered so far rather than hanging the promise.

## File path rules

- Pass an **absolute path** ending in `.mov`. `${FileManager.documentsDirectory}/...` is the easiest source of a writable path.
- AVFoundation refuses to write to an existing path. The bridge deletes the file at the requested path **before** the capture starts to spare you that error.
- The `.mov` is small (\~2–4 MB for a 1.5 s clip). Clean up old files yourself if you're capturing repeatedly.

## Codec selection

`livePhotoVideoCodec` is optional. Acceptable values:

- `"hevc"` — preferred on iPhone 7 and later (supported devices). Smaller files.
- `"h264"` — wider compatibility (older systems, some editing tools).

If you pass a codec that the device doesn't list in `availableLivePhotoVideoCodecTypes`, the bridge silently lets AVFoundation pick its default rather than failing the capture. Read the resolved file with an `AVAsset` if you need to know what was actually written.

## Things to know

- Live Photo + `flashMode = "on"` works, but the captured movie includes the flash flicker; design for that.
- The `.mov` you get is exactly what Photos.app would save — it includes a slight pre-roll and post-roll around the shutter.
- `capturePhoto` only writes files to disk — it doesn't put anything in the system Photo Library. To save the photo and clip as a single linked Live Photo (the way Camera.app does it), pass both paths to [`Photos.saveLivePhoto`](#):

  ```ts
  await Photos.saveLivePhoto({
    imagePath: result.photoFileURL!,           // raw HEIC from `photoFile` option
    videoPath: result.livePhotoMovieFileURL!,  // .mov from `livePhotoMovieFile` option
    shouldMoveFile: true,                      // move both into Photos rather than copy
  })
  ```

  This pairs them into one PHAsset; Photos.app shows the long-press "Live" animation on it. The first call triggers the system Photo Library permission prompt. **Do not** substitute `result.image.toJPEGData()` for `result.photoFileURL` — the re-encoded JPEG loses the Live Photo asset identifier and PhotoKit rejects the pairing.



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Live Photo/index_example.md
---

# Example

```tsx
import {
  Button, CaptureVideoPreviewView, HStack, Image,
  Navigation, NavigationStack, Script, Spacer, Text, Toolbar, ToolbarItem,
  useEffect, useMemo, useObservable, VStack
} from "scripting"

type Shot = {
  index: number
  image: UIImage
  photoSize: string
  /** native 写盘的原始 still bytes(HEIC/JPEG),含 Live Photo asset identifier */
  photoURL?: string
  movieURL?: string
  movieSize?: number
  ms: number
  isDeferredProxy: boolean
}

function View() {
  const dismiss = Navigation.useDismiss()
  const isRunning = useObservable(false)
  const shots = useObservable<Shot[]>([])
  const captureCount = useObservable(0)
  const lastError = useObservable("")
  const livePhotoSupp = useObservable(false)
  const livePhotoEn = useObservable(false)

  const { session, camera, photoOutput } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)
    const photoOutput = new AVCapturePhotoOutput()

    session.configure(() => {
      session.sessionPreset = "photo"
      if (session.canAddInput(input)) session.addInput(input)
      if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
    })

    // 必须在 addOutput 之后查 supported,在那之前 photoOutput 没绑 session 时 supported=false。
    return { session, camera, photoOutput }
  }, [])

  useEffect(() => {
    async function start() {
      try {
        await session.startRunning()
        isRunning.setValue(true)

        // Live Photo 必须开启 enabled 之后才会真正生效。
        photoOutput.isLivePhotoCaptureEnabled = true
        // 读回真实值: 不支持的设备 setter 会被 clamp 回 false。
        livePhotoSupp.setValue(photoOutput.isLivePhotoCaptureSupported)
        livePhotoEn.setValue(photoOutput.isLivePhotoCaptureEnabled)

        console.log("[startRunning]", {
          preset: session.sessionPreset,
          liveSupp: photoOutput.isLivePhotoCaptureSupported,
          liveEn:   photoOutput.isLivePhotoCaptureEnabled,
        })
      } catch (e) {
        await Dialog.alert({ message: `Failed to start: ${String(e)}` })
        dismiss()
      }
    }
    start()
    return () => {
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  async function takeLivePhoto() {
    const idx = captureCount.value + 1
    captureCount.setValue(idx)
    const ts = Date.now()
    // 同时让 native 写盘 still + .mov。两份文件共享 Apple Maker Note 里的
    // Live Photo asset identifier, Photos.saveLivePhoto 才能 pair 上。
    const photoFile = `${FileManager.documentsDirectory}/live_${idx}_${ts}.heic`
    const movieFile = `${FileManager.documentsDirectory}/live_${idx}_${ts}.mov`
    const start = Date.now()
    try {
      const result = await photoOutput.capturePhoto({
        codec: "hevc",
        photoFile,
        livePhotoMovieFile: movieFile,
        livePhotoVideoCodec: "hevc",
      })
      const ms = Date.now() - start

      // 读 movie 文件大小供 UI 显示
      let movieSize: number | undefined
      if (result.livePhotoMovieFileURL) {
        try {
          const stat = await FileManager.stat(result.livePhotoMovieFileURL)
          movieSize = stat.size
        } catch { /* ignore */ }
      }

      shots.setValue([{
        index: idx,
        image: result.image,
        photoSize: `${result.image.width}×${result.image.height}`,
        photoURL: result.photoFileURL,
        movieURL: result.livePhotoMovieFileURL,
        movieSize,
        ms,
        isDeferredProxy: result.isDeferredProxy,
      }, ...shots.value].slice(0, 6))
      lastError.setValue("")
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /** 不开 Live Photo,验证退化路径:resolve 不应包含 livePhotoMovieFileURL */
  async function takeRegular() {
    const idx = captureCount.value + 1
    captureCount.setValue(idx)
    const start = Date.now()
    try {
      const result = await photoOutput.capturePhoto({ codec: "hevc" })
      shots.setValue([{
        index: idx,
        image: result.image,
        photoSize: `${result.image.width}×${result.image.height}`,
        movieURL: result.livePhotoMovieFileURL,  // 应为 undefined
        ms: Date.now() - start,
        isDeferredProxy: result.isDeferredProxy,
      }, ...shots.value].slice(0, 6))
      lastError.setValue("")
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /**
   * 把最新一张 Live Photo 配对存进系统照片库。
   * 关键: `imagePath` 必须用 native 写盘的 `result.photoFileURL`(原始 HEIC,
   * 含 Apple Maker Note 里的 Live Photo asset identifier),用 toJPEGData 重编码
   * 出来的 JPEG 会丢这个 identifier, Photos.saveLivePhoto 报 PHPhotosError 3302。
   * `shouldMoveFile: true` 会把磁盘上两个文件 move 进 Photos,本地副本就消失了。
   */
  async function saveLast() {
    const last = shots.value[0]
    if (!last) {
      lastError.setValue("Capture a Live Photo first")
      return
    }
    if (!last.photoURL || !last.movieURL) {
      lastError.setValue("Last capture missing photoURL or movieURL (was it a Regular shot?)")
      return
    }
    try {
      await Photos.saveLivePhoto({
        imagePath: last.photoURL,
        videoPath: last.movieURL,
        shouldMoveFile: true,
      })
      lastError.setValue(`Saved Live Photo #${last.index} to Photos library`)
    } catch (e) {
      lastError.setValue(`Save failed: ${String(e)}`)
      console.error(e)
    }
  }

  /** 故意关掉 enabled 再调 Live Photo,期望 promise reject */
  async function probeReject() {
    photoOutput.isLivePhotoCaptureEnabled = false
    livePhotoEn.setValue(photoOutput.isLivePhotoCaptureEnabled)
    try {
      await photoOutput.capturePhoto({
        livePhotoMovieFile: `${FileManager.documentsDirectory}/should_reject.mov`,
      })
      lastError.setValue("Unexpected: did not reject")
    } catch (e) {
      lastError.setValue(`OK (rejected): ${String(e)}`)
    } finally {
      // 恢复 enabled 方便继续测
      photoOutput.isLivePhotoCaptureEnabled = true
      livePhotoEn.setValue(photoOutput.isLivePhotoCaptureEnabled)
    }
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="Live Photo capture"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 280 }}
          cornerRadius={12}
          masksToBounds
        />

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Status</Text>
          <Text font="footnote">
            running: {String(isRunning.value)} · liveSupp: {String(livePhotoSupp.value)} · liveEn: {String(livePhotoEn.value)}
          </Text>
          {lastError.value ? (
            <Text font="footnote" foregroundStyle="red">
              {lastError.value}
            </Text>
          ) : null}
        </VStack>

        <HStack padding={8} spacing={10}>
          <Button title="Live Photo" action={takeLivePhoto} />
          <Button title="Regular" action={takeRegular} />
          <Button title="Save last" action={saveLast} />
          <Button title="Probe reject" action={probeReject} />
          <Spacer />
          <Text font="footnote" foregroundStyle="secondaryLabel">
            shots: {captureCount.value}
          </Text>
        </HStack>

        {shots.value[0] ? (
          <Image
            image={shots.value[0].image}
            resizable
            scaleToFit
            frame={{ height: 140 }}
          />
        ) : null}

        <VStack alignment="leading" spacing={2} padding={8}>
          <Text font="caption">Recent captures (newest first)</Text>
          {shots.value.map(s => (
            <Text key={s.index} font="footnote">
              #{s.index} · {s.ms}ms · {s.photoSize}
              {s.isDeferredProxy ? " · proxy" : ""}
              {s.movieURL
                ? ` · mov ${s.movieSize ? Math.round(s.movieSize / 1024) + "KB" : "?"}`
                : " · no .mov"}
            </Text>
          ))}
        </VStack>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Quick Start/index.md
---

# Quick Start

`AVCaptureSession` is the low-level building block for camera and microphone capture in Scripting. It is the same API that `VideoRecorder` is built on top of — but exposed as discrete, composable objects so that you can assemble your own pipeline: choose a device, attach inputs and outputs, run the session, and respond to the iPhone 16 hardware Camera Control.

If you just want to "press a button and record an mp4", reach for [`VideoRecorder`](#) — it manages the state machine, audio session, orientation and pause/resume timeline for you. Use `AVCaptureSession` when you need:

- QR / barcode scanning while previewing video
- Custom photo capture (HEVC, flash mode, Live Photo)
- A custom recording flow that does not match `VideoRecorder`'s state machine
- iPhone 16 Camera Control bindings (zoom slider, exposure slider, custom controls)
- Multiple outputs simultaneously (e.g. photo + movie)

PRO is required to call `startRunning()`, `capturePhoto()` and `startRecording()`. Construction, configuration and `canAdd*` checks are free.

***

## Pipeline at a glance

```ts
const session = new AVCaptureSession()
const camera = AVCaptureDevice.default("video")!
const input = new AVCaptureDeviceInput(camera)

session.configure(() => {
  session.sessionPreset = "photo"
  if (session.canAddInput(input)) session.addInput(input)
})

await session.startRunning()
// ... use session ...
await session.stopRunning()
session.dispose()
```

***

## Permissions

You don't request camera or microphone permission yourself. `session.startRunning()` inspects the inputs you have attached, prompts the user the first time, and rejects the promise if they deny. Other Scripting APIs (Photos, Contacts, Location) work the same way — the API call is the permission gate.

```ts
try {
  await session.startRunning()
} catch (e) {
  // Camera (or microphone, if you added an audio input) was denied,
  // restricted, or unavailable.
}
```

***

## Picking a device

`AVCaptureDevice.default(mediaType)` is the simplest path. For a specific lens or position use `AVCaptureDevice.defaultDevice(...)` or `AVCaptureDevice.discoverySession(...)`:

```ts
// Best back camera with hardware fallback
const back = AVCaptureDevice.defaultDevice(
  "builtInWideAngleCamera", "video", "back"
)

// Enumerate every supported lens type
const session = AVCaptureDevice.discoverySession({
  deviceTypes: [
    "builtInWideAngleCamera",
    "builtInUltraWideCamera",
    "builtInTelephotoCamera",
  ],
  mediaType: "video",
  position: "back",
})
console.log(session.devices.map(d => d.localizedName))
```

***

## Adding inputs and outputs

Wrap the device in an `AVCaptureDeviceInput` (the constructor throws if the device is busy or denied), then attach outputs. Use `session.configure(...)` to batch your changes — it wraps `beginConfiguration()` / `commitConfiguration()` for you.

```ts
const input = new AVCaptureDeviceInput(AVCaptureDevice.default("video")!)

const photoOutput = new AVCapturePhotoOutput()
photoOutput.maxPhotoQualityPrioritization = "quality"

session.configure(() => {
  if (session.canAddInput(input)) session.addInput(input)
  if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
})
```

> Calling `addInput` / `addOutput` outside of `configure(...)` works too, but each mutation hits the queue separately. Group them when you can.

***

## Photo capture

```ts
await session.startRunning()
const result = await photoOutput.capturePhoto({ codec: "hevc", flashMode: "auto" })
console.log("Captured", result.image.size, result.metadata)
```

The resolved object has `image: UIImage`, `metadata: Record<string, any>`, and `isRawPhoto: boolean`.

***

## Movie recording

```ts
const movieOutput = new AVCaptureMovieFileOutput()
movieOutput.maxRecordedDuration = 60     // seconds; 0 = unlimited
session.addOutput(movieOutput)

await session.startRunning()
const path = `${FileManager.documentsDirectory}/clip.mov`
const finalPath = await movieOutput.startRecording(path)   // resolves when stopRecording() finalizes
// ... show UI / await user tap ...
await movieOutput.stopRecording()
console.log("saved", finalPath)
```

`startRecording` resolves when the file is fully finalized; do not delete the file before the promise resolves.

***

## QR / barcode scanning

`AVCaptureMetadataOutput` runs the system code detector on the live frames.

```ts
const metaOutput = new AVCaptureMetadataOutput()
session.configure(() => {
  if (session.canAddInput(input)) session.addInput(input)
  if (session.canAddOutput(metaOutput)) session.addOutput(metaOutput)
})

// Order matters — types must be set after the output is added.
metaOutput.metadataObjectTypes = ["qr", "ean13", "code128"]
metaOutput.setMetadataObjectsListener(objects => {
  for (const o of objects) {
    if (o.stringValue) console.log("scanned", o.type, o.stringValue)
  }
})

await session.startRunning()
```

Set `rectOfInterest = { x, y, width, height }` (normalized 0..1) to limit detection to a region of the frame.

Each detected object carries a raw `bounds` (normalized 0..1) and, for codes, raw `corners`. It also carries a `transformed` field whose `bounds` / `corners` are corrected for the connection's orientation and mirroring — use those when drawing an overlay on top of the preview:

```ts
metaOutput.setMetadataObjectsListener(objects => {
  for (const o of objects) {
    const box = o.transformed?.bounds ?? o.bounds   // {x,y,width,height}, 0..1
    // map box into your view's pixel rect and draw a highlight
  }
})
```

To convert a rectangle between an output's own coordinate space and the metadata output's normalized space, use `output.metadataOutputRectConverted({ x, y, width, height })` and its inverse `output.outputRectConverted(...)`. Both are available on every output and return `{ x, y, width, height }`.

***

## Showing a preview

Use `<CaptureVideoPreviewView session={session} videoDevice={camera}/>` in any UI you build with Scripting's view layer. See the `Preview View` page for the full prop list.

***

## Cleanup

When you are done with the session — typically in `onAppear`/`onDisappear` of your component, or before navigating away — stop and dispose:

```ts
await session.stopRunning()
session.dispose()
```

`dispose()` is idempotent. If you forget it, the wrapper is also released when the running script ends.

***

## Putting it all together

```ts
const camera = AVCaptureDevice.default("video")!
const session = new AVCaptureSession()
const input = new AVCaptureDeviceInput(camera)
const photoOutput = new AVCapturePhotoOutput()

session.configure(() => {
  session.sessionPreset = "photo"
  if (session.canAddInput(input)) session.addInput(input)
  if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
})

session.addRuntimeErrorListener(msg => console.error("session error:", msg))

await session.startRunning()
const photo = await photoOutput.capturePhoto({ codec: "hevc" })
await session.stopRunning()
session.dispose()
```



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Quick Start/index_example.md
---

# Example

```tsx
import {
  Button, CaptureVideoPreviewView, HStack, Navigation,
  NavigationStack, Path, Script, Spacer, Text, Toolbar, ToolbarItem,
  ToolbarItemGroup, useEffect, useMemo, useObservable, VStack
} from "scripting"

function View() {
  const dismiss = Navigation.useDismiss()
  const lastResult = useObservable("")
  const lastBounds = useObservable("—")
  const caps = useObservable("—")
  const isRunning = useObservable(false)
  const torchOn = useObservable(false)
  const supportsControls = useObservable(false)

  // 一次性建好 session + 输入 + 输出。useMemo 保证 hot reload 时不重复创建。
  const { session, camera, photoOutput, metaOutput } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)
    const photoOutput = new AVCapturePhotoOutput()
    const metaOutput = new AVCaptureMetadataOutput()

    session.configure(() => {
      session.sessionPreset = "high"
      if (session.canAddInput(input)) session.addInput(input)
      if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
      if (session.canAddOutput(metaOutput)) session.addOutput(metaOutput)
    })

    metaOutput.metadataObjectTypes = ["qr", "code128", "ean13"]
    metaOutput.setMetadataObjectsListener(objects => {
      for (const o of objects) {
        // 新增 API:transformed 是方向/镜像校正后的坐标(画 overlay 用),
        // corners 是机读码的四个角点。回退到原始 bounds。
        const b = o.transformed?.bounds ?? o.bounds
        lastBounds.setValue(
          `${o.type} @ ${b.x.toFixed(2)},${b.y.toFixed(2)} ${b.width.toFixed(2)}×${b.height.toFixed(2)}`
        )
        if (o.corners?.length) console.log("corners:", JSON.stringify(o.corners))
        if (o.transformed) console.log("transformed:", JSON.stringify(o.transformed))
        if (o.stringValue) {
          lastResult.setValue(`${o.type}: ${o.stringValue}`)
          break
        }
      }
    })

    return { session, camera, photoOutput, metaOutput }
  }, [])

  useEffect(() => {
    let interaction: AVCaptureEventInteraction | null = null

    async function start() {
      // startRunning 自带权限申请,拒绝时会 reject
      try {
        await session.startRunning()
        isRunning.setValue(true)
        logCapabilities()
      } catch (e) {
        await Dialog.alert({ message: `Failed: ${String(e)}` })
        dismiss()
        return
      }

      // iPhone 16 Camera Control: 系统缩放滑块 + 自定义曝光滑块 + 硬件按键拍照
      if (session.supportsControls) {
        supportsControls.setValue(true)
        const zoom = new AVCaptureSystemZoomSlider(camera)
        const ev = new AVCaptureSlider("EV", "sun.max", {
          range: [-2, 2],
          step: 0.33,
          defaultValue: 0,
          localizedValueFormat: "%.1f",
        })
        ev.setActionHandler(value => {
          camera.setExposureTargetBias(value).catch(console.error)
        })
        session.configure(() => {
          if (session.canAddControl(zoom)) session.addControl(zoom)
          if (session.canAddControl(ev)) session.addControl(ev)
        })

        interaction = new AVCaptureEventInteraction((phase, kind) => {
          if (phase === "ended" && kind === "primary") {
            takePhoto()
          }
        })
        interaction.attach()
      }
    }

    start()

    return () => {
      interaction?.detach()
      metaOutput.setMetadataObjectsListener(null)
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  // 新增 API 巡检:photo 能力查询 / connections / 坐标转换。startRunning 之后调用,
  // 此时 output 已有 connection,codec / maxPhotoDimensions 才有效。
  function logCapabilities() {
    const dims = photoOutput.maxPhotoDimensions
    const lines = [
      `photo codecs: ${photoOutput.availablePhotoCodecTypes.join(", ")}`,
      `live photo codecs: ${photoOutput.availableLivePhotoVideoCodecTypes.join(", ") || "none"}`,
      `flash: ${photoOutput.supportedFlashModes.join(", ")}`,
      `maxPhotoDimensions: ${dims.width}×${dims.height}`,
      `depth: ${photoOutput.isDepthDataDeliverySupported}, portraitMatte: ${photoOutput.isPortraitEffectsMatteDeliverySupported}, proRAW: ${photoOutput.isAppleProRAWSupported}`,
      `connections — photo: ${photoOutput.connections.length}, meta: ${metaOutput.connections.length}`,
    ]
    // 坐标转换:output 坐标 → metadata 归一化坐标(及其逆向)。
    const roi = { x: 0.25, y: 0.25, width: 0.5, height: 0.5 }
    const toMeta = metaOutput.metadataOutputRectConverted(roi)
    const back = metaOutput.outputRectConverted(toMeta)
    lines.push(`rect ${JSON.stringify(roi)} → meta ${JSON.stringify(toMeta)} → back ${JSON.stringify(back)}`)

    const c = photoOutput.connections[0]
    if (c) lines.push(`conn[0]: active=${c.isActive} mirrored=${c.isVideoMirrored} angle=${c.videoRotationAngle}`)

    console.log("[capabilities]\n" + lines.join("\n"))
    caps.setValue(`${photoOutput.availablePhotoCodecTypes.join("/")} · ${dims.width}×${dims.height} · conn ${photoOutput.connections.length}`)
  }

  async function takePhoto() {
    try {
      const result = await photoOutput.capturePhoto({ codec: "hevc" })
      await Dialog.alert({
        title: "Captured",
        message: `Photo size: ${result.image.width} × ${result.image.height}`,
      })
    } catch (e) {
      console.error("capturePhoto failed:", e)
    }
  }

  function toggleTorch() {
    if (!camera.hasTorch) return
    const next = torchOn.value ? "off" : "on"
    camera.setTorchMode(next)
    torchOn.setValue(next === "on")
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="AVCaptureSession Demo"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 480 }}
          cornerRadius={12}
          masksToBounds
        />
        <Text>Last scan: {lastResult.value || "—"}</Text>
        <Text font="footnote" foregroundStyle="secondaryLabel">
          Bounds (transformed): {lastBounds.value}
        </Text>
        <Text font="footnote" foregroundStyle="secondaryLabel">
          Capabilities: {caps.value}
        </Text>
        <Text font="footnote" foregroundStyle="secondaryLabel">
          Camera Control: {supportsControls.value ? "supported" : "not available on this device"}
        </Text>
        <HStack spacing={12}>
          <Button title="Photo" action={takePhoto} />
          <Button
            title={torchOn.value ? "Torch off" : "Torch on"}
            action={toggleTorch}
            disabled={!camera.hasTorch}
          />
          <Spacer />
        </HStack>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()
```



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Responsive capture/index.md
---

# Responsive capture

A family of `AVCapturePhotoOutput` switches that change how the capture pipeline behaves between shots. None of them change the photo _quality_ — they change _when_ you can take the next shot, and _how soon_ you get a usable image back from the current one.

***

## `isZeroShutterLagEnabled`

Builds a rolling buffer of recent frames so a tap captures the moment _just before_ the tap, not after. Most useful for action shots — kids, pets, sports.

- Defaults to `true` on devices where it's supported (iPhone XS / XR and newer).
- Set to `false` if you want strictly the moment of the tap (rare).

```ts
if (photoOutput.isZeroShutterLagSupported) {
  photoOutput.isZeroShutterLagEnabled = true
}
```

***

## `isResponsiveCaptureEnabled` + `isFastCapturePrioritizationEnabled`

These are a **pair**. They let the pipeline finish the current photo's processing in the background while the user keeps tapping.

**Order matters.** Apple gates `isFastCapturePrioritizationSupported` on `isResponsiveCaptureEnabled = true` (and `maxPhotoQualityPrioritization = "quality"`). So turn responsive on first — _then_ fast becomes supported.

```ts
photoOutput.maxPhotoQualityPrioritization = "quality"

if (photoOutput.isResponsiveCaptureSupported) {
  photoOutput.isResponsiveCaptureEnabled = true
}
// fastSupp only flips to true after the line above runs.
if (photoOutput.isFastCapturePrioritizationSupported) {
  photoOutput.isFastCapturePrioritizationEnabled = true
}
```

If you flip them out of order from JS, the bridge fixes it: setting `fast = true` first will turn `responsive` on if supported, and turning `responsive = false` first turns `fast` off. So this also works:

```ts
photoOutput.isFastCapturePrioritizationEnabled = true   // responsive gets auto-enabled
```

If `fastSupp` stays `false` even after `responsive` is on, the active format / preset doesn't allow it — fast is silently ignored. Common blockers: `maxPhotoQualityPrioritization` not `"quality"`, `isLivePhotoCaptureEnabled = true`, or a non-`photo` session preset.

***

## `isAutoDeferredPhotoDeliveryEnabled` (read this carefully)

Deferred Photo Delivery lets you tap the shutter again _immediately_, without waiting for the previous photo's full processing pipeline (Deep Fusion, Photonic Engine, Smart HDR) to finish. Apple does this by handing your app a "proxy" right away and finalizing the real photo asynchronously.

The catch — and the reason this section is much longer than the others — is that **the finalized photo never comes back through `capturePhoto()`**.

### What you actually get

When deferred kicks in, `capturePhoto()` resolves with:

```ts
{
  image: UIImage,         // ← this is the PROXY, not the final
  metadata: {...},
  isRawPhoto: false,
  isDeferredProxy: true,
}
```

The `image` is an _unfinished_ version of the photo: a quick render the system can produce in milliseconds. Visually it has more noise, less detail, and a weaker dynamic range than the final. It's perfectly fine for "show the user what they just shot" thumbnails, but it is **not the photo you want to keep**.

The system finalizes the real photo on its own clock — usually within seconds, but it can take longer if the device is busy or you've gone to background — and writes the result **directly to the user's Photo Library**. There is **no callback** into your app.

### So how do I get the final photo?

Use PhotoKit. Query the user's Photo Library for the most recent image after the proxy resolves:

```ts
photoOutput.isAutoDeferredPhotoDeliveryEnabled = true

const result = await photoOutput.capturePhoto()
if (result.isDeferredProxy) {
  // result.image is the proxy. Show it as a thumbnail.
  showThumbnail(result.image)
  // The final image will appear in the Photo Library on its own.
  // If your script needs it, you'll have to use Photo.getLastestPhotos or Photo.pickPhotos
}
```

### When _not_ to enable this

If your script wants the photo bytes immediately (for upload, processing, file save) and doesn't have or want Photo Library permission, **leave deferred off**. The default behavior — wait for the final, then resolve — is the right one for most scripts.

You'd opt in when:

- You're building a tap-many-photos-in-a-row UI and need quick feedback per shot
- You're already saving everything to the Photo Library anyway
- You'd rather show a less-perfect preview now than a spinner

***

## Detection cheat sheet

| Flag                                 | Min device                  |
| ------------------------------------ | --------------------------- |
| `isZeroShutterLagEnabled`            | iPhone XS / XR+             |
| `isResponsiveCaptureEnabled`         | iPhone 12+ (varies by lens) |
| `isFastCapturePrioritizationEnabled` | iPhone 12+                  |
| `isAutoDeferredPhotoDeliveryEnabled` | iPhone 11 Pro+              |



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Responsive capture/index_example.md
---

# Example

```tsx
import {
  Button, CaptureVideoPreviewView, HStack,
  Image, Navigation, NavigationStack, Script, Spacer, Text, Toggle,
  Toolbar, ToolbarItem, useEffect, useMemo, useObservable, VStack
} from "scripting"

type CaptureLog = {
  ms: number
  size: string
  isDeferredProxy: boolean
  index: number
}

function View() {
  const dismiss = Navigation.useDismiss()

  const isRunning = useObservable(false)
  const lastImage = useObservable<UIImage | null>(null)
  const log = useObservable<CaptureLog[]>([])
  const captureCount = useObservable(0)

  // 4 个响应性开关 + 一个能 / 不能控制的标记
  const supports = useObservable({
    zsl: false, resp: false, fast: false, defer: false,
  })

  // 用户当前的开关状态(不一定实际生效, 由 *Supported 决定)
  const zsl = useObservable(false)
  const resp = useObservable(false)
  const fast = useObservable(false)
  const defr = useObservable(false)

  const { session, camera, photoOutput } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)
    const photoOutput = new AVCapturePhotoOutput()
    photoOutput.maxPhotoQualityPrioritization = "quality"

    session.configure(() => {
      session.sessionPreset = "photo"
      if (session.canAddInput(input)) session.addInput(input)
      if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
    })

    return { session, camera, photoOutput }
  }, [])

  // 把 supported + enabled 状态从 native 重新拉一遍, 并 log 一行方便观察状态机。
  // *Supported 不是常量: fastSupp 依赖 respEn=true, 所以切 resp 之后必须重读。
  function syncFromNative(label: string) {
    const snapshot = {
      zslSupp: photoOutput.isZeroShutterLagSupported,
      respSupp: photoOutput.isResponsiveCaptureSupported,
      fastSupp: photoOutput.isFastCapturePrioritizationSupported,
      deferSupp: photoOutput.isAutoDeferredPhotoDeliverySupported,
      zslEn: photoOutput.isZeroShutterLagEnabled,
      respEn: photoOutput.isResponsiveCaptureEnabled,
      fastEn: photoOutput.isFastCapturePrioritizationEnabled,
      deferEn: photoOutput.isAutoDeferredPhotoDeliveryEnabled,
    }
    supports.setValue({
      zsl: snapshot.zslSupp,
      resp: snapshot.respSupp,
      fast: snapshot.fastSupp,
      defer: snapshot.deferSupp,
    })
    zsl.setValue(snapshot.zslEn)
    resp.setValue(snapshot.respEn)
    fast.setValue(snapshot.fastEn)
    defr.setValue(snapshot.deferEn)
    console.log(`[${label}]`, snapshot)
  }

  useEffect(() => {
    async function start() {
      try {
        await session.startRunning()
        isRunning.setValue(true)
        // 启动后 *Supported 才反映真实硬件能力 + active format
        syncFromNative("startRunning")
      } catch (e) {
        await Dialog.alert({ message: `Failed to start: ${String(e)}` })
        dismiss()
      }
    }
    start()
    return () => {
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  function flipZSL(v: boolean) {
    photoOutput.isZeroShutterLagEnabled = v
    syncFromNative(`zsl=${v}`)
  }
  function flipResp(v: boolean) {
    // bridge 在 native 兜底:开 resp 不会自动开 fast(需要单独开);
    // 关 resp 时会先关 fast 保持状态一致。
    photoOutput.isResponsiveCaptureEnabled = v
    syncFromNative(`resp=${v}`)
  }
  function flipFast(v: boolean) {
    // 开 fast 时 bridge 自动把 resp 也开起来(fastSupp 依赖 respEn=true);
    // 关 fast 单独关。
    photoOutput.isFastCapturePrioritizationEnabled = v
    syncFromNative(`fast=${v}`)
  }
  function flipDefer(v: boolean) {
    photoOutput.isAutoDeferredPhotoDeliveryEnabled = v
    syncFromNative(`defer=${v}`)
  }

  async function takeShot() {
    const start = Date.now()
    try {
      const result = await photoOutput.capturePhoto({ codec: "hevc" })
      const ms = Date.now() - start
      const idx = captureCount.value + 1
      captureCount.setValue(idx)
      lastImage.setValue(result.image)
      log.setValue([
        {
          index: idx,
          ms,
          size: `${result.image.width}×${result.image.height}`,
          isDeferredProxy: result.isDeferredProxy,
        },
        ...log.value,
      ].slice(0, 8))
    } catch (e) {
      await Dialog.alert({ message: `capturePhoto failed: ${String(e)}` })
    }
  }

  /** 连拍 5 张, 测响应性体感 */
  async function burst5() {
    for (let i = 0; i < 5; i++) {
      // 不 await 确保连发(响应性开启时这是关键体感)
      takeShot()
    }
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="Responsive capture"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 280 }}
          cornerRadius={12}
          masksToBounds
        />

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Capability (read after startRunning)</Text>
          <Text font="footnote">
            zsl: {String(supports.value.zsl)} · resp: {String(supports.value.resp)} · fast: {String(supports.value.fast)} · defer: {String(supports.value.defer)}
          </Text>
        </VStack>

        <VStack alignment="leading" spacing={6} padding={8}>
          <Toggle
            title="Zero Shutter Lag"
            value={zsl.value}
            onChanged={flipZSL}
            disabled={!supports.value.zsl}
          />
          <Toggle
            title="Responsive Capture"
            value={resp.value}
            onChanged={flipResp}
            disabled={!supports.value.resp}
          />
          <Toggle
            title="Fast Capture Prioritization"
            value={fast.value}
            onChanged={flipFast}
            disabled={!supports.value.fast}
          />
          <Toggle
            title="Auto Deferred Photo Delivery"
            value={defr.value}
            onChanged={flipDefer}
            disabled={!supports.value.defer}
          />
        </VStack>

        <HStack padding={8} spacing={12}>
          <Button title="Single shot" action={takeShot} />
          <Button title="Burst × 5" action={burst5} />
          <Spacer />
          <Text font="footnote" foregroundStyle="secondaryLabel">
            shots: {captureCount.value}
          </Text>
        </HStack>

        {lastImage.value ? (
          <Image
            image={lastImage.value}
            resizable
            scaleToFit
            frame={{ height: 120 }}
          />
        ) : null}

        <VStack alignment="leading" spacing={2} padding={8}>
          <Text font="caption">Recent captures (newest first)</Text>
          {log.value.map(entry => (
            <Text key={entry.index} font="footnote">
              #{entry.index} · {entry.ms}ms · {entry.size}{entry.isDeferredProxy ? " · proxy" : ""}
            </Text>
          ))}
        </VStack>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Tap-to-focus, interruptions, stabilization/index.md
---

# 

***

title: Tap-to-focus, interruptions, stabilization
description: Three small but common controls: focus / exposure point of interest, session interruption notifications, and movie stabilization mode.

***

The three main things you need to worry about when using `AVCaptureSession` are:

- tap-to-focus and tap-to-meter (focus / exposure point of interest on the device)
- session interruption notifications (a phone call, another app grabbing the camera, system pressure)
- video stabilization on the movie output

These are all device / connection level — they don't change how you wire up inputs and outputs.

***

## Tap-to-focus / tap-to-meter

`AVCaptureDevice` exposes a focus point and an exposure point. Both are normalized to `0..1` of the **sensor frame** (not your preview view), with `(0, 0)` at the **top-left of the landscape-oriented sensor**. Most apps map a tap on the preview view into normalized sensor coordinates and then write both the focus point and the exposure point at once:

```ts
const camera = AVCaptureDevice.default("video")!

// Whenever the user taps the preview view, translate the tap into
// normalized sensor coords (your preview layer can do this for you in native;
// in JS you typically pre-compute once per layout).
function tap(at: { x: number; y: number }) {
  if (camera.isFocusPointOfInterestSupported) {
    camera.setFocusPointOfInterest(at)
    camera.setFocusMode("autoFocus")          // single-shot AF at that point
  }
  if (camera.isExposurePointOfInterestSupported) {
    camera.setExposurePointOfInterest(at)
    camera.setExposureMode("continuousAutoExposure")
  }
}
```

A few gotchas:

- `setFocusPointOfInterest` and `setExposurePointOfInterest` are silent no-ops on devices that don't support them — guard with the `is*Supported` flag if you want to surface that to the user.
- These setters acquire the device configuration lock internally; you don't need to wrap them in `lockForConfiguration()`.
- Setting only the point doesn't trigger a refocus — you also need a focus mode (`autoFocus` for one-shot, `continuousAutoFocus` for tracking) and / or an exposure mode change.

***

## Session interruptions

iOS will sometimes pull the camera out from under you: an incoming call, another app moving to the foreground with multi-app support, FaceTime taking the front camera, system thermal pressure. The session keeps running in the background but is paused — your preview will look frozen until iOS hands the hardware back.

Subscribe to know when this happens:

```ts
session.addInterruptionListener((event, reason) => {
  if (event === "began") {
    // Show a "camera unavailable" overlay.
    console.log("interrupted because:", reason)
  } else {
    // Hide the overlay; the session will resume on its own.
    console.log("interruption ended")
  }
})
```

`reason` is one of:

| Reason                                              | When it fires                                                      |
| --------------------------------------------------- | ------------------------------------------------------------------ |
| `videoDeviceNotAvailableInBackground`               | Your app went to the background                                    |
| `audioDeviceInUseByAnotherClient`                   | Another app holds the microphone (e.g. a phone call)               |
| `videoDeviceInUseByAnotherClient`                   | Another app holds the camera (e.g. FaceTime)                       |
| `videoDeviceNotAvailableWithMultipleForegroundApps` | iPad split-view took the camera away                               |
| `videoDeviceNotAvailableDueToSystemPressure`        | Device is too hot or low on resources                              |
| `sensitiveContentMitigationActivated`               | System content blur is engaged                                     |
| `unknown`                                           | New reason added in a future iOS that this build doesn't recognize |

`event === "ended"` always passes an empty string — there is no "reason" for the resume.

You don't need to call `startRunning()` again after `"ended"`. The session resumes automatically.

***

## Video stabilization

The system can apply optical / sensor stabilization on the recorded video. You set a _preferred_ mode on the movie output's video connection — the system decides whether to actually activate it based on the active format and device capability. Always read back the active mode if you want to know what's really happening.

```ts
const movieOutput = new AVCaptureMovieFileOutput()
session.addOutput(movieOutput)

// Pick one before you start recording.
movieOutput.setVideoStabilizationMode("auto")

// After startRunning(), this reflects what the system actually picked:
console.log("active stabilization:", movieOutput.videoStabilizationMode)
```

| Mode                | Notes                                                   |
| ------------------- | ------------------------------------------------------- |
| `off`               | No stabilization.                                       |
| `standard`          | Conservative; good general-purpose default.             |
| `cinematic`         | Heavier crop, smoother result; more processing cost.    |
| `cinematicExtended` | Even heavier crop, designed for handheld walking shots. |
| `auto`              | Let iOS pick based on movement and lighting.            |

Notes:

- Stabilization is applied per **connection**, not per session. If you swap the device-input or rebuild the connection, you need to set the mode again.
- `setVideoStabilizationMode("...")` returns `false` if the movie output isn't attached to a session yet (no video connection exists). Set the mode after `session.addOutput(movieOutput)`.
- Throwing happens only on an unknown mode string — a misspell will surface immediately.
- `videoStabilizationMode` is **active**, not requested. The system may downgrade or disable it silently if the active format doesn't support it.

## Pause / resume and recording progress

A movie recording can be paused and resumed without producing a new file. Both calls are safe no-ops if you call them out of state, and on iOS below 18 (where `isRecordingPaused` is always `false`).

```ts
await movieOutput.startRecording(filePath)

movieOutput.pauseRecording()
console.log(movieOutput.isRecordingPaused)   // true
movieOutput.resumeRecording()

// Live progress while recording:
console.log("seconds:", movieOutput.recordedDuration)
console.log("bytes:", movieOutput.recordedFileSize)

const path = await movieOutput.stopRecording()  // the promise from startRecording resolves here
```

`recordedDuration` (seconds) and `recordedFileSize` (bytes) reflect the current recording and return `0` when not recording. Query `availableVideoCodecTypes` for the codecs the output can record (native raw values such as `"hvc1"` / `"avc1"`).



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/Tap-to-focus, interruptions, stabilization/index_example.md
---

# 

***

title: Example
description: Three small but common controls: focus / exposure point of interest, session interruption notifications, and movie stabilization mode.

***

```tsx
import {
  Button, CaptureVideoPreviewView, HStack, Menu, Navigation, NavigationStack,
  Picker, Script, Spacer, Text, Toolbar, ToolbarItem,
  useEffect, useMemo, useObservable, VStack
} from "scripting"

const STAB_MODES = ["off", "standard", "cinematic", "cinematicExtended", "auto"] as const
type StabMode = typeof STAB_MODES[number]

const POI_PRESETS: { label: string; point: { x: number; y: number } }[] = [
  { label: "Center", point: { x: 0.5, y: 0.5 } },
  { label: "Top-L", point: { x: 0.2, y: 0.2 } },
  { label: "Top-R", point: { x: 0.8, y: 0.2 } },
  { label: "Bot-L", point: { x: 0.2, y: 0.8 } },
  { label: "Bot-R", point: { x: 0.8, y: 0.8 } },
]

function View() {
  const dismiss = Navigation.useDismiss()

  const isRunning = useObservable(false)
  const interruption = useObservable("—")
  const lastPOI = useObservable("—")
  const activeStabilization = useObservable("off")
  const recording = useObservable(false)
  const paused = useObservable(false)
  const progress = useObservable("—")
  const recordedFile = useObservable("")
  const stabMode = useObservable<StabMode>("auto")

  // 录制进度计时器句柄(稳定引用,跨 render 不重建)。
  const timer = useMemo<{ id: number | null }>(() => ({ id: null }), [])

  const { session, camera, movieOutput } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)
    const movieOutput = new AVCaptureMovieFileOutput()

    session.configure(() => {
      session.sessionPreset = "high"
      if (session.canAddInput(input)) session.addInput(input)
      if (session.canAddOutput(movieOutput)) session.addOutput(movieOutput)
    })

    return { session, camera, movieOutput }
  }, [])

  // 中断监听
  useEffect(() => {
    session.addInterruptionListener((event, reason) => {
      if (event === "began") {
        interruption.setValue(`began · ${reason || "unknown"}`)
      } else {
        interruption.setValue("ended")
      }
    })
  }, [])

  // 启动 session + 初始稳定化
  useEffect(() => {
    async function start() {
      try {
        await session.startRunning()
        isRunning.setValue(true)
        // session.addOutput 之后 movieOutput 才有 video connection
        movieOutput.setVideoStabilizationMode(stabMode.value)
        activeStabilization.setValue(movieOutput.videoStabilizationMode)
        // 新增 API:可录制 codec 列表 + connections
        console.log("availableVideoCodecTypes:", movieOutput.availableVideoCodecTypes.join(", "))
        console.log("movieOutput connections:", movieOutput.connections.length)
      } catch (e) {
        await Dialog.alert({ message: `Failed to start: ${String(e)}` })
        dismiss()
      }
    }
    start()
    return () => {
      stopProgressTimer()
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  function applyPOI(p: { x: number; y: number }) {
    let did = false
    if (camera.isFocusPointOfInterestSupported) {
      camera.setFocusPointOfInterest(p)
      camera.setFocusMode("autoFocus")
      did = true
    }
    if (camera.isExposurePointOfInterestSupported) {
      camera.setExposurePointOfInterest(p)
      camera.setExposureMode("continuousAutoExposure")
      did = true
    }
    lastPOI.setValue(
      did
        ? `(${p.x.toFixed(2)}, ${p.y.toFixed(2)})`
        : "device does not support POI"
    )
  }

  function chooseStabilization(mode: StabMode) {
    stabMode.setValue(mode)
    const ok = movieOutput.setVideoStabilizationMode(mode)
    if (!ok) {
      lastPOI.setValue("setVideoStabilizationMode → false (no video connection?)")
      return
    }
    // active 在 startRunning 后由系统决定; 这里多读几次让 UI 反映现实
    activeStabilization.setValue(movieOutput.videoStabilizationMode)
  }

  function stopProgressTimer() {
    if (timer.id != null) {
      clearTimeout(timer.id)
      timer.id = null
    }
  }

  // 自递归 setTimeout(脚本环境只保证 setTimeout/clearTimeout)。每 0.5s 读一次
  // 新增的录制进度 API:recordedDuration / recordedFileSize / isRecordingPaused。
  function tickProgress() {
    const secs = movieOutput.recordedDuration.toFixed(1)
    const kb = (movieOutput.recordedFileSize / 1024).toFixed(0)
    progress.setValue(`${secs}s · ${kb} KB${movieOutput.isRecordingPaused ? " · paused" : ""}`)
    if (recording.value) {
      timer.id = setTimeout(tickProgress, 500)
    }
  }

  async function toggleRecording() {
    if (recording.value) {
      await movieOutput.stopRecording()
      return
    }
    try {
      const path = `${FileManager.documentsDirectory}/session_control_clip.mov`
      try { FileManager.removeSync(path) } catch { }
      recording.setValue(true)
      paused.setValue(false)
      timer.id = setTimeout(tickProgress, 500)
      const finalPath = await movieOutput.startRecording(path)
      recordedFile.setValue(finalPath)
      // 录制结束后 active 可能与录制中不同, 再读一次
      activeStabilization.setValue(movieOutput.videoStabilizationMode)
    } catch (e) {
      await Dialog.alert({ message: `Recording failed: ${String(e)}` })
    } finally {
      stopProgressTimer()
      recording.setValue(false)
      paused.setValue(false)
    }
  }

  // 新增 API:暂停 / 恢复当前录制(iOS 18+;更早系统是 no-op)。
  function togglePause() {
    if (!recording.value) return
    if (movieOutput.isRecordingPaused) {
      movieOutput.resumeRecording()
    } else {
      movieOutput.pauseRecording()
    }
    paused.setValue(movieOutput.isRecordingPaused)
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="PR A · session control"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 360 }}
          cornerRadius={12}
          masksToBounds
        />

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Status</Text>
          <Text font="footnote">
            running: {String(isRunning.value)} · stabilization (active): {activeStabilization.value}
          </Text>
          <Text font="footnote">interruption: {interruption.value}</Text>
          <Text font="footnote">last POI: {lastPOI.value}</Text>
          <Text font="footnote">recording progress: {progress.value}</Text>
          {recordedFile.value ? (
            <Text font="footnote" foregroundStyle="secondaryLabel">
              saved → {recordedFile.value}
            </Text>
          ) : null}
        </VStack>

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Tap-to-focus presets</Text>
          <HStack spacing={6}>
            {POI_PRESETS.map(p => (
              <Button
                key={p.label}
                title={p.label}
                action={() => applyPOI(p.point)}
              />
            ))}
          </HStack>
        </VStack>

        <HStack padding={8}>
          <Text font="caption">Stabilization</Text>
          <Spacer />
          <Menu title={stabMode.value}>
            <Picker
              title="Stabilization"
              value={stabMode.value}
              onChanged={(v: string) => chooseStabilization(v as StabMode)}
            >
              {STAB_MODES.map(m => (
                <Text key={m} tag={m}>{m}</Text>
              ))}
            </Picker>
          </Menu>
        </HStack>

        <HStack padding={8}>
          <Button
            title={recording.value ? "Stop recording" : "Start recording"}
            action={toggleRecording}
          />
          <Button
            title={paused.value ? "Resume" : "Pause"}
            action={togglePause}
            disabled={!recording.value}
          />
          <Spacer />
          <Text font="footnote" foregroundStyle="secondaryLabel">
            Tip: ⌘+H (simulator: Hardware → Home) triggers a background interruption.
          </Text>
        </HStack>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/AVCaptureSession & Camera Control/VideoRecorder vs AVCaptureSession.md
---

# VideoRecorder vs AVCaptureSession

Scripting ships two camera APIs that overlap intentionally. Pick the one that matches the shape of your problem.

## TL;DR

| You want to...                                                        | Use                                            |
| --------------------------------------------------------------------- | ---------------------------------------------- |
| Press record → save mp4                                               | `VideoRecorder`                                |
| Pause / resume during a single clip                                   | `VideoRecorder`                                |
| Built-in audio session, orientation, encoder, file management         | `VideoRecorder`                                |
| Scan QR / barcodes from live frames                                   | `AVCaptureSession` + `AVCaptureMetadataOutput` |
| Custom photo capture (HEVC, flash, Live Photo)                        | `AVCaptureSession` + `AVCapturePhotoOutput`    |
| Bind iPhone 16 Camera Control sliders / pickers                       | `AVCaptureSession` + `AVCaptureControl`        |
| Multiple outputs in one session (photo + movie + metadata)            | `AVCaptureSession`                             |
| Read raw `CMSampleBuffer` / `CVPixelBuffer` (future, not yet exposed) | `AVCaptureSession`                             |

## Concrete differences

`VideoRecorder` is a stateful singleton. It owns one capture session, one writer, one audio session, and a strict state machine (`idle → preparing → ready → recording → ...`). Most apps need exactly that. The trade-off: you cannot run two clips in parallel, attach extra outputs, or change the pipeline mid-flight.

`AVCaptureSession` is plain AVFoundation. Each instance is independent. You can construct multiple sessions, but only one will actually have access to the camera at any given moment — the OS arbitrates that.

If you start an `AVCaptureSession` while `VideoRecorder` is recording (or vice versa) you will get a runtime error from the second consumer. Build your UI to make these mutually exclusive — typically by deciding once at the top of the page which API to use.

## Migrating an existing VideoRecorder use case

Most VideoRecorder users do **not** need to migrate. Migrate if you find yourself:

- Calling `VideoRecorder.session` and reaching into AVFoundation by hand.
- Working around the state machine (e.g. wanting `recording` and `paused` to be flipped over multiple files).
- Needing `AVCaptureMetadataOutput` (QR scanning while recording).

Migration is a per-feature port: enumerate the device with `AVCaptureDevice`, wrap it with `AVCaptureDeviceInput`, attach `AVCaptureMovieFileOutput`, and replace state-listener calls with explicit promise chaining. See the `Quick Start` for the full pattern.

## Both at once

You **can** instantiate `AVCaptureSession` while `VideoRecorder` is `idle`. Just make sure to:

1. Call `await VideoRecorder.reset()` first if it was used earlier in the same script.
2. Call `await session.stopRunning(); session.dispose()` before letting the script return control to the user.



---
url: /guide/Changelog/3.1.0/AVPlayer.md
---

# AVPlayer

`AVPlayer` provides audio and video playback capabilities, including playback control, rate control, looping, playback state observation, and media metadata loading.

You set a media source using `setSource()` (local file or remote URL), then start playback using `play()`.

***

## Getting Started

```ts
const player = new AVPlayer()

if (player.setSource("https://example.com/audio.mp3")) {
  player.onReadyToPlay = () => {
    player.play()
  }

  player.onEnded = () => {
    console.log("Playback finished")
  }
} else {
  console.error("Failed to set media source")
}
```

***

## API Reference

### Properties

#### `volume: number`

Controls the playback volume.
Range: `0.0` (muted) to `1.0` (maximum).

```ts
player.volume = 0.5
```

***

#### `duration: DurationInSeconds`

The total duration of the media in seconds.
This value is `0` until the media has finished loading.

```ts
console.log(player.duration)
```

***

#### `currentTime: DurationInSeconds`

The current playback position in seconds.
You can assign a value to seek to a specific time.

```ts
player.currentTime = 30
```

***

#### `rate: number`

The **current playback rate**.

- `1.0` = normal speed
- `< 1.0` = slower playback
- `> 1.0` = faster playback

This property reflects the actual playback speed while playing.

```ts
player.rate = 1.25
```

***

#### `defaultRate: number`

The **default playback rate used when playback starts**.

- Used when calling `play()` **without** specifying `atRate`
- Changing `defaultRate` does **not** immediately affect an ongoing playback
- Primarily intended to control the rate for the _next_ playback start

```ts
player.defaultRate = 1.5
```

Typical use cases:

- The user selects a preferred playback speed before pressing play
- Playback automatically starts at that speed next time `play()` is called

***

#### `timeControlStatus: TimeControlStatus`

Indicates the current playback state:

- `paused`
  Playback is paused or has not started
- `waitingToPlayAtSpecifiedRate`
  Waiting for playback conditions (e.g. buffering, network)
- `playing`
  Playback is in progress

***

#### `numberOfLoops: number`

Controls how many times the media will loop:

- `0`: no looping
- positive value: loop a specific number of times
- negative value: loop indefinitely

```ts
player.numberOfLoops = -1
```

***

### Methods

#### `setSource(filePathOrURL: string): boolean`

Sets the media source for playback.

Supports:

- Local file paths
- Remote URLs

Returns:

- `true` if the source was set successfully
- `false` if it failed

***

#### `play(atRate?: number): boolean`

Starts playback of the current media.

Playback rate resolution order:

1. If `atRate` is provided, playback starts at that rate
2. Otherwise, `defaultRate` is used

During playback, you can still modify `rate` dynamically.

```ts
player.play()        // Uses defaultRate
player.play(1.25)    // Starts playback at 1.25× speed
```

Returns:

- `true` if playback started successfully
- `false` otherwise

***

#### `pause()`

Pauses playback.

***

#### `stop()`

Stops playback and resets the position to the beginning.

***

#### `dispose()`

Releases all player resources and removes internal observers.
Must be called when the player is no longer needed to avoid resource leaks.

***

#### `loadMetadata(): Promise<AVMetadataItem[] | null>`

Loads the full metadata of the current media.

Returns:

- An array of `AVMetadataItem`
- `null` if no source is set or metadata is unavailable

```ts
const metadata = await player.loadMetadata()
```

***

#### `loadCommonMetadata(): Promise<AVMetadataItem[] | null>`

Loads the _common metadata_ of the current media.

Common metadata provides format-independent `commonKey` values, typically used for title, artist, album, etc.

```ts
const common = await player.loadCommonMetadata()
```

***

### Callbacks

#### `onReadyToPlay?: () => void`

Called when the media is ready for playback.

***

#### `onTimeControlStatusChanged?: (status: TimeControlStatus) => void`

Called whenever the playback state changes, such as:

- waiting → playing
- playing → paused

***

#### `onEnded?: () => void`

Called when playback finishes.

***

#### `onError?: (message: string) => void`

Called when a playback error occurs.
Receives a descriptive error message.

***

## Audio Session Notes

`AVPlayer` relies on the system’s shared audio session.
You should configure and activate it before playback.

```ts
await SharedAudioSession.setCategory('playback', ['mixWithOthers'])
await SharedAudioSession.setActive(true)
```

Handling interruptions (e.g. phone calls):

```ts
SharedAudioSession.addInterruptionListener(type => {
  if (type === 'began') {
    player.pause()
  } else if (type === 'ended') {
    player.play()
  }
})
```

***

## Common Usage Examples

### Play Using the Default Rate

```ts
player.defaultRate = 1.5
player.play()
```

***

### Start Playback at a Specific Rate

```ts
player.play(2.0)
```

***

### Loop Playback

```ts
player.numberOfLoops = 3
player.play()
```

***

### Read Common Metadata

```ts
const metadata = await player.loadCommonMetadata()
if (metadata) {
  const title = metadata.find(i => i.commonKey === 'title')
  console.log(await title?.stringValue)
}
```

***

## Best Practices

1. **Differentiate `defaultRate` vs `rate`**

   - `defaultRate` affects how playback _starts_
   - `rate` reflects or controls the _current_ playback speed

2. **Always Release Resources**

   - Call `dispose()` when playback ends or the player is no longer needed

3. **Observe Playback State**

   - Use `onTimeControlStatusChanged` to update loading or playing UI states

4. **Configure Audio Session Before Playing**

   - Prevent unexpected background, mute, or mixing behavior

5. **Metadata Timing**

   - Reading metadata after `onReadyToPlay` is more reliable

***

## Full Example

```ts
const player = new AVPlayer()

await SharedAudioSession.setCategory('playback', ['mixWithOthers'])
await SharedAudioSession.setActive(true)

player.defaultRate = 1.25

if (player.setSource("https://example.com/audio.mp3")) {
  player.onReadyToPlay = () => {
    player.play()
  }

  player.onEnded = () => {
    console.log("Playback finished")
    player.dispose()
  }

  player.onError = message => {
    console.error("Playback error:", message)
    player.dispose()
  }

  const metadata = await player.loadCommonMetadata()
  if (metadata) {
    const title = metadata.find(i => i.commonKey === 'title')
    console.log("Title:", await title?.stringValue)
  }
}
```



---
url: /guide/Changelog/3.1.0/AudioCapture.md
---

# AudioCapture

The `AudioCapture` class taps the microphone via `AVAudioEngine` and
streams real-time signals to your script: raw PCM frames, RMS / peak
levels, and YIN-based pitch estimates. It is the right tool for
tuners, real-time waveform views, level-triggered logic, and custom
DSP. It can optionally write the captured audio to a WAV file.

> Choosing between `AudioRecorder` and `AudioCapture`:
>
> - **`AudioRecorder`** writes encoded files (m4a / aac / flac / mp3 / opus)
>   and only exposes power meters via `onLevelUpdate`. Pick it for the
>   final-quality recording use case.
> - **`AudioCapture`** exposes the raw waveform plus pitch and level
>   callbacks. Pick it for analysis-driven scripts. It can also save a
>   wav file via `saveTo`, which makes it a superset for _uncompressed_
>   recording.
> - Don't run both at the same time — they would compete for the same
>   audio input bus.

## Features

- Real-time **PCM buffer** callback (`Float32Array` or `Int16Array`).
- Real-time **pitch detection** via YIN with note name and cents offset.
- Real-time **RMS / peak level** callback at a configurable rate.
- Optional **WAV file** output (32-bit float, hardware sample rate).

## Usage

### Setup the audio session

`AudioCapture` shares the system audio session with the rest of the app.
Activate it once before creating the capture instance:

```ts
await SharedAudioSession.setActive(true)
await SharedAudioSession.setCategory(
  "playAndRecord",
  ["defaultToSpeaker"]
)
```

### Create an AudioCapture instance

`create` requests microphone permission and resolves with the instance.
It rejects if permission is denied.

```ts
const capture = await AudioCapture.create({
  // Hardware decides the actual values; these are hints.
  sampleRate: 44100,
  channels: 1,
  bufferSize: 1024,
  format: "float32",
  // Optional: also write captured audio to a wav file
  // saveTo: Path.join(FileManager.documentsDirectory, "capture.wav"),
})
```

### Listen to PCM buffers

```ts
capture.onBuffer = (frame) => {
  // frame.samples is a Float32Array (or Int16Array) of length frames * channels.
  // Channels are interleaved: [L, R, L, R, ...] for stereo.
  console.log(
    `pcm frames=${frame.frames} ch=${frame.channels} ` +
    `sr=${frame.sampleRate} avg=${frame.level.averagePower.toFixed(1)} dB`
  )
}

// Default 0 = follow the hardware tap rate (~43 Hz at 1024 frames / 44.1 kHz).
// Set a positive value to throttle; e.g. 30 = at most 30 buffers per second.
capture.bufferEmitRate = 0
```

### Pitch detection (tuner)

```ts
capture.pitchConfig = {
  minFrequency: 80,    // ignore anything below 80 Hz (low rumble)
  maxFrequency: 1200,  // ignore anything above 1200 Hz
  threshold: 0.15,     // YIN aperiodicity threshold; lower is stricter
  emitRate: 30,        // 30 Hz = one estimate every 33 ms
}

capture.onPitch = (frame) => {
  if (frame.frequency === 0) {
    // Unvoiced frame (silence / noise / chord).
    return
  }
  console.log(
    `${frame.note} ${frame.cents.toFixed(0)}¢  ` +
    `${frame.frequency.toFixed(2)} Hz (conf ${frame.confidence.toFixed(2)})`
  )
}
```

### Lightweight level meter

If you only need a VU meter, prefer `onLevel` over `onBuffer` — it does
not allocate a typed array per frame.

```ts
capture.levelEmitRate = 30
capture.onLevel = (level) => {
  const norm = Math.max(0, (level.averagePower + 60) / 60)
  // norm is roughly in [0, 1]; pipe it into your UI bar.
}
```

### Start, stop, dispose

```ts
const ok = capture.start()
if (!ok) {
  console.error("AudioCapture failed to start")
}

// later ...
capture.stop()
capture.dispose()
```

`stop()` halts the engine and closes the wav file (if any). `dispose()`
also tears down the JS callbacks; call it once you no longer need the
instance to free resources promptly.

### Error handling

```ts
capture.onError = (message) => {
  console.error("AudioCapture error:", message)
}
```

## API Reference

### `AudioCapture.create(config?)`

Requests microphone permission and constructs an instance.

- **config.sampleRate** (number, optional): Hint for the desired sample
  rate. The hardware decides the actual value, exposed via `sampleRate`.
  Default `44100`.
- **config.channels** (`1 | 2`, optional): Channel count hint. Default `1`.
- **config.bufferSize** (number, optional): Frames per tap. Range
  `[256, 8192]`. Default `1024`.
- **config.format** (`"float32" | "int16"`, optional): Sample format for
  `onBuffer.samples`. Default `"float32"`.
- **config.saveTo** (string, optional): If set, captured audio is
  written to this path as a 32-bit float WAV file.

Returns a `Promise<AudioCapture>`.

### `AudioCapture.isRunning`

Whether the engine is running.

### `AudioCapture.sampleRate`

Hardware sample rate after `start()`.

### `AudioCapture.channels`

Hardware channel count after `start()`.

### `AudioCapture.start()`

Starts the engine. Returns `false` on failure (no input available,
session conflict, etc. — `onError` will also fire).

### `AudioCapture.stop()`

Stops the engine and closes the wav file (if any).

### `AudioCapture.dispose()`

Releases the engine, all callbacks, and the wav file.

### `AudioCapture.onBuffer`

PCM buffer callback. Each invocation receives a fresh typed array; safe
to retain.

### `AudioCapture.bufferEmitRate`

Buffers per second for `onBuffer`. `0` = follow the hardware tap rate.

### `AudioCapture.onPitch`

YIN-based pitch estimate callback. `frequency === 0` indicates an
unvoiced frame.

### `AudioCapture.pitchConfig`

Pitch detector parameters: `minFrequency`, `maxFrequency`, `threshold`,
`emitRate`.

### `AudioCapture.onLevel`

RMS / peak level callback (no PCM payload). Cheaper than `onBuffer`.

### `AudioCapture.levelEmitRate`

Levels per second for `onLevel`. Default `30`.

### `AudioCapture.onError`

Error callback. Fires on engine startup failure or runtime issues.

## Example: simple tuner

```ts
import { Path } from 'scripting'

async function run() {
  await SharedAudioSession.setActive(true)
  await SharedAudioSession.setCategory("playAndRecord", ["defaultToSpeaker"])

  const capture = await AudioCapture.create({
    sampleRate: 44100,
    channels: 1,
    format: "float32",
  })

  capture.pitchConfig = {
    minFrequency: 70,
    maxFrequency: 1200,
    threshold: 0.15,
    emitRate: 30,
  }

  capture.onPitch = (frame) => {
    if (frame.frequency > 0 && frame.confidence > 0.7) {
      console.log(
        `${frame.note}  ${frame.cents.toFixed(0)} cents  ` +
        `${frame.frequency.toFixed(2)} Hz`
      )
    }
  }

  capture.onError = (msg) => console.error(msg)

  if (!capture.start()) {
    console.error("Failed to start")
    return
  }

  // Run for 30 seconds, then dispose.
  setTimeout(() => {
    capture.stop()
    capture.dispose()
  }, 30_000)
}

run()
```



---
url: /guide/Changelog/3.1.0/AudioRecorder (Level Metering).md
---

# 

***

title: AudioRecorder (Level Metering)
description: Added level metering: meteringEnabled / averagePower / peakPower / onLevelUpdate. Drive a VU meter or loudness-based triggers while recording, without exposing raw PCM samples.

***

The `AudioRecorder` class allows you to record audio data to a file. It provides functionalities to start, stop, pause, and manage audio recordings, with configurable settings for audio quality, sample rate, format, and more.

## Features

- Record audio from the system’s active input device.
- Record for a specified duration or until manually stopped.
- Pause and resume recordings.
- Delete recorded audio files.

## Usage

### Setup SharedAudioSesion

Before create an AudioRecorder instance, we need to setup the `SharedAudioSession`, the audio session is hardware-related and should be properly activated.

```ts
await SharedAudioSession.setActive(true)
await SharedAudioSession.setCategory(
  "playAndRecord",
  ["defaultToSpeaker"]
)
```

### Creating an AudioRecorder Instance

To create an audio recorder, use the `create` method:

```ts
async function createRecorder() {
  try {
    const filePath = Path.join(
      FileManager.documentsDirectory,
      "recording.m4a"
    )
    const recorder = await AudioRecorder.create(filePath, {
      format: "MPEG4AAC",
      sampleRate: 44100,
      numberOfChannels: 2,
      encoderAudioQuality: AVAudioQuality.high
    })
    return recorder
  } catch (error) {
    console.error("Failed to create recorder: ", error)
  }
}
```

### Recording Audio

You can start recording using the `record()` method:

```ts
async function startRecording() {
  const recorder = await createRecorder()
  if (recorder) {
    const success = recorder.record()
    console.log("Recording started: ", success)
  }
}
```

You can also provide options to control when to start recording and for how long:

```ts
function startSynchronizedRecording(recorderOne, recorderTwo) {
  let timeOffset = recorderOne.deviceCurrentTime + 0.01
  
  // Synchronize the recording time of both recorders.
  recorderOne.record({ atTime: timeOffset })
  recorderTwo.record({ atTime: timeOffset })
}
```

### Pausing and Stopping the Recording

To pause a recording:

```ts
function pauseRecording(recorder) {
  recorder.pause()
  console.log("Recording paused.")
}
```

To stop a recording:

```ts
function stopRecording(recorder) {
  recorder.stop()
  console.log("Recording stopped.")
}
```

### Deleting a Recording

To delete the recorded file:

```ts
function deleteRecording(recorder) {
  const success = recorder.deleteRecording()
  console.log("Recording deleted: ", success)
}
```

### Disposing of the Recorder

You should call `dispose()` when the recorder is no longer needed to free up resources:

```ts
function disposeRecorder(recorder) {
  recorder.dispose()
  console.log("Recorder disposed.")
}
```

### Event Handling

You can use the `onFinish` and `onError` callbacks to handle recording completion and errors:

```ts
async function setupRecorder() {
  const recorder = await createRecorder()
  if (recorder) {
    recorder.onFinish = (success) => {
      console.log("Recording finished successfully: ", success)
    }

    recorder.onError = (message) => {
      console.error("Recording error: ", message)
    }
  }
}
```

### Level Metering (VU meter / volume bar)

`AudioRecorder` can report the average and peak power of the input signal in
dBFS while recording, without exposing raw PCM samples. This is enough to
drive a VU meter or trigger logic on loudness.

Enable metering when creating the recorder, or by setting `meteringEnabled`
before calling `record()`:

```ts
const recorder = await AudioRecorder.create(filePath, {
  format: "MPEG4AAC",
  sampleRate: 44100,
  numberOfChannels: 1,
  meteringEnabled: true,
  // Optional: how often onLevelUpdate fires while recording.
  // In milliseconds, clamped to [16, 1000]. Default 50.
  levelUpdateInterval: 50,
})

recorder.onLevelUpdate = (level) => {
  // level.averagePower / level.peakPower are in dBFS, roughly [-160, 0].
  // Map to a 0..1 bar with something like:
  const norm = Math.max(0, (level.averagePower + 60) / 60)
  console.log(`avg=${level.averagePower.toFixed(1)} dB peak=${level.peakPower.toFixed(1)} dB`)
}

recorder.record()
```

You can also poll the meter manually instead of using the callback:

```ts
recorder.meteringEnabled = true
recorder.record()

setInterval(() => {
  recorder.updateMeters()
  const avg = recorder.averagePower(0)
  const peak = recorder.peakPower(0)
  console.log(`channel 0 → avg=${avg} peak=${peak}`)
}, 100)
```

The level timer stops automatically on `pause()` / `stop()` / `dispose()`
and resumes on the next `record()` while `onLevelUpdate` is set.

> If you need raw PCM samples, real-time waveform data, or pitch
> detection, use the `AudioCapture` class instead.
> `AudioRecorder` is optimized for writing encoded audio files
> (m4a / aac / flac / opus / mp3 / wav).

## API Reference

### `AudioRecorder.create(filePath, settings?)`

Creates an `AudioRecorder` instance with specified settings.

- **filePath** (string): The file system location to record to.
- **settings** (optional object): The audio settings for the recording:
  - **format** (AudioFormat): The format of the audio data. Options: "LinearPCM", "MPEG4AAC", "AppleLossless", "AppleIMA4", "iLBC", "ULaw".
  - **sampleRate** (number): The sample rate in hertz (8000 to 192000).
  - **numberOfChannels** (number): The number of channels (1 to 64).
  - **encoderAudioQuality** (AVAudioQuality): The quality of the audio encoding (from `AVAudioQuality.min` to `AVAudioQuality.max`).

Returns: A `Promise` that resolves with an `AudioRecorder` instance.

### `AudioRecorder.isRecording`

A  boolean indicating whether the recorder is recording.

### `AudioRecorder.currentTime`

The time, in seconds, since the beginning of the recording.

### `AudioRecorder.deviceCurrentTime`

The current time of the host audio device, in seconds.

### `AudioRecorder.record(options?)`

Starts recording audio.

- **options** (optional object): Recording options:
  - **atTime** (number): The time at which to start recording, relative to `deviceCurrentTime`.
  - **duration** (number): The duration of the recording, in seconds.

Returns: A boolean indicating whether recording started successfully.

### `AudioRecorder.pause()`

Pauses the current recording.

### `AudioRecorder.stop()`

Stops recording and closes the audio file.

### `AudioRecorder.deleteRecording()`

Deletes the recorded audio file.

Returns: A boolean indicating whether the deletion was successful.

### `AudioRecorder.dispose()`

Releases resources used by the recorder.

### `AudioRecorder.onFinish`

Callback function invoked when the recording finishes.

- **success** (boolean): Indicates whether the recording finished successfully.

### `AudioRecorder.onError`

Callback function invoked when an encoding error occurs.

- **message** (string): Describes the error.

### `AudioRecorder.meteringEnabled`

Whether level metering is enabled. Toggle before `record()` (or pass
`meteringEnabled: true` to `create`) so that `averagePower`, `peakPower`,
and `onLevelUpdate` report values.

### `AudioRecorder.levelUpdateInterval`

Sampling interval in milliseconds used by `onLevelUpdate`. Clamped to
`[16, 1000]`. Default `50`.

### `AudioRecorder.updateMeters()`

Refreshes the meter values. Call before reading `averagePower` /
`peakPower` if you do not use `onLevelUpdate`.

### `AudioRecorder.averagePower(channel?)`

Returns the average power for the given channel in dBFS, range roughly
`[-160, 0]`. Returns `0` when metering is disabled or the recorder is not
running.

- **channel** (number, optional): Zero-based channel index. Defaults to `0`.

### `AudioRecorder.peakPower(channel?)`

Returns the peak hold power for the given channel in dBFS.

### `AudioRecorder.onLevelUpdate`

Callback invoked while recording at `levelUpdateInterval` cadence when
`meteringEnabled` is `true`.

- **level.averagePower** (number): Average power in dBFS, averaged across channels.
- **level.peakPower** (number): Peak power in dBFS, averaged across channels.
- **level.channels** (`{ average; peak }[]`): Per-channel values.
- **level.timestamp** (number): `deviceCurrentTime` when the sample was taken, in seconds.

## Example Usage

```ts
import { Path } from 'scripting'

async function run() {

  await SharedAudioSession.setActive(true)
  await SharedAudioSession.setCategory(
    "playAndRecord",
    ["defaultToSpeaker"]
  )

  try {
    const filePath = Path.join(
      FileManager.documentsDirectory,
      "recording.m4a"
    )
    const recorder = await AudioRecorder.create(filePath, {
      format: "MPEG4AAC",
      sampleRate: 48000,
      numberOfChannels: 2,
      encoderAudioQuality: AVAudioQuality.high
    })

    recorder.onFinish = (success) => console.log("Recording finished successfully: ", success)
    recorder.onError = (message) => console.error("Recording error: ", message)

    recorder.record()
    setTimeout(() => {
      recorder.stop()
    }, 5000) // Stop recording after 5 seconds
  } catch (error) {
    console.error("Error: ", String(error))
  }
}

run()
```

Use the `AudioRecorder` class to easily manage audio recording operations in your scripts, providing flexibility and control over the audio recording process.



---
url: /guide/Changelog/3.1.0/Canvas (Web 2D drawing context)/index.md
---

# Canvas (Web 2D drawing context)

`Canvas` is a SwiftUI-Canvas-backed view that exposes a Web-Canvas-style 2D drawing
context. The JS-side `CanvasRenderingContext` is a command collector — every method
call or setter records an entry. SwiftUI replays the queue onto a real
`GraphicsContext` every time the view re-evaluates (state / layout changes).

***

## When to use it

- You already know the Web Canvas API and want to bring scripts over with minimal
  rewriting.
- You need imperative drawing (custom charts, sparklines, dashboards, badges,
  signatures, generative art) that doesn't fit neatly into the declarative `Shape` /
  `Rectangle` / `Chart` primitives.
- The drawing depends on data your script computes at render time — not on a 60fps
  animation loop.

For per-frame animation, use `<TimelineCanvas>` instead — it shares the same draw
API but ticks at \~60fps via SwiftUI's `TimelineView`. The closure of `<Canvas>`
runs at React-class frequency (state / layout changes), not per frame.

***

## Basic usage

```tsx
<Canvas
  frame={{ width: 300, height: 200 }}
  draw={(ctx, size) => {
    ctx.fillStyle = "systemBlue"
    ctx.fillRect(0, 0, size.width, size.height)

    ctx.save()
    ctx.translate(size.width / 2, size.height / 2)
    ctx.rotate(Math.PI / 4)
    ctx.strokeStyle = "white"
    ctx.lineWidth = 4
    ctx.strokeRect(-40, -40, 80, 80)
    ctx.restore()
  }}
/>
```

### Props

| Prop     | Type                                          | Description                                                                 |
| -------- | --------------------------------------------- | --------------------------------------------------------------------------- |
| `draw`   | `(ctx: CanvasRenderingContext, size) => void` | Required. Called on every redraw with a fresh ctx and the actual draw size. |
| `opaque` | `boolean`                                     | Defaults to `true`, matching SwiftUI's default.                             |

There are no `width` / `height` props — use any standard view modifier (`frame`,
`padding`, `aspectRatio`, ...) to size the canvas. The real draw size is provided to
`draw` as its second argument.

The `draw` function must be pure with respect to React state — don't call
`setState` inside it. Any return value is ignored.

***

## Supported API surface

### State stack

`save()` — push the full context state (transform, opacity, clip, style) onto a stack.
`restore()` — pop the top of the stack back into the current context.

### Transforms

| Method                           | Notes                                         |
| -------------------------------- | --------------------------------------------- |
| `translate(x, y)`                |                                               |
| `rotate(angle)`                  | `angle` in radians.                           |
| `scale(x, y)`                    |                                               |
| `transform(a, b, c, d, e, f)`    | Concatenates the matrix onto the current one. |
| `setTransform(a, b, c, d, e, f)` | Replaces the current matrix.                  |
| `resetTransform()`               |                                               |

### Paths

`beginPath`, `closePath`, `moveTo`, `lineTo`, `quadraticCurveTo`, `bezierCurveTo`,
`arc`, `arcTo`, `rect`, `ellipse`.

`ellipse(x, y, rx, ry, rotation, startAngle, endAngle, counterclockwise)` renders the
specified partial elliptical arc, with full support for all parameters.

### Drawing

| Method                   | Notes                                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `fill(rule?)`            | `rule` may be `"nonzero"` (default) or `"evenodd"`.                                                                            |
| `stroke()`               | Uses current `strokeStyle` + line settings.                                                                                    |
| `fillRect(x, y, w, h)`   |                                                                                                                                |
| `strokeRect(x, y, w, h)` |                                                                                                                                |
| `clearRect(x, y, w, h)`  | Uses `.clear` blend mode; behavior on opaque canvases differs from Web — to reset to a background color, draw with `fillRect`. |
| `clip(rule?)`            | Adds the current path as a clipping region; subsequent draws are masked. Use `save` / `restore` to remove the clip later.      |

### Text

`fillText(text, x, y, maxWidth?)`, `strokeText(text, x, y, maxWidth?)`.

- `font` accepts a number (`14` → `system(size: 14)`), a SwiftUI font name
  (`"caption"`, `"headline"`, ...), or a `{ name, size }` custom font object — same
  shape as the rest of the bridge.
- `textAlign` / `textBaseline` map to a SwiftUI anchor for `context.draw(_:at:anchor:)`.
- `strokeText` falls back to filling with `strokeStyle`. Outline-only
  text rendering is not yet supported.

#### measureText

```tsx
ctx.font = 22
const m = ctx.measureText("Hello")
//   m.width
//   m.actualBoundingBoxAscent / actualBoundingBoxDescent  (glyph bounds from baseline)
//   m.fontBoundingBoxAscent / fontBoundingBoxDescent      (font-design ascent / descent)
```

`measureText` is **synchronous** — it round-trips to the host and returns immediately,
so you can use the result to lay out subsequent draw commands (centering, pill
backgrounds, manual line breaks). It uses the current `ctx.font` value and reports
sizes in the same units as draw coordinates.

The metrics come from UIKit (`NSAttributedString` + `UIFont`). For SwiftUI text-style
fonts (`"headline"`, `"body"`, ...) the measurement uses
`UIFont.preferredFont(forTextStyle:)`, so width respects the user's current Dynamic
Type setting. SwiftUI's own rendering may differ from UIKit by less than a point on
edge-case glyphs.

### Images

```tsx
ctx.drawImage({ systemName: "star.fill" }, 16, 16, 32, 32)
ctx.drawImage({ filePath: "/some/local/path.png" }, 0, 0)
ctx.drawImage({ image: someUIImage }, 0, 0, 80, 80)
```

- Accepts `{ systemName }` for SF Symbols, `{ filePath }` for files on disk, or
  `{ image: UIImage }` for an in-memory `UIImage`.
- The 9-argument form (`sx, sy, sw, sh, dx, dy, dw, dh`) crops the source
  region before drawing it into the destination rect.
- `imageSmoothingEnabled = false` switches to nearest-neighbor interpolation for
  this canvas (useful for pixel art).
- Remote URLs are not supported here — use the `Image` component for async loading.

### Style state

The same setters and getters as Web canvas:

- `fillStyle`, `strokeStyle` — string color (see below), `CanvasGradient`, or
  `CanvasPattern`.
- `lineWidth`, `lineCap`, `lineJoin`, `miterLimit`, `setLineDash([...])` /
  `getLineDash()`, `lineDashOffset`.
- `globalAlpha` — applied as the SwiftUI context opacity.
- `font`, `textAlign`, `textBaseline`.
- `shadowOffsetX`, `shadowOffsetY`, `shadowBlur`, `shadowColor` — drop-shadow
  state applied to subsequent `fill` / `stroke` / `fillText` / `drawImage`.
- `globalCompositeOperation` — blend mode for subsequent draws (see below).
- `imageSmoothingEnabled` — controls bitmap interpolation for `drawImage`.

### Color strings

`fillStyle` / `strokeStyle` color strings go through the same parser as the rest of
the bridge. The following are all valid:

- Named SwiftUI / system colors: `"systemBlue"`, `"systemGray6"`, `"label"`,
  `"secondaryLabel"`, `"accentColor"`.
- Hex: `"#0a84ff"`, `"#fff"`.
- `"rgb(r, g, b)"` / `"rgba(r, g, b, a)"`.
- `"hsl(h, s%, l%)"` / `"hsla(h, s%, l%, a)"` — hue in degrees, saturation /
  lightness with the trailing `%`, alpha 0–1.

### Gradients

```tsx
const g = ctx.createLinearGradient(0, 0, size.width, size.height)
g.addColorStop(0, "systemTeal")
g.addColorStop(1, "systemIndigo")
ctx.fillStyle = g
ctx.fillRect(0, 0, size.width, size.height)
```

`createRadialGradient(x0, y0, r0, x1, y1, r1)` is also available.
`createConicGradient(startAngle, x, y)` (a SwiftUI `AngularGradient`) is available
as well — not in classic Web Canvas but accepted because the mapping is clean.

Gradient end-points are in canvas pixel coordinates, matching Web Canvas behavior.

> **Radial gradient note:** Web's `createRadialGradient` takes two circles (focal
> point + outer circle); SwiftUI only accepts a single center with start / end radii.
> The bridge uses the second circle's center `(x1, y1)` and treats `r0` / `r1` as
> the start / end radii — visually identical when `r0 ≈ 0` (the common case),
> otherwise the focal-point offset is approximated away.

### Patterns

```tsx
const pattern = ctx.createPattern({ systemName: "star.fill" }, "repeat")
ctx.fillStyle = pattern
ctx.fillRect(0, 0, size.width, size.height)
```

`ctx.createPattern(image, repetition)` returns a `CanvasPattern` you can assign to
`fillStyle` or `strokeStyle`. `image` uses the same source forms as `drawImage`.

> **Limitation:** SwiftUI's tiled-image shading tiles in both axes. `"repeat-x"`,
> `"repeat-y"`, and `"no-repeat"` are accepted by the API but currently behave the
> same as `"repeat"`. Use `ctx.clip(...)` to mask the unwanted axis if you need
> single-axis tiling.

### Shadows

```tsx
ctx.shadowColor   = "rgba(0,0,0,0.5)"
ctx.shadowBlur    = 10
ctx.shadowOffsetX = 4
ctx.shadowOffsetY = 6
ctx.fillStyle = "systemBlue"
ctx.fillRect(40, 40, 120, 80)
```

Shadow state applies to subsequent `fill` / `stroke` / `fillText` / `drawImage`
operations. Set `shadowColor` to a transparent color (or set `shadowBlur` and
both offsets back to `0`) to disable. `shadowBlur` follows Web semantics —
it's the Gaussian blur radius, not the standard deviation.

### Blend modes

```tsx
ctx.globalCompositeOperation = "multiply"
```

Supported values: `"source-over"` (default), `"multiply"`, `"screen"`,
`"overlay"`, `"darken"`, `"lighten"`, `"color-dodge"`, `"color-burn"`,
`"hard-light"`, `"soft-light"`, `"difference"`, `"exclusion"`, `"hue"`,
`"saturation"`, `"color"`, `"luminosity"`, `"plus-lighter"`,
`"destination-over"`.

Unsupported values silently fall back to `"source-over"`. Web's full set of
Porter-Duff modes (`"source-in"`, `"destination-in"`, `"xor"`, etc.) doesn't have
a 1:1 SwiftUI mapping and isn't included.

***

## Performance

The `draw` closure is invoked **synchronously from inside SwiftUI's Canvas closure**.
That closure runs at React-class frequency (state / layout changes), not at 60fps —
each invocation costs one JSCore round-trip plus a JSON serialization of the
commands array, which lands in the millisecond range for typical drawings (hundreds
of commands).

Keep the draw body lightweight: avoid heavy computation, large allocations, or
captures of huge objects. Don't issue thousands of `arc` segments where a single
`bezierCurveTo` would do.

***

***

## TimelineCanvas (per-frame animation)

`<Canvas>` re-runs its draw closure only when React re-evaluates the view (state /
layout changes). For `requestAnimationFrame`-style animation — bouncing balls,
particles, sweeping clocks, generative loops — wrap the same drawing API in a
`<TimelineCanvas>` instead. Under the hood it pairs SwiftUI's
`Canvas` with a `TimelineView`, so the draw closure fires on every frame the
scheduler hands out (\~60fps by default).

```tsx
import { TimelineCanvas, useRef, useState } from "scripting"

function BouncingBall() {
  const [paused, setPaused] = useState(false)
  const ball = useRef({ x: 30, y: 30, vx: 140, vy: 90, lastT: 0 })

  return <>
    <TimelineCanvas
      frame={{ width: 320, height: 180 }}
      paused={paused}
      draw={(ctx, size, time) => {
        const s = ball.current
        // clamp dt so resuming after pause doesn't fling the ball
        const dt = Math.min(0.05, time - s.lastT)
        s.lastT = time

        s.x += s.vx * dt
        s.y += s.vy * dt
        const r = 18
        if (s.x < r || s.x > size.width - r) s.vx = -s.vx
        if (s.y < r || s.y > size.height - r) s.vy = -s.vy

        ctx.fillStyle = "systemGray6"
        ctx.fillRect(0, 0, size.width, size.height)
        ctx.fillStyle = "systemBlue"
        ctx.beginPath()
        ctx.arc(s.x, s.y, r, 0, Math.PI * 2)
        ctx.fill()
      }}
    />
    <Button title={paused ? "Resume" : "Pause"} action={() => setPaused(!paused)} />
  </>
}
```

### Differences from `<Canvas>`

|                     | `<Canvas>`                  | `<TimelineCanvas>`                |
| ------------------- | --------------------------- | --------------------------------- |
| Closure runs on     | state / layout changes      | every frame (\~60fps default)     |
| Third argument      | —                           | `time` in seconds since mount     |
| Cost per invocation | once per redraw             | once per tick, on the main thread |
| Right for...        | charts, data-driven visuals | animation, particles, clocks      |

### Props

| Prop       | Type                                                           | Description                                                                                                                                               |
| ---------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `draw`     | `(ctx, size, time) => void`                                    | Required. `time` is **seconds since the view first appeared**, not a Unix timestamp.                                                                      |
| `paused`   | `boolean`                                                      | When `true`, SwiftUI stops the timeline and the last drawn frame stays on screen. Two-way: flipping this from `useState` halts / resumes immediately.     |
| `schedule` | `"animation"` \| `"periodic"` \| `{ minimumInterval: number }` | Tick cadence. Defaults to `"animation"` (\~60fps). Use `{ minimumInterval: 1/30 }` for \~30fps; `"periodic"` ticks once per second (suitable for clocks). |
| `opaque`   | `boolean`                                                      | Defaults to `true`.                                                                                                                                       |

### Per-frame state

The `draw` closure is recreated on every React render. For state that must survive
across frames (particle arrays, positions, accumulators), keep it in a `useRef` or
in module scope — exactly like classic Web Canvas + `rAF`:

```tsx
const particles = useRef<{ x: number, y: number }[]>([])
```

Don't store per-frame state in `useState` — that would trigger a React re-render on
every frame, which is wasted work.

### Time semantics

`time` is **relative to view mount**, in seconds. Two implications:

1. After \~hours the value stays in safe Number-precision range, so
   `time * speed % period` doesn't drift.
2. If you remount the component (e.g. via key change), `time` resets to `0`.

### Performance

Each tick costs one JSCore round-trip plus a JSON encode of the commands array.
For typical scenes (a few dozen primitives) this lands in the low-millisecond range
and comfortably hits 60fps. For heavy scenes (hundreds of `arc`s, many gradients,
or `measureText` per frame), watch your FPS readout — if it drops below \~50, drop
to `schedule={{ minimumInterval: 1/30 }}`.

A few rules of thumb:

- Cache anything that doesn't change per frame (gradient objects, colors,
  pre-computed paths).
- Avoid `measureText` inside `draw` if you can; measure once when fonts / strings
  change and reuse the result.
- Multiple `<TimelineCanvas>` in the same screen share the main thread; expect
  each one to take a slice of the frame budget.

SwiftUI pauses the timeline automatically when the view leaves the screen
(`NavigationStack` push, scrolled off-viewport), so you don't need to clean it up
manually — but flipping `paused: true` is the right call when _you_ want the
animation halted while the view is still visible.

***

## Not in current version

The following Web-canvas APIs are intentionally deferred — request them on the issue
tracker if you need them earlier:

- `getImageData` / `putImageData` (collector model can't read pixels back).
- `isPointInPath` / `isPointInStroke` (same reason).
- `getTransform` (collector model can't read state back).
- Outline-only `strokeText` — currently falls back to filling with `strokeStyle`.
- Single-axis pattern repetition (`"repeat-x"` / `"repeat-y"` / `"no-repeat"`).
- Porter-Duff `globalCompositeOperation` values without a SwiftUI mapping
  (`"source-in"`, `"destination-in"`, `"xor"`, etc.).



---
url: /guide/Changelog/3.1.0/Canvas (Web 2D drawing context)/index_example.md
---

# Example

```tsx
import { Button, Canvas, HStack, Navigation, NavigationStack, Script, ScrollView, Text, TimelineCanvas, useRef, useState, VStack } from "scripting"

function Example() {
  // Drive a state variable from the screen so the Canvas closure re-runs when you change it.
  // Every re-render replays the commands; nothing animates on its own in Phase 1.
  const [hue, setHue] = useState(0)

  return <NavigationStack>
    <ScrollView>
      <VStack
        navigationTitle={"Canvas"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={28}
        padding
      >

        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          Canvas exposes a Web-Canvas-style 2D context. The `draw` closure is called every time
          SwiftUI re-evaluates the view (state / layout changes). Issue commands on `ctx` —
          `fillRect`, `arc`, `stroke`, etc. — and Swift replays them onto a real SwiftUI
          GraphicsContext.
          {"\n\n"}
          Sizing is controlled by view modifiers (`frame`, `padding`, ...), NOT by canvas props.
          The actual draw size is passed as the second arg to `draw`.
        </Text>

        {/* 1. Basic primitives: fillRect / arc / strokeRect with style strings */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. Primitives + colors</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Color strings go through the same parser as the rest of the bridge — `"systemBlue"`,
            hex `"#RRGGBB"`, `"rgba(...)"`, `"accentColor"` are all valid.
          </Text>
          <Canvas
            frame={{ width: 320, height: 160 }}
            draw={(ctx, size) => {
              // Background
              ctx.fillStyle = "systemGray6"
              ctx.fillRect(0, 0, size.width, size.height)

              // Blue square
              ctx.fillStyle = "systemBlue"
              ctx.fillRect(16, 24, 80, 80)

              // Orange stroked square
              ctx.strokeStyle = "systemOrange"
              ctx.lineWidth = 6
              ctx.strokeRect(120, 24, 80, 80)

              // Red filled circle
              ctx.fillStyle = "systemRed"
              ctx.beginPath()
              ctx.arc(264, 64, 36, 0, Math.PI * 2)
              ctx.fill()
            }}
          />
        </VStack>

        {/* 2. save/restore + transforms */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. save / restore + transforms</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            `save` pushes the entire context state (transform, opacity, clip, style) onto a stack;
            `restore` pops it. A loop of `save → translate → rotate → fillRect → restore` keeps
            each tick independent.
          </Text>
          <Canvas
            frame={{ width: 320, height: 200 }}
            draw={(ctx, size) => {
              ctx.fillStyle = "systemBackground"
              ctx.fillRect(0, 0, size.width, size.height)

              const cx = size.width / 2
              const cy = size.height / 2
              const tickCount = 12

              ctx.fillStyle = "label"
              for (let i = 0; i < tickCount; i++) {
                ctx.save()
                ctx.translate(cx, cy)
                ctx.rotate((Math.PI * 2 * i) / tickCount)
                ctx.fillRect(-2, -64, 4, 16)
                ctx.restore()
              }

              // Center dot — proves transforms were rolled back.
              ctx.fillStyle = "systemBlue"
              ctx.beginPath()
              ctx.arc(cx, cy, 6, 0, Math.PI * 2)
              ctx.fill()
            }}
          />
        </VStack>

        {/* 3. Linear gradient + drawImage (SF symbol as image source) */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. Gradient + drawImage</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            {`\`createLinearGradient(x0, y0, x1, y1)\` returns a \`CanvasGradient\`; add stops and assign
            it to \`fillStyle\`. \`drawImage\` accepts \`{ systemName }\`, \`{ filePath }\` or \`{ image: UIImage }\` —
            the same source forms as the \`Image\` component (Phase 1 supports local sources only).`}
          </Text>
          <Canvas
            frame={{ width: 320, height: 180 }}
            draw={(ctx, size) => {
              const g = ctx.createLinearGradient(0, 0, size.width, size.height)
              g.addColorStop(0, "systemTeal")
              g.addColorStop(1, "systemIndigo")
              ctx.fillStyle = g
              ctx.fillRect(0, 0, size.width, size.height)

              ctx.fillStyle = "white"
              ctx.globalAlpha = 0.9
              ctx.font = 22
              ctx.textAlign = "left"
              ctx.textBaseline = "top"
              ctx.fillText("Linear gradient", 16, 16)

              ctx.globalAlpha = 1
              ctx.drawImage({ systemName: "sparkles" }, size.width - 64, 16, 48, 48)
            }}
          />
        </VStack>

        {/* 4. State-driven redraw */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>4. State-driven redraw</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Tap the button to change a React state. SwiftUI re-evaluates the view, the draw closure
            runs again with the new value, and the canvas redraws.
          </Text>
          <Canvas
            frame={{ width: 320, height: 120 }}
            draw={(ctx, size) => {
              ctx.fillStyle = `hsl(${hue}, 80%, 92%)`
              ctx.fillRect(0, 0, size.width, size.height)

              ctx.fillStyle = `hsl(${hue}, 70%, 45%)`
              ctx.beginPath()
              ctx.arc(size.width / 2, size.height / 2, 36, 0, Math.PI * 2)
              ctx.fill()

              ctx.fillStyle = "label"
              ctx.font = 14
              ctx.textAlign = "center"
              ctx.textBaseline = "middle"
              ctx.fillText(`hue: ${hue}°`, size.width / 2, size.height / 2 + 56)
            }}
          />
          <HStack>
            <Button
              title={"Cycle hue"}
              action={() => setHue((hue + 40) % 360)}
              buttonStyle={"borderedProminent"}
              controlSize={"small"}
            />
          </HStack>
        </VStack>

        {/* 5. measureText — synchronously measure text for layout */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>5. measureText</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            `ctx.measureText(text)` returns a `TextMetrics` synchronously — useful for centering,
            drawing a background pill behind a label, or laying out text by hand. Width and
            ascent/descent are reported in the same units as draw coordinates.
          </Text>
          <Canvas
            frame={{ width: 320, height: 140 }}
            draw={(ctx, size) => {
              ctx.fillStyle = "systemGray6"
              ctx.fillRect(0, 0, size.width, size.height)

              const label = "Tap to measure"
              ctx.font = 22

              const m = ctx.measureText(label)
              const padX = 14
              const padY = 8
              const pillW = m.width + padX * 2
              const pillH = m.actualBoundingBoxAscent + m.actualBoundingBoxDescent + padY * 2
              const cx = size.width / 2
              const cy = size.height / 2

              // Background pill sized to the measured text
              ctx.fillStyle = "systemBlue"
              ctx.beginPath()
              ctx.arc(cx - pillW / 2 + pillH / 2, cy, pillH / 2, Math.PI / 2, -Math.PI / 2)
              ctx.lineTo(cx + pillW / 2 - pillH / 2, cy - pillH / 2)
              ctx.arc(cx + pillW / 2 - pillH / 2, cy, pillH / 2, -Math.PI / 2, Math.PI / 2)
              ctx.lineTo(cx - pillW / 2 + pillH / 2, cy + pillH / 2)
              ctx.fill()

              ctx.fillStyle = "white"
              ctx.textAlign = "center"
              ctx.textBaseline = "middle"
              ctx.fillText(label, cx, cy)

              ctx.fillStyle = "secondaryLabel"
              ctx.font = 11
              ctx.textBaseline = "bottom"
              ctx.fillText(
                `width=${m.width.toFixed(1)}  ascent=${m.actualBoundingBoxAscent.toFixed(1)}`,
                cx,
                size.height - 8,
              )
            }}
          />
        </VStack>

        {/* 6. shadow */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>6. Shadow</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            `shadowColor / shadowBlur / shadowOffsetX / shadowOffsetY` apply a drop shadow to
            subsequent fills, strokes, text, and images.
          </Text>
          <Canvas
            frame={{ width: 320, height: 160 }}
            draw={(ctx, size) => {
              ctx.fillStyle = "systemBackground"
              ctx.fillRect(0, 0, size.width, size.height)

              ctx.shadowColor = "rgba(0, 0, 0, 0.35)"
              ctx.shadowBlur = 12
              ctx.shadowOffsetX = 4
              ctx.shadowOffsetY = 6

              ctx.fillStyle = "systemBlue"
              ctx.fillRect(24, 24, 100, 80)

              ctx.fillStyle = "systemRed"
              ctx.beginPath()
              ctx.arc(200, 64, 36, 0, Math.PI * 2)
              ctx.fill()

              // Disable shadow for label
              ctx.shadowColor = "rgba(0,0,0,0)"
              ctx.fillStyle = "label"
              ctx.font = 13
              ctx.textAlign = "center"
              ctx.textBaseline = "bottom"
              ctx.fillText("shadow on rect + circle", size.width / 2, size.height - 12)
            }}
          />
        </VStack>

        {/* 7. blend modes */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>7. globalCompositeOperation</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Set `ctx.globalCompositeOperation` to map onto a SwiftUI blend mode for subsequent
            draws. Demo: three overlapping discs in `multiply`.
          </Text>
          <Canvas
            frame={{ width: 320, height: 160 }}
            draw={(ctx, size) => {
              ctx.fillStyle = "white"
              ctx.fillRect(0, 0, size.width, size.height)

              ctx.globalCompositeOperation = "multiply"

              const r = 56
              const cy = size.height / 2
              const offsets = [-44, 0, 44]
              const colors = ["systemRed", "systemGreen", "systemBlue"]
              for (let i = 0; i < 3; i++) {
                ctx.fillStyle = colors[i]
                ctx.beginPath()
                ctx.arc(size.width / 2 + offsets[i], cy, r, 0, Math.PI * 2)
                ctx.fill()
              }
            }}
          />
        </VStack>

        {/* 8. partial ellipse arc */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>8. Partial ellipse arc</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            `ellipse(x, y, rx, ry, rotation, start, end, ccw)` renders only the requested arc.
            Demo: a tilted half-ellipse stroke + filled wedge.
          </Text>
          <Canvas
            frame={{ width: 320, height: 180 }}
            draw={(ctx, size) => {
              ctx.fillStyle = "systemGray6"
              ctx.fillRect(0, 0, size.width, size.height)

              // Tilted ellipse, top half only (start=0, end=π, ccw=true so we sweep the upper arc).
              ctx.strokeStyle = "systemPurple"
              ctx.lineWidth = 6
              ctx.beginPath()
              ctx.ellipse(
                size.width / 2, size.height / 2,
                100, 50,
                -Math.PI / 6,
                0, Math.PI,
                true,
              )
              ctx.stroke()

              // Filled pie wedge: an arc to a point and back
              ctx.fillStyle = "systemOrange"
              ctx.beginPath()
              ctx.moveTo(size.width / 2, size.height / 2)
              ctx.ellipse(
                size.width / 2, size.height / 2,
                70, 30,
                Math.PI / 8,
                -Math.PI / 6, Math.PI / 3,
                false,
              )
              ctx.closePath()
              ctx.fill()
            }}
          />
        </VStack>

        {/* 9. createPattern */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>9. createPattern</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Tile an image as fill. SwiftUI tiles in both axes — `"repeat-x"` / `"repeat-y"` /
            `"no-repeat"` map to the same behavior as `"repeat"` for now.
          </Text>
          <Canvas
            frame={{ width: 320, height: 160 }}
            draw={(ctx, size) => {
              // SF Symbols are black-on-clear templates — paint a backdrop first so the
              // transparent regions don't show through as the canvas's undefined "opaque" color.
              ctx.fillStyle = "systemGray6"
              ctx.fillRect(0, 0, size.width, size.height)

              const pattern = ctx.createPattern({ systemName: "star.fill" }, "repeat")
              ctx.fillStyle = pattern
              ctx.fillRect(0, 0, size.width, size.height)
            }}
          />
        </VStack>

        {/* 10. createConicGradient */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>10. createConicGradient</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            `createConicGradient(startAngle, x, y)` returns a SwiftUI `AngularGradient` — not in
            classic Web Canvas, but included because the mapping is clean.
          </Text>
          <Canvas
            frame={{ width: 320, height: 200 }}
            draw={(ctx, size) => {
              ctx.fillStyle = "systemBackground"
              ctx.fillRect(0, 0, size.width, size.height)

              const cx = size.width / 2
              const cy = size.height / 2
              const g = ctx.createConicGradient(0, cx, cy)
              g.addColorStop(0, "systemRed")
              g.addColorStop(0.17, "systemOrange")
              g.addColorStop(0.33, "systemYellow")
              g.addColorStop(0.5, "systemGreen")
              g.addColorStop(0.67, "systemTeal")
              g.addColorStop(0.83, "systemBlue")
              g.addColorStop(1, "systemPurple")
              ctx.fillStyle = g
              ctx.beginPath()
              ctx.arc(cx, cy, 84, 0, Math.PI * 2)
              ctx.fill()
            }}
          />
        </VStack>

        {/* 11. imageSmoothingEnabled + source-rect crop */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>11. imageSmoothingEnabled</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Set `ctx.imageSmoothingEnabled = false` for nearest-neighbor scaling (pixel art look).
            The 9-arg `drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)` form also crops the
            source rect — works best with sufficiently large image sources (`filePath` /
            in-memory `UIImage`); SF Symbols are tiny so source-crop won't show meaningful
            content for them.
          </Text>
          <Canvas
            frame={{ width: 320, height: 140 }}
            draw={(ctx, size) => {
              ctx.fillStyle = "systemGray6"
              ctx.fillRect(0, 0, size.width, size.height)

              // Left: smooth scaling (default)
              ctx.imageSmoothingEnabled = true
              ctx.drawImage({ systemName: "square.grid.3x3.fill" }, 20, 10, 120, 120)

              // Right: nearest-neighbor
              ctx.imageSmoothingEnabled = false
              ctx.drawImage({ systemName: "square.grid.3x3.fill" }, size.width - 140, 10, 120, 120)

              ctx.imageSmoothingEnabled = true
              ctx.fillStyle = "label"
              ctx.font = 11
              ctx.textAlign = "center"
              ctx.textBaseline = "bottom"
              ctx.fillText("smoothing on", 80, size.height - 4)
              ctx.fillText("smoothing off (pixelated)", size.width - 80, size.height - 4)
            }}
          />
        </VStack>

        {/* 12. TimelineCanvas — per-frame animation via SwiftUI TimelineView */}
        <TimelineCanvasDemo />

        {/* 13. TimelineCanvas — particle system, ~100 particles */}
        <TimelineCanvasParticleDemo />

      </VStack>
    </ScrollView>
  </NavigationStack>
}

function TimelineCanvasDemo() {
  // Pause / resume the timeline. The TimelineCanvas keeps the last frame visible while paused.
  const [paused, setPaused] = useState(false)

  // Bouncing ball — state lives in a ref so it survives across frames.
  // (Don't put per-frame state in useState — that triggers React re-renders unnecessarily.)
  const ball = useRef({ x: 60, y: 60, vx: 140, vy: 90, lastTime: 0 })

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>12. TimelineCanvas — per-frame animation</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Like Canvas, but driven by SwiftUI's TimelineView. The draw closure receives a third
      argument — `time` in seconds since the view mounted — and fires every frame
      (~60fps by default). Per-frame state goes in `useRef`.
    </Text>
    <TimelineCanvas
      frame={{ width: 320, height: 180 }}
      paused={paused}
      draw={(ctx, size, time) => {
        const s = ball.current
        const dt = Math.min(0.05, time - s.lastTime) // clamp dt to avoid huge jumps on resume
        s.lastTime = time

        s.x += s.vx * dt
        s.y += s.vy * dt

        const r = 18
        if (s.x < r) { s.x = r; s.vx = -s.vx }
        if (s.x > size.width - r) { s.x = size.width - r; s.vx = -s.vx }
        if (s.y < r) { s.y = r; s.vy = -s.vy }
        if (s.y > size.height - r) { s.y = size.height - r; s.vy = -s.vy }

        ctx.fillStyle = "systemGray6"
        ctx.fillRect(0, 0, size.width, size.height)

        ctx.fillStyle = "systemBlue"
        ctx.beginPath()
        ctx.arc(s.x, s.y, r, 0, Math.PI * 2)
        ctx.fill()

        ctx.fillStyle = "secondaryLabel"
        ctx.font = 11
        ctx.fillText(`t = ${time.toFixed(2)}s`, 8, 16)
      }}
    />
    <HStack>
      <Button title={paused ? "Resume" : "Pause"} action={() => setPaused(!paused)} />
    </HStack>
  </VStack>
}

function TimelineCanvasParticleDemo() {
  // ~100 particles, each a small circle. Demonstrates that TimelineCanvas can drive
  // hundreds of draw commands per frame; keep an eye on the displayed FPS to spot
  // performance regressions.
  //
  // Tip: each particle's color string is pre-computed once and stored on the
  // particle. Generating `hsla(...)` strings every frame would mean 100×
  // toString + 100× Swift-side color parses per tick — measurable in the
  // sub-millisecond range but enough to push a marginal scene under 60fps.
  type Particle = { x: number; y: number; vx: number; vy: number; r: number; color: string }
  const state = useRef<{
    particles: Particle[]
    lastTime: number
    fpsSampleTime: number
    fpsSampleCount: number
    fps: number
  } | null>(null)

  if (state.current == null) {
    const particles: Particle[] = []
    for (let i = 0; i < 100; i++) {
      const hue = Math.floor(Math.random() * 360)
      particles.push({
        x: 160 + (Math.random() - 0.5) * 100,
        y: 90 + (Math.random() - 0.5) * 60,
        vx: (Math.random() - 0.5) * 160,
        vy: (Math.random() - 0.5) * 160,
        r: 3 + Math.random() * 4,
        color: `hsla(${hue}, 80%, 60%, 0.85)`,
      })
    }
    state.current = { particles, lastTime: 0, fpsSampleTime: 0, fpsSampleCount: 0, fps: 0 }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>13. TimelineCanvas — particles + FPS readout</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      100 bouncing particles. The "FPS" overlay is computed from `time` deltas; if you see
      it drop well below 60, your scene is too heavy for per-frame mode — switch to a
      coarser `schedule` like `{"{ minimumInterval: 1/30 }"}`.
    </Text>
    <TimelineCanvas
      frame={{ width: 320, height: 180 }}
      draw={(ctx, size, time) => {
        const s = state.current!
        const dt = Math.min(0.05, s.lastTime === 0 ? 0 : time - s.lastTime)
        s.lastTime = time

        // FPS — update every 0.5s
        s.fpsSampleCount++
        if (time - s.fpsSampleTime > 0.5) {
          s.fps = s.fpsSampleCount / (time - s.fpsSampleTime)
          s.fpsSampleCount = 0
          s.fpsSampleTime = time
        }

        ctx.fillStyle = "systemGray6"
        ctx.fillRect(0, 0, size.width, size.height)

        for (const p of s.particles) {
          p.x += p.vx * dt
          p.y += p.vy * dt
          if (p.x < p.r) { p.x = p.r; p.vx = -p.vx }
          if (p.x > size.width - p.r) { p.x = size.width - p.r; p.vx = -p.vx }
          if (p.y < p.r) { p.y = p.r; p.vy = -p.vy }
          if (p.y > size.height - p.r) { p.y = size.height - p.r; p.vy = -p.vy }

          ctx.fillStyle = p.color
          ctx.beginPath()
          ctx.arc(p.x, p.y, p.r, 0, Math.PI * 2)
          ctx.fill()
        }

        ctx.fillStyle = "label"
        ctx.font = 12
        ctx.fillText(`fps ~ ${s.fps.toFixed(0)}`, 8, 18)
      }}
    />
  </VStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/Chart: LinePlot & AreaPlot (function curves)/index.md
---

# 

***

title: Chart: LinePlot & AreaPlot (function curves)
description: iOS 18+ LinePlot / AreaPlot mark types — plot smooth curves and areas straight from a JS function. Supports single-variable y=f(x), parametric (x,y)=f(t), and AreaPlot (yStart,yEnd)=f(x).

***

`LinePlot` / `AreaPlot` (iOS 18+) plot a smooth curve / area from a **JS function**, not from a data array. SwiftUI Charts samples the function on each chart layout (≈ viewport-width samples) and renders a continuous curve.

The bridge wires the JS callback through `emitWidgetEventSync` (the same channel used for synchronous gesture / drop callbacks), so each sample is one JSCore round-trip.

> **iOS 17 fallback**: the bridge logs an `API deprecated` warning and renders nothing for this mark. Other marks in the same chart still work.

***

## API — three forms

### 1. Single-variable `y = fn(x)`

```tsx
<LinePlot
  x="X"
  y="Y"
  domain={[0, Math.PI * 4]}        // optional
  fn={(x) => Math.sin(x)}
/>
```

- `domain` is optional. Omit to let the chart's visible x domain drive sampling.
- `fn(x: number) => number`. Return `NaN` / non-finite → SwiftUI Charts skips that sample.

### 2. Parametric `(x, y) = fn(t)`

```tsx
<LinePlot
  x="X" y="Y" t="t"
  domain={[0, Math.PI * 2]}        // required for parametric form
  fn={(t) => ({ x: Math.cos(t), y: Math.sin(t) })}
/>
```

- Bridge dispatches on the presence of `t`.
- `domain` is **required** here (the parametric form has no implicit visible-domain fallback).
- `fn` must return `{ x, y }`. Missing fields → that sample is dropped (NaN).

### 3. AreaPlot `(yStart, yEnd) = fn(x)`

```tsx
<AreaPlot
  x="X" yStart="lo" yEnd="hi"
  domain={[0, Math.PI * 4]}        // optional
  fn={(x) => ({ yStart: Math.sin(x) - 0.5, yEnd: Math.sin(x) + 0.5 })}
/>
```

- Fills the vertical band between `yStart` and `yEnd`. Common use: confidence band / envelope.

All three forms accept the standard `ChartMarkProps` (`foregroundStyle` / `opacity` / `lineStyle` / `interpolationMethod` / `accessibilityLabel` / ...) like any other mark — they're applied through the same `applyModifiers` path.

***

## Performance and correctness

- **Pure functions only.** SwiftUI Charts re-runs the closure on every chart layout. Calling `setState` or any other React state mutation inside `fn` triggers an infinite layout loop (same trap as `<ChartGesture>` / `<ChartOverlay>` / `<ChartPlotStyle>` closure bodies).
- **Each sample is a JSCore call (\~5µs).** A 400-pixel-wide chart re-samples ≈ 400 times per layout, ≈ 2 ms. Fine for static / occasionally-updating charts; visible jank on continuous scroll / pinch / per-frame state updates.
- **Stabilize React re-renders.** Each React render that touches the LinePlot's parent rebuilds the `fn` reference, gives it a new bridge callback id, and forces SwiftUI to fully re-layout. `useCallback` keeps the JS reference stable, but does **not** prevent SwiftUI from re-laying out; the bridge still mints a new SwiftUI `LinePlot` value each render. To minimize re-renders, lift state out of the chart tree or memoize the surrounding component.
- **Callback-id accumulation.** Currently every render registers a fresh callback id; old ids stay in the per-component map until the parent component unmounts. For long-lived charts with frequent updates the map grows by O(renders × plots). Acceptable for typical usage but watch out in scrubbing-heavy UIs.
- **Errors / non-finite.** Throwing inside `fn`, returning `undefined`, or returning `NaN` / `Infinity` → bridge substitutes `Double.nan` and SwiftUI Charts skips that sample. Don't rely on this for control flow; design `fn` to be total over its domain.
- **`@Sendable` thread.** SwiftUI Charts marks the closure `@Sendable`; in practice it's invoked on the main thread (where JSContext lives). The bridge `assert`s this. If a future SDK version starts dispatching off-main, the assert will catch it.

***

## See also

- `ChartGesture` — for closures driven by user gestures (pure-body rule applies the same way).
- `ChartPlotStyle` — another reader-style mark child whose closure is repeatedly evaluated.



---
url: /guide/Changelog/3.1.0/Chart: LinePlot & AreaPlot (function curves)/index_example.md
---

# Example

```tsx
import { AreaPlot, Chart, LinePlot, Navigation, NavigationStack, Script, ScrollView, Text, useState, VStack } from "scripting"

function Example() {
  // Drive amplitude with state to show that SwiftUI Charts re-samples the fn on every render.
  const [amplitude, setAmplitude] = useState(1)

  return <NavigationStack>
    <ScrollView>
      <VStack
        navigationTitle={"LinePlot & AreaPlot"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={28}
        padding
      >

        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          LinePlot / AreaPlot are Chart marks introduced in iOS 18+. You pass a JS function
          (not an array of samples); SwiftUI Charts samples it across the viewport at layout
          time and connects the points into a curve.
          {"\n\n"}
          The fn closure must stay pure (no setState, no external side effects). SwiftUI
          Charts re-samples it hundreds of times per layout pass, and each sample is one
          JSCore call — keep the body cheap.
        </Text>

        {/* 1. Single variable y = fn(x) */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. y = sin(x) — single variable</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            domain [0, 4π]. Toggle the link below to change the amplitude and watch the
            whole curve re-render (every render re-samples the function).
          </Text>
          <Chart frame={{ height: 220 }}>
            <LinePlot
              x={"X"}
              y={"Y"}
              domain={[0, Math.PI * 4]}
              fn={(x) => amplitude * Math.sin(x)}
              foregroundStyle={"blue"}
            />
          </Chart>
          <Text font={"caption2"}>amplitude: {amplitude.toFixed(2)}</Text>
          {/* Minimal amplitude toggle */}
          <Text
            foregroundStyle={"link"}
            onTapGesture={() => setAmplitude(amplitude === 1 ? 1.6 : 1)}
          >
            tap to toggle amplitude (1 ↔ 1.6)
          </Text>
        </VStack>

        {/* 2. Parametric curve (x, y) = fn(t) */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Parametric — circle (cos t, sin t)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            t ∈ [0, 2π]. fn returns a {`{ x, y }`} tuple, which the bridge converts to
            SwiftUI's (x: Double, y: Double) tuple. Traces a full circle.
          </Text>
          <Chart
            frame={{ height: 240, width: 240 }}
            chartXScale={{ from: -1.2, to: 1.2 }}
            chartYScale={{ from: -1.2, to: 1.2 }}
          >
            <LinePlot
              x={"X"}
              y={"Y"}
              t={"t"}
              domain={[0, Math.PI * 2]}
              fn={(t) => ({ x: Math.cos(t), y: Math.sin(t) })}
              foregroundStyle={"orange"}
            />
          </Chart>
        </VStack>

        {/* 3. AreaPlot — vertical band */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. AreaPlot — sin envelope ±0.5</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            fn returns {`{ yStart, yEnd }`}, and AreaPlot fills the vertical interval from
            yStart to yEnd at every x — typical use cases are confidence bands and envelopes.
          </Text>
          <Chart frame={{ height: 220 }}>
            <AreaPlot
              x={"X"}
              yStart={"lo"}
              yEnd={"hi"}
              domain={[0, Math.PI * 4]}
              fn={(x) => ({
                yStart: Math.sin(x) - 0.5,
                yEnd: Math.sin(x) + 0.5,
              })}
              foregroundStyle={{ color: "green", opacity: 0.35 }}
            />
            <LinePlot
              x={"X"}
              y={"Y"}
              domain={[0, Math.PI * 4]}
              fn={(x) => Math.sin(x)}
              foregroundStyle={"green"}
            />
          </Chart>
        </VStack>

      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/Chart: gesture, overlay & styling/index.md
---

# 

***

title: Chart: gesture, overlay & styling
description: ChartGesture (custom gestures + ChartProxy.select\* for programmatic selection), ChartPlotStyle (plot-area background / border / frame builder), ChartAxisLabelFormat (currency / number / date precision factories), and per-mark VoiceOver fields (accessibilityLabel / Value / Hidden).

***

This example demonstrates four chart interaction / customization features:

- **`ChartOverlay`** — a reader-style child of `<Chart>` that gives custom content access to a `ChartProxy` for hit-testing, value↔coordinate conversion, and reading the plot area frame. Mirrors SwiftUI Charts' `chartOverlay(alignment:content:) { proxy in ... }`.
- **Range selection** — pass `from` / `to` (instead of `value`) to `chartXSelection` / `chartYSelection` and the bridge wires up SwiftUI's `chartXSelection(range:)` / `chartYSelection(range:)` overload.
- **`ChartGesture`** — another reader-style child of `<Chart>`. The closure returns any `Gesture` descriptor and receives a writable `ChartProxy` so you can drive selection with custom gestures (e.g. single-finger drag-range on a categorical String axis). Mirrors `chartGesture(_:) { proxy in ... }`.
- **`ChartPlotStyle`** — a reader-style child whose closure builds a chain of plot-area modifiers (background / border / frame / shadow / corner radius / clip shape / opacity). Mirrors `chartPlotStyle { plot in plot.background(...).border(...) }`.

***

## ChartOverlay quick reference

```tsx
import { Chart, ChartOverlay, ChartProxy } from "scripting"

<Chart>
  <BarChart marks={...} />
  <ChartOverlay alignment={"topLeading"}>
    {(proxy: ChartProxy) => (
      // Render any view on top of the chart.
      // proxy.value / proxy.position / proxy.plotAreaSize are available here.
    )}
  </ChartOverlay>
</Chart>
```

`ChartProxy` is synchronous and returns `null` when the type token does not match the chart's actual axis data type:

```ts
interface ChartProxy {
  // Read: lookup / position / plot area
  value(args: { atX?: number; atY?: number; as: 'string' | 'number' | 'date' })
    : string | number | Date | null
  position(args: { x?: string | number | Date; y?: string | number | Date })
    : { x: number; y: number } | null
  readonly plotAreaSize: { width: number; height: number }
  readonly plotAreaFrame: { x: number; y: number; width: number; height: number }

  // Write: drive selection (use inside <ChartGesture>)
  selectXRange(args: { from: number; to: number }): void
  selectYRange(args: { from: number; to: number }): void
  selectXValue(args: { at: number }): void
  selectYValue(args: { at: number }): void
  selectAngleValue(args: { atRadians: number }): void
}
```

***

## Range selection quick reference

```tsx
const [range, setRange] = useState<{ from: string; to: string } | null>(null)

<Chart
  chartXSelection={{
    valueType: "string",
    from: range?.from,
    to: range?.to,
    onChanged: setRange,
  }}
>
  ...
</Chart>
```

- The bridge dispatches on the **presence of `from` / `to`** to pick the SwiftUI `chartXSelection(range:)` overload. Single-value selection (`value` + `onChanged`) keeps working unchanged.
- `valueType: 'string' | 'number' | 'date'` — must match the chart's plotted axis data type.
- `onChanged` fires whenever the selection changes and again with `null` when the selection is cleared.

> **Axis-type constraint**: range selection only works on **continuous axes** (number / date). On categorical String axes SwiftUI Charts neither responds to the default range gesture nor reverse-maps screen-pixel coordinates back to a category, so even `<ChartGesture>` + `proxy.selectXRange(...)` cannot drive a String-axis range. For String axes use the single-value form (`ChartSelection`) instead.

### Activation gesture (platform-specific)

`chartXSelection(range:)` default gesture differs by platform — **this is a SwiftUI Charts SDK behaviour, not a bridge limitation**:

- **iOS**: a **two-finger tap** on the chart. In iOS Simulator, hold **⌥ Option** while clicking the chart to simulate a two-finger touch.
- **macOS**: a **drag gesture**.

Single-finger long-press-and-drag does NOT trigger range selection by default. If you need a single-finger interaction or any custom activation, use `<ChartGesture>` to take over the chart's gesture handling.

Sources: [Mastering charts in SwiftUI · Selection](https://swiftwithmajid.com/2023/07/18/mastering-charts-in-swiftui-selection/), [WWDC23 · Explore pie charts and interactivity in Swift Charts](https://developer.apple.com/videos/play/wwdc2023/10037/).

The two forms are mutually exclusive on a given axis. Use a single-value selection for tap interactions, and the range form for drag-to-zoom or drag-to-summarize gestures.

***

## Axis-label precision (ChartAxisLabelFormat)

In addition to the short string tokens (`'number' | 'percent' | 'currency' | 'date' | 'time' | 'dateTime'`), the `valueLabel.format` field of `chartXAxis` / `chartYAxis` accepts a native `ChartAxisLabelFormat` instance. Use it when you need fraction-digit precision, a fixed currency code, or a non-default date / time style — mirrors SwiftUI Foundation's `FormatStyle` family.

```tsx
<Chart chartYAxis={{
  valueLabel: {
    format: ChartAxisLabelFormat.currency({ currencyCode: "CNY", fractionDigits: 2 })
  }
}}>
  ...
</Chart>
```

Available factories:

| Factory                                | Plottable | Options                                                                             |
| -------------------------------------- | --------- | ----------------------------------------------------------------------------------- |
| `ChartAxisLabelFormat.number({...})`   | `Double`  | `fractionDigits` (max) / `minFractionDigits` (min)                                  |
| `ChartAxisLabelFormat.percent({...})`  | `Double`  | same as number (`0.42` → `42%`)                                                     |
| `ChartAxisLabelFormat.currency({...})` | `Double`  | `fractionDigits` / `minFractionDigits` / `currencyCode` (defaults to device locale) |
| `ChartAxisLabelFormat.date({...})`     | `Date`    | `dateStyle`: `omitted` / `numeric` / `abbreviated` / `long` / `complete`            |
| `ChartAxisLabelFormat.time({...})`     | `Date`    | `timeStyle`: `omitted` / `shortened` / `standard` / `complete`                      |
| `ChartAxisLabelFormat.dateTime({...})` | `Date`    | both `dateStyle` and `timeStyle`                                                    |

> Short string tokens stay fully supported; pick whichever fits. Use the class when you need precision / currency / style; otherwise the concise `format: 'number'` form is plenty.

***

## ChartGesture quick reference

```tsx
import { Chart, ChartGesture, DragGesture } from "scripting"

<Chart
  chartXSelection={{ valueType: "number", from, to, onChanged: setRange }}
>
  ...marks...
  <ChartGesture>
    {(proxy) =>
      DragGesture({ minDistance: 0 })
        .onChanged(v => proxy.selectXRange({
          from: v.startLocation.x,
          to: v.location.x,
        }))
    }
  </ChartGesture>
</Chart>
```

- The closure returns a `Gesture` descriptor (`DragGesture()` / `TapGesture()` / `LongPressGesture()` / `MagnifyGesture()` / `RotateGesture()`), equivalent to SwiftUI's `chartGesture { proxy in ... }`.
- `proxy.selectXRange / selectYRange / selectXValue / selectYValue / selectAngleValue` accept **screen-space pixel coordinates** (not data values) — feed `DragGesture` event `startLocation.x` / `location.x` directly without reverse-mapping.
- After writing the selection, the matching `chartXSelection / chartYSelection / chartAngleSelection` binding fires `onChanged` with the bound data values.
- Only the first `<ChartGesture>` child of a chart is used (same rule as `<ChartOverlay>`).
- Use this to **replace** the default gesture (single-finger drag, custom activation, etc.).
- **Axis-type constraint**: same as the default range gesture — only number / date axes are supported. On categorical String axes the SDK can't reverse-map pixels back to a category, so `proxy.selectXRange` on a String axis won't fire `onChanged`.

***

## ChartPlotStyle quick reference

```tsx
import { Chart, ChartPlotStyle } from "scripting"

<Chart>
  <BarChart marks={...} />
  <ChartPlotStyle>
    {(plot) =>
      plot
        .background({ color: "gray", opacity: 0.1 })
        .border({ color: "gray", width: 1 })
        .frame({ height: 240 })
    }
  </ChartPlotStyle>
</Chart>
```

The closure receives an empty `ChartPlotProxy` and must return a (possibly transformed) `ChartPlotProxy`. Each chained call returns a new immutable proxy and accumulates an op; the bridge replays the ops on the real `ChartPlotContent` view inside `chartPlotStyle { plot in ... }`.

Available builder methods:

| Method             | Args                                                                   | Maps to                                         |
| ------------------ | ---------------------------------------------------------------------- | ----------------------------------------------- |
| `.background(arg)` | `Color` string, `Material` token, or `{ color?, material?, opacity? }` | `.background(...)`                              |
| `.border(arg)`     | `{ color?, width? }`                                                   | `.border(color, width:)`                        |
| `.frame(arg)`      | `{ width?, height? }`                                                  | `.frame(width:height:)`                         |
| `.padding(arg?)`   | `number` / `EdgeInsets` / `{ horizontal?, vertical? }` / no-arg        | `.padding(...)`                                 |
| `.cornerRadius(r)` | `number`                                                               | `.clipShape(RoundedRectangle(cornerRadius: r))` |
| `.opacity(v)`      | `number`                                                               | `.opacity(v)`                                   |
| `.shadow(arg)`     | `{ color?, radius?, x?, y? }`                                          | `.shadow(color:radius:x:y:)`                    |
| `.clipShape(arg)`  | `'capsule'` / `'rect'` / `{ rounded: <radius> }`                       | `.clipShape(...)`                               |

`Material` tokens: `'ultraThin'` / `'thin'` / `'regular'` / `'thick'` / `'ultraThick'` / `'bar'` (suffix `Material` is also accepted, e.g. `'regularMaterial'`).

> Like `<ChartOverlay>` and `<ChartGesture>`, only the FIRST `<ChartPlotStyle>` child of a chart is honored. The closure body must remain pure — `setState` calls inside will trigger an infinite chart-rebuild loop. Use it as a pure builder.

***

## Mark Accessibility

Each mark accepts three optional VoiceOver fields directly on its `ChartMarkProps`:

```tsx
<BarChart
  marks={data.map(d => ({
    label: d.year,
    value: d.sales,
    accessibilityLabel: `Year ${d.year}`,
    accessibilityValue: `${d.sales} dollars`,
    // accessibilityHidden: true,  // exclude this mark entirely
  }))}
/>
```

| Field                           | Maps to                                     | Effect                                                                                    |
| ------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `accessibilityLabel?: string`   | `.accessibilityLabel(_:)` on `ChartContent` | Overrides the SDK's default label (which is synthesized from the mark's plotted values).  |
| `accessibilityValue?: string`   | `.accessibilityValue(_:)`                   | Sets the spoken value separately from the label.                                          |
| `accessibilityHidden?: boolean` | `.accessibilityHidden(_:)`                  | When `true`, the mark is excluded from the VoiceOver tree (won't be focusable or spoken). |

These work on every mark type (`BarMark`, `LineMark`, `PointMark`, `RuleMark`, `RectangleMark`, `AreaMark`, sectors, ...) and are applied through the same `ChartContent.applyModifiers` path as `foregroundStyle` / `opacity` / etc.

> Test on a real device or in Simulator with `Settings → Accessibility → VoiceOver`. Swipe on the chart, then swipe right between marks to hear the labels you set.

***

## Pitfalls

- **`ChartOverlay` proxy is `null` on the very first synchronous render.** `<ChartOverlay>` falls back to `EmptyView` until SwiftUI has built the chart and injected a real proxy. Build for that case in your render function.
- **`SelectedRange / selectedRangeAxis` are NOT exposed on `ChartProxy`.** SwiftUI Charts does not surface range-selection state through `ChartProxy` — observe it through the `chartXSelection(range:)` / `chartYSelection(range:)` binding instead. The TS interface deliberately omits these.
- **`chartOverlay` does not have a `spacing` parameter.** Only `alignment` is supported (matches the SwiftUI API).
- **Keep overlay content cheap.** SwiftUI rebuilds the overlay closure every time the chart re-renders. Avoid heavy work or async kick-off inside.
- **`<ChartGesture>` / `<ChartOverlay>` closure body MUST stay pure.** SwiftUI Charts re-runs the closure on every chart rebuild; calling `setState` inside the body triggers a React re-render → another chart rebuild → the closure runs again → **infinite loop**. Push state changes into the gesture's `onChanged / onEnded` callbacks (which are user-event triggered) instead.
- **The `<ChartGesture>` closure must return a `GestureInfo`** (the value returned by `DragGesture()` / `TapGesture()` / etc.). Returning `null` or any other type is silently ignored.



---
url: /guide/Changelog/3.1.0/Chart: gesture, overlay & styling/index_example.md
---

# Example

```tsx
import { BarChart, Chart, ChartGesture, ChartOverlay, ChartPlotStyle, Color, DragGesture, GeometryReader, LineChart, Navigation, NavigationStack, PointChart, Rectangle, RoundedRectangle, RuleLineForLabelChart, Script, ScrollView, Spacer, Text, useState, VStack, ZStack } from "scripting"

const data = [
  { year: '2020', sales: 1200 },
  { year: '2021', sales: 1400 },
  { year: '2022', sales: 2000 },
  { year: '2023', sales: 2500 },
  { year: '2024', sales: 3600 },
]

function Example() {
  // Section 1 — single-value selection (existing API; shown alongside overlay-driven tooltip).
  const [hover, setHover] = useState<string | null>(null)
  const hoverPoint = hover != null ? data.find(d => d.year === hover) : null

  // Section 2 — range selection on a NUMERIC X axis (categorical String axes do
  // NOT respond to range-selection gestures in SwiftUI Charts; SDK limitation).
  const [range, setRange] = useState<{ from: number; to: number } | null>(null)
  const [rawDetails, setRawDetails] = useState<string>("(awaiting range gesture)")
  const inRangeIdx = (i: number) =>
    range != null && i >= range.from && i <= range.to

  // Section 3 — single-finger drag-range via <ChartGesture>. We feed pixel coords to
  // proxy.selectXRange so it works on a continuous axis even WITHOUT the SDK's default
  // two-finger gesture. Only number / date axes are supported; categorical String axes
  // can't reverse-map pixels back to a category, so they don't work even via this path.
  const [gestureRange, setGestureRange] = useState<{ from: number; to: number } | null>(null)
  const inGestureRange = (i: number) =>
    gestureRange != null && i >= gestureRange.from && i <= gestureRange.to

  return <NavigationStack>
    <ScrollView>
      <VStack
        navigationTitle={"Chart Overlay & Range Selection"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={32}
        padding
      >

        {/* 1. ChartOverlay: hit-test → custom tooltip */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. ChartOverlay tooltip (hit-test via ChartProxy)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}
            styledText={{
              content: [
                {
                  content: "Tap or drag on the chart. The overlay reads the X coordinate via",
                  font: "caption",
                  foregroundColor: "secondaryLabel",
                },
                {
                  content: " proxy.value({atX, as: 'string'})",
                  font: "caption",
                  foregroundColor: "label",
                  monospaced: true,
                },
                {
                  content: "and draws a custom annotation.",
                  font: "caption",
                  foregroundColor: "secondaryLabel",
                },
              ]
            }}
          />
          <Chart
            frame={{ height: 240 }}
            chartXSelection={{
              value: hover,
              onChanged: (v: any) => {
                setHover(v ?? null)
              },
              valueType: "string",
            }}
          >
            <LineChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                interpolationMethod: "catmullRom",
                symbol: "circle",
                // VoiceOver 三件套：以 mark 为单位 override SDK 默认拼接的 label/value。
                // 开启 VoiceOver 后，左右滑动每个圆点会朗读这里的字符串而不是默认的 "Year 2024 Sales 3600"。
                accessibilityLabel: `Year ${d.year}`,
                accessibilityValue: `${d.sales} dollars`,
              }))}
            />
            {hoverPoint != null
              ? <RuleLineForLabelChart
                marks={[{
                  label: hoverPoint.year,
                  foregroundStyle: { color: "gray", opacity: 0.4 },
                }]}
              />
              : null}
            <ChartOverlay alignment={"topLeading"}>
              {(proxy) => (
                hoverPoint == null
                  ? <Spacer />
                  : <ZStack
                    padding={6}
                    background={
                      <RoundedRectangle cornerRadius={4} fill={"regularMaterial"} />
                    }
                  >
                    <Text font={"caption2"}>
                      {hoverPoint.year}: ${hoverPoint.sales}
                    </Text>
                  </ZStack>
              )}
            </ChartOverlay>
          </Chart>
        </VStack>

        {/* 2. Range selection: NUMERIC X axis (PointChart). String axes do not respond. */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Range selection (chartXSelection range form)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            On iOS, the default range-selection gesture is a TWO-FINGER tap on the chart
            (in Simulator: hold ⌥ Option then click). On macOS it's a drag.
            Selected: {range == null ? "(none)" : `${range.from} → ${range.to}`}
          </Text>
          <Text font={"caption2"} foregroundStyle={"orange"} monospaced>
            raw onChanged details: {rawDetails}
          </Text>
          <Chart
            frame={{ height: 240 }}
            chartXSelection={{
              valueType: "number",
              from: range?.from,
              to: range?.to,
              onChanged: (v: any) => {
                setRawDetails(JSON.stringify(v))
                setRange(v)
              },
            }}
          >
            <PointChart
              marks={data.map((d, i) => ({
                x: i,
                y: d.sales,
                foregroundStyle: inRangeIdx(i) ? "orange" : "gray",
                symbolSize: inRangeIdx(i) ? 120 : 60,
              }))}
            />
          </Chart>
        </VStack>

        {/* 3. Single-finger drag-range via <ChartGesture> (number axis). */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. Single-finger drag-range (chartGesture)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Drag with a single finger anywhere on the chart — covered points turn orange.
            chartGesture takes over the chart's gesture handling, so this works without the
            two-finger default. Pair with chartXSelection(range:) to get bound data values.
            {"\n"}Selected: {gestureRange == null ? "(none)" : `${gestureRange.from} → ${gestureRange.to}`}
          </Text>
          <Chart
            frame={{ height: 240 }}
            chartXSelection={{
              valueType: "number",
              from: gestureRange?.from,
              to: gestureRange?.to,
              onChanged: setGestureRange,
            }}
          >
            <PointChart
              marks={data.map((d, i) => ({
                x: i,
                y: d.sales,
                foregroundStyle: inGestureRange(i) ? "orange" : "blue",
                symbolSize: inGestureRange(i) ? 120 : 60,
              }))}
            />
            <ChartGesture>
              {(proxy) =>
                DragGesture({ minDistance: 0 })
                  .onChanged(v => proxy.selectXRange({
                    from: v.startLocation.x,
                    to: v.location.x,
                  }))
              }
            </ChartGesture>
          </Chart>
        </VStack>

        {/* 4. ChartAxisLabelFormat — Y 轴用 currency / number 精度形态 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>4. ChartAxisLabelFormat (axis label precision)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Two charts share the same data; the only difference is the Y-axis valueLabel.format.
            Top chart uses the short token "currency" (default fraction digits, device locale).
            Bottom chart uses ChartAxisLabelFormat.currency with explicit fractionDigits + currencyCode.
          </Text>

          <Text font={"caption2"} foregroundStyle={"label"}>
            Top: format: 'currency'
          </Text>
          <Chart
            frame={{ height: 180 }}
            chartYAxis={{
              valueLabel: {
                format: 'currency',
              },
            }}
          >
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "blue",
              }))}
            />
          </Chart>

          <Text font={"caption2"} foregroundStyle={"label"}>
            Bottom: format: ChartAxisLabelFormat.currency({"{"} currencyCode: "CNY", fractionDigits: 2 {"}"})
          </Text>
          <Chart
            frame={{ height: 180 }}
            chartYAxis={{
              valueLabel: {
                format: ChartAxisLabelFormat.currency({
                  currencyCode: "CNY",
                  fractionDigits: 2,
                }),
              },
            }}
          >
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "orange",
              }))}
            />
          </Chart>

          <Text font={"caption2"} foregroundStyle={"label"}>
            Plain number with one fraction digit:
          </Text>
          <Chart
            frame={{ height: 180 }}
            chartYAxis={{
              valueLabel: {
                format: ChartAxisLabelFormat.number({
                  fractionDigits: 1,
                  minFractionDigits: 1,
                }),
              },
            }}
          >
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "green",
              }))}
            />
          </Chart>
        </VStack>

        {/* 5. ChartPlotStyle — plot 区域自定义视觉 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>5. ChartPlotStyle (custom plot-area styling)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            ChartPlotStyle is a reader-style child whose closure receives a builder proxy.
            Each chained call accumulates an op (background / border / frame / shadow / ...);
            on the Swift side the bridge replays the ops on the real ChartPlotContent view.
          </Text>

          <Text font={"caption2"} foregroundStyle={"label"}>
            5a. background + border (gray fill, 1pt gray outline):
          </Text>
          <Chart frame={{ height: 180 }}>
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "blue",
              }))}
            />
            <ChartPlotStyle>
              {(plot) =>
                plot
                  .background({ color: "gray", opacity: 0.12 })
                  .border({ color: "gray", width: 1 })
              }
            </ChartPlotStyle>
          </Chart>

          <Text font={"caption2"} foregroundStyle={"label"}>
            5b. material background + corner radius (regularMaterial, 12pt rounded corners):
          </Text>
          <Chart frame={{ height: 180 }}>
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "orange",
              }))}
            />
            <ChartPlotStyle>
              {(plot) =>
                plot
                  .background({ material: "regularMaterial" })
                  .cornerRadius(12)
              }
            </ChartPlotStyle>
          </Chart>

          <Text font={"caption2"} foregroundStyle={"label"}>
            5c. shadow + frame (drop shadow + fixed plot height):
          </Text>
          <Chart frame={{ height: 200 }}>
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "green",
              }))}
            />
            <ChartPlotStyle>
              {(plot) =>
                plot
                  .background({ color: "white" })
                  .shadow({ color: "gray", radius: 6, x: 0, y: 2 })
                  .frame({ height: 140 })
              }
            </ChartPlotStyle>
          </Chart>
        </VStack>

      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/Chart: legend control/index.md
---

# 

***

title: Chart: legend control
description: chartLegend accepts a Visibility string ("automatic" / "visible" / "hidden") to keep or remove the auto-generated legend, or an object (\{ position, alignment?, spacing?, content? }) to reposition or fully customize it.

***

The `chartLegend` modifier controls the legend of a chart. It accepts two forms:

- A **`Visibility`** string — `"automatic"` (default), `"visible"`, or `"hidden"` — to keep or remove the auto-generated legend.
- An **object** to customize the legend's placement: `{ position, alignment?, spacing?, content? }`.

```tsx
// Visibility form
<Chart chartLegend={"hidden"}>...</Chart>

// Object form — move the legend to the bottom
<Chart chartLegend={{ position: "bottom", spacing: 8 }}>...</Chart>
```

A legend only appears when a chart has more than one series. Use `foregroundStyleBy` (or `symbolBy` / `lineStyleBy`) on your marks to group data into series.

## Example Scenario

This example renders a grouped bar chart with three color series, so a legend is shown. A segmented picker switches `chartLegend` between the visibility values and a custom bottom-anchored legend:

- `"automatic"` / `"visible"` — keep the auto-generated legend.
- `"hidden"` — remove the legend.
- `"bottom (custom)"` — use the object form to move the legend below the plot.

## Props

### `chartLegend?: Visibility | { position, alignment?, spacing?, content? }`

- `Visibility`: `"automatic"` | `"visible"` | `"hidden"`.
- Object form:
  - `position: AnnotationPosition` — where the legend sits relative to the plot (e.g. `"bottom"`, `"top"`, `"trailing"`).
  - `alignment?: Alignment` — alignment of the legend within its position.
  - `spacing?: number` — spacing between the plot and the legend.
  - `content?: VirtualNode` — a custom legend view that replaces the auto-generated one.

## Use Cases

- Hiding a legend that is redundant with axis labels.
- Moving the legend to a position that fits your layout.
- Providing a fully custom legend view.



---
url: /guide/Changelog/3.1.0/Chart: legend control/index_example.md
---

# Example

```tsx
import { BarChart, BarChartProps, Chart, List, Navigation, NavigationStack, Picker, Script, Section, Text, useMemo, useState, Visibility, VStack, } from "scripting"

const data = [
  { color: "Green", type: "Cube", count: 2 },
  { color: "Green", type: "Sphere", count: 0 },
  { color: "Green", type: "Pyramid", count: 1 },
  { color: "Purple", type: "Cube", count: 1 },
  { color: "Purple", type: "Sphere", count: 1 },
  { color: "Purple", type: "Pyramid", count: 1 },
  { color: "Pink", type: "Cube", count: 1 },
  { color: "Pink", type: "Sphere", count: 2 },
  { color: "Pink", type: "Pyramid", count: 0 },
]

// 几种 chartLegend 形态:Visibility 字符串 + 自定义位置对象。
const legendModes = {
  automatic: "automatic" as Visibility,
  visible: "visible" as Visibility,
  hidden: "hidden" as Visibility,
  "bottom (custom)": { position: "bottom", spacing: 8 } as const,
}

type LegendModeKey = keyof typeof legendModes

function Example() {
  const [mode, setMode] = useState<LegendModeKey>("automatic")

  const marks = useMemo(() => {
    return data.map(item => ({
      label: item.type,
      value: item.count,
      positionBy: {
        value: item.color,
        axis: "horizontal",
      },
      foregroundStyleBy: item.color,
      cornerRadius: 8,
    }) as BarChartProps["marks"][0])
  }, [])

  return <NavigationStack>
    <List
      navigationTitle={"chartLegend"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        footer={
          <Text>
            "visible" / "automatic" keep the auto-generated legend; "hidden" removes it.
            The last option uses the object form to move the legend to the bottom.
          </Text>
        }
      >
        <Picker
          title={"Legend"}
          value={mode}
          onChanged={value => setMode(value as LegendModeKey)}
          pickerStyle={"segmented"}
        >
          {Object.keys(legendModes).map(key =>
            <Text key={key} tag={key}>{key}</Text>
          )}
        </Picker>
      </Section>

      <VStack frame={{ height: 360 }}>
        <Chart chartLegend={legendModes[mode]}>
          <BarChart marks={marks} />
        </Chart>
      </VStack>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/Chart: scroll target behavior/index.md
---

# 

***

title: Chart: scroll target behavior
description: chartScrollTargetBehavior(.valueAligned) snaps chart scroll deceleration to data boundaries. Pick unit step for numeric axes or matching DateComponents for date axes; majorAlignment controls the secondary 'page' snap.

***

`chartScrollTargetBehavior` controls where a chart's scroll _parks_ when the user lifts a finger after a swipe. Without it, scrolling a chart with `chartScrollableAxes` feels free-form — release the gesture mid-scroll and the leading edge can sit on any pixel. With it, scroll deceleration always lands on a meaningful data boundary (a day, a week, an integer index, ...).

Mirrors SwiftUI Charts' `chartScrollTargetBehavior(.valueAligned(...))`. Only the `valueAligned` form is bridged — there's no `paging` shortcut on Chart in SwiftUI either; what people usually mean by "paging" is `valueAligned(... majorAlignment: .page)`.

***

## API

```ts
chartScrollTargetBehavior?: ChartScrollTargetBehavior

type ChartScrollTargetBehavior = {
  unit?: number           // numeric axis: snap step
  matching?: DateComponents // date axis: snap step
  majorAlignment?: 'page' | 'unit' | { unit: number } | { matching: DateComponents }
}
```

- **`unit` / `matching` are mutually exclusive.** Pick `unit` for a numeric x axis, `matching` for a date x axis. Mixing both is not supported.
- **`matching` expects a `DateComponents` instance** (the global `new DateComponents({...})` exposed by the bridge — same class used for notifications/triggers). Pass `{ day: 1 }` for "snap by day", `{ day: 7 }` for "snap by week", `{ month: 1 }` for "snap by month", etc.
- **`majorAlignment` is the secondary "page" snap.** SwiftUI Charts uses it to decide where larger paging boundaries sit (e.g. snap by day, but page by month — releasing a longer swipe always parks at month edges).
  - `'page'` — major boundaries at viewport-page edges.
  - `'unit'` — no separate major alignment; reuses the primary step. (This is the SDK default; passing `'unit'` is the same as omitting `majorAlignment`.)
  - `{ unit: N }` — major boundaries every N numeric units (only valid when the primary step is `unit`).
  - `{ matching: DateComponents }` — major boundaries on those calendar boundaries (only valid when the primary step is `matching`).

> The bridge silently drops a cross-form `majorAlignment` (e.g. `{ unit: 7 }` paired with a `matching: ...` primary), since SwiftUI Charts' `MajorValueAlignment<Value>` is statically typed.

***

## Required pairings

`chartScrollTargetBehavior` does nothing on its own. Pair it with:

- **`chartScrollableAxes`** — turns scrolling on. Without it the chart just renders the full domain at once; there's nothing to snap.
- **`chartXVisibleDomain`** (or `chartYVisibleDomain` for vertical) — fixes the visible window's size in data units. Determines what counts as a "page" for `majorAlignment: 'page'`.

```tsx
<Chart
  chartScrollableAxes={"horizontal"}
  chartXVisibleDomain={86400 * 14}     // 14 days visible
  chartScrollTargetBehavior={{
    matching: new DateComponents({ day: 1 }),
    majorAlignment: { matching: new DateComponents({ month: 1 }) },
  }}
>
  ...
</Chart>
```

***

## Recipes

```tsx
// Date axis, snap daily, page by month
chartScrollTargetBehavior={{
  matching: new DateComponents({ day: 1 }),
  majorAlignment: { matching: new DateComponents({ month: 1 }) },
}}

// Date axis, snap weekly, page by viewport
chartScrollTargetBehavior={{
  matching: new DateComponents({ day: 7 }),
  majorAlignment: 'page',
}}

// Numeric axis, snap to integer index, page by viewport
chartScrollTargetBehavior={{
  unit: 1,
  majorAlignment: 'page',
}}

// Date axis, just snap by day, no major alignment override (SDK default)
chartScrollTargetBehavior={{
  matching: new DateComponents({ day: 1 }),
}}
```

***

## Pitfalls

- **Categorical (String) axes are not supported.** SwiftUI Charts' `ValueAligned` requires `Plottable + Numeric` (numeric axes) or `Date` (date axes). On a String x axis the modifier silently does nothing. To get a numeric x axis with `BarChart` / `LineChart` you need a `Date` label; for pure numeric x, use `PointChart` (whose marks are `{ x: number, y: number }`).
- **`unit` is in _data units_, not pixels.** For a Double axis, `unit: 1` means "snap every 1 unit on the chart's data domain". For a date axis, you must use `matching` instead.
- **`majorAlignment` defaults to `'unit'` when omitted.** Pass `'page'` explicitly if you want page-level snapping.
- **`chartXVisibleDomain` must be set for paging to feel right.** Without an explicit visible domain, the SDK picks one and your "page" boundaries will land in unexpected places.
- **Set `unit: 'day'` (etc.) on each mark for date-axis charts.** That's a property on the _mark itself_ (`ChartMarkProps.unit`), unrelated to `chartScrollTargetBehavior`. Without it Charts logs `Falling back to a fixed dimension size for a mark. Consider adding unit to the data...` and bars/lines render at a fixed pixel width that may not match the date stride. Match the `unit` on marks to the smallest sensible granularity of your data (typically `'day'` for daily data, `'hour'` for hourly, etc.).



---
url: /guide/Changelog/3.1.0/Chart: scroll target behavior/index_example.md
---

# Example

```tsx
import { BarChart, Chart, LineChart, Navigation, NavigationStack, PointChart, Script, ScrollView, Text, VStack } from "scripting"

// 60 天的"日访问量"假数据，用于演示 date 轴按日 stop / 按月 major 对齐。
const dailyData: { date: Date; visits: number }[] = (() => {
  const arr: { date: Date; visits: number }[] = []
  const start = new Date(2026, 0, 1) // 2026-01-01
  for (let i = 0; i < 60; i++) {
    const d = new Date(start.getTime() + i * 86400_000)
    // 简单合成的波动 + 偶尔尖峰
    const base = 200 + Math.round(Math.sin(i / 4) * 60)
    const spike = i % 9 === 0 ? 120 : 0
    arr.push({ date: d, visits: base + spike })
  }
  return arr
})()

// 60 个连续 index 的"评分"假数据，演示 numeric 轴按 unit=1 stop / page 主对齐。
const numericData: { x: number; y: number }[] = Array.from({ length: 60 }, (_, i) => ({
  x: i,
  y: 50 + Math.round(Math.cos(i / 3) * 25 + (i % 7 === 0 ? 18 : 0)),
}))

function Example() {
  return <NavigationStack>
    <ScrollView>
      <VStack
        navigationTitle={"Chart Scroll Target Behavior"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={28}
        padding
      >

        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          chartScrollTargetBehavior tells SwiftUI Charts where to "park" the scroll deceleration.
          Without it, scrolling a chart with chartScrollableAxes feels free-form; with it, releasing
          a swipe lands on a meaningful data boundary (a day, a month, an integer index).
          {"\n\n"}
          Pair it with chartScrollableAxes (otherwise the chart isn't scrollable, and snapping has
          nothing to act on) and chartXVisibleDomain (controls how much of the data is visible at
          once — also determines what counts as a "page").
        </Text>

        {/* 1. 日期轴：按日 stop，按月 major 对齐 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. Date axis — daily stops, monthly major</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            60 days of synthetic visit data. Swipe horizontally; release and the visible window
            should snap so the leading edge sits on a day boundary, with month edges acting as the
            larger "page" alignment.
          </Text>
          <Chart
            frame={{ height: 220 }}
            chartScrollableAxes={"horizontal"}
            chartXVisibleDomain={86400 * 14}
            chartScrollTargetBehavior={{
              matching: new DateComponents({ day: 1 }),
              majorAlignment: { matching: new DateComponents({ month: 1 }) },
            }}
            chartXAxis={{
              valueLabel: { format: "date" },
            }}
          >
            <LineChart
              marks={dailyData.map(d => ({
                label: d.date,
                value: d.visits,
                // unit: "day" 告诉 Charts 每个 mark 在 X 轴上占多大 —— 否则 SDK 会回落到固定像素宽度
                // 并 log "Falling back to a fixed dimension size for a mark"。
                unit: "day",
                interpolationMethod: "monotone",
                foregroundStyle: "blue",
              }))}
            />
          </Chart>
        </VStack>

        {/* 2. 日期轴：按周 stop（page 主对齐） */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Date axis — weekly stops, page major</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Same data, but stops snap on weekly boundaries (every 7 days) and the major alignment is
            the visible page. Useful when you want exactly N visible weeks per "page".
          </Text>
          <Chart
            frame={{ height: 220 }}
            chartScrollableAxes={"horizontal"}
            chartXVisibleDomain={86400 * 21}
            chartScrollTargetBehavior={{
              matching: new DateComponents({ day: 7 }),
              majorAlignment: "page",
            }}
            chartXAxis={{
              valueLabel: { format: "date" },
            }}
          >
            <BarChart
              marks={dailyData.map(d => ({
                label: d.date,
                value: d.visits,
                unit: "day",
                foregroundStyle: "orange",
              }))}
            />
          </Chart>
        </VStack>

        {/* 3. 数值轴：按 1 unit stop，page 主对齐 —— 必须用 numeric x 的 mark（PointChart），
            BarChart 的 label 是 string/Date，会走 categorical 轴，chartScrollTargetBehavior 在
            categorical 轴上不生效（SDK 限制）。 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. Numeric axis — unit stops, page major</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Numeric x axis (0..59). Each scroll deceleration snaps so the leading edge lands on an
            integer; major alignment is the visible page (10 units wide). Note: this requires a
            numeric-x mark (PointChart), since BarChart's `label` field becomes a categorical String
            axis on which chartScrollTargetBehavior is silently no-op.
          </Text>
          <Chart
            frame={{ height: 220 }}
            chartScrollableAxes={"horizontal"}
            chartXVisibleDomain={10}
            chartScrollTargetBehavior={{
              unit: 1,
              majorAlignment: "page",
            }}
          >
            <PointChart
              marks={numericData.map(d => ({
                x: d.x,
                y: d.y,
                foregroundStyle: "green",
                symbolSize: 80,
              }))}
            />
          </Chart>
        </VStack>

      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/Custom Keyboard.md
---

# Custom Keyboard

The `CustomKeyboard` namespace provides a comprehensive API for building fully custom keyboard UIs in the Scripting app. It allows you to create JSX-based keyboards, insert or modify text, query input state, respond to user interaction, and control keyboard layout or navigation.

***

## 1. Environment & Setup

### Requirements

- You must define your keyboard interface in a file named `**keyboard.tsx**` inside your script project.
- The `CustomKeyboard` API is **only available in the keyboard extension environment**.
- It is **not available** in App scripts, Intents (`intent.tsx`), or Widgets (`widget.tsx`).
- You must enable the keyboard in iOS settings:

  ```
  Settings > General > Keyboard > Keyboards > Add New Keyboard > Scripting
  ```

  Then tap the **Scripting Keyboard** and enable **Allow Full Access** to unlock clipboard and network features.

***

## 2. Presentation

### `present(node: VirtualNode): void`

Renders your custom keyboard UI using the given JSX node. This function **must be called once** in `keyboard.tsx`.

```tsx
function MyKeyboard() {
  return <Text>Hello from keyboard</Text>
}

CustomKeyboard.present(<MyKeyboard />)
```

***

## 3. Text Input State

| Property           | Type             | Description                              |
| ------------------ | ---------------- | ---------------------------------------- |
| `textBeforeCursor` | `string \| null` | Text before the cursor                   |
| `textAfterCursor`  | `string \| null` | Text after the cursor                    |
| `selectedText`     | `string \| null` | Currently selected text                  |
| `allText`          | `string`         | Currently entered text                   |
| `hasText`          | `boolean`        | Whether the text input contains any text |

***

## 4. Input Traits

### `useTraits(): TextInputTraits`

Hook to retrieve the current input traits (e.g., keyboard type, return key style). It automatically updates when `textDidChange` or `selectionDidChange` events occur.

### `traits: TextInputTraits`

A snapshot of the traits at the last change. Prefer `useTraits()` in JSX components for reactivity.

#### Example fields:

- `keyboardType`: `'default'`, `'numberPad'`, `'emailAddress'`...
- `returnKeyType`: `'go'`, `'search'`, `'done'`...
- `autocapitalizationType`: `'none'`, `'sentences'`, etc.
- `textContentType`: semantic input hints like `'username'`, `'oneTimeCode'`, etc.
- `keyboardAppearance`: `'light'`, `'dark'`, etc.

***

## 5. Text Manipulation

### `insertText(text: string): void`

Insert text at the current cursor position.

### `deleteBackward(): void`

Delete one character before the cursor.

### `moveCursor(offset: number): void`

Move the cursor by a number of characters. Negative = left; Positive = right.

### `setMarkedText(text, location, length): void`

Mark a portion of inserted text (used in composition scenarios like Pinyin input).

### `unmarkText(): void`

Clear any currently marked text.

***

## 6. Keyboard Behavior Control

### `dismiss(): void`

Dismiss the keyboard view.

### `nextKeyboard(): void`

Switch to the next system keyboard.

### `requestHeight(height: number): void`

Request a new keyboard height in points. Recommended range is **216–360pt**.

### `setHasDictationKey(value: boolean): void`

Control whether the dictation (microphone) key is shown.

### `setToolbarVisible(visible: boolean): void`

Show or hide the custom keyboard toolbar. Useful for debugging.

***

## 7. Navigation

### `allScripts: KeyboardScriptInfo[]`

Lists all scripts that can run in the custom keyboard extension.

```ts
const scripts = CustomKeyboard.allScripts
```

Each item contains:

| Property        | Type     | Description                 |
| --------------- | -------- | --------------------------- |
| `name`          | `string` | The script's stable name    |
| `localizedName` | `string` | The localized display name  |
| `icon`          | `string` | The script's SF Symbol name |
| `color`         | `string` | The script color name       |

### `switchToScript(scriptName: string, queryParameters?: Record<string, string>): Promise<void>`

Dismisses the current keyboard script and runs another keyboard script by name.
The optional `queryParameters` object is exposed to the target script as `Script.queryParameters`.

```ts
await CustomKeyboard.switchToScript("Rime Pinyin DEMO", {
  source: Script.name,
  mode: "symbols",
})
```

### `nextScript(queryParameters?: Record<string, string>): Promise<void>`

Dismisses the current keyboard script and runs the next available keyboard script.
The optional `queryParameters` object is exposed to the target script as `Script.queryParameters`.

```ts
await CustomKeyboard.nextScript({
  source: Script.name,
})
```

### `dismissToHome(): void`

Dismisses the currently active keyboard script and returns to the **Scripting keyboard home screen** (script list). Useful for letting users choose another script.

```ts
CustomKeyboard.dismissToHome()
```

***

## 8. User Feedback

### `playInputClick(): void`

Play the standard system keyboard click sound. Useful when simulating real key taps.

```ts
CustomKeyboard.playInputClick()
```

***

## 9. Event Listeners

### `addListener(event, callback): void`

Register a listener for keyboard or text input changes.

| Event                 | Callback Signature                  | Description                     |
| --------------------- | ----------------------------------- | ------------------------------- |
| `textWillChange`      | `() => void`                        | Before text changes             |
| `textDidChange`       | `(traits: TextInputTraits) => void` | After text changes              |
| `selectionWillChange` | `() => void`                        | Before cursor/selection changes |
| `selectionDidChange`  | `(traits: TextInputTraits) => void` | After cursor/selection changes  |

### `removeListener(event, callback): void`

Remove a specific listener.

### `removeAllListeners(event): void`

Remove all listeners for a given event type.

***

## 10. Full Example

```tsx
function MyKeyboard() {
  const traits = CustomKeyboard.useTraits()

  const insert = async (text: string) => {
    CustomKeyboard.playInputClick()
    CustomKeyboard.insertText(text)
  }

  return (
    <VStack spacing={12}>
      <Text>Input type: {traits.keyboardType}</Text>
      <HStack spacing={10}>
        <Button title="你" action={() => insert("你")} />
        <Button title="好" action={() => insert("好")} />
        <Button title="←" action={() => CustomKeyboard.deleteBackward()} />
        <Button title="Back" action={() => CustomKeyboard.dismissToHome()} />
      </HStack>
    </VStack>
  )
}

CustomKeyboard.present(<MyKeyboard />)
```

***

## 11. Best Practices

- **Call `present()` only once** in your `keyboard.tsx` file.
- Use `requestHeight()` to ensure appropriate layout on different screen sizes.
- Prefer `useTraits()` for reactive input context access in JSX.
- Use `dismissToHome()` instead of `dismiss()` if you want to return to the script list.
- Call `playInputClick()` when simulating key taps for user feedback.
- Always check for `hasText` before calling `deleteBackward()`.



---
url: /guide/Changelog/3.1.0/Device (Python).md
---

# 

***

title: Device (Python)
description: Python-side read-only device info: model, system version, screen, battery, orientation, and locale.

***

The `scripting` Python package exposes `Device` with read-only properties describing the host device — model, system version, screen, locale, battery, and orientation. Each property fires a single RPC call to fetch the current value; cache the result yourself if you read the same property in a tight loop.

```python
import scripting; Device = scripting.Device

print(Device.model, Device.systemName, Device.systemVersion)
```

***

## Properties

### Hardware identity

| Name                    | Type | Description                                    |
| ----------------------- | ---- | ---------------------------------------------- |
| `Device.model`          | str  | E.g. `"iPhone"`, `"iPad"`.                     |
| `Device.localizedModel` | str  | Localized form of `model`.                     |
| `Device.systemName`     | str  | E.g. `"iOS"`, `"iPadOS"`.                      |
| `Device.systemVersion`  | str  | E.g. `"17.0"`.                                 |
| `Device.isiPhone`       | bool | The current device is an iPhone.               |
| `Device.isiPad`         | bool | The current device is an iPad.                 |
| `Device.isiOSAppOnMac`  | bool | Running as an iOS app on Mac (Catalyst-style). |

### Screen

| Name                 | Type | Description                                          |
| -------------------- | ---- | ---------------------------------------------------- |
| `Device.screen`      | dict | `{"width": float, "height": float, "scale": float}`. |
| `Device.colorScheme` | str  | `"light"` or `"dark"`.                               |

### Battery & sensors

| Name                    | Type  | Description                                         |
| ----------------------- | ----- | --------------------------------------------------- |
| `Device.batteryState`   | str   | `"full"`, `"charging"`, `"unplugged"`, `"unknown"`. |
| `Device.batteryLevel`   | float | `0.0`-`1.0`, `-1.0` if monitoring is unavailable.   |
| `Device.proximityState` | bool  | Proximity sensor close to user.                     |

### Orientation

| Name                 | Type | Description                                                                                                         |
| -------------------- | ---- | ------------------------------------------------------------------------------------------------------------------- |
| `Device.orientation` | str  | `"portrait"`, `"portraitUpsideDown"`, `"landscapeLeft"`, `"landscapeRight"`, `"faceUp"`, `"faceDown"`, `"unknown"`. |
| `Device.isLandscape` | bool | Device is in landscape orientation.                                                                                 |
| `Device.isPortrait`  | bool | Device is in portrait orientation.                                                                                  |
| `Device.isFlat`      | bool | Device is lying flat.                                                                                               |

### Locale

| Name                        | Type       | Description                                                   |
| --------------------------- | ---------- | ------------------------------------------------------------- |
| `Device.systemLocale`       | str        | Current locale identifier, e.g. `"en_US"`.                    |
| `Device.preferredLanguages` | list\[str] | User-preferred language tags, e.g. `["en-US", "zh-Hans-CN"]`. |
| `Device.systemLanguageTag`  | str        | Same shape as items in `preferredLanguages`.                  |
| `Device.systemLanguageCode` | str        | E.g. `"en"`.                                                  |
| `Device.systemCountryCode`  | str        | E.g. `"US"`.                                                  |
| `Device.systemScriptCode`   | str        | E.g. `"Hans"` (empty for languages without explicit script).  |

***

## Examples

### Detect iPad / portrait layout

```python
import scripting; Device = scripting.Device

if Device.isiPad and Device.isLandscape:
    print("Render the wide layout")
else:
    print("Render the narrow layout")
```

### Battery status

```python
import scripting; Device = scripting.Device

state = Device.batteryState
level = Device.batteryLevel
print(f"Battery: {int(level * 100)}% ({state})")
```

### Localized greeting

```python
import scripting; Device = scripting.Device

primary = (Device.preferredLanguages or ["en"])[0]
greeting = "你好" if primary.startswith("zh") else "Hello"
print(greeting)
```



---
url: /guide/Changelog/3.1.0/Dialog (Python).md
---

# 

***

title: Dialog (Python)
description: Python-side synchronous Dialog API: alert / confirm / prompt / actionSheet wrappers around the host's modal UI.

***

The `scripting` Python package exposes `Dialog`, mirroring the JS-side `Dialog` namespace. It provides synchronous wrappers around the host's modal UI — alerts, confirms, prompts and action sheets. Each call blocks until the user dismisses the dialog and returns the result.

```python
import scripting; Dialog = scripting.Dialog
```

The dialog is displayed on top of the currently visible view controller, so this only makes sense when the host app is in the foreground (e.g. when the user explicitly ran the script from the app).

***

## Methods

### `Dialog.alert(message, title=None, buttonLabel=None) -> None`

Show a single-button alert. Returns when the user taps the dismiss button.

```python
import scripting; Dialog = scripting.Dialog
Dialog.alert("Operation completed", title="Done")
```

| Param       | Type | Required | Description                                              |
| ----------- | ---- | -------- | -------------------------------------------------------- |
| message     | str  | Yes      | Body text of the alert.                                  |
| title       | str  | No       | Optional title above the message.                        |
| buttonLabel | str  | No       | Custom dismiss button label. Defaults to localized `OK`. |

### `Dialog.confirm(message, title=None, cancelLabel=None, confirmLabel=None) -> bool`

Show a two-button confirm dialog. Returns `True` when the user taps the confirm button, `False` for cancel.

```python
import scripting; Dialog = scripting.Dialog

if Dialog.confirm("Delete the file?", title="Confirm",
                  cancelLabel="Keep", confirmLabel="Delete"):
    delete_file()
```

| Param        | Type | Required | Description                  |
| ------------ | ---- | -------- | ---------------------------- |
| message      | str  | Yes      | Body text.                   |
| title        | str  | No       | Title.                       |
| cancelLabel  | str  | No       | Custom cancel button label.  |
| confirmLabel | str  | No       | Custom confirm button label. |

### `Dialog.prompt(title=None, message=None, defaultValue=None, placeholder=None, obscureText=False, cancelLabel=None, confirmLabel=None) -> str | None`

Show a text-input prompt. Returns the entered string, or `None` if the user cancelled.

```python
import scripting; Dialog = scripting.Dialog

name = Dialog.prompt(title="Your name", placeholder="Alice")
if name is not None:
    print(f"Hello, {name}")
```

| Param        | Type | Required | Description                                                         |
| ------------ | ---- | -------- | ------------------------------------------------------------------- |
| title        | str  | No       | Title.                                                              |
| message      | str  | No       | Optional supporting text below the title.                           |
| defaultValue | str  | No       | Pre-filled text in the input.                                       |
| placeholder  | str  | No       | Placeholder shown when the input is empty.                          |
| obscureText  | bool | No       | When `True`, masks the input (password style). Defaults to `False`. |
| cancelLabel  | str  | No       | Custom cancel button label.                                         |
| confirmLabel | str  | No       | Custom confirm button label.                                        |

### `Dialog.actionSheet(title, actions, message=None, cancelButton=True) -> int | None`

Show an action sheet with multiple choices. Returns the index of the chosen action (0-based), or `None` if cancelled.

```python
import scripting; Dialog = scripting.Dialog

idx = Dialog.actionSheet(
    title="Choose an export format",
    actions=[
        {"label": "JSON"},
        {"label": "CSV"},
        {"label": "Delete original", "destructive": True},
    ],
)
if idx == 0:
    export_json()
elif idx == 1:
    export_csv()
elif idx == 2:
    delete_original()
```

| Param        | Type        | Required | Description                                                                                   |
| ------------ | ----------- | -------- | --------------------------------------------------------------------------------------------- |
| title        | str         | Yes      | Sheet title.                                                                                  |
| actions      | list\[dict] | Yes      | List of `{"label": str, "destructive": bool?}`. `destructive=True` renders the action in red. |
| message      | str         | No       | Optional supporting text.                                                                     |
| cancelButton | bool        | No       | Show a cancel button (defaults to `True`).                                                    |



---
url: /guide/Changelog/3.1.0/Github API.md
---

# Github API

Provides authenticated access to the GitHub REST API.

Prerequisites:

- A Personal Access Token must be configured in `Settings → GitHub`
- Each script or skill maintains its own permission state per capability
- The first call to a capability may trigger an authorization prompt
- Tokens are securely stored in the iCloud-synced Keychain and are not accessible from JavaScript

Limitations:

- Extension environments (Widget / Keyboard / Notification) cannot present authorization UI
- If permissions have not been granted in the main app, calls in those environments will fail

***

## Permission Model

### Permission

Defines the capabilities a script or skill can request:

```ts
type Permission =
  | "read_profile"
  | "read_repos"
  | "read_contents"
  | "write_contents"
  | "read_issues"
  | "write_issues"
  | "read_pull_requests"
  | "write_pull_requests"
  | "read_actions"
  | "write_actions"
  | "search_repositories"
  | "search_issues"
  | "search_code"
```

***

### Permission Status

```ts
"allowed" | "denied" | "unset"
```

- `allowed`: granted
- `denied`: rejected
- `unset`: not requested yet

***

## Availability

### Availability Type

```ts
type Availability = {
  available: boolean
  proRequired: boolean
  tokenConfigured: boolean
}
```

***

### isAvailable()

```ts
const ok = GitHub.isAvailable()

if (!ok) {
  console.log("GitHub API is not available. Check token configuration.")
}
```

Notes:

- Checks whether a token is configured
- Does NOT check permission state

***

### getAvailability()

```ts
const availability = await GitHub.getAvailability()

console.log(availability.available)
console.log(availability.tokenConfigured)
```

***

## Permission Management

### getPermissionStatus()

```ts
const status = await GitHub.getPermissionStatus({
  permission: "read_repos"
})

console.log(status) // allowed / denied / unset
```

***

### requestPermissions()

```ts
const granted = await GitHub.requestPermissions([
  "read_repos",
  "read_contents"
])

console.log("Granted:", granted)
```

Notes:

- Requests permissions in batch
- Returns the final set of allowed permissions

***

## Common Types

### SortDirection

```ts
type SortDirection = "asc" | "desc"
```

***

### ArchiveFormat

```ts
type ArchiveFormat = "zipball" | "tarball"
```

***

### CommitterIdentity

```ts
type CommitterIdentity = {
  name: string
  email: string
  date?: string
}
```

***

## User & Repository

### getViewer()

```ts
const user = await GitHub.getViewer()
console.log(user.login)
```

***

### getRepo()

```ts
const repo = await GitHub.getRepo({
  owner: "facebook",
  repo: "react"
})

console.log(repo.full_name)
```

***

### listRepos()

```ts
const repos = await GitHub.listRepos({
  sort: "updated",
  perPage: 10
})

repos.forEach(r => {
  console.log(r.full_name)
})
```

***

### listUserRepos()

```ts
const repos = await GitHub.listUserRepos({
  username: "torvalds",
  perPage: 5
})

console.log(repos.map(r => r.name))
```

***

## Branches & Commits

### listBranches()

```ts
const branches = await GitHub.listBranches({
  owner: "apple",
  repo: "swift"
})

console.log(branches.map(b => b.name))
```

***

### listCommits()

```ts
const commits = await GitHub.listCommits({
  owner: "apple",
  repo: "swift",
  perPage: 5
})

commits.forEach(c => {
  console.log(c.sha)
})
```

***

### compareCommits()

```ts
const result = await GitHub.compareCommits({
  owner: "apple",
  repo: "swift",
  base: "main",
  head: "feature-branch"
})

console.log(result.status)
```

***

## File Contents

### getContent()

```ts
const content = await GitHub.getContent({
  owner: "octocat",
  repo: "Hello-World",
  path: "README.md"
})

console.log(content)
```

***

### getTextContent()

```ts
const file = await GitHub.getTextContent({
  owner: "octocat",
  repo: "Hello-World",
  path: "README.md"
})

console.log(file.text)
```

***

### getRawContent()

```ts
const data = await GitHub.getRawContent({
  owner: "octocat",
  repo: "Hello-World",
  path: "image.png"
})

// binary data
```

***

### putContent()

Create file:

```ts
await GitHub.putContent({
  owner: "yourname",
  repo: "test-repo",
  path: "hello.txt",
  message: "add file",
  content: "Hello from Scripting"
})
```

Update file:

```ts
const file = await GitHub.getContent({
  owner: "yourname",
  repo: "test-repo",
  path: "hello.txt"
})

await GitHub.putContent({
  owner: "yourname",
  repo: "test-repo",
  path: "hello.txt",
  message: "update file",
  content: "Updated content",
  sha: file.sha
})
```

***

### deleteContent()

```ts
await GitHub.deleteContent({
  owner: "yourname",
  repo: "test-repo",
  path: "hello.txt",
  message: "delete file",
  sha: "file_sha"
})
```

***

### downloadArchive()

```ts
const archive = await GitHub.downloadArchive({
  owner: "facebook",
  repo: "react"
})
```

***

## Issues

### listIssues()

```ts
const issues = await GitHub.listIssues({
  owner: "facebook",
  repo: "react",
  state: "open"
})

console.log(issues.length)
```

***

### createIssue()

```ts
const issue = await GitHub.createIssue({
  owner: "yourname",
  repo: "test-repo",
  title: "Bug report",
  body: "Something is wrong"
})

console.log(issue.number)
```

***

### createIssueComment()

```ts
await GitHub.createIssueComment({
  owner: "yourname",
  repo: "test-repo",
  issueNumber: 1,
  body: "Thanks for reporting"
})
```

***

## Pull Requests

### listPullRequests()

```ts
const prs = await GitHub.listPullRequests({
  owner: "facebook",
  repo: "react",
  state: "open"
})

console.log(prs.length)
```

***

### createPullRequest()

```ts
const pr = await GitHub.createPullRequest({
  owner: "yourname",
  repo: "test-repo",
  title: "Add feature",
  head: "feature-branch",
  base: "main",
  body: "Description"
})

console.log(pr.html_url)
```

***

## GitHub Actions

### listWorkflows()

```ts
const workflows = await GitHub.listWorkflows({
  owner: "yourname",
  repo: "test-repo"
})

console.log(workflows)
```

***

### dispatchWorkflow()

```ts
await GitHub.dispatchWorkflow({
  owner: "yourname",
  repo: "test-repo",
  workflow: "ci.yml",
  ref: "main",
  inputs: {
    env: "prod"
  }
})
```

***

## Search APIs

### searchRepositories()

```ts
const result = await GitHub.searchRepositories({
  query: "react stars:>100000",
  sort: "stars"
})

console.log(result.items.length)
```

***

### searchIssues()

```ts
const result = await GitHub.searchIssues({
  query: "repo:facebook/react bug"
})

console.log(result.items.length)
```

***

### searchCode()

```ts
const result = await GitHub.searchCode({
  query: "fetch repo:facebook/react"
})

console.log(result.items.length)
```

***

## Releases

### getLatestRelease()

```ts
const release = await GitHub.getLatestRelease({
  owner: "facebook",
  repo: "react"
})

console.log(release.tag_name)
```

***

### downloadReleaseAsset()

```ts
const data = await GitHub.downloadReleaseAsset({
  owner: "owner",
  repo: "repo",
  assetId: 123456
})
```

***

## Best Practices

- Call `requestPermissions` at startup to avoid fragmented prompts
- Use `getPermissionStatus` to prevent redundant requests
- Use:

  - `getRawContent`
  - `getBlob`
    for large or binary files



---
url: /guide/Changelog/3.1.0/Haptics/index.md
---

# Haptics

`Haptics` exposes Core Haptics for scripts that need custom tactile patterns beyond the lightweight `HapticFeedback` helpers.

Use `Haptics.transient()` or `Haptics.continuous()` for simple one-shot effects. Use `HapticEngine`, `HapticPattern`, `HapticEvent`, and parameter objects when you need precise timing, envelopes, dynamic parameters, AHAP data, or reusable pattern players.

```ts
await Haptics.transient(1.0, 0.7)
await Haptics.continuous(0.4, 0.6, 0.35)
```

## Pattern Playback

```ts
const engine = new HapticEngine()

const pattern = new HapticPattern([
  new HapticEvent("hapticTransient", [
    new HapticEventParameter("hapticIntensity", 1.0),
    new HapticEventParameter("hapticSharpness", 0.8),
  ], 0),
  new HapticEvent("hapticContinuous", [
    new HapticEventParameter("hapticIntensity", 0.45),
    new HapticEventParameter("hapticSharpness", 0.25),
  ], 0.08, 0.35),
])

engine.start()
const player = engine.makePlayer(pattern)
player.start()
```

## Engine

#### `new HapticEngine(audioSession?)`

Creates a Core Haptics engine. Omit `audioSession` for the default engine, pass `null` to let Core Haptics create its own audio session, or pass `SharedAudioSession` to share the app audio session.

#### Static Capabilities

```ts
HapticEngine.supportsHaptics
HapticEngine.supportsAudio
Haptics.supportsHaptics
Haptics.supportsAudio
```

#### Properties

```ts
engine.currentTime
engine.isRunning
engine.playsHapticsOnly
engine.playsAudioOnly
engine.isMutedForAudio
engine.isMutedForHaptics
engine.autoShutdownEnabled
engine.onStopped = reason => {}
engine.onReset = () => {}
```

#### Methods

```ts
engine.start()
await engine.startAsync()
await engine.stop()
engine.makePlayer(pattern)
engine.makeAdvancedPlayer(pattern)
engine.playPatternFromFile(filePath)
engine.playPatternFromData(data)
engine.registerAudioResource(filePath, options?)
engine.unregisterAudioResource(resourceID)
engine.dispose()
```

Synchronous methods throw JavaScript `Error` objects when Core Haptics reports a failure. Promise methods reject with `Error`.

## Events and Parameters

```ts
new HapticEventParameter(parameterID, value)
new HapticDynamicParameter(parameterID, value, relativeTime)
new HapticParameterCurveControlPoint(relativeTime, value)
new HapticParameterCurve(parameterID, controlPoints, relativeTime)
new HapticEvent(eventType, parameters, relativeTime, duration?)
new HapticPattern(events, parametersOrCurves?)
```

Common event types:

- `"hapticTransient"`
- `"hapticContinuous"`
- `"audioContinuous"`
- `"audioCustom"`

Common event parameters:

- `"hapticIntensity"`
- `"hapticSharpness"`
- `"attackTime"`
- `"decayTime"`
- `"releaseTime"`
- `"sustained"`

## AHAP Data

```ts
const data = FileManager.readAsData("/path/to/pattern.ahap")
const pattern = HapticPattern.fromData(data)

const engine = new HapticEngine()
engine.start()
engine.playPatternFromData(data)
```

`HapticPattern.fromDictionary(dictionary)` accepts an AHAP-style dictionary, and `pattern.exportDictionary()` returns a dictionary representation of a pattern.



---
url: /guide/Changelog/3.1.0/Haptics/index_example.md
---

# Example

```tsx
import {
  Button,
  List,
  Navigation,
  NavigationStack,
  Script,
  Section,
  Text,
  useEffect,
  useState,
  VStack,
} from "scripting"

let activeEngine: HapticEngine | null = null

function wait(milliseconds: number): Promise<void> {
  return new Promise(resolve => {
    setTimeout(resolve, milliseconds)
  })
}

function logHeader(title: string) {
  console.clear()
  console.present()
  console.log(`Haptics demo: ${title}`)
}

async function runDemo(
  title: string,
  body: () => void | Promise<void>,
  setStatus: (status: string) => void
) {
  logHeader(title)
  setStatus(`Running: ${title}`)
  try {
    await body()
    setStatus(`Done: ${title}`)
    console.log("Done")
  } catch (error) {
    const message = String(error)
    setStatus(`Failed: ${title}`)
    console.error(message)
    await Dialog.alert({
      title,
      message,
    })
  }
}

function disposeActiveEngine() {
  if (!activeEngine) {
    return
  }
  try {
    activeEngine.dispose()
  } catch (error) {
    console.error("dispose failed", String(error))
  }
  activeEngine = null
}

function useEngine(audioSession?: typeof SharedAudioSession | null): HapticEngine {
  disposeActiveEngine()
  const engine = new HapticEngine(audioSession)
  engine.onStopped = reason => {
    console.log("engine.onStopped", reason)
  }
  engine.onReset = () => {
    console.log("engine.onReset")
  }
  activeEngine = engine
  return engine
}

function makePulsePattern(): HapticPattern {
  return new HapticPattern([
    new HapticEvent("hapticTransient", [
      new HapticEventParameter("hapticIntensity", 1),
      new HapticEventParameter("hapticSharpness", 0.85),
    ], 0),
    new HapticEvent("hapticTransient", [
      new HapticEventParameter("hapticIntensity", 0.6),
      new HapticEventParameter("hapticSharpness", 0.4),
    ], 0.16),
    new HapticEvent("hapticContinuous", [
      new HapticEventParameter("hapticIntensity", 0.35),
      new HapticEventParameter("hapticSharpness", 0.25),
      new HapticEventParameter("attackTime", 0.02),
      new HapticEventParameter("releaseTime", 0.12),
    ], 0.32, 0.45),
  ])
}

function makeDynamicPattern(): HapticPattern {
  return new HapticPattern([
    new HapticEvent("hapticContinuous", [
      new HapticEventParameter("hapticIntensity", 0.35),
      new HapticEventParameter("hapticSharpness", 0.25),
    ], 0, 1.1),
  ], [
    new HapticDynamicParameter("hapticIntensityControl", 0.8, 0.2),
    new HapticParameterCurve("hapticSharpnessControl", [
      new HapticParameterCurveControlPoint(0, 0.1),
      new HapticParameterCurveControlPoint(0.35, 1),
      new HapticParameterCurveControlPoint(0.9, 0.2),
    ], 0),
  ])
}

function makeAHAPData(): Data {
  const exported = makePulsePattern().exportDictionary()
  const data = Data.fromRawString(JSON.stringify(exported))
  if (!data) {
    throw new Error("Failed to create AHAP Data.")
  }
  return data
}

function Example() {
  const dismiss = Navigation.useDismiss()
  const [status, setStatus] = useState("Ready")

  useEffect(() => {
    return () => {
      disposeActiveEngine()
    }
  }, [])

  return <NavigationStack>
    <List
      navigationTitle={"Haptics"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section header={<Text>Status</Text>}>
        <VStack alignment={"leading"}>
          <Text font={"headline"}>supportsHaptics</Text>
          <Text font={"caption"}>{String(Haptics.supportsHaptics)}</Text>
        </VStack>
        <VStack alignment={"leading"}>
          <Text font={"headline"}>supportsAudio</Text>
          <Text font={"caption"}>{String(Haptics.supportsAudio)}</Text>
        </VStack>
        <VStack alignment={"leading"}>
          <Text font={"headline"}>last run</Text>
          <Text font={"caption"}>{status}</Text>
        </VStack>
      </Section>

      <Section
        header={<Text>Convenience</Text>}
        footer={<Text>These helpers create and reuse an internal engine.</Text>}
      >
        <Button
          title={"Haptics.transient(1, 0.8)"}
          action={() => runDemo("Haptics.transient", async () => {
            await Haptics.transient(1, 0.8)
          }, setStatus)}
        />
        <Button
          title={"Haptics.continuous(0.45, 0.6, 0.25)"}
          action={() => runDemo("Haptics.continuous", async () => {
            await Haptics.continuous(0.45, 0.6, 0.25)
          }, setStatus)}
        />
      </Section>

      <Section
        header={<Text>Engine</Text>}
        footer={<Text>Tests the constructors, capability properties, start, stop, and dispose.</Text>}
      >
        <Button
          title={"new HapticEngine() start/stop"}
          action={() => runDemo("HapticEngine default", async () => {
            const engine = useEngine()
            console.log("HapticEngine.supportsHaptics", HapticEngine.supportsHaptics)
            console.log("HapticEngine.supportsAudio", HapticEngine.supportsAudio)
            engine.autoShutdownEnabled = true
            engine.start()
            console.log("isRunning after start", engine.isRunning)
            await engine.stop()
            console.log("isRunning after stop", engine.isRunning)
            disposeActiveEngine()
          }, setStatus)}
        />
        <Button
          title={"new HapticEngine(SharedAudioSession)"}
          action={() => runDemo("HapticEngine SharedAudioSession", async () => {
            const engine = useEngine(SharedAudioSession)
            await engine.startAsync()
            console.log("currentTime", engine.currentTime)
            await engine.stop()
            disposeActiveEngine()
          }, setStatus)}
        />
        <Button
          title={"new HapticEngine(null)"}
          action={() => runDemo("HapticEngine null audio session", async () => {
            const engine = useEngine(null)
            engine.start()
            await engine.stop()
            disposeActiveEngine()
          }, setStatus)}
        />
      </Section>

      <Section
        header={<Text>Pattern Player</Text>}
        footer={<Text>Builds events and parameters, then plays them through a reusable player.</Text>}
      >
        <Button
          title={"HapticEvent + HapticPattern + makePlayer"}
          action={() => runDemo("Pattern player", async () => {
            const engine = useEngine()
            const pattern = makePulsePattern()
            console.log("pattern.duration", pattern.duration)
            engine.start()
            const player = engine.makePlayer(pattern)
            player.start(0)
            await wait(1000)
            await engine.stop()
            disposeActiveEngine()
          }, setStatus)}
        />
        <Button
          title={"sendParameters + scheduleParameterCurve"}
          action={() => runDemo("Dynamic parameters", async () => {
            const engine = useEngine()
            const pattern = makeDynamicPattern()
            engine.start()
            const player = engine.makePlayer(pattern)
            player.start(0)
            player.sendParameters([
              new HapticDynamicParameter("hapticIntensityControl", 1, 0),
              new HapticDynamicParameter("hapticSharpnessControl", 0.8, 0),
            ], 0.18)
            player.scheduleParameterCurve(
              new HapticParameterCurve("hapticIntensityControl", [
                new HapticParameterCurveControlPoint(0, 0.2),
                new HapticParameterCurveControlPoint(0.4, 1),
                new HapticParameterCurveControlPoint(0.8, 0.1),
              ], 0),
              0.25
            )
            await wait(1500)
            await engine.stop()
            disposeActiveEngine()
          }, setStatus)}
        />
        <Button
          title={"makeAdvancedPlayer pause/resume/seek"}
          action={() => runDemo("Advanced player", async () => {
            const engine = useEngine()
            const pattern = new HapticPattern([
              new HapticEvent("hapticContinuous", [
                new HapticEventParameter("hapticIntensity", 0.5),
                new HapticEventParameter("hapticSharpness", 0.5),
              ], 0, 1.6),
            ])
            engine.start()
            const player = engine.makeAdvancedPlayer(pattern)
            player.completionHandler = error => {
              console.log("advanced completion", error ? String(error) : "ok")
            }
            player.playbackRate = 1
            player.start(0)
            await wait(350)
            player.pause(0)
            console.log("paused")
            await wait(250)
            player.seek(0.5)
            player.resume(0)
            console.log("resumed from offset 0.5")
            await wait(1200)
            await engine.stop()
            disposeActiveEngine()
          }, setStatus)}
        />
      </Section>

      <Section
        header={<Text>AHAP</Text>}
        footer={<Text>Uses exportDictionary, fromDictionary, fromData, fromFile, and playPatternFromData.</Text>}
      >
        <Button
          title={"exportDictionary + fromDictionary"}
          action={() => runDemo("AHAP dictionary", async () => {
            const engine = useEngine()
            const dictionary = makePulsePattern().exportDictionary()
            console.log(JSON.stringify(dictionary, null, 2))
            const pattern = HapticPattern.fromDictionary(dictionary)
            engine.start()
            engine.makePlayer(pattern).start(0)
            await wait(1000)
            await engine.stop()
            disposeActiveEngine()
          }, setStatus)}
        />
        <Button
          title={"fromData + playPatternFromData"}
          action={() => runDemo("AHAP Data", async () => {
            const engine = useEngine()
            const data = makeAHAPData()
            const pattern = HapticPattern.fromData(data)
            console.log("data.size", data.size)
            console.log("pattern.duration", pattern.duration)
            engine.start()
            engine.playPatternFromData(data)
            await wait(1000)
            await engine.stop()
            disposeActiveEngine()
          }, setStatus)}
        />
        <Button
          title={"fromFile"}
          action={() => runDemo("AHAP file", async () => {
            const path = `${FileManager.temporaryDirectory}/haptics-demo.ahap`
            const json = JSON.stringify(makePulsePattern().exportDictionary())
            FileManager.writeAsStringSync(path, json)
            const engine = useEngine()
            const pattern = HapticPattern.fromFile(path)
            console.log("file", path)
            console.log("pattern.duration", pattern.duration)
            engine.start()
            engine.makePlayer(pattern).start(0)
            await wait(1000)
            await engine.stop()
            disposeActiveEngine()
          }, setStatus)}
        />
      </Section>

      <Section
        header={<Text>Error Semantics</Text>}
        footer={<Text>Native throwing APIs should surface as JavaScript errors.</Text>}
      >
        <Button
          title={"Invalid event type throws"}
          action={() => runDemo("Invalid event type", async () => {
            try {
              new HapticEvent("badType" as HapticEventType, [], 0)
              throw new Error("Expected invalid event type to throw.")
            } catch (error) {
              console.log("Caught expected error:", String(error))
              await Dialog.alert({
                title: "Caught expected error",
                message: String(error),
              })
            }
          }, setStatus)}
        />
        <Button
          title={"Negative relativeTime throws"}
          action={() => runDemo("Negative relativeTime", async () => {
            try {
              new HapticDynamicParameter("hapticIntensityControl", 1, -0.1)
              throw new Error("Expected negative relativeTime to throw.")
            } catch (error) {
              console.log("Caught expected error:", String(error))
              await Dialog.alert({
                title: "Caught expected error",
                message: String(error),
              })
            }
          }, setStatus)}
        />
        <Button
          title={"Invalid AHAP Data throws"}
          action={() => runDemo("Invalid AHAP Data", async () => {
            const data = Data.fromRawString("{\"not\":\"ahap\"}")
            if (!data) {
              throw new Error("Failed to create invalid Data.")
            }
            try {
              HapticPattern.fromData(data)
              throw new Error("Expected invalid AHAP data to throw.")
            } catch (error) {
              console.log("Caught expected error:", String(error))
              await Dialog.alert({
                title: "Caught expected error",
                message: String(error),
              })
            }
          }, setStatus)}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  disposeActiveEngine()
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/ImageIO.md
---

# ImageIO

Low-level image container I/O: read EXIF / GPS / TIFF / IPTC metadata, and encode images to formats (and with embedded metadata) that `UIImage.toPNGData` / `toJPEGData` can't produce.

> **Why not just use `UIImage`?** A `UIImage` is a _decoded bitmap_ — by the time you have one, the original file's metadata (EXIF, GPS, ...) is already gone, and `toPNGData` / `toJPEGData` cannot write HEIC / TIFF / GIF. `ImageIO` works at the encoded-container level, so it can both read existing metadata and write it back.

```ts
// Read metadata
const meta = await ImageIO.readMetadata("/path/to/photo.jpg")
console.log(meta.pixelWidth, meta.pixelHeight)
console.log(meta.gps?.Latitude, meta.gps?.Longitude)

// Re-encode a UIImage to HEIC with GPS
await ImageIO.writeImage({
  image,                       // a UIImage
  to: "/path/to/out.heic",
  format: "heic",
  quality: 0.9,
  metadata: {
    gps: { Latitude: 37.33, LatitudeRef: "N", Longitude: 122.0, LongitudeRef: "W" },
  },
})
```

***

## `ImageIO.readMetadata(source)`

```ts
function readMetadata(source: string | Data): Promise<ImageMetadata>
```

Reads container-level metadata from a file path or `Data`. Rejects if the source can't be decoded as an image.

```ts
type ImageMetadata = {
  pixelWidth?: number
  pixelHeight?: number
  dpiWidth?: number
  dpiHeight?: number
  depth?: number
  colorModel?: string
  orientation?: number        // EXIF orientation 1–8
  hasAlpha?: boolean
  profileName?: string
  exif?: Record<string, any>  // CGImageProperties Exif keys, e.g. DateTimeOriginal
  gps?: Record<string, any>   // GPS keys, e.g. Latitude / Longitude / LatitudeRef
  tiff?: Record<string, any>
  iptc?: Record<string, any>
}
```

The well-known dictionaries (`exif` / `gps` / `tiff` / `iptc`) use Apple's CGImageProperties key names verbatim (`gps.Latitude`, `exif.DateTimeOriginal`, ...).

***

## `ImageIO.writeImage(options)`

```ts
function writeImage(options: ImageWriteOptions): Promise<void>
```

Encodes and writes an image to `to`. Provide **exactly one** of `image` or `source`:

| Field       | Type                                           | Notes                                                                                                                         |
| ----------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `image?`    | `UIImage`                                      | Re-encode from a decoded bitmap. The original file's metadata is **not** preserved — only the `metadata` you pass is written. |
| `source?`   | `string \| Data`                               | Copy from an original encoded image, **preserving its metadata**, then overlay the `metadata` you pass.                       |
| `to`        | `string`                                       | Output file path. An existing file is overwritten.                                                                            |
| `format?`   | `'jpeg' \| 'png' \| 'heic' \| 'tiff' \| 'gif'` | Required with `image`; defaults to the source's format with `source`.                                                         |
| `quality?`  | `number`                                       | Lossy compression 0..1 (jpeg / heic only).                                                                                    |
| `metadata?` | `ImageMetadata`                                | Merged on top of the source's metadata when using `source`.                                                                   |

### Tag a photo with GPS while keeping its EXIF

Use the `source` variant — re-encoding through a `UIImage` would drop the original EXIF:

```ts
await ImageIO.writeImage({
  source: "/path/to/original.jpg",   // keeps original EXIF / TIFF
  to: "/path/to/tagged.jpg",
  metadata: { gps: { Latitude: 10.0, LatitudeRef: "N" } },  // overlay GPS
})
```

***

## Caveats

- **`image` drops original metadata.** A `UIImage` is a decoded bitmap. To preserve a file's existing EXIF/GPS, use the `source` variant, not `image`.
- **`quality` only applies to jpeg / heic.** It's ignored for png / tiff / gif.
- **HEIC encoding** requires a device/simulator that supports the HEVC image encoder; on older simulators HEIC may fail — fall back to jpeg if `writeImage` rejects.
- **Key names are raw CGImageProperties keys.** When writing `exif` / `gps` / `tiff` / `iptc`, use Apple's key names (e.g. `Latitude`, `LatitudeRef`, `DateTimeOriginal`).



---
url: /guide/Changelog/3.1.0/Location/index.md
---

# Location

The Location API provides access to the device’s geographic location, geocoding services, system map location picking, and heading (compass) information. It is available as a global API in Scripting and can be used directly without importing any modules.

The API respects system permissions, user-selected accuracy levels, and platform limitations, and is suitable for scripts, interactive views, and supported widget scenarios.

## LocationAccuracy

Defines the desired accuracy level for location data.

**Type Definition**

```ts
type LocationAccuracy =
  | "best"
  | "tenMeters"
  | "hundredMeters"
  | "kilometer"
  | "threeKilometers"
  | "bestForNavigation"
  | "reduced"
```

**Description**

- `best`
  Requests the highest accuracy available on the device.

- `tenMeters`
  Requests approximately 10-meter accuracy.

- `hundredMeters`
  Requests approximately 100-meter accuracy.

- `kilometer`
  Requests approximately 1-kilometer accuracy.

- `threeKilometers`
  Requests coarse accuracy within approximately 3 kilometers.

- `bestForNavigation`
  Optimized for navigation use cases, with higher update frequency and power consumption.

- `reduced`
  Requests reduced-accuracy location data, typically used when the user has granted approximate location access.

## LocationInfo

Represents a geographic coordinate with an associated timestamp.

**Type Definition**

```ts
type LocationInfo = {
  latitude: number
  longitude: number
  timestamp: number
}
```

**Properties**

- `latitude`
  Latitude in degrees.

- `longitude`
  Longitude in degrees.

- `timestamp`
  Time when the location was recorded, in milliseconds since the Unix epoch.

## LocationPlacemark

Provides a human-readable description of a geographic location, usually returned by geocoding operations.

**Type Definition**

```ts
type LocationPlacemark = {
  location?: LocationInfo
  region?: string
  timeZone?: string
  name?: string
  thoroughfare?: string
  subThoroughfare?: string
  locality?: string
  subLocality?: string
  administrativeArea?: string
  subAdministrativeArea?: string
  postalCode?: string
  isoCountryCode?: string
  country?: string
  inlandWater?: string
  ocean?: string
  areasOfInterest?: string[]
}
```

**Description**

A placemark may include address components, administrative regions, country information, and points of interest. Field availability depends on the location and system map data.

## Heading

Represents compass and orientation information derived from the device’s sensors.

**Type Definition**

```ts
type Heading = {
  headingAccuracy: number
  trueHeading: number
  magneticHeading: number
  timestamp: Date
  x: number
  y: number
  z: number
}
```

**Properties**

- `headingAccuracy`
  Maximum deviation, in degrees, between the reported heading and the true geomagnetic heading.

- `trueHeading`
  Heading relative to true north, in degrees.

- `magneticHeading`
  Heading relative to magnetic north, in degrees.

- `timestamp`
  Time at which the heading was measured.

- `x`, `y`, `z`
  Raw geomagnetic field values for the three axes, measured in microteslas.

## Authorization and Configuration

### isAuthorizedForWidgetUpdates

```ts
const isAuthorizedForWidgetUpdates: boolean
```

Indicates whether the current widget is eligible to receive location updates.

### accuracy

```ts
const accuracy: LocationAccuracy
```

The currently configured desired location accuracy.

### setAccuracy

```ts
function setAccuracy(accuracy: LocationAccuracy): Promise<void>
```

Sets the desired accuracy level for subsequent location requests. Higher accuracy may increase power consumption and require additional permissions.

**Example**

```ts
await Location.setAccuracy("hundredMeters")
```

## Requesting Location

### requestCurrent

```ts
function requestCurrent(
  options?: { forceRequest?: boolean }
): Promise<LocationInfo | null>
```

Requests the device’s current location.

By default, a cached location is returned immediately if available. If no cached location exists, a new location request is performed.

When `forceRequest` is set to `true`, any cached location is ignored and a fresh request is always made.

**Example**

```ts
const location = await Location.requestCurrent()

if (location) {
  console.log(location.latitude, location.longitude)
}
```

Forcing a fresh location request:

```ts
const location = await Location.requestCurrent({
  forceRequest: true
})
```

### pickFromMap

```ts
function pickFromMap(): Promise<LocationInfo | null>
```

Presents the system map interface and allows the user to manually select a location.

**Example**

```ts
const picked = await Location.pickFromMap()

if (picked) {
  console.log("Picked location:", picked.latitude, picked.longitude)
}
```

## Geocoding

### reverseGeocode

```ts
function reverseGeocode(options: {
  latitude: number
  longitude: number
  locale?: string
}): Promise<LocationPlacemark[] | null>
```

Converts a geographic coordinate into human-readable address information.

**Example**

```ts
const placemarks = await Location.reverseGeocode({
  latitude: 39.9042,
  longitude: 116.4074,
  locale: "en-US"
})

console.log(placemarks?.[0]?.locality)
```

### geocodeAddress

```ts
function geocodeAddress(options: {
  address: string
  locale?: string
}): Promise<LocationPlacemark[] | null>
```

Converts a textual address into geographic placemark results.

**Example**

```ts
const results = await Location.geocodeAddress({
  address: "Times Square",
  locale: "en-US"
})

const location = results?.[0]?.location
```

## Heading and Compass

### requestHeading

```ts
function requestHeading(): Promise<Heading | null>
```

Returns the most recently reported heading. If heading updates have never been started, the result is `null`.

**Example**

```ts
const heading = await Location.requestHeading()

if (heading) {
  console.log(heading.trueHeading)
}
```

### startUpdatingHeading

```ts
function startUpdatingHeading(options?: {
  requestAlwaysAuthorization?: boolean
}): Promise<{ mode: "always" | "whenInUse" }>
```

Starts continuous heading updates.

When `options.requestAlwaysAuthorization` is `true`, the system requests "Always" authorization
instead of the default "When In Use".

The promise resolves with `{ mode }` reflecting the authorization actually granted by the
system. If you requested `"always"` but `mode` resolves as `"whenInUse"`, iOS did not (or
could not) prompt the user — typically because the user has already declined the upgrade
once. iOS allows only a single programmatic Always upgrade attempt; afterwards the user must
go to **Settings → Privacy & Security → Location Services → Scripting → Always** manually.

### stopUpdatingHeading

```ts
function stopUpdatingHeading(): void
```

Stops heading updates and releases related system resources.

### addHeadingListener

```ts
function addHeadingListener(
  listener: (heading: Heading) => void
): void
```

Registers a listener that is called whenever the heading changes.

**Example**

```ts
await Location.startUpdatingHeading()

Location.addHeadingListener(heading => {
  console.log("Heading:", heading.trueHeading)
})
```

### removeHeadingListener

```ts
function removeHeadingListener(
  listener?: (heading: Heading) => void
): void
```

Removes a previously registered heading listener. If no listener is provided, all heading listeners are removed.

### startUpdatingLocation

```ts
function startUpdatingLocation(options?: {
  requestAlwaysAuthorization?: boolean
}): Promise<{ mode: "always" | "whenInUse" }>
```

Starts continuous location updates. Subsequent updates are delivered to listeners registered via
`addLocationListener`.

When `options.requestAlwaysAuthorization` is `true`, the system requests "Always" authorization,
which is required if you intend to keep receiving updates while the app is backgrounded.

The promise resolves with `{ mode }` reflecting the authorization actually granted. If you
requested `"always"` but `mode` resolves as `"whenInUse"`, iOS suppressed the upgrade prompt
(only one programmatic Always upgrade attempt is permitted per app install). Direct the user
to **Settings → Privacy & Security → Location Services → Scripting → Always** to grant it
manually.

### stopUpdatingLocation

```ts
function stopUpdatingLocation(): void
```

Stops continuous location updates and releases related system resources.
This does not affect one-shot calls such as `requestCurrent`.

### addLocationListener

```ts
function addLocationListener(
  listener: (location: LocationInfo) => void
): void
```

Registers a listener that is called whenever a new location is reported.

**Example**

```ts
await Location.startUpdatingLocation()

Location.addLocationListener(location => {
  console.log("Lat/Lng:", location.latitude, location.longitude)
})
```

### removeLocationListener

```ts
function removeLocationListener(
  listener?: (location: LocationInfo) => void
): void
```

Removes a previously registered location listener. If no listener is provided, all location
listeners are removed and continuous updates stop.

### allowsBackgroundLocationUpdates / setAllowsBackgroundLocationUpdates

```ts
const allowsBackgroundLocationUpdates: boolean
function setAllowsBackgroundLocationUpdates(value: boolean): void
```

Whether the app receives location updates while in the background.

### pausesLocationUpdatesAutomatically / setPausesLocationUpdatesAutomatically

```ts
const pausesLocationUpdatesAutomatically: boolean
function setPausesLocationUpdatesAutomatically(value: boolean): void
```

Whether the system automatically pauses location updates when location data is unlikely to change.

### showsBackgroundLocationIndicator / setShowsBackgroundLocationIndicator

```ts
const showsBackgroundLocationIndicator: boolean
function setShowsBackgroundLocationIndicator(value: boolean): void
```

Whether the status bar background indicator is shown when the app uses location services
in the background under `authorizedAlways`.

### distanceFilter / setDistanceFilter

```ts
const distanceFilter: number
function setDistanceFilter(meters: number): void
```

The minimum horizontal distance (in meters) the device must move before a new update is
generated. Use `-1` to receive every movement.

### headingFilter / setHeadingFilter

```ts
const headingFilter: number
function setHeadingFilter(degrees: number): void
```

The minimum angular change (in degrees) required before a heading update is generated.
Use `-1` to receive every change.

### activityType / setActivityType

```ts
const activityType: ActivityType
function setActivityType(value: ActivityType): void
```

A hint that helps iOS optimize battery usage and accuracy:
`"other"`, `"automotiveNavigation"`, `"fitness"`, `"otherNavigation"` or `"airborne"`.



---
url: /guide/Changelog/3.1.0/Location/index_example.md
---

# Example

```tsx
import {
  Button,
  List,
  Navigation,
  NavigationStack,
  Script,
  Section,
  Text,
  Toggle,
  useEffect,
  useState,
  VStack,
} from "scripting"

const accuracyCycle: LocationAccuracy[] = [
  "best",
  "tenMeters",
  "hundredMeters",
  "kilometer",
  "threeKilometers",
  "bestForNavigation",
  "reduced",
]

const activityCycle: Location.ActivityType[] = [
  "other",
  "automotiveNavigation",
  "fitness",
  "otherNavigation",
  "airborne",
]

function nextOf<T>(items: T[], current: T): T {
  const idx = items.indexOf(current)
  return items[(idx + 1) % items.length]
}

function fmt(n: number, digits = 4): string {
  return Number.isFinite(n) ? n.toFixed(digits) : String(n)
}

// Show a hint when "Always" was requested but iOS only granted "When In Use".
function maybeWarnAlwaysUpgrade(
  requested: boolean,
  result: { mode: "always" | "whenInUse" }
) {
  if (requested && result.mode !== "always") {
    Dialog.alert({
      title: "Always not granted",
      message:
        'iOS did not prompt for "Always" upgrade. Open Settings → Privacy & ' +
        'Security → Location Services → Scripting → Always to enable it manually.'
    })
  }
}

function Example() {
  const dismiss = Navigation.useDismiss()

  // Streaming readouts
  const [latestLocation, setLatestLocation] = useState<LocationInfo | null>(null)
  const [latestHeading, setLatestHeading] = useState<Location.Heading | null>(null)
  const [streamingLocation, setStreamingLocation] = useState(false)
  const [streamingHeading, setStreamingHeading] = useState(false)

  // Settings (mirrored to component state for UI re-render)
  const [accuracy, setAccuracyState] = useState<LocationAccuracy>(Location.accuracy)
  const [activityType, setActivityTypeState] = useState<Location.ActivityType>(Location.activityType)
  const [allowsBg, setAllowsBg] = useState(Location.allowsBackgroundLocationUpdates)
  const [pausesAuto, setPausesAuto] = useState(Location.pausesLocationUpdatesAutomatically)
  const [showsIndicator, setShowsIndicator] = useState(Location.showsBackgroundLocationIndicator)
  const [distanceFilter, setDistanceFilterState] = useState(Location.distanceFilter)
  const [headingFilter, setHeadingFilterState] = useState(Location.headingFilter)

  // Cleanup streams on unmount.
  useEffect(() => {
    return () => {
      Location.removeLocationListener()
      Location.removeHeadingListener()
      Location.stopUpdatingLocation()
      Location.stopUpdatingHeading()
    }
  }, [])

  return <NavigationStack>
    <List
      navigationTitle={"Location"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      {/* Read-only state */}
      <Section
        header={<Text>Status</Text>}
      >
        <VStack alignment={"leading"}>
          <Text font={"headline"}>isAuthorizedForWidgetUpdates</Text>
          <Text font={"caption"}>{String(Location.isAuthorizedForWidgetUpdates)}</Text>
        </VStack>
        <VStack alignment={"leading"}>
          <Text font={"headline"}>accuracy</Text>
          <Text font={"caption"}>{accuracy}</Text>
        </VStack>
        <VStack alignment={"leading"}>
          <Text font={"headline"}>activityType</Text>
          <Text font={"caption"}>{activityType}</Text>
        </VStack>
      </Section>

      {/* One-shot APIs */}
      <Section header={<Text>One-shot</Text>}>
        <Button
          title={"requestCurrent (cached if available)"}
          action={async () => {
            const loc = await Location.requestCurrent()
            Dialog.alert({
              message: loc
                ? `lat=${fmt(loc.latitude)}\nlng=${fmt(loc.longitude)}`
                : "No location returned."
            })
          }}
        />
        <Button
          title={"requestCurrent ({ forceRequest: true })"}
          action={async () => {
            const loc = await Location.requestCurrent({ forceRequest: true })
            Dialog.alert({
              message: loc
                ? `lat=${fmt(loc.latitude)}\nlng=${fmt(loc.longitude)}`
                : "No location returned."
            })
          }}
        />
        <Button
          title={"requestHeading"}
          action={async () => {
            const h = await Location.requestHeading()
            Dialog.alert({
              message: h
                ? `trueHeading=${fmt(h.trueHeading, 1)}\nmagnetic=${fmt(h.magneticHeading, 1)}`
                : "No heading available."
            })
          }}
        />
        <Button
          title={"pickFromMap"}
          action={async () => {
            const picked = await Location.pickFromMap()
            Dialog.alert({
              message: picked
                ? `lat=${fmt(picked.latitude)}\nlng=${fmt(picked.longitude)}`
                : "Cancelled."
            })
          }}
        />
        <Button
          title={"reverseGeocode (Apple Park)"}
          action={async () => {
            try {
              const placemarks = await Location.reverseGeocode({
                latitude: 37.334900,
                longitude: -122.009020,
              })
              const first = placemarks?.[0]
              Dialog.alert({
                message: first
                  ? `${first.name ?? ""}\n${first.locality ?? ""}, ${first.country ?? ""}`
                  : "No placemark found."
              })
            } catch (e) {
              Dialog.alert({ message: String(e) })
            }
          }}
        />
        <Button
          title={"geocodeAddress (\"1 Infinite Loop\")"}
          action={async () => {
            try {
              const placemarks = await Location.geocodeAddress({
                address: "1 Infinite Loop, Cupertino, CA",
              })
              const first = placemarks?.[0]
              Dialog.alert({
                message: first?.location
                  ? `lat=${fmt(first.location.latitude)}\nlng=${fmt(first.location.longitude)}`
                  : "No result."
              })
            } catch (e) {
              Dialog.alert({ message: String(e) })
            }
          }}
        />
      </Section>

      {/* Heading stream */}
      <Section
        header={<Text>Heading stream</Text>}
        footer={<Text>Toggle on to subscribe via addHeadingListener.</Text>}
      >
        <Toggle
          title={"startUpdatingHeading"}
          value={streamingHeading}
          onChanged={async (on) => {
            if (on) {
              try {
                const result = await Location.startUpdatingHeading({ requestAlwaysAuthorization: false })
                maybeWarnAlwaysUpgrade(false, result)
                Location.addHeadingListener(setLatestHeading)
                setStreamingHeading(true)
              } catch (e) {
                Dialog.alert({ message: String(e) })
              }
            } else {
              Location.removeHeadingListener(setLatestHeading)
              Location.stopUpdatingHeading()
              setStreamingHeading(false)
              setLatestHeading(null)
            }
          }}
        />
        <VStack alignment={"leading"}>
          <Text font={"headline"}>latest heading</Text>
          <Text font={"caption"}>
            {latestHeading
              ? `true=${fmt(latestHeading.trueHeading, 1)}° / mag=${fmt(latestHeading.magneticHeading, 1)}°`
              : "—"}
          </Text>
        </VStack>
      </Section>

      {/* Location stream */}
      <Section
        header={<Text>Location stream</Text>}
        footer={<Text>Toggle on to subscribe via addLocationListener.</Text>}
      >
        <Toggle
          title={"startUpdatingLocation (whenInUse)"}
          value={streamingLocation}
          onChanged={async (on) => {
            if (on) {
              try {
                const result = await Location.startUpdatingLocation({ requestAlwaysAuthorization: false })
                maybeWarnAlwaysUpgrade(false, result)
                Location.addLocationListener(setLatestLocation)
                setStreamingLocation(true)
              } catch (e) {
                Dialog.alert({ message: String(e) })
              }
            } else {
              Location.removeLocationListener(setLatestLocation)
              Location.stopUpdatingLocation()
              setStreamingLocation(false)
              setLatestLocation(null)
            }
          }}
        />
        <Button
          title={"Restart with requestAlwaysAuthorization"}
          action={async () => {
            Location.removeLocationListener(setLatestLocation)
            Location.stopUpdatingLocation()
            try {
              const result = await Location.startUpdatingLocation({ requestAlwaysAuthorization: true })
              maybeWarnAlwaysUpgrade(true, result)
              Location.addLocationListener(setLatestLocation)
              setStreamingLocation(true)
            } catch (e) {
              Dialog.alert({ message: String(e) })
            }
          }}
        />
        <VStack alignment={"leading"}>
          <Text font={"headline"}>latest location</Text>
          <Text font={"caption"}>
            {latestLocation
              ? `lat=${fmt(latestLocation.latitude)} / lng=${fmt(latestLocation.longitude)}`
              : "—"}
          </Text>
        </VStack>
      </Section>

      {/* Settings */}
      <Section
        header={<Text>Settings</Text>}
        footer={<Text>Tap a value to cycle through valid options.</Text>}
      >
        <Button
          title={`setAccuracy → ${accuracy}`}
          action={async () => {
            const next = nextOf(accuracyCycle, accuracy)
            await Location.setAccuracy(next)
            setAccuracyState(next)
          }}
        />
        <Button
          title={`setActivityType → ${activityType}`}
          action={() => {
            const next = nextOf(activityCycle, activityType)
            Location.setActivityType(next)
            setActivityTypeState(next)
          }}
        />
        <Toggle
          title={"allowsBackgroundLocationUpdates"}
          value={allowsBg}
          onChanged={(on) => {
            Location.setAllowsBackgroundLocationUpdates(on)
            setAllowsBg(on)
          }}
        />
        <Toggle
          title={"pausesLocationUpdatesAutomatically"}
          value={pausesAuto}
          onChanged={(on) => {
            Location.setPausesLocationUpdatesAutomatically(on)
            setPausesAuto(on)
          }}
        />
        <Toggle
          title={"showsBackgroundLocationIndicator"}
          value={showsIndicator}
          onChanged={(on) => {
            Location.setShowsBackgroundLocationIndicator(on)
            setShowsIndicator(on)
          }}
        />
        <Button
          title={`setDistanceFilter → ${distanceFilter}m`}
          action={() => {
            // -1 (none) → 0 → 10 → 100 → 500 → -1
            const presets = [-1, 0, 10, 100, 500]
            const idx = presets.indexOf(distanceFilter)
            const next = presets[(idx + 1) % presets.length]
            Location.setDistanceFilter(next)
            setDistanceFilterState(next)
          }}
        />
        <Button
          title={`setHeadingFilter → ${headingFilter}°`}
          action={() => {
            const presets = [-1, 1, 5, 15, 45]
            const idx = presets.indexOf(headingFilter)
            const next = presets[(idx + 1) % presets.length]
            Location.setHeadingFilter(next)
            setHeadingFilterState(next)
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/MapKit/Annotation/index.md
---

# 

***

title: Annotation
description: `<Annotation>` anchors a custom SwiftUI view at a map coordinate, beyond the stock `<Marker>` glyph.

***

`<Annotation>` anchors any view tree at a map coordinate. Unlike `<Marker>`,
which is constrained to a pin glyph plus a tint, an annotation renders
arbitrary children — badges, photos, custom shapes, anything you can build
with the views layer. Use it whenever the pin needs to look like something
other than a stock MapKit marker.

```tsx
<Map cameraPosition={cam}>
  <Annotation
    coordinate={{ latitude: 31.24, longitude: 121.49 }}
    title="Bund"
    anchor="bottom"
  >
    <ZStack>
      <Circle fill="systemRed" frame={{ width: 24, height: 24 }} />
      <Text font="caption2" foregroundStyle="white">★</Text>
    </ZStack>
  </Annotation>
</Map>
```

iOS 17+. Selection (`tag`) requires iOS 18+ — the same constraint as
`<Marker tag>`.

***

## Props

| Prop         | Type                     | Description                                                                       |
| ------------ | ------------------------ | --------------------------------------------------------------------------------- |
| `coordinate` | `MapCoordinate`          | Required. Where the annotation anchors on the map.                                |
| `title`      | `string?`                | Optional MapKit label shown next to the content view. Empty / omitted = no label. |
| `anchor`     | `KeywordPoint \| Point?` | Which point of the content view sticks to the coordinate. Defaults to `"center"`. |
| `tag`        | `string?`                | Stable identifier for `<Map selection>`. Untagged annotations are not selectable. |

### `anchor` values

`KeywordPoint` covers the SwiftUI named `UnitPoint`s — handy presets:

```ts
"center" | "top" | "bottom" | "leading" | "trailing"
| "topLeading" | "topTrailing" | "bottomLeading" | "bottomTrailing" | "zero"
```

For fine-grained placement, pass a `Point` in `[0..1]` unit space:

```tsx
<Annotation coordinate={pt} anchor={{ x: 0.5, y: 0.85 }}>...</Annotation>
```

A pin that points down at the coordinate, for example, anchors at
`"bottom"` (so the pin's bottom edge sits on the spot).

***

## Selection

Annotation taps participate in `<Map selection>` exactly the same way
tagged markers do — the bound observable receives
`{ type: "marker", tag }` when the user taps a tagged annotation, and
`null` when they tap empty map background:

```tsx
const selection = useObservable<MapSelectionValue | null>(null)

return <Map cameraPosition={cam} selection={selection}>
  <Annotation coordinate={spot} tag="bund" anchor="bottom">
    <CustomPin highlighted={isSelected(selection.value, "bund")} />
  </Annotation>
</Map>
```

Annotation does not participate in `<Map itemSelection>` — it has no
`MapItem` to bind to. If your script uses `itemSelection`, annotations
render normally but tapping them does not fire the observable.

***

## Map-level title / subtitle visibility

`<Map>` accepts two props for hiding or forcing the MapKit-rendered text
labels that accompany annotations:

| Prop                  | Type                                   | Description                                                                                                            |
| --------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `annotationTitles`    | `"automatic" \| "visible" \| "hidden"` | Title labels for `Marker(item:)`, `<Annotation>`, and Apple POI labels.                                                |
| `annotationSubtitles` | `"automatic" \| "visible" \| "hidden"` | Subtitle labels — mostly meaningful for `Marker(item:)` (whose `MapItem.placemark` carries a subtitle) and Apple POIs. |

```tsx
<Map cameraPosition={cam} annotationTitles="hidden">
  {/* No title labels rendered, including the <Annotation title> above. */}
  ...
</Map>
```

These are MapKit's `Visibility` enum — `"automatic"` follows MapKit's
default zoom-dependent behavior. `<Annotation>` does not carry a subtitle
field itself; `annotationSubtitles` therefore has no effect on annotation
output, only on items / Apple POIs in the same map.

***

## Custom popover / sheet on tap

The Annotation's content closure is a regular SwiftUI view subtree, so any
view-layer modifier — including `popover` and the sheet family — attaches
to it directly. There is no dedicated "Annotation card" prop because none
is needed: write the same modifier you would on a normal view.

```tsx
const selection = useObservable<MapSelectionValue | null>(null)
const popoverShown = useObservable(false)

// Sync the popover open state to the selection observable.
useEffect(() => {
  popoverShown.setValue(
    selection.value?.type === "marker" && selection.value.tag === "bund"
  )
}, [selection.value])

return <Map cameraPosition={cam} selection={selection}>
  <Annotation coordinate={spot} tag="bund" anchor="bottom">
    <CustomPin
      popover={{
        isPresented: popoverShown,
        content: <BundDetail onDismiss={() => selection.setValue(null)} />,
      }}
    />
  </Annotation>
</Map>
```

This is the same pattern SwiftUI itself uses for custom annotation cards —
the popover anchors to the annotation's content view automatically. Apple's
`itemDetailSelectionAccessory` / `featureSelectionAccessory` are only for
`Marker(item:)` and Apple-rendered POIs; `<Annotation>` rolls its own card
via this view-layer modifier path.

***

## When to choose `<Annotation>` vs `<Marker>`

- **`<Marker>`** — the visual is a stock MapKit pin: tint, optional SF
  Symbol glyph or monogram, optional auto POI glyph from `MapItem`. Use
  for "ordinary pins" and `MapItem`-based annotations.
- **`<Annotation>`** — the visual is your own SwiftUI subtree. Use when
  you need a chip, a photo callout, a stretched ribbon, or anything else
  that isn't a Marker glyph.

The two coexist freely inside the same `<Map>` and share the same
`<Map selection>` / `tag` mechanism.



---
url: /guide/Changelog/3.1.0/MapKit/Annotation/index_example.md
---

# 

***

title: Example
description: `<Annotation>` anchors a custom SwiftUI view at a map coordinate, beyond the stock `<Marker>` glyph.

***

```tsx
import {
  Annotation, Button, Circle, HStack, Map, Marker, Navigation, NavigationStack,
  Picker, RoundedRectangle, Script, ScrollView, Spacer, Text, useEffect, useObservable, useState,
  VStack, ZStack,
} from "scripting"
import type { KeywordPoint, MapAnnotationLabelVisibility, MapSelectionValue } from "scripting"

// Demo center: People's Square, Shanghai
const initialRegion = {
  center: { latitude: 31.2304, longitude: 121.4737 },
  span: { latitudeDelta: 0.05, longitudeDelta: 0.05 },
}

// Three landmarks around the demo center.
const points = [
  { id: "bund", name: "Bund", coord: { latitude: 31.2397, longitude: 121.4906 } },
  { id: "lujia", name: "Lujiazui", coord: { latitude: 31.2397, longitude: 121.5000 } },
  { id: "xtd", name: "Xintiandi", coord: { latitude: 31.2218, longitude: 121.4760 } },
] as const

type PointId = (typeof points)[number]["id"]

function CustomPinDemo() {
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  const selection = useObservable<MapSelectionValue | null>(null)

  const tappedId =
    selection.value != null && selection.value.type === "marker"
      ? (selection.value.tag as PointId)
      : null
  const tapped = points.find(p => p.id === tappedId)

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>{`1. Custom-content \`<Annotation>\``}</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`Each pin is a custom SwiftUI subtree (rounded chip with letter). Tapping
      a chip writes its \`tag\` into \`<Map selection>\`; we use that to grow the
      selected chip and tint it red.`}
    </Text>
    {tapped != null
      ? <Text font={"caption"} foregroundStyle={"systemBlue"}>
        Selected: {tapped.name}
      </Text>
      : <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
        Tap a chip to select it.
      </Text>}
    <Map
      cameraPosition={position}
      selection={selection}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {points.map(p => {
        const isSelected = p.id === tappedId
        return <Annotation
          coordinate={p.coord}
          title={p.name}
          anchor="bottom"
          tag={p.id}
        >
          <ZStack>
            <RoundedRectangle
              cornerRadius={10}
              fill={isSelected ? "systemRed" : "systemBlue"}
              frame={{ width: isSelected ? 32 : 24, height: isSelected ? 32 : 24 }}
            />
            <Text
              font={isSelected ? "headline" : "caption"}
              foregroundStyle={"white"}
            >
              {p.name.charAt(0)}
            </Text>
          </ZStack>
        </Annotation>
      })}
    </Map>
  </VStack>
}

function AnchorPickerDemo() {
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  const [anchor, setAnchor] = useState<KeywordPoint>("center")

  const anchorOptions: KeywordPoint[] = [
    "center", "top", "bottom", "leading", "trailing",
    "topLeading", "topTrailing", "bottomLeading", "bottomTrailing",
  ]

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>2. `anchor` placement</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      The same content view, anchored at different `KeywordPoint`s relative to
      the same coordinate. `"bottom"` is the classic pin-style anchor (pin
      tip sits on the spot); `"center"` puts the visual center on the spot.
    </Text>
    <Picker title="anchor" value={anchor} onChanged={(v: any) => setAnchor(v as KeywordPoint)}>
      {anchorOptions.map(opt => (
        <Text tag={opt}>{opt}</Text>
      ))}
    </Picker>
    <Map
      cameraPosition={position}
      frame={{ height: 240 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      <Annotation
        coordinate={initialRegion.center}
        title=""
        anchor={anchor}
      >
        <ZStack>
          <Circle fill="systemOrange" frame={{ width: 28, height: 28 }} />
          <Text font="caption2" foregroundStyle={"white"}>●</Text>
        </ZStack>
      </Annotation>
      {/* Reference pin marks the exact coordinate the annotation is anchored to. */}
      <Marker title="" coordinate={initialRegion.center} tint="systemRed" />
    </Map>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      The red Marker pin marks the actual coordinate. Compare its position to
      the orange annotation as you cycle through anchors.
    </Text>
  </VStack>
}

function TitleVisibilityDemo() {
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  const [titles, setTitles] = useState<MapAnnotationLabelVisibility>("automatic")

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>{`3. \`<Map annotationTitles>\``}</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`Toggle the global title visibility. \`annotationTitles\` applies to
      \`Marker(item:)\`, \`<Annotation title>\`, and Apple POI labels in the
      same map.`}
    </Text>
    <Picker title="annotationTitles" value={titles} onChanged={(v: any) => setTitles(v as MapAnnotationLabelVisibility)}>
      <Text tag="automatic">automatic</Text>
      <Text tag="visible">visible</Text>
      <Text tag="hidden">hidden</Text>
    </Picker>
    <Map
      cameraPosition={position}
      annotationTitles={titles}
      frame={{ height: 240 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {points.map(p => (
        <Annotation coordinate={p.coord} title={p.name} anchor="bottom">
          <Circle fill="systemGreen" frame={{ width: 20, height: 20 }} />
        </Annotation>
      ))}
    </Map>
  </VStack>
}

function SelectionPopoverDemo() {
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  // selection 走 <Map selection>(Phase 3f),annotation tap 写入 { type:"marker", tag }
  const selection = useObservable<MapSelectionValue | null>(null)
  // popover 用 Observable<boolean> 形式,直接跟 selection 状态同步
  const popoverShown = useObservable(false)

  // selection → popover 双向同步:
  //  - 点中 annotation → 显示 popover
  //  - 点空白 / 关闭 popover → 清空 selection
  useEffect(() => {
    const isMarker =
      selection.value?.type === "marker" && selection.value.tag === "popover-pin"
    popoverShown.setValue(isMarker)
  }, [selection.value])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>{`4. Selection-driven popover`}</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`SwiftUI 原生模式:annotation content view 上直接挂 \`popover\` modifier。
      tap 写入 selection observable,我们再把它同步到 popover 的 isPresented。`}
    </Text>
    <Map
      cameraPosition={position}
      selection={selection}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      <Annotation
        coordinate={initialRegion.center}
        title="People's Square"
        anchor="bottom"
        tag="popover-pin"
      >
        <ZStack
          popover={{
            isPresented: popoverShown,
            arrowEdge: "bottom",
            presentationCompactAdaptation: "popover",
            content: <VStack alignment={"leading"} spacing={8} padding>
              <Text font={"headline"}>People's Square</Text>
              <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
                The popover anchors automatically to the annotation it sits on.
                Tap the map background to dismiss — selection clears and the
                popover hides via the observable.
              </Text>
              <HStack>
                <Spacer />
                <Button title="Close" action={() => selection.setValue(null)} />
              </HStack>
            </VStack>,
          }}
        >
          <Circle fill="systemPurple" frame={{ width: 28, height: 28 }} />
          <Text font="caption2" foregroundStyle={"white"}>i</Text>
        </ZStack>
      </Annotation>
    </Map>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      {`Apple's \`itemDetailSelectionAccessory\` is only for \`Marker(item:)\`. For
      \`<Annotation>\` you roll the card yourself with the same view modifier
      you'd use on any other view.`}
    </Text>
  </VStack>
}

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Annotation"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"Annotation"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={24}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`Custom-content map annotations. Use whenever a pin's visual needs to
          be something other than a stock MapKit marker glyph. Coexists with
          \`<Marker>\` in the same \`<Map>\` and shares the \`<Map selection>\` /
            \`tag\` selection mechanism.`}
        </Text>

        <CustomPinDemo />
        <AnchorPickerDemo />
        <TitleVisibilityDemo />
        <SelectionPopoverDemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/MapKit/Map/index.md
---

# Map

`Map` is a SwiftUI MapKit–backed view (iOS 17+). It renders a map with optional
camera binding, styling, annotations (`Marker`, `MapPolyline`, `MapPolygon`,
`MapCircle`), and built-in MapKit controls.

The shape of the API mirrors SwiftUI MapKit directly — no Web-style imperative
calls (`addMarker(...)`). You declare what should appear on the map; the bridge
turns the tree into `MapContent`.

***

## Basic usage

```tsx
import { Map, Marker, useObservable } from "scripting"

function Demo() {
  const position = useObservable<MapCameraPosition>(
    MapCameraPosition.region({
      center: { latitude: 31.23, longitude: 121.47 },
      span: { latitudeDelta: 0.05, longitudeDelta: 0.05 },
    })
  )

  return <Map cameraPosition={position}>
    <Marker
      title="Bund"
      coordinate={{ latitude: 31.24, longitude: 121.49 }}
      tint="systemRed"
    />
  </Map>
}
```

Use any standard view modifier (`frame`, `padding`, `aspectRatio`, ...) to size the
map. There are no `width` / `height` props.

***

## Camera position

Two mutually exclusive ways to set the camera:

| Prop                    | Type                            | Behavior                                                                                         |
| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `cameraPosition`        | `Observable<MapCameraPosition>` | Two-way binding. User gestures write the resulting `MapCameraPosition` back into the observable. |
| `initialCameraPosition` | `MapCameraPosition`             | One-time initial value, no write-back.                                                           |

> The props are named `cameraPosition` / `initialCameraPosition` rather than
> `position` / `initialPosition` to avoid clashing with the SwiftUI
> `.position(x:y:)` view modifier.

`MapCameraPosition` is an opaque value (`MapCameraPosition` class). Construct it
via factories on the `MapCameraPosition` namespace — never pass a plain dict:

```ts
MapCameraPosition.region({ center, span })
MapCameraPosition.rect({ center, size: { width, height } })   // size in meters
MapCameraPosition.camera({ centerCoordinate, distance, heading?, pitch? })
// or: MapCameraPosition.camera(MapCamera.make({...}))
MapCameraPosition.item({ coordinate, name? }, { allowsAutomaticPitch?: boolean })
MapCameraPosition.userLocation({ fallback?: MapCameraPosition })
MapCameraPosition.automatic()
```

Read what's currently framed via the readonly accessors:

```ts
const pos: MapCameraPosition = camera.value
pos.region              // MapRegion | null
pos.rect                // { center, size } | null
pos.camera              // MapCamera | null
pos.item                // { coordinate, name? } | null
pos.fallbackPosition    // MapCameraPosition | null
pos.allowsAutomaticPitch
pos.positionedByUser    // true if the most recent change came from a user gesture
```

User gestures write the new `MapCameraPosition` back directly — whatever form
the camera ends up in (typically a region after pan/zoom) is what the observable
will hold.

***

## Map style

```tsx
<Map mapStyle={{ style: "standard", showsTraffic: true }}>...</Map>

<Map mapStyle={{ style: "hybrid", elevation: "realistic" }}>...</Map>

<Map mapStyle={{
  style: "standard",
  pointsOfInterest: { includes: ["restaurant", "park"] },
}}>...</Map>
```

`pointsOfInterest` accepts `"all"`, `"excludingAll"`, or `{ includes: [...] }` /
`{ excludes: [...] }` with category strings like `"airport"`, `"cafe"`,
`"restaurant"`, etc.

***

## Map content

The following are valid children of `<Map>`:

### `Marker`

```tsx
<Marker
  title="Bund"
  coordinate={{ latitude: 31.24, longitude: 121.49 }}
  tint="systemRed"
/>

<Marker
  coordinate={{ latitude: 31.23, longitude: 121.47 }}
  systemImage="building.2"
  tint="systemBlue"
/>

<Marker
  title="A"
  coordinate={{ latitude: 31.23, longitude: 121.47 }}
  monogram="A"
/>
```

`systemImage` and `monogram` are mutually exclusive. `tint` accepts the same
color strings as the rest of the bridge (system colors, `"#RRGGBB"`,
`"rgba(...)"`, etc.).

### `MapPolyline`

```tsx
<MapPolyline
  coordinates={[
    { latitude: 31.23, longitude: 121.47 },
    { latitude: 31.24, longitude: 121.48 },
    { latitude: 31.245, longitude: 121.495 },
  ]}
  strokeColor="systemBlue"
  strokeStyle={{ lineWidth: 4 }}
/>
```

`contourStyle` is `"straight"` (default) or `"geodesic"`. The difference is
invisible at short distances and only meaningful for cross-continent routes.

### `MapPolygon`

```tsx
<MapPolygon
  coordinates={[ ... ]}
  fillColor="systemBlue"
  strokeColor="white"
  strokeStyle={{ lineWidth: 2 }}
/>
```

### `MapCircle`

```tsx
<MapCircle
  center={{ latitude: 31.23, longitude: 121.47 }}
  radius={500}
  fillColor="systemBlue"
  strokeColor="white"
/>
```

`radius` is in meters.

***

## Built-in controls

Use the `controls` prop and pass either a single control element or a Fragment
containing several:

```tsx
<Map
  controls={<>
    <MapUserLocationButton />
    <MapCompass />
    <MapScaleView />
  </>}
>
  ...
</Map>
```

Valid controls:

- `MapUserLocationButton` — recenter on user location (asks for permission)
- `MapCompass` — compass rose that resets rotation
- `MapPitchToggle` — toggle 2D / pitched view
- `MapScaleView` — adaptive scale bar

***

## `strokeStyle`

Used by `MapPolyline`, `MapPolygon`, and `MapCircle`:

```ts
type MapStrokeStyle = {
  lineWidth?: number                                // points
  lineCap?: "butt" | "round" | "square"
  lineJoin?: "miter" | "round" | "bevel"
  dash?: number[]                                   // dash/gap lengths in points
}
```

***

## `cameraBounds` — constrain pan / zoom

Pass a `MapCameraBounds` instance to clamp how far the user can pan and
zoom an interactive map. Two factories:

```ts
// Lock the center inside a region, and optionally cap zoom range
// (camera-to-center distance in meters).
const bounds = MapCameraBounds.centerCoordinateBounds(
  {
    center: { latitude: 31.2304, longitude: 121.4737 },
    span:   { latitudeDelta: 0.1, longitudeDelta: 0.1 },
  },
  { minimumDistance: 200, maximumDistance: 8000 }
)

// Restrict zoom only — the center is free to pan anywhere.
const zoomOnly = MapCameraBounds.distance({
  minimumDistance: 500,
  maximumDistance: 50_000,
})

return <Map cameraPosition={cam} cameraBounds={bounds}>...</Map>
```

`minimumDistance` / `maximumDistance` are measured in meters from the camera
to its `centerCoordinate`. Both fields are optional in either factory; pass
the ones you want. `MapCameraBounds.distance(...)` requires at least one of
them (passing an empty options dict returns `null` and the prop has no
effect).

The constraint applies to user gestures only — programmatic `cameraPosition`
writes from JS can still place the camera outside the bounds. MapKit will
typically animate back into bounds on the next user interaction.

***

## Performance tips

- Marker count: a few dozen markers is fine. For hundreds, prefer cluster-like
  preprocessing in your script and only emit markers visible in the current
  region.
- Update cadence: each render replays the full content tree. If your script
  derives many markers from large arrays on every state change, memoize them
  with `useMemo`.
- `cameraPosition` is two-way: a `setValue` from JS triggers a re-render; the gesture
  reconciler skips equivalent writes to avoid loops.



---
url: /guide/Changelog/3.1.0/MapKit/Map/index_example.md
---

# Example

```tsx
import {
  Button, HStack, Map, MapCircle, MapCompass, MapPitchToggle, MapPolygon, MapPolyline,
  MapScaleView, MapUserLocationButton, Marker, Navigation, NavigationStack, Picker, Script,
  ScrollView, Text, useMemo, useObservable, useState, VStack,
} from "scripting"
import type { MapStyleSpec, MapPointsOfInterestSpec } from "scripting"

function Example() {
  // Camera bound to most of the demos below. Demo 4 swaps it through every
  // MapCameraPosition variant; the other demos read its current value.
  const position = useObservable<MapCameraPosition>(
    MapCameraPosition.region({
      center: { latitude: 31.2354, longitude: 121.4905 },
      span: { latitudeDelta: 0.04, longitudeDelta: 0.04 },
    })
  )

  // ───── Demo 2 state: mapStyle picker ─────
  const [styleKind, setStyleKind] = useState<"standard" | "imagery" | "hybrid">("standard")
  const [showsTraffic, setShowsTraffic] = useState(false)

  const mapStyle: MapStyleSpec = useMemo(() => {
    if (styleKind === "imagery") {
      return { style: "imagery", elevation: "realistic" }
    }
    if (styleKind === "hybrid") {
      return { style: "hybrid", elevation: "realistic", showsTraffic }
    }
    return { style: "standard", showsTraffic }
  }, [styleKind, showsTraffic])

  // ───── Demo 4 state: camera-spec variants ─────
  type CameraKind = "region" | "rect" | "camera" | "automatic" | "userLocation"
  const [cameraKind, setCameraKind] = useState<CameraKind>("region")

  const applyCamera = (kind: CameraKind) => {
    setCameraKind(kind)
    switch (kind) {
      case "region":
        position.setValue(MapCameraPosition.region({
          center: { latitude: 31.2354, longitude: 121.4905 },
          span: { latitudeDelta: 0.04, longitudeDelta: 0.04 },
        }))
        return
      case "rect":
        // 5 km × 5 km square around the Bund
        position.setValue(MapCameraPosition.rect({
          center: { latitude: 31.2407, longitude: 121.4905 },
          size: { width: 5000, height: 5000 },
        }))
        return
      case "camera":
        position.setValue(MapCameraPosition.camera({
          centerCoordinate: { latitude: 31.2397, longitude: 121.4994 },
          distance: 1500,
          heading: 30,
          pitch: 45,
        }))
        return
      case "automatic":
        position.setValue(MapCameraPosition.automatic())
        return
      case "userLocation":
        // Requires user location permission; falls back to .automatic without it.
        position.setValue(MapCameraPosition.userLocation())
        return
    }
  }

  // ───── Demo 5 state: POI filter ─────
  type POIMode = "all" | "excludingAll" | "includes" | "excludes"
  const [poiMode, setPoiMode] = useState<POIMode>("all")

  const poiSpec: MapPointsOfInterestSpec = useMemo(() => {
    if (poiMode === "all") return "all"
    if (poiMode === "excludingAll") return "excludingAll"
    if (poiMode === "includes") return { includes: ["restaurant", "cafe", "park"] }
    return { excludes: ["gasStation", "atm", "parking"] }
  }, [poiMode])

  // ───── Demo 6: geodesic polyline state ─────
  // Toggle between straight and geodesic to visualise the curvature on long routes.
  const [geodesic, setGeodesic] = useState(true)

  // ───── Demo 8: pitch toggle ─────
  const pitchedPosition = useObservable<MapCameraPosition>(
    MapCameraPosition.camera({
      centerCoordinate: { latitude: 31.2397, longitude: 121.4994 },
      distance: 1200,
      heading: 30,
      pitch: 60,
    })
  )

  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map View"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"Map"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={20}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`\`Map\` is a SwiftUI MapKit view. Pass an \`Observable<MapCameraPosition>\` to
          \`cameraPosition\` for two-way binding — gestures write the new camera back on
          gesture end. Use the children for \`Marker\`, \`MapPolyline\`, \`MapPolygon\`,
          \`MapCircle\`; use \`controls={...}\` to mount built-in MapKit controls.`}
        </Text>

        {/* 1. Basic map with Marker + Polyline + Circle */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. Basic map</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Three markers (plain label, SF Symbol, monogram), a polyline tracing a path
            between them, and a circle showing a 300m radius. Drag/zoom — the region writes
            back to `cameraPosition`.
          </Text>
          <Map
            cameraPosition={position}
            mapStyle={mapStyle}
            controls={<>
              <MapUserLocationButton />
              <MapCompass />
              <MapScaleView />
            </>}
            frame={{ height: 320 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <Marker
              title="Bund"
              coordinate={{ latitude: 31.2407, longitude: 121.4905 }}
              tint="systemRed"
            />
            <Marker
              title="People's Square"
              coordinate={{ latitude: 31.2304, longitude: 121.4737 }}
              systemImage="building.2"
              tint="systemBlue"
            />
            <Marker
              title="Lujiazui"
              coordinate={{ latitude: 31.2397, longitude: 121.4994 }}
              monogram="L"
              tint="systemPurple"
            />
            <MapPolyline
              coordinates={[
                { latitude: 31.2304, longitude: 121.4737 },
                { latitude: 31.2407, longitude: 121.4905 },
                { latitude: 31.2397, longitude: 121.4994 },
              ]}
              strokeColor="systemOrange"
              strokeStyle={{ lineWidth: 4, lineCap: "round", lineJoin: "round" }}
            />
            <MapCircle
              center={{ latitude: 31.2354, longitude: 121.4905 }}
              radius={300}
              fillColor="rgba(0, 122, 255, 0.15)"
              strokeColor="systemBlue"
              strokeStyle={{ lineWidth: 2 }}
            />
          </Map>
        </VStack>

        {/* 2. mapStyle + showsTraffic + elevation */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Map style</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Switch the map above between Standard / Imagery / Hybrid. Imagery and Hybrid
            request realistic elevation; only Standard and Hybrid honor `showsTraffic`.
          </Text>
          <HStack spacing={8}>
            <Button title="Standard" action={() => setStyleKind("standard")} />
            <Button title="Imagery" action={() => setStyleKind("imagery")} />
            <Button title="Hybrid" action={() => setStyleKind("hybrid")} />
          </HStack>
          <HStack spacing={8}>
            <Button
              title={showsTraffic ? "Traffic: ON" : "Traffic: OFF"}
              action={() => setShowsTraffic(v => !v)}
            />
          </HStack>
        </VStack>

        {/* 3. Polygon demo */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. Polygon</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            A filled polygon outlining a rough quad around People's Square. Uses
            `initialCameraPosition` (one-way init, no write-back).
          </Text>
          <Map
            initialCameraPosition={MapCameraPosition.region({
              center: { latitude: 31.2304, longitude: 121.4737 },
              span: { latitudeDelta: 0.02, longitudeDelta: 0.02 },
            })}
            frame={{ height: 240 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <MapPolygon
              coordinates={[
                { latitude: 31.234, longitude: 121.470 },
                { latitude: 31.234, longitude: 121.478 },
                { latitude: 31.227, longitude: 121.478 },
                { latitude: 31.227, longitude: 121.470 },
              ]}
              fillColor="rgba(52, 199, 89, 0.25)"
              strokeColor="systemGreen"
              strokeStyle={{ lineWidth: 2 }}
            />
          </Map>
        </VStack>

        {/* 4. All 5 MapCameraPosition variants */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>4. Camera spec variants</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Cycle a dedicated `cameraPosition` observable through every
            `MapCameraPosition` form. The map directly below responds.
            `userLocation` needs location permission; without it MapKit falls
            back to `automatic`.
          </Text>
          <Picker
            title="Camera"
            value={cameraKind}
            onChanged={(v: any) => applyCamera(v as CameraKind)}
            pickerStyle={"segmented"}
          >
            <Text tag={"region"}>region</Text>
            <Text tag={"rect"}>rect</Text>
            <Text tag={"camera"}>camera</Text>
            <Text tag={"automatic"}>auto</Text>
            <Text tag={"userLocation"}>user</Text>
          </Picker>
          <Map
            cameraPosition={position}
            frame={{ height: 260 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <Marker
              title="People's Square"
              coordinate={{ latitude: 31.2304, longitude: 121.4737 }}
              tint="systemRed"
            />
            <Marker
              title="Lujiazui"
              coordinate={{ latitude: 31.2397, longitude: 121.4994 }}
              tint="systemBlue"
            />
          </Map>
          <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
            Note: dragging the map afterwards writes a `{"{ region }"}` form
            back, regardless of which variant you started with. The map in
            Demo 1 shares the same observable, so it will respond too.
          </Text>
        </VStack>

        {/* 5. POI filter */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>5. Points of interest filter</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Filter which POIs MapKit renders. `includes` shows only the listed categories;
            `excludes` shows everything except them; `excludingAll` hides all POIs.
          </Text>
          <Picker
            title="POI"
            value={poiMode}
            onChanged={(v: any) => setPoiMode(v as POIMode)}
            pickerStyle={"segmented"}
          >
            <Text tag={"all"}>all</Text>
            <Text tag={"excludingAll"}>none</Text>
            <Text tag={"includes"}>food + park</Text>
            <Text tag={"excludes"}>no gas/atm</Text>
          </Picker>
          <Map
            initialCameraPosition={MapCameraPosition.region({
              center: { latitude: 31.2304, longitude: 121.4737 },
              span: { latitudeDelta: 0.015, longitudeDelta: 0.015 },
            })}
            mapStyle={{ style: "standard", pointsOfInterest: poiSpec }}
            frame={{ height: 260 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          />
        </VStack>

        {/* 6. Geodesic polyline (long-haul route) */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>6. Geodesic polyline</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Beijing ⇄ San Francisco great-circle vs straight line. Geodesic follows the
            shortest path on a sphere — visibly curved on long routes; the straight form
            cuts diagonally across the projection.
          </Text>
          <HStack spacing={8}>
            <Button
              title={geodesic ? "Mode: geodesic" : "Mode: straight"}
              action={() => setGeodesic(v => !v)}
            />
          </HStack>
          <Map
            initialCameraPosition={MapCameraPosition.region({
              center: { latitude: 50, longitude: -160 },
              span: { latitudeDelta: 90, longitudeDelta: 200 },
            })}
            mapStyle={{ style: "standard" }}
            frame={{ height: 260 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <Marker title="Beijing"
              coordinate={{ latitude: 39.9042, longitude: 116.4074 }}
              tint="systemRed"
            />
            <Marker title="San Francisco"
              coordinate={{ latitude: 37.7749, longitude: -122.4194 }}
              tint="systemBlue"
            />
            <MapPolyline
              coordinates={[
                { latitude: 39.9042, longitude: 116.4074 },
                { latitude: 37.7749, longitude: -122.4194 },
              ]}
              strokeColor="systemOrange"
              strokeStyle={{ lineWidth: 3, lineCap: "round" }}
              contourStyle={geodesic ? "geodesic" : "straight"}
            />
          </Map>
        </VStack>

        {/* 7. Dashed strokes + lineCap / lineJoin */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>7. Stroke styles</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Three polylines side-by-side showing `dash` + `lineCap` + `lineJoin` combinations,
            plus a dashed `MapCircle` outline. Dash lengths and gaps are in points.
          </Text>
          <Map
            initialCameraPosition={MapCameraPosition.region({
              center: { latitude: 31.2354, longitude: 121.4905 },
              span: { latitudeDelta: 0.012, longitudeDelta: 0.018 },
            })}
            frame={{ height: 280 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <MapPolyline
              coordinates={[
                { latitude: 31.238, longitude: 121.484 },
                { latitude: 31.238, longitude: 121.497 },
              ]}
              strokeColor="systemRed"
              strokeStyle={{ lineWidth: 5, lineCap: "butt" }}
            />
            <MapPolyline
              coordinates={[
                { latitude: 31.235, longitude: 121.484 },
                { latitude: 31.235, longitude: 121.497 },
              ]}
              strokeColor="systemBlue"
              strokeStyle={{ lineWidth: 5, lineCap: "round", dash: [12, 6] }}
            />
            <MapPolyline
              coordinates={[
                { latitude: 31.232, longitude: 121.484 },
                { latitude: 31.232, longitude: 121.490 },
                { latitude: 31.234, longitude: 121.497 },
              ]}
              strokeColor="systemGreen"
              strokeStyle={{ lineWidth: 5, lineJoin: "round", dash: [4, 4] }}
            />
            <MapCircle
              center={{ latitude: 31.2354, longitude: 121.4905 }}
              radius={250}
              fillColor="rgba(175, 82, 222, 0.10)"
              strokeColor="systemPurple"
              strokeStyle={{ lineWidth: 2, dash: [8, 4] }}
            />
          </Map>
        </VStack>

        {/* 8. MapPitchToggle + pitched 3D camera */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>8. Pitched camera + MapPitchToggle</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Hybrid + realistic elevation + a `camera`-form initial position with pitch=60°.
            The pitch-toggle control in the corner flips between flat and pitched view.
          </Text>
          <Map
            cameraPosition={pitchedPosition}
            mapStyle={{ style: "hybrid", elevation: "realistic" }}
            controls={<>
              <MapPitchToggle />
              <MapCompass />
            </>}
            frame={{ height: 320 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <Marker title="Lujiazui"
              coordinate={{ latitude: 31.2397, longitude: 121.4994 }}
              systemImage="building.2.crop.circle"
              tint="systemTeal"
            />
          </Map>
        </VStack>

        <CameraBoundsDemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

function CameraBoundsDemo() {
  // 中心约束:相机中心被锁在外滩 ~5km 矩形内,推不出去。
  const center = { latitude: 31.2397, longitude: 121.4906 }
  const region = { center, span: { latitudeDelta: 0.05, longitudeDelta: 0.05 } }
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(region))

  const [mode, setMode] = useState<"region" | "distance" | "off">("region")

  // 用 useMemo 避免每次 render 重建 bounds(SwiftUI 端按对象身份判等)。
  const bounds = useMemo(() => {
    if (mode === "off") return undefined
    if (mode === "region") {
      return MapCameraBounds.centerCoordinateBounds(region, {
        minimumDistance: 500,
        maximumDistance: 8000,
      })
    }
    // distance-only:中心可以拖到任意地方,只限 zoom 范围
    return MapCameraBounds.distance({ minimumDistance: 1000, maximumDistance: 20000 })
  }, [mode])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>9. `cameraBounds` — clamp pan / zoom</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`\`MapCameraBounds.centerCoordinateBounds\` 把中心锁在 region 内 + 限 zoom。
      \`MapCameraBounds.distance\` 只限 zoom,中心可以自由拖。
      off 时取消约束,作为对照。试着拖远 / 拖近 / 拖到很远的地方看效果。`}
    </Text>
    <Picker title="bounds" value={mode} onChanged={(v: any) => setMode(v as typeof mode)} pickerStyle="segmented">
      <Text tag="region">region + zoom</Text>
      <Text tag="distance">zoom only</Text>
      <Text tag="off">off</Text>
    </Picker>
    <Map
      cameraPosition={position}
      cameraBounds={bounds}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      <Marker title="Bund" coordinate={center} tint="systemRed" />
    </Map>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      Bounds 只影响用户手势 — JS 端 `cameraPosition.setValue(...)` 仍可把相机程序化
      移到约束外。MapKit 通常在下一次手势时把相机动画拉回合法范围。
    </Text>
  </VStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/MapKit/MapDirections/index.md
---

# 

***

title: MapDirections
description: MapKit route planning: `calculate(...)` for full routes and `calculateETA(...)` for travel time only.
tag: PRO
--------

`MapDirections` plans routes between two endpoints using MapKit. Two entry points:

- `MapDirections.calculate(options)` — full route(s) with turn-by-turn steps and
  a ready-to-render polyline.
- `MapDirections.calculateETA(options)` — travel time / distance / arrival
  window only. Cheaper and faster than `calculate` when you don't need the
  geometry.

Both APIs are network-backed by Apple's directions servers and require **no
iOS system permissions**. The result is plain data — no opaque handles to
dispose.

Pair with the views layer: `route.coordinates` is shaped exactly for
`<MapPolyline coordinates={route.coordinates}>` from the `<Map>` view.

***

## `calculate` — plan a route

```ts
const resp = await MapDirections.calculate({
  source: { latitude: 31.2304, longitude: 121.4737 },        // People's Square
  destination: { latitude: 31.2397, longitude: 121.4994 },   // Lujiazui
  transportType: "walking",
})

const route = resp.routes[0]
console.log(route.distance, "m")             // total distance in meters
console.log(route.expectedTravelTime, "s")   // ETA in seconds
console.log(route.steps.length, "steps")     // turn-by-turn count
```

### Options

| Option                    | Type                                              | Description                                                                   |
| ------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- |
| `source`                  | `DirectionsEndpoint`                              | Required. Bare `MapCoordinate` or `{ coordinate, name? }`.                    |
| `destination`             | `DirectionsEndpoint`                              | Required. Same shape as `source`.                                             |
| `transportType`           | `"automobile" \| "walking" \| "transit" \| "any"` | Default `"automobile"`.                                                       |
| `requestsAlternateRoutes` | `boolean`                                         | Default `false`. Up to 3 routes when supported (driving / highway only).      |
| `departureDate`           | `Date`                                            | Plan a route departing at this time. Wins over `arrivalDate` if both are set. |
| `arrivalDate`             | `Date`                                            | Plan a route arriving by this time.                                           |
| `tollPreference`          | `"any" \| "avoid"`                                | Default `"any"`.                                                              |
| `highwayPreference`       | `"any" \| "avoid"`                                | Default `"any"`.                                                              |

### `DirectionsResponse`

| Field         | Type                | Description                                                                                             |
| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------- |
| `source`      | `MapItem`           | Same shape as `MapSearch.locate` results — includes `coordinate`, `placemark`, `formattedAddress`, etc. |
| `destination` | `MapItem`           | Same shape.                                                                                             |
| `routes`      | `DirectionsRoute[]` | At least 1 entry.                                                                                       |

### `DirectionsRoute`

| Field                | Type                    | Description                                                                   |
| -------------------- | ----------------------- | ----------------------------------------------------------------------------- |
| `name`               | `string`                | Route label (e.g. road name).                                                 |
| `distance`           | `number`                | Total distance in meters.                                                     |
| `expectedTravelTime` | `number`                | ETA in seconds.                                                               |
| `transportType`      | `TransportType`         | Mode used for this route.                                                     |
| `coordinates`        | `MapCoordinate[]`       | Ready-to-render polyline. Pass straight to `<MapPolyline coordinates={...}>`. |
| `steps`              | `DirectionsRouteStep[]` | Turn-by-turn instructions.                                                    |
| `hasTolls`           | `boolean`               | Any tolled segments.                                                          |
| `hasHighways`        | `boolean`               | Any highway segments.                                                         |
| `advisoryNotices`    | `string[]`              | Optional advisory text from Apple.                                            |

### Rendering with `<MapPolyline>`

```tsx
<Map cameraPosition={position}>
  <Marker title="Start" coordinate={route.coordinates[0]} tint="systemGreen" />
  <Marker title="End"   coordinate={route.coordinates.at(-1)!} tint="systemRed" />
  <MapPolyline
    coordinates={route.coordinates}
    strokeColor="systemBlue"
    strokeStyle={{ lineWidth: 4, lineCap: "round" }}
  />
</Map>
```

***

## `calculateETA` — time / distance only

```ts
const eta = await MapDirections.calculateETA({
  source: { latitude: 31.2304, longitude: 121.4737 },
  destination: { latitude: 31.2397, longitude: 121.4994 },
  transportType: "automobile",
})

console.log(eta.expectedTravelTime, "s")
console.log(eta.distance, "m")
console.log(eta.expectedArrivalDate.toLocaleString())
```

Use this when you only need the headline numbers — it skips downloading the
full route geometry, so it's noticeably faster than `calculate`.

***

## Notes & limitations

- **Transit** (`transportType: "transit"`) is supported in a limited set of
  regions. Outside those, the request rejects with `directionsNotFound`. For
  broad coverage prefer `"automobile"` or `"walking"`.
- **Alternates** typically only return multiple routes for driving on roads
  with realistic alternatives — walking usually returns a single route.
- **No cancel handle**: a new `calculate` call doesn't cancel an in-flight one.
  Responses arrive in whatever order Apple's servers return them, so if you
  fire requests rapidly (e.g. while the user is moving sliders) implement your
  own "latest-wins" guard.
- **`departureDate` and `arrivalDate` are mutually exclusive**: if both are
  provided, `departureDate` wins; `arrivalDate` is ignored.



---
url: /guide/Changelog/3.1.0/MapKit/MapDirections/index_example.md
---

# 

***

title: Example
description: MapKit route planning: `calculate(...)` for full routes and `calculateETA(...)` for travel time only.
tag: PRO
--------

```tsx
import {
  Button, HStack, Map, MapPolyline, Marker, Navigation, NavigationStack, Picker,
  Script, ScrollView, Text, useEffect, useObservable, useState, VStack,
} from "scripting"

// Shanghai landmarks used across the demos.
const PEOPLES_SQUARE = { latitude: 31.2304, longitude: 121.4737 }
const BUND = { latitude: 31.2407, longitude: 121.4905 }
const LUJIAZUI = { latitude: 31.2397, longitude: 121.4994 }

const initialRegion = {
  center: { latitude: 31.2354, longitude: 121.4905 },
  span: { latitudeDelta: 0.04, longitudeDelta: 0.04 },
}

// Phase 3e: distance / duration formatting delegates to MapUtils, which wraps
// MKDistanceFormatter / DateComponentsFormatter so the output respects the
// device locale.
const fmtDistance = (meters: number) => MapUtils.formatDistance(meters)
const fmtDuration = (seconds: number) => MapUtils.formatDuration(seconds)

// ───────────────────────────────────────────────────────────────────────
// Demo 1: calculate a single route and render the polyline
// ───────────────────────────────────────────────────────────────────────
function SingleRouteDemo() {
  // Phase 3g: 拿到完整 response 而不是单挑 route — 这样 source / destination 的
  // MapItem 可以直接喂给 <Marker item={...}>,触发 Apple 的 auto POI glyph。
  const [resp, setResp] = useState<MapDirections.DirectionsResponse | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  const route = resp?.routes[0] ?? null

  const calc = async () => {
    setLoading(true); setErr(null)
    try {
      const r = await MapDirections.calculate({
        source: { coordinate: PEOPLES_SQUARE, name: "People's Square" },
        destination: { coordinate: LUJIAZUI, name: "Lujiazui" },
        transportType: "automobile",
      })
      setResp(r)
      const fit = MapUtils.regionFromCoordinates(r.routes[0].coordinates, 0.2)
      if (fit) position.setValue(MapCameraPosition.region(fit))
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>1. Calculate + render</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`Drive from People's Square to Lujiazui. The returned \`route.coordinates\` polyline
      feeds straight into \`<MapPolyline coordinates={...}>\`; the response's
      \`source\` / \`destination\` MapItems are dropped into \`<Marker item={...}>\`
      so MapKit picks the POI glyph automatically.`}
    </Text>
    <HStack spacing={8}>
      <Button title={loading ? "Calculating..." : "Calculate"} action={calc} />
      {route != null
        ? <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {fmtDistance(route.distance)} · {fmtDuration(route.expectedTravelTime)} · {route.steps.length} steps
        </Text>
        : null}
    </HStack>
    {err != null
      ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text>
      : null}
    <Map
      cameraPosition={position}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {resp != null
        ? <>
          {/* MapItem 形态:title / coordinate / glyph 都由 MapKit 自己挑。 */}
          <Marker item={resp.source} tint="systemGreen" />
          <Marker item={resp.destination} tint="systemRed" />
        </>
        : <>
          {/* 路线还没算出来时回落到坐标形态。 */}
          <Marker title="Start" coordinate={PEOPLES_SQUARE} tint="systemGreen" />
          <Marker title="End" coordinate={LUJIAZUI} tint="systemRed" />
        </>}
      {route != null
        ? <MapPolyline
          coordinates={route.coordinates}
          strokeColor="systemBlue"
          strokeStyle={{ lineWidth: 4, lineCap: "round", lineJoin: "round" }}
        />
        : null}
    </Map>
  </VStack>
}

// ───────────────────────────────────────────────────────────────────────
// Demo 2: switch transportType and watch the route change shape / length
// ───────────────────────────────────────────────────────────────────────
function TransportTypeDemo() {
  type Mode = "automobile" | "walking"
  const [mode, setMode] = useState<Mode>("walking")
  const [resp, setResp] = useState<MapDirections.DirectionsResponse | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  const route = resp?.routes[0] ?? null

  useEffect(() => {
    let cancelled = false
    setLoading(true); setErr(null)
    MapDirections.calculate({
      source: { coordinate: BUND, name: "Bund" },
      destination: { coordinate: LUJIAZUI, name: "Lujiazui" },
      transportType: mode,
    }).then(r => {
      if (cancelled) return
      setResp(r)
      const fit = MapUtils.regionFromCoordinates(r.routes[0].coordinates, 0.2)
      if (fit) position.setValue(MapCameraPosition.region(fit))
    }).catch(e => {
      if (cancelled) return
      setErr(String(e))
    }).finally(() => {
      if (!cancelled) setLoading(false)
    })
    return () => { cancelled = true }
  }, [mode])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>2. transportType switch</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Same start/end (Bund → Lujiazui) but different transport mode. Driving prefers
      bridges + roads; walking takes a much more direct path.
    </Text>
    <Picker
      title="Mode"
      value={mode}
      onChanged={(v: any) => setMode(v as Mode)}
      pickerStyle={"segmented"}
    >
      <Text tag={"automobile"}>automobile</Text>
      <Text tag={"walking"}>walking</Text>
    </Picker>
    {loading ? <Text font={"caption2"}>Calculating...</Text> : null}
    {err != null ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text> : null}
    {route != null
      ? <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
        {route.transportType} · {fmtDistance(route.distance)} · {fmtDuration(route.expectedTravelTime)}
      </Text>
      : null}
    <Map
      cameraPosition={position}
      frame={{ height: 260 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {resp != null
        ? <>
          <Marker item={resp.source} tint="systemRed" />
          <Marker item={resp.destination} tint="systemPurple" />
        </>
        : <>
          <Marker title="Bund" coordinate={BUND} tint="systemRed" />
          <Marker title="Lujiazui" coordinate={LUJIAZUI} tint="systemPurple" />
        </>}
      {route != null
        ? <MapPolyline
          coordinates={route.coordinates}
          strokeColor={mode === "walking" ? "systemTeal" : "systemBlue"}
          strokeStyle={{ lineWidth: 4, lineCap: "round" }}
        />
        : null}
    </Map>
  </VStack>
}

// ───────────────────────────────────────────────────────────────────────
// Demo 3: alternates — render multiple routes side by side
// ───────────────────────────────────────────────────────────────────────
const ALTERNATE_COLORS = ["systemBlue", "systemOrange", "systemPurple"] as const

function AlternatesDemo() {
  const [resp, setResp] = useState<MapDirections.DirectionsResponse | null>(null)
  // 选中的 route 在地图上 stroke 加粗 + 不透明,未选中的回落到细 + 半透明,
  // 视觉上把"导航选了哪条"立刻表达清楚。
  const [selectedIdx, setSelectedIdx] = useState(0)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  const routes = resp?.routes ?? []

  const calc = async () => {
    setLoading(true); setErr(null)
    try {
      const r = await MapDirections.calculate({
        source: { coordinate: PEOPLES_SQUARE, name: "People's Square" },
        destination: { coordinate: LUJIAZUI, name: "Lujiazui" },
        transportType: "automobile",
        requestsAlternateRoutes: true,
      })
      setResp(r)
      setSelectedIdx(0)
      const allCoords = r.routes.flatMap(rt => rt.coordinates)
      const fit = MapUtils.regionFromCoordinates(allCoords, 0.2)
      if (fit) position.setValue(MapCameraPosition.region(fit))
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>3. Alternates + selection</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`\`requestsAlternateRoutes: true\` may return up to 3 driving routes. Tap a row
      below to highlight that route — the selected polyline renders thicker and
      fully opaque, others fade to make the choice obvious.`}
    </Text>
    <HStack spacing={8}>
      <Button title={loading ? "Calculating..." : "Calculate (with alternates)"} action={calc} />
    </HStack>
    {err != null ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text> : null}
    <VStack alignment={"leading"} spacing={4}>
      {routes.map((r, i) => {
        const isSelected = i === selectedIdx
        const color = ALTERNATE_COLORS[i % ALTERNATE_COLORS.length]
        return <Button
          key={i}
          action={() => setSelectedIdx(i)}
          buttonStyle={isSelected ? "borderedProminent" : "bordered"}
          tint={color}
        >
          <HStack spacing={8}>
            <Text font={"caption"} foregroundStyle={isSelected ? "white" : color}>
              {`${i + 1}. ${r.name || "(unnamed)"}`}
            </Text>
            <Text font={"caption2"} foregroundStyle={isSelected ? "white" : "secondaryLabel"}>
              {`${fmtDistance(r.distance)} · ${fmtDuration(r.expectedTravelTime)}`}
            </Text>
          </HStack>
        </Button>
      })}
    </VStack>
    <Map
      cameraPosition={position}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {resp != null
        ? <>
          <Marker item={resp.source} tint="systemGreen" />
          <Marker item={resp.destination} tint="systemRed" />
        </>
        : <>
          <Marker title="Start" coordinate={PEOPLES_SQUARE} tint="systemGreen" />
          <Marker title="End" coordinate={LUJIAZUI} tint="systemRed" />
        </>}
      {/* 未选中的先画(细),选中的最后画压在上面(粗)。MapPolyline 目前不接收
          opacity / 视图层 modifier,这里用 stroke width(3 vs 6)制造主次对比。 */}
      {routes.map((r, i) => {
        if (i === selectedIdx) return null
        return <MapPolyline
          key={`alt-${i}`}
          coordinates={r.coordinates}
          strokeColor={ALTERNATE_COLORS[i % ALTERNATE_COLORS.length]}
          strokeStyle={{ lineWidth: 3, lineCap: "round" }}
        />
      })}
      {routes[selectedIdx] != null
        ? <MapPolyline
          key={`sel-${selectedIdx}`}
          coordinates={routes[selectedIdx].coordinates}
          strokeColor={ALTERNATE_COLORS[selectedIdx % ALTERNATE_COLORS.length]}
          strokeStyle={{ lineWidth: 6, lineCap: "round", lineJoin: "round" }}
        />
        : null}
    </Map>
  </VStack>
}

// ───────────────────────────────────────────────────────────────────────
// Demo 4: calculateETA — time / distance only, no geometry download
// ───────────────────────────────────────────────────────────────────────
function ETADemo() {
  type Mode = "automobile" | "walking"
  const [mode, setMode] = useState<Mode>("automobile")
  const [eta, setEta] = useState<MapDirections.ETAResponse | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)

  const calc = async () => {
    setLoading(true); setErr(null)
    try {
      const result = await MapDirections.calculateETA({
        source: { coordinate: PEOPLES_SQUARE, name: "People's Square" },
        destination: { coordinate: LUJIAZUI, name: "Lujiazui" },
        transportType: mode,
        departureDate: new Date(),
      })
      setEta(result)
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>4. `calculateETA`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Skip the polyline download; get back travel time / distance / arrival window only.
      Cheaper than `calculate` when the UI just needs a headline number.
    </Text>
    <Picker
      title="Mode"
      value={mode}
      onChanged={(v: any) => setMode(v as Mode)}
      pickerStyle={"segmented"}
    >
      <Text tag={"automobile"}>automobile</Text>
      <Text tag={"walking"}>walking</Text>
    </Picker>
    <HStack spacing={8}>
      <Button title={loading ? "Calculating..." : "Calculate ETA"} action={calc} />
    </HStack>
    {err != null ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text> : null}
    {eta != null
      ? <VStack alignment={"leading"} spacing={2}>
        <Text font={"caption"}>{`Travel: ${fmtDuration(eta.expectedTravelTime)}`}</Text>
        <Text font={"caption"}>{`Distance: ${fmtDistance(eta.distance)}`}</Text>
        <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>
          {`Depart: ${eta.expectedDepartureDate.toLocaleTimeString()}`}
        </Text>
        <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>
          {`Arrive: ${eta.expectedArrivalDate.toLocaleTimeString()}`}
        </Text>
      </VStack>
      : null}
  </VStack>
}

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Directions"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"MapDirections"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={20}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`\`MapDirections.calculate(...)\` returns route polylines that plug straight into
          \`<MapPolyline coordinates={...}>\`. \`MapDirections.calculateETA(...)\` returns
          time / distance only — handy when you don't need the geometry. No system
          permissions required.`}
        </Text>
        <SingleRouteDemo />
        <TransportTypeDemo />
        <AlternatesDemo />
        <ETADemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/MapKit/MapLookAround/index.md
---

# MapLookAround

`MapLookAround` resolves a LookAround (street-level) scene reference for a
coordinate. Pair with the `<LookAroundPreview>` view to render the scene
interactively.

```tsx
import { LookAroundPreview, useEffect, useState } from "scripting"

function Example() {
  const [scene, setScene] = useState<MapLookAroundScene | null>(null)
  useEffect(() => {
    MapLookAround.request({ latitude: 37.3349, longitude: -122.0090 })
      .then(setScene)
  }, [])
  return <LookAroundPreview scene={scene} frame={{ height: 240 }} />
}
```

***

## `request` — fetch a scene

```ts
const scene = await MapLookAround.request({
  latitude: 31.2397,
  longitude: 121.4994,
})
if (scene == null) {
  // No street view available at this location.
}
```

`scene` is an opaque handle backed by `MKLookAroundScene`. Two readable fields
in JS:

| Member       | Type            | Description                                   |
| ------------ | --------------- | --------------------------------------------- |
| `coordinate` | `MapCoordinate` | Anchor coordinate the scene was requested at. |

## `<LookAroundPreview scene>` — render the scene

| Prop               | Type                                                 | Default        | Description                                                 |
| ------------------ | ---------------------------------------------------- | -------------- | ----------------------------------------------------------- |
| `scene`            | `MapLookAroundScene \| null`                         | —              | Scene to render. `null` shows a placeholder.                |
| `showsRoadLabels`  | `boolean?`                                           | `true`         | Overlay street / road names.                                |
| `allowsNavigation` | `boolean?`                                           | `true`         | Allow tapping to expand into the full-screen viewer.        |
| `badgePosition`    | `"topLeading" \| "topTrailing" \| "bottomTrailing"?` | `"topLeading"` | Position of Apple's "Look Around" badge inside the preview. |

The component also accepts all standard layout / framing modifiers
(`frame={...}`, `padding`, `clipShape`, etc.).

## Notes

- LookAround coverage skews to major US / EU / JP / KR cities; many locations
  resolve to `null`. Always handle the null branch in your UI.
- The view uses Apple's interactive preview internally — you can't add custom
  overlays or annotations on top.
- A scene reference stays valid while the JS context lives; you don't need to
  dispose it.



---
url: /guide/Changelog/3.1.0/MapKit/MapLookAround/index_example.md
---

# Example

```tsx
import {
  Button, HStack, LookAroundPreview, MapCoordinate, Navigation, NavigationStack, Picker,
  Script, ScrollView, Text, useEffect, useState, VStack,
} from "scripting"

const SPOTS: Record<string, { name: string; coordinate: MapCoordinate }> = {
  apple_park: { name: "Apple Park", coordinate: { latitude: 37.3349, longitude: -122.0090 } },
  bund: { name: "Bund, Shanghai", coordinate: { latitude: 31.2407, longitude: 121.4905 } },
  shibuya: { name: "Shibuya Crossing", coordinate: { latitude: 35.6595, longitude: 139.7005 } },
  sahara: { name: "Sahara (no coverage)", coordinate: { latitude: 23.0, longitude: 12.0 } },
}

type Spot = keyof typeof SPOTS

function Example() {
  const [spot, setSpot] = useState<Spot>("apple_park")
  const [scene, setScene] = useState<MapLookAroundScene | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)

  // Re-request whenever the picker selection changes.
  useEffect(() => {
    let cancelled = false
    setLoading(true); setErr(null); setScene(null)
    MapLookAround.request(SPOTS[spot].coordinate)
      .then(s => { if (!cancelled) setScene(s) })
      .catch(e => { if (!cancelled) setErr(String(e)) })
      .finally(() => { if (!cancelled) setLoading(false) })
    return () => { cancelled = true }
  }, [spot])

  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map LookAround"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"LookAround"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={16}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`MapLookAround.request({ latitude, longitude }) resolves a
          MapLookAroundScene reference (or null when there's no street-level
          coverage). Feed the result into <LookAroundPreview scene> to render.`}
        </Text>

        <Picker
          title="Spot"
          value={spot}
          onChanged={(v: any) => setSpot(v as Spot)}
          pickerStyle={"segmented"}
        >
          {(Object.keys(SPOTS) as Spot[]).map(key =>
            <Text key={key} tag={key}>{SPOTS[key].name}</Text>
          )}
        </Picker>

        <HStack spacing={8}>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            {SPOTS[spot].name}
          </Text>
          {loading ? <Text font={"caption2"}>Loading...</Text> : null}
          {scene == null && !loading && err == null
            ? <Text font={"caption2"} foregroundStyle={"systemOrange"}>
              No street view at this location.
            </Text>
            : null}
        </HStack>
        {err != null
          ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text>
          : null}

        <LookAroundPreview
          scene={scene}
          showsRoadLabels
          frame={{ height: 240 }}
          clipShape={{ type: "rect", cornerRadius: 12 }}
        />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/MapKit/MapSearch/index.md
---

# 

***

title: MapSearch
description: MapKit keyword search: one-shot `locate(...)` and stateful autocomplete via `createCompleter(...)`.

***

`MapSearch` runs MapKit's on-device keyword search. Two entry points:

- `MapSearch.locate(options)` — one-shot search, returns `MapItem[]`.
- `MapSearch.createCompleter(options?)` — stateful autocomplete, designed for
  text-input fields. Delivers suggestions via listener callbacks.

Both are pure query APIs and require **no system permissions**. Coordinates are
returned as `MapCoordinate`, so results plug straight into `<Marker>` /
`<Map>` from the views layer.

Forward / reverse geocoding (address ↔ coordinates) lives on the existing
`Location` namespace (`Location.geocodeAddress`, `Location.reverseGeocode`).

***

## `locate` — one-shot search

```ts
const items = await MapSearch.locate({
  query: "coffee",
  region: {
    center: { latitude: 31.2304, longitude: 121.4737 },
    span: { latitudeDelta: 0.02, longitudeDelta: 0.02 },
  },
})

for (const item of items) {
  console.log(item.name, item.coordinate, item.formattedAddress)
}
```

### Options

| Option                  | Type                                                       | Description                                                                                                                   |
| ----------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`                                                   | Required. Non-empty search term.                                                                                              |
| `region`                | `MapRegion?`                                               | Restrict the search to a region. Omit to use a wide area around the device's last known coarse location.                      |
| `resultTypes`           | `("pointOfInterest" \| "address" \| "physicalFeature")[]?` | Default: `["pointOfInterest", "address"]`. `physicalFeature` is iOS 18+ — silently ignored on older systems.                  |
| `pointOfInterestFilter` | `MapPointsOfInterestSpec?`                                 | Same shape as `<Map mapStyle={{ pointsOfInterest }}>`. Use `"excludingAll"`, `{ includes: [...] }`, or `{ excludes: [...] }`. |

### Result — `MapItem`

`MapItem` is a top-level opaque class (also returned by `MapDirections`). Read
fields by name; do not try to serialize the instance directly.

| Field                     | Type                | Description                                                                                                             |
| ------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `coordinate`              | `MapCoordinate`     | Always present.                                                                                                         |
| `name`                    | `string \| null`    | "Apple Park Visitor Center"                                                                                             |
| `formattedAddress`        | `string \| null`    | "10600 N Tantau Ave, Cupertino, CA, United States"                                                                      |
| `placemark`               | `LocationPlacemark` | Always present.                                                                                                         |
| `phoneNumber`             | `string \| null`    |                                                                                                                         |
| `url`                     | `string \| null`    |                                                                                                                         |
| `pointOfInterestCategory` | `string \| null`    | `"restaurant"` / `"cafe"` / ...                                                                                         |
| `timeZone`                | `string \| null`    | `"America/Los_Angeles"`                                                                                                 |
| `isCurrentLocation`       | `boolean`           | `true` only when MapKit handed back the device's current-location item; search / directions results are always `false`. |

### `openInMaps(options?)` — hand off to Apple Maps

```ts
const items = await MapSearch.locate({ query: "coffee" })
if (items.length > 0) {
  await items[0].openInMaps({ directionsMode: "walking" })
}
```

Resolves with `true` when the system accepted the launch request. The current
app moves to the background while Apple Maps takes over.

| Option           | Type                                               | Description                                                                                          |
| ---------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `directionsMode` | `"driving" \| "walking" \| "transit" \| "default"` | Show directions on the opened map. `"default"` lets Apple Maps pick the mode based on user settings. |
| `showsTraffic`   | `boolean`                                          | Show live traffic overlay.                                                                           |
| `mapType`        | `"standard" \| "satellite" \| "hybrid"`            | Map type to apply.                                                                                   |

> `JSON.stringify(item)` and `Object.keys(item)` will not return the field
> dictionary — `MapItem` is a class with getters, not a plain object. Spread the
> fields yourself if you need a serializable snapshot.

### Geometry helpers

```ts
item.distance(other)  // meters, Haversine; `other` is a coordinate or another MapItem
item.bearing(other)   // degrees [0, 360), 0 = north
```

Both delegate to `MapUtils.distance` / `MapUtils.bearing`.

### `MapItem.forCurrentLocation()`

Apple's placeholder MapItem for "the device's current location". Synchronous,
no permission prompt, no coordinate fetched locally — Apple Maps interprets the
sentinel when handed to `openInMaps()`.

```ts
await MapItem.forCurrentLocation().openInMaps({ directionsMode: "walking" })
```

Returned items satisfy `isCurrentLocation === true`.

***

## Selecting markers and built-in POIs — `<Map selection>`

Bind an observable of `MapSelectionValue | null` to `<Map selection>`. The
written value is a tagged union:

| `value.type` | Source                                      | Shape                                                                   |
| ------------ | ------------------------------------------- | ----------------------------------------------------------------------- |
| `"marker"`   | A `<Marker tag>` you rendered               | `{ type: "marker", tag: string }`                                       |
| `"feature"`  | An Apple-rendered built-in POI / landmark   | `{ type: "feature", coordinate, title, kind, pointOfInterestCategory }` |
| `null`       | Empty map background was tapped, or initial | —                                                                       |

```tsx
const selection = useObservable<MapSelectionValue | null>(null)
const items: MapItem[] = ...

return <Map cameraPosition={cam} selection={selection}>
  {items.map((item, i) => (
    <Marker item={item} tag={`hit-${i}`} />
  ))}
</Map>
```

Branch on `value.type` to handle each case:

```ts
const sel = selection.value
if (sel == null) {
  // Background tap
} else if (sel.type === "marker") {
  const item = items.find((_, i) => `hit-${i}` === sel.tag)
  // ... use your MapItem
} else {
  // sel.type === "feature" — an Apple POI
  // sel.coordinate, sel.title, sel.pointOfInterestCategory
}
```

`kind` is one of `"pointOfInterest"` / `"physicalFeature"` / `"territory"` /
`"unknown"`. `pointOfInterestCategory` uses the same vocabulary as
`MapPointOfInterestCategory` (e.g. `"restaurant"`, `"cafe"`) and is `null` when
the feature has no category.

Markers without a `tag` are not selectable.

### iOS 17 limitation

On iOS 17, only `type: "feature"` is reported — tapping a tagged `<Marker>`
does **not** fire selection. The unified marker/feature selection requires
iOS 18+ (`MapSelection<Value>`). If your script targets iOS 17 devices, design
around feature taps for POI selection and treat marker selection as iOS 18+ only.

***

## Item selection + Apple's auto detail cards — `<Map itemSelection>`

iOS 18+ adds a higher-level path: bind `<Map itemSelection>` to an
`Observable<MapItem | null>` and pair `<Marker item={mapItem}>` markers with
Apple's built-in detail card via `<Map itemDetailSelectionAccessory>` /
`<Map featureSelectionAccessory>`.

```tsx
const selected = useObservable<MapItem | null>(null)
const items: MapItem[] = ...

return <Map
  cameraPosition={cam}
  itemSelection={selected}
  itemDetailSelectionAccessory="automatic"
  featureSelectionAccessory="automatic"
>
  {items.map(item => (
    <Marker item={item} tint={selected.value === item ? "systemRed" : "systemBlue"} />
  ))}
</Map>
```

- Tapping `<Marker item>` writes that exact `MapItem` instance into the
  observable. Compare with `===` to find the picked item (the JS side keeps
  reference identity through MapKit selection).
- Apple's auto card pops up automatically:
  - `itemDetailSelectionAccessory` — card for tapped item markers (e.g.,
    address, phone, "Directions" button).
  - `featureSelectionAccessory` — card for tapped Apple-rendered POI labels.
- Style values: `"automatic"` (MapKit picks callout vs sheet), `"callout"`,
  `"sheet"`. Pass `null` (or omit the prop) to disable.

> **Nested presentation caveat**: `"automatic"` and `"sheet"` use a modal
> sheet presentation (`MKPresentableSelectionAccessoryViewController`).
> Inside `Navigation.present(...)`-style modal contexts the presentation
> chain conflicts with the parent modal — iOS 18 currently aborts the
> second tap with `Attempt to present ... which is already presenting`,
> and in some cases dismisses the parent modal entirely. Prefer
> `"callout"` (inline anchored bubble, no modal presentation) when the
> map lives inside a presented sheet or `Navigation.present` page.

`itemSelection` is mutually exclusive with `selection`: if both are set,
`itemSelection` wins and string-tag markers do not fire.

### iOS 17 limitation

`itemSelection`, `itemDetailSelectionAccessory`, and `featureSelectionAccessory`
are all iOS 18+. On iOS 17 the props are silently ignored — the map renders,
markers display, but tapping does not write to `itemSelection` and no
Apple-styled card appears.

### Cancellation note

`locate` does not expose a cancellation handle. For typeahead scenarios use
`createCompleter` instead — repeated `locate` calls do not deduplicate stale
responses and a fast typist can see results arrive out of order.

***

## `createCompleter` — autocomplete

```ts
const completer = MapSearch.createCompleter({
  region: { ... },
  resultTypes: ["address", "pointOfInterest", "query"],
})

completer.addListener(suggestions => {
  setOptions(suggestions)
})

completer.setQuery("apple")
// ...later, when the user taps a suggestion:
const items = await completer.resolve(selected)
```

### Options

| Option        | Type                                             | Description                                                                                                                                                            |
| ------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region`      | `MapRegion?`                                     | Bias suggestions toward a region. Can be changed later via `completer.setRegion(...)`.                                                                                 |
| `resultTypes` | `("pointOfInterest" \| "address" \| "query")[]?` | Default: `["pointOfInterest", "address"]`. Note `"query"` is only valid on the completer (offers query-completion suggestions); `"physicalFeature"` is not valid here. |

### Methods

| Method                | Description                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `setQuery(query)`     | Update the search fragment. Triggers a new round of suggestions.                                 |
| `setRegion(region)`   | Update the bias region.                                                                          |
| `addListener(fn)`     | Subscribe to suggestion batches. Each call replaces the previous batch — no diff merging needed. |
| `removeListener(fn?)` | Remove one listener, or all listeners when called without arguments.                             |
| `resolve(completion)` | Look up the full `MapItem[]` for a tapped suggestion.                                            |
| `dispose()`           | Release the underlying completer. Idempotent — safe to call multiple times.                      |

### Lifecycle

One completer corresponds to one input field — sharing a completer between
unrelated fields will cross-contaminate results because the underlying
`queryFragment` is single-valued. Call `dispose()` when the field unmounts.

### Suggestion lifetime

A `MapSearchCompletion`'s `id` is only valid until the completer issues its
next batch of suggestions. Resolving a stale suggestion rejects with
`"unknown completion id"`. In React-style UIs, store the array of suggestions
in state alongside the user's selection so the chosen suggestion's `id` is
always paired with the batch it came from.

***

## Combining with `<Map>`

Hand the whole `MapItem` to `<Marker>` and MapKit fills in title, coordinate,
and a POI-category-driven glyph for you:

```tsx
{items.map(item => (
  <Marker item={item} tint="systemBlue" />
))}
```

If you also pass `title` / `systemImage` / `monogram`, the marker reverts to
the default pin (or your specified glyph) and uses your override — auto-glyph
selection only applies when none of those are given. The two forms are mutually
exclusive in the type system: passing both `item` and `coordinate` is a
compile-time error.

```tsx
// item + custom glyph — your systemImage wins, title still defaults to item.name
<Marker item={mapItem} systemImage="cup.and.saucer.fill" tint="systemRed" />

// coordinate form — you supply everything
<Marker title="Bund" coordinate={{ latitude: 31.24, longitude: 121.49 }} />
```

To fit the map around the result set, use `MapUtils.regionFromCoordinates`:

```ts
const region = MapUtils.regionFromCoordinates(items.map(i => i.coordinate))
if (region) position.setValue({ region })
```

***

## Errors

`locate` rejects when:

- `query` is missing or empty
- The underlying `MKLocalSearch` fails (network, no results, etc.)

`completer.resolve` rejects when:

- The completion id is stale (next batch invalidated it)
- The underlying `MKLocalSearch` lookup fails

The completer's listener never receives a synchronous error; on backend
failure the listener is called with an empty array.



---
url: /guide/Changelog/3.1.0/MapKit/MapSearch/index_example.md
---

# 

***

title: Example
description: MapKit keyword search: one-shot `locate(...)` and stateful autocomplete via `createCompleter(...)`.

***

```tsx
import {
  Button, HStack, Map, Marker, Navigation, NavigationStack,
  Script, ScrollView, Text, TextField, useEffect, useMemo, useObservable, useRef,
  useState, VStack,
} from "scripting"

// Demo center: People's Square, Shanghai
const initialRegion = {
  center: { latitude: 31.2304, longitude: 121.4737 },
  span: { latitudeDelta: 0.05, longitudeDelta: 0.05 },
}

function LocateDemo() {
  const [query, setQuery] = useState("coffee")
  const [items, setItems] = useState<MapItem[]>([])
  const [isLoading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)

  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  // Phase 3h: <Map itemSelection> binds the tapped MapItem directly.
  // Apple's `itemDetailSelectionAccessory` shows the auto-generated detail card.
  // Apple POI taps are handled by `featureSelectionAccessory` (also auto card)
  // and don't fire this observable. iOS 17 silently no-ops on both.
  const selectedItem = useObservable<MapItem | null>(null)

  const search = async () => {
    setLoading(true)
    setErr(null)
    selectedItem.setValue(null)
    try {
      const result = await MapSearch.locate({
        query,
        region: initialRegion,
        resultTypes: ["pointOfInterest"],
      })
      setItems(result)
      // Auto-fit the map around the results.
      const fit = MapUtils.regionFromCoordinates(result.map(i => i.coordinate))
      if (fit) position.setValue(MapCameraPosition.region(fit))
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  // Hand the first result off to Apple Maps with walking directions overlaid.
  const openFirstInMaps = async () => {
    const first = items[0]
    if (!first) return
    await first.openInMaps({ directionsMode: "walking", showsTraffic: true })
  }

  // forCurrentLocation() returns Apple's placeholder MapItem that
  // resolves to the device's location inside Apple Maps — no permission needed.
  const openCurrentInMaps = () => MapItem.forCurrentLocation().openInMaps()

  // Distance from the search center to the selected marker, via MapItem.distance.
  const selected = selectedItem.value
  const selectedDistance = selected != null
    ? MapUtils.formatDistance(selected.distance(initialRegion.center))
    : null

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>1. `MapSearch.locate` + selection</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`One-shot search for points of interest near People's Square. Each hit
      drops into a \`<Marker item={item}>\`. Tapping (iOS 18+) writes the
      tapped MapItem into \`itemSelection\` and Apple shows its built-in
      detail card via \`itemDetailSelectionAccessory\`. Tapping an Apple-rendered
      POI label shows the same auto card via \`featureSelectionAccessory\`.`}
    </Text>
    <TextField
      title="query"
      value={query}
      onChanged={setQuery}
      prompt="Search keyword"
    />
    <HStack spacing={8}>
      <Button title={isLoading ? "Searching..." : "Search"} action={search} />
      <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
        {items.length} hits
      </Text>
    </HStack>
    {items.length > 0
      ? <Button
        title={`Open "${items[0].name ?? "first hit"}" in Maps`}
        buttonStyle="bordered"
        action={openFirstInMaps}
      />
      : null}
    <Button
      title="Open current location in Maps"
      buttonStyle="bordered"
      action={openCurrentInMaps}
    />
    {selected != null
      ? <VStack alignment={"leading"} spacing={2}>
        <Text font={"caption"} foregroundStyle={"systemBlue"}>
          Selected: {selected.name ?? "(unnamed)"}
        </Text>
        {selected.formattedAddress != null
          ? <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>
            {selected.formattedAddress}
          </Text>
          : null}
        {selectedDistance != null
          ? <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
            {selectedDistance} from search center
          </Text>
          : null}
      </VStack>
      : null}
    {err != null
      ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text>
      : null}
    <Map
      cameraPosition={position}
      itemSelection={selectedItem}
      // `"callout"` is an inline anchored bubble — does not trigger a sheet
      // presentation. Safe inside `Navigation.present`-style nested modals.
      // `"automatic"` / `"sheet"` may conflict with the parent modal chain
      // (iOS 18 currently aborts with "already presenting" — see Phase 3h docs).
      itemDetailSelectionAccessory="callout"
      featureSelectionAccessory="callout"
      frame={{ height: 280 }}
      clipShape={{ type: 'rect', cornerRadius: 12 }}
    >
      {items.map(item => (
        // Item-based marker — MapKit picks the POI glyph and uses item.name
        // as the marker title. The same MapItem reference is what itemSelection
        // observes when the user taps the marker.
        <Marker
          item={item}
          tint={selected === item ? "systemRed" : "systemBlue"}
        />
      ))}
    </Map>
  </VStack>
}

function CompleterDemo() {
  const [query, setQuery] = useState("")
  const [suggestions, setSuggestions] = useState<MapSearch.MapSearchCompletion[]>([])
  const [resolved, setResolved] = useState<MapItem[]>([])
  const [resolveErr, setResolveErr] = useState<string | null>(null)

  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  // Hold the completer in a ref so it survives re-renders.
  const completerRef = useRef<ReturnType<typeof MapSearch.createCompleter> | null>(null)

  useEffect(() => {
    const c = MapSearch.createCompleter({
      region: initialRegion,
      resultTypes: ["pointOfInterest", "address"],
    })
    completerRef.current = c
    const listener = (suggs: MapSearch.MapSearchCompletion[]) => {
      setSuggestions(suggs)
    }
    c.addListener(listener)
    return () => {
      c.removeListener(listener)
      c.dispose()
      completerRef.current = null
    }
  }, [])

  const onQueryChange = (text: string) => {
    setQuery(text)
    completerRef.current?.setQuery(text)
  }

  const onPickSuggestion = async (s: MapSearch.MapSearchCompletion) => {
    setResolveErr(null)
    try {
      const items = await completerRef.current!.resolve(s)
      setResolved(items)
      const fit = MapUtils.regionFromCoordinates(items.map(i => i.coordinate))
      if (fit) position.setValue(MapCameraPosition.region(fit))
    } catch (e) {
      setResolveErr(String(e))
    }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>2. `MapSearch.createCompleter`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Stateful autocomplete. Type and watch suggestions update live. Tap one to
      resolve it to `MapItem[]` and drop the hits on the map.
    </Text>
    <TextField
      title="query"
      value={query}
      onChanged={onQueryChange}
      prompt="Start typing..."
    />
    <VStack alignment={"leading"} spacing={4}>
      {suggestions.slice(0, 6).map(s => (
        <Button
          title={s.title + (s.subtitle ? ` — ${s.subtitle}` : "")}
          buttonStyle="bordered"
          action={() => onPickSuggestion(s)}
        />
      ))}
    </VStack>
    {resolveErr != null
      ? <Text font={"caption"} foregroundStyle={"systemRed"}>{resolveErr}</Text>
      : null}
    <Map
      cameraPosition={position}
      frame={{ height: 240 }}
      clipShape={{ type: 'rect', cornerRadius: 12 }}
    >
      {resolved.map(item => (
        <Marker item={item} tint="systemRed" />
      ))}
    </Map>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      Note: a completion's `id` is invalidated by the next suggestion batch — pick
      from the current list, not a stale state snapshot.
    </Text>
  </VStack>
}

function POIFilterDemo() {
  const [items, setItems] = useState<MapItem[]>([])
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  const run = async (filter: any, label: string) => {
    const result = await MapSearch.locate({
      query: "shop",
      region: initialRegion,
      pointOfInterestFilter: filter,
    })
    setItems(result)
    const fit = MapUtils.regionFromCoordinates(result.map(i => i.coordinate))
    if (fit) position.setValue(MapCameraPosition.region(fit))
    console.log(`${label}: ${result.length} hits`)
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>3. `pointOfInterestFilter`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`Restrict POI categories in search results. Same \`MapPointsOfInterestSpec\`
      union accepted by \`<Map mapStyle>\`.`}
    </Text>
    <HStack spacing={8}>
      <Button
        title="cafe + restaurant only"
        buttonStyle="bordered"
        action={() => run({ includes: ["cafe", "restaurant"] }, "includes")}
      />
      <Button
        title="exclude gasStation"
        buttonStyle="bordered"
        action={() => run({ excludes: ["gasStation"] }, "excludes")}
      />
    </HStack>
    <Map
      cameraPosition={position}
      frame={{ height: 240 }}
      clipShape={{ type: 'rect', cornerRadius: 12 }}
    >
      {items.map(item => (
        <Marker item={item} tint="systemGreen" />
      ))}
    </Map>
  </VStack>
}

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Search"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"MapSearch"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={24}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          MapKit on-device search. No permissions required — coordinates can flow
          directly into `Marker` / `Map` from the views layer. For typeahead UIs,
          prefer `createCompleter` over polling `locate` on every keystroke.
        </Text>

        <LocateDemo />
        <CompleterDemo />
        <POIFilterDemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/MapKit/MapSnapshotter/index.md
---

# MapSnapshotter

`MapSnapshotter` renders a static map image offscreen via MapKit. Useful when
you need a map picture without a live `<Map>` view — widget previews,
share-sheet thumbnails, exported reports, or any place SwiftUI's `Map` isn't
available.

```tsx
const snap = await MapSnapshotter.take({
  region: {
    center: { latitude: 31.2407, longitude: 121.4905 },
    span: { latitudeDelta: 0.02, longitudeDelta: 0.02 },
  },
  size: { width: 320, height: 200 },
})

// snap.image is a UIImage — feed it straight into <Image>.
return <Image image={snap.image} />
```

***

## `take` — render a snapshot

### Options

| Option       | Type                                | Description                                                                         |
| ------------ | ----------------------------------- | ----------------------------------------------------------------------------------- |
| `region`     | `MapRegion?`                        | Region to capture. Mutually exclusive with `camera`.                                |
| `camera`     | `MapCamera?`                        | Eye-style framing (`MapCamera.make(...)`). Wins over `region` if both are supplied. |
| `size`       | `{ width: number; height: number }` | Required. Output dimensions in points; both > 0.                                    |
| `scale`      | `number?`                           | Pixel scale factor. Default = device main screen scale.                             |
| `mapStyle`   | `MapStyleSpec?`                     | Same shape as `<Map mapStyle>`. Default `{ style: "standard" }`.                    |
| `appearance` | `"light" \| "dark"?`                | Color tint of the rendered map.                                                     |

### `MapSnapshot`

| Member              | Type                | Description                                                                                                                                                                                                                                             |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`              | `{ width, height }` | Matches `options.size`.                                                                                                                                                                                                                                 |
| `image`             | `UIImage`           | Rendered map. Plug into `<Image image={snap.image} />` or use any of the `UIImage` instance methods — `toPNGBase64String()`, `toPNGData()`, `preparingThumbnail(size)`, `withTintColor(...)`, etc.                                                      |
| `point(coordinate)` | `{ x, y }`          | Convert a geographic coordinate into snapshot-space points (matches `size`). Coordinates outside the visible region still return a point — values may be negative or exceed `size`, so bounds-check if you only want to draw overlays inside the frame. |

### Overlay coordinates

`point` is the snapshotter's escape hatch for drawing pins or labels on top of
the image:

```tsx
const pin = snap.point({ latitude: 31.24, longitude: 121.49 })
const inBounds =
  pin.x >= 0 && pin.y >= 0 && pin.x <= snap.size.width && pin.y <= snap.size.height

return <ZStack>
  <Image image={snap.image} />
  {inBounds
    ? <Image
        systemName="mappin.circle.fill"
        position={{ x: pin.x, y: pin.y }}
        foregroundStyle="systemRed"
      />
    : null}
</ZStack>
```

### Working with the `UIImage`

`snap.image` exposes the same `UIImage` instance returned by other APIs, so
all the existing helpers work — for example, downscale before sharing:

```ts
const thumb = snap.image.preparingThumbnail({ width: 160, height: 100 })
const pngBase64 = await thumb?.toPNGBase64String()
```

***

## Notes

- A 1024×768 retina PNG can be a few megabytes; reach for `preparingThumbnail`
  before persisting if the snapshot is only used as a preview.
- Apple caps `scale` around 3x on most devices; values above are silently
  clamped.
- Network-backed (Apple's map tile service) — failures resolve through the
  Promise rejection with the underlying error message.



---
url: /guide/Changelog/3.1.0/MapKit/MapSnapshotter/index_example.md
---

# Example

```tsx
import {
  Button, Color, HStack, Image, MapCoordinate, MapRegion, Navigation, NavigationStack,
  Picker, Script, ScrollView, Text, useState, VStack, ZStack,
} from "scripting"

type POI = { name: string; coord: MapCoordinate; tint: Color }

type PresetDef = {
  region: MapRegion
  pois: POI[]
}

// Each preset ships with a couple of named POIs nearby — typical
// "widget preview" pattern: render a static map with multiple labeled pins.
const PRESETS: Record<string, PresetDef> = {
  bund: {
    region: {
      center: { latitude: 31.2407, longitude: 121.4905 },
      span: { latitudeDelta: 0.025, longitudeDelta: 0.025 },
    },
    pois: [
      { name: "Bund", coord: { latitude: 31.2407, longitude: 121.4905 }, tint: "systemRed" },
      { name: "Lujiazui", coord: { latitude: 31.2397, longitude: 121.4994 }, tint: "systemBlue" },
      { name: "Yu Garden", coord: { latitude: 31.2275, longitude: 121.4920 }, tint: "systemPurple" },
    ],
  },
  apple_park: {
    region: {
      center: { latitude: 37.3349, longitude: -122.0090 },
      span: { latitudeDelta: 0.015, longitudeDelta: 0.015 },
    },
    pois: [
      { name: "Apple Park", coord: { latitude: 37.3349, longitude: -122.0090 }, tint: "systemRed" },
      { name: "Visitor Center", coord: { latitude: 37.3327, longitude: -122.0053 }, tint: "systemTeal" },
    ],
  },
  golden_gate: {
    region: {
      center: { latitude: 37.8199, longitude: -122.4783 },
      span: { latitudeDelta: 0.025, longitudeDelta: 0.025 },
    },
    pois: [
      { name: "Bridge North", coord: { latitude: 37.8324, longitude: -122.4795 }, tint: "systemOrange" },
      { name: "Bridge South", coord: { latitude: 37.8070, longitude: -122.4750 }, tint: "systemOrange" },
      { name: "Fort Point", coord: { latitude: 37.8104, longitude: -122.4769 }, tint: "systemBrown" },
    ],
  },
}

type Preset = keyof typeof PRESETS

const SNAP_W = 320
const SNAP_H = 220

function Example() {
  const [preset, setPreset] = useState<Preset>("bund")
  const [style, setStyle] = useState<"standard" | "imagery" | "hybrid">("standard")
  const [appearance, setAppearance] = useState<"light" | "dark">("light")
  const [snap, setSnap] = useState<MapSnapshot | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)

  const def = PRESETS[preset]

  const take = async () => {
    setLoading(true); setErr(null)
    try {
      const result = await MapSnapshotter.take({
        region: def.region,
        size: { width: SNAP_W, height: SNAP_H },
        mapStyle: { style },
        appearance,
      })
      setSnap(result)
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  // For each POI of the active preset, project the geo coordinate onto the
  // snapshot's point space. Clip to snapshot bounds so off-screen pins drop
  // out instead of bleeding past the image edge.
  const overlays = snap != null
    ? def.pois.map(p => {
        const pt = snap.point(p.coord)
        const inBounds =
          pt.x >= 0 && pt.y >= 0 && pt.x <= snap.size.width && pt.y <= snap.size.height
        return { ...p, pt, inBounds }
      })
    : []

  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Snapshotter"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"MapSnapshotter"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={16}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`MapSnapshotter.take(...) renders a static map offscreen and returns
          a MapSnapshot { image, point }. The image
          below is the snapshot's image fed into <Image image={snap.image}>.`}
        </Text>

        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>Preset region</Text>
          <Picker
            title="Region"
            value={preset}
            onChanged={(v: any) => setPreset(v as Preset)}
            pickerStyle={"segmented"}
          >
            <Text tag={"bund"}>Bund</Text>
            <Text tag={"apple_park"}>Apple Park</Text>
            <Text tag={"golden_gate"}>Golden Gate</Text>
          </Picker>
        </VStack>

        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>Map style</Text>
          <Picker
            title="Style"
            value={style}
            onChanged={(v: any) => setStyle(v as any)}
            pickerStyle={"segmented"}
          >
            <Text tag={"standard"}>standard</Text>
            <Text tag={"imagery"}>imagery</Text>
            <Text tag={"hybrid"}>hybrid</Text>
          </Picker>
        </VStack>

        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>Appearance</Text>
          <Picker
            title="Appearance"
            value={appearance}
            onChanged={(v: any) => setAppearance(v as any)}
            pickerStyle={"segmented"}
          >
            <Text tag={"light"}>light</Text>
            <Text tag={"dark"}>dark</Text>
          </Picker>
        </VStack>

        <HStack spacing={8}>
          <Button title={loading ? "Rendering..." : "Take snapshot"} action={take} />
          {snap != null
            ? <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
              {snap.size.width} × {snap.size.height} pt
            </Text>
            : null}
        </HStack>

        {err != null
          ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text>
          : null}

        {snap != null
          ? <ZStack frame={{ width: SNAP_W, height: SNAP_H }}>
            <Image
              image={snap.image}
              resizable
              scaleToFit
              frame={{ width: SNAP_W, height: SNAP_H }}
              clipShape={{ type: "rect", cornerRadius: 12 }}
            />
            {/* 多个 POI 覆盖:每个 pin + 文字标签都按 snap.point(...) 投影到画布上。 */}
            {overlays.filter(o => o.inBounds).map(o =>
              <VStack key={o.name} spacing={1} position={{ x: o.pt.x, y: o.pt.y - 14 }}>
                <Image
                  systemName="mappin.circle.fill"
                  font={"title3"}
                  foregroundStyle={o.tint}
                />
                <Text
                  font={"caption2"}
                  foregroundStyle={"white"}
                  padding={{ horizontal: 4, vertical: 1 }}
                  background={"rgba(0, 0, 0, 0.55)"}
                  clipShape={{ type: "rect", cornerRadius: 4 }}
                >
                  {o.name}
                </Text>
              </VStack>
            )}
          </ZStack>
          : <Text font={"caption"} foregroundStyle={"tertiaryLabel"}>
            Snapshot will appear here after rendering.
          </Text>}

        {snap != null
          ? <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
            {`${overlays.filter(o => o.inBounds).length} / ${overlays.length} POIs in bounds — out-of-bounds coordinates are clipped instead of bleeding past the image edge.`}
          </Text>
          : null}
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/MapKit/MapUtils/index.md
---

# 

***

title: MapUtils
description: Synchronous MapKit geometry helpers: `distance`, `bearing`, `regionContains`, `regionFromCoordinates`.

***

`MapUtils` is a small set of synchronous geometry helpers for the MapKit
coordinate / region types from the views layer. Pure functions, safe to call
during render or in tight loops.

***

## `distance(a, b)`

Great-circle distance between two `MapCoordinate`s in **meters**, computed via
the Haversine formula using mean Earth radius (`6_371_008.8 m`).

```ts
const d = MapUtils.distance(
  { latitude: 39.9042, longitude: 116.4074 },  // Beijing
  { latitude: 31.2304, longitude: 121.4737 },  // Shanghai
)
// d ≈ 1_067_000  (meters)
```

Accuracy is good enough for typical "near me / how far away" use cases. For
applications that need geodetic-grade precision (geological surveying etc.),
use a dedicated geodesy library.

***

## `bearing(a, b)`

Initial bearing (forward azimuth) from `a` to `b`, in degrees normalized to
`[0, 360)`:

| Value | Direction |
| ----- | --------- |
| `0`   | North     |
| `90`  | East      |
| `180` | South     |
| `270` | West      |

```ts
MapUtils.bearing(
  { latitude: 0, longitude: 0 },
  { latitude: 0, longitude: 1 },
)  // 90
```

The bearing returned is the **initial** bearing — on long great-circle routes
the actual direction at the destination is different. For map-marker rotation
the initial bearing is what you want.

***

## `regionContains(region, coordinate)`

Whether `coordinate` lies inside the rectangular `MapRegion`:

```ts
const region = {
  center: { latitude: 31.23, longitude: 121.47 },
  span: { latitudeDelta: 0.1, longitudeDelta: 0.1 },
}
MapUtils.regionContains(region, { latitude: 31.24, longitude: 121.48 })  // true
MapUtils.regionContains(region, { latitude: 32.00, longitude: 121.47 })  // false
```

**Caveat**: does not handle regions that straddle the ±180° antimeridian (the
"Pacific date line"). If you need cross-meridian membership, split the test
into two regions manually.

***

## `regionFromCoordinates(coordinates, paddingFactor?)`

Smallest `MapRegion` enclosing all coordinates. Useful for fitting the camera
around a set of `Marker`s or a polyline.

```ts
const region = MapUtils.regionFromCoordinates([
  { latitude: 31.23, longitude: 121.47 },
  { latitude: 31.24, longitude: 121.50 },
  { latitude: 31.22, longitude: 121.49 },
])

if (region) {
  position.setValue({ region })  // fits the camera around all three points
}
```

| Parameter       | Default | Description                                                     |
| --------------- | ------- | --------------------------------------------------------------- |
| `paddingFactor` | `0.1`   | Fractional expansion of the bounding span. `0` for a tight fit. |

Edge cases:

- Empty array → returns `null`.
- Single coordinate → returns a region with a minimal 0.01° span centered on
  that point.
- Coordinates collinear in latitude or longitude → span is clamped to a
  minimum of `0.005°` to avoid `0` span (which MapKit would reject).
- Antimeridian-crossing input (e.g. one point at `+170°`, one at `-170°`)
  produces a region spanning the long way around. Not Phase-3a–supported.

***

## `formatDistance(meters, options?)`

Localized human-readable distance via Apple's `MKDistanceFormatter`. Negative
inputs clamp to `0`.

```ts
MapUtils.formatDistance(1230)                            // "1.2 km" (locale-dependent)
MapUtils.formatDistance(1230, { units: "imperial" })     // "0.8 mi"
MapUtils.formatDistance(1230, { unitStyle: "full" })     // "1.2 kilometers"
```

| Option      | Type                                   | Description                                             |
| ----------- | -------------------------------------- | ------------------------------------------------------- |
| `units`     | `"metric" \| "imperial" \| "default"`  | Force a unit system. Default follows the device locale. |
| `unitStyle` | `"default" \| "abbreviated" \| "full"` | Length of the unit suffix (`"km"` vs `"kilometers"`).   |

Output is locale-aware — do not assert on exact strings in tests.

***

## `formatDuration(seconds, options?)`

Localized duration via `DateComponentsFormatter`. Negative inputs return an
empty string.

```ts
MapUtils.formatDuration(3725)                              // "1h 2m"
MapUtils.formatDuration(3725, { unitsStyle: "full" })       // "1 hour, 2 minutes"
MapUtils.formatDuration(3725, { unitsStyle: "positional" }) // "1:02:05"
MapUtils.formatDuration(86_400 + 3600, { maximumUnitCount: 1 }) // "1d"
```

| Option             | Type                                                                          | Default                     | Description                                                                 |
| ------------------ | ----------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------- |
| `unitsStyle`       | `"positional" \| "abbreviated" \| "short" \| "full" \| "brief" \| "spellOut"` | `"abbreviated"`             | Visual style of the unit suffix.                                            |
| `allowedUnits`     | `("day" \| "hour" \| "minute" \| "second")[]`                                 | `["day", "hour", "minute"]` | Which units the formatter is allowed to emit.                               |
| `maximumUnitCount` | `number`                                                                      | unlimited                   | Cap how many unit segments appear (`1` collapses `3661s` to just `"1 hr"`). |

***

## When to use

- After `MapSearch.locate` / `Location.geocodeAddress`:
  `regionFromCoordinates` lets you auto-fit the camera around all hits.
- "Within Xm of me": call `distance(myLocation, item.coordinate) < X`.
- Sorting search results by proximity: stable-sort the array by `distance`.
- Compass arrow on a marker pointing to a target: `bearing` gives the rotation
  in degrees.
- Rendering route metadata (`route.distance` / `route.expectedTravelTime` from
  `MapDirections`): `formatDistance` / `formatDuration` give locale-aware labels.



---
url: /guide/Changelog/3.1.0/MapKit/MapUtils/index_example.md
---

# 

***

title: Example
description: Synchronous MapKit geometry helpers: `distance`, `bearing`, `regionContains`, `regionFromCoordinates`.

***

```tsx
import {
  Button, HStack, Map, Marker, Navigation, NavigationStack, Script,
  ScrollView, Text, useEffect, useMemo, useObservable, useState, VStack,
} from "scripting"
import type { MapCoordinate } from "scripting"

const beijing: MapCoordinate = { latitude: 39.9042, longitude: 116.4074 }
const shanghai: MapCoordinate = { latitude: 31.2304, longitude: 121.4737 }
const guangzhou: MapCoordinate = { latitude: 23.1291, longitude: 113.2644 }
const sanFrancisco: MapCoordinate = { latitude: 37.7749, longitude: -122.4194 }

function DistanceBearingDemo() {
  const [from, setFrom] = useState<MapCoordinate>(beijing)
  const [to, setTo] = useState<MapCoordinate>(shanghai)

  const d = useMemo(() => MapUtils.distance(from, to), [from, to])
  const b = useMemo(() => MapUtils.bearing(from, to), [from, to])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>1. `distance` + `bearing`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Haversine distance (meters) and initial bearing (degrees, 0 = north,
      90 = east) between two coordinates.
    </Text>
    <HStack spacing={8}>
      <Button title="Beijing → Shanghai" buttonStyle="bordered"
        action={() => { setFrom(beijing); setTo(shanghai) }} />
      <Button title="Shanghai → Guangzhou" buttonStyle="bordered"
        action={() => { setFrom(shanghai); setTo(guangzhou) }} />
      <Button title="Beijing → SF" buttonStyle="bordered"
        action={() => { setFrom(beijing); setTo(sanFrancisco) }} />
    </HStack>
    <Text monospaced>
      {`from: ${from.latitude.toFixed(3)}, ${from.longitude.toFixed(3)}\n`}
      {`to:   ${to.latitude.toFixed(3)}, ${to.longitude.toFixed(3)}\n`}
      {`distance: ${(d / 1000).toFixed(1)} km\n`}
      {`bearing:  ${b.toFixed(1)}°`}
    </Text>
  </VStack>
}

function RegionContainsDemo() {
  // Region around People's Square, Shanghai
  const region = {
    center: { latitude: 31.2304, longitude: 121.4737 },
    span: { latitudeDelta: 0.05, longitudeDelta: 0.05 },
  }

  const testPoints: { label: string; coord: MapCoordinate; inside: boolean }[] = useMemo(() => {
    const probes = [
      { label: "Bund", coord: { latitude: 31.2407, longitude: 121.4905 } },
      { label: "Lujiazui", coord: { latitude: 31.2397, longitude: 121.4994 } },
      { label: "Pudong Intl Airport", coord: { latitude: 31.1443, longitude: 121.8083 } },
      { label: "Hangzhou", coord: { latitude: 30.2741, longitude: 120.1551 } },
    ]
    return probes.map(p => ({ ...p, inside: MapUtils.regionContains(region, p.coord) }))
  }, [])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>2. `regionContains`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Region: ~5 km box around People's Square. Probe a few points to see which
      land inside.
    </Text>
    <VStack alignment={"leading"} spacing={4}>
      {testPoints.map(p => (
        <Text monospaced>
          {p.inside ? "✓ inside  " : "✗ outside "} {p.label}
        </Text>
      ))}
    </VStack>
  </VStack>
}

function RegionFromCoordinatesDemo() {
  const [paddingFactor, setPaddingFactor] = useState(0.1)

  const coords = useMemo<MapCoordinate[]>(() => [
    { latitude: 31.2407, longitude: 121.4905 },  // Bund
    { latitude: 31.2304, longitude: 121.4737 },  // People's Square
    { latitude: 31.2397, longitude: 121.4994 },  // Lujiazui
    { latitude: 31.2229, longitude: 121.4583 },  // Nanjing Rd
  ], [])

  const region = useMemo(
    () => MapUtils.regionFromCoordinates(coords, paddingFactor),
    [coords, paddingFactor]
  )

  // 用 cameraPosition (双向 observable) 而不是 initialCameraPosition,这样
  // paddingFactor 变化时新计算的 region 会通过 setValue 推到地图。
  // initialCameraPosition 顾名思义只在首次挂载生效,后续不响应 prop 变化。
  const camera = useObservable<MapCameraPosition>(
    region != null ? MapCameraPosition.region(region) : MapCameraPosition.automatic()
  )

  useEffect(() => {
    if (region != null) {
      camera.setValue(MapCameraPosition.region(region))
    }
  }, [region])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>3. `regionFromCoordinates`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Smallest enclosing region for 4 Shanghai landmarks. Padding expands the
      bounding box outward.
    </Text>
    <HStack spacing={8}>
      <Button title="tight (0)" buttonStyle="bordered" action={() => setPaddingFactor(0)} />
      <Button title="10% pad" buttonStyle="bordered" action={() => setPaddingFactor(0.1)} />
      <Button title="50% pad" buttonStyle="bordered" action={() => setPaddingFactor(0.5)} />
    </HStack>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      paddingFactor: {paddingFactor}{"  ·  "}
      span: {region?.span.latitudeDelta.toFixed(4)}° × {region?.span.longitudeDelta.toFixed(4)}°
    </Text>
    <Map
      cameraPosition={camera}
      frame={{ height: 280 }}
      clipShape={{
        type: 'rect',
        cornerRadius: 12
      }}
    >
      {coords.map(c => (
        <Marker
          coordinate={c}
          tint="systemBlue"
        />
      ))}
    </Map>
  </VStack>
}

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Utils"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"MapUtils"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={24}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          Synchronous geometry helpers for MapKit coordinate / region types. Pure
          functions, safe to call during render.
        </Text>

        <DistanceBearingDemo />
        <RegionContainsDemo />
        <RegionFromCoordinatesDemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/MediaPlayer (Live Stream).md
---

# MediaPlayer (Live Stream)

The `MediaPlayer` API allows you to interact with the Now Playing Center, manage Now Playing Info, and respond to remote control events. Below is a comprehensive guide on its usage, including best practices and examples.

***

## Getting Started

The `MediaPlayer` API provides control over media playback information and remote command handling. To get started:

1. Set the `nowPlayingInfo` to display current media information.
2. Configure available commands using `setAvailableCommands()`.
3. Register a `commandHandler` to respond to remote events.

```typescript
MediaPlayer.nowPlayingInfo = {
  title: "Song Title",
  artist: "Artist Name",
  playbackRate: 1.0,
  elapsedPlaybackTime: 30,
  playbackDuration: 240
}

MediaPlayer.setAvailableCommands(["play", "pause", "nextTrack", "previousTrack"])

MediaPlayer.commandHandler = (command, event) => {
  console.log(`Command received: ${command}`)
}
```

***

## API Reference

### NowPlayingInfo

The `nowPlayingInfo` object displays metadata about the currently playing media. Set it to `null` to clear the Now Playing Info Center.

**Properties:**

- **`title`**: `string` (Required)
  - The title of the media item.
- **`artist`**: `string` (Optional)
  - The artist or performer of the media item.
- **`albumTitle`**: `string` (Optional)
  - The album title of the media item.
- **`artwork`**: `UIImage` (Optional)
  - An image representing the media item.
- **`mediaType`**: `MediaType` (Optional)
  - Defaults to `audio`.
- **`playbackRate`**: `number` (Optional)
  - Defaults to `0`. Indicates the current playback rate.
- **`elapsedPlaybackTime`**: `DurationInSeconds` (Optional)
  - Defaults to `0`. The current playback time.
- **`playbackDuration`**: `DurationInSeconds` (Optional)
  - Defaults to `0`. The total duration of the media.
- **`isLiveStream`**: `boolean` (Optional)
  - Defaults to `false`. Set to `true` for live streams (e.g., radio broadcasts) so the system hides the progress bar in the Lock Screen and Control Center Now Playing UI.

### Playback State

The `playbackState` property indicates the app's current playback state:

- **`unknown`**: Default state when playback status is undefined.
- **`playing`**: Media is actively playing.
- **`paused`**: Media playback is paused.
- **`stopped`**: Playback has stopped.
- **`interrupted`**: Playback is interrupted by an external event.

```typescript
if (MediaPlayer.playbackState === MediaPlayerPlaybackState.playing) {
    console.log("Media is currently playing")
}
```

### Commands and Event Handlers

#### `setAvailableCommands(commands: MediaPlayerRemoteCommand[])`

Specifies which remote commands are enabled for user interaction.

**Example:**

```typescript
MediaPlayer.setAvailableCommands(["play", "pause", "stop", "nextTrack"])
```

#### `commandHandler`

A callback to handle remote commands. Register this function to process commands like `play`, `pause`, or `seekBackward`.

**Example:**

```typescript
MediaPlayer.commandHandler = (command, event) => {
  switch (command) {
    case "play":
      console.log("Play command received")
      break
    case "pause":
      console.log("Pause command received")
      break
    default:
      console.log(`Command not handled: ${command}`)
  }
}
```

**Supported Commands:**

- `play`, `pause`, `stop`, `nextTrack`, `previousTrack`
- `seekBackward`, `seekForward`, `skipBackward`, `skipForward`
- `rating`, `like`, `dislike`, `bookmark`
- `changeRepeatMode`, `changeShuffleMode`
- `enableLanguageOption`, `disableLanguageOption`

***

## Common Use Cases

### Display Now Playing Info

```typescript
MediaPlayer.nowPlayingInfo = {
  title: "Podcast Episode",
  artist: "Podcast Host",
  elapsedPlaybackTime: 120,
  playbackDuration: 1800,
  playbackRate: 1.0
}
```

### Respond to Playback Commands

```typescript
MediaPlayer.setAvailableCommands(["play", "pause", "stop"])

MediaPlayer.commandHandler = (command, event) => {
  if (command === "play") {
    console.log("Start playback")
  } else if (command === "pause") {
    console.log("Pause playback")
  }
}
```

### Handle Custom Events

```typescript
MediaPlayer.commandHandler = (command, event) => {
  if (command === "seekForward") {
    const seekEvent = event as MediaPlayerSeekCommandEvent
    console.log(`Seek Event Type: ${seekEvent.type}`)
  }
}
```

***

## Best Practices

1. **Keep Metadata Up-to-Date:** Update `nowPlayingInfo` as playback changes.
2. **Handle All Relevant Commands:** Ensure user interactions like skipping or seeking are supported.
3. **Resource Management:** Clear `nowPlayingInfo` when playback stops to avoid stale information.
4. **Test with External Devices:** Use remote controls like headphones or car systems to validate command handling.
5. **Provide Feedback:** Inform users of successful or failed actions in response to commands.

***

## Full Example

Below is a complete implementation of `MediaPlayer`:

```typescript
// Set Now Playing Info
MediaPlayer.nowPlayingInfo = {
  title: "Song Title",
  artist: "Artist Name",
  albumTitle: "Album Name",
  playbackRate: 1.0,
  elapsedPlaybackTime: 0,
  playbackDuration: 300
}

// Enable Commands
MediaPlayer.setAvailableCommands(["play", "pause", "nextTrack", "previousTrack", "seekForward", "seekBackward"])

// Handle Commands
MediaPlayer.commandHandler = (command, event) => {
  switch (command) {
    case "play":
      console.log("Playing media")
      break
    case "pause":
      console.log("Pausing media")
      break
    case "nextTrack":
      console.log("Skipping to next track")
      break
    case "seekForward":
      const seekEvent = event as MediaPlayerSeekCommandEvent
      console.log(`Seek Event: ${seekEvent.type}`)
      break
    default:
      console.log(`Unhandled command: ${command}`)
  }
}
```



---
url: /guide/Changelog/3.1.0/NaturalLanguage/Contextual Embedding.md
---

# Contextual Embedding

`ContextualEmbedding` provides transformer-style sequence embeddings: each token in a sentence gets a vector that depends on its surrounding context (unlike `Embedding`, where a word always maps to the same vector).

***

## Static factories

### `ContextualEmbedding.forLanguage(language): ContextualEmbedding | null`

Most recent embedding suitable for `language`, or `null` if none.

### `ContextualEmbedding.forScript(script): ContextualEmbedding | null`

Most recent embedding for an ISO 15924 script (`"Latn"`, `"Hans"`, `"Cyrl"`, ...).

### `ContextualEmbedding.forModelIdentifier(modelIdentifier): ContextualEmbedding | null`

Locate an embedding by its model identifier. Useful when you want inference to use exactly the same model as a previous training run — capture the `modelIdentifier` then, reuse it here.

```ts
const emb = NaturalLanguage.ContextualEmbedding.forLanguage("en")
```

***

## Properties

| Property                | Type         | Description                                                    |
| ----------------------- | ------------ | -------------------------------------------------------------- |
| `modelIdentifier`       | `string`     | Stable identifier for this model revision.                     |
| `languages`             | `Language[]` | Languages the model covers.                                    |
| `scripts`               | `Script[]`   | Scripts the model covers.                                      |
| `revision`              | `number`     | OS-published revision number.                                  |
| `dimension`             | `number`     | Length of each token vector.                                   |
| `maximumSequenceLength` | `number`     | Maximum number of token vectors the model will emit per input. |
| `hasAvailableAssets`    | `boolean`    | Whether the model assets are already on-device.                |

***

## Methods

### `prepare(): Promise<void>`

Request that the model's assets be loaded onto the device, then resolve. The assets are downloaded on demand the first time, so the first call may take noticeably longer than subsequent ones. `embeddingResult()` before `prepare()` resolves will typically fail.

> **Simulator limitation:** the simulator sandbox can't write to `/var/db/com.apple.naturallanguaged/...`, so `prepare()` always rejects there. Use a real device.

### `embeddingResult(text, language?): Promise<ContextualEmbeddingResult>`

Compute contextual embeddings for `text`. Each token in the result has the model's own tokenization (typically wordpieces), its UTF-16 range, and a vector of length `dimension`.

```ts
{
  sequenceLength: number
  tokens: Array<{
    text: string
    range: { location: number, length: number }
    vector: number[]
  }>
}
```

***

## Example

```ts
const emb = NaturalLanguage.ContextualEmbedding.forLanguage("en")
if (!emb) return

await emb.prepare()

const r = await emb.embeddingResult("The bank charged a fee.", "en")
console.log(r.sequenceLength)       // number of token vectors
console.log(r.tokens[0].vector.length === emb.dimension)   // true

// Cosine similarity between two tokens in the same sentence:
const a = r.tokens[1].vector
const b = r.tokens[2].vector
let dot = 0, na = 0, nb = 0
for (let i = 0; i < a.length; i++) { dot += a[i]*b[i]; na += a[i]*a[i]; nb += b[i]*b[i] }
const cos = dot / (Math.sqrt(na) * Math.sqrt(nb))
```

***

## Notes

- Unlike `Embedding.distance`, contextual embeddings are sentence-aware: `"bank"` in "river bank" and "bank account" yield different vectors.
- The model assets are shared across all apps on the device; `prepare()` is cheap after the first download.



---
url: /guide/Changelog/3.1.0/NaturalLanguage/Embedding.md
---

# Embedding

`Embedding` exposes Apple's built-in **word** and **sentence** embeddings: dense vectors used for similarity, nearest-neighbor search, and distance computation.

There is no public constructor — get an instance from one of the static factories.

***

## Static factories

### `Embedding.wordEmbedding(language, revision?): Embedding | null`

The built-in word embedding for `language`. Returns `null` if no embedding is available on this OS for that language.

### `Embedding.sentenceEmbedding(language, revision?): Embedding | null`

The built-in sentence embedding for `language` (iOS 14+). Returns `null` on iOS 13 or when no sentence embedding is available.

```ts
const wordEmb = NaturalLanguage.Embedding.wordEmbedding("en")
const sentEmb = NaturalLanguage.Embedding.sentenceEmbedding("en")
```

***

## Properties

| Property         | Type               | Description                                             |
| ---------------- | ------------------ | ------------------------------------------------------- |
| `language`       | `Language \| null` | Language of the embedding.                              |
| `dimension`      | `number`           | Length of each vector.                                  |
| `vocabularySize` | `number`           | Number of distinct tokens in the embedding.             |
| `revision`       | `number`           | OS-published revision number; useful for cache busting. |

***

## Lookup methods

### `contains(token: string): boolean`

Whether `token` is in the embedding's vocabulary.

### `vector(token: string): number[] | null`

Vector for `token` (length = `dimension`), or `null` if the token isn't in vocabulary.

### `distance(first, second, type?): number | null`

Cosine distance between two tokens (`[0, 2]`; smaller is closer).
Returns `null` if either token isn't in vocabulary — use `contains` to disambiguate "no signal" from "very far apart".

### `neighbors(token, maximumCount, type?): { token, distance }[]`

Up to `maximumCount` nearest neighbors of `token`, sorted by ascending distance. Returns `[]` if `token` isn't in vocabulary.

***

## Examples

### Word similarity

```ts
const emb = NaturalLanguage.Embedding.wordEmbedding("en")
if (emb) {
  console.log(emb.distance("cat", "kitten"))     // small — semantically close
  console.log(emb.distance("cat", "airplane"))   // larger
}
```

### Nearest neighbors

```ts
const emb = NaturalLanguage.Embedding.wordEmbedding("en")
if (emb) {
  const nbs = emb.neighbors("happy", 5)
  for (const { token, distance } of nbs) {
    console.log(`${token}\t${distance.toFixed(3)}`)
  }
  // joyful  0.341
  // glad    0.402
  // ...
}
```

### Raw vector

```ts
const v = emb?.vector("hello")
if (v) {
  // dot product with another vector ...
}
```

***

## Notes

- `wordEmbedding("en")` is the most reliably available embedding. Other languages may return `null` depending on OS revision.
- `distanceType` currently only supports `"cosine"`; the parameter is reserved for future metrics.



---
url: /guide/Changelog/3.1.0/NaturalLanguage/Gazetteer.md
---

# Gazetteer

`Gazetteer` is a user-supplied dictionary mapping **labels** to **terms**. Attach one to a `Tagger` to make the tagger recognize domain-specific vocabulary — product names, code identifiers, internal jargon — that the system model wouldn't normally catch.

***

## Construction

```ts
const gazetteer = new NaturalLanguage.Gazetteer({
  product: ["Scripting", "Pro"],
  company: ["Acme", "Acme Corp"]
}, "en")
```

- `dictionary`: `{ label: [term, term, ...] }`. Each label can have many terms; the gazetteer maps any matching term back to that label.
- `language?: Language` — optional hint when terms are language-specific.

The constructor **throws** if the dictionary is malformed (e.g. empty terms or duplicate terms under different labels).

***

## Properties

| Property   | Type               | Description                                                                                    |
| ---------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `language` | `Language \| null` | Language hint passed to the constructor (may not be retained for dictionary-built gazetteers). |

***

## Methods

### `label(term: string): string | null`

Returns the label `term` maps to, or `null` for a miss.

```ts
gazetteer.label("Scripting")   // → "product"
gazetteer.label("Acme")        // → "company"
gazetteer.label("Banana")      // → null
```

***

## Using a gazetteer with `Tagger`

```ts
const gz = new NaturalLanguage.Gazetteer({
  product: ["Scripting"],
  company: ["Acme"]
}, "en")

const tagger = new NaturalLanguage.Tagger(["nameType"])
tagger.setGazetteers([gz], "nameType")
tagger.setText("Acme ships the Scripting app.")

const tags = tagger.tags(null, "word", "nameType", {
  omitWhitespace: true,
  omitPunctuation: true
})
// → tags include { tag: "company", ... } and { tag: "product", ... },
//   instead of just OrganizationName / nil.
```

Gazetteer hits **override** the system model for that scheme. If the tagger is constructed with `"nameType"`, then `setGazetteers([gz], "nameType")` will replace standard `OrganizationName` / `PersonalName` labels with your custom labels for the words that match.

***

## Notes

- This is the lightweight, in-script way to extend tagging. The heavier (and out of scope here) alternative is `NLModel`, which trains a full classifier from labeled data.
- Multiple gazetteers can be attached to the same scheme via `setGazetteers([gz1, gz2, ...], scheme)`.



---
url: /guide/Changelog/3.1.0/NaturalLanguage/Language Recognition.md
---

# Language Recognition

Detect the dominant language of a string or rank candidate languages by confidence.

***

## Functions

### `NaturalLanguage.dominantLanguage(text: string): Language | null`

Return the single most likely language for `text`. Returns `null` when the text is too short or ambiguous to classify.

```ts
NaturalLanguage.dominantLanguage("Bonjour le monde")   // → "fr"
NaturalLanguage.dominantLanguage("今天天气很好")       // → "zh-Hans"
NaturalLanguage.dominantLanguage("")                   // → null
```

***

### `NaturalLanguage.languageHypotheses(text, options?): LanguageHypothesis[]`

Return up to `maximumCount` candidate languages sorted by confidence (descending).

- `options.maximumCount?: number` — defaults to `3`.
- `options.constraints?: Language[]` — soft preference; recognizer favors candidates in this set but is not strictly limited to them.
- `options.hints?: { [language: string]: number }` — prior probabilities (BCP-47 → 0...1).

```ts
const ranked = NaturalLanguage.languageHypotheses("Buenos días", {
  maximumCount: 3,
  constraints: ["es", "pt", "it"],
  hints: { es: 0.8 }
})
// → [{ language: "es", confidence: 0.92 }, { language: "pt", confidence: 0.05 }, ...]
```

***

## Notes

- Language identification is offline and extremely fast — feel free to call it on every keystroke if needed.
- For very short input (one or two words), the recognizer may return `null` or low confidence. Provide more context when possible.



---
url: /guide/Changelog/3.1.0/NaturalLanguage/Tagger.md
---

# Tagger

`Tagger` annotates text with part-of-speech, lemma, language/script, named entities, sentiment, and custom labels from gazetteers.

***

## Construction

```ts
const tagger = new NaturalLanguage.Tagger([
  "lexicalClass",   // part of speech
  "nameType",       // person / place / organization
  "lemma",
  "sentimentScore"
])
tagger.setText("Tim Cook visited Beijing yesterday. I love this city!")
```

Pass only the schemes you actually need — they control which analyses the tagger performs.

***

## Tag schemes

```ts
type TagScheme =
  | "tokenType"              // word / punctuation / whitespace / other
  | "lexicalClass"           // Noun, Verb, Adjective, ...
  | "nameType"               // PersonalName, PlaceName, OrganizationName
  | "nameTypeOrLexicalClass"
  | "lemma"
  | "language"
  | "script"
  | "sentimentScore"         // numeric string in [-1, 1]
```

***

## Methods

### `setText(text: string): void`

Attach text. All subsequent queries operate on it.

### `setLanguage(language: Language, range?: StringRange): void`

Override the language hint for the whole text or a sub-range.

### `tag(at, unit, scheme): { tag: string | null, range } | null`

Look up the tag at a single UTF-16 offset.

### `tags(range, unit, scheme, options?): { tag: string | null, range }[]`

Enumerate all tags in a range. Pass `null` as `range` to scan the whole text.

`options` (`TaggerOptions`) lets you skip tokens you don't care about:

- `omitWords` / `omitPunctuation` / `omitWhitespace` / `omitOther`
- `joinNames` (treat `"John Smith"` as a single token)
- `joinContractions` (treat `"don't"` as a single token)

### `tagHypotheses(at, unit, scheme, maximumCount): { hypotheses, range }`

Top-K candidate tags at a position, as `{ "Noun": 0.7, "Verb": 0.2, ... }`.

### `enumerateNamedEntities(range?, options?): NamedEntityResult[]`

Convenience over `tags(..., "word", "nameType", ...)`: returns person / place / organization mentions only, with `joinNames` enabled so multi-token names appear as one entity.

### `sentimentScore(range?): number | null`

Score sentiment in the range `[-1, 1]` (more negative → more positive). Requires the tagger to have been constructed with `"sentimentScore"`. Scoring starts from `range.location` at paragraph granularity.

### `setGazetteers(gazetteers, scheme): void`

Attach one or more `Gazetteer` to a scheme. Gazetteer hits take precedence over the system model for that scheme. See `Gazetteer`.

***

## Examples

### Named entities

```ts
const tagger = new NaturalLanguage.Tagger(["nameType"])
tagger.setText("Tim Cook visited Beijing yesterday.")
console.log(tagger.enumerateNamedEntities())
// [
//   { entity: "personalName", text: "Tim Cook", range: { location: 0,  length: 8 } },
//   { entity: "placeName",    text: "Beijing",  range: { location: 17, length: 7 } }
// ]
```

### Part-of-speech

```ts
const tagger = new NaturalLanguage.Tagger(["lexicalClass"])
tagger.setText("Apple released new products.")
const tags = tagger.tags(null, "word", "lexicalClass", {
  omitWhitespace: true,
  omitPunctuation: true
})
// → [ { tag: "Noun", range }, { tag: "Verb", range }, { tag: "Adjective", range }, { tag: "Noun", range } ]
```

### Sentiment

```ts
const tagger = new NaturalLanguage.Tagger(["sentimentScore"])
tagger.setText("I love this beautiful sunny day!")
const score = tagger.sentimentScore()   // → ~0.9 (positive)
```

### Tag hypotheses

```ts
const r = tagger.tagHypotheses(0, "word", "lexicalClass", 3)
// {
//   hypotheses: { "Noun": 0.72, "ProperNoun": 0.18, "Adjective": 0.05 },
//   range: { location: 0, length: 5 }
// }
```



---
url: /guide/Changelog/3.1.0/NaturalLanguage/Tokenizer.md
---

# Tokenizer

Split text into word, sentence, paragraph, or document tokens.

***

## Function

### `NaturalLanguage.tokenize(text, options?): TokenRange[]`

Walk `text` at the requested granularity and return an ordered list of tokens.

- `options.unit?: "word" | "sentence" | "paragraph" | "document"` — defaults to `"word"`.
- `options.language?: Language` — optional hint that helps the tokenizer pick the right model for languages without explicit word boundaries (e.g. Chinese, Japanese, Thai).

Each token is:

```ts
{
  text: string                 // the substring
  range: { location, length }  // UTF-16 offset
  attributes: {                // present only when relevant
    emoji?: boolean
    numeric?: boolean
    symbolic?: boolean
  }
}
```

***

## Examples

```ts
// Word tokens
const words = NaturalLanguage.tokenize("Hello, world! 🎉", { unit: "word" })
// → ["Hello", "world", "🎉"] (with attributes.emoji on the last one)

// Sentence tokens
const sentences = NaturalLanguage.tokenize(
  "First sentence. Second one!",
  { unit: "sentence" }
)
// → 2 tokens

// Chinese: pass a language hint to help word segmentation
const cn = NaturalLanguage.tokenize("苹果发布了新产品", {
  unit: "word",
  language: "zh-Hans"
})
```

***

## Notes

- `range.location` / `range.length` are UTF-16 offsets, matching native JS string indexing. `text.substring(range.location, range.location + range.length)` always returns `token.text`.
- The tokenizer does not filter punctuation or whitespace — if you only want substantive words, filter the result yourself or use `Tagger.tags(..., { omitPunctuation: true, omitWhitespace: true })`.



---
url: /guide/Changelog/3.1.0/Path2D (SwiftUI Path)/index.md
---

# Path2D (SwiftUI Path)

`Path2D` is a vector path you build segment by segment, mirroring SwiftUI's `Path`. It is a
plain value: build it with line and curve commands, query its geometry, transform it, render it
with the `<PathShape>` view, or use it as a clipping / hit-testing / container shape.

> The name `Path2D` is used because `Path` is already taken by the file-path utilities. The
> drawing API itself follows SwiftUI's `Path`.

***

## Conventions

- Points are `{ x, y }`, rectangles are `{ x, y, width, height }`.
- Angles are in **radians**.
- Build methods are **chainable** (they return the path).
- Coordinates are absolute (in the shape's own coordinate space), exactly like SwiftUI's `Path`.

***

## Building a path

```tsx
// Imperative.
const p = new Path2D()
p.move({ x: 200, y: 100 })
p.addLine({ x: 100, y: 300 })
p.addLine({ x: 300, y: 300 })
p.closeSubpath()

// Or with a builder closure (mirrors SwiftUI's `Path { ... }`).
const heart = new Path2D(path => {
  path.move({ x: 150, y: 100 })
  path.addCurve({ x: 150, y: 300 }, { x: 0, y: 180 }, { x: 80, y: 320 })
  path.addCurve({ x: 150, y: 100 }, { x: 220, y: 320 }, { x: 300, y: 180 })
})
```

### Build methods

| Method                                                           | Description                                               |
| ---------------------------------------------------------------- | --------------------------------------------------------- |
| `move(to)`                                                       | Begin a new subpath at a point.                           |
| `addLine(to)`                                                    | Add a straight line from the current point.               |
| `addLines(points)`                                               | Add connected line segments, starting at the first point. |
| `addQuadCurve(to, control)`                                      | Quadratic Bézier curve with one control point.            |
| `addCurve(to, control1, control2)`                               | Cubic Bézier curve with two control points.               |
| `addArc({ center, radius, startAngle, endAngle, clockwise? })`   | Circular arc. Angles in radians.                          |
| `addRelativeArc({ center, radius, startAngle, delta })`          | Arc described by a start angle and an angular delta.      |
| `addRect(rect)`                                                  | A rectangular subpath.                                    |
| `addRoundedRect({ rect, cornerRadius? \| cornerSize?, style? })` | A rounded rectangle.                                      |
| `addEllipse(rect)`                                               | An ellipse inscribed in a rectangle.                      |
| `addPath(other)`                                                 | Append another `Path2D`.                                  |
| `closeSubpath()`                                                 | Close the current subpath.                                |

> `clockwise` follows SwiftUI's convention. This is the opposite of the Web Canvas
> `counterclockwise` flag — keep that in mind when porting Canvas code.

***

## Rendering with `<PathShape>`

`<PathShape>` renders a `Path2D` as a SwiftUI shape. It accepts `fill`, `stroke`, `trim` and all
view modifiers, exactly like `Rectangle` or `Circle`. Provide **either** `path` (a prebuilt value)
**or** `draw` (a size-responsive builder, like `<Canvas>`).

```tsx
// Static path.
<PathShape path={heart} fill="systemPink" />

// Size-responsive: the closure receives the draw size on every layout.
<PathShape
  fill="orange"
  stroke={{ shapeStyle: "black", strokeStyle: { lineWidth: 2 } }}
  draw={(path, size) => {
    path.move({ x: size.width / 2, y: 0 })
    path.addLine({ x: 0, y: size.height })
    path.addLine({ x: size.width, y: size.height })
    path.closeSubpath()
  }}
/>
```

Sizing is controlled by view modifiers (`frame`, `padding`, ...). With `draw`, the actual draw size
is the second argument; do not call `setState` inside the closure.

***

## Geometry queries

These are computed on demand and return immediately.

```tsx
heart.boundingRect()                  // { x, y, width, height }
heart.contains({ x: 150, y: 200 })    // boolean
heart.contains({ x: 0, y: 0 }, true)  // even-odd fill rule
heart.isEmpty()                       // boolean
heart.currentPoint()                  // { x, y } | null
```

***

## Transforming

Transforms return a **new** `Path2D` (the original is unchanged).

```tsx
const moved = heart.offsetBy(40, 0)
const scaled = heart.applying({ a: 2, b: 0, c: 0, d: 2, tx: 0, ty: 0 })
const half = heart.trimmedPath(0, 0.5)   // first half of the path's length
```

***

## As a clip / content / container shape

Pass a `Path2D` anywhere a shape is accepted:

```tsx
<Image imageUrl={url} clipShape={heart} />
<Color color="black" contentShape={heart} />
```

To use a path as a **mask**, render it as a `<PathShape>` and pass that view to `mask`:

```tsx
<Image imageUrl={url} mask={<PathShape path={heart} fill="black" />} />
```



---
url: /guide/Changelog/3.1.0/Path2D (SwiftUI Path)/index_example.md
---

# Example

```tsx
import { HStack, Navigation, NavigationStack, Path2D, PathShape, Rectangle, Script, ScrollView, Text, useState, VStack } from "scripting"

// 一个可复用的三角形(绝对坐标),演示构建 + 几何查询 + clip。
const triangle = new Path2D(p => {
  p.move({ x: 150, y: 20 })
  p.addLine({ x: 20, y: 260 })
  p.addLine({ x: 280, y: 260 })
  p.closeSubpath()
})

function Example() {
  const [probeInside, setProbeInside] = useState(false)
  const rect = triangle.boundingRect()

  return <NavigationStack>
    <ScrollView>
      <VStack
        navigationTitle={"Path2D"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={28}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`\`Path2D\` mirrors SwiftUI's \`Path\`: build it with line / curve commands, then render it
          with \`<PathShape>\` (fill / stroke / modifiers), query its geometry, or use it as a clip
          shape. Points are {"{ x, y }"}, angles are radians.`}
        </Text>

        {/* 1. Static path: fill + stroke */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. Build + fill / stroke</Text>
          <PathShape
            path={triangle}
            fill={"systemOrange"}
            stroke={{ shapeStyle: "label", strokeStyle: { lineWidth: 3 } }}
            frame={{ width: 300, height: 280 }}
          />
        </VStack>

        {/* 2. Curves */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Quadratic + cubic curves</Text>
          <PathShape
            fill={"systemPink"}
            frame={{ width: 300, height: 220 }}
            draw={(p, size) => {
              p.move({ x: size.width / 2, y: 30 })
              p.addCurve(
                { x: size.width / 2, y: size.height - 20 },
                { x: 0, y: size.height * 0.6 },
                { x: size.width * 0.3, y: size.height },
              )
              p.addCurve(
                { x: size.width / 2, y: 30 },
                { x: size.width * 0.7, y: size.height },
                { x: size.width, y: size.height * 0.6 },
              )
            }}
          />
        </VStack>

        {/* 3. Arc + rounded rect, stroked */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. Arc + rounded rect</Text>
          <PathShape
            stroke={{ shapeStyle: "systemBlue", strokeStyle: { lineWidth: 4 } }}
            frame={{ width: 300, height: 160 }}
            draw={(p) => {
              p.addRoundedRect({ rect: { x: 20, y: 20, width: 120, height: 120 }, cornerRadius: 24 })
              p.addArc({ center: { x: 230, y: 80 }, radius: 55, startAngle: 0, endAngle: Math.PI * 1.5 })
            }}
          />
        </VStack>

        {/* 4. Geometry query */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>4. Geometry</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            boundingRect = {"{"} x: {rect.x.toFixed(0)}, y: {rect.y.toFixed(0)}, w:{" "}
            {rect.width.toFixed(0)}, h: {rect.height.toFixed(0)} {"}"}
          </Text>
          <HStack spacing={12}>
            <Text>contains (150, 200): {String(triangle.contains({ x: 150, y: 200 }))}</Text>
          </HStack>
          <Text>contains (10, 10): {String(triangle.contains({ x: 10, y: 10 }))}</Text>
        </VStack>

        {/* 5. As a clip shape */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>5. clipShape</Text>
          <Rectangle
            fill={"systemTeal"}
            frame={{ width: 300, height: 280 }}
            clipShape={triangle}
          />
        </VStack>

      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.1.0/Photos/index.md
---

# Photos

The `Photos` module provides unified access to the system photo library and camera. It enables scripts to:

- Capture photos or record videos using the system camera
- Pick images, videos, or Live Photos from the photo library
- Retrieve the most recent photos
- Save images or videos to the Photos app
- Query the library for assets by media type, album, date, or favorites, and read rich metadata
- Load image, data, video, or Live Photo representations from a specific asset
- Browse, create, and delete albums; favorite or delete assets

All APIs are built on top of native iOS frameworks such as Photos and PHPicker, and follow these principles:

- System-managed permissions
- Promise-based asynchronous APIs
- System-controlled UI presentation
- Secure and constrained access to media data

***

## CaptureInfo

```ts
type CaptureInfo = {
  cropRect: {
    x: number
    y: number
    width: number
    height: number
  } | null
  originalImage: UIImage | null
  editedImage: UIImage | null
  imagePath: string | null
  mediaMetadata: Record<string, any> | null
  mediaPath: string | null
  mediaType: string | null
}
```

`CaptureInfo` describes the complete result of a capture operation (photo or video).

### Properties

- `cropRect`
  The cropping rectangle applied during editing.
  `null` if no cropping was performed.

- `originalImage`
  The original image captured by the camera.

- `editedImage`
  The edited image, if editing was enabled and applied.

- `imagePath`
  File path to the captured image on disk.

- `mediaMetadata`
  Metadata associated with the captured media, such as EXIF data.

- `mediaPath`
  File path to the captured video.

- `mediaType`
  The UTType string describing the media type.

***

## availableMediaTypes()

```ts
function availableMediaTypes(): string[] | null
```

Returns the list of media UTTypes supported by the current device’s camera.

Common use cases include checking whether video capture is supported or dynamically adjusting capture options.

Returns `null` if the information is unavailable.

***

## capture(options)

```ts
function capture(options: {
  mode: "photo" | "video"
  mediaTypes: UTType[]
  allowsEditing?: boolean
  cameraDevice?: "rear" | "front"
  cameraFlashMode?: "auto" | "on" | "off"
  videoMaximumDuration?: DurationInSeconds
  videoQuality?: 
    | "low"
    | "medium"
    | "high"
    | "640x480"
    | "iFrame960x540"
    | "iFrame1280x720"
}): Promise<CaptureInfo | null>
```

Presents the system camera interface to capture a photo or record a video.

### Options

- `mode`
  Capture mode

  - `"photo"`: capture a photo
  - `"video"`: record a video

- `mediaTypes`
  Allowed media UTTypes.

- `allowsEditing`
  Whether the user can edit the captured media.

- `cameraDevice`
  Camera to use. Defaults to `"rear"`.

- `cameraFlashMode`
  Flash behavior. Defaults to `"auto"`.

- `videoMaximumDuration`
  Maximum video duration in seconds.

- `videoQuality`
  Video resolution and encoding quality.

### Behavior Notes

- The UI is fully system-managed
- The Promise resolves only after the user finishes or cancels the operation
- Permission prompts are handled by the system

***

## pick(options)

```ts
function pick(options?: {
  mode?: "default" | "compact"
  filter?: PHPickerFilter
  limit?: number
}): Promise<PHPickerResult[]>
```

Presents the system photo picker to select media items from the photo library.

### Options

- `mode`
  Picker layout style

  - `default`: grid layout
  - `compact`: linear layout

- `filter`
  A `PHPickerFilter` that restricts selectable asset types.

- `limit`
  Maximum number of selectable items. Defaults to `1`.

### Return Value

Returns an array of `PHPickerResult` objects.
Each result must be explicitly resolved into a concrete media representation.

***

## PHPickerFilter

`PHPickerFilter` defines which asset types can be selected in `Photos.pick`.

It is a non-instantiable class and can only be constructed via static methods.

***

### Basic Filters

- `PHPickerFilter.images()`
  Allows selection of standard images.

- `PHPickerFilter.videos()`
  Allows selection of videos.

- `PHPickerFilter.livePhotos()`
  Allows selection of Live Photos.

- `PHPickerFilter.bursts()`
  Burst photo sequences.

- `PHPickerFilter.panoramas()`
  Panorama photos.

- `PHPickerFilter.screenshots()`
  Screenshots.

- `PHPickerFilter.screenRecordings()`
  Screen recording videos.

- `PHPickerFilter.depthEffectPhotos()`
  Photos with depth effects (portrait photos).

- `PHPickerFilter.cinematicVideos()`
  Cinematic mode videos.

- `PHPickerFilter.slomoVideos()`
  Slow-motion videos.

- `PHPickerFilter.timelapseVideos()`
  Time-lapse videos.

***

### Composite Filters

- `PHPickerFilter.all(filters)`
  Matches assets that satisfy all provided filters
  Logical AND

- `PHPickerFilter.any(filters)`
  Matches assets that satisfy at least one filter
  Logical OR

- `PHPickerFilter.not(filter)`
  Excludes assets matching the specified filter
  Logical NOT

#### Example

```ts
const filter = PHPickerFilter.any([
  PHPickerFilter.livePhotos(),
  PHPickerFilter.images()
])

await Photos.pick({ filter })
```

***

## PHPickerResult

Represents a single item returned from the photo picker.

### itemProvider: ItemProvider

The item provider for the selected asset, which can be used to load the asset.

### livePhoto()

```ts
livePhoto(): Promise<LivePhoto | null>
```

Attempts to read the result as a Live Photo.
Resolves to `null` if the asset cannot be represented as a Live Photo.

***

### uiImage()

```ts
uiImage(): Promise<UIImage | null>
```

Attempts to read the result as a UIImage object.
Resolves to `null` if the asset cannot be represented as an image.

***

### imagePath()

```ts
imagePath(): Promise<string | null>
```

If this result can be read as an image, this file will be copied to the app group's sandbox and returns a promise that resolves to the image path, otherwise returns null, or rejects with an error. You should delete the image file when you no longer need it.

#### Example

```ts
const filePath = await result.imagePath()
```

***

### videoPath()

```ts
videoPath(): Promise<string | null>
```

If this result can be read as a video, this file will be copied to the app group's sandbox and returns a promise that resolves to the video path, otherwise returns null, or rejects with an error. You should delete the video file when you no longer need it.

***

## getLatestPhotos(count)

```ts
function getLatestPhotos(count: number): Promise<UIImage[] | null>
```

Retrieves the most recent photos from the photo library.

### Notes

- Images only (no videos)
- Ordered from newest to oldest
- Returns `null` if access is unavailable

***

## pickPhotos(count)

```ts
function pickPhotos(count: number): Promise<UIImage[]>
```

Legacy convenience API for selecting a fixed number of photos.

Returns an array of `UIImage` objects without file paths or metadata.

***

## takePhoto()

```ts
function takePhoto(): Promise<UIImage | null>
```

Quick photo capture API.

- No advanced configuration
- Returns `null` if the user cancels

***

## savePhoto(path, options)

```ts
function savePhoto(
  path: string,
  options?: { fileName?: string }
): Promise<boolean>
```

Saves an image file from disk to the Photos app.

***

## savePhoto(image, options)

```ts
function savePhoto(
  image: Data,
  options?: { fileName?: string }
): Promise<boolean>
```

Saves raw image data directly to the Photos app, avoiding temporary files.

***

## saveVideo(path, options)

```ts
function saveVideo(
  path: string,
  options?: { fileName?: string }
): Promise<boolean>
```

Saves a video file from disk to the Photos app.

***

## saveVideo(video, options)

```ts
function saveVideo(
  video: Data,
  options?: { fileName?: string }
): Promise<boolean>
```

Saves raw video data directly to the Photos app.

***

## Photo Asset Layer

Beyond the transactional pick/capture/save APIs, the module exposes the underlying photo library as addressable assets. This lets scripts enumerate the library, read metadata, load media at controlled sizes, and manage albums.

### authorizationStatus(accessLevel?)

```ts
function authorizationStatus(
  accessLevel?: "addOnly" | "readWrite"
): "notDetermined" | "restricted" | "denied" | "authorized" | "limited"
```

Returns the current authorization status without prompting. Access is requested automatically the first time you read or write the library. Defaults to `"readWrite"`.

### fetchAssets(options?)

```ts
function fetchAssets(options?: PHFetchOptions): Promise<PHAsset[]>
function fetchAssets(localIdentifiers: string[]): Promise<PHAsset[]>
```

Fetch assets matching `PHFetchOptions`, or fetch specific assets by their local identifiers.

```ts
type PHFetchOptions = {
  mediaType?: "image" | "video" | "audio"
  mediaSubtypes?: PHAssetMediaSubtype[]
  favoritesOnly?: boolean
  includeHidden?: boolean
  includeAllBurstAssets?: boolean
  sortBy?: "creationDate" | "modificationDate"
  ascending?: boolean
  limit?: number
  createdAfter?: number   // milliseconds since epoch
  createdBefore?: number
}
```

`PHAssetMediaSubtype` is one of `"photoPanorama"`, `"photoHDR"`, `"photoScreenshot"`, `"photoLive"`, `"photoDepthEffect"`, `"videoStreamed"`, `"videoHighFrameRate"`, `"videoTimelapse"`.

```ts
const recent = await Photos.fetchAssets({
  mediaType: "image",
  favoritesOnly: true,
  limit: 20,
})
```

### fetchAsset(localIdentifier)

```ts
function fetchAsset(localIdentifier: string): Promise<PHAsset | null>
```

Fetch a single asset by its stable `localIdentifier`. Store the identifier to reference the same asset across script runs.

***

## PHAsset

A reference to an image, video, or Live Photo in the library.

### Properties

- `localIdentifier: string` — stable, persistent identifier.
- `mediaType: "image" | "video" | "audio" | "unknown"`
- `mediaSubtypes: PHAssetMediaSubtype[]`
- `pixelWidth: number`, `pixelHeight: number`
- `creationDate: number | null`, `modificationDate: number | null` — milliseconds since epoch.
- `duration: number` — seconds; `0` for images.
- `isFavorite: boolean`, `isHidden: boolean`
- `location: PHAssetLocation | null` — latitude, longitude, altitude, accuracies, speed, course, timestamp.
- `burstIdentifier: string | null`, `representsBurst: boolean`
- `sourceType: "userLibrary" | "cloudShared" | "itunesSynced" | "unknown"`

### requestImage(options?)

```ts
requestImage(options?: {
  targetWidth?: number
  targetHeight?: number
  contentMode?: "aspectFit" | "aspectFill"
  deliveryMode?: "opportunistic" | "highQualityFormat" | "fastFormat"
  version?: "current" | "original" | "unadjusted"
  allowNetworkAccess?: boolean
}): Promise<UIImage | null>
```

Loads a `UIImage` at the requested size. Omit the target size to load the full resolution. Downloads from iCloud when needed unless `allowNetworkAccess` is `false`.

### requestImageData(options?)

```ts
requestImageData(options?: {
  version?: "current" | "original" | "unadjusted"
  allowNetworkAccess?: boolean
}): Promise<{ data: Data; uti: UTType; orientation: number } | null>
```

Loads the original file data, its uniform type identifier, and EXIF orientation.

### requestVideoURL(options?)

```ts
requestVideoURL(options?: {
  version?: "current" | "original" | "unadjusted"
  allowNetworkAccess?: boolean
}): Promise<string | null>
```

Exports the asset's video to a temporary file in the app sandbox and resolves its path. Delete the file when no longer needed. Resolves `null` for assets without video.

### requestLivePhoto(options?)

```ts
requestLivePhoto(options?: {
  targetWidth?: number
  targetHeight?: number
  allowNetworkAccess?: boolean
}): Promise<LivePhoto | null>
```

Loads a `LivePhoto` representation, or `null` if the asset is not a Live Photo.

### setFavorite(value) / delete()

```ts
setFavorite(value: boolean): Promise<boolean>
delete(): Promise<boolean>
```

Mark/unmark as favorite, or delete the asset. Deletion presents a system confirmation prompt; resolves `false` if the user cancels.

***

## Albums

### fetchAlbums(options?) / fetchAlbum(localIdentifier)

```ts
function fetchAlbums(options?: {
  type?: "album" | "smartAlbum"
  assetCollectionSubtype?: string
}): Promise<PHAssetCollection[]>

function fetchAlbum(localIdentifier: string): Promise<PHAssetCollection | null>
```

Fetch albums and smart albums. Omit `type` to fetch both.

### createAlbum(title) / deleteAlbums(albums) / deleteAssets(assets)

```ts
function createAlbum(title: string): Promise<PHAssetCollection | null>
function deleteAlbums(albums: PHAssetCollection[]): Promise<boolean>
function deleteAssets(assets: PHAsset[]): Promise<boolean>
```

Create a user album, delete albums, or batch-delete assets. Deletions present a system confirmation prompt.

## PHAssetCollection

- `localIdentifier: string`
- `title: string | null`
- `type: "album" | "smartAlbum" | "moment"`
- `subtype: string` — e.g. `"smartAlbumUserLibrary"`, `"smartAlbumFavorites"`, `"albumRegular"`.
- `estimatedAssetCount: number` — the asset count; falls back to an exact count when the fast estimate is unavailable (common for smart albums).
- `startDate: number | null`, `endDate: number | null`

```ts
fetchAssets(options?: PHFetchOptions): Promise<PHAsset[]>
addAssets(assets: PHAsset[]): Promise<boolean>
removeAssets(assets: PHAsset[]): Promise<boolean>
```

`addAssets` / `removeAssets` are valid only for user-created albums.

```ts
const album = await Photos.createAlbum("My Script Album")
const favorites = await Photos.fetchAssets({ favoritesOnly: true, limit: 10 })
await album?.addAssets(favorites)
```

***

## Design Notes

- All APIs are asynchronous and permission-aware
- All UI is system-managed and not customizable
- Picker results are lazy and must be explicitly resolved
- Save APIs return only success status, not asset identifiers
- `PHAsset` is addressable by `localIdentifier`; persist it to reload the same asset later
- Mutating operations (favorite, delete, album changes) require write access and may present system prompts



---
url: /guide/Changelog/3.1.0/Photos/index_example.md
---

# Example

```tsx
import { Button, Dialog, List, Navigation, NavigationStack, Script, Section, Text, } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <List
      navigationTitle={"Photos"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section
        footer={
          <Text>Get the latest specified number of photos from the Photos app.</Text>
        }
      >
        <Button
          title={"Photos.getLatestPhotos"}
          action={async () => {
            const images = await Photos.getLatestPhotos(1)
            const image = images?.[0]

            if (image != null) {
              Dialog.alert({
                message: `Image size: ${image.width}*${image.height}`
              })
            } else {
              Dialog.alert({
                message: "Cancelled"
              })
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Present a photo picker dialog and pick limited number of photos.</Text>
        }
      >

        <Button
          title={"Photos.pickPhotos"}
          action={async () => {
            const images = await Photos.pickPhotos(1)
            const image = images?.[0]

            if (image != null) {
              Dialog.alert({
                message: `Image size: ${image.width}*${image.height}`
              })
            } else {
              Dialog.alert({
                message: "Cancelled"
              })
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Take a photo and return a UIImage instance.</Text>
        }
      >
        <Button
          title={"Photos.takePhoto"}
          action={async () => {
            const image = await Photos.takePhoto()

            if (image != null) {
              Dialog.alert({
                message: `Image size: ${image.width}*${image.height}`
              })
            } else {
              Dialog.alert({
                message: "Cancelled"
              })
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Save an image to the Photos app. Returns a boolean value indicates that whether the operation is successful.</Text>
        }
      >
        <Button
          title={"Photos.savePhoto"}
          action={async () => {
            const image = await Photos.takePhoto()

            if (image != null) {
              const success = await Photos.savePhoto(Data.fromJPEG(image, 0.5)!)
              Dialog.alert({
                message: "The photo has been saved: " + success
              })
            } else {
              Dialog.alert({
                message: "Canceled"
              })
            }
          }}
        />
      </Section>

      <Section
        header={<Text>Photo Asset Layer</Text>}
        footer={
          <Text>Query the library and read rich metadata (date, dimensions, location, subtypes) from each PHAsset.</Text>
        }
      >
        <Button
          title={"Photos.fetchAssets"}
          action={async () => {
            const status = Photos.authorizationStatus()
            const assets = await Photos.fetchAssets({ mediaType: "image", limit: 5 })
            const newest = assets[0]

            if (newest == null) {
              Dialog.alert({ message: `No photos found. (status: ${status})` })
              return
            }

            const created = newest.creationDate != null
              ? new Date(newest.creationDate).toLocaleString()
              : "unknown"
            const where = newest.location != null
              ? `${newest.location.latitude.toFixed(3)}, ${newest.location.longitude.toFixed(3)}`
              : "none"

            Dialog.alert({
              message: [
                `Fetched ${assets.length} asset(s).`,
                `Newest: ${newest.pixelWidth}×${newest.pixelHeight}`,
                `Created: ${created}`,
                `Favorite: ${newest.isFavorite}`,
                `Subtypes: ${newest.mediaSubtypes.join(", ") || "none"}`,
                `Location: ${where}`,
              ].join("\n")
            })
          }}
        />

        <Button
          title={"Asset.requestImage (thumbnail)"}
          action={async () => {
            const assets = await Photos.fetchAssets({ mediaType: "image", limit: 1 })
            const asset = assets[0]
            if (asset == null) {
              Dialog.alert({ message: "No photos found." })
              return
            }
            const image = await asset.requestImage({
              targetWidth: 200,
              targetHeight: 200,
              contentMode: "aspectFill",
            })
            Dialog.alert({
              message: image != null
                ? `Loaded thumbnail: ${image.width}×${image.height}`
                : "Failed to load image."
            })
          }}
        />

        <Button
          title={"Photos.fetchAlbums"}
          action={async () => {
            const albums = await Photos.fetchAlbums({ type: "smartAlbum" })
            const titles = albums
              .slice(0, 8)
              .map(a => `• ${a.title ?? a.subtype} (${a.estimatedAssetCount})`)
              .join("\n")
            Dialog.alert({
              message: `Found ${albums.length} smart album(s):\n${titles}`
            })
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Changelog/3.1.0/Python.md
---

# Python

The `Python` global runs Python code snippets inside the Scripting app via the embedded Python interpreter — the same runtime that powers Python index scripts. Useful for one-off computations, ad-hoc data wrangling, or invoking Python libraries from a JS / TS script without registering a separate Python script.

Code is executed using `python -c <code>`, so each call runs a fresh top-level module — module state from previous calls is **not** preserved. Imports and computed values must be set up inside `code` itself.

`Shell.run` and `Python.run` share a single serial queue: while one is running, others wait. The embedded Python interpreter shares global state (env vars, `sys.modules`) with `ios_system`, so the two cannot run concurrently.

> The current version does **not** honor `options.timeout` — long-running Python snippets will block subsequent `Shell.run` / `Python.run` calls until they finish. Wrap your code with your own timeout logic if needed.

***

## Methods

### `Python.run(code, options?): Promise<{ output, exitCode }>`

Execute a Python code snippet. Returns when the snippet exits.

```ts
function run(code: string, options?: ShellRunOptions): Promise<{
  output: string
  exitCode: number
}>
```

#### `ShellRunOptions`

| Name            | Type                    | Required | Description                                                                                                                             |
| --------------- | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| cwd             | string                  | No       | Working directory for the snippet (`os.getcwd()` inside Python). Restored after the call.                                               |
| env             | Record\<string, string> | No       | Extra environment variables. Injected into `os.environ` (Python-level) and into the process via `setenv`, then restored after the call. |
| queryParameters | Record\<string, string> | No       | Convenience field — serialized as JSON and exposed as `os.environ["SCRIPTING_QUERY_PARAMETERS"]`. Mirrors `Script.queryParameters`.     |
| timeout         | number                  | No       | **Not honored** in the current version (kept for API parity with `Shell.run`).                                                          |

#### Result

| Name     | Type   | Description                                                                                                                                                 |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| output   | string | Combined stdout + stderr produced by the snippet.                                                                                                           |
| exitCode | number | `0` on success. Non-zero values (e.g. when the snippet raises an unhandled exception) resolve normally; only argument validation errors reject the promise. |

> Unlike `Shell.run`, the Python.run result does **not** include `timedOut` / `cancelled` fields, because the underlying Python bridge has no timeout / cancel primitives.

***

## env injection note

The embedded Python interpreter snapshots `os.environ` at first `Py_Initialize`, so plain `setenv` from Swift does **not** propagate to subsequent reads of `os.environ`. To make `env` and `queryParameters` actually visible inside the snippet, the host injects a small prelude before your code that updates `os.environ` at the Python layer. This is transparent — your `code` runs as-is. Subprocesses spawned by the snippet (via `subprocess`, `os.system`, etc.) also see the variables because `setenv` is still applied.

***

## Examples

### Basic snippet

```ts
const r = await Python.run("print(1 + 2)")
console.log(r.output)   // "3\n"
console.log(r.exitCode) // 0
```

### Reading parameters

```ts
const r = await Python.run(`
import os, json
qp = json.loads(os.environ["SCRIPTING_QUERY_PARAMETERS"])
print(f"hello {qp['name']}")
`, {
  queryParameters: { name: "Alice" },
})
console.log(r.output) // "hello Alice\n"
```

### Using a Python library

```ts
const r = await Python.run(`
import statistics
data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
print(f"mean={statistics.mean(data):.2f}")
print(f"stdev={statistics.stdev(data):.2f}")
`)
console.log(r.output)
// mean=5.50
// stdev=3.03
```

### Handling errors

```ts
const r = await Python.run("raise RuntimeError('boom')")
if (r.exitCode !== 0) {
  console.log("snippet failed:")
  console.log(r.output) // contains the Python traceback
}
```

### Working directory

```ts
const r = await Python.run("import os; print(os.listdir('.'))", {
  cwd: "/tmp",
})
console.log(r.output) // contents of /tmp
```



---
url: /guide/Changelog/3.1.0/Redirect Rules.md
---

# Redirect Rules

Redirect Rules automatically rewrite a page's address in Safari and send you to a different one — for example, sending every `www.reddit.com` page to `old.reddit.com`, or a mobile site to its desktop version.

This feature requires Scripting PRO.

***

## How It Works

When you navigate to a page, Scripting checks its URL against your enabled rules in order. The first rule whose pattern matches rewrites the URL using its target template, and Safari is redirected there.

Each rule has a **match mode**:

- **Wildcard** (default, recommended) — `*` matches any run of characters. Each `*` becomes a capture you can reuse in the target as `$1`, `$2`, and so on.
- **Regex** (advanced) — the pattern is a regular expression matched against the whole URL. Use `$0` for the whole match and `$1`–`$9` for capture groups.

The rewritten address must start with `http://` or `https://`.

***

## Add a Rule

In the Safari Browser Scripts settings, open **Redirect Rules** and tap **Add**:

- **Name** — an optional label for the list.
- **Match mode** — Wildcard or Regex.
- **Match pattern** — the URL pattern to match.
- **Redirect to** — the target template, using `$1`, `$2`, … (or `$0` in regex mode).
- **Test** — enter a sample URL to preview the rewrite before saving.

Each rule has an **Enabled** switch. Tap a row to edit it, or swipe to delete.

***

## Examples

**Wildcard** — Reddit to old.reddit:

```
Pattern:  *://www.reddit.com/*
Redirect: https://old.reddit.com/$2
```

`https://www.reddit.com/r/swift` becomes `https://old.reddit.com/r/swift`. (`$1` captured the scheme, `$2` the path.)

**Regex** — mobile Wikipedia to desktop:

```
Pattern:  ^https://([a-z]+)\.m\.wikipedia\.org/(.*)$
Redirect: https://$1.wikipedia.org/$2
```

`https://en.m.wikipedia.org/wiki/Swift` becomes `https://en.wikipedia.org/wiki/Swift`.

***

## Notes

- Rules apply to top-level page navigation only, not to content embedded inside a page.
- A rule that would keep matching its own output will not loop endlessly — once a target has been used for a page, it is not redirected to again.
- Prefer Wildcard mode when you can. Keep regular expressions simple; a very complex regex can slow down matching.
- Changes you make in the settings take effect on your next navigation.



---
url: /guide/Changelog/3.1.0/Remote Push.md
---

# Remote Push

Remote Push lets your devices receive push notifications sent from your own servers and automations. After setting it up, you get a single API key that you call over HTTPS to deliver notifications to your registered devices.

***

## Getting Your API Key

Open **Tools → Remote Push** and tap **Set Up Remote Push**. This registers the current device and issues one API key for your account.

- The API key is shared across every device signed in with the same Apple ID.
- One key can have multiple registered devices.
- Keep the key private — anyone who has it can send notifications to your devices.

On the same page you can rename devices, toggle delivery per device, send a test push, and review recent logs.

***

## Base URL & Authentication

```
https://push.scripting.fun
```

All endpoints require your API key as a Bearer token:

```
Authorization: Bearer <your_api_key>
```

***

## Send a Push

### `POST /push`

Send a notification to specific devices, or to all of your devices.

```ts
POST /push
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "title": "Build finished",
  "body": "Your deploy completed successfully.",
  "deviceIds": ["a8336eb5-708b-4e4c-93a0-d8a3feb99e89"],
  "action": "scripting://run/MyScript?action=Deploy",
  "image": "https://example.com/preview.jpg",
  "icon": "hammer.fill",
  "iconColor": "systemOrange",
  "actionButtons": [
    { "label": "Open Logs", "action": "scripting://run/MyScript?action=Logs" },
    { "label": "Re-run", "action": "scripting://run/MyScript?action=Rerun" }
  ],
  "badge": 1,
  "sound": "default"
}
```

### Parameters

| Name              | Type      | Required | Description                                                                                                                                                                                 |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title             | string    | Yes      | Notification title.                                                                                                                                                                         |
| body              | string    | Yes      | Notification body text.                                                                                                                                                                     |
| deviceIds         | string\[] | No       | Target device IDs (UUIDs). Omit to send to all of your active devices. Devices with delivery turned off are always skipped.                                                                 |
| action            | string    | No       | A URL scheme opened when the notification is tapped (for example a `scripting://` deep link).                                                                                               |
| image             | string    | No       | A remote image URL. The image is downloaded on the device and shown in the expanded (long‑press) notification.                                                                              |
| icon              | string    | No       | An SF Symbol name (e.g. `hammer.fill`) or a remote image URL, shown as the sender avatar.                                                                                                   |
| iconColor         | string    | No       | Tint color for an SF Symbol `icon`: a named color (`systemRed`, `label`, ...), `#RGB`/`#RRGGBB`, `rgb()/rgba()`, or `hsl()/hsla()`. Defaults to `systemBlue`. Ignored when `icon` is a URL. |
| actionButtons     | object\[] | No       | Custom buttons shown when the notification is long‑pressed. Each item is `{ "label": string, "action": string }`, where `action` is a URL scheme opened on tap.                             |
| badge             | number    | No       | App icon badge number.                                                                                                                                                                      |
| sound             | string    | No       | Notification sound name. Defaults to `default`.                                                                                                                                             |
| category          | string    | No       | Notification category identifier.                                                                                                                                                           |
| threadId          | string    | No       | Thread identifier used to group notifications.                                                                                                                                              |
| interruptionLevel | string    | No       | How the notification interrupts: `passive`, `active` (default), `time-sensitive`, or `critical`.                                                                                            |
| criticalVolume    | number    | No       | Sound volume `0.0`–`1.0` for `critical` alerts (default `1.0`). Ignored unless `interruptionLevel` is `critical`.                                                                           |

> `image`, `icon`, and `actionButtons` produce a rich notification: long‑press (or pull down) the delivered notification to see the image, avatar, and action buttons. The server enables the required `mutable-content` flag automatically.

> `time-sensitive` notifications break through Focus modes and the scheduled notification summary. `critical` alerts additionally bypass the mute switch and Do Not Disturb and always play a sound — but they require Apple's Critical Alerts entitlement on the app. Until that entitlement is approved, a `critical` push automatically falls back to `time-sensitive`.

### Response

```json
{
  "ok": true,
  "data": {
    "push_id": "uuid",
    "target_devices": 2,
    "sent_at": "2026-05-25T10:00:00.000Z",
    "results": [
      { "deviceId": "a8336eb5-...", "status": "sent", "apnsId": "uuid" },
      { "deviceId": "b7220fa4-...", "status": "failed", "errorCode": "BadDeviceToken" }
    ],
    "daily_limit": 1000,
    "remaining": 985
  }
}
```

`remaining` and `daily_limit` in the body reflect your quota after this push. The `X-Push-Limit-Remaining` response header carries the same remaining count (measured before the push) and is also present on rate-limit errors.

***

## List Devices

### `GET /devices`

List your registered devices. Use each device `id` for the `deviceIds` array when sending a push.

```json
{
  "ok": true,
  "data": {
    "devices": [
      {
        "id": "a8336eb5-708b-4e4c-93a0-d8a3feb99e89",
        "device_name": "iPhone 15",
        "is_active": true,
        "push_enabled": true,
        "created_at": "2026-05-25T10:00:00.000Z"
      }
    ],
    "total": 1
  }
}
```

A device with `push_enabled: false` stays in the list but is skipped when sending pushes.

***

## Subscription Keys

Sometimes you want a third party — a subscription source, a feed, an automation you don't fully control — to push to your devices, without handing over your master API key (which can also manage devices, read your subscription, and mint more keys).

In **Tools → Remote Push → Subscription Keys** you can mint **send-only** keys derived from your master key:

- A subscription key can only `POST /push` to **your** devices. Every management endpoint (devices, key info, other subscription keys, logs, stats) is rejected with `MASTER_KEY_REQUIRED`.
- It uses the exact same request as the master key — just put the subscription key in the `Authorization: Bearer` header.
- Its pushes count against your account's shared daily limit.
- You can disable (reversible) or delete (permanent) a subscription key from the app at any time. A disabled or deleted key immediately stops working.

This lets a single source serve many users: each user mints one subscription key and hands it over; the source pushes to each user through that user's key, and any user can cut it off independently.

***

## Daily Limit & Statistics

### `GET /push/limit`

Returns the daily push limit and how many remain.

```json
{
  "data": {
    "date": "2026-05-25",
    "push_count": 15,
    "limit": 1000,
    "remaining": 985
  }
}
```

### `GET /push/stats`

Returns overall and daily push statistics, including totals and success rate.

***

## Push Logs

### `GET /push/logs`

Returns recent push history. Accepts an optional `limit` query parameter (1–100, default 50).

```
GET /push/logs?limit=20
```

***

## Example

```bash
curl -X POST https://push.scripting.fun/push \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","body":"World"}'
```

***

## Bark-Compatible API

This server also speaks the [Bark](https://github.com/Finb/Bark) API, so Bark-compatible tools and scripts work by pointing them at `https://push.scripting.fun` and using one of your **subscription keys** as the Bark key.

### Endpoints

- `GET|POST /:key/:body`
- `GET|POST /:key/:title/:body`
- `GET|POST /:key/:title/:subtitle/:body`
- `POST /:key` — all fields in the JSON body
- `POST /push` — with `device_key` (or a `device_keys` array) in the JSON body
- `GET /ping`, `GET /healthz`, `GET /info`, `GET /register/:key`

`key` / `device_key` is a subscription key (Tools → Remote Push → Subscription Keys). It pushes to your registered devices and counts against your account's shared daily limit.

### Supported parameters

`title`, `subtitle`, `body`, `level` (`active` / `timeSensitive` / `passive` / `critical`), `badge`, `sound`, `icon` (URL), `group`, `url`, `copy`, `autoCopy`, `call`, `volume`, `ciphertext` + `iv`, `id`.

- `sound` — a built-in Bark sound name such as `minuet`.
- `call=1` — repeats the sound for \~30 seconds.
- `level=critical` with `volume` (0–10) — a critical alert. Requires the app's Critical Alerts entitlement; until that is approved by Apple it falls back to `time-sensitive`.
- `url` — opened when the notification is tapped.
- `copy` — long-press the notification and tap **Copy** to copy this text (or the whole body if omitted). `autoCopy=1` copies on delivery.
- `badge` — sets the app icon badge; send `badge=0` to clear it (iOS keeps the last badge until you explicitly reset it).
- Encrypted push — set the AES key in **Tools → Remote Push → Encryption**, then send `ciphertext` (base64) and an optional `iv`.

`markdown` is treated as plain text; `isArchive` / `ttl` are ignored (there is no in-app message history).

### Example

```bash
curl "https://push.scripting.fun/<key>/Build%20finished/Deploy%20succeeded?sound=minuet&group=ci"
```

***

## Rate Limiting

- Each account has a daily push limit, shared across the account's keys (master and subscription keys). Check the current limit and remaining count with `GET /push/limit`.
- The `X-Push-Limit-Remaining` response header shows the remaining count.



---
url: /guide/Changelog/3.1.0/Rime.md
---

# 

***

title: Rime
description: Added a programmable Chinese input-method engine: load schemas, feed key events, render candidates, and commit text from JavaScript in both the main app and the keyboard extension.
tag: PRO
--------

The `Rime` namespace exposes a programmable Chinese input-method engine that ships with the main app and the keyboard extension. Use it to build custom input flows: load schemas, feed key events, render candidates yourself, and commit the chosen text.

The engine is process-global; you set it up once and create one `Rime.Session` per input session.

***

## Data directories

`Rime` reads schemas/dictionaries from a **shared data directory** and stores user state (user dictionaries, build cache) in a **user data directory**. Both default to the app group container shared between the main app and the keyboard extension, so the schemas you import in the main app are immediately available from the keyboard.

- `Rime.sharedDataDir` — string path to the shared (read-only) directory.
- `Rime.userDataDir` — string path to the user directory.

You may override either path when calling `Rime.setup({ sharedDataDir, userDataDir })`, for example when running tests in a private sandbox.

***

## Lifecycle

### `Rime.setup(options?): Promise<void>`

Initializes the engine. Call this once before any other `Rime.*` API. Subsequent calls in the same process resolve successfully without re-initializing.

```ts
await Rime.setup()
// or:
await Rime.setup({
  sharedDataDir: "/path/to/shared",
  userDataDir: "/path/to/user",
  appName: "my.input.method",  // log identifier
})
```

### `Rime.deploy(options?): Promise<void>`

Recompiles schemas and rebuilds user dictionaries when needed. Call after importing or modifying schema/dict files in `sharedDataDir`.

```ts
await Rime.deploy()
await Rime.deploy({ fullCheck: true })  // force a full rebuild
```

### Status getters (synchronous)

```ts
Rime.version       // string, e.g. "1.16.1"
Rime.isSetUp       // boolean
Rime.isDeploying   // boolean
```

***

## Schemas

### `Rime.listSchemas(): Promise<{ id, name }[]>`

```ts
const schemas = await Rime.listSchemas()
// [{ id: "luna_pinyin", name: "朙月拼音" }, ...]
```

### `Rime.getCurrentSchema(): { id, name } | null`

Returns the engine-wide current schema, or `null` when no schema is active.

### `Rime.selectSchema(schemaId): Promise<void>`

Switches the engine-wide default schema. New sessions created after this call inherit the new schema; existing sessions keep their previous schema until you call `session.selectSchema(id)` on them.

```ts
await Rime.selectSchema("luna_pinyin")
```

***

## Engine-wide options

These flags (e.g. `ascii_mode`, `full_shape`, `simplification`) are propagated to new sessions through an internal shared session. Per-session overrides are still possible via `session.setOption(...)`.

```ts
Rime.getOption("ascii_mode")           // boolean
Rime.setOption("ascii_mode", true)
Rime.getProperty("language")           // string | null
Rime.setProperty("language", "zh")
```

***

## Notifications

`Rime.onNotification` is a single optional handler invoked on the main thread when the engine fires events.

```ts
Rime.onNotification = (event) => {
  switch (event.type) {
    case "deployStart":
    case "deploySuccess":
    case "deployFailure":
      // event.sessionId — usually 0 for engine-wide events
      break
    case "schemaChanged":
      // event.schemaId, optional event.schemaName
      break
    case "optionChanged":
      // event.option (string), event.enabled (boolean)
      break
    case "other":
      // event.raw = { type, value } — unrecognised events
      break
  }
}

// Detach when no longer needed:
Rime.onNotification = null
```

To support multiple subscribers, fan out from one handler:

```ts
const subs = []
Rime.onNotification = (e) => subs.forEach((s) => s(e))
```

***

## `Rime.Session`

A session represents a single input attempt. Create one with `new Rime.Session()` and release it with `session.close()` when done.

```ts
const session = new Rime.Session()
try {
  if (!session.processKey(charCode)) {
    // engine did not consume the key — pass it through to the host text field
    CustomKeyboard.insertText(String.fromCharCode(charCode))
  }
  if (session.commit) {
    CustomKeyboard.insertText(session.commit)
  }
  if (session.context?.preedit) {
    CustomKeyboard.setMarkedText(session.context.preedit, 0, 0)
  } else {
    CustomKeyboard.unmarkText()
  }
} finally {
  session.close()
}
```

### Key handling

```ts
session.processKey(keyCode: number, modifiers?: number): boolean
```

`keyCode` uses X11 keysym values (e.g. `'w'.charCodeAt(0)` is `0x77`, `Return` is `0xff0d`). Returns `true` when the engine consumed the key.

### Composition state

```ts
session.context  // Rime.Context | null — fresh snapshot per access
session.commit   // string | null — drains pending commit text
session.status   // Rime.Status | null — schema + mode flags
```

`session.context` has the shape:

```ts
{
  preedit: string | null,
  cursorPos: number,
  selectionStart: number,
  selectionEnd: number,
  commitTextPreview?: string,
  selectKeys?: string,
  selectLabels?: string[],
  menu: {
    pageNo: number,
    pageSize: number,
    isLastPage: boolean,
    highlightedIndex: number,
    candidates: Array<{ text: string, comment: string | null }>,
  } | null,
}
```

### Candidate selection

```ts
session.selectCandidate(index: number): boolean              // absolute index in the full menu
session.selectCandidateOnCurrentPage(index: number): boolean // 0-based on current page
```

### Commit / clear

```ts
session.commitComposition(): { text: string | null } | null  // force commit
session.clearComposition(): void                              // discard
```

### Per-session schema and options

```ts
session.selectSchema(schemaId: string): boolean
session.setOption(name: string, value: boolean): void
session.getOption(name: string): boolean
session.setProperty(name: string, value: string): void
session.getProperty(name: string): string | null
session.currentSchema  // { id, name } | null (derived from status)
```

### Closing

```ts
session.close(): void
```

After `close()`, all methods become no-ops (`processKey` returns `false`, `context` returns `null`, etc.) and `session.closed` is `true`. Calling `close()` again is safe.

***

## End-to-end example

```ts
await Rime.setup()
await Rime.deploy()

const session = new Rime.Session()

try {
  // type "wo"
  session.processKey(0x77 /* w */)
  session.processKey(0x6f /* o */)

  const ctx = session.context!
  console.log(ctx.preedit)                       // "wo"
  console.log(ctx.menu?.candidates[0].text)      // "我"

  // accept first candidate
  session.selectCandidate(0)
  console.log(session.commit)                    // "我"
} finally {
  session.close()
}
```

***

## Notes

- The shared and user directories must exist and be writable. The default app-group locations are created on first `setup()` automatically.
- The engine deploys schemas in the background; render a "loading" indicator while `Rime.isDeploying` is `true`.
- To switch between Chinese and ASCII (English) modes from a key, your schema needs a `key_binder` section. Without one, `Rime.setOption("ascii_mode", true)` still works, but a Shift-toggle key will not.
- Importing user dictionaries: drop `.dict.yaml` files into `sharedDataDir`, then call `Rime.deploy()`.



---
url: /guide/Changelog/3.1.0/Safari Browser Scripts.md
---

# Safari Browser Scripts

Safari Browser Scripts let Scripting run userscripts in Safari through the Safari Web Extension. The runtime supports Greasemonkey-style `GM.*` APIs and selected Scripting APIs.

***

## Where Scripts Run

There are two sources:

- `browser.tsx` in a Scripting script project. It is built to `browser.js`.
- Installed `.user.js` / `.js` files from Safari's extension popup.

Scripts installed from Safari's extension popup are stored under:

```ts
scripting-safari-extension/userscripts/
```

Downloads and GM storage live in the same root:

```ts
scripting-safari-extension/downloads/
scripting-safari-extension/storages/
```

This root follows the Safari Browser Data storage location configured in Settings, including WebDAV when enabled.

***

## Script Format

Create or install a `.user.js` / `.js` file with a userscript metadata block:

```js
// ==UserScript==
// @name GitHub Demo
// @match https://github.com/*
// @grant GM.log
// @grant Scripting.FileManager
// ==/UserScript==

GM.log("loaded", location.href)
```

Common metadata keys:

```ts
// @name
// @namespace
// @version
// @description
// @author
// @match
// @include
// @exclude
// @exclude-match
// @connect
// @grant
// @require
// @resource
// @run-at document-start | document-body | document-end | document-idle
// @inject-into auto | content | page
// @weight 1..999
// @noframes
// @homepageURL
// @supportURL
// @updateURL
// @downloadURL
// @license
```

`@weight` controls execution order when multiple scripts match the page. Larger weights run first. If no `@run-at` is provided, scripts run at `document-end`.

`@inject-into` defaults to `auto`. With `auto`, a script that declares any `@grant` (`GM.*` or `Scripting.*`) runs in the **content world** (privileged APIs available, isolated from the page's JavaScript), while a script with `@grant none` or no grant runs in the **page world** (shares the page's real `window`, can read page globals). Use `@inject-into content` or `@inject-into page` to force a world explicitly. `GM.*`, `Scripting.*`, and extension messaging are only available in the content world; grants are ignored in the page world. On pages whose Content-Security-Policy blocks injected scripts, `auto` page-world scripts automatically fall back to the content world.

***

## Permissions

Privileged APIs must be declared with `@grant`.

```js
// @grant GM.getValue
// @grant GM.setValue
// @grant GM.xmlHttpRequest
// @grant GM.cookie
// @grant Scripting.FileManager
```

`@grant none` disables GM APIs, but `GM_info` and `GM.info` remain available for compatibility.

Cross-origin network, download, resource, and cookie access must be allowed with `@connect`.

```js
// @connect api.github.com
// @connect https://api.github.com/*
// @connect *
```

When a required grant or connect rule is missing, the runtime throws an error with a stable `code` such as `permissionDenied` or `connectDenied`.

***

## `GM_info`

`GM_info` and `GM.info` expose parsed metadata and runtime details:

```ts
GM_info.script.name
GM_info.script.version
GM_info.script.matches
GM_info.script.connects
GM_info.script.runAt
GM_info.script.injectInto
GM_info.script.weight
GM_info.scriptHandler
GM_info.version
```

***

## Supported GM APIs

### Storage

```ts
await GM.getValue(key, defaultValue)
await GM.setValue(key, value)
await GM.deleteValue(key)
await GM.listValues()

const id = GM.addValueChangeListener(key, (key, oldValue, newValue, remote) => {})
GM.removeValueChangeListener(id)
```

GM storage is stored as JSON under `scripting-safari-extension/storages/`.

### DOM and Menu

```ts
GM.log(...items)
GM.addStyle(css)
GM.addElement("div", { textContent: "Hello" })
GM.addElement(document.body, "button", { textContent: "Run" })

const id = GM.registerMenuCommand("Run", () => {})
GM.unregisterMenuCommand(id)
GM.removeMenuCommand(id)
```

Menu commands are shown in Safari's extension popup for the current page.

### Tabs, Clipboard, Notification

```ts
const tab = await GM.openInTab("https://github.com/trending", { active: false })
tab.close()
await GM.closeTab()

await GM.setClipboard("Hello")
await GM.notification({ title: "Scripting", text: "Done" })
```

`GM.closeTab()` closes the current tab when supported by Safari. `GM.openInTab()` returns a tab control with `close()`.

### Resources

```ts
const text = await GM.getResourceText("name")
const url = await GM.getResourceURL("name")
```

Declare resources in the metadata block:

```js
// @resource name https://example.com/file.txt
```

### Download

```ts
await GM.download({
  url: "https://example.com/file.txt",
  name: "file.txt",
  onload(response) {
    GM.log(response.path)
  }
})
```

Downloaded files are stored under `scripting-safari-extension/downloads/`.

### XHR

```ts
await GM.xmlHttpRequest({
  method: "GET",
  url: "https://api.github.com/zen",
  responseType: "text",
  overrideMimeType: "text/plain",
  onloadstart(event) {},
  onprogress(event) {},
  onreadystatechange(response) {},
  onload(response) {},
  onloadend(response) {}
})
```

The runtime supports `responseType` values `text`, `json`, `arraybuffer`, `blob`, and `document`, plus `user`, `password`, `headers`, `data`, `timeout`, `binary`, `overrideMimeType`, `upload` callbacks, `finalUrl`, and `responseURL`.

### Cookies

```ts
await GM.cookie.set({
  url: location.href,
  name: "scripting_test",
  value: "1",
  path: "/",
  secure: true
})

const cookies = await GM.cookie.list({ url: location.href, name: "scripting_test" })
await GM.cookie.delete({ url: location.href, name: "scripting_test" })
```

Callback style is also supported:

```ts
GM.cookie.list({ url: location.href }, cookies => {
  GM.log(cookies)
})
```

***

## `Scripting.FileManager`

Use `@grant Scripting.FileManager` or `@grant Scripting.*` to access the API.

### Properties

```ts
Scripting.FileManager.documentsDirectory: string
Scripting.FileManager.iCloudDocumentsDirectory: string | null
Scripting.FileManager.appGroupDocumentsDirectory: string | null
Scripting.FileManager.safariBrowserDirectory: string
Scripting.FileManager.safariBrowserStorageDirectory: string
Scripting.FileManager.safariBrowserDownloadsDirectory: string
Scripting.FileManager.safariBrowserUserscriptsDirectory: string
Scripting.FileManager.isiCloudEnabled: boolean
```

In regular Scripting app scripts, the same Safari data directories are available as `FileManager.safariBrowserDirectory`, `FileManager.safariBrowserStorageDirectory`, `FileManager.safariBrowserDownloadsDirectory`, and `FileManager.safariBrowserUserscriptsDirectory`.

### Methods

```ts
await Scripting.FileManager.readAsString(path)
await Scripting.FileManager.writeAsString(path, contents)
await Scripting.FileManager.createDirectory(path, true)
await Scripting.FileManager.readDirectory(path)
await Scripting.FileManager.exists(path)
await Scripting.FileManager.remove(path)
```

All file operations are limited to directories exposed by `Scripting.FileManager`.

***

## Installed Scripts

Safari's extension popup can install userscripts from the current page or from a URL. Installed scripts can be enabled, disabled, updated, or deleted in the popup and in Tools > Development > Safari Browser Scripts.

Use the Tools page to inspect:

- Installed userscripts.
- GM storage JSON files.
- Downloads created by `GM.download`.

***

## Example

```ts
// ==UserScript==
// @name Save Page URL
// @match https://github.com/*
// @grant GM.log
// @grant Scripting.FileManager
// ==/UserScript==

const fm = Scripting.FileManager
const dir = `${fm.appGroupDocumentsDirectory ?? fm.documentsDirectory}/Safari Notes`
const file = `${dir}/last-url.txt`

await fm.createDirectory(dir)
await fm.writeAsString(file, location.href)

GM.log(await fm.readAsString(file))
```



---
url: /guide/Changelog/3.1.0/Script (Python).md
---

# Script (Python)

The `scripting` Python package provides a `Script` namespace that mirrors the JS-side `Script` global, so a Python `index.py` can read its runtime context and hand a result back to the JS caller of `await Script.run({name})`.

The package is bundled with the runtime — `from scripting import Script` works out of the box in any Python index script.

***

## Properties

### `Script.name: str`

Name of the currently running script. Empty string if the host did not inject the name (e.g. ad-hoc `Python.run` snippets).

```python
import scripting; Script = scripting.Script
print(Script.name)  # "MyAwesomeScript"
```

### `Script.queryParameters: dict`

Parameters the caller passed via `Script.run({queryParameters})`, the `scripting-ts run ... --queryparameters '<json>'` command, or the `scripting://run/<name>?a=1&b=2` URL scheme. JSON value types are preserved (`bool` / `int` / `float` / `None` / `list` / `dict`); values from a URL scheme are always strings, because URL query strings cannot carry typed values. Returns an empty dict if no parameters were provided.

```python
import scripting; Script = scripting.Script
foo = Script.queryParameters.get("foo", "default")
```

### `Script.metadata: dict`

Display metadata declared in the script's `metadata.json`. Mirrors the JS-side `Script.metadata` object. Common keys:

| Key                   | Type   | Description                                              |
| --------------------- | ------ | -------------------------------------------------------- |
| name                  | string | Script name.                                             |
| icon                  | string | SFSymbol name.                                           |
| iconImage             | string | Optional path to a custom icon image.                    |
| color                 | string | Hex color string (`#FF0000`) or CSS color name.          |
| version               | string | Script version.                                          |
| description           | string | English description.                                     |
| localizedName         | string | Resolved localized name for the current system language. |
| localizedDescription  | string | Resolved localized description.                          |
| localizedNames        | dict   | Localized names by language code.                        |
| localizedDescriptions | dict   | Localized descriptions by language code.                 |
| author                | dict   | `{ name, email?, homepage? }`.                           |
| contributors          | list   | List of objects with the same shape as `author`.         |

Returns an empty dict for ad-hoc `Python.run` calls that aren't tied to an index script.

### `Script.directory: str`

Filesystem path to the current script's source directory (typically `<documents>/scripts/<name>/`). Mirrors the JS-side `Script.directory`. Use this to reference files bundled with the script (assets, sub-modules, etc.). Empty string for ad-hoc `Python.run` snippets that aren't tied to an index script.

```python
import os
import scripting; Script = scripting.Script
asset = os.path.join(Script.directory, "assets", "icon.png")
```

***

## Methods

### `Script.run(name, queryParameters=None, singleMode=False)`

Run another script and synchronously wait for it to exit. Mirrors `await Script.run({name, queryParameters, singleMode})` on the JS side.

```python
def run(name: str, queryParameters: dict | None = None, singleMode: bool = False) -> Any | None
```

| Param           | Type | Required | Description                                                                                        |
| --------------- | ---- | -------- | -------------------------------------------------------------------------------------------------- |
| name            | str  | Yes      | Name of the script to launch.                                                                      |
| queryParameters | dict | No       | Passed to the called script as `Script.queryParameters`; JSON value types are preserved.           |
| singleMode      | bool | No       | When `True`, exits any currently-running instance of `name` before launching. Defaults to `False`. |

Returns whatever the called script delivered through `Script.exit(value)`, or `None` if the script didn't call `Script.exit` with a value.

Raises `RuntimeError` if the host fails to launch the script (script not found, runtime not available, etc.) or if the RPC bridge is missing. Raises `ValueError` for an empty `name`.

```python
import scripting; Script = scripting.Script

result = Script.run("DataFetcher", queryParameters={"url": "https://example.com"})
print("got:", result)
```

### `Script.runTS(path, queryParameters=None, scriptName=None)`

Run a `.ts` / `.tsx` file by absolute filesystem path and synchronously wait for it to exit. Useful when you have a TypeScript helper sitting next to your Python `index.py` (or anywhere on disk) and want to call it directly without registering it as a separate index script.

```python
def runTS(path: str, queryParameters: dict | None = None, scriptName: str | None = None) -> Any | None
```

The host transpiles the source on the fly and runs it as an entry-style JS script — `Script.queryParameters`, `Script.exit(value)`, and the rest of the JS-side `Script` API all work inside the file.

`scriptName` controls the script-namespace the called file runs under — that is the key under which Storage / Keychain etc. are isolated. By default it falls back to the current Python script's `Script.name`, so a Python `index.py` and the `.tsx` helpers it invokes **share the same Storage / Keychain scope**. Pass an explicit string to override; pass an empty string to fall back to the file's basename (independent scope).

`Script.directory` inside the called file is the parent directory of `path`.

Returns whatever the file delivers through `Script.exit(value)`, or `None` if the file completed without calling `Script.exit` with a value. Raises `RuntimeError` if the path doesn't exist, can't be read, fails to transpile, or the JS code throws during evaluation.

```python
import os
import scripting; Script = scripting.Script

helper_path = os.path.join(Script.directory, "helper.tsx")
result = Script.runTS(helper_path, queryParameters={"limit": "10"})
print(result)
```

```typescript
// helper.tsx
const limit = Number(Script.queryParameters.limit ?? "5")
const items = await fetchTopItems(limit)
Script.exit(items)
```

### `Script.exit(value=None)`

Exit the current script. If `value` is provided, it is JSON-serialized and delivered back to the JS caller of `await Script.run({name})` as the resolution value. Without `value`, the JS caller receives `None`.

```python
def exit(value: Any | None = None) -> NoReturn
```

`value` must be JSON-serializable (`dict`, `list`, `str`, `int`, `float`, `bool`, `None`, and combinations). If serialization fails, the JS caller receives `None` (no exception is raised — the call still terminates the script).

```python
import scripting; Script = scripting.Script

result = compute_something()
Script.exit({"ok": True, "result": result})
# Script.exit returns NoReturn — code after this line never runs.
```

***

## Examples

### Receiving parameters and returning a value

```python
# index.py
import scripting; Script = scripting.Script

params = Script.queryParameters
name = params.get("name", "world")
greeting = f"Hello, {name}!"

Script.exit({"greeting": greeting, "length": len(greeting)})
```

```ts
// caller (JS / TS)
const r = await Script.run({
  name: "Greeter",
  queryParameters: { name: "Alice" },
})
console.log(r.greeting)  // "Hello, Alice!"
console.log(r.length)    // 13
```

### Chaining Python scripts

```python
# orchestrator.py
import scripting; Script = scripting.Script

raw = Script.run("Fetcher", queryParameters={"id": "42"})
processed = Script.run("Processor", queryParameters={"data": raw["body"]})
Script.exit(processed)
```

### Reading metadata and resolving asset paths

```python
import os, json
import scripting; Script = scripting.Script

print(f"Running {Script.name} v{Script.metadata.get('version', '?')}")

# Read a file shipped with the script.
config_path = os.path.join(Script.directory, "config.json")
with open(config_path) as f:
    config = json.load(f)
```



---
url: /guide/Changelog/3.1.0/ScrollView: scroll position & visibility tracking/index.md
---

# 

***

title: ScrollView: scroll position & visibility tracking
description: scrollPosition(id:anchor:) two-way binds the leading visible item's id to JS state on plain ScrollView (no ScrollViewReader needed). onScrollTargetVisibilityChange (iOS 18+) reports the full visible-id set as you scroll. Children mark themselves with key=\{...} (mapped to SwiftUI .id()) and the layout container needs scrollTargetLayout.

***

The `ScrollView` component displays its content within a scrollable region. As the user performs scroll gestures, the visible portion of the content is updated accordingly. You can scroll vertically, horizontally, or in both directions using the `axes` prop.

## Type

```ts
type ScrollViewProps = {
  axes?: AxisSet
  children?: VirtualNode | VirtualNode[] | (VirtualNode | undefined | null)[]
}
```

## Overview

- Scroll direction is controlled by the `axes` property.
- Contents are placed inside children, typically using layouts like `<VStack>` or `<HStack>`.
- Zooming is not supported.

## Default Behavior

- The default scroll axis is **vertical**.
- Scroll indicators are shown based on platform conventions unless configured via modifiers.

## Example

```tsx
<ScrollView>
  <VStack>
    {new Array(100).fill('').map((_, index) => (
      <Text>Row {index}</Text>
    ))}
  </VStack>
</ScrollView>
```

***

## ScrollView Modifiers

You can apply the following view modifiers to configure scroll-related behavior.

***

## `scrollIndicator`

Controls the visibility of scroll indicators.

### Type

```ts
scrollIndicator?: ScrollScrollIndicatorVisibility | {
  visibility: ScrollScrollIndicatorVisibility
  axes: AxisSet
}
```

### `ScrollScrollIndicatorVisibility` options:

- `"automatic"`: Follows platform default behavior.
- `"visible"`: Indicators appear but may auto-hide based on OS behavior.
- `"hidden"`: Hidden unless overridden by system behavior.
- `"never"`: Never show indicators.

### Example

```tsx
<ScrollView scrollIndicator="never">
  <VStack>{/* content */}</VStack>
</ScrollView>
```

With axis-specific visibility:

```tsx
<ScrollView
  scrollIndicator={{
    visibility: "hidden",
    axes: "vertical"
  }}
>
  <VStack>{/* content */}</VStack>
</ScrollView>
```

***

## `scrollDisabled`

Enables or disables scrolling behavior entirely.

### Type

```ts
scrollDisabled?: boolean
```

### Example

```tsx
<ScrollView scrollDisabled>
  <Text>This scroll view is locked.</Text>
</ScrollView>
```

***

## `scrollClipDisabled`

Controls whether the scroll view clips content that extends beyond its bounds.

### Type

```ts
scrollClipDisabled?: boolean
```

### Example

```tsx
<ScrollView scrollClipDisabled>
  {/* Content may overflow scroll bounds visually */}
</ScrollView>
```

***

## `scrollDismissesKeyboard`

Determines how the scroll interaction affects the software keyboard.

### Type

```ts
scrollDismissesKeyboard?: ScrollDismissesKeyboardMode
```

### Options

- `"automatic"`: Default behavior based on context.
- `"immediately"`: Dismiss keyboard as soon as scrolling starts.
- `"interactively"`: Allow user to drag to dismiss keyboard.
- `"never"`: Scrolling will not dismiss the keyboard.

### Example

```tsx
<ScrollView scrollDismissesKeyboard="interactively">
  {/* Content with text input */}
</ScrollView>
```

***

## `defaultScrollAnchor`

Defines which point in the content should be visible initially or stay anchored when content size changes.

### Type

```ts
defaultScrollAnchor?: KeywordPoint | Point
```

### `KeywordPoint` values

- `"top"`, `"bottom"`, `"leading"`, `"trailing"`, `"center"`, `"topLeading"`, `"bottomTrailing"` etc.

### Example

```tsx
<ScrollView defaultScrollAnchor="bottom">
  <VStack>
    {/* New content will appear anchored to the bottom */}
  </VStack>
</ScrollView>
```

***

## `AxisSet`

Defines the scrollable directions for a scroll view.

### Type

```ts
type AxisSet = 'vertical' | 'horizontal' | 'all'
```

### Usage

```tsx
<ScrollView axes="horizontal">
  <HStack>{/* horizontally scrollable content */}</HStack>
</ScrollView>
```

***

## `scrollTargetLayout`

Applies this modifier to layout containers such as LazyHStack, LazyVStack, HStack, or VStack that represent the main repeating content inside a ScrollView.

### Type

```ts
scrollTargetLayout?: boolean
```

### Usage

When set to `true`, this modifier designates the associated layout container as a scroll target region within the `ScrollView`. It allows the scroll behavior system to determine how scrolling should align to elements within the container.

```tsx
<ScrollView axes="horizontal">
  <LazyHStack scrollTargetLayout>
    {items.map(item => <Text>{item.title}</Text>)}
  </LazyHStack>
</ScrollView>
```

***

## `scrollTargetBehavior`

Defines how scrollable views behave when aligning content to scroll targets.

### Type

```ts
scrollTargetBehavior?: ScrollTargetBehavior
```

```ts
type ScrollTargetBehavior =
  | "paging"
  | "viewAligned"
  | "viewAlignedLimitAutomatic"
  | "viewAlignedLimitAlways"
  | "viewAlignedLimitNever"
  | "viewAlignedLimitAlwaysByFew"
  | "viewAlignedLimitAlwaysByOne"
```

#### Description of Variants

- **`"paging"`**: Scrolls one page at a time, aligned to the container’s dimensions.
- **`"viewAligned"`**: Scrolls to align views directly, based on view frames.
- **`"viewAlignedLimitAutomatic"`**: Limits scrolling in compact horizontal size classes, but allows full scrolling otherwise.
- **`"viewAlignedLimitAlways"`**: Always restricts scrolling to a limited number of items.
- **`"viewAlignedLimitNever"`**: Allows unrestricted scrolling without view-based limitations.
- **`"viewAlignedLimitAlwaysByFew"`** _(iOS 18.0+)_: Limits scrolling to a small number of views per gesture, automatically determined.
- **`"viewAlignedLimitAlwaysByOne"`** _(iOS 18.0+)_: Restricts each scroll gesture to advance exactly one view at a time.

### Description

This modifier configures the scroll behavior, such as paging and alignment strategy, for views within a scrollable container.

***

## `scrollPosition`

Two-way binds the **id of the leading visible item** in a `ScrollView` to JS state. Mirrors SwiftUI's `.scrollPosition(id:anchor:)` — no `ScrollViewReader` wrapper required.

### Type

```ts
scrollPosition?:
  | Observable<string>
  | Observable<number>
  | Observable<string | null>
  | Observable<number | null>
  | { value: Observable<string | number | null>; anchor?: KeywordPoint | Point }
  | {
      value: string | number | null
      onChanged: (newValue: string | number | null) => void
      anchor?: KeywordPoint | Point
    }
```

### Setup

1. The container directly under the `ScrollView` (typically `LazyVStack` / `LazyHStack` / `VStack`) needs `scrollTargetLayout`.
2. Each child you want to be a scroll target needs a `key="..."` prop — the bridge maps it to SwiftUI's `.id()`.
3. Bind `scrollPosition` to a state — `Observable` form or `{ value, onChanged }` form.

### Example

```tsx
const [visibleId, setVisibleId] = useState<string | null>(null)

<ScrollView
  scrollPosition={{ value: visibleId, onChanged: setVisibleId, anchor: "top" }}
>
  <LazyVStack scrollTargetLayout>
    {items.map(it => (
      <HStack key={it.id}>{/* row content */}</HStack>
    ))}
  </LazyVStack>
</ScrollView>
```

- `id` may be `string` or `number`. Pick the type when initialising the state and stick with it — the bridge dispatches on the runtime type.
- Setting the state to `null` lets SwiftUI manage the scroll position; setting it to a known id scrolls that item to the anchor.
- `anchor` is a `UnitPoint`: a string keyword (`"top"` / `"center"` / `"leading"` / ...) or `{ x, y }`.

### Pitfalls

- **Forgetting `scrollTargetLayout`.** Without it, SwiftUI doesn't know which subview is the "current" scroll target — the binding silently does nothing.
- **Mixing id types.** A `Observable<number>` won't bind against a child whose `key` was rendered as a string. Keep both sides consistent.
- **Type changes mid-flight.** Initialise the observable with a real value (e.g. `useState<string|null>("first")`) so the bridge can detect the type at modifier time. A purely-`null`-initial observable defaults to the string path.
- **ScrollViewReader vs scrollPosition.** Don't bind both to the same scroll view — the imperative `scrollTo(id:)` and declarative `scrollPosition` will fight each other. Pick one.

***

## `onScrollTargetVisibilityChange`

iOS 18+. Reports the **set of currently-visible scroll target ids** whenever it changes (filtered by `threshold`). Mirrors SwiftUI's `.onScrollTargetVisibilityChange(idType:threshold:_:)`.

### Type

```ts
onScrollTargetVisibilityChange?: {
  idType: "string" | "number"
  threshold?: number   // 0.0 - 1.0, default 0.5
  onChanged: (ids: string[] | number[]) => void
}
```

### Setup

Same as `scrollPosition`:

1. The layout container needs `scrollTargetLayout`.
2. Children must be marked with `key="..."` or `key={123}`.
3. **`idType` must match the runtime type of the keys.** The SwiftUI API is generic, and the bridge has to dispatch statically at modifier-creation time — there's no way to recover the ID type from `[AnyHashable]` at runtime. Use `"string"` for string keys, `"number"` for number keys.

### Example

```tsx
const [visibleIds, setVisibleIds] = useState<string[]>([])

<ScrollView
  onScrollTargetVisibilityChange={{
    idType: "string",
    threshold: 0.5,
    onChanged: (ids) => setVisibleIds(ids as string[]),
  }}
>
  <LazyVStack scrollTargetLayout>
    {items.map(it => <Row key={it.id} />)}
  </LazyVStack>
</ScrollView>
```

### Pitfalls

- **iOS 17 fallback.** On iOS 17 the bridge logs an `API deprecated` warning and skips the modifier — content passes through. Other modifiers are unaffected.
- **`threshold` semantics.** `0.5` = the view must be at least 50% within the viewport to count as visible. `0` = any pixel triggers; `1` = the entire view must be visible.
- **Callback frequency.** During scrolling the callback is invoked on the main thread inline (no throttling). A list with \~30 items where \~5 are visible is fine; for very dense lists with rapid scrolling, keep the callback body cheap.
- **Compatible with `scrollPosition`.** They serve different purposes — `scrollPosition` gives you the leading id, `onScrollTargetVisibilityChange` gives you the entire visible set. Using both on the same scroll view is safe.

***

## `scrollContentBackground`

Specifies the visibility of the background for scrollable views, such as `ScrollView`, within the current view context.

### Type

```ts
scrollContentBackground?: Visibility
```

### Description

This modifier controls whether the default background behind scrollable content (typically a system-provided background) is shown, hidden, or determined automatically based on system behavior.

It is commonly used when customizing the appearance of scrollable views or when layering custom backgrounds behind scroll content.

### Visibility Options

- **`'automatic'`**
  The system decides whether the background should be visible based on the current context and platform conventions.

- **`'hidden'`**
  Hides the scroll view’s default background, allowing custom background layers or transparent effects.

- **`'visible'`**
  Forces the default scroll content background to be shown, even if a custom background is present.

### Example: Hiding Scroll Background

```tsx
<List scrollContentBackground="hidden">
  <Text>No background here</Text>
</List>
```

This example removes the default background from the scroll view, making it fully transparent or allowing underlying views to show through.

***

## Summary

| Modifier / Prop                  | Description                                                              |
| -------------------------------- | ------------------------------------------------------------------------ |
| `axes`                           | Defines scroll direction (`vertical`, `horizontal`, or `all`)            |
| `scrollIndicator`                | Controls scroll indicator visibility and supports axis-specific config   |
| `scrollDisabled`                 | Disables scrolling entirely when set to `true`                           |
| `scrollClipDisabled`             | Prevents clipping of content that overflows the scroll bounds            |
| `scrollDismissesKeyboard`        | Configures how scrolling interacts with the software keyboard            |
| `defaultScrollAnchor`            | Sets the initial or persistent scroll anchor point in the content        |
| `scrollTargetLayout`             | Marks a container (like `LazyHStack`) as the scroll target for alignment |
| `scrollTargetBehavior`           | Determines how content aligns and scrolls within the scroll view         |
| `scrollPosition`                 | Two-way binds the leading visible item's id to JS state                  |
| `onScrollTargetVisibilityChange` | iOS 18+, subscribes to the visible id set                                |
| `scrollContentBackground`        | Sets the visibility of the scroll view’s default background              |



---
url: /guide/Changelog/3.1.0/ScrollView: scroll position & visibility tracking/index_example.md
---

# Example

```tsx
import { Button, Color, ForEach, HStack, KeywordPoint, LazyVStack, Navigation, NavigationStack, Picker, RoundedRectangle, Script, ScrollView, Text, useState, VStack } from "scripting"

function Example() {
  const colors: Color[] = [
    "systemRed",
    "systemOrange",
    "systemYellow",
    "systemGreen",
    "systemBlue",
    "systemPurple",
    "systemIndigo",
    "systemPink",
  ]
  const [scrollAnchor, setScrollAnchor] = useState<KeywordPoint>("bottom")

  // scrollPosition demo —— 把 leading 可见 item id 双向绑到 state；
  // 子节点用 `key=...`，bridge 会映射到 SwiftUI `.id()`。
  const positionItems = Array.from({ length: 50 }, (_, i) => ({
    id: `pos-${i}`,
    title: `Row ${i + 1}`,
    color: colors[i % colors.length],
  }))
  const [visibleId, setVisibleId] = useState<string | null>(null)

  // onScrollTargetVisibilityChange demo —— iOS 18+，跟踪当前可见 id 集合（threshold ≥ 0.5）。
  const visItems = Array.from({ length: 30 }, (_, i) => ({
    id: `vis-${i}`,
    title: `Item ${i + 1}`,
    color: colors[i % colors.length],
  }))
  const [visibleIds, setVisibleIds] = useState<string[]>([])

  return <NavigationStack>
    <ScrollView
      navigationTitle={"ScrollView"}
      defaultScrollAnchor={scrollAnchor}
      navigationBarTitleDisplayMode={"inline"}
      key={scrollAnchor}
    >
      <VStack
        spacing={16}
        padding
      >
        <Picker
          title={"Default Scroll Anchor"}
          value={scrollAnchor}
          onChanged={setScrollAnchor as any}
          pickerStyle={"menu"}
        >
          <Text tag={"top"}>Top</Text>
          <Text tag={"center"}>Center</Text>
          <Text tag={"bottom"}>Bottom</Text>
        </Picker>

        <ScrollView
          axes={"horizontal"}
          frame={{
            height: 64
          }}
        >
          <HStack spacing={8}>
            <ForEach
              count={15}
              itemBuilder={index =>
                <RoundedRectangle
                  key={index.toString()}
                  fill={"systemIndigo"}
                  cornerRadius={6}
                  frame={{
                    width: 64,
                    height: 64,
                  }}
                  overlay={
                    <Text>{index}</Text>
                  }
                />
              }
            />
          </HStack>
        </ScrollView>

        <ForEach
          count={colors.length}
          itemBuilder={index => {
            const color = colors[index]
            return <RoundedRectangle
              key={color}
              fill={color}
              cornerRadius={16}
              frame={{
                height: 100
              }}
            />
          }}
        />

        {/* scrollPosition section —— 把 leading 可见 item id 同步给 JS，并支持 jump-to-id */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>scrollPosition(id:anchor:)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Two-way binds the leading visible item's id. Tap a Jump button to scroll to a row.
          </Text>
          <HStack spacing={6}>
            <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>Visible:</Text>
            <Text font={"caption"} monospaced>{visibleId ?? "—"}</Text>
          </HStack>
          <HStack spacing={8}>
            <Button title={"Jump to first"} action={() => setVisibleId("pos-0")} buttonStyle={"borderedProminent"} controlSize={"small"} />
            <Button title={"Jump to 25"} action={() => setVisibleId("pos-24")} buttonStyle={"borderedProminent"} controlSize={"small"} />
            <Button title={"Jump to last"} action={() => setVisibleId("pos-49")} buttonStyle={"borderedProminent"} controlSize={"small"} />
          </HStack>
          <ScrollView
            frame={{ height: 280 }}
            background={
              <RoundedRectangle cornerRadius={12} fill={"secondarySystemBackground"} />
            }
            scrollPosition={{
              value: visibleId,
              onChanged: (id) => setVisibleId(id as string | null),
              anchor: "top",
            }}
          >
            <LazyVStack scrollTargetLayout spacing={8} padding={8}>
              {positionItems.map(it => (
                <HStack
                  key={it.id}
                  spacing={12}
                  padding={10}
                  background={
                    <RoundedRectangle cornerRadius={10} fill={{ color: it.color, opacity: 0.18 }} />
                  }
                >
                  <RoundedRectangle cornerRadius={6} frame={{ width: 24, height: 24 }} fill={it.color} />
                  <Text font={"body"}>{it.title}</Text>
                  <Text font={"caption"} foregroundStyle={"secondaryLabel"}>{it.id}</Text>
                </HStack>
              ))}
            </LazyVStack>
          </ScrollView>
        </VStack>

        {/* onScrollTargetVisibilityChange section —— iOS 18+，整组可见 id 跟踪 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>onScrollTargetVisibilityChange</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            iOS 18+. Reports the array of currently-visible scroll-target ids (≥ 50% visible).
          </Text>
          <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>
            visible ({visibleIds.length}):
          </Text>
          <Text font={"caption"} monospaced>
            {visibleIds.length > 0 ? visibleIds.join(", ") : "—"}
          </Text>
          <ScrollView
            frame={{ height: 220 }}
            background={
              <RoundedRectangle cornerRadius={12} fill={"secondarySystemBackground"} />
            }
            onScrollTargetVisibilityChange={{
              idType: "string",
              threshold: 0.5,
              onChanged: (ids) => setVisibleIds(ids as string[]),
            }}
          >
            <LazyVStack scrollTargetLayout spacing={8} padding={8}>
              {visItems.map(it => (
                <HStack
                  key={it.id}
                  spacing={12}
                  padding={10}
                  background={
                    <RoundedRectangle cornerRadius={10} fill={{ color: it.color, opacity: 0.18 }} />
                  }
                >
                  <RoundedRectangle cornerRadius={6} frame={{ width: 24, height: 24 }} fill={it.color} />
                  <Text font={"body"}>{it.title}</Text>
                  <Text font={"caption"} foregroundStyle={"secondaryLabel"}>{it.id}</Text>
                </HStack>
              ))}
            </LazyVStack>
          </ScrollView>
        </VStack>
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()


```



---
url: /guide/Changelog/3.1.0/Search Shortcuts.md
---

# Search Shortcuts

Search Shortcuts let you type a trigger word followed by a query in Safari's address bar and jump straight to a site's search results — for example, typing `gh hello world` can take you to GitHub's search for "hello world".

This feature requires Scripting PRO.

***

## How It Works

When you search from Safari's address bar, Scripting looks at the first word of your query. If it matches a shortcut's trigger, the rest of the query is sent to that shortcut's search URL instead of your default search engine.

- The **first word** is the trigger. A shortcut can have several triggers, and any of them activates it.
- **Everything after it** becomes the search query.
- The query is URL-encoded and substituted into the shortcut's URL where you put `%s`.

It works with Safari's address-bar search on common search engines (Google, Bing, DuckDuckGo, Yahoo, Baidu, Ecosia, Startpage). Make sure your query starts with the trigger word.

***

## Add a Shortcut

In the Safari Browser Scripts settings, open **Search Shortcuts** and tap **Add**:

- **Triggers** — one or more words with no spaces, e.g. `gh`. Add several (such as `gh` and `git`) and any of them activates the shortcut. Use **Add trigger** to add more, and the minus button to remove one.
- **Name** — an optional label for the list.
- **Search URL** — the destination, with `%s` where the query should go.

Each shortcut has an **Enabled** switch. Tap a row to edit it, or swipe to delete.

### Different URLs for iPhone/iPad and Mac

By default one search URL is used on every device. If you want a mobile-optimized site on iPhone/iPad and the full site on Mac, turn on **Use different URLs for iPhone/iPad and Mac**. Both fields are pre-filled with your current URL, so you only change the side you need — for example an `m.` mobile host for iPhone/iPad and the desktop host for Mac. The extension picks the URL that matches the device you are searching on.

***

## Examples

| Triggers    | Search URL                                        |
| ----------- | ------------------------------------------------- |
| `gh`, `git` | `https://github.com/search?q=%s`                  |
| `yt`        | `https://www.youtube.com/results?search_query=%s` |
| `npm`       | `https://www.npmjs.com/search?q=%s`               |
| `w`         | `https://en.wikipedia.org/w/index.php?search=%s`  |

With the `gh` shortcut above, searching `gh swiftui` — or `git swiftui` — opens `https://github.com/search?q=swiftui`.

The destination does not have to be a web search. A custom app URL scheme or a Universal Link also works, so a shortcut can open another app's search directly.

***

## Notes

- Shortcuts are matched only when the first word equals one of the triggers. A normal query that does not start with a trigger passes through to your default search engine unchanged.
- Triggers are matched case-insensitively.
- Changes you make in the settings take effect on your next search.



---
url: /guide/Changelog/3.1.0/SharedAudioSession.md
---

# 

***

title: SharedAudioSession
description: New audio routing APIs: list available inputs, set the preferred input (e.g. force builtInMic), override the output port, observe route changes, plus an in-process "prefer built-in mic" switch for clean input/output separation when wireless headphones are connected.

***

The `SharedAudioSession` interface provides a convenient way to manage and interact with the shared audio session in your script. The audio session acts as an intermediary between your script, the Scripting app, the operating system, and the underlying audio hardware, enabling you to configure and control audio behavior effectively.

## Features

- Retrieve and set audio session categories, modes, and options.
- Configure the preferred sample rate for audio input and output.
- Handle audio interruptions.
- Query device capabilities for supported categories and modes.
- Tailor audio behaviors for specific app use cases, such as video recording, voice chat, or background playback.

***

## Methods and Properties

### 1. **Session Category and Options**

#### `category`

Get the current audio session category.

```typescript
const category = await SharedAudioSession.category
console.log(category) // Example: 'playback'
```

#### `categoryOptions`

Retrieve the current audio session category options.

```typescript
const options = await SharedAudioSession.categoryOptions
console.log(options) // Example: ['mixWithOthers', 'allowAirPlay']
```

#### `setCategory(category: AudioSessionCategory, options: AudioSessionCategoryOptions[])`

Set the audio session category with specific options.

```typescript
await SharedAudioSession.setCategory('playback', ['mixWithOthers'])
```

***

### 2. **Session Mode**

#### `mode`

Retrieve the current audio session mode.

```typescript
const mode = await SharedAudioSession.mode
console.log(mode) // Example: 'videoChat'
```

#### `setMode(mode: AudioSessionMode)`

Set the audio session mode.

```typescript
await SharedAudioSession.setMode('voiceChat')
```

***

### 3. **Sample Rate**

#### `preferredSampleRate`

Retrieve the preferred sample rate in hertz.

```typescript
const sampleRate = await SharedAudioSession.preferredSampleRate
console.log(sampleRate) // Example: 44100
```

#### `setPreferredSampleRate(sampleRate: number)`

Set the preferred sample rate for audio input and output.

```typescript
await SharedAudioSession.setPreferredSampleRate(48000)
```

***

### 4. **Interruption Handling**

#### `addInterruptionListener(listener: AudioSessionInterruptionListener)`

Listen for audio interruptions.

```typescript
SharedAudioSession.addInterruptionListener((type) => {
  if (type === 'began') {
    console.log('Audio interruption began')
  } else if (type === 'ended') {
    console.log('Audio interruption ended')
  }
})
```

#### `removeInterruptionListener(listener: AudioSessionInterruptionListener)`

Remove an interruption listener.

```typescript
SharedAudioSession.removeInterruptionListener(myListener)
```

***

### 5. **Device Capabilities**

#### `availableCategories`

Get the list of audio session categories available on the device.

```typescript
const categories = await SharedAudioSession.availableCategories
console.log(categories) // Example: ['playback', 'record', 'soloAmbient']
```

#### `availableModes`

Get the list of audio session modes available on the device.

```typescript
const modes = await SharedAudioSession.availableModes
console.log(modes) // Example: ['default', 'videoChat', 'voiceChat']
```

***

### 6. **Additional Properties**

#### `isOtherAudioPlaying`

Check if other audio is currently playing on the device.

```typescript
const isPlaying = await SharedAudioSession.isOtherAudioPlaying
console.log(isPlaying) // Example: true
```

#### `secondaryAudioShouldBeSilencedHint`

Check if secondary audio should be silenced.

```typescript
const shouldSilence = await SharedAudioSession.secondaryAudioShouldBeSilencedHint
console.log(shouldSilence) // Example: false
```

#### `allowHapticsAndSystemSoundsDuringRecording`

Check if haptics and system sounds are allowed during recording.

```typescript
const allowHaptics = await SharedAudioSession.allowHapticsAndSystemSoundsDuringRecording
console.log(allowHaptics) // Example: true
```

#### `prefersNoInterruptionsFromSystemAlerts`

Check if the session prefers no interruptions from system alerts.

```typescript
const prefersNoInterruptions = await SharedAudioSession.prefersNoInterruptionsFromSystemAlerts
console.log(prefersNoInterruptions) // Example: false
```

***

### 7. **Session Activation**

#### `setActive(active: boolean, options?: AudioSessionSetActiveOptions[])`

Activate or deactivate the shared audio session with optional options.

- `active`: Set to `true` to activate the session, `false` to deactivate it.
- `options`: An array of optional activation options, such as 'interruptSpokenAudioAndMixWithOthers'.

```typescript
await SharedAudioSession.setActive(
  true,
  ['notifyOthersOnDeactivation']
)
```

***

### 8. **System Settings**

#### `setAllowHapticsAndSystemSoundsDuringRecording(value: boolean)`

Enable or disable haptics and system sounds during recording.

```typescript
await SharedAudioSession.setAllowHapticsAndSystemSoundsDuringRecording(true)
```

#### `setPrefersNoInterruptionsFromSystemAlerts(value: boolean)`

Set the preference for no interruptions from system alerts.

```typescript
await SharedAudioSession.setPrefersNoInterruptionsFromSystemAlerts(true)
```

***

### 9. **Audio Routing**

iOS chooses input and output audio routes independently. The APIs below let you list available
input ports, force the recording input to a specific port (typically `builtInMic`), and override
the output to the device speaker — useful when you want to record from the phone microphone while
keeping a Bluetooth headset for playback (avoiding the lower-quality bidirectional Bluetooth HFP
link).

> `setPreferredInput` and `overrideOutputAudioPort` only work after the session is active. Always
> call `setActive(true)` first.

#### `availableInputs`

The list of input ports the system currently exposes for this session. Bluetooth, USB, and headset
microphones only appear when the active category options allow them (e.g. `allowBluetoothHFP`).

```typescript
const inputs = await SharedAudioSession.availableInputs
for (const port of inputs) {
  console.log(port.portType, port.portName, port.uid)
}
```

#### `currentRoute`

The currently selected input and output ports.

```typescript
const route = await SharedAudioSession.currentRoute
console.log('input:', route.inputs[0]?.portType)
console.log('output:', route.outputs[0]?.portType)
```

#### `setPreferredInput(input: AudioSessionPort | null)`

Pick a specific input port. Pass `null` to clear the preference. The argument is matched against
`availableInputs` first by `uid`, then by `portType`. Rejects with `Cannot setPreferredInput before
setActive(true).` if the session is not active.

```typescript
await SharedAudioSession.setActive(true)
const inputs = await SharedAudioSession.availableInputs
const builtIn = inputs.find(p => p.portType === 'builtInMic')
if (builtIn) {
  await SharedAudioSession.setPreferredInput(builtIn)
}
```

#### `overrideOutputAudioPort(port: 'speaker' | 'none')`

Force the output to the device speaker, or remove the override. Independent from input selection.

```typescript
await SharedAudioSession.overrideOutputAudioPort('speaker')
// later
await SharedAudioSession.overrideOutputAudioPort('none')
```

#### `setPrefersBuiltInMicWhenAvailable(enabled: boolean)`

Enable an in-process switch that automatically steers the input back to `builtInMic` whenever it
becomes available, even after a Bluetooth headset, USB mic, or wired headset is plugged in. The
output route is left untouched, which is what enables clean I/O separation: built-in mic for input,
wireless headphones (A2DP) for playback.

The switch is **not persisted** across launches, but it does affect every script running inside the
host app while the host process is alive. Manual `setPreferredInput` calls (route change reason
`override`) are not overwritten by the switch.

Enabling the switch immediately attempts to apply the preference once.

```typescript
await SharedAudioSession.setActive(true)
await SharedAudioSession.setPrefersBuiltInMicWhenAvailable(true)

// Later, query state:
const enabled = await SharedAudioSession.prefersBuiltInMicWhenAvailable
```

#### Route change events

```typescript
SharedAudioSession.addRouteChangeListener((reason, current) => {
  console.log('route changed:', reason)
  console.log('inputs now:', current.inputs.map(p => p.portType))
})
```

`reason` is one of `'newDeviceAvailable' | 'oldDeviceUnavailable' | 'categoryChange' | 'override' | 'wakeFromSleep' | 'noSuitableRouteForCategory' | 'routeConfigurationChange' | 'unknown'`.

***

### 10. **Systemwide Output Volume**

#### `outputVolume: number`

The systemwide output volume. This property is a number between 0 and 1, representing the volume level as a percentage.

#### outputVolume EventListener

Type Definition:

```ts
type AudioSessionOutputVolumeListener = (newValue: number, oldValue: number) => void
```

##### `addOutputVolumeListener(listener: AudioSessionOutputVolumeListener)`

Add an event listener for changes in the systemwide output volume.

```typescript
SharedAudioSession.addOutputVolumeListener((newValue, oldValue) => {
  console.log(`Output volume changed from ${oldValue} to ${newValue}`)
})
```

##### `removeOutputVolumeListener(listener: AudioSessionOutputVolumeListener)`

Remove an event listener for changes in the systemwide output volume.

***

## Enumerations

### **AudioSessionSetActiveOptions**

Optional activation options:

- `'notifyOthersOnDeactivation'`: Notify other audio sessions when deactivating the shared audio session.

### **AudioSessionCategory**

Defines the session's audio category:

- `'ambient'`: Ambient audio, such as background music or ambient sounds.
- `'multiRoute'`: Multi-route audio, such as routing distinct streams of audio data to different output devices at the same time.
- `'playAndRecord'`: Play and record audio, such as voice chat or video conferencing.
- `'playback'`: Playback audio, such as music or sound effects.
- `'record'`: Recording audio, such as voice chat or video conferencing.
- `'soloAmbient'`: Solo ambient audio, such as background music or ambient sounds.

### **AudioSessionCategoryOptions**

Optional behaviors for audio categories:

- `'mixWithOthers'`: Mix with other audio sessions.
- `'duckOthers'`: Duck other audio sessions.
- `'interruptSpokenAudioAndMixWithOthers'`: Interrupt spoken audio and mix with others.
- `'allowBluetooth'`: Allow Bluetooth audio.
- `'allowBluetoothA2DP'`: Allow Bluetooth A2DP audio.
- `'allowAirPlay'`: Allow AirPlay audio.
- `'defaultToSpeaker'`: Default to speaker, even if headphones are connected.
- `'overrideMutedMicrophoneInterruption'`: Override muted microphone interruption.

### **AudioSessionMode**

Specifies the session's mode:

- `'default'`: Default mode.
- `'gameChat'`: Game chat mode.
- `'measurement'`: Measurement mode, such as audio input or output.
- `'moviePlayback'`: Movie playback mode, such as movie content.
- `'spokenAudio'`: Spoken audio mode, such as voice chat.
- `'videoChat'`: Video chat mode, such as video conferencing.
- `'videoRecording'`: Video recording mode, such as video conferencing.
- `'voicePrompt'`: Voice prompt mode, such as text-to-speech.

### **AudioSessionInterruptionType**

Specifies the type of interruption:

- `'began'`
- `'ended'`
- `'unknown'`

***

This interface offers extensive control over audio session management in Scripting, making it suitable for building audio-heavy script like music players and video conferencing tools.



---
url: /guide/Changelog/3.1.0/Shell.md
---

# Shell

The `Shell` global runs shell commands inside the Scripting app via the embedded `ios_system` runtime. Useful for ad-hoc tooling — listing and editing files, processing text streams, fetching URLs with `curl`, archiving with `tar`, running `python`, etc.

> **Available commands are limited to what `ios_system` ships.** This is _not_ a full POSIX shell. Only commands provided by the bundled `ios_system` modules work: roughly the basic file / text / network utilities (`ls`, `cp`, `mv`, `rm`, `cat`, `echo`, `grep`, `sed`, `awk`, `cut`, `sort`, `uniq`, `head`, `tail`, `wc`, `find`, `xargs`, `tar`, `gzip`, `curl`, `scp`, `sftp`, `ssh`, `python`, ...) plus shell builtins (`cd`, `pwd`, `env`, `export`, pipes, redirects). External tools that are **not** bundled — `git`, `make`, `node`, `npm`, `brew`, `gcc`, etc. — are unavailable, and you cannot execute arbitrary binaries shipped with a script (iOS sandbox restriction).

`Shell.run` and `Python.run` share a single serial queue: while one is running, others wait. This is intentional — `ios_system` and the embedded Python interpreter share global state (env vars, `sys.modules`, current working directory) and cannot run concurrently.

***

## Methods

### `Shell.run(command, options?): Promise<ShellExecutionResult>`

Execute a shell command. Returns when the command exits or the timeout is reached. Non-zero exit codes resolve normally; only argument validation errors reject the promise.

```ts
function run(command: string, options?: ShellRunOptions): Promise<ShellExecutionResult>
```

#### `ShellRunOptions`

| Name            | Type                    | Required | Description                                                                                                                                                                              |
| --------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cwd             | string                  | No       | Working directory for the command. Relative paths are resolved against the documents directory; `~/` is expanded to the documents directory.                                             |
| timeout         | number                  | No       | Maximum execution time in seconds. Defaults to `120`. When exceeded, the command is killed and the promise resolves with `timedOut: true`.                                               |
| env             | Record\<string, string> | No       | Extra environment variables injected for this invocation only. Restored to their previous values after the command finishes.                                                             |
| queryParameters | Record\<string, string> | No       | String key/value pairs serialized as JSON and exposed to the subprocess via the `SCRIPTING_QUERY_PARAMETERS` environment variable. Mirrors `Script.queryParameters` for ad-hoc commands. |

#### `ShellExecutionResult`

| Name      | Type    | Description                                                                                                                                                                                |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| output    | string  | Combined stdout + stderr produced by the command. The underlying `ios_system` pipes both into a single stream, so they cannot be separated.                                                |
| exitCode  | number  | Process exit code. `0` means success. Non-zero values are surfaced as resolved promises (no rejection), so the caller can handle expected non-zero exits (e.g. `grep` finding no matches). |
| timedOut  | boolean | `true` when the command was killed because it exceeded `options.timeout`.                                                                                                                  |
| cancelled | boolean | `true` when the command was cancelled by the host.                                                                                                                                         |

***

## Examples

### Basic command

```ts
const r = await Shell.run("echo hi && pwd", { cwd: "/tmp" })
console.log(r.output)   // "hi\n/tmp\n"
console.log(r.exitCode) // 0
```

### Handling non-zero exits

```ts
const r = await Shell.run("grep -q needle haystack.txt")
if (r.exitCode === 0) {
  console.log("found")
} else if (r.exitCode === 1) {
  console.log("not found")
} else {
  console.log("error:", r.output)
}
```

### Passing parameters via env

```ts
const r = await Shell.run("echo $GREETING", {
  env: { GREETING: "hello world" },
})
console.log(r.output) // "hello world\n"
```

### Sharing parameters with `Script.queryParameters`

```ts
const r = await Shell.run('python -c "import os, json; print(json.loads(os.environ[\\"SCRIPTING_QUERY_PARAMETERS\\"]))"', {
  queryParameters: { name: "Alice", count: "3" },
})
console.log(r.output) // "{'name': 'Alice', 'count': '3'}\n"
```

### Detecting a timeout

```ts
const r = await Shell.run("sleep 30", { timeout: 2 })
if (r.timedOut) {
  console.log("killed by timeout")
}
```



---
url: /guide/Changelog/3.1.0/Speech (SSML).md
---

# Speech (SSML)

The `Speech` interface provides a high-level API for text-to-speech (TTS) functionality. This interface allows you to synthesize speech, control playback, and manage speech synthesis settings. Below are the details of the `Speech` API, its methods, properties, and usage examples.

***

## Features Overview

- **Text-to-Speech:** Convert text into speech with customizable options like pitch, rate, and volume.
- **Voice Management:** Choose from available system voices by language or identifier.
- **Markdown Support:** Render text with basic formatting using Markdown.
- **SSML Support:** Drive fine-grained pronunciation, pauses, and prosody with SSML (iOS 16+).
- **Audio Session Management:** Control audio sessions for seamless speech integration with other audio sources.
- **Event Listeners:** Respond to speech synthesis lifecycle events.

***

## Type Definitions

### `SpeechBoundary`

Specifies when to pause or stop speech:

- `'immediate'`: Pause/stop immediately.
- `'word'`: Pause/stop after finishing the current word.

***

### `SpeechSynthesisVoice`

Represents a voice for speech synthesis:

- `identifier`: Unique voice identifier.
- `name`: Display name of the voice.
- `language`: BCP 47 language and locale code.
- `quality`: Voice quality (`'default'`, `'premium'`, `'enhanced'`).
- `gender`: Voice gender (`'male'`, `'female'`, `'unspecified'`).

***

### `SpeechProgressDetails`

Details about progress during speech synthesis:

- `text`: Full text being spoken.
- `start`: Start index of the current word.
- `end`: End index of the current word.
- `word`: The current word being spoken.

***

### `SpeechSynthesisOptions`

Options for customizing speech synthesis:

- `isMarkdown` (optional): Interpret text as Markdown. Mutually exclusive with `isSSML`.
- `isSSML` (optional): Interpret text as an SSML (Speech Synthesis Markup Language) document. The text must be wrapped in a `<speak>...</speak>` root element. Available on iOS 16+. Mutually exclusive with `isMarkdown`.
- `pitch`, `rate`, `volume`: Override global `Speech` values for pitch, rate, and volume.
- `preUtteranceDelay`, `postUtteranceDelay`: Control pauses before and after utterances.
- `voiceIdentifier`, `voiceLanguage`: Override global voice settings.

***

## Static Properties

### Global Speech Settings

- `pitch`: Default pitch value (range: `0.5` to `2.0`; default: `1.0`).
- `rate`: Speech rate (range: `Speech.minSpeechRate` to `Speech.maxSpeechRate`; default: `Speech.defaultSpeechRate`).
- `volume`: Default volume (range: `0.0` to `1.0`; default: `1.0`).
- `preUtteranceDelay`, `postUtteranceDelay`: Global delays before and after utterances.

### Voice and Language

- `speechVoices`: Retrieves all available voices.
- `currentLanguageCode`: The device's current language code.

### Audio Session

- `usesApplicationAudioSession`: Specifies whether the app manages the audio session.

***

## Methods

### Speaking and Synthesis

- `speak(text: string, options?: SpeechSynthesisOptions): Promise<void>`\
  Adds text to the speech queue for synthesis.

- `synthesizeToFile(text: string, filePath: string, options?: SpeechSynthesisOptions): Promise<void>`\
  Synthesizes text to an audio file in the documents directory.

### Playback Control

- `pause(at?: SpeechBoundary): Promise<boolean>`\
  Pauses speech at the specified boundary. Defaults to "immediate".

- `resume(): Promise<boolean>`\
  Resumes speech from the paused state.

- `stop(at?: SpeechBoundary): Promise<boolean>`\
  Stops speech at the specified boundary. Defaults to "immediate".

### State Management

- `isSpeaking`: Checks if the synthesizer is speaking or paused.
- `isPaused`: Checks if the synthesizer is in a paused state.

### Voice Management

- `setVoiceByIdentifier(identifier: string): Promise<boolean>`\
  Sets a voice by its identifier.

- `setVoiceByLanguage(language: string): Promise<boolean>`\
  Sets a voice by its language code.

***

## Event Listeners

### Supported Events

- `start`: Speech synthesis starts.
- `pause`: Speech pauses.
- `continue`: Speech resumes.
- `finish`: Speech finishes.
- `cancel`: Speech is canceled.
- `progress`: Provides progress details (`SpeechProgressDetails`).

### Managing Listeners

- `addListener(event: string, listener: Function): void`\
  Adds an event listener.

- `removeListener(event: string, listener: Function): void`\
  Removes an event listener.

***

## Examples

### Setup `SharedAudioSession`

```ts
await SharedAudioSession.setActive(true)
await SharedAudioSession.setCategory(
  "playback",
  ["mixWithOthers"]
)
```

### Speak Text

```ts
await Speech.speak("Hello, world!")
```

### Speak with Custom Options

```ts
await Speech.speak("Welcome to **Scripting**", {
  isMarkdown: true,
  pitch: 1.5,
  rate: 0.8,
  voiceLanguage: "en-US",
})
```

### Synthesize to File

```ts
import { Path } from "scripting"

const filePath = Path.join(FileManager.documentDirectory, "output.caf")
await Speech.synthesizeToFile("Saving to file.", filePath, { rate: 1.0 })
```

### Control Playback

```ts
await Speech.speak("Pausing example...")
await Speech.pause("word")
await Speech.resume()
await Speech.stop() // Defaults stop "immediately".
```

### Add Progress Listener

```ts
Speech.addListener("progress", (details) => {
  console.log(`Speaking: ${details.word}`)
});
await Speech.speak("Event listening example.")
Speech.removeListener("progress", listener)
```

### Speak SSML (iOS 16+)

SSML lets you control pauses, prosody, pronunciation, and substitutions inline. Wrap the markup in a single `<speak>` root and pass `isSSML: true`.

Inline SSML tags (e.g. `<prosody>`, `<voice>`, `<break>`) take precedence; the utterance-level `voice` / `rate` / `pitch` / `volume` options still apply as fallbacks for any text that is not overridden by inline tags.

If the SSML cannot be parsed, the promise rejects with `"Failed to parse SSML representation."`. Passing both `isMarkdown: true` and `isSSML: true` rejects the promise with a usage error.

```ts
await Speech.speak(
  `<speak>
     Hello
     <break time="500ms" />
     <prosody rate="150%">nice to meet you!</prosody>
     <sub alias="World Wide Web Consortium">W3C</sub>
   </speak>`,
  { isSSML: true }
)
```

Supported SSML tags include `<speak>`, `<break>`, `<prosody>`, `<sub>`, `<phoneme>`, and others documented by Apple. See [`AVSpeechUtterance.init(ssmlRepresentation:)`](https://developer.apple.com/documentation/avfaudio/avspeechutterance/init\(ssmlrepresentation:\)) for details.



---
url: /guide/Changelog/3.1.0/SpeechRecognition.md
---

# SpeechRecognition

The `SpeechRecognition` interface provides a high-level API for performing speech recognition. It supports real-time speech recognition and recognition of audio files, offering flexibility in a variety of use cases.

***

## Features Overview

- **Real-Time Recognition:** Transcribe live audio from the microphone.
- **File-Based Recognition:** Analyze and transcribe recorded audio files.
- **Multi-Language Support:** Specify the recognition locale for different languages.
- **Intermediate Results:** Access partial and final results for progressive transcription.
- **Custom Callbacks:** Handle transcription results and sound level changes with event listeners.

***

## Type Definitions

### `RecognitionTaskHint`

Hints for the type of task for which speech recognition is used:

- `'confirmation'`: For commands like "yes," "no," or "maybe."
- `'dictation'`: For tasks similar to keyboard dictation.
- `'search'`: For identifying search terms.
- `'unspecified'`: For general-purpose speech recognition.

***

### `SpeechRecognitionResult`

Represents the result of speech recognition:

- `isFinal`: Indicates if the transcription is complete and final.
- `text`: Convenience alias for `bestTranscription.formattedString`, kept for backward compatibility.
- `bestTranscription`: The transcription with the highest confidence level (`SpeechTranscription`).
- `transcriptions`: Alternative transcriptions of the audio, sorted in descending order of confidence (`SpeechTranscription[]`).
- `metadata`: Aggregate speech metrics. Only available on final results (iOS 14.5+) (`SpeechRecognitionMetadata`).

***

### `SpeechTranscription`

A transcription of recognized speech:

- `formattedString`: The entire transcription formatted into a single, user-displayable string.
- `segments`: The individual word/utterance segments that compose this transcription (`SpeechTranscriptionSegment[]`).

> Speaking rate and average pause duration are reported on `SpeechRecognitionResult.metadata` instead, and only on final results.

***

### `SpeechTranscriptionSegment`

A single segment within a transcription, typically corresponding to a word:

- `substring`: The text content of this segment.
- `substringRange`: The UTF-16 character range of `substring` within the parent transcription's `formattedString` (`{ location: number, length: number }`).
- `timestamp`: The seconds offset, relative to the audio start, at which this segment was spoken.
- `duration`: The duration in seconds of this segment within the audio.
- `confidence`: Confidence in the accuracy of this segment, in `[0.0, 1.0]`. Only meaningful on final results; partial results typically report `0`.
- `alternativeSubstrings`: Alternative substrings the recognizer also considered for this segment.

***

### `SpeechRecognitionMetadata`

Aggregate speech metrics for a final recognition result:

- `speakingRate`: Speaking rate in words per minute.
- `averagePauseDuration`: Average pause duration in seconds between words.
- `speechStartTimestamp`: Seconds offset within the audio at which the user started speaking.
- `speechDuration`: Duration in seconds of the spoken speech.

***

## Static Properties

### Supported Locales

- `supportedLocales`: Returns a list of locales supported by the speech recognizer, such as `"en-US"`, `"fr-FR"`, or `"zh-CN"`.

### Recognition State

- `isRecognizing`: Indicates whether a recognition request is currently active.

***

## Methods

### Start Real-Time Recognition

`start(options: object): Promise<boolean>`\
Starts speech recognition from the device microphone.

#### Options

- `locale`: Locale string for the desired language (optional).
- `partialResults`: Return intermediate results (default: `true`).
- `addsPunctuation`: Automatically add punctuation to results (default: `false`).
- `requestOnDeviceRecognition`: Keep audio data on the device (default: `false`).
- `taskHint`: Specify the recognition task type (`'confirmation'`, `'dictation'`, `'search'`, `'unspecified'`).
- `useDefaultAudioSessionSettings`: Use default audio session settings (default: `true`).
- `preferredInput`: Preferred audio input port. `'auto'` (default) lets the system choose;
  `'builtInMic'` forces the device's built-in microphone even when a Bluetooth headset is
  connected — useful for keeping wireless headphones for playback while recording from the
  built-in mic for better audio quality. Falls back silently to the system default when
  `builtInMic` is not available on the device.
- `onResult`: Callback for recognition results (`SpeechRecognitionResult`).
- `onSoundLevelChanged`: Callback for sound level changes (optional).

#### Example

```ts
await SpeechRecognition.start({
  locale: "en-US",
  partialResults: true,
  addsPunctuation: true,
  onResult: (result) => {
    console.log("Transcription:", result.text)
  },
  onSoundLevelChanged: (level) => {
    console.log("Sound Level:", level)
  }
})
```

***

### Recognize Speech in Audio Files

`recognizeFile(options: object): Promise<boolean>`\
Starts recognition for a recorded audio file.

#### Options

- `filePath`: Path to the audio file.
- `locale`: Locale string for the desired language (optional).
- `partialResults`: Return intermediate results (default: `false`).
- `addsPunctuation`: Automatically add punctuation to results (default: `false`).
- `requestOnDeviceRecognition`: Keep audio data on the device (default: `false`).
- `taskHint`: Specify the recognition task type (`'confirmation'`, `'dictation'`, `'search'`, `'unspecified'`).
- `onResult`: Callback for recognition results (`SpeechRecognitionResult`).

#### Example

```ts
await SpeechRecognition.recognizeFile({
  filePath: FileManager.join(FileManager.documentDirectory, "example.wav"),
  locale: "en-US",
  addsPunctuation: true,
  onResult: (result) => {
    console.log("File Transcription:", result.text)
  }
})
```

***

### Stop Recognition

`stop(): Promise<void>`\
Stops an active speech recognition session.

#### Example

```ts
await SpeechRecognition.stop()
```

***

## Examples

### Real-Time Recognition with Progress Updates

```ts
await SpeechRecognition.start({
  locale: "en-US",
  onResult: (result) => {
    console.log(result.isFinal ? "Final Result:" : "Partial Result:", result.text)
  },
  onSoundLevelChanged: (level) => {
    console.log("Sound Level:", level)
  }
})
```

### Recognize Audio File

```ts
await SpeechRecognition.recognizeFile({
  filePath: FileManager.join(FileManager.documentDirectory, "audio.m4a"),
  partialResults: false,
  onResult: (result) => {
    console.log("File recognition completed. Transcription:", result.text)
  }
})
```

### Inspect Word-Level Timing and Alternatives

```ts
await SpeechRecognition.recognizeFile({
  filePath: FileManager.join(FileManager.documentDirectory, "audio.m4a"),
  partialResults: false,
  onResult: (result) => {
    if (!result.isFinal) return

    for (const segment of result.bestTranscription.segments) {
      console.log(
        `[${segment.timestamp.toFixed(2)}s + ${segment.duration.toFixed(2)}s] `
          + `${segment.substring} (confidence ${segment.confidence.toFixed(2)})`
      )
      if (segment.alternativeSubstrings.length > 0) {
        console.log("  alternatives:", segment.alternativeSubstrings.join(", "))
      }
    }

    if (result.metadata) {
      console.log("Speaking rate (wpm):", result.metadata.speakingRate)
      console.log("Speech duration (s):", result.metadata.speechDuration)
    }

    if (result.transcriptions.length > 1) {
      console.log("Alternative transcriptions:")
      for (const t of result.transcriptions.slice(1)) {
        console.log(" -", t.formattedString)
      }
    }
  }
})
```

***

### Stop Active Recognition

```ts
if (await SpeechRecognition.start({
  // ...
})) {
  // Stop after 10 seconds.
  setTimeout(() => {
    await SpeechRecognition.stop()
  }, 10 * 1000)
}

```

***

## Notes

- Ensure the necessary microphone or file access permissions are granted before using this API.
- Use `supportedLocales` to determine available languages for recognition.
- For optimal performance, use audio files in formats supported by iOS (e.g., `.wav`, `.m4a`).



---
url: /guide/Changelog/3.1.0/Spotlight.md
---

# Spotlight

`Spotlight` lets scripts add their own resources to the system Spotlight index. When the user taps one of those results, Scripting runs the same script's `spotlight.tsx` file.

Spotlight indexing requires Scripting PRO.

## Index Items

```ts
await Spotlight.index({
  id: "note-42",
  title: "Project Notes",
  contentDescription: "Open the project note from Spotlight.",
  keywords: ["notes", "project"],
  parameters: {
    noteID: "42",
    source: "spotlight"
  }
})
```

`id` is local to the current script. Calling `Spotlight.index` again with the same `id` updates the existing item.

```ts
await Spotlight.indexItems([
  {
    id: "task-1",
    title: "Follow up"
  },
  {
    id: "task-2",
    title: "Send invoice",
    parameters: { invoiceID: "2026-001" }
  }
])
```

## Item Fields

Only `id` and `title` are required. Apart from the two Scripting-only fields below, every field maps 1:1 to a property of Apple's [`CSSearchableItemAttributeSet`](https://developer.apple.com/documentation/corespotlight/cssearchableitemattributeset) and is grouped here the same way Apple documents them.

**Scripting-only**

- `id` _(required)_ — Script-local identifier, unique within the current script. Returned as `Spotlight.current.id` when the result is tapped.
- `parameters` — Arbitrary JSON delivered to `spotlight.tsx` as `Spotlight.current.parameters`. This is not a Spotlight metadata field; it is how you pass context to your tap handler.

**General**

- `title` _(required)_ — Primary title shown in the result.
- `displayName` — Display name; falls back to `title` when omitted.
- `alternateNames` — Other names the item can also be found by.
- `contentType` — Uniform Type Identifier (`UTType`) used to pick the result icon, e.g. `"public.image"`, `"com.adobe.pdf"`, `"public.movie"`, `"public.folder"`. Defaults to plain text.
- `contentURL` — URL of the underlying content; use a `file://` URL for local content.
- `thumbnailData` — Thumbnail image bytes. Takes priority over `thumbnailURL`.
- `thumbnailURL` — Local file URL string pointing to a thumbnail image.
- `keywords` — Extra terms the item should match against.
- `rankingHint` — Higher numbers rank the item higher among results.
- `supportsNavigation` — Marks the item as navigable; pair with `latitude` / `longitude`.
- `supportsPhoneCall` — Marks the item as callable; pair with `phoneNumbers`.

**Documents**

- `contentDescription` — Longer description shown under the title.
- `subject` — Subject of the content.
- `kind` — Human-readable kind, e.g. `"Note"`, `"Invoice"`.
- `creator` — Entity that created the content.
- `pageCount` — Number of pages.
- `fileSize` — Content size in bytes.

**Messaging**

- `textContent` — Full searchable body text; improves recall for free-text queries.
- `authorNames` — Author display names.
- `emailAddresses` — Associated email addresses.
- `phoneNumbers` — Associated phone numbers.

**Media**

- `comment` — Free-form comment.
- `contentCreationDate` — Creation date. Defaults to the first index time when omitted.
- `contentModificationDate` — Modification date. Defaults to the last index time when omitted.
- `lastUsedDate` — When the item was last used.

**Events**

- `startDate` / `endDate` — For event-like items.
- `dueDate` / `completionDate` — For task-like items.
- `allDay` — Whether the event spans the whole day.

**Places**

- `latitude` / `longitude` / `altitude` — Coordinates, in degrees / degrees / meters.
- `namedLocation` — Human-readable place name.
- `city` / `stateOrProvince` / `country` / `postalCode` / `fullyFormattedAddress` — Address components.

**Item-level**

- `expirationDate` — When Spotlight should drop the item from the index. Omit it to keep the item indexed until you delete it explicitly.

Notes:

- **Dates** (`contentCreationDate`, `lastUsedDate`, `startDate`, `expirationDate`, ...) accept a `Date`, an ISO-8601 string, or a numeric timestamp in seconds.
- **Thumbnails**: `thumbnailData` wins over `thumbnailURL` when both are set.

A full example touching every group:

```ts
await Spotlight.index({
  id: "doc-7",
  parameters: { reportID: "q3" },

  // General
  title: "Q3 Report",
  displayName: "Q3 Report",
  alternateNames: ["Quarterly Report"],
  contentType: "com.adobe.pdf",
  contentURL: "file:///path/to/report.pdf",
  thumbnailData: Data.fromFile("/path/to/thumb.png") ?? undefined,
  thumbnailURL: "/path/to/thumb.png",
  keywords: ["report", "finance"],
  rankingHint: 10,
  supportsNavigation: false,
  supportsPhoneCall: false,

  // Documents
  contentDescription: "Quarterly financials.",
  subject: "Finance",
  kind: "Report",
  creator: "Finance Team",
  pageCount: 12,
  fileSize: 204800,

  // Messaging
  textContent: "Full searchable body text...",
  authorNames: ["Jane Doe"],
  emailAddresses: ["jane@example.com"],
  phoneNumbers: ["+1-555-0100"],

  // Media
  comment: "Reviewed",
  contentCreationDate: new Date(),
  contentModificationDate: new Date(),
  lastUsedDate: Date.now(),

  // Events
  startDate: "2026-07-01T00:00:00Z",
  endDate: "2026-09-30T00:00:00Z",
  dueDate: new Date(),
  completionDate: new Date(),
  allDay: false,

  // Places
  latitude: 37.3349,
  longitude: -122.009,
  altitude: 30,
  namedLocation: "Apple Park",
  city: "Cupertino",
  stateOrProvince: "CA",
  country: "USA",
  postalCode: "95014",
  fullyFormattedAddress: "1 Apple Park Way, Cupertino, CA 95014",

  // Item-level
  expirationDate: new Date(),
})
```

## Search Reliability

How well an item surfaces is decided by the system, not by Scripting. A few things help:

- **Put every searchable term in `keywords` as a separate entry.** Spotlight matches whole words and word _prefixes_, not arbitrary substrings — searching `"part"` will match `"partner"` but searching `"art"` will not match it. For dictionary-style data, add each spelling, inflection, and alternate form as its own keyword (e.g. `["run", "runs", "running", "ran"]`).
- **Keep `title` short and exact.** It is the strongest matching field; put the canonical term there and push variants into `keywords` / `alternateNames`.
- **Use `rankingHint`** (higher = earlier) to bias ranking _among your own items_.
- **`textContent`** improves recall for longer free-text queries (definitions, body text).

Limitations to be aware of:

- Spotlight does not do substring/fuzzy matching, so mid-word or partial queries may not match. Add explicit prefixes as keywords if you need them.
- Apple's built-in results (Dictionary, Contacts, etc.) are privileged system data sources and are ranked separately. Custom items generally cannot outrank them for short, common words, no matter how they are tagged.

## Large Indexes

`indexItems` accepts large arrays and submits them to the system in batches; you can index several thousand items per script. `await` the call — it resolves once the work is handed to Spotlight, and awaiting is the recommended way to know indexing finished and to catch errors. Updating an existing `id` overwrites the previous item, so re-indexing is safe to call repeatedly.

## Handle Taps

Create a `spotlight.tsx` file in the script project:

```ts
const item = Spotlight.current

if (item) {
  console.log(item.id)
  console.log(JSON.stringify(item.parameters))
}
```

`Spotlight.current` is `null` in other script environments. It is available when `spotlight.tsx` is launched from a Spotlight result.

Spotlight tap parameters are not exposed through `Script.queryParameters`.

## Manage Items

```ts
const items = await Spotlight.getItems()

await Spotlight.delete("note-42")
await Spotlight.deleteItems(["task-1", "task-2"])
await Spotlight.deleteAll()
```

Users can also manage indexed items from Tools > Spotlight, including deleting entries whose script or `spotlight.tsx` file no longer exists.



---
url: /guide/Changelog/3.1.0/Storage (Python).md
---

# Storage (Python)

The `scripting` Python package exposes `Storage`, mirroring the JS-side `Storage` namespace. It provides a per-script persistent key-value store backed by `UserDefaults`, so Python and JS index scripts can share the same value when they read/write the same key.

```python
import scripting; Storage = scripting.Storage
```

By default each script's keys are isolated from other scripts. Pass `shared=True` to read/write the cross-script shared domain.

***

## Methods

### `Storage.set(key, value, shared=False) -> bool`

Persist `value` under `key`. `value` must be JSON-serializable (`str`, `int`, `float`, `bool`, `None`, `list`, `dict` and combinations). Returns `True` on success.

```python
Storage.set("counter", 42)
Storage.set("user", {"name": "Alice", "premium": True})
```

### `Storage.get(key, shared=False) -> Any | None`

Read the value previously stored under `key`. Returns `None` if the key doesn't exist.

```python
n = Storage.get("counter") or 0
user = Storage.get("user")  # {"name": "Alice", "premium": True}
```

### `Storage.remove(key, shared=False) -> None`

Delete the entry under `key`. No-op if the key doesn't exist.

### `Storage.contains(key, shared=False) -> bool`

Whether the key exists in storage.

### `Storage.keys() -> list[str]`

List all keys belonging to the current script (per-script namespace only — not the shared domain).

### `Storage.clear() -> None`

Remove all per-script keys for the current script. Does not affect the shared domain or other scripts' data.

***

## Parameters

| Name   | Type | Required       | Description                                                                                                             |
| ------ | ---- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| key    | str  | Yes            | The storage key. Per-script keys are automatically prefixed with the script's name; shared keys are used verbatim.      |
| value  | Any  | Yes (set only) | JSON-serializable value to store.                                                                                       |
| shared | bool | No             | When `True`, operates on the cross-script shared domain instead of the current script's namespace. Defaults to `False`. |

***

## Examples

### Counter that survives across runs

```python
import scripting; Storage = scripting.Storage; Script = scripting.Script

count = (Storage.get("hits") or 0) + 1
Storage.set("hits", count)
Script.exit({"hits": count})
```

### Sharing data with the JS side

```python
# Python side
import scripting; Storage = scripting.Storage
Storage.set("session_token", "abc123", shared=True)
```

```ts
// JS side reads the same value
const token = Storage.get<string>("session_token", { shared: true })
```

### Listing and clearing this script's data

```python
import scripting; Storage = scripting.Storage

print("Stored keys:", Storage.keys())
Storage.clear()  # wipe everything this script wrote
```



---
url: /guide/Changelog/3.1.0/symbolEffect: drawOn / drawOff + isActive + options/index.md
---

# 

***

title: symbolEffect: drawOn / drawOff + isActive + options
description: iOS 26 / SF Symbols 7 introduces drawOn and drawOff symbol animations. The bridge now exposes them via the `isActive` trigger form (mirrors SwiftUI symbolEffect(\_:options:isActive:)) — flip a bool to draw the symbol on or off. The new SymbolEffectOptions (speed / repeat / nonRepeating) is also wired through, and isActive is opened up for the existing appear / disappear / scale effects. Silent fallback on iOS \< 26 for drawOn/drawOff.

***

These modifiers allow you to customize how **SF Symbols** are displayed and animated inside views, particularly with the `Image` component.

***

## `symbolRenderingMode`

Sets the **rendering mode** for symbol images within the view.

### Type

```ts
symbolRenderingMode?: SymbolRenderingMode
```

### Options (`SymbolRenderingMode`)

- `"monochrome"` – A single-color version using the foreground style
- `"hierarchical"` – Multiple layers with different opacities for depth (good for semantic coloring)
- `"multicolor"` – Uses the symbol's built-in colors
- `"palette"` – Allows layered tinting (like using multiple `foregroundStyle` layers)

### Example

```tsx
<Image
  systemName="star.fill"
  symbolRenderingMode="palette"
  foregroundStyle={{
    primary: "red",
    secondary: "orange",
    tertiary: "yellow"
  }}
/>
```

### Explanation:

- `symbolRenderingMode="palette"` tells the system to render the symbol in **multiple layered styles**.
- `foregroundStyle` now uses an object with `primary`, `secondary`, and optionally `tertiary` layers to color those symbol layers individually.

> This matches SwiftUI's behavior with `.symbolRenderingMode(.palette)` and `.foregroundStyle(primary, secondary, tertiary)`.

***

## `symbolVariant`

Displays the symbol with a particular **visual variant**.

### Type

```ts
symbolVariant?: SymbolVariants
```

### Options (`SymbolVariants`)

- `"none"` – Default symbol with no variant
- `"circle"` – Encapsulated in a circle
- `"square"` – Encapsulated in a square
- `"rectangle"` – Encapsulated in a rectangle
- `"fill"` – Filled symbol
- `"slash"` – Adds a slash over the symbol (often used to indicate "off" states)

### Example

```tsx
<Image
  systemName="wifi"
  symbolVariant="slash"
/>
```

***

## `symbolEffect`

Applies a **symbol animation effect** to the view. This can include transitions (appear/disappear), scale, bounce, rotation, breathing, pulsing, and wiggle effects. You can also bind the effect to a value so it animates when the value changes.

### Type

```ts
symbolEffect?: SymbolEffect
```

There are two forms of usage:

***

### 1. **Simple effects** (transition, scale, etc.)

You can directly assign a symbol effect name:

#### Examples

```tsx
<Image
  systemName="heart"
  symbolEffect="appear"
/>

<Image
  systemName="checkmark"
  symbolEffect="scaleByLayer"
/>
```

***

### 2. **Value-bound discrete effects**

These effects animate when the associated value changes.

#### Type

```ts
symbolEffect?: {
  effect: DiscreteSymbolEffect
  value: string | number | boolean
  options?: SymbolEffectOptions
}
```

#### Example

```tsx
<Image
  systemName="star.fill"
  symbolEffect={{
    effect: "bounce",
    value: isFavorited
  }}
/>
```

In this example, each time `isFavorited` changes, the bounce animation is triggered.

***

### 3. **Trigger effects** (`isActive`, mirrors SwiftUI `symbolEffect(_:options:isActive:)`)

In SwiftUI's trigger form, the **steady state is `isActive = false`** (symbol visible). Flipping `isActive` plays the effect's animation; the direction depends on the effect:

| Effect        | `isActive=false` (steady) | `isActive=true` (effect engaged)         |
| ------------- | ------------------------- | ---------------------------------------- |
| `appear`      | invisible                 | visible (appears)                        |
| `disappear`   | visible                   | invisible (disappears)                   |
| `scale`       | base size                 | scaled                                   |
| **`drawOn`**  | **visible** (drawn)       | **invisible** (draw-off animation plays) |
| **`drawOff`** | **invisible**             | **visible** (draw-on animation plays)    |

Note that `drawOn` / `drawOff` describe the **animation style** (stroke-by-stroke drawing) — not the final state. `.drawOn` behaves like `.disappear` with a draw-style animation; `.drawOff` behaves like `.appear` with a draw-style animation.

```tsx
const [hidden, setHidden] = useState(false)

<Image
  systemName="checkmark.circle"
  symbolEffect={{
    effect: "drawOn",
    isActive: hidden,
  }}
/>

<Button title={hidden ? "Show" : "Hide"} action={() => setHidden(!hidden)} />
```

> `drawOn` / `drawOff` are SF Symbols 7 effects (iOS 26+). On earlier iOS the bridge silently passes content through unchanged.

***

### 4. **Animation options** (`SymbolEffectOptions`)

Attach `options` to either the value-bound or the trigger form. **Note:** SwiftUI treats trigger-form transitions like `drawOn` / `drawOff` / `appear` / `disappear` as single-shot — `repeat` is honored most reliably on value-bound effects (`pulse`, `bounce`, etc.).

```tsx
<Image
  systemName="bell.fill"
  symbolEffect={{
    effect: "pulse",
    value: pulseTick,
    options: {
      speed: 0.7,
      repeat: { count: 3, delay: 0.4 },
    },
  }}
/>
```

```ts
type SymbolEffectOptions = {
  /** Animation speed multiplier. `2` = twice as fast. */
  speed?: number
  /** Force a one-shot. Mutually exclusive with `repeat` — if both are set, `nonRepeating` wins and a warning is logged. */
  nonRepeating?: boolean
  /**
   * Repetition policy:
   *  - `"continuous"`: loop forever (iOS 18+; on iOS 17 falls back to `.repeating`)
   *  - `{ count, delay? }`: periodic — `count` cycles with optional `delay` (seconds) between them (iOS 18+)
   *  - `{ delay }`: periodic with delay only (iOS 18+)
   */
  repeat?:
    | "continuous"
    | { count: number; delay?: number }
    | { delay: number; count?: number }
}
```

***

## Available Discrete Effects (`DiscreteSymbolEffect`)

Use these with the value-bound form — animation replays whenever `value` changes.

| Category          | Effects                                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bounce**        | `bounce`, `bounceByLayer`, `bounceDown`, `bounceUp`, `bounceWholeSymbol`                                                                                                              |
| **Breathe**       | `breathe`, `breatheByLayer`, `breathePlain`, `breathePulse`, `breatheWholeSymbol`                                                                                                     |
| **Pulse**         | `pulse`, `pulseByLayer`, `pulseWholeSymbol`                                                                                                                                           |
| **Rotate**        | `rotate`, `rotateByLayer`, `rotateClockwise`, `rotateCounterClockwise`, `rotateWholeSymbol`                                                                                           |
| **VariableColor** | `variableColor`, `variableColorCumulative`, `variableColorDimInactiveLayers`, `variableColorHideInactiveLayers`, `variableColorIterative`                                             |
| **Wiggle**        | `wiggle`, `wiggleByLayer`, `wiggleWholeSymbol`, `wiggleLeft`, `wiggleRight`, `wiggleUp`, `wiggleDown`, `wiggleForward`, `wiggleBackward`, `wiggleClockwise`, `wiggleCounterClockwise` |

## Available Trigger Effects (`TriggerSymbolEffect`)

Use these with the `isActive` form. `drawOn` / `drawOff` are iOS 26+; the rest are iOS 17+.

| Category                               | Effects                                                                                 |
| -------------------------------------- | --------------------------------------------------------------------------------------- |
| **Appear**                             | `appear`, `appearByLayer`, `appearUp`, `appearDown`, `appearWholeSymbol`                |
| **Disappear**                          | `disappear`, `disappearByLayer`, `disappearUp`, `disappearDown`, `disappearWholeSymbol` |
| **Scale**                              | `scale`, `scaleByLayer`, `scaleUp`, `scaleDown`, `scaleWholeSymbol`                     |
| **DrawOn** _(iOS 26+ / SF Symbols 7)_  | `drawOn`, `drawOnByLayer`, `drawOnWholeSymbol`, `drawOnIndividually`                    |
| **DrawOff** _(iOS 26+ / SF Symbols 7)_ | `drawOff`, `drawOffByLayer`, `drawOffWholeSymbol`, `drawOffIndividually`                |

***

## Full Example

```tsx
<Image
  systemName="bell.fill"
  symbolRenderingMode="hierarchical"
  symbolVariant="circle"
  symbolEffect={{
    effect: "breathePulse",
    value: isNotified
  }}
  foregroundStyle="indigo"
/>
```

This image uses:

- a hierarchical rendering mode
- a circular variant around the symbol
- a pulsing animation bound to `isNotified` state

***

## Summary

| Modifier              | Description                                                             |
| --------------------- | ----------------------------------------------------------------------- |
| `symbolRenderingMode` | Sets how SF Symbols are rendered (monochrome, multicolor, etc.)         |
| `symbolVariant`       | Applies a visual variant like `fill`, `circle`, or `slash`              |
| `symbolEffect`        | Adds visual animation effects; can be static or bound to a state change |



---
url: /guide/Changelog/3.1.0/symbolEffect: drawOn / drawOff + isActive + options/index_example.md
---

# Example

```tsx
import { Button, HStack, Image, Navigation, NavigationStack, Script, Text, useState, VStack } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  // drawOn: isActive=false is the steady "drawn" state (visible).
  // Flipping isActive false→true triggers the DRAW-OFF animation (the symbol erases away).
  // Flipping back triggers the DRAW-ON animation (the symbol redraws).
  const [hiddenDefault, setHiddenDefault] = useState(false)
  const [hiddenByLayer, setHiddenByLayer] = useState(false)
  const [hiddenIndividually, setHiddenIndividually] = useState(false)

  // options demo: pulse on a value change, with speed + finite repeat.
  // value-form effects honor `repeat` reliably; trigger-form drawOn does not (single-shot).
  const [pulseTick, setPulseTick] = useState(0)

  // appear/disappear via isActive (iOS 17+) — analogous trigger family.
  const [hiddenStar, setHiddenStar] = useState(false)

  // existing value-form regression
  const [bounceCounter, setBounceCounter] = useState(0)

  return <NavigationStack>
    <VStack
      navigationTitle="symbolEffect"
      navigationBarTitleDisplayMode="inline"
      toolbar={{
        topBarTrailing: <Button title="Done" action={dismiss} />
      }}
    >
      <VStack
        spacing={24}
        padding
        alignment="leading"
      >
        {/* drawOn / drawOff (iOS 26+) */}
        <VStack alignment="leading" spacing={8}>
          <Text font="headline">drawOn (iOS 26+)</Text>
          <Text font="caption" foregroundStyle="secondaryLabel">
            With drawOn, isActive=false is the "drawn" steady state. Tap Hide to play
            the draw-OFF animation (erases away); tap Show to play draw-ON (redraws).
            byLayer / individually only change how layered symbols animate.
          </Text>
          <HStack spacing={24}>
            <VStack spacing={6}>
              <Image
                systemName="checkmark.circle"
                font={48}
                foregroundStyle="systemGreen"
                symbolEffect={{ effect: "drawOn", isActive: hiddenDefault }}
              />
              <Button
                title={hiddenDefault ? "Show" : "Hide"}
                action={() => setHiddenDefault(!hiddenDefault)}
                controlSize="small"
                buttonStyle="bordered"
              />
              <Text font="caption2">drawOn</Text>
            </VStack>
            <VStack spacing={6}>
              <Image
                systemName="square.and.arrow.up"
                font={48}
                foregroundStyle="systemBlue"
                symbolEffect={{ effect: "drawOnByLayer", isActive: hiddenByLayer }}
              />
              <Button
                title={hiddenByLayer ? "Show" : "Hide"}
                action={() => setHiddenByLayer(!hiddenByLayer)}
                controlSize="small"
                buttonStyle="bordered"
              />
              <Text font="caption2">byLayer</Text>
            </VStack>
            <VStack spacing={6}>
              <Image
                systemName="cloud.sun"
                font={48}
                foregroundStyle="systemOrange"
                symbolEffect={{ effect: "drawOnIndividually", isActive: hiddenIndividually }}
              />
              <Button
                title={hiddenIndividually ? "Show" : "Hide"}
                action={() => setHiddenIndividually(!hiddenIndividually)}
                controlSize="small"
                buttonStyle="bordered"
              />
              <Text font="caption2">individually</Text>
            </VStack>
          </HStack>
        </VStack>

        {/* options on a value-form effect (where speed + repeat are reliably honored) */}
        <VStack alignment="leading" spacing={8}>
          <Text font="headline">options (speed + repeat)</Text>
          <Text font="caption" foregroundStyle="secondaryLabel">
            Tap Pulse to replay the pulse animation 3 times at 0.7x speed with a 0.4s gap.
            options.repeat works on value-bound effects; trigger-form drawOn is single-shot.
          </Text>
          <HStack spacing={16}>
            <Image
              systemName="bell.fill"
              font={48}
              foregroundStyle="systemRed"
              symbolEffect={{
                effect: "pulse",
                value: pulseTick,
                options: { speed: 0.7, repeat: { count: 3, delay: 0.4 } },
              }}
            />
            <Button
              title="Pulse"
              action={() => setPulseTick(pulseTick + 1)}
              buttonStyle="borderedProminent"
              controlSize="small"
            />
            <Text font="caption" monospaced>tick: {pulseTick}</Text>
          </HStack>
        </VStack>

        {/* appear / disappear via isActive */}
        <VStack alignment="leading" spacing={8}>
          <Text font="headline">disappear (isActive)</Text>
          <Text font="caption" foregroundStyle="secondaryLabel">
            The same trigger form works for the iOS 17+ appear / disappear / scale family.
            disappear isActive=true hides the symbol (fade-style), parallel to drawOn isActive=true.
          </Text>
          <HStack spacing={16}>
            <Image
              systemName="star.fill"
              font={48}
              foregroundStyle="systemYellow"
              symbolEffect={{ effect: "disappear", isActive: hiddenStar }}
            />
            <Button
              title={hiddenStar ? "Show" : "Hide"}
              action={() => setHiddenStar(!hiddenStar)}
              buttonStyle="bordered"
              controlSize="small"
            />
          </HStack>
        </VStack>

        {/* value-form regression */}
        <VStack alignment="leading" spacing={8}>
          <Text font="headline">value-bound (bounce on change)</Text>
          <Text font="caption" foregroundStyle="secondaryLabel">
            Existing form: animation replays whenever value changes.
          </Text>
          <HStack spacing={16}>
            <Image
              systemName="heart.fill"
              font={48}
              foregroundStyle="systemPink"
              symbolEffect={{ effect: "bounce", value: bounceCounter }}
            />
            <Button
              title="Bounce"
              action={() => setBounceCounter(bounceCounter + 1)}
              buttonStyle="bordered"
              controlSize="small"
            />
            <Text font="caption" monospaced>{bounceCounter}</Text>
          </HStack>
        </VStack>
      </VStack>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />,
  })

  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.2.0/CloudSharedData.md
---

# CloudSharedData

The `CloudSharedData` class lets your script read and write an iCloud-backed shared data store and collaborate on it with other users — for example a baby-growth log that the whole family maintains together through the same script.

Data is stored in CloudKit (the owner's private iCloud database) and synced across participants. It requires the user to be signed in to iCloud and a **Pro** subscription, and the script must declare the `cloudSharedData` permission.

***

## Who creates a store

A store is identified by a **UUID**. Scripts are pure consumers — they cannot create or list stores. Instead:

- Create a store in **Settings → iCloud Shared Data** (or ask the assistant to create one). You get a store **UUID**.
- Paste that UUID into your script: `new CloudSharedData(uuid)`.
- To collaborate, share the store (from the management page or via `share()` / `presentShareSheet()` below) and have others accept. Once accepted, they paste the **same** UUID into the same script.

Isolation works by consent, not structure:

- **Per script/skill** — the first time a given script or skill touches a store, the user is asked to grant access for that script + store. Denying makes all calls for that store fail. Grants can be revoked in Settings → iCloud Shared Data.
- **Across users** — handled by CloudKit and Apple ID. A user can only access a store that was explicitly shared with them and that they accepted.

***

## Creating an instance

```ts
// The UUID comes from Settings → iCloud Shared Data, or from a share you accepted.
const store = new CloudSharedData("3F2504E0-4F89-41D3-9A0C-0305E82C3301")
```

***

## Directory semantics (entries)

Use key/value entries when multiple people append or edit independent records — concurrent appends never conflict.

```ts
// Owner or any participant
await store.put("2026-06-20", { height: 75, weight: 9.2 })

const entry = await store.get("2026-06-20")
// entry?.value -> { height: 75, weight: 9.2 }

const all = await store.entries()
// [{ key: "2026-06-20", value: {...}, hasBlob: false }, ...]

await store.remove("2026-06-20")
```

Attach a binary blob to an entry:

```ts
const photo = Data.fromJPEG(image, 0.8)!
await store.put("first-smile", { note: "🙂" }, photo)
const e = await store.get("first-smile")
// e?.blob -> Data | null
```

Same key written again overwrites it (last write wins). Editing the _same_ entry concurrently resolves last-writer-wins; appending or removing _different_ keys never conflicts.

***

## Single-file semantics

When the whole store is one document, use the file APIs (independent of entries):

```ts
await store.writeFile(Data.fromString(JSON.stringify(state))!)
const data = await store.readFile()
```

Concurrent writes to the file are last-writer-wins.

***

## Sharing

```ts
// Get a link to invite collaborators (works in every host, including widgets):
const info = await store.share({ permission: "readWrite" })
// info.url -> send it via Messages, etc.

// Or present the native invite sheet (main app, Share / Translation UI extensions):
await store.presentShareSheet({ permission: "readWrite" })

// Inspect participants / permission:
const current = await store.shareInfo()

// Stop sharing (owner only):
await store.stopSharing()
```

In the native sheet the user can choose between "only invited people" and "anyone with the link", and read-only vs read-write.

***

## Staying in sync

```ts
// Pull-based: cheaply check whether anything changed, then re-read.
if (await store.refresh()) {
  const all = await store.entries()
}

// Push-based: get notified when others change the store.
const unsubscribe = store.onChange(async () => {
  const all = await store.entries()
  // update your UI
})
// Call unsubscribe() when you no longer need updates.
```

***

## Methods

| Method                         | Description                                                           |
| ------------------------------ | --------------------------------------------------------------------- |
| `new CloudSharedData(storeId)` | Connect to a store by UUID (created in Settings, or shared with you). |
| `put(key, value, blob?)`       | Write/overwrite an entry.                                             |
| `get(key)`                     | Read an entry, or `null`.                                             |
| `remove(key)`                  | Delete an entry.                                                      |
| `entries()`                    | List all entries (blobs not loaded).                                  |
| `writeFile(data)`              | Overwrite the store's single-file data.                               |
| `readFile()`                   | Read the single-file data, or `null`.                                 |
| `refresh()`                    | Returns `true` if the store changed since the last call.              |
| `onChange(callback)`           | Observe remote changes; returns an unsubscribe function.              |
| `share(options?)`              | Start/fetch sharing; returns share info with a link.                  |
| `presentShareSheet(options?)`  | Present the native invite sheet.                                      |
| `shareInfo()`                  | Current share info, or `null`.                                        |
| `stopSharing()`                | Stop sharing (owner only).                                            |

***

## Notes

- Requires iCloud sign-in and a Pro subscription; declare the `cloudSharedData` permission in the script.
- Scripts cannot create or list stores — do that in Tools → iCloud Shared Data, or ask the assistant. Scripts consume a store by its UUID.
- Joining a shared store: when someone shares a store with you, tap their share link to open Scripting. It shows the store and an Accept button; after accepting, the store appears in Tools → iCloud Shared Data, where you can copy its ID and paste it into a script.
- The data API (read/write/share-link) works in the app and extensions; the native invite sheet only where a presentation context exists (app, Share / Translation UI extensions).
- Always call the function returned by `onChange` when you are done observing.



---
url: /guide/Changelog/3.2.0/DocumentInteraction/index.md
---

# DocumentInteraction

The `DocumentInteraction` interface presents the system **"Open in…"** menu (and the fuller options menu) for a file, letting the user pick an app to open or copy the file with.

> **There is no "open in default app" on iOS.** iOS has no concept of a default app per file type, and no public API to open a file directly in its associated app. Presenting this menu and letting the user choose is the only supported way to hand a file to another app.

## API

```ts
namespace DocumentInteraction {
  // "Open in…" menu — only the apps that can open/copy the file.
  function openInMenu(filePath: string): Promise<string | null>

  // Full options menu — Open in… plus Copy / Print / Save to Files / Markup, etc.
  function optionsMenu(filePath: string): Promise<string | null>
}
```

Both resolve to the **bundle identifier** of the app the file was sent to, or `null` if the user dismissed the menu without choosing an app (for `optionsMenu`, `null` also covers performing a non-open action such as Copy).

- `openInMenu` **rejects** if the file does not exist, or if no app is available to open it.
- `optionsMenu` **rejects** if the file does not exist.

On iPad the menu is shown as a popover anchored to the center of the current page.

## Example

```tsx
const path = FileManager.documentsDirectory + "/report.pdf"

try {
  const app = await DocumentInteraction.openInMenu(path)
  if (app != null) {
    console.log("Opened in:", app) // e.g. "com.apple.mobilenotes"
  } else {
    console.log("User dismissed the menu.")
  }
} catch (e) {
  // File missing, or no app can open this file type.
  console.error(e)
}
```

## Notes

- `filePath` must be the absolute path of an existing file.
- For files obtained from a document picker (security-scoped), make sure your script holds access to the file before presenting the menu.
- The file's display name comes from its file name; the file type is inferred from its extension.



---
url: /guide/Changelog/3.2.0/DocumentInteraction/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text } from "scripting"

// 准备一个示例文件,返回其绝对路径。
async function makeSampleFile(): Promise<string> {
  const path = FileManager.documentsDirectory + "/document-interaction-sample.txt"
  await FileManager.writeAsString(path, "Hello from Scripting!\nPick an app to open this file.")
  return path
}

function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"DocumentInteraction"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        footer={<Text>Presents the system "Open in…" menu so the user can pick an app to open the file with. iOS has no API to open a file directly in its default app.</Text>}
      >
        <Button
          title={"openInMenu"}
          action={async () => {
            try {
              const path = await makeSampleFile()
              const app = await DocumentInteraction.openInMenu(path)
              await Dialog.alert({
                message: app != null ? `Opened in: ${app}` : "Dismissed without choosing an app.",
              })
            } catch (e) {
              await Dialog.alert({ title: "Failed", message: String(e) })
            }
          }}
        />

        <Button
          title={"optionsMenu"}
          action={async () => {
            try {
              const path = await makeSampleFile()
              const app = await DocumentInteraction.optionsMenu(path)
              await Dialog.alert({
                message: app != null ? `Opened in: ${app}` : "Dismissed, or a non-open action was performed.",
              })
            } catch (e) {
              await Dialog.alert({ title: "Failed", message: String(e) })
            }
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Changelog/3.2.0/Editor/index.md
---

# Editor

A powerful code editor that can be controlled programmatically or embedded into a user interface. It supports syntax highlighting, read/write access, and flexible presentation using the `EditorController` class and the `Editor` component.

***

## EditorController

### Overview

`EditorController` is used to manage an instance of the editor. It allows you to configure the editor content, track changes, present the UI, and release resources.

### Constructor

Creates a new editor controller instance.

**Parameters**:

- `content` (optional): The initial text content displayed in the editor.
- `ext` (optional): The file extension used to determine syntax highlighting. Supported values include `tsx`, `ts`, `js`, `jsx`, `txt`, `md`, `css`, `html`, and `json`.
- `readOnly` (optional): If `true`, the editor is set to read-only mode. Defaults to `false`.

***

### Properties

#### `ext`

A read-only string indicating the file extension type provided during initialization. It determines the language syntax used in the editor.

#### `content`

A string representing the current content of the editor. You can assign a new value to update the editor programmatically.

#### `onContentChanged`

An optional callback function that will be triggered when the content is changed by the user. This callback is **not called immediately**, but approximately 100 milliseconds after editing occurs. This allows for debounced content tracking or autosave behavior.

***

### Methods

#### `present(options?)`

Displays the editor modally.

**Parameters**:

- `navigationTitle` (optional): Set the navigation title of the editor.
- `scriptName` (optional): A custom script name that overrides the default `Script.name` while the editor is running. Defaults to `"Temporary Script"`.
- `fullscreen` (optional): A boolean value that determines whether the editor should be presented in fullscreen mode. Defaults to `false`.

**Returns**: A Promise that resolves when the editor is dismissed.

#### `dismiss()`

Dismisses the currently presented editor view. This does **not** dispose of the controller instance, so you can call `present()` again later.

**Returns**: A Promise that resolves when dismissal is complete.

#### Navigation

- `scrollToLine(line)`: Scroll so the given **1-based** line is centered and place the cursor there.
- `scrollToPosition(position)`: Scroll so the given character offset is centered and place the cursor there.
- `scrollSelectionIntoView()`: Scroll so the current selection is visible.

#### Selection & text

- `getSelectedText(): Promise<string>`: Get the currently selected text (empty string when there is no selection). The promise **rejects** if the editor is not presented (timeout) or has been disposed.
- `setSelection(start, end)`: Select the range `[start, end)` and scroll it into view.
- `replaceSelection(text)`: Replace the current selection with `text`. When there is no selection, the text is inserted at the cursor.
- `selectAll()`: Select all text.

#### Search

- `searchText(query, options?): Promise<EditorTextRange[]>`: Search the whole document and return all matched ranges (`{ start, end, line }`). `options` supports `caseSensitive`, `regexp`, and `wholeWord`. The matching runs inside the editor, so you don't have to compute offsets yourself.

Scripting does not impose a built-in search UI — combine `searchText` (or your own matching over `content`) with `setSelection` to highlight a match and `replaceSelection` to replace it, so you can build a search & replace experience that fits your script.

#### Editing

- `undo()` / `redo()`: Undo or redo the last change.
- `toggleLineComment()` / `toggleBlockComment()`: Toggle line or block comments around the current selection.

#### `dispose()`

Releases the resources held by the editor controller. This must be called when the controller is no longer needed to avoid memory leaks. Once disposed, the controller cannot be used again.

***

## Editor Component

The `Editor` component is a React-style view that renders the editor inline within your UI. It is typically used in conjunction with an `EditorController` instance.

**Props**:

- `controller`: An `EditorController` instance that manages the editor's content and behavior.
- `scriptName` (optional): Overrides the default script name for the embedded editor session.
- `showAccessoryView` (optional): Whether to show the accessory view when the keyboard is visible. This is useful for showing buttons like "Move Left", "Move Right", "Delete", "Dissmiss Keyboard", etc. Defaults to `false`. It is recommended to set this to `true` when the editor is fully visible on the screen, such as when the editor is the only view in the screen.

***

### Example Usage

```tsx
function MyEditor() {
  const controller = useMemo(() => {
    return new EditorController({
      content: `const text = "Hello, World!"`,
      ext: "ts",
      readOnly: false,
    })
  }, [])
  
  useEffect(() => {
    return () => {
      controller.dispose()
    }
  }, [controller])

  return (
    <Editor
      controller={controller}
      scriptName="My Script"
      showAccessoryView
    />
  )
}
```

***

### Example: a custom search & replace bar (`index.tsx`)

This example builds its own search UI on top of the interaction APIs: `searchText` finds the
matches, `setSelection` highlights the current one, and `replaceSelection` replaces it.

```tsx
import { useEffect, useMemo, useState } from "scripting"

function EditorWithSearch() {
  const controller = useMemo(() => new EditorController({
    ext: "ts",
    content: [
      `const greeting = "hello"`,
      `console.log(greeting)`,
      `console.log(greeting.toUpperCase())`,
    ].join("\n"),
  }), [])

  const [query, setQuery] = useState("")
  const [replacement, setReplacement] = useState("")
  const [matches, setMatches] = useState<EditorTextRange[]>([])
  const [index, setIndex] = useState(0)

  useEffect(() => () => controller.dispose(), [controller])

  async function runSearch() {
    const result = await controller.searchText(query, { caseSensitive: false })
    setMatches(result)
    setIndex(0)
    if (result.length > 0) {
      const m = result[0]
      controller.setSelection(m.start, m.end)
    }
  }

  function goTo(next: number) {
    if (matches.length === 0) return
    const i = (next + matches.length) % matches.length
    setIndex(i)
    controller.setSelection(matches[i].start, matches[i].end)
  }

  function replaceCurrent() {
    if (matches.length === 0) return
    // The current match is already selected, so just replace the selection,
    // then re-run the search since offsets shifted.
    controller.replaceSelection(replacement)
    runSearch()
  }

  return (
    <VStack>
      <HStack>
        <TextField title="Find" value={query} onChanged={setQuery} />
        <Button title="Search" action={runSearch} />
      </HStack>
      <HStack>
        <TextField title="Replace" value={replacement} onChanged={setReplacement} />
        <Button title="Replace" action={replaceCurrent} />
      </HStack>
      <HStack>
        <Text>{matches.length > 0 ? `${index + 1} / ${matches.length}` : "No matches"}</Text>
        <Button title="Prev" action={() => goTo(index - 1)} />
        <Button title="Next" action={() => goTo(index + 1)} />
      </HStack>
      <Editor controller={controller} showAccessoryView />
    </VStack>
  )
}
```



---
url: /guide/Changelog/3.2.0/Editor/index_example.md
---

# Example

```tsx
import { Button, Editor, HStack, Navigation, NavigationStack, Script, Spacer, Text, TextField, useEffect, useMemo, useState, VStack } from "scripting"

// 这个示例基于 EditorController 的交互 API 自建一个搜索 / 替换栏：
//   - searchText  查找所有匹配（编辑器内完成，返回 { start, end, line }）
//   - setSelection 高亮当前匹配并滚动到可见
//   - replaceSelection 替换当前选中的匹配
//   - scrollToLine 跳转到指定行
// Scripting 不内置搜索 UI，你可以像这样组合出契合脚本的体验。

function Example() {
  const controller = useMemo(() => new EditorController({
    ext: "ts",
    content: [
      `const greeting = "hello"`,
      `console.log(greeting)`,
      `console.log(greeting.toUpperCase())`,
      `console.log(greeting.length)`,
    ].join("\n"),
  }), [])

  const [query, setQuery] = useState("greeting")
  const [replacement, setReplacement] = useState("message")
  const [matches, setMatches] = useState<EditorTextRange[]>([])
  const [index, setIndex] = useState(0)

  // 不再使用时释放编辑器资源。
  useEffect(() => () => controller.dispose(), [controller])

  async function runSearch() {
    const result = await controller.searchText(query, { caseSensitive: false })
    setMatches(result)
    setIndex(0)
    if (result.length > 0) {
      controller.setSelection(result[0].start, result[0].end)
    }
  }

  function goTo(next: number) {
    if (matches.length === 0) {
      return
    }
    const i = (next + matches.length) % matches.length
    setIndex(i)
    controller.setSelection(matches[i].start, matches[i].end)
  }

  async function replaceCurrent() {
    if (matches.length === 0) {
      return
    }
    // 当前匹配已被选中，直接替换选区；替换后偏移变化，重新搜索。
    controller.replaceSelection(replacement)
    await runSearch()
  }

  return <NavigationStack>
    <VStack
      navigationTitle={"Editor Search"}
      navigationBarTitleDisplayMode={"inline"}
      spacing={8}
      padding
    >
      <HStack>
        <TextField title={"Find"} value={query} onChanged={setQuery} />
        <Button title={"Search"} action={runSearch} />
      </HStack>

      <HStack>
        <TextField title={"Replace"} value={replacement} onChanged={setReplacement} />
        <Button title={"Replace"} action={replaceCurrent} />
      </HStack>

      <HStack>
        <Text>{matches.length > 0 ? `${index + 1} / ${matches.length}` : "No matches"}</Text>
        <Spacer />
        <Button title={"Prev"} action={() => goTo(index - 1)} />
        <Button title={"Next"} action={() => goTo(index + 1)} />
        <Button title={"Top"} action={() => controller.scrollToLine(1)} />
      </HStack>

      <Editor controller={controller} showAccessoryView />
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Control Widget.md
---

# Control Widget

The `ControlWidget` API enables users to add custom Button or Toggle controls to the iOS Control Center or Lock Screen. Each control is linked to an `AppIntent` to execute custom script logic. The controls support privacy protection, dynamic state labels, and SFSymbols icons.

***

## Control Label Type

### `ControlWidgetLabel`

Represents a label for a control, including the main label or value label in active/inactive state.

| Property           | Type       | Description                                                       |
| ------------------ | ---------- | ----------------------------------------------------------------- |
| `title`            | `string`   | The main title of the label.                                      |
| `systemImage`      | `string?`  | Optional SFSymbol image name for the label.                       |
| `privacySensitive` | `boolean?` | If `true`, the label content is hidden when the device is locked. |

***

## 1. `ControlWidgetButton`

Renders a button control that executes a script intent when tapped.

```ts
function ControlWidgetButton(props: ControlWidgetButtonProps): JSX.Element
```

### `ControlWidgetButtonProps`

| Property             | Type                          | Description                                                                                                              |
| -------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `privacySensitive`   | `boolean?`                    | If `true`, the control's state and content are hidden when the device is locked.                                         |
| `intent`             | `AppIntent<any>`              | The intent to be executed when the button is tapped.                                                                     |
| `label`              | `ControlWidgetLabel`          | The main label shown on the button.                                                                                      |
| `activeValueLabel`   | `ControlWidgetLabel \| null?` | The label shown when the button is active. Must be paired with `inactiveValueLabel`. Overrides `systemImage` in `label`. |
| `inactiveValueLabel` | `ControlWidgetLabel \| null?` | The label shown when the button is inactive. Must be paired with `activeValueLabel`. Overrides `systemImage` in `label`. |

> If either `activeValueLabel` or `inactiveValueLabel` is provided, both should be specified to ensure proper state display.

***

## 2. `ControlWidgetToggle`

Renders a toggle control that updates a boolean value using a script intent.

```ts
function ControlWidgetToggle<T extends { value: boolean }>(props: ControlWidgetToggleProps<T>): JSX.Element
```

### `ControlWidgetToggleProps<T>`

| Property             | Type                          | Description                                                                        |
| -------------------- | ----------------------------- | ---------------------------------------------------------------------------------- |
| `privacySensitive`   | `boolean?`                    | If `true`, the control's state and content are hidden when the device is locked.   |
| `intent`             | `AppIntent<T>`                | The intent to execute when toggled. The type `T` must extend `{ value: boolean }`. |
| `label`              | `ControlWidgetLabel`          | The main label for the toggle.                                                     |
| `activeValueLabel`   | `ControlWidgetLabel \| null?` | Label displayed when toggle is ON. Must be paired with `inactiveValueLabel`.       |
| `inactiveValueLabel` | `ControlWidgetLabel \| null?` | Label displayed when toggle is OFF. Must be paired with `activeValueLabel`.        |

***

## 3. `ControlWidget` Namespace

```ts
namespace ControlWidget
```

### `ControlWidget.parameter: string`

A user-defined string parameter set during control configuration. Useful for targeting specific resources (e.g., a device ID or door ID).

***

### `ControlWidget.present(element: VirtualNode): void`

Displays the control UI. Only `ControlWidgetButton` or `ControlWidgetToggle` elements are supported.

#### Usage Notes:

- `control_widget_button.tsx` must only render a `ControlWidgetButton`.
- `control_widget_toggle.tsx` must only render a `ControlWidgetToggle`.
- To hide the entire control content on the Lock Screen, use `privacySensitive` on the root.
- To redact only specific labels or values, apply `privacySensitive` inside `ControlWidgetLabel`.

#### Example:

```tsx
/// app_intents.tsx
export const ToggleDoorIntent = AppIntentManager.register({
  name: "ToggleDoorIntent",
  protocol: AppIntentProtocol.AppIntent,
  perform: async ({ id, value }: { id: string; value: boolean }) => {
    await setDoorState(id, value)
    ControlWidget.reloadToggles()
  }
})

/// control_widget_toggle.tsx
async function run() {
  const doorId = ControlWidget.parameter || "default"
  const data = await fetchDoorData(doorId)

  ControlWidget.present(
    <ControlWidgetToggle
      privacySensitive
      intent={ToggleDoorIntent({ id: doorId, value: !data.doorOpened })}
      label={{
        title: `Door ${doorId}`,
        systemImage: data.doorOpened ? "door.garage.opened" : "door.garage.closed"
      }}
      activeValueLabel={{ title: "The door is opened" }}
      inactiveValueLabel={{ title: "The door is closed" }}
    />
  )
}

run()
```

***

### `ControlWidget.reloadButtons(): void`

Reloads all control widget buttons. Useful when the intent result changes the UI state.

***

### `ControlWidget.reloadToggles(): void`

Reloads all toggle widgets. Call this after a toggle action to update state.

***

## 4. Development Notes

- Every control must be associated with an `AppIntent` to define its behavior.
- Toggle controls must pass an intent with a parameter shape `{ value: boolean }`.
- If using value labels (`activeValueLabel` / `inactiveValueLabel`), always provide both.
- System images (`systemImage`) should follow [SF Symbols](https://developer.apple.com/sf-symbols/) naming conventions.
- Use `ControlWidget.reloadButtons()` and `reloadToggles()` to force UI updates after state changes in the background.



---
url: /guide/Custom Keyboard.md
---

# Custom Keyboard

The `CustomKeyboard` namespace provides a comprehensive API for building fully custom keyboard UIs in the Scripting app. It allows you to create JSX-based keyboards, insert or modify text, query input state, respond to user interaction, and control keyboard layout or navigation.

***

## 1. Environment & Setup

### Requirements

- You must define your keyboard interface in a file named `**keyboard.tsx**` inside your script project.
- The `CustomKeyboard` API is **only available in the keyboard extension environment**.
- It is **not available** in App scripts, Intents (`intent.tsx`), or Widgets (`widget.tsx`).
- You must enable the keyboard in iOS settings:

  ```
  Settings > General > Keyboard > Keyboards > Add New Keyboard > Scripting
  ```

  Then tap the **Scripting Keyboard** and enable **Allow Full Access** to unlock clipboard and network features.

***

## 2. Presentation

### `present(node: VirtualNode): void`

Renders your custom keyboard UI using the given JSX node. This function **must be called once** in `keyboard.tsx`.

```tsx
function MyKeyboard() {
  return <Text>Hello from keyboard</Text>
}

CustomKeyboard.present(<MyKeyboard />)
```

***

## 3. Text Input State

| Property           | Type             | Description                              |
| ------------------ | ---------------- | ---------------------------------------- |
| `textBeforeCursor` | `string \| null` | Text before the cursor                   |
| `textAfterCursor`  | `string \| null` | Text after the cursor                    |
| `selectedText`     | `string \| null` | Currently selected text                  |
| `allText`          | `string`         | Currently entered text                   |
| `hasText`          | `boolean`        | Whether the text input contains any text |

***

## 4. Input Traits

### `useTraits(): TextInputTraits`

Hook to retrieve the current input traits (e.g., keyboard type, return key style). It automatically updates when `textDidChange` or `selectionDidChange` events occur.

### `traits: TextInputTraits`

A snapshot of the traits at the last change. Prefer `useTraits()` in JSX components for reactivity.

#### Example fields:

- `keyboardType`: `'default'`, `'numberPad'`, `'emailAddress'`...
- `returnKeyType`: `'go'`, `'search'`, `'done'`...
- `autocapitalizationType`: `'none'`, `'sentences'`, etc.
- `textContentType`: semantic input hints like `'username'`, `'oneTimeCode'`, etc.
- `keyboardAppearance`: `'light'`, `'dark'`, etc.

***

## 5. Text Manipulation

### `insertText(text: string): void`

Insert text at the current cursor position.

### `deleteBackward(): void`

Delete one character before the cursor.

### `moveCursor(offset: number): void`

Move the cursor by a number of characters. Negative = left; Positive = right.

### `setMarkedText(text, location, length): void`

Mark a portion of inserted text (used in composition scenarios like Pinyin input).

### `unmarkText(): void`

Clear any currently marked text.

***

## 6. Keyboard Behavior Control

### `dismiss(): void`

Dismiss the keyboard view.

### `nextKeyboard(): void`

Switch to the next system keyboard.

### `requestHeight(height: number): void`

Request a new keyboard height in points. Recommended range is **216–360pt**.

### `setHasDictationKey(value: boolean): void`

Control whether the dictation (microphone) key is shown.

### `setToolbarVisible(visible: boolean): void`

Show or hide the custom keyboard toolbar. Useful for debugging.

***

## 7. Navigation

### `allScripts: KeyboardScriptInfo[]`

Lists all scripts that can run in the custom keyboard extension.

```ts
const scripts = CustomKeyboard.allScripts
```

Each item contains:

| Property        | Type     | Description                 |
| --------------- | -------- | --------------------------- |
| `name`          | `string` | The script's stable name    |
| `localizedName` | `string` | The localized display name  |
| `icon`          | `string` | The script's SF Symbol name |
| `color`         | `string` | The script color name       |

### `switchToScript(scriptName: string, queryParameters?: Record<string, string>): Promise<void>`

Dismisses the current keyboard script and runs another keyboard script by name.
The optional `queryParameters` object is exposed to the target script as `Script.queryParameters`.

```ts
await CustomKeyboard.switchToScript("Rime Pinyin DEMO", {
  source: Script.name,
  mode: "symbols",
})
```

### `nextScript(queryParameters?: Record<string, string>): Promise<void>`

Dismisses the current keyboard script and runs the next available keyboard script.
The optional `queryParameters` object is exposed to the target script as `Script.queryParameters`.

```ts
await CustomKeyboard.nextScript({
  source: Script.name,
})
```

### `dismissToHome(): void`

Dismisses the currently active keyboard script and returns to the **Scripting keyboard home screen** (script list). Useful for letting users choose another script.

```ts
CustomKeyboard.dismissToHome()
```

***

## 8. User Feedback

### `playInputClick(): void`

Play the standard system keyboard click sound. Useful when simulating real key taps.

```ts
CustomKeyboard.playInputClick()
```

***

## 9. Event Listeners

### `addListener(event, callback): void`

Register a listener for keyboard or text input changes.

| Event                 | Callback Signature                  | Description                     |
| --------------------- | ----------------------------------- | ------------------------------- |
| `textWillChange`      | `() => void`                        | Before text changes             |
| `textDidChange`       | `(traits: TextInputTraits) => void` | After text changes              |
| `selectionWillChange` | `() => void`                        | Before cursor/selection changes |
| `selectionDidChange`  | `(traits: TextInputTraits) => void` | After cursor/selection changes  |

### `removeListener(event, callback): void`

Remove a specific listener.

### `removeAllListeners(event): void`

Remove all listeners for a given event type.

***

## 10. Full Example

```tsx
function MyKeyboard() {
  const traits = CustomKeyboard.useTraits()

  const insert = async (text: string) => {
    CustomKeyboard.playInputClick()
    CustomKeyboard.insertText(text)
  }

  return (
    <VStack spacing={12}>
      <Text>Input type: {traits.keyboardType}</Text>
      <HStack spacing={10}>
        <Button title="你" action={() => insert("你")} />
        <Button title="好" action={() => insert("好")} />
        <Button title="←" action={() => CustomKeyboard.deleteBackward()} />
        <Button title="Back" action={() => CustomKeyboard.dismissToHome()} />
      </HStack>
    </VStack>
  )
}

CustomKeyboard.present(<MyKeyboard />)
```

***

## 11. Best Practices

- **Call `present()` only once** in your `keyboard.tsx` file.
- Use `requestHeight()` to ensure appropriate layout on different screen sizes.
- Prefer `useTraits()` for reactive input context access in JSX.
- Use `dismissToHome()` instead of `dismiss()` if you want to return to the script list.
- Call `playInputClick()` when simulating key taps for user feedback.
- Always check for `hasText` before calling `deleteBackward()`.



---
url: /guide/Device Capabilities/AVAsset Reader / Writer / Export.md
---

# 

***

title: AVAsset Reader / Writer / Export
description: Low-level media pipelines: export-session transcode, frame-level read, and frame / sample write to mp4 / m4a.
tag: PRO
--------

Three lower-level companions to `AVAsset`, mirroring the iOS `AVAssetExportSession` / `AVAssetReader` / `AVAssetWriter` APIs:

- **`AVAssetExportSession`** — high-level transcoding / re-encoding with a preset name.
- **`AVAssetReader` + outputs** — pull decoded video frames as `UIImage` or PCM audio as `Float32Array`.
- **`AVAssetWriter` + `AVAssetWriterInput`** — push frames / samples produced in JS into a new mp4 / m4a file.

> **Local files only.** Both `AVAssetReader` and `AVAssetExportSession` are unreliable when fed an HTTP-streamed asset. Download remote sources to a local path first (`fetch()` + `FileManager.writeAsBytes()`), then construct the asset from that path.

***

## AVAssetExportSession

High-level transcode / re-encode using a preset.

```ts
const asset = new AVAsset("/path/to/input.mov")
const session = new AVAssetExportSession(asset, "HEVCHighestQuality")
session.outputFileType = "mp4"
session.onProgress = p => console.log(`${(p * 100).toFixed(0)}%`)
await session.exportTo("/path/to/output.mp4")
```

### Constructor

#### `new AVAssetExportSession(asset: AVAsset, presetName: AVAssetExportPreset)`

Throws if `asset` is not a non-disposed `AVAsset`. The preset's compatibility with the asset is validated lazily inside `exportTo()`.

```ts
type AVAssetExportPreset =
  | '640x480' | '960x540' | '1280x720' | '1920x1080' | '3840x2160'
  | 'AppleM4A'
  | 'LowQuality' | 'MediumQuality' | 'HighestQuality'
  | 'HEVC1920x1080' | 'HEVC3840x2160' | 'HEVCHighestQuality'
  | 'AppleProRes422LPCM' | 'AppleProRes4444LPCM'
```

### Properties

| Property                      | Type                                                                 | Description                                                                                                                |
| ----------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `outputFileType?`             | `'mp4' \| 'mov' \| 'm4a' \| 'm4v'`                                   | Optional. Pre-validated against the preset's `supportedFileTypes` to avoid an ObjC exception that would crash the process. |
| `timeRange?`                  | `{ start: MediaTime; duration: MediaTime }`                          | Optional clip range.                                                                                                       |
| `shouldOptimizeForNetworkUse` | `boolean`                                                            | Defaults to `true`.                                                                                                        |
| `status`                      | `'unknown' \| 'exporting' \| 'completed' \| 'failed' \| 'cancelled'` | Read-only.                                                                                                                 |
| `onProgress?`                 | `(p: number) => void`                                                | Polled at \~5 Hz while exporting; final call is always `1.0`.                                                              |

### Methods

#### `exportTo(outputPath: string): Promise<void>`

Resolves on success, rejects with the underlying `session.error.localizedDescription` on failure (including the cancellation case). Calling while another export is running rejects immediately.

If `outputFileType` is incompatible with the preset, the promise rejects with a list of supported types — it does **not** throw an uncatchable ObjC `NSInvalidArgumentException`.

#### `cancel(): void`

Cancels the in-flight export. The pending `exportTo` promise rejects with `"Export cancelled."`.

#### `dispose(): void`

Releases the underlying session.

***

## AVAssetReader

Pull decoded samples from an asset, frame-by-frame or chunk-by-chunk.

```ts
const asset = new AVAsset("/path/to/input.mp4")
const tracks = await asset.loadTracks("video")

const reader = new AVAssetReader(asset)
const out = new AVAssetReaderVideoOutput(tracks[0])
reader.add(out)
reader.startReading()

for (;;) {
  const frame = await out.copyNextFrame()
  if (frame == null) break  // true end-of-stream
  console.log(frame.presentationTime.seconds, frame.image.size)
}
```

### `AVAssetReader`

| Member                     | Description                                                                       |
| -------------------------- | --------------------------------------------------------------------------------- |
| `new AVAssetReader(asset)` | Throws if `asset` is disposed or invalid.                                         |
| `add(output): boolean`     | Returns `false` if reader is past `'unknown'` or output is incompatible.          |
| `startReading(): boolean`  | Must be called after `add()` and before any `copyNextX()`.                        |
| `cancelReading()`          | Aborts reading; pending `copyNextX()` promises reject with `"Reader cancelled."`. |
| `status`                   | `'unknown' \| 'reading' \| 'completed' \| 'failed' \| 'cancelled'`                |
| `error`                    | `string \| null` — localized error message when `status === 'failed'`.            |
| `dispose()`                | Cancels and releases.                                                             |

### `AVAssetReaderVideoOutput`

```ts
class AVAssetReaderVideoOutput {
  constructor(track: AVAssetTrack, options?: { pixelFormat?: 'bgra' | 'rgba' })
  copyNextFrame(): Promise<{ image: UIImage; presentationTime: MediaTime } | null>
}
```

`copyNextFrame()` returns `null` only on a clean end-of-stream. If the reader transitions to `'failed'` or `'cancelled'`, the promise **rejects** so you don't silently see "0 frames decoded".

### `AVAssetReaderAudioOutput`

```ts
class AVAssetReaderAudioOutput {
  constructor(tracks: AVAssetTrack[], options?: { sampleRate?: number; channels?: number })
  copyNextSamples(): Promise<{
    samples: Float32Array       // length === frameCount * channels (interleaved)
    frameCount: number
    sampleRate: number
    channels: number
    presentationTime: MediaTime
  } | null>
}
```

Always interleaved 32-bit float PCM. Pass multiple tracks to mix; `options.sampleRate` and `options.channels` resample / re-channel.

***

## AVAssetWriter

Manually push UIImage frames or PCM chunks to produce a new mp4 / m4a.

```ts
const sampleRate = 44100
const writer = new AVAssetWriter("/tmp/out.m4a", "m4a")
const input = AVAssetWriterInput.audio({ sampleRate, channels: 1, codec: "pcm" })
writer.add(input)
writer.startWriting()
writer.startSession(MediaTime.zero())

const samples = new Float32Array(sampleRate)  // 1 second of silence
input.appendPCMSamples(samples, sampleRate, 1, MediaTime.make({ value: 0, timescale: sampleRate }))
input.markAsFinished()
await writer.finishWriting()
```

### `AVAssetWriter`

| Member                                        | Description                                                            |
| --------------------------------------------- | ---------------------------------------------------------------------- |
| `new AVAssetWriter(outputPath, fileType)`     | Throws on unsupported `fileType` (`'mp4' \| 'mov' \| 'm4a' \| 'm4v'`). |
| `add(input): boolean`                         | Must be called before `startWriting`.                                  |
| `startWriting(): boolean`                     |                                                                        |
| `startSession(atSourceTime: MediaTime): void` | Usually `MediaTime.zero()`.                                            |
| `finishWriting(): Promise<void>`              | Resolves on `completed`, rejects on `failed` / `cancelled`.            |
| `cancelWriting()`                             |                                                                        |
| `status`                                      | `'unknown' \| 'writing' \| 'completed' \| 'failed' \| 'cancelled'`     |
| `error`                                       | Localized error when `status === 'failed'`.                            |
| `dispose()`                                   |                                                                        |

### `AVAssetWriterInput` (static factories)

```ts
AVAssetWriterInput.video({
  width: number, height: number,
  codec?: 'h264' | 'hevc',          // default 'h264'
  bitRate?: number,                 // bits per second
  frameRate?: number,
})

AVAssetWriterInput.audio({
  sampleRate?: number,              // default 44100
  channels?: number,                // default 1
  codec?: 'aac' | 'pcm',            // default 'aac'
  bitRate?: number,                 // only meaningful for AAC
})
```

| Member                                                                       | Description                                                                         |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `isReadyForMoreMediaData`                                                    | `true` when the encoder can accept more samples without blocking.                   |
| `markAsFinished()`                                                           | Call before `writer.finishWriting()`.                                               |
| `appendVideoFrame(image, presentationTime): boolean`                         | Returns `false` when the input is full or finished — `await whenReady()` and retry. |
| `appendPCMSamples(samples, sampleRate, channels, presentationTime): boolean` | Interleaved Float32; `samples.length === frameCount * channels`.                    |
| `whenReady(): Promise<void>`                                                 | Resolves when `isReadyForMoreMediaData` becomes `true`.                             |



---
url: /guide/Device Capabilities/AVAsset.md
---

# AVAsset

`AVAsset` is a heavyweight handle to a media resource (audio / video) backed by an iOS `AVURLAsset`. It lets you read media properties, metadata, and tracks, and extract still images at arbitrary times — without spinning up an `AVPlayer`.

You can also pass an `AVAsset` to `AVPlayer.setSource(asset)` to share the underlying media (and any already-loaded metadata) between inspection and playback.

***

## Getting Started

```ts
const asset = new AVAsset("https://example.com/movie.mp4")

const duration = await asset.loadDuration()
console.log("Duration:", duration.seconds, "seconds")

const playable = await asset.loadIsPlayable()
if (playable) {
  const player = new AVPlayer()
  player.setSource(asset)
  player.play()
}
```

***

## Validation

The constructor is intentionally lazy and matches the iOS `AVURLAsset` semantics:

- It does **not** verify file existence.
- It does **not** verify URL reachability.
- For remote URLs, only obviously malformed strings (where the underlying `URL(string:)` returns `nil`) throw immediately.
- All other failures (404, network errors, missing local files, unrecognized formats) surface as **Promise rejections** on the first `loadXxx()` call.

```ts
// Constructor succeeds — no validation:
const asset = new AVAsset("/does/not/exist.mp3")

// First load attempt rejects with a descriptive error:
try {
  await asset.loadDuration()
} catch (e) {
  console.error("Failed to load:", e.message)
}
```

***

## API Reference

### Constructor

#### `new AVAsset(filePathOrURL: string, options?: { headers?: Record<string, string> })`

Creates an asset from either a local file path or a remote `http(s)://` URL.

For remote URLs, you may pass HTTP headers (useful for authenticated content):

```ts
const asset = new AVAsset("https://example.com/private.mp4", {
  headers: { Authorization: "Bearer abc123" }
})
```

***

### Properties

#### `source: string`

The original file path or URL string used to construct this asset. Read-only.

***

### Async Loaders

All `loadXxx()` methods return a `Promise`. Failures (including missing files / unreachable URLs / unsupported formats) reject with an `Error`.

#### `loadDuration(): Promise<MediaTime>`

The total duration of the asset.

#### `loadIsPlayable(): Promise<boolean>`

Whether the asset can be played back.

#### `loadIsExportable(): Promise<boolean>`

Whether the asset can be exported (e.g. via `AVAssetExportSession`).

#### `loadIsReadable(): Promise<boolean>`

Whether the asset's media data can be read.

#### `loadHasProtectedContent(): Promise<boolean>`

Whether the asset has DRM-protected content.

#### `loadPreferredTransform(): Promise<{ a, b, c, d, tx, ty }>`

The 6 components of the preferred affine transform (rotation / scale / translation) used when rendering the video portion.

#### `loadMetadata(): Promise<AVMetadataItem[] | null>`

Loads all metadata items from the asset.

#### `loadCommonMetadata(): Promise<AVMetadataItem[] | null>`

Loads the common metadata items (each carries a `commonKey`).

***

### Tracks

#### `loadTracks(mediaType?: AVMediaType): Promise<AVAssetTrack[]>`

Loads tracks from the asset, optionally filtered by media type.

```ts
const videoTracks = await asset.loadTracks("video")
if (videoTracks.length > 0) {
  const size = await videoTracks[0].loadNaturalSize()
  console.log("Video size:", size.width, "x", size.height)
}
```

`AVMediaType` is one of:

```
'video' | 'audio' | 'subtitle' | 'text' | 'closedCaption' | 'metadata' | 'muxed' | 'timecode'
```

#### `AVAssetTrack`

| Member                    | Type                           | Description                            |
| ------------------------- | ------------------------------ | -------------------------------------- |
| `trackID`                 | `number`                       | Persistent identifier within the asset |
| `mediaType`               | `AVMediaType`                  | Track media type                       |
| `loadNaturalSize()`       | `Promise<Size>`                | Natural pixel dimensions               |
| `loadNaturalTimeScale()`  | `Promise<number>`              | Natural timescale                      |
| `loadNominalFrameRate()`  | `Promise<number>`              | Frames per second                      |
| `loadEstimatedDataRate()` | `Promise<number>`              | Bits per second                        |
| `loadTimeRange()`         | `Promise<{ start, duration }>` | Time range within the asset            |
| `loadLanguageCode()`      | `Promise<string \| null>`      | ISO 639-2/T language code              |

***

### Image Generation

#### `generateImage(time, options?): Promise<{ image, actualTime }>`

Generates a still image at a single requested time.

```ts
const time = MediaTime.make({ seconds: 5, preferredTimescale: 600 })
const result = await asset.generateImage(time, {
  maximumSize: { width: 640, height: 360 }
})
console.log("Got frame at", result.actualTime.seconds)
```

#### `generateImages(times, options?): Promise<...>`

Generates still images for an array of times. Each result is reported independently — successful entries carry `image` and `actualTime`; failed entries carry `error`.

```ts
const times = [0, 5, 10, 15].map(s =>
  MediaTime.make({ seconds: s, preferredTimescale: 600 })
)

const results = await asset.generateImages(times)
for (const r of results) {
  if ("image" in r) {
    console.log("Frame at", r.actualTime.seconds)
  } else {
    console.warn("Failed at", r.requestedTime.seconds, "—", r.error)
  }
}
```

#### `AVAssetImageGenerateOptions`

| Field                            | Type        | Default            | Description                                           |
| -------------------------------- | ----------- | ------------------ | ----------------------------------------------------- |
| `maximumSize`                    | `Size`      | natural            | Output size cap; aspect ratio is preserved            |
| `toleranceBefore`                | `MediaTime` | `MediaTime.zero()` | Max time before requested time the generator may pick |
| `toleranceAfter`                 | `MediaTime` | `MediaTime.zero()` | Max time after requested time the generator may pick  |
| `appliesPreferredTrackTransform` | `boolean`   | `true`             | Whether to honour the preferred track transform       |

***

### Lifecycle

#### `dispose(): void`

Releases the underlying `AVURLAsset`. Subsequent `loadXxx()` calls will reject. The script runtime auto-disposes any `AVAsset` you do not explicitly dispose when the script ends.

***

## AVAssetImageGenerator

`AVAsset.generateImage(...)` covers the one-shot "grab a cover frame" case. When you need to extract **many** frames — a thumbnail strip, per-frame OCR/ML — reach for the standalone `AVAssetImageGenerator`. Compared to the one-shot method it:

- **reuses one configured generator** across calls,
- **streams results frame-by-frame** as each one decodes (instead of waiting for the whole batch), and
- can be **cancelled mid-flight**.

```ts
const asset = new AVAsset("/path/to/movie.mp4")
const gen = new AVAssetImageGenerator(asset)

gen.maximumSize = { width: 320, height: 180 }
gen.requestedTimeToleranceBefore = MediaTime.zero()  // exact-frame
gen.requestedTimeToleranceAfter = MediaTime.zero()

const times = [0, 1, 2, 3, 4].map(s =>
  MediaTime.make({ seconds: s, preferredTimescale: 600 })
)

await gen.generate(times, frame => {
  switch (frame.status) {
    case "succeeded":
      console.log("frame", frame.actualTime.seconds, frame.image.width)
      break
    case "failed":
      console.log("failed", frame.requestedTime.seconds, frame.error)
      break
    case "cancelled":
      break
  }
})

gen.dispose()
asset.dispose()
```

### Properties

| Property                         | Type                                                         | Description                                                            |
| -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `maximumSize?`                   | `Size`                                                       | Max output size in pixels; aspect ratio preserved.                     |
| `requestedTimeToleranceBefore?`  | `MediaTime`                                                  | Tolerance before the requested time. `MediaTime.zero()` = exact frame. |
| `requestedTimeToleranceAfter?`   | `MediaTime`                                                  | Tolerance after the requested time.                                    |
| `appliesPreferredTrackTransform` | `boolean`                                                    | Respect rotation/mirroring. Defaults to `true`.                        |
| `apertureMode?`                  | `'cleanAperture' \| 'productionAperture' \| 'encodedPixels'` | Aperture mode.                                                         |

### Methods

#### `copyImage(time): Promise<{ image, actualTime }>`

Generates a single frame. Rejects with the underlying generator error.

#### `generate(times, onFrame): Promise<void>`

Generates a frame per time. `onFrame` fires once per requested time with a result tagged `succeeded` / `failed` / `cancelled`. The promise resolves once **every** time has been reported.

#### `cancel(): void`

Cancels in-flight generation. Pending times report `status: 'cancelled'` (the `generate` promise still resolves).

#### `dispose(): void`

Cancels and releases. Auto-called when the script finishes.

> **Local files only**, like the other low-level AVAsset companions. Download remote assets first.

***

## Sharing With AVPlayer

`AVPlayer.setSource(asset)` reuses the underlying media so any property already loaded on the asset is shared:

```ts
const asset = new AVAsset(url)
const metadata = await asset.loadCommonMetadata()  // pre-load before playback

const player = new AVPlayer()
player.setSource(asset)
player.play()
```

***

## Best Practices

1. **Use the right level of API** — for inspection only, prefer `AVAsset` over `AVPlayer` to avoid the playback machinery.
2. **Share assets between inspection and playback** — construct an `AVAsset` once, pass it to `AVPlayer.setSource(asset)`.
3. **Always handle Promise rejections** — failures surface there, not in the constructor.
4. **Prefer batch image generation** — `generateImages(times)` is more efficient than calling `generateImage(time)` in a loop.
5. **Tolerances trade exactness for speed** — for thumbnails, a small `toleranceBefore`/`After` (e.g. half a second) is usually faster than exact-frame seeking.

***

## Full Example

```ts
const asset = new AVAsset("/path/to/movie.mp4")

try {
  const [duration, videoTracks] = await Promise.all([
    asset.loadDuration(),
    asset.loadTracks("video"),
  ])

  console.log("Duration:", duration.seconds, "s")

  if (videoTracks.length > 0) {
    const size = await videoTracks[0].loadNaturalSize()
    console.log("Resolution:", size.width, "x", size.height)
  }

  // Take a thumbnail at the midpoint
  const mid = MediaTime.make({
    seconds: duration.seconds / 2,
    preferredTimescale: 600
  })
  const { image } = await asset.generateImage(mid, {
    maximumSize: { width: 320, height: 180 }
  })

  console.log("Thumbnail size:", image.width, "x", image.height)
} catch (e) {
  console.error("Asset error:", e.message)
} finally {
  asset.dispose()
}
```



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Camera Control (iOS 18+).md
---

# Camera Control (iOS 18+)

iOS 18 introduced the **Camera Control** — the dedicated hardware button on iPhone 16 (and on-screen control surface on other devices) that lets people adjust capture settings without diving into your UI. AVFoundation models this as a list of `AVCaptureControl` instances attached to the running `AVCaptureSession`. Scripting bridges all of them.

## Detecting support

The hardware Camera Control only ships on iPhone 16 and later. Always feature-detect:

```ts
if (!session.supportsControls) {
  // Fall back to plain on-screen UI; do not call addControl/setControlsDelegate.
  return
}
console.log(`max controls: ${session.maxControlsCount}`)
```

`session.supportsControls` is safe to call on older devices — Scripting wraps it with a `respondsToSelector` check so it just returns `false` rather than crashing.

## Built-in system controls

The two most common controls are provided by the system; pass the device they should bind to:

```ts
const camera = AVCaptureDevice.default("video")!
const zoom = new AVCaptureSystemZoomSlider(camera, value => {
  console.log("zoom →", value)
})
const exposure = new AVCaptureSystemExposureBiasSlider(camera, value => {
  console.log("exposure bias →", value)
})

session.configure(() => {
  if (session.canAddControl(zoom)) session.addControl(zoom)
  if (session.canAddControl(exposure)) session.addControl(exposure)
})
```

The system writes the zoom factor / exposure bias straight back to the device for you. The action callback is purely informational — use it to update your own UI.

## Custom slider

Continuous, stepped, or discrete-values:

```ts
// Continuous, formatted as ƒ-stops
const aperture = new AVCaptureSlider("Aperture", "camera.aperture", {
  range: [1.2, 16],
  defaultValue: 1.8,
  localizedValueFormat: "ƒ%.1f",
})

// Stepped (discrete) slider
const evStep = new AVCaptureSlider("EV", "sun.max", {
  range: [-2, 2],
  step: 0.33,
  prominentValues: [-1, 0, 1],
})

// Pre-defined values
const iso = new AVCaptureSlider("ISO", "circle.fill", {
  values: [50, 100, 200, 400, 800, 1600, 3200],
  defaultValue: 200,
  localizedValueFormat: "ISO %.0f",
})

aperture.setActionHandler(value => updateAperture(value))
```

Pass any [SF Symbols](https://developer.apple.com/sf-symbols/) name; Scripting does not validate it. If the symbol cannot be resolved at runtime the control simply renders without an icon.

## Custom index picker

Use this when titles are non-numeric or non-uniform:

```ts
const wb = new AVCaptureIndexPicker("White Balance", "camera.filters", {
  localizedIndexTitles: ["Auto", "Daylight", "Cloudy", "Tungsten"],
  defaultIndex: 0,
})
wb.setActionHandler(index => applyWhiteBalance(index))
```

## Adding controls to the session

`addControl(...)` follows the same rules as inputs/outputs: prefer `configure(...)` so the changes commit atomically. Adding more than `maxControlsCount` is a no-op (`canAddControl` returns `false`).

```ts
session.configure(() => {
  if (session.canAddControl(zoom)) session.addControl(zoom)
  if (session.canAddControl(aperture)) session.addControl(aperture)
  if (session.canAddControl(wb)) session.addControl(wb)
})
```

## Receiving lifecycle events

`AVCaptureSessionControlsDelegate` tells you when the system Camera Control UI shows / hides — useful for dimming your own overlay while the system control is on screen.

```ts
session.setControlsDelegate({
  didBecomeActive: () => setSystemControlVisible(true),
  willEnterFullscreenAppearance: () => setOverlayDimmed(true),
  willExitFullscreenAppearance: () => setOverlayDimmed(false),
  didBecomeInactive: () => setSystemControlVisible(false),
})
```

Pass `null` to remove the delegate.

## Hooking the hardware button to capture

The hardware Camera Control button does **not** dispatch through your control delegate by default — you must attach an `AVCaptureEventInteraction`. Without it, half-presses and full-presses are silently swallowed:

```ts
const interaction = new AVCaptureEventInteraction((phase, kind) => {
  if (phase === "ended" && kind === "primary") {
    photoOutput.capturePhoto({ codec: "hevc" })
  }
})
interaction.attach()

// when leaving the page:
interaction.detach()
```

`phase` is `"began" | "ended" | "cancelled"`. `kind` is `"primary"` for the main press and `"secondary"` for half-press / focus events.

## Common pitfalls

- **Delegate never fires.** You forgot `setControlsDelegate(...)`, or the session never started running.
- **Hardware press does nothing.** You forgot `new AVCaptureEventInteraction(...).attach()`.
- **`supportsControls` is `false`.** Either you are on a device without the hardware Camera Control, or the session has not been configured yet — always check after `addInput(...)`.
- **Custom slider does not show.** Either the SF Symbol name is wrong, or `maxControlsCount` is exceeded — Scripting silently drops the `addControl` call in both cases.



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/CaptureVideoPreviewView.md
---

# CaptureVideoPreviewView

`<CaptureVideoPreviewView/>` is the SwiftUI surface for rendering a live preview of any `AVCaptureSession` you have built. It mirrors `<VideoRecorderPreviewView/>` but accepts an arbitrary session, so it works with the pipelines you assemble manually.

```tsx
<CaptureVideoPreviewView
  session={session}
  videoDevice={camera}
  videoGravity="resizeAspectFill"
  cornerRadius={12}
  masksToBounds
/>
```

## Props

| Prop              | Type                                               | Default              | Description                                                                                                                                                                                           |
| ----------------- | -------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session`         | `AVCaptureSession`                                 | required             | The session to render. Must already have a video input attached to actually show frames.                                                                                                              |
| `videoDevice`     | `AVCaptureDevice`                                  | optional             | Pass the device backing the input. Doing so enables `AVCaptureDevice.RotationCoordinator`, so the preview rotates with the device. Without it the preview keeps the connection's default orientation. |
| `videoGravity`    | `'resize' \| 'resizeAspect' \| 'resizeAspectFill'` | `'resizeAspectFill'` | Same semantics as `AVLayerVideoGravity`.                                                                                                                                                              |
| `isVideoMirrored` | `boolean`                                          | system default       | Force the connection's `videoMirrored` flag (e.g. mirror front camera).                                                                                                                               |
| `cornerRadius`    | `number`                                           | `0`                  | Convenience for rounded preview tiles. Set `masksToBounds` if you need clipping.                                                                                                                      |
| `masksToBounds`   | `boolean`                                          | `false`              | Apply `masksToBounds` to the preview layer (turn on for `cornerRadius`).                                                                                                                              |

## Lifecycle

The preview view does **not** start or stop the session for you — call `session.startRunning()` from JavaScript when you want frames flowing. A typical SwiftUI-style pattern:

```tsx
function CameraPage() {
  const session = useMemo(() => buildSession(), [])

  useEffect(() => {
    session.startRunning()
    return () => {
      session.stopRunning()
      session.dispose()
    }
  }, [])

  return (
    <VStack>
      <CaptureVideoPreviewView session={session} videoDevice={camera} />
      <Button title="Capture" action={() => photoOutput.capturePhoto()} />
    </VStack>
  )
}
```

## Notes

- The same `AVCaptureSession` may only be rendered by one preview view at a time.
- Changing `videoGravity` / `isVideoMirrored` / `cornerRadius` after the view has rendered re-applies them on the next layout pass.
- For multi-cam setups (multiple inputs in the same session) use a single preview view; AVFoundation does the compositing internally.



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Device formats/index.md
---

# Device formats

Each `AVCaptureDevice` advertises an array of `AVCaptureDeviceFormat`s — one entry per capture mode the hardware supports (1080p30, 4K60, 720p binned, spatial video, etc.). Picking the right format is how you control resolution, frame rate, HDR, multi-cam compatibility, stabilization, and a handful of front-camera effects (Center Stage, Studio Light, Portrait).

The session preset (`session.sessionPreset = "photo"`) is a coarse alias that asks the system to pick a reasonable format. Switching the active format yourself locks the device into exact dimensions and frame rates.

## The wrapper, briefly

```ts
class AVCaptureDeviceFormat {
  readonly mediaType: string                 // "vide" / "soun" / ...
  readonly width: number                     // pixel width (0 for non-video)
  readonly height: number
  readonly fieldOfView: number               // degrees, horizontal

  readonly videoMaxZoomFactor: number
  readonly videoZoomFactorUpscaleThreshold: number
  readonly isVideoBinned: boolean

  readonly isHighestPhotoQualitySupported: boolean
  readonly isHighPhotoQualitySupported: boolean

  readonly isVideoHDRSupported: boolean
  readonly isMultiCamSupported: boolean
  readonly supportedColorSpaces: ("sRGB" | "P3_D65" | "HLG_BT2020" | "appleLog" | "appleLog2")[]
  readonly autoFocusSystem: "none" | "contrastDetection" | "phaseDetection"

  readonly videoSupportedFrameRateRanges: {
    minFrameRate: number, maxFrameRate: number,
    minFrameDuration: number, maxFrameDuration: number   // seconds
  }[]

  isVideoStabilizationModeSupported(
    mode: "off"|"standard"|"cinematic"|"cinematicExtended"
        |"cinematicExtendedEnhanced"|"previewOptimized"|"lowLatency"|"auto"
  ): boolean

  readonly isSpatialVideoCaptureSupported: boolean
  readonly isCenterStageSupported: boolean
  readonly isPortraitEffectSupported: boolean
  readonly isStudioLightSupported: boolean
}
```

You never construct one — obtain instances from `device.formats` or `device.activeFormat`.

## Identity is stable

Each device wrapper hands out the same `AVCaptureDeviceFormat` instance for the same underlying format every time. So:

```ts
const a = device.formats[0]
const b = device.formats[0]
console.log(a === b)                                       // true
console.log(device.formats.includes(device.activeFormat))  // true
```

That lets you do `formats.indexOf(device.activeFormat)`, compare with `===`, or stash a chosen format and reuse it later. The same underlying format obtained from two different `AVCaptureDevice` instances is two different JS wrappers, though — only meaningful if you build two device objects on purpose.

## Choosing a format

Standard pattern: filter `device.formats`, pick by your own rules, hand the winner to `setActiveFormat`.

```ts
const camera = AVCaptureDevice.default("video")!

// All 1080p formats that can do 60 fps and HDR
const candidates = camera.formats.filter(f =>
  f.width === 1920 && f.height === 1080 &&
  f.isVideoHDRSupported &&
  f.videoSupportedFrameRateRanges.some(r => r.maxFrameRate >= 60)
)

// Prefer non-binned (full sensor), then take whatever's left as a tie-breaker.
const winner =
  candidates.find(f => !f.isVideoBinned) ??
  candidates[0]

if (winner) {
  camera.setActiveFormat(winner)
}
```

A few common filters worth knowing:

| Goal                             | Filter expression                                                 |
| -------------------------------- | ----------------------------------------------------------------- |
| 4K UHD                           | `f.width === 3840 && f.height === 2160`                           |
| 60 fps capable                   | `f.videoSupportedFrameRateRanges.some(r => r.maxFrameRate >= 60)` |
| HDR ready                        | `f.isVideoHDRSupported`                                           |
| Spatial video (iPhone 15 Pro+)   | `f.isSpatialVideoCaptureSupported`                                |
| Multi-cam compatible             | `f.isMultiCamSupported`                                           |
| Supports cinematic stabilization | `f.isVideoStabilizationModeSupported("cinematic")`                |
| Apple Log color                  | `f.supportedColorSpaces.includes("appleLog")`                     |
| Center Stage capable (front cam) | `f.isCenterStageSupported`                                        |

## `setActiveFormat` rules

- The format **must** come from this same device's `formats` array. Passing a format obtained from another device throws — the check happens before any configuration lock, so a stray format won't take the camera down with it.
- `setActiveFormat` performs the change inside its own configuration lock. For a batch of related changes (format + color space + frame rate clamp), wrap the whole block in `device.lockForConfiguration()` / `device.unlockForConfiguration()` yourself so the camera only re-negotiates once.
- Changing format while a session is running is fine; connections are re-negotiated automatically. Sample-buffer outputs may briefly drop frames during the switch.

```ts
// Batched change — single lock, no flicker between settings
camera.lockForConfiguration()
try {
  camera.setActiveFormat(winner)
  camera.setActiveColorSpace("P3_D65")
  camera.setActiveVideoMinFrameDuration(1 / 60)
} finally {
  camera.unlockForConfiguration()
}
```

## Active color space

The active format dictates _which_ color spaces are possible; `device.activeColorSpace` and `device.setActiveColorSpace(value)` choose among them.

```ts
const camera = AVCaptureDevice.default("video")!
const supported = camera.activeFormat.supportedColorSpaces
console.log("current:", camera.activeColorSpace)
console.log("options:", supported)

if (supported.includes("appleLog")) {
  camera.setActiveColorSpace("appleLog")   // grading workflow
} else if (supported.includes("P3_D65")) {
  camera.setActiveColorSpace("P3_D65")     // wide-gamut still display
}
```

`setActiveColorSpace` throws if the value isn't in `activeFormat.supportedColorSpaces`. Switching format may change which color spaces are valid; re-check after `setActiveFormat`.

## Locking frame rate (`setActiveVideoMin/MaxFrameDuration`)

The active format publishes a range of supported frame rates — e.g. 1–60 fps. Use the two clamp setters to pin where in that range the camera actually runs:

- `device.setActiveVideoMinFrameDuration(seconds)` — **shorter** duration ⇒ **higher** maximum fps. Pass `1 / 60` to cap at 60 fps.
- `device.setActiveVideoMaxFrameDuration(seconds)` — **longer** duration ⇒ **lower** minimum fps. Pass `1 / 24` to floor at 24 fps.

```ts
// Lock to exactly 60 fps on a format that supports it
camera.setActiveVideoMinFrameDuration(1 / 60)
camera.setActiveVideoMaxFrameDuration(1 / 60)

console.log("now running between",
  1 / camera.activeVideoMaxFrameDuration, "and",
  1 / camera.activeVideoMinFrameDuration, "fps")
```

Both setters validate the seconds value against `activeFormat.videoSupportedFrameRateRanges` and throw if it falls outside every range. The getters return `0` when the device hasn't been clamped (the format's natural range is in effect).

## Field gotchas

- `width` / `height` / `fieldOfView` are **`0`** on non-video formats (audio, metadata) — they have no video dimensions. Filter to `mediaType === "vide"` if you only care about cameras.
- `videoSupportedFrameRateRanges` can have **multiple entries** — a single format may support, e.g., 1–30 fps and 60 fps in two separate ranges. Don't assume the array has one element.
- `videoMaxZoomFactor` is the hardware ceiling. `videoZoomFactorUpscaleThreshold` is the point above which the system starts digital upscaling instead of staying within the sensor's optical range.
- `isHighestPhotoQualitySupported` / `isHighPhotoQualitySupported` describe **photo** quality tiers — they affect `photoOutput.maxPhotoQualityPrioritization`, not video.
- `isCenterStageSupported` etc. report per-format support. The global toggle that turns these effects on system-wide is separate; on formats where the per-format flag is `false`, the system-wide toggle has no effect for this device.



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Device formats/index_example.md
---

# Example

```tsx
import {
  Button, CaptureVideoPreviewView, HStack, List, Navigation, NavigationStack,
  Script, ScrollView, Section, Spacer, Text, Toolbar, ToolbarItem,
  useEffect, useMemo, useObservable, VStack
} from "scripting"

type FormatRow = {
  /** 同一 wrapper 引用, 传回 setActiveFormat 用 */
  ref: AVCaptureDeviceFormat
  index: number
  label: string
  fpsLabel: string
  flagsLabel: string
  isActive: boolean
}

function describeFormat(f: AVCaptureDeviceFormat): { fps: string, flags: string } {
  // 多 range 拼接, 因为单个 format 可能同时报多档 fps
  const fps = f.videoSupportedFrameRateRanges
    .map(r => r.minFrameRate === r.maxFrameRate
      ? `${Math.round(r.maxFrameRate)}`
      : `${Math.round(r.minFrameRate)}-${Math.round(r.maxFrameRate)}`)
    .join(" / ") + "fps"

  const flags: string[] = []
  if (f.isVideoBinned) flags.push("binned")
  if (f.isVideoHDRSupported) flags.push("hdr")
  if (f.isMultiCamSupported) flags.push("multiCam")
  if (f.isSpatialVideoCaptureSupported) flags.push("spatial")
  if (f.isCenterStageSupported) flags.push("centerStage")
  if (f.isPortraitEffectSupported) flags.push("portrait")
  if (f.isStudioLightSupported) flags.push("studioLight")
  if (f.isHighestPhotoQualitySupported) flags.push("photoHQ+")
  return { fps, flags: flags.join(", ") || "—" }
}

function View() {
  const dismiss = Navigation.useDismiss()
  const isRunning = useObservable(false)
  const lastError = useObservable("")
  const activeLabel = useObservable("")
  // bump 一下触发 UI 重读 activeFormat / activeColorSpace / 帧率 clamp 状态
  const tick = useObservable(0)

  const { session, camera } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)

    session.configure(() => {
      // photo preset 让相机先以拍照模式跑起来, 后面 setActiveFormat 再覆盖具体维度
      session.sessionPreset = "photo"
      if (session.canAddInput(input)) session.addInput(input)
    })

    return { session, camera }
  }, [])

  // 一次性把 formats 包成行数据。`camera.formats` 对同一底层 format 始终返回同一实例,
  // 所以 `ref === camera.activeFormat` 用来高亮当前项是可靠的。
  const allRows = useMemo<FormatRow[]>(() => {
    return camera.formats.map((f, i) => {
      const { fps, flags } = describeFormat(f)
      return {
        ref: f,
        index: i,
        label: `${f.width}×${f.height} · ${f.mediaType}`,
        fpsLabel: fps,
        flagsLabel: flags,
        isActive: false,
      }
    })
  }, [camera])

  // 简单过滤: 4K / 1080p60 / spatial / multiCam — 用文档里给出的常见 filter
  const presets = useMemo(() => [
    { name: "All", filter: (_: AVCaptureDeviceFormat) => true },
    { name: "4K", filter: (f: AVCaptureDeviceFormat) => f.width === 3840 && f.height === 2160 },
    { name: "1080p60", filter: (f: AVCaptureDeviceFormat) =>
        f.width === 1920 && f.height === 1080 &&
        f.videoSupportedFrameRateRanges.some(r => r.maxFrameRate >= 60) },
    { name: "HDR", filter: (f: AVCaptureDeviceFormat) => f.isVideoHDRSupported },
    { name: "MultiCam", filter: (f: AVCaptureDeviceFormat) => f.isMultiCamSupported },
    { name: "Spatial", filter: (f: AVCaptureDeviceFormat) => f.isSpatialVideoCaptureSupported },
  ], [])

  const filter = useObservable<string>("All")
  const filteredRows = useMemo(() => {
    const pred = presets.find(p => p.name === filter.value)?.filter ?? (() => true)
    void tick.value // 让 active 高亮跟着切换重算
    return allRows
      .filter(r => pred(r.ref))
      .map(r => ({ ...r, isActive: r.ref === camera.activeFormat }))
  }, [allRows, filter.value, tick.value])

  function refreshActiveLabel() {
    const af = camera.activeFormat
    const minDur = camera.activeVideoMinFrameDuration
    const maxDur = camera.activeVideoMaxFrameDuration
    const fpsHi = minDur > 0 ? Math.round(1 / minDur) : null
    const fpsLo = maxDur > 0 ? Math.round(1 / maxDur) : null
    const fpsTag = (fpsHi || fpsLo) ? ` · ${fpsLo ?? "?"}-${fpsHi ?? "?"}fps` : ""
    activeLabel.setValue(
      `#${allRows.findIndex(r => r.ref === af)} · ${af.width}×${af.height} · ${camera.activeColorSpace}${fpsTag}`
    )
  }

  useEffect(() => {
    async function start() {
      try {
        await session.startRunning()
        isRunning.setValue(true)
        refreshActiveLabel()
      } catch (e) {
        await Dialog.alert({ message: `Failed to start: ${String(e)}` })
        dismiss()
      }
    }
    start()
    return () => {
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  async function applyFormat(row: FormatRow) {
    try {
      camera.setActiveFormat(row.ref)
      tick.setValue(tick.value + 1)
      refreshActiveLabel()
      lastError.setValue("")
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /** 把 active format 支持的色彩空间挨个尝一遍, 演示 setActiveColorSpace 的校验 */
  function cycleColorSpace() {
    try {
      const list = camera.activeFormat.supportedColorSpaces
      if (list.length === 0) {
        lastError.setValue("Active format reports no color spaces")
        return
      }
      const current = camera.activeColorSpace
      const idx = list.indexOf(current as any)
      const next = list[(idx + 1) % list.length]
      camera.setActiveColorSpace(next)
      tick.setValue(tick.value + 1)
      refreshActiveLabel()
      lastError.setValue(`color space → ${next}`)
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /** 把 fps 锁到 active format 支持的最高档 — 走 setActiveVideoMin/MaxFrameDuration 的合法路径 */
  function lockToMaxFps() {
    try {
      const ranges = camera.activeFormat.videoSupportedFrameRateRanges
      if (ranges.length === 0) {
        lastError.setValue("Active format reports no fps ranges")
        return
      }
      const top = ranges.reduce((a, b) => a.maxFrameRate >= b.maxFrameRate ? a : b)
      // 锁死 = min duration === max duration = 1 / top.maxFrameRate
      const dur = 1 / top.maxFrameRate
      camera.setActiveVideoMinFrameDuration(dur)
      camera.setActiveVideoMaxFrameDuration(dur)
      tick.setValue(tick.value + 1)
      refreshActiveLabel()
      lastError.setValue(`locked to ${Math.round(top.maxFrameRate)}fps`)
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /** 验证非法 fps duration 被拒: 用 1/1000 秒 (≈ 1000fps) 远超任何 format 的能力, 期望 throw */
  function probeInvalidFps() {
    try {
      camera.setActiveVideoMinFrameDuration(1 / 1000)
      lastError.setValue("Unexpected: invalid fps accepted")
    } catch (e) {
      lastError.setValue(`OK (rejected): ${String(e)}`)
    }
  }

  /** 验证跨 device 拒绝: 再取一次 default("video") 包成不同 wrapper, 把它的 format
   *  传给当前 camera, 期望抛 "does not belong to this device" */
  function probeForeignReject() {
    const another = AVCaptureDevice.default("video")
    if (!another) {
      lastError.setValue("No second device wrapper available")
      return
    }
    const foreign = another.formats[0]
    try {
      camera.setActiveFormat(foreign)
      lastError.setValue("Unexpected: foreign format accepted")
    } catch (e) {
      lastError.setValue(`OK (rejected): ${String(e)}`)
    }
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="Device formats"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 200 }}
          cornerRadius={12}
          masksToBounds
        />

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Status</Text>
          <Text font="footnote">
            running: {String(isRunning.value)} · active: {activeLabel.value} · total: {allRows.length}
          </Text>
          {lastError.value ? (
            <Text font="footnote" foregroundStyle="red">{lastError.value}</Text>
          ) : null}
        </VStack>

        <ScrollView axes="horizontal" scrollIndicator={'hidden'}>
          <HStack padding={8} spacing={8}>
            {presets.map(p => (
              <Button
                key={p.name}
                title={`${p.name} (${allRows.filter(r => p.filter(r.ref)).length})`}
                buttonStyle={filter.value === p.name ? "borderedProminent" : "bordered"}
                controlSize="small"
                action={() => filter.setValue(p.name)}
              />
            ))}
          </HStack>
        </ScrollView>

        <ScrollView axes="horizontal" scrollIndicator={'hidden'}>
          <HStack padding={8} spacing={8}>
            <Button title="Cycle color space" buttonStyle="bordered" controlSize="small" action={cycleColorSpace} />
            <Button title="Lock to max fps"   buttonStyle="bordered" controlSize="small" action={lockToMaxFps} />
            <Button title="Probe bad fps"      buttonStyle="bordered" controlSize="small" action={probeInvalidFps} />
            <Button title="Probe foreign"      buttonStyle="bordered" controlSize="small" action={probeForeignReject} />
          </HStack>
        </ScrollView>

        <List>
          <Section header={<Text>{filteredRows.length} format(s)</Text>}>
            {filteredRows.map(r => (
              <Button
                key={r.index}
                action={() => applyFormat(r)}
              >
                <VStack alignment="leading" spacing={2}>
                  <HStack>
                    <Text font="footnote" fontWeight={r.isActive ? "bold" : "regular"}>
                      #{r.index} · {r.label}
                    </Text>
                    <Spacer />
                    {r.isActive ? <Text font="footnote" foregroundStyle="green">ACTIVE</Text> : null}
                  </HStack>
                  <Text font="caption" foregroundStyle="secondaryLabel">
                    {r.fpsLabel} · {r.flagsLabel}
                  </Text>
                </VStack>
              </Button>
            ))}
          </Section>
        </List>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Live Photo/index.md
---

# Live Photo

A Live Photo is a photo _plus_ a short `.mov` companion clip captured around the shutter. `AVCapturePhotoOutput` lets you opt in per capture — pass `livePhotoMovieFile` to `capturePhoto` and `capturePhoto` resolves with both the still image and the path of the saved movie.

## Prerequisites

- The photo output must have `isLivePhotoCaptureSupported === true` (true on all camera-capable iPhones).
- You must enable it once on the output: `photoOutput.isLivePhotoCaptureEnabled = true`. The bridge silently clamps this to `false` on outputs that don't support Live Photo, so a follow-up read is the simplest feature gate.
- If `isLivePhotoCaptureEnabled` is `false` at the moment `capturePhoto` is called with `livePhotoMovieFile`, the promise **rejects immediately** rather than performing a non-Live capture.
- Do not enable `isAutoDeferredPhotoDeliveryEnabled` at the same time. With deferred on, the system may finalize without producing the `.mov`, and `livePhotoMovieFileURL` will be absent from the resolved value.

## Wiring it up

```ts
const camera = AVCaptureDevice.default("video")!
const session = new AVCaptureSession()
const photoOutput = new AVCapturePhotoOutput()

session.configure(() => {
  session.sessionPreset = "photo"
  session.addInput(new AVCaptureDeviceInput(camera))
  session.addOutput(photoOutput)
})

// One-time setup. The flag survives across capturePhoto calls.
photoOutput.isLivePhotoCaptureEnabled = true

await session.startRunning()

const ts = Date.now()
const photoFile = `${FileManager.documentsDirectory}/live_${ts}.heic`
const movieFile = `${FileManager.documentsDirectory}/live_${ts}.mov`

const result = await photoOutput.capturePhoto({
  codec: "hevc",
  photoFile,                 // ← required if you'll later call Photos.saveLivePhoto
  livePhotoMovieFile: movieFile,
  livePhotoVideoCodec: "hevc",
})

console.log("photo:", result.image.width, "×", result.image.height)
console.log("still file:", result.photoFileURL)
console.log("movie:", result.livePhotoMovieFileURL)
```

The resolved object has the usual `image / metadata / isRawPhoto / isDeferredProxy` plus an extra `photoFileURL: string` (if you passed `photoFile`) and `livePhotoMovieFileURL: string` (if you passed `livePhotoMovieFile`). If you didn't request a Live Photo, the `.mov` field is absent.

### Why `photoFile` matters for Live Photo

`capturePhoto` always gives you `result.image: UIImage` — but `UIImage` is a decoded bitmap with no original metadata. When you save a Live Photo to the system Photo Library via `Photos.saveLivePhoto(...)`, PhotoKit verifies that the still and the `.mov` share a Live Photo asset identifier (embedded in the Apple Maker Note under key 17 on the still; in `com.apple.quicktime.content.identifier` on the movie). Re-encoding the `UIImage` via `image.toJPEGData()` strips that identifier and PhotoKit rejects the pair with **`PHPhotosErrorDomain 3302`**.

The `photoFile` option avoids this by asking the bridge to write `photo.fileDataRepresentation()` straight to disk — that's the raw bytes the camera produced, with the Maker Note intact. Feed `result.photoFileURL` into `Photos.saveLivePhoto({ imagePath, videoPath })` and pairing works.

## What "resolve" actually waits for

A Live Photo capture fires two parallel AVFoundation callbacks: one for the still image and one for the `.mov` file. The bridge waits for **both** before resolving — you always get a fully usable pair, or an error. AVFoundation does not guarantee an order between the two, so don't rely on file timestamps to infer it.

The system also runs a "capture finish" sweep at the end. If something goes wrong half-way (e.g. the device drops the `.mov`), the bridge falls back to whatever has been delivered so far rather than hanging the promise.

## File path rules

- Pass an **absolute path** ending in `.mov`. `${FileManager.documentsDirectory}/...` is the easiest source of a writable path.
- AVFoundation refuses to write to an existing path. The bridge deletes the file at the requested path **before** the capture starts to spare you that error.
- The `.mov` is small (\~2–4 MB for a 1.5 s clip). Clean up old files yourself if you're capturing repeatedly.

## Codec selection

`livePhotoVideoCodec` is optional. Acceptable values:

- `"hevc"` — preferred on iPhone 7 and later (supported devices). Smaller files.
- `"h264"` — wider compatibility (older systems, some editing tools).

If you pass a codec that the device doesn't list in `availableLivePhotoVideoCodecTypes`, the bridge silently lets AVFoundation pick its default rather than failing the capture. Read the resolved file with an `AVAsset` if you need to know what was actually written.

## Things to know

- Live Photo + `flashMode = "on"` works, but the captured movie includes the flash flicker; design for that.
- The `.mov` you get is exactly what Photos.app would save — it includes a slight pre-roll and post-roll around the shutter.
- `capturePhoto` only writes files to disk — it doesn't put anything in the system Photo Library. To save the photo and clip as a single linked Live Photo (the way Camera.app does it), pass both paths to [`Photos.saveLivePhoto`](#):

  ```ts
  await Photos.saveLivePhoto({
    imagePath: result.photoFileURL!,           // raw HEIC from `photoFile` option
    videoPath: result.livePhotoMovieFileURL!,  // .mov from `livePhotoMovieFile` option
    shouldMoveFile: true,                      // move both into Photos rather than copy
  })
  ```

  This pairs them into one PHAsset; Photos.app shows the long-press "Live" animation on it. The first call triggers the system Photo Library permission prompt. **Do not** substitute `result.image.toJPEGData()` for `result.photoFileURL` — the re-encoded JPEG loses the Live Photo asset identifier and PhotoKit rejects the pairing.



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Live Photo/index_example.md
---

# Example

```tsx
import {
  Button, CaptureVideoPreviewView, HStack, Image,
  Navigation, NavigationStack, Script, Spacer, Text, Toolbar, ToolbarItem,
  useEffect, useMemo, useObservable, VStack
} from "scripting"

type Shot = {
  index: number
  image: UIImage
  photoSize: string
  /** native 写盘的原始 still bytes(HEIC/JPEG),含 Live Photo asset identifier */
  photoURL?: string
  movieURL?: string
  movieSize?: number
  ms: number
  isDeferredProxy: boolean
}

function View() {
  const dismiss = Navigation.useDismiss()
  const isRunning = useObservable(false)
  const shots = useObservable<Shot[]>([])
  const captureCount = useObservable(0)
  const lastError = useObservable("")
  const livePhotoSupp = useObservable(false)
  const livePhotoEn = useObservable(false)

  const { session, camera, photoOutput } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)
    const photoOutput = new AVCapturePhotoOutput()

    session.configure(() => {
      session.sessionPreset = "photo"
      if (session.canAddInput(input)) session.addInput(input)
      if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
    })

    // 必须在 addOutput 之后查 supported,在那之前 photoOutput 没绑 session 时 supported=false。
    return { session, camera, photoOutput }
  }, [])

  useEffect(() => {
    async function start() {
      try {
        await session.startRunning()
        isRunning.setValue(true)

        // Live Photo 必须开启 enabled 之后才会真正生效。
        photoOutput.isLivePhotoCaptureEnabled = true
        // 读回真实值: 不支持的设备 setter 会被 clamp 回 false。
        livePhotoSupp.setValue(photoOutput.isLivePhotoCaptureSupported)
        livePhotoEn.setValue(photoOutput.isLivePhotoCaptureEnabled)

        console.log("[startRunning]", {
          preset: session.sessionPreset,
          liveSupp: photoOutput.isLivePhotoCaptureSupported,
          liveEn:   photoOutput.isLivePhotoCaptureEnabled,
        })
      } catch (e) {
        await Dialog.alert({ message: `Failed to start: ${String(e)}` })
        dismiss()
      }
    }
    start()
    return () => {
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  async function takeLivePhoto() {
    const idx = captureCount.value + 1
    captureCount.setValue(idx)
    const ts = Date.now()
    // 同时让 native 写盘 still + .mov。两份文件共享 Apple Maker Note 里的
    // Live Photo asset identifier, Photos.saveLivePhoto 才能 pair 上。
    const photoFile = `${FileManager.documentsDirectory}/live_${idx}_${ts}.heic`
    const movieFile = `${FileManager.documentsDirectory}/live_${idx}_${ts}.mov`
    const start = Date.now()
    try {
      const result = await photoOutput.capturePhoto({
        codec: "hevc",
        photoFile,
        livePhotoMovieFile: movieFile,
        livePhotoVideoCodec: "hevc",
      })
      const ms = Date.now() - start

      // 读 movie 文件大小供 UI 显示
      let movieSize: number | undefined
      if (result.livePhotoMovieFileURL) {
        try {
          const stat = await FileManager.stat(result.livePhotoMovieFileURL)
          movieSize = stat.size
        } catch { /* ignore */ }
      }

      shots.setValue([{
        index: idx,
        image: result.image,
        photoSize: `${result.image.width}×${result.image.height}`,
        photoURL: result.photoFileURL,
        movieURL: result.livePhotoMovieFileURL,
        movieSize,
        ms,
        isDeferredProxy: result.isDeferredProxy,
      }, ...shots.value].slice(0, 6))
      lastError.setValue("")
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /** 不开 Live Photo,验证退化路径:resolve 不应包含 livePhotoMovieFileURL */
  async function takeRegular() {
    const idx = captureCount.value + 1
    captureCount.setValue(idx)
    const start = Date.now()
    try {
      const result = await photoOutput.capturePhoto({ codec: "hevc" })
      shots.setValue([{
        index: idx,
        image: result.image,
        photoSize: `${result.image.width}×${result.image.height}`,
        movieURL: result.livePhotoMovieFileURL,  // 应为 undefined
        ms: Date.now() - start,
        isDeferredProxy: result.isDeferredProxy,
      }, ...shots.value].slice(0, 6))
      lastError.setValue("")
    } catch (e) {
      lastError.setValue(String(e))
    }
  }

  /**
   * 把最新一张 Live Photo 配对存进系统照片库。
   * 关键: `imagePath` 必须用 native 写盘的 `result.photoFileURL`(原始 HEIC,
   * 含 Apple Maker Note 里的 Live Photo asset identifier),用 toJPEGData 重编码
   * 出来的 JPEG 会丢这个 identifier, Photos.saveLivePhoto 报 PHPhotosError 3302。
   * `shouldMoveFile: true` 会把磁盘上两个文件 move 进 Photos,本地副本就消失了。
   */
  async function saveLast() {
    const last = shots.value[0]
    if (!last) {
      lastError.setValue("Capture a Live Photo first")
      return
    }
    if (!last.photoURL || !last.movieURL) {
      lastError.setValue("Last capture missing photoURL or movieURL (was it a Regular shot?)")
      return
    }
    try {
      await Photos.saveLivePhoto({
        imagePath: last.photoURL,
        videoPath: last.movieURL,
        shouldMoveFile: true,
      })
      lastError.setValue(`Saved Live Photo #${last.index} to Photos library`)
    } catch (e) {
      lastError.setValue(`Save failed: ${String(e)}`)
      console.error(e)
    }
  }

  /** 故意关掉 enabled 再调 Live Photo,期望 promise reject */
  async function probeReject() {
    photoOutput.isLivePhotoCaptureEnabled = false
    livePhotoEn.setValue(photoOutput.isLivePhotoCaptureEnabled)
    try {
      await photoOutput.capturePhoto({
        livePhotoMovieFile: `${FileManager.documentsDirectory}/should_reject.mov`,
      })
      lastError.setValue("Unexpected: did not reject")
    } catch (e) {
      lastError.setValue(`OK (rejected): ${String(e)}`)
    } finally {
      // 恢复 enabled 方便继续测
      photoOutput.isLivePhotoCaptureEnabled = true
      livePhotoEn.setValue(photoOutput.isLivePhotoCaptureEnabled)
    }
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="Live Photo capture"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 280 }}
          cornerRadius={12}
          masksToBounds
        />

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Status</Text>
          <Text font="footnote">
            running: {String(isRunning.value)} · liveSupp: {String(livePhotoSupp.value)} · liveEn: {String(livePhotoEn.value)}
          </Text>
          {lastError.value ? (
            <Text font="footnote" foregroundStyle="red">
              {lastError.value}
            </Text>
          ) : null}
        </VStack>

        <HStack padding={8} spacing={10}>
          <Button title="Live Photo" action={takeLivePhoto} />
          <Button title="Regular" action={takeRegular} />
          <Button title="Save last" action={saveLast} />
          <Button title="Probe reject" action={probeReject} />
          <Spacer />
          <Text font="footnote" foregroundStyle="secondaryLabel">
            shots: {captureCount.value}
          </Text>
        </HStack>

        {shots.value[0] ? (
          <Image
            image={shots.value[0].image}
            resizable
            scaleToFit
            frame={{ height: 140 }}
          />
        ) : null}

        <VStack alignment="leading" spacing={2} padding={8}>
          <Text font="caption">Recent captures (newest first)</Text>
          {shots.value.map(s => (
            <Text key={s.index} font="footnote">
              #{s.index} · {s.ms}ms · {s.photoSize}
              {s.isDeferredProxy ? " · proxy" : ""}
              {s.movieURL
                ? ` · mov ${s.movieSize ? Math.round(s.movieSize / 1024) + "KB" : "?"}`
                : " · no .mov"}
            </Text>
          ))}
        </VStack>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Quick Start/index.md
---

# Quick Start

`AVCaptureSession` is the low-level building block for camera and microphone capture in Scripting. It is the same API that `VideoRecorder` is built on top of — but exposed as discrete, composable objects so that you can assemble your own pipeline: choose a device, attach inputs and outputs, run the session, and respond to the iPhone 16 hardware Camera Control.

If you just want to "press a button and record an mp4", reach for [`VideoRecorder`](#) — it manages the state machine, audio session, orientation and pause/resume timeline for you. Use `AVCaptureSession` when you need:

- QR / barcode scanning while previewing video
- Custom photo capture (HEVC, flash mode, Live Photo)
- A custom recording flow that does not match `VideoRecorder`'s state machine
- iPhone 16 Camera Control bindings (zoom slider, exposure slider, custom controls)
- Multiple outputs simultaneously (e.g. photo + movie)

PRO is required to call `startRunning()`, `capturePhoto()` and `startRecording()`. Construction, configuration and `canAdd*` checks are free.

***

## Pipeline at a glance

```ts
const session = new AVCaptureSession()
const camera = AVCaptureDevice.default("video")!
const input = new AVCaptureDeviceInput(camera)

session.configure(() => {
  session.sessionPreset = "photo"
  if (session.canAddInput(input)) session.addInput(input)
})

await session.startRunning()
// ... use session ...
await session.stopRunning()
session.dispose()
```

***

## Permissions

You don't request camera or microphone permission yourself. `session.startRunning()` inspects the inputs you have attached, prompts the user the first time, and rejects the promise if they deny. Other Scripting APIs (Photos, Contacts, Location) work the same way — the API call is the permission gate.

```ts
try {
  await session.startRunning()
} catch (e) {
  // Camera (or microphone, if you added an audio input) was denied,
  // restricted, or unavailable.
}
```

***

## Picking a device

`AVCaptureDevice.default(mediaType)` is the simplest path. For a specific lens or position use `AVCaptureDevice.defaultDevice(...)` or `AVCaptureDevice.discoverySession(...)`:

```ts
// Best back camera with hardware fallback
const back = AVCaptureDevice.defaultDevice(
  "builtInWideAngleCamera", "video", "back"
)

// Enumerate every supported lens type
const session = AVCaptureDevice.discoverySession({
  deviceTypes: [
    "builtInWideAngleCamera",
    "builtInUltraWideCamera",
    "builtInTelephotoCamera",
  ],
  mediaType: "video",
  position: "back",
})
console.log(session.devices.map(d => d.localizedName))
```

***

## Adding inputs and outputs

Wrap the device in an `AVCaptureDeviceInput` (the constructor throws if the device is busy or denied), then attach outputs. Use `session.configure(...)` to batch your changes — it wraps `beginConfiguration()` / `commitConfiguration()` for you.

```ts
const input = new AVCaptureDeviceInput(AVCaptureDevice.default("video")!)

const photoOutput = new AVCapturePhotoOutput()
photoOutput.maxPhotoQualityPrioritization = "quality"

session.configure(() => {
  if (session.canAddInput(input)) session.addInput(input)
  if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
})
```

> Calling `addInput` / `addOutput` outside of `configure(...)` works too, but each mutation hits the queue separately. Group them when you can.

***

## Photo capture

```ts
await session.startRunning()
const result = await photoOutput.capturePhoto({ codec: "hevc", flashMode: "auto" })
console.log("Captured", result.image.size, result.metadata)
```

The resolved object has `image: UIImage`, `metadata: Record<string, any>`, and `isRawPhoto: boolean`.

***

## Movie recording

```ts
const movieOutput = new AVCaptureMovieFileOutput()
movieOutput.maxRecordedDuration = 60     // seconds; 0 = unlimited
session.addOutput(movieOutput)

await session.startRunning()
const path = `${FileManager.documentsDirectory}/clip.mov`
const finalPath = await movieOutput.startRecording(path)   // resolves when stopRecording() finalizes
// ... show UI / await user tap ...
await movieOutput.stopRecording()
console.log("saved", finalPath)
```

`startRecording` resolves when the file is fully finalized; do not delete the file before the promise resolves.

***

## QR / barcode scanning

`AVCaptureMetadataOutput` runs the system code detector on the live frames.

```ts
const metaOutput = new AVCaptureMetadataOutput()
session.configure(() => {
  if (session.canAddInput(input)) session.addInput(input)
  if (session.canAddOutput(metaOutput)) session.addOutput(metaOutput)
})

// Order matters — types must be set after the output is added.
metaOutput.metadataObjectTypes = ["qr", "ean13", "code128"]
metaOutput.setMetadataObjectsListener(objects => {
  for (const o of objects) {
    if (o.stringValue) console.log("scanned", o.type, o.stringValue)
  }
})

await session.startRunning()
```

Set `rectOfInterest = { x, y, width, height }` (normalized 0..1) to limit detection to a region of the frame.

Each detected object carries a raw `bounds` (normalized 0..1) and, for codes, raw `corners`. It also carries a `transformed` field whose `bounds` / `corners` are corrected for the connection's orientation and mirroring — use those when drawing an overlay on top of the preview:

```ts
metaOutput.setMetadataObjectsListener(objects => {
  for (const o of objects) {
    const box = o.transformed?.bounds ?? o.bounds   // {x,y,width,height}, 0..1
    // map box into your view's pixel rect and draw a highlight
  }
})
```

To convert a rectangle between an output's own coordinate space and the metadata output's normalized space, use `output.metadataOutputRectConverted({ x, y, width, height })` and its inverse `output.outputRectConverted(...)`. Both are available on every output and return `{ x, y, width, height }`.

***

## Showing a preview

Use `<CaptureVideoPreviewView session={session} videoDevice={camera}/>` in any UI you build with Scripting's view layer. See the `Preview View` page for the full prop list.

***

## Cleanup

When you are done with the session — typically in `onAppear`/`onDisappear` of your component, or before navigating away — stop and dispose:

```ts
await session.stopRunning()
session.dispose()
```

`dispose()` is idempotent. If you forget it, the wrapper is also released when the running script ends.

***

## Putting it all together

```ts
const camera = AVCaptureDevice.default("video")!
const session = new AVCaptureSession()
const input = new AVCaptureDeviceInput(camera)
const photoOutput = new AVCapturePhotoOutput()

session.configure(() => {
  session.sessionPreset = "photo"
  if (session.canAddInput(input)) session.addInput(input)
  if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
})

session.addRuntimeErrorListener(msg => console.error("session error:", msg))

await session.startRunning()
const photo = await photoOutput.capturePhoto({ codec: "hevc" })
await session.stopRunning()
session.dispose()
```



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Quick Start/index_example.md
---

# Example

```tsx
import {
  Button, CaptureVideoPreviewView, HStack, Navigation,
  NavigationStack, Path, Script, Spacer, Text, Toolbar, ToolbarItem,
  ToolbarItemGroup, useEffect, useMemo, useObservable, VStack
} from "scripting"

function View() {
  const dismiss = Navigation.useDismiss()
  const lastResult = useObservable("")
  const lastBounds = useObservable("—")
  const caps = useObservable("—")
  const isRunning = useObservable(false)
  const torchOn = useObservable(false)
  const supportsControls = useObservable(false)

  // 一次性建好 session + 输入 + 输出。useMemo 保证 hot reload 时不重复创建。
  const { session, camera, photoOutput, metaOutput } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)
    const photoOutput = new AVCapturePhotoOutput()
    const metaOutput = new AVCaptureMetadataOutput()

    session.configure(() => {
      session.sessionPreset = "high"
      if (session.canAddInput(input)) session.addInput(input)
      if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
      if (session.canAddOutput(metaOutput)) session.addOutput(metaOutput)
    })

    metaOutput.metadataObjectTypes = ["qr", "code128", "ean13"]
    metaOutput.setMetadataObjectsListener(objects => {
      for (const o of objects) {
        // 新增 API:transformed 是方向/镜像校正后的坐标(画 overlay 用),
        // corners 是机读码的四个角点。回退到原始 bounds。
        const b = o.transformed?.bounds ?? o.bounds
        lastBounds.setValue(
          `${o.type} @ ${b.x.toFixed(2)},${b.y.toFixed(2)} ${b.width.toFixed(2)}×${b.height.toFixed(2)}`
        )
        if (o.corners?.length) console.log("corners:", JSON.stringify(o.corners))
        if (o.transformed) console.log("transformed:", JSON.stringify(o.transformed))
        if (o.stringValue) {
          lastResult.setValue(`${o.type}: ${o.stringValue}`)
          break
        }
      }
    })

    return { session, camera, photoOutput, metaOutput }
  }, [])

  useEffect(() => {
    let interaction: AVCaptureEventInteraction | null = null

    async function start() {
      // startRunning 自带权限申请,拒绝时会 reject
      try {
        await session.startRunning()
        isRunning.setValue(true)
        logCapabilities()
      } catch (e) {
        await Dialog.alert({ message: `Failed: ${String(e)}` })
        dismiss()
        return
      }

      // iPhone 16 Camera Control: 系统缩放滑块 + 自定义曝光滑块 + 硬件按键拍照
      if (session.supportsControls) {
        supportsControls.setValue(true)
        const zoom = new AVCaptureSystemZoomSlider(camera)
        const ev = new AVCaptureSlider("EV", "sun.max", {
          range: [-2, 2],
          step: 0.33,
          defaultValue: 0,
          localizedValueFormat: "%.1f",
        })
        ev.setActionHandler(value => {
          camera.setExposureTargetBias(value).catch(console.error)
        })
        session.configure(() => {
          if (session.canAddControl(zoom)) session.addControl(zoom)
          if (session.canAddControl(ev)) session.addControl(ev)
        })

        interaction = new AVCaptureEventInteraction((phase, kind) => {
          if (phase === "ended" && kind === "primary") {
            takePhoto()
          }
        })
        interaction.attach()
      }
    }

    start()

    return () => {
      interaction?.detach()
      metaOutput.setMetadataObjectsListener(null)
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  // 新增 API 巡检:photo 能力查询 / connections / 坐标转换。startRunning 之后调用,
  // 此时 output 已有 connection,codec / maxPhotoDimensions 才有效。
  function logCapabilities() {
    const dims = photoOutput.maxPhotoDimensions
    const lines = [
      `photo codecs: ${photoOutput.availablePhotoCodecTypes.join(", ")}`,
      `live photo codecs: ${photoOutput.availableLivePhotoVideoCodecTypes.join(", ") || "none"}`,
      `flash: ${photoOutput.supportedFlashModes.join(", ")}`,
      `maxPhotoDimensions: ${dims.width}×${dims.height}`,
      `depth: ${photoOutput.isDepthDataDeliverySupported}, portraitMatte: ${photoOutput.isPortraitEffectsMatteDeliverySupported}, proRAW: ${photoOutput.isAppleProRAWSupported}`,
      `connections — photo: ${photoOutput.connections.length}, meta: ${metaOutput.connections.length}`,
    ]
    // 坐标转换:output 坐标 → metadata 归一化坐标(及其逆向)。
    const roi = { x: 0.25, y: 0.25, width: 0.5, height: 0.5 }
    const toMeta = metaOutput.metadataOutputRectConverted(roi)
    const back = metaOutput.outputRectConverted(toMeta)
    lines.push(`rect ${JSON.stringify(roi)} → meta ${JSON.stringify(toMeta)} → back ${JSON.stringify(back)}`)

    const c = photoOutput.connections[0]
    if (c) lines.push(`conn[0]: active=${c.isActive} mirrored=${c.isVideoMirrored} angle=${c.videoRotationAngle}`)

    console.log("[capabilities]\n" + lines.join("\n"))
    caps.setValue(`${photoOutput.availablePhotoCodecTypes.join("/")} · ${dims.width}×${dims.height} · conn ${photoOutput.connections.length}`)
  }

  async function takePhoto() {
    try {
      const result = await photoOutput.capturePhoto({ codec: "hevc" })
      await Dialog.alert({
        title: "Captured",
        message: `Photo size: ${result.image.width} × ${result.image.height}`,
      })
    } catch (e) {
      console.error("capturePhoto failed:", e)
    }
  }

  function toggleTorch() {
    if (!camera.hasTorch) return
    const next = torchOn.value ? "off" : "on"
    camera.setTorchMode(next)
    torchOn.setValue(next === "on")
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="AVCaptureSession Demo"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 480 }}
          cornerRadius={12}
          masksToBounds
        />
        <Text>Last scan: {lastResult.value || "—"}</Text>
        <Text font="footnote" foregroundStyle="secondaryLabel">
          Bounds (transformed): {lastBounds.value}
        </Text>
        <Text font="footnote" foregroundStyle="secondaryLabel">
          Capabilities: {caps.value}
        </Text>
        <Text font="footnote" foregroundStyle="secondaryLabel">
          Camera Control: {supportsControls.value ? "supported" : "not available on this device"}
        </Text>
        <HStack spacing={12}>
          <Button title="Photo" action={takePhoto} />
          <Button
            title={torchOn.value ? "Torch off" : "Torch on"}
            action={toggleTorch}
            disabled={!camera.hasTorch}
          />
          <Spacer />
        </HStack>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Responsive capture/index.md
---

# Responsive capture

A family of `AVCapturePhotoOutput` switches that change how the capture pipeline behaves between shots. None of them change the photo _quality_ — they change _when_ you can take the next shot, and _how soon_ you get a usable image back from the current one.

***

## `isZeroShutterLagEnabled`

Builds a rolling buffer of recent frames so a tap captures the moment _just before_ the tap, not after. Most useful for action shots — kids, pets, sports.

- Defaults to `true` on devices where it's supported (iPhone XS / XR and newer).
- Set to `false` if you want strictly the moment of the tap (rare).

```ts
if (photoOutput.isZeroShutterLagSupported) {
  photoOutput.isZeroShutterLagEnabled = true
}
```

***

## `isResponsiveCaptureEnabled` + `isFastCapturePrioritizationEnabled`

These are a **pair**. They let the pipeline finish the current photo's processing in the background while the user keeps tapping.

**Order matters.** Apple gates `isFastCapturePrioritizationSupported` on `isResponsiveCaptureEnabled = true` (and `maxPhotoQualityPrioritization = "quality"`). So turn responsive on first — _then_ fast becomes supported.

```ts
photoOutput.maxPhotoQualityPrioritization = "quality"

if (photoOutput.isResponsiveCaptureSupported) {
  photoOutput.isResponsiveCaptureEnabled = true
}
// fastSupp only flips to true after the line above runs.
if (photoOutput.isFastCapturePrioritizationSupported) {
  photoOutput.isFastCapturePrioritizationEnabled = true
}
```

If you flip them out of order from JS, the bridge fixes it: setting `fast = true` first will turn `responsive` on if supported, and turning `responsive = false` first turns `fast` off. So this also works:

```ts
photoOutput.isFastCapturePrioritizationEnabled = true   // responsive gets auto-enabled
```

If `fastSupp` stays `false` even after `responsive` is on, the active format / preset doesn't allow it — fast is silently ignored. Common blockers: `maxPhotoQualityPrioritization` not `"quality"`, `isLivePhotoCaptureEnabled = true`, or a non-`photo` session preset.

***

## `isAutoDeferredPhotoDeliveryEnabled` (read this carefully)

Deferred Photo Delivery lets you tap the shutter again _immediately_, without waiting for the previous photo's full processing pipeline (Deep Fusion, Photonic Engine, Smart HDR) to finish. Apple does this by handing your app a "proxy" right away and finalizing the real photo asynchronously.

The catch — and the reason this section is much longer than the others — is that **the finalized photo never comes back through `capturePhoto()`**.

### What you actually get

When deferred kicks in, `capturePhoto()` resolves with:

```ts
{
  image: UIImage,         // ← this is the PROXY, not the final
  metadata: {...},
  isRawPhoto: false,
  isDeferredProxy: true,
}
```

The `image` is an _unfinished_ version of the photo: a quick render the system can produce in milliseconds. Visually it has more noise, less detail, and a weaker dynamic range than the final. It's perfectly fine for "show the user what they just shot" thumbnails, but it is **not the photo you want to keep**.

The system finalizes the real photo on its own clock — usually within seconds, but it can take longer if the device is busy or you've gone to background — and writes the result **directly to the user's Photo Library**. There is **no callback** into your app.

### So how do I get the final photo?

Use PhotoKit. Query the user's Photo Library for the most recent image after the proxy resolves:

```ts
photoOutput.isAutoDeferredPhotoDeliveryEnabled = true

const result = await photoOutput.capturePhoto()
if (result.isDeferredProxy) {
  // result.image is the proxy. Show it as a thumbnail.
  showThumbnail(result.image)
  // The final image will appear in the Photo Library on its own.
  // If your script needs it, you'll have to use Photo.getLastestPhotos or Photo.pickPhotos
}
```

### When _not_ to enable this

If your script wants the photo bytes immediately (for upload, processing, file save) and doesn't have or want Photo Library permission, **leave deferred off**. The default behavior — wait for the final, then resolve — is the right one for most scripts.

You'd opt in when:

- You're building a tap-many-photos-in-a-row UI and need quick feedback per shot
- You're already saving everything to the Photo Library anyway
- You'd rather show a less-perfect preview now than a spinner

***

## Detection cheat sheet

| Flag                                 | Min device                  |
| ------------------------------------ | --------------------------- |
| `isZeroShutterLagEnabled`            | iPhone XS / XR+             |
| `isResponsiveCaptureEnabled`         | iPhone 12+ (varies by lens) |
| `isFastCapturePrioritizationEnabled` | iPhone 12+                  |
| `isAutoDeferredPhotoDeliveryEnabled` | iPhone 11 Pro+              |



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Responsive capture/index_example.md
---

# Example

```tsx
import {
  Button, CaptureVideoPreviewView, HStack,
  Image, Navigation, NavigationStack, Script, Spacer, Text, Toggle,
  Toolbar, ToolbarItem, useEffect, useMemo, useObservable, VStack
} from "scripting"

type CaptureLog = {
  ms: number
  size: string
  isDeferredProxy: boolean
  index: number
}

function View() {
  const dismiss = Navigation.useDismiss()

  const isRunning = useObservable(false)
  const lastImage = useObservable<UIImage | null>(null)
  const log = useObservable<CaptureLog[]>([])
  const captureCount = useObservable(0)

  // 4 个响应性开关 + 一个能 / 不能控制的标记
  const supports = useObservable({
    zsl: false, resp: false, fast: false, defer: false,
  })

  // 用户当前的开关状态(不一定实际生效, 由 *Supported 决定)
  const zsl = useObservable(false)
  const resp = useObservable(false)
  const fast = useObservable(false)
  const defr = useObservable(false)

  const { session, camera, photoOutput } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)
    const photoOutput = new AVCapturePhotoOutput()
    photoOutput.maxPhotoQualityPrioritization = "quality"

    session.configure(() => {
      session.sessionPreset = "photo"
      if (session.canAddInput(input)) session.addInput(input)
      if (session.canAddOutput(photoOutput)) session.addOutput(photoOutput)
    })

    return { session, camera, photoOutput }
  }, [])

  // 把 supported + enabled 状态从 native 重新拉一遍, 并 log 一行方便观察状态机。
  // *Supported 不是常量: fastSupp 依赖 respEn=true, 所以切 resp 之后必须重读。
  function syncFromNative(label: string) {
    const snapshot = {
      zslSupp: photoOutput.isZeroShutterLagSupported,
      respSupp: photoOutput.isResponsiveCaptureSupported,
      fastSupp: photoOutput.isFastCapturePrioritizationSupported,
      deferSupp: photoOutput.isAutoDeferredPhotoDeliverySupported,
      zslEn: photoOutput.isZeroShutterLagEnabled,
      respEn: photoOutput.isResponsiveCaptureEnabled,
      fastEn: photoOutput.isFastCapturePrioritizationEnabled,
      deferEn: photoOutput.isAutoDeferredPhotoDeliveryEnabled,
    }
    supports.setValue({
      zsl: snapshot.zslSupp,
      resp: snapshot.respSupp,
      fast: snapshot.fastSupp,
      defer: snapshot.deferSupp,
    })
    zsl.setValue(snapshot.zslEn)
    resp.setValue(snapshot.respEn)
    fast.setValue(snapshot.fastEn)
    defr.setValue(snapshot.deferEn)
    console.log(`[${label}]`, snapshot)
  }

  useEffect(() => {
    async function start() {
      try {
        await session.startRunning()
        isRunning.setValue(true)
        // 启动后 *Supported 才反映真实硬件能力 + active format
        syncFromNative("startRunning")
      } catch (e) {
        await Dialog.alert({ message: `Failed to start: ${String(e)}` })
        dismiss()
      }
    }
    start()
    return () => {
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  function flipZSL(v: boolean) {
    photoOutput.isZeroShutterLagEnabled = v
    syncFromNative(`zsl=${v}`)
  }
  function flipResp(v: boolean) {
    // bridge 在 native 兜底:开 resp 不会自动开 fast(需要单独开);
    // 关 resp 时会先关 fast 保持状态一致。
    photoOutput.isResponsiveCaptureEnabled = v
    syncFromNative(`resp=${v}`)
  }
  function flipFast(v: boolean) {
    // 开 fast 时 bridge 自动把 resp 也开起来(fastSupp 依赖 respEn=true);
    // 关 fast 单独关。
    photoOutput.isFastCapturePrioritizationEnabled = v
    syncFromNative(`fast=${v}`)
  }
  function flipDefer(v: boolean) {
    photoOutput.isAutoDeferredPhotoDeliveryEnabled = v
    syncFromNative(`defer=${v}`)
  }

  async function takeShot() {
    const start = Date.now()
    try {
      const result = await photoOutput.capturePhoto({ codec: "hevc" })
      const ms = Date.now() - start
      const idx = captureCount.value + 1
      captureCount.setValue(idx)
      lastImage.setValue(result.image)
      log.setValue([
        {
          index: idx,
          ms,
          size: `${result.image.width}×${result.image.height}`,
          isDeferredProxy: result.isDeferredProxy,
        },
        ...log.value,
      ].slice(0, 8))
    } catch (e) {
      await Dialog.alert({ message: `capturePhoto failed: ${String(e)}` })
    }
  }

  /** 连拍 5 张, 测响应性体感 */
  async function burst5() {
    for (let i = 0; i < 5; i++) {
      // 不 await 确保连发(响应性开启时这是关键体感)
      takeShot()
    }
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="Responsive capture"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 280 }}
          cornerRadius={12}
          masksToBounds
        />

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Capability (read after startRunning)</Text>
          <Text font="footnote">
            zsl: {String(supports.value.zsl)} · resp: {String(supports.value.resp)} · fast: {String(supports.value.fast)} · defer: {String(supports.value.defer)}
          </Text>
        </VStack>

        <VStack alignment="leading" spacing={6} padding={8}>
          <Toggle
            title="Zero Shutter Lag"
            value={zsl.value}
            onChanged={flipZSL}
            disabled={!supports.value.zsl}
          />
          <Toggle
            title="Responsive Capture"
            value={resp.value}
            onChanged={flipResp}
            disabled={!supports.value.resp}
          />
          <Toggle
            title="Fast Capture Prioritization"
            value={fast.value}
            onChanged={flipFast}
            disabled={!supports.value.fast}
          />
          <Toggle
            title="Auto Deferred Photo Delivery"
            value={defr.value}
            onChanged={flipDefer}
            disabled={!supports.value.defer}
          />
        </VStack>

        <HStack padding={8} spacing={12}>
          <Button title="Single shot" action={takeShot} />
          <Button title="Burst × 5" action={burst5} />
          <Spacer />
          <Text font="footnote" foregroundStyle="secondaryLabel">
            shots: {captureCount.value}
          </Text>
        </HStack>

        {lastImage.value ? (
          <Image
            image={lastImage.value}
            resizable
            scaleToFit
            frame={{ height: 120 }}
          />
        ) : null}

        <VStack alignment="leading" spacing={2} padding={8}>
          <Text font="caption">Recent captures (newest first)</Text>
          {log.value.map(entry => (
            <Text key={entry.index} font="footnote">
              #{entry.index} · {entry.ms}ms · {entry.size}{entry.isDeferredProxy ? " · proxy" : ""}
            </Text>
          ))}
        </VStack>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Tap-to-focus, interruptions, stabilization/index.md
---

# 

***

title: Tap-to-focus, interruptions, stabilization
description: Three small but common controls: focus / exposure point of interest, session interruption notifications, and movie stabilization mode.

***

The three main things you need to worry about when using `AVCaptureSession` are:

- tap-to-focus and tap-to-meter (focus / exposure point of interest on the device)
- session interruption notifications (a phone call, another app grabbing the camera, system pressure)
- video stabilization on the movie output

These are all device / connection level — they don't change how you wire up inputs and outputs.

***

## Tap-to-focus / tap-to-meter

`AVCaptureDevice` exposes a focus point and an exposure point. Both are normalized to `0..1` of the **sensor frame** (not your preview view), with `(0, 0)` at the **top-left of the landscape-oriented sensor**. Most apps map a tap on the preview view into normalized sensor coordinates and then write both the focus point and the exposure point at once:

```ts
const camera = AVCaptureDevice.default("video")!

// Whenever the user taps the preview view, translate the tap into
// normalized sensor coords (your preview layer can do this for you in native;
// in JS you typically pre-compute once per layout).
function tap(at: { x: number; y: number }) {
  if (camera.isFocusPointOfInterestSupported) {
    camera.setFocusPointOfInterest(at)
    camera.setFocusMode("autoFocus")          // single-shot AF at that point
  }
  if (camera.isExposurePointOfInterestSupported) {
    camera.setExposurePointOfInterest(at)
    camera.setExposureMode("continuousAutoExposure")
  }
}
```

A few gotchas:

- `setFocusPointOfInterest` and `setExposurePointOfInterest` are silent no-ops on devices that don't support them — guard with the `is*Supported` flag if you want to surface that to the user.
- These setters acquire the device configuration lock internally; you don't need to wrap them in `lockForConfiguration()`.
- Setting only the point doesn't trigger a refocus — you also need a focus mode (`autoFocus` for one-shot, `continuousAutoFocus` for tracking) and / or an exposure mode change.

***

## Session interruptions

iOS will sometimes pull the camera out from under you: an incoming call, another app moving to the foreground with multi-app support, FaceTime taking the front camera, system thermal pressure. The session keeps running in the background but is paused — your preview will look frozen until iOS hands the hardware back.

Subscribe to know when this happens:

```ts
session.addInterruptionListener((event, reason) => {
  if (event === "began") {
    // Show a "camera unavailable" overlay.
    console.log("interrupted because:", reason)
  } else {
    // Hide the overlay; the session will resume on its own.
    console.log("interruption ended")
  }
})
```

`reason` is one of:

| Reason                                              | When it fires                                                      |
| --------------------------------------------------- | ------------------------------------------------------------------ |
| `videoDeviceNotAvailableInBackground`               | Your app went to the background                                    |
| `audioDeviceInUseByAnotherClient`                   | Another app holds the microphone (e.g. a phone call)               |
| `videoDeviceInUseByAnotherClient`                   | Another app holds the camera (e.g. FaceTime)                       |
| `videoDeviceNotAvailableWithMultipleForegroundApps` | iPad split-view took the camera away                               |
| `videoDeviceNotAvailableDueToSystemPressure`        | Device is too hot or low on resources                              |
| `sensitiveContentMitigationActivated`               | System content blur is engaged                                     |
| `unknown`                                           | New reason added in a future iOS that this build doesn't recognize |

`event === "ended"` always passes an empty string — there is no "reason" for the resume.

You don't need to call `startRunning()` again after `"ended"`. The session resumes automatically.

***

## Video stabilization

The system can apply optical / sensor stabilization on the recorded video. You set a _preferred_ mode on the movie output's video connection — the system decides whether to actually activate it based on the active format and device capability. Always read back the active mode if you want to know what's really happening.

```ts
const movieOutput = new AVCaptureMovieFileOutput()
session.addOutput(movieOutput)

// Pick one before you start recording.
movieOutput.setVideoStabilizationMode("auto")

// After startRunning(), this reflects what the system actually picked:
console.log("active stabilization:", movieOutput.videoStabilizationMode)
```

| Mode                | Notes                                                   |
| ------------------- | ------------------------------------------------------- |
| `off`               | No stabilization.                                       |
| `standard`          | Conservative; good general-purpose default.             |
| `cinematic`         | Heavier crop, smoother result; more processing cost.    |
| `cinematicExtended` | Even heavier crop, designed for handheld walking shots. |
| `auto`              | Let iOS pick based on movement and lighting.            |

Notes:

- Stabilization is applied per **connection**, not per session. If you swap the device-input or rebuild the connection, you need to set the mode again.
- `setVideoStabilizationMode("...")` returns `false` if the movie output isn't attached to a session yet (no video connection exists). Set the mode after `session.addOutput(movieOutput)`.
- Throwing happens only on an unknown mode string — a misspell will surface immediately.
- `videoStabilizationMode` is **active**, not requested. The system may downgrade or disable it silently if the active format doesn't support it.

## Pause / resume and recording progress

A movie recording can be paused and resumed without producing a new file. Both calls are safe no-ops if you call them out of state, and on iOS below 18 (where `isRecordingPaused` is always `false`).

```ts
await movieOutput.startRecording(filePath)

movieOutput.pauseRecording()
console.log(movieOutput.isRecordingPaused)   // true
movieOutput.resumeRecording()

// Live progress while recording:
console.log("seconds:", movieOutput.recordedDuration)
console.log("bytes:", movieOutput.recordedFileSize)

const path = await movieOutput.stopRecording()  // the promise from startRecording resolves here
```

`recordedDuration` (seconds) and `recordedFileSize` (bytes) reflect the current recording and return `0` when not recording. Query `availableVideoCodecTypes` for the codecs the output can record (native raw values such as `"hvc1"` / `"avc1"`).



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/Tap-to-focus, interruptions, stabilization/index_example.md
---

# 

***

title: Example
description: Three small but common controls: focus / exposure point of interest, session interruption notifications, and movie stabilization mode.

***

```tsx
import {
  Button, CaptureVideoPreviewView, HStack, Menu, Navigation, NavigationStack,
  Picker, Script, Spacer, Text, Toolbar, ToolbarItem,
  useEffect, useMemo, useObservable, VStack
} from "scripting"

const STAB_MODES = ["off", "standard", "cinematic", "cinematicExtended", "auto"] as const
type StabMode = typeof STAB_MODES[number]

const POI_PRESETS: { label: string; point: { x: number; y: number } }[] = [
  { label: "Center", point: { x: 0.5, y: 0.5 } },
  { label: "Top-L", point: { x: 0.2, y: 0.2 } },
  { label: "Top-R", point: { x: 0.8, y: 0.2 } },
  { label: "Bot-L", point: { x: 0.2, y: 0.8 } },
  { label: "Bot-R", point: { x: 0.8, y: 0.8 } },
]

function View() {
  const dismiss = Navigation.useDismiss()

  const isRunning = useObservable(false)
  const interruption = useObservable("—")
  const lastPOI = useObservable("—")
  const activeStabilization = useObservable("off")
  const recording = useObservable(false)
  const paused = useObservable(false)
  const progress = useObservable("—")
  const recordedFile = useObservable("")
  const stabMode = useObservable<StabMode>("auto")

  // 录制进度计时器句柄(稳定引用,跨 render 不重建)。
  const timer = useMemo<{ id: number | null }>(() => ({ id: null }), [])

  const { session, camera, movieOutput } = useMemo(() => {
    const camera = AVCaptureDevice.default("video")!
    const session = new AVCaptureSession()
    const input = new AVCaptureDeviceInput(camera)
    const movieOutput = new AVCaptureMovieFileOutput()

    session.configure(() => {
      session.sessionPreset = "high"
      if (session.canAddInput(input)) session.addInput(input)
      if (session.canAddOutput(movieOutput)) session.addOutput(movieOutput)
    })

    return { session, camera, movieOutput }
  }, [])

  // 中断监听
  useEffect(() => {
    session.addInterruptionListener((event, reason) => {
      if (event === "began") {
        interruption.setValue(`began · ${reason || "unknown"}`)
      } else {
        interruption.setValue("ended")
      }
    })
  }, [])

  // 启动 session + 初始稳定化
  useEffect(() => {
    async function start() {
      try {
        await session.startRunning()
        isRunning.setValue(true)
        // session.addOutput 之后 movieOutput 才有 video connection
        movieOutput.setVideoStabilizationMode(stabMode.value)
        activeStabilization.setValue(movieOutput.videoStabilizationMode)
        // 新增 API:可录制 codec 列表 + connections
        console.log("availableVideoCodecTypes:", movieOutput.availableVideoCodecTypes.join(", "))
        console.log("movieOutput connections:", movieOutput.connections.length)
      } catch (e) {
        await Dialog.alert({ message: `Failed to start: ${String(e)}` })
        dismiss()
      }
    }
    start()
    return () => {
      stopProgressTimer()
      session.stopRunning().finally(() => session.dispose())
    }
  }, [])

  function applyPOI(p: { x: number; y: number }) {
    let did = false
    if (camera.isFocusPointOfInterestSupported) {
      camera.setFocusPointOfInterest(p)
      camera.setFocusMode("autoFocus")
      did = true
    }
    if (camera.isExposurePointOfInterestSupported) {
      camera.setExposurePointOfInterest(p)
      camera.setExposureMode("continuousAutoExposure")
      did = true
    }
    lastPOI.setValue(
      did
        ? `(${p.x.toFixed(2)}, ${p.y.toFixed(2)})`
        : "device does not support POI"
    )
  }

  function chooseStabilization(mode: StabMode) {
    stabMode.setValue(mode)
    const ok = movieOutput.setVideoStabilizationMode(mode)
    if (!ok) {
      lastPOI.setValue("setVideoStabilizationMode → false (no video connection?)")
      return
    }
    // active 在 startRunning 后由系统决定; 这里多读几次让 UI 反映现实
    activeStabilization.setValue(movieOutput.videoStabilizationMode)
  }

  function stopProgressTimer() {
    if (timer.id != null) {
      clearTimeout(timer.id)
      timer.id = null
    }
  }

  // 自递归 setTimeout(脚本环境只保证 setTimeout/clearTimeout)。每 0.5s 读一次
  // 新增的录制进度 API:recordedDuration / recordedFileSize / isRecordingPaused。
  function tickProgress() {
    const secs = movieOutput.recordedDuration.toFixed(1)
    const kb = (movieOutput.recordedFileSize / 1024).toFixed(0)
    progress.setValue(`${secs}s · ${kb} KB${movieOutput.isRecordingPaused ? " · paused" : ""}`)
    if (recording.value) {
      timer.id = setTimeout(tickProgress, 500)
    }
  }

  async function toggleRecording() {
    if (recording.value) {
      await movieOutput.stopRecording()
      return
    }
    try {
      const path = `${FileManager.documentsDirectory}/session_control_clip.mov`
      try { FileManager.removeSync(path) } catch { }
      recording.setValue(true)
      paused.setValue(false)
      timer.id = setTimeout(tickProgress, 500)
      const finalPath = await movieOutput.startRecording(path)
      recordedFile.setValue(finalPath)
      // 录制结束后 active 可能与录制中不同, 再读一次
      activeStabilization.setValue(movieOutput.videoStabilizationMode)
    } catch (e) {
      await Dialog.alert({ message: `Recording failed: ${String(e)}` })
    } finally {
      stopProgressTimer()
      recording.setValue(false)
      paused.setValue(false)
    }
  }

  // 新增 API:暂停 / 恢复当前录制(iOS 18+;更早系统是 no-op)。
  function togglePause() {
    if (!recording.value) return
    if (movieOutput.isRecordingPaused) {
      movieOutput.resumeRecording()
    } else {
      movieOutput.pauseRecording()
    }
    paused.setValue(movieOutput.isRecordingPaused)
  }

  return (
    <NavigationStack>
      <VStack
        navigationTitle="PR A · session control"
        toolbar={
          <Toolbar>
            <ToolbarItem placement="topBarTrailing">
              <Button title="Done" systemImage="xmark" action={dismiss} />
            </ToolbarItem>
          </Toolbar>
        }
      >
        <CaptureVideoPreviewView
          session={session}
          videoDevice={camera}
          videoGravity="resizeAspectFill"
          frame={{ height: 360 }}
          cornerRadius={12}
          masksToBounds
        />

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Status</Text>
          <Text font="footnote">
            running: {String(isRunning.value)} · stabilization (active): {activeStabilization.value}
          </Text>
          <Text font="footnote">interruption: {interruption.value}</Text>
          <Text font="footnote">last POI: {lastPOI.value}</Text>
          <Text font="footnote">recording progress: {progress.value}</Text>
          {recordedFile.value ? (
            <Text font="footnote" foregroundStyle="secondaryLabel">
              saved → {recordedFile.value}
            </Text>
          ) : null}
        </VStack>

        <VStack alignment="leading" spacing={4} padding={8}>
          <Text font="caption">Tap-to-focus presets</Text>
          <HStack spacing={6}>
            {POI_PRESETS.map(p => (
              <Button
                key={p.label}
                title={p.label}
                action={() => applyPOI(p.point)}
              />
            ))}
          </HStack>
        </VStack>

        <HStack padding={8}>
          <Text font="caption">Stabilization</Text>
          <Spacer />
          <Menu title={stabMode.value}>
            <Picker
              title="Stabilization"
              value={stabMode.value}
              onChanged={(v: string) => chooseStabilization(v as StabMode)}
            >
              {STAB_MODES.map(m => (
                <Text key={m} tag={m}>{m}</Text>
              ))}
            </Picker>
          </Menu>
        </HStack>

        <HStack padding={8}>
          <Button
            title={recording.value ? "Stop recording" : "Start recording"}
            action={toggleRecording}
          />
          <Button
            title={paused.value ? "Resume" : "Pause"}
            action={togglePause}
            disabled={!recording.value}
          />
          <Spacer />
          <Text font="footnote" foregroundStyle="secondaryLabel">
            Tip: ⌘+H (simulator: Hardware → Home) triggers a background interruption.
          </Text>
        </HStack>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <View /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/AVCaptureSession & Camera Control/VideoRecorder vs AVCaptureSession.md
---

# VideoRecorder vs AVCaptureSession

Scripting ships two camera APIs that overlap intentionally. Pick the one that matches the shape of your problem.

## TL;DR

| You want to...                                                        | Use                                            |
| --------------------------------------------------------------------- | ---------------------------------------------- |
| Press record → save mp4                                               | `VideoRecorder`                                |
| Pause / resume during a single clip                                   | `VideoRecorder`                                |
| Built-in audio session, orientation, encoder, file management         | `VideoRecorder`                                |
| Scan QR / barcodes from live frames                                   | `AVCaptureSession` + `AVCaptureMetadataOutput` |
| Custom photo capture (HEVC, flash, Live Photo)                        | `AVCaptureSession` + `AVCapturePhotoOutput`    |
| Bind iPhone 16 Camera Control sliders / pickers                       | `AVCaptureSession` + `AVCaptureControl`        |
| Multiple outputs in one session (photo + movie + metadata)            | `AVCaptureSession`                             |
| Read raw `CMSampleBuffer` / `CVPixelBuffer` (future, not yet exposed) | `AVCaptureSession`                             |

## Concrete differences

`VideoRecorder` is a stateful singleton. It owns one capture session, one writer, one audio session, and a strict state machine (`idle → preparing → ready → recording → ...`). Most apps need exactly that. The trade-off: you cannot run two clips in parallel, attach extra outputs, or change the pipeline mid-flight.

`AVCaptureSession` is plain AVFoundation. Each instance is independent. You can construct multiple sessions, but only one will actually have access to the camera at any given moment — the OS arbitrates that.

If you start an `AVCaptureSession` while `VideoRecorder` is recording (or vice versa) you will get a runtime error from the second consumer. Build your UI to make these mutually exclusive — typically by deciding once at the top of the page which API to use.

## Migrating an existing VideoRecorder use case

Most VideoRecorder users do **not** need to migrate. Migrate if you find yourself:

- Calling `VideoRecorder.session` and reaching into AVFoundation by hand.
- Working around the state machine (e.g. wanting `recording` and `paused` to be flipped over multiple files).
- Needing `AVCaptureMetadataOutput` (QR scanning while recording).

Migration is a per-feature port: enumerate the device with `AVCaptureDevice`, wrap it with `AVCaptureDeviceInput`, attach `AVCaptureMovieFileOutput`, and replace state-listener calls with explicit promise chaining. See the `Quick Start` for the full pattern.

## Both at once

You **can** instantiate `AVCaptureSession` while `VideoRecorder` is `idle`. Just make sure to:

1. Call `await VideoRecorder.reset()` first if it was used earlier in the same script.
2. Call `await session.stopRunning(); session.dispose()` before letting the script return control to the user.



---
url: /guide/Device Capabilities/AVMetadataItem.md
---

# AVMetadataItem

The `AVMetadataItem` class represents a single metadata entry within a media file, such as an audio or video resource.
Instances of this class are typically returned by the methods `AVPlayer.loadMetadata()` and `AVPlayer.loadCommonMetadata()` and provide access to metadata embedded in media resources.

Each metadata item describes one piece of information—such as the title, artist, album name, artwork, or encoding details—and can be accessed in multiple typed forms.

***

## Class Definition

### `class AVMetadataItem`

***

### **Properties**

#### `key: string`

The metadata item’s key.
This value identifies the specific metadata field and is usually tied to the underlying media format (e.g., ID3, QuickTime, iTunes).

**Example**

```ts
console.log(item.key) // e.g. "id3/TIT2"
```

***

#### `commonKey?: string`

The **common key** corresponding to the metadata item.
This key maps the format-specific `key` to a general, standardized key within the “common key space.”
It allows accessing metadata fields across different media formats in a unified way.

**Example**

```ts
console.log(item.commonKey) // e.g. "title"
```

***

#### `identifier?: string`

A unique identifier for the metadata item.
Used to distinguish multiple entries of the same type.

***

#### `extendedLanguageTag?: string`

The extended language tag of the metadata item (e.g., `"en-US"` or `"zh-Hans"`).
Indicates the language of the metadata content, if applicable.

***

#### `locale?: string`

The locale associated with this metadata item.
This may contain additional region or language localization information.

***

#### `time?: number`

The timestamp (in seconds) of the metadata item within the media’s timeline.
Useful for time-based metadata, such as subtitles or synchronized lyrics.

**Example**

```ts
console.log(item.time) // e.g. 12.53
```

***

#### `duration?: number`

The duration (in seconds) that this metadata item applies to.
Some visual metadata (such as timed artwork or lyric frames) may have an active duration.

***

#### `startDate?: Date`

The start date of the metadata item, if available.
Returns `null` when no date information is provided.

***

#### `dataType?: string`

The data type of the metadata item’s value (e.g., `"com.apple.metadata.datatype.UTF-8"`, `"public.jpeg"`).
This can help determine how to interpret the metadata’s underlying data.

***

#### `extraAttributes: Promise<Record<string, any> | null>`

Extra attributes associated with the metadata item.
These attributes are format-specific and depend on the metadata container and keyspace.

For example, an ID3 tag’s `"APIC"` frame (attached picture) may include a picture description or type.

**Example**

```ts
const extras = await item.extraAttributes
console.log(extras)
// Example output: { description: "Cover (front)", pictureType: 3 }
```

***

#### `dataValue: Promise<Data | null>`

Returns the metadata value as a `Data` object.
Useful for binary content such as embedded artwork or other non-text data.

**Example**

```ts
const imageData = await item.dataValue
if (imageData) {
  const image = UIImage.fromData(imageData)
  // Use image
}
```

***

#### `stringValue: Promise<string | null>`

Returns the metadata value as a `string`.
This is the most common form for textual metadata such as titles, artists, and album names.

**Example**

```ts
const title = await item.stringValue
console.log("Title:", title)
```

***

#### `numberValue: Promise<number | null>`

Returns the metadata value as a `number`.
Useful for numeric fields such as bitrate, sample rate, or track number.

**Example**

```ts
const bitrate = await item.numberValue
console.log("Bitrate:", bitrate)
```

***

#### `dateValue: Promise<Date | null>`

Returns the metadata value as a `Date` object.
Applicable to time-related metadata such as recording or release dates.

**Example**

```ts
const date = await item.dateValue
console.log("Release Date:", date?.toISOString())
```

***

## Example Usage

```ts
const metadata = await player.loadMetadata()
for (const item of metadata) {
  const key = item.commonKey ?? item.key
  const value =
    (await item.stringValue) ??
    (await item.numberValue) ??
    (await item.dateValue)
  console.log(`${key}: ${value}`)
}
```

**Notes:**

- Prefer using `commonKey` when available for format-agnostic access.
- Asynchronous properties (`stringValue`, `dataValue`, `extraAttributes`) return Promises and should be awaited.
- Use `AVPlayer.loadCommonMetadata()` for standardized metadata fields such as title, album, artist, and artwork.

***

## Common Use Cases

| Purpose       | Common Key (`commonKey`) | Description                         |
| ------------- | ------------------------ | ----------------------------------- |
| Title         | `"title"`                | The media’s title                   |
| Artist        | `"artist"`               | The performer or author             |
| Album         | `"albumName"`            | The album name                      |
| Artwork       | `"artwork"`              | Embedded artwork image (JPEG/PNG)   |
| Encoder       | `"encoder"`              | The software or encoder used        |
| Creation Date | `"creationDate"`         | The recording or creation timestamp |



---
url: /guide/Device Capabilities/AVPlayer.md
---

# AVPlayer

`AVPlayer` provides audio and video playback capabilities, including playback control, rate control, looping, playback state observation, and media metadata loading.

You set a media source using `setSource()` (local file or remote URL), then start playback using `play()`.

***

## Getting Started

```ts
const player = new AVPlayer()

if (player.setSource("https://example.com/audio.mp3")) {
  player.onReadyToPlay = () => {
    player.play()
  }

  player.onEnded = () => {
    console.log("Playback finished")
  }
} else {
  console.error("Failed to set media source")
}
```

***

## API Reference

### Properties

#### `volume: number`

Controls the playback volume.
Range: `0.0` (muted) to `1.0` (maximum).

```ts
player.volume = 0.5
```

***

#### `duration: DurationInSeconds`

The total duration of the media in seconds.
This value is `0` until the media has finished loading.

```ts
console.log(player.duration)
```

***

#### `currentTime: DurationInSeconds`

The current playback position in seconds.
You can assign a value to seek to a specific time.

```ts
player.currentTime = 30
```

***

#### `rate: number`

The **current playback rate**.

- `1.0` = normal speed
- `< 1.0` = slower playback
- `> 1.0` = faster playback

This property reflects the actual playback speed while playing.

```ts
player.rate = 1.25
```

***

#### `defaultRate: number`

The **default playback rate used when playback starts**.

- Used when calling `play()` **without** specifying `atRate`
- Changing `defaultRate` does **not** immediately affect an ongoing playback
- Primarily intended to control the rate for the _next_ playback start

```ts
player.defaultRate = 1.5
```

Typical use cases:

- The user selects a preferred playback speed before pressing play
- Playback automatically starts at that speed next time `play()` is called

***

#### `timeControlStatus: TimeControlStatus`

Indicates the current playback state:

- `paused`
  Playback is paused or has not started
- `waitingToPlayAtSpecifiedRate`
  Waiting for playback conditions (e.g. buffering, network)
- `playing`
  Playback is in progress

***

#### `numberOfLoops: number`

Controls how many times the media will loop:

- `0`: no looping
- positive value: loop a specific number of times
- negative value: loop indefinitely

```ts
player.numberOfLoops = -1
```

***

### Methods

#### `setSource(filePathOrURL: string): boolean`

Sets the media source for playback.

Supports:

- Local file paths
- Remote URLs

Returns:

- `true` if the source was set successfully
- `false` if it failed

***

#### `play(atRate?: number): boolean`

Starts playback of the current media.

Playback rate resolution order:

1. If `atRate` is provided, playback starts at that rate
2. Otherwise, `defaultRate` is used

During playback, you can still modify `rate` dynamically.

```ts
player.play()        // Uses defaultRate
player.play(1.25)    // Starts playback at 1.25× speed
```

Returns:

- `true` if playback started successfully
- `false` otherwise

***

#### `pause()`

Pauses playback.

***

#### `stop()`

Stops playback and resets the position to the beginning.

***

#### `dispose()`

Releases all player resources and removes internal observers.
Must be called when the player is no longer needed to avoid resource leaks.

***

#### `loadMetadata(): Promise<AVMetadataItem[] | null>`

Loads the full metadata of the current media.

Returns:

- An array of `AVMetadataItem`
- `null` if no source is set or metadata is unavailable

```ts
const metadata = await player.loadMetadata()
```

***

#### `loadCommonMetadata(): Promise<AVMetadataItem[] | null>`

Loads the _common metadata_ of the current media.

Common metadata provides format-independent `commonKey` values, typically used for title, artist, album, etc.

```ts
const common = await player.loadCommonMetadata()
```

***

### Callbacks

#### `onReadyToPlay?: () => void`

Called when the media is ready for playback.

***

#### `onTimeControlStatusChanged?: (status: TimeControlStatus) => void`

Called whenever the playback state changes, such as:

- waiting → playing
- playing → paused

***

#### `onEnded?: () => void`

Called when playback finishes.

***

#### `onError?: (message: string) => void`

Called when a playback error occurs.
Receives a descriptive error message.

***

## Audio Session Notes

`AVPlayer` relies on the system’s shared audio session.
You should configure and activate it before playback.

```ts
await SharedAudioSession.setCategory('playback', ['mixWithOthers'])
await SharedAudioSession.setActive(true)
```

Handling interruptions (e.g. phone calls):

```ts
SharedAudioSession.addInterruptionListener(type => {
  if (type === 'began') {
    player.pause()
  } else if (type === 'ended') {
    player.play()
  }
})
```

***

## Common Usage Examples

### Play Using the Default Rate

```ts
player.defaultRate = 1.5
player.play()
```

***

### Start Playback at a Specific Rate

```ts
player.play(2.0)
```

***

### Loop Playback

```ts
player.numberOfLoops = 3
player.play()
```

***

### Read Common Metadata

```ts
const metadata = await player.loadCommonMetadata()
if (metadata) {
  const title = metadata.find(i => i.commonKey === 'title')
  console.log(await title?.stringValue)
}
```

***

## Best Practices

1. **Differentiate `defaultRate` vs `rate`**

   - `defaultRate` affects how playback _starts_
   - `rate` reflects or controls the _current_ playback speed

2. **Always Release Resources**

   - Call `dispose()` when playback ends or the player is no longer needed

3. **Observe Playback State**

   - Use `onTimeControlStatusChanged` to update loading or playing UI states

4. **Configure Audio Session Before Playing**

   - Prevent unexpected background, mute, or mixing behavior

5. **Metadata Timing**

   - Reading metadata after `onReadyToPlay` is more reliable

***

## Full Example

```ts
const player = new AVPlayer()

await SharedAudioSession.setCategory('playback', ['mixWithOthers'])
await SharedAudioSession.setActive(true)

player.defaultRate = 1.25

if (player.setSource("https://example.com/audio.mp3")) {
  player.onReadyToPlay = () => {
    player.play()
  }

  player.onEnded = () => {
    console.log("Playback finished")
    player.dispose()
  }

  player.onError = message => {
    console.error("Playback error:", message)
    player.dispose()
  }

  const metadata = await player.loadCommonMetadata()
  if (metadata) {
    const title = metadata.find(i => i.commonKey === 'title')
    console.log("Title:", await title?.stringValue)
  }
}
```



---
url: /guide/Device Capabilities/AppStore.md
---

# AppStore

The `AppStore` API allows you to display App Store app information **directly inside the Scripting app**, without navigating users away to the system App Store application.

This API is built on top of Apple’s native App Store presentation components and is suitable for scenarios such as **app recommendations, app collections, related app discovery, and ecosystem entry points**.

***

## Namespace: `AppStore`

```ts
namespace AppStore
```

***

## Overview

- Present an App Store product page inside the Scripting app using a **modal view**
- Users can view app details, screenshots, ratings, and release notes
- Users can **download, update, or open** the app directly
- Automatically returns to the current script UI after dismissal
- Does not launch or switch to the system App Store app

***

## API Summary

| Method                   | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| `presentApp(id: string)` | Presents an App Store product page for the specified app |
| `dismissApp()`           | Dismisses the currently presented App Store page         |

***

## API Reference

### `presentApp(id: string): Promise<void>`

Presents the App Store product page for a specific app inside the Scripting app.

#### Parameters

| Name | Type     | Description                               |
| ---- | -------- | ----------------------------------------- |
| `id` | `string` | The **App Store app identifier (App ID)** |

- The App ID is the numeric identifier used by the App Store
- It can be extracted from an App Store URL
  Example:
  `https://apps.apple.com/app/id123456789`
  The ID is `"123456789"`

#### Return Value

- Returns a `Promise<void>`
- The promise resolves when the App Store modal is dismissed
- Throws an error if another App Store modal is already presented

#### Behavior

- Presents the App Store page as a modal view
- Only **one App Store modal** can be active at a time
- Calling `presentApp` again while one is already open will result in an error

#### Example

```ts
await AppStore.presentApp("123456789")
```

***

### `dismissApp(): Promise<void>`

Dismisses the App Store modal that was opened using `presentApp`.

#### Return Value

- Returns a `Promise<void>`
- Resolves when the modal has been successfully dismissed

#### Usage Notes

- In most cases, manual dismissal is not required
- Useful when:

  - Implementing custom UI-driven dismissal logic
  - Closing the App Store page at a specific point in a script’s workflow

#### Example

```ts
await AppStore.dismissApp()
```

***

## Usage Examples

### Example 1: App Recommendation Entry

```ts
import { Button } from "scripting"

function AppRecommendation() {
  return (
    <Button
      title="View Recommended App"
      action={() => {
        AppStore.presentApp("123456789")
      }}
    />
  )
}
```

***

### Example 2: App Collection / Favorites

```ts
const favoriteApps = [
  { name: "App A", id: "123456789" },
  { name: "App B", id: "987654321" }
]

function AppList() {
  return favoriteApps.map(app => (
    <Button
      title={app.name}
      action={() => {
        AppStore.presentApp(app.id)
      }}
    />
  ))
}
```

***

## Errors and Considerations

### Common Errors

- **An App Store modal is already presented**

  - Calling `presentApp` again will throw an error
  - Ensure your logic prevents duplicate presentations

### Limitations

- Only App Store app product pages are supported
- Subscription pages, developer profiles, and other App Store sections are not supported
- The provided App ID must be valid and publicly available on the App Store



---
url: /guide/Device Capabilities/AudioRecorder.md
---

# AudioRecorder

The `AudioRecorder` class allows you to record audio data to a file. It provides functionalities to start, stop, pause, and manage audio recordings, with configurable settings for audio quality, sample rate, format, and more.

## Features

- Record audio from the system’s active input device.
- Record for a specified duration or until manually stopped.
- Pause and resume recordings.
- Delete recorded audio files.

## Usage

### Setup SharedAudioSesion

Before create an AudioRecorder instance, we need to setup the `SharedAudioSession`, the audio session is hardware-related and should be properly activated.

```ts
await SharedAudioSession.setActive(true)
await SharedAudioSession.setCategory(
  "playAndRecord",
  ["defaultToSpeaker"]
)
```

### Creating an AudioRecorder Instance

To create an audio recorder, use the `create` method:

```ts
async function createRecorder() {
  try {
    const filePath = Path.join(
      FileManager.documentsDirectory,
      "recording.m4a"
    )
    const recorder = await AudioRecorder.create(filePath, {
      format: "MPEG4AAC",
      sampleRate: 44100,
      numberOfChannels: 2,
      encoderAudioQuality: AVAudioQuality.high
    })
    return recorder
  } catch (error) {
    console.error("Failed to create recorder: ", error)
  }
}
```

### Recording Audio

You can start recording using the `record()` method:

```ts
async function startRecording() {
  const recorder = await createRecorder()
  if (recorder) {
    const success = recorder.record()
    console.log("Recording started: ", success)
  }
}
```

You can also provide options to control when to start recording and for how long:

```ts
function startSynchronizedRecording(recorderOne, recorderTwo) {
  let timeOffset = recorderOne.deviceCurrentTime + 0.01
  
  // Synchronize the recording time of both recorders.
  recorderOne.record({ atTime: timeOffset })
  recorderTwo.record({ atTime: timeOffset })
}
```

### Pausing and Stopping the Recording

To pause a recording:

```ts
function pauseRecording(recorder) {
  recorder.pause()
  console.log("Recording paused.")
}
```

To stop a recording:

```ts
function stopRecording(recorder) {
  recorder.stop()
  console.log("Recording stopped.")
}
```

### Deleting a Recording

To delete the recorded file:

```ts
function deleteRecording(recorder) {
  const success = recorder.deleteRecording()
  console.log("Recording deleted: ", success)
}
```

### Disposing of the Recorder

You should call `dispose()` when the recorder is no longer needed to free up resources:

```ts
function disposeRecorder(recorder) {
  recorder.dispose()
  console.log("Recorder disposed.")
}
```

### Event Handling

You can use the `onFinish` and `onError` callbacks to handle recording completion and errors:

```ts
async function setupRecorder() {
  const recorder = await createRecorder()
  if (recorder) {
    recorder.onFinish = (success) => {
      console.log("Recording finished successfully: ", success)
    }

    recorder.onError = (message) => {
      console.error("Recording error: ", message)
    }
  }
}
```

### Level Metering (VU meter / volume bar)

`AudioRecorder` can report the average and peak power of the input signal in
dBFS while recording, without exposing raw PCM samples. This is enough to
drive a VU meter or trigger logic on loudness.

Enable metering when creating the recorder, or by setting `meteringEnabled`
before calling `record()`:

```ts
const recorder = await AudioRecorder.create(filePath, {
  format: "MPEG4AAC",
  sampleRate: 44100,
  numberOfChannels: 1,
  meteringEnabled: true,
  // Optional: how often onLevelUpdate fires while recording.
  // In milliseconds, clamped to [16, 1000]. Default 50.
  levelUpdateInterval: 50,
})

recorder.onLevelUpdate = (level) => {
  // level.averagePower / level.peakPower are in dBFS, roughly [-160, 0].
  // Map to a 0..1 bar with something like:
  const norm = Math.max(0, (level.averagePower + 60) / 60)
  console.log(`avg=${level.averagePower.toFixed(1)} dB peak=${level.peakPower.toFixed(1)} dB`)
}

recorder.record()
```

You can also poll the meter manually instead of using the callback:

```ts
recorder.meteringEnabled = true
recorder.record()

setInterval(() => {
  recorder.updateMeters()
  const avg = recorder.averagePower(0)
  const peak = recorder.peakPower(0)
  console.log(`channel 0 → avg=${avg} peak=${peak}`)
}, 100)
```

The level timer stops automatically on `pause()` / `stop()` / `dispose()`
and resumes on the next `record()` while `onLevelUpdate` is set.

> If you need raw PCM samples, real-time waveform data, or pitch
> detection, use the `AudioCapture` class instead.
> `AudioRecorder` is optimized for writing encoded audio files
> (m4a / aac / flac / opus / mp3 / wav).

## API Reference

### `AudioRecorder.create(filePath, settings?)`

Creates an `AudioRecorder` instance with specified settings.

- **filePath** (string): The file system location to record to.
- **settings** (optional object): The audio settings for the recording:
  - **format** (AudioFormat): The format of the audio data. Options: "LinearPCM", "MPEG4AAC", "AppleLossless", "AppleIMA4", "iLBC", "ULaw".
  - **sampleRate** (number): The sample rate in hertz (8000 to 192000).
  - **numberOfChannels** (number): The number of channels (1 to 64).
  - **encoderAudioQuality** (AVAudioQuality): The quality of the audio encoding (from `AVAudioQuality.min` to `AVAudioQuality.max`).

Returns: A `Promise` that resolves with an `AudioRecorder` instance.

### `AudioRecorder.isRecording`

A  boolean indicating whether the recorder is recording.

### `AudioRecorder.currentTime`

The time, in seconds, since the beginning of the recording.

### `AudioRecorder.deviceCurrentTime`

The current time of the host audio device, in seconds.

### `AudioRecorder.record(options?)`

Starts recording audio.

- **options** (optional object): Recording options:
  - **atTime** (number): The time at which to start recording, relative to `deviceCurrentTime`.
  - **duration** (number): The duration of the recording, in seconds.

Returns: A boolean indicating whether recording started successfully.

### `AudioRecorder.pause()`

Pauses the current recording.

### `AudioRecorder.stop()`

Stops recording and closes the audio file.

### `AudioRecorder.deleteRecording()`

Deletes the recorded audio file.

Returns: A boolean indicating whether the deletion was successful.

### `AudioRecorder.dispose()`

Releases resources used by the recorder.

### `AudioRecorder.onFinish`

Callback function invoked when the recording finishes.

- **success** (boolean): Indicates whether the recording finished successfully.

### `AudioRecorder.onError`

Callback function invoked when an encoding error occurs.

- **message** (string): Describes the error.

### `AudioRecorder.meteringEnabled`

Whether level metering is enabled. Toggle before `record()` (or pass
`meteringEnabled: true` to `create`) so that `averagePower`, `peakPower`,
and `onLevelUpdate` report values.

### `AudioRecorder.levelUpdateInterval`

Sampling interval in milliseconds used by `onLevelUpdate`. Clamped to
`[16, 1000]`. Default `50`.

### `AudioRecorder.updateMeters()`

Refreshes the meter values. Call before reading `averagePower` /
`peakPower` if you do not use `onLevelUpdate`.

### `AudioRecorder.averagePower(channel?)`

Returns the average power for the given channel in dBFS, range roughly
`[-160, 0]`. Returns `0` when metering is disabled or the recorder is not
running.

- **channel** (number, optional): Zero-based channel index. Defaults to `0`.

### `AudioRecorder.peakPower(channel?)`

Returns the peak hold power for the given channel in dBFS.

### `AudioRecorder.onLevelUpdate`

Callback invoked while recording at `levelUpdateInterval` cadence when
`meteringEnabled` is `true`.

- **level.averagePower** (number): Average power in dBFS, averaged across channels.
- **level.peakPower** (number): Peak power in dBFS, averaged across channels.
- **level.channels** (`{ average; peak }[]`): Per-channel values.
- **level.timestamp** (number): `deviceCurrentTime` when the sample was taken, in seconds.

## Example Usage

```ts
import { Path } from 'scripting'

async function run() {

  await SharedAudioSession.setActive(true)
  await SharedAudioSession.setCategory(
    "playAndRecord",
    ["defaultToSpeaker"]
  )

  try {
    const filePath = Path.join(
      FileManager.documentsDirectory,
      "recording.m4a"
    )
    const recorder = await AudioRecorder.create(filePath, {
      format: "MPEG4AAC",
      sampleRate: 48000,
      numberOfChannels: 2,
      encoderAudioQuality: AVAudioQuality.high
    })

    recorder.onFinish = (success) => console.log("Recording finished successfully: ", success)
    recorder.onError = (message) => console.error("Recording error: ", message)

    recorder.record()
    setTimeout(() => {
      recorder.stop()
    }, 5000) // Stop recording after 5 seconds
  } catch (error) {
    console.error("Error: ", String(error))
  }
}

run()
```

Use the `AudioRecorder` class to easily manage audio recording operations in your scripts, providing flexibility and control over the audio recording process.



---
url: /guide/Device Capabilities/BackgroundKeeper.md
---

# BackgroundKeeper

The `BackgroundKeeper` API provides control over background keep-alive behavior in the **Scripting App**, allowing scripts to extend their runtime after the app transitions to the background. This can be useful for maintaining ongoing operations, such as network connections or active processes, for a limited period while the app is not in the foreground.

> **Availability:**
> This API is only available when the script is running in the main app (`Script.env === "index"`).
> Use it responsibly, as prolonged background execution may increase power consumption.

***

## Overview

When the app moves to the background (due to a background event such as a system-triggered state change), you can call `BackgroundKeeper.keepAlive()` to request that the app continue running for a limited duration.
When the app returns to the foreground, you should call `BackgroundKeeper.stopKeepAlive()` to release background resources.

Multiple scripts can request background keep-alive at the same time. Internally, the system maintains a **keep-alive request queue**:

- Each call to `keepAlive()` adds the calling script to the queue.
- Each call to `stopKeepAlive()` removes it.
- The keep-alive process stops only when **all requests** have been removed from the queue.

> **Note:**
> Even with keep-alive enabled, iOS may still terminate the app under conditions such as high memory usage or strict power constraints.

***

## Namespace: `BackgroundKeeper`

### Properties

#### `isActive: Promise<boolean>`

Returns a promise that resolves to a boolean value indicating whether the keep-alive process is currently active.

**Example:**

```ts
const active = await BackgroundKeeper.isActive
if (active) {
  console.log("Keep-alive is currently active")
} else {
  console.log("Keep-alive is not active")
}
```

***

### Methods

#### `keepAlive(): Promise<boolean>`

Starts the background keep-alive process.

- If the process is already active, this method resolves to `true`.
- If successfully started, it resolves to `true`.
- If the system denies the request, it may resolve to `false`.

**Returns:**
`Promise<boolean>` — Indicates whether the keep-alive process was successfully started.

**Example:**

```ts
const started = await BackgroundKeeper.keepAlive()
if (started) {
  console.log("Background keep-alive started successfully")
} else {
  console.log("Failed to start background keep-alive")
}
```

***

#### `stopKeepAlive(): Promise<void>`

Stops the keep-alive request for the current script.
This does **not** guarantee that the entire keep-alive process will stop immediately, as other scripts may still have active requests.

**Returns:**
`Promise<void>` — Resolves when the stop request is processed.

**Example:**

```ts
await BackgroundKeeper.stopKeepAlive()
console.log("Keep-alive request for this script has been released")
```

***

## Example Usage

```ts
async function runBackgroundTask() {
  const started = await BackgroundKeeper.keepAlive()
  if (!started) {
    console.log("Unable to keep app alive in background")
    return
  }

  try {
    console.log("Performing background work...")
    // Perform background operations (e.g., sync data, monitor sensors)
    await new Promise(resolve => setTimeout(resolve, 10000))
  } finally {
    await BackgroundKeeper.stopKeepAlive()
    console.log("Stopped background keep-alive")
  }
}
```

***

## Notes and Best Practices

- Use **keep-alive sparingly** — continuous background activity may significantly increase battery drain.
- Always **stop keep-alive** once your background task is complete or when the app returns to the foreground.
- Avoid using `BackgroundKeeper` for indefinite background execution. The system may still suspend or terminate the app.
- The keep-alive mechanism is cooperative — if multiple scripts request it, all must release their requests before it stops.



---
url: /guide/Device Capabilities/Bluetooth/BluetoothCentralManager.md
---

# BluetoothCentralManager

The `BluetoothCentralManager` namespace provides core functionality for managing Bluetooth Low Energy (BLE) operations as a central device. It supports scanning, connecting, disconnecting, and retrieving known or connected peripherals. This API is ideal for building custom Bluetooth workflows, interacting with smart devices, wearables, and IoT peripherals.

***

## Properties

### `isScanning: Promise<boolean>`

> Returns whether the central manager is currently scanning for peripherals.

- **Type**: `Promise<boolean>`
- **Example**:

  ```ts
  const scanning = await BluetoothCentralManager.isScanning
  console.log(scanning ? "Scanning..." : "Not scanning")
  ```

***

## Methods

### `startScan(onDiscoverPeripheral, options?): Promise<void>`

> Starts scanning for BLE peripherals. The scan continues until you call `stopScan()`. The callback will be triggered every time a peripheral is discovered.

#### Parameters

- `onDiscoverPeripheral: (peripheral, advertisementData, rssi) => void`

  - Callback triggered on discovery.
  - Arguments:

    - `peripheral`: A `BluetoothPeripheral` object
    - `advertisementData`: A `BluetoothAdvertisementData` object
    - `rssi`: Signal strength in dBm

- `options?: { services?: string[]; allowDuplicates?: boolean; solicitedServiceUUIDs?: string[] }`

  - `services`: An array of UUID strings to filter devices by services
  - `allowDuplicates`: If `true`, reports duplicates; if `false` (default), filters out repeated discoveries
  - `solicitedServiceUUIDs`: An array of UUID strings to filter devices by solicited services

##### BluetoothAdvertisementData

When using `BluetoothCentralManager.startScan()` to scan for Bluetooth peripherals, each discovered device includes an `advertisementData` object. This object contains key metadata extracted from the peripheral's BLE advertisement packets. It can help identify, filter, or categorize devices before establishing a connection.

***

###### Type Definition

```ts
type BluetoothAdvertisementData = {
  localName?: string
  txPowerLevel?: number
  manufacturerData?: Data
  serviceData?: Record<string, Data>
  serviceUUIDs?: string[]
  overflowServiceUUIDs?: string[]
  isConnectable?: boolean
  solicitedServiceUUIDs?: string[]
}
```

***

###### Field Descriptions

| Field Name              | Type                              | Description                                                                                |
| ----------------------- | --------------------------------- | ------------------------------------------------------------------------------------------ |
| `localName`             | `string` (optional)               | The local name advertised by the peripheral, if available. Useful for display.             |
| `txPowerLevel`          | `number` (optional)               | Transmit power level in dBm. Combined with RSSI, it can be used for distance estimation.   |
| `manufacturerData`      | `Data` (optional)                 | Manufacturer-specific binary data. Often used to encode model or serial information.       |
| `serviceData`           | `Record<string, Data>` (optional) | Service-specific data mapped by UUID. Each value is a `Data` object.                       |
| `serviceUUIDs`          | `string[]` (optional)             | List of service UUIDs the peripheral is advertising. Indicates supported capabilities.     |
| `overflowServiceUUIDs`  | `string[]` (optional)             | Additional service UUIDs not included in `serviceUUIDs` due to size limits.                |
| `isConnectable`         | `boolean` (optional)              | Indicates whether the peripheral accepts connections. Helps filter broadcast-only devices. |
| `solicitedServiceUUIDs` | `string[]` (optional)             | UUIDs of services that the peripheral is requesting from central devices.                  |

***

###### Common Use Cases

- **Filtering devices** by `localName`, `serviceUUIDs`, or `isConnectable`
- **Identifying vendor-specific devices** using `manufacturerData`
- **Estimating distance** using `txPowerLevel` + RSSI
- **Understanding device intentions** via `solicitedServiceUUIDs`

***

###### Notes

- All fields are optional; some peripherals may omit certain fields.
- `manufacturerData` and `serviceData` are raw `Data` objects and must be parsed using manufacturer-specific formats.
- `serviceUUIDs` represent only advertised services. To get the full list of available services, call `peripheral.discoverServices()` after connecting.

#### Returns

- `Promise<void>`

#### Example

```ts
await BluetoothCentralManager.startScan((peripheral, adv, rssi) => {
  console.log(`Discovered ${peripheral.name} with RSSI ${rssi}`)
}, {
  services: ["180D"], // Filter for Heart Rate Service
  allowDuplicates: false
})
```

***

### `stopScan(): Promise<void>`

> Stops an ongoing scan.

#### Returns

- `Promise<void>`

#### Example

```ts
await BluetoothCentralManager.stopScan()
console.log("Scan stopped")
```

***

### `retrievePeripherals(ids: string[]): Promise<BluetoothPeripheral[]>`

> Retrieves known peripherals by their identifiers.

#### Parameters

- `ids`: An array of peripheral UUID strings

#### Returns

- `Promise<BluetoothPeripheral[]>`

#### Example

```ts
const known = await BluetoothCentralManager.retrievePeripherals(["A1-B2-C3-D4"])
```

***

### `retrieveConnectedPeripherals(serviceUUIDs: string[]): Promise<BluetoothPeripheral[]>`

> Retrieves currently connected peripherals that provide at least one of the specified services.

#### Parameters

- `serviceUUIDs`: An array of service UUID strings

#### Returns

- `Promise<BluetoothPeripheral[]>`

#### Example

```ts
const connected = await BluetoothCentralManager.retrieveConnectedPeripherals(["180F"])
console.log(`Found ${connected.length} connected devices with Battery Service`)
```

***

### `connect(peripheral, options?): Promise<void>`

> Establishes a connection to the specified peripheral.

#### Parameters

- `peripheral`: A `BluetoothPeripheral` object to connect to
- `options?`:

  - `startDelay?: number` – Delay in seconds before connecting
  - `enableTransportBridging?: boolean` – Enables transport bridging (advanced)
  - `requiresANCS?: boolean` – Whether Apple Notification Center Service is required
  - `enableAutoReconnect?: boolean` – Whether to auto-reconnect if disconnected
  - `notifyOnConnection?: boolean` - Whether to notify when the connection is established
  - `notifyOnDisconnection?: boolean` - Whether to notify when the connection is disconnected
  - `notifyOnNotification?: boolean` - Whether to notify when a notification is received

#### Returns

- `Promise<void>`

#### Example

```ts
await BluetoothCentralManager.connect(peripheral, {
  startDelay: 100,
  enableAutoReconnect: true
})
console.log("Connected")
```

***

### `disconnect(peripheral): Promise<void>`

> Disconnects from the specified peripheral. This is a non-blocking operation.

#### Parameters

- `peripheral`: A `BluetoothPeripheral` object

#### Returns

- `Promise<void>`

#### Notes

- Physical disconnection is not guaranteed if other apps are connected to the same peripheral.
- From the app's perspective, the device is considered disconnected and `onDisconnected` will be triggered.

#### Example

```ts
await BluetoothCentralManager.disconnect(peripheral)
console.log("Disconnected")
```

***

## Workflow Example

```ts
await BluetoothCentralManager.startScan((peripheral) => {
  BluetoothCentralManager.stopScan()
  BluetoothCentralManager.connect(peripheral)
    .then(() => peripheral.discoverServices())
    .then(() => console.log("Services discovered"))
})
```

***

## Best Practices

- Always call `stopScan()` when scanning is no longer needed to save battery and reduce system load.
- Make sure Bluetooth permissions are granted before using these APIs.
- After connecting to a peripheral, call `discoverServices()` followed by `discoverCharacteristics()` before reading or writing data.



---
url: /guide/Device Capabilities/Bluetooth/BluetoothCharacteristic.md
---

# BluetoothCharacteristic

The `BluetoothCharacteristic` interface represents a Bluetooth Low Energy (BLE) characteristic, which is the fundamental data unit in a BLE service. A characteristic exposes a specific piece of data and supports operations such as reading, writing, or subscribing to notifications.

***

## 1. Properties

### `uuid: string`

The universally unique identifier (UUID) of the characteristic.

- Used to identify standard (e.g., `"2A37"` for Heart Rate Measurement) or custom vendor-defined characteristics.

***

### `serviceUUID: string | null`

The UUID of the service that contains this characteristic. May be `null` if the service is not known or not yet discovered.

***

### `properties: BluetoothCharacteristicProperty[]`

An array of supported operations for this characteristic. These define how the characteristic can be interacted with (read, write, notify, etc.).

#### Available Values (`BluetoothCharacteristicProperty`):

| Property                       | Description                                       |
| ------------------------------ | ------------------------------------------------- |
| `"broadcast"`                  | Supports broadcasting                             |
| `"read"`                       | Supports reading                                  |
| `"writeWithoutResponse"`       | Supports writing without requiring acknowledgment |
| `"write"`                      | Supports writing with response                    |
| `"notify"`                     | Supports notification when value changes          |
| `"indicate"`                   | Supports indication with acknowledgment           |
| `"authenticatedSignedWrites"`  | Supports authenticated signed writes              |
| `"extendedProperties"`         | Has extended properties (defined via descriptors) |
| `"notifyEncryptionRequired"`   | Notification requires an encrypted connection     |
| `"indicateEncryptionRequired"` | Indication requires an encrypted connection       |

**Example:**

```ts
if (characteristic.properties.includes("read")) {
  const value = await peripheral.readValue(characteristic)
}
```

***

### `isNotifying: boolean`

Indicates whether notifications or indications are currently enabled for the characteristic.

- `true`: Notifications or indications are active
- `false`: Notifications are not active

***

### `value: Data | null`

The current value of the characteristic, as a `Data` object.

- May be `null` if the value has not yet been read or written.
- Use `peripheral.readValue(characteristic)` to fetch the latest value.

***

## 2. Attribute Permissions

Although not directly present in the characteristic interface, attributes may be configured with permissions when used in a Peripheral (GATT Server) role.

### `BluetoothAttributePermissions` (Enum)

| Permission                  | Description                               |
| --------------------------- | ----------------------------------------- |
| `"readable"`                | The attribute can be read                 |
| `"writeable"`               | The attribute can be written              |
| `"readEncryptionRequired"`  | Requires an encrypted connection to read  |
| `"writeEncryptionRequired"` | Requires an encrypted connection to write |

***

## 3. Usage Examples

### Read from a characteristic (requires `"read"`)

```ts
if (characteristic.properties.includes("read")) {
  const value = await peripheral.readValue(characteristic)
  console.log("Value:", value?.toRawString())
}
```

***

### Write to a characteristic

```ts
const data = Data.fromRawString("COMMAND")
if (characteristic.properties.includes("writeWithoutResponse")) {
  await peripheral.writeValue(characteristic, data, "withoutResponse")
} else if (characteristic.properties.includes("write")) {
  await peripheral.writeValue(characteristic, data, "withResponse")
}
```

***

### Subscribe to notifications

```ts
if (characteristic.properties.includes("notify")) {
  await peripheral.subscribe(characteristic, (error, value) => {
    if (!error && value) {
      console.log("Notification received:", value.toHexString())
    }
  })
}
```

***

### Unsubscribe from notifications

```ts
await peripheral.unsubscribe(characteristic)
```

***

## 4. Best Practices and Notes

- Always call `discoverCharacteristics(service)` before interacting with any characteristic.
- Do not assume all characteristics support read/write; check `properties` before performing operations.
- When subscribing to notifications or indications, you must explicitly call `subscribe()` and later `unsubscribe()` to clean up.
- For `"writeWithoutResponse"` operations, use `canSendWriteWithoutResponse` to control flow rate.
- Before writing, use `maxWriteValueLength()` to ensure the data size is within limits.



---
url: /guide/Device Capabilities/Bluetooth/BluetoothPeripheral.md
---

# BluetoothPeripheral

The `BluetoothPeripheral` interface represents a Bluetooth Low Energy (BLE) peripheral device. It provides properties and methods for interacting with the device, including connecting, discovering services and characteristics, reading/writing values, and subscribing to notifications.

***

## Properties (Read-only)

### `id: string`

A unique identifier (UUID string) for the peripheral. It remains constant across app launches and can be used to identify and reconnect to the device.

***

### `name: string | null`

The name of the peripheral device, or `null` if not available (e.g., if not broadcast).

***

### `isConnected: boolean`

Indicates whether the peripheral is currently connected.

- `true`: Connected and ready for communication
- `false`: Not connected or disconnected

***

### `canSendWriteWithoutResponse: boolean`

Indicates whether the peripheral is ready to send write requests without waiting for a response.

- `true`: Supports fast, unacknowledged writes (`writeWithoutResponse`)
- `false`: Requires response before next write

The `onReadyToSendWriteWithoutResponse` callback is triggered when this changes to `true`.

***

### `ancsAuthorized: boolean`

Indicates whether the peripheral is authorized to use Apple Notification Center Service (ANCS). Relevant only for peripherals that support ANCS.

***

### `services: BluetoothService[] | null`

The list of services discovered on the peripheral. `null` if `discoverServices()` has not been called yet.

***

## Event Handlers

### `onConnected: (() => void) | null`

Called when the peripheral is successfully connected.

***

### `onDisconnected: ((error: Error | null, isReconnecting: boolean) => void) | null`

Called when the peripheral is disconnected.

- `error`: An error object if the disconnection was unexpected, or `null` if intentional
- `isReconnecting`: `true` if the system is attempting to reconnect automatically

***

### `onConnectFailed: ((error: Error) => void) | null`

Called when the peripheral fails to connect.

***

### `onNameChanged: ((name: string | null) => void) | null`

Called when the peripheral's name changes.

***

### `onDiscoverServices: ((error: Error | null, services: BluetoothService[] | null) => void) | null`

Called after calling `discoverServices()`.

***

### `onDiscoverCharacteristics: ((error: Error | null, characteristics: BluetoothCharacteristic[] | null) => void) | null`

Called after calling `discoverCharacteristics()`.

***

### `onDiscoverIncludedServices: ((error: Error | null, services: BluetoothService[] | null) => void) | null`

Called after calling `discoverIncludedServices()`.

***

### `onReadyToSendWriteWithoutResponse: (() => void) | null`

Called when the peripheral is ready to send more write requests without response.

***

## Methods

### `readValue(characteristic: BluetoothCharacteristic): Promise<Data>`

Reads the value of a given characteristic.

- **Parameters**:

  - `characteristic`: The characteristic to read from
- **Returns**: A `Promise<Data>` containing the value

***

### `maxWriteValueLength(writeType: "withResponse" | "withoutResponse"): number`

Gets the maximum number of bytes that can be written in a single operation.

- **Parameters**:

  - `writeType`: `"withResponse"` or `"withoutResponse"`
- **Returns**: A `number` representing the max write size

***

### `writeValue(characteristic, value, writeType): Promise<void>`

Writes data to a characteristic.

- **Parameters**:

  - `characteristic`: Target characteristic
  - `value`: The data to write (`Data`)
  - `writeType`: `"withResponse"` or `"withoutResponse"`
- **Returns**: `Promise<void>`

***

### `subscribe(characteristic, handler): Promise<void>`

Subscribes to notifications or indications from a characteristic.

- **Requirements**: The characteristic must support `"notify"` or `"indicate"`
- **Parameters**:

  - `characteristic`: Target characteristic
  - `handler(error, value)`: Callback triggered on value change

    - `error`: Error object if any
    - `value`: New value as `Data`
- **Returns**: `Promise<void>`

***

### `unsubscribe(characteristic): Promise<void>`

Unsubscribes from notifications for a characteristic.

- **Parameters**:

  - `characteristic`: Target characteristic
- **Returns**: `Promise<void>`

***

### `discoverServices(serviceUUIDs?: string[]): Promise<void>`

Discovers the services available on the peripheral.

- **Parameters**:

  - `serviceUUIDs`: Optional list of service UUIDs to filter
- **Returns**: `Promise<void>`

***

### `discoverIncludedServices(service, includedServiceUUIDs?): Promise<void>`

Discovers included services within a service.

- **Parameters**:

  - `service`: The parent service
  - `includedServiceUUIDs`: Optional list of included service UUIDs
- **Returns**: `Promise<void>`

***

### `discoverCharacteristics(service, characteristicUUIDs?): Promise<void>`

Discovers characteristics within a service.

- **Parameters**:

  - `service`: The target service
  - `characteristicUUIDs`: Optional list of characteristic UUIDs
- **Returns**: `Promise<void>`

***

### `readRSSI(): Promise<number>`

Reads the current Received Signal Strength Indicator (RSSI).

- **Returns**: A `Promise<number>` representing signal strength in dBm

***

## Examples

### Connect and Read Characteristics

```ts
await BluetoothCentralManager.connect(peripheral)
await peripheral.discoverServices()

for (const service of peripheral.services ?? []) {
  await peripheral.discoverCharacteristics(service)
  for (const char of service.characteristics ?? []) {
    if (char.properties.includes("read")) {
      const value = await peripheral.readValue(char)
      console.log("Value:", value?.toRawString())
    }
  }
}
```

***

### Write Value and Subscribe

```ts
const data = Data.fromRawString("hello")
await peripheral.writeValue(characteristic, data, "withResponse")

await peripheral.subscribe(characteristic, (error, value) => {
  if (!error && value) {
    console.log("Notification:", value.toHexString())
  }
})
```

***

## Notes

- Always call `discoverServices()` and `discoverCharacteristics()` before interacting with a peripheral’s data.
- Be sure to `unsubscribe()` when notifications are no longer needed.
- Avoid writing when `canSendWriteWithoutResponse` is `false`.



---
url: /guide/Device Capabilities/Bluetooth/BluetoothPeripheralManager.md
---

# BluetoothPeripheralManager

The `BluetoothPeripheralManager` API enables your device to act as a Bluetooth Low Energy (BLE) peripheral. It allows you to:

- Advertise device name and service UUIDs
- Add or remove services with characteristics
- Handle read and write requests from central devices
- Notify subscribed centrals of characteristic value changes
- Manage connection parameters such as connection latency

This API is ideal for building custom sensor devices, BLE peripheral simulators, controllers, and similar use cases.

***

## Core Status Property

### `isAdvertising: Promise<boolean>`

Returns whether the device is currently advertising as a peripheral.

```ts
const advertising = await BluetoothPeripheralManager.isAdvertising
console.log(advertising ? "Advertising" : "Not advertising")
```

***

## Advertising Control

### `startAdvertising(advertisementData: { localName?: string; serviceUUIDs?: string[] }): Promise<void>`

Begins BLE advertising with optional device name and service UUIDs.

```ts
await BluetoothPeripheralManager.startAdvertising({
  localName: "MyPeripheral",
  serviceUUIDs: ["1234", "ABCD"]
})
```

***

### `stopAdvertising(): Promise<void>`

Stops ongoing BLE advertising.

```ts
await BluetoothPeripheralManager.stopAdvertising()
```

***

## Service Management

### `addService(service): Promise<void>`

Adds a service and its characteristics to the peripheral.

**Parameters:**

```ts
{
  uuid: string,
  characteristics: Array<{
    uuid: string,
    properties: string[], // e.g., ["read", "notify"]
    permissions: string[], // e.g., ["readable"]
    value?: Data
  }>
}
```

**Example:**

```ts
await BluetoothPeripheralManager.addService({
  uuid: "180F",
  characteristics: [
    {
      uuid: "2A19",
      properties: ["read", "notify"],
      permissions: ["readable"],
      value: Data.fromIntArray([85]) // 85% battery
    }
  ]
})
```

***

### `removeService(serviceUUID: string): Promise<void>`

Removes a previously added service by its UUID.

***

### `removeAllServices(): Promise<void>`

Removes all services added by the current script.

***

## Event Handlers for Central Interaction

### `onRestoreState: ((state) => void) | null`

Called when the system restores your script due to a background BLE session. Useful for restoring service and advertising state.

```ts
BluetoothPeripheralManager.onRestoreState = (state) => {
  console.log("Restored state. Services count:", state.services.length)
}
```

```ts
type RestoreState = {
  services: BluetoothServiceInfo[]
  advertisementData: BluetoothAdvertisementData
}
```

***

### `onReadyToUpdateSubscribers: (() => void) | null`

Called when the system's transmission queue is cleared and ready to send notifications again after a previous failure due to queue congestion.

```ts
BluetoothPeripheralManager.onReadyToUpdateSubscribers = () => {
  console.log("Ready to resend notifications")
}
```

***

### `onReadCharacteristicValue: (characteristicId, offset, central) => Promise<{result, value}>`

Invoked when a remote central requests to read a characteristic.

If not implemented, the system returns `readNotPermitted`.

```ts
BluetoothPeripheralManager.onReadCharacteristicValue = async (id, offset, central) => {
  if (id === "2A19") {
    return {
      result: BluetoothATTResponseCode.success,
      value: Data.fromIntArray([85]) // battery level
    }
  }
  return { result: BluetoothATTResponseCode.attributeNotFound }
}
```

**Signature:**

```ts
(
  characteristicId: string,
  offset: number,
  central: {
    id: string,
    maximumUpdateValueLength: number
  }
) => Promise<{
  result: BluetoothATTResponseCode,
  value?: Data | null
}>
```

***

### `onWriteCharacteristicValue: (characteristicId, offset, value, central) => Promise<BluetoothATTResponseCode>`

Invoked when a remote central attempts to write to a characteristic.

If not implemented, the system returns `writeNotPermitted`.

```ts
BluetoothPeripheralManager.onWriteCharacteristicValue = async (id, offset, value, central) => {
  console.log(`Write request to ${id}:`, value.toIntArray())
  if (id === "2A19") {
    return BluetoothATTResponseCode.success
  }
  return BluetoothATTResponseCode.attributeNotFound
}
```

**Signature:**

```ts
(
  characteristicId: string,
  offset: number,
  value: Data,
  central: {
    id: string,
    maximumUpdateValueLength: number
  }
) => Promise<BluetoothATTResponseCode>
```

***

### `onSubscribe: (characteristicId, central) => void`

Called when a central subscribes to a characteristic that supports notifications or indications.

```ts
BluetoothPeripheralManager.onSubscribe = (id, central) => {
  console.log(`Central ${central.id} subscribed to ${id}`)
}
```

***

### `onUnsubscribe: (characteristicId, central) => void`

Called when a central unsubscribes from a characteristic.

```ts
BluetoothPeripheralManager.onUnsubscribe = (id, central) => {
  console.log(`Central ${central.id} unsubscribed from ${id}`)
}
```

***

## Notifications and Subscriptions

### `getSubscribers(characteristicId: string): Promise<Central[]>`

Returns a list of central devices currently subscribed to a given characteristic.

Each item:

```ts
{
  id: string,
  maximumUpdateValueLength: number
}
```

***

### `updateValue(characteristicId: string, value: Data, options?): Promise<boolean>`

Sends a notification or indication to all subscribed centrals (or a specified subset) with the updated characteristic value.

**Returns:**

- `true`: Successfully sent
- `false`: Queue is full — wait for `onReadyToUpdateSubscribers` before retrying

***

## Connection Parameters

### `setDesiredConnectionLatency(centralId: string, latency): Promise<void>`

Sets the preferred connection latency for a specific central device.

- `"low"` – Faster interaction, higher power usage
- `"medium"` – Balanced
- `"high"` – Lower power usage, less frequent interaction

***

## `BluetoothATTResponseCode` Enumeration

Defines response codes for read/write operations:

| Name                            | Value | Meaning                        |
| ------------------------------- | ----- | ------------------------------ |
| `success`                       | 0     | Operation succeeded            |
| `invalidHandle`                 | 1     | Invalid handle                 |
| `readNotPermitted`              | 2     | Read not permitted             |
| `writeNotPermitted`             | 3     | Write not permitted            |
| `invalidPdu`                    | 4     | Invalid PDU                    |
| `insufficientAuthentication`    | 5     | Not authenticated              |
| `requestNotSupported`           | 6     | Request not supported          |
| `invalidOffset`                 | 7     | Invalid offset                 |
| `insufficientAuthorization`     | 8     | Not authorized                 |
| `prepareQueueFull`              | 9     | Prepare queue is full          |
| `attributeNotFound`             | 10    | Attribute not found            |
| `attributeNotLong`              | 11    | Attribute not long             |
| `insufficientEncryptionKeySize` | 12    | Encryption key size too small  |
| `invalidAttributeValueLength`   | 13    | Invalid attribute value length |
| `unlikelyError`                 | 14    | Unlikely error occurred        |
| `insufficientEncryption`        | 15    | Encryption required            |
| `unsupportedGroupType`          | 16    | Unsupported group type         |
| `insufficientResources`         | 17    | Insufficient resources         |

***

## Example: Broadcasting a Battery Service

```ts
await BluetoothPeripheralManager.addService({
  uuid: "180F",
  characteristics: [
    {
      uuid: "2A19",
      properties: ["read", "notify"],
      permissions: ["readable"],
      value: Data.fromIntArray([100]) // Battery level 100%
    }
  ]
})

await BluetoothPeripheralManager.startAdvertising({
  localName: "BatteryPeripheral",
  serviceUUIDs: ["180F"]
})

BluetoothPeripheralManager.onReadCharacteristicValue = async (id, offset, central) => {
  return { result: BluetoothATTResponseCode.success, value: Data.fromIntArray([90]) }
}
```



---
url: /guide/Device Capabilities/Bluetooth/BluetoothService.md
---

# BluetoothService

The `BluetoothService` interface represents a Bluetooth Low Energy (BLE) service. A service is a logical grouping of related characteristics and possibly other included services. Services are used to define the functionality of a peripheral device, such as Heart Rate Monitoring or Battery Level Reporting.

***

## Overview

Services provide structure to BLE communication. Each service is identified by a universally unique identifier (UUID) and may include:

- Characteristics: Data points and operations (e.g., read/write/notify)
- Included services: References to other services

***

## Properties

### `uuid: string`

The UUID of the service.

- This UUID identifies the type of service (e.g., standard service like Battery Service `"180F"` or custom UUID for vendor-defined functionality).
- You can use this to filter or recognize services.

***

### `peripheralId: string | null`

The identifier of the peripheral that contains this service.

- If the peripheral context is not known or no longer available, this value may be `null`.

***

### `isPrimary: boolean`

Indicates whether this is a primary or secondary service.

- `true`: This is a primary service essential to the device's functionality
- `false`: This is a secondary service typically used as a dependency of another service

***

### `includedServices: BluetoothService[] | null`

An array of included services referenced by this service.

- Included services may be primary or secondary.
- If not yet discovered, this value will be `null`.
- You must call `discoverIncludedServices(service)` on the associated `BluetoothPeripheral` to populate this.

***

### `characteristics: BluetoothCharacteristic[] | null`

The characteristics contained in this service.

- These define the operations (read, write, notify, etc.) and data exposed by the service.
- If not yet discovered, this will be `null`.
- You must call `discoverCharacteristics(service)` on the associated `BluetoothPeripheral` to populate this.

***

## Example

### Discover characteristics in a service

```ts
await peripheral.discoverServices()
for (const service of peripheral.services ?? []) {
  console.log("Service UUID:", service.uuid)

  await peripheral.discoverCharacteristics(service)
  for (const characteristic of service.characteristics ?? []) {
    console.log("Characteristic UUID:", characteristic.uuid)
  }
}
```

***

### Discover included services

```ts
await peripheral.discoverServices()
for (const service of peripheral.services ?? []) {
  await peripheral.discoverIncludedServices(service)
  for (const included of service.includedServices ?? []) {
    console.log("Included Service UUID:", included.uuid)
  }
}
```

***

## Notes

- All properties are read-only.
- Services must be discovered before accessing characteristics or included services.
- When working with included services, recursive discovery may be necessary if they contain their own dependencies.



---
url: /guide/Device Capabilities/Calendar.md
---

# Calendar

The `Calendar` API in the Scripting app provides access to iOS calendars, calendar accounts, and event/reminder management.\
Developers can retrieve default calendars, create new ones, list calendars supporting specific entity types, and manage calendar properties.

***

## Type Definitions

### CalendarType

Represents types of calendars:

| Value            | Description               |
| :--------------- | :------------------------ |
| `"birthday"`     | Birthday calendar         |
| `"calDAV"`       | CalDAV protocol calendar  |
| `"exchange"`     | Exchange account calendar |
| `"local"`        | Local calendar            |
| `"subscription"` | Subscription calendar     |

### CalendarSourceType

Represents the type of calendar account source:

| Value          | Description        |
| :------------- | :----------------- |
| `"birthdays"`  | Birthday account   |
| `"calDAV"`     | CalDAV account     |
| `"exchange"`   | Exchange account   |
| `"local"`      | Local account      |
| `"mobileMe"`   | MobileMe account   |
| `"subscribed"` | Subscribed account |

### CalendarEventAvailability

Represents event availability settings:

| Value           | Description |
| :-------------- | :---------- |
| `"busy"`        | Busy        |
| `"free"`        | Free        |
| `"tentative"`   | Tentative   |
| `"unavailable"` | Unavailable |

### CalendarEntityType

Represents types of entities calendars can manage:

| Value        | Description |
| :----------- | :---------- |
| `"event"`    | Event       |
| `"reminder"` | Reminder    |

***

## Class: CalendarSource

Represents a calendar account source (e.g., Local, Exchange).

### Properties

| Property     | Type                 | Description                          |
| :----------- | :------------------- | :----------------------------------- |
| `type`       | `CalendarSourceType` | The account source type              |
| `title`      | `string`             | The account source title             |
| `identifier` | `string`             | The account source unique identifier |

### Methods

#### `getCalendars(entityType: CalendarEntityType): Promise<Calendar[]>`

Gets the list of calendars for this source based on entity type.

- **Parameters**
  - `entityType: CalendarEntityType` — The entity type to retrieve.
- **Returns**
  - `Promise<Calendar[]>` — An array of calendar objects.

***

## Class: Calendar

Represents a calendar object that manages events and reminders.

### Properties

| Property                       | Type                        | Description                                |
| :----------------------------- | :-------------------------- | :----------------------------------------- |
| `identifier`                   | `string`                    | Unique identifier of the calendar          |
| `title`                        | `string`                    | Calendar title                             |
| `color`                        | `Color`                     | Calendar color                             |
| `type`                         | `CalendarType`              | Calendar type                              |
| `source`                       | `CalendarSource`            | Calendar Source                            |
| `allowedEntityTypes`           | `CalendarEntityType`        | Allowed entity types (`event`, `reminder`) |
| `isForEvents`                  | `boolean`                   | Whether the calendar is for events         |
| `isForReminders`               | `boolean`                   | Whether the calendar is for reminders      |
| `allowsContentModifications`   | `boolean`                   | Whether modifications are allowed          |
| `isSubscribed`                 | `boolean`                   | Whether the calendar is subscribed         |
| `supportedEventAvailabilities` | `CalendarEventAvailability` | Supported event availabilities             |

### Methods

#### `remove(): Promise<void>`

Deletes the calendar.

#### `save(): Promise<void>`

Saves changes to the calendar.

#### `static defaultForEvents(): Promise<Calendar | null>`

Gets the default event calendar set by the system.

#### `static defaultForReminders(): Promise<Calendar | null>`

Gets the default reminder calendar set by the system.

#### `static forEvents(): Promise<Calendar[]>`

Lists all calendars that support events.

#### `static forReminders(): Promise<Calendar[]>`

Lists all calendars that support reminders.

#### `static create(options: { title: string, entityType: CalendarEntityType, sourceType: CalendarSourceType, color?: Color }): Promise<Calendar>`

Creates a new calendar.

- **Parameters**
  - `title: string` — Calendar title
  - `entityType: CalendarEntityType` — Supported entity type
  - `sourceType: CalendarSourceType` — Account source type
  - `color?: Color` — (Optional) Calendar color
- **Returns**
  - `Promise<Calendar>` — The newly created calendar.

#### `static presentChooser(allowMultipleSelection?: boolean): Promise<Calendar[]>`

Presents a calendar chooser view.

- **Parameters**
  - `allowMultipleSelection?: boolean` — Allow multiple selection, default `false`.
- **Returns**
  - `Promise<Calendar[]>` — Selected calendars.

#### `static getSources(): CalendarSource[]`

Retrieves all available calendar sources on the device.

***

## Example Code

### Retrieve Default Event Calendar

```tsx
const defaultEventCalendar = await Calendar.defaultForEvents()
if (defaultEventCalendar) {
  console.log(`Default event calendar: ${defaultEventCalendar.title}`)
} else {
  console.log('No default event calendar found')
}
```

### Create a New Local Event Calendar

```tsx
const newCalendar = await Calendar.create({
  title: 'Workout Schedule',
  entityType: 'event',
  sourceType: 'local',
  color: '#FF5733'
})

await newCalendar.save()
console.log(`Created new calendar: ${newCalendar.title}`)
```

### List All Event-Supporting Calendars

```tsx
const eventCalendars = await Calendar.forEvents()
for (const calendar of eventCalendars) {
  console.log(`Calendar: ${calendar.title}`)
}
```

### Delete the First Event Calendar

```tsx
const eventCalendars = await Calendar.forEvents()
if (eventCalendars.length > 0) {
  const calendarToRemove = eventCalendars[0]
  await calendarToRemove.remove()
  console.log(`Removed calendar: ${calendarToRemove.title}`)
}
```

### Present Calendar Chooser

```tsx
const selectedCalendars = await Calendar.presentChooser(true)
for (const calendar of selectedCalendars) {
  console.log(`Selected calendar: ${calendar.title}`)
}
```



---
url: /guide/Device Capabilities/CalendarEvent.md
---

# CalendarEvent

The `CalendarEvent` API enables creating, reading, editing, and managing events in the iOS calendar.
Developers can configure event details such as title, time, location, participants, recurrence rules, alarms, availability, and structured locations, and can display system-provided interfaces for creating or editing events.

***

## 1. Types

## EventParticipant

Represents an attendee of the event:

- `isCurrentUser: boolean` – Indicates whether this attendee represents the current user
- `name?: string` – Display name
- `role: ParticipantRole` – The attendee’s role
- `type: ParticipantType` – The type of attendee
- `status: ParticipantStatus` – The attendee’s participation status

### ParticipantRole

- `chair`
- `nonParticipant`
- `optional`
- `required`
- `unknown`

### ParticipantType

- `group`
- `person`
- `resource`
- `room`
- `unknown`

### ParticipantStatus

- `unknown`
- `pending`
- `accepted`
- `declined`
- `tentative`
- `delegated`
- `completed`
- `inProcess`

***

## EventAvailability

Indicates how the event affects the user’s availability:

- `notSupported`
- `busy`
- `free`
- `tentative`
- `unavailable`

***

## EventStructuredLocation

Describes a location that can be used for location-based alarms.

- `title: string | null` – A name for the location
- `geoLocation: LocationInfo | null` – Latitude and longitude
- `radius: number` – Radius in meters for the geofence trigger

***

## AlarmProximity

Describes how a location alarm triggers:

- `none`
- `enter`
- `leave`

***

## 2. EventAlarm

`CalendarEvent` supports attaching one or more `EventAlarm` instances.
Alarms may be:

- absolute date alarms
- relative alarms (relative to the start of the event)
- location-based alarms using geofence triggers

See the EventAlarm documentation for detailed information.

***

## 3. CalendarEvent Class

## Constructor

```ts
new(): CalendarEvent
```

Creates an in-memory event instance.
Call `save()` to persist it into the calendar.

***

## 4. Properties

## General Information

### identifier: string

A unique identifier for the event.

### title: string

The title of the event.

### notes: string | null

Additional notes.

### url: string | null

A URL associated with the event.

### calendar: Calendar | null

The calendar to which the event belongs.
This property cannot be set to `null`. To remove an event, use `remove()`.

***

## Time and Location

### isAllDay: boolean

Indicates whether the event lasts all day.

### startDate: Date

The start date and time.

### endDate: Date

The end date and time.

### timeZone: string | null

The event’s time zone.

### location: string | null

A text description of the location.

### structuredLocation: EventStructuredLocation | null

A structured location that includes geolocation data for alarms.

***

## Event Metadata

### creationDate: Date | null

The date when the event was created.

### lastModifiedDate: Date | null

The date of the most recent modification.

### occurrenceDate: Date

For recurring events, this is the original scheduled date of this specific occurrence.

### isDetached: boolean

Indicates whether this event represents a modified occurrence of a recurring series.

***

## Participants and Availability

### attendees: EventParticipant\[] | null

An array of attendees.

### organizer: EventParticipant | null

The organizer of the event.

### hasAttendees: boolean

Indicates whether the event has attendees.

### availability: EventAvailability

Indicates the event’s impact on availability.

***

## Alarms

### alarms: EventAlarm\[] | null

The alarms associated with the event.

### hasAlarm: boolean

Indicates whether the event has any alarms.

***

## Recurrence

### recurrenceRules: RecurrenceRule\[] | null

The recurrence rules of the event.

### hasRecurrenceRules: boolean

Indicates whether the event has recurrence rules.

***

## Additional State Flags

### hasNotes: boolean

Indicates whether the event contains notes.

### hasChanges: boolean

Indicates whether the event or any nested objects contain unsaved changes.

***

## 5. Instance Methods

## Alarm Management

### addAlarm(alarm: EventAlarm): void

Adds an alarm to the event.

### removAlarm(alarm: EventAlarm): void

Removes an alarm from the event.
(Note: The method name is `removAlarm`.)

***

## Recurrence Management

### addRecurrenceRule(rule: RecurrenceRule): void

Appends a recurrence rule.

### removeRecurrenceRule(rule: RecurrenceRule): void

Removes a recurrence rule.

***

## Saving and Deleting

### `save(): Promise<void>`

Saves the event to the calendar.

### `remove(): Promise<void>`

Removes the event from the calendar.

***

## Editing UI

### `presentEditView(): Promise<EventEditViewAction>`

Displays the system event-editing interface and resolves with:

- `saved`
- `deleted`
- `canceled`

***

## 6. Static Methods

## `get(identifier: string): Promise<CalendarEvent | null>`

Fetches a calendar event by its identifier.

### `getAll(startDate: Date, endDate: Date, calendars?: Calendar[]): Promise<CalendarEvent[]>`

Fetches calendar events within a given date range.

- Provide an array of calendars to restrict the search
- Use `null` or omit the parameter to search all calendars

***

### `presentCreateView(): Promise<CalendarEvent | null>`

Displays the system interface for creating a new event.

- Returns the created event if saved
- Returns `null` if canceled

***

## 7. Usage Examples

## Creating and Saving an Event

```ts
const defaultCalendar = await Calendar.defaultForEvents()
const event = new CalendarEvent()
event.title = "Team Meeting"
event.calendar = defaultCalendar!
event.startDate = new Date("2024-01-15T09:00:00")
event.endDate = new Date("2024-01-15T10:00:00")
event.location = "Conference Room"

await event.save()
```

***

## Adding a Recurrence Rule

```ts
const rule = RecurrenceRule.create({
  frequency: "weekly",
  interval: 1,
  daysOfTheWeek: ["monday", "wednesday", "friday"],
  end: RecurrenceEnd.fromDate(new Date("2024-12-31")),
})

event.addRecurrenceRule(rule)
await event.save()
```

***

## Adding an Alarm

```ts
const alarm = EventAlarm.fromRelativeOffset(-600)
event.addAlarm(alarm)
await event.save()
```

***

## Fetching Events

```ts
const events = await CalendarEvent.getAll(
  new Date("2024-01-01"),
   new Date("2024-01-31")
 )

for (const e of events) {
  console.log(`Event: ${e.title}, Starts: ${e.startDate}`)
}
```

***

## Presenting the Create View

```ts
const created = await CalendarEvent.presentCreateView()
if (created) {
  console.log("Created event:", created.title)
}
```

***

## Editing an Existing Event

```ts
const result = await event.presentEditView()
console.log("Edit action:", result)
```

***

## Removing an Event

```ts
await event.remove()
console.log("Event removed")
```

***

## 8. Additional Notes

### Time Zone Considerations

When working with events that span time zones, set `timeZone` explicitly to avoid incorrect scheduling or display.

### Recurring Events

Editing individual occurrences of a recurring event may produce a detached instance.
Use `occurrenceDate` to determine the original date of the modified occurrence.

### Attendees

Attendee data depends on the calendar source (iCloud, Exchange, etc.) and may vary in availability.

### Structured Location

When using location-based alarms, the user must grant the necessary location permissions.



---
url: /guide/Device Capabilities/Contact/index.md
---

# Contact

The `Contact` module in the Scripting app allows you to access and manage contacts on the device. You can create, query, update, and delete contacts, as well as manage contact groups and containers.

## Overview of Data Structures

| Type                             | Description                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------- |
| **ContactInfo**                  | Represents detailed information of a single contact.                         |
| **ContactContainer**             | Represents a contact storage container, such as local, Exchange, or CardDAV. |
| **ContactGroup**                 | Represents a contact group for categorizing contacts.                        |
| **ContactLabeledValue**          | A labeled value, such as phone number or email address.                      |
| **ContactPostalAddress**         | Represents a postal address.                                                 |
| **ContactSocialProfile**         | Represents social profile information.                                       |
| **ContactInstantMessageAddress** | Represents instant messaging account information.                            |

***

## Creating a Contact

```ts
try {
  const contact = await Contact.createContact({
    givenName: 'John',
    familyName: 'Doe',
    phoneNumbers: [{ label: 'mobile', value: '+1234567890' }],
    emailAddresses: [{ label: 'work', value: 'john.doe@example.com' }]
  })
  console.log('Contact created:', contact)
} catch (error) {
  console.error('Failed to create contact:', error)
}
```

- Either `givenName` or `familyName` is required.
- You may specify an optional `containerIdentifier`. If not provided, the contact is added to the default container.
- Always handle potential errors due to permission issues or invalid input.

***

## Updating a Contact

```ts
try {
  const updated = await Contact.updateContact({
    identifier: contact.identifier,
    phoneNumbers: [{ label: 'home', value: '+9876543210' }]
  })
  console.log('Contact updated:', updated)
} catch (error) {
  console.error('Failed to update contact:', error)
}
```

- `identifier` is required.
- Only the provided fields will be updated; others remain unchanged.

***

## Fetching Contacts

### Fetch a Contact by Identifier

```ts
try {
  const contact = await Contact.fetchContact(contactId, { fetchImageData: true })
  console.log('Contact fetched:', contact)
} catch (error) {
  console.error('Failed to fetch contact:', error)
}
```

### Fetch All Contacts

```ts
try {
  const contacts = await Contact.fetchAllContacts({ fetchImageData: false })
  console.log('All contacts:', contacts)
} catch (error) {
  console.error('Failed to fetch contacts:', error)
}
```

### Fetch Contacts in a Container or Group

```ts
try {
  const contacts = await Contact.fetchContactsInContainer(containerId)
  console.log('Contacts in container:', contacts)
} catch (error) {
  console.error('Failed to fetch contacts in container:', error)
}

try {
  const groupContacts = await Contact.fetchContactsInGroup(groupId)
  console.log('Contacts in group:', groupContacts)
} catch (error) {
  console.error('Failed to fetch contacts in group:', error)
}
```

- Set `fetchImageData` to `true` only if you need the contact's image data.

***

## Deleting a Contact

```ts
try {
  await Contact.deleteContact(contactId)
  console.log('Contact deleted')
} catch (error) {
  console.error('Failed to delete contact:', error)
}
```

***

## Contact Container Management

### Fetch All Containers

```ts
try {
  const containers = await Contact.fetchContainers()
  console.log('Contact containers:', containers)
} catch (error) {
  console.error('Failed to fetch containers:', error)
}
```

### Get the Default Container Identifier

```ts
try {
  const defaultContainerId = await Contact.defaultContainerIdentifier
  console.log('Default container ID:', defaultContainerId)
} catch (error) {
  console.error('Failed to fetch default container:', error)
}
```

Container types:

- `unassigned`
- `local`
- `exchange`
- `cardDAV`

***

## Contact Group Management

### Create a Contact Group

```ts
try {
  const group = await Contact.createGroup('Friends', defaultContainerId)
  console.log('Group created:', group)
} catch (error) {
  console.error('Failed to create group:', error)
}
```

### Fetch Groups

```ts
try {
  const groups = await Contact.fetchGroups()
  console.log('Groups:', groups)
} catch (error) {
  console.error('Failed to fetch groups:', error)
}
```

### Delete a Group

```ts
try {
  await Contact.deleteGroup(groupId)
  console.log('Group deleted')
} catch (error) {
  console.error('Failed to delete group:', error)
}
```

***

## Managing Contact and Group Relationship

### Add Contact to a Group

```ts
try {
  await Contact.addContactToGroup(contactId, groupId)
  console.log('Contact added to group')
} catch (error) {
  console.error('Failed to add contact to group:', error)
}
```

### Remove Contact from a Group

```ts
try {
  await Contact.removeContactFromGroup(contactId, groupId)
  console.log('Contact removed from group')
} catch (error) {
  console.error('Failed to remove contact from group:', error)
}
```

***

## Example ContactInfo Structure

```json
{
  "identifier": "XXXX-XXXX",
  "givenName": "John",
  "familyName": "Doe",
  "phoneNumbers": [{ "label": "mobile", "value": "+1234567890" }],
  "emailAddresses": [{ "label": "work", "value": "john@example.com" }],
  "postalAddresses": [{
    "label": "home",
    "street": "123 Apple St.",
    "city": "Cupertino",
    "state": "CA",
    "postalCode": "95014",
    "country": "USA",
    "isoCountryCode": "US"
  }]
}
```

***

## Important Notes

- All API operations can fail due to reasons such as lack of permission or invalid parameters. Always use `try-catch`.
- User permission is required to access contacts.
- `imageData` should only be fetched if necessary to reduce memory usage.
- Ensure the `identifier` is valid when performing update or delete operations.

***

## Complete Example: Create and Fetch a Contact

```ts
try {
  const contact = await Contact.createContact({
    givenName: 'Alice',
    familyName: 'Smith',
    phoneNumbers: [{ label: 'mobile', value: '+19876543210' }]
  })
  console.log('Contact created:', contact)

  const fetched = await Contact.fetchContact(contact.identifier)
  console.log('Fetched contact:', fetched.givenName)
} catch (error) {
  console.error('Operation failed:', error)
}
```



---
url: /guide/Device Capabilities/Contact/index_example.md
---

# Example

```tsx
import { Script } from "scripting"

async function run() {
  console.present().then(() => {
    Script.exit()
  })

  console.log("Start to fetch contacts")
  try {
    const contacts = await Contact.fetchAllContacts()

    const first = contacts.at(0)

    if (!first) {
      console.log("No contacts found")
    } else {
      console.log("There are " + contacts.length + " contacts")

      const name = [
        first.givenName,
        first.familyName
      ].join(" ")
      
      console.log("First contact name: " + name)
    }
  } catch (e) {
    console.error(e)
  }
}

run()
```



---
url: /guide/Device Capabilities/Device/index.md
---

# Device

The `Device` namespace provides access to information about the current device and its environment, including hardware characteristics, system details, screen metrics, battery status, orientation, proximity sensor state, locale and language settings, wake lock control, and network interfaces.

This API is commonly used to adapt UI layouts, behavior, and feature availability based on the device’s runtime context.

***

## Orientation

Represents the physical orientation of the device.

```ts
type Orientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscapeLeft"
  | "landscapeRight"
  | "faceUp"
  | "faceDown"
  | "unknown"
```

### Description

- `portrait`: Portrait orientation, default upright position
- `portraitUpsideDown`: Portrait orientation, upside down
- `landscapeLeft`: Landscape orientation rotated to the left
- `landscapeRight`: Landscape orientation rotated to the right
- `faceUp`: Device is lying flat with the screen facing upward
- `faceDown`: Device is lying flat with the screen facing downward
- `unknown`: Orientation cannot be determined

***

## InterfaceOrientation

Represents the supported interface orientations for the app.

```ts
type InterfaceOrientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscape"
  | "landscapeLeft"
  | "landscapeRight"
  | "all"
  | "allButUpsideDown"
```

### Description

- `portrait`: Portrait orientation, default upright position
- `portraitUpsideDown`: Portrait orientation, upside down
- `landscape`: Landscape orientation, either left or right
- `landscapeLeft`: Landscape orientation rotated to the left
- `landscapeRight`: Landscape orientation rotated to the right
- `all`: All supported orientations
- `allButUpsideDown`: All supported orientations except upside down

***

## NetworkInterface

Describes a single network interface address.

```ts
type NetworkInterface = {
  address: string
  netmask: string | null
  family: "IPv4" | "IPv6"
  mac: string | null
  isInternal: boolean
  cidr: string | null
}
```

### Properties

- `address`: IP address
- `netmask`: Subnet mask
- `family`: Address family, either IPv4 or IPv6
- `mac`: MAC address (may be null depending on system restrictions)
- `isInternal`: Indicates whether the interface is internal (for example, loopback)
- `cidr`: CIDR notation, such as `192.168.1.10/24`

***

## BatteryState

Represents the current battery state.

```ts
type BatteryState = "full" | "charging" | "unplugged" | "unknown"
```

### Description

- `full`: Battery is fully charged
- `charging`: Device is currently charging
- `unplugged`: Device is not connected to power
- `unknown`: Battery state cannot be determined

***

## Device Information

### model

```ts
const model: string
```

The device model, such as `"iPhone"` or `"iPad"`.

***

### localizedModel

```ts
const localizedModel: string
```

The localized name of the device model.

***

### systemVersion

```ts
const systemVersion: string
```

The current operating system version, for example `"18.2"`.

***

### systemName

```ts
const systemName: string
```

The name of the operating system, such as `"iOS"`, `"iPadOS"`, or `"macOS"`.

***

### isiPad / isiPhone

```ts
const isiPad: boolean
const isiPhone: boolean
```

Indicates whether the current device is an iPad or an iPhone.

***

### screen

```ts
const screen: {
  width: number
  height: number
  scale: number
}
```

Screen metrics:

- `width`: Screen width in logical pixels
- `height`: Screen height in logical pixels
- `scale`: Screen scale factor (for example, 2 or 3)

***

## Battery and Sensors

### batteryState

```ts
const batteryState: BatteryState
```

The current battery state.

***

### batteryLevel

```ts
const batteryLevel: number
```

The current battery level, expressed as a value between `0.0` and `1.0`.

***

### proximityState

```ts
const proximityState: boolean
```

The state of the proximity sensor.
`true` indicates that the device is close to the user, such as during a phone call.

***

## Orientation and Layout

### isLandscape / isPortrait / isFlat

```ts
const isLandscape: boolean
const isPortrait: boolean
const isFlat: boolean
```

- `isLandscape`: Indicates whether the device is in a landscape orientation
- `isPortrait`: Indicates whether the device is in a portrait orientation
- `isFlat`: Indicates whether the device is lying flat (face up or face down)

***

### orientation

```ts
const orientation: Orientation
```

The current physical orientation of the device.

***

### supportedInterfaceOrientations

```ts
var supportedInterfaceOrientations: InterfaceOrientation[]
```

The list of supported interface orientations. You can set this property to limit the orientations that your page supports.

#### Example

```tsx
function Page() {
  useEffect(() => {
    Device.supportedInterfaceOrientations = ["all"]
    return () => {
      Device.supportedInterfaceOrientations = Device.userConfiguredInterfaceOrientations
    }
  }, [])
  return <VStack>...</VStack>
}
```

***

### userConfiguredInterfaceOrientations

```ts
const userConfiguredInterfaceOrientations: InterfaceOrientation[]
```

The list of interface orientations configured by the user. You can use this value to set `supportedInterfaceOrientations` to restore the default interface orientations.

***

## Appearance and Environment

### colorScheme

```ts
const colorScheme: ColorScheme
```

The current system color scheme, such as light or dark mode.

***

### isiOSAppOnMac

```ts
const isiOSAppOnMac: boolean
```

Indicates whether the current process is an iPhone or iPad app running on macOS.

***

## Locale and Language

### systemLocale

```ts
const systemLocale: string
```

The current system locale, for example `"en_US"`.

***

### preferredLanguages

```ts
const preferredLanguages: string[]
```

The user’s preferred languages, for example:

```ts
["en-US", "zh-Hans-CN"]
```

***

### systemLocales (Deprecated)

```ts
const systemLocales: string[]
```

Deprecated. Use `preferredLanguages` instead.

***

### systemLanguageTag

```ts
const systemLanguageTag: string
```

The current language tag, such as `"en-US"`.

***

### systemLanguageCode

```ts
const systemLanguageCode: string
```

The current language code, such as `"en"`.

***

### systemCountryCode

```ts
const systemCountryCode: string | undefined
```

The current country code, such as `"US"`.

***

### systemScriptCode

```ts
const systemScriptCode: string | undefined
```

The script code of the current locale, such as `"Hans"` for Simplified Chinese.

***

## Wake Lock

### isWakeLockEnabled

```ts
const isWakeLockEnabled: Promise<boolean>
```

Retrieves whether the wake lock is currently enabled, preventing the device from automatically sleeping.

***

### setWakeLockEnabled

```ts
function setWakeLockEnabled(enabled: boolean): void
```

Enables or disables the wake lock.

Notes:

- Available only in the **Scripting app**
- When enabled, the device will remain awake and not auto-lock

***

## Battery Listeners

### addBatteryStateListener

```ts
function addBatteryStateListener(
  callback: (state: BatteryState) => void
): void
```

Registers a listener for battery state changes.

***

### removeBatteryStateListener

```ts
function removeBatteryStateListener(
  callback?: (state: BatteryState) => void
): void
```

Removes a battery state listener.
If `callback` is not provided, all battery state listeners are removed.

***

### addBatteryLevelListener

```ts
function addBatteryLevelListener(
  callback: (level: number) => void
): void
```

Registers a listener for battery level changes.

***

### removeBatteryLevelListener

```ts
function removeBatteryLevelListener(
  callback?: (level: number) => void
): void
```

Removes a battery level listener.
If `callback` is not provided, all battery level listeners are removed.

***

## Orientation Listeners

### addOrientationListener

```ts
function addOrientationListener(
  callback: (orientation: Orientation) => void
): void
```

Starts observing device orientation changes.

Notes:

- This method must be called before orientation updates are delivered
- Orientation updates do not work when system orientation lock is enabled

***

### removeOrientationListener

```ts
function removeOrientationListener(
  callback?: (orientation: Orientation) => void
): void
```

Removes an orientation change listener.
If `callback` is not provided, all orientation listeners are removed and observation is stopped.

***

## Proximity Listeners

### addProximityStateListener

```ts
function addProximityStateListener(
  callback: (state: boolean) => void
): void
```

Registers a listener for proximity sensor state changes.

***

### removeProximityStateListener

```ts
function removeProximityStateListener(
  callback?: (state: boolean) => void
): void
```

Removes a proximity state listener.
If `callback` is not provided, all proximity listeners are removed.

***

## Network

### networkInterfaces

```ts
function networkInterfaces(): Record<string, NetworkInterface[]>
```

Returns the network interfaces available on the device.

Return value:

- Keys are interface names (such as `en0`, `lo0`)
- Values are arrays of `NetworkInterface` objects associated with each interface

This method is useful for network diagnostics, retrieving local IP addresses, and debugging connectivity issues.



---
url: /guide/Device Capabilities/Device/index_example.md
---

# Example

```tsx
import { Button, Device, List, Navigation, NavigationStack, Script, Text, VStack } from "scripting"

 function Example() {
  const dismiss = Navigation.useDismiss()

  const details: {
    name: string
    value: string | boolean | number
  }[] = [
      {
        name: "Device.isiPhone",
        value: Device.isiPhone
      },
      {
        name: "Device.isiPad",
        value: Device.isiPad,
      },
      {
        name: "Device.systemVersion",
        value: Device.systemVersion,
      },
      {
        name: "Device.systemName",
        value: Device.systemName,
      },
      {
        name: "Device.isPortrait",
        value: Device.isPortrait,
      },
      {
        name: "Device.isLandscape",
        value: Device.isLandscape,
      },
      {
        name: "Device.isFlat",
        value: Device.isFlat,
      },
      {
        name: "Device.batteryLevel",
        value: Device.batteryLevel,
      },
      {
        name: "Device.batteryState",
        value: Device.batteryState,
      }
    ]

  return <NavigationStack>
    <List
      navigationTitle={"Device"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      {details.map(item =>
        <VStack
          badge={item.value.toString()}
          alignment={"leading"}
        >
          <Text font={"headline"}>{item.name}</Text>
          <Text font={"caption"}>{typeof item.value}</Text>
        </VStack>
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/DocumentInteraction/index.md
---

# DocumentInteraction

The `DocumentInteraction` interface presents the system **"Open in…"** menu (and the fuller options menu) for a file, letting the user pick an app to open or copy the file with.

> **There is no "open in default app" on iOS.** iOS has no concept of a default app per file type, and no public API to open a file directly in its associated app. Presenting this menu and letting the user choose is the only supported way to hand a file to another app.

## API

```ts
namespace DocumentInteraction {
  // "Open in…" menu — only the apps that can open/copy the file.
  function openInMenu(filePath: string): Promise<string | null>

  // Full options menu — Open in… plus Copy / Print / Save to Files / Markup, etc.
  function optionsMenu(filePath: string): Promise<string | null>
}
```

Both resolve to the **bundle identifier** of the app the file was sent to, or `null` if the user dismissed the menu without choosing an app (for `optionsMenu`, `null` also covers performing a non-open action such as Copy).

- `openInMenu` **rejects** if the file does not exist, or if no app is available to open it.
- `optionsMenu` **rejects** if the file does not exist.

On iPad the menu is shown as a popover anchored to the center of the current page.

## Example

```tsx
const path = FileManager.documentsDirectory + "/report.pdf"

try {
  const app = await DocumentInteraction.openInMenu(path)
  if (app != null) {
    console.log("Opened in:", app) // e.g. "com.apple.mobilenotes"
  } else {
    console.log("User dismissed the menu.")
  }
} catch (e) {
  // File missing, or no app can open this file type.
  console.error(e)
}
```

## Notes

- `filePath` must be the absolute path of an existing file.
- For files obtained from a document picker (security-scoped), make sure your script holds access to the file before presenting the menu.
- The file's display name comes from its file name; the file type is inferred from its extension.



---
url: /guide/Device Capabilities/DocumentInteraction/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text } from "scripting"

// 准备一个示例文件,返回其绝对路径。
async function makeSampleFile(): Promise<string> {
  const path = FileManager.documentsDirectory + "/document-interaction-sample.txt"
  await FileManager.writeAsString(path, "Hello from Scripting!\nPick an app to open this file.")
  return path
}

function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"DocumentInteraction"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        footer={<Text>Presents the system "Open in…" menu so the user can pick an app to open the file with. iOS has no API to open a file directly in its default app.</Text>}
      >
        <Button
          title={"openInMenu"}
          action={async () => {
            try {
              const path = await makeSampleFile()
              const app = await DocumentInteraction.openInMenu(path)
              await Dialog.alert({
                message: app != null ? `Opened in: ${app}` : "Dismissed without choosing an app.",
              })
            } catch (e) {
              await Dialog.alert({ title: "Failed", message: String(e) })
            }
          }}
        />

        <Button
          title={"optionsMenu"}
          action={async () => {
            try {
              const path = await makeSampleFile()
              const app = await DocumentInteraction.optionsMenu(path)
              await Dialog.alert({
                message: app != null ? `Opened in: ${app}` : "Dismissed, or a non-open action was performed.",
              })
            } catch (e) {
              await Dialog.alert({ title: "Failed", message: String(e) })
            }
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/DocumentPicker.md
---

# DocumentPicker

The `DocumentPicker` class provides an interface to the iOS document picker, allowing users to select files or directories and export files from within the Files app. This is useful for scripts that need to access user files, share content, or organize resources in a specified directory.

## Type Definitions

### `PickFilesOption`

Options for configuring file selection with `pickFiles`.

- **`initialDirectory`** (optional)
  - _Type_: `string`
  - _Description_: Specifies the initial directory that the document picker displays.

- **`types`** (optional)
  - _Type_: `string[]`
  - _Description_: An array of uniform type identifiers (UTIs) for the document picker to display. For more details, see [Uniform Type Identifiers](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct).

- **`shouldShowFileExtensions`** (optional)
  - _Type_: `boolean`
  - _Description_: Indicates if file extensions should be visible. Defaults to `true`.

- **`allowsMultipleSelection`** (optional)
  - _Type_: `boolean`
  - _Description_: Allows selecting multiple files. Defaults to `false`.

### `PickFileBookmarkOptions`

Options for picking a file and saving it as a persistent bookmark.

- **`preferredName`** (optional)
  - _Type_: `string`
  - _Description_: The preferred bookmark name. If omitted, the selected file name is used. If the name already exists, the user will be asked to choose another name.

- **`initialDirectory`** (optional)
  - _Type_: `string`
  - _Description_: Specifies the initial directory that the document picker displays.

- **`types`** (optional)
  - _Type_: `string[]`
  - _Description_: An array of uniform type identifiers (UTIs) for the document picker to display.

- **`shouldShowFileExtensions`** (optional)
  - _Type_: `boolean`
  - _Description_: Indicates if file extensions should be visible. Defaults to `true`.

### `PickDirectoryBookmarkOptions`

Options for picking a directory and saving it as a persistent bookmark.

- **`preferredName`** (optional)
  - _Type_: `string`
  - _Description_: The preferred bookmark name. If omitted, the selected directory name is used. If the name already exists, the user will be asked to choose another name.

- **`initialDirectory`** (optional)
  - _Type_: `string`
  - _Description_: Specifies the initial directory that the document picker displays.

### `DocumentPickerBookmarkResult`

The result returned after saving a bookmark.

- **`path`**
  - _Type_: `string`
  - _Description_: The selected file or directory path.

- **`bookmarkName`**
  - _Type_: `string`
  - _Description_: The saved bookmark name. This may differ from `preferredName` if the user renamed it.

### `ExportFilesOptions`

Options for exporting files using `exportFiles`.

- **`initialDirectory`** (optional)
  - _Type_: `string`
  - _Description_: Specifies the initial directory that the document picker displays.

- **`files`**
  - _Type_: `Array<{ data: Data; name: string }>`
  - _Description_: An array of files to be exported. Each file object must contain:
    - **`data`**: The file data.
    - **`name`**: The file name.

## Class Methods

### `DocumentPicker.pickFiles(options?: PickFilesOption): Promise<string[]>`

Allows users to pick files from the Files app.

#### Parameters

- **`options`** (optional): `PickFilesOption`
  - Configuration options for file selection.

#### Returns

- A promise that resolves with an array of file paths (`string[]`).

#### Example

```typescript
async function run() {
  const imageFilePath = await DocumentPicker.pickFiles()
  if (imageFilePath != null) {
    // Handle the selected file paths
  }
}
run()
```

### `DocumentPicker.pickDirectory(initialDirectory?: string): Promise<string | null>`

Allows users to pick a directory from the Files app.

#### Parameters

- **`initialDirectory`** (optional): `string`
  - The initial directory that the document picker displays.

#### Returns

- A promise that resolves with the selected directory path as a `string`, or `null` if the user canceled the picker.

#### Example

```typescript
const selectedDirectory = await DocumentPicker.pickDirectory()
if (selectedDirectory == null) {
  // User canceled the picker
}
```

### `DocumentPicker.pickFileBookmark(options?: PickFileBookmarkOptions): Promise<DocumentPickerBookmarkResult | null>`

Allows users to pick a file from the Files app and save it as a persistent security-scoped bookmark.

`pickFiles` only starts access for the current script run and releases it when the script is destroyed or `stopAcessingSecurityScopedResources()` is called. `pickFileBookmark` stores a bookmark so future script runs can access the selected file through `FileManager.bookmarkedPath(bookmarkName)`.

#### Parameters

- **`options`** (optional): `PickFileBookmarkOptions`
  - Configuration options for file selection and the bookmark name.

#### Returns

- A promise that resolves with `{ path, bookmarkName }`, or `null` if the user canceled the picker or bookmark naming.

#### Example

```typescript
const result = await DocumentPicker.pickFileBookmark({
  preferredName: "My Config",
  types: ["public.json"],
})

if (result != null) {
  console.log(result.path)
  console.log(FileManager.bookmarkedPath(result.bookmarkName))
}
```

### `DocumentPicker.pickDirectoryBookmark(options?: PickDirectoryBookmarkOptions): Promise<DocumentPickerBookmarkResult | null>`

Allows users to pick a directory from the Files app and save it as a persistent security-scoped bookmark.

`pickDirectory` only starts access for the current script run and releases it when the script is destroyed or `stopAcessingSecurityScopedResources()` is called. `pickDirectoryBookmark` stores a bookmark so future script runs can access the selected directory through `FileManager.bookmarkedPath(bookmarkName)`.

#### Parameters

- **`options`** (optional): `PickDirectoryBookmarkOptions`
  - Configuration options for directory selection and the bookmark name.

#### Returns

- A promise that resolves with `{ path, bookmarkName }`, or `null` if the user canceled the picker or bookmark naming.

#### Example

```typescript
const result = await DocumentPicker.pickDirectoryBookmark({
  preferredName: "Workspace",
})

if (result != null) {
  const directory = FileManager.bookmarkedPath(result.bookmarkName)
  console.log(directory)
}
```

### `DocumentPicker.exportFiles(options: ExportFilesOptions): Promise<string[]>`

Exports files to the Files app.

#### Parameters

- **`options`**: `ExportFilesOptions`
  - Configuration options for file export, including file data and names.

#### Returns

- A promise that resolves with an array of exported file paths (`string[]`).

#### Example

```typescript
async function run() {
  const textContent = "Hello Scripting!"
  const result = await DocumentPicker.exportFiles({
    files: [
      {
        data: Data.fromString(textContent)!,
        name: 'greeting.txt',
      }
    ]
  });

  if (result.length > 0) {
    console.log('Exported files: ', result)
  }
}
run()
```

### `DocumentPicker.stopAcessingSecurityScopedResources(): void`

Relinquishes access to security-scoped resources, like files or directories accessed via the document picker. Use this method when you no longer need access to these resources to ensure your app manages resources efficiently.



---
url: /guide/Device Capabilities/EventAlarm.md
---

# EventAlarm

`EventAlarm` represents a reminder rule that can be attached to both **CalendarEvent** and **Reminder** objects.
It supports three major alarm types:

- **Absolute-time alarms**
- **Relative alarms** (relative to an event’s start time)
- **Location-based alarms** (geofence triggers)

This class aligns with the behavior of iOS EventKit alarms and provides flexible notification capabilities across calendar and reminder data.

***

## 1. Creating an Alarm

### EventAlarm.fromAbsoluteDate(date: Date): EventAlarm

Creates an alarm that fires at a specific, absolute moment in time.

- Independent from the event’s `startDate`
- Triggers when the system time reaches the specified date

Example:

```ts
const alarm = EventAlarm.fromAbsoluteDate(new Date("2025-01-01T09:00:00"))
```

***

### EventAlarm.fromRelativeOffset(offset: DurationInSeconds): EventAlarm

Creates an alarm that fires relative to the event’s start time.

`offset` interpretation:

- Negative value: fires _before_ the event starts
- Positive value: fires _after_ the event starts

Example (alarm 10 minutes before the event):

```ts
const alarm = EventAlarm.fromRelativeOffset(-600)
```

***

## 2. Properties

### absoluteDate: Date | null

The absolute date on which the alarm fires.

Behavior:

- Setting this property on a **relative alarm** converts it into an absolute alarm and clears `relativeOffset`.
- When `null`, the alarm may be relative or location-based.

***

### relativeOffset: number

Time offset in seconds from the event’s start time.

Behavior:

- Setting this property on an **absolute alarm** converts the alarm into a relative alarm and clears `absoluteDate`.
- Always measured relative to the `startDate` of a CalendarEvent or Reminder.

Example:

```ts
alarm.relativeOffset = -300  // fire 5 minutes before
```

***

### structuredLocation: EventStructuredLocation | null

Defines the location used for location-based alarms.

`EventStructuredLocation` contains:

- `title: string | null` – Human-readable name
- `geoLocation: LocationInfo | null` – Latitude/longitude
- `radius: number` – Geofence radius in meters

Example:

```ts
alarm.structuredLocation = {
  title: "Office",
  geoLocation: { latitude: 37.332, longitude: -122.030 },
  radius: 100
}
```

***

### proximity: AlarmProximity

Defines how the location alarm is triggered.

| Value   | Meaning                                 |
| ------- | --------------------------------------- |
| `none`  | Default; no location trigger            |
| `enter` | Trigger when the user enters the region |
| `leave` | Trigger when the user exits the region  |

Example:

```ts
alarm.proximity = AlarmProximity.enter
```

***

## 3. Usage in CalendarEvent and Reminder APIs

### Using EventAlarm with CalendarEvent

```ts
const event = new CalendarEvent()
event.title = "Team Meeting"
event.startDate = ...
event.endDate = ...

const alarm = EventAlarm.fromRelativeOffset(-900) // 15 min before
event.addAlarm(alarm)

await event.save()
```

***

### Using EventAlarm with Reminder

Reminders also support alarms:

```ts
const reminder = new Reminder()
reminder.title = "Pay Electricity Bill"

const alarm = EventAlarm.fromAbsoluteDate(new Date("2025-02-01T10:00:00"))
reminder.addAlarm(alarm)

await reminder.save()
```

Location-based alarms work for reminders as well.

***

## 4. Best Practices

1. **Use absolute alarms** for fixed calendar moments (e.g., birthdays, bill due dates).
2. **Use relative alarms** when the trigger depends on the event’s start time (e.g., meeting reminders).
3. **Use geofence alarms** for contextual triggers (e.g., remind me to pick up a package when I get home).
4. Location alarms require appropriate location permissions from the user.



---
url: /guide/Device Capabilities/FontPicker.md
---

# FontPicker

The `FontPicker` namespace provides methods for selecting fonts from the system’s available font list.
It opens the system font picker UI, allowing the user to choose a font, and returns the **PostScript name** of the selected font.

***

## Overview

In scenarios such as custom text editors, UI design, or typography styling, users may need to select a font dynamically.
`FontPicker` offers a simple asynchronous interface to display the system’s font picker and obtain the selected font name.

***

## Methods

### `pickFont(): Promise<string | null>`

Opens the system font picker interface and lets the user select a font.
Returns a Promise that resolves when the user either selects a font or cancels the picker.

**Return Value:**

- `string` — The **PostScript name** of the selected font (e.g., `"Helvetica-Bold"`, `"KaitiSC-Regular"`).
- `null` — Returned if the user cancels the picker.

***

## Example

```ts
const fontPostscriptName = await FontPicker.pickFont()
if (fontPostscriptName == null) {
  // User canceled the font picker
  console.log("Font selection canceled")
} else {
  console.log("Selected font:", fontPostscriptName)
}
```

Example output:

```
Selected font: HelveticaNeue-Bold
```

***

## Usage Notes

- The returned font name can be used directly in text rendering or UI styling contexts.
- If the user cancels the selection, the return value is `null`; your code should handle this case gracefully.
- The fonts displayed in the picker depend on the fonts currently installed on the system, including both built-in and user-installed fonts.

***

## Summary

| Method       | Return Type               | Description                                                                                             |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------- |
| `pickFont()` | `Promise<string \| null>` | Opens the system font picker and returns the PostScript name of the selected font or `null` if canceled |



---
url: /guide/Device Capabilities/HapticFeedback.md
---

# HapticFeedback

```tsx
import { Button, List, Navigation, NavigationStack, Script, } from "scripting"

function Example() {

  return <NavigationStack>
    <List
      navigationTitle={"HapticFeedback"}
    >
      <Button
        title={"HapticFeedback.vibrate"}
        action={() => {
          HapticFeedback.vibrate()
        }}
      />

      <Button
        title={"HapticFeedback.lightImpact"}
        action={() => {
          HapticFeedback.lightImpact()
        }}
      />

      <Button
        title={"HapticFeedback.mediumImpact"}
        action={() => {
          HapticFeedback.mediumImpact()
        }}
      />

      <Button
        title={"HapticFeedback.heavyImpact"}
        action={() => {
          HapticFeedback.heavyImpact()
        }}
      />

      <Button
        title={"HapticFeedback.softImpact"}
        action={() => {
          HapticFeedback.softImpact()
        }}
      />

      <Button
        title={"HapticFeedback.rigidImpact"}
        action={() => {
          HapticFeedback.rigidImpact()
        }}
      />

      <Button
        title={"HapticFeedback.selection"}
        action={() => {
          HapticFeedback.selection()
        }}
      />

      <Button
        title={"HapticFeedback.notificationSuccess"}
        action={() => {
          HapticFeedback.notificationSuccess()
        }}
      />

      <Button
        title={"HapticFeedback.notificationError"}
        action={() => {
          HapticFeedback.notificationError()
        }}
      />

      <Button
        title={"HapticFeedback.notificationWarning"}
        action={() => {
          HapticFeedback.notificationWarning()
        }}
      />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/Health/HealthActivitySummary.md
---

# HealthActivitySummary

The `HealthActivitySummary` class provides an interface for accessing daily summaries of user activity as recorded by the Apple Health system. This includes move, exercise, and stand metrics, and optionally supports both energy-based and time-based activity move goals.

This class is useful for apps that aim to present a user's daily activity rings or generate daily fitness reports.

***

## Use Cases

- Displaying daily activity ring progress (Move, Exercise, Stand)
- Comparing user activity against daily goals
- Building custom health dashboards and fitness visualizations
- Providing trend analysis or goal reminders

***

## Class: `HealthActivitySummary`

### Properties

| Property           | Type                     | Description                                                                                                           |
| ------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `dateComponents`   | `DateComponents`         | Represents the calendar date associated with this activity summary.                                                   |
| `activityMoveMode` | `HealthActivityMoveMode` | Indicates the move mode used for this summary — either active energy (`activeEnergy`) or move time (`appleMoveTime`). |

***

### Methods

Each of the following methods returns a numeric value representing either the achieved metric or the goal for that metric on the specified date. All values are returned in the unit specified by the caller.

#### `activeEnergyBurned(unit: HealthUnit): number`

Returns the amount of active energy burned for the day in the given unit (e.g., kilocalories).

#### `activeEnergyBurnedGoal(unit: HealthUnit): number`

Returns the daily goal for active energy burned in the given unit.

> Only valid when `activityMoveMode` is `HealthActivityMoveMode.activeEnergy`.

***

#### `appleMoveTime(unit: HealthUnit): number`

Returns the duration of movement (in minutes or seconds) tracked by the Apple Watch's move time mode.

#### `appleMoveTimeGoal(unit: HealthUnit): number`

Returns the goal for move time on the current day.

> Only valid when `activityMoveMode` is `HealthActivityMoveMode.appleMoveTime`.

***

#### `appleExerciseTime(unit: HealthUnit): number`

Returns the total time spent in exercise (typically in minutes), as measured by the Apple Watch.

#### `appleExerciseTimeGoal(unit: HealthUnit): number`

Returns the exercise time goal for the current day.

***

#### `appleStandHours(unit: HealthUnit): number`

Returns the number of hours in which the user stood and moved for at least one minute.

#### `appleStandHoursGoal(unit: HealthUnit): number`

Returns the user's stand hours goal for the day (typically 12).

***

## Example Usage

```ts
async function showTodaySummary() {
  const startDate = new Date()
  startDate.setHours(0, 0, 0, 0)

  const start = DateComponents.fromDate(startDate)
  const end = DateComponents.fromDate(startDate)
  end.date += 1

  const summaries = await Health.queryActivitySummaries({
    start, // today
    end,
  })

  if (summaries.length === 0) {
    console.log('No activity summary available for today.')
    return
  }

  const summary = summaries[0]

  console.log('Date:', summary.dateComponents)
  console.log('Move Mode:', summary.activityMoveMode)

  const kcal = summary.activeEnergyBurned(HealthUnit.kilocalorie())
  const kcalGoal = summary.activeEnergyBurnedGoal(HealthUnit.kilocalorie())

  console.log(`Active Energy Burned: ${kcal} / ${kcalGoal} kcal`)
  console.log(`Exercise Time: ${summary.appleExerciseTime(HealthUnit.minute())} min`)
  console.log(`Stand Hours: ${summary.appleStandHours(HealthUnit.count())} hr`)
}
```

***

## Notes

- `HealthActivitySummary` does not store historical trend data. Use multiple summaries to build a timeline.
- Depending on the user's Apple Watch settings, the move goal can be based on energy burned or move time.
- All returned values are numeric and can be formatted or converted further based on your needs.
- `HealthUnit` must match the type of data requested. For time-based values, use `HealthUnit.minute()` or `HealthUnit.second()`. For count-based values like stand hours, use `HealthUnit.count()`.



---
url: /guide/Device Capabilities/Health/HealthCategorySample.md
---

# HealthCategorySample

The `HealthCategorySample` class represents an individual category-based health record, such as a sleep session, menstrual flow level, or a test result. These samples are used to store discrete events or conditions over time, usually characterized by a start and end date along with a categorical value.

***

## Overview

This class is suitable for:

- Tracking and analyzing time-bound health events (e.g., sleep analysis)
- Recording categorical values with a specific time interval (e.g., "present" or "not present")
- Manually creating samples for use with HealthKit-compatible export or analysis

***

## Properties

| Property       | Type                          | Description                                                                       |
| -------------- | ----------------------------- | --------------------------------------------------------------------------------- |
| `uuid`         | `string`                      | A unique identifier for the sample.                                               |
| `categoryType` | `HealthCategoryType`          | The category type of the sample (e.g., `sleepAnalysis`, `sexualActivity`).        |
| `startDate`    | `Date`                        | The start date and time of the recorded event.                                    |
| `endDate`      | `Date`                        | The end date and time of the recorded event.                                      |
| `value`        | `number`                      | The categorical value for the sample, from a specific `HealthCategoryValue` enum. |
| `metadata`     | `Record<string, any> \| null` | Optional additional metadata about the sample (e.g., source, notes).              |

***

## Method: `static create(...)`

Creates a new `HealthCategorySample` instance using the specified parameters.

### Signature

```ts
static create(options: {
  type: HealthCategoryType
  startDate: Date
  endDate: Date
  value: HealthCategoryValueAppetiteChanges | HealthCategoryValueAppleStandHour | HealthCategoryValueAppleWalkingSteadinessEvent | HealthCategoryValueCervicalMucusQuality | HealthCategoryValueContraceptive | HealthCategoryValueEnvironmentalAudioExposureEvent | HealthCategoryValueHeadphoneAudioExposureEvent | HealthCategoryValueLowCardioFitnessEvent | HealthCategoryValueOvulationTestResult | HealthCategoryValuePregnancyTestResult | HealthCategoryValuePresence | HealthCategoryValueProgesteroneTestResult | HealthCategoryValueSeverity | HealthCategoryValueSleepAnalysis | HealthCategoryValueVaginalBleeding
  metadata?: Record<string, any> | null
}): HealthCategorySample | null
```

### Parameters

| Parameter   | Type                                    | Description                                           |
| ----------- | --------------------------------------- | ----------------------------------------------------- |
| `type`      | `HealthCategoryType`                    | The category type this sample represents.             |
| `startDate` | `Date`                                  | When the health event began.                          |
| `endDate`   | `Date`                                  | When the health event ended.                          |
| `value`     | One of the `HealthCategoryValue*` enums | The specific categorical value. Must match the type.  |
| `metadata`  | Optional `Record<string, any>`          | Optional data such as annotations or tracking source. |

### Returns

- A `HealthCategorySample` instance if the inputs are valid.
- `null` if the parameters are invalid (e.g., value/type mismatch).

***

## Usage Examples

### 1. Creating a Sleep Analysis Sample

```ts
const sample = HealthCategorySample.create({
  type: 'sleepAnalysis',
  startDate: new Date('2025-07-01T23:00:00'),
  endDate: new Date('2025-07-02T06:00:00'),
  value: HealthCategoryValueSleepAnalysis.asleep,
  metadata: { source: 'manual entry' }
})

if (sample) {
  console.log(`Created sleep sample from ${sample.startDate} to ${sample.endDate}`)
}
```

### 2. Logging a Sexual Activity Event

```ts
const event = HealthCategorySample.create({
  type: 'sexualActivity',
  startDate: new Date('2025-07-03T22:30:00'),
  endDate: new Date('2025-07-03T22:40:00'),
  value: HealthCategoryValuePresence.present
})
```

### 3. Tracking Ovulation Test Result

```ts
const result = HealthCategorySample.create({
  type: 'ovulationTestResult',
  startDate: new Date('2025-07-05T08:00:00'),
  endDate: new Date('2025-07-05T08:05:00'),
  value: HealthCategoryValueOvulationTestResult.positive
})
```

***

## Notes on `value`

The `value` field must be a valid enum value for the given category type. For example:

- `sleepAnalysis` must use `HealthCategoryValueSleepAnalysis`
- `sexualActivity` must use `HealthCategoryValuePresence`
- `menstrualFlow` must use `HealthCategoryValueSeverity`
- `ovulationTestResult` must use `HealthCategoryValueOvulationTestResult`

If the value and type do not match, the sample creation will fail and return `null`.

***

## Common Use Cases

| Type                              | Value Enum                                           | Use Case Example       |
| --------------------------------- | ---------------------------------------------------- | ---------------------- |
| `sleepAnalysis`                   | `HealthCategoryValueSleepAnalysis`                   | Sleep tracking apps    |
| `sexualActivity`                  | `HealthCategoryValuePresence`                        | Lifestyle logging      |
| `menstrualFlow`                   | `HealthCategoryValueSeverity`                        | Menstrual health apps  |
| `pregnancyTestResult`             | `HealthCategoryValuePregnancyTestResult`             | Fertility tracking     |
| `appleStandHour`                  | `HealthCategoryValueAppleStandHour`                  | Stand reminder history |
| `environmentalAudioExposureEvent` | `HealthCategoryValueEnvironmentalAudioExposureEvent` | Noise alerts tracking  |



---
url: /guide/Device Capabilities/Health/HealthCategoryType.md
---

# HealthCategoryType

The `HealthCategoryType` identifies discrete health-related states or events, often recorded as binary values (e.g., present or not present) or discrete outcomes. These are commonly used for tracking symptoms, reproductive health, audio exposure events, and sleep states.

***

## 1. Apple Events and System Health

| Identifier                        | Description                                             |
| --------------------------------- | ------------------------------------------------------- |
| `appleStandHour`                  | Indicates whether the user stood up during an hour      |
| `environmentalAudioExposureEvent` | Notifies of high environmental noise exposure           |
| `headphoneAudioExposureEvent`     | Indicates potentially harmful headphone volume exposure |
| `highHeartRateEvent`              | Detects unusually high heart rate during inactivity     |
| `lowHeartRateEvent`               | Detects unusually low heart rate                        |
| `irregularHeartRhythmEvent`       | Flags irregular heart rhythms (e.g., AFib)              |
| `lowCardioFitnessEvent`           | Indicates low cardio fitness level                      |
| `appleWalkingSteadinessEvent`     | Indicates risk of falling due to walking instability    |

***

## 2. Mindfulness and Hygiene

| Identifier           | Description                                     |
| -------------------- | ----------------------------------------------- |
| `mindfulSession`     | Logs a mindfulness session                      |
| `handwashingEvent`   | Detects handwashing activity (Apple Watch)      |
| `toothbrushingEvent` | Logs toothbrushing sessions (e.g., via sensors) |

***

## 3. Reproductive and Menstrual Health

| Identifier                         | Description                                 |
| ---------------------------------- | ------------------------------------------- |
| `menstrualFlow`                    | Records menstrual bleeding and its severity |
| `intermenstrualBleeding`           | Bleeding between menstrual periods          |
| `prolongedMenstrualPeriods`        | Periods longer than usual                   |
| `infrequentMenstrualCycles`        | Infrequent cycle occurrence                 |
| `irregularMenstrualCycles`         | Irregular cycle patterns                    |
| `persistentIntermenstrualBleeding` | Ongoing bleeding between cycles             |
| `bleedingDuringPregnancy`          | Bleeding while pregnant                     |
| `bleedingAfterPregnancy`           | Postpartum bleeding                         |
| `pregnancy`                        | Indicates whether the user is pregnant      |
| `lactation`                        | Indicates breastfeeding or milk production  |
| `sexualActivity`                   | Logs sexual activity                        |
| `ovulationTestResult`              | Ovulation test result (positive, negative)  |
| `pregnancyTestResult`              | Pregnancy test result                       |
| `progesteroneTestResult`           | Progesterone test outcome                   |
| `contraceptive`                    | Contraceptive method being used             |
| `cervicalMucusQuality`             | Tracks type of cervical mucus               |

***

## 4. Sleep and Breathing

| Identifier        | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `sleepAnalysis`   | Sleep duration and categorization (e.g., in bed, asleep) |
| `sleepApneaEvent` | Detected apnea event during sleep                        |

***

## 5. Symptoms and Conditions

| Identifier                           | Description                                      |
| ------------------------------------ | ------------------------------------------------ |
| `abdominalCramps`                    | Stomach or menstrual cramps                      |
| `acne`                               | Acne severity                                    |
| `appetiteChanges`                    | Increase or decrease in appetite                 |
| `bladderIncontinence`                | Urinary control issues                           |
| `bloating`                           | Feeling of abdominal swelling                    |
| `breastPain`                         | Pain or tenderness in the breast                 |
| `chestTightnessOrPain`               | Tightness or discomfort in the chest             |
| `chills`                             | Sudden feeling of cold without cause             |
| `constipation`                       | Difficulty passing stool                         |
| `coughing`                           | Cough symptom                                    |
| `diarrhea`                           | Loose or watery stools                           |
| `dizziness`                          | Feeling lightheaded or unsteady                  |
| `drySkin`                            | Skin dryness                                     |
| `fainting`                           | Temporary loss of consciousness                  |
| `fatigue`                            | General tiredness or low energy                  |
| `fever`                              | Elevated body temperature                        |
| `generalizedBodyAche`                | Full body soreness or aching                     |
| `hairLoss`                           | Notable hair thinning or shedding                |
| `headache`                           | Head pain                                        |
| `heartburn`                          | Burning sensation in chest or throat             |
| `hotFlashes`                         | Sudden feeling of warmth (commonly in menopause) |
| `lossOfSmell`                        | Anosmia (loss of smell)                          |
| `lossOfTaste`                        | Ageusia (loss of taste)                          |
| `lowerBackPain`                      | Pain in the lower back                           |
| `memoryLapse`                        | Difficulty remembering                           |
| `moodChanges`                        | Mood swings or emotional variation               |
| `nausea`                             | Sensation of wanting to vomit                    |
| `nightSweats`                        | Sweating during sleep                            |
| `pelvicPain`                         | Pain in the lower abdominal area                 |
| `rapidPoundingOrFlutteringHeartbeat` | Palpitations or abnormal heart rhythms           |
| `runnyNose`                          | Nasal discharge                                  |
| `shortnessOfBreath`                  | Difficulty breathing                             |
| `sinusCongestion`                    | Nasal blockage due to sinus inflammation         |
| `skippedHeartbeat`                   | Noticeable skipped or irregular heartbeats       |
| `sleepChanges`                       | Changes in sleep quality or duration             |
| `soreThroat`                         | Throat irritation or pain                        |
| `vaginalDryness`                     | Lack of natural vaginal lubrication              |
| `vomiting`                           | Expelling stomach contents                       |
| `wheezing`                           | Whistling sound while breathing                  |

***

## Use Cases

- **Reproductive Health Apps**: Use types like `menstrualFlow`, `ovulationTestResult`, `pregnancy`, and `lactation` to help users track fertility and cycles.
- **Mindfulness and Lifestyle**: Use `mindfulSession`, `handwashingEvent`, and `toothbrushingEvent` for promoting daily habits.
- **Sleep and Heart Monitoring**: Use `sleepAnalysis`, `sleepApneaEvent`, and heart rhythm-related types to provide nighttime and cardiovascular insights.
- **Symptom Trackers**: Use symptom-related types (e.g., `fatigue`, `fever`, `nausea`) in journaling, recovery, or diagnostics support apps.

***

## Example: Save a Sleep Stage Sample

```ts
const sample = HealthCategorySample.create({
  type: "sleepAnalysis",
  startDate: new Date("2025-07-03T22:30:00"),
  endDate: new Date("2025-07-04T06:30:00"),
  value: HealthCategoryValueSleepAnalysis.asleepDeep
})

await Health.saveCategorySample(sample)
```

***

## Example: Query Mindful Sessions

```ts
const results = await Health.queryCategorySamples({
  type: "mindfulSession",
  startDate: new Date("2025-07-01"),
  endDate: new Date("2025-07-05")
})

for (const session of results) {
  console.log("From", session.startDate, "to", session.endDate)
}
```

***

## Notes

- The `value` provided to a category sample must match the expected enum for the given `type`.
- If the `value` does not match the required category value type, the `create()` method will return `null`.
- Samples must span at least one second (`endDate > startDate`).



---
url: /guide/Device Capabilities/Health/HealthCategoryValue Types.md
---

# HealthCategoryValue Types

This document provides a comprehensive reference for all supported `HealthCategoryValue` enums used with `HealthCategorySample.create()` and related APIs. Each enum represents a specific categorical value associated with a `HealthCategoryType`.

***

## 1. `HealthCategoryValuePresence`

**Applicable Types:**

- `mindfulSession`
- `intermenstrualBleeding`
- `sexualActivity`
- `pregnancy`
- `lactation`

**Description:** Indicates the presence or absence of an event.

| Value        | Meaning                 |
| ------------ | ----------------------- |
| `present`    | The event occurred      |
| `notPresent` | The event did not occur |

***

## 2. `HealthCategoryValueSeverity`

**Applicable Types:**

- `menstrualFlow`
- `acneSeverity`
- `hairLossSeverity`
- `abdominalCramps`
- `headache`
- `nausea`

**Description:** Represents the severity level of a symptom.

| Value         | Meaning           |
| ------------- | ----------------- |
| `unspecified` | Not specified     |
| `notPresent`  | Not present       |
| `mild`        | Mild severity     |
| `moderate`    | Moderate severity |
| `severe`      | Severe            |

***

## 3. `HealthCategoryValueSleepAnalysis`

**Applicable Types:**

- `sleepAnalysis`

**Description:** Categorizes sleep states during a given time range.

| Value               | Meaning                         |
| ------------------- | ------------------------------- |
| `inBed`             | In bed (not necessarily asleep) |
| `asleepUnspecified` | Asleep (unspecified phase)      |
| `awake`             | Awake                           |
| `asleepCore`        | Core sleep                      |
| `asleepDeep`        | Deep sleep                      |
| `asleepREM`         | REM sleep                       |

***

## 4. `HealthCategoryValueOvulationTestResult`

**Applicable Types:**

- `ovulationTestResult`

| Value                     | Meaning                              |
| ------------------------- | ------------------------------------ |
| `negative`                | No LH surge detected                 |
| `luteinizingHormoneSurge` | LH surge detected (ovulation likely) |
| `indeterminate`           | Result unclear                       |
| `estrogenSurge`           | Estrogen surge detected              |

***

## 5. `HealthCategoryValuePregnancyTestResult`

**Applicable Types:**

- `pregnancyTestResult`

| Value           | Meaning           |
| --------------- | ----------------- |
| `negative`      | Test was negative |
| `positive`      | Test was positive |
| `indeterminate` | Result unclear    |

***

## 6. `HealthCategoryValueProgesteroneTestResult`

**Applicable Types:**

- `progesteroneTestResult`

| Value           | Meaning           |
| --------------- | ----------------- |
| `negative`      | Test was negative |
| `positive`      | Test was positive |
| `indeterminate` | Result unclear    |

***

## 7. `HealthCategoryValueCervicalMucusQuality`

**Applicable Types:**

- `cervicalMucusQuality`

| Value      | Meaning           |
| ---------- | ----------------- |
| `dry`      | Dry               |
| `sticky`   | Sticky            |
| `creamy`   | Creamy            |
| `watery`   | Watery            |
| `eggWhite` | Egg-white texture |

***

## 8. `HealthCategoryValueContraceptive`

**Applicable Types:**

- `contraceptive`

| Value                | Meaning                   |
| -------------------- | ------------------------- |
| `unspecified`        | Not specified             |
| `implant`            | Contraceptive implant     |
| `injection`          | Hormonal injection        |
| `intrauterineDevice` | Intrauterine device (IUD) |
| `intravaginalRing`   | Vaginal ring              |
| `oral`               | Oral contraceptive        |
| `patch`              | Transdermal patch         |

***

## 9. `HealthCategoryValueVaginalBleeding` _(iOS 18+)_

**Applicable Types:**

- `vaginalBleeding`

| Value         | Meaning         |
| ------------- | --------------- |
| `unspecified` | Not specified   |
| `light`       | Light bleeding  |
| `medium`      | Medium bleeding |
| `heavy`       | Heavy bleeding  |
| `none`        | No bleeding     |

***

## 10. `HealthCategoryValueAppetiteChanges`

**Applicable Types:**

- `appetiteChanges`

| Value         | Meaning               |
| ------------- | --------------------- |
| `unspecified` | Not specified         |
| `noChange`    | No change in appetite |
| `decreased`   | Appetite decreased    |
| `increased`   | Appetite increased    |

***

## 11. `HealthCategoryValueAppleStandHour`

**Applicable Types:**

- `appleStandHour`

| Value   | Meaning            |
| ------- | ------------------ |
| `stood` | User stood up      |
| `idle`  | User remained idle |

***

## 12. `HealthCategoryValueAppleWalkingSteadinessEvent`

**Applicable Types:**

- `appleWalkingSteadinessEvent`

| Value            | Meaning                     |
| ---------------- | --------------------------- |
| `initialLow`     | Initial low stability       |
| `initialVeryLow` | Initial very low stability  |
| `repeatLow`      | Repeated low stability      |
| `repeatVeryLow`  | Repeated very low stability |

***

## 13. `HealthCategoryValueEnvironmentalAudioExposureEvent`

**Applicable Types:**

- `environmentalAudioExposureEvent`

| Value            | Meaning                                 |
| ---------------- | --------------------------------------- |
| `momentaryLimit` | Momentary noise exposure limit exceeded |

***

## 14. `HealthCategoryValueHeadphoneAudioExposureEvent`

**Applicable Types:**

- `headphoneAudioExposureEvent`

| Value           | Meaning                                |
| --------------- | -------------------------------------- |
| `sevenDayLimit` | Exceeded recommended 7-day audio limit |

***

## 15. `HealthCategoryValueLowCardioFitnessEvent`

**Applicable Types:**

- `lowCardioFitnessEvent`

| Value        | Meaning                           |
| ------------ | --------------------------------- |
| `lowFitness` | Low cardio fitness level detected |

***

## Usage Example

```ts
const sample = HealthCategorySample.create({
  type: "menstrualFlow",
  startDate: new Date("2025-07-03T10:00:00"),
  endDate: new Date("2025-07-03T12:00:00"),
  value: HealthCategoryValueSeverity.moderate
})

await Health.saveCategorySample(sample)
```

***

## Notes

- Each enum value must match the `type` specified in the sample; using an incorrect enum will result in an error.
- Ensure HealthKit permissions are granted before saving or reading samples.
- `HealthCategorySample` values are stored using Apple's `HKCategoryTypeIdentifier` mapping under the hood.



---
url: /guide/Device Capabilities/Health/HealthCharacteristicType.md
---

# HealthCharacteristicType

This section describes enums related to **user health profile attributes** and **activity configuration**, including biological sex, blood type, skin type, wheelchair use, and activity move mode. These enums are used with the `Health` API to retrieve user profile data from HealthKit.

***

## 1. `HealthBiologicalSex`

Represents the user’s biological sex.

| Enum Value | Description     |
| ---------- | --------------- |
| `notSet`   | Not set         |
| `female`   | Female          |
| `male`     | Male            |
| `other`    | Other/nonbinary |

***

## 2. `HealthBloodType`

Represents the user’s blood type.

| Enum Value   | Description |
| ------------ | ----------- |
| `notSet`     | Not set     |
| `aPositive`  | A Positive  |
| `aNegative`  | A Negative  |
| `bPositive`  | B Positive  |
| `bNegative`  | B Negative  |
| `abPositive` | AB Positive |
| `abNegative` | AB Negative |
| `oPositive`  | O Positive  |
| `oNegative`  | O Negative  |

***

## 3. `HealthFitzpatrickSkinType`

Represents the Fitzpatrick skin type classification, indicating the skin's response to sun exposure.

| Enum Value | Type     | Description                                 |
| ---------- | -------- | ------------------------------------------- |
| `notSet`   | –        | Not set                                     |
| `I`        | Type I   | Very fair, always burns, never tans         |
| `II`       | Type II  | Fair, usually burns, tans minimally         |
| `III`      | Type III | Medium, sometimes mild burn, gradually tans |
| `IV`       | Type IV  | Olive/dark, rarely burns, tans well         |
| `V`        | Type V   | Brown skin, rarely burns, tans easily       |
| `VI`       | Type VI  | Deeply pigmented, never burns               |

***

## 4. `HealthWheelchairUse`

Indicates whether the user uses a wheelchair.

| Enum Value | Description     |
| ---------- | --------------- |
| `notSet`   | Not set         |
| `no`       | Does not use    |
| `yes`      | Uses wheelchair |

***

## 5. `HealthActivityMoveMode`

Represents how the user prefers to track their movement goals in the Activity summary.

| Enum Value      | Description                                  |
| --------------- | -------------------------------------------- |
| `activeEnergy`  | Based on active energy burned                |
| `appleMoveTime` | Based on movement duration (Apple Move Time) |

***

## Usage Examples

```ts
// Check if the user uses a wheelchair
const wheelchair = await Health.wheelchairUse()
if (wheelchair === HealthWheelchairUse.yes) {
  console.log("The user uses a wheelchair")
}

// Retrieve and log the user's Fitzpatrick skin type
const skinType = await Health.fitzpatrickSkinType()
switch (skinType) {
  case HealthFitzpatrickSkinType.III:
    console.log("Medium skin type, gradually tans")
    break
}

// Determine user's activity move mode
const moveMode = await Health.activityMoveMode()
if (moveMode === HealthActivityMoveMode.appleMoveTime) {
  console.log("The user uses Apple Move Time mode")
}
```



---
url: /guide/Device Capabilities/Health/HealthCorrelation.md
---

# HealthCorrelation

The `HealthCorrelation` class represents a group of health samples that are logically related. It provides an interface for accessing and creating correlation records that group multiple health data types together—such as combining dietary intake and blood pressure readings, or linking ovulation tests with menstrual flow records.

***

## Use Cases

- Grouping blood pressure systolic and diastolic values together
- Associating food intake with nutritional data
- Creating a composite record for cycle tracking events

***

## Properties

| Property Name               | Type                                                                                                                 | Description                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `uuid`                      | `string`                                                                                                             | A unique identifier for the correlation sample.                              |
| `correlationType`           | `HealthCorrelationType`                                                                                              | The type of the correlation, such as `"bloodPressure"` or `"food"`.          |
| `startDate`                 | `Date`                                                                                                               | The start time of the correlation event.                                     |
| `endDate`                   | `Date`                                                                                                               | The end time of the correlation event.                                       |
| `metadata`                  | `Record<string, any> \| null`                                                                                        | Optional metadata associated with the correlation, such as user annotations. |
| `samples`                   | `(HealthQuantitySample \| HealthCumulativeQuantitySample \| HealthDiscreteQuantitySample \| HealthCategorySample)[]` | All samples included in this correlation.                                    |
| `quantitySamples`           | `HealthQuantitySample[]`                                                                                             | A convenience array of all quantity-based samples.                           |
| `cumulativeQuantitySamples` | `HealthCumulativeQuantitySample[]`                                                                                   | A filtered array of only cumulative quantity samples.                        |
| `discreteQuantitySamples`   | `HealthDiscreteQuantitySample[]`                                                                                     | A filtered array of only discrete quantity samples.                          |
| `categorySamples`           | `HealthCategorySample[]`                                                                                             | A filtered array of all category-based samples.                              |

***

## Static Method

### `HealthCorrelation.create(options): HealthCorrelation | null`

Creates a new correlation with one or more health samples.

#### Parameters

| Parameter   | Type                                               | Required | Description                                                  |
| ----------- | -------------------------------------------------- | -------- | ------------------------------------------------------------ |
| `type`      | `HealthCorrelationType`                            | Yes      | The correlation type, e.g., `"bloodPressure"` or `"food"`.   |
| `startDate` | `Date`                                             | Yes      | The start time of the correlation.                           |
| `endDate`   | `Date`                                             | Yes      | The end time of the correlation.                             |
| `metadata`  | `Record<string, any> \| null`                      | No       | Optional metadata to store alongside the correlation.        |
| `objects`   | `(HealthQuantitySample \| HealthCategorySample)[]` | Yes      | The array of health samples to associate in the correlation. |

#### Returns

- A new `HealthCorrelation` instance if the parameters are valid.
- Returns `null` if the type and samples are incompatible or validation fails.

***

## Examples

### Example 1: Create a blood pressure correlation

```ts
const systolic = HealthQuantitySample.create({
  type: "bloodPressureSystolic",
  startDate: new Date("2025-07-04T08:00:00"),
  endDate: new Date("2025-07-04T08:01:00"),
  value: 120,
  unit: HealthUnit.millimeterOfMercury()
})

const diastolic = HealthQuantitySample.create({
  type: "bloodPressureDiastolic",
  startDate: new Date("2025-07-04T08:00:00"),
  endDate: new Date("2025-07-04T08:01:00"),
  value: 80,
  unit: HealthUnit.millimeterOfMercury()
})

const correlation = HealthCorrelation.create({
  type: "bloodPressure",
  startDate: systolic.startDate,
  endDate: systolic.endDate,
  objects: [systolic, diastolic]
})

if (correlation) {
  // save correlation...
}
```

***

### Example 2: Query and inspect a correlation

```ts
for (const sample of correlation.quantitySamples) {
  const value = sample.quantityValue(HealthUnit.millimeterOfMercury())
  console.log(`${sample.quantityType}: ${value}`)
}
```

***

## Notes

- Samples in a correlation must match the expected types for the given `HealthCorrelationType`.
- Currently supported correlation types include `"bloodPressure"` and `"food"`.
- This class allows grouping samples for higher-level reasoning or visualization of composite health events.



---
url: /guide/Device Capabilities/Health/HealthHeartbeatSeriesSample.md
---

# HealthHeartbeatSeriesSample

The `HealthHeartbeatSeriesSample` class provides an interface for accessing **heartbeat series samples**, representing a series of individual heartbeat intervals recorded over time. These samples are typically used for analyzing heart rhythm and detecting irregularities such as atrial fibrillation.

This class is returned by the public API method `Health.queryHeartbeatSeriesSamples()`.

***

## Use Cases

- **Monitoring heart rhythm** during workouts or recovery
- **Analyzing irregular heartbeats**
- **Studying heart behavior** during sleep or rest
- **Generating datasets** for research or diagnostics

***

## Class: `HealthHeartbeatSeriesSample`

### Properties

| Property     | Type                          | Description                                                           |
| ------------ | ----------------------------- | --------------------------------------------------------------------- |
| `uuid`       | `string`                      | A unique identifier for the sample                                    |
| `sampleType` | `string`                      | The type of the sample. Typically `"HKHeartbeatSeriesTypeIdentifier"` |
| `startDate`  | `Date`                        | When the heartbeat series recording began                             |
| `endDate`    | `Date`                        | When the recording ended                                              |
| `count`      | `number`                      | Total number of heartbeat intervals in the series                     |
| `metadata`   | `Record<string, any> \| null` | Optional metadata including device info or annotations                |

> **Note**: This class currently does not expose individual RR intervals. It represents only the series summary.

***

## Method: `Health.queryHeartbeatSeriesSamples(options?)`

### Definition

```ts
function queryHeartbeatSeriesSamples(
  options?: {
    startDate?: Date
    endDate?: Date
    limit?: number
    strictStartDate?: boolean
    strictEndDate?: boolean
    sortDescriptors?: Array<{
      key: "startDate" | "endDate" | "count"
      order?: "forward" | "reverse"
    }>
    requestPermissions?: HealthQuantityType[]
  }
): Promise<HealthHeartbeatSeriesSample[]>
```

### Parameters

- `startDate` _(optional)_: Only return samples on or after this date.
- `endDate` _(optional)_: Only return samples on or before this date.
- `limit` _(optional)_: Maximum number of samples to return.
- `strictStartDate` _(optional)_: If true, only include samples whose `startDate` equals `startDate`.
- `strictEndDate` _(optional)_: If true, only include samples whose `endDate` equals `endDate`.
- `sortDescriptors` _(optional)_: Sort results by `startDate`, `endDate`, or `count`, in forward or reverse order.
- `requestPermissions` _(optional)_: An array of health quantity types for which to request permissions before querying. You must request permissions for the types you want to query. Default only requests permissions for the `heartbeat`, `heartRateVariabilitySDNN` and `heartRate` types.

### Returns

A Promise resolving to an array of `HealthHeartbeatSeriesSample` instances, sorted according to the provided descriptors.

***

## Example

```ts
async function fetchHeartbeatSeries() {
  const heartbeatSamples = await Health.queryHeartbeatSeriesSamples({
    startDate: new Date('2024-01-01'),
    endDate: new Date(),
    sortDescriptors: [
      { key: 'startDate', order: 'reverse' }
    ],
    limit: 5,
  })

  for (const sample of heartbeatSamples) {
    console.log('UUID:', sample.uuid)
    console.log('Start:', sample.startDate)
    console.log('End:', sample.endDate)
    console.log('Beats Count:', sample.count)
    console.log('Metadata:', sample.metadata)
  }
}
```

***

## Notes

- If no permission is granted to access heartbeat data, the returned array will be empty.
- Heartbeat series are most commonly recorded by Apple Watch and represent detailed rhythm data over short durations.



---
url: /guide/Device Capabilities/Health/HealthKit Permission Behavior.md
---

# HealthKit Permission Behavior

When using the Health module provided by the Scripting app to access iOS HealthKit data, it's important to understand how HealthKit handles authorization and how Scripting adapts to these behaviors. This document explains the authorization flow, Promise behavior, and best practices for handling missing permissions.

***

## Key Characteristics of iOS HealthKit Authorization

1. **No public API to check authorization status**
   iOS does not provide any public API to determine whether a specific HealthKit data type has been authorized or denied. Apps cannot check this directly.

2. **Authorization prompt appears only once per type**
   The system will show a permission dialog only if the data type's status is `notDetermined`. Once the user grants or denies access, the dialog will not reappear.

3. **No system-level error if access is denied**
   If an app attempts to access unauthorized data, HealthKit will not throw a system error. Instead, some APIs return empty results, while others may reject the Promise.

***

## Scripting App Behavior

### Automatic Authorization Request

When you call any Health API that requires access to protected data, the Scripting app will automatically trigger the system permission dialog **if any of the required types are not yet determined**.

For example:

```ts
await Health.dateOfBirth()
await Health.bloodType()
await Health.queryQuantitySamples('stepCount')
```

***

## Promise Behavior by API

| Method                             | Behavior if unauthorized | Promise rejects? |
| ---------------------------------- | ------------------------ | ---------------- |
| `Health.queryQuantitySamples()`    | Returns empty array `[]` | No               |
| `Health.queryCategorySamples()`    | Returns empty array `[]` | No               |
| `Health.dateOfBirth()`             | No result                | Yes              |
| `Health.bloodType()` (and similar) | No result                | Yes              |

***

## Code Examples

### Example 1: Querying samples (returns empty array when unauthorized)

```ts
const steps = await Health.queryQuantitySamples('stepCount')

if (steps.length === 0) {
  console.log("No step data returned. This may be due to lack of permission or no recorded data.")
}
```

### Example 2: Reading profile information (rejects if unauthorized)

```ts
try {
  const dob = await Health.dateOfBirth()
  console.log(`Date of birth: ${dob.year}-${dob.month}-${dob.day}`)
} catch (err) {
  console.warn("Failed to read date of birth. The user may not have granted permission.")
}
```

***

## Permission Merging on Multiple Calls

If you call multiple permission-requiring methods simultaneously using `Promise.all`, Scripting will automatically merge the required permissions into a **single system dialog** request. This improves user experience by avoiding repeated prompts.

```ts
try {
  const [dob, blood] = await Promise.all([
    Health.dateOfBirth(),
    Health.bloodType()
  ])
  console.log(dob, blood)
} catch (err) {
  console.warn("User may have denied one or more requested permissions.")
}
```

***

## Best Practices and UI Recommendations

| Situation                         | Recommended Handling                                       |
| --------------------------------- | ---------------------------------------------------------- |
| First-time access to Health data  | Inform the user what data will be accessed and why         |
| Empty data returned               | Check for empty array or null and show a helpful message   |
| Rejected Promise from profile API | Use `try...catch` and offer a recovery path                |
| Confused users with missing data  | Provide clear instructions for checking Health permissions |

***

## Manual Authorization

Go to **Health app > Data Access & Devices > Scripting**, and make sure the necessary data types are enabled.



---
url: /guide/Device Capabilities/Health/HealthQuantitySample.md
---

# HealthQuantitySample

The `HealthQuantitySample` class represents a single health quantity data point, such as a heart rate measurement, a recorded step count, or a logged calorie value. It provides information about the measurement’s type, time interval, unit, value, and optional metadata.

This class is the base for more specialized subclasses: `HealthCumulativeQuantitySample` and `HealthDiscreteQuantitySample`.

***

## Overview

A `HealthQuantitySample` encapsulates the following:

- A **specific health metric** (e.g., steps, heart rate)
- A **value with unit**
- A **time window** representing when the data was recorded
- Optional **metadata** for context or classification

This class is primarily used for:

- Reading individual health data samples
- Writing new health data samples
- Converting values between units

***

## Properties

| Property       | Type                          | Description                              |
| -------------- | ----------------------------- | ---------------------------------------- |
| `uuid`         | `string`                      | Unique identifier for the sample         |
| `quantityType` | `HealthQuantityType`          | Type of the health metric                |
| `startDate`    | `Date`                        | Start of the measurement                 |
| `endDate`      | `Date`                        | End of the measurement                   |
| `count`        | `number`                      | Number of samples aggregated (usually 1) |
| `metadata`     | `Record<string, any> \| null` | Optional metadata dictionary             |

***

## Methods

### `quantityValue(unit: HealthUnit): number`

Converts the sample's stored value to the specified unit.

**Parameters:**

- `unit`: A `HealthUnit` instance (e.g., `HealthUnit.kilocalorie()`)

**Returns:**

- The converted numeric value.

**Example:**

```ts
const bpm = sample.quantityValue(HealthUnit.count().divided(HealthUnit.minute()))
console.log(`Heart Rate: ${bpm} bpm`)
```

***

## Static Methods

### `HealthQuantitySample.create(options): HealthQuantitySample | null`

Creates a new quantity sample with the specified parameters.

**Parameters:**

```ts
{
  type: HealthQuantityType
  startDate: Date
  endDate: Date
  value: number
  unit: HealthUnit
  metadata?: Record<string, any> | null
}
```

**Returns:**

- A new `HealthQuantitySample` if valid, otherwise `null`.

**Example:**

```ts
const sample = HealthQuantitySample.create({
  type: 'stepCount',
  startDate: new Date('2025-07-01T09:00:00'),
  endDate: new Date('2025-07-01T09:01:00'),
  value: 200,
  unit: HealthUnit.count(),
  metadata: { source: 'manualEntry' }
})
```

***

## Subclass: HealthCumulativeQuantitySample

The `HealthCumulativeQuantitySample` class represents cumulative data (i.e., totals over time), such as energy burned or distance traveled.

## Additional Properties

| Property                  | Type      | Description                                          |
| ------------------------- | --------- | ---------------------------------------------------- |
| `hasUndeterminedDuration` | `boolean` | Indicates whether the sample’s duration is uncertain |

## Additional Methods

### `sumQuantity(unit: HealthUnit): number`

Returns the total accumulated quantity in the specified unit.

**Example:**

```ts
const totalKcal = cumulativeSample.sumQuantity(HealthUnit.kilocalorie())
console.log(`Total active energy: ${totalKcal} kcal`)
```

### `quantityValue(unit: HealthUnit): number`

Alias for `sumQuantity()` — retrieves the total value in the given unit.

***

## Subclass: HealthDiscreteQuantitySample

The `HealthDiscreteQuantitySample` class represents a series of discrete values sampled at specific times — such as heart rate measurements or step counts across a time window.

## Additional Properties

| Property                         | Type                         | Description                                   |
| -------------------------------- | ---------------------------- | --------------------------------------------- |
| `mostRecentQuantityDateInterval` | `HealthDateInterval \| null` | Time window of the most recent recorded value |

## Additional Methods

| Method                     | Description                                             |
| -------------------------- | ------------------------------------------------------- |
| `averageQuantity(unit)`    | Returns the average of all values in the specified unit |
| `maximumQuantity(unit)`    | Returns the maximum value in the specified unit         |
| `minimumQuantity(unit)`    | Returns the minimum value in the specified unit         |
| `mostRecentQuantity(unit)` | Returns the most recent recorded value (if available)   |

### Example:

```ts
const avg = discreteSample.averageQuantity(HealthUnit.count())
const max = discreteSample.maximumQuantity(HealthUnit.count())
const recent = discreteSample.mostRecentQuantity(HealthUnit.count())
console.log(`Average: ${avg}, Max: ${max}, Recent: ${recent}`)
```

***

## Use Cases

| Scenario                          | Use This Class                   | Example                                     |
| --------------------------------- | -------------------------------- | ------------------------------------------- |
| Record or retrieve a single value | `HealthQuantitySample`           | A manually entered weight                   |
| Work with totals over time        | `HealthCumulativeQuantitySample` | Total distance walked in 1 hour             |
| Analyze statistics across samples | `HealthDiscreteQuantitySample`   | Min/Max/Average heart rate during a workout |

***

## Related Types

- `HealthUnit`: Represents the unit of measurement.
- `HealthQuantityType`: Specifies the kind of health metric being measured.
- `HealthDateInterval`: A time range used for timestamping specific values.



---
url: /guide/Device Capabilities/Health/HealthQuantityType.md
---

# HealthQuantityType

This document lists all supported `HealthQuantityType` identifiers, categorized by domain. Each type is associated with a measurable health-related metric and can be used to track fitness, vital signs, nutrition, environment, and more.

***

## 1. Body Measurements

| Identifier                      | Description                                             |
| ------------------------------- | ------------------------------------------------------- |
| `bodyMass`                      | Weight of the body (in kilograms or pounds)             |
| `bodyMassIndex`                 | Body Mass Index (BMI), a weight-to-height ratio         |
| `height`                        | Height of the user                                      |
| `bodyFatPercentage`             | Percentage of fat in the body                           |
| `leanBodyMass`                  | Mass excluding fat, bones, and organs                   |
| `waistCircumference`            | Waist measurement, often used in metabolic health       |
| `appleSleepingWristTemperature` | Skin temperature during sleep from Apple Watch          |
| `bodyTemperature`               | Core body temperature                                   |
| `basalBodyTemperature`          | Minimum daily body temperature, often used in fertility |

***

## 2. Activity & Fitness

| Identifier                    | Description                                    |
| ----------------------------- | ---------------------------------------------- |
| `stepCount`                   | Number of steps taken                          |
| `distanceWalkingRunning`      | Distance walked or run                         |
| `flightsClimbed`              | Number of floors climbed                       |
| `activeEnergyBurned`          | Active calories burned through movement        |
| `basalEnergyBurned`           | Calories burned at rest                        |
| `appleExerciseTime`           | Time spent in Apple-defined exercise           |
| `appleMoveTime`               | Move ring time for activity summary            |
| `appleStandTime`              | Time standing (Apple Watch)                    |
| `pushCount`                   | Number of wheelchair pushes                    |
| `distanceWheelchair`          | Distance traveled via wheelchair               |
| `nikeFuel`                    | Deprecated Nike activity score                 |
| `estimatedWorkoutEffortScore` | Effort score estimation (Apple Workout)        |
| `workoutEffortScore`          | Direct effort score from workouts              |
| `physicalEffort`              | Intensity estimation of effort during workouts |

***

## 3. Exercise-Specific Metrics

| Identifier                        | Description                              |
| --------------------------------- | ---------------------------------------- |
| `cyclingSpeed`                    | Speed during cycling                     |
| `cyclingPower`                    | Power output during cycling              |
| `cyclingCadence`                  | Pedal revolutions per minute             |
| `cyclingFunctionalThresholdPower` | Max sustainable power for cycling        |
| `distanceCycling`                 | Distance cycled                          |
| `distanceRowing`                  | Distance rowed                           |
| `rowingSpeed`                     | Speed while rowing                       |
| `distanceSwimming`                | Distance swum                            |
| `swimmingStrokeCount`             | Number of swimming strokes               |
| `distancePaddleSports`            | Distance paddled (e.g., kayaking)        |
| `paddleSportsSpeed`               | Speed during paddle sports               |
| `distanceSkatingSports`           | Distance in skating sports               |
| `distanceDownhillSnowSports`      | Distance in downhill skiing/snowboarding |
| `distanceCrossCountrySkiing`      | Distance in cross-country skiing         |
| `crossCountrySkiingSpeed`         | Speed in cross-country skiing            |

***

## 4. Running & Walking Analysis

| Identifier                       | Description                       |
| -------------------------------- | --------------------------------- |
| `runningSpeed`                   | Running speed                     |
| `runningPower`                   | Running power output              |
| `runningStrideLength`            | Stride length                     |
| `runningVerticalOscillation`     | Vertical bounce during running    |
| `runningGroundContactTime`       | Foot-ground contact time          |
| `walkingStepLength`              | Step length while walking         |
| `walkingSpeed`                   | Walking speed                     |
| `walkingAsymmetryPercentage`     | Gait asymmetry                    |
| `walkingDoubleSupportPercentage` | % of time both feet are on ground |
| `appleWalkingSteadiness`         | Apple’s fall risk metric          |
| `walkingHeartRateAverage`        | Avg heart rate during walking     |
| `sixMinuteWalkTestDistance`      | Distance in 6-minute walk test    |
| `stairAscentSpeed`               | Speed ascending stairs            |
| `stairDescentSpeed`              | Speed descending stairs           |

***

## 5. Heart & Vitals

| Identifier                   | Description                             |
| ---------------------------- | --------------------------------------- |
| `heartRate`                  | Beats per minute                        |
| `restingHeartRate`           | Resting heart rate                      |
| `walkingHeartRateAverage`    | Average heart rate while walking        |
| `heartRateVariabilitySDNN`   | HRV: Standard deviation of NN intervals |
| `heartRateRecoveryOneMinute` | HR recovery 1 min post-exercise         |
| `peripheralPerfusionIndex`   | Blood perfusion index                   |
| `atrialFibrillationBurden`   | AFib percentage over time               |
| `vo2Max`                     | Max oxygen uptake, fitness metric       |
| `bloodPressureSystolic`      | Systolic blood pressure                 |
| `bloodPressureDiastolic`     | Diastolic blood pressure                |
| `oxygenSaturation`           | Blood oxygen %                          |
| `bloodGlucose`               | Blood sugar level                       |
| `insulinDelivery`            | Insulin delivered                       |
| `inhalerUsage`               | Number of inhaler puffs                 |
| `respiratoryRate`            | Breaths per minute                      |
| `forcedExpiratoryVolume1`    | Volume in first second of exhalation    |
| `forcedVitalCapacity`        | Max air exhaled after deep breath       |
| `peakExpiratoryFlowRate`     | Peak flow during exhalation             |

***

## 6. Audio & Environment

| Identifier                    | Description                               |
| ----------------------------- | ----------------------------------------- |
| `environmentalAudioExposure`  | Ambient sound levels                      |
| `environmentalSoundReduction` | Noise reduction via headphones            |
| `headphoneAudioExposure`      | Audio exposure from headphones            |
| `uvExposure`                  | Ultraviolet radiation exposure            |
| `timeInDaylight`              | Time spent in daylight (Apple Watch)      |
| `underwaterDepth`             | Depth below water during activity         |
| `waterTemperature`            | Temperature of water when swimming/diving |

***

## 7. Nutrition (Dietary Intake)

| Identifier                  | Description                 |
| --------------------------- | --------------------------- |
| `dietaryEnergyConsumed`     | Total dietary energy intake |
| `dietaryProtein`            | Protein intake              |
| `dietaryCarbohydrates`      | Carbohydrate intake         |
| `dietaryFatTotal`           | Total fat intake            |
| `dietaryFatSaturated`       | Saturated fat               |
| `dietaryFatMonounsaturated` | Monounsaturated fat         |
| `dietaryFatPolyunsaturated` | Polyunsaturated fat         |
| `dietarySugar`              | Total sugar                 |
| `dietaryFiber`              | Fiber                       |
| `dietaryWater`              | Water intake (in mL or L)   |
| `dietaryCaffeine`           | Caffeine intake             |
| `dietaryCholesterol`        | Cholesterol intake          |
| `dietarySodium`             | Sodium intake               |
| `dietaryPotassium`          | Potassium intake            |
| `dietaryCalcium`            | Calcium intake              |
| `dietaryIron`               | Iron intake                 |
| `dietaryMagnesium`          | Magnesium intake            |
| `dietaryZinc`               | Zinc intake                 |
| `dietaryIodine`             | Iodine intake               |
| `dietaryVitaminA`           | Vitamin A intake            |
| `dietaryVitaminB6`          | Vitamin B6 intake           |
| `dietaryVitaminB12`         | Vitamin B12 intake          |
| `dietaryVitaminC`           | Vitamin C intake            |
| `dietaryVitaminD`           | Vitamin D intake            |
| `dietaryVitaminE`           | Vitamin E intake            |
| `dietaryVitaminK`           | Vitamin K intake            |
| `dietaryThiamin`            | Vitamin B1 intake           |
| `dietaryRiboflavin`         | Vitamin B2 intake           |
| `dietaryNiacin`             | Vitamin B3 intake           |
| `dietaryPantothenicAcid`    | Vitamin B5 intake           |
| `dietaryFolate`             | Folate intake               |
| `dietaryCopper`             | Copper intake               |
| `dietarySelenium`           | Selenium intake             |
| `dietaryChromium`           | Chromium intake             |
| `dietaryManganese`          | Manganese intake            |
| `dietaryMolybdenum`         | Molybdenum intake           |
| `dietaryPhosphorus`         | Phosphorus intake           |
| `dietaryBiotin`             | Biotin intake               |

***

## 8. Lifestyle & Others

| Identifier                           | Description                        |
| ------------------------------------ | ---------------------------------- |
| `bloodAlcoholContent`                | Blood alcohol %                    |
| `numberOfAlcoholicBeverages`         | Count of alcoholic drinks          |
| `numberOfTimesFallen`                | Fall detection count               |
| `appleSleepingBreathingDisturbances` | Sleep breathing irregularity count |

***

## When to Use `HealthQuantityType`

You will provide a `HealthQuantityType` string when:

1. **Querying quantity samples**:

```ts
const results = await Health.queryQuantitySamples({
  type: "stepCount",
  startDate: new Date("2025-07-01"),
  endDate: new Date("2025-07-02")
})
```

2. **Writing a quantity sample**:

```ts
const sample = HealthQuantitySample.create({
  type: "bodyMass",
  unit: HealthUnit.gramUnit(HealthUnitPrefix.kilo),
  value: 70.0,
  startDate: new Date("2025-07-01 00:00:00"),
  endDate:  new Date("2025-07-02 00:00:00"),
})

await Health.saveQuantitySample(sample)
```

3. **Reading statistics from a workout**:

```ts
const stat = workout.allStatistics["heartRate"]
const avg = stat?.averageQuantity(HealthUnit.count().divided(HealthUnit.minute()))
```



---
url: /guide/Device Capabilities/Health/HealthStatistics.md
---

# HealthStatistics

The `HealthStatistics` class provides an interface for analyzing **aggregated health quantity data** over a specified time range. It allows you to compute key statistical values such as:

- Total duration
- Average, sum, minimum, maximum quantities
- Most recent value and its date range

This class is ideal for generating summaries of daily, weekly, or custom health data intervals.

***

## Overview

Each `HealthStatistics` instance represents statistics for a specific `HealthQuantityType` within a defined `startDate` and `endDate` range. You can optionally filter statistics by a `HealthSource` (e.g., only include samples recorded by a specific device or app).

***

## Properties

| Property       | Type                     | Description                                                       |
| -------------- | ------------------------ | ----------------------------------------------------------------- |
| `quantityType` | `HealthQuantityType`     | The quantity type the statistics are based on (e.g., `stepCount`) |
| `startDate`    | `Date`                   | The beginning of the statistics window                            |
| `endDate`      | `Date`                   | The end of the statistics window                                  |
| `sources`      | `HealthSource[] \| null` | The list of sources contributing data to these statistics         |

***

## Methods

### `duration(unit: HealthUnit, source?: HealthSource): number | null`

Returns the total accumulated **duration** of all samples within the range.

- `unit`: The unit of time to return the duration in (e.g., seconds, minutes).
- `source` _(optional)_: If provided, only samples from that source will be included.

Returns `null` if no matching samples are found.

***

### `averageQuantity(unit: HealthUnit, source?: HealthSource): number | null`

Returns the **average quantity** value of all samples.

- `unit`: The unit to express the average in (e.g., `HealthUnit.bpm()`).
- `source` _(optional)_: Filter samples by source.

***

### `sumQuantity(unit: HealthUnit, source?: HealthSource): number | null`

Returns the **total sum** of quantity values over the date range.

***

### `minimumQuantity(unit: HealthUnit, source?: HealthSource): number | null`

Returns the **minimum** recorded value in the given unit.

***

### `maximumQuantity(unit: HealthUnit, source?: HealthSource): number | null`

Returns the **maximum** recorded value in the given unit.

***

### `mostRecentQuantity(unit: HealthUnit, source?: HealthSource): number | null`

Returns the **most recent** quantity value recorded within the range. If no values are available, returns `null`.

***

### `mostRecentQuantityDateInterval(source?: HealthSource): HealthDateInterval | null`

Returns a `HealthDateInterval` object indicating the **start and end time** of the most recent recorded value. Useful for knowing **when** the last data point was recorded.

***

## Example Usage

```ts
const stats = await Health.queryStatistics({
  type: "stepCount",
  startDate: new Date("2025-07-01"),
  endDate: new Date("2025-07-02")
})

const totalSteps = stats.sumQuantity(HealthUnit.count())
const average = stats.averageQuantity(HealthUnit.count())
const mostRecent = stats.mostRecentQuantity(HealthUnit.count())
const recentInterval = stats.mostRecentQuantityDateInterval()

console.log("Steps Summary:")
console.log("Total:", totalSteps)
console.log("Average:", average)
console.log("Most Recent:", mostRecent)
console.log("Interval:", recentInterval)
```

***

## `HealthSource` Class

The `HealthSource` class represents the **origin** of a HealthKit sample. It is typically an app or device that generated or synced the health data.

### Properties

| Property           | Type     | Description                                              |
| ------------------ | -------- | -------------------------------------------------------- |
| `bundleIdentifier` | `string` | The app or device bundle ID (e.g., `"com.apple.Health"`) |
| `name`             | `string` | A human-readable name for the source                     |

### Static Methods

#### `HealthSource.forCurrentApp(): HealthSource`

Returns a `HealthSource` object representing the current Scripting app. This can be used to filter statistics only for data recorded or synced by your app.

***

## Example: Filtering by Source

```ts
const stats = await Health.queryStatistics("heartRate", {
  startDate: new Date("2025-07-01"),
  endDate: new Date("2025-07-02")
})

const currentAppSource = HealthSource.forCurrentApp()
const averageHR = stats.averageQuantity(HealthUnit.countPerMinute(), currentAppSource)

console.log("Heart rate from this app:", averageHR)
```

***

## Summary

- `HealthStatistics` helps you analyze trends over time by calculating averages, totals, and most recent values.
- Supports optional filtering by source using `HealthSource`.
- Useful for building visual health summaries and dashboards based on HealthKit data.



---
url: /guide/Device Capabilities/Health/HealthStatisticsCollection.md
---

# HealthStatisticsCollection

The `HealthStatisticsCollection` class provides a structured representation of **time-based grouped health statistics**, such as daily, weekly, or monthly summaries. Each entry in the collection corresponds to one interval, and encapsulates its own `HealthStatistics` object.

This class is particularly useful for:

- Plotting **health trends over time**
- Generating **time-series reports**
- Separating and accessing statistics by date intervals

***

## Overview

Each `HealthStatisticsCollection` is:

- Created by a time-based health statistics query
- Aligned using an anchor date and interval component (e.g., daily, weekly)
- Optionally aggregated by data source (e.g., app, device)

***

## Methods

### `sources(): HealthSource[]`

Returns an array of `HealthSource` objects that contributed data to this collection.

Each `HealthSource` represents a device or app that generated health samples (e.g., Apple Watch, iPhone, a third-party app).

#### Example

```ts
const sources = collection.sources()
sources.forEach(source => {
  console.log("Source:", source.name, source.bundleIdentifier)
})
```

***

### `statistics(): HealthStatistics[]`

Returns all interval-based statistics in the collection as an array of `HealthStatistics` objects.

Each item represents one time interval, aligned by the query's `anchorDate` and `intervalComponents`.

#### Example

```ts
const allStats = collection.statistics()
allStats.forEach(stat => {
  const value = stat.sumQuantity(HealthUnit.count())
  console.log(`From ${stat.startDate} to ${stat.endDate}: ${value} steps`)
})
```

***

### `statisticsFor(date: Date): HealthStatistics | null`

Returns the `HealthStatistics` object that contains the given date, if it falls within any of the predefined intervals in the collection.

If no interval includes the given date, it returns `null`.

#### Example

```ts
const stat = collection.statisticsFor(new Date("2025-07-01"))
if (stat) {
  const value = stat.averageQuantity(HealthUnit.count())
  console.log("Average on July 1st:", value)
} else {
  console.log("No data for July 1st.")
}
```

***

## When to Use

Use `HealthStatisticsCollection` when:

- You want to break health data into **intervals** (e.g., by day/week/month)
- You need to **retrieve and analyze health trends** over time
- You're building **graphs** or **dashboards** from historical health data



---
url: /guide/Device Capabilities/Health/HealthUnit/index.md
---

# HealthUnit

The `HealthUnit` class provides an interface to construct and manipulate various units used in HealthKit. You can create basic units (e.g., grams, meters, liters), apply metric prefixes (e.g., milligrams, kilometers), and perform arithmetic operations like multiplication, division, exponentiation, and inversion.

***

## Enum: `HealthMetricPrefix`

Represents metric prefixes applied to units:

| Enum Value | Symbol | Example    |
| ---------- | ------ | ---------- |
| `none`     | —      | `gram()`   |
| `milli`    | m      | milligram  |
| `centi`    | c      | centimeter |
| `kilo`     | k      | kilometer  |
| `mega`     | M      | megajoule  |
| `micro`    | µ      | microliter |
| `nano`     | n      | nanometer  |

Refer to the full enum for more supported prefixes.

***

## 1. Creating Units

### Basic Units

```ts
const weight = HealthUnit.gram()
const distance = HealthUnit.meter()
const energy = HealthUnit.kilocalorie()
```

### Prefixed Units

```ts
const mg = HealthUnit.gramUnit(HealthMetricPrefix.milli)
const km = HealthUnit.meterUnit(HealthMetricPrefix.kilo)
const mL = HealthUnit.literUnit(HealthMetricPrefix.milli)
```

### Create from Unit String

```ts
const unit = HealthUnit.fromString('kg')
```

***

## 2. Unit Arithmetic

### Multiplication

```ts
const meter = HealthUnit.meter()
const second = HealthUnit.second()
const speed = meter.divided(second) // meters per second
```

### Division

```ts
const bpm = HealthUnit.count().divided(HealthUnit.minute()) // beats per minute
```

### Exponentiation

```ts
const m2 = HealthUnit.meter().raisedToPower(HealthMetricPrefix.none) // square meters
```

### Reciprocal

```ts
const perLiter = HealthUnit.liter().reciprocal() // 1 per liter
```

***

## 3. Unit Properties

| Property     | Type    | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `unitString` | string  | String representation of the unit (e.g., "kg") |
| `isNull`     | boolean | Indicates whether the unit is null/invalid     |

***

## 4. Using with `HealthQuantitySample`

Use `HealthUnit` when creating or reading quantity-based health samples.

### Create a Sample

```ts
const unit = HealthUnit.kilocalorie()

const sample = HealthQuantitySample.create({
  type: 'activeEnergyBurned',
  startDate: new Date('2025-07-04T10:00:00'),
  endDate: new Date('2025-07-04T10:30:00'),
  value: 150,
  unit: unit,
})
```

### Read Sample in Another Unit

```ts
const valueInJoules = sample.quantityValue(HealthUnit.joule())
```

***

## 5. Common Units Overview

| Category        | Example Methods                           |
| --------------- | ----------------------------------------- |
| Weight          | `gram()`, `pound()`, `ounce()`            |
| Length          | `meter()`, `inch()`, `mile()`             |
| Volume          | `liter()`, `fluidOunceUS()`               |
| Time            | `second()`, `minute()`, `hour()`, `day()` |
| Energy          | `kilocalorie()`, `joule()`                |
| Temperature     | `degreeCelsius()`, `kelvin()`             |
| Voltage         | `volt()`, `voltUnit(prefix)`              |
| Light Intensity | `lux()`, `luxUnit(prefix)`                |
| Dimensionless   | `count()`, `percent()`                    |
| Sound Level     | `decibelAWeightedSoundPressureLevel()`    |

***

## 6. Example: Composite Unit Sample

```ts
// steps per minute
const unit = HealthUnit.count().divided(HealthUnit.minute())

const stepSample = HealthQuantitySample.create({
  type: 'stepCount',
  startDate: new Date(),
  endDate: new Date(),
  value: 120,
  unit: unit,
})
```

***

## 7. Example: Parse from Unit String

```ts
const unit = HealthUnit.fromString('g/mL')
console.log(unit.unitString) // g/mL
console.log(unit.isNull)     // false
```

***

## 8. `Health.preferredUnits()` Method

Retrieves the **user’s preferred display units** for one or more `HealthQuantityType` entries. This is useful when presenting health data in a way that respects the system’s regional and user-specific settings (e.g., showing weight in kilograms vs pounds).

***

### Method Signature

```ts
function preferredUnits(
  quantityTypes: HealthQuantityType[]
): Promise<Record<HealthQuantityType, HealthUnit>>
```

***

### Parameters

| Name            | Type                   | Description                                                         |
| --------------- | ---------------------- | ------------------------------------------------------------------- |
| `quantityTypes` | `HealthQuantityType[]` | An array of health quantity types (e.g., `"bodyMass"`, `"height"`). |

***

### Returns

A `Promise` that resolves to a mapping object (`Record`) where each key is a `HealthQuantityType`, and each value is a corresponding `HealthUnit` representing the user's preferred unit for that type.

***

### Throws

An error if the system fails to determine the preferred units for the given quantity types.

***

### Example

```ts
const types: HealthQuantityType[] = ["bodyMass", "height", "dietaryEnergyConsumed"]

const preferred = await Health.preferredUnits(types)

const bodyMassUnit = preferred["bodyMass"]         // e.g., kilograms or pounds
const heightUnit = preferred["height"]             // e.g., meters or inches
const energyUnit = preferred["dietaryEnergyConsumed"] // e.g., kilocalories

console.log("Preferred units:")
console.log("Weight:", bodyMassUnit)
console.log("Height:", heightUnit)
console.log("Energy:", energyUnit)
```

***

### Usage Notes

- Preferred units may vary across devices depending on locale and user Health app settings.
- Always call this method before displaying health data in the UI if you want to respect the user’s expectations.
- For unsupported or unknown quantity types, the result may omit that key.



---
url: /guide/Device Capabilities/Health/HealthUnit/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text, useState } from "scripting"

// Wrap a unit operation as a "safe" call. On incompatible dimensions or an invalid unit
// string, HealthKit used to raise an Objective-C exception that Swift cannot catch, crashing
// the app outright; it now throws a JS error you can handle with try/catch.
function attempt(fn: () => string): string {
  try {
    return fn()
  } catch (e) {
    return `threw → ${String(e)}`
  }
}

function Example() {
  const dismiss = Navigation.useDismiss()
  const [rows, setRows] = useState<{ label: string; value: string }[] | null>(null)

  const runDemo = () => {
    const out: { label: string; value: string }[] = []

    // 1) Build units: basic / prefixed / compound / parsed from a string. All local, no Health authorization needed.
    const kcal = HealthUnit.kilocalorie()
    const kJ = HealthUnit.jouleUnit(HealthMetricPrefix.kilo)
    const mgPerML = HealthUnit.gramUnit(HealthMetricPrefix.milli)
      .divided(HealthUnit.literUnit(HealthMetricPrefix.milli))
    const parsed = HealthUnit.fromString("g/mL")
    out.push({ label: "Units", value: `${kcal.unitString}, ${kJ.unitString}, ${mgPerML.unitString}, ${parsed.unitString}` })

    // 2) Create an energy sample locally and read it back in another compatible unit — a normal conversion.
    const sample = HealthQuantitySample.create({
      type: "activeEnergyBurned",
      startDate: new Date(),
      endDate: new Date(),
      value: 150,
      unit: kcal,
    })
    if (sample != null) {
      out.push({ label: "150 kcal in kJ", value: `${sample.quantityValue(kJ).toFixed(1)} kJ` })
    }

    // 3) Safety: read the energy sample in an incompatible unit (meter) — throws a catchable error instead of crashing.
    if (sample != null) {
      out.push({
        label: "Read energy as meter",
        value: attempt(() => `unexpected: ${sample.quantityValue(HealthUnit.meter())}`),
      })
    }

    // 4) Safety: parse an invalid unit string — throws a catchable error instead of crashing.
    out.push({
      label: "fromString(\"not-a-unit\")",
      value: attempt(() => `unexpected: ${HealthUnit.fromString("not-a-unit").unitString}`),
    })

    // 5) Safety: create a step-count sample with a mismatched unit (kilogram) — throws a catchable error instead of crashing.
    out.push({
      label: "Create stepCount with kg",
      value: attempt(() => {
        const bad = HealthQuantitySample.create({
          type: "stepCount",
          startDate: new Date(),
          endDate: new Date(),
          value: 100,
          unit: HealthUnit.gramUnit(HealthMetricPrefix.kilo),
        })
        return bad == null ? "rejected (null)" : "unexpected: created"
      }),
    })

    setRows(out)
  }

  return <NavigationStack>
    <List
      navigationTitle={"HealthUnit"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button title={"Done"} action={dismiss} />,
      }}
    >
      <Text font={"footnote"} foregroundStyle={"secondaryLabel"}>
        Build units, convert between compatible units, and see how incompatible units or invalid unit strings now throw a catchable error instead of crashing the app. Runs locally — no Health authorization required.
      </Text>

      <Button title={"Run"} action={runDemo} />

      {rows != null && <Section header={<Text>Results</Text>}>
        {rows.map((row, i) => <Text key={String(i)} font={"footnote"}>
          {`${row.label}: ${row.value}`}
        </Text>)}
      </Section>}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/Health/HealthWorkout.md
---

# HealthWorkout

The `HealthWorkout` class provides a high-level interface for accessing and analyzing workout data from Apple Health. A workout represents a full session of physical activity, such as running, swimming, or cycling, recorded between a start and end time, and may include additional events and aggregated statistics.

***

## Use Cases

- Retrieve and display workout history
- Analyze workout types and durations
- Correlate workout sessions with metrics such as heart rate, calories burned, or distance
- Visualize workout events like pauses, resumes, laps, and segments
- Access health statistics collected during the workout session

***

## Properties

| Property              | Type                                                   | Description                                                                                      |
| --------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `uuid`                | `string`                                               | A unique identifier for the workout instance.                                                    |
| `workoutActivityType` | `HealthWorkoutActivityType`                            | The type of activity, such as running, swimming, yoga, etc.                                      |
| `startDate`           | `Date`                                                 | The start time of the workout session.                                                           |
| `endDate`             | `Date`                                                 | The end time of the workout session.                                                             |
| `duration`            | `number`                                               | The duration of the workout in seconds.                                                          |
| `metadata`            | `Record<string, any> \| null`                          | Optional metadata, which may include the source app, device, or user-defined tags.               |
| `workoutEvents`       | `HealthWorkoutEvent[] \| null`                         | An array of workout events such as pauses, laps, or segments, captured during the session.       |
| `allStatistics`       | `Record<HealthQuantityType, HealthStatistics \| null>` | A dictionary mapping quantity types to statistics recorded during the workout (e.g. heart rate). |

***

## Related Types

### `HealthWorkoutActivityType`

Represents the type of physical activity, such as:

- `running`
- `walking`
- `cycling`
- `swimming`
- `yoga`
- ... and many more (see `HealthWorkoutActivityType` documentation)

### `HealthWorkoutEvent`

Represents a specific event during the workout, such as:

- pause
- resume
- motion paused/resumed
- lap or segment markers

### `HealthStatistics`

Provides calculated metrics such as:

- `averageQuantity()`
- `sumQuantity()`
- `maximumQuantity()`
- `minimumQuantity()`
- `mostRecentQuantity()`

These are based on health data samples (e.g., heart rate, energy burned) during the workout's time interval.

***

## Example Usage

```ts
function displayWorkoutSummary(workout: HealthWorkout) {
  console.log(`Workout ID: ${workout.uuid}`)
  console.log(`Activity Type: ${workout.workoutActivityType}`)
  console.log(`Start: ${workout.startDate.toISOString()}`)
  console.log(`End: ${workout.endDate.toISOString()}`)
  console.log(`Duration: ${(workout.duration / 60).toFixed(1)} minutes`)

  if (workout.metadata) {
    console.log(`Metadata: ${JSON.stringify(workout.metadata)}`)
  }

  if (workout.workoutEvents) {
    for (const event of workout.workoutEvents) {
      console.log(`Event: ${HealthWorkoutEventType[event.type]} at ${event.dateInterval.start.toISOString()}`)
    }
  }

  const heartRateStats = workout.allStatistics["heartRate"]
  if (heartRateStats) {
    console.log(`Average Heart Rate: ${heartRateStats.averageQuantity("count/min")} bpm`)
  }
}
```

***

## Notes

- `HealthWorkout` instances are typically retrieved using query APIs such as `Health.queryWorkouts()` (if available in the framework).
- The `allStatistics` property provides quick access to summary data without needing to query samples manually.
- Use the `workoutEvents` property to reconstruct the timeline of activity (e.g., when the user paused or resumed).



---
url: /guide/Device Capabilities/Health/HealthWorkoutActivityType.md
---

# HealthWorkoutActivityType

Each enum value below includes a description of its purpose and typical use case.

| Enum                            | Description & Use Case                                                                             |
| ------------------------------- | -------------------------------------------------------------------------------------------------- |
| `americanFootball`              | American-style football, high-intensity team sport. Track during practices or games.               |
| `archery`                       | Archery training or competition. Good for logging precision-focused, stationary activities.        |
| `australianFootball`            | A variation of football native to Australia, fast-paced and high-contact sport.                    |
| `badminton`                     | Lightweight racquet sport for cardio and agility workouts.                                         |
| `baseball`                      | Baseball sessions including batting practice or matches.                                           |
| `basketball`                    | Basketball games or shooting drills, useful for tracking cardio and intervals.                     |
| `bowling`                       | Bowling activity, typically low-intensity and often includes standing periods.                     |
| `boxing`                        | Boxing training or matches—good for tracking high-intensity interval workouts.                     |
| `climbing`                      | Rock climbing, indoor or outdoor; involves strength, balance, and endurance.                       |
| `cricket`                       | Cricket practice or match play, includes running and arm movement.                                 |
| `crossTraining`                 | Cross-training routines that combine multiple types of exercises. Often used for circuit training. |
| `curling`                       | Ice-based team sport that involves sliding stones and sweeping; tracks light movement.             |
| `cycling`                       | Bicycling activities, indoor or outdoor, for tracking distance and speed.                          |
| `dance`                         | Any general form of dance (e.g., ballet, hip-hop) used for cardio or artistic workouts.            |
| `danceInspiredTraining`         | Dance-based fitness routines like Zumba, which blend music and cardio movement.                    |
| `elliptical`                    | Elliptical machine workouts, low-impact cardio often done indoors.                                 |
| `equestrianSports`              | Horseback riding and related training, suitable for both leisure and competition.                  |
| `fencing`                       | Sword-fighting sport, involves fast footwork and short bursts of effort.                           |
| `fishing`                       | Logging fishing sessions, includes walking, standing, and casting motions.                         |
| `functionalStrengthTraining`    | Practical strength training like kettlebells or resistance band workouts.                          |
| `golf`                          | Golfing activities including driving range, walking between holes, and swinging.                   |
| `gymnastics`                    | Gymnastic routines such as balance beam or rings, emphasizing flexibility and control.             |
| `handball`                      | Indoor or outdoor handball sport, often fast-paced and cardio-intensive.                           |
| `hiking`                        | Hiking through natural trails or mountains; often includes elevation gain.                         |
| `hockey`                        | Ice or field hockey, combining speed, coordination, and teamwork.                                  |
| `hunting`                       | Tracking and logging time during hunting activities, including walking and idle periods.           |
| `lacrosse`                      | High-intensity team sport involving a ball and stick; includes sprinting and throwing.             |
| `martialArts`                   | All forms of martial arts such as karate, judo, and Brazilian jiu-jitsu.                           |
| `mindAndBody`                   | Gentle exercise combining mental and physical health, e.g., stretching, meditation.                |
| `mixedMetabolicCardioTraining`  | Intense routines like HIIT, combining anaerobic and aerobic segments.                              |
| `paddleSports`                  | Sports like kayaking and canoeing; use for water-based arm-intensive workouts.                     |
| `play`                          | Unstructured or informal play, often for children or families.                                     |
| `preparationAndRecovery`        | Activities like foam rolling, light stretching, and cooldown routines.                             |
| `racquetball`                   | Fast-paced indoor sport with a racquet and ball, tracked for cardio and agility.                   |
| `rowing`                        | Rowing on machines or watercraft; works upper body and core.                                       |
| `rugby`                         | Contact team sport similar to football; intense running and tackling.                              |
| `running`                       | All types of running (jogging, sprints, races); includes treadmill and outdoor runs.               |
| `sailing`                       | Sailing activities; may include balance and upper-body coordination.                               |
| `skatingSports`                 | Ice skating or roller skating; combines speed and balance.                                         |
| `snowSports`                    | General snow-based sports including sledding and snowshoeing.                                      |
| `soccer`                        | Soccer practice or games; cardio-intensive and agility-based.                                      |
| `softball`                      | Similar to baseball, slower pitch and larger ball; use in matches or training.                     |
| `squash`                        | High-speed indoor racquet sport; excellent for cardio and reflexes.                                |
| `stairClimbing`                 | Climbing stairs or using a stair machine; great for lower-body strength and cardio.                |
| `surfingSports`                 | Surfing and other board water sports; tracks core and balance workouts.                            |
| `swimming`                      | All swimming styles (freestyle, breaststroke); great for full-body cardio.                         |
| `tableTennis`                   | Ping pong; light activity, good for hand-eye coordination and reaction.                            |
| `tennis`                        | Tennis practice or matches, singles or doubles.                                                    |
| `trackAndField`                 | Track events like sprinting or long jump, also field events like discus.                           |
| `traditionalStrengthTraining`   | Weightlifting, barbell squats, bench press, etc.                                                   |
| `volleyball`                    | Indoor or beach volleyball; jumping, running, and team coordination.                               |
| `walking`                       | Casual or brisk walking sessions; track steps, distance, and time.                                 |
| `waterFitness`                  | Water aerobics or aquatic resistance workouts.                                                     |
| `waterPolo`                     | Team water sport; combines swimming with ball-handling.                                            |
| `waterSports`                   | Other water activities not listed separately (e.g., jet skiing, paddle boarding).                  |
| `wrestling`                     | Grappling sports like freestyle or Greco-Roman wrestling.                                          |
| `yoga`                          | Yoga practices, including hatha, vinyasa, and power yoga.                                          |
| `barre`                         | Ballet-inspired fitness that combines dance, yoga, and strength.                                   |
| `coreTraining`                  | Exercises focused on abdominal and back muscles.                                                   |
| `crossCountrySkiing`            | Skiing across snow-covered terrain; endurance-focused.                                             |
| `downhillSkiing`                | Skiing on slopes; includes chairlift time and descent tracking.                                    |
| `flexibility`                   | Stretching-focused routines to improve joint mobility.                                             |
| `highIntensityIntervalTraining` | Alternating bursts of intense activity and rest; e.g., sprint-rest-sprint.                         |
| `jumpRope`                      | Jumping rope workouts, cardio-focused.                                                             |
| `kickboxing`                    | Fitness or competitive kickboxing routines.                                                        |
| `pilates`                       | Low-impact training focused on alignment, breathing, and core strength.                            |
| `snowboarding`                  | Snowboarding activity, including jumps and carving.                                                |
| `stairs`                        | General stair usage or exercises involving staircases.                                             |
| `stepTraining`                  | Aerobic routines with a step platform.                                                             |
| `wheelchairWalkPace`            | Wheelchair rolling at walking speed.                                                               |
| `wheelchairRunPace`             | Wheelchair rolling at running speed.                                                               |
| `taiChi`                        | Gentle martial arts practice; used for balance, flow, and mindfulness.                             |
| `mixedCardio`                   | Blended cardio types (e.g., run + bike).                                                           |
| `handCycling`                   | Arm-powered cycling activity.                                                                      |
| `discSports`                    | Sports involving discs like ultimate frisbee.                                                      |
| `fitnessGaming`                 | Video games that encourage physical activity (e.g., Ring Fit, VR fitness).                         |
| `cardioDance`                   | Aerobic dancing specifically designed to raise heart rate.                                         |
| `socialDance`                   | Partner-based or formal dances (e.g., ballroom, tango).                                            |
| `pickleball`                    | Paddle sport combining elements of badminton, tennis, and ping-pong.                               |
| `cooldown`                      | Post-workout recovery routines to lower heart rate and stretch muscles.                            |
| `swimBikeRun`                   | Triathlon-style activity, combining swimming, cycling, and running.                                |
| `transition`                    | Transition phase between sports in triathlon, such as from swim to bike.                           |
| `underwaterDiving`              | Recreational or professional diving (e.g., scuba).                                                 |
| `other`                         | Any activity not covered by the above types. Use when your workout doesn't fit a defined category. |

***

**Usage Example:**

```ts
const workoutType = HealthWorkoutActivityType.running
```



---
url: /guide/Device Capabilities/Health/HealthWorkoutEvent.md
---

# HealthWorkoutEvent

The `HealthWorkoutEvent` class provides an interface for accessing workout-related events in Apple Health data. Each event represents a specific moment or action within a workout session, such as when the workout is paused, resumed, or marked with a lap or milestone.

***

## Use Cases

- Analyzing workout flow: determine when a user paused or resumed a workout.
- Measuring active versus idle workout time.
- Identifying workout laps or marked segments.
- Supporting custom logic in workout summaries or visualizations.

***

## Enum: `HealthWorkoutEventType`

This enum defines the various types of workout events.

| Value | Name                   | Description                                                                 |
| ----- | ---------------------- | --------------------------------------------------------------------------- |
| `1`   | `pause`                | Indicates that the workout was paused manually.                             |
| `2`   | `resume`               | Indicates that the workout was resumed after a pause.                       |
| `3`   | `lap`                  | Marks a lap during the workout, useful for sports like running or swimming. |
| `4`   | `marker`               | A generic marker placed by the system or user for reference.                |
| `5`   | `motionPaused`         | Indicates that the workout was automatically paused due to no movement.     |
| `6`   | `motionResumed`        | Workout automatically resumed after detecting motion.                       |
| `7`   | `segment`              | Marks the start of a new workout segment, e.g., during interval training.   |
| `8`   | `pauseOrResumeRequest` | A system-generated request to pause or resume, not a guaranteed action.     |

***

## Class: `HealthWorkoutEvent`

### Properties

| Property       | Type                          | Description                                                          |
| -------------- | ----------------------------- | -------------------------------------------------------------------- |
| `type`         | `HealthWorkoutEventType`      | The specific event type (e.g., pause, lap, motionPaused).            |
| `dateInterval` | `HealthDateInterval`          | The time interval during which this event occurred.                  |
| `metadata`     | `Record<string, any> \| null` | Optional metadata describing additional information about the event. |

> Note: `HealthDateInterval` contains `start`, `end`, and `duration` (in seconds).

***

## Example

### Logging Workout Events

```ts
function logWorkoutEvent(event: HealthWorkoutEvent) {
  const { type, dateInterval, metadata } = event
  const start = dateInterval.start.toISOString()
  const end = dateInterval.end.toISOString()
  const duration = dateInterval.duration

  console.log(`Event Type: ${HealthWorkoutEventType[type]}`)
  console.log(`Start: ${start}`)
  console.log(`End: ${end}`)
  console.log(`Duration (sec): ${duration}`)

  if (metadata) {
    console.log(`Metadata: ${JSON.stringify(metadata)}`)
  }
}
```

***

## Notes

- Workout events are typically part of a `HealthWorkout` instance, which includes these events as an array.
- You can use these events to reconstruct the full timeline of a workout session and determine user behavior.
- Automatic motion detection (pause/resume) is particularly useful for passive workouts such as walking or cycling.



---
url: /guide/Device Capabilities/Health/Query Statistics Collection.md
---

# Query Statistics Collection

The `Health.queryStatisticsCollection()` method retrieves **time-based aggregated statistics** for a given `HealthQuantityType` over a specified date range. It returns a `HealthStatisticsCollection` object, which contains multiple `HealthStatistics` entries aligned to defined time intervals (such as daily, weekly, or monthly).

This method is ideal for analyzing trends, building charts, and generating historical summaries of health data.

***

## Method Signature

```ts
function queryStatisticsCollection(
  quantityType: HealthQuantityType,
  options: {
    startDate?: Date
    endDate?: Date
    strictStartDate?: boolean
    strictEndDate?: boolean
    statisticsOptions?: HealthStatisticsOptions | Array<HealthStatisticsOptions>
    anchorDate: Date
    intervalComponents: DateComponents
  }
): Promise<HealthStatisticsCollection>
```

***

## Parameters

| Name                         | Type                                         | Required | Description                                                                                                                                                                  |
| ---------------------------- | -------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `quantityType`               | `HealthQuantityType`                         | Yes      | The health quantity type to query (e.g., `"stepCount"`, `"heartRate"`).                                                                                                      |
| `options.startDate`          | `Date`                                       | No       | The start date of the time range. Samples outside this range will be excluded.                                                                                               |
| `options.endDate`            | `Date`                                       | No       | The end date of the time range.                                                                                                                                              |
| `options.strictStartDate`    | `boolean`                                    | No       | If `true`, includes only statistics whose interval starts exactly at `startDate`.                                                                                            |
| `options.strictEndDate`      | `boolean`                                    | No       | If `true`, includes only statistics whose interval ends exactly at `endDate`.                                                                                                |
| `options.statisticsOptions`  | `HealthStatisticsOptions[]` or single option | No       | The list of statistics to compute. Can include: `"cumulativeSum"`, `"discreteAverage"`, `"discreteMin"`, `"discreteMax"`, `"mostRecent"`, `"duration"`, `"separateBySource"` |
| `options.anchorDate`         | `Date`                                       | Yes      | The anchor date used to align intervals. For example, use midnight to align daily intervals to calendar days.                                                                |
| `options.intervalComponents` | `DateComponents`                             | Yes      | Defines the interval for grouping data (e.g., day, week, month). Create using `new DateComponents({ day: 1 })`, etc.                                                         |

***

## Return Value

Returns a `Promise` that resolves to a `HealthStatisticsCollection` object. This collection includes statistics for each time interval between the start and end dates, aligned by the anchor date and grouped using the provided `intervalComponents`.

***

## Example: Retrieve Daily Step Count Statistics for the Past 7 Days

```ts
const now = new Date()
const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)

const collection = await Health.queryStatisticsCollection("stepCount", {
  startDate: sevenDaysAgo,
  endDate: now,
  anchorDate: new Date(), // typically midnight today
  intervalComponents: new DateComponents({ day: 1 }),
  statisticsOptions: ["cumulativeSum"]
})

const stats = collection.statistics()
for (const stat of stats) {
  const steps = stat.sumQuantity(HealthUnit.count())
  console.log(`From ${stat.startDate.toDateString()}: ${steps} steps`)
}
```

***

## Notes

- If no data exists for a specific interval, its corresponding `HealthStatistics` entry may return `null` values.
- Intervals are aligned using the `anchorDate`, and the grouping is defined by `intervalComponents`.
- If you only need overall statistics for the full range without interval grouping, use `Health.queryStatistics()` instead.



---
url: /guide/Device Capabilities/Health/Query Statistics.md
---

# Query Statistics

The `queryStatistics` method retrieves **aggregated statistics** for a specific health quantity type over a defined date range. It can compute metrics such as total sum, average, minimum, maximum, most recent value, and duration, with optional support for breaking down results by source (e.g., device or app).

This method is ideal for producing **daily, weekly, or historical health summaries**.

***

## Method Signature

```ts
function queryStatistics(
  quantityType: HealthQuantityType,
  options?: {
    startDate?: Date
    endDate?: Date
    strictStartDate?: boolean
    strictEndDate?: boolean
    statisticsOptions?: HealthStatisticsOptions | Array<HealthStatisticsOptions>
  }
): Promise<HealthStatistics | null>
```

***

## Parameters

### `quantityType: HealthQuantityType` (required)

The health quantity type to query, such as:

- `"stepCount"`
- `"heartRate"`
- `"bodyMass"`
- `"activeEnergyBurned"`
- Any supported `HealthQuantityType`

***

### `options` (optional)

An object specifying filtering and configuration options for the query.

| Option              | Type                                                     | Description                                                                             |
| ------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `startDate`         | `Date`                                                   | The start date for the query range.                                                     |
| `endDate`           | `Date`                                                   | The end date for the query range.                                                       |
| `strictStartDate`   | `boolean`                                                | If `true`, only includes statistics that **begin exactly** at `startDate`. Optional.    |
| `strictEndDate`     | `boolean`                                                | If `true`, only includes statistics that **end exactly** at `endDate`. Optional.        |
| `statisticsOptions` | `HealthStatisticsOptions` or `HealthStatisticsOptions[]` | An option or array of options to define what kind of statistics to retrieve. See below. |

***

## Available `HealthStatisticsOptions`

| Option               | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `"cumulativeSum"`    | Includes the total sum of all quantity values.              |
| `"discreteAverage"`  | Includes the average of discrete samples.                   |
| `"discreteMin"`      | Includes the minimum value.                                 |
| `"discreteMax"`      | Includes the maximum value.                                 |
| `"mostRecent"`       | Includes the most recently recorded sample.                 |
| `"duration"`         | Includes the total duration of all samples.                 |
| `"separateBySource"` | Separates results by source (e.g., different apps/devices). |

***

## Return Value

Returns a `Promise` that resolves to a `HealthStatistics` object, or `null` if no data is available for the given type and range.

Use the returned `HealthStatistics` object to access computed values like:

- `sumQuantity(...)`
- `averageQuantity(...)`
- `mostRecentQuantity(...)`
- `duration(...)`

***

## Example: Query Daily Step Count Summary

```ts
const stats = await Health.queryStatistics("stepCount", {
  startDate: new Date("2025-07-01"),
  endDate: new Date("2025-07-02"),
  statisticsOptions: ["cumulativeSum", "mostRecent", "duration"]
})

if (stats) {
  const steps = stats.sumQuantity(HealthUnit.count())
  const last = stats.mostRecentQuantity(HealthUnit.count())
  const time = stats.duration(HealthUnit.second())

  console.log("Steps:", steps)
  console.log("Most recent count:", last)
  console.log("Duration (s):", time)
} else {
  console.log("No step count data found.")
}
```

***

## Example: Query Average Heart Rate from This App Only

```ts
const stats = await Health.queryStatistics("heartRate", {
  startDate: new Date("2025-07-01"),
  endDate: new Date("2025-07-02"),
  statisticsOptions: ["discreteAverage"]
})

const source = HealthSource.forCurrentApp()
const averageHR = stats?.averageQuantity(HealthUnit.countPerMinute(), source)

console.log("App-only Heart Rate:", averageHR)
```

***

## Notes

- If `statisticsOptions` is not specified, some fields (like sum, average, or most recent) may return `null`.
- This method returns **aggregated values**—to access raw samples, use `queryQuantitySamples()` instead.
- Results depend on the type of quantity. For instance, heart rate supports `discreteAverage`, while step count supports `cumulativeSum`.



---
url: /guide/Device Capabilities/Health/Reading Activity Summaries.md
---

# Reading Activity Summaries

The Scripting app provides access to **daily activity summary data** from Apple Health using the global function `Health.queryActivitySummaries()`. These summaries represent **Move**, **Exercise**, and **Stand** goals tracked by Apple Watch, along with completion metrics and historical trends.

This API is ideal for displaying daily ring data or analyzing long-term fitness trends.

***

## What Is an Activity Summary?

An `HealthActivitySummary` provides a high-level overview of a day’s Apple Watch activity:

- **Move (Active Energy Burned)**

  - `activeEnergyBurned(unit: HealthUnit): number`
  - `activeEnergyBurnedGoal(unit: HealthUnit): number`

- **Exercise (Minutes)**

  - `appleExerciseTime(unit: HealthUnit): number`
  - `appleExerciseTimeGoal(unit: HealthUnit): number`

- **Stand (Hours)**

  - `appleStandHours(unit: HealthUnit): number`
  - `appleStandHoursGoal(unit: HealthUnit): number`

- **Date Information**

  - `dateComponents: DateComponents` – a `DateComponents` object containing at least year, month, and day.

***

## API Overview

```ts
Health.queryActivitySummaries(
  options?: {
    start: DateComponents
    end: DateComponents
  }
): Promise<HealthActivitySummary[]>
```

***

## Parameters

| Parameter | Type             | Description                                                                      |
| --------- | ---------------- | -------------------------------------------------------------------------------- |
| `start`   | `DateComponents` | The start of the query range. Only summaries on or after this date are returned. |
| `end`     | `DateComponents` | The end of the query range. Only summaries on or before this date are returned.  |

> If you omit the options, the API returns all available summaries (up to system limits).
> Summaries are returned sorted by date in ascending order.

***

## Example: Read Last 7 Days’ Activity Summaries

```ts
async function fetchLastWeek() {
  // Build DateComponents for the date range
  const today = new Date()
  const sevenDaysAgo = new Date(
    today.getFullYear(),
    today.getMonth(),
    today.getDate() - 6
  )

  const startComponents = DateComponents.fromDate(sevenDaysAgo)
  const endComponents = DateComponents.fromDate(today)

  // Query activity summaries
  const summaries = await Health.queryActivitySummaries({
    start: startComponents,
    end: endComponents,
  })

  // Iterate and log each day’s data
  for (const summary of summaries) {
    const date = summary.dateComponents.date
    console.log(`Date: ${date?.toDateString()}`)

    const kcal = summary.activeEnergyBurned(HealthUnit.kilocalorie())
    const kcalGoal = summary.activeEnergyBurnedGoal(HealthUnit.kilocalorie())
    const exerciseMin = summary.appleExerciseTime(HealthUnit.minute())
    const standHrs = summary.appleStandHours(HealthUnit.count())

    console.log(` Move:    ${kcal} / ${kcalGoal} kcal`)
    console.log(` Exercise: ${exerciseMin} min`)
    console.log(` Stand:    ${standHrs} hrs`)
    console.log('---')
  }
}

fetchLastWeek()
```

***

## Notes

- **DateComponents** must include at least year, month, and day—other fields (hour, minute) are ignored for daily summaries.
- Each metric method returns a raw `number` in the specified unit.
- Use `HealthUnit` factory methods (e.g., `kilocalorie()`, `minute()`, `count()`) to specify units.
- Days with no data (e.g., Apple Watch off-wrist) may be omitted from results.

***

## Summary

1. Call `Health.queryActivitySummaries({ start, end })` with `DateComponents` to specify your date range.
2. Receive an array of `HealthActivitySummary`, sorted ascending by date.
3. Use the summary’s methods to read actual vs. goal values for Move, Exercise, and Stand.
4. Convert and display the numbers in your UI or analytics.



---
url: /guide/Device Capabilities/Health/Reading Category Samples.md
---

# Reading Category Samples

The Scripting app provides access to **category-based health data** using the global function `Health.queryCategorySamples()`. Category samples represent health-related events or states with a start date, end date, and a discrete value — such as sleep stages, mindful sessions, menstrual flow, and ovulation test results.

This guide explains how to query, interpret, and use category samples in your scripts.

***

## What Is a Category Sample?

A **category sample** includes:

- `type`: The category data type (e.g., `"sleepAnalysis"`, `"mindfulSession"`)
- `startDate` / `endDate`: The time interval the event occurred
- `value`: An integer representing a state, mapped from an enum
- `metadata`: Optional additional info

Examples:

- `"sleepAnalysis"` with value `asleepCore`, `awake`, or `inBed`
- `"menstrualFlow"` with value `mild`, `moderate`, or `severe`

***

## API Overview

```ts
Health.queryCategorySamples(
  categoryType: HealthCategoryType,
  options?: {
    startDate?: Date
    endDate?: Date
    limit?: number
    strictStartDate?: boolean
    strictEndDate?: boolean
    sortDescriptors?: Array<{
      key: "startDate" | "endDate" | "value"
      order?: "forward" | "reverse"
    }>
  }
): Promise<HealthCategorySample[]>
```

***

## Parameters

| Parameter                           | Description                                                    |
| ----------------------------------- | -------------------------------------------------------------- |
| `categoryType`                      | The type of category data to query (e.g., `"sleepAnalysis"`)   |
| `startDate` / `endDate`             | Time range to filter results                                   |
| `limit`                             | Maximum number of samples to return                            |
| `strictStartDate` / `strictEndDate` | Whether to match the exact start or end times                  |
| `sortDescriptors`                   | Optional sorting (e.g., by `startDate`, `endDate`, or `value`) |

***

## Example: Reading Sleep Analysis Samples

```ts
const results = await Health.queryCategorySamples("sleepAnalysis", {
  startDate: new Date("2025-07-01T00:00:00"),
  endDate: new Date("2025-07-05T00:00:00"),
  sortDescriptors: [{ key: "startDate", order: "forward" }]
})

for (const sample of results) {
  console.log("Start:", sample.startDate)
  console.log("End:", sample.endDate)
  console.log("Sleep State:", sample.value) // Use enum to interpret value
}
```

You can map the `value` to an enum like this:

```ts
const value = sample.value

switch (value) {
  case HealthCategoryValueSleepAnalysis.awake:
    console.log("Awake")
    break
  case HealthCategoryValueSleepAnalysis.asleepCore:
    console.log("Asleep (Core)")
    break
  case HealthCategoryValueSleepAnalysis.asleepDeep:
    console.log("Asleep (Deep)")
    break
  case HealthCategoryValueSleepAnalysis.inBed:
    console.log("In bed")
    break
  // Handle other states as needed
}
```

***

## Example: Reading Mindful Session Events

```ts
const sessions = await Health.queryCategorySamples("mindfulSession", {
  startDate: new Date(Date.now() - 7 * 86400 * 1000), // past 7 days
})

console.log(`Found ${sessions.length} mindful sessions`)
```

***

## Notes

- All returned items are instances of `HealthCategorySample`
- The `.value` field is numeric and should be interpreted using the appropriate enum
- You can access optional `.metadata` for extra context if available
- Category data is ideal for modeling sleep, mental wellness, reproductive health, and symptoms

***

## Summary

To read category samples:

1. Use `Health.queryCategorySamples(categoryType, options)`
2. Filter by date, sort, and limit as needed
3. Map `.value` to the correct enum for human-readable interpretation

This API gives you structured access to event-based health records in HealthKit.



---
url: /guide/Device Capabilities/Health/Reading Characteristic Data.md
---

# Reading Characteristic Data

HealthKit stores **characteristics** as immutable personal attributes, such as biological sex, date of birth, blood type, skin type, wheelchair usage, and activity move mode. These values are typically entered by the user in the Health app and rarely change.

The Scripting app provides global asynchronous APIs for accessing these values.

***

## Supported Characteristics

You can read the following characteristics:

| Characteristic        | API                            | Return Type                      |
| --------------------- | ------------------------------ | -------------------------------- |
| Date of birth         | `Health.dateOfBirth()`         | `DateComponents`                 |
| Biological sex        | `Health.biologicalSex()`       | `HealthBiologicalSex` enum       |
| Blood type            | `Health.bloodType()`           | `HealthBloodType` enum           |
| Fitzpatrick skin type | `Health.fitzpatrickSkinType()` | `HealthFitzpatrickSkinType` enum |
| Wheelchair use status | `Health.wheelchairUse()`       | `HealthWheelchairUse` enum       |
| Activity move mode    | `Health.activityMoveMode()`    | `HealthActivityMoveMode` enum    |

***

## 1. Read Date of Birth

```ts
const birthDate = await Health.dateOfBirth()
console.log(`Year: ${birthDate.year}, Month: ${birthDate.month}, Day: ${birthDate.day}`)
```

Returned object conforms to `DateComponents`:

```ts
{
  era?: number
  year?: number
  month?: number
  day?: number
  hour?: number
  minute?: number
  second?: number
  weekday?: number
  ...
}
```

***

## 2. Read Biological Sex

```ts
const sex = await Health.biologicalSex()

switch (sex) {
  case HealthBiologicalSex.female:
    console.log("Female")
    break
  case HealthBiologicalSex.male:
    console.log("Male")
    break
  case HealthBiologicalSex.other:
    console.log("Other")
    break
  case HealthBiologicalSex.notSet:
    console.log("Not Set")
    break
}
```

***

## 3. Read Blood Type

```ts
const blood = await Health.bloodType()

switch (blood) {
  case HealthBloodType.aPositive:
    console.log("A+")
    break
  case HealthBloodType.oNegative:
    console.log("O-")
    break
  // ... other values
  default:
    console.log("Not Set")
}
```

***

## 4. Read Fitzpatrick Skin Type

```ts
const skinType = await Health.fitzpatrickSkinType()

switch (skinType) {
  case HealthFitzpatrickSkinType.I:
    console.log("Type I: Very fair")
    break
  case HealthFitzpatrickSkinType.VI:
    console.log("Type VI: Deeply pigmented dark brown to black")
    break
  default:
    console.log("Not Set")
}
```

***

## 5. Read Wheelchair Use Status

```ts
const wheelchair = await Health.wheelchairUse()

if (wheelchair === HealthWheelchairUse.yes) {
  console.log("User uses a wheelchair")
} else if (wheelchair === HealthWheelchairUse.no) {
  console.log("User does not use a wheelchair")
} else {
  console.log("Not Set")
}
```

***

## 6. Read Activity Move Mode

```ts
const mode = await Health.activityMoveMode()

if (mode === HealthActivityMoveMode.activeEnergy) {
  console.log("Tracking by active energy burned")
} else if (mode === HealthActivityMoveMode.appleMoveTime) {
  console.log("Tracking by Apple Move Time")
}
```

***

## Error Handling

Each method may throw an error if:

- The characteristic is not set by the user
- The permission is denied
- HealthKit is unavailable

Example:

```ts
try {
  const sex = await Health.biologicalSex()
  console.log(sex)
} catch (err) {
  console.error("Failed to read biological sex:", err)
}
```

***

## Summary

You can access personal attributes using the following global APIs:

```ts
await Health.dateOfBirth()
await Health.biologicalSex()
await Health.bloodType()
await Health.fitzpatrickSkinType()
await Health.wheelchairUse()
await Health.activityMoveMode()
```

These values are static and reflect the user’s personal configuration in the Health app. Be sure to handle missing or unset values gracefully.



---
url: /guide/Device Capabilities/Health/Reading Correlation Data.md
---

# Reading Correlation Data

The Scripting app allows you to query **correlated health data** using the global `Health.queryCorrelations()` API. A correlation groups related health samples into a single logical event — such as a blood pressure reading (systolic and diastolic) or a food intake record (calories, protein, etc.).

This guide explains how to retrieve and interpret correlation data from HealthKit.

***

## What Is a Correlation?

A **correlation** in HealthKit represents a composite health event made up of multiple samples, including:

- `"bloodPressure"` — combines `bloodPressureSystolic` and `bloodPressureDiastolic`
- `"food"` — may include `dietaryEnergyConsumed`, `dietaryProtein`, `dietaryCarbohydrates`, etc.

Each correlation includes:

- Start and end date
- Type (`"bloodPressure"` or `"food"`)
- Metadata (optional)
- Associated samples (quantity or category samples)

***

## API Overview

```ts
Health.queryCorrelations(
  correlationType: HealthCorrelationType,
  options?: {
    startDate?: Date
    endDate?: Date
    limit?: number
    strictStartDate?: boolean
    strictEndDate?: boolean
    sortDescriptors?: Array<{
      key: "startDate" | "endDate"
      order?: "forward" | "reverse"
    }>
  }
): Promise<HealthCorrelation[]>
```

***

## Parameters

| Parameter                         | Description                                 |
| --------------------------------- | ------------------------------------------- |
| `correlationType`                 | `"bloodPressure"` or `"food"`               |
| `startDate`/`endDate`             | Query time range                            |
| `limit`                           | Maximum number of correlations to return    |
| `strictStartDate`/`strictEndDate` | Whether to match exact boundaries           |
| `sortDescriptors`                 | Sort by `startDate` or `endDate` (optional) |

***

## Example: Query Blood Pressure Correlations

```ts
const correlations = await Health.queryCorrelations("bloodPressure", {
  startDate: new Date("2025-07-01T00:00:00"),
  endDate: new Date("2025-07-02T00:00:00"),
  limit: 5,
  sortDescriptors: [{ key: "startDate", order: "reverse" }]
})

for (const correlation of correlations) {
  console.log("Start:", correlation.startDate)
  console.log("End:", correlation.endDate)

  const systolic = correlation.quantitySamples.find(
    s => s.quantityType === "bloodPressureSystolic"
  )

  const diastolic = correlation.quantitySamples.find(
    s => s.quantityType === "bloodPressureDiastolic"
  )

  if (systolic && diastolic) {
    const sys = systolic.quantityValue(HealthUnit.millimeterOfMercury())
    const dia = diastolic.quantityValue(HealthUnit.millimeterOfMercury())
    console.log(`Blood Pressure: ${sys}/${dia} mmHg`)
  }
}
```

***

## Example: Query Food Correlations

```ts
const correlations = await Health.queryCorrelations("food", {
  startDate: new Date(Date.now() - 86400 * 1000),
  limit: 10
})

for (const correlation of correlations) {
  console.log("Food intake at:", correlation.startDate)

  for (const sample of correlation.quantitySamples) {
    const value = sample.quantityValue(sample.quantityType.includes("Energy")
      ? HealthUnit.kilocalorie()
      : HealthUnit.gram())
    console.log(`${sample.quantityType}: ${value}`)
  }
}
```

***

## Accessing Correlation Samples

Each correlation contains the following sample arrays:

- `quantitySamples`: All quantity samples (including cumulative/discrete)
- `cumulativeQuantitySamples`: Only cumulative quantity samples
- `discreteQuantitySamples`: Only discrete quantity samples
- `categorySamples`: Any associated category samples (for future support)

You can use `.quantityType` and `.quantityValue(unit)` to interpret each sample.

***

## Error Handling

```ts
try {
  const results = await Health.queryCorrelations("bloodPressure")
  console.log("Found", results.length, "records")
} catch (err) {
  console.error("Failed to query correlations:", err)
}
```

***

## Summary

To read correlation data from HealthKit:

1. Call `Health.queryCorrelations(type, options)`
2. Iterate through each `HealthCorrelation`
3. Access `quantitySamples` or `categorySamples`
4. Use `.quantityValue(unit)` to extract values

This is useful for composite health records like blood pressure or nutrition intake.



---
url: /guide/Device Capabilities/Health/Reading Heartbeat Series Samples.md
---

# Reading Heartbeat Series Samples

The Scripting app provides access to **heartbeat series samples** stored in Apple Health using the global API `Health.queryHeartbeatSeriesSamples()`. These samples represent beat-to-beat heartbeat intervals collected during workouts or background monitoring sessions (usually via Apple Watch).

Each record contains the **time range**, **number of beats**, and optional **metadata**, but not the raw interval values.

***

## What Is a Heartbeat Series Sample?

A `HealthHeartbeatSeriesSample` object includes:

- `uuid`: A unique identifier for the sample
- `sampleType`: Always `"heartbeatSeries"`
- `startDate` / `endDate`: The time range over which the heartbeats were recorded
- `count`: The number of heartbeat intervals collected
- `metadata`: Optional information attached by the recording source (e.g., watch model, app version)

> **Note:** This API provides high-level information about the series. It does not expose individual heartbeat intervals.

***

## API Reference

```ts
Health.queryHeartbeatSeriesSamples(
  options?: {
    startDate?: Date
    endDate?: Date
    limit?: number
    strictStartDate?: boolean
    strictEndDate?: boolean
    sortDescriptors?: Array<{
      key: "startDate" | "endDate"
      order?: "forward" | "reverse"
    }>
    requestPermissions?: HealthQuantityType[]
  }
): Promise<HealthHeartbeatSeriesSample[]>
```

***

## Parameters

| Parameter                           | Description                                    |
| ----------------------------------- | ---------------------------------------------- |
| `startDate` / `endDate`             | Optional filter range for sample time interval |
| `limit`                             | Maximum number of samples to return            |
| `strictStartDate` / `strictEndDate` | Whether to include only exact matches          |
| `sortDescriptors`                   | Optional sorting by `startDate` or `endDate`   |
| `requestPermissions`                | Optional requesting permission for other types |

***

## Example: Query Recent Heartbeat Series

```ts
const results = await Health.queryHeartbeatSeriesSamples({
  startDate: new Date("2025-07-01T00:00:00"),
  endDate: new Date("2025-07-05T00:00:00"),
  limit: 10,
  sortDescriptors: [{ key: "startDate", order: "reverse" }]
})

for (const sample of results) {
  console.log("UUID:", sample.uuid)
  console.log("Start:", sample.startDate)
  console.log("End:", sample.endDate)
  console.log("Heartbeat count:", sample.count)
  console.log("Metadata:", sample.metadata)
  console.log("---")
}
```

***

## Limitations

- Individual heartbeat intervals (R–R data) are **not accessible** via this API.

- To analyze HRV or derive BPM, you’ll need **only the `count`** and **duration**:

  ```ts
  const durationSeconds = (sample.endDate.getTime() - sample.startDate.getTime()) / 1000
  const avgBPM = (sample.count / durationSeconds) * 60
  ```

- Gaps or anomalies (e.g. pauses, data loss) are not available in this summary sample.

***

## Summary

To read heartbeat series:

1. Call `Health.queryHeartbeatSeriesSamples()` with optional date range or limits.
2. Iterate through the returned `HealthHeartbeatSeriesSample` objects.
3. Each item provides `startDate`, `endDate`, `count`, and `metadata`.
4. You can approximate average BPM over the session using `count` and duration.

This API is useful for **overviewing heart rhythm tracking sessions**, especially for detecting how often heart rate was sampled during a day or workout.



---
url: /guide/Device Capabilities/Health/Reading Medications and Dose Events/index.md
---

# Reading Medications and Dose Events

The Scripting app provides read access to the **Medications** a person tracks in the Health app, together with their logged **dose events**, using `Health.queryMedications()` and `Health.queryMedicationDoseEvents()`.

> Requires iOS 26.0 or later. On earlier systems both functions reject with an error.

This guide explains how to list a person's medications and how to read the doses they logged.

***

## Medications and Dose Events

- A **medication** (`HealthUserAnnotatedMedication`) is something the person tracks in the Health app. It carries a `nickname`, an `isArchived` flag, a `hasSchedule` flag, and a `medication` concept.
- A **medication concept** (`HealthMedicationConcept`) describes the medication itself: a stable `identifier`, a `displayText` name, a `generalForm` (such as `"tablet"` or `"injection"`), and `relatedCodings` (such as RxNorm codes).
- A **dose event** (`HealthMedicationDoseEvent`) is a single logged dose — taken, skipped, snoozed, or not interacted with. It links back to a medication through `medicationConceptIdentifier`.

***

## Permission

Medications use **per-object authorization**: the first time you call `Health.queryMedications()`, the system asks the person to choose which medications your script may access. The Scripting app requests this automatically — you don't request authorization yourself.

***

## API Overview

```ts
Health.queryMedications(options?: {
  isArchived?: boolean
  hasSchedule?: boolean
  limit?: number
}): Promise<HealthUserAnnotatedMedication[]>

Health.queryMedicationDoseEvents(options?: {
  startDate?: Date
  endDate?: Date
  limit?: number
  strictStartDate?: boolean
  strictEndDate?: boolean
  sortDescriptors?: Array<{
    key: "startDate" | "endDate"
    order?: "forward" | "reverse"
  }>
  statuses?: HealthMedicationDoseEventLogStatus[]
  scheduledStartDate?: Date
  scheduledEndDate?: Date
  medicationConceptIdentifiers?: string[]
}): Promise<HealthMedicationDoseEvent[]>
```

***

## Example: Listing Active Medications

```ts
const medications = await Health.queryMedications({
  isArchived: false,
})

for (const item of medications) {
  console.log("Name:", item.nickname ?? item.medication.displayText)
  console.log("Form:", item.medication.generalForm)
  console.log("Scheduled:", item.hasSchedule)
}
```

***

## Example: Reading Today's Dose Events

```ts
const startOfDay = new Date()
startOfDay.setHours(0, 0, 0, 0)

const doses = await Health.queryMedicationDoseEvents({
  startDate: startOfDay,
  endDate: new Date(),
  sortDescriptors: [{ key: "startDate", order: "reverse" }],
})

for (const dose of doses) {
  console.log("Status:", dose.logStatus)       // "taken" | "skipped" | ...
  console.log("Dose:", dose.doseQuantity, dose.unit.unitString)
  console.log("When:", dose.startDate)
}
```

***

## Example: Doses for a Specific Medication

Use a medication's `identifier` to fetch only its doses:

```ts
const medications = await Health.queryMedications({ isArchived: false })
const target = medications[0]

const doses = await Health.queryMedicationDoseEvents({
  medicationConceptIdentifiers: [target.medication.identifier],
  statuses: ["taken"],
})

console.log(`Logged ${doses.length} taken dose(s) of ${target.medication.displayText}`)
```

***

## Notes

- `Health.queryMedications()` returns `HealthUserAnnotatedMedication` instances; `Health.queryMedicationDoseEvents()` returns `HealthMedicationDoseEvent` instances.
- `scheduledDate` and `scheduledDoseQuantity` are only present for scheduled dose events (`scheduleType === "schedule"`); they are `null` for as-needed doses.
- A dose event's `medicationConceptIdentifier` matches the `identifier` of the medication's concept, so you can group doses by medication.
- These APIs are read-only — medications and dose events are managed by the Health app and can't be created from a script.

***

## Summary

1. Use `Health.queryMedications()` to list the medications a person tracks.
2. Use `Health.queryMedicationDoseEvents()` to read logged doses, filtered by date, status, schedule window, or medication.
3. Link the two with `HealthMedicationConcept.identifier` / `HealthMedicationDoseEvent.medicationConceptIdentifier`.



---
url: /guide/Device Capabilities/Health/Reading Medications and Dose Events/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text, useState } from "scripting"

// 把一次服药事件格式化成一行可读文本。
function describeDose(dose: HealthMedicationDoseEvent): string {
  const parts: string[] = [dose.logStatus]
  if (dose.doseQuantity != null) {
    parts.push(`${dose.doseQuantity} ${dose.unit.unitString}`)
  }
  parts.push(dose.startDate.toLocaleString())
  return parts.join(" · ")
}

// 服药事件详情页:用某个用药的 identifier 只取它的 dose events,演示两个 API 的串联。
function DoseEventsView({
  medication,
}: {
  medication: HealthUserAnnotatedMedication
}) {
  const dismiss = Navigation.useDismiss()
  const [doses, setDoses] = useState<HealthMedicationDoseEvent[] | null>(null)
  const [error, setError] = useState<string | null>(null)

  const load = async () => {
    setError(null)
    try {
      const end = new Date()
      const start = new Date(end.getTime() - 30 * 86400 * 1000) // 近 30 天
      const result = await Health.queryMedicationDoseEvents({
        startDate: start,
        endDate: end,
        medicationConceptIdentifiers: [medication.medication.identifier],
        sortDescriptors: [{ key: "startDate", order: "reverse" }],
      })
      setDoses(result)
    } catch (e) {
      setError(String(e))
    }
  }

  return <NavigationStack>
    <List
      navigationTitle={medication.nickname ?? medication.medication.displayText}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button title={"Done"} action={dismiss} />,
        confirmationAction: <Button title={"Load"} action={load} />,
      }}
    >
      {error != null
        ? <Text foregroundStyle={"systemRed"}>{error}</Text>
        : doses == null
          ? <Text foregroundStyle={"secondaryLabel"}>Tap “Load” to read the dose events from the last 30 days.</Text>
          : doses.length === 0
            ? <Text foregroundStyle={"secondaryLabel"}>No dose events found.</Text>
            : <Section header={<Text>{`${doses.length} dose event(s)`}</Text>}>
                {doses.map(dose => <Text key={dose.uuid}>{describeDose(dose)}</Text>)}
              </Section>}
    </List>
  </NavigationStack>
}

function Example() {
  const [medications, setMedications] = useState<HealthUserAnnotatedMedication[] | null>(null)
  const [error, setError] = useState<string | null>(null)

  // 查询用户在「健康」中跟踪的用药。首次调用会触发 per-object 授权(系统弹「选择药物」)。
  const loadMedications = async () => {
    if (!Health.isHealthDataAvailable) {
      await Dialog.alert({ message: "Health data is not available on this device." })
      return
    }
    setError(null)
    try {
      const result = await Health.queryMedications({ isArchived: false })
      setMedications(result)
    } catch (e) {
      // iOS 26 以下会在这里 reject。
      setError(String(e))
    }
  }

  const openDoses = (medication: HealthUserAnnotatedMedication) => {
    Navigation.present({ element: <DoseEventsView medication={medication} /> })
  }

  return <NavigationStack>
    <List
      navigationTitle={"Medications"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Text font={"footnote"} foregroundStyle={"secondaryLabel"}>
        Reads the medications tracked in the Health app and their logged doses. Requires iOS 26 and grants access to the medications you choose.
      </Text>

      <Button title={"Load medications"} action={loadMedications} />

      {error != null
        ? <Text foregroundStyle={"systemRed"}>{error}</Text>
        : medications == null
          ? null
          : medications.length === 0
            ? <Text foregroundStyle={"secondaryLabel"}>No medications found.</Text>
            : <Section header={<Text>{`${medications.length} medication(s)`}</Text>}>
                {medications.map(item => <Button
                  key={item.medication.identifier}
                  action={() => openDoses(item)}
                >
                  <Text>{item.nickname ?? item.medication.displayText}</Text>
                  <Text font={"footnote"} foregroundStyle={"secondaryLabel"}>
                    {`${item.medication.generalForm}${item.hasSchedule ? " · scheduled" : ""}`}
                  </Text>
                </Button>)}
              </Section>}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/Health/Reading Quantity Samples.md
---

# Reading Quantity Samples

The Scripting app allows you to query **quantity-based health data**, such as step count, heart rate, body mass, calories burned, distance, and more, using the global `Health.queryQuantitySamples()` API.

This guide explains how to retrieve quantity samples and work with the results.

***

## What Are Quantity Samples?

A **quantity sample** represents a numeric health measurement taken at a specific time or over a time interval. Common examples include:

- `stepCount`
- `heartRate`
- `bodyMass`
- `activeEnergyBurned`
- `distanceWalkingRunning`

These samples can be either **discrete** (a single measurement) or **cumulative** (a value summed over time).

***

## API Overview

```ts
Health.queryQuantitySamples(
  quantityType: HealthQuantityType,
  options?: {
    startDate?: Date
    endDate?: Date
    limit?: number
    strictStartDate?: boolean
    strictEndDate?: boolean
    sortDescriptors?: Array<{
      key: "startDate" | "endDate" | "count"
      order?: "forward" | "reverse"
    }>
  }
): Promise<Array<HealthQuantitySample | HealthCumulativeQuantitySample | HealthDiscreteQuantitySample>>
```

***

## Parameters

- `quantityType`: The health data type to query (e.g., `"stepCount"`, `"heartRate"`)
- `startDate` / `endDate`: Time range for filtering samples
- `limit`: Maximum number of results
- `strictStartDate` / `strictEndDate`: If `true`, only samples starting/ending exactly at those dates will be included
- `sortDescriptors`: Optional array to sort results by `startDate`, `endDate`, or `count`

***

## Sample Code: Reading Step Count

```ts
const results = await Health.queryQuantitySamples("stepCount", {
  startDate: new Date("2025-07-01T00:00:00"),
  endDate: new Date("2025-07-02T00:00:00"),
  limit: 10,
  sortDescriptors: [{ key: "startDate", order: "reverse" }]
})

for (const sample of results) {
  const value = sample.quantityValue(HealthUnit.count())
  console.log(`Steps: ${value} from ${sample.startDate} to ${sample.endDate}`)
}
```

***

## Sample Code: Reading Heart Rate with Unit

```ts
const results = await Health.queryQuantitySamples("heartRate", {
  startDate: new Date(Date.now() - 3600 * 1000), // past hour
})

for (const sample of results) {
  const bpm = sample.quantityValue(
    HealthUnit.count().divided(HealthUnit.minute())
  )
  console.log(`Heart Rate: ${bpm} bpm at ${sample.startDate}`)
}
```

***

## Interpreting Sample Types

Each sample returned may be:

- `HealthQuantitySample`: The base class
- `HealthCumulativeQuantitySample`: Includes `.sumQuantity(unit)`
- `HealthDiscreteQuantitySample`: Includes `.averageQuantity(unit)`, `.maximumQuantity(unit)`, etc.

You can use `instanceof` or feature detection to check for extended properties.

Example:

```ts
if ("averageQuantity" in sample) {
  const avg = sample.averageQuantity(HealthUnit.count())
  console.log("Average:", avg)
}
```

***

## Notes

- The unit passed to `.quantityValue()` **must match** the type (e.g., use `count()` for steps, `gram(HealthMetricPrefix.kilo)` for body mass).
- Some types (like heart rate) require compound units like `count().divided(minute())`.
- The time interval is defined by `startDate` and `endDate` on each sample.
- Samples may have an optional `.metadata` and `.count`.

***

## Common Units by Type

| Quantity Type              | Recommended Unit                                  |
| -------------------------- | ------------------------------------------------- |
| `"stepCount"`              | `HealthUnit.count()`                              |
| `"heartRate"`              | `HealthUnit.count().divided(HealthUnit.minute())` |
| `"bodyMass"`               | `HealthUnit.gram(HealthMetricPrefix.kilo)`        |
| `"activeEnergyBurned"`     | `HealthUnit.kilocalorie()`                        |
| `"distanceWalkingRunning"` | `HealthUnit.meter()`                              |

***

## Error Handling

```ts
try {
  const results = await Health.queryQuantitySamples("stepCount")
  console.log("Sample count:", results.length)
} catch (err) {
  console.error("Failed to query samples:", err)
}
```

***

## Summary

To read quantity samples:

1. Call `Health.queryQuantitySamples(type, options)`
2. Loop through the results
3. Use `.quantityValue(unit)` or `.sumQuantity(unit)` depending on the type

This API gives you powerful access to time-series health data stored in HealthKit.



---
url: /guide/Device Capabilities/Health/Reading Workout Samples.md
---

# Reading Workout Samples

The Scripting app allows you to retrieve **workout sessions** from HealthKit using the global `Health.queryWorkouts()` function. Workouts represent physical activity sessions such as running, walking, swimming, cycling, strength training, and more.

Each workout includes metadata such as duration, activity type, start/end times, and detailed statistics like heart rate, distance, and energy burned.

***

## What Is a Workout?

A **HealthWorkout** record contains:

- `startDate` / `endDate`: The duration of the workout session
- `duration`: Total duration in seconds
- `workoutActivityType`: Enum representing the workout type (e.g., running, walking)
- `metadata`: Optional custom metadata
- `workoutEvents`: Optional array of workout-related events (e.g., pauses, laps)
- `allStatistics`: A dictionary of detailed quantity statistics (e.g., heart rate, distance, calories)

***

## API Overview

```ts
Health.queryWorkouts(
  options?: {
    startDate?: Date
    endDate?: Date
    limit?: number
    strictStartDate?: boolean
    strictEndDate?: boolean
    sortDescriptors?: Array<{
      key: "startDate" | "endDate" | "duration"
      order?: "forward" | "reverse"
    }>
    requestPermissions?: HealthQuantityType[]
  }
): Promise<HealthWorkout[]>
```

***

## Parameters

| Parameter                           | Description                                                                         |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| `startDate` / `endDate`             | Optional time range to filter workouts                                              |
| `limit`                             | Maximum number of workouts to return                                                |
| `strictStartDate` / `strictEndDate` | Whether to match the exact start/end dates                                          |
| `sortDescriptors`                   | Sort results by `startDate`, `endDate`, or `duration`                               |
| `requestPermissions`                | An array of health quantity types for which to request permissions before querying. |

***

## Example: Read Recent Workouts

```ts
const workouts = await Health.queryWorkouts({
  startDate: new Date("2025-07-01"),
  endDate: new Date("2025-07-05"),
  sortDescriptors: [{ key: "startDate", order: "reverse" }]
})

for (const workout of workouts) {
  console.log("Workout Type:", workout.workoutActivityType)
  console.log("Start:", workout.startDate)
  console.log("End:", workout.endDate)
  console.log("Duration (min):", workout.duration / 60)

  const heartRate = workout.allStatistics["heartRate"]
  const energy = workout.allStatistics["activeEnergyBurned"]

  if (heartRate) {
    const avgHR = heartRate.averageQuantity(HealthUnit.count().divided(HealthUnit.minute()))
    console.log("Avg Heart Rate:", avgHR)
  }

  if (energy) {
    const kcal = energy.sumQuantity(HealthUnit.kilocalorie())
    console.log("Calories Burned:", kcal)
  }

  console.log("---")
}
```

***

## Accessing Detailed Statistics

The `allStatistics` dictionary provides detailed quantity data recorded during the workout. You can extract values using:

```ts
const stat = workout.allStatistics["heartRate"]
const avg = stat?.averageQuantity(HealthUnit.count().divided(HealthUnit.minute()))
const max = stat?.maximumQuantity(HealthUnit.count().divided(HealthUnit.minute()))
```

Common available statistics include:

- `"heartRate"`
- `"activeEnergyBurned"`
- `"distanceWalkingRunning"`
- `"stepCount"`

***

## Workout Events (Optional)

If recorded, `workout.workoutEvents` contains an array of time-stamped workout events:

```ts
for (const event of workout.workoutEvents || []) {
  console.log("Event:", event.type)
  console.log("From:", event.dateInterval.start)
  console.log("To:", event.dateInterval.end)
}
```

Event types include: pause, resume, lap, segment, motion pause/resume, etc.

***

## Notes

- Each workout is an instance of `HealthWorkout`
- `workoutActivityType` is an enum, which you can map to labels or icons
- If `allStatistics` is missing some keys, the data may not have been recorded by the device/app
- You can combine workout data with category and quantity samples for full activity insights

***

## Summary

To read workouts from HealthKit:

1. Call `Health.queryWorkouts(options)` to get a list of `HealthWorkout` records
2. Use `startDate`, `endDate`, and sorting options to filter and order results
3. Access properties like `duration`, `activityType`, and `allStatistics` for insights
4. Optionally inspect `workoutEvents` and metadata

This API is ideal for analyzing exercise history, generating workout summaries, or visualizing fitness trends.



---
url: /guide/Device Capabilities/Health/Requesting Multiple Permissions at Once/index.md
---

# Requesting Multiple Permissions at Once

When a script needs access to several kinds of HealthKit data, you don't have to ask for each permission separately. If you trigger multiple permission-requiring `Health` APIs around the same time, the app collects the pending authorizations within a short window and presents a **single** HealthKit authorization sheet that lists all of them.

This keeps the experience clean: the user sees one combined sheet instead of a chain of separate prompts.

***

## How It Works

Every read/write `Health` API (such as `queryQuantitySamples`, `queryCategorySamples`, `queryWorkouts`, or `dateOfBirth`) requests authorization for the data it touches before running. When you start several of them together, those requests are merged:

- Requests that arrive close together are batched into one authorization sheet.
- Data types that were already authorized are skipped, so no sheet appears when nothing new is needed.
- If more requests arrive while a sheet is still on screen, they are queued and presented after the current one is dismissed.

You don't call any explicit "request permission" method — just call the APIs you need, and authorization is requested automatically.

***

## Requesting Multiple Permissions at Once

Use `Promise.all` (or `Promise.allSettled`) to start the queries together:

```ts
const results = await Promise.allSettled([
  Health.queryQuantitySamples("stepCount", { limit: 1 }),
  Health.queryQuantitySamples("heartRate", { limit: 1 }),
  Health.queryCategorySamples("sleepAnalysis", { limit: 1 }),
  Health.queryWorkouts({ limit: 1 }),
  Health.dateOfBirth(),
])

console.log(results)
```

All of these queries touch different HealthKit data types, so HealthKit shows one sheet covering every type that still needs authorization.

***

## Requesting One at a Time

If you `await` each request before starting the next, every call completes its authorization before the following one begins, so the user may see a separate sheet for each:

```ts
await Health.queryQuantitySamples("stepCount", { limit: 1 })
await Health.queryCategorySamples("sleepAnalysis", { limit: 1 })
await Health.queryWorkouts({ limit: 1 })
```

Prefer starting requests together when you know up front which data types your script needs.

***

## Notes

- `Health` APIs require a Scripting PRO subscription.
- Check `Health.isHealthDataAvailable` before querying; it is `false` on devices without HealthKit.
- The authorization sheet only lists data types that are not yet determined. If everything is already authorized, no sheet appears and the queries run immediately.



---
url: /guide/Device Capabilities/Health/Requesting Multiple Permissions at Once/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, Text } from "scripting"

// 同时触发多个需要授权的 Health API,验证它们会合并成一次 HealthKit 授权弹框。
async function requestTogether() {
  if (!Health.isHealthDataAvailable) {
    await Dialog.alert({ message: "Health data is not available on this device." })
    return
  }

  // Fire several permission-requiring queries at the same time. The app
  // collects the pending authorizations within a short window and shows a
  // single HealthKit permission sheet covering all of them.
  const tasks: Record<string, Promise<unknown>> = {
    "Step Count": Health.queryQuantitySamples("stepCount", { limit: 1 }),
    "Heart Rate": Health.queryQuantitySamples("heartRate", { limit: 1 }),
    "Active Energy": Health.queryQuantitySamples("activeEnergyBurned", { limit: 1 }),
    "Sleep Analysis": Health.queryCategorySamples("sleepAnalysis", { limit: 1 }),
    "Workouts": Health.queryWorkouts({ limit: 1 }),
    "Date of Birth": Health.dateOfBirth(),
  }

  const labels = Object.keys(tasks)
  const results = await Promise.allSettled(Object.values(tasks))

  const summary = results.map((result, index) => {
    const label = labels[index]
    if (result.status === "fulfilled") {
      const value = result.value
      const detail = Array.isArray(value) ? `${value.length} item(s)` : "ok"
      return `${label}: ${detail}`
    }
    return `${label}: failed (${result.reason})`
  }).join("\n")

  console.log(summary)
  await Dialog.alert({ title: "Permission results", message: summary })
}

// 逐个 await 调用:每个请求在下一个开始前就完成授权,因此会弹出多个分开的授权弹框,
// 与上面的"合并请求"形成对照。
async function requestSequentially() {
  if (!Health.isHealthDataAvailable) {
    await Dialog.alert({ message: "Health data is not available on this device." })
    return
  }

  try {
    await Health.queryQuantitySamples("stepCount", { limit: 1 })
    await Health.queryCategorySamples("sleepAnalysis", { limit: 1 })
    await Health.queryWorkouts({ limit: 1 })
    await Dialog.alert({ message: "Sequential requests finished." })
  } catch (error) {
    await Dialog.alert({ title: "Failed", message: String(error) })
  }
}

function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"Multiple Permissions"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Text
        font={"footnote"}
        foregroundStyle={"secondaryLabel"}
      >
        Calling several permission-requiring Health APIs at once merges their authorization into a single HealthKit sheet.
      </Text>

      <Button
        title={"Request multiple permissions together"}
        action={requestTogether}
      />

      <Button
        title={"Request sequentially (separate sheets)"}
        action={requestSequentially}
      />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/Health/Writing Health Category Samples.md
---

# Writing Health Category Samples

The Scripting app allows you to write **categorical health data** to Apple HealthKit using the `HealthCategorySample` class and the `Health.saveCategorySample()` method. Category samples represent discrete health-related events or conditions, such as sleep stages, mindful sessions, menstrual flow, ovulation test results, and more.

This guide describes how to create and save a `HealthCategorySample`.

***

## Prerequisites

- Confirm that HealthKit is available on the device:

  ```ts
  if (!Health.isHealthDataAvailable) {
    throw new Error("Health data is not available on this device.")
  }
  ```

- Ensure the script has the required permission for the target category type. The Scripting app will automatically request authorization if needed when saving.

***

## 1. Create a `HealthCategorySample`

Use `HealthCategorySample.create()` to construct a new category sample.

### Parameters

- `type`: A `HealthCategoryType` string (e.g., `"sleepAnalysis"`, `"mindfulSession"`, `"menstrualFlow"`, etc.).
- `startDate`: The beginning of the time interval that the event applies to (JavaScript `Date`).
- `endDate`: The end of the event’s time interval (JavaScript `Date`).
- `value`: The integer value representing the state of the category. You must use the corresponding enum value based on the type.
- `metadata` _(optional)_: An optional metadata object describing additional attributes.

### Value Mapping

The `value` must be one of the pre-defined category values. For example:

- For `"sleepAnalysis"`, use the `HealthCategoryValueSleepAnalysis` enum:

  - `HealthCategoryValueSleepAnalysis.asleepCore`
  - `HealthCategoryValueSleepAnalysis.awake`
  - etc.

- For `"menstrualFlow"`, use `HealthCategoryValueSeverity`:

  - `HealthCategoryValueSeverity.mild`, `moderate`, `severe`, etc.

Refer to each category type’s enum definition for valid values.

***

### Example

```ts
const sample = HealthCategorySample.create({
  type: "sleepAnalysis",
  startDate: new Date("2025-07-03T23:00:00"),
  endDate: new Date("2025-07-04T07:00:00"),
  value: HealthCategoryValueSleepAnalysis.asleepCore,
  metadata: {
    source: "ScriptingApp"
  }
})

if (!sample) {
  throw new Error("Failed to create HealthCategorySample.")
}
```

***

## 2. Save the Category Sample

Use `Health.saveCategorySample()` to save the created sample to HealthKit.

```ts
await Health.saveCategorySample(sample)
```

If saving fails (e.g., due to permission denial), the promise will reject with an error.

***

## Full Example

```ts
async function writeSleepData() {
  const sample = HealthCategorySample.create({
    type: "sleepAnalysis",
    startDate: new Date("2025-07-03T23:00:00"),
    endDate: new Date("2025-07-04T07:00:00"),
    value: HealthCategoryValueSleepAnalysis.asleepCore,
  })

  if (!sample) {
    console.error("Failed to create sample.")
    return
  }

  try {
    await Health.saveCategorySample(sample)
    console.log("Sleep data saved successfully.")
  } catch (err) {
    console.error("Error saving sample:", err)
  }
}

writeSleepData()
```

***

## Notes

- The `value` must be a valid enum for the selected `type`, or the creation will fail.
- `startDate` and `endDate` define the time range the event applies to — e.g., a sleep session or a mindful moment.
- Metadata is optional but can be useful for tagging data source or context.



---
url: /guide/Device Capabilities/Health/Writing Health Correlation Data.md
---

# Writing Health Correlation Data

In the Scripting app, you can write **correlated health data** to Apple HealthKit using the global `HealthCorrelation.create()` method and `Health.saveCorrelation()`. A correlation represents a relationship between multiple health samples, such as a blood pressure reading that includes both systolic and diastolic values, or a meal record that includes nutritional quantities.

This guide explains how to create and save a correlation sample.

***

## What Is a Correlation?

A correlation groups related health data samples into a single, logical record. HealthKit currently supports the following correlation types:

- `"bloodPressure"` — includes two quantity samples: `"bloodPressureSystolic"` and `"bloodPressureDiastolic"`
- `"food"` — can include multiple nutritional quantity samples such as calories, protein, carbohydrates, etc.

***

## 1. Create Related Quantity Samples

Before creating a correlation, you must first create the individual `HealthQuantitySample` instances that will be included.

### Example: Blood Pressure Samples

```ts
const systolic = HealthQuantitySample.create({
  type: "bloodPressureSystolic",
  startDate: new Date(),
  endDate: new Date(),
  value: 120,
  unit: HealthUnit.millimeterOfMercury()
})

const diastolic = HealthQuantitySample.create({
  type: "bloodPressureDiastolic",
  startDate: new Date(),
  endDate: new Date(),
  value: 80,
  unit: HealthUnit.millimeterOfMercury()
})
```

Check that both samples are not null before proceeding.

***

## 2. Create the Correlation

Use `HealthCorrelation.create()` to group the samples into a correlation.

### Parameters

- `type`: `"bloodPressure"` or `"food"`
- `startDate`: Start of the event
- `endDate`: End of the event
- `objects`: An array of `HealthQuantitySample` (or `HealthCategorySample`) instances to include
- `metadata` _(optional)_: Additional metadata (e.g., source, context)

### Example

```ts
const correlation = HealthCorrelation.create({
  type: "bloodPressure",
  startDate: systolic.startDate,
  endDate: systolic.endDate,
  objects: [systolic, diastolic],
  metadata: {
    source: "ScriptingApp"
  }
})

if (!correlation) {
  throw new Error("Failed to create correlation.")
}
```

***

## 3. Save the Correlation to HealthKit

Use `Health.saveCorrelation()` to persist the correlation data to the HealthKit store.

```ts
await Health.saveCorrelation(correlation)
```

***

## Full Example: Writing a Blood Pressure Correlation

```ts
async function writeBloodPressure() {
  const systolic = HealthQuantitySample.create({
    type: "bloodPressureSystolic",
    startDate: new Date(),
    endDate: new Date(),
    value: 120,
    unit: HealthUnit.millimeterOfMercury()
  })

  const diastolic = HealthQuantitySample.create({
    type: "bloodPressureDiastolic",
    startDate: new Date(),
    endDate: new Date(),
    value: 80,
    unit: HealthUnit.millimeterOfMercury()
  })

  if (!systolic || !diastolic) {
    console.error("Failed to create samples.")
    return
  }

  const correlation = HealthCorrelation.create({
    type: "bloodPressure",
    startDate: systolic.startDate,
    endDate: systolic.endDate,
    objects: [systolic, diastolic],
    metadata: {
      note: "Manually recorded",
    }
  })

  if (!correlation) {
    console.error("Failed to create correlation.")
    return
  }

  try {
    await Health.saveCorrelation(correlation)
    console.log("Blood pressure data saved.")
  } catch (err) {
    console.error("Failed to save:", err)
  }
}

writeBloodPressure()
```

***

## Notes

- All quantity samples in the correlation **must have matching or consistent time ranges**.
- For `"bloodPressure"`, the correlation must include **both** `systolic` and `diastolic` samples.
- For `"food"`, you may include multiple samples like:

  - `"dietaryEnergyConsumed"` → `HealthUnit.kilocalorie()`
  - `"dietaryProtein"` → `HealthUnit.gram()`
  - `"dietaryCarbohydrates"` → `HealthUnit.gram()`
- Correlation creation returns `null` if invalid or incomplete.



---
url: /guide/Device Capabilities/Health/Writing Health Quantity Samples.md
---

# Writing Health Quantity Samples

The Scripting app allows you to write quantity-based health data (such as step count, heart rate, calories, and more) to Apple HealthKit using the `HealthQuantitySample` class and the `Health.saveQuantitySample` method.

This guide explains how to create and save a new quantity sample.

## Prerequisites

- Ensure HealthKit is available on the device:

  ```ts
  if (!Health.isHealthDataAvailable) {
    throw new Error("Health data is not available on this device.")
  }
  ```

- Make sure your script has the appropriate write permission for the quantity type you want to save. Permissions are requested automatically when you call save APIs.

## 1. Create a `HealthQuantitySample`

Use `HealthQuantitySample.create()` to instantiate a new sample.

### Parameters

- `type`: A `HealthQuantityType` string, such as `"stepCount"`, `"heartRate"`, `"bodyMass"`, etc.
- `startDate`: The start of the measurement period (a JavaScript `Date` object).
- `endDate`: The end of the measurement period (a JavaScript `Date` object).
- `value`: The numeric value of the sample.
- `unit`: A `HealthUnit` representing the measurement unit (e.g., `HealthUnit.count()`, `HealthUnit.gram()`, `HealthUnit.meter()`).
- `metadata` _(optional)_: An object containing additional metadata.

### Example

```ts
const sample = HealthQuantitySample.create({
  type: "stepCount",
  startDate: new Date("2025-07-03T08:00:00"),
  endDate: new Date("2025-07-03T09:00:00"),
  value: 1200,
  unit: HealthUnit.count(),
  metadata: {
    source: "ScriptingApp"
  }
})

if (!sample) {
  throw new Error("Failed to create HealthQuantitySample.")
}
```

## 2. Save the Quantity Sample

After creating the sample, use `Health.saveQuantitySample()` to store it in the HealthKit database.

```ts
await Health.saveQuantitySample(sample)
```

If saving fails (e.g., due to missing permissions), the promise will reject with an error.

## Full Example

```ts
async function writeStepCount() {
  const sample = HealthQuantitySample.create({
    type: "stepCount",
    startDate: new Date("2025-07-03T08:00:00"),
    endDate: new Date("2025-07-03T09:00:00"),
    value: 1200,
    unit: HealthUnit.count(),
  })

  if (!sample) {
    console.error("Failed to create sample.")
    return
  }

  try {
    await Health.saveQuantitySample(sample)
    console.log("Step count saved successfully.")
  } catch (err) {
    console.error("Failed to save sample:", err)
  }
}

writeStepCount()
```

## Notes

- The unit must match the type. For example:

  - `"stepCount"` → `HealthUnit.count()`
  - `"bodyMass"` → `HealthUnit.gram(HealthMetrixPrefix.kilo)`
  - `"heartRate"` → `HealthUnit.count().divided(HealthUnit.minute())`
- If the sample’s type is cumulative (e.g., steps, distance), the `startDate` and `endDate` should cover the time window over which the value was measured.



---
url: /guide/Device Capabilities/HomeKit/HMAccessory.md
---

# HMAccessory

`HMAccessory` is a single HomeKit accessory — a light, sensor, lock, thermostat, etc. — and its services.

***

## Read-only properties

| Property                | Type                  | Description                                               |
| ----------------------- | --------------------- | --------------------------------------------------------- |
| `uuid`                  | `string`              | Stable HomeKit UUID.                                      |
| `name`                  | `string`              | User-assigned name.                                       |
| `room`                  | `HMRoom \| null`      | The room this accessory belongs to.                       |
| `category`              | `HMAccessoryCategory` | High-level category (`'lightbulb'`, `'thermostat'`, ...). |
| `manufacturer`          | `string \| null`      |                                                           |
| `model`                 | `string \| null`      |                                                           |
| `firmwareVersion`       | `string \| null`      |                                                           |
| `isReachable`           | `boolean`             | Whether HomeKit can talk to it right now.                 |
| `isBlocked`             | `boolean`             |                                                           |
| `isBridged`             | `boolean`             | True if this accessory is exposed via a HomeKit bridge.   |
| `bridgedAccessoryUUIDs` | `string[] \| null`    | Children if this is a bridge.                             |
| `services`              | `HMService[]`         | Cluster of typed characteristics.                         |

***

## Operations

```ts
await accessory.rename("Living Room Lamp")
await accessory.identify()                       // ask the accessory to physically identify (e.g. blink)
```

***

## Events

```ts
accessory.onReachabilityChanged    = ok => { /* ... */ }
accessory.onNameChanged            = name => { /* ... */ }
accessory.onServicesChanged        = list => { /* ... */ }
accessory.onFirmwareVersionChanged = v => { /* ... */ }
```

***

## Example: turn a light on

```ts
const home = await HMHomeManager.primaryHome
const light = home?.accessories.find(a => a.category === 'lightbulb')
const power = light?.services
  .find(s => s.serviceType === 'lightbulb')
  ?.characteristics.find(c => c.characteristicType === 'powerState')

await power?.writeValue(true)
```



---
url: /guide/Device Capabilities/HomeKit/HMActionSet.md
---

# HMActionSet

`HMActionSet` is a HomeKit scene — a named bundle of characteristic write actions executed atomically.

There are two kinds:

- **User-defined** scenes you create via `home.addUserActionSet(name)`, then populate with `addCharacteristicAction(...)`.
- **System** scenes (`wakeUp`, `sleep`, `homeArrival`, `homeDeparture`) that Apple maintains automatically. You can read them via `home.builtinActionSets()` and execute them, but not modify their actions.

***

## Properties

| Property            | Type                            | Description                                                                                   |
| ------------------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
| `uuid`              | `string`                        |                                                                                               |
| `name`              | `string`                        |                                                                                               |
| `type`              | `HMActionSetType`               | `'userDefined' \| 'wakeUp' \| 'sleep' \| 'homeArrival' \| 'homeDeparture' \| 'triggerOwned'`. |
| `isExecuting`       | `boolean`                       |                                                                                               |
| `lastExecutionDate` | `Date \| null`                  |                                                                                               |
| `actions`           | `HMCharacteristicWriteAction[]` | Read-only snapshot of the included writes.                                                    |

***

## Building a scene

```ts
const movie = await home.addUserActionSet("Movie Time")

const lampPower = livingRoomLight.services
  .find(s => s.serviceType === 'lightbulb')!
  .characteristics.find(c => c.characteristicType === 'powerState')!

await movie.addCharacteristicAction(lampPower, false)

await home.executeActionSet(movie)
```

Remove individual actions with `removeCharacteristicAction(characteristic)`, or remove the whole scene with `home.removeActionSet(movie)`.



---
url: /guide/Device Capabilities/HomeKit/HMCharacteristic.md
---

# HMCharacteristic

`HMCharacteristic` is a single readable / writable / observable value on an `HMService`. It exposes its current value, allowed range/format via `metadata`, and an event-subscription API.

***

## Properties

| Property             | Type                               | Description                                                  |
| -------------------- | ---------------------------------- | ------------------------------------------------------------ |
| `uuid`               | `string`                           | Stable HomeKit UUID.                                         |
| `serviceUUID`        | `string`                           | UUID of the parent service.                                  |
| `characteristicType` | `HMCharacteristicType`             | Semantic role (`'powerState'`, `'currentTemperature'`, ...). |
| `properties`         | `HMCharacteristicProperty[]`       | `'readable' \| 'writable' \| 'supportsEvent' \| 'hidden'`.   |
| `metadata`           | `HMCharacteristicMetadata \| null` | Format / units / min / max / validValues.                    |
| `value`              | `HMCharacteristicValue \| null`    | Last cached value (use `readValue()` to refresh).            |

***

## Read & write

```ts
const v = await ch.readValue()                   // hits the accessory
await ch.writeValue(true)                        // coerced & range-checked vs metadata
```

`writeValue` rejects with an `Error` when the value violates `metadata.minimumValue` / `metadata.maximumValue` / `metadata.validValues` / `metadata.maxLength`.

***

## Subscribe to value changes

```ts
await ch.subscribe((err, value) => {
  if (err) return console.error(err)
  console.log("update:", value)
})

// later
await ch.unsubscribe()
```

> HomeKit notification delivery is best-effort. For mission-critical observation, also poll `readValue()` periodically.



---
url: /guide/Device Capabilities/HomeKit/HMHome.md
---

# HMHome

`HMHome` represents a single HomeKit home and its full graph of rooms, accessories, scenes, zones, and users.

***

## Read-only graph

| Property        | Type               | Description                                                                |
| --------------- | ------------------ | -------------------------------------------------------------------------- |
| `uuid`          | `string`           | Stable HomeKit UUID.                                                       |
| `name`          | `string`           | Display name.                                                              |
| `isPrimary`     | `boolean`          | Whether this is the user's primary home (deprecated by Apple in iOS 16.1). |
| `rooms`         | `HMRoom[]`         | All rooms (including the default "entire-home" room).                      |
| `accessories`   | `HMAccessory[]`    | All accessories paired in this home.                                       |
| `actionSets`    | `HMActionSet[]`    | All scenes (user-defined + system: wakeUp / sleep / arrival / departure).  |
| `zones`         | `HMZone[]`         | Zones (user groupings of rooms).                                           |
| `serviceGroups` | `HMServiceGroup[]` | Service groups (read-only in v1).                                          |
| `currentUser`   | `HMUser`           | The current logged-in user.                                                |

***

## Mutations

```ts
await home.rename("Cabin")

const room = await home.addRoom("Garage")
await home.removeRoom(room)

await home.addAndSetupAccessories()              // shows the system add-accessory UI
await home.removeAccessory(accessory)
await home.assignAccessoryToRoom(accessory, room)

const zone = await home.addZone("Upstairs")
await home.removeZone(zone)

await home.executeActionSet(scene)
const scene = await home.addUserActionSet("Movie Time")
await home.removeActionSet(scene)
```

`builtinActionSets()` returns the four system scenes:

```ts
const { wakeUp, sleep, homeArrival, homeDeparture } = home.builtinActionSets()
if (homeArrival) await home.executeActionSet(homeArrival)
```

***

## Events

```ts
home.onAccessoriesChanged = list => { /* ... */ }
home.onRoomsChanged       = list => { /* ... */ }
home.onActionSetsChanged  = list => { /* ... */ }
home.onNameChanged        = name => { /* ... */ }
```



---
url: /guide/Device Capabilities/HomeKit/HMHomeManager.md
---

# 

***

title: HMHomeManager
description: Top-level entry: authorization, list of homes, primary home, and home/auth events.
tag: PRO
--------

`HMHomeManager` is the top-level entry into HomeKit. It exposes the user's homes and home-update events.

> The system permission prompt is triggered automatically the first time you call any `HMHomeManager.*` API — you do not need to request it manually. Toggle the permission later from **Settings → Permissions → HomeKit** or **Settings → Privacy & Security → HomeKit**.

***

## Reading homes

```ts
const homes = await HMHomeManager.homes        // HMHome[]
```

The getter waits internally until HomeKit has finished its initial sync (Apple does not deliver `homes` synchronously after construction).

If the user has not yet decided on the system HomeKit permission, the first access shows the standard iOS permission prompt and the promise resolves once the user makes a choice. If the user denies access, the promise rejects with an _"HomeKit access is not authorized"_ error.

> Apple removed the explicit "primary home" concept in iOS 16.1, so this API does not expose `primaryHome` / `updatePrimaryHome`. Use `(await HMHomeManager.homes)[0]` if you want a default home.

***

## Mutating homes

```ts
await HMHomeManager.addHome("Beach House")
await HMHomeManager.removeHome(home)
```

***

## Events

```ts
HMHomeManager.onHomesChanged = homes => console.log("homes count:", homes.length)
```

Setting the callback to `null` stops further deliveries.



---
url: /guide/Device Capabilities/HomeKit/HMRoom.md
---

# HMRoom

`HMRoom` is a named grouping of accessories within an `HMHome`.

```ts
class HMRoom {
  readonly uuid: string
  readonly name: string
  readonly accessories: HMAccessory[]

  rename(name: string): Promise<void>
}
```

To create / delete a room, use `home.addRoom(name)` / `home.removeRoom(room)`. To move an accessory between rooms, use `home.assignAccessoryToRoom(accessory, room)`.



---
url: /guide/Device Capabilities/HomeKit/HMService.md
---

# HMService

`HMService` is a typed cluster of characteristics on an `HMAccessory`. The service type (`'lightbulb'`, `'thermostat'`, `'temperatureSensor'`, ...) tells you what role the cluster plays.

```ts
class HMService {
  readonly uuid: string
  readonly name: string
  readonly serviceType: HMServiceType
  readonly accessoryUUID: string
  readonly isPrimaryService: boolean
  readonly isUserInteractive: boolean
  readonly characteristics: HMCharacteristic[]
  readonly linkedServices: HMService[] | null
  readonly associatedServiceType: HMServiceType | null

  rename(name: string): Promise<void>
  updateAssociatedServiceType(type: HMServiceType | null): Promise<void>
}
```

> Service types form an open string union — `HMServiceType` includes the well-known values plus `(string & {})` so newer HomeKit versions still surface unknown types as raw strings.



---
url: /guide/Device Capabilities/HomeKit/HMZone.md
---

# HMZone

`HMZone` is a user-defined grouping of rooms (e.g. "Upstairs", "Outdoor"). Rooms can belong to multiple zones.

```ts
class HMZone {
  readonly uuid: string
  readonly name: string
  readonly rooms: HMRoom[]

  rename(name: string): Promise<void>
  addRoom(room: HMRoom): Promise<void>
  removeRoom(room: HMRoom): Promise<void>
}
```

Create / delete zones via `home.addZone(name)` / `home.removeZone(zone)`.



---
url: /guide/Device Capabilities/ImageIO.md
---

# ImageIO

Low-level image container I/O: read EXIF / GPS / TIFF / IPTC metadata, and encode images to formats (and with embedded metadata) that `UIImage.toPNGData` / `toJPEGData` can't produce.

> **Why not just use `UIImage`?** A `UIImage` is a _decoded bitmap_ — by the time you have one, the original file's metadata (EXIF, GPS, ...) is already gone, and `toPNGData` / `toJPEGData` cannot write HEIC / TIFF / GIF. `ImageIO` works at the encoded-container level, so it can both read existing metadata and write it back.

```ts
// Read metadata
const meta = await ImageIO.readMetadata("/path/to/photo.jpg")
console.log(meta.pixelWidth, meta.pixelHeight)
console.log(meta.gps?.Latitude, meta.gps?.Longitude)

// Re-encode a UIImage to HEIC with GPS
await ImageIO.writeImage({
  image,                       // a UIImage
  to: "/path/to/out.heic",
  format: "heic",
  quality: 0.9,
  metadata: {
    gps: { Latitude: 37.33, LatitudeRef: "N", Longitude: 122.0, LongitudeRef: "W" },
  },
})
```

***

## `ImageIO.readMetadata(source)`

```ts
function readMetadata(source: string | Data): Promise<ImageMetadata>
```

Reads container-level metadata from a file path or `Data`. Rejects if the source can't be decoded as an image.

```ts
type ImageMetadata = {
  pixelWidth?: number
  pixelHeight?: number
  dpiWidth?: number
  dpiHeight?: number
  depth?: number
  colorModel?: string
  orientation?: number        // EXIF orientation 1–8
  hasAlpha?: boolean
  profileName?: string
  exif?: Record<string, any>  // CGImageProperties Exif keys, e.g. DateTimeOriginal
  gps?: Record<string, any>   // GPS keys, e.g. Latitude / Longitude / LatitudeRef
  tiff?: Record<string, any>
  iptc?: Record<string, any>
}
```

The well-known dictionaries (`exif` / `gps` / `tiff` / `iptc`) use Apple's CGImageProperties key names verbatim (`gps.Latitude`, `exif.DateTimeOriginal`, ...).

***

## `ImageIO.writeImage(options)`

```ts
function writeImage(options: ImageWriteOptions): Promise<void>
```

Encodes and writes an image to `to`. Provide **exactly one** of `image` or `source`:

| Field       | Type                                           | Notes                                                                                                                         |
| ----------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `image?`    | `UIImage`                                      | Re-encode from a decoded bitmap. The original file's metadata is **not** preserved — only the `metadata` you pass is written. |
| `source?`   | `string \| Data`                               | Copy from an original encoded image, **preserving its metadata**, then overlay the `metadata` you pass.                       |
| `to`        | `string`                                       | Output file path. An existing file is overwritten.                                                                            |
| `format?`   | `'jpeg' \| 'png' \| 'heic' \| 'tiff' \| 'gif'` | Required with `image`; defaults to the source's format with `source`.                                                         |
| `quality?`  | `number`                                       | Lossy compression 0..1 (jpeg / heic only).                                                                                    |
| `metadata?` | `ImageMetadata`                                | Merged on top of the source's metadata when using `source`.                                                                   |

### Tag a photo with GPS while keeping its EXIF

Use the `source` variant — re-encoding through a `UIImage` would drop the original EXIF:

```ts
await ImageIO.writeImage({
  source: "/path/to/original.jpg",   // keeps original EXIF / TIFF
  to: "/path/to/tagged.jpg",
  metadata: { gps: { Latitude: 10.0, LatitudeRef: "N" } },  // overlay GPS
})
```

***

## Caveats

- **`image` drops original metadata.** A `UIImage` is a decoded bitmap. To preserve a file's existing EXIF/GPS, use the `source` variant, not `image`.
- **`quality` only applies to jpeg / heic.** It's ignored for png / tiff / gif.
- **HEIC encoding** requires a device/simulator that supports the HEVC image encoder; on older simulators HEIC may fail — fall back to jpeg if `writeImage` rejects.
- **Key names are raw CGImageProperties keys.** When writing `exif` / `gps` / `tiff` / `iptc`, use Apple's key names (e.g. `Latitude`, `LatitudeRef`, `DateTimeOriginal`).



---
url: /guide/Device Capabilities/Keychain.md
---

# Keychain

`Keychain` provides secure access to the system keychain for storing **sensitive and persistent data** inside the Scripting environment. It is designed for:

- Authentication tokens
- Login credentials
- License and subscription states
- Encryption keys
- Private user data

All data is protected using the system-level Keychain security mechanism.

***

## 1. Per-Script Keychain Scope

In Scripting, `Keychain` uses a **per-script isolation model**.

### 1.1 Scope Rules

- Each script has its **own independent Keychain scope**
- A script can **only access the Keychain data it has written**
- Different scripts:

  - Cannot read each other’s Keychain data
  - Cannot overwrite each other’s keys
  - Even if the same key name is used
  - Even if `synchronizable: true` is enabled
- Each script is treated as an **independent security sandbox**

***

### 1.2 Security Implications

This design ensures that:

- No script can steal credentials from another script
- Subscription, login state, and authorization data are fully isolated
- Malicious scripts cannot access private user data stored by other scripts
- The security boundary is stricter than the system-level app Keychain alone

***

### 1.3 Script Removal Behavior

- When a script is deleted:

  - All Keychain data under that script’s scope is automatically removed
- Other scripts’ Keychain data is not affected

***

## 2. Namespace

```ts
namespace Keychain
```

***

## 3. Supported Data Types

`Keychain` supports three data types:

| Type        | Write     | Read      |
| ----------- | --------- | --------- |
| String      | `set`     | `get`     |
| Boolean     | `setBool` | `getBool` |
| Binary Data | `setData` | `getData` |

***

## 4. KeychainAccessibility

```ts
type KeychainAccessibility =
  | 'passcode'
  | 'unlocked'
  | 'unlocked_this_device'
  | 'first_unlock'
  | 'first_unlock_this_device'
```

| Value                      | Description                                                                     |
| -------------------------- | ------------------------------------------------------------------------------- |
| `passcode`                 | Accessible only when a device passcode is set; does not migrate to a new device |
| `unlocked`                 | Accessible only while the device is unlocked                                    |
| `unlocked_this_device`     | Accessible only on the current device; does not migrate                         |
| `first_unlock`             | Accessible after the first unlock following a restart                           |
| `first_unlock_this_device` | Same as `first_unlock`, but does not migrate                                    |

The default depends on whether iCloud synchronization is enabled:

```ts
synchronizable: false // accessibility: "first_unlock_this_device"
synchronizable: true  // accessibility: "first_unlock"
```

When `synchronizable: true` is used, `passcode`, `unlocked_this_device`, and `first_unlock_this_device` are not allowed because they have `ThisDeviceOnly` semantics and cannot synchronize to other devices. Writes with these combinations fail and return `false`.

***

## 5. iCloud Synchronization (synchronizable)

```ts
synchronizable?: boolean
```

| Value   | Description                                         |
| ------- | --------------------------------------------------- |
| `true`  | Synchronizes across devices using the same Apple ID |
| `false` | Stored only on the local device                     |

Default:

```ts
synchronizable: false
```

When enabled, Keychain items use the migratable default accessibility policy `first_unlock`. If you customize `accessibility`, use a synchronizable policy such as `unlocked` or `first_unlock`.

Even when enabled, synchronization is still restricted to the **current script scope**.

***

## 6. Writing Data

### 6.1 Store a String

```ts
Keychain.set(key: string, value: string, options?): boolean
```

```ts
Keychain.set("token", "abcdef")
```

```ts
Keychain.set("token", "abcdef", {
  accessibility: "first_unlock",
  synchronizable: true
})
```

***

### 6.2 Store a Boolean

```ts
Keychain.setBool(key: string, value: boolean, options?): boolean
```

```ts
Keychain.setBool("is_login", true)
```

***

### 6.3 Store Binary Data

```ts
Keychain.setData(key: string, value: Data, options?): boolean
```

```ts
Keychain.setData("avatar", imageData)
```

***

### 6.4 Overwrite Rules

- Existing values are automatically overwritten
- `true` is returned on success
- `false` is returned on failure

***

## 7. Reading Data

### 7.1 Read a String

```ts
Keychain.get(key: string, options?): string | null
```

***

### 7.2 Read a Boolean

```ts
Keychain.getBool(key: string, options?): boolean | null
```

***

### 7.3 Read Binary Data

```ts
Keychain.getData(key: string, options?): Data | null
```

***

## 8. Removing Data

```ts
Keychain.remove(key: string, options?): boolean
```

- If the key exists, it is deleted and returns `true`
- If the key does not exist, it still safely returns `true`

***

## 9. Checking for Key Existence

```ts
Keychain.contains(key: string, options?): boolean
```

***

## 10. Listing All Keys

```ts
Keychain.keys(options?): string[]
```

***

## 11. Clearing the Keychain

```ts
Keychain.clear(options?): boolean
```

Behavior:

- Only clears data within the **current script scope**
- Does not affect other scripts
- Does not affect the app’s own Keychain data or other apps

***

## 12. synchronizable Read/Write Consistency Rules

If a key is written with:

```ts
synchronizable: true
```

Then all subsequent operations **must use the same flag**:

```ts
Keychain.set("token", "abc", { synchronizable: true })

Keychain.get("token") // Cannot read
Keychain.get("token", { synchronizable: true }) // Can read
```

***

## 13. Security Recommendations

### Suitable Data

- Authentication tokens
- Subscription and license states
- User identifiers
- Encryption keys

### Not Recommended

- Large binary files
- High-frequency cache data
- Public configuration values

***

## 14. Typical Usage Examples

```ts
// Write
Keychain.set("token", "abcdef")
Keychain.setBool("is_login", true)
Keychain.setData("avatar", avatarData)

// Read
const token = Keychain.get("token")
const isLogin = Keychain.getBool("is_login")
const avatar = Keychain.getData("avatar")

// Remove
Keychain.remove("token")

// Check existence
Keychain.contains("token")

// List all keys
Keychain.keys()

// Clear
Keychain.clear()
```



---
url: /guide/Device Capabilities/LanguageModelSession.md
---

# LanguageModelSession

`LanguageModelSession` provides access to Apple Intelligence local language models through iOS Foundation Models. It allows scripts to perform on-device AI tasks such as text generation, structured JSON output, and streaming responses.

This API encapsulates system-level language model capabilities and supports:

- On-device AI inference (Apple Intelligence)
- JSON Schema structured output
- Streaming token responses
- Session-level resource management
- Controlled generation parameters

`LanguageModelSession` is a global API and does not require importing from the `scripting` module.

***

## Availability

```ts
LanguageModelSession.isAvailable
```

Indicates whether Foundation Models are available on the current device.

Return value:

```ts
boolean
```

Notes:

- Only devices supporting Apple Intelligence will return `true`.
- You should check availability before creating a session.

Example:

```ts
if (!LanguageModelSession.isAvailable) {
  console.log("LanguageModelSession is not available on this device")
}
```

***

## Creating a Session

```ts
new LanguageModelSession(options?)
```

Parameters:

```ts
{
  instructions?: string
}
```

Description:

- Creates a new language model session.
- `instructions` act as system-level guidance controlling model behavior.
- Instructions remain active throughout the session lifecycle.

Example:

```ts
const session = new LanguageModelSession({
  instructions: "You are a professional financial assistant."
})
```

***

## Properties

## isResponding

```ts
readonly isResponding: boolean
```

Description:

- Indicates whether the model is currently generating a response.
- Useful for managing UI state.

***

## Prewarming the Model

```ts
prewarm(promptPrefix?: string): void
```

Description:

- Requests the system to load required model resources in advance.
- Reduces initial response latency.
- Optionally caches a prompt prefix.

Parameters:

```ts
promptPrefix?: string
```

Example:

```ts
session.prewarm("You are a JSON extraction assistant")
```

Recommended use cases:

- Before the user initiates an AI task
- When reducing first-token latency is important

***

## Generating Responses

```ts
respond<T>(prompt, options?)
```

Returns:

```ts
Promise<{
  content: string
  json: T | null
}>
```

Description:

- Produces a complete response.
- Supports structured JSON output via schema validation.
- Automatically attempts JSON parsing.

Parameters:

```ts
{
  temperature?: number
  maxResponseTokens?: number
  schema?: JSONSchemaObject
}
```

Parameter details:

- `temperature`

  - Range: 0.0 \~ 1.0
  - Higher values increase randomness.
- `maxResponseTokens`

  - Maximum number of tokens to generate.
- `schema`

  - Expected JSON structure.
  - If generated content is not valid JSON, `json` will be `null`.

***

## Structured Output Example

```ts
const session = new LanguageModelSession()

const result = await session.respond(
  `Parse the following receipt:
  Parking fee
  Convention Center
  2026-02-09 12:23:45
  ¥19
  Credit card payment`,
  {
    schema: {
      type: "object",
      description: "Receipt JSON",
      properties: {
        amount: { type: "number", description: "Amount" },
        category: { type: "string", description: "Category" },
        address: { type: "string", description: "Address", required: false },
        isIncome: { type: "boolean", decription: "Whether it is an income" }
      }
    }
  }
)

console.log(result.content)
console.log(result.json)
```

***

## Streaming Responses

```ts
streamResponse(prompt, options?)
```

Returns:

```ts
Promise<ReadableStream>
```

Description:

- Produces streaming output.
- Suitable for chat interfaces or incremental display.

Parameters:

```ts
{
  temperature?: number
  maxResponseTokens?: number
}
```

Example:

```ts
const stream = await session.streamResponse(
  "Tell a joke about a dog",
  { temperature: 0.7 }
)

let fullText = ""

for await (const chunk of stream) {
  console.log(chunk)
  fullText = chunk
}
```

***

## Releasing Resources

```ts
dispose(): void
```

Description:

- Releases resources associated with the session.
- Recommended after finishing usage to reduce memory usage.

Example:

```ts
session.dispose()
```

***

## Complete Example

```tsx
import { Script } from "scripting"

console.present().then(() => {
  Script.exit()
})

async function run() {

  if (!LanguageModelSession.isAvailable) {
    console.log("Not supported on this device")
    return
  }

  const session = new LanguageModelSession({
    instructions: "You are a structured data extraction assistant."
  })

  session.prewarm("Parse receipt")

  const result = await session.respond(
    "Parse: Parking fee Convention Center ¥19",
    {
      temperature: 0.2,
      schema: {
        type: "object",
        description: "JSON result",
        properties: {
          amount: { type: "number", description: "Amount" },
          category: { type: "string", description: "Category" }
        }
      }
    }
  )

  console.log(result.json)

  const stream = await session.streamResponse(
    "Tell a joke about a dog"
  )

  for await (const text of stream) {
    console.log(text)
  }

  session.dispose()
}

run()
```

***

## Best Practices

- Reuse a session for multiple requests when possible.
- Call `prewarm` before first use to reduce latency.
- Use `schema` for reliable structured output.
- Use `streamResponse` for long-form or interactive responses.
- Call `dispose` when finished to release resources.



---
url: /guide/Device Capabilities/LocalAuth.md
---

# LocalAuth

The `LocalAuth` API is a wrapper around the iOS Local Authentication framework, enabling biometric or passcode authentication in your Scripting app scripts. This document explains how to use the `LocalAuth` API effectively.

## Overview

The `LocalAuth` module provides methods and properties for checking authentication availability and performing user authentication. It supports biometrics like Face ID, Touch ID, and Optic ID, as well as fallback options like passcodes.

***

## Properties

### `LocalAuth.isAvailable`

- **Type:** `boolean`
- **Description:** Indicates whether authentication can proceed using any available policies.
- **Example:**
  ```tsx
  if (LocalAuth.isAvailable) {
    console.log("Authentication is available.")
  } else {
    console.log("Authentication is not available.")
  }
  ```

### `LocalAuth.isBiometricsAvailable`

- **Type:** `boolean`
- **Description:** Indicates whether biometric authentication can proceed.
- **Example:**
  ```tsx
  if (LocalAuth.isBiometricsAvailable) {
    console.log("Biometric authentication is available.")
  } else {
    console.log("Biometric authentication is not available.")
  }
  ```

### `LocalAuth.biometryType`

- **Type:** `LocalAuthBiometryType`
- **Description:** Specifies the type of biometric authentication supported by the device. Possible values:
  - `"faceID"`
  - `"touchID"`
  - `"opticID"`
  - `"none"`
  - `"unknown"`
- **Example:**
  ```tsx
  const biometry = LocalAuth.biometryType
  console.log(`Biometry type: ${biometry}`)
  ```

***

## Methods

### `LocalAuth.authenticate(reason: string, useBiometrics?: boolean): Promise<boolean>`

- **Description:** Authenticates the user with available biometrics or a fallback method (e.g., passcode). Returns a promise that resolves to `true` if authentication succeeds, or `false` if it fails.
- **Parameters:**
  - `reason` (string): The message displayed to the user when prompting for authentication. This must not be empty. Example: `'Authenticate to access MyScript.'`
  - `useBiometrics` (boolean, optional): Defaults to `true`. If `true`, the method uses biometrics for authentication otherwise, it uses biometrics or a fallback method (e.g., passcode).
- **Example:**
  ```tsx
  async function authenticateUser() {
    const reason = "Authenticate to access MyScript."
    const result = await LocalAuth.authenticate(reason, true)
    if (result) {
      console.log("Authentication succeeded.")
    } else {
      console.log("Authentication failed.")
    }
  }

  authenticateUser()
  ```

***

## Usage Examples

### Check Biometric Availability

```tsx
if (LocalAuth.isBiometricsAvailable) {
  console.log("Device supports biometric authentication.")
  console.log(`Biometry type: ${LocalAuth.biometryType}`)
} else {
  console.log("Biometric authentication is not supported on this device.")
}
```

### Authenticate with Biometrics

```tsx
async function accessSecureData() {
  const authenticated = await LocalAuth.authenticate(
    "Authenticate to access secure data."
  )
  if (authenticated) {
    console.log("Access granted.")
  } else {
    console.log("Access denied.")
  }
}

accessSecureData()
```

### Fallback to Passcode Authentication

```tsx
async function authenticateWithFallback() {
  const authenticated = await LocalAuth.authenticate(
    "Authenticate to proceed.",
    false // Allow biometrics or passcode
  )
  console.log(authenticated ? "Authenticated" : "Authentication failed")
}

authenticateWithFallback()
```

***

## Notes

- Always provide a meaningful message in the `reason` parameter to help users understand why authentication is being requested.
- Use `LocalAuth.isAvailable` and `LocalAuth.isBiometricsAvailable` to check the availability of authentication options before invoking `LocalAuth.authenticate`.
- Handle both success and failure cases gracefully to provide a seamless user experience.



---
url: /guide/Device Capabilities/Location/index.md
---

# Location

The Location API provides access to the device’s geographic location, geocoding services, system map location picking, and heading (compass) information. It is available as a global API in Scripting and can be used directly without importing any modules.

The API respects system permissions, user-selected accuracy levels, and platform limitations, and is suitable for scripts, interactive views, and supported widget scenarios.

## LocationAccuracy

Defines the desired accuracy level for location data.

**Type Definition**

```ts
type LocationAccuracy =
  | "best"
  | "tenMeters"
  | "hundredMeters"
  | "kilometer"
  | "threeKilometers"
  | "bestForNavigation"
  | "reduced"
```

**Description**

- `best`
  Requests the highest accuracy available on the device.

- `tenMeters`
  Requests approximately 10-meter accuracy.

- `hundredMeters`
  Requests approximately 100-meter accuracy.

- `kilometer`
  Requests approximately 1-kilometer accuracy.

- `threeKilometers`
  Requests coarse accuracy within approximately 3 kilometers.

- `bestForNavigation`
  Optimized for navigation use cases, with higher update frequency and power consumption.

- `reduced`
  Requests reduced-accuracy location data, typically used when the user has granted approximate location access.

## LocationInfo

Represents a geographic coordinate with an associated timestamp.

**Type Definition**

```ts
type LocationInfo = {
  latitude: number
  longitude: number
  timestamp: number
}
```

**Properties**

- `latitude`
  Latitude in degrees.

- `longitude`
  Longitude in degrees.

- `timestamp`
  Time when the location was recorded, in milliseconds since the Unix epoch.

## LocationPlacemark

Provides a human-readable description of a geographic location, usually returned by geocoding operations.

**Type Definition**

```ts
type LocationPlacemark = {
  location?: LocationInfo
  region?: string
  timeZone?: string
  name?: string
  thoroughfare?: string
  subThoroughfare?: string
  locality?: string
  subLocality?: string
  administrativeArea?: string
  subAdministrativeArea?: string
  postalCode?: string
  isoCountryCode?: string
  country?: string
  inlandWater?: string
  ocean?: string
  areasOfInterest?: string[]
}
```

**Description**

A placemark may include address components, administrative regions, country information, and points of interest. Field availability depends on the location and system map data.

## Heading

Represents compass and orientation information derived from the device’s sensors.

**Type Definition**

```ts
type Heading = {
  headingAccuracy: number
  trueHeading: number
  magneticHeading: number
  timestamp: Date
  x: number
  y: number
  z: number
}
```

**Properties**

- `headingAccuracy`
  Maximum deviation, in degrees, between the reported heading and the true geomagnetic heading.

- `trueHeading`
  Heading relative to true north, in degrees.

- `magneticHeading`
  Heading relative to magnetic north, in degrees.

- `timestamp`
  Time at which the heading was measured.

- `x`, `y`, `z`
  Raw geomagnetic field values for the three axes, measured in microteslas.

## Authorization and Configuration

### isAuthorizedForWidgetUpdates

```ts
const isAuthorizedForWidgetUpdates: boolean
```

Indicates whether the current widget is eligible to receive location updates.

### accuracy

```ts
const accuracy: LocationAccuracy
```

The currently configured desired location accuracy.

### setAccuracy

```ts
function setAccuracy(accuracy: LocationAccuracy): Promise<void>
```

Sets the desired accuracy level for subsequent location requests. Higher accuracy may increase power consumption and require additional permissions.

**Example**

```ts
await Location.setAccuracy("hundredMeters")
```

## Requesting Location

### requestCurrent

```ts
function requestCurrent(
  options?: { forceRequest?: boolean }
): Promise<LocationInfo | null>
```

Requests the device’s current location.

By default, a cached location is returned immediately if available. If no cached location exists, a new location request is performed.

When `forceRequest` is set to `true`, any cached location is ignored and a fresh request is always made.

**Example**

```ts
const location = await Location.requestCurrent()

if (location) {
  console.log(location.latitude, location.longitude)
}
```

Forcing a fresh location request:

```ts
const location = await Location.requestCurrent({
  forceRequest: true
})
```

### pickFromMap

```ts
function pickFromMap(): Promise<LocationInfo | null>
```

Presents the system map interface and allows the user to manually select a location.

**Example**

```ts
const picked = await Location.pickFromMap()

if (picked) {
  console.log("Picked location:", picked.latitude, picked.longitude)
}
```

## Geocoding

### reverseGeocode

```ts
function reverseGeocode(options: {
  latitude: number
  longitude: number
  locale?: string
}): Promise<LocationPlacemark[] | null>
```

Converts a geographic coordinate into human-readable address information.

**Example**

```ts
const placemarks = await Location.reverseGeocode({
  latitude: 39.9042,
  longitude: 116.4074,
  locale: "en-US"
})

console.log(placemarks?.[0]?.locality)
```

### geocodeAddress

```ts
function geocodeAddress(options: {
  address: string
  locale?: string
}): Promise<LocationPlacemark[] | null>
```

Converts a textual address into geographic placemark results.

**Example**

```ts
const results = await Location.geocodeAddress({
  address: "Times Square",
  locale: "en-US"
})

const location = results?.[0]?.location
```

## Heading and Compass

### requestHeading

```ts
function requestHeading(): Promise<Heading | null>
```

Returns the most recently reported heading. If heading updates have never been started, the result is `null`.

**Example**

```ts
const heading = await Location.requestHeading()

if (heading) {
  console.log(heading.trueHeading)
}
```

### startUpdatingHeading

```ts
function startUpdatingHeading(options?: {
  requestAlwaysAuthorization?: boolean
}): Promise<{ mode: "always" | "whenInUse" }>
```

Starts continuous heading updates.

When `options.requestAlwaysAuthorization` is `true`, the system requests "Always" authorization
instead of the default "When In Use".

The promise resolves with `{ mode }` reflecting the authorization actually granted by the
system. If you requested `"always"` but `mode` resolves as `"whenInUse"`, iOS did not (or
could not) prompt the user — typically because the user has already declined the upgrade
once. iOS allows only a single programmatic Always upgrade attempt; afterwards the user must
go to **Settings → Privacy & Security → Location Services → Scripting → Always** manually.

### stopUpdatingHeading

```ts
function stopUpdatingHeading(): void
```

Stops heading updates and releases related system resources.

### addHeadingListener

```ts
function addHeadingListener(
  listener: (heading: Heading) => void
): void
```

Registers a listener that is called whenever the heading changes.

**Example**

```ts
await Location.startUpdatingHeading()

Location.addHeadingListener(heading => {
  console.log("Heading:", heading.trueHeading)
})
```

### removeHeadingListener

```ts
function removeHeadingListener(
  listener?: (heading: Heading) => void
): void
```

Removes a previously registered heading listener. If no listener is provided, all heading listeners are removed.

### startUpdatingLocation

```ts
function startUpdatingLocation(options?: {
  requestAlwaysAuthorization?: boolean
}): Promise<{ mode: "always" | "whenInUse" }>
```

Starts continuous location updates. Subsequent updates are delivered to listeners registered via
`addLocationListener`.

When `options.requestAlwaysAuthorization` is `true`, the system requests "Always" authorization,
which is required if you intend to keep receiving updates while the app is backgrounded.

The promise resolves with `{ mode }` reflecting the authorization actually granted. If you
requested `"always"` but `mode` resolves as `"whenInUse"`, iOS suppressed the upgrade prompt
(only one programmatic Always upgrade attempt is permitted per app install). Direct the user
to **Settings → Privacy & Security → Location Services → Scripting → Always** to grant it
manually.

### stopUpdatingLocation

```ts
function stopUpdatingLocation(): void
```

Stops continuous location updates and releases related system resources.
This does not affect one-shot calls such as `requestCurrent`.

### addLocationListener

```ts
function addLocationListener(
  listener: (location: LocationInfo) => void
): void
```

Registers a listener that is called whenever a new location is reported.

**Example**

```ts
await Location.startUpdatingLocation()

Location.addLocationListener(location => {
  console.log("Lat/Lng:", location.latitude, location.longitude)
})
```

### removeLocationListener

```ts
function removeLocationListener(
  listener?: (location: LocationInfo) => void
): void
```

Removes a previously registered location listener. If no listener is provided, all location
listeners are removed and continuous updates stop.

### allowsBackgroundLocationUpdates / setAllowsBackgroundLocationUpdates

```ts
const allowsBackgroundLocationUpdates: boolean
function setAllowsBackgroundLocationUpdates(value: boolean): void
```

Whether the app receives location updates while in the background.

### pausesLocationUpdatesAutomatically / setPausesLocationUpdatesAutomatically

```ts
const pausesLocationUpdatesAutomatically: boolean
function setPausesLocationUpdatesAutomatically(value: boolean): void
```

Whether the system automatically pauses location updates when location data is unlikely to change.

### showsBackgroundLocationIndicator / setShowsBackgroundLocationIndicator

```ts
const showsBackgroundLocationIndicator: boolean
function setShowsBackgroundLocationIndicator(value: boolean): void
```

Whether the status bar background indicator is shown when the app uses location services
in the background under `authorizedAlways`.

### distanceFilter / setDistanceFilter

```ts
const distanceFilter: number
function setDistanceFilter(meters: number): void
```

The minimum horizontal distance (in meters) the device must move before a new update is
generated. Use `-1` to receive every movement.

### headingFilter / setHeadingFilter

```ts
const headingFilter: number
function setHeadingFilter(degrees: number): void
```

The minimum angular change (in degrees) required before a heading update is generated.
Use `-1` to receive every change.

### activityType / setActivityType

```ts
const activityType: ActivityType
function setActivityType(value: ActivityType): void
```

A hint that helps iOS optimize battery usage and accuracy:
`"other"`, `"automotiveNavigation"`, `"fitness"`, `"otherNavigation"` or `"airborne"`.



---
url: /guide/Device Capabilities/Location/index_example.md
---

# Example

```tsx
import {
  Button,
  List,
  Navigation,
  NavigationStack,
  Script,
  Section,
  Text,
  Toggle,
  useEffect,
  useState,
  VStack,
} from "scripting"

const accuracyCycle: LocationAccuracy[] = [
  "best",
  "tenMeters",
  "hundredMeters",
  "kilometer",
  "threeKilometers",
  "bestForNavigation",
  "reduced",
]

const activityCycle: Location.ActivityType[] = [
  "other",
  "automotiveNavigation",
  "fitness",
  "otherNavigation",
  "airborne",
]

function nextOf<T>(items: T[], current: T): T {
  const idx = items.indexOf(current)
  return items[(idx + 1) % items.length]
}

function fmt(n: number, digits = 4): string {
  return Number.isFinite(n) ? n.toFixed(digits) : String(n)
}

// Show a hint when "Always" was requested but iOS only granted "When In Use".
function maybeWarnAlwaysUpgrade(
  requested: boolean,
  result: { mode: "always" | "whenInUse" }
) {
  if (requested && result.mode !== "always") {
    Dialog.alert({
      title: "Always not granted",
      message:
        'iOS did not prompt for "Always" upgrade. Open Settings → Privacy & ' +
        'Security → Location Services → Scripting → Always to enable it manually.'
    })
  }
}

function Example() {
  const dismiss = Navigation.useDismiss()

  // Streaming readouts
  const [latestLocation, setLatestLocation] = useState<LocationInfo | null>(null)
  const [latestHeading, setLatestHeading] = useState<Location.Heading | null>(null)
  const [streamingLocation, setStreamingLocation] = useState(false)
  const [streamingHeading, setStreamingHeading] = useState(false)

  // Settings (mirrored to component state for UI re-render)
  const [accuracy, setAccuracyState] = useState<LocationAccuracy>(Location.accuracy)
  const [activityType, setActivityTypeState] = useState<Location.ActivityType>(Location.activityType)
  const [allowsBg, setAllowsBg] = useState(Location.allowsBackgroundLocationUpdates)
  const [pausesAuto, setPausesAuto] = useState(Location.pausesLocationUpdatesAutomatically)
  const [showsIndicator, setShowsIndicator] = useState(Location.showsBackgroundLocationIndicator)
  const [distanceFilter, setDistanceFilterState] = useState(Location.distanceFilter)
  const [headingFilter, setHeadingFilterState] = useState(Location.headingFilter)

  // Cleanup streams on unmount.
  useEffect(() => {
    return () => {
      Location.removeLocationListener()
      Location.removeHeadingListener()
      Location.stopUpdatingLocation()
      Location.stopUpdatingHeading()
    }
  }, [])

  return <NavigationStack>
    <List
      navigationTitle={"Location"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      {/* Read-only state */}
      <Section
        header={<Text>Status</Text>}
      >
        <VStack alignment={"leading"}>
          <Text font={"headline"}>isAuthorizedForWidgetUpdates</Text>
          <Text font={"caption"}>{String(Location.isAuthorizedForWidgetUpdates)}</Text>
        </VStack>
        <VStack alignment={"leading"}>
          <Text font={"headline"}>accuracy</Text>
          <Text font={"caption"}>{accuracy}</Text>
        </VStack>
        <VStack alignment={"leading"}>
          <Text font={"headline"}>activityType</Text>
          <Text font={"caption"}>{activityType}</Text>
        </VStack>
      </Section>

      {/* One-shot APIs */}
      <Section header={<Text>One-shot</Text>}>
        <Button
          title={"requestCurrent (cached if available)"}
          action={async () => {
            const loc = await Location.requestCurrent()
            Dialog.alert({
              message: loc
                ? `lat=${fmt(loc.latitude)}\nlng=${fmt(loc.longitude)}`
                : "No location returned."
            })
          }}
        />
        <Button
          title={"requestCurrent ({ forceRequest: true })"}
          action={async () => {
            const loc = await Location.requestCurrent({ forceRequest: true })
            Dialog.alert({
              message: loc
                ? `lat=${fmt(loc.latitude)}\nlng=${fmt(loc.longitude)}`
                : "No location returned."
            })
          }}
        />
        <Button
          title={"requestHeading"}
          action={async () => {
            const h = await Location.requestHeading()
            Dialog.alert({
              message: h
                ? `trueHeading=${fmt(h.trueHeading, 1)}\nmagnetic=${fmt(h.magneticHeading, 1)}`
                : "No heading available."
            })
          }}
        />
        <Button
          title={"pickFromMap"}
          action={async () => {
            const picked = await Location.pickFromMap()
            Dialog.alert({
              message: picked
                ? `lat=${fmt(picked.latitude)}\nlng=${fmt(picked.longitude)}`
                : "Cancelled."
            })
          }}
        />
        <Button
          title={"reverseGeocode (Apple Park)"}
          action={async () => {
            try {
              const placemarks = await Location.reverseGeocode({
                latitude: 37.334900,
                longitude: -122.009020,
              })
              const first = placemarks?.[0]
              Dialog.alert({
                message: first
                  ? `${first.name ?? ""}\n${first.locality ?? ""}, ${first.country ?? ""}`
                  : "No placemark found."
              })
            } catch (e) {
              Dialog.alert({ message: String(e) })
            }
          }}
        />
        <Button
          title={"geocodeAddress (\"1 Infinite Loop\")"}
          action={async () => {
            try {
              const placemarks = await Location.geocodeAddress({
                address: "1 Infinite Loop, Cupertino, CA",
              })
              const first = placemarks?.[0]
              Dialog.alert({
                message: first?.location
                  ? `lat=${fmt(first.location.latitude)}\nlng=${fmt(first.location.longitude)}`
                  : "No result."
              })
            } catch (e) {
              Dialog.alert({ message: String(e) })
            }
          }}
        />
      </Section>

      {/* Heading stream */}
      <Section
        header={<Text>Heading stream</Text>}
        footer={<Text>Toggle on to subscribe via addHeadingListener.</Text>}
      >
        <Toggle
          title={"startUpdatingHeading"}
          value={streamingHeading}
          onChanged={async (on) => {
            if (on) {
              try {
                const result = await Location.startUpdatingHeading({ requestAlwaysAuthorization: false })
                maybeWarnAlwaysUpgrade(false, result)
                Location.addHeadingListener(setLatestHeading)
                setStreamingHeading(true)
              } catch (e) {
                Dialog.alert({ message: String(e) })
              }
            } else {
              Location.removeHeadingListener(setLatestHeading)
              Location.stopUpdatingHeading()
              setStreamingHeading(false)
              setLatestHeading(null)
            }
          }}
        />
        <VStack alignment={"leading"}>
          <Text font={"headline"}>latest heading</Text>
          <Text font={"caption"}>
            {latestHeading
              ? `true=${fmt(latestHeading.trueHeading, 1)}° / mag=${fmt(latestHeading.magneticHeading, 1)}°`
              : "—"}
          </Text>
        </VStack>
      </Section>

      {/* Location stream */}
      <Section
        header={<Text>Location stream</Text>}
        footer={<Text>Toggle on to subscribe via addLocationListener.</Text>}
      >
        <Toggle
          title={"startUpdatingLocation (whenInUse)"}
          value={streamingLocation}
          onChanged={async (on) => {
            if (on) {
              try {
                const result = await Location.startUpdatingLocation({ requestAlwaysAuthorization: false })
                maybeWarnAlwaysUpgrade(false, result)
                Location.addLocationListener(setLatestLocation)
                setStreamingLocation(true)
              } catch (e) {
                Dialog.alert({ message: String(e) })
              }
            } else {
              Location.removeLocationListener(setLatestLocation)
              Location.stopUpdatingLocation()
              setStreamingLocation(false)
              setLatestLocation(null)
            }
          }}
        />
        <Button
          title={"Restart with requestAlwaysAuthorization"}
          action={async () => {
            Location.removeLocationListener(setLatestLocation)
            Location.stopUpdatingLocation()
            try {
              const result = await Location.startUpdatingLocation({ requestAlwaysAuthorization: true })
              maybeWarnAlwaysUpgrade(true, result)
              Location.addLocationListener(setLatestLocation)
              setStreamingLocation(true)
            } catch (e) {
              Dialog.alert({ message: String(e) })
            }
          }}
        />
        <VStack alignment={"leading"}>
          <Text font={"headline"}>latest location</Text>
          <Text font={"caption"}>
            {latestLocation
              ? `lat=${fmt(latestLocation.latitude)} / lng=${fmt(latestLocation.longitude)}`
              : "—"}
          </Text>
        </VStack>
      </Section>

      {/* Settings */}
      <Section
        header={<Text>Settings</Text>}
        footer={<Text>Tap a value to cycle through valid options.</Text>}
      >
        <Button
          title={`setAccuracy → ${accuracy}`}
          action={async () => {
            const next = nextOf(accuracyCycle, accuracy)
            await Location.setAccuracy(next)
            setAccuracyState(next)
          }}
        />
        <Button
          title={`setActivityType → ${activityType}`}
          action={() => {
            const next = nextOf(activityCycle, activityType)
            Location.setActivityType(next)
            setActivityTypeState(next)
          }}
        />
        <Toggle
          title={"allowsBackgroundLocationUpdates"}
          value={allowsBg}
          onChanged={(on) => {
            Location.setAllowsBackgroundLocationUpdates(on)
            setAllowsBg(on)
          }}
        />
        <Toggle
          title={"pausesLocationUpdatesAutomatically"}
          value={pausesAuto}
          onChanged={(on) => {
            Location.setPausesLocationUpdatesAutomatically(on)
            setPausesAuto(on)
          }}
        />
        <Toggle
          title={"showsBackgroundLocationIndicator"}
          value={showsIndicator}
          onChanged={(on) => {
            Location.setShowsBackgroundLocationIndicator(on)
            setShowsIndicator(on)
          }}
        />
        <Button
          title={`setDistanceFilter → ${distanceFilter}m`}
          action={() => {
            // -1 (none) → 0 → 10 → 100 → 500 → -1
            const presets = [-1, 0, 10, 100, 500]
            const idx = presets.indexOf(distanceFilter)
            const next = presets[(idx + 1) % presets.length]
            Location.setDistanceFilter(next)
            setDistanceFilterState(next)
          }}
        />
        <Button
          title={`setHeadingFilter → ${headingFilter}°`}
          action={() => {
            const presets = [-1, 1, 5, 15, 45]
            const idx = presets.indexOf(headingFilter)
            const next = presets[(idx + 1) % presets.length]
            Location.setHeadingFilter(next)
            setHeadingFilterState(next)
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/MapKit/Annotation/index.md
---

# 

***

title: Annotation
description: `<Annotation>` anchors a custom SwiftUI view at a map coordinate, beyond the stock `<Marker>` glyph.

***

`<Annotation>` anchors any view tree at a map coordinate. Unlike `<Marker>`,
which is constrained to a pin glyph plus a tint, an annotation renders
arbitrary children — badges, photos, custom shapes, anything you can build
with the views layer. Use it whenever the pin needs to look like something
other than a stock MapKit marker.

```tsx
<Map cameraPosition={cam}>
  <Annotation
    coordinate={{ latitude: 31.24, longitude: 121.49 }}
    title="Bund"
    anchor="bottom"
  >
    <ZStack>
      <Circle fill="systemRed" frame={{ width: 24, height: 24 }} />
      <Text font="caption2" foregroundStyle="white">★</Text>
    </ZStack>
  </Annotation>
</Map>
```

iOS 17+. Selection (`tag`) requires iOS 18+ — the same constraint as
`<Marker tag>`.

***

## Props

| Prop         | Type                     | Description                                                                       |
| ------------ | ------------------------ | --------------------------------------------------------------------------------- |
| `coordinate` | `MapCoordinate`          | Required. Where the annotation anchors on the map.                                |
| `title`      | `string?`                | Optional MapKit label shown next to the content view. Empty / omitted = no label. |
| `anchor`     | `KeywordPoint \| Point?` | Which point of the content view sticks to the coordinate. Defaults to `"center"`. |
| `tag`        | `string?`                | Stable identifier for `<Map selection>`. Untagged annotations are not selectable. |

### `anchor` values

`KeywordPoint` covers the SwiftUI named `UnitPoint`s — handy presets:

```ts
"center" | "top" | "bottom" | "leading" | "trailing"
| "topLeading" | "topTrailing" | "bottomLeading" | "bottomTrailing" | "zero"
```

For fine-grained placement, pass a `Point` in `[0..1]` unit space:

```tsx
<Annotation coordinate={pt} anchor={{ x: 0.5, y: 0.85 }}>...</Annotation>
```

A pin that points down at the coordinate, for example, anchors at
`"bottom"` (so the pin's bottom edge sits on the spot).

***

## Selection

Annotation taps participate in `<Map selection>` exactly the same way
tagged markers do — the bound observable receives
`{ type: "marker", tag }` when the user taps a tagged annotation, and
`null` when they tap empty map background:

```tsx
const selection = useObservable<MapSelectionValue | null>(null)

return <Map cameraPosition={cam} selection={selection}>
  <Annotation coordinate={spot} tag="bund" anchor="bottom">
    <CustomPin highlighted={isSelected(selection.value, "bund")} />
  </Annotation>
</Map>
```

Annotation does not participate in `<Map itemSelection>` — it has no
`MapItem` to bind to. If your script uses `itemSelection`, annotations
render normally but tapping them does not fire the observable.

***

## Map-level title / subtitle visibility

`<Map>` accepts two props for hiding or forcing the MapKit-rendered text
labels that accompany annotations:

| Prop                  | Type                                   | Description                                                                                                            |
| --------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `annotationTitles`    | `"automatic" \| "visible" \| "hidden"` | Title labels for `Marker(item:)`, `<Annotation>`, and Apple POI labels.                                                |
| `annotationSubtitles` | `"automatic" \| "visible" \| "hidden"` | Subtitle labels — mostly meaningful for `Marker(item:)` (whose `MapItem.placemark` carries a subtitle) and Apple POIs. |

```tsx
<Map cameraPosition={cam} annotationTitles="hidden">
  {/* No title labels rendered, including the <Annotation title> above. */}
  ...
</Map>
```

These are MapKit's `Visibility` enum — `"automatic"` follows MapKit's
default zoom-dependent behavior. `<Annotation>` does not carry a subtitle
field itself; `annotationSubtitles` therefore has no effect on annotation
output, only on items / Apple POIs in the same map.

***

## Custom popover / sheet on tap

The Annotation's content closure is a regular SwiftUI view subtree, so any
view-layer modifier — including `popover` and the sheet family — attaches
to it directly. There is no dedicated "Annotation card" prop because none
is needed: write the same modifier you would on a normal view.

```tsx
const selection = useObservable<MapSelectionValue | null>(null)
const popoverShown = useObservable(false)

// Sync the popover open state to the selection observable.
useEffect(() => {
  popoverShown.setValue(
    selection.value?.type === "marker" && selection.value.tag === "bund"
  )
}, [selection.value])

return <Map cameraPosition={cam} selection={selection}>
  <Annotation coordinate={spot} tag="bund" anchor="bottom">
    <CustomPin
      popover={{
        isPresented: popoverShown,
        content: <BundDetail onDismiss={() => selection.setValue(null)} />,
      }}
    />
  </Annotation>
</Map>
```

This is the same pattern SwiftUI itself uses for custom annotation cards —
the popover anchors to the annotation's content view automatically. Apple's
`itemDetailSelectionAccessory` / `featureSelectionAccessory` are only for
`Marker(item:)` and Apple-rendered POIs; `<Annotation>` rolls its own card
via this view-layer modifier path.

***

## When to choose `<Annotation>` vs `<Marker>`

- **`<Marker>`** — the visual is a stock MapKit pin: tint, optional SF
  Symbol glyph or monogram, optional auto POI glyph from `MapItem`. Use
  for "ordinary pins" and `MapItem`-based annotations.
- **`<Annotation>`** — the visual is your own SwiftUI subtree. Use when
  you need a chip, a photo callout, a stretched ribbon, or anything else
  that isn't a Marker glyph.

The two coexist freely inside the same `<Map>` and share the same
`<Map selection>` / `tag` mechanism.



---
url: /guide/Device Capabilities/MapKit/Annotation/index_example.md
---

# 

***

title: Example
description: `<Annotation>` anchors a custom SwiftUI view at a map coordinate, beyond the stock `<Marker>` glyph.

***

```tsx
import {
  Annotation, Button, Circle, HStack, Map, Marker, Navigation, NavigationStack,
  Picker, RoundedRectangle, Script, ScrollView, Spacer, Text, useEffect, useObservable, useState,
  VStack, ZStack,
} from "scripting"
import type { KeywordPoint, MapAnnotationLabelVisibility, MapSelectionValue } from "scripting"

// Demo center: People's Square, Shanghai
const initialRegion = {
  center: { latitude: 31.2304, longitude: 121.4737 },
  span: { latitudeDelta: 0.05, longitudeDelta: 0.05 },
}

// Three landmarks around the demo center.
const points = [
  { id: "bund", name: "Bund", coord: { latitude: 31.2397, longitude: 121.4906 } },
  { id: "lujia", name: "Lujiazui", coord: { latitude: 31.2397, longitude: 121.5000 } },
  { id: "xtd", name: "Xintiandi", coord: { latitude: 31.2218, longitude: 121.4760 } },
] as const

type PointId = (typeof points)[number]["id"]

function CustomPinDemo() {
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  const selection = useObservable<MapSelectionValue | null>(null)

  const tappedId =
    selection.value != null && selection.value.type === "marker"
      ? (selection.value.tag as PointId)
      : null
  const tapped = points.find(p => p.id === tappedId)

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>{`1. Custom-content \`<Annotation>\``}</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`Each pin is a custom SwiftUI subtree (rounded chip with letter). Tapping
      a chip writes its \`tag\` into \`<Map selection>\`; we use that to grow the
      selected chip and tint it red.`}
    </Text>
    {tapped != null
      ? <Text font={"caption"} foregroundStyle={"systemBlue"}>
        Selected: {tapped.name}
      </Text>
      : <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
        Tap a chip to select it.
      </Text>}
    <Map
      cameraPosition={position}
      selection={selection}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {points.map(p => {
        const isSelected = p.id === tappedId
        return <Annotation
          coordinate={p.coord}
          title={p.name}
          anchor="bottom"
          tag={p.id}
        >
          <ZStack>
            <RoundedRectangle
              cornerRadius={10}
              fill={isSelected ? "systemRed" : "systemBlue"}
              frame={{ width: isSelected ? 32 : 24, height: isSelected ? 32 : 24 }}
            />
            <Text
              font={isSelected ? "headline" : "caption"}
              foregroundStyle={"white"}
            >
              {p.name.charAt(0)}
            </Text>
          </ZStack>
        </Annotation>
      })}
    </Map>
  </VStack>
}

function AnchorPickerDemo() {
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  const [anchor, setAnchor] = useState<KeywordPoint>("center")

  const anchorOptions: KeywordPoint[] = [
    "center", "top", "bottom", "leading", "trailing",
    "topLeading", "topTrailing", "bottomLeading", "bottomTrailing",
  ]

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>2. `anchor` placement</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      The same content view, anchored at different `KeywordPoint`s relative to
      the same coordinate. `"bottom"` is the classic pin-style anchor (pin
      tip sits on the spot); `"center"` puts the visual center on the spot.
    </Text>
    <Picker title="anchor" value={anchor} onChanged={(v: any) => setAnchor(v as KeywordPoint)}>
      {anchorOptions.map(opt => (
        <Text tag={opt}>{opt}</Text>
      ))}
    </Picker>
    <Map
      cameraPosition={position}
      frame={{ height: 240 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      <Annotation
        coordinate={initialRegion.center}
        title=""
        anchor={anchor}
      >
        <ZStack>
          <Circle fill="systemOrange" frame={{ width: 28, height: 28 }} />
          <Text font="caption2" foregroundStyle={"white"}>●</Text>
        </ZStack>
      </Annotation>
      {/* Reference pin marks the exact coordinate the annotation is anchored to. */}
      <Marker title="" coordinate={initialRegion.center} tint="systemRed" />
    </Map>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      The red Marker pin marks the actual coordinate. Compare its position to
      the orange annotation as you cycle through anchors.
    </Text>
  </VStack>
}

function TitleVisibilityDemo() {
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  const [titles, setTitles] = useState<MapAnnotationLabelVisibility>("automatic")

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>{`3. \`<Map annotationTitles>\``}</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`Toggle the global title visibility. \`annotationTitles\` applies to
      \`Marker(item:)\`, \`<Annotation title>\`, and Apple POI labels in the
      same map.`}
    </Text>
    <Picker title="annotationTitles" value={titles} onChanged={(v: any) => setTitles(v as MapAnnotationLabelVisibility)}>
      <Text tag="automatic">automatic</Text>
      <Text tag="visible">visible</Text>
      <Text tag="hidden">hidden</Text>
    </Picker>
    <Map
      cameraPosition={position}
      annotationTitles={titles}
      frame={{ height: 240 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {points.map(p => (
        <Annotation coordinate={p.coord} title={p.name} anchor="bottom">
          <Circle fill="systemGreen" frame={{ width: 20, height: 20 }} />
        </Annotation>
      ))}
    </Map>
  </VStack>
}

function SelectionPopoverDemo() {
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  // selection 走 <Map selection>(Phase 3f),annotation tap 写入 { type:"marker", tag }
  const selection = useObservable<MapSelectionValue | null>(null)
  // popover 用 Observable<boolean> 形式,直接跟 selection 状态同步
  const popoverShown = useObservable(false)

  // selection → popover 双向同步:
  //  - 点中 annotation → 显示 popover
  //  - 点空白 / 关闭 popover → 清空 selection
  useEffect(() => {
    const isMarker =
      selection.value?.type === "marker" && selection.value.tag === "popover-pin"
    popoverShown.setValue(isMarker)
  }, [selection.value])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>{`4. Selection-driven popover`}</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`SwiftUI 原生模式:annotation content view 上直接挂 \`popover\` modifier。
      tap 写入 selection observable,我们再把它同步到 popover 的 isPresented。`}
    </Text>
    <Map
      cameraPosition={position}
      selection={selection}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      <Annotation
        coordinate={initialRegion.center}
        title="People's Square"
        anchor="bottom"
        tag="popover-pin"
      >
        <ZStack
          popover={{
            isPresented: popoverShown,
            arrowEdge: "bottom",
            presentationCompactAdaptation: "popover",
            content: <VStack alignment={"leading"} spacing={8} padding>
              <Text font={"headline"}>People's Square</Text>
              <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
                The popover anchors automatically to the annotation it sits on.
                Tap the map background to dismiss — selection clears and the
                popover hides via the observable.
              </Text>
              <HStack>
                <Spacer />
                <Button title="Close" action={() => selection.setValue(null)} />
              </HStack>
            </VStack>,
          }}
        >
          <Circle fill="systemPurple" frame={{ width: 28, height: 28 }} />
          <Text font="caption2" foregroundStyle={"white"}>i</Text>
        </ZStack>
      </Annotation>
    </Map>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      {`Apple's \`itemDetailSelectionAccessory\` is only for \`Marker(item:)\`. For
      \`<Annotation>\` you roll the card yourself with the same view modifier
      you'd use on any other view.`}
    </Text>
  </VStack>
}

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Annotation"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"Annotation"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={24}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`Custom-content map annotations. Use whenever a pin's visual needs to
          be something other than a stock MapKit marker glyph. Coexists with
          \`<Marker>\` in the same \`<Map>\` and shares the \`<Map selection>\` /
            \`tag\` selection mechanism.`}
        </Text>

        <CustomPinDemo />
        <AnchorPickerDemo />
        <TitleVisibilityDemo />
        <SelectionPopoverDemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/MapKit/Map/index.md
---

# Map

`Map` is a SwiftUI MapKit–backed view (iOS 17+). It renders a map with optional
camera binding, styling, annotations (`Marker`, `MapPolyline`, `MapPolygon`,
`MapCircle`), and built-in MapKit controls.

The shape of the API mirrors SwiftUI MapKit directly — no Web-style imperative
calls (`addMarker(...)`). You declare what should appear on the map; the bridge
turns the tree into `MapContent`.

***

## Basic usage

```tsx
import { Map, Marker, useObservable } from "scripting"

function Demo() {
  const position = useObservable<MapCameraPosition>(
    MapCameraPosition.region({
      center: { latitude: 31.23, longitude: 121.47 },
      span: { latitudeDelta: 0.05, longitudeDelta: 0.05 },
    })
  )

  return <Map cameraPosition={position}>
    <Marker
      title="Bund"
      coordinate={{ latitude: 31.24, longitude: 121.49 }}
      tint="systemRed"
    />
  </Map>
}
```

Use any standard view modifier (`frame`, `padding`, `aspectRatio`, ...) to size the
map. There are no `width` / `height` props.

***

## Camera position

Two mutually exclusive ways to set the camera:

| Prop                    | Type                            | Behavior                                                                                         |
| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `cameraPosition`        | `Observable<MapCameraPosition>` | Two-way binding. User gestures write the resulting `MapCameraPosition` back into the observable. |
| `initialCameraPosition` | `MapCameraPosition`             | One-time initial value, no write-back.                                                           |

> The props are named `cameraPosition` / `initialCameraPosition` rather than
> `position` / `initialPosition` to avoid clashing with the SwiftUI
> `.position(x:y:)` view modifier.

`MapCameraPosition` is an opaque value (`MapCameraPosition` class). Construct it
via factories on the `MapCameraPosition` namespace — never pass a plain dict:

```ts
MapCameraPosition.region({ center, span })
MapCameraPosition.rect({ center, size: { width, height } })   // size in meters
MapCameraPosition.camera({ centerCoordinate, distance, heading?, pitch? })
// or: MapCameraPosition.camera(MapCamera.make({...}))
MapCameraPosition.item({ coordinate, name? }, { allowsAutomaticPitch?: boolean })
MapCameraPosition.userLocation({ fallback?: MapCameraPosition })
MapCameraPosition.automatic()
```

Read what's currently framed via the readonly accessors:

```ts
const pos: MapCameraPosition = camera.value
pos.region              // MapRegion | null
pos.rect                // { center, size } | null
pos.camera              // MapCamera | null
pos.item                // { coordinate, name? } | null
pos.fallbackPosition    // MapCameraPosition | null
pos.allowsAutomaticPitch
pos.positionedByUser    // true if the most recent change came from a user gesture
```

User gestures write the new `MapCameraPosition` back directly — whatever form
the camera ends up in (typically a region after pan/zoom) is what the observable
will hold.

***

## Map style

```tsx
<Map mapStyle={{ style: "standard", showsTraffic: true }}>...</Map>

<Map mapStyle={{ style: "hybrid", elevation: "realistic" }}>...</Map>

<Map mapStyle={{
  style: "standard",
  pointsOfInterest: { includes: ["restaurant", "park"] },
}}>...</Map>
```

`pointsOfInterest` accepts `"all"`, `"excludingAll"`, or `{ includes: [...] }` /
`{ excludes: [...] }` with category strings like `"airport"`, `"cafe"`,
`"restaurant"`, etc.

***

## Map content

The following are valid children of `<Map>`:

### `Marker`

```tsx
<Marker
  title="Bund"
  coordinate={{ latitude: 31.24, longitude: 121.49 }}
  tint="systemRed"
/>

<Marker
  coordinate={{ latitude: 31.23, longitude: 121.47 }}
  systemImage="building.2"
  tint="systemBlue"
/>

<Marker
  title="A"
  coordinate={{ latitude: 31.23, longitude: 121.47 }}
  monogram="A"
/>
```

`systemImage` and `monogram` are mutually exclusive. `tint` accepts the same
color strings as the rest of the bridge (system colors, `"#RRGGBB"`,
`"rgba(...)"`, etc.).

### `MapPolyline`

```tsx
<MapPolyline
  coordinates={[
    { latitude: 31.23, longitude: 121.47 },
    { latitude: 31.24, longitude: 121.48 },
    { latitude: 31.245, longitude: 121.495 },
  ]}
  strokeColor="systemBlue"
  strokeStyle={{ lineWidth: 4 }}
/>
```

`contourStyle` is `"straight"` (default) or `"geodesic"`. The difference is
invisible at short distances and only meaningful for cross-continent routes.

### `MapPolygon`

```tsx
<MapPolygon
  coordinates={[ ... ]}
  fillColor="systemBlue"
  strokeColor="white"
  strokeStyle={{ lineWidth: 2 }}
/>
```

### `MapCircle`

```tsx
<MapCircle
  center={{ latitude: 31.23, longitude: 121.47 }}
  radius={500}
  fillColor="systemBlue"
  strokeColor="white"
/>
```

`radius` is in meters.

***

## Built-in controls

Use the `controls` prop and pass either a single control element or a Fragment
containing several:

```tsx
<Map
  controls={<>
    <MapUserLocationButton />
    <MapCompass />
    <MapScaleView />
  </>}
>
  ...
</Map>
```

Valid controls:

- `MapUserLocationButton` — recenter on user location (asks for permission)
- `MapCompass` — compass rose that resets rotation
- `MapPitchToggle` — toggle 2D / pitched view
- `MapScaleView` — adaptive scale bar

***

## `strokeStyle`

Used by `MapPolyline`, `MapPolygon`, and `MapCircle`:

```ts
type MapStrokeStyle = {
  lineWidth?: number                                // points
  lineCap?: "butt" | "round" | "square"
  lineJoin?: "miter" | "round" | "bevel"
  dash?: number[]                                   // dash/gap lengths in points
}
```

***

## `cameraBounds` — constrain pan / zoom

Pass a `MapCameraBounds` instance to clamp how far the user can pan and
zoom an interactive map. Two factories:

```ts
// Lock the center inside a region, and optionally cap zoom range
// (camera-to-center distance in meters).
const bounds = MapCameraBounds.centerCoordinateBounds(
  {
    center: { latitude: 31.2304, longitude: 121.4737 },
    span:   { latitudeDelta: 0.1, longitudeDelta: 0.1 },
  },
  { minimumDistance: 200, maximumDistance: 8000 }
)

// Restrict zoom only — the center is free to pan anywhere.
const zoomOnly = MapCameraBounds.distance({
  minimumDistance: 500,
  maximumDistance: 50_000,
})

return <Map cameraPosition={cam} cameraBounds={bounds}>...</Map>
```

`minimumDistance` / `maximumDistance` are measured in meters from the camera
to its `centerCoordinate`. Both fields are optional in either factory; pass
the ones you want. `MapCameraBounds.distance(...)` requires at least one of
them (passing an empty options dict returns `null` and the prop has no
effect).

The constraint applies to user gestures only — programmatic `cameraPosition`
writes from JS can still place the camera outside the bounds. MapKit will
typically animate back into bounds on the next user interaction.

***

## Performance tips

- Marker count: a few dozen markers is fine. For hundreds, prefer cluster-like
  preprocessing in your script and only emit markers visible in the current
  region.
- Update cadence: each render replays the full content tree. If your script
  derives many markers from large arrays on every state change, memoize them
  with `useMemo`.
- `cameraPosition` is two-way: a `setValue` from JS triggers a re-render; the gesture
  reconciler skips equivalent writes to avoid loops.



---
url: /guide/Device Capabilities/MapKit/Map/index_example.md
---

# Example

```tsx
import {
  Button, HStack, Map, MapCircle, MapCompass, MapPitchToggle, MapPolygon, MapPolyline,
  MapScaleView, MapUserLocationButton, Marker, Navigation, NavigationStack, Picker, Script,
  ScrollView, Text, useMemo, useObservable, useState, VStack,
} from "scripting"
import type { MapStyleSpec, MapPointsOfInterestSpec } from "scripting"

function Example() {
  // Camera bound to most of the demos below. Demo 4 swaps it through every
  // MapCameraPosition variant; the other demos read its current value.
  const position = useObservable<MapCameraPosition>(
    MapCameraPosition.region({
      center: { latitude: 31.2354, longitude: 121.4905 },
      span: { latitudeDelta: 0.04, longitudeDelta: 0.04 },
    })
  )

  // ───── Demo 2 state: mapStyle picker ─────
  const [styleKind, setStyleKind] = useState<"standard" | "imagery" | "hybrid">("standard")
  const [showsTraffic, setShowsTraffic] = useState(false)

  const mapStyle: MapStyleSpec = useMemo(() => {
    if (styleKind === "imagery") {
      return { style: "imagery", elevation: "realistic" }
    }
    if (styleKind === "hybrid") {
      return { style: "hybrid", elevation: "realistic", showsTraffic }
    }
    return { style: "standard", showsTraffic }
  }, [styleKind, showsTraffic])

  // ───── Demo 4 state: camera-spec variants ─────
  type CameraKind = "region" | "rect" | "camera" | "automatic" | "userLocation"
  const [cameraKind, setCameraKind] = useState<CameraKind>("region")

  const applyCamera = (kind: CameraKind) => {
    setCameraKind(kind)
    switch (kind) {
      case "region":
        position.setValue(MapCameraPosition.region({
          center: { latitude: 31.2354, longitude: 121.4905 },
          span: { latitudeDelta: 0.04, longitudeDelta: 0.04 },
        }))
        return
      case "rect":
        // 5 km × 5 km square around the Bund
        position.setValue(MapCameraPosition.rect({
          center: { latitude: 31.2407, longitude: 121.4905 },
          size: { width: 5000, height: 5000 },
        }))
        return
      case "camera":
        position.setValue(MapCameraPosition.camera({
          centerCoordinate: { latitude: 31.2397, longitude: 121.4994 },
          distance: 1500,
          heading: 30,
          pitch: 45,
        }))
        return
      case "automatic":
        position.setValue(MapCameraPosition.automatic())
        return
      case "userLocation":
        // Requires user location permission; falls back to .automatic without it.
        position.setValue(MapCameraPosition.userLocation())
        return
    }
  }

  // ───── Demo 5 state: POI filter ─────
  type POIMode = "all" | "excludingAll" | "includes" | "excludes"
  const [poiMode, setPoiMode] = useState<POIMode>("all")

  const poiSpec: MapPointsOfInterestSpec = useMemo(() => {
    if (poiMode === "all") return "all"
    if (poiMode === "excludingAll") return "excludingAll"
    if (poiMode === "includes") return { includes: ["restaurant", "cafe", "park"] }
    return { excludes: ["gasStation", "atm", "parking"] }
  }, [poiMode])

  // ───── Demo 6: geodesic polyline state ─────
  // Toggle between straight and geodesic to visualise the curvature on long routes.
  const [geodesic, setGeodesic] = useState(true)

  // ───── Demo 8: pitch toggle ─────
  const pitchedPosition = useObservable<MapCameraPosition>(
    MapCameraPosition.camera({
      centerCoordinate: { latitude: 31.2397, longitude: 121.4994 },
      distance: 1200,
      heading: 30,
      pitch: 60,
    })
  )

  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map View"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"Map"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={20}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`\`Map\` is a SwiftUI MapKit view. Pass an \`Observable<MapCameraPosition>\` to
          \`cameraPosition\` for two-way binding — gestures write the new camera back on
          gesture end. Use the children for \`Marker\`, \`MapPolyline\`, \`MapPolygon\`,
          \`MapCircle\`; use \`controls={...}\` to mount built-in MapKit controls.`}
        </Text>

        {/* 1. Basic map with Marker + Polyline + Circle */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. Basic map</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Three markers (plain label, SF Symbol, monogram), a polyline tracing a path
            between them, and a circle showing a 300m radius. Drag/zoom — the region writes
            back to `cameraPosition`.
          </Text>
          <Map
            cameraPosition={position}
            mapStyle={mapStyle}
            controls={<>
              <MapUserLocationButton />
              <MapCompass />
              <MapScaleView />
            </>}
            frame={{ height: 320 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <Marker
              title="Bund"
              coordinate={{ latitude: 31.2407, longitude: 121.4905 }}
              tint="systemRed"
            />
            <Marker
              title="People's Square"
              coordinate={{ latitude: 31.2304, longitude: 121.4737 }}
              systemImage="building.2"
              tint="systemBlue"
            />
            <Marker
              title="Lujiazui"
              coordinate={{ latitude: 31.2397, longitude: 121.4994 }}
              monogram="L"
              tint="systemPurple"
            />
            <MapPolyline
              coordinates={[
                { latitude: 31.2304, longitude: 121.4737 },
                { latitude: 31.2407, longitude: 121.4905 },
                { latitude: 31.2397, longitude: 121.4994 },
              ]}
              strokeColor="systemOrange"
              strokeStyle={{ lineWidth: 4, lineCap: "round", lineJoin: "round" }}
            />
            <MapCircle
              center={{ latitude: 31.2354, longitude: 121.4905 }}
              radius={300}
              fillColor="rgba(0, 122, 255, 0.15)"
              strokeColor="systemBlue"
              strokeStyle={{ lineWidth: 2 }}
            />
          </Map>
        </VStack>

        {/* 2. mapStyle + showsTraffic + elevation */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Map style</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Switch the map above between Standard / Imagery / Hybrid. Imagery and Hybrid
            request realistic elevation; only Standard and Hybrid honor `showsTraffic`.
          </Text>
          <HStack spacing={8}>
            <Button title="Standard" action={() => setStyleKind("standard")} />
            <Button title="Imagery" action={() => setStyleKind("imagery")} />
            <Button title="Hybrid" action={() => setStyleKind("hybrid")} />
          </HStack>
          <HStack spacing={8}>
            <Button
              title={showsTraffic ? "Traffic: ON" : "Traffic: OFF"}
              action={() => setShowsTraffic(v => !v)}
            />
          </HStack>
        </VStack>

        {/* 3. Polygon demo */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. Polygon</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            A filled polygon outlining a rough quad around People's Square. Uses
            `initialCameraPosition` (one-way init, no write-back).
          </Text>
          <Map
            initialCameraPosition={MapCameraPosition.region({
              center: { latitude: 31.2304, longitude: 121.4737 },
              span: { latitudeDelta: 0.02, longitudeDelta: 0.02 },
            })}
            frame={{ height: 240 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <MapPolygon
              coordinates={[
                { latitude: 31.234, longitude: 121.470 },
                { latitude: 31.234, longitude: 121.478 },
                { latitude: 31.227, longitude: 121.478 },
                { latitude: 31.227, longitude: 121.470 },
              ]}
              fillColor="rgba(52, 199, 89, 0.25)"
              strokeColor="systemGreen"
              strokeStyle={{ lineWidth: 2 }}
            />
          </Map>
        </VStack>

        {/* 4. All 5 MapCameraPosition variants */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>4. Camera spec variants</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Cycle a dedicated `cameraPosition` observable through every
            `MapCameraPosition` form. The map directly below responds.
            `userLocation` needs location permission; without it MapKit falls
            back to `automatic`.
          </Text>
          <Picker
            title="Camera"
            value={cameraKind}
            onChanged={(v: any) => applyCamera(v as CameraKind)}
            pickerStyle={"segmented"}
          >
            <Text tag={"region"}>region</Text>
            <Text tag={"rect"}>rect</Text>
            <Text tag={"camera"}>camera</Text>
            <Text tag={"automatic"}>auto</Text>
            <Text tag={"userLocation"}>user</Text>
          </Picker>
          <Map
            cameraPosition={position}
            frame={{ height: 260 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <Marker
              title="People's Square"
              coordinate={{ latitude: 31.2304, longitude: 121.4737 }}
              tint="systemRed"
            />
            <Marker
              title="Lujiazui"
              coordinate={{ latitude: 31.2397, longitude: 121.4994 }}
              tint="systemBlue"
            />
          </Map>
          <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
            Note: dragging the map afterwards writes a `{"{ region }"}` form
            back, regardless of which variant you started with. The map in
            Demo 1 shares the same observable, so it will respond too.
          </Text>
        </VStack>

        {/* 5. POI filter */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>5. Points of interest filter</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Filter which POIs MapKit renders. `includes` shows only the listed categories;
            `excludes` shows everything except them; `excludingAll` hides all POIs.
          </Text>
          <Picker
            title="POI"
            value={poiMode}
            onChanged={(v: any) => setPoiMode(v as POIMode)}
            pickerStyle={"segmented"}
          >
            <Text tag={"all"}>all</Text>
            <Text tag={"excludingAll"}>none</Text>
            <Text tag={"includes"}>food + park</Text>
            <Text tag={"excludes"}>no gas/atm</Text>
          </Picker>
          <Map
            initialCameraPosition={MapCameraPosition.region({
              center: { latitude: 31.2304, longitude: 121.4737 },
              span: { latitudeDelta: 0.015, longitudeDelta: 0.015 },
            })}
            mapStyle={{ style: "standard", pointsOfInterest: poiSpec }}
            frame={{ height: 260 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          />
        </VStack>

        {/* 6. Geodesic polyline (long-haul route) */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>6. Geodesic polyline</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Beijing ⇄ San Francisco great-circle vs straight line. Geodesic follows the
            shortest path on a sphere — visibly curved on long routes; the straight form
            cuts diagonally across the projection.
          </Text>
          <HStack spacing={8}>
            <Button
              title={geodesic ? "Mode: geodesic" : "Mode: straight"}
              action={() => setGeodesic(v => !v)}
            />
          </HStack>
          <Map
            initialCameraPosition={MapCameraPosition.region({
              center: { latitude: 50, longitude: -160 },
              span: { latitudeDelta: 90, longitudeDelta: 200 },
            })}
            mapStyle={{ style: "standard" }}
            frame={{ height: 260 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <Marker title="Beijing"
              coordinate={{ latitude: 39.9042, longitude: 116.4074 }}
              tint="systemRed"
            />
            <Marker title="San Francisco"
              coordinate={{ latitude: 37.7749, longitude: -122.4194 }}
              tint="systemBlue"
            />
            <MapPolyline
              coordinates={[
                { latitude: 39.9042, longitude: 116.4074 },
                { latitude: 37.7749, longitude: -122.4194 },
              ]}
              strokeColor="systemOrange"
              strokeStyle={{ lineWidth: 3, lineCap: "round" }}
              contourStyle={geodesic ? "geodesic" : "straight"}
            />
          </Map>
        </VStack>

        {/* 7. Dashed strokes + lineCap / lineJoin */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>7. Stroke styles</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Three polylines side-by-side showing `dash` + `lineCap` + `lineJoin` combinations,
            plus a dashed `MapCircle` outline. Dash lengths and gaps are in points.
          </Text>
          <Map
            initialCameraPosition={MapCameraPosition.region({
              center: { latitude: 31.2354, longitude: 121.4905 },
              span: { latitudeDelta: 0.012, longitudeDelta: 0.018 },
            })}
            frame={{ height: 280 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <MapPolyline
              coordinates={[
                { latitude: 31.238, longitude: 121.484 },
                { latitude: 31.238, longitude: 121.497 },
              ]}
              strokeColor="systemRed"
              strokeStyle={{ lineWidth: 5, lineCap: "butt" }}
            />
            <MapPolyline
              coordinates={[
                { latitude: 31.235, longitude: 121.484 },
                { latitude: 31.235, longitude: 121.497 },
              ]}
              strokeColor="systemBlue"
              strokeStyle={{ lineWidth: 5, lineCap: "round", dash: [12, 6] }}
            />
            <MapPolyline
              coordinates={[
                { latitude: 31.232, longitude: 121.484 },
                { latitude: 31.232, longitude: 121.490 },
                { latitude: 31.234, longitude: 121.497 },
              ]}
              strokeColor="systemGreen"
              strokeStyle={{ lineWidth: 5, lineJoin: "round", dash: [4, 4] }}
            />
            <MapCircle
              center={{ latitude: 31.2354, longitude: 121.4905 }}
              radius={250}
              fillColor="rgba(175, 82, 222, 0.10)"
              strokeColor="systemPurple"
              strokeStyle={{ lineWidth: 2, dash: [8, 4] }}
            />
          </Map>
        </VStack>

        {/* 8. MapPitchToggle + pitched 3D camera */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>8. Pitched camera + MapPitchToggle</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Hybrid + realistic elevation + a `camera`-form initial position with pitch=60°.
            The pitch-toggle control in the corner flips between flat and pitched view.
          </Text>
          <Map
            cameraPosition={pitchedPosition}
            mapStyle={{ style: "hybrid", elevation: "realistic" }}
            controls={<>
              <MapPitchToggle />
              <MapCompass />
            </>}
            frame={{ height: 320 }}
            clipShape={{
              type: 'rect',
              cornerRadius: 12
            }}
          >
            <Marker title="Lujiazui"
              coordinate={{ latitude: 31.2397, longitude: 121.4994 }}
              systemImage="building.2.crop.circle"
              tint="systemTeal"
            />
          </Map>
        </VStack>

        <CameraBoundsDemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

function CameraBoundsDemo() {
  // 中心约束:相机中心被锁在外滩 ~5km 矩形内,推不出去。
  const center = { latitude: 31.2397, longitude: 121.4906 }
  const region = { center, span: { latitudeDelta: 0.05, longitudeDelta: 0.05 } }
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(region))

  const [mode, setMode] = useState<"region" | "distance" | "off">("region")

  // 用 useMemo 避免每次 render 重建 bounds(SwiftUI 端按对象身份判等)。
  const bounds = useMemo(() => {
    if (mode === "off") return undefined
    if (mode === "region") {
      return MapCameraBounds.centerCoordinateBounds(region, {
        minimumDistance: 500,
        maximumDistance: 8000,
      })
    }
    // distance-only:中心可以拖到任意地方,只限 zoom 范围
    return MapCameraBounds.distance({ minimumDistance: 1000, maximumDistance: 20000 })
  }, [mode])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>9. `cameraBounds` — clamp pan / zoom</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`\`MapCameraBounds.centerCoordinateBounds\` 把中心锁在 region 内 + 限 zoom。
      \`MapCameraBounds.distance\` 只限 zoom,中心可以自由拖。
      off 时取消约束,作为对照。试着拖远 / 拖近 / 拖到很远的地方看效果。`}
    </Text>
    <Picker title="bounds" value={mode} onChanged={(v: any) => setMode(v as typeof mode)} pickerStyle="segmented">
      <Text tag="region">region + zoom</Text>
      <Text tag="distance">zoom only</Text>
      <Text tag="off">off</Text>
    </Picker>
    <Map
      cameraPosition={position}
      cameraBounds={bounds}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      <Marker title="Bund" coordinate={center} tint="systemRed" />
    </Map>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      Bounds 只影响用户手势 — JS 端 `cameraPosition.setValue(...)` 仍可把相机程序化
      移到约束外。MapKit 通常在下一次手势时把相机动画拉回合法范围。
    </Text>
  </VStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/MapKit/MapDirections/index.md
---

# 

***

title: MapDirections
description: MapKit route planning: `calculate(...)` for full routes and `calculateETA(...)` for travel time only.
tag: PRO
--------

`MapDirections` plans routes between two endpoints using MapKit. Two entry points:

- `MapDirections.calculate(options)` — full route(s) with turn-by-turn steps and
  a ready-to-render polyline.
- `MapDirections.calculateETA(options)` — travel time / distance / arrival
  window only. Cheaper and faster than `calculate` when you don't need the
  geometry.

Both APIs are network-backed by Apple's directions servers and require **no
iOS system permissions**. The result is plain data — no opaque handles to
dispose.

Pair with the views layer: `route.coordinates` is shaped exactly for
`<MapPolyline coordinates={route.coordinates}>` from the `<Map>` view.

***

## `calculate` — plan a route

```ts
const resp = await MapDirections.calculate({
  source: { latitude: 31.2304, longitude: 121.4737 },        // People's Square
  destination: { latitude: 31.2397, longitude: 121.4994 },   // Lujiazui
  transportType: "walking",
})

const route = resp.routes[0]
console.log(route.distance, "m")             // total distance in meters
console.log(route.expectedTravelTime, "s")   // ETA in seconds
console.log(route.steps.length, "steps")     // turn-by-turn count
```

### Options

| Option                    | Type                                              | Description                                                                   |
| ------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- |
| `source`                  | `DirectionsEndpoint`                              | Required. Bare `MapCoordinate` or `{ coordinate, name? }`.                    |
| `destination`             | `DirectionsEndpoint`                              | Required. Same shape as `source`.                                             |
| `transportType`           | `"automobile" \| "walking" \| "transit" \| "any"` | Default `"automobile"`.                                                       |
| `requestsAlternateRoutes` | `boolean`                                         | Default `false`. Up to 3 routes when supported (driving / highway only).      |
| `departureDate`           | `Date`                                            | Plan a route departing at this time. Wins over `arrivalDate` if both are set. |
| `arrivalDate`             | `Date`                                            | Plan a route arriving by this time.                                           |
| `tollPreference`          | `"any" \| "avoid"`                                | Default `"any"`.                                                              |
| `highwayPreference`       | `"any" \| "avoid"`                                | Default `"any"`.                                                              |

### `DirectionsResponse`

| Field         | Type                | Description                                                                                             |
| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------- |
| `source`      | `MapItem`           | Same shape as `MapSearch.locate` results — includes `coordinate`, `placemark`, `formattedAddress`, etc. |
| `destination` | `MapItem`           | Same shape.                                                                                             |
| `routes`      | `DirectionsRoute[]` | At least 1 entry.                                                                                       |

### `DirectionsRoute`

| Field                | Type                    | Description                                                                   |
| -------------------- | ----------------------- | ----------------------------------------------------------------------------- |
| `name`               | `string`                | Route label (e.g. road name).                                                 |
| `distance`           | `number`                | Total distance in meters.                                                     |
| `expectedTravelTime` | `number`                | ETA in seconds.                                                               |
| `transportType`      | `TransportType`         | Mode used for this route.                                                     |
| `coordinates`        | `MapCoordinate[]`       | Ready-to-render polyline. Pass straight to `<MapPolyline coordinates={...}>`. |
| `steps`              | `DirectionsRouteStep[]` | Turn-by-turn instructions.                                                    |
| `hasTolls`           | `boolean`               | Any tolled segments.                                                          |
| `hasHighways`        | `boolean`               | Any highway segments.                                                         |
| `advisoryNotices`    | `string[]`              | Optional advisory text from Apple.                                            |

### Rendering with `<MapPolyline>`

```tsx
<Map cameraPosition={position}>
  <Marker title="Start" coordinate={route.coordinates[0]} tint="systemGreen" />
  <Marker title="End"   coordinate={route.coordinates.at(-1)!} tint="systemRed" />
  <MapPolyline
    coordinates={route.coordinates}
    strokeColor="systemBlue"
    strokeStyle={{ lineWidth: 4, lineCap: "round" }}
  />
</Map>
```

***

## `calculateETA` — time / distance only

```ts
const eta = await MapDirections.calculateETA({
  source: { latitude: 31.2304, longitude: 121.4737 },
  destination: { latitude: 31.2397, longitude: 121.4994 },
  transportType: "automobile",
})

console.log(eta.expectedTravelTime, "s")
console.log(eta.distance, "m")
console.log(eta.expectedArrivalDate.toLocaleString())
```

Use this when you only need the headline numbers — it skips downloading the
full route geometry, so it's noticeably faster than `calculate`.

***

## Notes & limitations

- **Transit** (`transportType: "transit"`) is supported in a limited set of
  regions. Outside those, the request rejects with `directionsNotFound`. For
  broad coverage prefer `"automobile"` or `"walking"`.
- **Alternates** typically only return multiple routes for driving on roads
  with realistic alternatives — walking usually returns a single route.
- **No cancel handle**: a new `calculate` call doesn't cancel an in-flight one.
  Responses arrive in whatever order Apple's servers return them, so if you
  fire requests rapidly (e.g. while the user is moving sliders) implement your
  own "latest-wins" guard.
- **`departureDate` and `arrivalDate` are mutually exclusive**: if both are
  provided, `departureDate` wins; `arrivalDate` is ignored.



---
url: /guide/Device Capabilities/MapKit/MapDirections/index_example.md
---

# 

***

title: Example
description: MapKit route planning: `calculate(...)` for full routes and `calculateETA(...)` for travel time only.
tag: PRO
--------

```tsx
import {
  Button, HStack, Map, MapPolyline, Marker, Navigation, NavigationStack, Picker,
  Script, ScrollView, Text, useEffect, useObservable, useState, VStack,
} from "scripting"

// Shanghai landmarks used across the demos.
const PEOPLES_SQUARE = { latitude: 31.2304, longitude: 121.4737 }
const BUND = { latitude: 31.2407, longitude: 121.4905 }
const LUJIAZUI = { latitude: 31.2397, longitude: 121.4994 }

const initialRegion = {
  center: { latitude: 31.2354, longitude: 121.4905 },
  span: { latitudeDelta: 0.04, longitudeDelta: 0.04 },
}

// Phase 3e: distance / duration formatting delegates to MapUtils, which wraps
// MKDistanceFormatter / DateComponentsFormatter so the output respects the
// device locale.
const fmtDistance = (meters: number) => MapUtils.formatDistance(meters)
const fmtDuration = (seconds: number) => MapUtils.formatDuration(seconds)

// ───────────────────────────────────────────────────────────────────────
// Demo 1: calculate a single route and render the polyline
// ───────────────────────────────────────────────────────────────────────
function SingleRouteDemo() {
  // Phase 3g: 拿到完整 response 而不是单挑 route — 这样 source / destination 的
  // MapItem 可以直接喂给 <Marker item={...}>,触发 Apple 的 auto POI glyph。
  const [resp, setResp] = useState<MapDirections.DirectionsResponse | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  const route = resp?.routes[0] ?? null

  const calc = async () => {
    setLoading(true); setErr(null)
    try {
      const r = await MapDirections.calculate({
        source: { coordinate: PEOPLES_SQUARE, name: "People's Square" },
        destination: { coordinate: LUJIAZUI, name: "Lujiazui" },
        transportType: "automobile",
      })
      setResp(r)
      const fit = MapUtils.regionFromCoordinates(r.routes[0].coordinates, 0.2)
      if (fit) position.setValue(MapCameraPosition.region(fit))
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>1. Calculate + render</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`Drive from People's Square to Lujiazui. The returned \`route.coordinates\` polyline
      feeds straight into \`<MapPolyline coordinates={...}>\`; the response's
      \`source\` / \`destination\` MapItems are dropped into \`<Marker item={...}>\`
      so MapKit picks the POI glyph automatically.`}
    </Text>
    <HStack spacing={8}>
      <Button title={loading ? "Calculating..." : "Calculate"} action={calc} />
      {route != null
        ? <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {fmtDistance(route.distance)} · {fmtDuration(route.expectedTravelTime)} · {route.steps.length} steps
        </Text>
        : null}
    </HStack>
    {err != null
      ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text>
      : null}
    <Map
      cameraPosition={position}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {resp != null
        ? <>
          {/* MapItem 形态:title / coordinate / glyph 都由 MapKit 自己挑。 */}
          <Marker item={resp.source} tint="systemGreen" />
          <Marker item={resp.destination} tint="systemRed" />
        </>
        : <>
          {/* 路线还没算出来时回落到坐标形态。 */}
          <Marker title="Start" coordinate={PEOPLES_SQUARE} tint="systemGreen" />
          <Marker title="End" coordinate={LUJIAZUI} tint="systemRed" />
        </>}
      {route != null
        ? <MapPolyline
          coordinates={route.coordinates}
          strokeColor="systemBlue"
          strokeStyle={{ lineWidth: 4, lineCap: "round", lineJoin: "round" }}
        />
        : null}
    </Map>
  </VStack>
}

// ───────────────────────────────────────────────────────────────────────
// Demo 2: switch transportType and watch the route change shape / length
// ───────────────────────────────────────────────────────────────────────
function TransportTypeDemo() {
  type Mode = "automobile" | "walking"
  const [mode, setMode] = useState<Mode>("walking")
  const [resp, setResp] = useState<MapDirections.DirectionsResponse | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  const route = resp?.routes[0] ?? null

  useEffect(() => {
    let cancelled = false
    setLoading(true); setErr(null)
    MapDirections.calculate({
      source: { coordinate: BUND, name: "Bund" },
      destination: { coordinate: LUJIAZUI, name: "Lujiazui" },
      transportType: mode,
    }).then(r => {
      if (cancelled) return
      setResp(r)
      const fit = MapUtils.regionFromCoordinates(r.routes[0].coordinates, 0.2)
      if (fit) position.setValue(MapCameraPosition.region(fit))
    }).catch(e => {
      if (cancelled) return
      setErr(String(e))
    }).finally(() => {
      if (!cancelled) setLoading(false)
    })
    return () => { cancelled = true }
  }, [mode])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>2. transportType switch</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Same start/end (Bund → Lujiazui) but different transport mode. Driving prefers
      bridges + roads; walking takes a much more direct path.
    </Text>
    <Picker
      title="Mode"
      value={mode}
      onChanged={(v: any) => setMode(v as Mode)}
      pickerStyle={"segmented"}
    >
      <Text tag={"automobile"}>automobile</Text>
      <Text tag={"walking"}>walking</Text>
    </Picker>
    {loading ? <Text font={"caption2"}>Calculating...</Text> : null}
    {err != null ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text> : null}
    {route != null
      ? <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
        {route.transportType} · {fmtDistance(route.distance)} · {fmtDuration(route.expectedTravelTime)}
      </Text>
      : null}
    <Map
      cameraPosition={position}
      frame={{ height: 260 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {resp != null
        ? <>
          <Marker item={resp.source} tint="systemRed" />
          <Marker item={resp.destination} tint="systemPurple" />
        </>
        : <>
          <Marker title="Bund" coordinate={BUND} tint="systemRed" />
          <Marker title="Lujiazui" coordinate={LUJIAZUI} tint="systemPurple" />
        </>}
      {route != null
        ? <MapPolyline
          coordinates={route.coordinates}
          strokeColor={mode === "walking" ? "systemTeal" : "systemBlue"}
          strokeStyle={{ lineWidth: 4, lineCap: "round" }}
        />
        : null}
    </Map>
  </VStack>
}

// ───────────────────────────────────────────────────────────────────────
// Demo 3: alternates — render multiple routes side by side
// ───────────────────────────────────────────────────────────────────────
const ALTERNATE_COLORS = ["systemBlue", "systemOrange", "systemPurple"] as const

function AlternatesDemo() {
  const [resp, setResp] = useState<MapDirections.DirectionsResponse | null>(null)
  // 选中的 route 在地图上 stroke 加粗 + 不透明,未选中的回落到细 + 半透明,
  // 视觉上把"导航选了哪条"立刻表达清楚。
  const [selectedIdx, setSelectedIdx] = useState(0)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  const routes = resp?.routes ?? []

  const calc = async () => {
    setLoading(true); setErr(null)
    try {
      const r = await MapDirections.calculate({
        source: { coordinate: PEOPLES_SQUARE, name: "People's Square" },
        destination: { coordinate: LUJIAZUI, name: "Lujiazui" },
        transportType: "automobile",
        requestsAlternateRoutes: true,
      })
      setResp(r)
      setSelectedIdx(0)
      const allCoords = r.routes.flatMap(rt => rt.coordinates)
      const fit = MapUtils.regionFromCoordinates(allCoords, 0.2)
      if (fit) position.setValue(MapCameraPosition.region(fit))
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>3. Alternates + selection</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`\`requestsAlternateRoutes: true\` may return up to 3 driving routes. Tap a row
      below to highlight that route — the selected polyline renders thicker and
      fully opaque, others fade to make the choice obvious.`}
    </Text>
    <HStack spacing={8}>
      <Button title={loading ? "Calculating..." : "Calculate (with alternates)"} action={calc} />
    </HStack>
    {err != null ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text> : null}
    <VStack alignment={"leading"} spacing={4}>
      {routes.map((r, i) => {
        const isSelected = i === selectedIdx
        const color = ALTERNATE_COLORS[i % ALTERNATE_COLORS.length]
        return <Button
          key={i}
          action={() => setSelectedIdx(i)}
          buttonStyle={isSelected ? "borderedProminent" : "bordered"}
          tint={color}
        >
          <HStack spacing={8}>
            <Text font={"caption"} foregroundStyle={isSelected ? "white" : color}>
              {`${i + 1}. ${r.name || "(unnamed)"}`}
            </Text>
            <Text font={"caption2"} foregroundStyle={isSelected ? "white" : "secondaryLabel"}>
              {`${fmtDistance(r.distance)} · ${fmtDuration(r.expectedTravelTime)}`}
            </Text>
          </HStack>
        </Button>
      })}
    </VStack>
    <Map
      cameraPosition={position}
      frame={{ height: 280 }}
      clipShape={{ type: "rect", cornerRadius: 12 }}
    >
      {resp != null
        ? <>
          <Marker item={resp.source} tint="systemGreen" />
          <Marker item={resp.destination} tint="systemRed" />
        </>
        : <>
          <Marker title="Start" coordinate={PEOPLES_SQUARE} tint="systemGreen" />
          <Marker title="End" coordinate={LUJIAZUI} tint="systemRed" />
        </>}
      {/* 未选中的先画(细),选中的最后画压在上面(粗)。MapPolyline 目前不接收
          opacity / 视图层 modifier,这里用 stroke width(3 vs 6)制造主次对比。 */}
      {routes.map((r, i) => {
        if (i === selectedIdx) return null
        return <MapPolyline
          key={`alt-${i}`}
          coordinates={r.coordinates}
          strokeColor={ALTERNATE_COLORS[i % ALTERNATE_COLORS.length]}
          strokeStyle={{ lineWidth: 3, lineCap: "round" }}
        />
      })}
      {routes[selectedIdx] != null
        ? <MapPolyline
          key={`sel-${selectedIdx}`}
          coordinates={routes[selectedIdx].coordinates}
          strokeColor={ALTERNATE_COLORS[selectedIdx % ALTERNATE_COLORS.length]}
          strokeStyle={{ lineWidth: 6, lineCap: "round", lineJoin: "round" }}
        />
        : null}
    </Map>
  </VStack>
}

// ───────────────────────────────────────────────────────────────────────
// Demo 4: calculateETA — time / distance only, no geometry download
// ───────────────────────────────────────────────────────────────────────
function ETADemo() {
  type Mode = "automobile" | "walking"
  const [mode, setMode] = useState<Mode>("automobile")
  const [eta, setEta] = useState<MapDirections.ETAResponse | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)

  const calc = async () => {
    setLoading(true); setErr(null)
    try {
      const result = await MapDirections.calculateETA({
        source: { coordinate: PEOPLES_SQUARE, name: "People's Square" },
        destination: { coordinate: LUJIAZUI, name: "Lujiazui" },
        transportType: mode,
        departureDate: new Date(),
      })
      setEta(result)
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>4. `calculateETA`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Skip the polyline download; get back travel time / distance / arrival window only.
      Cheaper than `calculate` when the UI just needs a headline number.
    </Text>
    <Picker
      title="Mode"
      value={mode}
      onChanged={(v: any) => setMode(v as Mode)}
      pickerStyle={"segmented"}
    >
      <Text tag={"automobile"}>automobile</Text>
      <Text tag={"walking"}>walking</Text>
    </Picker>
    <HStack spacing={8}>
      <Button title={loading ? "Calculating..." : "Calculate ETA"} action={calc} />
    </HStack>
    {err != null ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text> : null}
    {eta != null
      ? <VStack alignment={"leading"} spacing={2}>
        <Text font={"caption"}>{`Travel: ${fmtDuration(eta.expectedTravelTime)}`}</Text>
        <Text font={"caption"}>{`Distance: ${fmtDistance(eta.distance)}`}</Text>
        <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>
          {`Depart: ${eta.expectedDepartureDate.toLocaleTimeString()}`}
        </Text>
        <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>
          {`Arrive: ${eta.expectedArrivalDate.toLocaleTimeString()}`}
        </Text>
      </VStack>
      : null}
  </VStack>
}

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Directions"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"MapDirections"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={20}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`\`MapDirections.calculate(...)\` returns route polylines that plug straight into
          \`<MapPolyline coordinates={...}>\`. \`MapDirections.calculateETA(...)\` returns
          time / distance only — handy when you don't need the geometry. No system
          permissions required.`}
        </Text>
        <SingleRouteDemo />
        <TransportTypeDemo />
        <AlternatesDemo />
        <ETADemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/MapKit/MapLookAround/index.md
---

# MapLookAround

`MapLookAround` resolves a LookAround (street-level) scene reference for a
coordinate. Pair with the `<LookAroundPreview>` view to render the scene
interactively.

```tsx
import { LookAroundPreview, useEffect, useState } from "scripting"

function Example() {
  const [scene, setScene] = useState<MapLookAroundScene | null>(null)
  useEffect(() => {
    MapLookAround.request({ latitude: 37.3349, longitude: -122.0090 })
      .then(setScene)
  }, [])
  return <LookAroundPreview scene={scene} frame={{ height: 240 }} />
}
```

***

## `request` — fetch a scene

```ts
const scene = await MapLookAround.request({
  latitude: 31.2397,
  longitude: 121.4994,
})
if (scene == null) {
  // No street view available at this location.
}
```

`scene` is an opaque handle backed by `MKLookAroundScene`. Two readable fields
in JS:

| Member       | Type            | Description                                   |
| ------------ | --------------- | --------------------------------------------- |
| `coordinate` | `MapCoordinate` | Anchor coordinate the scene was requested at. |

## `<LookAroundPreview scene>` — render the scene

| Prop               | Type                                                 | Default        | Description                                                 |
| ------------------ | ---------------------------------------------------- | -------------- | ----------------------------------------------------------- |
| `scene`            | `MapLookAroundScene \| null`                         | —              | Scene to render. `null` shows a placeholder.                |
| `showsRoadLabels`  | `boolean?`                                           | `true`         | Overlay street / road names.                                |
| `allowsNavigation` | `boolean?`                                           | `true`         | Allow tapping to expand into the full-screen viewer.        |
| `badgePosition`    | `"topLeading" \| "topTrailing" \| "bottomTrailing"?` | `"topLeading"` | Position of Apple's "Look Around" badge inside the preview. |

The component also accepts all standard layout / framing modifiers
(`frame={...}`, `padding`, `clipShape`, etc.).

## Notes

- LookAround coverage skews to major US / EU / JP / KR cities; many locations
  resolve to `null`. Always handle the null branch in your UI.
- The view uses Apple's interactive preview internally — you can't add custom
  overlays or annotations on top.
- A scene reference stays valid while the JS context lives; you don't need to
  dispose it.



---
url: /guide/Device Capabilities/MapKit/MapLookAround/index_example.md
---

# Example

```tsx
import {
  Button, HStack, LookAroundPreview, MapCoordinate, Navigation, NavigationStack, Picker,
  Script, ScrollView, Text, useEffect, useState, VStack,
} from "scripting"

const SPOTS: Record<string, { name: string; coordinate: MapCoordinate }> = {
  apple_park: { name: "Apple Park", coordinate: { latitude: 37.3349, longitude: -122.0090 } },
  bund: { name: "Bund, Shanghai", coordinate: { latitude: 31.2407, longitude: 121.4905 } },
  shibuya: { name: "Shibuya Crossing", coordinate: { latitude: 35.6595, longitude: 139.7005 } },
  sahara: { name: "Sahara (no coverage)", coordinate: { latitude: 23.0, longitude: 12.0 } },
}

type Spot = keyof typeof SPOTS

function Example() {
  const [spot, setSpot] = useState<Spot>("apple_park")
  const [scene, setScene] = useState<MapLookAroundScene | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)

  // Re-request whenever the picker selection changes.
  useEffect(() => {
    let cancelled = false
    setLoading(true); setErr(null); setScene(null)
    MapLookAround.request(SPOTS[spot].coordinate)
      .then(s => { if (!cancelled) setScene(s) })
      .catch(e => { if (!cancelled) setErr(String(e)) })
      .finally(() => { if (!cancelled) setLoading(false) })
    return () => { cancelled = true }
  }, [spot])

  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map LookAround"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"LookAround"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={16}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`MapLookAround.request({ latitude, longitude }) resolves a
          MapLookAroundScene reference (or null when there's no street-level
          coverage). Feed the result into <LookAroundPreview scene> to render.`}
        </Text>

        <Picker
          title="Spot"
          value={spot}
          onChanged={(v: any) => setSpot(v as Spot)}
          pickerStyle={"segmented"}
        >
          {(Object.keys(SPOTS) as Spot[]).map(key =>
            <Text key={key} tag={key}>{SPOTS[key].name}</Text>
          )}
        </Picker>

        <HStack spacing={8}>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            {SPOTS[spot].name}
          </Text>
          {loading ? <Text font={"caption2"}>Loading...</Text> : null}
          {scene == null && !loading && err == null
            ? <Text font={"caption2"} foregroundStyle={"systemOrange"}>
              No street view at this location.
            </Text>
            : null}
        </HStack>
        {err != null
          ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text>
          : null}

        <LookAroundPreview
          scene={scene}
          showsRoadLabels
          frame={{ height: 240 }}
          clipShape={{ type: "rect", cornerRadius: 12 }}
        />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/MapKit/MapSearch/index.md
---

# 

***

title: MapSearch
description: MapKit keyword search: one-shot `locate(...)` and stateful autocomplete via `createCompleter(...)`.

***

`MapSearch` runs MapKit's on-device keyword search. Two entry points:

- `MapSearch.locate(options)` — one-shot search, returns `MapItem[]`.
- `MapSearch.createCompleter(options?)` — stateful autocomplete, designed for
  text-input fields. Delivers suggestions via listener callbacks.

Both are pure query APIs and require **no system permissions**. Coordinates are
returned as `MapCoordinate`, so results plug straight into `<Marker>` /
`<Map>` from the views layer.

Forward / reverse geocoding (address ↔ coordinates) lives on the existing
`Location` namespace (`Location.geocodeAddress`, `Location.reverseGeocode`).

***

## `locate` — one-shot search

```ts
const items = await MapSearch.locate({
  query: "coffee",
  region: {
    center: { latitude: 31.2304, longitude: 121.4737 },
    span: { latitudeDelta: 0.02, longitudeDelta: 0.02 },
  },
})

for (const item of items) {
  console.log(item.name, item.coordinate, item.formattedAddress)
}
```

### Options

| Option                  | Type                                                       | Description                                                                                                                   |
| ----------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`                                                   | Required. Non-empty search term.                                                                                              |
| `region`                | `MapRegion?`                                               | Restrict the search to a region. Omit to use a wide area around the device's last known coarse location.                      |
| `resultTypes`           | `("pointOfInterest" \| "address" \| "physicalFeature")[]?` | Default: `["pointOfInterest", "address"]`. `physicalFeature` is iOS 18+ — silently ignored on older systems.                  |
| `pointOfInterestFilter` | `MapPointsOfInterestSpec?`                                 | Same shape as `<Map mapStyle={{ pointsOfInterest }}>`. Use `"excludingAll"`, `{ includes: [...] }`, or `{ excludes: [...] }`. |

### Result — `MapItem`

`MapItem` is a top-level opaque class (also returned by `MapDirections`). Read
fields by name; do not try to serialize the instance directly.

| Field                     | Type                | Description                                                                                                             |
| ------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `coordinate`              | `MapCoordinate`     | Always present.                                                                                                         |
| `name`                    | `string \| null`    | "Apple Park Visitor Center"                                                                                             |
| `formattedAddress`        | `string \| null`    | "10600 N Tantau Ave, Cupertino, CA, United States"                                                                      |
| `placemark`               | `LocationPlacemark` | Always present.                                                                                                         |
| `phoneNumber`             | `string \| null`    |                                                                                                                         |
| `url`                     | `string \| null`    |                                                                                                                         |
| `pointOfInterestCategory` | `string \| null`    | `"restaurant"` / `"cafe"` / ...                                                                                         |
| `timeZone`                | `string \| null`    | `"America/Los_Angeles"`                                                                                                 |
| `isCurrentLocation`       | `boolean`           | `true` only when MapKit handed back the device's current-location item; search / directions results are always `false`. |

### `openInMaps(options?)` — hand off to Apple Maps

```ts
const items = await MapSearch.locate({ query: "coffee" })
if (items.length > 0) {
  await items[0].openInMaps({ directionsMode: "walking" })
}
```

Resolves with `true` when the system accepted the launch request. The current
app moves to the background while Apple Maps takes over.

| Option           | Type                                               | Description                                                                                          |
| ---------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `directionsMode` | `"driving" \| "walking" \| "transit" \| "default"` | Show directions on the opened map. `"default"` lets Apple Maps pick the mode based on user settings. |
| `showsTraffic`   | `boolean`                                          | Show live traffic overlay.                                                                           |
| `mapType`        | `"standard" \| "satellite" \| "hybrid"`            | Map type to apply.                                                                                   |

> `JSON.stringify(item)` and `Object.keys(item)` will not return the field
> dictionary — `MapItem` is a class with getters, not a plain object. Spread the
> fields yourself if you need a serializable snapshot.

### Geometry helpers

```ts
item.distance(other)  // meters, Haversine; `other` is a coordinate or another MapItem
item.bearing(other)   // degrees [0, 360), 0 = north
```

Both delegate to `MapUtils.distance` / `MapUtils.bearing`.

### `MapItem.forCurrentLocation()`

Apple's placeholder MapItem for "the device's current location". Synchronous,
no permission prompt, no coordinate fetched locally — Apple Maps interprets the
sentinel when handed to `openInMaps()`.

```ts
await MapItem.forCurrentLocation().openInMaps({ directionsMode: "walking" })
```

Returned items satisfy `isCurrentLocation === true`.

***

## Selecting markers and built-in POIs — `<Map selection>`

Bind an observable of `MapSelectionValue | null` to `<Map selection>`. The
written value is a tagged union:

| `value.type` | Source                                      | Shape                                                                   |
| ------------ | ------------------------------------------- | ----------------------------------------------------------------------- |
| `"marker"`   | A `<Marker tag>` you rendered               | `{ type: "marker", tag: string }`                                       |
| `"feature"`  | An Apple-rendered built-in POI / landmark   | `{ type: "feature", coordinate, title, kind, pointOfInterestCategory }` |
| `null`       | Empty map background was tapped, or initial | —                                                                       |

```tsx
const selection = useObservable<MapSelectionValue | null>(null)
const items: MapItem[] = ...

return <Map cameraPosition={cam} selection={selection}>
  {items.map((item, i) => (
    <Marker item={item} tag={`hit-${i}`} />
  ))}
</Map>
```

Branch on `value.type` to handle each case:

```ts
const sel = selection.value
if (sel == null) {
  // Background tap
} else if (sel.type === "marker") {
  const item = items.find((_, i) => `hit-${i}` === sel.tag)
  // ... use your MapItem
} else {
  // sel.type === "feature" — an Apple POI
  // sel.coordinate, sel.title, sel.pointOfInterestCategory
}
```

`kind` is one of `"pointOfInterest"` / `"physicalFeature"` / `"territory"` /
`"unknown"`. `pointOfInterestCategory` uses the same vocabulary as
`MapPointOfInterestCategory` (e.g. `"restaurant"`, `"cafe"`) and is `null` when
the feature has no category.

Markers without a `tag` are not selectable.

### iOS 17 limitation

On iOS 17, only `type: "feature"` is reported — tapping a tagged `<Marker>`
does **not** fire selection. The unified marker/feature selection requires
iOS 18+ (`MapSelection<Value>`). If your script targets iOS 17 devices, design
around feature taps for POI selection and treat marker selection as iOS 18+ only.

***

## Item selection + Apple's auto detail cards — `<Map itemSelection>`

iOS 18+ adds a higher-level path: bind `<Map itemSelection>` to an
`Observable<MapItem | null>` and pair `<Marker item={mapItem}>` markers with
Apple's built-in detail card via `<Map itemDetailSelectionAccessory>` /
`<Map featureSelectionAccessory>`.

```tsx
const selected = useObservable<MapItem | null>(null)
const items: MapItem[] = ...

return <Map
  cameraPosition={cam}
  itemSelection={selected}
  itemDetailSelectionAccessory="automatic"
  featureSelectionAccessory="automatic"
>
  {items.map(item => (
    <Marker item={item} tint={selected.value === item ? "systemRed" : "systemBlue"} />
  ))}
</Map>
```

- Tapping `<Marker item>` writes that exact `MapItem` instance into the
  observable. Compare with `===` to find the picked item (the JS side keeps
  reference identity through MapKit selection).
- Apple's auto card pops up automatically:
  - `itemDetailSelectionAccessory` — card for tapped item markers (e.g.,
    address, phone, "Directions" button).
  - `featureSelectionAccessory` — card for tapped Apple-rendered POI labels.
- Style values: `"automatic"` (MapKit picks callout vs sheet), `"callout"`,
  `"sheet"`. Pass `null` (or omit the prop) to disable.

> **Nested presentation caveat**: `"automatic"` and `"sheet"` use a modal
> sheet presentation (`MKPresentableSelectionAccessoryViewController`).
> Inside `Navigation.present(...)`-style modal contexts the presentation
> chain conflicts with the parent modal — iOS 18 currently aborts the
> second tap with `Attempt to present ... which is already presenting`,
> and in some cases dismisses the parent modal entirely. Prefer
> `"callout"` (inline anchored bubble, no modal presentation) when the
> map lives inside a presented sheet or `Navigation.present` page.

`itemSelection` is mutually exclusive with `selection`: if both are set,
`itemSelection` wins and string-tag markers do not fire.

### iOS 17 limitation

`itemSelection`, `itemDetailSelectionAccessory`, and `featureSelectionAccessory`
are all iOS 18+. On iOS 17 the props are silently ignored — the map renders,
markers display, but tapping does not write to `itemSelection` and no
Apple-styled card appears.

### Cancellation note

`locate` does not expose a cancellation handle. For typeahead scenarios use
`createCompleter` instead — repeated `locate` calls do not deduplicate stale
responses and a fast typist can see results arrive out of order.

***

## `createCompleter` — autocomplete

```ts
const completer = MapSearch.createCompleter({
  region: { ... },
  resultTypes: ["address", "pointOfInterest", "query"],
})

completer.addListener(suggestions => {
  setOptions(suggestions)
})

completer.setQuery("apple")
// ...later, when the user taps a suggestion:
const items = await completer.resolve(selected)
```

### Options

| Option        | Type                                             | Description                                                                                                                                                            |
| ------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region`      | `MapRegion?`                                     | Bias suggestions toward a region. Can be changed later via `completer.setRegion(...)`.                                                                                 |
| `resultTypes` | `("pointOfInterest" \| "address" \| "query")[]?` | Default: `["pointOfInterest", "address"]`. Note `"query"` is only valid on the completer (offers query-completion suggestions); `"physicalFeature"` is not valid here. |

### Methods

| Method                | Description                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `setQuery(query)`     | Update the search fragment. Triggers a new round of suggestions.                                 |
| `setRegion(region)`   | Update the bias region.                                                                          |
| `addListener(fn)`     | Subscribe to suggestion batches. Each call replaces the previous batch — no diff merging needed. |
| `removeListener(fn?)` | Remove one listener, or all listeners when called without arguments.                             |
| `resolve(completion)` | Look up the full `MapItem[]` for a tapped suggestion.                                            |
| `dispose()`           | Release the underlying completer. Idempotent — safe to call multiple times.                      |

### Lifecycle

One completer corresponds to one input field — sharing a completer between
unrelated fields will cross-contaminate results because the underlying
`queryFragment` is single-valued. Call `dispose()` when the field unmounts.

### Suggestion lifetime

A `MapSearchCompletion`'s `id` is only valid until the completer issues its
next batch of suggestions. Resolving a stale suggestion rejects with
`"unknown completion id"`. In React-style UIs, store the array of suggestions
in state alongside the user's selection so the chosen suggestion's `id` is
always paired with the batch it came from.

***

## Combining with `<Map>`

Hand the whole `MapItem` to `<Marker>` and MapKit fills in title, coordinate,
and a POI-category-driven glyph for you:

```tsx
{items.map(item => (
  <Marker item={item} tint="systemBlue" />
))}
```

If you also pass `title` / `systemImage` / `monogram`, the marker reverts to
the default pin (or your specified glyph) and uses your override — auto-glyph
selection only applies when none of those are given. The two forms are mutually
exclusive in the type system: passing both `item` and `coordinate` is a
compile-time error.

```tsx
// item + custom glyph — your systemImage wins, title still defaults to item.name
<Marker item={mapItem} systemImage="cup.and.saucer.fill" tint="systemRed" />

// coordinate form — you supply everything
<Marker title="Bund" coordinate={{ latitude: 31.24, longitude: 121.49 }} />
```

To fit the map around the result set, use `MapUtils.regionFromCoordinates`:

```ts
const region = MapUtils.regionFromCoordinates(items.map(i => i.coordinate))
if (region) position.setValue({ region })
```

***

## Errors

`locate` rejects when:

- `query` is missing or empty
- The underlying `MKLocalSearch` fails (network, no results, etc.)

`completer.resolve` rejects when:

- The completion id is stale (next batch invalidated it)
- The underlying `MKLocalSearch` lookup fails

The completer's listener never receives a synchronous error; on backend
failure the listener is called with an empty array.



---
url: /guide/Device Capabilities/MapKit/MapSearch/index_example.md
---

# 

***

title: Example
description: MapKit keyword search: one-shot `locate(...)` and stateful autocomplete via `createCompleter(...)`.

***

```tsx
import {
  Button, HStack, Map, Marker, Navigation, NavigationStack,
  Script, ScrollView, Text, TextField, useEffect, useMemo, useObservable, useRef,
  useState, VStack,
} from "scripting"

// Demo center: People's Square, Shanghai
const initialRegion = {
  center: { latitude: 31.2304, longitude: 121.4737 },
  span: { latitudeDelta: 0.05, longitudeDelta: 0.05 },
}

function LocateDemo() {
  const [query, setQuery] = useState("coffee")
  const [items, setItems] = useState<MapItem[]>([])
  const [isLoading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)

  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))
  // Phase 3h: <Map itemSelection> binds the tapped MapItem directly.
  // Apple's `itemDetailSelectionAccessory` shows the auto-generated detail card.
  // Apple POI taps are handled by `featureSelectionAccessory` (also auto card)
  // and don't fire this observable. iOS 17 silently no-ops on both.
  const selectedItem = useObservable<MapItem | null>(null)

  const search = async () => {
    setLoading(true)
    setErr(null)
    selectedItem.setValue(null)
    try {
      const result = await MapSearch.locate({
        query,
        region: initialRegion,
        resultTypes: ["pointOfInterest"],
      })
      setItems(result)
      // Auto-fit the map around the results.
      const fit = MapUtils.regionFromCoordinates(result.map(i => i.coordinate))
      if (fit) position.setValue(MapCameraPosition.region(fit))
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  // Hand the first result off to Apple Maps with walking directions overlaid.
  const openFirstInMaps = async () => {
    const first = items[0]
    if (!first) return
    await first.openInMaps({ directionsMode: "walking", showsTraffic: true })
  }

  // forCurrentLocation() returns Apple's placeholder MapItem that
  // resolves to the device's location inside Apple Maps — no permission needed.
  const openCurrentInMaps = () => MapItem.forCurrentLocation().openInMaps()

  // Distance from the search center to the selected marker, via MapItem.distance.
  const selected = selectedItem.value
  const selectedDistance = selected != null
    ? MapUtils.formatDistance(selected.distance(initialRegion.center))
    : null

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>1. `MapSearch.locate` + selection</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`One-shot search for points of interest near People's Square. Each hit
      drops into a \`<Marker item={item}>\`. Tapping (iOS 18+) writes the
      tapped MapItem into \`itemSelection\` and Apple shows its built-in
      detail card via \`itemDetailSelectionAccessory\`. Tapping an Apple-rendered
      POI label shows the same auto card via \`featureSelectionAccessory\`.`}
    </Text>
    <TextField
      title="query"
      value={query}
      onChanged={setQuery}
      prompt="Search keyword"
    />
    <HStack spacing={8}>
      <Button title={isLoading ? "Searching..." : "Search"} action={search} />
      <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
        {items.length} hits
      </Text>
    </HStack>
    {items.length > 0
      ? <Button
        title={`Open "${items[0].name ?? "first hit"}" in Maps`}
        buttonStyle="bordered"
        action={openFirstInMaps}
      />
      : null}
    <Button
      title="Open current location in Maps"
      buttonStyle="bordered"
      action={openCurrentInMaps}
    />
    {selected != null
      ? <VStack alignment={"leading"} spacing={2}>
        <Text font={"caption"} foregroundStyle={"systemBlue"}>
          Selected: {selected.name ?? "(unnamed)"}
        </Text>
        {selected.formattedAddress != null
          ? <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>
            {selected.formattedAddress}
          </Text>
          : null}
        {selectedDistance != null
          ? <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
            {selectedDistance} from search center
          </Text>
          : null}
      </VStack>
      : null}
    {err != null
      ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text>
      : null}
    <Map
      cameraPosition={position}
      itemSelection={selectedItem}
      // `"callout"` is an inline anchored bubble — does not trigger a sheet
      // presentation. Safe inside `Navigation.present`-style nested modals.
      // `"automatic"` / `"sheet"` may conflict with the parent modal chain
      // (iOS 18 currently aborts with "already presenting" — see Phase 3h docs).
      itemDetailSelectionAccessory="callout"
      featureSelectionAccessory="callout"
      frame={{ height: 280 }}
      clipShape={{ type: 'rect', cornerRadius: 12 }}
    >
      {items.map(item => (
        // Item-based marker — MapKit picks the POI glyph and uses item.name
        // as the marker title. The same MapItem reference is what itemSelection
        // observes when the user taps the marker.
        <Marker
          item={item}
          tint={selected === item ? "systemRed" : "systemBlue"}
        />
      ))}
    </Map>
  </VStack>
}

function CompleterDemo() {
  const [query, setQuery] = useState("")
  const [suggestions, setSuggestions] = useState<MapSearch.MapSearchCompletion[]>([])
  const [resolved, setResolved] = useState<MapItem[]>([])
  const [resolveErr, setResolveErr] = useState<string | null>(null)

  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  // Hold the completer in a ref so it survives re-renders.
  const completerRef = useRef<ReturnType<typeof MapSearch.createCompleter> | null>(null)

  useEffect(() => {
    const c = MapSearch.createCompleter({
      region: initialRegion,
      resultTypes: ["pointOfInterest", "address"],
    })
    completerRef.current = c
    const listener = (suggs: MapSearch.MapSearchCompletion[]) => {
      setSuggestions(suggs)
    }
    c.addListener(listener)
    return () => {
      c.removeListener(listener)
      c.dispose()
      completerRef.current = null
    }
  }, [])

  const onQueryChange = (text: string) => {
    setQuery(text)
    completerRef.current?.setQuery(text)
  }

  const onPickSuggestion = async (s: MapSearch.MapSearchCompletion) => {
    setResolveErr(null)
    try {
      const items = await completerRef.current!.resolve(s)
      setResolved(items)
      const fit = MapUtils.regionFromCoordinates(items.map(i => i.coordinate))
      if (fit) position.setValue(MapCameraPosition.region(fit))
    } catch (e) {
      setResolveErr(String(e))
    }
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>2. `MapSearch.createCompleter`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Stateful autocomplete. Type and watch suggestions update live. Tap one to
      resolve it to `MapItem[]` and drop the hits on the map.
    </Text>
    <TextField
      title="query"
      value={query}
      onChanged={onQueryChange}
      prompt="Start typing..."
    />
    <VStack alignment={"leading"} spacing={4}>
      {suggestions.slice(0, 6).map(s => (
        <Button
          title={s.title + (s.subtitle ? ` — ${s.subtitle}` : "")}
          buttonStyle="bordered"
          action={() => onPickSuggestion(s)}
        />
      ))}
    </VStack>
    {resolveErr != null
      ? <Text font={"caption"} foregroundStyle={"systemRed"}>{resolveErr}</Text>
      : null}
    <Map
      cameraPosition={position}
      frame={{ height: 240 }}
      clipShape={{ type: 'rect', cornerRadius: 12 }}
    >
      {resolved.map(item => (
        <Marker item={item} tint="systemRed" />
      ))}
    </Map>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      Note: a completion's `id` is invalidated by the next suggestion batch — pick
      from the current list, not a stale state snapshot.
    </Text>
  </VStack>
}

function POIFilterDemo() {
  const [items, setItems] = useState<MapItem[]>([])
  const position = useObservable<MapCameraPosition>(MapCameraPosition.region(initialRegion))

  const run = async (filter: any, label: string) => {
    const result = await MapSearch.locate({
      query: "shop",
      region: initialRegion,
      pointOfInterestFilter: filter,
    })
    setItems(result)
    const fit = MapUtils.regionFromCoordinates(result.map(i => i.coordinate))
    if (fit) position.setValue(MapCameraPosition.region(fit))
    console.log(`${label}: ${result.length} hits`)
  }

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>3. `pointOfInterestFilter`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      {`Restrict POI categories in search results. Same \`MapPointsOfInterestSpec\`
      union accepted by \`<Map mapStyle>\`.`}
    </Text>
    <HStack spacing={8}>
      <Button
        title="cafe + restaurant only"
        buttonStyle="bordered"
        action={() => run({ includes: ["cafe", "restaurant"] }, "includes")}
      />
      <Button
        title="exclude gasStation"
        buttonStyle="bordered"
        action={() => run({ excludes: ["gasStation"] }, "excludes")}
      />
    </HStack>
    <Map
      cameraPosition={position}
      frame={{ height: 240 }}
      clipShape={{ type: 'rect', cornerRadius: 12 }}
    >
      {items.map(item => (
        <Marker item={item} tint="systemGreen" />
      ))}
    </Map>
  </VStack>
}

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Search"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"MapSearch"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={24}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          MapKit on-device search. No permissions required — coordinates can flow
          directly into `Marker` / `Map` from the views layer. For typeahead UIs,
          prefer `createCompleter` over polling `locate` on every keystroke.
        </Text>

        <LocateDemo />
        <CompleterDemo />
        <POIFilterDemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/MapKit/MapSnapshotter/index.md
---

# MapSnapshotter

`MapSnapshotter` renders a static map image offscreen via MapKit. Useful when
you need a map picture without a live `<Map>` view — widget previews,
share-sheet thumbnails, exported reports, or any place SwiftUI's `Map` isn't
available.

```tsx
const snap = await MapSnapshotter.take({
  region: {
    center: { latitude: 31.2407, longitude: 121.4905 },
    span: { latitudeDelta: 0.02, longitudeDelta: 0.02 },
  },
  size: { width: 320, height: 200 },
})

// snap.image is a UIImage — feed it straight into <Image>.
return <Image image={snap.image} />
```

***

## `take` — render a snapshot

### Options

| Option       | Type                                | Description                                                                         |
| ------------ | ----------------------------------- | ----------------------------------------------------------------------------------- |
| `region`     | `MapRegion?`                        | Region to capture. Mutually exclusive with `camera`.                                |
| `camera`     | `MapCamera?`                        | Eye-style framing (`MapCamera.make(...)`). Wins over `region` if both are supplied. |
| `size`       | `{ width: number; height: number }` | Required. Output dimensions in points; both > 0.                                    |
| `scale`      | `number?`                           | Pixel scale factor. Default = device main screen scale.                             |
| `mapStyle`   | `MapStyleSpec?`                     | Same shape as `<Map mapStyle>`. Default `{ style: "standard" }`.                    |
| `appearance` | `"light" \| "dark"?`                | Color tint of the rendered map.                                                     |

### `MapSnapshot`

| Member              | Type                | Description                                                                                                                                                                                                                                             |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size`              | `{ width, height }` | Matches `options.size`.                                                                                                                                                                                                                                 |
| `image`             | `UIImage`           | Rendered map. Plug into `<Image image={snap.image} />` or use any of the `UIImage` instance methods — `toPNGBase64String()`, `toPNGData()`, `preparingThumbnail(size)`, `withTintColor(...)`, etc.                                                      |
| `point(coordinate)` | `{ x, y }`          | Convert a geographic coordinate into snapshot-space points (matches `size`). Coordinates outside the visible region still return a point — values may be negative or exceed `size`, so bounds-check if you only want to draw overlays inside the frame. |

### Overlay coordinates

`point` is the snapshotter's escape hatch for drawing pins or labels on top of
the image:

```tsx
const pin = snap.point({ latitude: 31.24, longitude: 121.49 })
const inBounds =
  pin.x >= 0 && pin.y >= 0 && pin.x <= snap.size.width && pin.y <= snap.size.height

return <ZStack>
  <Image image={snap.image} />
  {inBounds
    ? <Image
        systemName="mappin.circle.fill"
        position={{ x: pin.x, y: pin.y }}
        foregroundStyle="systemRed"
      />
    : null}
</ZStack>
```

### Working with the `UIImage`

`snap.image` exposes the same `UIImage` instance returned by other APIs, so
all the existing helpers work — for example, downscale before sharing:

```ts
const thumb = snap.image.preparingThumbnail({ width: 160, height: 100 })
const pngBase64 = await thumb?.toPNGBase64String()
```

***

## Notes

- A 1024×768 retina PNG can be a few megabytes; reach for `preparingThumbnail`
  before persisting if the snapshot is only used as a preview.
- Apple caps `scale` around 3x on most devices; values above are silently
  clamped.
- Network-backed (Apple's map tile service) — failures resolve through the
  Promise rejection with the underlying error message.



---
url: /guide/Device Capabilities/MapKit/MapSnapshotter/index_example.md
---

# Example

```tsx
import {
  Button, Color, HStack, Image, MapCoordinate, MapRegion, Navigation, NavigationStack,
  Picker, Script, ScrollView, Text, useState, VStack, ZStack,
} from "scripting"

type POI = { name: string; coord: MapCoordinate; tint: Color }

type PresetDef = {
  region: MapRegion
  pois: POI[]
}

// Each preset ships with a couple of named POIs nearby — typical
// "widget preview" pattern: render a static map with multiple labeled pins.
const PRESETS: Record<string, PresetDef> = {
  bund: {
    region: {
      center: { latitude: 31.2407, longitude: 121.4905 },
      span: { latitudeDelta: 0.025, longitudeDelta: 0.025 },
    },
    pois: [
      { name: "Bund", coord: { latitude: 31.2407, longitude: 121.4905 }, tint: "systemRed" },
      { name: "Lujiazui", coord: { latitude: 31.2397, longitude: 121.4994 }, tint: "systemBlue" },
      { name: "Yu Garden", coord: { latitude: 31.2275, longitude: 121.4920 }, tint: "systemPurple" },
    ],
  },
  apple_park: {
    region: {
      center: { latitude: 37.3349, longitude: -122.0090 },
      span: { latitudeDelta: 0.015, longitudeDelta: 0.015 },
    },
    pois: [
      { name: "Apple Park", coord: { latitude: 37.3349, longitude: -122.0090 }, tint: "systemRed" },
      { name: "Visitor Center", coord: { latitude: 37.3327, longitude: -122.0053 }, tint: "systemTeal" },
    ],
  },
  golden_gate: {
    region: {
      center: { latitude: 37.8199, longitude: -122.4783 },
      span: { latitudeDelta: 0.025, longitudeDelta: 0.025 },
    },
    pois: [
      { name: "Bridge North", coord: { latitude: 37.8324, longitude: -122.4795 }, tint: "systemOrange" },
      { name: "Bridge South", coord: { latitude: 37.8070, longitude: -122.4750 }, tint: "systemOrange" },
      { name: "Fort Point", coord: { latitude: 37.8104, longitude: -122.4769 }, tint: "systemBrown" },
    ],
  },
}

type Preset = keyof typeof PRESETS

const SNAP_W = 320
const SNAP_H = 220

function Example() {
  const [preset, setPreset] = useState<Preset>("bund")
  const [style, setStyle] = useState<"standard" | "imagery" | "hybrid">("standard")
  const [appearance, setAppearance] = useState<"light" | "dark">("light")
  const [snap, setSnap] = useState<MapSnapshot | null>(null)
  const [loading, setLoading] = useState(false)
  const [err, setErr] = useState<string | null>(null)

  const def = PRESETS[preset]

  const take = async () => {
    setLoading(true); setErr(null)
    try {
      const result = await MapSnapshotter.take({
        region: def.region,
        size: { width: SNAP_W, height: SNAP_H },
        mapStyle: { style },
        appearance,
      })
      setSnap(result)
    } catch (e) {
      setErr(String(e))
    } finally {
      setLoading(false)
    }
  }

  // For each POI of the active preset, project the geo coordinate onto the
  // snapshot's point space. Clip to snapshot bounds so off-screen pins drop
  // out instead of bleeding past the image edge.
  const overlays = snap != null
    ? def.pois.map(p => {
        const pt = snap.point(p.coord)
        const inBounds =
          pt.x >= 0 && pt.y >= 0 && pt.x <= snap.size.width && pt.y <= snap.size.height
        return { ...p, pt, inBounds }
      })
    : []

  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Snapshotter"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"MapSnapshotter"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={16}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          {`MapSnapshotter.take(...) renders a static map offscreen and returns
          a MapSnapshot { image, point }. The image
          below is the snapshot's image fed into <Image image={snap.image}>.`}
        </Text>

        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>Preset region</Text>
          <Picker
            title="Region"
            value={preset}
            onChanged={(v: any) => setPreset(v as Preset)}
            pickerStyle={"segmented"}
          >
            <Text tag={"bund"}>Bund</Text>
            <Text tag={"apple_park"}>Apple Park</Text>
            <Text tag={"golden_gate"}>Golden Gate</Text>
          </Picker>
        </VStack>

        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>Map style</Text>
          <Picker
            title="Style"
            value={style}
            onChanged={(v: any) => setStyle(v as any)}
            pickerStyle={"segmented"}
          >
            <Text tag={"standard"}>standard</Text>
            <Text tag={"imagery"}>imagery</Text>
            <Text tag={"hybrid"}>hybrid</Text>
          </Picker>
        </VStack>

        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>Appearance</Text>
          <Picker
            title="Appearance"
            value={appearance}
            onChanged={(v: any) => setAppearance(v as any)}
            pickerStyle={"segmented"}
          >
            <Text tag={"light"}>light</Text>
            <Text tag={"dark"}>dark</Text>
          </Picker>
        </VStack>

        <HStack spacing={8}>
          <Button title={loading ? "Rendering..." : "Take snapshot"} action={take} />
          {snap != null
            ? <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
              {snap.size.width} × {snap.size.height} pt
            </Text>
            : null}
        </HStack>

        {err != null
          ? <Text font={"caption"} foregroundStyle={"systemRed"}>{err}</Text>
          : null}

        {snap != null
          ? <ZStack frame={{ width: SNAP_W, height: SNAP_H }}>
            <Image
              image={snap.image}
              resizable
              scaleToFit
              frame={{ width: SNAP_W, height: SNAP_H }}
              clipShape={{ type: "rect", cornerRadius: 12 }}
            />
            {/* 多个 POI 覆盖:每个 pin + 文字标签都按 snap.point(...) 投影到画布上。 */}
            {overlays.filter(o => o.inBounds).map(o =>
              <VStack key={o.name} spacing={1} position={{ x: o.pt.x, y: o.pt.y - 14 }}>
                <Image
                  systemName="mappin.circle.fill"
                  font={"title3"}
                  foregroundStyle={o.tint}
                />
                <Text
                  font={"caption2"}
                  foregroundStyle={"white"}
                  padding={{ horizontal: 4, vertical: 1 }}
                  background={"rgba(0, 0, 0, 0.55)"}
                  clipShape={{ type: "rect", cornerRadius: 4 }}
                >
                  {o.name}
                </Text>
              </VStack>
            )}
          </ZStack>
          : <Text font={"caption"} foregroundStyle={"tertiaryLabel"}>
            Snapshot will appear here after rendering.
          </Text>}

        {snap != null
          ? <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
            {`${overlays.filter(o => o.inBounds).length} / ${overlays.length} POIs in bounds — out-of-bounds coordinates are clipped instead of bleeding past the image edge.`}
          </Text>
          : null}
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/MapKit/MapUtils/index.md
---

# 

***

title: MapUtils
description: Synchronous MapKit geometry helpers: `distance`, `bearing`, `regionContains`, `regionFromCoordinates`.

***

`MapUtils` is a small set of synchronous geometry helpers for the MapKit
coordinate / region types from the views layer. Pure functions, safe to call
during render or in tight loops.

***

## `distance(a, b)`

Great-circle distance between two `MapCoordinate`s in **meters**, computed via
the Haversine formula using mean Earth radius (`6_371_008.8 m`).

```ts
const d = MapUtils.distance(
  { latitude: 39.9042, longitude: 116.4074 },  // Beijing
  { latitude: 31.2304, longitude: 121.4737 },  // Shanghai
)
// d ≈ 1_067_000  (meters)
```

Accuracy is good enough for typical "near me / how far away" use cases. For
applications that need geodetic-grade precision (geological surveying etc.),
use a dedicated geodesy library.

***

## `bearing(a, b)`

Initial bearing (forward azimuth) from `a` to `b`, in degrees normalized to
`[0, 360)`:

| Value | Direction |
| ----- | --------- |
| `0`   | North     |
| `90`  | East      |
| `180` | South     |
| `270` | West      |

```ts
MapUtils.bearing(
  { latitude: 0, longitude: 0 },
  { latitude: 0, longitude: 1 },
)  // 90
```

The bearing returned is the **initial** bearing — on long great-circle routes
the actual direction at the destination is different. For map-marker rotation
the initial bearing is what you want.

***

## `regionContains(region, coordinate)`

Whether `coordinate` lies inside the rectangular `MapRegion`:

```ts
const region = {
  center: { latitude: 31.23, longitude: 121.47 },
  span: { latitudeDelta: 0.1, longitudeDelta: 0.1 },
}
MapUtils.regionContains(region, { latitude: 31.24, longitude: 121.48 })  // true
MapUtils.regionContains(region, { latitude: 32.00, longitude: 121.47 })  // false
```

**Caveat**: does not handle regions that straddle the ±180° antimeridian (the
"Pacific date line"). If you need cross-meridian membership, split the test
into two regions manually.

***

## `regionFromCoordinates(coordinates, paddingFactor?)`

Smallest `MapRegion` enclosing all coordinates. Useful for fitting the camera
around a set of `Marker`s or a polyline.

```ts
const region = MapUtils.regionFromCoordinates([
  { latitude: 31.23, longitude: 121.47 },
  { latitude: 31.24, longitude: 121.50 },
  { latitude: 31.22, longitude: 121.49 },
])

if (region) {
  position.setValue({ region })  // fits the camera around all three points
}
```

| Parameter       | Default | Description                                                     |
| --------------- | ------- | --------------------------------------------------------------- |
| `paddingFactor` | `0.1`   | Fractional expansion of the bounding span. `0` for a tight fit. |

Edge cases:

- Empty array → returns `null`.
- Single coordinate → returns a region with a minimal 0.01° span centered on
  that point.
- Coordinates collinear in latitude or longitude → span is clamped to a
  minimum of `0.005°` to avoid `0` span (which MapKit would reject).
- Antimeridian-crossing input (e.g. one point at `+170°`, one at `-170°`)
  produces a region spanning the long way around. Not Phase-3a–supported.

***

## `formatDistance(meters, options?)`

Localized human-readable distance via Apple's `MKDistanceFormatter`. Negative
inputs clamp to `0`.

```ts
MapUtils.formatDistance(1230)                            // "1.2 km" (locale-dependent)
MapUtils.formatDistance(1230, { units: "imperial" })     // "0.8 mi"
MapUtils.formatDistance(1230, { unitStyle: "full" })     // "1.2 kilometers"
```

| Option      | Type                                   | Description                                             |
| ----------- | -------------------------------------- | ------------------------------------------------------- |
| `units`     | `"metric" \| "imperial" \| "default"`  | Force a unit system. Default follows the device locale. |
| `unitStyle` | `"default" \| "abbreviated" \| "full"` | Length of the unit suffix (`"km"` vs `"kilometers"`).   |

Output is locale-aware — do not assert on exact strings in tests.

***

## `formatDuration(seconds, options?)`

Localized duration via `DateComponentsFormatter`. Negative inputs return an
empty string.

```ts
MapUtils.formatDuration(3725)                              // "1h 2m"
MapUtils.formatDuration(3725, { unitsStyle: "full" })       // "1 hour, 2 minutes"
MapUtils.formatDuration(3725, { unitsStyle: "positional" }) // "1:02:05"
MapUtils.formatDuration(86_400 + 3600, { maximumUnitCount: 1 }) // "1d"
```

| Option             | Type                                                                          | Default                     | Description                                                                 |
| ------------------ | ----------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------- |
| `unitsStyle`       | `"positional" \| "abbreviated" \| "short" \| "full" \| "brief" \| "spellOut"` | `"abbreviated"`             | Visual style of the unit suffix.                                            |
| `allowedUnits`     | `("day" \| "hour" \| "minute" \| "second")[]`                                 | `["day", "hour", "minute"]` | Which units the formatter is allowed to emit.                               |
| `maximumUnitCount` | `number`                                                                      | unlimited                   | Cap how many unit segments appear (`1` collapses `3661s` to just `"1 hr"`). |

***

## When to use

- After `MapSearch.locate` / `Location.geocodeAddress`:
  `regionFromCoordinates` lets you auto-fit the camera around all hits.
- "Within Xm of me": call `distance(myLocation, item.coordinate) < X`.
- Sorting search results by proximity: stable-sort the array by `distance`.
- Compass arrow on a marker pointing to a target: `bearing` gives the rotation
  in degrees.
- Rendering route metadata (`route.distance` / `route.expectedTravelTime` from
  `MapDirections`): `formatDistance` / `formatDuration` give locale-aware labels.



---
url: /guide/Device Capabilities/MapKit/MapUtils/index_example.md
---

# 

***

title: Example
description: Synchronous MapKit geometry helpers: `distance`, `bearing`, `regionContains`, `regionFromCoordinates`.

***

```tsx
import {
  Button, HStack, Map, Marker, Navigation, NavigationStack, Script,
  ScrollView, Text, useEffect, useMemo, useObservable, useState, VStack,
} from "scripting"
import type { MapCoordinate } from "scripting"

const beijing: MapCoordinate = { latitude: 39.9042, longitude: 116.4074 }
const shanghai: MapCoordinate = { latitude: 31.2304, longitude: 121.4737 }
const guangzhou: MapCoordinate = { latitude: 23.1291, longitude: 113.2644 }
const sanFrancisco: MapCoordinate = { latitude: 37.7749, longitude: -122.4194 }

function DistanceBearingDemo() {
  const [from, setFrom] = useState<MapCoordinate>(beijing)
  const [to, setTo] = useState<MapCoordinate>(shanghai)

  const d = useMemo(() => MapUtils.distance(from, to), [from, to])
  const b = useMemo(() => MapUtils.bearing(from, to), [from, to])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>1. `distance` + `bearing`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Haversine distance (meters) and initial bearing (degrees, 0 = north,
      90 = east) between two coordinates.
    </Text>
    <HStack spacing={8}>
      <Button title="Beijing → Shanghai" buttonStyle="bordered"
        action={() => { setFrom(beijing); setTo(shanghai) }} />
      <Button title="Shanghai → Guangzhou" buttonStyle="bordered"
        action={() => { setFrom(shanghai); setTo(guangzhou) }} />
      <Button title="Beijing → SF" buttonStyle="bordered"
        action={() => { setFrom(beijing); setTo(sanFrancisco) }} />
    </HStack>
    <Text monospaced>
      {`from: ${from.latitude.toFixed(3)}, ${from.longitude.toFixed(3)}\n`}
      {`to:   ${to.latitude.toFixed(3)}, ${to.longitude.toFixed(3)}\n`}
      {`distance: ${(d / 1000).toFixed(1)} km\n`}
      {`bearing:  ${b.toFixed(1)}°`}
    </Text>
  </VStack>
}

function RegionContainsDemo() {
  // Region around People's Square, Shanghai
  const region = {
    center: { latitude: 31.2304, longitude: 121.4737 },
    span: { latitudeDelta: 0.05, longitudeDelta: 0.05 },
  }

  const testPoints: { label: string; coord: MapCoordinate; inside: boolean }[] = useMemo(() => {
    const probes = [
      { label: "Bund", coord: { latitude: 31.2407, longitude: 121.4905 } },
      { label: "Lujiazui", coord: { latitude: 31.2397, longitude: 121.4994 } },
      { label: "Pudong Intl Airport", coord: { latitude: 31.1443, longitude: 121.8083 } },
      { label: "Hangzhou", coord: { latitude: 30.2741, longitude: 120.1551 } },
    ]
    return probes.map(p => ({ ...p, inside: MapUtils.regionContains(region, p.coord) }))
  }, [])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>2. `regionContains`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Region: ~5 km box around People's Square. Probe a few points to see which
      land inside.
    </Text>
    <VStack alignment={"leading"} spacing={4}>
      {testPoints.map(p => (
        <Text monospaced>
          {p.inside ? "✓ inside  " : "✗ outside "} {p.label}
        </Text>
      ))}
    </VStack>
  </VStack>
}

function RegionFromCoordinatesDemo() {
  const [paddingFactor, setPaddingFactor] = useState(0.1)

  const coords = useMemo<MapCoordinate[]>(() => [
    { latitude: 31.2407, longitude: 121.4905 },  // Bund
    { latitude: 31.2304, longitude: 121.4737 },  // People's Square
    { latitude: 31.2397, longitude: 121.4994 },  // Lujiazui
    { latitude: 31.2229, longitude: 121.4583 },  // Nanjing Rd
  ], [])

  const region = useMemo(
    () => MapUtils.regionFromCoordinates(coords, paddingFactor),
    [coords, paddingFactor]
  )

  // 用 cameraPosition (双向 observable) 而不是 initialCameraPosition,这样
  // paddingFactor 变化时新计算的 region 会通过 setValue 推到地图。
  // initialCameraPosition 顾名思义只在首次挂载生效,后续不响应 prop 变化。
  const camera = useObservable<MapCameraPosition>(
    region != null ? MapCameraPosition.region(region) : MapCameraPosition.automatic()
  )

  useEffect(() => {
    if (region != null) {
      camera.setValue(MapCameraPosition.region(region))
    }
  }, [region])

  return <VStack alignment={"leading"} spacing={8}>
    <Text font={"headline"}>3. `regionFromCoordinates`</Text>
    <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
      Smallest enclosing region for 4 Shanghai landmarks. Padding expands the
      bounding box outward.
    </Text>
    <HStack spacing={8}>
      <Button title="tight (0)" buttonStyle="bordered" action={() => setPaddingFactor(0)} />
      <Button title="10% pad" buttonStyle="bordered" action={() => setPaddingFactor(0.1)} />
      <Button title="50% pad" buttonStyle="bordered" action={() => setPaddingFactor(0.5)} />
    </HStack>
    <Text font={"caption2"} foregroundStyle={"tertiaryLabel"}>
      paddingFactor: {paddingFactor}{"  ·  "}
      span: {region?.span.latitudeDelta.toFixed(4)}° × {region?.span.longitudeDelta.toFixed(4)}°
    </Text>
    <Map
      cameraPosition={camera}
      frame={{ height: 280 }}
      clipShape={{
        type: 'rect',
        cornerRadius: 12
      }}
    >
      {coords.map(c => (
        <Marker
          coordinate={c}
          tint="systemBlue"
        />
      ))}
    </Map>
  </VStack>
}

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <ScrollView
      navigationTitle="Map Utils"
      toolbar={{
        cancellationAction: <Button
          title="Close"
          action={dismiss}
        />
      }}
    >
      <VStack
        navigationTitle={"MapUtils"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={24}
        padding
      >
        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          Synchronous geometry helpers for MapKit coordinate / region types. Pure
          functions, safe to call during render.
        </Text>

        <DistanceBearingDemo />
        <RegionContainsDemo />
        <RegionFromCoordinatesDemo />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Device Capabilities/MediaComposer/MediaComposer Example.md
---

# MediaComposer Example

This example demonstrates how to use `MediaComposer` to compose a final video from **video, image, and audio sources**, and export it to the script directory.

The workflow covered in this example includes:

1. Picking an audio file
2. Picking an image
3. Picking a video
4. Building a visual timeline (video + image)
5. Inserting audio at a specific time
6. Exporting the composed video

***

## Example Code

```tsx
import { Path, Script } from "scripting"

console.present().then(() => Script.exit())

async function run() {
  try {

    const audioPath = (await DocumentPicker.pickFiles({
      types: ["public.audio"]
    })).at(0)

    if (audioPath == null) {
      console.error("no audio")
      return
    }

    console.log("Audio Picked")

    const imageResult = (await Photos.pick({
      filter: PHPickerFilter.images()
    })).at(0)

    const imagePath = await imageResult?.itemProvider.loadFilePath("public.image")

    if (!imagePath) {
      console.log("No image")
      return
    }

    console.log("Image picked")

    const videoResult = (await Photos.pick({
      filter: PHPickerFilter.videos()
    })).at(0)

    const videoPath = await videoResult?.itemProvider.loadFilePath("public.movie")

    if (videoPath == null) {
      console.log("No video")
      return
    }

    console.log("Video Picked")

    console.log("Start composing...")

    const exportPath = Path.join(
      Script.directory,
      "dest.mp4"
    )

    const exportResult = await MediaComposer.composeAndExport({
      exportPath,
      timeline: {
        videoItems: [{
          videoPath: videoPath
        }, {
          imagePath: imagePath,
          duration: MediaTime.make({
            seconds: 5,
            preferredTimescale: 600
          })
        }],
        audioClips: [{
          path: audioPath,
          at: MediaTime.make({
            seconds: 5,
            preferredTimescale: 600
          })
        }]
      }
    })

    console.log(
      "Result:",
      exportResult.exportPath,
      "\n",
      exportResult.duration.getSeconds()
    )

  } catch (e) {
    console.error(e)
  }
}

run()
```

***

## Timeline Breakdown

### Visual Timeline (videoItems)

```ts
videoItems: [
  { videoPath },
  {
    imagePath,
    duration: MediaTime.make({
      seconds: 5,
      preferredTimescale: 600
    })
  }
]
```

- The first `VideoItem` is a full video clip
- The second `VideoItem` is an image displayed for 5 seconds
- All `videoItems` are concatenated **in strict order**
- Final video duration = video duration + 5 seconds

***

### Audio Timeline (audioClips)

```ts
audioClips: [{
  path: audioPath,
  at: MediaTime.make({
    seconds: 5,
    preferredTimescale: 600
  })
}]
```

- The audio starts playing at **5 seconds** on the final timeline
- When `at` is omitted, audio clips are appended sequentially
- Audio does **not** affect the final video duration

***

## Export Result

```ts
{
  exportPath: string
  duration: MediaTime
}
```

- `exportPath`: the full output file path
- `duration`: the total video duration (derived from `videoItems`)

***

## Common Errors and Edge Cases

### 1. ImageClip without duration

```ts
{
  imagePath: "...",
  // ❌ missing duration
}
```

**Issue:**

- Images have no intrinsic duration
- Omitting `duration` will cause composition to fail

**Solution:**

- Always provide an explicit `MediaTime` duration

***

### 2. Using raw numbers instead of MediaTime

```ts
// ❌ incorrect
at: 5
```

**Correct usage:**

```ts
at: MediaTime.make({
  seconds: 5,
  preferredTimescale: 600
})
```

All time values in MediaComposer **must** be represented by `MediaTime`.

***

### 3. Mixed timescales causing precision issues

**Issue:**

- Different media sources may use different timescales
- This can lead to rounding errors during trimming, fades, or alignment

**Recommendation:**

- Use a consistent `preferredTimescale` (e.g. 600)
- Convert external times using `convertScale` when needed

***

### 4. Audio extending beyond the video duration

**Behavior:**

- Audio that exceeds the end of the video does not extend the final duration
- Any audio beyond the video end is automatically truncated

***

### 5. Unexpected audio balance when mixing original and external audio

**Cause:**

- By default, original video audio and external audio are mixed together
- Without ducking, dialogue may be masked by background music

***

## Audio Ducking Behavior

### What is Ducking

Ducking refers to:

> Automatically lowering the volume of external audio (e.g. background music) when original video audio (e.g. dialogue) is present.

***

### Ducking Configuration

```ts
exportOptions: {
  ducking: {
    enabled: true,
    duckedVolume: 0.25,
    attackSeconds: 0.15,
    releaseSeconds: 0.25
  }
}
```

#### Parameters

- **enabled**
  Enables or disables ducking (default: `true`)

- **duckedVolume**
  Target volume for external audio during ducking (0...1)

- **attackSeconds**
  Ramp-down duration before original audio starts

- **releaseSeconds**
  Ramp-up duration after original audio ends

***

### Conditions for Ducking to Apply

Ducking is applied only when all of the following are true:

1. `VideoClip.keepOriginalAudio === true`
2. At least one external `AudioClip` exists
3. `exportOptions.ducking.enabled !== false`

***

## Audio Mixing Rules Summary

1. **Original Video Audio**

   - Included only when `keepOriginalAudio` is set to `true`

2. **External Audio**

   - Can be positioned or appended sequentially
   - Supports per-clip `volume`, `fade`, and looping

3. **Final Mix**

   - All audio sources are mixed into a single output track
   - Audio never changes the final video duration
   - Ducking is applied automatically during mixing



---
url: /guide/Device Capabilities/MediaComposer/MediaTime.md
---

# MediaTime

`MediaTime` represents **precise media time values** in audio and video processing. It is the fundamental time type used by MediaComposer in Scripting.

Conceptually, `MediaTime` corresponds to a time value with an explicit time base (similar to `CMTime` in AVFoundation), but provides a safer and more expressive abstraction for the scripting layer.

A `MediaTime` instance can represent **numeric time**, **invalid time**, **indefinite time**, or **infinite time**, and supports strict arithmetic and comparison operations.

***

## Key Features

- Precise construction using **value + timescale** or **seconds + preferredTimescale**
- Time scaling with configurable rounding methods
- Safe arithmetic and comparison operations
- Explicit modeling of invalid, indefinite, and infinite time values
- Designed for timeline composition, trimming, alignment, fades, and placement

***

## Time Precision Model

`MediaTime` is based on the following core concepts:

- **value**: an integer time value
- **timescale**: the number of time units per second

Examples:

- `value = 300`, `timescale = 600` → 0.5 seconds
- `value = 18000`, `timescale = 600` → 30 seconds

This model allows frame-accurate or sample-accurate timing without relying on floating-point arithmetic.

***

## Read-only Properties

### secondes

```ts
readonly secondes: number
```

The time expressed in seconds as a floating-point value.
This is a derived value intended mainly for display or debugging. It is **not recommended for timeline calculations**.

***

### isValid

```ts
readonly isValid: boolean
```

Indicates whether the time is valid and usable for calculations.
Returns `false` for invalid, indefinite, or infinite time values.

***

### isPositiveInfinity / isNegativeInfinity

```ts
readonly isPositiveInfinity: boolean
readonly isNegativeInfinity: boolean
```

Indicates whether the time represents positive or negative infinity.
These values are typically used as internal boundary markers in timeline logic.

***

### isIndefinite

```ts
readonly isIndefinite: boolean
```

Indicates whether the time is indefinite.
This is commonly used when a media asset’s duration has not yet been determined.

***

### isNumeric

```ts
readonly isNumeric: boolean
```

Indicates whether the time can participate in numeric calculations.
Arithmetic and comparison operations should only be performed when this value is `true`.

***

### hasBeenRounded

```ts
readonly hasBeenRounded: boolean
```

Indicates whether the time has undergone rounding during construction or scale conversion.
This is useful when validating frame- or sample-accurate timelines.

***

## Time Conversion

### convertScale

```ts
convertScale(newTimescale: number, method: MediaTimeRoundingMethod): MediaTime
```

Converts the time to a new timescale using the specified rounding method.

**Typical use cases:**

- Aligning video frame timing (e.g. 600, 90000)
- Aligning audio sample timing (e.g. 44100, 48000)
- Avoiding precision errors caused by mixed timescales

***

## Accessing Time Values

### getSeconds

```ts
getSeconds(): number
```

Returns the time expressed in seconds as a floating-point value.
Semantically equivalent to reading `secondes`, but clearer in intent.

***

## Time Arithmetic

### plus / minus

```ts
plus(other: MediaItem): MediaItem
minus(other: MediaItem): MediaItem
```

Performs time addition or subtraction and returns a new `MediaTime`.

- Both operands must be numeric
- The original instances are not modified
- The result follows the internal time base rules

***

## Time Comparison

```ts
lt(other: MediaItem): boolean
gt(other: MediaItem): boolean
lte(other: MediaItem): boolean
gte(other: MediaItem): boolean
eq(other: MediaItem): boolean
neq(other: MediaItem): boolean
```

Compares two time values.

- Supports strict ordering and equality checks
- Produces deterministic results even for non-numeric times
- Recommended for timeline sorting, trimming, and boundary checks

***

## Static Constructors

### make

```ts
static make(options: {
  value: number
  timescale: number
} | {
  seconds: number
  preferredTimescale: number
}): MediaTime
```

Creates a `MediaTime` instance.

#### Using value + timescale

```ts
MediaTime.make({
  value: 300,
  timescale: 600
})
```

Best suited for low-level or precision-critical scenarios.

***

#### Using seconds + preferredTimescale

```ts
MediaTime.make({
  seconds: 5,
  preferredTimescale: 600
})
```

Recommended for most scripting-level use cases where seconds are the primary unit.

***

### zero

```ts
static zero(): MediaTime
```

Returns a `MediaTime` representing **0 seconds**.

***

### invalid

```ts
static invalid(): MediaTime
```

Returns an invalid time value.
Useful for explicitly representing errors or unavailable timing information.

***

### indefinite

```ts
static indefinite(): MediaTime
```

Returns an indefinite time value.
Typically used when a media asset’s duration is not yet known.

***

### positiveInfinity / negativeInfinity

```ts
static positiveInfinity(): MediaTime
static negativeInfinity(): MediaTime
```

Returns positive or negative infinite time values.
These are mainly intended for internal timeline boundary handling and are not recommended for general scripting logic.

***

## Usage Guidelines and Best Practices

- Avoid using floating-point seconds directly for timeline calculations; prefer `MediaTime`
- Explicitly convert timescales when mixing audio and video sources
- Check `isNumeric` before performing arithmetic or comparisons
- Use consistent timescales when constructing `TimeRange` or `at` values

***

## Typical Usage in MediaComposer

- Placing audio or video clips on the timeline (`AudioClip.at`)
- Defining trimming ranges (`TimeRange`)
- Calculating precise export durations
- Driving fades, alignment, looping, and synchronization behavior



---
url: /guide/Device Capabilities/MediaComposer/Quick Start.md
---

# Quick Start

`MediaComposer` is used in Scripting to **compose video, image, and audio timelines and export a final media file**.
It provides a stable and precise timeline model that supports video clips, image clips, audio overlays, fades, audio ducking, and flexible export configuration.

This module is suitable for:

- Mixing videos and images into a single output
- Adding background music, voice-over, or sound effects
- Generating videos from image sequences
- Automated and script-driven media production

***

## Design Overview

MediaComposer consists of three core layers:

1. **Time Model**
   Based on `MediaTime` and `TimeRange` for precise time representation

2. **Timeline Model**

   - `VideoItem[]`: visual timeline (videos or images, sequential)
   - `AudioClip[]`: audio timeline (positioned or sequential)

3. **Export System**
   A unified `composeAndExport` API for rendering and exporting

***

## Timeline Structure

```ts
timeline: {
  videoItems: VideoItem[]
  audioClips: AudioClip[]
}
```

- **videoItems**
  Defines the visual timeline. Video and image items are concatenated strictly in array order.
- **audioClips**
  Defines the audio timeline. Clips may be explicitly positioned or appended sequentially.

The final exported duration is determined by the **videoItems timeline**.

***

## VideoItem

```ts
type VideoItem = XOR<VideoClip, ImageClip>
```

A `VideoItem` represents a single visual segment in the timeline.
It can be either a **video clip** or an **image clip**, but never both.

***

## VideoClip

```ts
type VideoClip = {
  videoPath: string
  sourceTimeRange?: TimeRange | null
  keepOriginalAudio?: boolean
  fade?: FadeConfig | null
}
```

### videoPath

- Path to the video file
- Local video files are supported

***

### sourceTimeRange

```ts
sourceTimeRange?: TimeRange | null
```

- Specifies the portion of the source video to use
- Defaults to the entire video when omitted

**Common use cases:**

- Trimming a video
- Extracting a specific segment as material

***

### keepOriginalAudio

```ts
keepOriginalAudio?: boolean
```

- Whether to keep the original audio from the video
- Default: `false`

**Notes:**

- When `true`, the video’s original audio participates in the final mix
- External `audioClips` may still be used simultaneously
- Ducking behavior is controlled by `ExportOptions.ducking`

***

### fade

```ts
fade?: FadeConfig | null
```

- Per-clip fade-in / fade-out configuration
- Overrides the global video fade when provided

***

## ImageClip

```ts
type ImageClip = {
  imagePath: string
  duration: MediaTime
  contentMode?: "fit" | "crop"
  backgroundColor?: Color
  fade?: FadeConfig | null
}
```

`ImageClip` allows a still image to appear as a timed segment within the video timeline.

***

### imagePath

- Path to the image file
- Common image formats are supported (JPEG, PNG, HEIC, etc.)

***

### duration

```ts
duration: MediaTime
```

- The display duration of the image clip in the video
- This field is required

***

### contentMode

```ts
contentMode?: "fit" | "crop"
```

- Controls how the image is scaled to the render size
- Default: `fit`

Behavior:

- `fit`: Entire image is visible; letterboxing may occur
- `crop`: Image fills the frame; excess is cropped

***

### backgroundColor

```ts
backgroundColor?: Color
```

- Background color for areas not covered by the image
- Commonly used together with `fit` mode

***

### fade

```ts
fade?: FadeConfig | null
```

- Fade-in / fade-out configuration for the image clip
- Behaves the same as fades for video clips

***

## AudioClip

```ts
type AudioClip = {
  path: string
  sourceTimeRange?: TimeRange | null
  at?: MediaTime
  volume?: number
  fade?: FadeConfig | null
  loopToFitVideoDuration?: boolean
}
```

`AudioClip` is used to add background music, narration, or sound effects to the final video.

***

### path

- Path to the audio file

***

### sourceTimeRange

- Specifies the portion of the audio to use
- Defaults to the entire audio file

***

### at

```ts
at?: MediaTime
```

- Explicit placement time on the final timeline
- When omitted, audio clips are appended sequentially

***

### volume

```ts
volume?: number
```

- Per-clip gain (0...1)
- Default: `1`

***

### fade

- Fade-in / fade-out configuration for the audio clip

***

### loopToFitVideoDuration

```ts
loopToFitVideoDuration?: boolean
```

- Whether the audio should loop to match the total video duration
- Commonly used for background music

***

## FadeConfig

```ts
type FadeConfig = {
  fadeInSeconds?: number
  fadeOutSeconds?: number
}
```

- Duration is expressed in seconds
- Applicable to video, image, and audio clips
- Defaults to 0 when omitted

***

## ExportOptions

```ts
type ExportOptions = {
  renderSize?: Size
  frameRate?: number
  scaleMode?: VideoScaleMode
  globalVideoFade?: FadeConfig | null
  externalAudioBaseVolume?: number
  ducking?: DuckingConfig
  presetName?: ExportPreset
  outputFileType?: ExportFileType
  colorSpacePolicy?: ColorSpacePolicy
}
```

### Common options

- **renderSize**
  Output resolution, default is 1080×1920

- **frameRate**
  Rendering frame rate, default is 30

- **globalVideoFade**
  Global fade applied to all visual clips unless overridden

- **ducking**
  Automatically lowers external audio volume when original video audio exists

- **presetName / outputFileType**
  Control encoding quality and output format

- **colorSpacePolicy**
  Color space conversion policy, default is `forceSDR`, other options are `keepSource`.

***

## composeAndExport

```ts
function composeAndExport(options: {
  exportPath: string
  timeline: {
    videoItems: VideoItem[]
    audioClips: AudioClip[]
  }
  exportOptions?: ExportOptions
  overwrite?: boolean
}): Promise<{
  exportPath: string
  duration: MediaTime
}>
```

### Parameters

- **exportPath**
  Output file path

- **timeline.videoItems**
  Visual timeline (videos and images, in sequence)

- **timeline.audioClips**
  Audio timeline (positioned or sequential)

- **exportOptions**
  Optional export configuration

- **overwrite**
  Whether to overwrite an existing file (default: `true`)

***

### Return Value

```ts
{
  exportPath: string
  duration: MediaTime
}
```

- **exportPath**: final output path
- **duration**: total duration of the exported video (derived from `videoItems`)

***

## Usage Guidelines and Best Practices

- Always use `MediaTime` for time values; avoid raw floating-point seconds
- `ImageClip.duration` must always be explicitly specified
- Audio and visual timelines are independent but mixed in the final output
- For complex projects, use a consistent timescale (e.g. 600)
- Background music typically uses `loopToFitVideoDuration`

***

## Typical Use Cases

- Mixed image and video composition
- Adding background music or narration to videos
- Automated video generation
- Script-driven content creation pipelines



---
url: /guide/Device Capabilities/MediaLibrary.md
---

# MediaLibrary

The `MediaLibrary` module provides read-only access to the user's local media library, allowing scripts to query songs, albums, artists, and playlists, and retrieve artwork.

Important notes:

- The user must grant permission to access the media library.
- Only items available in the device media library are returned (including locally synced content, iTunes synced content, and downloaded Apple Music tracks).
- All returned data structures are read-only and cannot modify the system library.

***

## Data Models

### Item

Represents a single song.

```ts
type Item = {
  title: string
  persistentID: string
  artist?: string
  albumTitle?: string
  albumArtist?: string
  genre?: string
  composer?: string
  albumTrackNumber?: number
  albumTrackCount?: number
  discNumber?: number
  discCount?: number
  playbackDuration?: number
  playbackStoreID?: string
  isCloudItem?: boolean
  hasProtectedAsset?: boolean
}
```

Field descriptions:

- `title`: Song title
- `persistentID`: Unique local media library identifier (used for playback and artwork retrieval)
- `artist`: Performing artist
- `albumTitle`: Album name
- `albumArtist`: Album artist
- `genre`: Genre
- `composer`: Composer
- `albumTrackNumber`: Track number within the album
- `albumTrackCount`: Total track count of the album
- `discNumber`: Disc number
- `discCount`: Total disc count
- `playbackDuration`: Duration in seconds
- `playbackStoreID`: Apple Music Store ID (if available)
- `isCloudItem`: Indicates whether the item is cloud-based
- `hasProtectedAsset`: Indicates DRM-protected content

***

### Playlist

Represents a playlist.

```ts
type Playlist = {
  persistentID: string
  name: string
  trackCount: number
}
```

Field descriptions:

- `persistentID`: Unique playlist identifier
- `name`: Playlist name
- `trackCount`: Number of tracks

***

### Album

Represents an album.

```ts
type Album = {
  title: string
  artist?: string
  persistentID?: string
  trackCount?: number
}
```

Field descriptions:

- `title`: Album title
- `artist`: Album artist
- `persistentID`: Album identifier (may be unavailable in some cases)
- `trackCount`: Number of tracks

***

## Query Options

### SongQueryOptions

```ts
type SongQueryOptions = {
  limit?: number
  sortBy?:
    | "title"
    | "artist"
    | "albumTitle"
    | "playbackDuration"
    | "albumTrackNumber"
  ascending?: boolean
}
```

Description:

- `limit`: Maximum number of results
- `sortBy`: Field used for sorting
- `ascending`: Sort order (default is descending if not specified)

***

### AlbumQueryOptions

```ts
type AlbumQueryOptions = {
  limit?: number
  sortBy?: "title" | "artist" | "trackCount"
  ascending?: boolean
}
```

***

### PlaylistQueryOptions

```ts
type PlaylistQueryOptions = {
  limit?: number
  sortBy?: "name" | "trackCount"
  ascending?: boolean
}
```

***

### ArtistQueryOptions

```ts
type ArtistQueryOptions = {
  limit?: number
  ascending?: boolean
}
```

***

### SongFilter

Used to filter song queries.

```ts
type SongFilter = {
  title?: string
  artist?: string
  albumTitle?: string
  genre?: string
  composer?: string
  persistentID?: string
}
```

Notes:

- Supports exact match filtering.
- Multiple fields may be combined.

***

## API Methods

### getSongs

Query songs.

```ts
function getSongs(
  filter?: SongFilter,
  options?: SongQueryOptions
): Promise<Item[]>
```

Example:

```ts
const songs = await MediaLibrary.getSongs(
  { artist: "Taylor Swift" },
  { sortBy: "title", ascending: true, limit: 20 }
)

console.log(songs)
```

***

### getSongByPersistentID

Retrieve a single song by `persistentID`.

```ts
function getSongByPersistentID(
  persistentID: string
): Promise<Item | null>
```

Example:

```ts
const song = await MediaLibrary.getSongByPersistentID("123456789")

if (song) {
  console.log(song.title)
}
```

***

### getAlbums

Retrieve albums.

```ts
function getAlbums(
  options?: AlbumQueryOptions
): Promise<Album[]>
```

Example:

```ts
const albums = await MediaLibrary.getAlbums({
  sortBy: "title",
  ascending: true
})
```

***

### getAlbumSongs

Retrieve songs within a specific album.

```ts
function getAlbumSongs(
  albumTitle: string,
  options?: SongQueryOptions
): Promise<Item[]>
```

Example:

```ts
const tracks = await MediaLibrary.getAlbumSongs("1989", {
  sortBy: "albumTrackNumber",
  ascending: true
})
```

Notes:

- Matching is based on album title.
- If multiple albums share the same name, results may include tracks from all matching albums.

***

### getArtists

Retrieve artist names.

```ts
function getArtists(
  options?: ArtistQueryOptions
): Promise<string[]>
```

Example:

```ts
const artists = await MediaLibrary.getArtists({ limit: 50 })
```

***

### getArtistSongs

Retrieve songs by a specific artist.

```ts
function getArtistSongs(
  artist: string,
  options?: SongQueryOptions
): Promise<Item[]>
```

Example:

```ts
const songs = await MediaLibrary.getArtistSongs("Adele", {
  sortBy: "playbackDuration",
  ascending: false
})
```

***

### getPlaylists

Retrieve playlists.

```ts
function getPlaylists(
  options?: PlaylistQueryOptions
): Promise<Playlist[]>
```

Example:

```ts
const playlists = await MediaLibrary.getPlaylists({
  sortBy: "trackCount",
  ascending: false
})
```

***

### getPlaylistSongs

Retrieve songs within a playlist.

```ts
function getPlaylistSongs(
  playlistPersistentID: string,
  options?: SongQueryOptions
): Promise<Item[]>
```

Example:

```ts
const songs = await MediaLibrary.getPlaylistSongs("9988776655", {
  sortBy: "title"
})
```

***

### getArtwork

Retrieve artwork for a song.

```ts
function getArtwork(
  persistentID: string,
  size?: {
    width: number
    height: number
  }
): Promise<UIImage | null>
```

Description:

- Returns a `UIImage`.
- `size` specifies the desired render dimensions.
- Returns `null` if artwork is unavailable.

Example:

```ts
const image = await MediaLibrary.getArtwork("123456789", {
  width: 300,
  height: 300
})

if (image) {
  console.log("Artwork loaded")
}
```

***

## Best Practices

- Use `limit` to control result size for large queries.
- For playback workflows, store `persistentID` instead of entire item objects.
- Load artwork on demand rather than preloading in bulk.
- To play songs, combine this module with `SystemMusicPlayer.setQueueByPersistentIDs`.



---
url: /guide/Device Capabilities/MediaPlayer.md
---

# MediaPlayer

The `MediaPlayer` API allows you to interact with the Now Playing Center, manage Now Playing Info, and respond to remote control events. Below is a comprehensive guide on its usage, including best practices and examples.

***

## Getting Started

The `MediaPlayer` API provides control over media playback information and remote command handling. To get started:

1. Set the `nowPlayingInfo` to display current media information.
2. Configure available commands using `setAvailableCommands()`.
3. Register a `commandHandler` to respond to remote events.

```typescript
MediaPlayer.nowPlayingInfo = {
  title: "Song Title",
  artist: "Artist Name",
  playbackRate: 1.0,
  elapsedPlaybackTime: 30,
  playbackDuration: 240
}

MediaPlayer.setAvailableCommands(["play", "pause", "nextTrack", "previousTrack"])

MediaPlayer.commandHandler = (command, event) => {
  console.log(`Command received: ${command}`)
}
```

***

## API Reference

### NowPlayingInfo

The `nowPlayingInfo` object displays metadata about the currently playing media. Set it to `null` to clear the Now Playing Info Center.

**Properties:**

- **`title`**: `string` (Required)
  - The title of the media item.
- **`artist`**: `string` (Optional)
  - The artist or performer of the media item.
- **`albumTitle`**: `string` (Optional)
  - The album title of the media item.
- **`artwork`**: `UIImage` (Optional)
  - An image representing the media item.
- **`mediaType`**: `MediaType` (Optional)
  - Defaults to `audio`.
- **`playbackRate`**: `number` (Optional)
  - Defaults to `0`. Indicates the current playback rate.
- **`elapsedPlaybackTime`**: `DurationInSeconds` (Optional)
  - Defaults to `0`. The current playback time.
- **`playbackDuration`**: `DurationInSeconds` (Optional)
  - Defaults to `0`. The total duration of the media.
- **`isLiveStream`**: `boolean` (Optional)
  - Defaults to `false`. Set to `true` for live streams (e.g., radio broadcasts) so the system hides the progress bar in the Lock Screen and Control Center Now Playing UI.

### Playback State

The `playbackState` property indicates the app's current playback state:

- **`unknown`**: Default state when playback status is undefined.
- **`playing`**: Media is actively playing.
- **`paused`**: Media playback is paused.
- **`stopped`**: Playback has stopped.
- **`interrupted`**: Playback is interrupted by an external event.

```typescript
if (MediaPlayer.playbackState === MediaPlayerPlaybackState.playing) {
    console.log("Media is currently playing")
}
```

### Commands and Event Handlers

#### `setAvailableCommands(commands: MediaPlayerRemoteCommand[])`

Specifies which remote commands are enabled for user interaction.

**Example:**

```typescript
MediaPlayer.setAvailableCommands(["play", "pause", "stop", "nextTrack"])
```

#### `commandHandler`

A callback to handle remote commands. Register this function to process commands like `play`, `pause`, or `seekBackward`.

**Example:**

```typescript
MediaPlayer.commandHandler = (command, event) => {
  switch (command) {
    case "play":
      console.log("Play command received")
      break
    case "pause":
      console.log("Pause command received")
      break
    default:
      console.log(`Command not handled: ${command}`)
  }
}
```

**Supported Commands:**

- `play`, `pause`, `stop`, `nextTrack`, `previousTrack`
- `seekBackward`, `seekForward`, `skipBackward`, `skipForward`
- `rating`, `like`, `dislike`, `bookmark`
- `changeRepeatMode`, `changeShuffleMode`
- `enableLanguageOption`, `disableLanguageOption`

***

## Common Use Cases

### Display Now Playing Info

```typescript
MediaPlayer.nowPlayingInfo = {
  title: "Podcast Episode",
  artist: "Podcast Host",
  elapsedPlaybackTime: 120,
  playbackDuration: 1800,
  playbackRate: 1.0
}
```

### Respond to Playback Commands

```typescript
MediaPlayer.setAvailableCommands(["play", "pause", "stop"])

MediaPlayer.commandHandler = (command, event) => {
  if (command === "play") {
    console.log("Start playback")
  } else if (command === "pause") {
    console.log("Pause playback")
  }
}
```

### Handle Custom Events

```typescript
MediaPlayer.commandHandler = (command, event) => {
  if (command === "seekForward") {
    const seekEvent = event as MediaPlayerSeekCommandEvent
    console.log(`Seek Event Type: ${seekEvent.type}`)
  }
}
```

***

## Best Practices

1. **Keep Metadata Up-to-Date:** Update `nowPlayingInfo` as playback changes.
2. **Handle All Relevant Commands:** Ensure user interactions like skipping or seeking are supported.
3. **Resource Management:** Clear `nowPlayingInfo` when playback stops to avoid stale information.
4. **Test with External Devices:** Use remote controls like headphones or car systems to validate command handling.
5. **Provide Feedback:** Inform users of successful or failed actions in response to commands.

***

## Full Example

Below is a complete implementation of `MediaPlayer`:

```typescript
// Set Now Playing Info
MediaPlayer.nowPlayingInfo = {
  title: "Song Title",
  artist: "Artist Name",
  albumTitle: "Album Name",
  playbackRate: 1.0,
  elapsedPlaybackTime: 0,
  playbackDuration: 300
}

// Enable Commands
MediaPlayer.setAvailableCommands(["play", "pause", "nextTrack", "previousTrack", "seekForward", "seekBackward"])

// Handle Commands
MediaPlayer.commandHandler = (command, event) => {
  switch (command) {
    case "play":
      console.log("Playing media")
      break
    case "pause":
      console.log("Pausing media")
      break
    case "nextTrack":
      console.log("Skipping to next track")
      break
    case "seekForward":
      const seekEvent = event as MediaPlayerSeekCommandEvent
      console.log(`Seek Event: ${seekEvent.type}`)
      break
    default:
      console.log(`Unhandled command: ${command}`)
  }
}
```



---
url: /guide/Device Capabilities/NaturalLanguage/Contextual Embedding.md
---

# Contextual Embedding

`ContextualEmbedding` provides transformer-style sequence embeddings: each token in a sentence gets a vector that depends on its surrounding context (unlike `Embedding`, where a word always maps to the same vector).

***

## Static factories

### `ContextualEmbedding.forLanguage(language): ContextualEmbedding | null`

Most recent embedding suitable for `language`, or `null` if none.

### `ContextualEmbedding.forScript(script): ContextualEmbedding | null`

Most recent embedding for an ISO 15924 script (`"Latn"`, `"Hans"`, `"Cyrl"`, ...).

### `ContextualEmbedding.forModelIdentifier(modelIdentifier): ContextualEmbedding | null`

Locate an embedding by its model identifier. Useful when you want inference to use exactly the same model as a previous training run — capture the `modelIdentifier` then, reuse it here.

```ts
const emb = NaturalLanguage.ContextualEmbedding.forLanguage("en")
```

***

## Properties

| Property                | Type         | Description                                                    |
| ----------------------- | ------------ | -------------------------------------------------------------- |
| `modelIdentifier`       | `string`     | Stable identifier for this model revision.                     |
| `languages`             | `Language[]` | Languages the model covers.                                    |
| `scripts`               | `Script[]`   | Scripts the model covers.                                      |
| `revision`              | `number`     | OS-published revision number.                                  |
| `dimension`             | `number`     | Length of each token vector.                                   |
| `maximumSequenceLength` | `number`     | Maximum number of token vectors the model will emit per input. |
| `hasAvailableAssets`    | `boolean`    | Whether the model assets are already on-device.                |

***

## Methods

### `prepare(): Promise<void>`

Request that the model's assets be loaded onto the device, then resolve. The assets are downloaded on demand the first time, so the first call may take noticeably longer than subsequent ones. `embeddingResult()` before `prepare()` resolves will typically fail.

> **Simulator limitation:** the simulator sandbox can't write to `/var/db/com.apple.naturallanguaged/...`, so `prepare()` always rejects there. Use a real device.

### `embeddingResult(text, language?): Promise<ContextualEmbeddingResult>`

Compute contextual embeddings for `text`. Each token in the result has the model's own tokenization (typically wordpieces), its UTF-16 range, and a vector of length `dimension`.

```ts
{
  sequenceLength: number
  tokens: Array<{
    text: string
    range: { location: number, length: number }
    vector: number[]
  }>
}
```

***

## Example

```ts
const emb = NaturalLanguage.ContextualEmbedding.forLanguage("en")
if (!emb) return

await emb.prepare()

const r = await emb.embeddingResult("The bank charged a fee.", "en")
console.log(r.sequenceLength)       // number of token vectors
console.log(r.tokens[0].vector.length === emb.dimension)   // true

// Cosine similarity between two tokens in the same sentence:
const a = r.tokens[1].vector
const b = r.tokens[2].vector
let dot = 0, na = 0, nb = 0
for (let i = 0; i < a.length; i++) { dot += a[i]*b[i]; na += a[i]*a[i]; nb += b[i]*b[i] }
const cos = dot / (Math.sqrt(na) * Math.sqrt(nb))
```

***

## Notes

- Unlike `Embedding.distance`, contextual embeddings are sentence-aware: `"bank"` in "river bank" and "bank account" yield different vectors.
- The model assets are shared across all apps on the device; `prepare()` is cheap after the first download.



---
url: /guide/Device Capabilities/NaturalLanguage/Embedding.md
---

# Embedding

`Embedding` exposes Apple's built-in **word** and **sentence** embeddings: dense vectors used for similarity, nearest-neighbor search, and distance computation.

There is no public constructor — get an instance from one of the static factories.

***

## Static factories

### `Embedding.wordEmbedding(language, revision?): Embedding | null`

The built-in word embedding for `language`. Returns `null` if no embedding is available on this OS for that language.

### `Embedding.sentenceEmbedding(language, revision?): Embedding | null`

The built-in sentence embedding for `language` (iOS 14+). Returns `null` on iOS 13 or when no sentence embedding is available.

```ts
const wordEmb = NaturalLanguage.Embedding.wordEmbedding("en")
const sentEmb = NaturalLanguage.Embedding.sentenceEmbedding("en")
```

***

## Properties

| Property         | Type               | Description                                             |
| ---------------- | ------------------ | ------------------------------------------------------- |
| `language`       | `Language \| null` | Language of the embedding.                              |
| `dimension`      | `number`           | Length of each vector.                                  |
| `vocabularySize` | `number`           | Number of distinct tokens in the embedding.             |
| `revision`       | `number`           | OS-published revision number; useful for cache busting. |

***

## Lookup methods

### `contains(token: string): boolean`

Whether `token` is in the embedding's vocabulary.

### `vector(token: string): number[] | null`

Vector for `token` (length = `dimension`), or `null` if the token isn't in vocabulary.

### `distance(first, second, type?): number | null`

Cosine distance between two tokens (`[0, 2]`; smaller is closer).
Returns `null` if either token isn't in vocabulary — use `contains` to disambiguate "no signal" from "very far apart".

### `neighbors(token, maximumCount, type?): { token, distance }[]`

Up to `maximumCount` nearest neighbors of `token`, sorted by ascending distance. Returns `[]` if `token` isn't in vocabulary.

***

## Examples

### Word similarity

```ts
const emb = NaturalLanguage.Embedding.wordEmbedding("en")
if (emb) {
  console.log(emb.distance("cat", "kitten"))     // small — semantically close
  console.log(emb.distance("cat", "airplane"))   // larger
}
```

### Nearest neighbors

```ts
const emb = NaturalLanguage.Embedding.wordEmbedding("en")
if (emb) {
  const nbs = emb.neighbors("happy", 5)
  for (const { token, distance } of nbs) {
    console.log(`${token}\t${distance.toFixed(3)}`)
  }
  // joyful  0.341
  // glad    0.402
  // ...
}
```

### Raw vector

```ts
const v = emb?.vector("hello")
if (v) {
  // dot product with another vector ...
}
```

***

## Notes

- `wordEmbedding("en")` is the most reliably available embedding. Other languages may return `null` depending on OS revision.
- `distanceType` currently only supports `"cosine"`; the parameter is reserved for future metrics.



---
url: /guide/Device Capabilities/NaturalLanguage/Gazetteer.md
---

# Gazetteer

`Gazetteer` is a user-supplied dictionary mapping **labels** to **terms**. Attach one to a `Tagger` to make the tagger recognize domain-specific vocabulary — product names, code identifiers, internal jargon — that the system model wouldn't normally catch.

***

## Construction

```ts
const gazetteer = new NaturalLanguage.Gazetteer({
  product: ["Scripting", "Pro"],
  company: ["Acme", "Acme Corp"]
}, "en")
```

- `dictionary`: `{ label: [term, term, ...] }`. Each label can have many terms; the gazetteer maps any matching term back to that label.
- `language?: Language` — optional hint when terms are language-specific.

The constructor **throws** if the dictionary is malformed (e.g. empty terms or duplicate terms under different labels).

***

## Properties

| Property   | Type               | Description                                                                                    |
| ---------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `language` | `Language \| null` | Language hint passed to the constructor (may not be retained for dictionary-built gazetteers). |

***

## Methods

### `label(term: string): string | null`

Returns the label `term` maps to, or `null` for a miss.

```ts
gazetteer.label("Scripting")   // → "product"
gazetteer.label("Acme")        // → "company"
gazetteer.label("Banana")      // → null
```

***

## Using a gazetteer with `Tagger`

```ts
const gz = new NaturalLanguage.Gazetteer({
  product: ["Scripting"],
  company: ["Acme"]
}, "en")

const tagger = new NaturalLanguage.Tagger(["nameType"])
tagger.setGazetteers([gz], "nameType")
tagger.setText("Acme ships the Scripting app.")

const tags = tagger.tags(null, "word", "nameType", {
  omitWhitespace: true,
  omitPunctuation: true
})
// → tags include { tag: "company", ... } and { tag: "product", ... },
//   instead of just OrganizationName / nil.
```

Gazetteer hits **override** the system model for that scheme. If the tagger is constructed with `"nameType"`, then `setGazetteers([gz], "nameType")` will replace standard `OrganizationName` / `PersonalName` labels with your custom labels for the words that match.

***

## Notes

- This is the lightweight, in-script way to extend tagging. The heavier (and out of scope here) alternative is `NLModel`, which trains a full classifier from labeled data.
- Multiple gazetteers can be attached to the same scheme via `setGazetteers([gz1, gz2, ...], scheme)`.



---
url: /guide/Device Capabilities/NaturalLanguage/Language Recognition.md
---

# Language Recognition

Detect the dominant language of a string or rank candidate languages by confidence.

***

## Functions

### `NaturalLanguage.dominantLanguage(text: string): Language | null`

Return the single most likely language for `text`. Returns `null` when the text is too short or ambiguous to classify.

```ts
NaturalLanguage.dominantLanguage("Bonjour le monde")   // → "fr"
NaturalLanguage.dominantLanguage("今天天气很好")       // → "zh-Hans"
NaturalLanguage.dominantLanguage("")                   // → null
```

***

### `NaturalLanguage.languageHypotheses(text, options?): LanguageHypothesis[]`

Return up to `maximumCount` candidate languages sorted by confidence (descending).

- `options.maximumCount?: number` — defaults to `3`.
- `options.constraints?: Language[]` — soft preference; recognizer favors candidates in this set but is not strictly limited to them.
- `options.hints?: { [language: string]: number }` — prior probabilities (BCP-47 → 0...1).

```ts
const ranked = NaturalLanguage.languageHypotheses("Buenos días", {
  maximumCount: 3,
  constraints: ["es", "pt", "it"],
  hints: { es: 0.8 }
})
// → [{ language: "es", confidence: 0.92 }, { language: "pt", confidence: 0.05 }, ...]
```

***

## Notes

- Language identification is offline and extremely fast — feel free to call it on every keystroke if needed.
- For very short input (one or two words), the recognizer may return `null` or low confidence. Provide more context when possible.



---
url: /guide/Device Capabilities/NaturalLanguage/Tagger.md
---

# Tagger

`Tagger` annotates text with part-of-speech, lemma, language/script, named entities, sentiment, and custom labels from gazetteers.

***

## Construction

```ts
const tagger = new NaturalLanguage.Tagger([
  "lexicalClass",   // part of speech
  "nameType",       // person / place / organization
  "lemma",
  "sentimentScore"
])
tagger.setText("Tim Cook visited Beijing yesterday. I love this city!")
```

Pass only the schemes you actually need — they control which analyses the tagger performs.

***

## Tag schemes

```ts
type TagScheme =
  | "tokenType"              // word / punctuation / whitespace / other
  | "lexicalClass"           // Noun, Verb, Adjective, ...
  | "nameType"               // PersonalName, PlaceName, OrganizationName
  | "nameTypeOrLexicalClass"
  | "lemma"
  | "language"
  | "script"
  | "sentimentScore"         // numeric string in [-1, 1]
```

***

## Methods

### `setText(text: string): void`

Attach text. All subsequent queries operate on it.

### `setLanguage(language: Language, range?: StringRange): void`

Override the language hint for the whole text or a sub-range.

### `tag(at, unit, scheme): { tag: string | null, range } | null`

Look up the tag at a single UTF-16 offset.

### `tags(range, unit, scheme, options?): { tag: string | null, range }[]`

Enumerate all tags in a range. Pass `null` as `range` to scan the whole text.

`options` (`TaggerOptions`) lets you skip tokens you don't care about:

- `omitWords` / `omitPunctuation` / `omitWhitespace` / `omitOther`
- `joinNames` (treat `"John Smith"` as a single token)
- `joinContractions` (treat `"don't"` as a single token)

### `tagHypotheses(at, unit, scheme, maximumCount): { hypotheses, range }`

Top-K candidate tags at a position, as `{ "Noun": 0.7, "Verb": 0.2, ... }`.

### `enumerateNamedEntities(range?, options?): NamedEntityResult[]`

Convenience over `tags(..., "word", "nameType", ...)`: returns person / place / organization mentions only, with `joinNames` enabled so multi-token names appear as one entity.

### `sentimentScore(range?): number | null`

Score sentiment in the range `[-1, 1]` (more negative → more positive). Requires the tagger to have been constructed with `"sentimentScore"`. Scoring starts from `range.location` at paragraph granularity.

### `setGazetteers(gazetteers, scheme): void`

Attach one or more `Gazetteer` to a scheme. Gazetteer hits take precedence over the system model for that scheme. See `Gazetteer`.

***

## Examples

### Named entities

```ts
const tagger = new NaturalLanguage.Tagger(["nameType"])
tagger.setText("Tim Cook visited Beijing yesterday.")
console.log(tagger.enumerateNamedEntities())
// [
//   { entity: "personalName", text: "Tim Cook", range: { location: 0,  length: 8 } },
//   { entity: "placeName",    text: "Beijing",  range: { location: 17, length: 7 } }
// ]
```

### Part-of-speech

```ts
const tagger = new NaturalLanguage.Tagger(["lexicalClass"])
tagger.setText("Apple released new products.")
const tags = tagger.tags(null, "word", "lexicalClass", {
  omitWhitespace: true,
  omitPunctuation: true
})
// → [ { tag: "Noun", range }, { tag: "Verb", range }, { tag: "Adjective", range }, { tag: "Noun", range } ]
```

### Sentiment

```ts
const tagger = new NaturalLanguage.Tagger(["sentimentScore"])
tagger.setText("I love this beautiful sunny day!")
const score = tagger.sentimentScore()   // → ~0.9 (positive)
```

### Tag hypotheses

```ts
const r = tagger.tagHypotheses(0, "word", "lexicalClass", 3)
// {
//   hypotheses: { "Noun": 0.72, "ProperNoun": 0.18, "Adjective": 0.05 },
//   range: { location: 0, length: 5 }
// }
```



---
url: /guide/Device Capabilities/NaturalLanguage/Tokenizer.md
---

# Tokenizer

Split text into word, sentence, paragraph, or document tokens.

***

## Function

### `NaturalLanguage.tokenize(text, options?): TokenRange[]`

Walk `text` at the requested granularity and return an ordered list of tokens.

- `options.unit?: "word" | "sentence" | "paragraph" | "document"` — defaults to `"word"`.
- `options.language?: Language` — optional hint that helps the tokenizer pick the right model for languages without explicit word boundaries (e.g. Chinese, Japanese, Thai).

Each token is:

```ts
{
  text: string                 // the substring
  range: { location, length }  // UTF-16 offset
  attributes: {                // present only when relevant
    emoji?: boolean
    numeric?: boolean
    symbolic?: boolean
  }
}
```

***

## Examples

```ts
// Word tokens
const words = NaturalLanguage.tokenize("Hello, world! 🎉", { unit: "word" })
// → ["Hello", "world", "🎉"] (with attributes.emoji on the last one)

// Sentence tokens
const sentences = NaturalLanguage.tokenize(
  "First sentence. Second one!",
  { unit: "sentence" }
)
// → 2 tokens

// Chinese: pass a language hint to help word segmentation
const cn = NaturalLanguage.tokenize("苹果发布了新产品", {
  unit: "word",
  language: "zh-Hans"
})
```

***

## Notes

- `range.location` / `range.length` are UTF-16 offsets, matching native JS string indexing. `text.substring(range.location, range.location + range.length)` always returns `token.text`.
- The tokenizer does not filter punctuation or whitespace — if you only want substantive words, filter the result yourself or use `Tagger.tags(..., { omitPunctuation: true, omitWhitespace: true })`.



---
url: /guide/Device Capabilities/Notification/index.md
---

# Notification

The `Notification` module in the **Scripting** app allows you to schedule, manage, and display local notifications with advanced trigger types, interactive actions, and rich UI capabilities.

***

## Table of Contents

1. [Scheduling Notifications](#scheduling-notifications)
2. [Notification Triggers](#notification-triggers)

   - [TimeIntervalNotificationTrigger](#timeintervalnotificationtrigger)
   - [CalendarNotificationTrigger](#calendarnotificationtrigger)
   - [LocationNotificationTrigger](#locationnotificationtrigger)
3. [Notification Actions](#notification-actions)
4. [Rich Notifications with Custom UI](#rich-notifications-with-custom-ui)
5. [Managing Notifications](#managing-notifications)
6. [NotificationInfo and Request Structure](#notificationinfo-and-request-structure)
7. [Comprehensive Example](#comprehensive-example)

***

## Scheduling Notifications

Use `Notification.schedule` to schedule a local notification. It supports content, triggers, tap behaviors, action buttons, rich UI, and delivery configurations:

```ts
await Notification.schedule({
  title: "Reminder",
  body: "Time to stand up!",
  trigger: new TimeIntervalNotificationTrigger({
    timeInterval: 1800,
    repeats: true
  }),
  actions: [
    {
      title: "OK",
      url: Script.createRunURLScheme("My Script", { acknowledged: true })
    }
  ],
  tapAction: {
    type: "runScript",
    scriptName: "Acknowledge Script"
  },
  customUI: false
})
```

### Parameters

| Name                | Type                                                                                                          | Description                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `title`             | `string`                                                                                                      | Required. Notification title.                                                    |
| `subtitle`          | `string?`                                                                                                     | Optional. Additional context.                                                    |
| `body`              | `string?`                                                                                                     | Optional. Main content text.                                                     |
| `badge`             | `number?`                                                                                                     | Optional. App icon badge count.                                                  |
| `iconImageData`     | `Data` \| `SystemImageIcon` \| `null`                                                                         | Optional. Custom notification icon image data or system icon name.               |
| `silent`            | `boolean?`                                                                                                    | Optional. Defaults to `false`. If `true`, delivers silently without sound.       |
| `interruptionLevel` | `"active"` \| `"passive"` \| `"timeSensitive"`                                                                | Optional. Defines priority and delivery behavior.                                |
| `userInfo`          | `Record<string, any>?`                                                                                        | Optional. Custom metadata.                                                       |
| `threadIdentifier`  | `string?`                                                                                                     | Optional. Identifier for grouping notifications.                                 |
| `trigger`           | `TimeIntervalNotificationTrigger` \| `CalendarNotificationTrigger` \| `LocationNotificationTrigger` \| `null` | Optional. Defines when the notification is delivered.                            |
| `actions`           | `NotificationAction[]?`                                                                                       | Optional. Action buttons shown when long-pressing or expanding the notification. |
| `customUI`          | `boolean?`                                                                                                    | Optional. Enables rich notification UI using `notification.tsx`.                 |
| `tapAction`         | `"none"` \| `{ type: "runScript", scriptName: string }` \| `{ type: "openURL", url: string }`                 | Optional. Controls what happens when the user taps the notification.             |

#### SystemImageIcon

```ts
type SystemImageIcon = {
  systemImage: string
  color: Color
}
```

Used to define notification icon using system image name and color.

- `systemImage`: SFSymbol name
- `color`: Icon color

***

### Notification Actions (`actions`)

The `actions` parameter defines action buttons that are shown when the user long-presses or expands the notification. Each action has a title and an optional URL to open when tapped.

#### Notification Action (`NotificationAction`)

```ts
type NotificationAction = {
  title: string;
  icon?: string;
  url: string;
  destructive?: boolean;
}
```

- `title`: Action button title
- `icon`: Action button icon
- `url`: URL to open when tapped
- `destructive`: Whether the action is destructive

***

### Tap Behavior (`tapAction`)

The `tapAction` parameter gives you precise control over what happens when the user taps the notification:

- `"none"` – Do nothing when tapped
- `{ type: "runScript", scriptName: string }` – Run a different script
- `{ type: "openURL", url: string }` – Open a deep link or web page

If `tapAction` is not provided, the default behavior is to run the **current script**, and the notification details can be accessed using `Notification.current`.

***

## Notification Triggers

### TimeIntervalNotificationTrigger

Triggers a notification after a specified number of seconds.

```ts
new TimeIntervalNotificationTrigger({
  timeInterval: 3600,
  repeats: true
})
```

- `timeInterval`: Delay in seconds
- `repeats`: Whether it repeats
- `nextTriggerDate()`: Returns the next expected trigger date

***

### CalendarNotificationTrigger

Triggers when the current date matches specific calendar components.

```ts
const components = new DateComponents({ hour: 8, minute: 0 })
new CalendarNotificationTrigger({
  dateMatching: components,
  repeats: true
})
```

- Supports components like `year`, `month`, `day`, `hour`, etc.
- Useful for daily or weekly reminders

***

### LocationNotificationTrigger

Triggers when entering or exiting a geographic region.

```ts
new LocationNotificationTrigger({
  region: {
    identifier: "Work",
    center: { latitude: 37.7749, longitude: -122.4194 },
    radius: 100,
    notifyOnEntry: true,
    notifyOnExit: false
  },
  repeats: false
})
```

- Fires based on entering/exiting the specified circular region

***

## Notification Actions

Use the `actions` array to define buttons shown when the notification is expanded:

```ts
actions: [
  {
    title: "Open Details",
    url: Script.createRunURLScheme("Details Script", { fromNotification: true })
  },
  {
    title: "Dismiss",
    url: Script.createRunURLScheme("Dismiss Script", { dismissed: true }),
    destructive: true
  }
]
```

- Use `Script.createRunURLScheme(...)` to generate Scripting app URLs
- Action buttons appear on long-press or pull-down

***

## Rich Notifications with Custom UI

You can provide an interactive JSX interface:

1. Set `customUI: true` in the `Notification.schedule()` call
2. Create a `notification.tsx` file
3. Call `Notification.present(element)` inside that file

### `Notification.present(element: JSX.Element): void`

Must be called from `notification.tsx`. Renders the element as the expanded notification interface.

***

### Example `notification.tsx`

```tsx
import { Notification, VStack, Text, Button } from 'scripting'

function NotificationView() {
  return (
    <VStack>
      <Text>Need to complete your task?</Text>
      <Button title="Done" action={() => console.log("Task completed")} />
      <Button title="Later" action={() => console.log("Task postponed")} />
    </VStack>
  )
}

Notification.present(<NotificationView />)
```

***

## Managing Notifications

| Method                                 | Description                                           |
| -------------------------------------- | ----------------------------------------------------- |
| `getAllDelivereds()`                   | Returns all delivered notifications.                  |
| `getAllPendings()`                     | Returns all scheduled but undelivered notifications.  |
| `removeAllDelivereds()`                | Removes all delivered notifications.                  |
| `removeAllPendings()`                  | Cancels all pending notifications.                    |
| `removeDelivereds(ids)`                | Removes delivered notifications with matching IDs.    |
| `removePendings(ids)`                  | Cancels scheduled notifications with matching IDs.    |
| `getAllDeliveredsOfCurrentScript()`    | Delivered notifications from the current script only. |
| `getAllPendingsOfCurrentScript()`      | Scheduled notifications from the current script only. |
| `removeAllDeliveredsOfCurrentScript()` | Clears current script’s delivered notifications.      |
| `removeAllPendingsOfCurrentScript()`   | Cancels current script’s pending notifications.       |
| `setBadgeCount(count)`                 | Sets the app icon badge value.                        |

***

## NotificationInfo and Request Structure

Use `Notification.current` to get launch context when the script is opened from a notification tap:

```ts
if (Notification.current) {
  const { title, userInfo } = Notification.current.request.content
  console.log(`Launched from: ${title}`, userInfo)
}
```

### `NotificationRequest` Fields

| Field                      | Description                           |
| -------------------------- | ------------------------------------- |
| `identifier`               | Unique ID for the request             |
| `content.title`            | Notification title                    |
| `content.subtitle`         | Optional subtitle                     |
| `content.body`             | Notification body                     |
| `content.userInfo`         | Custom metadata                       |
| `content.threadIdentifier` | Grouping key                          |
| `trigger`                  | Trigger object that controls delivery |

***

## Comprehensive Example

This example demonstrates a full-featured notification with actions, rich UI, and repeated delivery.

### Step 1: Schedule the Notification

```ts
await Notification.schedule({
  title: "Hydration Reminder",
  body: "Time to drink water!",
  interruptionLevel: "timeSensitive",
  iconImageData: UIImage
    .fromSFSymbol("waterbottle")!
    .withTintColor("systemBlue")!
    .toPNGData(),
  customUI: true,
  trigger: new TimeIntervalNotificationTrigger({
    timeInterval: 3600,
    repeats: true
  }),
  tapAction: {
    type: "runScript",
    scriptName: "Hydration Tracker"
  },
  actions: [
    {
      title: "I Drank",
      url: Script.createRunURLScheme("Hydration Tracker", { drank: true }),
    },
    {
      title: "Ignore",
      url: Script.createRunURLScheme("Hydration Tracker", { drank: false }),
      destructive: true
    }
  ]
})
```

### Step 2: Define `notification.tsx`

```tsx
import { Notification, VStack, Text, Button } from 'scripting'

function HydrationUI() {
  return (
    <VStack>
      <Text>Have you drunk water?</Text>
      <Button title="Yes" action={() => console.log("Hydration confirmed")} />
      <Button title="No" action={() => console.log("Reminder ignored")} />
    </VStack>
  )
}

Notification.present(<HydrationUI />)
```

***

## Summary

The `Notification` API in the Scripting app supports:

- Time, calendar, and location-based triggers
- Actionable buttons and script redirection
- Tap behaviors via `tapAction`
- Rich notification UI via `notification.tsx`
- Full lifecycle management (deliver, remove, query)



---
url: /guide/Device Capabilities/Notification/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Notification, Script, Section, } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <List
      navigationTitle={"Notification"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section
      >
        <Button
          title={"Schedule a Notification with actions"}
          action={async () => {
            Notification.schedule({
              title: "Notification Testing",
              body: "Long Press or Pull Down",
              actions: [
                {
                  title: "Widget",
                  url: Script.createRunURLScheme(Script.name, {
                    doc: "Widget",
                  })
                },
                {
                  title: "LiveActivity",
                  url: Script.createRunURLScheme(Script.name, {
                    doc: "LiveActivity",
                  })
                }
              ]
            })
          }}
        />
      </Section>

      <Section
      >
        <Button
          title={"Schedule a Notification with Rich Content"}
          action={async () => {
            Notification.schedule({
              title: "Notification Testing",
              body: "Long Press or Pull Down to show rich content.",
              customUI: true,
              userInfo: {
                title: "AudioRecorder",
                subtitle: "The interface allows you to record audio data to a file. It provides functionalities to start, stop, pause, and manage audio recordings, with configurable settings for audio quality, sample rate, format, and more.",
              }
            })
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/PDF.md
---

# PDF

The `PDFDocument` and `PDFPage` classes in the **Scripting** app provide a simplified and powerful interface for working with PDF files, including reading, editing, and exporting content. Both synchronous and asynchronous methods are supported for optimal flexibility.

***

## `PDFPage` Class

Represents a single page within a PDF document. It offers access to text content, raw data, and related metadata.

### Static Methods

#### `PDFPage.fromImage(image: UIImage): PDFPage | null`

Creates a new PDF page from the given image.

- **Parameters**:

  - `image`: The image to convert into a PDF page.
- **Returns**: A `PDFPage` instance, or `null` if creation fails.

***

### Properties

#### `document: PDFDocument | null`

The parent `PDFDocument` instance this page belongs to, or `null` if it hasn’t been added to a document yet.

#### `label: string | null`

A user-visible label for the page, such as a page title.

#### `numberOfCharacters: number`

The total number of text characters on the page.

***

### Asynchronous Getters

#### `string: Promise<string | null>`

Returns the text content of the page. May return `null` if the page contains only images or non-text content.

#### `data: Promise<Data | null>`

Returns the raw binary representation of the page.

***

## `PDFDocument` Class

Represents an entire PDF document. This class enables reading, inspecting, editing pages, and saving the document.

***

### Static Methods

#### `PDFDocument.fromData(data: Data): PDFDocument | null`

Creates a new document from raw PDF data.

- **Parameters**:

  - `data`: A valid PDF binary buffer.
- **Returns**: A `PDFDocument` instance or `null` if the data is invalid.

#### `PDFDocument.fromFilePath(filePath: string): PDFDocument | null`

Loads a PDF document from a file path.

- **Parameters**:

  - `filePath`: Path to a valid PDF file.
- **Returns**: A `PDFDocument` instance, or `null` if the file cannot be read.

***

### Read-Only Properties

#### `pageCount: number`

The total number of pages in the document.

#### `filePath: string | null`

The original file path of the PDF, or `null` if created in memory.

#### `isLocked: boolean`

Indicates whether the document is locked and requires a password.

#### `isEncrypted: boolean`

Indicates whether the document is encrypted.

#### `documentAttributes: object | null`

Optional document metadata:

```ts
{
  author?: string | null
  creationDate?: Date | null
  creator?: string | null
  keywords?: any | null
  modificationDate?: Date | null
  producer?: string | null
  subject?: string | null
  title?: string | null
}
```

##### Example

```ts
const doc = PDFDocument.fromFilePath("path/to/example.pdf")
const attrs = doc.documentAttributes
console.log(attrs?.title) // "Project Report"
```

***

### Asynchronous Getters

#### `data: Promise<Data | null>`

Asynchronously retrieves the document's binary data.

#### `string: Promise<string | null>`

Asynchronously retrieves the full text content of the PDF. May return `null` for image-based documents.

***

### Instance Methods

#### `pageAt(index: number): PDFPage | null`

Returns the page at the given index.

- **Parameters**:

  - `index`: Zero-based index of the page.
- **Returns**: A `PDFPage` instance or `null` if out of range.

#### `indexOf(page: PDFPage): number`

Returns the index of the specified page within the document.

- **Parameters**:

  - `page`: A `PDFPage` object from this document.
- **Returns**: The page index, or `-1` if not found.

#### `removePageAt(index: number): void`

Removes the page at the specified index.

#### `insertPageAt(page: PDFPage, atIndex: number): void`

Inserts a page at the specified index.

##### Example

```ts
const doc = PDFDocument.fromFilePath("path/to/document.pdf")
const imagePage = PDFPage.fromImage(image)
doc.insertPageAt(imagePage, 1)
```

#### `exchangePage(atIndex: number, withPageIndex: number): void`

Swaps two pages in the document.

***

### Save Methods

#### `writeSync(toFilePath: string, options?): boolean`

Writes the document to a file synchronously with optional encryption and configuration.

- **Parameters**:

  - `toFilePath`: Path to save the new PDF.
  - `options` (optional):

    ```ts
    {
      ownerPassword?: string
      userPassword?: string
      burnInAnnotations?: boolean
      saveTextFromOCR?: boolean
      saveImagesAsJPEG?: boolean
    }
    ```
- **Returns**: `true` if the file was saved successfully, `false` otherwise.

##### Example

```ts
const doc = PDFDocument.fromFilePath("path/to/input.pdf")
const success = doc.writeSync("path/to/output.pdf", {
  ownerPassword: "admin",
  userPassword: "1234"
})
```

#### `write(toFilePath: string, options?): Promise<boolean>`

Asynchronously writes the document to a file.

- Same parameters as `writeSync`.
- **Returns**: A `Promise<boolean>` indicating success.

***

### Unlock Method

#### `unlock(password: string): boolean`

Attempts to unlock an encrypted PDF document.

- **Parameters**:

  - `password`: The password string.
- **Returns**: `true` if unlocked successfully, otherwise `false`.

***

## Example Usage

```ts
const doc = PDFDocument.fromFilePath("path/to/book.pdf")
if (doc && !doc.isLocked) {
  const firstPage = doc.pageAt(0)
  const text = await firstPage?.string
  console.log("First page text:", text)
  
  const success = await doc.write("path/to/book-copy.pdf")
  console.log(success ? "Saved successfully" : "Save failed")
}
```



---
url: /guide/Device Capabilities/Pasteboard.md
---

# Pasteboard

The `Pasteboard` namespace provides a complete interface for reading, writing, and observing system pasteboard (clipboard) changes in the **Scripting app**.
Compared to the deprecated `Clipboard` API, `Pasteboard` offers more robust features, including:

- Support for multiple data types (text, images, URLs, binary data, etc.)
- Change event callbacks (`onChanged` and `onRemoved`)
- Privacy controls such as `localOnly` and expiration time

> **Note**
> To allow pasting from other apps, go to:
> **Settings > Scripting > Paste from Other Apps > Allow**

***

## Namespace: `Pasteboard`

### Type Definition

#### `Item`

Represents a pasteboard item.
Each item is a map (`Record<UTType, string | UIImage | Data>`) where the key is a data type (`UTType`) and the value can be a string, image, or binary data.

Common types:

- `public.plain-text` → plain text
- `public.url` → URL string
- `public.jpeg` / `public.png` → image (`UIImage`)
- `public.data` → binary data (`Data`)

**Example**

```ts
const item: Pasteboard.Item = {
  "public.plain-text": "Hello, world!",
  "public.url": "https://example.com"
}
```

***

## Properties

### `hasStrings: Promise<boolean>`

Checks whether the pasteboard contains text content.

**Example**

```ts
if (await Pasteboard.hasStrings) {
  console.log("Pasteboard contains text")
}
```

***

### `hasImages: Promise<boolean>`

Checks whether the pasteboard contains images.

**Example**

```ts
if (await Pasteboard.hasImages) {
  console.log("Pasteboard contains images")
}
```

***

### `hasURLs: Promise<boolean>`

Checks whether the pasteboard contains URLs.

**Example**

```ts
if (await Pasteboard.hasURLs) {
  console.log("Pasteboard contains URLs")
}
```

***

### `numberOfItems: Promise<number>`

Returns the number of items currently stored in the pasteboard.

**Example**

```ts
const count = await Pasteboard.numberOfItems
console.log(`The pasteboard contains ${count} items`)
```

***

### `changeCount: Promise<number>`

Returns the number of times the pasteboard contents have changed since system startup.
This value increases whenever the pasteboard is modified (items added, updated, or removed).

**Example**

```ts
const changeCount = await Pasteboard.changeCount
console.log("Pasteboard change count:", changeCount)
```

***

## Text Operations

### `getString(): Promise<string | null>`

Retrieves the text string of the first pasteboard item.

**Example**

```ts
const text = await Pasteboard.getString()
if (text) console.log("Pasteboard text:", text)
```

***

### `setString(string: string | null): Promise<void>`

Sets the text string of the first pasteboard item.

**Example**

```ts
await Pasteboard.setString("Scripting is powerful!")
```

***

### `getStrings(): Promise<string[] | null>`

Retrieves all text strings from the pasteboard.

**Example**

```ts
const texts = await Pasteboard.getStrings()
console.log(texts)
```

***

### `setStrings(strings: string[] | null): Promise<void>`

Sets multiple text strings to the pasteboard (each string becomes a separate item).

**Example**

```ts
await Pasteboard.setStrings(["Apple", "Banana", "Cherry"])
```

***

## URL Operations

### `getURL(): Promise<string | null>`

Retrieves the first URL string from the pasteboard.

**Example**

```ts
const url = await Pasteboard.getURL()
if (url) console.log("Pasteboard URL:", url)
```

***

### `setURL(url: string | null): Promise<void>`

Sets a URL string as the first pasteboard item.

**Example**

```ts
await Pasteboard.setURL("https://example.com")
```

***

### `getURLs(): Promise<string[] | null>`

Retrieves all URL strings from the pasteboard.

**Example**

```ts
const urls = await Pasteboard.getURLs()
console.log(urls)
```

***

### `setURLs(urls: string[] | null): Promise<void>`

Sets multiple URLs to the pasteboard.

**Example**

```ts
await Pasteboard.setURLs([
  "https://apple.com",
  "https://openai.com"
])
```

***

## Image Operations

### `getImage(): Promise<UIImage | null>`

Retrieves the first image (`UIImage`) from the pasteboard.

**Example**

```ts
const img = await Pasteboard.getImage()
if (img) console.log("Image retrieved from pasteboard")
```

***

### `setImage(image: UIImage | null): Promise<void>`

Sets the first pasteboard item to an image.

**Example**

```ts
await Pasteboard.setImage(myImage)
```

***

### `getImages(): Promise<UIImage[] | null>`

Retrieves all image objects from the pasteboard.

**Example**

```ts
const images = await Pasteboard.getImages()
console.log(`Retrieved ${images?.length ?? 0} images`)
```

***

### `setImages(images: UIImage[] | null): Promise<void>`

Sets multiple images to the pasteboard.

**Example**

```ts
await Pasteboard.setImages([img1, img2, img3])
```

***

## Item Management

### `addItems(items: Item[]): Promise<void>`

Appends new items to the existing pasteboard content without clearing it.

**Example**

```ts
await Pasteboard.addItems([
  { "public.plain-text": "First item" },
  { "public.url": "https://example.com" }
])
```

***

### `setItems(items: Item[], options?: { localOnly?: boolean, expirationDate?: Date }): Promise<void>`

Replaces the pasteboard contents with new items and applies optional privacy settings.

**Parameters**

- `items`: An array of pasteboard items.
- `options.localOnly`: If `true`, prevents the pasteboard content from being shared to other devices via Handoff.
- `options.expirationDate`: Sets an expiration time after which the system automatically removes the content.

**Example**

```ts
await Pasteboard.setItems(
  [
    { "public.plain-text": "Sensitive Info" }
  ],
  {
    localOnly: true,
    expirationDate: new Date(Date.now() + 60 * 1000) // Expires in 1 minute
  }
)
```

***

### `getItems(): Promise<Item[] | null>`

Retrieves all pasteboard items as an array of `Pasteboard.Item` objects.

**Example**

```ts
const items = await Pasteboard.getItems()
console.log(items)
```

***

## Event Callbacks

### `onChanged: ((addedKeys: string[]) => void) | null | undefined`

Called when the pasteboard content changes.
The parameter `addedKeys` is an array of the added representation types (`UTType`).

**Example**

```ts
Pasteboard.onChanged = addedKeys => {
  console.log("Added pasteboard types:", addedKeys)
}
```

***

### `onRemoved: ((removedKeys: string[]) => void) | null | undefined`

Called when content is removed from the pasteboard.
The parameter `removedKeys` is an array of the removed representation types (`UTType`).

**Example**

```ts
Pasteboard.onRemoved = removedKeys => {
  console.log("Removed pasteboard types:", removedKeys)
}
```

***

## Deprecated Clipboard API

The legacy `Clipboard` namespace is **deprecated** and retained only for backward compatibility.

| Deprecated Method                  | Replacement                  |
| ---------------------------------- | ---------------------------- |
| `Clipboard.copyText(text: string)` | `Pasteboard.setString(text)` |
| `Clipboard.getText()`              | `Pasteboard.getString()`     |

***

## Best Practices

- Always use the new `Pasteboard` API instead of `Clipboard`.
- Use `changeCount` to detect when pasteboard contents have changed.
- Use `expirationDate` to automatically clear sensitive data after a specific duration.
- Set `localOnly: true` for data that should not sync across devices.
- Use `hasStrings`, `hasImages`, and `hasURLs` to check available content types before reading.
- Use `onChanged` and `onRemoved` callbacks to react in real time to pasteboard updates.



---
url: /guide/Device Capabilities/Photos/index.md
---

# Photos

The `Photos` module provides unified access to the system photo library and camera. It enables scripts to:

- Capture photos or record videos using the system camera
- Pick images, videos, or Live Photos from the photo library
- Retrieve the most recent photos
- Save images or videos to the Photos app
- Query the library for assets by media type, album, date, or favorites, and read rich metadata
- Load image, data, video, or Live Photo representations from a specific asset
- Browse, create, and delete albums; favorite or delete assets

All APIs are built on top of native iOS frameworks such as Photos and PHPicker, and follow these principles:

- System-managed permissions
- Promise-based asynchronous APIs
- System-controlled UI presentation
- Secure and constrained access to media data

***

## CaptureInfo

```ts
type CaptureInfo = {
  cropRect: {
    x: number
    y: number
    width: number
    height: number
  } | null
  originalImage: UIImage | null
  editedImage: UIImage | null
  imagePath: string | null
  mediaMetadata: Record<string, any> | null
  mediaPath: string | null
  mediaType: string | null
}
```

`CaptureInfo` describes the complete result of a capture operation (photo or video).

### Properties

- `cropRect`
  The cropping rectangle applied during editing.
  `null` if no cropping was performed.

- `originalImage`
  The original image captured by the camera.

- `editedImage`
  The edited image, if editing was enabled and applied.

- `imagePath`
  File path to the captured image on disk.

- `mediaMetadata`
  Metadata associated with the captured media, such as EXIF data.

- `mediaPath`
  File path to the captured video.

- `mediaType`
  The UTType string describing the media type.

***

## availableMediaTypes()

```ts
function availableMediaTypes(): string[] | null
```

Returns the list of media UTTypes supported by the current device’s camera.

Common use cases include checking whether video capture is supported or dynamically adjusting capture options.

Returns `null` if the information is unavailable.

***

## capture(options)

```ts
function capture(options: {
  mode: "photo" | "video"
  mediaTypes: UTType[]
  allowsEditing?: boolean
  cameraDevice?: "rear" | "front"
  cameraFlashMode?: "auto" | "on" | "off"
  videoMaximumDuration?: DurationInSeconds
  videoQuality?: 
    | "low"
    | "medium"
    | "high"
    | "640x480"
    | "iFrame960x540"
    | "iFrame1280x720"
}): Promise<CaptureInfo | null>
```

Presents the system camera interface to capture a photo or record a video.

### Options

- `mode`
  Capture mode

  - `"photo"`: capture a photo
  - `"video"`: record a video

- `mediaTypes`
  Allowed media UTTypes.

- `allowsEditing`
  Whether the user can edit the captured media.

- `cameraDevice`
  Camera to use. Defaults to `"rear"`.

- `cameraFlashMode`
  Flash behavior. Defaults to `"auto"`.

- `videoMaximumDuration`
  Maximum video duration in seconds.

- `videoQuality`
  Video resolution and encoding quality.

### Behavior Notes

- The UI is fully system-managed
- The Promise resolves only after the user finishes or cancels the operation
- Permission prompts are handled by the system

***

## pick(options)

```ts
function pick(options?: {
  mode?: "default" | "compact"
  filter?: PHPickerFilter
  limit?: number
}): Promise<PHPickerResult[]>
```

Presents the system photo picker to select media items from the photo library.

### Options

- `mode`
  Picker layout style

  - `default`: grid layout
  - `compact`: linear layout

- `filter`
  A `PHPickerFilter` that restricts selectable asset types.

- `limit`
  Maximum number of selectable items. Defaults to `1`.

### Return Value

Returns an array of `PHPickerResult` objects.
Each result must be explicitly resolved into a concrete media representation.

***

## PHPickerFilter

`PHPickerFilter` defines which asset types can be selected in `Photos.pick`.

It is a non-instantiable class and can only be constructed via static methods.

***

### Basic Filters

- `PHPickerFilter.images()`
  Allows selection of standard images.

- `PHPickerFilter.videos()`
  Allows selection of videos.

- `PHPickerFilter.livePhotos()`
  Allows selection of Live Photos.

- `PHPickerFilter.bursts()`
  Burst photo sequences.

- `PHPickerFilter.panoramas()`
  Panorama photos.

- `PHPickerFilter.screenshots()`
  Screenshots.

- `PHPickerFilter.screenRecordings()`
  Screen recording videos.

- `PHPickerFilter.depthEffectPhotos()`
  Photos with depth effects (portrait photos).

- `PHPickerFilter.cinematicVideos()`
  Cinematic mode videos.

- `PHPickerFilter.slomoVideos()`
  Slow-motion videos.

- `PHPickerFilter.timelapseVideos()`
  Time-lapse videos.

***

### Composite Filters

- `PHPickerFilter.all(filters)`
  Matches assets that satisfy all provided filters
  Logical AND

- `PHPickerFilter.any(filters)`
  Matches assets that satisfy at least one filter
  Logical OR

- `PHPickerFilter.not(filter)`
  Excludes assets matching the specified filter
  Logical NOT

#### Example

```ts
const filter = PHPickerFilter.any([
  PHPickerFilter.livePhotos(),
  PHPickerFilter.images()
])

await Photos.pick({ filter })
```

***

## PHPickerResult

Represents a single item returned from the photo picker.

### itemProvider: ItemProvider

The item provider for the selected asset, which can be used to load the asset.

### livePhoto()

```ts
livePhoto(): Promise<LivePhoto | null>
```

Attempts to read the result as a Live Photo.
Resolves to `null` if the asset cannot be represented as a Live Photo.

***

### uiImage()

```ts
uiImage(): Promise<UIImage | null>
```

Attempts to read the result as a UIImage object.
Resolves to `null` if the asset cannot be represented as an image.

***

### imagePath()

```ts
imagePath(): Promise<string | null>
```

If this result can be read as an image, this file will be copied to the app group's sandbox and returns a promise that resolves to the image path, otherwise returns null, or rejects with an error. You should delete the image file when you no longer need it.

#### Example

```ts
const filePath = await result.imagePath()
```

***

### videoPath()

```ts
videoPath(): Promise<string | null>
```

If this result can be read as a video, this file will be copied to the app group's sandbox and returns a promise that resolves to the video path, otherwise returns null, or rejects with an error. You should delete the video file when you no longer need it.

***

## getLatestPhotos(count)

```ts
function getLatestPhotos(count: number): Promise<UIImage[] | null>
```

Retrieves the most recent photos from the photo library.

### Notes

- Images only (no videos)
- Ordered from newest to oldest
- Returns `null` if access is unavailable

***

## pickPhotos(count)

```ts
function pickPhotos(count: number): Promise<UIImage[]>
```

Legacy convenience API for selecting a fixed number of photos.

Returns an array of `UIImage` objects without file paths or metadata.

***

## takePhoto()

```ts
function takePhoto(): Promise<UIImage | null>
```

Quick photo capture API.

- No advanced configuration
- Returns `null` if the user cancels

***

## savePhoto(path, options)

```ts
function savePhoto(
  path: string,
  options?: { fileName?: string }
): Promise<boolean>
```

Saves an image file from disk to the Photos app.

***

## savePhoto(image, options)

```ts
function savePhoto(
  image: Data,
  options?: { fileName?: string }
): Promise<boolean>
```

Saves raw image data directly to the Photos app, avoiding temporary files.

***

## saveVideo(path, options)

```ts
function saveVideo(
  path: string,
  options?: { fileName?: string }
): Promise<boolean>
```

Saves a video file from disk to the Photos app.

***

## saveVideo(video, options)

```ts
function saveVideo(
  video: Data,
  options?: { fileName?: string }
): Promise<boolean>
```

Saves raw video data directly to the Photos app.

***

## Photo Asset Layer

Beyond the transactional pick/capture/save APIs, the module exposes the underlying photo library as addressable assets. This lets scripts enumerate the library, read metadata, load media at controlled sizes, and manage albums.

### authorizationStatus(accessLevel?)

```ts
function authorizationStatus(
  accessLevel?: "addOnly" | "readWrite"
): "notDetermined" | "restricted" | "denied" | "authorized" | "limited"
```

Returns the current authorization status without prompting. Access is requested automatically the first time you read or write the library. Defaults to `"readWrite"`.

### fetchAssets(options?)

```ts
function fetchAssets(options?: PHFetchOptions): Promise<PHAsset[]>
function fetchAssets(localIdentifiers: string[]): Promise<PHAsset[]>
```

Fetch assets matching `PHFetchOptions`, or fetch specific assets by their local identifiers.

```ts
type PHFetchOptions = {
  mediaType?: "image" | "video" | "audio"
  mediaSubtypes?: PHAssetMediaSubtype[]
  favoritesOnly?: boolean
  includeHidden?: boolean
  includeAllBurstAssets?: boolean
  sortBy?: "creationDate" | "modificationDate"
  ascending?: boolean
  limit?: number
  createdAfter?: number   // milliseconds since epoch
  createdBefore?: number
}
```

`PHAssetMediaSubtype` is one of `"photoPanorama"`, `"photoHDR"`, `"photoScreenshot"`, `"photoLive"`, `"photoDepthEffect"`, `"videoStreamed"`, `"videoHighFrameRate"`, `"videoTimelapse"`.

```ts
const recent = await Photos.fetchAssets({
  mediaType: "image",
  favoritesOnly: true,
  limit: 20,
})
```

### fetchAsset(localIdentifier)

```ts
function fetchAsset(localIdentifier: string): Promise<PHAsset | null>
```

Fetch a single asset by its stable `localIdentifier`. Store the identifier to reference the same asset across script runs.

***

## PHAsset

A reference to an image, video, or Live Photo in the library.

### Properties

- `localIdentifier: string` — stable, persistent identifier.
- `mediaType: "image" | "video" | "audio" | "unknown"`
- `mediaSubtypes: PHAssetMediaSubtype[]`
- `pixelWidth: number`, `pixelHeight: number`
- `creationDate: number | null`, `modificationDate: number | null` — milliseconds since epoch.
- `duration: number` — seconds; `0` for images.
- `isFavorite: boolean`, `isHidden: boolean`
- `location: PHAssetLocation | null` — latitude, longitude, altitude, accuracies, speed, course, timestamp.
- `burstIdentifier: string | null`, `representsBurst: boolean`
- `sourceType: "userLibrary" | "cloudShared" | "itunesSynced" | "unknown"`

### requestImage(options?)

```ts
requestImage(options?: {
  targetWidth?: number
  targetHeight?: number
  contentMode?: "aspectFit" | "aspectFill"
  deliveryMode?: "opportunistic" | "highQualityFormat" | "fastFormat"
  version?: "current" | "original" | "unadjusted"
  allowNetworkAccess?: boolean
}): Promise<UIImage | null>
```

Loads a `UIImage` at the requested size. Omit the target size to load the full resolution. Downloads from iCloud when needed unless `allowNetworkAccess` is `false`.

### requestImageData(options?)

```ts
requestImageData(options?: {
  version?: "current" | "original" | "unadjusted"
  allowNetworkAccess?: boolean
}): Promise<{ data: Data; uti: UTType; orientation: number } | null>
```

Loads the original file data, its uniform type identifier, and EXIF orientation.

### requestVideoURL(options?)

```ts
requestVideoURL(options?: {
  version?: "current" | "original" | "unadjusted"
  allowNetworkAccess?: boolean
}): Promise<string | null>
```

Exports the asset's video to a temporary file in the app sandbox and resolves its path. Delete the file when no longer needed. Resolves `null` for assets without video.

### requestLivePhoto(options?)

```ts
requestLivePhoto(options?: {
  targetWidth?: number
  targetHeight?: number
  allowNetworkAccess?: boolean
}): Promise<LivePhoto | null>
```

Loads a `LivePhoto` representation, or `null` if the asset is not a Live Photo.

### setFavorite(value) / delete()

```ts
setFavorite(value: boolean): Promise<boolean>
delete(): Promise<boolean>
```

Mark/unmark as favorite, or delete the asset. Deletion presents a system confirmation prompt; resolves `false` if the user cancels.

***

## Albums

### fetchAlbums(options?) / fetchAlbum(localIdentifier)

```ts
function fetchAlbums(options?: {
  type?: "album" | "smartAlbum"
  assetCollectionSubtype?: string
}): Promise<PHAssetCollection[]>

function fetchAlbum(localIdentifier: string): Promise<PHAssetCollection | null>
```

Fetch albums and smart albums. Omit `type` to fetch both.

### createAlbum(title) / deleteAlbums(albums) / deleteAssets(assets)

```ts
function createAlbum(title: string): Promise<PHAssetCollection | null>
function deleteAlbums(albums: PHAssetCollection[]): Promise<boolean>
function deleteAssets(assets: PHAsset[]): Promise<boolean>
```

Create a user album, delete albums, or batch-delete assets. Deletions present a system confirmation prompt.

## PHAssetCollection

- `localIdentifier: string`
- `title: string | null`
- `type: "album" | "smartAlbum" | "moment"`
- `subtype: string` — e.g. `"smartAlbumUserLibrary"`, `"smartAlbumFavorites"`, `"albumRegular"`.
- `estimatedAssetCount: number` — the asset count; falls back to an exact count when the fast estimate is unavailable (common for smart albums).
- `startDate: number | null`, `endDate: number | null`

```ts
fetchAssets(options?: PHFetchOptions): Promise<PHAsset[]>
addAssets(assets: PHAsset[]): Promise<boolean>
removeAssets(assets: PHAsset[]): Promise<boolean>
```

`addAssets` / `removeAssets` are valid only for user-created albums.

```ts
const album = await Photos.createAlbum("My Script Album")
const favorites = await Photos.fetchAssets({ favoritesOnly: true, limit: 10 })
await album?.addAssets(favorites)
```

***

## Design Notes

- All APIs are asynchronous and permission-aware
- All UI is system-managed and not customizable
- Picker results are lazy and must be explicitly resolved
- Save APIs return only success status, not asset identifiers
- `PHAsset` is addressable by `localIdentifier`; persist it to reload the same asset later
- Mutating operations (favorite, delete, album changes) require write access and may present system prompts



---
url: /guide/Device Capabilities/Photos/index_example.md
---

# Example

```tsx
import { Button, Dialog, List, Navigation, NavigationStack, Script, Section, Text, } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <List
      navigationTitle={"Photos"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section
        footer={
          <Text>Get the latest specified number of photos from the Photos app.</Text>
        }
      >
        <Button
          title={"Photos.getLatestPhotos"}
          action={async () => {
            const images = await Photos.getLatestPhotos(1)
            const image = images?.[0]

            if (image != null) {
              Dialog.alert({
                message: `Image size: ${image.width}*${image.height}`
              })
            } else {
              Dialog.alert({
                message: "Cancelled"
              })
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Present a photo picker dialog and pick limited number of photos.</Text>
        }
      >

        <Button
          title={"Photos.pickPhotos"}
          action={async () => {
            const images = await Photos.pickPhotos(1)
            const image = images?.[0]

            if (image != null) {
              Dialog.alert({
                message: `Image size: ${image.width}*${image.height}`
              })
            } else {
              Dialog.alert({
                message: "Cancelled"
              })
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Take a photo and return a UIImage instance.</Text>
        }
      >
        <Button
          title={"Photos.takePhoto"}
          action={async () => {
            const image = await Photos.takePhoto()

            if (image != null) {
              Dialog.alert({
                message: `Image size: ${image.width}*${image.height}`
              })
            } else {
              Dialog.alert({
                message: "Cancelled"
              })
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Save an image to the Photos app. Returns a boolean value indicates that whether the operation is successful.</Text>
        }
      >
        <Button
          title={"Photos.savePhoto"}
          action={async () => {
            const image = await Photos.takePhoto()

            if (image != null) {
              const success = await Photos.savePhoto(Data.fromJPEG(image, 0.5)!)
              Dialog.alert({
                message: "The photo has been saved: " + success
              })
            } else {
              Dialog.alert({
                message: "Canceled"
              })
            }
          }}
        />
      </Section>

      <Section
        header={<Text>Photo Asset Layer</Text>}
        footer={
          <Text>Query the library and read rich metadata (date, dimensions, location, subtypes) from each PHAsset.</Text>
        }
      >
        <Button
          title={"Photos.fetchAssets"}
          action={async () => {
            const status = Photos.authorizationStatus()
            const assets = await Photos.fetchAssets({ mediaType: "image", limit: 5 })
            const newest = assets[0]

            if (newest == null) {
              Dialog.alert({ message: `No photos found. (status: ${status})` })
              return
            }

            const created = newest.creationDate != null
              ? new Date(newest.creationDate).toLocaleString()
              : "unknown"
            const where = newest.location != null
              ? `${newest.location.latitude.toFixed(3)}, ${newest.location.longitude.toFixed(3)}`
              : "none"

            Dialog.alert({
              message: [
                `Fetched ${assets.length} asset(s).`,
                `Newest: ${newest.pixelWidth}×${newest.pixelHeight}`,
                `Created: ${created}`,
                `Favorite: ${newest.isFavorite}`,
                `Subtypes: ${newest.mediaSubtypes.join(", ") || "none"}`,
                `Location: ${where}`,
              ].join("\n")
            })
          }}
        />

        <Button
          title={"Asset.requestImage (thumbnail)"}
          action={async () => {
            const assets = await Photos.fetchAssets({ mediaType: "image", limit: 1 })
            const asset = assets[0]
            if (asset == null) {
              Dialog.alert({ message: "No photos found." })
              return
            }
            const image = await asset.requestImage({
              targetWidth: 200,
              targetHeight: 200,
              contentMode: "aspectFill",
            })
            Dialog.alert({
              message: image != null
                ? `Loaded thumbnail: ${image.width}×${image.height}`
                : "Failed to load image."
            })
          }}
        />

        <Button
          title={"Photos.fetchAlbums"}
          action={async () => {
            const albums = await Photos.fetchAlbums({ type: "smartAlbum" })
            const titles = albums
              .slice(0, 8)
              .map(a => `• ${a.title ?? a.subtype} (${a.estimatedAssetCount})`)
              .join("\n")
            Dialog.alert({
              message: `Found ${albums.length} smart album(s):\n${titles}`
            })
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/Play Video/AVPlayerView.md
---

# AVPlayerView

`AVPlayerView` is a video playback component introduced in Scripting that wraps the system-native `AVPlayerViewController`.
Unlike `VideoPlayer`, `AVPlayerView` **fully supports system Picture in Picture (PiP)** and exposes PiP lifecycle state to scripts.

This component is intended for **media-centric scenarios** where native playback behavior, PiP, Now Playing integration, and background playback are required.

***

## 1. When to Use AVPlayerView

Use `AVPlayerView` when you need:

- System Picture in Picture (PiP) for video
- Native playback controls
- Integration with Now Playing / Control Center / Lock Screen
- Automatic PiP when entering background
- Fine-grained observation of PiP lifecycle

If you do **not** need PiP, `VideoPlayer` remains a lighter alternative.

***

## 2. Core Properties Explained

### 2.1 `player`

```ts
player: AVPlayer
```

- The underlying media player
- Fully managed by the developer
- Supports local files, remote URLs, HLS streams, etc.

`AVPlayerView` **does not own the player lifecycle**.
The player must remain alive while PiP is active.

***

### 2.2 `pipStatus`

```ts
pipStatus: Observable<PIPStatus>
```

Provides real-time updates for the PiP lifecycle.

Possible values:

| Value              | Meaning               |
| ------------------ | --------------------- |
| `willStart`        | PiP is about to start |
| `didStart`         | PiP has started       |
| `willStop`         | PiP is about to stop  |
| `didStop`          | PiP has stopped       |
| `undefined / null` | No PiP activity yet   |

This value is **system-controlled**.
You should **observe it only**, never assign values manually.

***

## 3. Picture in Picture Configuration

### 3.1 `allowsPictureInPicturePlayback`

- Enables or disables PiP entirely
- Default: `true`

When set to `false`:

- PiP controls are hidden
- PiP cannot be activated

***

### 3.2 `canStartPictureInPictureAutomaticallyFromInline`

- If enabled, PiP starts automatically when:

  - The app moves to background
  - Video is playing inline
- Default: `false`

Recommended for:

- Media apps
- Continuous playback experiences

***

### 3.3 `updatesNowPlayingInfoCenter`

- Controls automatic updates to:

  - Lock screen
  - Control Center
  - External playback controls
- Default: `true`

Should generally remain enabled for video playback apps.

***

## 4. Full-Screen Playback Behavior

### 4.1 `entersFullScreenWhenPlaybackBegins`

- Automatically enters full screen on play
- Default: `false`

***

### 4.2 `exitsFullScreenWhenPlaybackEnds`

- Automatically exits full screen on completion
- Default: `false`

***

## 5. Video Scaling (`videoGravity`)

```ts
videoGravity?: AVLayerVideoGravity
```

| Value              | Behavior                                    |
| ------------------ | ------------------------------------------- |
| `resize`           | Stretch to fill (no aspect ratio)           |
| `resizeAspect`     | Preserve aspect ratio, fit inside (default) |
| `resizeAspectFill` | Preserve aspect ratio, fill and crop        |

***

## 6. Complete Demo Example

The following example demonstrates:

- Creating and configuring `AVPlayer`
- Activating audio playback session
- Observing PiP lifecycle
- Controlling playback state
- Proper cleanup

```tsx
function Example() {
  const dismiss = Navigation.useDismiss()
  const [status, setStatus] = useState<TimeControlStatus>(
    TimeControlStatus.paused
  )
  const pipstatus = useObservable<PIPStatus>()

  console.log(pipstatus.value)

  const player = useMemo(() => {
    const player = new AVPlayer()

    player.setSource(
      "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
    )

    player.onTimeControlStatusChanged = status => {
      setStatus(status)
    }

    SharedAudioSession.setActive(true)
    SharedAudioSession.setCategory(
      "playback",
      ["defaultToSpeaker"]
    )

    return player
  }, [])

  useEffect(() => {
    return () => {
      player.dispose()
    }
  }, [])

  return <NavigationStack>
    <VStack
      navigationTitle="VideoPlayer"
      navigationBarTitleDisplayMode="inline"
      toolbar={{
        cancellationAction: <Button
          title="Done"
          action={dismiss}
        />
      }}
    >
      <AVPlayerView
        player={player}
        pipStatus={pipstatus}
        canStartPictureInPictureAutomaticallyFromInline
        updatesNowPlayingInfoCenter
        entersFullScreenWhenPlaybackBegins
      />

      <Button
        title={
          status === TimeControlStatus.paused
            ? "Play"
            : "Pause"
        }
        action={() => {
          if (status === TimeControlStatus.paused) {
            player.play()
          } else {
            player.pause()
          }
        }}
      />
    </VStack>
  </NavigationStack>
}
```

***

## 7. PiP Lifecycle Notes

Typical PiP state progression:

1. `willStart`
2. `didStart`
3. PiP running
4. `willStop`
5. `didStop`

The system may skip stages in error or interruption scenarios.
Always treat `didStart` and `didStop` as authoritative.

***

## 8. Important Notes and Constraints

### 8.1 AVPlayerView PiP is System-Level PiP

- Uses native video PiP
- Completely separate from Scripting’s custom PiP View Modifiers
- These two mechanisms must not be mixed

***

### 8.2 Audio Session Is Required

For PiP to work reliably:

- An active audio session is required
- Category should be `playback`
- Background audio capability must be enabled

Failing to configure the audio session may cause PiP to fail silently.

***

### 8.3 Do Not Dispose AVPlayer While PiP Is Active

- Disposing or replacing `AVPlayer` during PiP
- Will force PiP to stop unexpectedly
- May result in system errors

Always wait until `pipStatus` reaches `didStop` before releasing the player.

***

## 9. Recommended Best Practices

- Use `AVPlayerView` exclusively for video PiP
- Treat `pipStatus` as read-only state
- Keep `AVPlayer` lifecycle stable during PiP
- Configure audio session explicitly
- Avoid frequent player replacement
- Clean up resources only after PiP has fully stopped



---
url: /guide/Device Capabilities/Play Video/VideoPlayer/index.md
---

# VideoPlayer

The `VideoPlayer` view integrates a powerful `AVPlayer` backend with a simple, customizable front-end UI for playing video and audio content. With this setup, you can easily load media, control playback, handle events, and even add custom overlays.

## Overview

`VideoPlayer` requires an `AVPlayer` instance, which you configure to load your media, control its playback (play, pause, stop), and respond to events like when the video is ready or ends. The `overlay` prop allows you to place interactive UI elements over the video content, below any system playback controls.

**Key points:**

- Control playback through the `AVPlayer` instance passed into `VideoPlayer`.
- Add custom UI elements on top of the video using `overlay`.
- Listen for events like `onReadyToPlay`, `onEnded`, or `onError` to react to media lifecycle states.

## Basic Usage

First, create and configure the `AVPlayer` instance:

```tsx
const player = new AVPlayer()

// Set the media source: local file path or remote URL
player.setSource("https://example.com/video.mp4")

// When the media is ready, start playing
player.onReadyToPlay = () => {
  console.log("Media is ready, starting playback.")
  player.play()
}

// Handle playback state changes
player.onTimeControlStatusChanged = (status) => {
  console.log("Playback status changed:", status)
}

// Handle the end of playback
player.onEnded = () => {
  console.log("Playback ended.")
}

// Handle errors
player.onError = (message) => {
  console.error("Playback error:", message)
}

// Configure playback properties
player.volume = 1.0          // Full volume
player.rate = 1.0            // Normal speed
player.numberOfLoops = 0     // No looping
```

Then, use the `VideoPlayer` view in your UI:

```tsx
<VideoPlayer
  player={player}
  overlay={
    <HStack padding>
      <Button title="Pause" action={() => player.pause()} />
      <Button title="Play" action={() => player.play()} />
    </HStack>
  }
/>
```

This displays the video with your custom controls positioned at the bottom-left corner.

## Example Scenario

Imagine you want a video with custom controls and automatic replay:

```tsx
function VideoPlayerView() {
  const player = useMemo(() => new AVPlayer(), [])

  useEffect(() => {
    player.setSource(
      Path.join(
        Script.directory,
        "localvideo.mp4"
      )
    )
    player.onReadyToPlay = () => player.play()
    player.onEnded = () => player.play() // Restart video automatically when ended

    
    // Setup shared audio session.
    SharedAudioSession.setActive(true)
    SharedAudioSession.setCategory(
      'playback',
      ['mixWithOthers']
    )

    return () => {
      // Dispose the AVPlayer instance when the view to be destroied.
      player.dispose()
    }
  }, [])

  return <VideoPlayer
    player={player}
    overlay={
      <HStack padding>
        <Button title="Pause" action={() => player.pause()} />
        <Button title="Resume" action={() => player.play()} />
      </HStack>
    }
    frame={{
      height: 300
    }}
  />
}
```

This setup:

- Loads and plays a local video file immediately when ready.
- Automatically replays the video once it ends.
- Provides custom pause/resume controls overlaid on the bottom-right corner.

## Summary

The `VideoPlayer` component, powered by an `AVPlayer` instance, gives you fine-grained control over video playback in your app. From adjusting volume and playback speed to handling buffering states and errors, and even layering your own UI controls over the video, the `VideoPlayer` component and `AVPlayer` class allow for a rich and interactive media experience.



---
url: /guide/Device Capabilities/Play Video/VideoPlayer/index_example.md
---

# Example

```tsx
import { Button, Navigation, NavigationStack, Script, useEffect, useMemo, useState, VideoPlayer, VStack } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()
  const [status, setStatus] = useState<TimeControlStatus>(TimeControlStatus.paused)

  const player = useMemo(() => {
    const player = new AVPlayer()
    player.setSource("https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4")
    player.onTimeControlStatusChanged = (status) => {
      setStatus(status)
    }
    SharedAudioSession.setActive(true)
    SharedAudioSession.setCategory(
      'playback',
      ['mixWithOthers']
    )
    return player
  }, [])

  useEffect(() => {
    return () => {
      player.dispose()
    }
  }, [])

  return <NavigationStack>
    <VStack
      navigationTitle={"VideoPlayer"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <VideoPlayer
        player={player}
        frame={{
          height: 300
        }}
      />
      <Button
        title={status === TimeControlStatus.paused
          ? "Play"
          : "Pause"
        }
        action={() => {
          if (status === TimeControlStatus.paused) {
            player.play()
          } else {
            player.pause()
          }
        }}
      />
    </VStack>
  </NavigationStack >
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/QRCode/index.md
---

The `QRCode` module provides functionality for **parsing**, **generating**, and **scanning** QR codes. Scripts can use this module to decode QR codes from images, generate QR code images from text, or open the system scanning interface to scan a QR code.

This module is suitable for the following scenarios:

- Parsing QR code content from a local image file
- Parsing QR codes from a `UIImage` object
- Generating a QR code image from text
- Opening the scanning interface to scan a QR code

All methods are **asynchronous APIs** and return a `Promise`.

***

# API

## parse

Parse a QR code from an image file at the specified path.

```ts
function parse(filePath: string): Promise<string | null>
```

This method reads the image file at the specified path and attempts to recognize the QR code contained in the image.

If a QR code is successfully decoded, the text content embedded in the QR code is returned. If no QR code is detected or parsing fails, the method returns `null`.

### Example

```ts
const result = await QRCode.parse('path/to/file')

if (result != null) {
  console.log(result)
}
```

***

# parseImage

Parse a QR code from a `UIImage` object.

```ts
function parseImage(image: UIImage): Promise<string | null>
```

This method parses a QR code directly from an in-memory image object without requiring the image to be saved to a file first.

### Example

```ts
const image = await Image.fromFile('/path/to/qrcode.png')

const result = await QRCode.parseImage(image)

if (result != null) {
  console.log(result)
}
```

***

# generate

Generate a QR code image from text.

```ts
function generate(text: string): Promise<UIImage | null>
```

This method encodes the specified text into a QR code and returns the generated QR code image.

### Example

```ts
const image = await QRCode.generate('https://example.com')

if (image != null) {
  console.log(image)
}
```

***

# scan

Open the scanning interface and scan a QR code.

```ts
function scan(): Promise<string | null>
```

This method opens the QR code scanning interface and uses the device camera to scan a QR code.

When the scan succeeds, the text content embedded in the QR code is returned.

If the user cancels the scan or no QR code is recognized, the method returns `null`.

### Example

```ts
const result = await QRCode.scan()

if (result != null) {
  console.log(result)
}
```



---
url: /guide/Device Capabilities/QRCode/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text } from "scripting"

function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"QRCode"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        footer={
          <Text>Open the QRCode scan page and scan.</Text>
        }
      >
        <Button
          title={"QRCode.scan"}
          action={async () => {
            const result = await QRCode.scan()
            if (result) {
              Dialog.alert({
                message: "Result: " + result
              })
            } else {
              Dialog.alert({
                message: "Cancelled"
              })
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Parse QRCode file to a string.</Text>
        }
      >
        <Button
          title={"QRCode.parse"}
          action={async () => {
            const result = await DocumentPicker.pickFiles({
              allowsMultipleSelection: false
            })
            if (result.length) {
              const code = await QRCode.parse(result[0])
              Dialog.alert({
                message: "Parse reuslt: " + code
              })
            }
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/QuickLook.md
---

# QuickLook

The **QuickLook API** in the Scripting app provides a simple way to preview text, images, or files within your scripts. This is a wrapper around iOS QuickLook capabilities, allowing you to quickly display previews for a wide range of content types.

Each method returns a promise that resolves when the QuickLook view is dismissed, enabling you to chain actions or handle post-preview logic easily.

***

## **API Reference**

### `QuickLook.previewText(text: string): Promise<void>`

Displays a preview of a text string.

#### **Parameters**

- `text` (string): The text content to display in the preview.
- `fullscreen` (boolean?): Whether preview in a fullscreen mode. Defaults to false.

#### **Returns**

- A `Promise<void>`: Resolves after the preview is dismissed.

#### **Example**

```tsx
await QuickLook.previewText("Hello, world! This is a QuickLook preview.")
console.log("Text preview dismissed")
```

***

### `QuickLook.previewImage(image: UIImage): Promise<void>`

Displays a preview of an image.

#### **Parameters**

- `image` (UIImage): The image to display in the preview.
- `fullscreen` (boolean?): Whether preview in a fullscreen mode. Defaults to false.

#### **Returns**

- A `Promise<void>`: Resolves after the preview is dismissed.

#### **Example**

```tsx
// Assume `myImage` is a UIImage instance
await QuickLook.previewImage(myImage)
console.log("Image preview dismissed")
```

***

### `QuickLook.previewURLs(urls: string[]): Promise<void>`

Displays a preview of one or more files located at the given file URL strings.

#### **Parameters**

- `urls` (string\[]): An array of file URL strings. Each string should point to a valid file path or remote file that can be previewed by QuickLook.
- `fullscreen` (boolean?): Whether preview in a fullscreen mode. Defaults to false.

#### **Returns**

- A `Promise<void>`: Resolves after the preview is dismissed.

#### **Example**

```tsx
const fileURLs = [
  "/path/to/file1.pdf",
  "/path/to/file2.jpg",
]

await QuickLook.previewURLs(fileURLs)
console.log("File previews dismissed")
```

***

## **Usage Notes**

- **UI Blocking**: These methods present a modal QuickLook view. Execution of subsequent code (after `await`) will pause until the user dismisses the preview.
- **Error Handling**: Use `try...catch` to handle errors such as invalid file paths or unsupported content types.
- **Supported File Types**: The supported file types depend on iOS QuickLook capabilities, which include common file types like PDFs, images, text files, and more.

***

## **Example Use Case**

### Previewing Text, Images, and Files Sequentially

```tsx
// Preview a text
await QuickLook.previewText("QuickLook Preview Example")

// Preview an image
const myImage = UIImage.fromFile("/path/to/image.png")
await QuickLook.previewImage(myImage)

// Preview files
const fileURLs = [
  "/path/to/file1.pdf",
  "/path/to/file2.jpg",
]
await QuickLook.previewURLs(fileURLs)

console.log("All previews completed")
```

With this API, you can integrate QuickLook previews seamlessly into your scripts, enhancing the user experience with minimal effort.



---
url: /guide/Device Capabilities/Recurrence.md
---

# Recurrence

The recurrence-related types and classes (`RecurrenceFrequency`, `RecurrenceDayOfWeek`, `RecurrenceWeekday`, `RecurrenceEnd`, and `RecurrenceRule`) allow you to define and manage recurring patterns for events and reminders in the `Scripting` app. These types and classes make it possible to set up recurrence intervals, specify days or months for recurring patterns, and define end conditions.

## Recurrence Types and Classes

### 1. `RecurrenceFrequency`

`RecurrenceFrequency` defines the frequency with which an event or reminder repeats. The frequency can be one of the following values:

- `daily`: Repeats every day.
- `weekly`: Repeats every week.
- `monthly`: Repeats every month.
- `yearly`: Repeats every year.

This type is used as a property within the `RecurrenceRule` class to specify how often the recurrence should occur.

**Example Usage:**

```ts
const frequency: RecurrenceFrequency = "weekly"
```

### 2. `RecurrenceWeekday`

`RecurrenceWeekday` is an enumeration representing the days of the week. It allows you to specify which day or days an event should recur on within a weekly pattern. The values are:

- `"sunday"`, `"monday"`, `"tuesday"`, `"wednesday"`, `"thursday"`, `"friday"`, `"saturday"`

**Example Usage:**

```ts
const weekday: RecurrenceWeekday = "monday"
```

### 3. `RecurrenceDayOfWeek`

`RecurrenceDayOfWeek` allows for specifying a particular weekday, optionally combined with a `weekNumber`. This type is useful in more complex weekly recurrence patterns where you want to specify both the weekday and its occurrence within a month (like the second Tuesday of each month).

`RecurrenceDayOfWeek` can either be:

- A `RecurrenceWeekday`, or
- An object containing:
  - `weekday`: A `RecurrenceWeekday` (e.g., `"monday"`)
  - `weekNumber`: A number indicating which occurrence of the weekday (positive or negative for backward counting). For example, `1` is the first occurrence, `-1` is the last occurrence.

**Example Usage:**

```ts
const dayOfWeek: RecurrenceDayOfWeek = { weekday: "tuesday", weekNumber: 2 }
```

### 4. `RecurrenceEnd`

`RecurrenceEnd` defines when a recurrence rule should stop. It provides two options for ending a recurrence:

- `fromCount(count: number)`: Ends the recurrence after a specified number of occurrences.
- `fromDate(date: Date)`: Ends the recurrence on a specific date.

This is useful when setting a limit for how many times the event or reminder should recur.

#### RecurrenceEnd Methods

- **fromCount(count)**: Creates a count-based recurrence end.
  ```ts
  const endByCount = RecurrenceEnd.fromCount(10)
  ```

- **fromDate(date)**: Creates a date-based recurrence end.
  ```ts
  const endByDate = RecurrenceEnd.fromDate(new Date("2024-12-31"))
  ```

### 5. `RecurrenceRule`

`RecurrenceRule` defines the complete pattern for a recurring event or reminder, including its frequency, interval, specific days, months, and an optional end condition.

#### RecurrenceRule Properties

- **identifier**: `string` – Unique identifier for the recurrence rule.
- **frequency**: `RecurrenceFrequency` – Frequency of recurrence (daily, weekly, monthly, yearly).
- **interval**: `number` – Interval between recurrences (e.g., every 2 weeks). Must be greater than 0.
- **recurrenceEnd**: `RecurrenceEnd (optional)` – Specifies the end of the recurrence.
- **firstDayOfTheWeek**: `number` – The day treated as the start of the week.
- **daysOfTheWeek**: `RecurrenceDayOfWeek[] (optional)` – Specific days of the week for the recurrence.
- **daysOfTheMonth**: `number[] (optional)` – Specific days of the month (values from 1 to 31, or -1 to -31).
- **daysOfTheYear**: `number[] (optional)` – Specific days of the year.
- **weeksOfTheYear**: `number[] (optional)` – Specific weeks of the year.
- **monthsOfTheYear**: `number[] (optional)` – Specific months of the year.
- **setPositions**: `number[] (optional)` – Filters recurrences to specific positions within the frequency period.

#### RecurrenceRule Method

- **create(options)**: Creates a `RecurrenceRule` instance using the specified options.
  - **Options**:
    - **frequency**: Frequency of the recurrence (e.g., `daily`, `weekly`).
    - **interval**: Interval for the recurrence (e.g., every 2 days).
    - **daysOfTheWeek**: Array of `RecurrenceDayOfWeek`.
    - **daysOfTheMonth**: Array of specific days in the month.
    - **monthsOfTheYear**: Array of specific months for recurrence.
    - **weeksOfTheYear**: Array of specific weeks for recurrence.
    - **daysOfTheYear**: Array of specific days in the year.
    - **setPositions**: Array of ordinal numbers for filtering recurrences.
    - **end**: Specifies the end of the recurrence rule.

```ts
const rule = RecurrenceRule.create({
  frequency: "monthly",
  interval: 1,
  daysOfTheWeek: [{ weekday: "monday", weekNumber: 1 }],
  end: RecurrenceEnd.fromCount(10)
})
```

## Using Recurrence Types and Classes Together

To create a recurring event or reminder with these types, follow these steps:

1. **Define the Frequency**: Set a `RecurrenceFrequency` to specify how often the event or reminder should occur.
2. **Specify Days or Months**: Use `RecurrenceWeekday`, `RecurrenceDayOfWeek`, `daysOfTheMonth`, etc., to specify exact days.
3. **Set the Interval**: Use `interval` to control how often the event or reminder should recur based on the frequency.
4. **Define the End Condition** (optional): Use `RecurrenceEnd` to specify when the recurrence should stop.
5. **Create the Rule**: Use `RecurrenceRule.create()` with the configured options.

### Example: Recurring Meeting Every Second Tuesday for 6 Months

```ts
const recurrenceRule = RecurrenceRule.create({
  frequency: "monthly",
  interval: 1,
  daysOfTheWeek: [{ weekday: "tuesday", weekNumber: 2 }],
  end: RecurrenceEnd.fromCount(6)
})

// Add recurrenceRule to your event or reminder
event.addRecurrenceRule(recurrenceRule)
await event.save()
```

This example creates a `RecurrenceRule` for an event that occurs every second Tuesday each month, ending after six occurrences.



---
url: /guide/Device Capabilities/Reminder.md
---

# Reminder

The `Reminder` API provides the ability to create, edit, and manage reminders in the iOS calendar system.
It supports configuring due dates through `DateComponents`, assigning priorities, adding notes, managing recurrence rules, working with alarms, and tracking completion state.
This API is suitable for a wide range of task and schedule reminder scenarios.

***

## 1. Class: `Reminder`

The `Reminder` class represents an individual reminder item and provides properties and methods to read and modify its data.

***

## 2. Properties

### identifier: string

A unique identifier assigned by the system (read-only).

### calendar: Calendar | null

The calendar to which the reminder belongs.
The calendar can be null if the reminder is not associated with a calendarm, but you must do not set the calendar to null.

### title: string

The title or summary of the reminder.

### notes: string | null

Optional notes providing additional context.

***

## Completion State

### isCompleted: boolean

Indicates whether the reminder is marked as completed.

- Setting this property to `true` automatically sets `completionDate` to the current date.
- Setting it to `false` sets `completionDate` to `null`.

Special consideration:
If a reminder is completed on another device or client, `isCompleted` may be `true` while `completionDate` remains `null`.

### completionDate: Date | null

The date on which the reminder was completed.

- Assigning a date sets `isCompleted = true`.
- Assigning `null` clears the completed state.

***

## Due Date

### dueDateComponents: DateComponents | null

Represents the reminder’s due date using date components.
Supports partially specified date or time fields.
Useful for date-based or recurring reminders.

You may use `DateComponents.isValidDate` to check whether the components form a valid date.

### dueDate: Date | null

Deprecated.
Use `dueDateComponents` instead.
You can read the equivalent date using `dueDateComponents?.date`.

### dueDateIncludesTime: boolean

Deprecated.
Use `dueDateComponents?.hour != null && dueDateComponents?.minute != null` to determine whether the due date includes a time component.

***

## Priority

### priority: number

An integer representing the reminder’s priority.
Higher values typically indicate greater importance or urgency.

***

## Recurrence

### recurrenceRules: RecurrenceRule\[] | null

An array of recurrence rules associated with the reminder.

### hasRecurrenceRules: boolean

Indicates whether the reminder contains recurrence rules (read-only).

***

## Alarms

### alarms: EventAlarm\[] | null

A collection of alarms associated with the reminder.
Alarms may be based on:

- absolute dates
- relative offsets
- structured locations (geofence triggers)

### hasAlarm: boolean

Indicates whether the reminder contains any alarms.

***

## Attendees

### attendees: EventParticipant\[] | null

An array of attendee objects (read-only).
Not all reminder sources support attendee data.

### hasAttendees: boolean

Indicates whether the reminder has attendees.

***

## State Indicators

### hasNotes: boolean

Indicates whether the reminder contains notes.

### hasChanges: boolean

Indicates whether the reminder or any of its nested objects contains unsaved changes.

***

## 3. Instance Methods

### addAlarm(alarm: EventAlarm): void

Adds an alarm to the reminder.

### removAlarm(alarm: EventAlarm): void

Removes the specified alarm.
(Method name is `removAlarm`.)

***

### addRecurrenceRule(rule: RecurrenceRule): void

Adds a recurrence rule.

### removeRecurrenceRule(rule: RecurrenceRule): void

Removes a recurrence rule.

***

### `save(): Promise<void>`

Saves changes to the reminder.
If the reminder has not been saved before, it is added to its associated calendar.

### `remove(): Promise<void>`

Deletes the reminder from the calendar.

***

## 4. Static Methods

### `Reminder.get(identifier: string): Promise<Reminder | null>`

Returns a reminder by its identifier, or `null` if not found.

***

### `Reminder.getAll(calendars?: Calendar[]): Promise<Reminder[]>`

Returns all reminders, optionally filtered by the specified calendars.

***

### `Reminder.getIncompletes(options?): Promise<Reminder[]>`

Returns incomplete reminders filtered by due date range and/or calendar set.

Options:

- `startDate?: Date`
  Includes reminders whose due date is after this date.

- `endDate?: Date`
  Includes reminders whose due date is before this date.

- `calendars?: Calendar[]`
  Specifies which calendars to search.

This method does not expand recurrence rules; it only returns reminders with concrete due dates.

***

### `Reminder.getCompleteds(options?): Promise<Reminder[]>`

Returns completed reminders filtered by completion date range and/or calendar set.

Options:

- `startDate?: Date`
  Includes reminders completed after this date.

- `endDate?: Date`
  Includes reminders completed before this date.

- `calendars?: Calendar[]`
  Specifies which calendars to search.

***

## 5. Usage Examples

## Creating a Reminder with DateComponents

```ts
const reminder = new Reminder()
reminder.title = "Prepare meeting materials"
reminder.notes = "Finish before Monday’s team meeting"

reminder.dueDateComponents = new DateComponents({
  year: 2025,
  month: 10,
  day: 6,
  hour: 9,
  minute: 30,
})

reminder.priority = 2
await reminder.save()
```

***

## Creating a Date-Only Reminder

```ts
reminder.dueDateComponents = new DateComponents({
  year: 2025,
  month: 10,
  day: 6,
})
```

***

## Creating DateComponents from a Date

```ts
const now = new Date()
reminder.dueDateComponents = DateComponents.fromDate(now)
```

***

## Fetching All Reminders

```ts
const reminders = await Reminder.getAll()
for (const r of reminders) {
  console.log(`Reminder: ${r.title}`)
}
```

***

## Fetching Incomplete Reminders

```ts
const incompletes = await Reminder.getIncompletes({
  startDate: new Date("2025-01-01"),
  endDate: new Date("2025-01-31"),
})
```

***

## Marking a Reminder as Completed

```ts
reminder.isCompleted = true
await reminder.save()
```

***

## Deleting a Reminder

```ts
await reminder.remove()
```

***

## 6. Additional Notes

### Date Management

Using `dueDateComponents` is recommended for all due-date handling.
It supports:

- date-only values
- date with time
- partial components
- validity checks through `isValidDate`

### Recurrence

Reminder queries do not expand recurrence rules.
They operate only on the reminder objects that have concrete due dates.
Recurrence rules can be added or removed through the API.

### Alarms

Alarms may be absolute, relative, or location-based, and are shared with the `CalendarEvent` API.

### Attendees

Some reminder sources do not support attendee data; in such cases, the attendees array may be `null`.



---
url: /guide/Device Capabilities/Safari/index.md
---

# Safari

The `Safari` module provides functions to open and display websites either externally using the system default browser or internally within the Scripting app using an in-app Safari view. It enables seamless web content access in both immersive and external browsing scenarios.

***

## Module: `Safari`

This module includes two functions:

***

### ▸ `Safari.openURL(url: string): Promise<boolean>`

Opens a URL using the system's default method for handling the specified URL scheme. This may launch Safari, another browser, or a different app altogether—depending on the scheme and installed apps.

#### Parameters

- **`url`** (`string`): The URL to open. Can begin with `http://`, `https://`, or any custom URL scheme (e.g., `mailto:`, `tel:`, `appname://`).

#### Returns

- A `Promise<boolean>` that resolves to `true` if the URL was successfully opened, or `false` if it failed (e.g., due to an invalid scheme or unsupported URL).

#### Example

```ts
const success = await Safari.openURL('mailto:hello@example.com')
if (!success) {
  console.error('Failed to open the URL')
}
```

***

### ▸ `Safari.present(url: string, fullscreen?: boolean): Promise<void>`

Presents a web page using an in-app Safari view. The page is shown modally within the Scripting app. The returned Promise resolves only after the user closes the web view.

#### Parameters

- **`url`** (`string`): The website URL to present.
- **`fullscreen`** (`boolean`, optional): Whether to show the view in fullscreen mode. Defaults to `true`.

#### Returns

- A `Promise<void>` that resolves when the user closes the web view.

#### Examples

Present a site in fullscreen (default):

```ts
await Safari.present('https://developer.apple.com')

// Code here runs after the web view is dismissed
console.log('The web view has been closed.')
```

Present a site in a non-fullscreen view (e.g., as part of an embedded interface):

```ts
await Safari.present('https://news.ycombinator.com', false)

// Code here runs after the web view is dismissed
console.log('The web view has been closed.')
```

***

## Use Cases

- Redirecting users to external links such as help docs, authentication pages, or App Store URLs.
- Displaying online content (e.g., blog posts, dashboards) directly in-app.
- Launching another app using its URL scheme.

***

## Notes

- Always provide a valid and fully qualified URL.
- Use `present()` to keep the user within the app.
- Use `openURL()` for external redirection or when launching another app via a URL scheme.



---
url: /guide/Device Capabilities/Safari/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, } from "scripting"

function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"Safari"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Button
        title={"Open URL in system default browser"}
        action={() => {
          Safari.openURL("https://github.com")
        }}
      />

      <Button
        title={"Open URL in-app browser"}
        action={async () => {
          await Safari.present("https://github.com", false)
          console.log("Dismissed")
        }}
      />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/Send Mail.md
---

# Send Mail

The `MailUI` module allows your script to present a native mail compose view, enabling users to send emails with recipients, subject, body, and attachments prefilled. It also provides a way to check whether the device is capable of sending emails.

The original `Mail` module is deprecated and has been replaced by `MailUI`.

***

## `MailUI.isAvailable: boolean`

Returns `true` if the device is configured to send emails using the built-in Mail app.

```ts
if (!MailUI.isAvailable) {
  console.log("Mail is not available on this device.")
}
```

***

## `MailUI.present(options): Promise<"cancelled" | "sent" | "failed" | "saved">`

Presents the system mail composer with the provided options. Users can edit the message, then send, cancel, or save it as a draft.

### Parameters

| Name                           | Type           | Required | Description                                                                                  |
| ------------------------------ | -------------- | -------- | -------------------------------------------------------------------------------------------- |
| `toRecipients`                 | `string[]`     | Yes      | List of email addresses to include in the **To** field.                                      |
| `ccRecipients`                 | `string[]`     | No       | List of email addresses for the **CC** (carbon copy) field.                                  |
| `bccRecipients`                | `string[]`     | No       | List of email addresses for the **BCC** (blind carbon copy) field.                           |
| `preferredSendingEmailAddress` | `string`       | No       | If the user has multiple accounts configured, this can specify the preferred sender's email. |
| `subject`                      | `string`       | No       | Email subject line.                                                                          |
| `body`                         | `string`       | No       | The content of the email body.                                                               |
| `attachments`                  | `Attachment[]` | No       | Array of files to attach to the email.                                                       |

### Attachment Object

Each attachment must include the following fields:

| Property   | Type     | Required | Description                                               |
| ---------- | -------- | -------- | --------------------------------------------------------- |
| `data`     | `Data`   | Yes      | The binary content to attach.                             |
| `mimeType` | `string` | Yes      | The MIME type (e.g., `"image/png"`, `"application/pdf"`). |
| `fileName` | `string` | Yes      | Name of the file as it will appear in the eMailUI.        |

***

### Return Value

Returns a `Promise` that resolves to one of the following result strings:

- `"sent"` – The user sent the email.
- `"cancelled"` – The user cancelled email composition.
- `"failed"` – Sending failed due to an error (e.g., no email account configured).
- `"saved"` – The email was saved as a draft.

***

### Throws

This method will throw an error if:

- `MailUI.isAvailable` is `false`
- The options are malformed or missing required fields

***

## Example: Simple Email

```ts
if (MailUI.isAvailable) {
  const result = await MailUI.present({
    toRecipients: ["user@example.com"],
    subject: "Hello from script",
    body: "This email was sent using the Scripting app!"
  })

  console.log("Result:", result) // sent, cancelled, failed, or saved
}
```

***

## Example: Email with Attachment

```ts
const fileData = Data.fromString("Here is the content of the attached file.")

if (MailUI.isAvailable) {
  const result = await MailUI.present({
    toRecipients: ["user@example.com"],
    subject: "Document attached",
    body: "Please find the document attached.",
    attachments: [
      {
        data: fileData,
        mimeType: "text/plain",
        fileName: "notes.txt"
      }
    ]
  })

  if (result === "sent") {
    console.log("Email successfully sent.")
  } else {
    console.log("Email not sent:", result)
  }
}
```

***

## Notes

- The system mail composer must be presented in an interactive context (not in background-only scripts).
- The user controls the final sending of the message.
- This API requires a properly configured mail account.



---
url: /guide/Device Capabilities/Send Message.md
---

# Send Message

The `MessageUI` namespace provides functions to detect messaging capabilities and present a system message compose view from within a script. You can send SMS or MMS messages with optional subject and attachments, depending on device capabilities.

## Availability Properties

### `MessageUI.isAvailable: boolean`

Returns `true` if the device is capable of sending plain text messages.

```ts
if (!MessageUI.isAvailable) {
  console.log("This device cannot send messages.")
}
```

### `MessageUI.canSendSubject: boolean`

Returns `true` if the device supports adding a **subject** to messages.

### `MessageUI.canSendAttachments: boolean`

Returns `true` if the device supports including **attachments** in messages.

***

## `MessageUI.present(options): Promise<"cancelled" | "sent" | "failed">`

Displays the system’s message composer with the specified content and resolves with the result of the user’s action.

### Parameters

| Name          | Type           | Required | Description                                                               |
| ------------- | -------------- | -------- | ------------------------------------------------------------------------- |
| `recipients`  | `string[]`     | Yes      | An array of recipient phone numbers.                                      |
| `body`        | `string`       | Yes      | The text content of the message body.                                     |
| `subject`     | `string`       | No       | Optional subject line. Ignored if `canSendSubject` is `false`.            |
| `attachments` | `Attachment[]` | No       | Optional list of attachments. Ignored if `canSendAttachments` is `false`. |

### Attachment Object

Each item in the `attachments` array must include:

| Property   | Type     | Required | Description                                                                                                                                               |
| ---------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`     | `Data`   | Yes      | The binary data to be attached to the message.                                                                                                            |
| `type`     | `UTType` | Yes      | A [Uniform Type Identifier](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype) string, such as `"public.image"` or `"public.text"`. |
| `fileName` | `string` | Yes      | The name that will appear for the attachment in the message.                                                                                              |

***

### Return Value

Returns a `Promise` that resolves to one of the following values:

- `"sent"`: The message was successfully sent by the user.
- `"cancelled"`: The user canceled the message.
- `"failed"`: The message failed to send due to an error (e.g., connectivity or system failure).

***

## Example: Basic Text Message

```ts
if (MessageUI.isAvailable) {
  const result = await MessageUI.present({
    recipients: ["1234567890"],
    body: "Hello from Scripting!"
  })

  console.log("Message result:", result) // sent, cancelled, or failed
}
```

***

## Example: Message with Subject and Attachment

```ts
const fileData = Data.fromString("This is the document content.")

if (MessageUI.isAvailable && MessageUI.canSendAttachments) {
  const result = await MessageUI.present({
    recipients: ["1234567890"],
    body: "Here is the document.",
    subject: "Requested File",
    attachments: [
      {
        data: fileData,
        type: "public.text",
        fileName: "document.txt"
      }
    ]
  })

  if (result === "sent") {
    console.log("Message successfully sent.")
  } else {
    console.log("Message was not sent:", result)
  }
}
```

***

## Notes

- The `subject` and `attachments` options are automatically ignored if not supported on the device.
- This API only presents the UI; sending is user-controlled.
- Can only be used in interactive scripts (not background-only scripts).



---
url: /guide/Device Capabilities/ShareSheet.md
---

# ShareSheet

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text } from "scripting"

function Example() {

  return <NavigationStack>
    <List
      navigationTitle={"ShareSheet"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        footer={
          <Text>Present a ShareSheet UI.</Text>
        }
      >
        <Button
          title={"ShareSheet.present"}
          action={async () => {
            // const image = await Photos.getLatestPhotos(1)
            // await ShareSheet.present([image])
            if (await ShareSheet.present(["Hello Scripting!"])) {
              Dialog.alert({
                message: "Share successfully."
              })
            } else {
              Dialog.alert({
                message: "Cancelled"
              })
            }
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/SharedAudioSession.md
---

# SharedAudioSession

The `SharedAudioSession` interface provides a convenient way to manage and interact with the shared audio session in your script. The audio session acts as an intermediary between your script, the Scripting app, the operating system, and the underlying audio hardware, enabling you to configure and control audio behavior effectively.

## Features

- Retrieve and set audio session categories, modes, and options.
- Configure the preferred sample rate for audio input and output.
- Handle audio interruptions.
- Query device capabilities for supported categories and modes.
- Tailor audio behaviors for specific app use cases, such as video recording, voice chat, or background playback.

***

## Methods and Properties

### 1. **Session Category and Options**

#### `category`

Get the current audio session category.

```typescript
const category = await SharedAudioSession.category
console.log(category) // Example: 'playback'
```

#### `categoryOptions`

Retrieve the current audio session category options.

```typescript
const options = await SharedAudioSession.categoryOptions
console.log(options) // Example: ['mixWithOthers', 'allowAirPlay']
```

#### `setCategory(category: AudioSessionCategory, options: AudioSessionCategoryOptions[])`

Set the audio session category with specific options.

```typescript
await SharedAudioSession.setCategory('playback', ['mixWithOthers'])
```

***

### 2. **Session Mode**

#### `mode`

Retrieve the current audio session mode.

```typescript
const mode = await SharedAudioSession.mode
console.log(mode) // Example: 'videoChat'
```

#### `setMode(mode: AudioSessionMode)`

Set the audio session mode.

```typescript
await SharedAudioSession.setMode('voiceChat')
```

***

### 3. **Sample Rate**

#### `preferredSampleRate`

Retrieve the preferred sample rate in hertz.

```typescript
const sampleRate = await SharedAudioSession.preferredSampleRate
console.log(sampleRate) // Example: 44100
```

#### `setPreferredSampleRate(sampleRate: number)`

Set the preferred sample rate for audio input and output.

```typescript
await SharedAudioSession.setPreferredSampleRate(48000)
```

***

### 4. **Interruption Handling**

#### `addInterruptionListener(listener: AudioSessionInterruptionListener)`

Listen for audio interruptions.

```typescript
SharedAudioSession.addInterruptionListener((type) => {
  if (type === 'began') {
    console.log('Audio interruption began')
  } else if (type === 'ended') {
    console.log('Audio interruption ended')
  }
})
```

#### `removeInterruptionListener(listener: AudioSessionInterruptionListener)`

Remove an interruption listener.

```typescript
SharedAudioSession.removeInterruptionListener(myListener)
```

***

### 5. **Device Capabilities**

#### `availableCategories`

Get the list of audio session categories available on the device.

```typescript
const categories = await SharedAudioSession.availableCategories
console.log(categories) // Example: ['playback', 'record', 'soloAmbient']
```

#### `availableModes`

Get the list of audio session modes available on the device.

```typescript
const modes = await SharedAudioSession.availableModes
console.log(modes) // Example: ['default', 'videoChat', 'voiceChat']
```

***

### 6. **Additional Properties**

#### `isOtherAudioPlaying`

Check if other audio is currently playing on the device.

```typescript
const isPlaying = await SharedAudioSession.isOtherAudioPlaying
console.log(isPlaying) // Example: true
```

#### `secondaryAudioShouldBeSilencedHint`

Check if secondary audio should be silenced.

```typescript
const shouldSilence = await SharedAudioSession.secondaryAudioShouldBeSilencedHint
console.log(shouldSilence) // Example: false
```

#### `allowHapticsAndSystemSoundsDuringRecording`

Check if haptics and system sounds are allowed during recording.

```typescript
const allowHaptics = await SharedAudioSession.allowHapticsAndSystemSoundsDuringRecording
console.log(allowHaptics) // Example: true
```

#### `prefersNoInterruptionsFromSystemAlerts`

Check if the session prefers no interruptions from system alerts.

```typescript
const prefersNoInterruptions = await SharedAudioSession.prefersNoInterruptionsFromSystemAlerts
console.log(prefersNoInterruptions) // Example: false
```

***

### 7. **Session Activation**

#### `setActive(active: boolean, options?: AudioSessionSetActiveOptions[])`

Activate or deactivate the shared audio session with optional options.

- `active`: Set to `true` to activate the session, `false` to deactivate it.
- `options`: An array of optional activation options, such as 'interruptSpokenAudioAndMixWithOthers'.

```typescript
await SharedAudioSession.setActive(
  true,
  ['notifyOthersOnDeactivation']
)
```

***

### 8. **System Settings**

#### `setAllowHapticsAndSystemSoundsDuringRecording(value: boolean)`

Enable or disable haptics and system sounds during recording.

```typescript
await SharedAudioSession.setAllowHapticsAndSystemSoundsDuringRecording(true)
```

#### `setPrefersNoInterruptionsFromSystemAlerts(value: boolean)`

Set the preference for no interruptions from system alerts.

```typescript
await SharedAudioSession.setPrefersNoInterruptionsFromSystemAlerts(true)
```

***

### 9. **Audio Routing**

iOS chooses input and output audio routes independently. The APIs below let you list available
input ports, force the recording input to a specific port (typically `builtInMic`), and override
the output to the device speaker — useful when you want to record from the phone microphone while
keeping a Bluetooth headset for playback (avoiding the lower-quality bidirectional Bluetooth HFP
link).

> `setPreferredInput` and `overrideOutputAudioPort` only work after the session is active. Always
> call `setActive(true)` first.

#### `availableInputs`

The list of input ports the system currently exposes for this session. Bluetooth, USB, and headset
microphones only appear when the active category options allow them (e.g. `allowBluetoothHFP`).

```typescript
const inputs = await SharedAudioSession.availableInputs
for (const port of inputs) {
  console.log(port.portType, port.portName, port.uid)
}
```

#### `currentRoute`

The currently selected input and output ports.

```typescript
const route = await SharedAudioSession.currentRoute
console.log('input:', route.inputs[0]?.portType)
console.log('output:', route.outputs[0]?.portType)
```

#### `setPreferredInput(input: AudioSessionPort | null)`

Pick a specific input port. Pass `null` to clear the preference. The argument is matched against
`availableInputs` first by `uid`, then by `portType`. Rejects with `Cannot setPreferredInput before
setActive(true).` if the session is not active.

```typescript
await SharedAudioSession.setActive(true)
const inputs = await SharedAudioSession.availableInputs
const builtIn = inputs.find(p => p.portType === 'builtInMic')
if (builtIn) {
  await SharedAudioSession.setPreferredInput(builtIn)
}
```

#### `overrideOutputAudioPort(port: 'speaker' | 'none')`

Force the output to the device speaker, or remove the override. Independent from input selection.

```typescript
await SharedAudioSession.overrideOutputAudioPort('speaker')
// later
await SharedAudioSession.overrideOutputAudioPort('none')
```

#### `setPrefersBuiltInMicWhenAvailable(enabled: boolean)`

Enable an in-process switch that automatically steers the input back to `builtInMic` whenever it
becomes available, even after a Bluetooth headset, USB mic, or wired headset is plugged in. The
output route is left untouched, which is what enables clean I/O separation: built-in mic for input,
wireless headphones (A2DP) for playback.

The switch is **not persisted** across launches, but it does affect every script running inside the
host app while the host process is alive. Manual `setPreferredInput` calls (route change reason
`override`) are not overwritten by the switch.

Enabling the switch immediately attempts to apply the preference once.

```typescript
await SharedAudioSession.setActive(true)
await SharedAudioSession.setPrefersBuiltInMicWhenAvailable(true)

// Later, query state:
const enabled = await SharedAudioSession.prefersBuiltInMicWhenAvailable
```

#### Route change events

```typescript
SharedAudioSession.addRouteChangeListener((reason, current) => {
  console.log('route changed:', reason)
  console.log('inputs now:', current.inputs.map(p => p.portType))
})
```

`reason` is one of `'newDeviceAvailable' | 'oldDeviceUnavailable' | 'categoryChange' | 'override' | 'wakeFromSleep' | 'noSuitableRouteForCategory' | 'routeConfigurationChange' | 'unknown'`.

***

### 10. **Systemwide Output Volume**

#### `outputVolume: number`

The systemwide output volume. This property is a number between 0 and 1, representing the volume level as a percentage.

#### outputVolume EventListener

Type Definition:

```ts
type AudioSessionOutputVolumeListener = (newValue: number, oldValue: number) => void
```

##### `addOutputVolumeListener(listener: AudioSessionOutputVolumeListener)`

Add an event listener for changes in the systemwide output volume.

```typescript
SharedAudioSession.addOutputVolumeListener((newValue, oldValue) => {
  console.log(`Output volume changed from ${oldValue} to ${newValue}`)
})
```

##### `removeOutputVolumeListener(listener: AudioSessionOutputVolumeListener)`

Remove an event listener for changes in the systemwide output volume.

***

## Enumerations

### **AudioSessionSetActiveOptions**

Optional activation options:

- `'notifyOthersOnDeactivation'`: Notify other audio sessions when deactivating the shared audio session.

### **AudioSessionCategory**

Defines the session's audio category:

- `'ambient'`: Ambient audio, such as background music or ambient sounds.
- `'multiRoute'`: Multi-route audio, such as routing distinct streams of audio data to different output devices at the same time.
- `'playAndRecord'`: Play and record audio, such as voice chat or video conferencing.
- `'playback'`: Playback audio, such as music or sound effects.
- `'record'`: Recording audio, such as voice chat or video conferencing.
- `'soloAmbient'`: Solo ambient audio, such as background music or ambient sounds.

### **AudioSessionCategoryOptions**

Optional behaviors for audio categories:

- `'mixWithOthers'`: Mix with other audio sessions.
- `'duckOthers'`: Duck other audio sessions.
- `'interruptSpokenAudioAndMixWithOthers'`: Interrupt spoken audio and mix with others.
- `'allowBluetooth'`: Allow Bluetooth audio.
- `'allowBluetoothA2DP'`: Allow Bluetooth A2DP audio.
- `'allowAirPlay'`: Allow AirPlay audio.
- `'defaultToSpeaker'`: Default to speaker, even if headphones are connected.
- `'overrideMutedMicrophoneInterruption'`: Override muted microphone interruption.

### **AudioSessionMode**

Specifies the session's mode:

- `'default'`: Default mode.
- `'gameChat'`: Game chat mode.
- `'measurement'`: Measurement mode, such as audio input or output.
- `'moviePlayback'`: Movie playback mode, such as movie content.
- `'spokenAudio'`: Spoken audio mode, such as voice chat.
- `'videoChat'`: Video chat mode, such as video conferencing.
- `'videoRecording'`: Video recording mode, such as video conferencing.
- `'voicePrompt'`: Voice prompt mode, such as text-to-speech.

### **AudioSessionInterruptionType**

Specifies the type of interruption:

- `'began'`
- `'ended'`
- `'unknown'`

***

This interface offers extensive control over audio session management in Scripting, making it suitable for building audio-heavy script like music players and video conferencing tools.



---
url: /guide/Device Capabilities/Speech/index.md
---

# Speech

The `Speech` interface provides a high-level API for text-to-speech (TTS) functionality. This interface allows you to synthesize speech, control playback, and manage speech synthesis settings. Below are the details of the `Speech` API, its methods, properties, and usage examples.

***

## Features Overview

- **Text-to-Speech:** Convert text into speech with customizable options like pitch, rate, and volume.
- **Voice Management:** Choose from available system voices by language or identifier.
- **Markdown Support:** Render text with basic formatting using Markdown.
- **SSML Support:** Drive fine-grained pronunciation, pauses, and prosody with SSML (iOS 16+).
- **Audio Session Management:** Control audio sessions for seamless speech integration with other audio sources.
- **Event Listeners:** Respond to speech synthesis lifecycle events.

***

## Type Definitions

### `SpeechBoundary`

Specifies when to pause or stop speech:

- `'immediate'`: Pause/stop immediately.
- `'word'`: Pause/stop after finishing the current word.

***

### `SpeechSynthesisVoice`

Represents a voice for speech synthesis:

- `identifier`: Unique voice identifier.
- `name`: Display name of the voice.
- `language`: BCP 47 language and locale code.
- `quality`: Voice quality (`'default'`, `'premium'`, `'enhanced'`).
- `gender`: Voice gender (`'male'`, `'female'`, `'unspecified'`).

***

### `SpeechProgressDetails`

Details about progress during speech synthesis:

- `text`: Full text being spoken.
- `start`: Start index of the current word.
- `end`: End index of the current word.
- `word`: The current word being spoken.

***

### `SpeechSynthesisOptions`

Options for customizing speech synthesis:

- `isMarkdown` (optional): Interpret text as Markdown. Mutually exclusive with `isSSML`.
- `isSSML` (optional): Interpret text as an SSML (Speech Synthesis Markup Language) document. The text must be wrapped in a `<speak>...</speak>` root element. Available on iOS 16+. Mutually exclusive with `isMarkdown`.
- `pitch`, `rate`, `volume`: Override global `Speech` values for pitch, rate, and volume.
- `preUtteranceDelay`, `postUtteranceDelay`: Control pauses before and after utterances.
- `voiceIdentifier`, `voiceLanguage`: Override global voice settings.

***

## Static Properties

### Global Speech Settings

- `pitch`: Default pitch value (range: `0.5` to `2.0`; default: `1.0`).
- `rate`: Speech rate (range: `Speech.minSpeechRate` to `Speech.maxSpeechRate`; default: `Speech.defaultSpeechRate`).
- `volume`: Default volume (range: `0.0` to `1.0`; default: `1.0`).
- `preUtteranceDelay`, `postUtteranceDelay`: Global delays before and after utterances.

### Voice and Language

- `speechVoices`: Retrieves all available voices.
- `currentLanguageCode`: The device's current language code.

### Audio Session

- `usesApplicationAudioSession`: Specifies whether the app manages the audio session.

***

## Methods

### Speaking and Synthesis

- `speak(text: string, options?: SpeechSynthesisOptions): Promise<void>`\
  Adds text to the speech queue for synthesis.

- `synthesizeToFile(text: string, filePath: string, options?: SpeechSynthesisOptions): Promise<void>`\
  Synthesizes text to an audio file in the documents directory.

### Playback Control

- `pause(at?: SpeechBoundary): Promise<boolean>`\
  Pauses speech at the specified boundary. Defaults to "immediate".

- `resume(): Promise<boolean>`\
  Resumes speech from the paused state.

- `stop(at?: SpeechBoundary): Promise<boolean>`\
  Stops speech at the specified boundary. Defaults to "immediate".

### State Management

- `isSpeaking`: Checks if the synthesizer is speaking or paused.
- `isPaused`: Checks if the synthesizer is in a paused state.

### Voice Management

- `setVoiceByIdentifier(identifier: string): Promise<boolean>`\
  Sets a voice by its identifier.

- `setVoiceByLanguage(language: string): Promise<boolean>`\
  Sets a voice by its language code.

***

## Event Listeners

### Supported Events

- `start`: Speech synthesis starts.
- `pause`: Speech pauses.
- `continue`: Speech resumes.
- `finish`: Speech finishes.
- `cancel`: Speech is canceled.
- `progress`: Provides progress details (`SpeechProgressDetails`).

### Managing Listeners

- `addListener(event: string, listener: Function): void`\
  Adds an event listener.

- `removeListener(event: string, listener: Function): void`\
  Removes an event listener.

***

## Examples

### Setup `SharedAudioSession`

```ts
await SharedAudioSession.setActive(true)
await SharedAudioSession.setCategory(
  "playback",
  ["mixWithOthers"]
)
```

### Speak Text

```ts
await Speech.speak("Hello, world!")
```

### Speak with Custom Options

```ts
await Speech.speak("Welcome to **Scripting**", {
  isMarkdown: true,
  pitch: 1.5,
  rate: 0.8,
  voiceLanguage: "en-US",
})
```

### Synthesize to File

```ts
import { Path } from "scripting"

const filePath = Path.join(FileManager.documentDirectory, "output.caf")
await Speech.synthesizeToFile("Saving to file.", filePath, { rate: 1.0 })
```

### Control Playback

```ts
await Speech.speak("Pausing example...")
await Speech.pause("word")
await Speech.resume()
await Speech.stop() // Defaults stop "immediately".
```

### Add Progress Listener

```ts
Speech.addListener("progress", (details) => {
  console.log(`Speaking: ${details.word}`)
});
await Speech.speak("Event listening example.")
Speech.removeListener("progress", listener)
```

### Speak SSML (iOS 16+)

SSML lets you control pauses, prosody, pronunciation, and substitutions inline. Wrap the markup in a single `<speak>` root and pass `isSSML: true`.

Inline SSML tags (e.g. `<prosody>`, `<voice>`, `<break>`) take precedence; the utterance-level `voice` / `rate` / `pitch` / `volume` options still apply as fallbacks for any text that is not overridden by inline tags.

If the SSML cannot be parsed, the promise rejects with `"Failed to parse SSML representation."`. Passing both `isMarkdown: true` and `isSSML: true` rejects the promise with a usage error.

```ts
await Speech.speak(
  `<speak>
     Hello
     <break time="500ms" />
     <prosody rate="150%">nice to meet you!</prosody>
     <sub alias="World Wide Web Consortium">W3C</sub>
   </speak>`,
  { isSSML: true }
)
```

Supported SSML tags include `<speak>`, `<break>`, `<prosody>`, `<sub>`, `<phoneme>`, and others documented by Apple. See [`AVSpeechUtterance.init(ssmlRepresentation:)`](https://developer.apple.com/documentation/avfaudio/avspeechutterance/init\(ssmlrepresentation:\)) for details.



---
url: /guide/Device Capabilities/Speech/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Path, Script, Section, Text, } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <List
      navigationTitle={"Speech Example"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section
        footer={
          <Text>Activate the SharedAudioSeesion, and speak a text.</Text>
        }
      >
        <Button
          title={"Speak a text"}
          action={async () => {
            console.present()
            if (await Speech.isSpeaking) {
              await Speech.stop('immediate')
              console.log("Stopped.")
              return
            }

            await SharedAudioSession.setActive(true)
            await SharedAudioSession.setCategory('playback', ['mixWithOthers'])

            const listener = () => {
              console.log("Speak completed!")
              Speech.removeListener('finish', listener)
            }

            Speech.addListener('finish', listener)

            await Speech.speak('Hi there, welcome to Scripting! I wish this app is helpful to you.', {
              voiceLanguage: 'en-US',
            })

            console.log("Started, tap the run button to stop.")
          }}
        />
      </Section>
      <Section
        footer={
          <Text>Synthesize text to the file stored in local documents directory.</Text>
        }
      >
        <Button
          title={"synthesize to File"}
          action={async () => {
            console.present()
            const filePath = Path.join(FileManager.documentsDirectory, 'greeting.caf')
            const listener = () => {
              if (FileManager.existsSync(filePath)) {
                console.log("Audio file is saved to " + filePath + ". Start to play it.")

                let player = new AVPlayer()
                player.setSource(filePath)
                player.onReadyToPlay = () => {
                  player.play()
                }
                player.onEnded = () => {
                  player.dispose()
                }
              } else {
                console.log("Failed to save audio file.")
              }
              Speech.removeListener('finish', listener)
            }

            Speech.addListener('finish', listener)

            await Speech.synthesizeToFile(
              'Hi there, welcome to Scripting! I wish this app is helpful to you.',
              filePath, {
              voiceLanguage: 'en-US',
            })
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/SpeechRecognition/index.md
---

# SpeechRecognition

The `SpeechRecognition` interface provides a high-level API for performing speech recognition. It supports real-time speech recognition and recognition of audio files, offering flexibility in a variety of use cases.

***

## Features Overview

- **Real-Time Recognition:** Transcribe live audio from the microphone.
- **File-Based Recognition:** Analyze and transcribe recorded audio files.
- **Multi-Language Support:** Specify the recognition locale for different languages.
- **Intermediate Results:** Access partial and final results for progressive transcription.
- **Custom Callbacks:** Handle transcription results and sound level changes with event listeners.

***

## Type Definitions

### `RecognitionTaskHint`

Hints for the type of task for which speech recognition is used:

- `'confirmation'`: For commands like "yes," "no," or "maybe."
- `'dictation'`: For tasks similar to keyboard dictation.
- `'search'`: For identifying search terms.
- `'unspecified'`: For general-purpose speech recognition.

***

### `SpeechRecognitionResult`

Represents the result of speech recognition:

- `isFinal`: Indicates if the transcription is complete and final.
- `text`: Convenience alias for `bestTranscription.formattedString`, kept for backward compatibility.
- `bestTranscription`: The transcription with the highest confidence level (`SpeechTranscription`).
- `transcriptions`: Alternative transcriptions of the audio, sorted in descending order of confidence (`SpeechTranscription[]`).
- `metadata`: Aggregate speech metrics. Only available on final results (iOS 14.5+) (`SpeechRecognitionMetadata`).

***

### `SpeechTranscription`

A transcription of recognized speech:

- `formattedString`: The entire transcription formatted into a single, user-displayable string.
- `segments`: The individual word/utterance segments that compose this transcription (`SpeechTranscriptionSegment[]`).

> Speaking rate and average pause duration are reported on `SpeechRecognitionResult.metadata` instead, and only on final results.

***

### `SpeechTranscriptionSegment`

A single segment within a transcription, typically corresponding to a word:

- `substring`: The text content of this segment.
- `substringRange`: The UTF-16 character range of `substring` within the parent transcription's `formattedString` (`{ location: number, length: number }`).
- `timestamp`: The seconds offset, relative to the audio start, at which this segment was spoken.
- `duration`: The duration in seconds of this segment within the audio.
- `confidence`: Confidence in the accuracy of this segment, in `[0.0, 1.0]`. Only meaningful on final results; partial results typically report `0`.
- `alternativeSubstrings`: Alternative substrings the recognizer also considered for this segment.

***

### `SpeechRecognitionMetadata`

Aggregate speech metrics for a final recognition result:

- `speakingRate`: Speaking rate in words per minute.
- `averagePauseDuration`: Average pause duration in seconds between words.
- `speechStartTimestamp`: Seconds offset within the audio at which the user started speaking.
- `speechDuration`: Duration in seconds of the spoken speech.

***

## Static Properties

### Supported Locales

- `supportedLocales`: Returns a list of locales supported by the speech recognizer, such as `"en-US"`, `"fr-FR"`, or `"zh-CN"`.

### Recognition State

- `isRecognizing`: Indicates whether a recognition request is currently active.

***

## Methods

### Start Real-Time Recognition

`start(options: object): Promise<boolean>`\
Starts speech recognition from the device microphone.

#### Options

- `locale`: Locale string for the desired language (optional).
- `partialResults`: Return intermediate results (default: `true`).
- `addsPunctuation`: Automatically add punctuation to results (default: `false`).
- `requestOnDeviceRecognition`: Keep audio data on the device (default: `false`).
- `taskHint`: Specify the recognition task type (`'confirmation'`, `'dictation'`, `'search'`, `'unspecified'`).
- `useDefaultAudioSessionSettings`: Use default audio session settings (default: `true`).
- `preferredInput`: Preferred audio input port. `'auto'` (default) lets the system choose;
  `'builtInMic'` forces the device's built-in microphone even when a Bluetooth headset is
  connected — useful for keeping wireless headphones for playback while recording from the
  built-in mic for better audio quality. Falls back silently to the system default when
  `builtInMic` is not available on the device.
- `onResult`: Callback for recognition results (`SpeechRecognitionResult`).
- `onSoundLevelChanged`: Callback for sound level changes (optional).

#### Example

```ts
await SpeechRecognition.start({
  locale: "en-US",
  partialResults: true,
  addsPunctuation: true,
  onResult: (result) => {
    console.log("Transcription:", result.text)
  },
  onSoundLevelChanged: (level) => {
    console.log("Sound Level:", level)
  }
})
```

***

### Recognize Speech in Audio Files

`recognizeFile(options: object): Promise<boolean>`\
Starts recognition for a recorded audio file.

#### Options

- `filePath`: Path to the audio file.
- `locale`: Locale string for the desired language (optional).
- `partialResults`: Return intermediate results (default: `false`).
- `addsPunctuation`: Automatically add punctuation to results (default: `false`).
- `requestOnDeviceRecognition`: Keep audio data on the device (default: `false`).
- `taskHint`: Specify the recognition task type (`'confirmation'`, `'dictation'`, `'search'`, `'unspecified'`).
- `onResult`: Callback for recognition results (`SpeechRecognitionResult`).

#### Example

```ts
await SpeechRecognition.recognizeFile({
  filePath: FileManager.join(FileManager.documentDirectory, "example.wav"),
  locale: "en-US",
  addsPunctuation: true,
  onResult: (result) => {
    console.log("File Transcription:", result.text)
  }
})
```

***

### Stop Recognition

`stop(): Promise<void>`\
Stops an active speech recognition session.

#### Example

```ts
await SpeechRecognition.stop()
```

***

## Examples

### Real-Time Recognition with Progress Updates

```ts
await SpeechRecognition.start({
  locale: "en-US",
  onResult: (result) => {
    console.log(result.isFinal ? "Final Result:" : "Partial Result:", result.text)
  },
  onSoundLevelChanged: (level) => {
    console.log("Sound Level:", level)
  }
})
```

### Recognize Audio File

```ts
await SpeechRecognition.recognizeFile({
  filePath: FileManager.join(FileManager.documentDirectory, "audio.m4a"),
  partialResults: false,
  onResult: (result) => {
    console.log("File recognition completed. Transcription:", result.text)
  }
})
```

### Inspect Word-Level Timing and Alternatives

```ts
await SpeechRecognition.recognizeFile({
  filePath: FileManager.join(FileManager.documentDirectory, "audio.m4a"),
  partialResults: false,
  onResult: (result) => {
    if (!result.isFinal) return

    for (const segment of result.bestTranscription.segments) {
      console.log(
        `[${segment.timestamp.toFixed(2)}s + ${segment.duration.toFixed(2)}s] `
          + `${segment.substring} (confidence ${segment.confidence.toFixed(2)})`
      )
      if (segment.alternativeSubstrings.length > 0) {
        console.log("  alternatives:", segment.alternativeSubstrings.join(", "))
      }
    }

    if (result.metadata) {
      console.log("Speaking rate (wpm):", result.metadata.speakingRate)
      console.log("Speech duration (s):", result.metadata.speechDuration)
    }

    if (result.transcriptions.length > 1) {
      console.log("Alternative transcriptions:")
      for (const t of result.transcriptions.slice(1)) {
        console.log(" -", t.formattedString)
      }
    }
  }
})
```

***

### Stop Active Recognition

```ts
if (await SpeechRecognition.start({
  // ...
})) {
  // Stop after 10 seconds.
  setTimeout(() => {
    await SpeechRecognition.stop()
  }, 10 * 1000)
}

```

***

## Notes

- Ensure the necessary microphone or file access permissions are granted before using this API.
- Use `supportedLocales` to determine available languages for recognition.
- For optimal performance, use audio files in formats supported by iOS (e.g., `.wav`, `.m4a`).



---
url: /guide/Device Capabilities/SpeechRecognition/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text, } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <List
      navigationTitle={"SpeechRecognition"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section
        footer={
          <Text>Returns the list of locales that are supported by the speech recognizer.</Text>
        }
      >
        <Button
          title={"SpeechRecognition.supportedLocales"}
          action={() => {
            console.clear()
            console.present()
            console.log(JSON.stringify(SpeechRecognition.supportedLocales, null, 2))
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Returns a boolean that indicates whether the recognizer is running.</Text>
        }
      >
        <Button
          title={"SpeechRecognition.isRecognizing"}
          action={() => {
            console.clear()
            console.present()
            console.log(
              "SpeechRecognition.isRecognizing",
              SpeechRecognition.isRecognizing
            )
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Start a speech audio buffer recognition request. Return a boolean value that indicates whether the operation was successfully.</Text>
        }
      >
        <Button
          title={"SpeechRecognition.start"}
          action={async () => {
            console.clear()
            console.present()
            console.log("Speech recognizing is started, it will stop after 5s.")

            if (await SpeechRecognition.start({
              locale: "en-US",
              partialResults: false,
              onResult: result => {
                console.log("Result: " + result.text)
              }
            })) {
              setTimeout(async () => {
                await SpeechRecognition.stop()
                console.log("Stoped")
              }, 5000)
            } else {
              console.error("Failed to start recognizing")
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Start a request to recognize speech in a recorded audio file.</Text>
        }
      >
        <Button
          title={"SpeechRecognition.recognizeFile"}
          action={async () => {
            console.clear()
            console.present()
            console.log("SpeechRecognition is started, it will stop after 5s.")

            let audioFilePathToRecognize = await DocumentPicker.pickFiles({
              types: ["public.audio"]
            })

            if (audioFilePathToRecognize.length === 0) {
              console.log("Please pick a audio file.")
              return
            }

            if (await SpeechRecognition.recognizeFile({
              filePath: audioFilePathToRecognize[0],
              partialResults: true,
              onResult: (result) => {
                console.log("Recognized result: " + result.text)
              }
            })) {
              console.log("Started recognizing file...")
            } else {
              console.error("Failed to start recognizing",)
            }
          }}
        />
      </Section>

      <Section
        footer={
          <Text>Stop speech recognition request. Return a boolean value that indicates whether the operation was successfully.</Text>
        }
      >
        <Button
          title={"SpeechRecognition.stop"}
          action={async () => {
            if (SpeechRecognition.isRecognizing) {
              await SpeechRecognition.stop()
              Dialog.alert({
                message: "SpeechRecognition is stopped."
              })
            } else {
              Dialog.alert({
                message: "No progressing recognition."
              })
            }
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}


async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/Spotlight.md
---

# Spotlight

`Spotlight` lets scripts add their own resources to the system Spotlight index. When the user taps one of those results, Scripting runs the same script's `spotlight.tsx` file.

Spotlight indexing requires Scripting PRO.

## Index Items

```ts
await Spotlight.index({
  id: "note-42",
  title: "Project Notes",
  contentDescription: "Open the project note from Spotlight.",
  keywords: ["notes", "project"],
  parameters: {
    noteID: "42",
    source: "spotlight"
  }
})
```

`id` is local to the current script. Calling `Spotlight.index` again with the same `id` updates the existing item.

```ts
await Spotlight.indexItems([
  {
    id: "task-1",
    title: "Follow up"
  },
  {
    id: "task-2",
    title: "Send invoice",
    parameters: { invoiceID: "2026-001" }
  }
])
```

## Item Fields

Only `id` and `title` are required. Apart from the two Scripting-only fields below, every field maps 1:1 to a property of Apple's [`CSSearchableItemAttributeSet`](https://developer.apple.com/documentation/corespotlight/cssearchableitemattributeset) and is grouped here the same way Apple documents them.

**Scripting-only**

- `id` _(required)_ — Script-local identifier, unique within the current script. Returned as `Spotlight.current.id` when the result is tapped.
- `parameters` — Arbitrary JSON delivered to `spotlight.tsx` as `Spotlight.current.parameters`. This is not a Spotlight metadata field; it is how you pass context to your tap handler.

**General**

- `title` _(required)_ — Primary title shown in the result.
- `displayName` — Display name; falls back to `title` when omitted.
- `alternateNames` — Other names the item can also be found by.
- `contentType` — Uniform Type Identifier (`UTType`) used to pick the result icon, e.g. `"public.image"`, `"com.adobe.pdf"`, `"public.movie"`, `"public.folder"`. Defaults to plain text.
- `contentURL` — URL of the underlying content; use a `file://` URL for local content.
- `thumbnailData` — Thumbnail image bytes. Takes priority over `thumbnailURL`.
- `thumbnailURL` — Local file URL string pointing to a thumbnail image.
- `keywords` — Extra terms the item should match against.
- `rankingHint` — Higher numbers rank the item higher among results.
- `supportsNavigation` — Marks the item as navigable; pair with `latitude` / `longitude`.
- `supportsPhoneCall` — Marks the item as callable; pair with `phoneNumbers`.

**Documents**

- `contentDescription` — Longer description shown under the title.
- `subject` — Subject of the content.
- `kind` — Human-readable kind, e.g. `"Note"`, `"Invoice"`.
- `creator` — Entity that created the content.
- `pageCount` — Number of pages.
- `fileSize` — Content size in bytes.

**Messaging**

- `textContent` — Full searchable body text; improves recall for free-text queries.
- `authorNames` — Author display names.
- `emailAddresses` — Associated email addresses.
- `phoneNumbers` — Associated phone numbers.

**Media**

- `comment` — Free-form comment.
- `contentCreationDate` — Creation date. Defaults to the first index time when omitted.
- `contentModificationDate` — Modification date. Defaults to the last index time when omitted.
- `lastUsedDate` — When the item was last used.

**Events**

- `startDate` / `endDate` — For event-like items.
- `dueDate` / `completionDate` — For task-like items.
- `allDay` — Whether the event spans the whole day.

**Places**

- `latitude` / `longitude` / `altitude` — Coordinates, in degrees / degrees / meters.
- `namedLocation` — Human-readable place name.
- `city` / `stateOrProvince` / `country` / `postalCode` / `fullyFormattedAddress` — Address components.

**Item-level**

- `expirationDate` — When Spotlight should drop the item from the index. Omit it to keep the item indexed until you delete it explicitly.

Notes:

- **Dates** (`contentCreationDate`, `lastUsedDate`, `startDate`, `expirationDate`, ...) accept a `Date`, an ISO-8601 string, or a numeric timestamp in seconds.
- **Thumbnails**: `thumbnailData` wins over `thumbnailURL` when both are set.

A full example touching every group:

```ts
await Spotlight.index({
  id: "doc-7",
  parameters: { reportID: "q3" },

  // General
  title: "Q3 Report",
  displayName: "Q3 Report",
  alternateNames: ["Quarterly Report"],
  contentType: "com.adobe.pdf",
  contentURL: "file:///path/to/report.pdf",
  thumbnailData: Data.fromFile("/path/to/thumb.png") ?? undefined,
  thumbnailURL: "/path/to/thumb.png",
  keywords: ["report", "finance"],
  rankingHint: 10,
  supportsNavigation: false,
  supportsPhoneCall: false,

  // Documents
  contentDescription: "Quarterly financials.",
  subject: "Finance",
  kind: "Report",
  creator: "Finance Team",
  pageCount: 12,
  fileSize: 204800,

  // Messaging
  textContent: "Full searchable body text...",
  authorNames: ["Jane Doe"],
  emailAddresses: ["jane@example.com"],
  phoneNumbers: ["+1-555-0100"],

  // Media
  comment: "Reviewed",
  contentCreationDate: new Date(),
  contentModificationDate: new Date(),
  lastUsedDate: Date.now(),

  // Events
  startDate: "2026-07-01T00:00:00Z",
  endDate: "2026-09-30T00:00:00Z",
  dueDate: new Date(),
  completionDate: new Date(),
  allDay: false,

  // Places
  latitude: 37.3349,
  longitude: -122.009,
  altitude: 30,
  namedLocation: "Apple Park",
  city: "Cupertino",
  stateOrProvince: "CA",
  country: "USA",
  postalCode: "95014",
  fullyFormattedAddress: "1 Apple Park Way, Cupertino, CA 95014",

  // Item-level
  expirationDate: new Date(),
})
```

## Search Reliability

How well an item surfaces is decided by the system, not by Scripting. A few things help:

- **Put every searchable term in `keywords` as a separate entry.** Spotlight matches whole words and word _prefixes_, not arbitrary substrings — searching `"part"` will match `"partner"` but searching `"art"` will not match it. For dictionary-style data, add each spelling, inflection, and alternate form as its own keyword (e.g. `["run", "runs", "running", "ran"]`).
- **Keep `title` short and exact.** It is the strongest matching field; put the canonical term there and push variants into `keywords` / `alternateNames`.
- **Use `rankingHint`** (higher = earlier) to bias ranking _among your own items_.
- **`textContent`** improves recall for longer free-text queries (definitions, body text).

Limitations to be aware of:

- Spotlight does not do substring/fuzzy matching, so mid-word or partial queries may not match. Add explicit prefixes as keywords if you need them.
- Apple's built-in results (Dictionary, Contacts, etc.) are privileged system data sources and are ranked separately. Custom items generally cannot outrank them for short, common words, no matter how they are tagged.

## Large Indexes

`indexItems` accepts large arrays and submits them to the system in batches; you can index several thousand items per script. `await` the call — it resolves once the work is handed to Spotlight, and awaiting is the recommended way to know indexing finished and to catch errors. Updating an existing `id` overwrites the previous item, so re-indexing is safe to call repeatedly.

## Handle Taps

Create a `spotlight.tsx` file in the script project:

```ts
const item = Spotlight.current

if (item) {
  console.log(item.id)
  console.log(JSON.stringify(item.parameters))
}
```

`Spotlight.current` is `null` in other script environments. It is available when `spotlight.tsx` is launched from a Spotlight result.

Spotlight tap parameters are not exposed through `Script.queryParameters`.

## Manage Items

```ts
const items = await Spotlight.getItems()

await Spotlight.delete("note-42")
await Spotlight.deleteItems(["task-1", "task-2"])
await Spotlight.deleteAll()
```

Users can also manage indexed items from Tools > Spotlight, including deleting entries whose script or `spotlight.tsx` file no longer exists.



---
url: /guide/Device Capabilities/SystemMusicPlayer.md
---

# SystemMusicPlayer

The `SystemMusicPlayer` module provides control over the system-level music player. It is built on top of `MPMusicPlayerController.systemMusicPlayer`, which shares the playback queue and playback state with the system Music app.

This module allows scripts to:

- Control system music playback
- Set and manage the playback queue
- Control playback time, rate, repeat, and shuffle modes
- Observe playback state changes
- Access information about the currently playing item

Important notes:

- The user must grant media library access.
- Playing Apple Music content may require an active subscription.
- All operations affect the global system music player.

***

## Data Models

### PlaybackState

Represents the current playback state.

```ts
type PlaybackState =
  | "stopped"
  | "playing"
  | "paused"
  | "interrupted"
  | "seekingForward"
  | "seekingBackward"
```

Descriptions:

- `stopped`: Playback is stopped
- `playing`: Currently playing
- `paused`: Paused
- `interrupted`: Interrupted by system events (e.g. phone call)
- `seekingForward`: Fast-forwarding
- `seekingBackward`: Rewinding

***

### RepeatMode

Defines the repeat mode.

```ts
type RepeatMode =
  | "none"
  | "one"
  | "all"
  | "default"
```

Descriptions:

- `none`: No repeat
- `one`: Repeat current item
- `all`: Repeat entire queue
- `default`: Use system default

***

### ShuffleMode

Defines the shuffle mode.

```ts
type ShuffleMode =
  | "off"
  | "songs"
  | "albums"
  | "default"
```

Descriptions:

- `off`: Shuffle disabled
- `songs`: Shuffle songs
- `albums`: Shuffle albums
- `default`: Use system default

***

### NowPlayingItem

Represents the currently playing item.

```ts
type NowPlayingItem = {
  persistentID: string
  title: string
  playbackDuration: number
  playbackStoreID?: string
  artist?: string
  albumTitle?: string
  albumArtist?: string
  genre?: string
  composer?: string
}
```

Field descriptions:

- `persistentID`: Unique local media identifier
- `title`: Song title
- `playbackDuration`: Duration in seconds
- `playbackStoreID`: Apple Music Store ID (if available)
- Other fields are similar to `MediaLibrary.Item`

***

## Setting the Playback Queue

### setQueueByStoreIDs

Sets the playback queue using Apple Music Store IDs.

```ts
function setQueueByStoreIDs(options: {
  storeIDs: string[]
  startItemID?: string
  startTime?: number
}): Promise<void>
```

Parameters:

- `storeIDs`: Array of Apple Music Store IDs
- `startItemID`: Optional ID of the item to start playback from
- `startTime`: Optional starting playback time in seconds

Example:

```ts
await SystemMusicPlayer.setQueueByStoreIDs({
  storeIDs: ["123456789", "987654321"],
  startItemID: "123456789",
  startTime: 30
})

await SystemMusicPlayer.play()
```

***

### setQueueByPersistentIDs

Sets the playback queue using local media `persistentID` values.

```ts
function setQueueByPersistentIDs(options: {
  persistentIDs: string[]
  startItemID?: string
  startTime?: number
}): Promise<void>
```

Example:

```ts
await SystemMusicPlayer.setQueueByPersistentIDs({
  persistentIDs: ["111", "222", "333"],
  startItemID: "222"
})

await SystemMusicPlayer.play()
```

Recommended usage:

- Combine with `MediaLibrary.getSongs()` to build a queue from local content.

***

## Playback Controls

### prepare

Prepares the current playback queue.

```ts
function prepare(): Promise<void>
```

Typically called before `play()`.

***

### play

Starts playback.

```ts
function play(): Promise<void>
```

***

### pause

Pauses playback.

```ts
function pause(): Promise<void>
```

***

### stop

Stops playback.

```ts
function stop(): Promise<void>
```

***

### skipToNextItem

Skips to the next item in the queue.

```ts
function skipToNextItem(): Promise<void>
```

***

### skipToPreviousItem

Skips to the previous item.

```ts
function skipToPreviousItem(): Promise<void>
```

***

### seek

Seeks to a specific time in the current item.

```ts
function seek(to: number): Promise<void>
```

Parameter:

- `to`: Time in seconds

Example:

```ts
await SystemMusicPlayer.seek(60)
```

***

### setCurrentPlaybackTime

Sets the current playback time.

```ts
function setCurrentPlaybackTime(seconds: number): Promise<void>
```

***

### setCurrentPlaybackRate

Sets the playback rate.

```ts
function setCurrentPlaybackRate(rate: number): Promise<void>
```

Example:

```ts
await SystemMusicPlayer.setCurrentPlaybackRate(1.5)
```

***

### setRepeatMode

Sets the repeat mode.

```ts
function setRepeatMode(mode: RepeatMode): Promise<void>
```

***

### setShuffleMode

Sets the shuffle mode.

```ts
function setShuffleMode(mode: ShuffleMode): Promise<void>
```

***

## Playback State Accessors

### indexOfNowPlayingItem

Returns the index of the current item in the queue.

```ts
function indexOfNowPlayingItem(): number
```

***

### getNowPlayingItem

Returns the currently playing item.

```ts
function getNowPlayingItem(): NowPlayingItem | null
```

Example:

```ts
const item = SystemMusicPlayer.getNowPlayingItem()

if (item) {
  console.log(item.title)
}
```

***

### getPlaybackState

Returns the current playback state.

```ts
function getPlaybackState(): PlaybackState
```

***

### getCurrentPlaybackTime

Returns the current playback time in seconds.

```ts
function getCurrentPlaybackTime(): number
```

***

### getCurrentPlaybackRate

Returns the current playback rate.

```ts
function getCurrentPlaybackRate(): number
```

***

### getRepeatMode

Returns the current repeat mode.

```ts
function getRepeatMode(): RepeatMode
```

***

### getShuffleMode

Returns the current shuffle mode.

```ts
function getShuffleMode(): ShuffleMode
```

***

## Event Handling

### EventType

```ts
type EventType =
  | "playbackStateDidChange"
  | "nowPlayingItemDidChange"
  | "volumeDidChange"
```

***

### addEventListener

Adds an event listener.

```ts
function addEventListener<T extends EventType>(
  type: T,
  listener: (payload: any) => void
): void
```

Example:

```ts
SystemMusicPlayer.addEventListener(
  "playbackStateDidChange",
  state => {
    console.log("Playback state:", state)
  }
)

SystemMusicPlayer.addEventListener(
  "nowPlayingItemDidChange",
  item => {
    if (item) {
      console.log("Now playing:", item.title)
    }
  }
)
```

***

### removeEventListener

Removes an event listener.

```ts
function removeEventListener<T extends EventType>(
  type: T,
  listener: (payload: any) => void
): void
```

***

## Best Practices

- After setting a queue, call `prepare()` before `play()`.
- Listen to `nowPlayingItemDidChange` to update UI reactively.
- Use `persistentID` as a stable identifier rather than relying on queue index.
- Avoid frequently resetting the queue with `setQueue...`, as it replaces the entire playback queue.
- Remember that this is a global system music player; changes affect system-wide playback.



---
url: /guide/Device Capabilities/Translation.md
---

# Translation

The `Translation` API enables text translation between different languages. It supports both individual and batch translation use cases and is available on **iOS 18.0 or later**.

## Overview

The API is exposed as a `Translation` class, which includes:

- A shared singleton instance for global use
- Methods for translating single or multiple strings
- Support for automatic language detection based on user preferences

***

## Class: `Translation`

### `Translation.shared: Translation`

Provides a shared singleton instance of the `Translation` class. This is useful in scripts that do not have a UI or need to reuse a common translation host.

#### Example

```ts
const translated = await Translation.shared.translate({
  text: "Hello, world!",
  source: "en",
  target: "es"
})

console.log(translated) // Output: "¡Hola, mundo!"
```

***

### Method: `translate(options): Promise<string>`

Translates a single string from a source language to a target language.

#### Parameters

- `options.text: string`
  The input string to be translated.

- `options.source?: string`
  The source language code (e.g., `"en"` for English). If omitted or `null`, the translation system will attempt to detect the source language automatically. If detection is ambiguous, the user may be prompted to clarify.

- `options.target?: string`
  The target language code (e.g., `"es"` for Spanish). If omitted or `null`, the system will choose an appropriate target language based on the device’s `Device.preferredLanguages` and the detected source language.

#### Returns

- `Promise<string>` — A promise that resolves to the translated string.

#### Throws

- An error if the translation fails (e.g., network issues, unsupported languages, etc.).

#### Example

```ts
const translated = await Translation.shared.translate({
  text: "Good morning",
  target: "fr"
})

console.log(translated) // Output: "Bonjour"
```

***

### Method: `translateBatch(options): Promise<string[]>`

Translates an array of strings from a source language to a target language.

#### Parameters

- `options.texts: string[]`
  An array of strings to translate. The order of translations in the result matches the input array.

- `options.source?: string`
  The source language code. Behaves the same as in the `translate` method.

- `options.target?: string`
  The target language code. Behaves the same as in the `translate` method.

#### Returns

- `Promise<string[]>` — A promise that resolves to an array of translated strings.

#### Throws

- An error if any part of the batch translation fails.

#### Example

```ts
const results = await Translation.shared.translateBatch({
  texts: ["Hello", "Good night", "Thank you"],
  source: "en",
  target: "ja"
})

console.log(results)
// Output: ["こんにちは", "おやすみなさい", "ありがとう"]
```

***

## Notes

- Language codes should follow [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format (e.g., `"en"`, `"zh"`, `"de"`, `"fr"`).

- This API leverages system-level translation capabilities and may prompt for language disambiguation in certain cases.

- Use the `translationHost` view modifier in the following scenarios:

  - **Interactive Translations in UI Views**
    When your script presents a user interface (e.g., using `<VStack>`, `<List>`, etc.) and performs translations using a custom `Translation` instance (created via `new Translation()`), you **must** apply `translationHost` to the root view to allow the system to display permission dialogs, language download prompts, or source language selection alerts.

  - **Source Language Is `null`**
    If you omit the `source` field in your translation request and rely on the system to detect the language, `translationHost` ensures the system can prompt the user if detection fails.

  - **Languages May Need Downloading**
    If the device does not have the required source or target language installed, `translationHost` enables system prompts to download those languages interactively.

- You do **not** need to set `translationHost` when using the pre-bound `Translation.shared` instance in a headless or background script that does not render a user interface.



---
url: /guide/Device Capabilities/VideoRecorder/VideoRecorder/index.md
---

# VideoRecorder

`VideoRecorder` is a high-level video capture and recording module provided by Scripting.
It encapsulates complex AVFoundation details such as `AVCaptureSession` management, audio/video synchronization, orientation handling, encoding, and pause/resume timelines, and exposes a **state-driven**, script-friendly API.

Typical use cases include:

- Video recording with pause and resume
- Synchronized audio capture
- High frame rate and high bitrate recording
- ProRes video encoding
- Capturing photos during video recording
- Runtime camera control (focus, exposure, zoom, torch)
- UI-agnostic preview rendering via a separate preview view

***

## Design Principles

### State-Driven Architecture

`VideoRecorder` is governed by a strict internal state machine.
All public APIs are validated against the current state to prevent invalid transitions and undefined behavior.

```ts
type State =
  | "idle"
  | "preparing"
  | "ready"
  | "recording"
  | "paused"
  | "stopping"
  | "finished"
  | "failed"
```

State definitions:

- **idle**
  Initial state or fully reset. No active capture session.

- **preparing**
  Capture session, devices, and encoders are being configured.

- **ready**
  Fully prepared and ready to start recording.

- **recording**
  Actively recording video (and audio if enabled).

- **paused**
  Recording timeline is paused; media writing is suspended.

- **stopping**
  Recording is ending and the output file is being finalized.

- **finished**
  Recording completed successfully. `details` contains the output file path.

- **failed**
  An error occurred. `details` contains the error message.

***

## Capture Session

```ts
class AVCaptureSession {
  private constructor()
}
```

`VideoRecorder.session` exposes a read-only `AVCaptureSession` instance managed internally by `VideoRecorder`.

This session is intended for:

- Attaching preview views
- Integration with other components that require direct access to the capture session

The session **cannot be instantiated or modified directly**.

***

## Recorder Configuration

```ts
type Configuration = {
  camera?: {
    position: "front" | "back"
    preferredTypes?: CameraType[]
  }
  frameRate?: number
  audioEnabled?: boolean
  sessionPreset?: SessionPreset
  videoCodec?: VideoCodec
  videoBitRate?: number
  orientation?: VideoOrientation
  mirrorFrontCamera?: boolean
  autoConfigAppAudioSession?: boolean
}
```

### Camera Selection

- `position`
  Selects the front or back camera.

- `preferredTypes`
  A prioritized list of physical camera types, such as:

  - `"wide"`
  - `"ultraWide"`
  - `"telephoto"`
  - `"triple"`

If not specified, the system automatically selects an appropriate camera for the chosen position.

***

### Frame Rate

Supported frame rates:

- 24
- 30 (default)
- 60
- 120 (device-dependent)

***

### Audio Recording

```ts
audioEnabled?: boolean
```

Enables or disables audio recording.
Defaults to `true`.

***

### Session Preset

Controls capture resolution and quality, for example:

- `"high"`
- `"hd1920x1080"`
- `"hd4K3840x2160"`

***

### Video Codec

Supported codecs include:

- `"hevc"` (default)
- `"h264"`
- `"hevcWithAlpha"`
- `"proRes422"`
- `"proRes4444"`
- `"appleProRes4444XQ"`
- `"proResRAW"`

Availability depends on device capabilities and OS version.

***

### Video Bit Rate

```ts
videoBitRate?: number
```

Specifies the target video bitrate in bits per second.
Default value is `5_000_000`.
Only applies to certain codecs.

***

### Orientation

```ts
orientation?: "portrait" | "landscapeLeft" | "landscapeRight"
```

Defines the recording orientation and affects both pixel buffers and output metadata.

***

### Front Camera Mirroring

```ts
mirrorFrontCamera?: boolean
```

Mirrors the front camera image if set to `true`.
Defaults to `false`.

***

### Audio Session Management

```ts
autoConfigAppAudioSession?: boolean
```

- `true` (default)
  The system automatically configures the shared `AVAudioSession` for optimal recording.
  The original audio session state is **not restored** after recording.

- `false`
  The app is responsible for configuring `AVAudioSession`.
  Incompatible settings may cause recording to fail.

***

## State Access and Observation

### Get Current State

```ts
function getState(): Promise<State>
```

Returns the current state of the recorder.

***

### State Change Listener

```ts
function addStateListener(
  listener: (state: State, details?: string) => void
): void
```

- `state`
  The new recorder state.

- `details`

  - For `"failed"`: error description
  - For `"finished"`: output file path

```ts
function removeStateListener(
  listener?: (state: State, details?: string) => void
): void
```

If no listener is provided, all listeners are removed.

***

## Recording Lifecycle

### Prepare

```ts
function prepare(configuration?: Configuration): Promise<void>
```

- Creates and configures the capture session
- Requests camera and microphone permissions
- Initializes encoders

Transitions to the `ready` state upon success.

***

### Start Recording

```ts
function start(toPath: string): Promise<void>
```

- Begins recording
- Writes output to the specified file path
- Transitions to `recording`

***

### Pause and Resume

```ts
function pause(): Promise<void>
function resume(): Promise<void>
```

- Pauses and resumes the recording timeline
- Does not create separate files
- Suitable for long-form or segmented recording

***

### Stop Recording

```ts
function stop(options?: {
  closeSession?: boolean
}): Promise<void>
```

- Finalizes the recording
- Transitions to `finished`
- `details` contains the output file path

***

### Cancel Recording

```ts
function cancel(options?: {
  closeSession?: boolean
}): Promise<void>
```

- Aborts recording
- Deletes the output file
- Does not enter the `finished` state

***

### Reset Recorder

```ts
function reset(): Promise<void>
```

- Closes the capture session
- Clears all internal state
- Returns to the `idle` state

Typically used when switching cameras or fully releasing resources.

***

## Photo Capture During Recording

```ts
function takePhoto(): Promise<UIImage | null>
```

- Only valid while in the `recording` state
- Captures a still image from the current video stream
- Does not interrupt recording

***

## Camera Controls

### Torch (Flashlight)

```ts
const hasTorch: boolean
const torchMode: "auto" | "on" | "off"

function setTorchMode(mode: "auto" | "on" | "off"): void
```

***

### Focus and Exposure

```ts
function setFocusPoint(point: { x: number; y: number }): void
function setExposurePoint(point: { x: number; y: number }): void

function resetFocus(): void
function resetExposure(): void
```

- Coordinates are **normalized** (0.0–1.0)
- `{ x: 0, y: 0 }` corresponds to the top-left corner

***

### Zoom Control

```ts
const minZoomFactor: number
const maxZoomFactor: number
const currentZoomFactor: number

function setZoomFactor(factor: number): void
function rampZoomFactor(toFactor: number, rate: number): void
function resetZoom(): void
```

On iOS 18 and later:

```ts
const displayZoomFactor: number
const displayZoomFactorMultiplier: number
```

These values are intended for user-friendly zoom display in the UI.

***

## Typical Usage Flow

```ts
await VideoRecorder.prepare(config)
await VideoRecorder.start(path)

// recording in progress
await VideoRecorder.pause()
await VideoRecorder.resume()

await VideoRecorder.stop()
// or
await VideoRecorder.cancel()

await VideoRecorder.reset()
```

***

## Usage Notes and Best Practices

- A full lifecycle follows: `prepare → start → stop | cancel`
- Switching cameras during `recording` is not recommended; call `reset` first
- High frame rates and ProRes codecs require significant performance and storage
- When disabling automatic audio session configuration, ensure compatibility manually
- Preview rendering is decoupled from recording logic and should be handled separately



---
url: /guide/Device Capabilities/VideoRecorder/VideoRecorder/index_example.md
---

# Example

```tsx
import { Button, Navigation, NavigationStack, Script, useEffect, Path, MagnifyGesture, useObservable, VideoRecorderPreviewView, VStack, Toolbar, ToolbarItem, ToolbarItemGroup } from "scripting"

const recorder = VideoRecorder

function View() {
  // Access dismiss function.
  const dismiss = Navigation.useDismiss()
  const state = useObservable<VideoRecorder.State>("idle")
  const displayZoom = useObservable(1)
  const startZoom = useObservable(1)
  const volume = useObservable(0)
  const toastVisible = useObservable(false)
  const toastMessage = useObservable("")
  const position = useObservable<VideoRecorder.CameraPosition>("back")

  function showToast(message: string) {
    toastVisible.setValue(true)
    toastMessage.setValue(message)
  }

  useEffect(() => {

    const listener = (value: number, old: number) => {
      console.log("old:", old, "new:", value)
      volume.setValue(value)
    }
    SharedAudioSession.addOutputVolumeListener(listener)

    return () => {
      SharedAudioSession.removeOutputVolumeListener(listener)
    }
  }, [])

  async function prepare() {
    await recorder.prepare({
      camera: {
        position: position.value,
        // preferredTypes: ["triple"]
      },
      frameRate: 30,
      audioEnabled: true,
      orientation: "portrait",
      sessionPreset: "high",
      videoCodec: "appleProRes4444XQ",
      // autoConfigAppAudioSession: false
    })
  }

  useEffect(() => {
    prepare().then(() => {
      recorder.start(
        Path.join(
          FileManager.documentsDirectory,
          "test.mov"
        )
      )
    }).catch(e => {
      showToast("Failed to prepare:" + String(e))
    })
    recorder.addStateListener((
      newState, details
    ) => {
      state.setValue(newState)

      if (newState === "ready") {
        // recorder.rampZoomFactor(0.5, 4
      }

      if (newState === "failed") {
        Dialog.alert(details!)
      }

    })

    return () => {
      recorder.reset()
    }
  }, [])

  return <NavigationStack>
    <VStack
      toolbar={
        <Toolbar>
          <ToolbarItem
            placement="topBarLeading"
          >
            <Button
              title="Done"
              systemImage="xmark"
              action={dismiss}
            />
          </ToolbarItem>
          <ToolbarItem
            placement="topBarTrailing"
          >
            <Button
              title="Toggle Torch"
              action={() => {
                if (recorder.torchMode === "on") {
                  recorder.setTorchMode("off")
                } else {
                  recorder.setTorchMode("on")
                }
              }}
            />
          </ToolbarItem>
          <ToolbarItemGroup
            placement="bottomBar"
          >
            {state.value == "idle" && <Button
              title="Prepare"
              action={async () => {
                try {
                  await recorder.prepare()
                } catch (e) {
                  showToast("Failed to prepare:" + e)
                }
              }}
            />}
            {(state.value == "idle" || state.value == "ready") && <Button
              title="Toggle Camera"
              action={async () => {
                try {
                  position.setValue(
                    position.value == "back"
                      ? "front"
                      : "back"
                  )
                  await recorder.reset()
                  await prepare()
                } catch (e) {
                  showToast("Failed to toggle camera:" + e)
                }
              }}
            />}
            {state.value == "ready" && <Button
              title="Start"
              action={async () => {
                try {
                  await recorder.start(
                    Path.join(
                      FileManager.documentsDirectory,
                      "test.mov"
                    )
                  )
                } catch (e) {
                  showToast("Failed to start:" + e)
                }
              }}
            />}
            {state.value == "recording" && <Button
              title="Pause"
              action={async () => {
                try {
                  await recorder.pause()
                } catch (e) {
                  console.error("Failed to call pause", e)
                }
              }}
            />}
            {state.value == "paused" && <Button
              title="Resume"
              action={async () => {
                try {
                  await recorder.resume()
                } catch (e) {
                  showToast("Failed to resume:" + e)
                }
              }}
            />}
            {state.value == "recording" && <Button
              title="Cancel"
              action={async () => {
                try {
                  await recorder.cancel()
                } catch (e) {
                  showToast("Failed to cancel:" + e)
                }
              }}
            />}
            {state.value == "recording" && <Button
              title="Stop"
              action={async () => {
                try {
                  await recorder.stop()
                  await prepare()
                } catch (e) {
                  showToast("Failed to stop: " + e)
                }
              }}
            />}
          </ToolbarItemGroup>
        </Toolbar>
      }
      toast={{
        isPresented: toastVisible,
        message: toastMessage.value,
        position: "top"
      }}
    >

      {/*  <Text>State: {state.value}</Text>
      <Text>OutputVolume: {volume.value}</Text> */}
      <VideoRecorderPreviewView
        key="videoRecorder"
        ignoresSafeArea
        frame={{
          width: Device.screen.width
        }}
        aspectRatio={{
          value: 3 / 4,
          contentMode: "fill"
        }}
        gesture={
          MagnifyGesture()
            .onChanged(details => {
              recorder.setZoomFactor(
                details.magnification * startZoom.value
              )
              displayZoom.setValue(
                recorder.displayZoomFactor
              )
            })
            .onEnded(details => {
              recorder.setZoomFactor(
                details.magnification * startZoom.value
              )
              displayZoom.setValue(
                recorder.displayZoomFactor
              )
              startZoom.setValue(
                recorder.currentZoomFactor
              )
            })
        }
      />
    </VStack >
  </NavigationStack >
}

async function run() {
  // Present view.
  await Navigation.present({
    element: <View />
  })

  // Avoiding memory leaks.
  Script.exit()
}

run()
```



---
url: /guide/Device Capabilities/VideoRecorder/VideoRecorderPreviewView.md
---

# VideoRecorderPreviewView

`VideoRecorderPreviewView` is a UI component used to display the live video feed produced by `VideoRecorder`.
It is a **pure preview component** and does **not** manage recording logic or state.

Its responsibilities include:

- Rendering the real-time camera preview
- Supporting different video fill modes (`videoGravity`)
- Handling mirrored display (commonly for the front camera)
- Applying visual effects such as corner radius and clipping
- Composing with gestures to implement zoom, focus, or exposure interactions

***

## Design Principles

### Decoupled from Recording Logic

`VideoRecorderPreviewView`:

- Does not start, stop, or control recording
- Does not observe or depend on `VideoRecorder.State`
- Does not manage camera or encoder configuration

It only binds to the capture session managed by `VideoRecorder`.

***

### One-Way Dependency

```
VideoRecorder  ──▶  AVCaptureSession  ──▶  VideoRecorderPreviewView
```

- The capture session lifecycle is owned by `VideoRecorder`
- The preview view is a passive consumer for rendering only

***

## Props Definition

```ts
type VideoRecorderPreviewViewProps = {
  videoGravity?: "resizeAspect" | "resizeAspectFill" | "resize"
  isVideoMirrored?: boolean
  cornerRadius?: number
  masksToBounds?: boolean
}
```

***

## videoGravity

```ts
videoGravity?: "resizeAspect" | "resizeAspectFill" | "resize"
```

Controls how the video content is scaled and positioned within the view.
This maps directly to `AVLayerVideoGravity`.

- `resizeAspect`
  Preserves aspect ratio and fits the entire video within the view.
  Black bars may appear.

- `resizeAspectFill` (default)
  Preserves aspect ratio and fills the view, potentially cropping edges.

- `resize`
  Stretches the video to fill the view without preserving aspect ratio.

Choose the mode based on UI and layout requirements.

***

## isVideoMirrored

```ts
isVideoMirrored?: boolean
```

Determines whether the preview image is horizontally mirrored.

- `true`
  The preview is mirrored, typically used for front-facing cameras.

- `false` (default)
  The preview is displayed in its original orientation.

> Note:
> This property affects **preview rendering only** and does not change how the recorded video file is encoded.

***

## cornerRadius

```ts
cornerRadius?: number
```

Specifies the corner radius applied to the preview view’s background.

- Default value: `0`
- Affects only the view’s background by default
- To clip the video content itself, `masksToBounds` must be set to `true`

***

## masksToBounds

```ts
masksToBounds?: boolean
```

Controls whether the preview content is clipped to the view’s bounds.

- `false` (default)
  Rounded corners apply only to the background; the video content is not clipped.

- `true`
  The video content is clipped to the rounded corners.

Typically used together with `cornerRadius`.

***

## Lifecycle and Update Behavior

### Relationship with Declarative UI Frameworks

`VideoRecorderPreviewView` is a declarative component whose underlying native preview layer (for example, an `AVCaptureVideoPreviewLayer`) is intended to persist across updates.

Important considerations:

- **Recreating the view instance**
  May cause the underlying preview layer to be rebound to the capture session.

- **Frequent view reconstruction**
  Can lead to brief stutters, flashes, or preview interruptions.

***

### Importance of the `key` Property

In dynamic UI scenarios such as camera switching or session reconfiguration:

```tsx
<VideoRecorderPreviewView
  key="videoRecorder"
  ...
/>
```

Best practices:

- Always provide a stable, unique `key`
- Ensures the preview view remains correctly bound to the current capture session
- Prevents unnecessary destruction and recreation caused by diffing mismatches

***

## Cooperation with VideoRecorder

### Capture Session Source

Internally, `VideoRecorderPreviewView` binds to:

```ts
VideoRecorder.session
```

The preview view does not create or manage the session itself.

***

### Behavior When the Session Is Reset

When calling:

```ts
await VideoRecorder.reset()
```

- The underlying `AVCaptureSession` is stopped and released
- The preview may freeze or display a blank frame
- After calling `prepare` again, the preview resumes automatically

No additional handling is required in the preview view.

***

## Gestures and Interaction Composition

`VideoRecorderPreviewView` does **not** include built-in gesture handling.
Instead, it is designed to compose with the gesture system:

```tsx
<VideoRecorderPreviewView
  gesture={
    MagnifyGesture()
      .onChanged(details => {
        VideoRecorder.setZoomFactor(...)
      })
  }
/>
```

Common interaction patterns:

- Pinch gesture → adjust zoom via `setZoomFactor`
- Tap gesture → convert to normalized coordinates and call `setFocusPoint`
- Long press → lock or adjust exposure

***

## Usage Recommendations

- Avoid recreating the preview view while in the `recording` state
- When switching cameras:

  1. Call `VideoRecorder.reset()`
  2. Call `VideoRecorder.prepare(...)`
  3. Keep the preview view `key` stable
- Apply mirroring, rounding, and clipping at the preview layer
- Perform all recording control through `VideoRecorder`, not the preview view

***

## Minimal Example

```tsx
<VideoRecorderPreviewView
  key="videoRecorder"
  videoGravity="resizeAspectFill"
  isVideoMirrored={true}
  cornerRadius={12}
  masksToBounds={true}
/>
```

***

## Summary

`VideoRecorderPreviewView` is a **pure rendering component**:

- Renders the live camera feed
- Does not manage recording state or lifecycle
- Depends on `VideoRecorder` via a one-way capture session relationship
- Designed for flexible composition with gestures and UI layout



---
url: /guide/Device Capabilities/Vision.md
---

# Vision

The `Vision` module provides APIs for **text recognition** tasks.\
It supports recognizing text from static images or by scanning documents using the camera.

***

## Types

### `RecognizedText`

Represents a block of recognized text.

- `content: string`\
  The recognized text content.

- `confidence: number`\
  Confidence level (between `0.0` and `1.0`) where `1.0` indicates the highest confidence.

- `boundingBox: { x: number, y: number, width: number, height: number }`\
  The bounding box of the recognized text in normalized coordinates.

***

### `RecognizeTextOptions`

Configuration options for text recognition.

- `recognitionLevel?: "accurate" | "fast"`\
  Recognition mode:
  - `"accurate"` (default): Prioritizes accuracy.
  - `"fast"`: Prioritizes speed.

- `recognitionLanguages?: string[]`\
  Preferred recognition languages in ISO language codes, in priority order.

- `usesLanguageCorrection?: boolean`\
  Whether to apply automatic language correction during recognition.

- `minimumTextHeight?: number`\
  Minimum text height to recognize, relative to image height (default `0.03125`).

- `customWords?: string[]`\
  Custom vocabulary to prioritize during word recognition. Only effective when `usesLanguageCorrection` is `true`.

***

## Functions

### `recognizeText(image: UIImage, options?: RecognizeTextOptions): Promise<{ text: string, candidates: RecognizedText[] }>`

Recognizes text from the provided image.

- **Parameters**:
  - `image`: A `UIImage` object.
  - `options` _(optional)_: Recognition options.

- **Returns**:\
  A Promise resolving with:
  - `text`: All recognized text combined into a single string.
  - `candidates`: Array of recognized text blocks with details.

***

### `scanDocument(options?: RecognizeTextOptions): Promise<string[]>`

Scans a document using the device's camera and recognizes text.

- **Parameters**:
  - `options` _(optional)_: Recognition options.

- **Returns**:\
  A Promise resolving with an array of recognized text documents.\
  If the user cancels, the Promise rejects with an error.

***

## Usage Examples

### Recognize text from an image file

```tsx
const image = UIImage.fromFile('/path/to/image.png')
if (image) {
  const result = await Vision.recognizeText(image, {
    recognitionLevel: 'accurate',
    recognitionLanguages: ['en', 'zh-Hans'],
    usesLanguageCorrection: true
  })
  console.log('Recognized Text:', result.text)

  for (const block of result.candidates) {
    console.log(`Text: ${block.content}, Confidence: ${block.confidence}`)
  }
}
```

***

### Scan a document with camera

```tsx
try {
  const documents = await Vision.scanDocument({
    recognitionLevel: 'fast',
    recognitionLanguages: ['en']
  })
  console.log('Scanned Documents:', documents)
} catch (error) {
  console.error('Scan cancelled or failed:', error)
}
```



---
url: /guide/Device Capabilities/Weather/index.md
---

# Weather

The Weather API in Scripting provides access to real-time and forecast weather data, including current conditions, hourly forecasts, and daily forecasts. This API allows users to fetch weather details such as temperature, wind speed, humidity, and precipitation for a specified location.

## Types

### `UnitType`

Represents a unit of measurement with its value, symbol, and formatted string.

```ts
type UnitType = {
  value: number
  symbol: string
  formatted: string
}
```

### `UnitTemperature`, `UnitSpeed`, `UnitLength`, `UnitAngle`, `UnitPressure`

These types extend `UnitType` to represent temperature, speed, length, angle, and pressure.

## `WeatherCondition`

A string enum describing various weather conditions, including:

- `clear`
- `rain`
- `snow`
- `thunderstorms`
- `cloudy`
- `windy`
- ...

## Functions

### `Weather.requestCurrent(location: LocationInfo): Promise<CurrentWeather>`

Retrieves the current weather conditions for a given location.

#### Parameters

- `location: LocationInfo` – The location for which weather data is requested.

#### Returns

A `Promise` resolving to a `CurrentWeather` object.

#### Example

```ts
const location = { latitude: 37.7749, longitude: -122.4194 }
const weather = await Weather.requestCurrent(location)
console.log(`Current temperature: ${weather.temperature.formatted}`)
```

### `Weather.requestDailyForecast(location: LocationInfo, options?: { startDate: Date, endDate: Date }): Promise<WeatherDailyForecast>`

Retrieves the daily weather forecast for the specified location. You can optionally provide a start and end date to specify the forecast range.

#### Parameters

- `location: LocationInfo` – The location to query.
- `options.startDate` – The start date for the forecast.
- `options.endDate` – The end date for the forecast.

#### Returns

A `Promise` resolving to a `WeatherDailyForecast` object.

#### Example

```ts
const forecast = await Weather.requestDailyForecast(location, {
  startDate: new Date(),
  endDate: new Date(Date.now() + 5 * 24 * 60 * 60 * 1000)
})
console.log(`Tomorrow's weather: ${forecast.forecast[1].condition}`)
```

### `Weather.requestHourlyForecast(location: LocationInfo, options?: { startDate: Date, endDate: Date }): Promise<WeatherHourlyForecast>`

Retrieves the hourly weather forecast for the specified location. You can optionally provide a start and end date to specify the forecast range.

#### Parameters

- `location: LocationInfo` – The location to query.
- `options.startDate` – The start date for the forecast.
- `options.endDate` – The end date for the forecast.

#### Returns

A `Promise` resolving to a `WeatherHourlyForecast` object.

#### Example

```ts
const hourlyForecast = await Weather.requestHourlyForecast(location, {
  startDate: new Date(),
  endDate: new Date(Date.now() + 3 * 60 * 60 * 1000)
})
console.log(`Next hour's temperature: ${hourlyForecast.forecast[0].temperature.formatted}`)
```

## `CurrentWeather`

Represents the current weather conditions.

```ts
type CurrentWeather = {
  temperature: UnitTemperature
  apparentTemperature: UnitTemperature
  humidity: number
  wind: WeatherWind
  condition: WeatherCondition
  date: number
  symbolName: string
}
```

## `WeatherDailyForecast`

Represents the daily forecast.

```ts
type WeatherDailyForecast = {
  metadata: WeatherMetadata
  forecast: DayWeather[]
}
```

## `WeatherHourlyForecast`

Represents the hourly forecast.

```ts
type WeatherHourlyForecast = {
  metadata: WeatherMetadata
  forecast: HourWeather[]
}
```

## `DayWeather`

Represents daily weather details.

```ts
type DayWeather = {
  highTemperature: UnitTemperature
  lowTemperature: UnitTemperature
  wind: WeatherWind
  condition: WeatherCondition
  date: number
  symbolName: string
}
```

## `HourWeather`

Represents hourly weather details.

```ts
type HourWeather = {
  temperature: UnitTemperature
  humidity: number
  wind: WeatherWind
  condition: WeatherCondition
  date: number
  symbolName: string
}
```

## Example Usage

### Fetch and Display Current Weather

```ts
async function displayCurrentWeather() {
  const location = { latitude: 37.7749, longitude: -122.4194 }
  const weather = await Weather.requestCurrent(location)
  console.log(`The temperature is ${weather.temperature.formatted} with ${weather.condition}`)
}

displayCurrentWeather()
```

### Fetch and Display Daily Forecast

```ts
async function displayDailyForecast() {
  const location = { latitude: 37.7749, longitude: -122.4194 }
  const forecast = await Weather.requestDailyForecast(location, {
    startDate: new Date(),
    endDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
  })
  forecast.forecast.forEach(day => {
    console.log(`Date: ${new Date(day.date).toDateString()}, Condition: ${day.condition}`)
  })
}

displayDailyForecast()
```

### Fetch and Display Hourly Forecast

```ts
async function displayHourlyForecast() {
  const location = { latitude: 37.7749, longitude: -122.4194 }
  const hourlyForecast = await Weather.requestHourlyForecast(location, {
    startDate: new Date(),
    endDate: new Date(Date.now() + 5 * 60 * 60 * 1000)
  })
  hourlyForecast.forecast.forEach(hour => {
    console.log(`Time: ${new Date(hour.date).toLocaleTimeString()}, Temp: ${hour.temperature.formatted}`)
  })
}

displayHourlyForecast()
```



---
url: /guide/Device Capabilities/Weather/index_example.md
---

# Example

```tsx
import { Script } from "scripting"

console.present().then(() => {
  Script.exit()
})

console.log("Requesting Current Weather...")

async function displayCurrentWeather() {
  let location: LocationInfo | null = null
  try {
    console.log("Requesting location... Please move your device to trigger a location update.")
    location = await Location.requestCurrent()

    if (location) {
      const placemarks = await Location.reverseGeocode(location)
      if (placemarks && placemarks.length) {
        console.log(`Your current location: ${JSON.stringify(placemarks[0], null, 2)}`)
      }
    }
  } catch (e) {
    console.log("Failed to request location", e)
  }

  if (!location) {
    console.error("Please approval the location permission request")
    return
  }

  // Use the WeatherKit
  const weather = await Weather.requestCurrent(
    location
  )

  console.log(
    `The temperature is ${weather.temperature.formatted
    } with ${weather.condition}`
  )
}

displayCurrentWeather()
```



---
url: /guide/Device Capabilities/WebViewController.md
---

# WebViewController

The `WebViewController` class allows you to display and interact with embedded web content inside your script. It is designed for use cases like custom in-app browsers, rendering dynamic HTML, or communicating with JavaScript running in a web context.

***

## Class: `WebViewController`

```ts
const webView = new WebViewController()
```

### Constructor

```ts
new WebViewController(options?: { ephemeral?: boolean })
```

- **Options** (all optional):

  - `ephemeral`: When `true`, the WebView uses a non-persistent data store so cookies and website data are isolated from the default container and discarded when the controller is released. Useful for sandboxed login flows or clean-slate scraping.

#### Example

```ts
// Regular (persistent) WebView — shares cookies with other WebViewControllers.
const webView = new WebViewController()

// Ephemeral WebView — cookies are isolated and wiped when disposed.
const isolated = new WebViewController({ ephemeral: true })
```

***

## Properties

### `shouldAllowRequest?: (request) => Promise<boolean>`

An optional callback that determines whether to allow or block a request made by the WebView. This function is invoked before each resource is loaded, such as when navigating to a new page or submitting a form.

This is useful for intercepting navigation actions, implementing custom security logic, or filtering unwanted requests (e.g., ad domains).

#### Parameters

The function receives a single `request` object with the following properties:

- `url: string`
  The full URL of the request.

- `method: string`
  The HTTP method (e.g., `GET`, `POST`).

- `body?: Data | null`
  Optional body data sent with the request (e.g., for `POST` requests).

- `headers: Record<string, string>`
  HTTP request headers.

- `timeoutInterval: number`
  The timeout interval in seconds for the request.

- `navigationType: "linkActivated" | "reload" | "backForward" | "formResubmitted" | "formSubmitted" | "other"`
  The context that triggered the navigation.

#### Returns

A `Promise<boolean>` resolving to:

- `true`: allow the request to proceed
- `false`: block the request

#### Example

```ts
const webView = new WebViewController()

webView.shouldAllowRequest = async (request) => {
  console.log('Intercepted request to:', request.url)

  // Block all requests to example.com
  if (request.url.includes('example.com')) {
    return false
  }

  return true
}

await webView.loadURL('https://www.wikipedia.org')
await webView.present({ navigationTitle: 'Filtered WebView' })
```

***

## Methods

### `loadFile(path: string, allowingReadAccessTo?: string): Promise<boolean>`

Loads a web page from a local file.

- **Parameters**:

  - `path`: The path to the local file.
  - `allowingReadAccessTo` (optional): A directory to allow read access to.
- **Returns**: `Promise<boolean>` — Resolves to `true` if the load succeeds.

### `loadURL(url: string): Promise<boolean>`

Loads a webpage by its URL.

- **Parameters**:

  - `url`: The full URL of the webpage to load.
- **Returns**: `Promise<boolean>` — Resolves to `true` if the load succeeds.

***

### `loadHTML(html: string, baseURL?: string): Promise<boolean>`

Loads a web page using raw HTML content.

- **Parameters**:

  - `html`: The HTML string to render.
  - `baseURL` (optional): A base URL to resolve relative paths.
- **Returns**: `Promise<boolean>` — Resolves to `true` on successful load.

***

### `loadData(data: Data, mimeType: string, encoding: string, baseURL: string): Promise<boolean>`

Loads web content from raw data.

- **Parameters**:

  - `data`: The binary content to load.
  - `mimeType`: MIME type of the content (e.g., `"text/html"`).
  - `encoding`: Character encoding (e.g., `"utf-8"`).
  - `baseURL`: Base URL for resolving relative URLs.
- **Returns**: `Promise<boolean>`

***

### `waitForLoad(): Promise<boolean>`

Waits until the WebView has finished loading content.

- **Returns**: `Promise<boolean>`

***

### `getHTML(): Promise<string | null>`

Returns the current HTML content of the page.

- **Returns**: `Promise<string | null>`

***

### `evaluateJavaScript<T = any>(javascript: string): Promise<T>`

Evaluates the specified JavaScript string in the context of the WebView.

- **Parameters**:

  - `javascript`: A JavaScript code string to be evaluated.
    To retrieve a result from JavaScript, the code must explicitly use the `return` keyword.
- **Returns**: `Promise<T>` — Resolves with the result of the JavaScript evaluation. If the JavaScript code returns a value, it will be returned as the resolved value of the Promise.

#### Example

```ts
const webView = new WebViewController()
await webView.loadURL("https://example.com")
const title = await webView.evaluateJavaScript("return document.title") // Must use `return`
console.log(title) // "Example Domain"
webView.dispose()
```

Another example:

```ts
const webView = new WebViewController()
await webView.loadHTML(`
  <html>
    <body>
      <script>
        window.myValue = 42
      </script>
    </body>
  </html>
`)

await webView.waitForLoad()

const result = await webView.evaluateJavaScript('return window.myValue')
console.log(result) // 42
```

***

### `addScriptMessageHandler<P = any, R = any>(name: string, handler: (params?: P) => R): Promise<void>`

Installs a message handler callable from JavaScript in the web page, and enables sending a reply back from native code.

- **Parameters**:

  - `name`: The message handler name. Must be unique and non-empty.
  - `handler`: A callback function that receives parameters from JavaScript and returns a value. The return value will be sent back as the JavaScript promise resolution.

- **Returns**: `Promise<void>` — Resolves when the message handler is added successfully.

#### Example

```ts
let webView = new WebViewController()

await webView.addScriptMessageHandler("sayHi", (greeting: string) => {
  console.log("Receive a message", greeting)
  return "Hello!"
})

await webView.loadHTML(`
  <html>
    <body>
      <script>
        (async () => {
          const response = await window.webkit.messageHandlers.sayHi.postMessage("Hi!")
          alert(response) // Shows: "Hello!"
        })()
      </script>
    </body>
  </html>
`)
```

***

### `present(options?: { fullscreen?: boolean, navigationTitle?: string }): Promise<void>`

Presents the WebView in a modal sheet.

- **Options**:

  - `fullscreen`: If `true`, displays the WebView in fullscreen mode.
  - `navigationTitle`: Optional title for the navigation bar.
- **Returns**: `Promise<void>`

***

### `canGoBack(): Promise<boolean>`

Checks whether the WebView can go back in history.

***

### `canGoForward(): Promise<boolean>`

Checks whether the WebView can go forward in history.

***

### `goBack(): Promise<boolean>`

Navigates to the previous page in the history stack.

***

### `goForward(): Promise<boolean>`

Navigates to the next page in the history stack.

***

### `reload(): Promise<void>`

Reloads the current webpage.

***

### `takeSnapshot(options?): Promise<UIImage | null>`

Captures a snapshot of the WebView's currently visible viewport and returns it as a `UIImage`.

- **Options** (all optional):

  - `rect`: The rectangle (in the WebView's coordinate space, in points) to capture. Defaults to the full visible viewport.
  - `snapshotWidth`: The width (in points) of the resulting image. The height is scaled proportionally. Defaults to the WebView's width.
  - `afterScreenUpdates`: Whether to take the snapshot after pending screen updates have been applied. Defaults to `true`.

- **Returns**: `Promise<UIImage | null>` — Resolves to a `UIImage`, or `null` if the WebView is not on screen (i.e. `present()` has not been called and it is not used by a `<WebView>` view), or if the snapshot fails.

#### Example

```ts
const webView = new WebViewController()
await webView.loadURL('https://example.com')
await webView.present({ navigationTitle: 'Snapshot Demo' })

const image = await webView.takeSnapshot()
if (image) {
  const data = image.pngData()
  // Save or share the image...
}

webView.dispose()
```

***

### `getAllCookies(): Promise<Cookie[]>`

Returns every cookie currently stored in the WebView's cookie jar, including `HttpOnly` cookies that are not exposed to `document.cookie`.

- **Returns**: `Promise<Cookie[]>`

Each `Cookie` has the shape:

```ts
interface Cookie {
  name: string
  value: string
  domain: string
  path: string
  isSecure: boolean
  isHTTPOnly: boolean
  isSessionOnly: boolean
  expiresDate?: Date | null
}
```

***

### `getCookies(url: string): Promise<Cookie[]>`

Returns the cookies that would be sent with a request to the given URL. Matching follows the standard WebKit rules: the URL's host must match `cookie.domain` (with subdomain match when `cookie.domain` starts with `.`), and the URL's path must be covered by `cookie.path`.

- **Parameters**:

  - `url`: The URL used to filter cookies by domain and path.
- **Returns**: `Promise<Cookie[]>`

***

### `setCookie(cookie: Cookie): Promise<boolean>`

Sets (or overwrites) a cookie in the WebView's cookie store.

You can call `setCookie` **before** `loadURL` to pre-seed authentication state — the WebView's cookie store is ready as soon as the controller is created, even if the view has not been presented yet.

- **Parameters**:

  - `cookie`: The cookie to store. `name`, `value` and `domain` are required. `path` defaults to `"/"`. If `isSessionOnly` is `true` or `expiresDate` is omitted, the cookie is treated as a session cookie.
- **Returns**: `Promise<boolean>` — Resolves to `true` when the cookie is accepted, or `false` if the input is invalid.

#### Example

```ts
const webView = new WebViewController()

// Seed a session cookie before loading a gated page.
await webView.setCookie({
  name: "session",
  value: "abc123",
  domain: "example.com",
  path: "/",
  isSecure: true,
  isHTTPOnly: true,
  isSessionOnly: false,
  expiresDate: new Date(Date.now() + 86400_000),
})

await webView.loadURL("https://example.com/dashboard")
```

***

### `deleteCookie(cookie: { name: string, domain?: string, path?: string }): Promise<boolean>`

Deletes cookies that match the given descriptor.

You can either pass a full `Cookie` object returned by `getAllCookies` / `getCookies` to delete that exact cookie, or pass a partial descriptor to delete every cookie whose `name` (and optionally `domain` / `path`) matches.

- **Parameters**:

  - `cookie.name`: Cookie name to match (required).
  - `cookie.domain` (optional): When provided, only cookies with this exact domain are deleted.
  - `cookie.path` (optional): When provided, only cookies with this exact path are deleted.
- **Returns**: `Promise<boolean>` — Resolves to `true` when at least one cookie is removed, or `false` when nothing matched.

#### Example

```ts
const webView = new WebViewController()
await webView.loadURL("https://example.com")

// Delete every "tracker" cookie regardless of domain.
await webView.deleteCookie({ name: "tracker" })

// Or delete a specific cookie returned by getCookies.
const [c] = await webView.getCookies("https://example.com/")
if (c) {
  await webView.deleteCookie(c)
}
```

***

### `clearAllCookies(): Promise<void>`

Removes every cookie from the WebView's cookie store. Other website data (cache, local storage, etc.) is left untouched.

- **Returns**: `Promise<void>`

***

### `dismiss(): void`

Dismisses the WebView if currently presented.

***

### `dispose(): void`

Disposes the WebView instance and releases resources.

- If the WebView is still presented, it will first be dismissed.
- **Important**: You must call this to prevent memory leaks when done.

***

## Full Example

```ts
const webView = new WebViewController()

await webView.addScriptMessageHandler('greet', (name) => {
  return `Hello, ${name}`
})

await webView.loadHTML(`
  <html>
    <body>
      <h1>Custom WebView</h1>
      <button onclick="sendMessage()">Greet</button>
      <script>
        async function sendMessage() {
          const response = await window.webkit.messageHandlers.greet.postMessage("Alice")
          alert(response)
        }
      </script>
    </body>
  </html>
`)

await webView.present({ navigationTitle: 'WebView Demo' })
webView.dispose()
```



---
url: /guide/Intent/Intent.continueInForeground.md
---

# Intent.continueInForeground

`Intent.continueInForeground` is an API that leverages the **iOS 26+ AppIntents framework** to request the system to bring the **Scripting app** to the foreground while a Shortcut is running.

This method is used when a script—invoked from Shortcuts—requires full UI interaction within the Scripting app (for example: presenting a form, editing content, picking files, showing a full screen navigation flow, etc.).

When invoked:

- The system displays a dialog asking the user to continue the workflow in the app.
- If the user **confirms**, the system opens Scripting in the foreground and the script continues.
- If the user **cancels**, the script terminates immediately.

Because this is a system-level capability of AppIntents:

**This API requires iOS 26 or later.**

***

## API Definition

```ts
function continueInForeground(
  dialog?: Dialog | null,
  options?: {
    alwaysConfirm?: boolean;
  }
): Promise<void>;
```

## Parameters

### `dialog?: Dialog | null`

An optional message explaining why the workflow needs to continue in the foreground.

`Dialog` supports four formats:

```ts
type Dialog =
  | string
  | { full: string; supporting: string }
  | { full: string; supporting: string; systemImageName: string }
  | { full: string; systemImageName: string }
```

Examples:

```ts
"Do you want to continue in the app?"
```

```ts
{
  full: "Continue in the Scripting app?",
  supporting: "The next step requires full UI interaction.",
  systemImageName: "app"
}
```

Passing `null` will suppress the dialog entirely (not recommended unless you fully understand the UX implications).

***

### `options?: { alwaysConfirm?: boolean }`

Controls whether the system should always ask for confirmation:

- `alwaysConfirm: false` _(default)_
  The system may decide whether confirmation is needed based on context.

- `alwaysConfirm: true`
  The system always presents the confirmation dialog.

***

## Execution Behavior

When called inside `intent.tsx`:

1. The Shortcut pauses execution.
2. The system presents a confirmation dialog.
3. If the user accepts:

   - The Scripting app opens in the foreground.
   - The script continues executing after the `await`.
4. If the user cancels:

   - The entire script is terminated immediately.

This mirrors the behavior of Apple’s AppIntents `continueInApp()` functionality for system apps.

***

## Common Use Cases

Use `continueInForeground` when the next step **cannot** run in the background, including:

- Presenting a full-screen UI (`Navigation.present`)
- Editing content in a custom form or navigation stack
- Selecting files or interacting with UI components
- Scenarios requiring user input or multi-step flows
- Showing UI unavailable to background extensions

It should **not** be used for simple data processing or non-interactive tasks.

***

## Full Code Example

Below is the full working example demonstrating how `continueInForeground` enables a Shortcut to transfer execution into the Scripting app and then return UI input back to Shortcuts.

```tsx
// intent.tsx
import {
  Button,
  Intent,
  List,
  Navigation,
  NavigationStack,
  Script,
  Section,
  TextField,
  useState
} from "scripting"

function View() {
  const dismiss = Navigation.useDismiss()
  const [text, setText] = useState("")

  return <NavigationStack>

    <List navigationTitle="Intent Demo">

      <TextField
        title="Enter a text"
        value={text}
        onChanged={setText}
      />

      <Section>
        <Button
          title="Return Text"
          action={() => {
            dismiss(text)
          }}
          disabled={!/\S+/.test(text)}
        />
      </Section>

    </List>

  </NavigationStack>
}

async function runIntent() {

  // Step 1: Ask the user to continue in the foreground app
  await Intent.continueInForeground(
    "Do you want to open the app and continue?"
  )

  // Step 2: Present UI inside the Scripting app
  const text = await Navigation.present<string | null>(
    <View />
  )

  // Step 3: Optionally go back to Shortcuts
  Safari.openURL("shortcuts://")

  // Step 4: Return the result to Shortcuts
  Script.exit(
    Intent.text(
      text ?? "No text return"
    )
  )
}

runIntent()
```

***

## Notes and Recommendations

1. **Requires iOS 26+**
   Do not call this API on older systems.

2. **Use dialogs to explain why foreground interaction is required**
   This improves user trust and Shortcuts clarity.

3. **Always handle the cancellation case**
   If the user cancels, your script stops. Avoid assuming foreground UI will always appear.

4. **Foreground UI must be meaningful**
   Only use this API when the upcoming step truly requires UI.

5. **Can be combined with SnippetIntent (iOS 26+)**
   For workflows that mix in-Shortcut Snippet UI with in-app full UI.

***

## Summary

`Intent.continueInForeground` enables scripts invoked from Shortcuts to request foreground execution when UI interaction is required. It is:

- Based on iOS 26 AppIntents capabilities
- A system-confirmed context switch
- Essential for workflows involving full UI interactions
- Safely integrated via a structured `Dialog` system

This method allows Scripting to support advanced automation flows that seamlessly transition between Shortcuts and the full Scripting app UI.



---
url: /guide/Intent/Intent.requestConfirmation.md
---

# Intent.requestConfirmation

`Intent.requestConfirmation` pauses script execution and asks the user to confirm an action through a **system-managed confirmation UI**.
The confirmation interface consists of:

- A **SnippetIntent UI** (provided by you)
- Optional dialog text (system-generated or developer-defined)

Behavior:

- If the user **confirms**, the script continues (Promise resolves).
- If the user **cancels**, the script terminates immediately.
- The UI is fully managed by the system.
- The presented UI is defined by the provided SnippetIntent’s `perform()` return.

**This API is only available on iOS 26 or later.**

***

## API Definition

```ts
Intent.requestConfirmation(
  actionName: ConfirmationActionName,
  snippetIntent: AppIntent<any, VirtualNode, AppIntentProtocol.SnippetIntent>,
  options?: {
    dialog?: Dialog;
    showDialogAsPrompt?: boolean;
  }
): Promise<void>
```

***

## Parameter Details

## actionName: ConfirmationActionName

A semantic keyword describing the type of action being confirmed.
Apple uses this value to generate natural language around the confirmation UI.

Accepted values include:

```
"add" | "addData" | "book" | "buy" | "call" | "checkIn" |
"continue" | "create" | "do" | "download" | "filter" |
"find" | "get" | "go" | "log" | "open" | "order" |
"pay" | "play" | "playSound" | "post" | "request" |
"run" | "search" | "send" | "set" | "share" |
"start" | "startNavigation" | "toggle" | "turnOff" |
"turnOn" | "view"
```

Examples:

- `"set"` → “Do you want to set...?”
- `"buy"` → “Do you want to buy...?”
- `"toggle"` → “Do you want to toggle...?”

Choosing the correct semantic verb improves the clarity of the user-facing dialog.

***

## snippetIntent: SnippetIntent

This must be an AppIntent registered with:

```ts
protocol: AppIntentProtocol.SnippetIntent;
```

The UI displayed in the confirmation step **comes from this SnippetIntent’s `perform()` return**, which must be a TSX-based `VirtualNode`.

This is what the user sees and interacts with during confirmation.

***

## `options?: { dialog?: Dialog; showDialogAsPrompt?: boolean }`

### dialog?: Dialog

Optional text describing the confirmation request.
Supports four formats:

```ts
type Dialog =
  | string
  | { full: string; supporting: string }
  | { full: string; supporting: string; systemImageName: string }
  | { full: string; systemImageName: string };
```

Examples:

```ts
"Are you sure you want to continue?";
```

More structured version:

```ts
{
  full: "Set this color?",
  supporting: "This will update the theme color used across the app.",
  systemImageName: "paintpalette"
}
```

Use this to clearly explain what the user is confirming.

***

### showDialogAsPrompt?: boolean

- Default: `true`
  The system shows the dialog as a modal prompt.

- `false`
  The dialog may be integrated directly inside the Snippet card instead of a separate prompt.

***

## Execution Flow

When the script executes:

```ts
await Intent.requestConfirmation(...)
```

The following occurs:

1. Script execution is paused.

2. The system displays:

   - The SnippetIntent UI
   - Optional dialog text

3. The user chooses:

   - **Confirm** → Promise resolves → script continues
   - **Cancel** → script stops immediately

4. The system handles UI presentation and dismissal automatically.

There is no need to manually manage the UI lifecycle.

***

## Usage Scenarios

Recommended for:

- Confirming important changes (colors, appearance, configurations)
- Confirming destructive or irreversible actions
- Steps requiring explicit user approval
- Initiating subflows requiring UI preview or choice (e.g., color picker, item selector)
- Sensitive operations (e.g., updating settings, performing actions with side effects)

Not recommended for:

- Actions that do not require user approval
- Simple background data processing

***

## Complete Example

Below is a full working example demonstrating how to request user confirmation using a SnippetIntent.

It assumes you have two SnippetIntent AppIntents:

- `PickColorIntent` — allows user to select a color
- `ShowResultIntent` — displays the final result

## intent.tsx

```tsx
import { Intent, Script } from "scripting";
import { PickColorIntent, ShowResultIntent } from "./app_intents";

async function runIntent() {
  // Step 1: Ask the user to confirm the action via a Snippet UI
  await Intent.requestConfirmation("set", PickColorIntent(), {
    dialog: {
      full: "Are you sure you want to set this color?",
      supporting: "This will update the theme color used by your app.",
      systemImageName: "paintpalette",
    },
  });

  // Step 2: Read input from Shortcuts
  const text =
    Intent.shortcutParameter?.type === "text"
      ? Intent.shortcutParameter.value
      : "No text parameter from Shortcuts";

  // Step 3: Return another SnippetIntent result
  const snippet = Intent.snippetIntent({
    snippetIntent: ShowResultIntent({ content: text }),
  });

  Script.exit(snippet);
}

runIntent();
```

***

## Notes & Best Practices

- **Requires iOS 26+** — do not call this API on earlier versions.
- Always include a clear **dialog** message to improve user understanding.
- Use for actions that require explicit approval or confirmation.
- When possible, combine with SnippetIntent to provide a richer preview UI.
- Scripts terminate automatically when the user cancels; do not rely on cleanup code afterward.
- Avoid calling it unnecessarily; only use when confirmation is truly meaningful.



---
url: /guide/Intent/Quick Start.md
---

# Quick Start

Scripting allows you to define custom iOS Intents using an `intent.tsx` file. These scripts can receive input from the iOS share sheet or the Shortcuts app and return structured results. With optional UI presentation, you can create interactive workflows that process data and deliver output dynamically.

***

## 1. Creating and Configuring an Intent

### 1.1 Create an Intent Script

1. Create a new script project in the Scripting app.
2. Add a file named `intent.tsx` to the project.
3. Define your logic and optionally a UI component inside the file.

### 1.2 Configure Supported Input Types

Tap the project title in the editor’s title bar to open **Intent Settings**, then select supported input types:

- Text
- Images
- File URLs
- URLs

This configuration enables your script to appear in the share sheet or Shortcuts when matching input is provided.

***

## 2. Accessing Input Data

Inside `intent.tsx`, use the `Intent` API to access input values.

| Property                   | Description                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `Intent.shortcutParameter` | A single parameter passed from the Shortcuts app, with `.type` and `.value` fields. |
| `Intent.textsParameter`    | Array of text strings.                                                              |
| `Intent.urlsParameter`     | Array of URL strings.                                                               |
| `Intent.imagesParameter`   | Array of image file paths (UIImage objects).                                        |
| `Intent.fileURLsParameter` | Array of local file URL paths.                                                      |

Example:

```ts
if (Intent.shortcutParameter) {
  if (Intent.shortcutParameter.type === "text") {
    console.log(Intent.shortcutParameter.value)
  }
}
```

***

## 3. Returning a Result

Use `Script.exit(result)` to return a result to the caller, such as the Shortcuts app or another script. Valid return types include:

- Plain text: `Intent.text(value)`
- Attributed text: `Intent.attributedText(value)`
- URL: `Intent.url(value)`
- JSON: `Intent.json(value)`
- File path or file URL: `Intent.file(value)` or `Intent.fileURL(value)`

Example:

```ts
import { Script, Intent } from "scripting"

Script.exit(Intent.text("Done"))
```

***

## 4. Displaying Interactive UI

Use `Navigation.present()` to show a UI before returning a result. You can render a React-style component and then call `Script.exit()` after the interaction completes.

Example:

```ts
import { Intent, Script, Navigation, VStack, Text } from "scripting"

function MyIntentView() {
  return (
    <VStack>
      <Text>{Intent.textsParameter?.[0]}</Text>
    </VStack>
  )
}

async function run() {
  await Navigation.present({ element: <MyIntentView /> })
  Script.exit()
}

run()
```

***

## 5. Using Intents in the Share Sheet

If a script supports a specific input type (e.g., text or image), it will automatically appear as an option in the iOS share sheet:

1. Select content such as text or a file.
2. Tap the Share button.
3. Choose **Scripting** in the share sheet.
4. Scripting will list scripts that support the selected input type.

***

## 6. Using Intents in the Shortcuts App

You can call scripts from the Shortcuts app with or without UI:

- **Run Script**: Executes the script in the background.
- **Run Script in App**: Executes the script in the foreground, with UI presentation support.

Steps:

1. Open the Shortcuts app and create a new shortcut.
2. Add the **Run Script** or **Run Script in App** action from Scripting.
3. Choose the target script and pass input parameters if needed.

***

## 7. Intent API Reference

### `Intent` Properties

| Property            | Type                | Description                                     |
| ------------------- | ------------------- | ----------------------------------------------- |
| `shortcutParameter` | `ShortcutParameter` | Input from Shortcuts with `.type` and `.value`. |
| `textsParameter`    | `string[]`          | Array of input text values.                     |
| `urlsParameter`     | `string[]`          | Array of input URLs.                            |
| `imagesParameter`   | `UIImage[]`         | Array of image file paths or objects.           |
| `fileURLsParameter` | `string[]`          | Array of input file paths (local file URLs).    |

### `Intent` Methods

| Method                         | Return Type                 | Example                                |
| ------------------------------ | --------------------------- | -------------------------------------- |
| `Intent.text(value)`           | `IntentTextValue`           | `Intent.text("Hello")`                 |
| `Intent.attributedText(value)` | `IntentAttributedTextValue` | `Intent.attributedText("Styled Text")` |
| `Intent.url(value)`            | `IntentURLValue`            | `Intent.url("https://example.com")`    |
| `Intent.json(value)`           | `IntentJsonValue`           | `Intent.json({ key: "value" })`        |
| `Intent.file(path)`            | `IntentFileValue`           | `Intent.file("/path/to/file.txt")`     |
| `Intent.fileURL(path)`         | `IntentFileURLValue`        | `Intent.fileURL("/path/to/file.pdf")`  |
| `Intent.image(UIImage)`        | `IntentImageValue`          | `Intent.image(uiImage)`                |
| `Intent.view(node, value?)`    | `IntentViewValue`           | `Intent.view(<View />)`                |

***

## 8. Best Practices and Notes

- Always call `Script.exit()` to properly terminate the script and return a result.
- When displaying a UI, ensure `Navigation.present()` is awaited before calling `Script.exit()`.
- Use **"Run Script in App"** for large files or images to avoid process termination due to memory constraints.
- You can use `queryParameters` when launching scripts via URL scheme if additional data is needed.



---
url: /guide/Intent/SnippetIntent.md
---

# SnippetIntent

SnippetIntent is a special kind of AppIntent whose purpose is to render **interactive Snippet UI cards** inside the Shortcuts app (iOS 26+).

Key characteristics:

1. Must be registered in `app_intents.tsx`
2. Must specify `protocol: AppIntentProtocol.SnippetIntent`
3. `perform()` **must return a VirtualNode (TSX UI)**
4. Must be returned via `Intent.snippetIntent()`
5. Must be invoked from the Shortcuts action **“Show Snippet Intent”**
6. SnippetIntent is ideal for building interactive, step-based UI inside a Shortcut

It is not a data-returning Intent; it is exclusively for UI rendering in Shortcuts.

***

## 2. System Requirements

**SnippetIntent requires iOS 26 or later.**

On iOS versions earlier than 26:

- `Intent.snippetIntent()` is not available
- `Intent.requestConfirmation()` cannot be used
- The Shortcuts action “Show Snippet Intent” does not exist
- SnippetIntent-type AppIntents cannot be invoked by Shortcuts

***

## 3. Registering a SnippetIntent (app\_intents.tsx)

Example:

```tsx
export const PickColorIntent = AppIntentManager.register<void>({
  name: "PickColorIntent",
  protocol: AppIntentProtocol.SnippetIntent,
  perform: async () => {
    return <PickColorView />
  }
})
```

Another SnippetIntent:

```tsx
export const ShowResultIntent = AppIntentManager.register({
  name: "ShowResultIntent",
  protocol: AppIntentProtocol.SnippetIntent,
  perform: async ({ content }: { content: string }) => {
    return <ResultView content={content} />
  }
})
```

Requirements:

- `protocol` **must** be `AppIntentProtocol.SnippetIntent`
- `perform()` **must** return a TSX UI (VirtualNode)
- SnippetIntent cannot return non-UI types such as text, numbers, JSON, or file paths

***

## 4. Wrapping SnippetIntent Return Values — `Intent.snippetIntent`

A SnippetIntent cannot be passed directly to `Script.exit()`.
It must be wrapped in a `IntentSnippetIntentValue`.

```tsx
const snippetValue = Intent.snippetIntent(
  ShowResultIntent({ content: "Example Text" })
)

Script.exit(snippetValue)
```

### Type Definition

```ts
type SnippetIntentValue = {
  value?: IntentAttributedTextValue | IntentFileURLValue | IntentJsonValue | IntentTextValue | IntentURLValue | IntentFileValue | null
  snippetIntent: AppIntent<any, VirtualNode, AppIntentProtocol.SnippetIntent>
}

declare class IntentSnippetIntentValue extends IntentValue<
  'SnippetIntent',
  SnippetIntentValue
> {
  value: SnippetIntentValue
  type: 'SnippetIntent'
}
```

This wrapper makes the return value compatible with the Shortcuts “Show Snippet Intent” action.

***

## 5. Snippet Confirmation UI — `Intent.requestConfirmation`

iOS 26 Snippet Framework provides built-in confirmation UI driven by SnippetIntent.

### API

```ts
Intent.requestConfirmation(
  actionName: ConfirmationActionName,
  intent: AppIntent<any, VirtualNode, AppIntentProtocol.SnippetIntent>,
  options?: {
    dialog?: Dialog;
    showDialogAsPrompt?: boolean;
  }
): Promise<void>
```

### ConfirmationActionName

A predefined list of semantic action names used by system UI:

```
"add" | "addData" | "book" | "buy" | "call" | "checkIn" |
"continue" | "create" | "do" | "download" | "filter" |
"find" | "get" | "go" | "log" | "open" | "order" |
"pay" | "play" | "playSound" | "post" | "request" |
"run" | "search" | "send" | "set" | "share" |
"start" | "startNavigation" | "toggle" | "turnOff" |
"turnOn" | "view"
```

### Example

```tsx
await Intent.requestConfirmation(
  "set",
  PickColorIntent()
)
```

Execution behavior:

- Displays a Snippet UI for confirmation
- If the user confirms → Promise resolves and script continues
- If the user cancels → execution stops (system-driven behavior)

***

## 6. The “Show Snippet Intent” Action in Shortcuts (iOS 26+)

iOS 26 adds a new Shortcuts action:

**Show Snippet Intent**

This action is the only correct way to display SnippetIntent UI.

### Comparison with Other Scripting Actions

| Shortcuts Action              | UI Shown                       | Supports SnippetIntent | Usage               |
| ----------------------------- | ------------------------------ | ---------------------- | ------------------- |
| Run Script                    | None                           | No                     | Background logic    |
| Run Script in App             | Fullscreen UI inside Scripting | No                     | Rich app-level UI   |
| Show Snippet Intent (iOS 26+) | Snippet card UI                | Yes                    | SnippetIntent flows |

### Usage

1. Add “Show Snippet Intent” in Shortcuts
2. Select a Scripting script project
3. The script must return `Intent.snippetIntent(...)`
4. Shortcuts renders the UI in a Snippet card

***

## 7. IntentMemoryStorage — Cross-Intent State Store

## Why It Exists

Every AppIntent execution runs in an isolated environment:

- After an AppIntent `perform()` completes → its execution context is destroyed
- After a script calls `Script.exit()` → the JS context is destroyed

This means local variables **cannot persist between AppIntent calls**.

Snippet flows commonly involve:
PickColor → SetColor → ShowResult

Therefore a cross-Intent state mechanism is required.

***

## IntentMemoryStorage API

```ts
namespace IntentMemoryStorage {
  function get<T>(key: string): T | null
  function set(key: string, value: any): void
  function remove(key: string): void
  function contains(key: string): boolean
  function clear(): void
  function keys(): string[]
}
```

### Purpose

- Store small pieces of shared data across multiple AppIntents
- Works during the entire Shortcut flow
- Ideal for selections, temporary configuration, or intent-to-intent handoff

### Example

```ts
IntentMemoryStorage.set("color", "systemBlue")

const color = IntentMemoryStorage.get<Color>("color")
```

### Guidelines

Not recommended for large data.
For large data:

- Use `Storage` (persistent key-value store)
- Or save files via `FileManager` in `appGroupDocumentsDirectory`

IntentMemoryStorage should be treated as **temporary, lightweight state**.

***

## 8. Full Example Combining All Features (iOS 26+)

## app\_intents.tsx

```tsx
export const SetColorIntent = AppIntentManager.register({
  name: "SetColorIntent",
  protocol: AppIntentProtocol.AppIntent,
  perform: async (color: Color) => {
    IntentMemoryStorage.set("color", color)
  }
})

export const PickColorIntent = AppIntentManager.register<void>({
  name: "PickColorIntent",
  protocol: AppIntentProtocol.SnippetIntent,
  perform: async () => {
    return <PickColorView />
  }
})

export const ShowResultIntent = AppIntentManager.register({
  name: "ShowResultIntent",
  protocol: AppIntentProtocol.SnippetIntent,
  perform: async ({ content }: { content: string }) => {
    const color = IntentMemoryStorage.get<Color>("color") ?? "systemBlue"
    return <ResultView content={content} color={color} />
  }
})
```

## intent.tsx

```tsx
async function runIntent() {

  // 1. Ask the user to confirm setting the color via Snippet
  await Intent.requestConfirmation(
    "set",
    PickColorIntent()
  )

  // 2. Read Shortcuts input
  const textContent =
    Intent.shortcutParameter?.type === "text"
      ? Intent.shortcutParameter.value
      : "No text parameter from Shortcuts"

  // 3. Create final SnippetIntent UI
  const snippetIntentValue = Intent.snippetIntent({
    snippetIntent: ShowResultIntent({ content: textContent })
  })

  Script.exit(snippetIntentValue)
}

runIntent()
```

## Shortcuts Flow

1. User provides text
2. “Show Snippet Intent” runs the script
3. Script displays PickColorIntent confirmation UI via requestConfirmation
4. After confirmation, displays ShowResultIntent Snippet UI
5. Uses IntentMemoryStorage to persist the selected color

***

## 9. Summary

This document introduces all **new** Scripting features added for iOS 26+:

1. **SnippetIntent**

   - Registered using `AppIntentManager`
   - Returns TSX UI
   - Requires iOS 26+

2. **Intent.snippetIntent**

   - Wraps a SnippetIntent for Script.exit

3. **Intent.requestConfirmation**

   - Presents a confirmation Snippet UI
   - Requires SnippetIntent

4. **“Show Snippet Intent” action in Shortcuts**

   - Required to display SnippetIntent UI

5. **IntentMemoryStorage**

   - Lightweight cross-AppIntent storage
   - Not suitable for large binary/content data
   - Complements multi-step Snippet flows



---
url: /guide/Interactive Widget and LiveActivity.md
---

# Interactive Widget and LiveActivity

The **Scripting** app supports adding interactivity to **widgets** and **LiveActivity**, allowing you to create dynamic and interactive UIs using `Button` and `Toggle` components. These controls can execute **AppIntents** to trigger actions, making your widgets and live activities more powerful.

***

## 1. Introduction to AppIntents

### What are AppIntents?

An **AppIntent** defines a specific action that can be triggered by a control (e.g., a `Button` or `Toggle`) in a widget or LiveActivity UI. AppIntents enable seamless interaction and functionality by linking UI components with executable logic.

### Supported Protocols

AppIntents can implement the following protocols:

- **`AppIntent`**: General-purpose intents for triggering custom actions.
- **`AudioPlaybackIntent`**: Handles audio playback (e.g., play, pause, or toggle audio states).
- **`AudioRecordingIntent`**: Manages audio recording states (requires iOS 18+ and a LiveActivity to stay active during recording).
- **`LiveActivityIntent`**: Modifies or manages LiveActivity states.

***

## 2. Registering an AppIntent

To use an **AppIntent**, it must first be registered in the `app_intents.tsx` file using the `AppIntentManager.register` method.

### Example: Registering AppIntents

```typescript
// app_intents.tsx

import { AppIntentManager, AppIntentProtocol } from "scripting"

// Register an AppIntent
const IntentWithoutParams = AppIntentManager.register({
  name: "IntentWithoutParams",
  protocol: AppIntentProtocol.AppIntent,
  perform: async (params: undefined) => {
    // Perform a custom action
    console.log("Intent triggered")
    // Optionally reload widgets
    Widget.reloadAll()
  }
})

// Register an AppIntent with parameters
const ToggleIntentWithParams = AppIntentManager.register({
  name: "ToggleIntentWithParams",
  protocol: AppIntentProtocol.AudioPlaybackIntent,
  perform: async (audioName: string) => {
    // Perform action based on the parameter
    console.log(`Toggling audio playback for: ${audioName}`)
    Widget.reloadAll()
  }
})
```

***

## 3. Using AppIntents in Widgets or LiveActivity UIs

After registering an AppIntent, it can be linked to interactive components like `Button` and `Toggle` in your `widget.tsx` or LiveActivity UI file.

### Example: Using AppIntents in a Widget

```typescript
// widget.tsx

import { VStack, Button, Toggle } from "scripting"
import { IntentWithoutParams, ToggleIntentWithParams } from "./app_intents"
import { model } from "./model"

function WidgetView() {
  return (
    <VStack>
      <Button
        title="Tap me"
        intent={IntentWithoutParams(undefined)} // Trigger the intent without parameters
      />
      <Toggle
        title="Play or Pause"
        value={model.checked}
        intent={ToggleIntentWithParams("audio_name")} // Trigger the intent with a parameter
      />
    </VStack>
  )
}

// Present the widget
Widget.present(<WidgetView />)
```

***

## 4. API Reference

### `AppIntentManager.register`

Registers an AppIntent for use in widgets or LiveActivity UIs.

#### Parameters:

- `name` (string): A unique name for the intent.
- `protocol` (`AppIntentProtocol`): Specifies the type of intent (e.g., `AppIntent`, `AudioPlaybackIntent`).
- `perform` (function): The function to execute when the intent is triggered.

#### Returns:

- An `AppIntentFactory` function that can be used to create instances of the registered intent.

***

### `Button` Component

A tappable button that triggers an AppIntent.

#### Props:

- `title` (string): The button’s label.
- `intent` (`AppIntent<any>`): The AppIntent to execute when the button is tapped.
- `systemImage` (optional): An SF Symbol to display on the button.

***

### `Toggle` Component

A toggle switch that triggers an AppIntent when its value changes.

#### Props:

- `value` (boolean): Indicates the toggle's state (on/off).
- `intent` (`AppIntent<any>`): The AppIntent to execute when the toggle is toggled.
- `title` (string): The toggle’s label.
- `systemImage` (optional): An SF Symbol to display with the toggle.

***

## 5. Notes and Best Practices

- Use `Widget.reloadAll()` within `perform` functions to update widgets dynamically after executing an intent.
- Define your AppIntents in `app_intents.tsx` for organization and reusability.
- Use appropriate protocols (e.g., `AudioPlaybackIntent`) to match the intent's functionality.



---
url: /guide/LiveActivity.md
---

# LiveActivity

The `LiveActivity` API enables you to display real-time, dynamic information from your script on the Lock Screen and, where supported, in the Dynamic Island on iOS devices. It provides a structured interface to start, update, and end Live Activities, and observe their state throughout their lifecycle.

This document provides a complete guide to using the **LiveActivity API** in the Scripting app, including:

- Core concepts and lifecycle
- How to register a Live Activity UI
- How to start, update, and end Live Activities
- UI layout for Dynamic Island and Lock Screen
- Full TypeScript/TSX examples
- Detailed descriptions of every type and option

The API wraps Apple’s ActivityKit and brings it into the Scripting environment with a React-style UI building approach.

***

## 1. Understanding Live Activities

A Live Activity can appear in the following regions:

- Lock Screen
- Dynamic Island (iPhone 14 Pro and later)
- Banner-style presentation on devices without Dynamic Island

Live Activities are used for time-based and progress-based information, such as:

- Timers
- Fitness progress
- Delivery tracking
- Countdowns and reminders
- Real-time status updates

In Scripting, each Live Activity consists of:

1. **contentState** (a JSON-serializable object that updates over time)
2. **UI Builder** (a function that produces TSX UI for each state)

***

## 2. Live Activity State Types

```ts
type LiveActivityState = "active" | "dismissed" | "ended" | "stale";
```

| State     | Description                                                                                 |
| --------- | ------------------------------------------------------------------------------------------- |
| active    | The Live Activity is visible and can receive content updates.                               |
| stale     | The Live Activity is out of date. The system expects an update.                             |
| ended     | The Live Activity ended but may remain visible for up to four hours or a user-defined time. |
| dismissed | The Live Activity is no longer visible.                                                     |

***

## 3. LiveActivityDetail Type

```ts
type LiveActivityDetail = {
  id: string;
  state: LiveActivityState;
};
```

Represents a summary of each active Live Activity.

***

## 4. Live Activity UI Types

## 4.1 LiveActivityUIProps

```ts
type LiveActivityUIProps = {
  content: VirtualNode;
  compactLeading: VirtualNode;
  compactTrailing: VirtualNode;
  minimal: VirtualNode;
  children: VirtualNode | VirtualNode[];
};
```

These regions correspond to ActivityKit’s UI areas:

| Property        | Region                                                |
| --------------- | ----------------------------------------------------- |
| content         | Lock Screen and non–Dynamic Island devices            |
| compactLeading  | Leading area of compact Dynamic Island                |
| compactTrailing | Trailing area of compact Dynamic Island               |
| minimal         | The smallest pill-style display                       |
| children        | The expanded Dynamic Island layout (multiple regions) |

***

## 5. Registering a Live Activity UI

Live Activities **must** be registered inside a standalone file such as `live_activity.tsx`.

```tsx
import { LiveActivity, LiveActivityUI, LiveActivityUIBuilder } from "scripting";

export type State = {
  mins: number;
};

function ContentView(state: State) {
  return (
    <HStack activityBackgroundTint={{ light: "clear", dark: "clear" }}>
      <Image systemName="waterbottle" foregroundStyle="systemBlue" />
      <Text>{state.mins} minutes left until the next drink</Text>
    </HStack>
  );
}

const builder: LiveActivityUIBuilder<State> = (state) => {
  return (
    <LiveActivityUI
      content={<ContentView {...state} />}
      compactLeading={
        <HStack>
          <Image systemName="clock" />
          <Text>{state.mins}m</Text>
        </HStack>
      }
      compactTrailing={<Image systemName="waterbottle" foregroundStyle="systemBlue" />}
      minimal={<Image systemName="clock" />}>
      <LiveActivityUIExpandedCenter>
        <ContentView {...state} />
      </LiveActivityUIExpandedCenter>
    </LiveActivityUI>
  );
};

export const MyLiveActivity = LiveActivity.register("MyLiveActivity", builder);
```

***

## 6. Using a Live Activity in Your Script

```tsx
import {
  Button,
  Text,
  VStack,
  Navigation,
  NavigationStack,
  useMemo,
  useState,
  LiveActivityState,
  BackgroundKeeper,
} from "scripting";

import { MyLiveActivity } from "./live_activity";

function Example() {
  const dismiss = Navigation.useDismiss();
  const [state, setState] = useState<LiveActivityState>();

  const activity = useMemo(() => {
    const instance = MyLiveActivity();

    instance.addUpdateListener((s) => {
      setState(s);
      if (s === "dismissed") {
        BackgroundKeeper.stop();
      }
    });

    return instance;
  }, []);

  return (
    <NavigationStack>
      <VStack
        navigationTitle="Live Activity Example"
        navigationBarTitleDisplayMode="inline"
        toolbar={{
          cancellationAction: <Button title="Done" action={dismiss} />,
        }}>
        <Text>Activity State: {state ?? "-"}</Text>

        <Button
          title="Start Live Activity"
          disabled={state != null}
          action={() => {
            let count = 5;
            BackgroundKeeper.keepAlive();

            activity.start({ mins: count });

            function tick() {
              setTimeout(() => {
                count -= 1;
                if (count === 0) {
                  activity.end({ mins: 0 });
                  BackgroundKeeper.stop();
                } else {
                  activity.update({ mins: count });
                  tick();
                }
              }, 60000);
            }

            tick();
          }}
        />
      </VStack>
    </NavigationStack>
  );
}

async function run() {
  await Navigation.present(<Example />);
  Script.exit();
}

run();
```

***

## 7. LiveActivity Class API Reference

## 7.1 start(contentState, options?)

```ts
start(contentState: T, options?: LiveActivityOptions): Promise<boolean>
```

Starts a Live Activity.

### LiveActivityOptions

```ts
type LiveActivityOptions = {
  staleDate?: number | Date;
  relevanceScore?: number;
};
```

- **staleDate**: Timestamp(ms) or Date object at which the activity becomes stale
- **relevanceScore**: Determines which Live Activity is prioritized in the Dynamic Island

***

## 7.2 update(contentState, options?)

```ts
update(contentState: T, options?: LiveActivityUpdateOptions)
```

### LiveActivityUpdateOptions

```ts
type LiveActivityUpdateOptions = {
  staleDate?: number | Date;
  relevanceScore?: number;
  alert?: {
    title: string;
    body: string;
  };
};
```

Alerts appear on Apple Watch when sending an update.

***

## 7.3 end(contentState, options?)

```ts
end(contentState: T, options?: LiveActivityEndOptions)
```

### LiveActivityEndOptions

```ts
type LiveActivityEndOptions = {
  staleDate?: number ｜ Date
  relevanceScore?: number
  dismissTimeInterval?: number
}
```

Rules for dismissal (seconds):

- Not provided: default system retention (up to 4 hours)
- \<= 0: remove immediately
- \> 0: remove after the specified interval

***

## 7.4 Reading Activity State

```ts
getActivityState(): Promise<LiveActivityState | null>
```

***

## 7.5 Listening for State Changes

```ts
addUpdateListener(listener);
removeUpdateListener(listener);
```

Triggered when the Live Activity transitions between:

- active → stale
- active → ended
- ended → dismissed

***

## 7.6 Static Methods

```ts
static areActivitiesEnabled(): Promise<boolean>
static getAllActivities(): Promise<LiveActivityDetail[]>
static getAllActivitiesIds(): Promise<string[]>
static getActivityState(activityId: string)
static from(activityId, name)
static endAllActivities(options?)
```

***

## 8. UI Components for Expanded Layout

| Component                      | Description                       |
| ------------------------------ | --------------------------------- |
| LiveActivityUI                 | Root layout container             |
| LiveActivityUIExpandedLeading  | Leading region of expanded layout |
| LiveActivityUIExpandedTrailing | Trailing region                   |
| LiveActivityUIExpandedCenter   | Center region                     |
| LiveActivityUIExpandedBottom   | Bottom region                     |

These components help structure the expanded Dynamic Island.

***

## 9. Best Practices

## 9.1 contentState must be JSON-serializable

The following are not allowed:

- Functions
- Date objects (must use timestamps)
- Class instances
- Non-serializable structures

## 9.2 Live Activity registration must be in a standalone file

This is required due to UI compilation and ActivityKit rules.

## 9.3 Live Activities survive script termination

If your script needs to keep running (e.g., timers), use:

```ts
BackgroundKeeper.keepAlive();
```

***

## 10. Minimal Example

```ts
const activity = MyLiveActivity();

await activity.start({ mins: 10 });

await activity.update({ mins: 5 });

await activity.end({ mins: 0 }, { dismissTimeInterval: 0 });
```

## 11. Notes

- Live Activity starts asynchronously. You need to wait for `start` to return `true` before calling `update` and `end`.
- Live Activity cannot access documents and iCloud directories. If you want to access files or render images, you must save them to `FileManager.appGroupDocumentsDirectory`. For example, to render an image, you save it to `FileManager.appGroupDocumentsDirectory`, then use `<Image filePath={Path.join(FileManager.appGroupDocumentsDirectory, 'example.png')} />` to render it.
- Live Activity can access the Storage data shared with the app.



---
url: /guide/Quick Start.md
---

# Quick Start

Welcome to **Scripting**, an iOS app that lets you code UI components in **TypeScript** using **React-like TSX syntax**. With Scripting, you can create and present iOS utility UI pages through a familiar coding structure, using wrapped SwiftUI views for a smooth, native experience on iOS. This guide walks you through setting up your project, creating components, and working with hooks to build dynamic interfaces.

### Table of Contents

1. **Getting Started**
2. **Creating a Script Project**
3. **Importing Components**
4. **Creating Custom Components**
5. **Presenting UI Views**
6. **Using Hooks**
7. **Building Complex UIs**

***

### 1. Getting Started

In Scripting, you’ll create simple UI elements by defining them with function components. Every component and API you’ll need can be imported from the `scripting` package.

### 2. Creating a Script Project

Before you begin coding, you need to **create a script project**. Once the project is set up, write your code in the `index.tsx` file. This is your main entry point for defining UI components and logic.

Example setup in `index.tsx`:

```tsx
import { VStack, Text } from "scripting"

// Define a custom view component
function View() {
  return (
    <VStack>
      <Text>Hello, Scripting!</Text>
    </VStack>
  )
}
```

***

### 3. Importing Views

All views and some APIs from SwiftUI are wrapped and accessible through the `scripting` package. Here’s a list of some available views:

- **Layout Views**: `VStack`, `HStack`, `ZStack`, `Grid`
- **Controls**: `Button`, `Picker`, `Toggle`, `Slider`, `ColorPicker`
- **Collections**: `List`, `Section`
- **Date and Time**: `DatePicker`
- **Text and Labels**: `Text`, `Label`, `TextField`

To use these in your project, import them as shown:

```tsx
import { VStack, Text, Button, Picker } from "scripting"
```

***

### 4. Creating Custom Components

Function components in Scripting work just like in React, with JSX-like syntax for building reusable components.

Example:

```tsx
import { VStack, HStack, Text, Button } from "scripting"

function Greeting({
   name
}: {
   name: string 
}) {
  return (
    <HStack>
      <Text>Hello, {name}!</Text>
    </HStack>
  )
}

function MainView() {
  return (
    <VStack>
      <Greeting name="Scripting User" />
      <Button 
        title="Click Me" 
        action={() => console.log("Button Clicked!")}
      />
    </VStack>
  )
}
```

***

### 5. Presenting UI Views

To present a UI view, use the `Navigation.present` method. This allows you to display a custom component as a modal view and handle its dismissal. The `Navigation.present` method returns a promise that fulfills when the view is dismissed. To avoid memory leaks, always call `Script.exit()` after the view is dismissed.

Example:

```tsx
import { VStack, Text, Navigation, Script } from "scripting"

function View() {
  return (
    <VStack>
      <Text>Hello, Scripting!</Text>
    </VStack>
  )
}

// Present the view
Navigation.present({ 
  element: <View />
}).then(() => {
  // Clean up to avoid memory leaks
  Script.exit()
})
```

In this example, `Navigation.present({ element: <View /> })` displays the `View` component, and when the user dismisses it, `Script.exit()` ensures resources are freed.

***

### 6. Using Hooks

Scripting supports a range of React-like hooks for managing state, effects, memoization, and context. Here’s a guide on how to use each hook with examples:

***

#### `useState`

The `useState` hook lets you add local state to a function component.

```tsx
import { useState, VStack, Text, Button } from "scripting"

function Counter() {
  const [count, setCount] = useState(0)

  return (
    <VStack>
      <Text>Count: {count}</Text>
      <Button
        title="Increment"
        action={() => setCount(count + 1)}
      />
    </VStack>
  )
}
```

In this example, clicking the button updates the `count` variable, which automatically re-renders the component.

***

#### `useEffect`

The `useEffect` hook lets you perform side effects in your components, such as fetching data or setting up subscriptions.

```tsx
import { useState, useEffect, VStack, Text } from "scripting"

function TimeDisplay() {
  const [time, setTime] = useState(
    new Date().toLocaleTimeString()
  )

  useEffect(() => {
    let timerId: number

    const startTimer = () => {
      timerId = setTimeout(() => {
        setTime(new Date().toLocaleTimeString())
      }, 1000)
    }

    startTimer()
    
    return () => clearTimeout(timerId) // Clean up on unmount
  }, [])

  return <Text>Current Time: {time}</Text>
}
```

In this example, the `useEffect` hook sets up an interval to update the `time` variable every second, and clears the interval on component unmount.

***

#### `useReducer`

The `useReducer` hook is useful for managing complex state logic in components.

```tsx
import { useReducer, VStack, Text, Button } from "scripting"

type Action = { 
  type: "increment"
} | {
  type: "decrement"
}
const reducer = (state: number, action: Action) => {
  switch (action.type) {
    case "increment":
      return state + 1
    case "decrement":
      return state - 1
    default:
      return state
  }
}

function Counter() {
  const [count, dispatch] = useReducer(reducer, 0)

  return (
    <VStack>
      <Text>Count: {count}</Text>
      <Button 
        title="Increment"
        action={() => dispatch({ type: "increment" })}
      />
      <Button
        title="Decrement"
        action={() => dispatch({ type: "decrement" })}
      />
    </VStack>
  )
}
```

The `useReducer` hook helps you handle complex state transitions by using a reducer function.

***

#### `useCallback`

The `useCallback` hook lets you memoize functions, optimizing performance by preventing unnecessary re-creations of the function on every render.

```tsx
import { useState, useCallback, VStack, Text, Button } from "scripting"

function Counter() {
  const [count, setCount] = useState(0)

  const increment = useCallback(() => {
    setCount((prev) => prev + 1)
  }, [])

  return (
    <VStack>
      <Text>Count: {count}</Text>
      <Button 
        title="Increment"
        action={increment}
      />
    </VStack>
  )
}
```

With `useCallback`, the `increment` function is only re-created when necessary, improving performance in large or frequently updated components.

***

#### `useMemo`

The `useMemo` hook lets you memoize values, caching expensive computations for better performance.

```tsx
import { useState, useMemo, VStack, Text, Button } from "scripting"

function FactorialCounter() {
  const [count, setCount] = useState(1)

  const factorial = useMemo(() => {
    let result = 1
    for (let i = 1; i <= count; i++) result *= i
    return result
  }, [count])

  return (
    <VStack>
      <Text>Factorial of {count} is {factorial}</Text>
      <Button 
        title="Increase"
        action={() => setCount(count + 1)}
      />
    </VStack>
  )
}
```

The `useMemo` hook optimizes performance by only re-calculating the factorial when `count` changes.

***

#### `useContext`

The `useContext` hook allows components to access shared state across the app without prop drilling, using a Context API.

```tsx
import { createContext, useContext, VStack, Text, Button } from "scripting"

const CountContext = createContext<number>()

function Display() {
  const count = useContext(CountContext)
  return <Text>Shared Count: {count}</Text>
}

function App() {
  return (
    <CountContext.Provider value={42}>
      <VStack>
        <Display />
      </VStack>
    </CountContext.Provider>
  )
}
```

In this example, `useContext` accesses `CountContext` to get a shared count value across the app.

***

### 7. Building Complex UIs

Combine available views, hooks, and custom components to create complex, fully functional UIs.

Example:

```tsx
import { useState, VStack, Text, TextField, List, Section, NavigationStack, Script } from "scripting"

function ToDoApp() {
  const [tasks, setTasks] = useState(["Task 1", "Task 2", "Task 3"])
  const [content, setContent] = useState("")

  return (
    <NavigationStack>
        <List
          navigationTitle="My Tasks"
        >
          <Section>
            {tasks.map((task, index) => (
              <Text key={index}>{task}</Text>
            ))}
          </Section>
          
          <TextField
            title="New Task"
            value={content}
            onSubmit={() => {
              if (content.length === 0) {
                return
              }
              setTasks([...tasks, content])
              setContent("")
            }}
          />
        </List>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({
    element: <ToDoApp />
  })

  Script.exit()
}
```

***

For further details, check the full API documentation, which includes more examples and use cases for `scripting` package components and APIs.



---
url: /guide/Rime.md
---

# Rime

The `Rime` namespace exposes a programmable Chinese input-method engine that ships with the main app and the keyboard extension. Use it to build custom input flows: load schemas, feed key events, render candidates yourself, and commit the chosen text.

The engine is process-global; you set it up once and create one `Rime.Session` per input session.

***

## Data directories

`Rime` reads schemas/dictionaries from a **shared data directory** and stores user state (user dictionaries, build cache) in a **user data directory**. Both default to the app group container shared between the main app and the keyboard extension, so the schemas you import in the main app are immediately available from the keyboard.

- `Rime.sharedDataDir` — string path to the shared (read-only) directory.
- `Rime.userDataDir` — string path to the user directory.

You may override either path when calling `Rime.setup({ sharedDataDir, userDataDir })`, for example when running tests in a private sandbox.

***

## Lifecycle

### `Rime.setup(options?): Promise<void>`

Initializes the engine. Call this once before any other `Rime.*` API. Subsequent calls in the same process resolve successfully without re-initializing.

```ts
await Rime.setup()
// or:
await Rime.setup({
  sharedDataDir: "/path/to/shared",
  userDataDir: "/path/to/user",
  appName: "my.input.method",  // log identifier
})
```

### `Rime.deploy(options?): Promise<void>`

Recompiles schemas and rebuilds user dictionaries when needed. Call after importing or modifying schema/dict files in `sharedDataDir`.

```ts
await Rime.deploy()
await Rime.deploy({ fullCheck: true })  // force a full rebuild
```

### Status getters (synchronous)

```ts
Rime.version       // string, e.g. "1.16.1"
Rime.isSetUp       // boolean
Rime.isDeploying   // boolean
```

***

## Schemas

### `Rime.listSchemas(): Promise<{ id, name }[]>`

```ts
const schemas = await Rime.listSchemas()
// [{ id: "luna_pinyin", name: "朙月拼音" }, ...]
```

### `Rime.getCurrentSchema(): { id, name } | null`

Returns the engine-wide current schema, or `null` when no schema is active.

### `Rime.selectSchema(schemaId): Promise<void>`

Switches the engine-wide default schema. New sessions created after this call inherit the new schema; existing sessions keep their previous schema until you call `session.selectSchema(id)` on them.

```ts
await Rime.selectSchema("luna_pinyin")
```

***

## Engine-wide options

These flags (e.g. `ascii_mode`, `full_shape`, `simplification`) are propagated to new sessions through an internal shared session. Per-session overrides are still possible via `session.setOption(...)`.

```ts
Rime.getOption("ascii_mode")           // boolean
Rime.setOption("ascii_mode", true)
Rime.getProperty("language")           // string | null
Rime.setProperty("language", "zh")
```

***

## Notifications

`Rime.onNotification` is a single optional handler invoked on the main thread when the engine fires events.

```ts
Rime.onNotification = (event) => {
  switch (event.type) {
    case "deployStart":
    case "deploySuccess":
    case "deployFailure":
      // event.sessionId — usually 0 for engine-wide events
      break
    case "schemaChanged":
      // event.schemaId, optional event.schemaName
      break
    case "optionChanged":
      // event.option (string), event.enabled (boolean)
      break
    case "other":
      // event.raw = { type, value } — unrecognised events
      break
  }
}

// Detach when no longer needed:
Rime.onNotification = null
```

To support multiple subscribers, fan out from one handler:

```ts
const subs = []
Rime.onNotification = (e) => subs.forEach((s) => s(e))
```

***

## `Rime.Session`

A session represents a single input attempt. Create one with `new Rime.Session()` and release it with `session.close()` when done.

```ts
const session = new Rime.Session()
try {
  if (!session.processKey(charCode)) {
    // engine did not consume the key — pass it through to the host text field
    CustomKeyboard.insertText(String.fromCharCode(charCode))
  }
  if (session.commit) {
    CustomKeyboard.insertText(session.commit)
  }
  if (session.context?.preedit) {
    CustomKeyboard.setMarkedText(session.context.preedit, 0, 0)
  } else {
    CustomKeyboard.unmarkText()
  }
} finally {
  session.close()
}
```

### Key handling

```ts
session.processKey(keyCode: number, modifiers?: number): boolean
```

`keyCode` uses X11 keysym values (e.g. `'w'.charCodeAt(0)` is `0x77`, `Return` is `0xff0d`). Returns `true` when the engine consumed the key.

### Composition state

```ts
session.context  // Rime.Context | null — fresh snapshot per access
session.commit   // string | null — drains pending commit text
session.status   // Rime.Status | null — schema + mode flags
```

`session.context` has the shape:

```ts
{
  preedit: string | null,
  cursorPos: number,
  selectionStart: number,
  selectionEnd: number,
  commitTextPreview?: string,
  selectKeys?: string,
  selectLabels?: string[],
  menu: {
    pageNo: number,
    pageSize: number,
    isLastPage: boolean,
    highlightedIndex: number,
    candidates: Array<{ text: string, comment: string | null }>,
  } | null,
}
```

### Candidate selection

```ts
session.selectCandidate(index: number): boolean              // absolute index in the full menu
session.selectCandidateOnCurrentPage(index: number): boolean // 0-based on current page
```

### Commit / clear

```ts
session.commitComposition(): { text: string | null } | null  // force commit
session.clearComposition(): void                              // discard
```

### Per-session schema and options

```ts
session.selectSchema(schemaId: string): boolean
session.setOption(name: string, value: boolean): void
session.getOption(name: string): boolean
session.setProperty(name: string, value: string): void
session.getProperty(name: string): string | null
session.currentSchema  // { id, name } | null (derived from status)
```

### Closing

```ts
session.close(): void
```

After `close()`, all methods become no-ops (`processKey` returns `false`, `context` returns `null`, etc.) and `session.closed` is `true`. Calling `close()` again is safe.

***

## End-to-end example

```ts
await Rime.setup()
await Rime.deploy()

const session = new Rime.Session()

try {
  // type "wo"
  session.processKey(0x77 /* w */)
  session.processKey(0x6f /* o */)

  const ctx = session.context!
  console.log(ctx.preedit)                       // "wo"
  console.log(ctx.menu?.candidates[0].text)      // "我"

  // accept first candidate
  session.selectCandidate(0)
  console.log(session.commit)                    // "我"
} finally {
  session.close()
}
```

***

## Notes

- The shared and user directories must exist and be writable. The default app-group locations are created on first `setup()` automatically.
- The engine deploys schemas in the background; render a "loading" indicator while `Rime.isDeploying` is `true`.
- To switch between Chinese and ASCII (English) modes from a key, your schema needs a `key_binder` section. Without one, `Rime.setOption("ascii_mode", true)` still works, but a Shift-toggle key will not.
- Importing user dictionaries: drop `.dict.yaml` files into `sharedDataDir`, then call `Rime.deploy()`.



---
url: /guide/Script/Per-Script Permissions.md
---

# Per-Script Permissions

Scripting can require **per-script permission** for sensitive device capabilities. When the user enables **Require Per-Script Permission** in Settings, each script must be individually granted access to capabilities such as Calendar, Reminders, Contacts, Location, Photos, HomeKit, Health, the clipboard, and the file system — even if the app itself already has the corresponding system permission.

By default a capability is requested the first time the script calls the matching API. `Script.requestAccess` lets a script request several capabilities up front, so the user grants them all at once instead of being prompted one by one.

***

## `ScriptingApi`

Identifiers for the capabilities that can be granted per script:

```ts
type ScriptingApi =
  | "calendar"
  | "reminders"
  | "alarms"
  | "contacts"
  | "location"
  | "homeKit"
  | "photos"
  | "health"
  | "clipboard"
  | "fileSystem"
```

***

## `Script.requestAccess(apis: ScriptingApi[]): Promise<ScriptingApi[]>`

Requests per-script access to one or more capabilities and resolves with the capabilities that are granted.

- `apis` is required and must be a non-empty array. The promise rejects if it is empty or contains an unknown identifier.
- Prompts for the requested capabilities that have not been decided yet for this script, remembers the choices, and enforces them when the corresponding API is later used.
- Capabilities already allowed or denied are not asked again. If every requested capability is already decided, no prompt is shown.
- In environments without a presenting UI (Widget, Keyboard, Notification, or Share extensions), no prompt is shown.
- The prompt lets the user set each capability individually, or use **Allow All** / **Deny All**.
- It does **not** perform a Scripting PRO check. Capabilities that require PRO (such as `alarms`, `health`, `homeKit`) are still enforced when the corresponding API is actually called.

```ts
const granted = await Script.requestAccess(["calendar", "reminders"])

if (granted.includes("calendar")) {
  // The Calendar API can now be used without a first-use prompt.
}
```

***

## Declaring required permissions

You can declare the capabilities a script needs by long-pressing the script and choosing **Required Permissions**. Declared capabilities are requested automatically the first time the script is run from the app.



---
url: /guide/Script/Script (Python).md
---

# 

***

title: Script (Python)
description: Python-side Script API for index scripts: Script.name / queryParameters / metadata / documentsDirectory, plus Script.run and Script.exit for cross-script calls and result delivery.

***

The `scripting` Python package provides a `Script` namespace that mirrors the JS-side `Script` global, so a Python `index.py` can read its runtime context and hand a result back to the JS caller of `await Script.run({name})`.

The package is bundled with the runtime — `from scripting import Script` works out of the box in any Python index script.

***

## Properties

### `Script.name: str`

Name of the currently running script. Empty string if the host did not inject the name (e.g. ad-hoc `Python.run` snippets).

```python
import scripting; Script = scripting.Script
print(Script.name)  # "MyAwesomeScript"
```

### `Script.queryParameters: dict`

Parameters the caller passed via `Script.run({queryParameters})`, the `scripting-ts run ... --queryparameters '<json>'` command, or the `scripting://run/<name>?a=1&b=2` URL scheme. JSON value types are preserved (`bool` / `int` / `float` / `None` / `list` / `dict`); values from a URL scheme are always strings, because URL query strings cannot carry typed values. Returns an empty dict if no parameters were provided.

```python
import scripting; Script = scripting.Script
foo = Script.queryParameters.get("foo", "default")
```

### `Script.metadata: dict`

Display metadata declared in the script's `metadata.json`. Mirrors the JS-side `Script.metadata` object. Common keys:

| Key                   | Type   | Description                                              |
| --------------------- | ------ | -------------------------------------------------------- |
| name                  | string | Script name.                                             |
| icon                  | string | SFSymbol name.                                           |
| iconImage             | string | Optional path to a custom icon image.                    |
| color                 | string | Hex color string (`#FF0000`) or CSS color name.          |
| version               | string | Script version.                                          |
| description           | string | English description.                                     |
| localizedName         | string | Resolved localized name for the current system language. |
| localizedDescription  | string | Resolved localized description.                          |
| localizedNames        | dict   | Localized names by language code.                        |
| localizedDescriptions | dict   | Localized descriptions by language code.                 |
| author                | dict   | `{ name, email?, homepage? }`.                           |
| contributors          | list   | List of objects with the same shape as `author`.         |

Returns an empty dict for ad-hoc `Python.run` calls that aren't tied to an index script.

### `Script.directory: str`

Filesystem path to the current script's source directory (typically `<documents>/scripts/<name>/`). Mirrors the JS-side `Script.directory`. Use this to reference files bundled with the script (assets, sub-modules, etc.). Empty string for ad-hoc `Python.run` snippets that aren't tied to an index script.

```python
import os
import scripting; Script = scripting.Script
asset = os.path.join(Script.directory, "assets", "icon.png")
```

***

## Methods

### `Script.run(name, queryParameters=None, singleMode=False)`

Run another script and synchronously wait for it to exit. Mirrors `await Script.run({name, queryParameters, singleMode})` on the JS side.

```python
def run(name: str, queryParameters: dict | None = None, singleMode: bool = False) -> Any | None
```

| Param           | Type | Required | Description                                                                                        |
| --------------- | ---- | -------- | -------------------------------------------------------------------------------------------------- |
| name            | str  | Yes      | Name of the script to launch.                                                                      |
| queryParameters | dict | No       | Passed to the called script as `Script.queryParameters`; JSON value types are preserved.           |
| singleMode      | bool | No       | When `True`, exits any currently-running instance of `name` before launching. Defaults to `False`. |

Returns whatever the called script delivered through `Script.exit(value)`, or `None` if the script didn't call `Script.exit` with a value.

Raises `RuntimeError` if the host fails to launch the script (script not found, runtime not available, etc.) or if the RPC bridge is missing. Raises `ValueError` for an empty `name`.

```python
import scripting; Script = scripting.Script

result = Script.run("DataFetcher", queryParameters={"url": "https://example.com"})
print("got:", result)
```

### `Script.runTS(path, queryParameters=None, scriptName=None)`

Run a `.ts` / `.tsx` file by absolute filesystem path and synchronously wait for it to exit. Useful when you have a TypeScript helper sitting next to your Python `index.py` (or anywhere on disk) and want to call it directly without registering it as a separate index script.

```python
def runTS(path: str, queryParameters: dict | None = None, scriptName: str | None = None) -> Any | None
```

The host transpiles the source on the fly and runs it as an entry-style JS script — `Script.queryParameters`, `Script.exit(value)`, and the rest of the JS-side `Script` API all work inside the file.

`scriptName` controls the script-namespace the called file runs under — that is the key under which Storage / Keychain etc. are isolated. By default it falls back to the current Python script's `Script.name`, so a Python `index.py` and the `.tsx` helpers it invokes **share the same Storage / Keychain scope**. Pass an explicit string to override; pass an empty string to fall back to the file's basename (independent scope).

`Script.directory` inside the called file is the parent directory of `path`.

Returns whatever the file delivers through `Script.exit(value)`, or `None` if the file completed without calling `Script.exit` with a value. Raises `RuntimeError` if the path doesn't exist, can't be read, fails to transpile, or the JS code throws during evaluation.

```python
import os
import scripting; Script = scripting.Script

helper_path = os.path.join(Script.directory, "helper.tsx")
result = Script.runTS(helper_path, queryParameters={"limit": "10"})
print(result)
```

```typescript
// helper.tsx
const limit = Number(Script.queryParameters.limit ?? "5")
const items = await fetchTopItems(limit)
Script.exit(items)
```

### `Script.exit(value=None)`

Exit the current script. If `value` is provided, it is JSON-serialized and delivered back to the JS caller of `await Script.run({name})` as the resolution value. Without `value`, the JS caller receives `None`.

```python
def exit(value: Any | None = None) -> NoReturn
```

`value` must be JSON-serializable (`dict`, `list`, `str`, `int`, `float`, `bool`, `None`, and combinations). If serialization fails, the JS caller receives `None` (no exception is raised — the call still terminates the script).

```python
import scripting; Script = scripting.Script

result = compute_something()
Script.exit({"ok": True, "result": result})
# Script.exit returns NoReturn — code after this line never runs.
```

***

## Examples

### Receiving parameters and returning a value

```python
# index.py
import scripting; Script = scripting.Script

params = Script.queryParameters
name = params.get("name", "world")
greeting = f"Hello, {name}!"

Script.exit({"greeting": greeting, "length": len(greeting)})
```

```ts
// caller (JS / TS)
const r = await Script.run({
  name: "Greeter",
  queryParameters: { name: "Alice" },
})
console.log(r.greeting)  // "Hello, Alice!"
console.log(r.length)    // 13
```

### Chaining Python scripts

```python
# orchestrator.py
import scripting; Script = scripting.Script

raw = Script.run("Fetcher", queryParameters={"id": "42"})
processed = Script.run("Processor", queryParameters={"data": raw["body"]})
Script.exit(processed)
```

### Reading metadata and resolving asset paths

```python
import os, json
import scripting; Script = scripting.Script

print(f"Running {Script.name} v{Script.metadata.get('version', '?')}")

# Read a file shipped with the script.
config_path = os.path.join(Script.directory, "config.json")
with open(config_path) as f:
    config = json.load(f)
```



---
url: /guide/Script/Script Minimization and Resume.md
---

# Script Minimization and Resume

This section describes the Script APIs related to script minimization and resume behavior. These APIs allow a script running on iPhone to hide its UI without terminating the script instance, and to listen for resume or re-trigger events while the instance remains alive.

These capabilities are suitable for:

- UI-based scripts that need to preserve runtime state after the user hides the interface
- Non-UI scripts that remain alive in the background (for example, notification-driven scripts)

***

## Runtime Model Overview

### Script Instance Lifecycle

- Calling `Script.minimize()` does not terminate the script instance.
- Only `Script.exit()` fully terminates the script and releases resources.
- `Script.onResume()` is triggered only while the script instance is still alive.
- If `Script.exit()` has been called, subsequent triggers will create a new script instance and re-execute the entry file.

### Interaction with URL Schemes

- When using `scripting://run/...`:

  - If an existing instance is alive, `Script.onResume()` will be triggered.
  - The entry file will not be executed again.

- When using `scripting://run_single/...`:

  - All previous instances of the script are terminated.
  - `onResume` of the previous instance will not be triggered.
  - A new instance is created and the entry file runs again.

***

## API Reference

### `Script.supportsMinimization(): boolean`

Determines whether the current environment supports script minimization.

Not all environments allow minimization (for example, certain extension contexts).

```ts
if (Script.supportsMinimization()) {
  // Enable minimization-related logic
}
```

***

### `Script.isMinimized(): boolean`

Returns whether the current script is in the minimized state.

```ts
if (Script.isMinimized()) {
  console.log("Script is currently minimized")
}
```

***

### `Script.minimize(): Promise<boolean>`

Minimizes the current script.

After minimization:

- The UI is hidden.
- The script instance continues running.
- `Script.exit()` is not called.

Behavior rules:

- If the script is already minimized, nothing happens.
- If multiple windows mode is enabled, the method is ignored.
- Return value:

  - `true` if minimization succeeds
  - `false` if minimization is not performed (for example, unsupported environment or ignored state)

```ts
async function handleMinimize() {
  if (!Script.supportsMinimization()) return

  const success = await Script.minimize()
  if (!success) {
    console.log("Minimization was not performed")
  }
}
```

***

### `Script.enableMinimize(enabled?: boolean): void`

Enables minimize-on-swipe-dismiss for the script's **root presented UI** (the first page presented with `Navigation.present`, whether a sheet or a full-screen page).

Once enabled, when the user interactively **swipes the root page down to dismiss it**, the script is minimized instead of being ended: the UI is hidden, the script instance keeps running, `Script.onMinimize` is triggered, and the script can be resumed from the running scripts list — exactly as if `Script.minimize()` had been called.

Behavior rules:

- Affects only interactive swipe-down dismissal of the root page. Programmatic dismissal via `Navigation.useDismiss()(result)` still closes the page and resolves the `present` promise with `result` as usual.
- `Script.exit()` still fully terminates the script.
- Has no effect when multiple windows mode is enabled.
- Pass `false` to disable the behavior again. Defaults to `true`.
- While the script is minimized, the original `Navigation.present` promise stays pending (the same as after `Script.minimize()`). Use `Script.onResume()` to react when the script is restored.

```ts
// Keep the script alive when the user swipes the sheet away.
Script.enableMinimize()

await Navigation.present({
  element: <MyView />,
  modalPresentationStyle: "pageSheet",
})
```

***

### `Script.onMinimize(callback: () => void): () => void`

Registers a listener for the minimize event.

Triggered when:

- `Script.minimize()` successfully transitions the script into minimized state.
- The script moves from foreground to minimized state.

Returns a function that removes the listener.

```ts
const remove = Script.onMinimize(() => {
  console.log("Script has been minimized")
})

// Remove listener
remove()
```

***

### `Script.onResume(callback: (eventDetails: ResumeEventDetails) => void): () => void`

Registers a listener for resume or re-trigger events.

The resume event is delivered only when:

- The script instance is still alive.
- `Script.exit()` has not been called.

Returns a function that removes the listener.

```ts
const remove = Script.onResume(details => {
  console.log("Resume event:", details)
})
```

***

## ResumeEventDetails Structure

```ts
type ResumeEventDetails = {
  resumeFromMinimized: boolean
  widgetParameter: string | null
  controlWidgetParameter: string | null
  queryParameters: Record<string, any> | null
  notificationInfo: NotificationInfo | null
}
```

### `resumeFromMinimized: boolean`

- `true`: The script was restored from minimized state.
- `false`: The script was not restored from minimized state (for example, it was already in foreground or triggered by another source).

***

### `widgetParameter: string | null`

Parameter passed when the script is resumed by tapping a home screen widget.

***

### `controlWidgetParameter: string | null`

Parameter passed when the script is resumed by interacting with a Control Center widget.

***

### `queryParameters: Record<string, any> | null`

Query parameters passed when the script is resumed. Values keep their JSON types when resumed with a JSON object, but are strings when resumed via a `scripting://run/...` URL scheme.

***

### `notificationInfo: NotificationInfo | null`

Notification information passed when the script is resumed by tapping a notification.

***

## Behavior Scenarios

### UI-Based Script

#### Minimization Flow

- The script is running in the foreground.
- `Script.minimize()` is called.
- On success:

  - `Script.onMinimize` is triggered.
  - The UI is hidden.
  - The script instance remains alive.

#### Restoring from Minimized State

- The user taps the running script entry in the app.
- `Script.onResume` is triggered.
- `eventDetails.resumeFromMinimized === true`.

***

### External Triggers While in Foreground

When the script instance is alive and currently in the foreground:

- Tapping a notification
- Triggering the script via a widget run URL scheme
- Calling `Script.run()` for the same script

In these cases, `Script.onResume` is triggered and the corresponding parameter fields in `ResumeEventDetails` are populated.

***

### Non-UI (Background) Script

If the script has not called `Script.exit()`:

- Even without presenting UI,
- Tapping a notification or triggering the script again
- Will invoke registered `Script.onResume` callbacks.

If the script has called `Script.exit()`:

- A new trigger (notification, widget, etc.) creates a new script instance.
- The entry file executes again.
- Previous `onResume` listeners are not triggered.

***

## Usage Guidance

- Check `Script.supportsMinimization()` before enabling minimization-related features.
- Avoid calling `Script.exit()` if the script needs to remain alive.
- Use `Script.onResume()` to centralize handling of resume, widget triggers, notification taps, and URL-based triggers.
- Use `run_single` or `singleMode: true` when concurrent instances must be prevented.

This model enables long-lived script instances with hideable UI and unified resume handling across multiple trigger sources.



---
url: /guide/Script/Script.md
---

# Script

The `Script` module provides context and utility functions for managing script execution in the Scripting app. It enables you to access runtime metadata, terminate scripts with results, run other scripts programmatically, and construct URL schemes to launch or open scripts.

***

## Properties

### `name: string`

The name of the currently running script.

```ts
console.log(Script.name) // e.g., "MyScript"
```

***

### `directory: string`

The directory path where the script is located.

```ts
console.log(Script.directory) // e.g., "/private/var/mobile/Containers/..."
```

***

### `env: string`

Indicates the environment in which the current script is running. This allows the script to adapt its behavior based on the runtime context—whether it’s running in the main app, a widget, a notification, or an extension.

### Possible Values:

| Value              | Description                                                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `"index"`          | Running in the main app. Entry point is `index.tsx`. Used for normal UI logic.                                                          |
| `"widget"`         | Running in a widget. Entry point is `widget.tsx`. Used for home screen widgets.                                                         |
| `"control_widget"` | Running in a control widget. Entry point is `contrl_widget_button.tsx` or `control_widget_toggle.tsx`. Used for control center widgets. |
| `"notification"`   | Running in the rich notification extension. Entry point is `notification.tsx`.                                                          |
| `"intent"`         | Running as a share sheet or shortcut intent handler. Entry point is `intent.tsx`.                                                       |
| `"app_intents"`    | Running in the App Intents extension. Entry point is `app_intents.tsx`.                                                                 |
| `"assistant_tool"` | Running in the Assistant Tool context. Entry point is `assistant_tool.tsx`.                                                             |
| `"keyboard"`       | Running in the custom keyboard extension. Entry point is `keyboard.tsx`.                                                                |
| `"live_activity"`  | Running in the Live Activity extension. Entry point is `live_activity.tsx`.                                                             |

### Example:

```ts
if (Script.env === "widget") {
  Widget.present(<MyWidget />)
} else if (Script.env === "index") {
  Navigation.present({ element: <MainPage /> })
}
```

***

### `widgetParameter: string`

The parameter passed when the script is launched from a widget.

```ts
if (Script.widgetParameter) {
  console.log("Widget input:", Script.widgetParameter)
}
```

***

### `queryParameters: Record<string, any>`

Parameters passed to the script.

When the script is launched with a JSON object — for example `Script.run({ queryParameters })`, the `scripting-ts run ... --queryparameters '<json>'` command, or the keyboard `switchToScript` API — the original JSON value types are preserved (boolean, number, `null`, array, object).

When the script is launched via a `run` URL scheme, every value is a string, because URL query strings cannot carry typed values.

```ts
// Launched with a JSON object: { "enabled": true, "count": 3, "user": "John" }
console.log(Script.queryParameters.enabled) // true (boolean)
console.log(Script.queryParameters.count)   // 3 (number)
console.log(Script.queryParameters.user)    // "John" (string)

// Launched via URL: scripting://run/MyScript?user=John&id=123
console.log(Script.queryParameters.user) // "John"
console.log(Script.queryParameters.id)   // "123"
```

***

### `metadata: { ... }`

Metadata of the current script.

- `icon`: The icon of the script. Can be a SFSymbol name.
- `color`: The color of the script. Can be a hex color string like `#FF0000` or a CSS color name like `"red"`.
- `localizedName`: The localized name of the script in the current system language.
- `localizedNames`: A record of localized names for different languages. Keys are language codes (e.g., `"en"`, `"zh"`), and values are the localized names.
- `description`: The description of the script in English.
- `localizedDescription`: The localized description in the current system language.
- `localizedDescriptions`: A record of localized descriptions for different languages.
- `version`: The version string of the script.
- `author`: The script author's metadata:

  - `name`: The author's name
  - `email`: The author's email address
  - `homepage`: (optional) The author’s homepage
- `contributors`: An array of contributor objects with the same structure as `author`
- `remoteResource`: Information about a remote resource for this script:

  - `url`: The URL of the remote resource (e.g., a `.zip` or Git repository)
  - `autoUpdateInterval`: (optional) The auto-update interval in seconds. If not provided, auto-update is disabled.

```ts
console.log(Script.metadata.localizedName) // e.g., "天气助手"
console.log(Script.metadata.version)       // e.g., "1.2.0"
```

***

## Methods

### `Script.exit(result?): void`

Ends the script and optionally returns a result. This is required to release resources properly.

- `result?: any | IntentValue`: Any value or `IntentValue` object to return to the caller (e.g., Shortcuts or another script).

```ts
Script.exit("Done")

// or return structured value
Script.exit(Intent.json({ status: "ok" }))
```

***

### `Script.run<T>(options:): Promise<T | null>`

Runs another script programmatically and waits for its result.

- `options.name`: The name of the script to run.
- `options.queryParameters`: Optional data passed to the target script as `Script.queryParameters`; JSON value types are preserved.
- `options.singleMode`: If `true`, ensures only one instance of the script runs.

Returns: the value passed from `Script.exit(result)` in the target script.

```ts
const result = await Script.run({
  name: "ProcessData",
  queryParameters: { input: "abc" }
})

console.log(result)
```

***

### `Script.createRunURLScheme(scriptName, queryParameters?): string`

Creates a `scripting://run` URL to launch and execute a script.

```ts
const url = Script.createRunURLScheme("MyScript", { user: "Alice" })
// "scripting://run/MyScript?user=Alice"
```

***

### `Script.createRunSingleURLScheme(scriptName, queryParameters?): string`

Creates a `scripting://run_single` URL that ensures only one instance of the script runs.

```ts
const url = Script.createRunSingleURLScheme("MyScript", { id: "1" })
// "scripting://run_single/MyScript?id=1"
```

***

### `Script.createOpenURLScheme(scriptName): string`

Creates a `scripting://open` URL to open a script in the editor.

```ts
const url = Script.createOpenURLScheme("MyScript")
// "scripting://open/MyScript"
```

***

### `Script.createDocumentationURLScheme(title?): string`

Generates a URL to open the documentation page in the Scripting app.

- `title`: Optional. If provided, opens a specific documentation topic.

```ts
const url = Script.createDocumentationURLScheme("Widgets")
// "scripting://doc?title=Widgets"
```

***

### `createImportScriptsURLScheme(urls): string`

Generates a URL scheme for importing scripts from the specified URLs.

- `urls: string[]`: An array of URLs to import scripts from.

```ts
const urlScheme = Script.createImportScriptsURLScheme([
  "https://github.com/schl3ck/scripting-app-lib",
  "https://example.com/my-script.zip",
])
// "scripting://import_scripts?urls=..."
```

***

### `hasFullAccess(): boolean`

Determine whether user has full access to the Scripting PRO features.

Returns: `true` if the user has full access to the Scripting PRO features, otherwise `false`.

```ts
if (Script.hasFullAccess()) {
  // use Scripting PRO features
  Assistant.requestStructedData(...)
}
```

***

## Notes

- Always call `Script.exit()` to properly terminate a script and free memory.
- Use `Script.run()` to chain or modularize scripts and retrieve structured results.
- URL schemes can be used in external apps (like Shortcuts) to trigger scripts with parameters.
- `singleMode` is recommended for scripts that must not run in parallel.



---
url: /guide/TranslationUIProvider.md
---

# TranslationUIProvider

`TranslationUIProvider` allows scripts to take control of the system translation panel’s UI and interaction flow. It enables developers to build fully customized translation interfaces and implement their own default translation logic.

When a host app invokes the translation extension, Scripting executes the `translation_ui_provider.tsx` script. Within this environment, developers can access the source text provided by the host, perform translation logic, construct a custom UI, and present it using `TranslationUIProvider.present(...)`.

This capability is suitable for scenarios such as:

- Customizing the layout and interaction of the translation panel
- Displaying source text, translated results, language selectors, and controls
- Integrating custom translation services or pipelines
- Returning translated text to replace the original content (if allowed by the host)
- Providing a read-only translation interface without modifying the original text

`TranslationUIProvider` does not perform translation itself. It provides a UI container and session control interface. Translation logic must be implemented by the developer within the script, such as calling remote APIs or local processing modules.

***

## Availability

`TranslationUIProvider` requires **iOS 18.4 or later**.

***

## Availability

`TranslationUIProvider` is only available within the Translation UI Provider execution environment and should be used in the `translation_ui_provider.tsx` file.

When the system presents the translation panel, this script acts as the entry point of the session. A typical workflow includes:

1. Read the source text from the host
2. Execute default translation logic
3. Build and present a custom UI
4. Handle user interactions (expand panel, confirm result, finish session)

***

## Execution Model

`TranslationUIProvider` serves two main purposes:

- Providing access to the current translation session context (e.g., source text, replacement capability)
- Controlling the lifecycle and UI of the translation panel

The session is created by the system and host app. Scripting automatically injects the current session into the `TranslationUIProvider` namespace when executing `translation_ui_provider.tsx`.

***

## Session Input

### inputText

```ts
const inputText: string | null
```

Represents the source text provided by the host app.

This is typically the text selected by the user or passed by the host for translation. The value may be `null`, so scripts must handle this case explicitly.

Common usage:

- Display the source text in UI
- Use it as input for translation logic
- Show fallback UI when no text is available

Example:

```ts
const source = TranslationUIProvider.inputText

if (!source) {
  TranslationUIProvider.present(
    <Text>No text available for translation.</Text>
  )
}
```

`inputText` reflects the initial session input and should not be assumed to always exist.

***

### allowsReplacement

```ts
const allowsReplacement: boolean
```

Indicates whether the host app allows replacing the original text with the translated result.

If `true`, scripts can return a translation via `finish(translatedText)`. If `false`, translations can only be displayed, not applied.

Typical usage:

- Conditionally show “Replace” or “Use Translation” actions
- Adjust UI behavior based on capability

Example:

```ts
const canReplace = TranslationUIProvider.allowsReplacement
```

When replacement is not allowed, the UI should avoid presenting misleading actions.

***

## Panel Control

### present(node)

```ts
function present(node: VirtualNode): void
```

Displays the scripted UI in the translation panel.

This is the primary entry point for rendering UI. Developers should construct a `VirtualNode` and pass it to `present(...)`.

Example:

```tsx
import { Text, VStack } from "scripting"

TranslationUIProvider.present(
  <VStack spacing={12}>
    <Text>Custom Translation Panel</Text>
    <Text>{TranslationUIProvider.inputText ?? "No input text"}</Text>
  </VStack>
)
```

It is recommended to encapsulate the UI into a component:

```tsx
function TranslationView() {
  const source = TranslationUIProvider.inputText

  return <VStack spacing={12}>
    <Text>Original</Text>
    <Text>{source ?? "No input text"}</Text>
  </VStack>
}

TranslationUIProvider.present(<TranslationView />)
```

`present(...)` only renders the UI. It does not end the session or return results.

***

### expandSheet()

```ts
function expandSheet(): void
```

Requests the system to expand the translation panel.

This is useful when:

- Displaying long content
- Showing multiple translation results
- Providing advanced controls

Example:

```ts
TranslationUIProvider.expandSheet()
```

This is a request, not a guarantee. The system decides how to handle it.

***

### finish(translation?)

```ts
function finish(translation?: string | null): void
```

Ends the current translation session and optionally returns a translated result.

Two common patterns:

Close without replacement:

```ts
TranslationUIProvider.finish()
```

Close and return translation:

```ts
TranslationUIProvider.finish("Hello world")
```

Typical usage:

```ts
if (TranslationUIProvider.allowsReplacement) {
  TranslationUIProvider.finish(translatedText)
} else {
  TranslationUIProvider.finish()
}
```

Notes:

- Calling `finish(...)` ends the session immediately
- Passing a string attempts to return it to the host
- Passing `null` or omitting closes without replacement
- Final behavior depends on host capabilities

***

## Recommended Development Pattern

A typical structure in `translation_ui_provider.tsx`:

1. Read `inputText`
2. Handle empty input
3. Execute translation logic
4. Build UI with source and translated text
5. Let user confirm or cancel
6. Call `finish(...)` accordingly

***

## Example: Minimal Translation Panel

```tsx
import { Button, Text, VStack } from "scripting"

function TranslationView() {
  const source = TranslationUIProvider.inputText

  return <VStack spacing={12} padding={16}>
    <Text>Original Text</Text>
    <Text>{source ?? "No text available"}</Text>

    <Button
      title="Close"
      action={() => {
        TranslationUIProvider.finish()
      }}
    />
  </VStack>
}

TranslationUIProvider.present(<TranslationView />)
```

***

## Example: With Translation Result and Replacement

```tsx
import { Button, HStack, Text, VStack, useMemo } from "scripting"

function TranslationView() {
  const source = TranslationUIProvider.inputText
  const canReplace = TranslationUIProvider.allowsReplacement

  const translatedText = useMemo(() => {
    if (!source) return ""
    return `[Translated] ${source}`
  }, [source])

  if (!source) {
    return <VStack spacing={12} padding={16}>
      <Text>No text available for translation.</Text>
      <Button
        title="Close"
        action={() => {
          TranslationUIProvider.finish()
        }}
      />
    </VStack>
  }

  return <VStack spacing={16} padding={16}>
    <Text>Original</Text>
    <Text>{source}</Text>

    <Text>Translation</Text>
    <Text>{translatedText}</Text>

    <HStack spacing={12}>
      <Button
        title="Close"
        action={() => {
          TranslationUIProvider.finish()
        }}
      />

      {canReplace ? (
        <Button
          title="Use Translation"
          action={() => {
            TranslationUIProvider.finish(translatedText)
          }}
        />
      ) : null}
    </HStack>
  </VStack>
}

TranslationUIProvider.present(<TranslationView />)
```

***

## Example: Expanding the Panel

```tsx
import { Button, Text, VStack } from "scripting"

function TranslationView() {
  return <VStack spacing={12} padding={16}>
    <Text>{TranslationUIProvider.inputText ?? "No input text"}</Text>

    <Button
      title="Expand"
      action={() => {
        TranslationUIProvider.expandSheet()
      }}
    />

    <Button
      title="Close"
      action={() => {
        TranslationUIProvider.finish()
      }}
    />
  </VStack>
}

TranslationUIProvider.present(<TranslationView />)
```

***

## Lifecycle Notes

- `TranslationUIProvider` is scoped to the current translation session
- It is only valid during execution of `translation_ui_provider.tsx`
- `finish(...)` terminates the session
- After finishing, no further UI updates should be performed
- `present(...)` is typically called once to render the main UI

***

## Relationship with Translation Logic

`TranslationUIProvider` handles UI and session control, not translation.

Developers are responsible for implementing translation logic, such as:

- Calling remote APIs
- Using local models
- Providing multiple candidate results
- Applying domain-specific processing

Recommended separation:

- `TranslationUIProvider`: UI + session control
- Translation logic: data processing
- Components: UI structure

***

## Best Practices

- Always handle `inputText === null`
- Respect `allowsReplacement` when designing actions
- Call `finish(...)` only after user confirmation
- Use `expandSheet()` only when necessary
- Keep translation logic and UI modular



---
url: /guide/Types/Alignment.md
---

# Alignment

The `Alignment` type defines how to position content within a view’s frame, mirroring the behavior of SwiftUI’s built-in alignments. By applying an `Alignment` value, you can control where elements will be placed if they have extra space or need to align in a specific way.

## Overview

`Alignment` is useful when you have containers like `VStack`, `HStack`, `ZStack`, or any layout that involves stacking, layering, or positioning multiple views. By choosing an alignment, you tell the layout system how to position these views relative to each other or their container.

For example, a `ZStack` with a `topLeading` alignment will place its content toward the top-left corner of the container, while a `bottomTrailing` alignment puts it toward the bottom-right corner.

## Available Alignments

- **Basic Alignments:**
  - **`top`**: Aligns content along the top edge.
  - **`center`**: Centers content both horizontally and vertically.
  - **`bottom`**: Aligns content along the bottom edge.
  - **`leading`**: Aligns content along the leading edge (left side in left-to-right languages).
  - **`trailing`**: Aligns content along the trailing edge (right side in left-to-right languages).

- **Compound Alignments:**
  - **`topLeading`**: Aligns content at the top and leading edges.
  - **`topTrailing`**: Aligns content at the top and trailing edges.
  - **`bottomLeading`**: Aligns content at the bottom and leading edges.
  - **`bottomTrailing`**: Aligns content at the bottom and trailing edges.

- **Text Baseline Alignments:**
  Baseline alignments are useful when arranging text-containing views so their text aligns at a common baseline.
  - **`centerFirstTextBaseline`**
  - **`centerLastTextBaseline`**
  - **`leadingFirstTextBaseline`**
  - **`leadingLastTextBaseline`**
  - **`trailingFirstTextBaseline`**
  - **`trailingLastTextBaseline`**

## Example Usage

**Center Alignment**

```tsx
<ZStack alignment="center">
  <Rectangle fill="gray" frame={{width: 100, height: 100}} />
  <Text font="title">Centered Text</Text>
</ZStack>
```

In this example, the `Text` will be centered within the `Rectangle`.

**Top Leading Alignment**

```tsx
<ZStack alignment="topLeading">
  <Rectangle fill="gray" frame={{width: 200, height: 200}} />
  <Text>I'm at the top-left!</Text>
</ZStack>
```

Here, the `Text` appears in the top-left corner of the gray rectangle.

**Baseline Alignment with HStack**

```tsx
<HStack alignment="leadingFirstTextBaseline">
  <Text font="largeTitle">Big Title</Text>
  <Text font="title">Smaller Subtitle</Text>
</HStack>
```

This aligns the two texts so that their first lines of text share a baseline, keeping them visually aligned even though they’re different sizes.

## Summary

`Alignment` gives you fine-grained control over how content is positioned within a container. By selecting the appropriate alignment—whether it’s a basic edge-based alignment or a more advanced text-baseline alignment—you ensure your UI elements look visually coherent and intuitive.



---
url: /guide/Types/Color.md
---

# Color

The `Color` API supports various color formats, including HEX strings, RGBA strings, and predefined color keywords. It integrates seamlessly with SwiftUI's color system to provide vibrant, adaptive colors for your UI designs.

## `Color` Type

The `Color` type can represent colors in one of three formats:

1. **HEX String**: Standard hexadecimal color codes.
2. **RGBA String**: CSS-like color strings with red, green, blue, and alpha components.
3. **Keyword Colors**: A set of predefined system and semantic colors.

### Supported Formats

#### 1. HEX String (`ColorStringHex`)

- **Format**: `#RRGGBB` or `#RGB`
- **Example**:
  ```tsx
  const primaryColor: Color = "#FF5733"
  const secondaryColor: Color = "#333"
  ```

#### 2. RGBA String (`ColorStringRGBA`)

- **Format**: `rgba(R, G, B, A)`
  - `R`: Red, 0–255
  - `G`: Green, 0–255
  - `B`: Blue, 0–255
  - `A`: Alpha, 0–1 (transparency)
- **Example**:
  ```tsx
  const transparentBlack: Color = "rgba(0, 0, 0, 0.5)"
  const semiTransparentRed: Color = "rgba(255, 0, 0, 0.8)"
  ```

#### 3. Keyword Colors (`KeywordsColor`)

Predefined system colors that adapt to the current system appearance (light or dark mode) and accessibility settings. These colors provide consistency with native iOS apps.

- **Examples**:
  ```tsx
  const systemAccent: Color = "accentColor"
  const systemBackground: Color = "systemBackground"
  const linkColor: Color = "link"
  const customGray: Color = "systemGray4"
  ```

### List of Keyword Colors

#### System Colors

- `accentColor`
- `systemRed`, `systemGreen`, `systemBlue`, `systemOrange`, `systemYellow`, `systemPink`, `systemPurple`, `systemTeal`, `systemIndigo`, `systemBrown`, `systemMint`, `systemCyan`

#### Semantic Colors

- **Labels**: `label`, `secondaryLabel`, `tertiaryLabel`, `quaternaryLabel`
- **Fill Colors**: `systemFill`, `secondarySystemFill`, `tertiarySystemFill`, `quaternarySystemFill`
- **Backgrounds**:
  - `systemBackground`, `secondarySystemBackground`, `tertiarySystemBackground`
  - `systemGroupedBackground`, `secondarySystemGroupedBackground`, `tertiarySystemGroupedBackground`
- **Separators**: `separator`, `opaqueSeparator`

#### Legacy Colors

- `black`, `darkGray`, `lightGray`, `white`, `gray`, `red`, `green`, `blue`, `cyan`, `yellow`, `magenta`, `orange`, `purple`, `brown`, `clear`

### Usage in TSX Components

```tsx
import { View, Text, VStack } from 'scripting'

function MyView() {
  return (
    <VStack background="systemBackground">
      <Text foregroundStyle="accentColor">
        Welcome to the Scripting App!
      </Text>
    </VStack>
  )
}
```

This component uses system adaptive colors to maintain consistency with the iOS appearance.

### Notes

- **Performance**: When using keyword colors, the app ensures the color adapts dynamically to system settings such as Dark Mode.
- **Validation**: Invalid color strings may throw errors during runtime. Ensure your color strings conform to the expected format.



---
url: /guide/Types/DynamicShapeStyle.md
---

# DynamicShapeStyle

The `DynamicShapeStyle` type allows you to define two distinct styles for a shape—one for light mode and another for dark mode. The system automatically applies the appropriate style based on the current color scheme (light or dark) of the user’s device.

## Overview

Dynamic styling is a critical aspect of creating adaptive and visually appealing user interfaces. With `DynamicShapeStyle`, you can ensure that your shapes blend seamlessly with the user's preferred color scheme by defining separate styles for light and dark modes.

**Key points:**

- Define a style for **light mode** using the `light` property.
- Define a style for **dark mode** using the `dark` property.
- The system will automatically apply the appropriate style based on the user's current settings.

## Declaration

```tsx
type DynamicShapeStyle = {
    light: ShapeStyle;
    dark: ShapeStyle;
};
```

- **`light: ShapeStyle`**\
  The style to apply when the system is in light mode.

- **`dark: ShapeStyle`**\
  The style to apply when the system is in dark mode.

### Supported `ShapeStyle`

The `ShapeStyle` can be a color, gradient, or material. For example:

- **Colors**: Solid colors like `"red"`, hex values like `"#FF0000"`, or CSS-like RGBA strings like `"rgba(255, 0, 0, 1)"`.
- **Gradients**: Linear or radial gradients.
- **Materials**: System materials like `"regularMaterial"`, `"thickMaterial"`.

## Example Usage

### Using Dynamic Colors

```tsx
const dynamicStyle: DynamicShapeStyle = {
  light: "blue",
  dark: "gray"
}

<Text
  foregroundStyle={dynamicStyle}
/>
```

In this example, the shape appears **blue** in light mode and **gray** in dark mode.

### Using Dynamic Gradients

```tsx
const dynamicStyle: DynamicShapeStyle = {
  light: {
    gradient: [
      { color: "lightblue", location: 0 },
      { color: "white", location: 1 }
    ],
    startPoint: { x: 0, y: 0 },
    endPoint: { x: 1, y: 1 }
  },
  dark: {
    gradient: [
      { color: "darkblue", location: 0 },
      { color: "black", location: 1 }
    ],
    startPoint: { x: 0, y: 0 },
    endPoint: { x: 1, y: 1 }
  }
}

<Circle
  fill={dynamicStyle}
/>
```

Here, the shape uses a **light blue to white gradient** in light mode and a **dark blue to black gradient** in dark mode.

### Using Materials

```tsx
const dynamicStyle: DynamicShapeStyle = {
  light: "regularMaterial",
  dark: "ultraThickMaterial"
}

<HStack
  background={dynamicStyle}
></HStack>
```

This configuration applies a **regular material** in light mode and an **ultra-thick material** in dark mode.

## Why Use `DynamicShapeStyle`?

Dynamic styling helps create a better user experience by ensuring:

1. **Visual Harmony**: Your shapes adapt to the user's color scheme, maintaining aesthetic coherence.
2. **Accessibility**: Adjusting styles for dark mode improves readability and usability in low-light environments.
3. **Consistency**: Aligns your app's appearance with system-wide preferences, making it feel more integrated.

## Summary

With `DynamicShapeStyle`, you can create flexible and adaptive styles for shapes that seamlessly respond to the user's color scheme. By defining separate styles for light and dark modes, your app will look great in any environment, ensuring a consistent and user-friendly experience.



---
url: /guide/Types/Shape.md
---

# Shape

The `Shape` type defines a visual clipping or background shape used in view modifiers such as `clipShape`, `background`, or `border`. It mirrors SwiftUI's `Shape` protocol and supports standard system shapes and custom rounded rectangle configurations.

***

## Overview

A `Shape` can be:

- A **named shape keyword** (`'circle'`, `'rect'`, etc.)
- A **custom shape object** that defines corner radius or per-corner rounding.

These shapes are aligned within the frame of the containing view and are commonly used for clipping, masking, or background styling.

***

## Built-in Shapes

### `'rect'`

A standard rectangle. Can be customized with corner radius via the object form.

```tsx
clipShape="rect"
```

***

### `'circle'`

A perfect circle centered within the view’s frame. Its radius is half the length of the frame's shortest side.

```tsx
clipShape="circle"
```

***

### `'capsule'`

An elongated oval shape that spans the full width or height of the frame. Equivalent to a rounded rectangle with a corner radius equal to half of the shorter side.

```tsx
clipShape="capsule"
```

***

### `'ellipse'`

An ellipse that fills the frame.

```tsx
clipShape="ellipse"
```

***

### `'buttonBorder'`

A system-resolved shape for button borders. It automatically adapts based on platform and system context.

```tsx
clipShape="buttonBorder"
```

***

### `'containerRelative'`

A container-adaptive shape. If a container shape is defined in the view hierarchy, this resolves to a version of that shape. Otherwise, it defaults to a rectangle.

```tsx
clipShape="containerRelative"
```

***

## Custom Rectangle Shapes

To customize corner appearance on a rectangle, use one of the following object forms:

***

### Rounded Rectangle with Uniform Corner Radius

```ts
{
  type: 'rect',
  cornerRadius: number,
  style?: RoundedCornerStyle
}
```

- `cornerRadius`: Radius applied uniformly to all corners.
- `style` (optional): Corner style, such as `'circular'` or `'continuous'`.

#### Example

```tsx
clipShape={{
  type: 'rect',
  cornerRadius: 12,
  style: 'continuous'
}}
```

***

### Rounded Rectangle with Corner Size

```ts
{
  type: 'rect',
  cornerSize: {
    width: number
    height: number
  },
  style?: RoundedCornerStyle
}
```

- Allows specifying an elliptical radius with different width and height.

#### Example

```tsx
clipShape={{
  type: 'rect',
  cornerSize: { width: 10, height: 20 }
}}
```

***

### Rounded Rectangle with Per-Corner Radii

```ts
{
  type: 'rect',
  cornerRadii: {
    topLeading: number,
    topTrailing: number,
    bottomLeading: number,
    bottomTrailing: number
  },
  style?: RoundedCornerStyle
}
```

- Gives precise control over the rounding of each corner individually.

#### Example

```tsx
clipShape={{
  type: 'rect',
  cornerRadii: {
    topLeading: 10,
    topTrailing: 20,
    bottomLeading: 0,
    bottomTrailing: 30
  }
}}
```

***

## `RoundedCornerStyle`

Optional style that affects the curvature:

- `"circular"`: Traditional iOS-style round corners.
- `"continuous"` (default): Smooth and adaptive curves, typically used in modern UI designs.

***

## Summary Table

| Shape Type            | Description                                                         |
| --------------------- | ------------------------------------------------------------------- |
| `'rect'`              | Plain rectangle                                                     |
| `'circle'`            | Circle inside the smallest side of the frame                        |
| `'capsule'`           | Rounded shape spanning width or height                              |
| `'ellipse'`           | Ellipse stretched to frame                                          |
| `'buttonBorder'`      | Adaptive button outline shape                                       |
| `'containerRelative'` | Depends on parent container shape; falls back to rectangle          |
| `custom rect`         | Rectangles with specific corner radius or per-corner configurations |



---
url: /guide/Types/ShapeStyle.md
---

# ShapeStyle

The `ShapeStyle` type defines how colors, gradients, and materials can be applied to a view’s foreground or background, mirroring the styling capabilities found in SwiftUI. It encompasses a wide range of styling options, including simple colors, system materials, and complex gradients.

## Overview

When using modifiers like `foregroundStyle` or `background`, you can supply a `ShapeStyle` to determine the visual appearance. For example, a solid red background, a system material blur, or a linear gradient can all be represented using `ShapeStyle`.

**In SwiftUI (for reference):**

```swift
Text("Hello")
    .foregroundStyle(.red)
    .background(
        LinearGradient(
            colors: [.green, .blue],
            startPoint: .top,
            endPoint: .bottom
        )
    )
```

**In Scripting (TypeScript/TSX):**

```tsx
<Text
  foregroundStyle="red"
  background={{
    gradient: [
      { color: 'green', location: 0 },
      { color: 'blue', location: 1 }
    ],
    startPoint: { x: 0.5, y: 0 },
    endPoint: { x: 0.5, y: 1 }
  }}
>
  Hello
</Text>
```

## ShapeStyle Variants

The `ShapeStyle` type can be one of the following:

1. **Material**: System-defined materials that create layered effects, often adding blur or translucency.
2. **Color**: A solid color, which can be defined using keywords, hex strings, or RGBA strings.
3. **Gradient**: A collection of colors or gradient stops that produce a smooth color transition.
4. **LinearGradient**: A gradient that progresses linearly from a start point to an end point.
5. **RadialGradient**: A gradient that radiates outward from a center point.
6. **AngularGradient**: An angular gradient is also known as a “conic” gradient. This gradient applies the color function as the angle changes, relative to a center point and defined start and end angles.
7. **MeshGradient**: A two-dimensional gradient defined by a 2D grid of positioned colors.
8. **ColorWithGradientOrOpacity**: A combination of a base color that can produce a standard gradient automatically or have an adjusted opacity.

### Materials

**Material** refers to system blur effects like `regularMaterial`, `thinMaterial`, and so forth. They give your UI the distinctive “frosted” look often seen in native iOS apps.

**Example:**

```tsx
<HStack background="regularMaterial">
  {/* Content here */}
</HStack>
```

### Colors

**Colors** can be defined in three ways:

- **Keyword Colors**: System and named colors (e.g. `"systemBlue"`, `"red"`, `"label"`).
- **Hex Strings**: Like CSS hex (`"#FF0000"` or `"#F00"` for red).
- **RGBA Strings**: CSS rgba notation (`"rgba(255,0,0,1)"` for opaque red).

**Example:**

```tsx
<Text foregroundStyle="blue">Blue Text</Text>
<HStack background="#00FF00">Green Background</HStack>
<HStack background="rgba(255,255,255,0.5)">Semi-transparent White Background</HStack>
```

### Gradients

**Gradient** is defined as either an array of `Color` values or an array of `GradientStop` objects, where each `GradientStop` includes a `color` and a `location` (0 to 1) to define the transition.

**Example:**

```tsx
<HStack
  background={
    gradient([
      { color: 'red', location: 0 },
      { color: 'orange', location: 0.5 },
      { color: 'yellow', location: 1 }
    ])
  }
>
  {/* Content */}
</HStack>
```

### LinearGradient

**LinearGradient** lets you define a gradient that moves along a straight line between two points. You specify colors or stops, and the start/end points either as keywords (`'top'`, `'bottom'`, `'leading'`, `'trailing'`) or as `Point` objects (`{x: number, y: number}`).

**Example:**

```tsx
<HStack
  background={
    gradient("linear", {
      colors: ['green', 'blue'],
      startPoint: 'top',
      endPoint: 'bottom'
    })
  }
>
  {/* Content */}
</HStack>
```

Or, using gradient stops with custom coordinates:

```tsx
<HStack
  background={
    gradient("linear", {
      stops: [
        { color: 'green', location: 0 },
        { color: 'blue', location: 1 }
      ],
      startPoint: { x: 0.5, y: 0 },
      endPoint: { x: 0.5, y: 1 }
    })
  }
>
  {/* Content */}
</HStack>
```

### RadialGradient

**RadialGradient** spreads out colors from a central point, defined by a `center` coordinate, and transitions from a `startRadius` to an `endRadius`.

**Example:**

```tsx
<HStack
  background={
    gradient("radial", {
      colors: ['red', 'yellow'],
      center: { x: 0.5, y: 0.5 },
      startRadius: 0,
      endRadius: 100
    })
  }
>
  {/* Content */}
</HStack>
```

### AngularGradient

An `AngularGradient` defines a color gradient that sweeps around a center point in an angular (circular) fashion. It is useful for creating effects such as progress rings or circular transitions.

#### Definition

An `AngularGradient` can be defined in one of several ways:

```ts
type AngularGradient =
  | { stops: GradientStop[], center: KeywordPoint | Point, startAngle: Angle, endAngle: Angle }
  | { colors: Color[], center: KeywordPoint | Point, startAngle: Angle, endAngle: Angle }
  | { gradient: Gradient, center: KeywordPoint | Point, startAngle: Angle, endAngle: Angle }
  | { stops: GradientStop[], center: KeywordPoint | Point, angle: Angle }
  | { colors: Color[], center: KeywordPoint | Point, angle: Angle }
  | { gradient: Gradient, center: KeywordPoint | Point, angle: Angle }
```

#### Parameters

- **`colors`** or **`stops`**: Specifies the colors or color stops used in the gradient.
- **`center`**: The point around which the angular sweep is performed. Can be a named keyword (e.g., `"center"`, `"top"`) or a custom `Point`.
- **`startAngle`** and **`endAngle`**: Defines the angular sweep range.
- **`angle`** (optional alternative): A single angle that defines the full sweep extent.

#### Example

```tsx
<Circle
  fill={gradient("angular", {
    colors: ["blue", "purple", "pink"],
    center: "center",
    startAngle: 0,
    endAngle: 360
  })}
/>
```

In this example, a circular gradient fills a shape, sweeping clockwise from blue to pink around the center.

### MeshGradient (iOS 18.0+)

A `MeshGradient` is a two-dimensional gradient composed of a grid of colored control points. It offers fine-grained control over both color and shape, allowing for complex, dynamic gradient effects.

#### Definition

```ts
type MeshGradient = {
  width: number
  height: number
  points: Point[]
  colors: Color[]
  background?: Color
  smoothsColors?: boolean
}
```

#### Parameters

- **`width`**: Number of vertices per row.
- **`height`**: Number of vertices per column.
- **`points`**: The control points of the mesh (must match `width × height`).
- **`colors`**: The color assigned to each point (must also match `width × height`).
- **`background`** (optional): Color for the area outside the mesh. Defaults to `"clear"`.
- **`smoothsColors`** (optional): Whether color interpolation should be smooth (defaults to `true`).

> Note: Mesh gradients are supported on **iOS 18.0 and above**.

#### Example

```tsx
<Rectangle
  fill={gradient("mesh", {
    width: 2,
    height: 2,
    points: [
      { x: 0, y: 0 },
      { x: 1, y: 0 },
      { x: 0, y: 1 },
      { x: 1, y: 1 }
    ],
    colors: ["red", "yellow", "blue", "green"]
  })}
/>
```

This example defines a 2x2 mesh grid with color transitions across four control points in a rectangle.

### `gradient()` Utility Function

The `gradient()` helper function makes the code more readable and expressive. It supports all gradient types.

#### Signature

```ts
function gradient(gradient: Gradient): Gradient
function gradient(type: "linear", gradient: LinearGradient): LinearGradient
function gradient(type: "radial", gradient: RadialGradient): RadialGradient
function gradient(type: "angular", gradient: AngularGradient): AngularGradient
function gradient(type: "mesh", gradient: MeshGradient): MeshGradient
```

#### Description

- When used with one argument: `gradient(Gradient)` returns the input gradient as-is.
- When used with two arguments: the first argument specifies the type, and the second provides the gradient configuration.

#### Example

```tsx
<Text
  foregroundStyle={
    gradient("linear", {
      colors: ["red", "orange"],
      startPoint: "leading",
      endPoint: "trailing"
    })
  }
>
  Hello World!
</Text>
```

### ColorWithGradientOrOpacity

With `ColorWithGradientOrOpacity`, you start with a `color` and then can specify a `gradient: true` property to use its standard gradient variation, or apply an `opacity` factor to make it translucent.

**Example:**

```tsx
<HStack
  background={{
    color: 'blue',
    gradient: true,
    opacity: 0.8
  }}
>
  {/* Content */}
</HStack>
```

This would create a gradient variation of the base color and apply an 80% opacity.

## Summary

- Use **Materials** for system blur effects.
- Use **Colors** for solid fills.
- Use **Gradients**, **LinearGradient**, **RadialGradient**, **AngularGradient** or **MeshGradient** for smooth transitions between multiple colors.
- Use **ColorWithGradientOrOpacity** to adjust color opacity or use a standard color-derived gradient.

By choosing the appropriate variant of `ShapeStyle`, you can easily style elements with the desired appearance in your UI—whether you need a simple color fill, a dynamic gradient, or a polished material effect.



---
url: /guide/Utilities/App Events.md
---

# App Events

The `AppEvents` module in the Scripting app provides an interface to observe global application state changes, such as scene lifecycle transitions and changes in system-wide appearance (light/dark mode). These capabilities are essential for writing responsive scripts that react appropriately to runtime context.

***

## Scene Lifecycle

### `ScenePhase`

```ts
type ScenePhase = 'active' | 'inactive' | 'background'
```

Represents the state of the app’s scene:

- **`active`** – The app is in the foreground and interactive.
- **`inactive`** – The app is in transition or temporarily inactive.
- **`background`** – The app is running in the background and not visible.

***

## Color Scheme

### `ColorScheme`

```ts
type ColorScheme = 'light' | 'dark'
```

Reflects the current appearance mode of the device:

- **`light`** – Light mode UI
- **`dark`** – Dark mode UI

***

## `AppEventListenerManager<T>`

```ts
class AppEventListenerManager<T> {
  addListener(listener: (data: T) => void): void
  removeListener(listener: (data: T) => void): void
}
```

A generic event manager that allows you to register and unregister listeners dynamically. Used for both `scenePhase` and `colorScheme`.

***

## `AppEvents` Class

```ts
class AppEvents {
  static scenePhase: AppEventListenerManager<ScenePhase>
  static colorScheme: AppEventListenerManager<ColorScheme>
}
```

### `AppEvents.scenePhase`

Listen for scene phase transitions. Ideal for responding to foreground/background state changes.

#### Example

```ts
AppEvents.scenePhase.addListener((phase) => {
  if (phase === 'active') {
    console.log("App is active")
  } else if (phase === 'background') {
    console.log("App is in background")
  }
})
```

***

### `AppEvents.colorScheme`

Observe system-wide light/dark appearance changes in real time.

#### Example

```ts
AppEvents.colorScheme.addListener((scheme) => {
  console.log(`Current color scheme: ${scheme}`)
})
```

***

## `useColorScheme()` Hook

```ts
declare function useColorScheme(): ColorScheme
```

### Description

This hook provides a reactive way to access the current `ColorScheme` (`'light'` or `'dark'`) within a component. It automatically updates the value when the system theme changes.

### Example

```tsx
function ThemedView() {
  const colorScheme = useColorScheme()

  return <Text>
    {colorScheme === 'dark' ? 'Dark Mode Active' : 'Light Mode Active'}
  </Text>
}
```

***

## Notes

- Listeners registered with `AppEvents` should be manually removed when no longer needed to prevent memory leaks.
- `useColorScheme()` is the recommended way to reactively reflect the current theme in your components.
- These APIs allow you to respond to system and app-level state changes in a clean, declarative way—without relying on imperative lifecycle logic.



---
url: /guide/Utilities/Archive.md
---

# Archive

The `Archive` class provides a comprehensive interface for working with archive files (such as ZIP).
It supports reading, creating, updating, and extracting entries from archives, with both **asynchronous** and **synchronous** methods.

***

## Overview

`Archive` enables flexible management of compressed archive contents, including:

- Opening existing archives or creating new ones
- Adding files, directories, or in-memory data
- Extracting entries to memory or disk
- Deleting specific entries
- Listing archive contents
- Supporting multiple compression methods (e.g. `deflate`, `none`)
- Working in either synchronous or asynchronous modes

***

## Static Methods

### `static openForMode(path: string, accessMode: "update" | "read", options?: { pathEncoding?: Encoding }): Archive`

Opens an archive file.

**Parameters:**

| Name                   | Type       | Description                                                                 |                                                                                          |
| ---------------------- | ---------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `path`                 | `string`   | The file path of the archive.                                               |                                                                                          |
| `accessMode`           | `"update"` | `"read"`                                                                    | The access mode: - `"read"`: open for reading only. - `"update"`: open for modification. |
| `options.pathEncoding` | `Encoding` | Optional. The path encoding used inside the archive (default is `"utf-8"`). |                                                                                          |

**Returns:**
An `Archive` object.

**Example:**

```ts
const archive = Archive.openForMode("/tmp/example.zip", "update")
```

***

## Properties

### `path: string`

The path of the archive file.

**Example:**

```ts
console.log(archive.path)
```

***

### `data: Data | null`

The raw data of the archive (if opened from memory).

***

## Instance Methods

### `entries(pathEncoding?: Encoding): ArchiveEntry[]`

Retrieves the entries in the archive.

**Parameters:**

`pathEncoding`: Optional. The encoding to use for decoding entry paths (default is `"utf-8"`).

**Returns:**
An array of `ArchiveEntry` objects.

***

### `getEntryPaths(encoding?: Encoding): string[]`

Retrieves the paths of all entries in the archive.

**Parameters:**

`encoding`: Optional. The encoding to use for decoding entry paths (default is `"utf-8"`).

**Returns:**
An array of entry paths.

***

### `getEntry(path: string): ArchiveEntry | null`

Retrieves an entry by its path.

**Parameters:**

`path`: The path of the entry to retrieve.

**Returns:**
The `ArchiveEntry` object if found; otherwise, `null`.

***

### `contains(path: string): boolean`

Checks whether the archive contains a specific entry.

**Parameters:**

`path`: The path of the entry to check.

**Returns:**
`true` if the path exists; otherwise, `false`.

**Example:**

```ts
if (archive.contains("README.md")) {
  console.log("Archive contains README.md")
}
```

***

### `addEntry(path: string, toPath: string, options?: { compressionMethod?: "deflate" | "none"; bufferSize?: number }): Promise<void>`

Adds an existing file to the archive (asynchronously).

**Parameters:**

| Name                        | Type        | Description                                  |                                         |
| --------------------------- | ----------- | -------------------------------------------- | --------------------------------------- |
| `path`                      | `string`    | The source file path.                        |                                         |
| `toPath`                    | `string`    | The destination path inside the archive.     |                                         |
| `options.compressionMethod` | `"deflate"` | `"none"`                                     | Compression method (default: `"none"`). |
| `options.bufferSize`        | `number`    | Buffer size in bytes (default: `16 * 1024`). |                                         |

**Example:**

```ts
await archive.addEntry("/tmp/input.txt", "docs/input.txt", {
  compressionMethod: "deflate"
})
```

***

### `addEntrySync(path: string, toPath: string, options?)`

Synchronous version of `addEntry()`.
Throws an error if the entry cannot be added.

***

### `addFileEntry(path: string, uncompressedSize: number, provider: (offset: number, length: number) => Data, options?): Promise<void>`

Adds a file entry to the archive using a data provider function (asynchronous).

**Parameters:**

| Name                        | Type                                       | Description                                   |                                         |
| --------------------------- | ------------------------------------------ | --------------------------------------------- | --------------------------------------- |
| `path`                      | `string`                                   | The target file path inside the archive.      |                                         |
| `uncompressedSize`          | `number`                                   | The uncompressed file size.                   |                                         |
| `provider`                  | `(offset: number, length: number) => Data` | A function that provides file data by chunks. |                                         |
| `options.modificationDate`  | `Date`                                     | Optional modification date.                   |                                         |
| `options.compressionMethod` | `"deflate"`                                | `"none"`                                      | Compression method (default: `"none"`). |
| `options.bufferSize`        | `number`                                   | Buffer size in bytes (default: `16 * 1024`).  |                                         |

**Example:**

```ts
const data = Data.fromRawString("abcdefg".repeat(100))
await archive.addFileEntry("fromMemory.txt", data.count, (offset, length) => {
  return data.slice(offset, offset + length)
})
```

***

### `addFileEntrySync(...)`

Synchronous version of `addFileEntry()`.

***

### `addDirectoryEntry(path: string, options?): Promise<void>`

Adds a directory entry to the archive.

**Parameters:**

| Name                        | Type        | Description                         |                                         |
| --------------------------- | ----------- | ----------------------------------- | --------------------------------------- |
| `path`                      | `string`    | Directory path to add.              |                                         |
| `options.modificationDate`  | `Date`      | Optional modification date.         |                                         |
| `options.compressionMethod` | `"deflate"` | `"none"`                            | Compression method (default: `"none"`). |
| `options.bufferSize`        | `number`    | Buffer size (default: `16 * 1024`). |                                         |

**Example:**

```ts
await archive.addDirectoryEntry("images/")
```

***

### `addDirectoryEntrySync(...)`

Synchronous version of `addDirectoryEntry()`.

***

### `removeEntry(path: string, options?): Promise<void>`

Removes a specific entry from the archive (asynchronously).

**Parameters:**

| Name                 | Type     | Description                         |
| -------------------- | -------- | ----------------------------------- |
| `path`               | `string` | The path of the entry to remove.    |
| `options.bufferSize` | `number` | Buffer size (default: `16 * 1024`). |

**Example:**

```ts
await archive.removeEntry("old/file.txt")
```

***

### `removeEntrySync(...)`

Synchronous version of `removeEntry()`.

***

### `extract(path: string, consumer: (data: Data) => void, options?): Promise<void>`

Extracts a specific entry from the archive and provides its data in chunks via a consumer callback (asynchronous).

**Parameters:**

| Name                 | Type                   | Description                            |
| -------------------- | ---------------------- | -------------------------------------- |
| `path`               | `string`               | The path of the entry to extract.      |
| `consumer`           | `(data: Data) => void` | A callback to process each data chunk. |
| `options.bufferSize` | `number`               | Buffer size (default: `16 * 1024`).    |

**Example:**

```ts
await archive.extract("docs/manual.txt", (chunk) => {
  console.log("Received chunk:", chunk.count)
})
```

***

### `extractSync(...)`

Synchronous version of `extract()`.

***

### `extractTo(path: string, to: string, options?): Promise<void>`

Extracts an entry or directory from the archive to a specific file system location (asynchronously).

**Parameters:**

| Name                               | Type      | Description                                               |
| ---------------------------------- | --------- | --------------------------------------------------------- |
| `path`                             | `string`  | Path of the entry inside the archive.                     |
| `to`                               | `string`  | Target path to extract to.                                |
| `options.bufferSize`               | `number`  | Buffer size (default: `16 * 1024`).                       |
| `options.allowUncontainedSymlinks` | `boolean` | Whether to allow uncontained symlinks (default: `false`). |

**Example:**

```ts
await archive.extractTo("docs/", "/tmp/extracted/")
```

***

### `extractToSync(...)`

Synchronous version of `extractTo()`.

***

## ArchiveEntry Interface

`ArchiveEntry` represents a single entry (file, directory, or symbolic link) inside an archive.

| Property           | Type                                                     | Description                      |             |                 |
| ------------------ | -------------------------------------------------------- | -------------------------------- | ----------- | --------------- |
| `path`             | `string`                                                 | The path of the entry.           |             |                 |
| `type`             | `"file"`                                                 | `"directory"`                    | `"symlink"` | The entry type. |
| `isCompressed`     | `boolean`                                                | Whether the entry is compressed. |             |                 |
| `compressedSize`   | `number`                                                 | Compressed size in bytes.        |             |                 |
| `uncompressedSize` | `number`                                                 | Uncompressed size in bytes.      |             |                 |
| `fileAttributes`   | `{ posixPermissions?: number; modificationDate?: Date }` | File attributes.                 |             |                 |

**Example:**

```ts
for (const entry of archive.entries()) {
  console.log(`[${entry.type}] ${entry.path} (${entry.uncompressedSize} bytes)`)
}
```

***

## Examples

### Create a new archive and add files

```ts
const archive = Archive.openForMode("/tmp/example.zip", "update")

await archive.addEntry(
  "/tmp/hello.txt",
  "docs/hello.txt",
  { compressionMethod: "deflate" }
)

await archive.addDirectoryEntry("images/")
await archive.addEntry("/tmp/logo.png", "images/logo.png")

console.log("Archive entries:", archive.entries().length)
```

***

### Extract a file to disk

```ts
const archive = Archive.openForMode("/tmp/example.zip", "read")
await archive.extractTo("docs/hello.txt", "/tmp/unpacked/hello.txt")
```



---
url: /guide/Utilities/CloudSharedData.md
---

# CloudSharedData

The `CloudSharedData` class lets your script read and write an iCloud-backed shared data store and collaborate on it with other users — for example a baby-growth log that the whole family maintains together through the same script.

Data is stored in CloudKit (the owner's private iCloud database) and synced across participants. It requires the user to be signed in to iCloud and a **Pro** subscription, and the script must declare the `cloudSharedData` permission.

***

## Who creates a store

A store is identified by a **UUID**. Scripts are pure consumers — they cannot create or list stores. Instead:

- Create a store in **Settings → iCloud Shared Data** (or ask the assistant to create one). You get a store **UUID**.
- Paste that UUID into your script: `new CloudSharedData(uuid)`.
- To collaborate, share the store (from the management page or via `share()` / `presentShareSheet()` below) and have others accept. Once accepted, they paste the **same** UUID into the same script.

Isolation works by consent, not structure:

- **Per script/skill** — the first time a given script or skill touches a store, the user is asked to grant access for that script + store. Denying makes all calls for that store fail. Grants can be revoked in Settings → iCloud Shared Data.
- **Across users** — handled by CloudKit and Apple ID. A user can only access a store that was explicitly shared with them and that they accepted.

***

## Creating an instance

```ts
// The UUID comes from Settings → iCloud Shared Data, or from a share you accepted.
const store = new CloudSharedData("3F2504E0-4F89-41D3-9A0C-0305E82C3301")
```

***

## Directory semantics (entries)

Use key/value entries when multiple people append or edit independent records — concurrent appends never conflict.

```ts
// Owner or any participant
await store.put("2026-06-20", { height: 75, weight: 9.2 })

const entry = await store.get("2026-06-20")
// entry?.value -> { height: 75, weight: 9.2 }

const all = await store.entries()
// [{ key: "2026-06-20", value: {...}, hasBlob: false }, ...]

await store.remove("2026-06-20")
```

Attach a binary blob to an entry:

```ts
const photo = Data.fromJPEG(image, 0.8)!
await store.put("first-smile", { note: "🙂" }, photo)
const e = await store.get("first-smile")
// e?.blob -> Data | null
```

Same key written again overwrites it (last write wins). Editing the _same_ entry concurrently resolves last-writer-wins; appending or removing _different_ keys never conflicts.

***

## Single-file semantics

When the whole store is one document, use the file APIs (independent of entries):

```ts
await store.writeFile(Data.fromString(JSON.stringify(state))!)
const data = await store.readFile()
```

Concurrent writes to the file are last-writer-wins.

***

## Sharing

```ts
// Get a link to invite collaborators (works in every host, including widgets):
const info = await store.share({ permission: "readWrite" })
// info.url -> send it via Messages, etc.

// Or present the native invite sheet (main app, Share / Translation UI extensions):
await store.presentShareSheet({ permission: "readWrite" })

// Inspect participants / permission:
const current = await store.shareInfo()

// Stop sharing (owner only):
await store.stopSharing()
```

In the native sheet the user can choose between "only invited people" and "anyone with the link", and read-only vs read-write.

***

## Staying in sync

```ts
// Pull-based: cheaply check whether anything changed, then re-read.
if (await store.refresh()) {
  const all = await store.entries()
}

// Push-based: get notified when others change the store.
const unsubscribe = store.onChange(async () => {
  const all = await store.entries()
  // update your UI
})
// Call unsubscribe() when you no longer need updates.
```

***

## Methods

| Method                         | Description                                                           |
| ------------------------------ | --------------------------------------------------------------------- |
| `new CloudSharedData(storeId)` | Connect to a store by UUID (created in Settings, or shared with you). |
| `put(key, value, blob?)`       | Write/overwrite an entry.                                             |
| `get(key)`                     | Read an entry, or `null`.                                             |
| `remove(key)`                  | Delete an entry.                                                      |
| `entries()`                    | List all entries (blobs not loaded).                                  |
| `writeFile(data)`              | Overwrite the store's single-file data.                               |
| `readFile()`                   | Read the single-file data, or `null`.                                 |
| `refresh()`                    | Returns `true` if the store changed since the last call.              |
| `onChange(callback)`           | Observe remote changes; returns an unsubscribe function.              |
| `share(options?)`              | Start/fetch sharing; returns share info with a link.                  |
| `presentShareSheet(options?)`  | Present the native invite sheet.                                      |
| `shareInfo()`                  | Current share info, or `null`.                                        |
| `stopSharing()`                | Stop sharing (owner only).                                            |

***

## Notes

- Requires iCloud sign-in and a Pro subscription; declare the `cloudSharedData` permission in the script.
- Scripts cannot create or list stores — do that in Tools → iCloud Shared Data, or ask the assistant. Scripts consume a store by its UUID.
- Joining a shared store: when someone shares a store with you, tap their share link to open Scripting. It shows the store and an Accept button; after accepting, the store appears in Tools → iCloud Shared Data, where you can copy its ID and paste it into a script.
- The data API (read/write/share-link) works in the app and extensions; the native invite sheet only where a presentation context exists (app, Share / Translation UI extensions).
- Always call the function returned by `onChange` when you are done observing.



---
url: /guide/Utilities/Crypto.md
---

# Crypto

The `Crypto` module provides a set of cryptographic utilities for hashing, HMAC authentication, symmetric key generation, and AES-GCM encryption/decryption. It is designed to securely process `Data` instances using industry-standard algorithms.

***

## Overview

The `Crypto` module enables:

- Hashing data with MD5, SHA-1, SHA-2 family (SHA-224, SHA-256, SHA-384, SHA-512)
- Creating HMAC digests using a secret key
- Generating random symmetric encryption keys
- Encrypting and decrypting data with AES-GCM (authenticated encryption)

All operations are performed on the `Data` type, which encapsulates binary input/output.

***

## Functions

### `Crypto.generateSymmetricKey(size?: number): Data`

Generates a new random symmetric key.

- **Parameters:**

  - `size` (optional): Key size in bits. Defaults to `256`.

- **Returns:** A `Data` object representing the key.

- **Example:**

  ```ts
  const key = Crypto.generateSymmetricKey() // 256-bit key
  ```

***

### Hashing Functions

These functions return a cryptographic hash (digest) of the input data.

#### `Crypto.md5(data: Data): Data`

Hashes the input data using the MD5 algorithm (128-bit output).

- **Returns:** A `Data` object containing the MD5 digest.

- **Example:**

  ```ts
  const data = Data.fromString("Hello")
  const hash = Crypto.md5(data).toHexString()
  ```

***

#### `Crypto.sha1(data: Data): Data`

Uses the SHA-1 algorithm (160-bit output).

- **Returns:** A `Data` object.

***

#### `Crypto.sha256(data: Data): Data`

Uses the SHA-256 algorithm (256-bit output).

- **Returns:** A `Data` object.

- **Example:**

  ```ts
  const hash = Crypto.sha256(Data.fromString("test")).toHexString()
  ```

***

#### `Crypto.sha384(data: Data): Data`

Uses the SHA-384 algorithm (384-bit output).

- **Returns:** A `Data` object.

***

#### `Crypto.sha512(data: Data): Data`

Uses the SHA-512 algorithm (512-bit output).

- **Returns:** A `Data` object.

***

### HMAC Functions

These functions generate a hash-based message authentication code (HMAC) using a shared secret key.

All return a `Data` object representing the HMAC digest.

- **Parameters:**

  - `data`: The message to authenticate (`Data`)
  - `key`: The symmetric key (`Data`)

***

#### `Crypto.hmacMD5(data: Data, key: Data): Data`

Computes HMAC using MD5.

```ts
const key = Crypto.generateSymmetricKey()
const hmac = Crypto.hmacMD5(Data.fromString("msg"), key).toHexString()
```

***

#### `Crypto.hmacSHA1(data: Data, key: Data): Data`

Computes HMAC using SHA-1.

***

#### `Crypto.hmacSHA224(data: Data, key: Data): Data`

Computes HMAC using SHA-224.

***

#### `Crypto.hmacSHA256(data: Data, key: Data): Data`

Computes HMAC using SHA-256.

***

#### `Crypto.hmacSHA384(data: Data, key: Data): Data`

Computes HMAC using SHA-384.

***

#### `Crypto.hmacSHA512(data: Data, key: Data): Data`

Computes HMAC using SHA-512.

***

## AES-GCM Encryption

### `Crypto.encryptAESGCM(data: Data, key: Data, options?: { iv?: Data, aad?: Data }): Data | null`

Encrypts the given data using AES-GCM with the provided key.

- **Parameters:**

  - `data`: The plaintext `Data` to encrypt
  - `key`: A `Data` object representing the symmetric key
  - `options` (optional):

    - `iv`: Initialization vector (optional). If omitted, a random IV is used internally.
    - `aad`: Additional authenticated data (optional). Used for authentication but not encrypted.

- **Returns:** A `Data` object containing the encrypted ciphertext, or `null` on failure.

- **Example:**

  ```ts
  const key = Crypto.generateSymmetricKey()
  const plaintext = Data.fromString("secret message")
  const encrypted = Crypto.encryptAESGCM(plaintext, key)
  ```

***

### `Crypto.decryptAESGCM(data: Data, key: Data, aad?: Data): Data | null`

Decrypts AES-GCM-encrypted `Data` using the provided key and optional AAD.

- **Parameters:**

  - `data`: The encrypted data (`Data`)
  - `key`: The symmetric key used to encrypt the data
  - `aad` (optional): The additional authenticated data used during encryption (must match exactly)

- **Returns:** The decrypted plaintext as `Data`, or `null` if decryption fails (e.g., tag mismatch or incorrect key).

- **Example:**

  ```ts
  const decrypted = Crypto.decryptAESGCM(encrypted, key)
  console.log(decrypted?.toRawString())
  ```

***

## Summary of Algorithms

| Function  | Output Size  | Use Case                   |
| --------- | ------------ | -------------------------- |
| `md5`     | 128 bits     | Legacy checksums           |
| `sha1`    | 160 bits     | Compatibility              |
| `sha256`  | 256 bits     | General-purpose security   |
| `sha384`  | 384 bits     | Stronger hashing           |
| `sha512`  | 512 bits     | High-security requirements |
| `hmacXXX` | Same as hash | Authentication             |
| `AES-GCM` | variable     | Authenticated encryption   |

***

## Full Example

```ts
const key = Crypto.generateSymmetricKey()
const message = Data.fromString("Encrypt me")
const encrypted = Crypto.encryptAESGCM(message, key)
const decrypted = encrypted ? Crypto.decryptAESGCM(encrypted, key) : null

if (decrypted) {
  console.log("Decrypted:", decrypted.toRawString())
}
```

***

## Notes

- All functions require valid `Data` objects.
- For AES-GCM, if `iv` is omitted, a secure random IV is automatically applied.
- Encrypted `Data` may include the IV and authentication tag.



---
url: /guide/Utilities/Data.md
---

# Data

The `Data` class represents binary data in memory and provides a wide range of methods for manipulating, converting, compressing, decompressing, and transforming that data. It is useful for working with raw byte buffers, encoded files, images, and more.

***

## CompressionAlgorithm (Enum)

Specifies which compression algorithm to use when compressing or decompressing a `Data` instance:

| Value   | Description                                               |
| ------- | --------------------------------------------------------- |
| `lzfse` | Fast and efficient compression using the LZFSE algorithm. |
| `lz4`   | Very fast compression with moderate compression ratio.    |
| `lzma`  | High compression ratio, slower performance.               |
| `zlib`  | Standard and widely-used compression format.              |

***

## Instance Properties and Methods

### `size: number`

The length of the data in bytes (read-only).

***

### `resetBytes(startIndex: number, endIndex: number): void`

Resets a range of bytes to zero.

- `startIndex`: Starting index (inclusive)
- `endIndex`: Ending index (exclusive)

Throws an error if the indices are out of bounds.

***

### `advanced(amount: number): Data`

Returns a new `Data` instance by removing the first `amount` bytes from the buffer.

***

### `replaceSubrange(startIndex, endIndex, data): void`

Replaces a specified byte range with the content of another `Data` instance.

***

### `compressed(algorithm: CompressionAlgorithm): Data`

Compresses the current data using the specified algorithm and returns a new `Data` instance.

Throws an error if the data is empty or cannot be compressed.

***

### `decompressed(algorithm: CompressionAlgorithm): Data`

Decompresses the current data using the specified algorithm and returns a new `Data` instance.

Must use the same algorithm that was used to compress the data.

***

### `slice(start?: number, end?: number): Data`

Returns a new `Data` instance representing a slice of the original.

- `start`: Starting index (default is `0`)
- `end`: Ending index (default is the end of the data)

***

### `append(other: Data): void`

Appends another `Data` instance to the end of the current one.

***

### `getBytes(): Uint8Array | null` (Deprecated)

Use `toUint8Array()` instead.

***

### `toUint8Array(): Uint8Array | null`

Converts the data into a `Uint8Array`.

***

### `toArrayBuffer(): ArrayBuffer`

Converts the data into an `ArrayBuffer`.

***

### `toBase64String(): string`

Returns a Base64-encoded string representation of the data.

***

### `toHexString(): string`

Returns a hexadecimal string representation of the data.

***

### `toRawString(encoding?: string): string | null`

Converts the data into a string using the specified encoding (default: `"utf-8"`), strictly following the specified encoding, and returning `null` if the data is empty or cannot be converted to a string.

***

### `toDecodedString(encoding?: "utf8" | "ascii"): string`

Converts the data into a decoded string using the specified encoding (default: `"utf-8"`), loosing any bad characters.

***

### `toIntArray(): number[]`

Returns an array of integers representing the bytes of the data.

***

## Static Methods

### `Data.fromIntArray(array: number[]): Data`

Creates a `Data` instance from an array of integers.

***

### `Data.fromString(str: string, encoding?: string): Data | null` (Deprecated)

Use `Data.fromRawString()` instead.

***

### `Data.fromRawString(str: string, encoding?: string): Data | null`

Creates a `Data` instance from a raw string, using the specified encoding (default: `"utf-8"`).

***

### `Data.fromFile(filePath: string): Data | null`

Reads binary data from a file path and returns a `Data` instance.

***

### `Data.fromArrayBuffer(buffer: ArrayBuffer): Data | null`

Creates a `Data` instance from an `ArrayBuffer`.

***

### `Data.fromUint8Array(bytes: Uint8Array): Data | null`

Creates a `Data` instance from a `Uint8Array`.

***

### `Data.fromBase64String(base64: string): Data | null`

Creates a `Data` instance from a Base64-encoded string.

***

### `Data.fromHexString(hex: string): Data | null`

Creates a `Data` instance from a hexadecimal string.

***

### `Data.fromJPEG(image: UIImage, compressionQuality?: number): Data | null`

Converts a `UIImage` to JPEG format data.

- `compressionQuality`: Compression quality between `0.0` and `1.0` (default: `1.0`)

***

### `Data.fromPNG(image: UIImage): Data | null`

Converts a `UIImage` to PNG format data.

***

### `Data.combine(dataList: Data[]): Data`

Combines multiple `Data` instances into one.

Returns `null` if the list is empty or all items are empty.



---
url: /guide/Utilities/DateComponents.md
---

# DateComponents

The `DateComponents` class provides a flexible way to represent and manipulate individual components of a date and time value, such as year, month, day, hour, minute, second, and more. This class is modeled after Swift’s `DateComponents` and integrates with the current system calendar.

***

## Constructor

```ts
new DateComponents(options?)
```

### Parameters

The constructor accepts an optional `options` object to initialize date/time fields:

```ts
const components = new DateComponents({
  year: 2025,
  month: 6,
  day: 24,
  hour: 9,
  minute: 30
})
```

***

## Static Methods

### `DateComponents.fromDate(date: Date): DateComponents`

Creates a `DateComponents` instance by extracting all possible components from a given `Date` object.

#### Parameters

- `date` (`Date`): The source date.

#### Returns

- A `DateComponents` instance with year, month, day, hour, minute, second, and nanosecond set.

#### Example

```ts
const now = new Date()
const components = DateComponents.fromDate(now)
console.log(components.year, components.month)
```

***

### `DateComponents.forHourly(date: Date): DateComponents`

Creates a `DateComponents` instance representing the hourly trigger for scheduling purposes.

- Sets: `minute`

#### Example

```ts
const components = DateComponents.forHourly(new Date())
// Triggers every hour at the same minute as the provided date
```

***

### `DateComponents.forDaily(date: Date): DateComponents`

Creates a `DateComponents` instance representing the daily trigger.

- Sets: `hour`, `minute`

#### Example

```ts
const components = DateComponents.forDaily(new Date())
// Triggers daily at the same hour and minute as the provided date
```

***

### `DateComponents.forWeekly(date: Date): DateComponents`

Creates a `DateComponents` instance for weekly triggers, useful for weekly recurring events.

- Sets: `weekday`, `hour`, `minute`

#### Example

```ts
const components = DateComponents.forWeekly(new Date())
// Triggers weekly on the same weekday at the same time
```

***

### `DateComponents.forMonthly(date: Date): DateComponents`

Creates a `DateComponents` instance representing a monthly trigger.

- Sets: `day`, `hour`, `minute`

#### Example

```ts
const components = DateComponents.forMonthly(new Date())
// Triggers monthly on the same day and time
```

***

## Properties

### Read-only Properties

- **`date?: Date | null`**
  The computed `Date` object based on the current components using the current system calendar. Returns `null` if the components do not form a valid date.

- **`isValidDate: boolean`**
  Indicates whether the current combination of components forms a valid date.

***

### Date and Time Fields

Each of these fields can be initialized via the constructor or set manually afterward. All are `number | null` unless otherwise stated.

- `era`: The era of the date.

- `year`: The year component.

- `yearForWeekOfYear`: The year that corresponds to the week-based calendar.

- `quarter`: The quarter of the year (1 to 4).

- `month`: The month of the year (1 to 12).

- `isLeapMonth`: Optional boolean indicating whether the month is a leap month.

- `weekOfMonth`: The week number within the current month.

- `weekOfYear`: The week number within the current year.

- `weekday`: The day of the week (1 = Sunday, 2 = Monday, ..., 7 = Saturday).

- `weekdayOrdinal`: The ordinal occurrence of the weekday in the month.

  #### Example

  ```ts
  const components = new DateComponents()
  components.weekday = 2             // Monday
  components.weekdayOrdinal = 1      // First Monday of the month
  ```

- `day`: The day of the month.

- `hour`: The hour of the day (0–23).

- `minute`: The minute (0–59).

- `second`: The second (0–59).

- `nanosecond`: The nanosecond part of the time.

- `dayOfYear`: The day of the year (1–366).

***

## Usage Example

```ts
const components = new DateComponents({
  year: 2025,
  month: 12,
  day: 25,
  hour: 10,
  minute: 0
})

if (components.isValidDate) {
  console.log("Valid date:", components.date)
}
```

Or create from a `Date`:

```ts
const now = new Date()
const components = DateComponents.fromDate(now)
console.log(components.hour, components.minute)

const dailyTrigger = DateComponents.forDaily(new Date())
const weeklyTrigger = DateComponents.forWeekly(new Date())
```

***

## Notes

- `date` and `isValidDate` rely on the system’s calendar.
- Use specialized static methods (`forDaily`, `forWeekly`, etc.) for easier creation of recurring triggers.
- `DateComponents` is ideal for scheduling notifications, alarms, calendar events, and more.



---
url: /guide/Utilities/DateFormatter.md
---

# DateFormatter

The `DateFormatter` class provides comprehensive date and time formatting capabilities. It allows converting `Date` objects into localized strings and parsing strings back into `Date` values.
This API wraps iOS-native date formatting behavior and supports multiple calendars, time zones, localized formats, and custom formatting templates.

***

## Enums and Type Definitions

## DateFormatterStyle

Defines the level of detail used for date or time formatting.

| Value    | Description                                   |
| -------- | --------------------------------------------- |
| `none`   | No date or time displayed                     |
| `short`  | Short format, e.g., `12/1/25`, `3:20 PM`      |
| `medium` | Medium format, e.g., `Dec 1, 2025`            |
| `long`   | Long format, e.g., `December 1, 2025`         |
| `full`   | Full format, e.g., `Monday, December 1, 2025` |

***

## DateFormatterBehavior

Controls the formatter behavior mode.

| Value          | Description                                  |
| -------------- | -------------------------------------------- |
| `default`      | System default behavior                      |
| `behavior10_4` | Compatibility mode for older system behavior |

***

## CalendarIdentifier

Specifies the calendar used for formatting. This enables formatting using:

- Gregorian calendar
- Chinese lunar calendar
- Japanese calendar
- Islamic calendars
- Buddhist calendar
- ISO 8601 calendar
  and more.

Example values:

```
"current" | "gregorian" | "chinese" | "japanese" | "islamic" | "iso8601" | ...
```

Notes:

- `"current"` uses the system’s current calendar
- `"autoupdatingCurrent"` automatically updates when system settings change

***

## TimeZoneIdentifier

Specifies the time zone.

Available values:

```
"current" | "autoupdatingCurrent" | "gmt" | string
```

If a string is used, it must be a valid time-zone identifier such as:

- `"Asia/Shanghai"`
- `"America/Los_Angeles"`
- `"UTC"`

***

## Class: DateFormatter

## Initialization

### `new(): DateFormatter`

Creates a new date formatter instance.

***

## Static Methods

## `DateFormatter.localizedString(date, options)`

Returns a localized date string based on the specified date and time styles.

```ts
DateFormatter.localizedString(date: Date, options: {
  dateStyle: DateFormatterStyle
  timeStyle: DateFormatterStyle
}): string
```

Useful for quick formatting without manually configuring a formatter instance.

***

## `DateFormatter.dateFormat(template, locale?)`

Generates a localized date format string based on a template.

```
static dateFormat(template: string, locale?: string): string | null
```

Examples of templates:

- `"yyyyMMdd"`
- `"MMM d"`
- `"HH:mm"`

If `locale` is omitted, the system locale is used.

***

## Instance Methods

## `string(date: Date): string`

Formats a `Date` into a string.

Behavior:

- If `dateFormat` is set, it takes priority.
- Otherwise, formatting is based on `dateStyle` and `timeStyle`.

***

## `date(string: string): Date | null`

Parses a string into a `Date` object.
Parsing behavior depends on properties such as `dateFormat`, `locale`, and `calendar`.

***

## `setLocalizedDateFormatFromTemplate(template: string): void`

Generates a localized format string from the template and assigns it to `dateFormat`.

***

## Properties

## Core Formatting Properties

### `calendar: CalendarIdentifier`

Determines the calendar system used for formatting.
Examples: `"gregorian"`, `"chinese"`, `"buddhist"`.

***

### `timeZone: TimeZoneIdentifier`

Defines the time zone, such as `"Asia/Shanghai"`.

***

### `locale: string`

Specifies the formatting locale, such as:

- `"zh_CN"`
- `"en_US"`
- `"ja_JP"`

***

### `dateFormat: string`

Manually sets a custom date format template. Examples:

```
"yyyy-MM-dd HH:mm"
"MMM d, yyyy"
"EEEE"
```

When set, it overrides `dateStyle` and `timeStyle`.

***

### `dateStyle: DateFormatterStyle`

### `timeStyle: DateFormatterStyle`

Control the granularity of date and time output.

***

## Behavior Control

### `generatesCalendarDates: boolean`

Controls whether the formatter generates calendar-based dates. Typically left as default.

***

### `formatterBehavior: DateFormatterBehavior`

Controls the formatter behavior mode.

***

### `isLenient: boolean`

Enables lenient parsing of input strings, allowing more flexible interpretation.
Defaults to `false` to avoid accidental incorrect parsing.

***

### `twoDigitStartDate: Date | null`

Determines the interpretation range for two-digit years.

***

### `defaultDate: Date | null`

Used when parsing strings that do not specify a full date.

***

## Localization Symbol Properties

These properties customize how months, weekdays, quarters, and eras are displayed:

- `eraSymbols`
- `monthSymbols`
- `shortMonthSymbols`
- `weekdaySymbols`
- `shortWeekdaySymbols`
- `standaloneMonthSymbols`
- `quarterSymbols`
- `veryShortWeekdaySymbols`
- `amSymbol`
- `pmSymbol`
- `gregorianStartDate`

These are typically used only when overriding the system-provided localized symbols.

***

## Relative Date Formatting

### `doesRelativeDateFormatting: boolean`

Enables output like:

- Today
- Yesterday
- Tomorrow

in the corresponding locale.

Example in Chinese:

- 今天
- 昨天

Only works with certain date styles (e.g., medium and long).

***

## Code Examples

***

## Example 1: Localized formatting using dateStyle and timeStyle

```tsx
const df = new DateFormatter()
df.locale = "zh_CN"
df.dateStyle = DateFormatterStyle.full
df.timeStyle = DateFormatterStyle.short

const result = df.string(new Date())
// Example output: "Friday, December 12, 2025 at 3:20 PM"
```

***

## Example 2: Custom date format

```tsx
const df = new DateFormatter()
df.locale = "en_US"
df.dateFormat = "yyyy-MM-dd HH:mm"
df.timeZone = "Asia/Shanghai"

const str = df.string(new Date())
// Example output: "2025-12-12 15:20"
```

***

## Example 3: Formatting using the Chinese lunar calendar

```tsx
const df = new DateFormatter()
df.calendar = "chinese"
df.locale = "zh_CN"
df.dateFormat = "yyyy年MM月dd日 EEEE"

const lunar = df.string(new Date())
// Example output: "四十三年十月二十二日 星期五"
```

***

## Example 4: Parsing a date string

```tsx
const df = new DateFormatter()
df.dateFormat = "yyyy/MM/dd HH:mm"

const date = df.date("2025/12/12 08:00")
```

***

## Example 5: Using a localized template

```tsx
const df = new DateFormatter()
df.locale = "zh_CN"

// Automatically becomes a localized format, e.g., "12月12日"
df.setLocalizedDateFormatFromTemplate("MMdd")

const result = df.string(new Date())
```

***

## Example 6: Quick formatting using localizedString

```tsx
const str = DateFormatter.localizedString(new Date(), {
  dateStyle: DateFormatterStyle.medium,
  timeStyle: DateFormatterStyle.short
})
```



---
url: /guide/Utilities/Encoding.md
---

# Encoding

The `Encoding` type defines a set of supported character encodings used by methods like:

- `Data.fromRawString(str, encoding)` — converts a text string into binary data using the specified encoding.
- `Data.toRawString(encoding)` — converts binary data back into a string using the specified encoding.

These encodings allow interoperability with various text formats and systems, ensuring compatibility across languages and platforms.

***

## Available Encodings

| Encoding                | Description                                                                                                                                                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"utf-8" / "utf8"**    | UTF-8 (8-bit Unicode Transformation Format). The most common encoding for web and modern text processing. Efficient for ASCII-compatible text and supports all Unicode characters.                                           |
| **"utf-16" / "utf16"**  | UTF-16 (16-bit Unicode Transformation Format). Common in Windows and Apple platforms. Each character typically uses 2 bytes.                                                                                                 |
| **"utf-32" / "utf32"**  | UTF-32 (32-bit Unicode Transformation Format). Fixed 4-byte representation per character, used for direct Unicode code point manipulation.                                                                                   |
| **"ascii"**             | American Standard Code for Information Interchange. Represents English letters, digits, and basic symbols using one byte (0–127).                                                                                            |
| **"iso2022JP"**         | ISO-2022-JP. A Japanese character encoding used for emails and legacy systems. Supports JIS X 0201/0208 character sets.                                                                                                      |
| **"isoLatin1"**         | ISO-8859-1 (Latin-1). Covers Western European languages such as English, French, German, and Spanish.                                                                                                                        |
| **"japaneseEUC"**       | EUC-JP (Extended Unix Code for Japanese). Another Japanese encoding, used mainly in Unix systems.                                                                                                                            |
| **"macOSRoman"**        | Apple’s MacRoman encoding, historically used on classic Mac OS before Unicode adoption.                                                                                                                                      |
| **"nextstep"**          | NextStep encoding (NS encoding). A legacy encoding from NeXTSTEP systems. Rarely used today.                                                                                                                                 |
| **"nonLossyASCII"**     | Non-lossy ASCII encoding. Ensures that any Unicode string can be safely represented as ASCII escape sequences and later restored without data loss.                                                                          |
| **"shiftJIS"**          | Shift-JIS encoding for Japanese text, commonly used on Windows in Japan.                                                                                                                                                     |
| **"symbol"**            | Symbol encoding, used for specialized symbol fonts such as the Symbol typeface.                                                                                                                                              |
| **"unicode"**           | A general alias for Unicode encodings (usually UTF-16). Behaves similarly to `"utf16"`.                                                                                                                                      |
| **"utf16BigEndian"**    | UTF-16 with big-endian byte order. The most significant byte (MSB) comes first.                                                                                                                                              |
| **"utf16LittleEndian"** | UTF-16 with little-endian byte order. The least significant byte (LSB) comes first.                                                                                                                                          |
| **"utf32BigEndian"**    | UTF-32 with big-endian byte order.                                                                                                                                                                                           |
| **"utf32LittleEndian"** | UTF-32 with little-endian byte order.                                                                                                                                                                                        |
| **"windowsCP1250"**     | Windows code page 1250 for Central and Eastern European languages (e.g., Polish, Czech, Hungarian).                                                                                                                          |
| **"windowsCP1251"**     | Windows code page 1251 for Cyrillic scripts (e.g., Russian, Bulgarian, Serbian).                                                                                                                                             |
| **"windowsCP1252"**     | Windows code page 1252 for Western European languages (similar to Latin-1 but includes additional symbols).                                                                                                                  |
| **"windowsCP1253"**     | Windows code page 1253 for Greek language support.                                                                                                                                                                           |
| **"windowsCP1254"**     | Windows code page 1254 for Turkish language support.                                                                                                                                                                         |
| **"gbk"**               | GBK (Guojia Biaozhun Kuozhan). A widely used simplified Chinese character encoding, extending GB2312 to include traditional Chinese and Japanese kana. It is backward compatible with GB2312.                                |
| **"gb18030"**           | GB18030 (National Standard of the People's Republic of China). A superset of GBK and GB2312, and the official mandatory standard in China. Fully compatible with Unicode and capable of representing all Unicode characters. |

***

## Example Usage

### Converting a String to Data and Back

```ts
// Convert a UTF-8 string to binary data
const text = "こんにちは世界"  // "Hello World" in Japanese
const utf8Data = Data.fromRawString(text, "utf-8")

// Convert the binary data back to a string
const decoded = utf8Data.toRawString("utf-8")

console.log(decoded) // Output: こんにちは世界
```

***

### Using a Different Encoding

```ts
// Encode using Shift-JIS (Japanese)
const sjisData = Data.fromRawString("テスト", "shiftJIS")

// Decode back from Shift-JIS
const decodedSJIS = sjisData.toRawString("shiftJIS")
console.log(decodedSJIS) // Output: テスト
```

***

### Example for Windows Encodings

```ts
// Encode text with Central European characters
const text = "Příliš žluťoučký kůň úpěl ďábelské ódy"
const data = Data.fromRawString(text, "windowsCP1250")
const result = data.toRawString("windowsCP1250")
console.log(result)
```

***

## Notes

- When encoding or decoding fails (e.g., using the wrong encoding for the data), the returned string may contain invalid characters (�).
- For most use cases, `"utf-8"` is recommended due to its compatibility and efficiency.
- Legacy encodings such as `"shiftJIS"`, `"iso2022JP"`, and `"windowsCP125x"` are provided for interoperability with older file formats and systems.



---
url: /guide/Utilities/FileEntity.md
---

# FileEntity

The `FileEntity` class provides low-level file read and write operations.
It allows scripts and HTTP servers to open, read, write, seek, and close files efficiently.
`FileEntity` can also be used as a response body for `HttpResponse.raw()` to serve static or downloadable files.

***

## Overview

`FileEntity` enables direct file operations, including:

- Opening files in different modes (read, write, read/write, append, etc.)
- Reading and writing binary data (`Data` objects)
- Seeking to a specific offset in the file
- Closing files to release resources
- Returning file streams as HTTP responses

***

## Instance Properties

### `path: string`

The full path of the file represented by this `FileEntity` instance.

**Example:**

```ts
const file = FileEntity.openForReading("/path/to/file.txt")
console.log(file.path)
// Output: "/path/to/file.txt"
```

***

## Instance Methods

### `seek(offset: number): boolean`

Moves the file pointer to the specified byte offset.
Returns `true` if successful, or `false` if seeking fails.

**Parameters:**

| Name     | Type     | Description                 |
| -------- | -------- | --------------------------- |
| `offset` | `number` | The byte offset to move to. |

**Example:**

```ts
const file = FileEntity.openForReading("/path/to/data.bin")
file.seek(128)
```

***

### `read(size: number): Data`

Reads a specified number of bytes from the current file position and returns them as a `Data` object.

**Parameters:**

| Name   | Type     | Description              |
| ------ | -------- | ------------------------ |
| `size` | `number` | Number of bytes to read. |

**Returns:**
A `Data` object containing the read bytes.

**Example:**

```ts
const file = FileEntity.openForReading("/path/to/text.txt")
const data = file.read(100)
console.log(data.toRawString("utf-8"))
file.close()
```

***

### `write(data: Data): void`

Writes the provided `Data` to the current file position.
Throws an error if the file was not opened in a writable mode.

**Parameters:**

| Name   | Type   | Description                           |
| ------ | ------ | ------------------------------------- |
| `data` | `Data` | The binary data to write to the file. |

**Example:**

```ts
const data = Data.fromRawString("Hello, Scripting!", "utf-8")
const file = FileEntity.openNewForWriting("/tmp/test.txt")
file.write(data)
file.close()
```

***

### `close(): void`

Closes the file and releases the associated resources.
After closing, you should not call `read()` or `write()` again.

**Example:**

```ts
const file = FileEntity.openForReading("/path/to/file.txt")
// ... perform operations ...
file.close()
```

***

## Static Methods

### `static openForReading(path: string): FileEntity`

Opens a file in **read-only** mode.
Throws an error if the file does not exist or cannot be read.

**Parameters:**

| Name   | Type     | Description            |
| ------ | -------- | ---------------------- |
| `path` | `string` | The file path to open. |

**Example:**

```ts
const file = FileEntity.openForReading("/path/to/image.png")
```

***

### `static openNewForWriting(path: string): FileEntity`

Opens a file in **write-only** mode.
If the file already exists, it will be **overwritten**.

**Example:**

```ts
const file = FileEntity.openNewForWriting("/tmp/output.txt")
file.write(Data.fromRawString("New file created"))
file.close()
```

***

### `static openForWritingAndReading(path: string): FileEntity`

Opens a file in **read/write** mode.
If the file does not exist, it will be created automatically.

**Example:**

```ts
const file = FileEntity.openForWritingAndReading("/tmp/data.txt")
file.write(Data.fromRawString("abc"))
file.seek(0)
console.log(file.read(3).toRawString("utf-8"))
file.close()
```

***

### `static openForMode(path: string, mode: string): FileEntity`

Opens a file using the specified access mode.
The supported modes follow standard POSIX file semantics, but **it is strongly recommended to use binary-safe modes** such as `"rb"` or `"r+b"` for better cross-platform compatibility, since `FileEntity` performs all read/write operations in binary mode internally.

**Parameters:**

| Mode             | Description                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `"r"` / `"rb"`   | Read-only mode (file must exist). `"rb"` is recommended for better compatibility.                     |
| `"w"` / `"wb"`   | Write-only mode (creates a new file or overwrites the existing one). `"wb"` is recommended.           |
| `"a"` / `"ab"`   | Append mode (writes data to the end of the file; creates the file if missing). `"ab"` is recommended. |
| `"r+"` / `"r+b"` | Read/write mode (file must exist). `"r+b"` is recommended for binary read/write.                      |
| `"w+"` / `"w+b"` | Read/write mode (creates or overwrites the file). `"w+b"` is recommended.                             |
| `"a+"` / `"a+b"` | Read/append mode (creates the file if missing). `"a+b"` is recommended.                               |

> 💡 **Note:**
> Always prefer binary-safe modes (those ending with `b`), such as `"rb"`, `"wb"`, or `"r+b"`.
> This ensures consistent behavior across platforms and avoids newline or encoding conversion issues, since `FileEntity` handles all file I/O as binary streams.

**Example:**

```ts
// Open file in binary read/write mode (recommended)
const file = FileEntity.openForMode("/tmp/log.bin", "r+b")

// Write binary data
file.write(Data.fromRawString("append log\n"))

// Move to the beginning and read data
file.seek(0)
const content = file.read(20).toRawString("utf-8")
console.log(content)

file.close()
```

***

## Using FileEntity in HttpResponse

`FileEntity` can be used directly as the body of an HTTP response via `HttpResponse.raw()`.
This allows serving files or implementing file download endpoints.

**Example:**

```ts
server.registerHandler("/download", (req) => {
  const file = FileEntity.openForReading(Path.join(Script.directory, "manual.pdf"))
  return HttpResponse.raw(200, "OK", {
    headers: { "Content-Type": "application/pdf" },
    body: file
  })
})
```

Clients accessing `/download` will directly receive the file as a download.

***

## Summary

| Method                       | Description                          | Typical Use Case                |
| ---------------------------- | ------------------------------------ | ------------------------------- |
| `seek()`                     | Moves the read/write position        | Random access or partial reads  |
| `read()`                     | Reads data from file                 | Reading text or binary content  |
| `write()`                    | Writes data to file                  | Saving logs, exporting data     |
| `close()`                    | Closes the file                      | Always call after use           |
| `openForReading()`           | Opens a file for reading             | Serving static content          |
| `openNewForWriting()`        | Opens a file for writing (overwrite) | Creating new files              |
| `openForWritingAndReading()` | Opens for both reading and writing   | Editing or streaming            |
| `openForMode()`              | Opens file in custom mode            | POSIX-compatible access control |



---
url: /guide/Utilities/FileManager.md
---

# FileManager

The **FileManager** module provides a unified interface for interacting with the file system in Scripting. It serves as the primary API for accessing local files, iCloud files, App Group shared storage, and performing common file operations such as reading, writing, copying, moving, deleting, zipping, and unzipping.

***

## Core Properties

### `FileManager.scriptsDirectory: string`

Returns the directory path where script files are stored within the Scripting app.

### `FileManager.isiCloudEnabled: boolean`

Indicates whether iCloud is enabled for the user. Returns `false` if:

- The user is not logged into iCloud, or
- iCloud permissions have not been granted to the Scripting app.

### `FileManager.iCloudDocumentsDirectory: string`

Returns the path to the iCloud `Documents` directory.
Throws an error if iCloud is disabled. Always check `isiCloudEnabled` before calling.

### `FileManager.appGroupDocumentsDirectory: string`

Returns the path to the shared App Group `Documents` directory.
Files stored here are not accessible in the Files app, but scripts running inside Widgets can access them.

### `FileManager.isWebDAVAvailable: boolean`

Indicates whether WebDAV has been configured and is available for use.

### `FileManager.webDAVDocumentsDirectory: string`

Returns the path to the WebDAV-backed `Documents` cache directory.
Files written here will be queued for WebDAV sync after WebDAV is configured.

### `FileManager.safariBrowserDirectory: string`

Returns the Safari browser userscript data root. This directory follows the Safari Browser Data storage location configured in Settings and contains `userscripts/`, `storages/`, and `downloads/`.

Use this when an app script needs to inspect or maintain the whole Safari extension data area.

### `FileManager.safariBrowserStorageDirectory: string`

Returns the directory where Safari browser userscripts store GM value JSON files. This points to `scripting-safari-extension/storages/`.

### `FileManager.safariBrowserDownloadsDirectory: string`

Returns the directory where Safari browser userscripts save files through `GM.download`. This points to `scripting-safari-extension/downloads/`.

### `FileManager.safariBrowserUserscriptsDirectory: string`

Returns the directory where Safari browser userscripts installed from the extension popup are stored. This points to `scripting-safari-extension/userscripts/`.

### `FileManager.documentsDirectory: string`

Returns the path to the local `Documents` directory.
Files stored here are visible in the Files app. Widgets cannot access files in this directory.

### `FileManager.temporaryDirectory: string`

Returns the path to the system temporary directory.
Files stored here may be removed automatically by the system.

***

## iCloud File Management

### `FileManager.isFileStoredIniCloud(filePath: string): boolean`

Checks whether the specified file is stored in iCloud.

| Parameter | Type   | Description            |
| --------- | ------ | ---------------------- |
| filePath  | string | The file path to check |

### `FileManager.isiCloudFileDownloaded(filePath: string): boolean`

Checks whether an iCloud-stored file has been downloaded to the device.

### `FileManager.downloadFileFromiCloud(filePath: string): Promise<boolean>`

Downloads an iCloud file to the device.

| Returns           | Description                 |
| ----------------- | --------------------------- |
| Promise\<boolean> | `true` if download succeeds |

**Example:**

```ts
if (FileManager.isiCloudEnabled) {
  const file = FileManager.iCloudDocumentsDirectory + "/data.json";
  const success = await FileManager.downloadFileFromiCloud(file);
}
```

### `FileManager.getShareUrlOfiCloudFile(path: string, expiration?: number): string`

Generates a shareable download URL for an iCloud file.

| Parameter  | Type              | Description                                                                                                          |
| ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| path       | string            | The iCloud file path. Must begin with `FileManager.iCloudDocumentsDirectory`. File must be fully uploaded to iCloud. |
| expiration | number (optional) | Expiration timestamp of the share link                                                                               |

This call may throw an error. Use `try-catch` for error handling.

***

## Directory and File Operations

All operations are available in both asynchronous and synchronous forms.
Synchronous methods block execution; asynchronous versions are recommended for most use cases.

### Create Directory

#### `createDirectory(path: string, recursive?: boolean): Promise<void>`

#### `createDirectorySync(path: string, recursive?: boolean): void`

| Parameter | Type               | Description                                             |
| --------- | ------------------ | ------------------------------------------------------- |
| path      | string             | Directory path to create                                |
| recursive | boolean (optional) | If true, creates intermediate directories automatically |

### Create Symbolic Link

#### `createLink(path: string, target: string): Promise<void>`

#### `createLinkSync(path: string, target: string): void`

Creates a symbolic link at `path` pointing to `target`.

### Copy File

#### `copyFile(path: string, newPath: string): Promise<void>`

#### `copyFileSync(path: string, newPath: string): void`

### Read Directory

#### `readDirectory(path: string, recursive?: boolean): Promise<string[]>`

#### `readDirectorySync(path: string, recursive?: boolean): string[]`

Enumerates the contents of a directory and optionally recurses into subdirectories.

### Check Existence

#### `exists(path: string): Promise<boolean>`

#### `existsSync(path: string): boolean`

Checks whether a file or directory exists.

### File Bookmarks

Bookmarks allow persistent access to user-authorized external files or folders.

| Method                  | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `bookmarkExists(name)`  | Checks whether a bookmark exists                                |
| `getAllFileBookmarks()` | Returns all bookmark names and their paths                      |
| `bookmarkedPath(name)`  | Returns file path for the bookmark name, or `null` if not found |

***

### Determine File Type

| Method                            | Returns | Description                          |
| --------------------------------- | ------- | ------------------------------------ |
| `isFile / isFileSync`             | boolean | Whether the path refers to a file    |
| `isDirectory / isDirectorySync`   | boolean | Whether it refers to a directory     |
| `isLink / isLinkSync`             | boolean | Whether it refers to a symbolic link |
| `isBinaryFile / isBinaryFileSync` | boolean | Whether the file is binary           |

***

## File Reading and Writing

Supports three data formats: string, `Uint8Array`, and `Data`.

### Read File

| Method              | Return Type | Description                              |
| ------------------- | ----------- | ---------------------------------------- |
| readAsString / Sync | string      | Reads text using specified encoding      |
| readAsBytes / Sync  | Uint8Array  | Reads raw bytes                          |
| readAsData / Sync   | Data        | Reads the entire file as a `Data` object |

### Write File

| Method               | Data Format |
| -------------------- | ----------- |
| writeAsString / Sync | string      |
| writeAsBytes / Sync  | Uint8Array  |
| writeAsData / Sync   | Data        |

Existing files will be overwritten.

### Append to File

| Method            | Data Format |
| ----------------- | ----------- |
| appendText / Sync | string      |
| appendData / Sync | Data        |

If the file or its parent directory does not exist, it will be created automatically.

***

## File Information and Management

### `stat(path: string): Promise<FileStat>`

### `statSync(path: string): FileStat`

Returns a `FileStat` object for the file or directory. If the path is a symbolic link, the resolved target is reported.

### `rename / renameSync`

Moves or renames a file or directory.

### `remove / removeSync`

Removes a file or directory. Directories are removed recursively.

***

## Compression and Extraction

### `zip(srcPath: string, destPath: string, shouldKeepParent?: boolean): Promise<void>`

### `zipSync(srcPath: string, destPath: string, shouldKeepParent?: boolean): void`

Creates a zip archive from a file or directory.

### `unzip(srcPath: string, destPath: string): Promise<void>`

### `unzipSync(srcPath: string, destPath: string): void`

Extracts a zip archive to the specified destination.

**Example:**

```ts
const docs = FileManager.documentsDirectory;

await FileManager.zip(docs + "/MyScript", docs + "/MyScript.zip");
await FileManager.unzip(docs + "/MyScript.zip", docs + "/Output");
```

***

## Utility Methods

### `mimeType(path: string): string`

Returns the MIME type of the file based on its extension.

### `destinationOfSymbolicLink(path: string): string`

Returns the destination of a symbolic link.

***

## Types

### `FileStat`

```ts
type FileStat = {
  creationDate: number;
  modificationDate: number;
  type: string; // "file" | "directory" | "link" | "unixDomainSock" | "pipe" | "notFound"
  size: number;
};
```



---
url: /guide/Utilities/HeadphoneMotionManager.md
---

# HeadphoneMotionManager

The `HeadphoneMotionManager` namespace streams motion data from headphones that support spatial audio with dynamic head tracking, such as **AirPods Pro**, **AirPods Max**, and **AirPods 3**.

It wraps Apple's `CMHeadphoneMotionManager` and exposes attitude, rotation rate, user acceleration, gravity, and connection events to your scripts.

***

## Properties

| Name          | Type      | Description                                                                                                                         |
| ------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `isAvailable` | `boolean` | Whether headphone motion data is currently available. Returns `false` on simulators or when no compatible headphones are reachable. |
| `isActive`    | `boolean` | Whether motion updates are currently being delivered.                                                                               |

> Authorization is handled internally — your script does not need to query or request permission. The first call to `startDeviceMotionUpdates` triggers the system prompt automatically; if the user later denies access, subsequent calls reject with a clear error.

***

## Methods

### `startDeviceMotionUpdates(options): Promise<boolean>`

Begin streaming motion samples. Resolves with `true` once the stream is started.

```ts
startDeviceMotionUpdates(options: {
  onUpdate: (motion: HeadphoneDeviceMotion) => void
  onError?: (error: Error) => void
}): Promise<boolean>
```

| Option   | Type                                      | Required | Description                                             |
| -------- | ----------------------------------------- | -------- | ------------------------------------------------------- |
| onUpdate | `(motion: HeadphoneDeviceMotion) => void` | Yes      | Called for every motion sample.                         |
| onError  | `(error: Error) => void`                  | No       | Called if CoreMotion reports an error during streaming. |

Only one active subscription is supported at a time. Calling `startDeviceMotionUpdates` again replaces the previous handler.

### `stopDeviceMotionUpdates(): void`

Stop the current motion stream. Safe to call when no stream is active.

### `addListener(event, listener): void`

Subscribe to a connection event.

```ts
addListener(event: 'connect' | 'disconnect', listener: () => void): void
```

- `connect` fires when supported headphones become reachable.
- `disconnect` fires when they go away.

### `removeListener(event, listener): void`

Remove a previously registered listener. Pass the same function reference that was used with `addListener`.

***

## Data Types

```ts
type HeadphoneDeviceMotion = {
  timestamp: number          // seconds since device boot, monotonic
  attitude: {
    pitch: number            // radians
    roll: number             // radians
    yaw: number              // radians
    quaternion: { x: number; y: number; z: number; w: number }
  }
  rotationRate: { x: number; y: number; z: number }       // rad/s
  userAcceleration: { x: number; y: number; z: number }   // G
  gravity: { x: number; y: number; z: number }            // G
  sensorLocation: 'default' | 'leftHeadphone' | 'rightHeadphone'
  heading?: number                                        // degrees [0, 360)
  magneticField?: {
    field: { x: number; y: number; z: number }
    accuracy: 'uncalibrated' | 'low' | 'medium' | 'high'
  }
}
```

***

## Example

```ts
if (!HeadphoneMotionManager.isAvailable) {
  console.log("Headphone motion is not available on this device.")
} else {
  HeadphoneMotionManager.addListener('connect', () => {
    console.log("Headphones connected.")
  })
  HeadphoneMotionManager.addListener('disconnect', () => {
    console.log("Headphones disconnected.")
  })

  await HeadphoneMotionManager.startDeviceMotionUpdates({
    onUpdate: motion => {
      const yawDeg = motion.attitude.yaw * (180 / Math.PI)
      console.log(`yaw: ${yawDeg.toFixed(1)}°`)
    },
    onError: err => {
      console.error("motion error:", err.message)
    }
  })

  // Stop when finished:
  // HeadphoneMotionManager.stopDeviceMotionUpdates()
}
```

***

## Notes

- `Info.plist` must include `NSMotionUsageDescription`. Scripting already declares it.
- The first call to `startDeviceMotionUpdates` automatically triggers the system Motion & Fitness permission prompt. If the user denies it (now or later from Settings), `startDeviceMotionUpdates` rejects with a clear error so your script can surface a helpful message.



---
url: /guide/Utilities/HttpServer/HttpRequest.md
---

# HttpRequest

The `HttpRequest` class represents an HTTP request received by the server.
It encapsulates all request information, including path, method, headers, body, client address, and parsed parameters.
An instance of this class is provided as an argument to handler functions registered through `HttpServer.registerHandler()`.

***

## Overview

`HttpRequest` is typically used inside HTTP route handlers to:

- Access request path, method, headers, and body
- Read URL parameters and query parameters
- Parse form data (`application/x-www-form-urlencoded` or `multipart/form-data`)
- Verify authentication tokens or custom headers

***

## Properties

### `path: string`

The request path (excluding query parameters).

**Example:**

```ts
console.log(request.path)
// Output: "/api/user"
```

***

### `target: string`

The raw request-target from the request line, including the query string if present.
Unlike `path`, which is stripped of the query, `target` preserves the original target exactly as the client sent it.

**Example:**

```ts
// Request URL: /search?keyword=apple&page=2
console.log(request.target)
// Output: "/search?keyword=apple&page=2"

console.log(request.path)
// Output: "/search"
```

***

### `method: string`

The HTTP method of the request (e.g., `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`).

**Example:**

```ts
console.log(request.method)
// Output: "POST"
```

***

### `headers: Record<string, string>`

An object containing all HTTP request headers as key–value pairs.

**Example:**

```ts
console.log(request.headers["content-type"])
// Output: "application/json"
```

***

### `body: Data`

The request body as a `Data` object.
You can convert it to a string using methods such as `toRawString("utf-8")`.

**Example:**

```ts
const text = request.body.toRawString("utf-8")
console.log("Body content:", text)
```

***

### `address: string | null`

The IP address of the client that made the request.
If the address cannot be determined, this value is `null`.

**Example:**

```ts
console.log("Client address:", request.address)
```

***

### `params: Record<string, string>`

An object containing route parameters defined in the registered path.

**Example:**

```ts
// Route registration
server.registerHandler("/user/:id", (req) => {
  const userId = req.params["id"]
  return HttpResponse.ok(HttpResponseBody.text(`User ID: ${userId}`))
})
```

If the request path is `/user/123`, the response will be:

```
User ID: 123
```

***

### `queryParams: Array<{ key: string; value: string }>`

An array of query parameter key–value pairs extracted from the request URL.

**Example:**

```ts
// Request URL: /search?keyword=apple&page=2
for (const param of request.queryParams) {
  console.log(param.key, "=", param.value)
}
// Output:
// keyword = apple
// page = 2
```

***

## Methods

### `hasTokenForHeader(headerName: string, token: string): boolean`

Checks whether the specified header contains the given token value.
Commonly used for authentication headers such as `Authorization`.

**Parameters:**

| Name         | Type     | Description                                         |
| ------------ | -------- | --------------------------------------------------- |
| `headerName` | `string` | The name of the header to check (case-insensitive). |
| `token`      | `string` | The token string to match.                          |

**Returns:**

- `true` if the header contains the token
- `false` otherwise

**Example:**

```ts
if (!request.hasTokenForHeader("Authorization", "Bearer my-secret-token")) {
  return HttpResponse.unauthorized()
}
```

***

### `parseUrlencodedForm(): Array<{ key: string; value: string }>`

Parses the request body as `application/x-www-form-urlencoded` form data.
Typically used for HTML form submissions via POST.

**Returns:**
An array of key–value pairs representing form fields.

**Example:**

```ts
const form = request.parseUrlencodedForm()
for (const field of form) {
  console.log(field.key, "=", field.value)
}
```

If the body is:

```
username=thom&password=1234
```

then the output is:

```
username = thom
password = 1234
```

***

### `parseMultiPartFormData(): Array<{ name: string | null; filename: string | null; headers: Record<string, string>; data: Data }>`

Parses `multipart/form-data` requests, typically used for file uploads.

**Returns:**
An array of form parts, where each element contains:

| Property   | Type                     | Description                                                    |
| ---------- | ------------------------ | -------------------------------------------------------------- |
| `name`     | `string \| null`         | The field name.                                                |
| `filename` | `string \| null`         | The uploaded filename if the part is a file, otherwise `null`. |
| `headers`  | `Record<string, string>` | The part’s headers.                                            |
| `data`     | `Data`                   | The raw content of the field or file.                          |

**Example:**

```ts
const parts = request.parseMultiPartFormData()
for (const part of parts) {
  if (part.filename) {
    console.log("Uploaded file:", part.filename)
    FileManager.writeAsDataSync(Path.join(Script.directory, part.filename), part.data)
  } else {
    console.log("Field:", part.name, "=", part.data.toRawString("utf-8"))
  }
}
```

***

## Full Example

The example below shows how to read request data and respond accordingly:

```ts
server.registerHandler("/upload", (req) => {
  if (req.method === "POST") {
    const parts = req.parseMultiPartFormData()
    for (const part of parts) {
      if (part.filename) {
        console.log("Received file:", part.filename)
      } else {
        console.log("Field:", part.name)
      }
    }
    return HttpResponse.ok(HttpResponseBody.text("Upload successful"))
  } else {
    return HttpResponse.badRequest(HttpResponseBody.text("POST required"))
  }
})
```



---
url: /guide/Utilities/HttpServer/HttpResponse.md
---

# HttpResponse

The `HttpResponse` class represents an HTTP response object returned by the server to the client.
It defines the response’s status code, headers, and body, and provides convenient factory methods for creating common HTTP responses (e.g., `ok`, `notFound`, `internalServerError`).

`HttpResponse` is typically used together with `HttpResponseBody` to send text, HTML, binary data, or files back to the client.

***

## Overview

`HttpResponse` provides:

- Easy creation of standard HTTP responses (200, 404, 500, etc.)
- Support for custom status codes and reason phrases
- Ability to return text, binary, HTML, or file data
- Custom response headers
- Integration with `FileEntity` and `Data` for flexible body content

***

## Properties

### `statusCode: number`

The numeric HTTP status code.

**Example:**

```ts
const res = HttpResponse.ok(HttpResponseBody.text("OK"))
console.log(res.statusCode)
// Output: 200
```

***

### `reasonPhrase: string`

The reason phrase associated with the status code (e.g., `"OK"`, `"Not Found"`, `"Internal Server Error"`).

**Example:**

```ts
console.log(res.reasonPhrase)
// Output: "OK"
```

***

## Methods

### `headers(): Record<string, string>`

Returns the headers of the response as a key–value object.

**Example:**

```ts
const res = HttpResponse.ok(HttpResponseBody.text("Hello"))
console.log(res.headers())
```

***

### `static ok(body: HttpResponseBody): HttpResponse`

Creates a `200 OK` response.

**Parameters:**

| Name   | Type               | Description                                                               |
| ------ | ------------------ | ------------------------------------------------------------------------- |
| `body` | `HttpResponseBody` | The response body (use `HttpResponseBody.text()`, `data()`, or `html()`). |

**Example:**

```ts
return HttpResponse.ok(HttpResponseBody.text("Hello, world!"))
```

***

### `static created(): HttpResponse`

Returns a `201 Created` response, indicating that a new resource was successfully created.

**Example:**

```ts
return HttpResponse.created()
```

***

### `static accepted(): HttpResponse`

Returns a `202 Accepted` response, indicating the request was accepted but not yet processed.

**Example:**

```ts
return HttpResponse.accepted()
```

***

### `static movedPermanently(url: string): HttpResponse`

Returns a `301 Moved Permanently` redirect response.

**Parameters:**

| Name  | Type     | Description                    |
| ----- | -------- | ------------------------------ |
| `url` | `string` | The target URL to redirect to. |

**Example:**

```ts
return HttpResponse.movedPermanently("https://example.com/new-page")
```

***

### `static movedTemporarily(url: string): HttpResponse`

Returns a `302 Moved Temporarily` redirect response.

**Parameters:**

| Name  | Type     | Description                        |
| ----- | -------- | ---------------------------------- |
| `url` | `string` | The temporary redirect target URL. |

**Example:**

```ts
return HttpResponse.movedTemporarily("https://example.com/login")
```

***

### `static badRequest(body?: HttpResponseBody | null): HttpResponse`

Returns a `400 Bad Request` response, indicating invalid parameters or malformed input.

**Parameters:**

| Name   | Type                | Description                               |
| ------ | ------------------- | ----------------------------------------- |
| `body` | `HttpResponseBody?` | Optional error body describing the issue. |

**Example:**

```ts
return HttpResponse.badRequest(HttpResponseBody.text("Invalid parameters"))
```

***

### `static unauthorized(): HttpResponse`

Returns a `401 Unauthorized` response, indicating authentication is required.

**Example:**

```ts
return HttpResponse.unauthorized()
```

***

### `static forbidden(): HttpResponse`

Returns a `403 Forbidden` response, indicating the request is understood but not allowed.

**Example:**

```ts
return HttpResponse.forbidden()
```

***

### `static notFound(): HttpResponse`

Returns a `404 Not Found` response when the requested resource does not exist.

**Example:**

```ts
return HttpResponse.notFound()
```

***

### `static notAcceptable(): HttpResponse`

Returns a `406 Not Acceptable` response, indicating the request’s content type is unsupported.

**Example:**

```ts
return HttpResponse.notAcceptable()
```

***

### `static tooManyRequests(): HttpResponse`

Returns a `429 Too Many Requests` response, indicating the client is sending requests too quickly.

**Example:**

```ts
return HttpResponse.tooManyRequests()
```

***

### `static internalServerError(): HttpResponse`

Returns a `500 Internal Server Error` response, indicating an unexpected server error occurred.

**Example:**

```ts
return HttpResponse.internalServerError()
```

***

### `static raw(statusCode: number, phrase: string, options?: { headers?: Record<string, string>; body?: Data | FileEntity } | null): HttpResponse`

Creates a fully custom response with a specific status code, reason phrase, headers, and body.

**Parameters:**

| Name              | Type                     | Description                                   |
| ----------------- | ------------------------ | --------------------------------------------- |
| `statusCode`      | `number`                 | The HTTP status code.                         |
| `phrase`          | `string`                 | The reason phrase.                            |
| `options.headers` | `Record<string, string>` | Optional custom headers.                      |
| `options.body`    | `Data \| FileEntity`     | Optional response body (binary data or file). |

**Example:**

```ts
const file = FileEntity.openForReading(Path.join(Script.directory, "image.png"))
return HttpResponse.raw(200, "OK", {
  headers: { "Content-Type": "image/png" },
  body: file
})
```

***

## Usage with HttpResponseBody

### `HttpResponseBody.text(text: string)`

Returns a plain-text response body.

```ts
HttpResponse.ok(HttpResponseBody.text("Hello, world"))
```

### `HttpResponseBody.html(html: string)`

Returns an HTML response body.

```ts
HttpResponse.ok(HttpResponseBody.html("<h1>Welcome</h1>"))
```

### `HttpResponseBody.data(data: Data)`

Returns a binary data response body.

```ts
const data = Data.fromRawString("Binary content", "utf-8")
HttpResponse.ok(HttpResponseBody.data(data))
```

***

## Full Examples

### 1. Returning a JSON response

```ts
server.registerHandler("/user", (req) => {
  const json = JSON.stringify({ name: "Alice", age: 25 })
  const data = Data.fromRawString(json, "utf-8")
  return HttpResponse.ok(HttpResponseBody.data(data))
})
```

### 2. File download response

```ts
server.registerHandler("/download", (req) => {
  const file = FileEntity.openForReading(Path.join(Script.directory, "example.zip"))
  return HttpResponse.raw(200, "OK", {
    headers: { "Content-Type": "application/zip" },
    body: file
  })
})
```

### 3. Error handling response

```ts
server.registerHandler("/api", (req) => {
  if (req.method !== "POST") {
    return HttpResponse.badRequest(HttpResponseBody.text("POST method required"))
  }
  return HttpResponse.ok(HttpResponseBody.text("Success"))
})
```



---
url: /guide/Utilities/HttpServer/HttpResponseBody.md
---

# HttpResponseBody

The `HttpResponseBody` class represents the body content of an HTTP response.
It can contain text, HTML, binary data, or other forms of content.
`HttpResponseBody` is typically used with the `HttpResponse` class to return formatted data to the client.

***

## Overview

When building custom HTTP endpoints with `HttpServer`, the **response body** defines what content the client actually receives.
`HttpResponseBody` provides convenient static factory methods to construct various types of response content:

- Plain text (`text`)
- HTML content (`html`, `htmlBody`)
- Binary data (`data`)

***

## Common Use Cases

- Returning plain text (e.g., simple API messages)
- Returning HTML pages for browser display
- Returning binary data such as images, JSON files, or downloadable archives

***

## Static Methods

### `static text(text: string): HttpResponseBody`

Creates a plain-text response body.

**Parameters:**

| Name   | Type     | Description                                       |
| ------ | -------- | ------------------------------------------------- |
| `text` | `string` | The text content to include in the response body. |

**Example:**

```ts
const body = HttpResponseBody.text("Hello, world")
return HttpResponse.ok(body)
```

Response example:

```
HTTP/1.1 200 OK
Content-Type: text/plain

Hello, world
```

***

### `static data(data: Data): HttpResponseBody`

Creates a response body containing binary data.

**Parameters:**

| Name   | Type   | Description                                          |
| ------ | ------ | ---------------------------------------------------- |
| `data` | `Data` | The binary data object to send in the response body. |

**Example:**

```ts
const content = Data.fromRawString("Binary content", "utf-8")
return HttpResponse.ok(HttpResponseBody.data(content))
```

This is useful for sending files, images, or JSON payloads as binary data.

***

### `static html(html: string): HttpResponseBody`

Creates an HTML response body (standard HTML document).

**Parameters:**

| Name   | Type     | Description                                      |
| ------ | -------- | ------------------------------------------------ |
| `html` | `string` | The HTML markup to include in the response body. |

**Example:**

```ts
const html = `
<html>
  <head><title>Hello</title></head>
  <body><h1>Welcome to Scripting Server</h1></body>
</html>
`
return HttpResponse.ok(HttpResponseBody.html(html))
```

When accessed in a browser, the response is rendered as a web page.

***

### `static htmlBody(html: string): HttpResponseBody`

Creates an HTML **body-only** response.
Similar to `html()`, but may exclude full document structure (`<html>`, `<body>`, etc.).
This method is often used for partial HTML rendering or embedded HTML fragments.

**Parameters:**

| Name   | Type     | Description                       |
| ------ | -------- | --------------------------------- |
| `html` | `string` | The HTML snippet or body content. |

**Example:**

```ts
return HttpResponse.ok(HttpResponseBody.htmlBody("<h1>Inline HTML Body</h1>"))
```

***

## Example Use Cases

### 1. Return a plain-text response

```ts
server.registerHandler("/hello", (req) => {
  return HttpResponse.ok(HttpResponseBody.text("Hello from server"))
})
```

***

### 2. Return an HTML page

```ts
server.registerHandler("/", (req) => {
  const html = `
  <html>
    <head><title>Home</title></head>
    <body>
      <h1>Welcome</h1>
      <p>This is a simple Scripting HTTP server.</p>
    </body>
  </html>`
  return HttpResponse.ok(HttpResponseBody.html(html))
})
```

***

### 3. Return a binary file (e.g., an image)

```ts
server.registerHandler("/image", (req) => {
  const fileData = FileManager.readAsData(Path.join(Script.directory, "logo.png"))
  return HttpResponse.ok(HttpResponseBody.data(fileData))
})
```

***

### 4. Return a partial HTML fragment

```ts
server.registerHandler("/partial", (req) => {
  return HttpResponse.ok(HttpResponseBody.htmlBody("<div>Partial Content</div>"))
})
```

***

## Summary

| Method       | Description                  | Typical Use Case                      |
| ------------ | ---------------------------- | ------------------------------------- |
| `text()`     | Returns plain text content   | API responses, logs                   |
| `data()`     | Returns binary data          | Files, JSON, images                   |
| `html()`     | Returns a full HTML document | Web pages                             |
| `htmlBody()` | Returns an HTML fragment     | Template rendering or partial updates |



---
url: /guide/Utilities/HttpServer/HttpServer/index.md
---

# HttpServer

The `HttpServer` class provides a lightweight local HTTP server that can handle HTTP requests, serve static files, and manage WebSocket connections. It is commonly used for local debugging, communication between devices, and serving simple web APIs inside scripts.

***

## Overview

`HttpServer` supports:

- Handling custom HTTP routes with programmable handlers
- Serving static files or directories
- Managing WebSocket connections for real-time communication
- Listening on both IPv4 and IPv6
- Configurable ports (including automatic random ports)
- Server state tracking

***

## Properties

### `state: HttpServerState`

The current state of the server.

| State        | Description             |
| ------------ | ----------------------- |
| `"starting"` | The server is starting. |
| `"running"`  | The server is running.  |
| `"stopping"` | The server is stopping. |
| `"stopped"`  | The server is stopped.  |

***

### `port: number | null`

The port number the server is listening on.
If the server is not running, this value is `null`.

***

### `isIPv4: boolean`

Indicates whether the server is listening on an IPv4 address.
If `false`, the server may be using IPv6.

***

### `listenAddressIPv4: string | null`

The IPv4 address to listen on.
Only used when `forceIPv4` is set to `true`.

***

### `listenAddressIPv6: string | null`

The IPv6 address to listen on.
Only used when `forceIPv6` is set to `true`.

***

## Methods

### `registerHandler(path: string, handler: (request: HttpRequest) => HttpResponse): void`

> **Deprecated.** Prefer `registerAsyncHandler`. The sync entry point cannot `await` Keychain access, network IO, or file reads before responding, and is kept only for legacy scripts.

Registers a synchronous handler for a specific request path. The handler runs on the JavaScript main thread and must return an `HttpResponse` immediately.

**Parameters:**

| Name      | Type                                     | Description                                                             |
| --------- | ---------------------------------------- | ----------------------------------------------------------------------- |
| `path`    | `string`                                 | The route path (supports parameters, e.g., `/user/:id`).                |
| `handler` | `(request: HttpRequest) => HttpResponse` | The handler function that processes the request and returns a response. |

**Example:**

```ts
const server = new HttpServer()

server.registerHandler("/hello", (req) => {
  return HttpResponse.ok(HttpResponseBody.text("Hello, world!"))
})
```

***

### `registerAsyncHandler(path: string, handler: (request: HttpRequest) => Promise<HttpResponse>): void`

Registers an async handler. The handler may return a `Promise<HttpResponse>` and the server will wait for the promise to resolve before sending the reply. If the promise rejects, the server returns a 500 with the error message as the body.

**Parameters:**

| Name      | Type                                              | Description                                              |
| --------- | ------------------------------------------------- | -------------------------------------------------------- |
| `path`    | `string`                                          | The route path (supports parameters, e.g., `/user/:id`). |
| `handler` | `(request: HttpRequest) => Promise<HttpResponse>` | The async handler. Resolves with an `HttpResponse`.      |

**Example:**

```ts
const server = new HttpServer()

server.registerAsyncHandler("/slow", async (req) => {
  await new Promise(resolve => setTimeout(resolve, 200))
  return HttpResponse.ok(HttpResponseBody.text("slow ok"))
})
```

***

### `registerFile(path: string, filePath: string): void`

Registers a single static file for a specific path.

**Parameters:**

| Name       | Type     | Description                   |
| ---------- | -------- | ----------------------------- |
| `path`     | `string` | The HTTP request path.        |
| `filePath` | `string` | The local file path to serve. |

**Example:**

```ts
server.registerFile("/readme", Path.join(Script.directory, "README.md"))
```

Accessing `/readme` in the browser returns the file content.

***

### `registerFilesFromDirectory(path: string, directory: string, options?: { defaults?: string[] }): void`

Registers a directory of static files to serve.

**Parameters:**

| Name               | Type       | Description                                                                                    |
| ------------------ | ---------- | ---------------------------------------------------------------------------------------------- |
| `path`             | `string`   | The URL path template, e.g., `/static/:file`.                                                  |
| `directory`        | `string`   | The directory path to serve from.                                                              |
| `options.defaults` | `string[]` | Default files to serve if no filename is provided (default: `["index.html", "default.html"]`). |

**Example:**

```ts
server.registerFilesFromDirectory("/static/:file", Path.join(Script.directory, "html"), {
  defaults: ["index.html", "index.htm"]
})
```

When accessing `/static/`, the server automatically serves the default index file.

***

### `registerWebsocket(path: string, handlers: WebSocketHandlers): void`

Registers a WebSocket handler for the specified path.

**Parameters:**

| Name       | Type                | Description                            |
| ---------- | ------------------- | -------------------------------------- |
| `path`     | `string`            | The WebSocket endpoint path.           |
| `handlers` | `WebSocketHandlers` | The WebSocket event handler functions. |

**WebSocketHandlers type definition:**

```ts
interface WebSocketHandlers {
  onPong?: (session: WebSocketSession) => void
  onConnected?: (session: WebSocketSession) => void
  onDisconnected?: (session: WebSocketSession) => void
  handleText?: (session: WebSocketSession, text: string) => void
  handleBinary?: (session: WebSocketSession, data: Data) => void
}
```

**Example:**

```ts
const connectedSessions: WebSocketSession[] = []

server.registerWebsocket("/ws", {
  onConnected: (session) => {
    connectedSessions.push(session)
  },
  onDisconnected: (session) => {
    connectedSessions.splice(connectedSessions.indexOf(session), 1)
  },
  handleText: (session, text) => {
    session.writeText("Echo: " + text)
  }
})
```

***

### `registerMiddleware(handler: (request: HttpRequest) => Promise<HttpResponse | null | undefined>): void`

Registers an async middleware layer that runs before every route handler. Layers run in registration order. A layer may either:

- resolve with `null` / `undefined` to let the request pass through to the next layer or the route handler, or
- resolve with an `HttpResponse` to short-circuit the request — no subsequent middleware or route handler will run.

A rejection or thrown error becomes a `500` response.

**Parameters:**

| Name      | Type                                                               | Description                    |
| --------- | ------------------------------------------------------------------ | ------------------------------ |
| `handler` | `(req: HttpRequest) => Promise<HttpResponse \| null \| undefined>` | The async middleware function. |

**Example: simple auth gate**

```ts
server.registerMiddleware(async (req) => {
  if (!req.headers["x-auth"]) {
    return HttpResponse.unauthorized(HttpResponseBody.text("missing token"))
  }
  return null
})
```

***

### `setNotFoundHandler(handler: (request: HttpRequest) => Promise<HttpResponse>): void`

Sets the async handler invoked when no route matches the incoming request. The handler must resolve with an `HttpResponse`. Calling this multiple times replaces the previous handler. Rejection or throw becomes a `500`.

**Parameters:**

| Name      | Type                                          | Description            |
| --------- | --------------------------------------------- | ---------------------- |
| `handler` | `(req: HttpRequest) => Promise<HttpResponse>` | The async 404 handler. |

**Example:**

```ts
server.setNotFoundHandler(async (req) => {
  return HttpResponse.notFound(HttpResponseBody.text(`No route: ${req.path}`))
})
```

***

### `start(options?: { port?, forceIPv4?, tls? }): string | null`

Starts the HTTP server. Returns `null` on success, or an error message string on failure (configuration error, port in use, etc.).

**Parameters:**

| Name                     | Type             | Description                                                                                                                                            |
| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `options.port`           | `number`         | The port to listen on (default: `8080`). If `0` is specified, a random available port is chosen and exposed via `server.port` after start.             |
| `options.forceIPv4`      | `boolean`        | Whether to force IPv4 listening (default: `false`).                                                                                                    |
| `options.tls.p12`        | `string \| Data` | PKCS#12 identity. Either an absolute file path (`string`) or the raw P12 bytes (`Data`). The `Data` form is convenient when the P12 lives in Keychain. |
| `options.tls.password`   | `string`         | Password used to decrypt the P12.                                                                                                                      |
| `options.tls.minVersion` | `"1.2" \| "1.3"` | Minimum TLS protocol version (default: `"1.2"`). TLSv1.0 / 1.1 are not supported — Apple deprecated them in macOS 12 / iOS 15.                         |
| `options.tls.maxVersion` | `"1.2" \| "1.3"` | Maximum TLS protocol version. Default is unset (no upper bound). Pin to `"1.3"` on both `minVersion` and `maxVersion` to enforce TLSv1.3-only.         |

**HTTP example:**

```ts
const error = server.start({ port: 8080 })
if (error) {
  console.error("Failed to start:", error)
} else {
  console.log("Server running on port:", server.port)
}
```

**HTTPS from a P12 file:**

```ts
const error = server.start({
  port: 8443,
  tls: {
    p12: Path.join(Script.directory, "server.p12"),
    password: "your-p12-password",
  },
})
```

**HTTPS from P12 bytes (Keychain pipeline) + TLS 1.3 only:**

```ts
// Keychain APIs are synchronous and return null when the key is missing.
const p12Bytes = Keychain.getData("server.p12")
if (!p12Bytes) {
  throw new Error("server.p12 is not stored in Keychain")
}
server.start({
  port: 8443,
  tls: {
    p12: p12Bytes,
    password: "your-p12-password",
    minVersion: "1.3",
    maxVersion: "1.3",
  },
})
```

To generate a self-signed P12 for local testing:

```sh
openssl req -x509 -newkey rsa:2048 \
    -keyout localhost.key -out localhost.crt \
    -days 3650 -nodes -subj "/CN=localhost"
openssl pkcs12 -export -out localhost.p12 \
    -inkey localhost.key -in localhost.crt \
    -name "scripting-test" -password pass:yourpassword \
    -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES
```

***

### `stop(): void`

Stops the HTTP server and releases its resources.

**Example:**

```ts
server.stop()
console.log("Server stopped")
```

***

## Type Definitions

### `HttpServerState`

```ts
type HttpServerState = "starting" | "running" | "stopping" | "stopped"
```

***

### `WebSocketSession`

Represents a live WebSocket connection.

**Methods:**

| Method                    | Description                           |
| ------------------------- | ------------------------------------- |
| `writeText(text: string)` | Sends a text message to the client.   |
| `writeData(data: Data)`   | Sends a binary message to the client. |
| `close()`                 | Closes the connection.                |

***

## Full Example

Below is a complete example of a working HTTP + WebSocket server:

```ts
const server = new HttpServer()

// Register a simple HTTP route
server.registerHandler("/api/hello", (req) => {
  return HttpResponse.ok(HttpResponseBody.text("Hello from Scripting Server"))
})

// Serve static files from a directory
server.registerFilesFromDirectory("/public/:file", Path.join(Script.directory, "html"))

// WebSocket chat example
server.registerWebsocket("/chat", {
  onConnected: (session) => {
    console.log("Client connected")
    session.writeText("Welcome to the chat")
  },
  handleText: (session, text) => {
    console.log("Received:", text)
    session.writeText("You said: " + text)
  }
})

// Start the server
const error = server.start({ port: 8080 })
if (error) {
  console.error("Server failed to start:", error)
} else {
  console.log("HTTP Server started on port:", server.port)
}
```



---
url: /guide/Utilities/HttpServer/HttpServer/index_example.md
---

# Example

```tsx
/**
 * HttpServer 端到端冒烟 demo
 *
 * 启动后会监听一个随机端口(`server.start({ port: 0 })`),并把多种 handler
 * 注册上去:
 *   - 同步 handler GET /sync (registerHandler,已 @deprecated)
 *   - 异步 handler GET /slow (服务端 sleep 200ms 再返回,registerAsyncHandler)
 *   - 路径变量 GET /user/:id (验证 request.params 的 key 没有 ":" 前缀)
 *   - queryParams GET /query?a=1&b=2
 *   - 静态文件 GET /readme (registerFile)
 *   - 目录服务 GET /static/:path (registerFilesFromDirectory)
 *   - 目录浏览 GET /browse/:path (registerDirectoryBrowser)
 *   - WebSocket /ws (echo)
 *   - async middleware:挂在所有路由前;请求带 X-Allow header 才放行,否则 401
 *   - 自定义 404 (setNotFoundHandler):把请求路径回显到 body
 *
 * UI 上有 "Run tests" 按钮:启动后在客户端 fetch 一遍每个 endpoint,
 * 并把每行 PASS/FAIL 输出到列表里。还有 "Stop server" 收尾。
 *
 * HTTPS sample:
 *   把下方 `enableHttps` 改成 true 并在 Script.directory 下放一个名为
 *   "server.p12" 的自签名证书(密码改成 P12_PASSWORD 常量),server 会以
 *   https 启动。`fetch` 自签名证书校验失败 — 验证手段是手动 curl -k 试。
 *   P12 也可以直接传 bytes:`tls.p12 = Keychain.getData("server.p12")`
 *   (Keychain 接口是同步的,直接返回 Data | null),接同一个 start API。
 */

import {
  Button, HStack, List, Navigation, NavigationStack, Script,
  Section, Spacer, Text, useState, VStack, Path,
  fetch,
} from "scripting"

const P12_PASSWORD = "swiftertest"
const enableHttps = false

type TestResult = {
  name: string
  pass: boolean
  detail: string
}

// Module-level singleton: 避免 useState lazy initializer 在每次 re-render
// 重跑,旧 HttpServer 被 GC 触发 deinit -> stop 的不可见路径
const server = new HttpServer()

function View() {
  const [port, setPort] = useState<number | null>(null)
  const [running, setRunning] = useState(false)
  const [results, setResults] = useState<TestResult[]>([])
  const [busy, setBusy] = useState(false)

  // 拼一个本地目录给 registerFile / registerFilesFromDirectory / registerDirectoryBrowser
  // 用 Script.directory 下临时建几个文件
  async function prepareFixtures(): Promise<string> {
    const dir = Path.join(Script.directory, "http_demo_root")
    await FileManager.createDirectory(dir, true)

    const indexHTML = Path.join(dir, "index.html")
    if (!FileManager.existsSync(indexHTML)) {
      await FileManager.writeAsString(indexHTML, "<h1>index ok</h1>")
    }
    const note = Path.join(dir, "note.txt")
    if (!FileManager.existsSync(note)) {
      await FileManager.writeAsString(note, "hello from note")
    }
    const subdir = Path.join(dir, "sub")
    await FileManager.createDirectory(subdir, true)
    const subFile = Path.join(subdir, "inside.txt")
    if (!FileManager.existsSync(subFile)) {
      await FileManager.writeAsString(subFile, "deep file")
    }
    return dir
  }

  async function startServer() {
    if (running) return
    setBusy(true)
    try {
      const fixtureDir = await prepareFixtures()

      server.registerHandler("/sync", _ => {
        return HttpResponse.ok(HttpResponseBody.text("sync ok"))
      })

      // 异步 handler:走 registerAsyncHandler,JS 端可以返回 Promise,
      // server 在 setAsync 路径里 await 之后再发响应
      server.registerAsyncHandler("/slow", async _ => {
        await new Promise(resolve => setTimeout(resolve, 200))
        return HttpResponse.ok(HttpResponseBody.text("slow ok"))
      })

      server.registerHandler("/user/:id", req => {
        const id = req.params["id"] ?? "<missing>"
        return HttpResponse.ok(HttpResponseBody.text(`user id = ${id}`))
      })

      server.registerHandler("/query", req => {
        const dump = req.queryParams.map(q => `${q.key}=${q.value}`).join("&")
        return HttpResponse.ok(HttpResponseBody.text(dump))
      })

      server.registerFile("/readme", Path.join(fixtureDir, "note.txt"))

      server.registerFilesFromDirectory("/static/:path", fixtureDir, {
        defaults: ["index.html"],
      })

      server.registerDirectoryBrowser("/browse/:path", fixtureDir)

      server.registerWebsocket("/ws", {
        handleText: (session, text) => {
          session.writeText(`echo:${text}`)
        },
      })

      // /protected 由 async middleware 守卫:必须带 x-auth header 才放行
      server.registerAsyncHandler("/protected", async _ => {
        return HttpResponse.ok(HttpResponseBody.text("welcome"))
      })

      // async middleware: 只对 /protected 生效,其它路由放行
      server.registerMiddleware(async req => {
        if (req.path === "/protected" && !req.headers["x-auth"]) {
          return HttpResponse.unauthorized(HttpResponseBody.text("missing x-auth"))
        }
        return null
      })

      // 自定义 async 404,把请求路径回显到 body
      server.setNotFoundHandler(async req => {
        return HttpResponse.notFound(HttpResponseBody.text(`no route: ${req.path}`))
      })

      const startOptions: any = { port: 0 }
      if (enableHttps) {
        startOptions.port = 0
        startOptions.tls = {
          p12: Path.join(Script.directory, "server.p12"),
          password: P12_PASSWORD,
        }
      }
      const err = server.start(startOptions)
      if (err) {
        console.error("server start failed:", err)
        Dialog.alert({ title: "Start failed", message: err })
        return
      }
      setPort(server.port)
      setRunning(true)
      console.log("server listening on port", server.port)
    } catch (e) {
      console.error(e)
      Dialog.alert({ title: "Start error", message: String(e) })
    } finally {
      setBusy(false)
    }
  }

  function stopServer() {
    server.stop()
    setRunning(false)
    setPort(null)
    setResults([])
  }

  async function runTests() {
    if (!running || port == null) return
    setBusy(true)
    const collected: TestResult[] = []
    const scheme = enableHttps ? "https" : "http"
    const base = `${scheme}://127.0.0.1:${port}`

    async function check(name: string, req: () => Promise<{ status: number; text: string }>, expect: (r: { status: number; text: string }) => string | null) {
      try {
        const r = await req()
        const failReason = expect(r)
        collected.push({
          name,
          pass: failReason == null,
          detail: failReason ?? `${r.status} ${r.text.slice(0, 80)}`,
        })
      } catch (e) {
        collected.push({ name, pass: false, detail: `threw: ${String(e)}` })
      }
    }

    async function fetchText(url: string, headers?: Record<string, string>): Promise<{ status: number; text: string }> {
      const resp = await fetch(url, headers ? { headers } : undefined)
      const text = await resp.text()
      return { status: resp.status, text }
    }

    await check("GET /sync", () => fetchText(`${base}/sync`), r =>
      r.status === 200 && r.text === "sync ok" ? null : `expected 200 "sync ok"`)

    await check("GET /slow (async, ~200ms)", () => fetchText(`${base}/slow`), r =>
      r.status === 200 && r.text === "slow ok" ? null : `expected 200 "slow ok"`)

    await check("GET /user/:id (params key without colon)", () => fetchText(`${base}/user/42`), r =>
      r.status === 200 && r.text === "user id = 42" ? null : `expected "user id = 42"`)

    await check("GET /query?a=1&b=2", () => fetchText(`${base}/query?a=1&b=2`), r =>
      r.status === 200 && r.text === "a=1&b=2" ? null : `expected "a=1&b=2"`)

    await check("GET /readme (registerFile)", () => fetchText(`${base}/readme`), r =>
      r.status === 200 && r.text === "hello from note" ? null : `expected note content`)

    await check("GET /static/ (default index.html)", () => fetchText(`${base}/static/`), r =>
      r.status === 200 && r.text.includes("index ok") ? null : `expected index.html content`)

    await check("GET /static/note.txt", () => fetchText(`${base}/static/note.txt`), r =>
      r.status === 200 && r.text === "hello from note" ? null : `expected note content`)

    // 关键回归:之前 fopen 在目录上不会失败,导致命中目录返回 200 + 空 body。
    // 修复后命中目录(/static/sub)应该是 404
    await check("GET /static/sub (directory hit -> 404)", () => fetchText(`${base}/static/sub`), r =>
      r.status === 404 ? null : `expected 404, got ${r.status} "${r.text}"`)

    await check("GET /browse/ (directoryBrowser root list)", () => fetchText(`${base}/browse/`), r =>
      r.status === 200 && r.text.toLowerCase().includes("note.txt") ? null : `expected listing with note.txt`)

    await check("GET /browse/note.txt (directoryBrowser file)", () => fetchText(`${base}/browse/note.txt`), r =>
      r.status === 200 && r.text === "hello from note" ? null : `expected note content`)

    // async middleware:无 x-auth header 时被 401 截胡
    await check("GET /protected without x-auth (middleware 401)", () => fetchText(`${base}/protected`), r =>
      r.status === 401 && r.text === "missing x-auth" ? null : `expected 401 "missing x-auth", got ${r.status} "${r.text}"`)

    // 带 x-auth header 时 middleware 放行,/protected handler 返回 welcome
    await check("GET /protected with x-auth (middleware pass-through)", () => fetchText(`${base}/protected`, { "x-auth": "token" }), r =>
      r.status === 200 && r.text === "welcome" ? null : `expected 200 "welcome", got ${r.status} "${r.text}"`)

    // 自定义 404: setNotFoundHandler 把请求路径回显到 body
    await check("GET /nope (setNotFoundHandler echoes path)", () => fetchText(`${base}/nope`), r =>
      r.status === 404 && r.text === "no route: /nope" ? null : `expected 404 "no route: /nope", got ${r.status} "${r.text}"`)

    // WebSocket echo:用 WebSocket 客户端连一下
    // 注:WebSocket.onmessage 直接收 string | Data,不是 event 对象
    await check("WebSocket /ws echo", async () => {
      const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`)
      const received = await new Promise<string>((resolve, reject) => {
        const t = setTimeout(() => reject(new Error("ws timeout")), 3000)
        ws.onopen = () => ws.send("ping")
        ws.onmessage = msg => {
          clearTimeout(t)
          const text = typeof msg === "string" ? msg : (msg.toRawString() ?? "")
          resolve(text)
        }
        ws.onerror = e => {
          clearTimeout(t)
          reject(e)
        }
      })
      ws.close()
      return { status: 200, text: received }
    }, r => r.text === "echo:ping" ? null : `expected "echo:ping", got "${r.text}"`)

    setResults(collected)
    setBusy(false)
    console.log("tests done", collected.filter(r => r.pass).length, "/", collected.length, "passed")
  }

  // 注:不能用 useEffect cleanup 来 stop server —— Scripting 的 hook
  // 在 setState 触发 re-render 时会重跑 cleanup,会把 server 关掉。
  // 改成 Close 按钮显式 stop + dismiss。
  const dismiss = Navigation.useDismiss()
  function closeAndStop() {
    server.stop()
    dismiss()
  }

  return <NavigationStack>
    <List
      navigationTitle="HttpServer demo"
      toolbar={{
        topBarTrailing: <Button title="Close" action={closeAndStop} />,
      }}
    >
      <Section title="Server">
        <HStack>
          <Text>State</Text>
          <Spacer />
          <Text>{server.state}{port != null ? ` :${port}` : ""}</Text>
        </HStack>
        {/* 注:多个 Button 在 List 的 Section 里要垂直直接排,不要塞在
            HStack 里 —— SwiftUI List 行里两个 Button 排一起,点击事件
            会扩散到整行,两个 Button 都被命中,Start/Stop 误触跑测试。 */}
        {running
          ? <Button title="Stop server" disabled={busy} action={stopServer} />
          : <Button title="Start server" disabled={busy} action={startServer} />}
        <Button title="Run tests" disabled={!running || busy} action={runTests} />
      </Section>
      {results.length > 0 ? <Section title={`Results (${results.filter(r => r.pass).length}/${results.length})`}>
        {results.map((r, i) =>
          <VStack key={String(i)} alignment="leading">
            <HStack>
              <Text foregroundStyle={r.pass ? "green" : "red"}>{r.pass ? "PASS" : "FAIL"}</Text>
              <Text>{r.name}</Text>
            </HStack>
            <Text font="caption" foregroundStyle="secondaryLabel">{r.detail}</Text>
          </VStack>
        )}
      </Section> : null}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present(<View />)
  Script.exit()
}

run()

```



---
url: /guide/Utilities/HttpServer/WebSocketSession.md
---

# WebSocketSession

The `WebSocketSession` class represents an active WebSocket connection session.
It is created automatically when a client connects to a WebSocket endpoint registered via `HttpServer.registerWebsocket()` and enables **bi-directional real-time communication** between the server and the client.

***

## Overview

Through a `WebSocketSession`, you can:

- Receive text or binary data from clients
- Send messages (text or binary) back to clients
- Handle connection and disconnection events
- Close the WebSocket connection gracefully

Each `WebSocketSession` instance corresponds to one client connection and can be managed individually or stored for broadcasting messages.

***

## Use Cases

- Real-time chat or collaboration systems
- Live notifications or dashboard updates
- Device control or IoT message channels
- Local WebSocket servers communicating with other devices or web clients

***

## Methods

### `writeText(text: string): void`

Sends a text message to the connected client.

**Parameters:**

| Name   | Type     | Description               |
| ------ | -------- | ------------------------- |
| `text` | `string` | The text content to send. |

**Example:**

```ts
server.registerWebsocket("/chat", {
  onConnected: (session) => {
    session.writeText("Welcome to the chat room!")
  },
  handleText: (session, text) => {
    console.log("Client says:", text)
    session.writeText("You said: " + text)
  }
})
```

***

### `writeData(data: Data): void`

Sends a binary message to the connected client.

**Parameters:**

| Name   | Type   | Description              |
| ------ | ------ | ------------------------ |
| `data` | `Data` | The binary data to send. |

**Example:**

```ts
server.registerWebsocket("/binary", {
  onConnected: (session) => {
    const msg = Data.fromRawString("Binary hello", "utf-8")
    session.writeData(msg)
  }
})
```

***

### `close(): void`

Closes the WebSocket session.
After calling this method, the connection is terminated and no further messages will be received or sent.

**Example:**

```ts
server.registerWebsocket("/ws", {
  handleText: (session, text) => {
    if (text === "bye") {
      session.writeText("Goodbye!")
      session.close()
    }
  }
})
```

***

## Integration with `HttpServer.registerWebsocket()`

`WebSocketSession` instances are passed into the event handlers defined in `registerWebsocket()`.

### Example

```ts
const connectedSessions: WebSocketSession[] = []

server.registerWebsocket("/ws", {
  onConnected: (session) => {
    connectedSessions.push(session)
    console.log("Client connected")
    session.writeText("Connection established!")
  },
  handleText: (session, text) => {
    console.log("Received:", text)
    // Broadcast message to all clients
    for (const s of connectedSessions) {
      s.writeText("Broadcast: " + text)
    }
  },
  handleBinary: (session, data) => {
    console.log("Received binary data:", data.length)
  },
  onDisconnected: (session) => {
    const index = connectedSessions.indexOf(session)
    if (index !== -1) connectedSessions.splice(index, 1)
    console.log("Client disconnected")
  }
})
```

***

## Common WebSocket Event Handlers

These handlers are defined in `HttpServer.registerWebsocket()` and receive `WebSocketSession` objects.

| Handler          | Trigger                              | Parameters                                  | Description                                     |
| ---------------- | ------------------------------------ | ------------------------------------------- | ----------------------------------------------- |
| `onConnected`    | When a new connection is established | `(session: WebSocketSession)`               | Called once when a client connects.             |
| `onDisconnected` | When the client disconnects          | `(session: WebSocketSession)`               | Called when the connection is closed.           |
| `onPong`         | When a ping/pong frame is received   | `(session: WebSocketSession)`               | Used for heartbeat or connection health checks. |
| `handleText`     | When a text message is received      | `(session: WebSocketSession, text: string)` | Handles text-based messages.                    |
| `handleBinary`   | When a binary message is received    | `(session: WebSocketSession, data: Data)`   | Handles binary data messages.                   |

***

## Example: Simple Real-Time Chat Server

```ts
const sessions: WebSocketSession[] = []

server.registerWebsocket("/chat", {
  onConnected: (session) => {
    sessions.push(session)
    session.writeText("Welcome! There are " + sessions.length + " users online.")
  },
  handleText: (session, text) => {
    for (const s of sessions) {
      s.writeText(text) // Broadcast message to all connected clients
    }
  },
  onDisconnected: (session) => {
    const index = sessions.indexOf(session)
    if (index !== -1) sessions.splice(index, 1)
  }
})
```

**Client example (JavaScript):**

```js
const ws = new WebSocket("ws://localhost:8080/chat")
ws.onmessage = e => console.log("Server:", e.data)
ws.send("Hello everyone!")
```

***

## Type Definition

```ts
class WebSocketSession {
  writeText(text: string): void
  writeData(data: Data): void
  close(): void
}
```

***

## Summary

| Method        | Description                        | Typical Use Case                   |
| ------------- | ---------------------------------- | ---------------------------------- |
| `writeText()` | Sends a text message to the client | Chat, notifications, logs          |
| `writeData()` | Sends binary data to the client    | File transfer, streaming, IoT data |
| `close()`     | Closes the WebSocket connection    | Graceful shutdown or cleanup       |



---
url: /guide/Utilities/ItemProvider.md
---

# ItemProvider

`ItemProvider` represents a **deferred data provider** used to access content such as files, images, text, or URLs in a controlled and secure way.
It is commonly used in scenarios like drag and drop, file importing, and content selection from Photos or Files.

An `ItemProvider` does not store the data itself. Instead, it describes **how and under what constraints the data can be accessed**.

***

## Core Concepts

- `ItemProvider` describes capabilities, not concrete data
- Data loading is always subject to system security restrictions
- File-based resources can only be accessed within a limited, controlled scope
- Whether a file can be accessed in place is determined by the underlying system

***

## Properties

### registeredTypes

```ts
readonly registeredTypes: UTType[]
```

Represents all types that the item provider can supply at a semantic level.

- Includes both concrete types and inferred parent types
- Useful for high-level content classification or debugging
- Does not guarantee that a concrete file representation exists

***

### registeredInPlaceTypes

```ts
readonly registeredInPlaceTypes: UTType[]
```

Represents the set of types that support open-in-place access.

- Typically applies to large resources such as videos, audio files, or documents
- Actual in-place access is determined at load time

***

## Capability Checks

### hasItemConforming

```ts
hasItemConforming(type: UTType): boolean
```

Checks whether the content semantically conforms to the specified type.

- Performs a broad, semantic check
- Considers UTType inheritance
- Suitable for branching logic and content classification

***

### hasRepresentationConforming

```ts
hasRepresentationConforming(type: UTType): boolean
```

Checks whether a concrete, loadable representation exists for the specified type.

- Performs a strict check
- Suitable for file processing and format-specific workflows

***

### hasInPlaceRepresentationConforming

```ts
hasInPlaceRepresentationConforming(type: UTType): boolean
```

Checks whether a representation supporting open-in-place access exists.

- Commonly used to choose loading strategies for large files

***

## Object Loading Capabilities

### canLoadUIImage

```ts
canLoadUIImage(): boolean
```

Indicates whether the content can be loaded as a `UIImage`.

- Intended for UI display
- Does not guarantee preservation of original format or metadata

***

### canLoadLivePhoto

```ts
canLoadLivePhoto(): boolean
```

Indicates whether the content can be loaded as a `LivePhoto`.

- Used to distinguish Live Photos from static images
- When true, `loadLivePhoto` can be called

***

## Loading Methods

### loadUIImage

```ts
loadUIImage(): Promise<UIImage | null>
```

Loads a `UIImage` object.

- Suitable for lightweight display
- Not intended for file-level processing or asset preservation

***

### loadLivePhoto

```ts
loadLivePhoto(): Promise<LivePhoto | null>
```

Loads a `LivePhoto` object.

- Includes both the still image and paired video
- Suitable for display, saving, or further processing

***

### loadURL

```ts
loadURL(): Promise<string | null>
```

Loads a URL and returns it as a string.

- May represent a web URL or a file URL

***

### loadText

```ts
loadText(): Promise<string | null>
```

Loads plain text content.

- Supports plain text
- Rich text is automatically converted to plain text

***

### loadData

```ts
loadData(type: UTType): Promise<Data | null>
```

Loads raw binary data for the specified type.

- The entire data payload is loaded into memory
- Suitable for JSON, configuration files, or small resources
- Not recommended for large files such as video or audio

***

## File Path Loading and Security Scope

Access to file paths is subject to strict security rules.
All file access must occur within a limited callback scope provided by the API.

***

### loadFilePath

```ts
loadFilePath(type: UTType): Promise<string | null>
```

Loads a file path for the specified type. If the item provider can load data as the specified type, this file will be copied to the app group's temporary directory and the file path will be returned, otherwise null will be returned. You should delete the file when it is no longer needed.

Example:

```ts
const filePath = provider.loadFilePath("public.movie")
```

***

## Creating an ItemProvider

### fromUIImage

```ts
ItemProvider.fromUIImage(image: UIImage): ItemProvider
```

Creates an `ItemProvider` from a `UIImage`.

- Provides static image capabilities only
- Does not include Live Photo or original asset information

***

### fromText

```ts
ItemProvider.fromText(text: string): ItemProvider
```

Creates an `ItemProvider` from a text string.

***

### fromURL

```ts
ItemProvider.fromURL(url: string): ItemProvider | null
```

Creates an `ItemProvider` from a URL string.

- Returns `null` if the URL is invalid
- Supports both web URLs and file URLs

***

### fromFilePath

```ts
ItemProvider.fromFilePath(path: string): ItemProvider
```

Creates an `ItemProvider` from a file path.

- Preserves the original file
- Suitable for videos, audio, and documents
- Supports open-in-place capability checks

***

## Usage Guidelines

- Use `hasItemConforming` to determine content categories
- Use object loading methods for UI display
- Use file path loading methods for large resources
- Always access files only within the provided callback scope
- Never defer access to security-scoped files outside the callback



---
url: /guide/Utilities/JWT.md
---

# JWT

The `JWT` class provides synchronous APIs to sign, verify, and decode JSON Web Tokens.

***

## Constructor

```ts
new JWT(options?: {
  algorithm?: JWTAlgorithm
  secret?: string | Data
  privateKey?: string | Data
  publicKey?: string | Data
  passphrase?: string
  kid?: string
})
```

### Parameters

| Name       | Type           | Required | Description                                                      |
| ---------- | -------------- | -------- | ---------------------------------------------------------------- |
| algorithm  | JWTAlgorithm   | No       | Default signing algorithm. Defaults to `HS256`.                  |
| secret     | string \| Data | No       | Shared secret used by `HS256` / `HS384` / `HS512`.               |
| privateKey | string \| Data | No       | Private key used by `RS*` / `PS*` / `ES*` / `EdDSA` signing.     |
| publicKey  | string \| Data | No       | Public key used by `RS*` / `PS*` / `ES*` / `EdDSA` verification. |
| passphrase | string         | No       | Optional passphrase field for key workflows.                     |
| kid        | string         | No       | Optional key ID written into JWT header.                         |

### Supported Algorithms

- HMAC: `HS256`, `HS384`, `HS512`
- RSA PKCS#1 v1.5: `RS256`, `RS384`, `RS512`
- RSA-PSS: `PS256`, `PS384`, `PS512`
- ECDSA: `ES256`, `ES384`, `ES512`
- EdDSA: `EdDSA` (Ed25519)

***

## Methods

### `sign(payload, options?): string`

Creates a JWT string synchronously.

```ts
sign(payload: Record<string, any>, options?: {
  algorithm?: JWTAlgorithm
  header?: Record<string, any>
  issuer?: string
  subject?: string
  audience?: string | string[]
  jwtId?: string
  nonce?: string
  notBefore?: number | string
  expiresIn?: number | string
  issuedAt?: number | string
  kid?: string
}): string
```

### `verify(token, options?): { header; payload }`

Verifies signature and standard claims synchronously. Throws on failure.

```ts
verify(token: string, options?: {
  algorithm?: JWTAlgorithm | JWTAlgorithm[]
  issuer?: string | string[]
  subject?: string
  audience?: string | string[]
  jwtId?: string
  nonce?: string
  clockTolerance?: number
  currentDate?: number | Date
}): {
  header: Record<string, any>
  payload: Record<string, any>
}
```

### `decode(token): { header; payload; signature; signingInput }`

Decodes JWT without signature verification.

```ts
decode(token: string): {
  header: Record<string, any>
  payload: Record<string, any>
  signature: string
  signingInput: string
}
```

***

## Example

```ts
const jwt = new JWT({
  algorithm: "HS256",
  secret: "my-secret",
  kid: "k1"
})

const token = jwt.sign(
  { userId: "u_123", role: "admin" },
  {
    issuer: "Scripting",
    audience: ["app", "web"],
    expiresIn: 3600
  }
)

const verified = jwt.verify(token, {
  issuer: "Scripting",
  audience: "app",
  algorithm: "HS256"
})

console.log(verified.header.alg)
console.log(verified.payload.userId)
```

***

## Error Handling

All methods are synchronous. If validation or cryptographic operations fail, `JWT` throws an `Error`.



---
url: /guide/Utilities/OAuth2.md
---

# OAuth2

The `OAuth2` class provides a robust interface for managing OAuth 2.0 authorization flows in Scripting. It supports standard authorization code flows, PKCE (Proof Key for Code Exchange), access token renewal, and customizable token handling.

***

## Constructor

```ts
new OAuth2(options: {
  consumerKey: string
  consumerSecret: string
  authorizeUrl: string
  accessTokenUrl?: string
  responseType: string
  contentType?: string
})
```

### Parameters

| Name           | Type   | Required | Description                                                                         |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| consumerKey    | string | Yes      | The application's client ID or consumer key.                                        |
| consumerSecret | string | Yes      | The application's client secret.                                                    |
| authorizeUrl   | string | Yes      | The URL where the user will be redirected for authorization.                        |
| accessTokenUrl | string | No       | The endpoint to request the access token. If omitted, `authorizeUrl` is used.       |
| responseType   | string | Yes      | Typically `"code"` for the Authorization Code Grant flow.                           |
| contentType    | string | No       | Content type for token requests. Defaults to `"application/x-www-form-urlencoded"`. |

### Throws

- Error if the configuration is invalid or instantiation fails.

***

## Properties

### `accessTokenBasicAuthentification: boolean`

Enable this to use HTTP Basic authentication when exchanging the authorization code for an access token. Default is `false`.

***

### `allowMissingStateCheck: boolean`

Disables CSRF protection based on state parameter validation. **Use with caution.** Default is `false`.

***

### `encodeCallbackURL: boolean`

Encodes the callback URL when generating the authorization URL. Required by some providers. Default is `true`.

***

### `encodeCallbackURLQuery: boolean`

Controls whether the entire query string is encoded. Some services (e.g., Imgur) require this to be `false`. Default is `true`.

***

## Methods

### `authorize(options): Promise<OAuthCredential>`

Initiates the OAuth2 authorization flow, opening a browser window for the user to log in and grant permissions.

```ts
authorize(options: {
  callbackURL?: string
  scope: string
  state: string
  parameters?: Record<string, any>
  headers?: Record<string, string>
} & ({
  codeVerifier: string
  codeChallenge: string
  codeChallengeMethod: string
} | {
  codeVerifier?: never
  codeChallenge?: never
  codeChallengeMethod?: never
})): Promise<OAuthCredential>
```

#### Parameters

| Name                | Type                    | Required    | Description                                                                                 |
| ------------------- | ----------------------- | ----------- | ------------------------------------------------------------------------------------------- |
| callbackURL         | string                  | No          | Custom redirect URI. Default is `scripting://oauth_callback/{current_script_encoded_name}`. |
| scope               | string                  | Yes         | Space-separated list of requested scopes.                                                   |
| state               | string                  | Yes         | A unique string used to prevent CSRF attacks.                                               |
| parameters          | Record\<string, any>    | No          | Extra query parameters to send in the authorization request.                                |
| headers             | Record\<string, string> | No          | Extra headers to send in the request.                                                       |
| codeVerifier        | string                  | Conditional | Raw random string used in PKCE flow.                                                        |
| codeChallenge       | string                  | Conditional | Hashed version of the code verifier.                                                        |
| codeChallengeMethod | "plain" \| "S256"       | Conditional | Hashing method for code challenge. Default is `"S256"`.                                     |

#### Returns

- A Promise that resolves to an `OAuthCredential` object containing tokens and metadata.

#### Throws

- Error if the user denies authorization or a network/response error occurs.

#### Example

```ts
const oauth = new OAuth2({
  consumerKey: 'your-client-id',
  consumerSecret: 'your-client-secret',
  authorizeUrl: 'https://provider.com/oauth/authorize',
  accessTokenUrl: 'https://provider.com/oauth/token',
  responseType: 'code'
})

const credential = await oauth.authorize({
  scope: 'profile email',
  state: 'secure_random_state',
  callbackURL: Script.createOAuthCallbackURLScheme('my_oauth_script')
})

console.log(credential.oauthToken)
```

***

### `renewAccessToken(options): Promise<OAuthCredential>`

Exchanges a refresh token for a new access token from the provider.

```ts
renewAccessToken(options: {
  refreshToken: string
  parameters?: Record<string, any>
  headers?: Record<string, string>
}): Promise<OAuthCredential>
```

#### Parameters

| Name         | Type                    | Required | Description                            |
| ------------ | ----------------------- | -------- | -------------------------------------- |
| refreshToken | string                  | Yes      | The refresh token previously obtained. |
| parameters   | Record\<string, any>    | No       | Additional POST body parameters.       |
| headers      | Record\<string, string> | No       | Additional headers for the request.    |

#### Returns

- A Promise that resolves to an updated `OAuthCredential` object.

#### Throws

- Error if the refresh fails due to expired or revoked tokens.

#### Example

```ts
const newCredential = await oauth.renewAccessToken({
  refreshToken: previous.oauthRefreshToken
})

console.log(newCredential.oauthToken)
```

***

## OAuthCredential Type

The `OAuthCredential` object contains all relevant information from a successful OAuth2 transaction.

```ts
type OAuthCredential = {
  oauthToken: string
  oauthTokenSecret: string
  oauthRefreshToken: string
  oauthTokenExpiresAt: number | null
  oauthVerifier: string
  version: string
  signatureMethod: string
}
```

### Field Descriptions

| Field               | Type           | Description                                                      |
| ------------------- | -------------- | ---------------------------------------------------------------- |
| oauthToken          | string         | Access token to authorize requests to the API.                   |
| oauthTokenSecret    | string         | Token secret for request signing (used in OAuth1.0-like flows).  |
| oauthRefreshToken   | string         | Token used to refresh the access token.                          |
| oauthTokenExpiresAt | number \| null | Expiration time in Unix timestamp (ms). `null` if no expiration. |
| oauthVerifier       | string         | Verifier used for PKCE validation.                               |
| version             | string         | OAuth version (e.g., "2.0").                                     |
| signatureMethod     | string         | Method used to sign requests (e.g., "HMAC-SHA1", "PLAINTEXT").   |

***

## Best Practices

- Always verify `state` to protect against CSRF attacks unless explicitly disabled.
- Use `Script.createOAuthCallbackURLScheme(name)` to generate script-specific callback URLs.
- Securely store the `oauthRefreshToken` if long-term access is needed.
- Consider using PKCE for enhanced security, especially in public clients.



---
url: /guide/Utilities/Path.md
---

# Path

The `Path` API provides utility functions for handling and transforming file and directory paths. It is inspired by the Node.js `path` module, offering familiar methods for developers to work with paths effectively.

***

## Overview

The `Path` API provides methods for:

- Normalizing paths.
- Determining if a path is absolute.
- Joining path segments.
- Extracting path components like directory name, base name, and extension.
- Parsing paths into structured objects.

It simplifies cross-platform path handling by using the appropriate path delimiters and separators for the current operating system.

***

### Static Methods

#### `Path.normalize(path: string): string`

Normalizes the given path by resolving `..` and `.` segments.

- **Parameters:**
  - `path`: The input path to normalize.
- **Returns:**
  - A normalized path string.

#### Example:

```typescript
const normalizedPath = Path.normalize('/foo/bar//baz/asdf/quux/..')
console.log(normalizedPath) // '/foo/bar/baz/asdf'
```

***

#### `Path.isAbsolute(path: string): boolean`

Determines whether a given path is absolute.

- **Parameters:**
  - `path`: The input path.
- **Returns:**
  - `true` if the path is absolute, otherwise `false`.

#### Example:

```typescript
console.log(Path.isAbsolute('/foo/bar')) // true
console.log(Path.isAbsolute('foo/bar'))  // false
```

***

#### `Path.join(...args: string[]): string`

Joins multiple path segments into a single path and normalizes it.

- **Parameters:**
  - `...args`: The path segments to join.
- **Returns:**
  - A single normalized path string.

#### Example:

```typescript
const joinedPath = Path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
console.log(joinedPath) // '/foo/bar/baz/asdf'
```

***

#### `Path.dirname(path: string): string`

Returns the directory name of a path.

- **Parameters:**
  - `path`: The input path.
- **Returns:**
  - The directory name.

#### Example:

```typescript
console.log(Path.dirname('/foo/bar/baz/asdf/quux')) // '/foo/bar/baz/asdf'
```

***

#### `Path.basename(path: string, ext?: string): string`

Returns the last portion of a path, similar to the Unix `basename` command. Optionally, removes a file extension.

- **Parameters:**
  - `path`: The input path.
  - `ext` (optional): The file extension to remove.
- **Returns:**
  - The base name of the path.

#### Example:

```typescript
console.log(Path.basename('/foo/bar/baz/asdf/quux.html')) // 'quux.html'
console.log(Path.basename('/foo/bar/baz/asdf/quux.html', '.html')) // 'quux'
```

***

#### `Path.extname(path: string): string`

Returns the extension of the path.

- **Parameters:**
  - `path`: The input path.
- **Returns:**
  - The file extension, or an empty string if none exists.

#### Example:

```typescript
console.log(Path.extname('/foo/bar/baz/asdf/quux.html')) // '.html'
console.log(Path.extname('/foo/bar/baz/asdf/quux'))     // ''
```

***

#### `Path.parse(path: string): { root: string; dir: string; base: string; ext: string; name: string; }`

Parses a path into an object with the following properties:

- `root`: The root of the path.

- `dir`: The directory name.

- `base`: The file name including the extension.

- `ext`: The file extension.

- `name`: The file name without the extension.

- **Parameters:**
  - `path`: The input path.

- **Returns:**
  - An object with the parsed path properties.

#### Example:

```typescript
const parsed = Path.parse('/foo/bar/baz/asdf/quux.html')
console.log(parsed)
// {
//   root: '/',
//   dir: '/foo/bar/baz/asdf',
//   base: 'quux.html',
//   ext: '.html',
//   name: 'quux'
// }
```

***

## Common Use Cases

### Normalize a Path

```typescript
const normalizedPath = Path.normalize('./foo/bar/../baz')
console.log(normalizedPath) // './foo/baz'
```

### Check If a Path is Absolute

```typescript
console.log(Path.isAbsolute('/absolute/path')) // true
console.log(Path.isAbsolute('relative/path'))  // false
```

### Join Multiple Path Segments

```typescript
const fullPath = Path.join('/home', 'user', 'documents', 'file.txt')
console.log(fullPath) // '/home/user/documents/file.txt'
```

### Extract File Name and Extension

```typescript
const fileName = Path.basename('/path/to/file.txt')
const fileExt = Path.extname('/path/to/file.txt')
console.log(fileName) // 'file.txt'
console.log(fileExt)  // '.txt'
```

### Parse a Path

```typescript
const pathDetails = Path.parse('/path/to/file.txt')
console.log(pathDetails)
// {
//   root: '/',
//   dir: '/path/to',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file'
// }
```

***

## Best Practices

1. **Use Normalization:** Always normalize paths to ensure consistent formatting across platforms.
2. **Avoid Hardcoding Delimiters:** Use methods like `join` instead of concatenating strings with `/` or `\\`.

***

## Full Example

```typescript
import { Path } from 'scripting'

function main() {
  const filePath = '/foo/bar/baz/asdf/quux.html'

  console.log("Normalized Path:", Path.normalize(filePath))
  console.log("Is Absolute:", Path.isAbsolute(filePath))
  console.log("Directory Name:", Path.dirname(filePath))
  console.log("Base Name:", Path.basename(filePath))
  console.log("Extension:", Path.extname(filePath))

  const parsedPath = Path.parse(filePath)
  console.log("Parsed Path:", parsedPath)

  const joinedPath = Path.join('/foo', 'bar', 'baz')
  console.log("Joined Path:", joinedPath)
}

main()
```



---
url: /guide/Utilities/Python.md
---

# Python

The `Python` global runs Python code snippets inside the Scripting app via the embedded Python interpreter — the same runtime that powers Python index scripts. Useful for one-off computations, ad-hoc data wrangling, or invoking Python libraries from a JS / TS script without registering a separate Python script.

Code is executed using `python -c <code>`, so each call runs a fresh top-level module — module state from previous calls is **not** preserved. Imports and computed values must be set up inside `code` itself.

`Shell.run` and `Python.run` share a single serial queue: while one is running, others wait. The embedded Python interpreter shares global state (env vars, `sys.modules`) with `ios_system`, so the two cannot run concurrently.

> The current version does **not** honor `options.timeout` — long-running Python snippets will block subsequent `Shell.run` / `Python.run` calls until they finish. Wrap your code with your own timeout logic if needed.

***

## Methods

### `Python.run(code, options?): Promise<{ output, exitCode }>`

Execute a Python code snippet. Returns when the snippet exits.

```ts
function run(code: string, options?: ShellRunOptions): Promise<{
  output: string
  exitCode: number
}>
```

#### `ShellRunOptions`

| Name            | Type                    | Required | Description                                                                                                                             |
| --------------- | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| cwd             | string                  | No       | Working directory for the snippet (`os.getcwd()` inside Python). Restored after the call.                                               |
| env             | Record\<string, string> | No       | Extra environment variables. Injected into `os.environ` (Python-level) and into the process via `setenv`, then restored after the call. |
| queryParameters | Record\<string, string> | No       | Convenience field — serialized as JSON and exposed as `os.environ["SCRIPTING_QUERY_PARAMETERS"]`. Mirrors `Script.queryParameters`.     |
| timeout         | number                  | No       | **Not honored** in the current version (kept for API parity with `Shell.run`).                                                          |

#### Result

| Name     | Type   | Description                                                                                                                                                 |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| output   | string | Combined stdout + stderr produced by the snippet.                                                                                                           |
| exitCode | number | `0` on success. Non-zero values (e.g. when the snippet raises an unhandled exception) resolve normally; only argument validation errors reject the promise. |

> Unlike `Shell.run`, the Python.run result does **not** include `timedOut` / `cancelled` fields, because the underlying Python bridge has no timeout / cancel primitives.

***

## env injection note

The embedded Python interpreter snapshots `os.environ` at first `Py_Initialize`, so plain `setenv` from Swift does **not** propagate to subsequent reads of `os.environ`. To make `env` and `queryParameters` actually visible inside the snippet, the host injects a small prelude before your code that updates `os.environ` at the Python layer. This is transparent — your `code` runs as-is. Subprocesses spawned by the snippet (via `subprocess`, `os.system`, etc.) also see the variables because `setenv` is still applied.

***

## Examples

### Basic snippet

```ts
const r = await Python.run("print(1 + 2)")
console.log(r.output)   // "3\n"
console.log(r.exitCode) // 0
```

### Reading parameters

```ts
const r = await Python.run(`
import os, json
qp = json.loads(os.environ["SCRIPTING_QUERY_PARAMETERS"])
print(f"hello {qp['name']}")
`, {
  queryParameters: { name: "Alice" },
})
console.log(r.output) // "hello Alice\n"
```

### Using a Python library

```ts
const r = await Python.run(`
import statistics
data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
print(f"mean={statistics.mean(data):.2f}")
print(f"stdev={statistics.stdev(data):.2f}")
`)
console.log(r.output)
// mean=5.50
// stdev=3.03
```

### Handling errors

```ts
const r = await Python.run("raise RuntimeError('boom')")
if (r.exitCode !== 0) {
  console.log("snippet failed:")
  console.log(r.output) // contains the Python traceback
}
```

### Working directory

```ts
const r = await Python.run("import os; print(os.listdir('.'))", {
  cwd: "/tmp",
})
console.log(r.output) // contents of /tmp
```



---
url: /guide/Utilities/Redirect Rules.md
---

# Redirect Rules

Redirect Rules automatically rewrite a page's address in Safari and send you to a different one — for example, sending every `www.reddit.com` page to `old.reddit.com`, or a mobile site to its desktop version.

This feature requires Scripting PRO.

***

## How It Works

When you navigate to a page, Scripting checks its URL against your enabled rules in order. The first rule whose pattern matches rewrites the URL using its target template, and Safari is redirected there.

Each rule has a **match mode**:

- **Wildcard** (default, recommended) — `*` matches any run of characters. Each `*` becomes a capture you can reuse in the target as `$1`, `$2`, and so on.
- **Regex** (advanced) — the pattern is a regular expression matched against the whole URL. Use `$0` for the whole match and `$1`–`$9` for capture groups.

The rewritten address must start with `http://` or `https://`.

***

## Add a Rule

In the Safari Browser Scripts settings, open **Redirect Rules** and tap **Add**:

- **Name** — an optional label for the list.
- **Match mode** — Wildcard or Regex.
- **Match pattern** — the URL pattern to match.
- **Redirect to** — the target template, using `$1`, `$2`, … (or `$0` in regex mode).
- **Test** — enter a sample URL to preview the rewrite before saving.

Each rule has an **Enabled** switch. Tap a row to edit it, or swipe to delete.

***

## Examples

**Wildcard** — Reddit to old.reddit:

```
Pattern:  *://www.reddit.com/*
Redirect: https://old.reddit.com/$2
```

`https://www.reddit.com/r/swift` becomes `https://old.reddit.com/r/swift`. (`$1` captured the scheme, `$2` the path.)

**Regex** — mobile Wikipedia to desktop:

```
Pattern:  ^https://([a-z]+)\.m\.wikipedia\.org/(.*)$
Redirect: https://$1.wikipedia.org/$2
```

`https://en.m.wikipedia.org/wiki/Swift` becomes `https://en.wikipedia.org/wiki/Swift`.

***

## Notes

- Rules apply to top-level page navigation only, not to content embedded inside a page.
- A rule that would keep matching its own output will not loop endlessly — once a target has been used for a page, it is not redirected to again.
- Prefer Wildcard mode when you can. Keep regular expressions simple; a very complex regex can slow down matching.
- Changes you make in the settings take effect on your next navigation.



---
url: /guide/Utilities/Remote Push.md
---

# Remote Push

Remote Push lets your devices receive push notifications sent from your own servers and automations. After setting it up, you get a single API key that you call over HTTPS to deliver notifications to your registered devices.

***

## Getting Your API Key

Open **Tools → Remote Push** and tap **Set Up Remote Push**. This registers the current device and issues one API key for your account.

- The API key is shared across every device signed in with the same Apple ID.
- One key can have multiple registered devices.
- Keep the key private — anyone who has it can send notifications to your devices.

On the same page you can rename devices, toggle delivery per device, send a test push, and review recent logs.

***

## Base URL & Authentication

```
https://push.scripting.fun
```

All endpoints require your API key as a Bearer token:

```
Authorization: Bearer <your_api_key>
```

***

## Send a Push

### `POST /push`

Send a notification to specific devices, or to all of your devices.

```ts
POST /push
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "title": "Build finished",
  "body": "Your deploy completed successfully.",
  "deviceIds": ["a8336eb5-708b-4e4c-93a0-d8a3feb99e89"],
  "action": "scripting://run/MyScript?action=Deploy",
  "image": "https://example.com/preview.jpg",
  "icon": "hammer.fill",
  "iconColor": "systemOrange",
  "actionButtons": [
    { "label": "Open Logs", "action": "scripting://run/MyScript?action=Logs" },
    { "label": "Re-run", "action": "scripting://run/MyScript?action=Rerun" }
  ],
  "badge": 1,
  "sound": "default"
}
```

### Parameters

| Name              | Type      | Required | Description                                                                                                                                                                                 |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title             | string    | Yes      | Notification title.                                                                                                                                                                         |
| body              | string    | Yes      | Notification body text.                                                                                                                                                                     |
| deviceIds         | string\[] | No       | Target device IDs (UUIDs). Omit to send to all of your active devices. Devices with delivery turned off are always skipped.                                                                 |
| action            | string    | No       | A URL scheme opened when the notification is tapped (for example a `scripting://` deep link).                                                                                               |
| image             | string    | No       | A remote image URL. The image is downloaded on the device and shown in the expanded (long‑press) notification.                                                                              |
| icon              | string    | No       | An SF Symbol name (e.g. `hammer.fill`) or a remote image URL, shown as the sender avatar.                                                                                                   |
| iconColor         | string    | No       | Tint color for an SF Symbol `icon`: a named color (`systemRed`, `label`, ...), `#RGB`/`#RRGGBB`, `rgb()/rgba()`, or `hsl()/hsla()`. Defaults to `systemBlue`. Ignored when `icon` is a URL. |
| actionButtons     | object\[] | No       | Custom buttons shown when the notification is long‑pressed. Each item is `{ "label": string, "action": string }`, where `action` is a URL scheme opened on tap.                             |
| badge             | number    | No       | App icon badge number.                                                                                                                                                                      |
| sound             | string    | No       | Notification sound name. Defaults to `default`.                                                                                                                                             |
| category          | string    | No       | Notification category identifier.                                                                                                                                                           |
| threadId          | string    | No       | Thread identifier used to group notifications.                                                                                                                                              |
| interruptionLevel | string    | No       | How the notification interrupts: `passive`, `active` (default), `time-sensitive`, or `critical`.                                                                                            |
| criticalVolume    | number    | No       | Sound volume `0.0`–`1.0` for `critical` alerts (default `1.0`). Ignored unless `interruptionLevel` is `critical`.                                                                           |

> `image`, `icon`, and `actionButtons` produce a rich notification: long‑press (or pull down) the delivered notification to see the image, avatar, and action buttons. The server enables the required `mutable-content` flag automatically.

> `time-sensitive` notifications break through Focus modes and the scheduled notification summary. `critical` alerts additionally bypass the mute switch and Do Not Disturb and always play a sound — but they require Apple's Critical Alerts entitlement on the app. Until that entitlement is approved, a `critical` push automatically falls back to `time-sensitive`.

### Response

```json
{
  "ok": true,
  "data": {
    "push_id": "uuid",
    "target_devices": 2,
    "sent_at": "2026-05-25T10:00:00.000Z",
    "results": [
      { "deviceId": "a8336eb5-...", "status": "sent", "apnsId": "uuid" },
      { "deviceId": "b7220fa4-...", "status": "failed", "errorCode": "BadDeviceToken" }
    ],
    "daily_limit": 1000,
    "remaining": 985
  }
}
```

`remaining` and `daily_limit` in the body reflect your quota after this push. The `X-Push-Limit-Remaining` response header carries the same remaining count (measured before the push) and is also present on rate-limit errors.

***

## List Devices

### `GET /devices`

List your registered devices. Use each device `id` for the `deviceIds` array when sending a push.

```json
{
  "ok": true,
  "data": {
    "devices": [
      {
        "id": "a8336eb5-708b-4e4c-93a0-d8a3feb99e89",
        "device_name": "iPhone 15",
        "is_active": true,
        "push_enabled": true,
        "created_at": "2026-05-25T10:00:00.000Z"
      }
    ],
    "total": 1
  }
}
```

A device with `push_enabled: false` stays in the list but is skipped when sending pushes.

***

## Subscription Keys

Sometimes you want a third party — a subscription source, a feed, an automation you don't fully control — to push to your devices, without handing over your master API key (which can also manage devices, read your subscription, and mint more keys).

In **Tools → Remote Push → Subscription Keys** you can mint **send-only** keys derived from your master key:

- A subscription key can only `POST /push` to **your** devices. Every management endpoint (devices, key info, other subscription keys, logs, stats) is rejected with `MASTER_KEY_REQUIRED`.
- It uses the exact same request as the master key — just put the subscription key in the `Authorization: Bearer` header.
- Its pushes count against your account's shared daily limit.
- You can disable (reversible) or delete (permanent) a subscription key from the app at any time. A disabled or deleted key immediately stops working.

This lets a single source serve many users: each user mints one subscription key and hands it over; the source pushes to each user through that user's key, and any user can cut it off independently.

***

## Daily Limit & Statistics

### `GET /push/limit`

Returns the daily push limit and how many remain.

```json
{
  "data": {
    "date": "2026-05-25",
    "push_count": 15,
    "limit": 1000,
    "remaining": 985
  }
}
```

### `GET /push/stats`

Returns overall and daily push statistics, including totals and success rate.

***

## Push Logs

### `GET /push/logs`

Returns recent push history. Accepts an optional `limit` query parameter (1–100, default 50).

```
GET /push/logs?limit=20
```

***

## Example

```bash
curl -X POST https://push.scripting.fun/push \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","body":"World"}'
```

***

## Bark-Compatible API

This server also speaks the [Bark](https://github.com/Finb/Bark) API, so Bark-compatible tools and scripts work by pointing them at `https://push.scripting.fun` and using one of your **subscription keys** as the Bark key.

### Endpoints

- `GET|POST /:key/:body`
- `GET|POST /:key/:title/:body`
- `GET|POST /:key/:title/:subtitle/:body`
- `POST /:key` — all fields in the JSON body
- `POST /push` — with `device_key` (or a `device_keys` array) in the JSON body
- `GET /ping`, `GET /healthz`, `GET /info`, `GET /register/:key`

`key` / `device_key` is a subscription key (Tools → Remote Push → Subscription Keys). It pushes to your registered devices and counts against your account's shared daily limit.

### Supported parameters

`title`, `subtitle`, `body`, `level` (`active` / `timeSensitive` / `passive` / `critical`), `badge`, `sound`, `icon` (URL), `group`, `url`, `copy`, `autoCopy`, `call`, `volume`, `ciphertext` + `iv`, `id`.

- `sound` — a built-in Bark sound name such as `minuet`.
- `call=1` — repeats the sound for \~30 seconds.
- `level=critical` with `volume` (0–10) — a critical alert. Requires the app's Critical Alerts entitlement; until that is approved by Apple it falls back to `time-sensitive`.
- `url` — opened when the notification is tapped.
- `copy` — long-press the notification and tap **Copy** to copy this text (or the whole body if omitted). `autoCopy=1` copies on delivery.
- `badge` — sets the app icon badge; send `badge=0` to clear it (iOS keeps the last badge until you explicitly reset it).
- Encrypted push — set the AES key in **Tools → Remote Push → Encryption**, then send `ciphertext` (base64) and an optional `iv`.

`markdown` is treated as plain text; `isArchive` / `ttl` are ignored (there is no in-app message history).

### Example

```bash
curl "https://push.scripting.fun/<key>/Build%20finished/Deploy%20succeeded?sound=minuet&group=ci"
```

***

## Rate Limiting

- Each account has a daily push limit, shared across the account's keys (master and subscription keys). Check the current limit and remaining count with `GET /push/limit`.
- The `X-Push-Limit-Remaining` response header shows the remaining count.



---
url: /guide/Utilities/Request/FormData.md
---

# FormData

The `FormData` class provides a way to construct key/value pairs representing form fields and their values.
It is mainly used for building `multipart/form-data` requests that can include both text and binary data (such as files or images).

In the **Scripting app**, `FormData` is fully compatible with the standard **Fetch API**, allowing you to send data through `fetch()` with mixed text and file fields.

***

## Definition

```ts
class FormData {
  private formData
  append(name: string, value: string): void
  append(name: string, value: Data, mimeType: string, filename?: string): void
  get(name: string): string | Data | null
  getAll(name: string): any[]
  has(name: string): boolean
  delete(name: string): void
  set(name: string, value: string): void
  set(name: string, value: Data, filename?: string): void
  forEach(callback: (value: any, name: string, parent: FormData) => void): void
  entries(): [string, any][]
  toJson(): Record<string, any>
}
```

***

## Purpose

`FormData` is used to:

- Build `multipart/form-data` requests with text and file fields.
- Upload files (images, documents, audio, etc.) with metadata.
- Replace JSON-based bodies when binary data is included.

***

## Methods

### `append(name: string, value: string): void`

### `append(name: string, value: Data, mimeType: string, filename?: string): void`

Appends a new field to the form.
Can be used to add both text and file fields.

#### Parameters

| Parameter    | Type                  | Description                                                                                     |                                               |
| ------------ | --------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------- |
| **name**     | `string`              | The name of the form field.                                                                     |                                               |
| **value**    | `string`              | `Data`                                                                                          | The value of the field (text or binary data). |
| **mimeType** | `string`              | The MIME type of the file (e.g., `"image/png"`). Required only when `value` is a `Data` object. |                                               |
| **filename** | `string` _(optional)_ | The filename to include for file uploads.                                                       |                                               |

#### Example

```tsx
const form = new FormData()
form.append("username", "Tom")
form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "avatar.png")
```

***

### `set(name: string, value: string): void`

### `set(name: string, value: Data, filename?: string): void`

Sets a form field, replacing any existing field with the same name.
Unlike `append()`, this overwrites previous values.

#### Example

```tsx
const form = new FormData()
form.set("message", "Hello world")
form.set("file", Data.fromFile("/path/to/file.txt"), "text/plain", "note.txt")
```

***

### `get(name: string): string | Data | null`

Retrieves the value of a form field.
Returns `null` if the field does not exist.

#### Example

```tsx
const form = new FormData()
form.append("title", "My Post")
console.log(form.get("title")) // "My Post"
```

***

### `getAll(name: string): any[]`

Returns all values associated with a given field name (useful when using multiple `append()` calls with the same name).

#### Example

```tsx
const form = new FormData()
form.append("tag", "swift")
form.append("tag", "ios")
form.append("tag", "scripting")

console.log(form.getAll("tag")) // ["swift", "ios", "scripting"]
```

***

### `has(name: string): boolean`

Checks whether a form field exists.

#### Example

```tsx
const form = new FormData()
form.append("username", "Tom")

console.log(form.has("username")) // true
console.log(form.has("password")) // false
```

***

### `delete(name: string): void`

Deletes the specified field and all of its values.

#### Example

```tsx
const form = new FormData()
form.append("title", "Hello")
form.append("file", Data.fromFile("/path/to/file.txt"), "text/plain")

form.delete("file")
```

***

### `forEach(callback: (value: any, name: string, parent: FormData) => void): void`

Iterates over all form fields and invokes the callback function for each one.

#### Example

```tsx
const form = new FormData()
form.append("user", "Tom")
form.append("age", "25")

form.forEach((value, name) => {
  console.log(`${name}: ${value}`)
})
```

***

### `entries(): [string, any][]`

Returns an array of `[name, value]` pairs for all form fields.

#### Example

```tsx
const form = new FormData()
form.append("username", "Tom")
form.append("age", "25")
console.log(form.entries())
// [["username", "Tom"], ["age", "25"]]
```

***

### `toJson(): Record<string, any>`

Converts the form data into a plain JSON object for debugging or logging.
If the form contains binary data (`Data` objects), those fields will be represented as descriptive placeholders instead of raw binary data.

#### Example

```tsx
const form = new FormData()
form.append("name", "Tom")
form.append("photo", Data.fromFile("/path/to/avatar.png"), "image/png", "avatar.png")

console.log(form.toJson())
// { name: "Tom", photo: "[Data: image/png]" }
```

***

## Usage Examples

### Example 1 — Upload a File

```tsx
const form = new FormData()
form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "avatar.png")
form.append("userId", "1234")

const response = await fetch("https://api.example.com/upload", {
  method: "POST",
  body: form,
})

console.log(await response.json())
```

***

### Example 2 — Upload Multiple Files

```tsx
const form = new FormData()
form.append("files", Data.fromFile("/path/to/photo1.jpg"), "image/jpeg", "photo1.jpg")
form.append("files", Data.fromFile("/path/to/photo2.jpg"), "image/jpeg", "photo2.jpg")

await fetch("https://api.example.com/multi-upload", {
  method: "POST",
  body: form,
})
```

***

### Example 3 — Mixed Text and File Fields

```tsx
const form = new FormData()
form.append("title", "Travel Memories")
form.append("description", "A collection of travel photos.")
form.append("cover", Data.fromFile("/path/to/cover.png"), "image/png", "cover.png")

const response = await fetch("https://example.com/uploadPost", {
  method: "POST",
  body: form,
})

console.log(await response.text())
```

***

### Example 4 — Iterating and Debugging

```tsx
const form = new FormData()
form.append("name", "Alice")
form.append("file", Data.fromFile("/path/to/file.txt"), "text/plain", "file.txt")

form.forEach((value, name) => {
  console.log(`${name}:`, value instanceof Data ? "Binary Data" : value)
})
```

***

## Relationships with Other Classes

| Class          | Description                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------- |
| **`fetch()`**  | Accepts `FormData` as a request body; automatically sets `Content-Type` to `multipart/form-data`. |
| **`Data`**     | Used to represent binary content (e.g., files, images) added to form fields.                      |
| **`Request`**  | A `FormData` instance can be passed to `RequestInit.body`.                                        |
| **`Response`** | You can use `response.formData()` to parse a multipart response into a `FormData` object.         |

***

## Notes

- **Automatic Content-Type:** When you pass a `FormData` instance to `fetch()`, the app automatically sets the correct `Content-Type` header (with a boundary). Do not manually set it.
- **Multiple Fields:** Use `append()` to add multiple values with the same name.
- **Binary Uploads:** Always provide a MIME type for binary uploads. Otherwise, the data defaults to `application/octet-stream`.
- **JSON Conversion:** The `toJson()` method is intended for debugging and should not be used for actual data transmission.

***

## Summary

`FormData` is the **core class for building multipart/form-data requests** in the Scripting app.
It provides a flexible and developer-friendly API for combining text and binary fields, integrating seamlessly with `fetch()` and `Data`.

### Key Features

- Fully compatible with the Fetch API
- Supports text and file uploads
- Automatically handles multipart boundaries
- Useful debugging utilities (`entries()`, `toJson()`)
- Integrates natively with `Data`, `Request`, and `Response`



---
url: /guide/Utilities/Request/Headers.md
---

# Headers

The `Headers` class represents a collection of HTTP request or response header fields.
It is fully compatible with the **Fetch API** standard but includes additional convenience methods for scripting environments, such as JSON conversion for debugging and serialization.

A `Headers` object can be used in the following contexts:

- When creating a request via `RequestInit.headers`
- When reading headers from a `Response` object
- When programmatically modifying header data in a script

***

## Definition

```ts
class Headers {
  constructor(init?: HeadersInit)
  append(name: string, value: string): void
  get(name: string): string | null
  has(name: string): boolean
  set(name: string, value: string): void
  delete(name: string): void
  forEach(callback: (value: string, name: string) => void): void
  keys(): string[]
  values(): string[]
  entries(): [string, string][]
  toJson(): Record<string, string>
}
```

***

## HeadersInit Type

`Headers` can be initialized using multiple formats:

```ts
type HeadersInit = [string, string][] | Record<string, string> | Headers
```

You can create a `Headers` object using any of these forms:

```tsx
new Headers([["Content-Type", "application/json"]])
new Headers({ "Authorization": "Bearer token" })
new Headers(existingHeaders)
```

***

## Constructor

### `new Headers(init?: HeadersInit)`

Creates a new `Headers` instance.
You can optionally pass initial header data.

#### Parameters

| Parameter | Type          | Description                                                                  |
| --------- | ------------- | ---------------------------------------------------------------------------- |
| **init**  | `HeadersInit` | Initial header data. Can be an object, array, or another `Headers` instance. |

***

## Methods

### `append(name: string, value: string): void`

Adds a new value to an existing header field.
If the field already exists, the new value is **appended** instead of replacing the old one.

#### Example

```tsx
const headers = new Headers()
headers.append("Accept", "application/json")
headers.append("Accept", "text/plain") // Now "Accept" has two values
```

***

### `set(name: string, value: string): void`

Sets a header field to a specific value.
If the field already exists, it will be **overwritten**.

#### Example

```tsx
const headers = new Headers()
headers.set("Content-Type", "application/json")
headers.set("Authorization", "Bearer token-123")
```

***

### `get(name: string): string | null`

Retrieves the value of a specific header field.
Returns `null` if the field does not exist.

#### Example

```tsx
const headers = new Headers({ "Content-Type": "application/json" })
console.log(headers.get("Content-Type")) // "application/json"
```

***

### `has(name: string): boolean`

Checks whether a specific header field exists.

#### Example

```tsx
const headers = new Headers({ "Accept": "application/json" })
console.log(headers.has("Accept")) // true
console.log(headers.has("Authorization")) // false
```

***

### `delete(name: string): void`

Removes a specific header field.

#### Example

```tsx
const headers = new Headers({
  "Accept": "application/json",
  "Cache-Control": "no-cache"
})
headers.delete("Cache-Control")
```

***

### `forEach(callback: (value: string, name: string) => void): void`

Iterates over all header fields and executes the callback for each pair.

#### Example

```tsx
const headers = new Headers({
  "Accept": "application/json",
  "User-Agent": "ScriptingApp/1.0"
})

headers.forEach((value, name) => {
  console.log(`${name}: ${value}`)
})
```

***

### `keys(): string[]`

Returns an array containing all header names.

```tsx
const headers = new Headers({
  "Accept": "application/json",
  "User-Agent": "Scripting"
})
console.log(headers.keys()) // ["accept", "user-agent"]
```

> Note: Header names are **case-insensitive** and normalized to lowercase.

***

### `values(): string[]`

Returns an array containing all header values.

```tsx
const headers = new Headers({
  "Accept": "application/json",
  "User-Agent": "Scripting"
})
console.log(headers.values()) // ["application/json", "Scripting"]
```

***

### `entries(): [string, string][]`

Returns an array of `[name, value]` pairs representing all headers.

#### Example

```tsx
const headers = new Headers({
  "Accept": "application/json",
  "Cache-Control": "no-cache"
})
console.log(headers.entries())
// [["accept", "application/json"], ["cache-control", "no-cache"]]
```

***

### `toJson(): Record<string, string>`

Converts the header collection into a plain JSON object for easy serialization and debugging.

#### Example

```tsx
const headers = new Headers({
  "Content-Type": "application/json",
  "Authorization": "Bearer token"
})

console.log(headers.toJson())
// { "content-type": "application/json", "authorization": "Bearer token" }
```

***

## Usage Examples

### Example 1 — Setting Custom Headers in a Request

```tsx
const headers = new Headers()
headers.set("Content-Type", "application/json")
headers.set("Authorization", "Bearer token-xyz")

const response = await fetch("https://api.example.com/user", {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "Tom" }),
})
```

***

### Example 2 — Reading Response Headers

```tsx
const response = await fetch("https://example.com/data")
console.log("Content-Type:", response.headers.get("Content-Type"))
console.log("Server:", response.headers.get("Server"))
```

***

### Example 3 — Converting to JSON for Logging

```tsx
const response = await fetch("https://example.com/api")
console.log("Response Headers:", response.headers.toJson())
```

***

### Example 4 — Checking for Specific Headers

```tsx
const response = await fetch("https://example.com/info")
if (response.headers.has("Set-Cookie")) {
  console.log("The response contains a Set-Cookie header")
}
```

***

## Relationships with Other Classes

| Class          | Description                                                                              |
| -------------- | ---------------------------------------------------------------------------------------- |
| **`Request`**  | Headers can be defined in `RequestInit.headers` when creating requests.                  |
| **`Response`** | Access response headers via `response.headers`.                                          |
| **`fetch()`**  | Both requests and responses use `Headers` to manage header data.                         |
| **`Cookie`**   | Cookies returned in headers can be parsed into structured objects in `response.cookies`. |

***

## Notes

- **Case-insensitivity:** Header names are case-insensitive and stored in lowercase form.
- **Multi-value headers:** Use `append()` to add multiple values for the same header (e.g., for `Accept` or `Cookie`).
- **System headers:** Certain system-managed headers (e.g., `Host`, `Connection`) may be ignored or overwritten by the iOS networking stack.
- **Serialization:** The `toJson()` method is useful for logging, debugging, or serializing header data.

***

## Summary

The `Headers` class is a foundational component of the **Scripting networking system**, providing a consistent and convenient interface for managing HTTP headers.

It enables developers to:

- Add, modify, and remove headers dynamically
- Read and iterate through response headers
- Work with both request and response headers in a unified way
- Output structured header data for logging and debugging



---
url: /guide/Utilities/Request/ReadableStream.md
---

# ReadableStream

`ReadableStream` represents a **stream of data** that can be read incrementally rather than all at once.
In **Scripting**, `ReadableStream<Data>` is used in various scenarios, including:

- Handling **streaming HTTP responses** (e.g., `Response.body`)
- **Chunked file downloads** or large data transfers
- **Real-time data streams** such as logs, AI model output, or event streams

It follows the same behavior as the standard **Web Streams API**, allowing asynchronous iteration (`for await...of`) and manual reading via a `ReadableStreamDefaultReader`.

***

## Definition

```ts
class ReadableStream<T = any> {
  constructor(underlyingSource?: UnderlyingSource<T>)

  get locked(): boolean
  cancel(reason?: any): Promise<void>
  getReader(): ReadableStreamDefaultReader<T>
  tee(): [ReadableStream<T>, ReadableStream<T>]
}
```

***

## Overview

- A `ReadableStream` represents a **data source that can be consumed asynchronously**.
- Instead of loading the entire payload into memory, data is read **in chunks** as it becomes available.
- Only one active reader can consume a stream at a time. When locked (`locked = true`), no other consumer can access it until released or canceled.

***

## Properties

### `locked: boolean`

Indicates whether the stream is currently locked to a reader.
If `true`, you must release the lock or cancel the stream before another reader can be created.

#### Example

```tsx
const reader = response.body.getReader()
console.log(response.body.locked) // true
```

***

## Methods

### `getReader(): ReadableStreamDefaultReader<T>`

Returns a `ReadableStreamDefaultReader` that allows manual, incremental reading of stream data.
Each call to `reader.read()` returns a Promise resolving to an object `{ value, done }`.

#### Example

```tsx
const reader = response.body.getReader()

while (true) {
  const { done, value } = await reader.read()
  if (done) break
  console.log("Received chunk:", value)
}
```

***

### `cancel(reason?: any): Promise<void>`

Cancels reading from the stream.
Optionally provide a `reason` describing why the operation was aborted.

#### Example

```tsx
const reader = response.body.getReader()
await response.body.cancel("User canceled reading")
```

***

### `tee(): [ReadableStream<T>, ReadableStream<T>]`

Splits a stream into two identical branches that can be consumed independently.

#### Example

```tsx
const [stream1, stream2] = response.body.tee()

const reader1 = stream1.getReader()
const reader2 = stream2.getReader()
```

***

## ReadableStreamDefaultReader

When you obtain a reader using `getReader()`, you can manually control the reading process.

### Definition

```ts
interface ReadableStreamDefaultReader<T> {
  read(): Promise<{ value: T; done: boolean }>
  releaseLock(): void
  cancel(reason?: any): Promise<void>
}
```

#### Method Descriptions

| Method              | Description                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| **read()**          | Reads the next data chunk. Resolves with `{ value, done }`. When `done = true`, the stream has ended. |
| **releaseLock()**   | Releases the lock so the stream can be read again by another consumer.                                |
| **cancel(reason?)** | Cancels reading from the stream.                                                                      |

#### Example — Reading Stream Data

```tsx
const reader = response.body.getReader()

while (true) {
  const { done, value } = await reader.read()
  if (done) break

  // Each chunk is a Data instance
  const text = value.toRawString()
  console.log("Chunk:", text)
}

reader.releaseLock()
```

***

## Integration with Response

The `Response.body` property is a `ReadableStream<Data>` that allows streaming response content.

#### Example — Handling Streaming Network Response

```tsx
const response = await fetch("https://example.com/stream")

const reader = response.body.getReader()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  console.log("Received:", value.toRawString())
}
```

This method enables real-time data processing **before the full response is received**, ideal for:

- Real-time log streaming
- Progressive file downloads
- AI or LLM text generation (token streaming)

***

## Integration with Data

In Scripting, each stream chunk (`value`) is a `Data` object.
You can use the `Data` APIs such as `.toRawString()` or `.toUint8Array()` to inspect or transform the content.

#### Example — Save Stream Data to a File

```tsx
const reader = response.body.getReader()
const chunks: Data[] = []

while (true) {
  const { done, value } = await reader.read()
  if (done) break
  chunks.push(value)
}

const fileData = Data.combine(chunks)
FileManager.write(fileData, "/local/download.bin")
```

***

## Using Async Iteration

`ReadableStream` supports async iteration (`for await...of`), simplifying data consumption syntax:

```tsx
for await (const chunk of response.body) {
  console.log("Chunk size:", chunk.size)
}
```

This approach automatically handles the `done` condition for you, resulting in cleaner code.

***

## Common Use Cases

| Use Case                         | Example                                                                         |
| -------------------------------- | ------------------------------------------------------------------------------- |
| **Large File Download**          | Stream file chunks from the network and save locally without high memory usage. |
| **AI Output Streaming**          | Display real-time model output as it’s generated.                               |
| **Incremental Local Processing** | Process local files or streams incrementally.                                   |

***

## Notes

- **Single-reader rule:** Only one reader can consume a `ReadableStream` at a time.
- **Memory efficiency:** Streaming avoids loading large payloads entirely into memory.
- **Error handling:** Reading may reject on errors (e.g., network failure). Use `try...catch` to handle exceptions safely.
- **Chunk type:** For `Response.body`, each chunk is a `Data` object — not plain text or byte arrays.

***

## Summary

`ReadableStream` is a **core component of Scripting’s streaming data architecture**, providing efficient and flexible data handling capabilities.

### Key Features

- Asynchronous, incremental data reading
- Seamless integration with `fetch()`, `Response`, and `Data`
- Supports real-time processing and large data transfers
- Fully compatible with the standard **Web Streams API**



---
url: /guide/Utilities/Request/Request & RequestInit.md
---

# Request & RequestInit

The `Request` class represents a complete configuration of an HTTP request.
It can be passed directly to the `fetch()` method or used to clone, modify, or retry an existing request.

In Scripting, the `Request` API behaves similarly to the browser’s Fetch API but adds native extensions, including:

- Binary `Data` type support for request bodies
- Custom redirect handling
- Request timeout and cancellation
- Optional allowance for insecure (HTTP) requests
- Debug labels for internal logging

***

## Definition

```ts
class Request {
  url: string
  method: string
  headers: Headers
  body?: Data | FormData | string | ArrayBuffer
  allowInsecureRequest?: boolean
  handleRedirect?: (newRequest: RedirectRequest) => Promise<RedirectRequest | null>
  shouldAllowRedirect?: (newRequest: Request) => Promise<boolean> // deprecated
  timeout?: DurationInSeconds
  signal?: AbortSignal
  cancelToken?: CancelToken // deprecated
  debugLabel?: string

  constructor(input: string | Request, init?: RequestInit)
  clone(): Request
}
```

***

## Constructor

### `new Request(input: string | Request, init?: RequestInit)`

Creates a new `Request` instance from either a URL string or an existing `Request` object.

#### Parameters

| Parameter | Type          | Description                                                          |                                                  |
| --------- | ------------- | -------------------------------------------------------------------- | ------------------------------------------------ |
| **input** | `string`      | `Request`                                                            | The target URL, or an existing request to clone. |
| **init**  | `RequestInit` | Optional configuration object defining request settings (see below). |                                                  |

***

## Properties

| Property                 | Type                                                                | Description                                                                   |
| ------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **url**                  | `string`                                                            | The full URL of the request.                                                  |
| **method**               | `string`                                                            | The HTTP method (default is `"GET"`).                                         |
| **headers**              | `Headers`                                                           | A headers object representing the request headers.                            |
| **body**                 | `Data` \| `FormData` \| `string` \| `ArrayBuffer` \| `undefined`    | The request body, used only for non-`GET` and non-`HEAD` requests.            |
| **allowInsecureRequest** | `boolean`                                                           | Whether to allow plain HTTP requests (default `false`).                       |
| **handleRedirect**       | `(newRequest: RedirectRequest) => Promise<RedirectRequest \| null>` | Custom redirect handler. Return `null` to cancel the redirect.                |
| **shouldAllowRedirect**  | `(newRequest: Request) => Promise<boolean>`                         | Deprecated legacy redirect handler.                                           |
| **timeout**              | `number`                                                            | Timeout in seconds. The request will automatically abort after this duration. |
| **signal**               | `AbortSignal`                                                       | Abort signal from an `AbortController`, allowing manual cancellation.         |
| **cancelToken**          | `CancelToken`                                                       | Deprecated. Older cancellation mechanism; prefer `signal`.                    |
| **debugLabel**           | `string`                                                            | Optional label displayed in logs for debugging and tracking requests.         |

***

## Methods

### `clone(): Request`

Creates and returns a copy of the current request.
The cloned object can be safely modified (e.g., updating headers or timeout) without affecting the original request.

#### Example

```tsx
const req1 = new Request("https://api.example.com/user", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Alice" }),
})

const req2 = req1.clone()
console.log(req2.method) // "POST"
```

***

## Examples

### Example 1 — Creating a Simple Request

```tsx
const request = new Request("https://api.example.com/data", {
  method: "GET",
  headers: {
    "Accept": "application/json",
  },
  debugLabel: "Fetch User Data",
})

const response = await fetch(request)
const result = await response.json()
console.log(result)
```

***

### Example 2 — POST Request with a Body

```tsx
const request = new Request("https://api.example.com/upload", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ fileId: "abc123" }),
  timeout: 15,
})

const response = await fetch(request)
console.log(await response.text())
```

***

### Example 3 — Cloning and Modifying a Request

```tsx
const base = new Request("https://api.example.com/posts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
})

const cloned = base.clone()
cloned.headers.set("Authorization", "Bearer token-123")
cloned.debugLabel = "Authorized Upload"

await fetch(cloned)
```

***

## RequestInit Interface

The `RequestInit` interface defines configuration options for HTTP requests.
It is used as the second argument to `fetch()` or the optional configuration object when creating a new `Request`.
Scripting extends this interface with additional native fields.

***

## Definition

```ts
type RequestInit = {
  method?: string
  headers?: HeadersInit
  body?: Data | FormData | string | ArrayBuffer
  allowInsecureRequest?: boolean
  handleRedirect?: (newRequest: RedirectRequest) => Promise<RedirectRequest | null>
  shouldAllowRedirect?: (newRequest: Request) => Promise<boolean> // deprecated
  timeout?: DurationInSeconds
  signal?: AbortSignal
  cancelToken?: CancelToken // deprecated
  debugLabel?: string
}
```

***

## Field Descriptions

| Field                    | Type                                                                | Description                                                                                                            |   |
| ------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | - |
| **method**               | `string`                                                            | The HTTP method such as `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`. Default: `"GET"`.                                      |   |
| **headers**              | `HeadersInit`                                                       | Request headers, which can be a `Headers` object, key-value object `{ key: value }`, or array of `[key, value]` pairs. |   |
| **body**                 | `Data` \| `FormData` \| `string` \| `ArrayBuffer`                   | The request body. Ignored for `GET` and `HEAD` requests.                                                               |   |
| **allowInsecureRequest** | `boolean`                                                           | Allows HTTP requests (insecure). Default: `false`.                                                                     |   |
| **handleRedirect**       | `(newRequest: RedirectRequest) => Promise<RedirectRequest \| null>` | Custom redirect handler. Return `null` to block redirection.                                                           |   |
| **shouldAllowRedirect**  | `(newRequest: Request) => Promise<boolean>`                         | Deprecated. Older redirect callback.                                                                                   |   |
| **timeout**              | `number`                                                            | Request timeout in seconds. Triggers `AbortError` if exceeded.                                                         |   |
| **signal**               | `AbortSignal`                                                       | Used to abort requests manually through an `AbortController`.                                                          |   |
| **cancelToken**          | `CancelToken`                                                       | Deprecated cancellation mechanism. Use `signal` instead.                                                               |   |
| **debugLabel**           | `string`                                                            | A label displayed in the debug log for identifying requests.                                                           |   |

***

## Relationship with `fetch()`

`RequestInit` is typically passed as the second parameter to `fetch()` to configure a network request.

```tsx
const response = await fetch("https://example.com/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ id: 123 }),
  timeout: 10,
  debugLabel: "Upload JSON",
})
```

***

## Relationships with Other Classes

| Class                                 | Description                                                                            |
| ------------------------------------- | -------------------------------------------------------------------------------------- |
| **`Headers`**                         | Manages request headers, used with the `headers` field.                                |
| **`Data`**                            | Represents binary data. Can be used as the request body for file uploads or raw bytes. |
| **`FormData`**                        | Builds `multipart/form-data` bodies for form or file submissions.                      |
| **`AbortController` / `AbortSignal`** | Enables manual request cancellation.                                                   |
| **`CancelToken`**                     | Deprecated cancellation mechanism retained for backward compatibility.                 |
| **`RedirectRequest`**                 | Represents the redirected request passed to `handleRedirect`.                          |

***

## Examples

### Example 1 — Custom Redirect Handling

```tsx
const response = await fetch("https://example.com/start", {
  handleRedirect: async (newRequest) => {
    console.log("Redirect detected:", newRequest.url)
    if (newRequest.url.includes("blocked")) return null
    return newRequest
  },
})
```

***

### Example 2 — Allowing Insecure Requests

```tsx
const response = await fetch("http://insecure.example.com/data", {
  allowInsecureRequest: true,
})
console.log(await response.text())
```

***

### Example 3 — Using a Debug Label

```tsx
await fetch("https://example.com/api/ping", {
  debugLabel: "Ping Request",
})
// The log panel will display the label "Ping Request"
```

***

## RedirectRequest Interface

When a request encounters an **HTTP redirect**, and a `handleRedirect` callback is defined in the `Request` or `RequestInit` object, the system will invoke that callback before following the redirect.
The callback receives a `RedirectRequest` object, which describes the full details of the redirect request.
You can inspect or modify this object to control whether and how the redirect should proceed.

***

### Interface Definition

```ts
interface RedirectRequest {
  method: string
  url: string
  headers: Record<string, string>
  cookies: Cookie[]
  body?: Data
  timeout?: number
}
```

***

### Field Descriptions

| Field       | Type                     | Description                                                                                    |
| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
| **method**  | `string`                 | The HTTP method for the redirected request (e.g., `"GET"`, `"POST"`).                          |
| **url**     | `string`                 | The full target URL of the redirect.                                                           |
| **headers** | `Record<string, string>` | The HTTP headers to be sent with the redirect request. You can modify these before proceeding. |
| **cookies** | `Cookie[]`               | The list of cookies available for the redirected request (same format as `Response.cookies`).  |
| **body**    | `Data` _(optional)_      | The body of the redirect request, if applicable (e.g., for non-GET methods).                   |
| **timeout** | `number` _(optional)_    | The request timeout in seconds.                                                                |

***

### Use Cases

The `handleRedirect` callback allows you to:

- Inspect and validate redirect destinations for security or logic reasons.
- Modify redirect requests (add headers, update method, or include authorization tokens).
- Block unwanted or unsafe redirects.

When the callback returns:

- A modified `RedirectRequest` → The redirect proceeds using your modified configuration.
- `null` → The redirect is **canceled**, and the `fetch()` call resolves with the current response.

***

### Example: Intercepting and Controlling Redirects

```tsx
const response = await fetch("https://example.com/start", {
  handleRedirect: async (redirect) => {
    console.log("Redirecting to:", redirect.url)

    // Block redirects to external domains
    if (!redirect.url.startsWith("https://example.com")) {
      console.warn("Blocked external redirect:", redirect.url)
      return null
    }

    // Add authorization header to redirected request
    redirect.headers["Authorization"] = "Bearer my-token"
    return redirect
  },
})
```

***

### Example: Modifying Redirect Method and Body

```tsx
const response = await fetch("https://api.example.com/login", {
  handleRedirect: async (redirect) => {
    // Keep the request body when redirecting to a confirmation endpoint
    if (redirect.url.includes("/finalize")) {
      redirect.method = "POST"
      redirect.body = Data.fromRawString("action=confirm", "utf-8")
    }
    return redirect
  },
})
```

***

### Notes

- If `handleRedirect` is **not defined**, all redirects are automatically followed by default.
- Returning `null` from the callback prevents further redirection.
- Cookies are **not automatically forwarded**; you can manually inspect and decide whether to reuse cookies from `redirect.cookies`.
- Any modifications made to the `RedirectRequest` (such as headers or method) will be applied before the next request is executed.

***

## Summary

`Request` and `RequestInit` form the **foundation of Scripting’s networking system**:

- `Request` encapsulates a complete HTTP request and can be reused or cloned.
- `RequestInit` defines configuration options for flexible initialization.
- Together, they integrate tightly with `fetch()`, `Response`, `Headers`, `Data`, and `FormData`.



---
url: /guide/Utilities/Request/Response.md
---

# Response

The `Response` class represents the result of an HTTP request made using the `fetch()` API.
It provides access to the response body, headers, cookies, and metadata such as the status code and MIME type.

In the **Scripting app**, the `Response` API extends the standard Fetch API behavior to provide **native-level enhancements**, including:

- Access to structured cookie data
- Binary data handling via the `Data` type
- WHATWG-compatible streaming via `body` (`ReadableStream<Uint8Array>`)
- A zero-copy `dataStream` (`ReadableStream<Data>`) for streaming the body as native `Data`
- Access to expected content length, MIME type, and text encoding

***

## Definition

```ts
class Response {
  readonly body: ReadableStream<Uint8Array>
  get dataStream(): ReadableStream<Data>

  get bodyUsed(): boolean
  get cookies(): Cookie[]
  json(): Promise<any>
  text(): Promise<string>
  data(): Promise<Data>
  bytes(): Promise<Uint8Array>
  arrayBuffer(): Promise<ArrayBuffer>
  formData(): Promise<FormData>
  get status(): number
  get statusText(): string
  get headers(): Headers
  get ok(): boolean
  get url(): string
  get mimeType(): string | undefined
  get expectedContentLength(): number | undefined
  get textEncodingName(): string | undefined
}
```

***

## Properties

| Property                  | Type                         | Description                                                                                                                                                               |                                                                             |
| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **body**                  | `ReadableStream<Uint8Array>` | The response body as a readable stream of `Uint8Array` chunks (WHATWG-compatible).                                                                                        |                                                                             |
| **dataStream**            | `ReadableStream<Data>`       | The response body as a stream of native `Data` chunks — the zero-copy fast path. Mutually exclusive with `body` and the read methods; the body can only be consumed once. |                                                                             |
| **bodyUsed**              | `boolean`                    | Indicates whether the response body has been read.                                                                                                                        |                                                                             |
| **cookies**               | `Cookie[]`                   | A list of cookies sent by the server via the `Set-Cookie` header.                                                                                                         |                                                                             |
| **status**                | `number`                     | The HTTP status code of the response (e.g. `200`, `404`, `500`).                                                                                                          |                                                                             |
| **statusText**            | `string`                     | The status message returned by the server (e.g. `"OK"`, `"Not Found"`).                                                                                                   |                                                                             |
| **headers**               | `Headers`                    | A `Headers` object representing response headers.                                                                                                                         |                                                                             |
| **ok**                    | `boolean`                    | `true` if the status code is between 200 and 299, otherwise `false`.                                                                                                      |                                                                             |
| **url**                   | `string`                     | The final URL of the response after any redirects.                                                                                                                        |                                                                             |
| **mimeType**              | `string`                     | `undefined`                                                                                                                                                               | The MIME type inferred from headers (e.g. `"application/json"`).            |
| **expectedContentLength** | `number`                     | `undefined`                                                                                                                                                               | The expected size of the response body in bytes, if provided by the server. |
| **textEncodingName**      | `string`                     | `undefined`                                                                                                                                                               | The encoding used for text responses (e.g. `"utf-8"`).                      |

***

## Methods

### `json(): Promise<any>`

Parses the response body as JSON.

#### Example

```tsx
const response = await fetch("https://api.example.com/user")
const data = await response.json()
console.log(data.name)
```

***

### `text(): Promise<string>`

Reads the response body as a UTF-8 string (or using `textEncodingName` if available).

#### Example

```tsx
const response = await fetch("https://example.com/message.txt")
const text = await response.text()
console.log(text)
```

***

### `data(): Promise<Data>`

Reads the response body as a binary `Data` object, which can be used for file saving, image decoding, or Base64 conversion.

#### Example

```tsx
const response = await fetch("https://example.com/image.png")
const imageData = await response.data()
FileManager.write(imageData, "/local/image.png")
```

***

### `bytes(): Promise<Uint8Array>`

Reads the response as a byte array (`Uint8Array`).

#### Example

```tsx
const response = await fetch("https://example.com/file.bin")
const bytes = await response.bytes()
console.log("Received", bytes.length, "bytes")
```

***

### `arrayBuffer(): Promise<ArrayBuffer>`

Reads the response as an `ArrayBuffer`, useful for low-level binary operations.

#### Example

```tsx
const response = await fetch("https://example.com/file")
const buffer = await response.arrayBuffer()
console.log(buffer.byteLength)
```

***

### `dataStream: ReadableStream<Data>`

Streams the response body as native `Data` chunks. This is the zero-copy fast path: prefer it over `body` when you work with `Data` (e.g. appending chunks to a file), since `body` converts every chunk to `Uint8Array`. The body can only be consumed once, so reading `dataStream` makes `body` and the read methods (`data()`, `json()`, …) unavailable.

#### Example

```tsx
const response = await fetch("https://example.com/large-file")
const reader = response.dataStream.getReader()
const parts: Data[] = []
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  if (value != null) parts.push(value)
}
const data = Data.combine(parts)
```

***

### `formData(): Promise<FormData>`

Parses the response body as form data (for responses with `multipart/form-data` content).

#### Example

```tsx
const response = await fetch("https://example.com/form")
const form = await response.formData()
console.log(form.get("username"))
```

***

### `cookies: Cookie[]`

The `cookies` property provides direct access to the cookies set by the server via `Set-Cookie` headers.
Each cookie is represented by a `Cookie` object with structured metadata.

#### Cookie Type Definition

```ts
interface Cookie {
  name: string
  value: string
  domain: string
  path: string
  isSecure: boolean
  isHTTPOnly: boolean
  isSessionOnly: boolean
  expiresDate?: Date | null
}
```

| Field             | Type           | Description                                                   |
| ----------------- | -------------- | ------------------------------------------------------------- |
| **name**          | `string`       | Cookie name.                                                  |
| **value**         | `string`       | Cookie value.                                                 |
| **domain**        | `string`       | Domain to which the cookie belongs.                           |
| **path**          | `string`       | Path scope of the cookie.                                     |
| **isSecure**      | `boolean`      | `true` if the cookie is sent only over HTTPS.                 |
| **isHTTPOnly**    | `boolean`      | `true` if inaccessible to JavaScript.                         |
| **isSessionOnly** | `boolean`      | `true` if the cookie is temporary and expires at session end. |
| **expiresDate**   | `Date \| null` | Expiration date of the cookie, if specified.                  |

#### Example — Reading Cookies

```tsx
const response = await fetch("https://example.com/login")
for (const cookie of response.cookies) {
  console.log(`${cookie.name} = ${cookie.value}`)
}
```

#### Example — Manual Cookie Management

By default, **Scripting’s `fetch()` does not automatically store or send cookies**.
To reuse cookies across multiple requests, you can manually include them:

```tsx
const response = await fetch("https://example.com/login")
const cookies = response.cookies
const cookieHeader = cookies.map(c => `${c.name}=${c.value}`).join("; ")

const next = await fetch("https://example.com/dashboard", {
  headers: { "Cookie": cookieHeader },
})
```

This gives you **explicit cookie control** similar to browser developer tools.

***

## Relationship with Other Classes

| Class          | Description                                              |
| -------------- | -------------------------------------------------------- |
| **`Request`**  | Represents the HTTP request that produced this response. |
| **`Headers`**  | Manages response headers.                                |
| **`Data`**     | Represents binary data returned from the response body.  |
| **`FormData`** | Used when the response contains `multipart/form-data`.   |
| **`Cookie`**   | Represents a parsed HTTP cookie object.                  |

***

## Examples

### Example 1 — Handling JSON API Responses

```tsx
const response = await fetch("https://api.example.com/profile")
if (response.ok) {
  const user = await response.json()
  console.log(user.email)
} else {
  console.log("Error:", response.status, response.statusText)
}
```

***

### Example 2 — Downloading Binary Data

```tsx
const response = await fetch("https://example.com/photo.jpg")
const fileData = await response.data()
FileManager.write(fileData, "/local/photo.jpg")
```

***

### Example 3 — Reading Cookies from a Response

```tsx
const response = await fetch("https://example.com/login")
for (const cookie of response.cookies) {
  console.log(`Cookie: ${cookie.name} = ${cookie.value}`)
}
```

***

### Example 4 — Manual Cookie Persistence Between Requests

```tsx
const loginResponse = await fetch("https://example.com/login", {
  method: "POST",
  body: JSON.stringify({ username: "Tom", password: "1234" }),
  headers: { "Content-Type": "application/json" },
})

// Build a cookie header manually
const cookieHeader = loginResponse.cookies.map(c => `${c.name}=${c.value}`).join("; ")

// Use cookies in a new request
const dashboard = await fetch("https://example.com/dashboard", {
  headers: { "Cookie": cookieHeader },
})
console.log(await dashboard.text())
```

***

### Example 5 — Inspecting Metadata

```tsx
const response = await fetch("https://example.com/video.mp4")
console.log("MIME Type:", response.mimeType)
console.log("Expected Length:", response.expectedContentLength)
```

***

## Summary

The `Response` class in **Scripting** offers a rich and extensible interface for handling HTTP responses:

- Compatible with the standard Fetch API
- Adds native **cookie parsing** and management
- Supports **binary data streams** via the `Data` type
- Provides full access to headers, MIME type, and encoding
- Allows seamless use with `FormData` and `ReadableStream`



---
url: /guide/Utilities/Request/fetch.md
---

# fetch

The `fetch()` method initiates an HTTP/HTTPS network request and returns a `Promise` that resolves to a `Response` object.
It behaves similarly to the standard **Fetch API** available in browsers but includes **native extensions** optimized for Scripting’s iOS runtime environment — such as local file access, `Data` integration, custom redirect handling, abort control, and debugging labels.

***

## Definition

```ts
function fetch(url: string, init?: RequestInit): Promise<Response>
function fetch(request: Request): Promise<Response>
```

***

## Parameters

### 1. `url: string`

The URL to request.
It can be:

- A **network resource**, e.g. `"https://api.example.com/data"`
- A **local file URL**, e.g. `"file:///var/mobile/Containers/Data/Application/..."`

***

### 2. `init?: RequestInit`

An optional configuration object used to customize the request’s method, headers, body, timeout, abort signal, and other options.

```ts
type RequestInit = {
  method?: string;
  headers?: HeadersInit;
  body?: Data | FormData | string | ArrayBuffer;
  allowInsecureRequest?: boolean;
  handleRedirect?: (newRequest: RedirectRequest) => Promise<RedirectRequest | null>;
  shouldAllowRedirect?: (newRequest: Request) => Promise<boolean>; // deprecated
  timeout?: number; // seconds
  signal?: AbortSignal;
  cancelToken?: CancelToken; // deprecated
  debugLabel?: string;
}
```

#### Parameter Details

| Property                 | Type                                                                | Description                                                                                              |   |
| ------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | - |
| **method**               | `string`                                                            | The HTTP method, such as `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`. Defaults to `"GET"`.                    |   |
| **headers**              | `HeadersInit`                                                       | The request headers. Can be a `Headers` object, a key-value object, or an array of `[key, value]` pairs. |   |
| **body**                 | `Data` \| `FormData` \| `string` \| `ArrayBuffer`                   | The request body. Only used for methods other than `GET` or `HEAD`.                                      |   |
| **allowInsecureRequest** | `boolean`                                                           | Whether to allow HTTP requests when running in an HTTPS context. Defaults to `false`.                    |   |
| **handleRedirect**       | `(newRequest: RedirectRequest) => Promise<RedirectRequest \| null>` | Custom redirect handler. Return `null` to cancel the redirect.                                           |   |
| **shouldAllowRedirect**  | `(newRequest: Request) => Promise<boolean>`                         | Deprecated. Use `handleRedirect` instead.                                                                |   |
| **timeout**              | `number`                                                            | Timeout duration in seconds. Throws an `AbortError` when exceeded.                                       |   |
| **signal**               | `AbortSignal`                                                       | A signal object from `AbortController` that can abort the request.                                       |   |
| **cancelToken**          | `CancelToken`                                                       | Deprecated. Use `signal` instead.                                                                        |   |
| **debugLabel**           | `string`                                                            | A label shown in the log panel for debugging and tracing requests.                                       |   |

***

## Return Value

Returns a `Promise<Response>`.

The `Response` object represents the result of the request.
Even when the HTTP status code indicates failure (e.g., 404 or 500), `fetch` **resolves** successfully with a `Response`.
The Promise is **rejected** only when:

- The request cannot be completed (e.g., network error)
- The URL is malformed
- The request is aborted or times out

***

## Error Handling

| Error Type       | Trigger Condition                                                |
| ---------------- | ---------------------------------------------------------------- |
| **`TypeError`**  | Invalid URL, unsupported protocol, or incompatible request body. |
| **`AbortError`** | The request was aborted via `AbortController` or timed out.      |

***

## Examples

### Example 1 — Basic GET Request

```tsx
const response = await fetch("https://api.example.com/data")
if (response.ok) {
  const json = await response.json()
  console.log(json)
} else {
  console.log("Request failed:", response.status)
}
```

***

### Example 2 — POST Request with JSON Body

```tsx
const response = await fetch("https://api.example.com/posts", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Hello", content: "World" }),
})
const result = await response.json()
console.log(result)
```

***

### Example 3 — Uploading Files via `FormData`

```tsx
const form = new FormData()
form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "image.png")
form.append("user", "Tom")

const response = await fetch("https://api.example.com/upload", {
  method: "POST",
  body: form,
})
console.log(await response.json())
```

***

### Example 4 — Timeout Handling

```tsx
try {
  const response = await fetch("https://example.com/slow", { timeout: 10 })
  const text = await response.text()
  console.log(text)
} catch (err) {
  if (err.name === "AbortError") {
    console.log("Request aborted due to timeout")
  }
}
```

***

### Example 5 — Aborting Requests with `AbortController`

```tsx
const controller = new AbortController()

setTimeout(() => {
  controller.abort("User cancelled the request")
}, 3000)

try {
  const response = await fetch("https://example.com/large", { signal: controller.signal })
  const data = await response.text()
  console.log(data)
} catch (err) {
  if (err.name === "AbortError") {
    console.log("Request was manually aborted")
  }
}
```

***

### Example 6 — Custom Redirect Handling

```tsx
const response = await fetch("https://example.com/redirect", {
  handleRedirect: async (newRequest) => {
    console.log("Redirect detected:", newRequest.url)
    if (newRequest.url.includes("forbidden")) {
      return null // Cancel redirect
    }
    return newRequest // Allow redirect
  },
})
```

***

### Example 7 — Debug Label for Logging

```tsx
await fetch("https://api.example.com/status", {
  debugLabel: "Health Check",
})
// The request will be labeled "Health Check" in the log panel
```

***

## Relationship with Other Classes

| Class                                 | Description                                                                                                |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **`Request`**                         | Represents a network request. You can pass a `Request` object to `fetch(request)` to reuse configuration.  |
| **`Response`**                        | Represents the result of a network operation, with helper methods such as `.json()`, `.text()`, `.data()`. |
| **`AbortController` / `AbortSignal`** | Provides a way to abort requests programmatically.                                                         |
| **`FormData`**                        | Builds multipart/form-data bodies for file uploads and form submissions.                                   |
| **`Headers`**                         | Manages HTTP request and response headers.                                                                 |
| **`Data`**                            | Represents binary data and supports conversion to multiple formats (e.g., Base64, hex).                    |

***

## Additional Details

- **Cookie Management**:
  `fetch` does **not automatically store or send cookies**.
  Cookies from responses can be accessed via `response.cookies`.

- **Redirects**:
  Redirects are automatically followed unless overridden by `handleRedirect`.

- **Concurrency**:
  Each request runs independently and safely in parallel.

- **File Support**:
  You can upload local files using `Data.fromFile()` as the request body.

***

## Summary

The `fetch()` API in Scripting extends the standard web Fetch interface with native capabilities:

- Full iOS-native networking integration
- Support for `Data` binary objects
- File upload and download handling
- Timeout and abort control
- Custom redirect interception
- Local logging with `debugLabel`



---
url: /guide/Utilities/SQLite/Database and Connection.md
---

# Database and Connection

This section describes how to open SQLite databases, configure connections, and understand connection-related behaviors in Scripting.

SQLite is exposed as a **global namespace** in Scripting and can be used directly without importing.

***

## Opening a Database

### Opening a Disk Database

```ts
const dbPath = Path.join(
  FileManager.appGroupDocumentsDirectory,
  "app.db"
)
const db = SQLite.open(dbPath)
```

`SQLite.open` opens or creates a SQLite database located in the script’s data directory.

- If the database file does not exist, it will be created automatically
- Opening the same path multiple times will internally reuse database resources
- The returned `Database` instance is used for all subsequent operations

***

### Opening an In-Memory Database

```ts
const db = SQLite.openInMemory("temp")
```

`SQLite.openInMemory` creates a database that exists only in memory.

- In-memory databases are not persisted to disk
- All data is lost when the script ends or the database is released
- Suitable for temporary computations, testing, or intermediate results

The `name` parameter is used to distinguish different in-memory database instances.

***

## Database Configuration

An optional configuration object can be provided when opening a database:

```ts
const db = SQLite.open(dbPath, {
  foreignKeysEnabled: true,
  readonly: false,
  journalMode: "wal",
  busyMode: 5,
  maximumReaderCount: 5,
  label: "main-db"
})
```

***

### foreignKeysEnabled

```ts
foreignKeysEnabled: boolean
```

Controls whether foreign key constraints are enabled.

- `true`: Enables SQLite foreign key constraints (equivalent to `PRAGMA foreign_keys = ON`)
- `false`: Disables foreign key constraints

It is recommended to explicitly enable this option when using foreign keys.

***

### readonly

```ts
readonly: boolean
```

Controls whether the database is opened in read-only mode.

- `true`: Only read operations are allowed; all write operations will fail
- `false`: Both read and write operations are allowed

Read-only mode is useful for:

- Data inspection tools
- Analysis scripts
- Preventing accidental data modification

***

### journalMode

```ts
journalMode: "wal" | "default"
```

Specifies the SQLite journal mode.

- `"wal"`: Enables Write-Ahead Logging, suitable for concurrent read/write workloads
- `"default"`: Uses SQLite’s default journal mode

In most scenarios, `"wal"` is recommended.

***

### busyMode

```ts
busyMode: "immediateError" | number
```

Controls the behavior when the database is locked.

- `"immediateError"`: Immediately throws an error if the database is busy
- `number`: Maximum time to wait for the lock to be released, in seconds

Example:

```ts
busyMode: 3
```

This configuration allows the database to wait up to 3 seconds before failing.

***

### maximumReaderCount

```ts
maximumReaderCount: number
```

Limits the maximum number of concurrent reader connections.

This option is used to control concurrency and resource usage:

- Lower values reduce resource consumption
- Higher values allow greater read concurrency

***

### label

```ts
label: string | null
```

Assigns a human-readable label to the database connection.

This label is primarily used for:

- Debugging
- Logging
- Internal diagnostics

It does not affect database behavior.

***

## Database Instance

Both `SQLite.open` and `SQLite.openInMemory` return a `Database` instance:

```ts
const db: Database
```

The `Database` instance:

- Represents a logical database connection
- Serves as the entry point for SQL execution, transactions, and schema operations
- Does not expose underlying connections, threads, or queues

Connection creation, lifecycle management, and thread scheduling are handled internally.

***

## Concurrency and Threading Model

Concurrency control and thread management are handled entirely by Scripting:

- JavaScript code does not directly interact with threads
- All database operations are executed through internal queues with controlled concurrency
- Configuration options such as `busyMode` and `maximumReaderCount` influence internal scheduling behavior

This design ensures that the SQLite API remains:

- Predictable
- Safe to use without manual locking
- Free from cross-thread access issues at the script level

***

## Usage Recommendations

- Use disk databases for persistent data storage
- Use in-memory databases for temporary or test data
- Explicitly enable `foreignKeysEnabled` when foreign key constraints are required
- Use `"wal"` journal mode for concurrent workloads
- Consider read-only mode for inspection or analysis scripts

***

## Next Steps

After opening a database, typical next steps include:

- Executing SQL statements and querying data
- Performing batch writes using transactions
- Creating and managing tables and indexes

Continue with the following sections:

- **Executing SQL & Queries**
- **Transactions**
- **Schema Management**



---
url: /guide/Utilities/SQLite/Executing SQL and Query.md
---

# Executing SQL and Query

This section explains how to execute SQL statements, bind parameters, and query data using SQLite.

All operations are performed through a `Database` instance. SQLite handles connection management, threading, and scheduling internally, allowing JavaScript code to focus solely on SQL and data.

***

## Executing SQL

### execute

```ts
db.execute(sql: string, arguments?: Arguments): Promise<void>
```

`execute` runs one or multiple SQL statements that do not return result sets. It is commonly used for:

- Creating or modifying table schemas
- Inserting, updating, or deleting data
- Executing PRAGMA statements

Example:

```ts
await db.execute(
  "CREATE TABLE user (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)"
)
```

```ts
await db.execute(
  "UPDATE user SET age = ? WHERE name = ?",
  [19, "Tom"]
)
```

***

## Parameter Binding

SQLite supports two parameter binding styles: **positional parameters** and **named parameters**.

***

### Positional Parameters

```ts
await db.execute(
  "INSERT INTO user (name, age) VALUES (?, ?)",
  ["Tom", 18]
)
```

Values in the argument array are bound to `?` placeholders in order.

***

### Named Parameters

```ts
await db.execute(
  "INSERT INTO user (name, age) VALUES (:name, :age)",
  { name: "Lucy", age: 20 }
)
```

Named parameters are passed as an object. The object keys must match the parameter names used in the SQL statement.

***

### DatabaseValue Types

Bound values may be of the following types:

- `string`
- `number`
- `boolean`
- `Data`
- `Date`
- `null`

`Date` and `Data` values are stored using SQLite-compatible representations.

***

## Querying Data

SQLite provides three query methods, each intended for a different use case.

***

### fetchAll

```ts
db.fetchAll<T>(sql: string, arguments?: Arguments): Promise<T[]>
```

Executes a query and returns **all result rows**.

Example:

```ts
const users = await db.fetchAll<{ name: string; age: number }>(
  "SELECT name, age FROM user"
)
```

If the query returns no rows, an empty array is returned.

***

### fetchOne

```ts
db.fetchOne<T>(sql: string, arguments?: Arguments): Promise<T>
```

Executes a query and returns **the first result row**.

Example:

```ts
const user = await db.fetchOne<{ name: string }>(
  "SELECT name FROM user WHERE age = ?",
  [18]
)
```

Typical use cases include:

- Queries expected to return exactly one row (for example, by primary key)
- Aggregate queries such as `COUNT(*)`

If the query returns no rows, this method throws an error.

***

### fetchSet

```ts
db.fetchSet<T>(sql: string, arguments?: Arguments): Promise<T[]>
```

Executes a query and returns a **deduplicated result set**.

This method is useful when:

- Querying for unique values
- Logical de-duplication is required at the result level

Example:

```ts
const names = await db.fetchSet<{ name: string }>(
  "SELECT name FROM user"
)
```

Duplicate rows are removed from the returned result.

***

## Type Mapping

Query result values are automatically mapped to JavaScript types:

- SQLite INTEGER → `number`
- SQLite REAL → `number`
- SQLite TEXT → `string`
- SQLite BLOB → `Data`
- SQLite NULL → `null`

The shape of the returned objects is determined by the SQL query. SQLite does not enforce strict matching with the generic type `T`, but keeping them aligned is recommended for clarity and type safety.

***

## Error Handling

The following situations may cause methods to throw errors:

- SQL syntax errors
- Parameter count or name mismatches
- Constraint violations (for example, unique or foreign key constraints)
- `fetchOne` returning no rows
- Database lock timeouts caused by `busyMode`

Use `try / catch` when error handling is required:

```ts
try {
  await db.execute("INSERT INTO user (name) VALUES (?)", ["Tom"])
} catch (e) {
  console.error(e)
}
```

***

## Usage Recommendations

- Use `execute` for SQL statements that do not return results
- Use `fetchAll` when multiple rows are expected
- Use `fetchOne` when exactly one row is required
- Use `fetchSet` when deduplicated results are needed
- Always prefer parameter binding over SQL string concatenation
- Wrap complex write operations in transactions

***

## Next Steps

When atomicity is required across multiple write operations, or when changes must be rolled back on failure, continue with:

- **Transactions**



---
url: /guide/Utilities/SQLite/Overview.md
---

# Overview

The SQLite module provides a structured, type-friendly, and predictable API for working with SQLite databases in Scripting.

SQLite is exposed as a **global namespace** and does not require importing. It supports both disk-based and in-memory databases, and covers common use cases such as executing SQL statements, performing queries, managing transactions, defining schemas, and inspecting database structures.

***

## Getting Started

### Opening a Database

```ts
const dbPath = Path.join(FileManager.appGroupDocumentsDirectory, "app.db")
const db = SQLite.open(dbPath)
```

Opens a SQLite database located in the script’s data directory. If the file does not exist, it will be created automatically.

To open an in-memory database:

```ts
const db = SQLite.openInMemory("temp")
```

***

### Executing SQL

```ts
await db.execute(
  "CREATE TABLE user (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)"
)

await db.execute(
  "INSERT INTO user (name, age) VALUES (?, ?)",
  ["Tom", 18]
)
```

Both positional parameters and named parameters are supported.

***

### Querying Data

```ts
const users = await db.fetchAll<{ name: string; age: number }>(
  "SELECT name, age FROM user"
)

const user = await db.fetchOne<{ name: string }>(
  "SELECT name FROM user WHERE age = ?",
  [18]
)
```

***

### Using Transactions

```ts
await db.transaction([
  { sql: "INSERT INTO user (name, age) VALUES (?, ?)", args: ["Tom", 18] },
  { sql: "INSERT INTO user (name, age) VALUES (?, ?)", args: ["Lucy", 20] }
])
```

Transactions are declared as an ordered list of steps. All steps are executed sequentially, and any failure will cause the entire transaction to roll back.

***

## Core Capabilities

The SQLite module provides the following core capabilities:

- Database connection management
- SQL execution with parameter binding
- Structured data querying
- Explicit transaction control
- Table and index creation and removal
- Database schema inspection

***

## Documentation Structure

The SQLite documentation is organized by functional areas. Refer to the following sections based on your needs:

- **Database & Connection**
  Opening databases, configuration options, read-only mode, and concurrency behavior

- **Executing SQL & Queries**
  Executing SQL statements, parameter binding rules, and query APIs

- **Transactions**
  Transaction model, transaction kinds, and design constraints

- **Schema Management**
  Creating and managing tables and indexes using structured APIs

- **Schema Introspection**
  Inspecting tables, columns, primary keys, foreign keys, and indexes

- **Types Reference**
  Type definitions and enums used throughout the SQLite module

***

## Use Cases

The SQLite module is suitable for the following scenarios:

- Local data persistence
- Script-level caching and state storage
- Managing small to medium-sized structured datasets
- Building SQLite-based utility scripts
- Data migration, inspection, and debugging tools



---
url: /guide/Utilities/SQLite/Schema Introspection.md
---

# Schema Introspection

This section explains how to inspect and analyze database structures using SQLite’s schema introspection APIs.

Schema Introspection allows scripts to query database structure information at runtime, including tables, columns, primary keys, foreign keys, and indexes. These capabilities are commonly used for:

- Data migrations and version management
- Tooling scripts (such as database browsers or analyzers)
- Runtime schema validation
- Debugging and diagnostics

***

## Getting the Schema Version

### schemaVersion

```ts
db.schemaVersion(): Promise<number>
```

Returns the current database schema version.

This value is typically used to:

- Determine whether a database migration is required
- Integrate with external schema versioning logic

Example:

```ts
const version = await db.schemaVersion()
```

***

## Checking Table Existence

### tableExists

```ts
db.tableExists(tableName: string, schemaName?: string): Promise<boolean>
```

Checks whether a specified table exists.

- `schemaName` defaults to the main schema
- Returns `true` if the table exists

Example:

```ts
const exists = await db.tableExists("user")
```

***

## Inspecting Columns

### columnsIn

```ts
db.columnsIn(tableName: string, schemaName?: string): Promise<ColumnInfo[]>
```

Returns structural information for all columns in the specified table.

***

### ColumnInfo

```ts
type ColumnInfo = {
  name: string
  type: string
  defaultValueSQL: string | null
  isNotNull: boolean
  primaryKeyIndex: number
}
```

Field descriptions:

- `name`: column name
- `type`: column type
- `defaultValueSQL`: SQL expression for the default value
- `isNotNull`: whether the column is NOT NULL
- `primaryKeyIndex`: order of the column within the primary key (0 if not part of the primary key)

Example:

```ts
const columns = await db.columnsIn("user")
```

***

## Inspecting Primary Keys

### primaryKey

```ts
db.primaryKey(tableName: string, schemaName?: string): Promise<PrimaryKeyInfo>
```

Returns primary key information for the specified table.

***

### PrimaryKeyInfo

```ts
type PrimaryKeyInfo = {
  columns: string[]
  rowIDColumn: string | null
  isRowID: boolean
}
```

Field descriptions:

- `columns`: names of the primary key columns
- `rowIDColumn`: name of the associated rowid column, if applicable
- `isRowID`: whether SQLite’s implicit rowid is used as the primary key

Example:

```ts
const pk = await db.primaryKey("user")
```

***

## Inspecting Foreign Keys

### foreignKeys

```ts
db.foreignKeys(tableName: string, schemaName?: string): Promise<ForeignKeyInfo[]>
```

Returns all foreign key definitions for the specified table.

***

### ForeignKeyInfo

```ts
type ForeignKeyInfo = {
  id: number
  originColumns: string[]
  destinationTable: string
  destinationColumns: string[]
  mapping: {
    origin: string
    destination: string
  }[]
}
```

Field descriptions:

- `id`: foreign key identifier
- `originColumns`: columns in the current table
- `destinationTable`: referenced table
- `destinationColumns`: referenced columns
- `mapping`: one-to-one column mapping

Example:

```ts
const fks = await db.foreignKeys("order")
```

***

## Inspecting Indexes

### indexes

```ts
db.indexes(tableName: string, schemaName?: string): Promise<IndexInfo[]>
```

Returns all indexes defined on the specified table.

***

### IndexInfo

```ts
type IndexInfo = {
  name: string
  columns: string[]
  isUnique: boolean
  origin: "createIndex" | "primaryKeyConstraint" | "uniqueConstraint"
}
```

Field descriptions:

- `name`: index name
- `columns`: columns included in the index
- `isUnique`: whether the index is unique
- `origin`: source of the index

  - `"createIndex"`: created explicitly via `createIndex`
  - `"primaryKeyConstraint"`: generated by a primary key constraint
  - `"uniqueConstraint"`: generated by a unique constraint

Example:

```ts
const indexes = await db.indexes("user")
```

***

## Checking Unique Key Combinations

### isTableHasUniqueKeys

```ts
db.isTableHasUniqueKeys(
  tableName: string,
  uniqueKeys: string[]
): Promise<boolean>
```

Checks whether the specified table has a unique constraint or unique index that exactly matches the given column combination.

Example:

```ts
const hasUnique = await db.isTableHasUniqueKeys(
  "user",
  ["email"]
)
```

This method is commonly used to:

- Determine whether a unique index needs to be created
- Avoid redefining constraints during schema initialization or migration

***

## Usage Recommendations

- Inspect existing schema state before applying structural changes
- Prefer introspection over assumptions in migration logic
- Combine introspection APIs with tooling scripts for analysis or visualization
- Avoid calling schema inspection APIs in high-frequency execution paths

***

## Summary

Schema Introspection provides runtime visibility into database structure, enabling scripts to safely and reliably understand the current database state.

It is commonly used in combination with:

- **Schema Management** for defining and modifying structures
- **Transactions** to ensure atomic schema changes
- **Executing SQL & Queries** for data operations based on known schemas



---
url: /guide/Utilities/SQLite/Schema Management.md
---

# Schema Management

This section explains how to create, modify, and remove tables and indexes using SQLite’s structured schema APIs.

Instead of relying solely on raw SQL strings, Schema Management provides a **declarative, readable, and safer** approach to defining database structures, making it suitable for long-term, maintainable data models.

***

## Creating Tables

### createTable

```ts
db.createTable(
  name: string,
  options: {
    columns: ColumnDefinition[]
    ifNotExists?: boolean
  }
): Promise<void>
```

`createTable` creates a new table.

Example:

```ts
await db.createTable("user", {
  ifNotExists: true,
  columns: [
    { name: "id", type: "INTEGER", primaryKey: true, autoIncrement: true },
    { name: "name", type: "TEXT", notNull: true },
    { name: "age", type: "INTEGER" }
  ]
})
```

***

### ColumnDefinition

```ts
type ColumnDefinition = {
  name: string
  type: string
  primaryKey?: boolean
  autoIncrement?: boolean
  notNull?: boolean
  unique?: boolean
  indexed?: boolean
  checkSQL?: string
  collation?: DatabaseCollation
  defaultValue?: DatabaseValue
  defaultSQL?: string
  references?: ColumnReferences
}
```

Common column attributes include:

- `name`: column name
- `type`: SQLite column type (for example, `INTEGER`, `TEXT`)
- `primaryKey`: whether the column is a primary key
- `autoIncrement`: enables auto-increment (only valid for integer primary keys)
- `notNull`: applies a NOT NULL constraint
- `unique`: applies a UNIQUE constraint
- `indexed`: creates an index on the column
- `checkSQL`: CHECK constraint expression
- `collation`: column collation rule
- `defaultValue`: default value (parameterized form)
- `defaultSQL`: default value (raw SQL expression)
- `references`: foreign key reference definition

***

### Default Values

`defaultValue` and `defaultSQL` are mutually exclusive. Use one or the other.

```ts
{ name: "createdAt", type: "INTEGER", defaultSQL: "CURRENT_TIMESTAMP" }
```

```ts
{ name: "status", type: "TEXT", defaultValue: "active" }
```

***

### Foreign Key References

```ts
references?: {
  table: string
  column?: string
  onDelete?: "cascade" | "restrict" | "setNull" | "setDefault"
  onUpdate?: "cascade" | "restrict" | "setNull" | "setDefault"
  deferred?: boolean
}
```

Example:

```ts
{
  name: "userId",
  type: "INTEGER",
  references: {
    table: "user",
    column: "id",
    onDelete: "cascade"
  }
}
```

***

## Renaming Tables

### renameTable

```ts
db.renameTable(name: string, newName: string): Promise<void>
```

Example:

```ts
await db.renameTable("user", "users")
```

***

## Dropping Tables

### dropTable

```ts
db.dropTable(name: string): Promise<void>
```

Example:

```ts
await db.dropTable("temp_data")
```

***

## Creating Indexes

### createIndex

```ts
db.createIndex(
  name: string,
  options: {
    table: string
    columns: string[]
    unique?: boolean
    ifNotExists?: boolean
    condition?: string
  }
): Promise<void>
```

Example:

```ts
await db.createIndex("idx_user_name", {
  table: "user",
  columns: ["name"],
  unique: false
})
```

***

### Partial Indexes

```ts
await db.createIndex("idx_active_user", {
  table: "user",
  columns: ["name"],
  condition: "age >= 18"
})
```

***

## Dropping Indexes

### dropIndex

```ts
db.dropIndex(name: string): Promise<void>
```

Example:

```ts
await db.dropIndex("idx_user_name")
```

***

### dropIndexOn

```ts
db.dropIndexOn(tableName: string, columns: string[]): Promise<void>
```

Drops the index associated with the specified table and column combination.

Example:

```ts
await db.dropIndexOn("user", ["name"])
```

***

## Design Principles

The Schema Management API follows these principles:

- **Structure over string concatenation**
  Reduces the risk of SQL syntax errors and improves readability

- **Declarative over imperative**
  Clearly describes what the schema should be, not how to assemble SQL

- **One-to-one mapping with SQLite capabilities**
  Avoids hidden behavior or unexpected abstractions

***

## Usage Recommendations

- Prefer `createTable` for long-lived schemas
- Use `ifNotExists` to avoid duplicate creation
- Create indexes explicitly for frequently queried columns
- Ensure `foreignKeysEnabled` is enabled when using foreign keys
- Perform schema changes within transactions or migration logic

***

## Next Steps

After creating and managing schemas, you may want to:

- Inspect existing database structures
- Retrieve column, primary key, and foreign key information
- Analyze indexes and constraints

Continue with:

- **Schema Introspection**



---
url: /guide/Utilities/SQLite/Transaction.md
---

# Transaction

This section describes the transaction model, transaction types.

The SQLite transaction API uses a **step-based, declarative model** to provide predictable, controlled, and safe transaction behavior at the scripting level.

***

## Transaction Overview

A transaction groups multiple database operations into a single atomic unit:

- All steps succeed → the transaction is committed
- Any step fails → the transaction is rolled back
- After rollback, the database remains unchanged

SQLite guarantees consistency and isolation internally. JavaScript code does not need to manually handle rollback logic.

***

## transaction

```ts
db.transaction(
  steps: TransactionStep[],
  options?: {
    kind?: "deferred" | "immediate" | "exclusive"
  }
): Promise<void>
```

`transaction` executes a transaction defined by an ordered list of SQL steps.

***

## Transaction Steps

```ts
type TransactionStep = {
  sql: string
  args?: Arguments | null
}
```

Each transaction step consists of:

- `sql`: the SQL statement to execute
- `args`: optional bound parameters

Example:

```ts
await db.transaction([
  {
    sql: "INSERT INTO user (name, age) VALUES (?, ?)",
    args: ["Tom", 18]
  },
  {
    sql: "INSERT INTO user (name, age) VALUES (?, ?)",
    args: ["Lucy", 20]
  }
])
```

Steps are executed sequentially in the order they are declared.

***

## Transaction Kinds

Transactions support three kinds, corresponding to SQLite’s native transaction modes:

```ts
kind?: "deferred" | "immediate" | "exclusive"
```

***

### deferred

The default transaction kind.

- No locks are acquired when the transaction begins
- Locks are obtained only when the first read or write occurs
- Suitable for most general-purpose transaction scenarios

***

### immediate

- Attempts to acquire a write lock immediately when the transaction begins
- Fails immediately if the write lock cannot be acquired
- Useful when subsequent write operations must be guaranteed to proceed

***

### exclusive

- Acquires an exclusive lock when the transaction begins
- Blocks all other read and write operations
- Intended for scenarios that require full database exclusivity

***

## Error Handling and Rollback

A transaction will be rolled back automatically if any of the following occur:

- SQL execution errors
- Parameter binding errors
- Constraint violations (unique, foreign key, etc.)
- Database lock conflicts

Example:

```ts
try {
  await db.transaction([
    { sql: "INSERT INTO user (id, name) VALUES (1, 'Tom')" },
    { sql: "INSERT INTO user (id, name) VALUES (1, 'Lucy')" }
  ])
} catch (e) {
  console.error("Transaction failed:", e)
}
```

***

## Usage Recommendations

- Group operations that must succeed together into a single transaction
- Prefer the default `deferred` transaction kind
- Use `immediate` when early write-lock acquisition is required
- Avoid long-running or unrelated work inside transactions
- Do not rely on conditional logic to determine transaction steps

***

## Next Steps

After working with transactions, you may want to:

- Create and manage table schemas
- Define indexes and constraints
- Inspect database schema information

Continue with:

- **Schema Management**
- **Schema Introspection**



---
url: /guide/Utilities/SSH/SFTP Client.md
---

# SFTP Client

`SFTPClient` provides access to a remote file system over an SSH connection using the SFTP protocol.
It supports directory operations, file management, attribute retrieval, and path resolution.
Files can be opened using `openFile()`, which returns an `SFTPFile` instance for reading and writing.

Instances of this class are typically created through:

```ts
const sftp = await ssh.openSFTP()
```

***

## Properties

### `readonly isActive: boolean`

Indicates whether the SFTP connection is still active.

- `true`: The connection is active
- `false`: The connection is closed or invalid

***

## Methods

***

## `close(): Promise<void>`

Closes the SFTP connection.

#### Returns:

- A promise that resolves when the connection is successfully closed.

#### Example:

```ts
await sftp.close()
```

***

## `readDirectory(atPath: string): Promise<DirectoryEntry[]>`

Reads the contents of a directory.

### Parameters:

- **`atPath`**: The path of the directory to read.

### Returns:

An array of directory entries:

```ts
{
  filename: string
  longname: string
  attributes: {
    size?: number
    userId?: number
    groupId?: number
    accessTime?: Date
    modificationTime?: Date
    permissions?: number
  }
}[]
```

### Example:

```ts
const items = await sftp.readDirectory("/var/log")
```

***

## `createDirectory(atPath: string): Promise<void>`

Creates a directory at the specified path.

### Parameters:

- `atPath`: The path where the directory should be created.

### Returns:

A promise that resolves when the directory is created.

### Example:

```ts
await sftp.createDirectory("/home/user/new-folder")
```

***

## `removeDirectory(atPath: string): Promise<void>`

Removes a directory. The directory must be empty.

### Parameters:

- `atPath`: The directory path to remove.

### Example:

```ts
await sftp.removeDirectory("/home/user/empty-dir")
```

***

## `rename(oldPath: string, newPath: string): Promise<void>`

Renames or moves a file or directory.

### Parameters:

- `oldPath`: The current path.
- `newPath`: The new path.

### Example:

```ts
await sftp.rename("/home/user/a.txt", "/home/user/b.txt")
```

***

## `getAttributes(atPath: string): Promise<FileAttributes>`

Retrieves file or directory metadata.

### Returns:

```ts
{
  size?: number
  userId?: number
  groupId?: number
  accessTime?: Date
  modificationTime?: Date
  permissions?: number
}
```

### Example:

```ts
const attrs = await sftp.getAttributes("/etc/hosts")
```

***

## `openFile(filePath: string, flags: SFTPOpenFileFlags | SFTPOpenFileFlags[]): Promise<SFTPFile>`

Opens a file with the specified flags and returns an `SFTPFile` instance.

### Parameters:

- `filePath`: The path of the file to open.
- `flags`: One or more of the following:

```
"read" | "write" | "append" | "create" | "truncate" | "forceCreate"
```

### Returns:

- A promise that resolves to an `SFTPFile` object.

### Example:

```ts
const file = await sftp.openFile("/home/user/log.txt", ["read"])
const data = await file.readAll()
await file.close()
```

***

## `remove(atPath: string): Promise<void>`

Removes a file.

### Parameters:

- `atPath`: The file path to remove.

### Example:

```ts
await sftp.remove("/home/user/old.txt")
```

***

## `getRealPath(atPath: string): Promise<string>`

Resolves symbolic links, `~`, and relative paths to an absolute path.

### Example:

```ts
const real = await sftp.getRealPath("~/documents")
```

***

## Usage Example

```ts
const ssh = await SSHClient.connect({
  host: "192.168.1.10",
  authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "pass")
})

const sftp = await ssh.openSFTP()

// Read a directory
const list = await sftp.readDirectory("/home/user")

// Open a file and read contents
const file = await sftp.openFile("/home/user/info.txt", "read")
const data = await file.readAll()
await file.close()

// Create a directory
await sftp.createDirectory("/home/user/new-folder")

// Delete a file
await sftp.remove("/home/user/temp.txt")

await sftp.close()
```



---
url: /guide/Utilities/SSH/SFTP File.md
---

# SFTP File

`SFTPFile` represents an opened remote file accessed through an SFTP session.
It provides low-level operations such as reading, writing, retrieving attributes, and closing the file.

Instances of this class are typically obtained through:

```ts
const file = await sftp.openFile(path, flags)
```

***

## Properties

***

### `readonly isActive: boolean`

Indicates whether the file handle is still open.

- `true`: The file is open and can be used
- `false`: The file has been closed or is no longer valid

***

## Methods

***

## `readAttributes(): Promise<FileAttributes>`

Reads metadata attributes of the file.

### Returns:

An object containing file attributes:

```ts
{
  size?: number
  userId?: number
  groupId?: number
  accessTime?: Date
  modificationTime?: Date
  permissions?: number
}
```

### Example:

```ts
const attrs = await file.readAttributes()
console.log(attrs.size)
```

***

## `read(options?: { from?: number, length?: number }): Promise<Data>`

Reads data from the file with optional offset and length.

### Parameters:

- `from?`: The byte offset to start reading from. Defaults to `0`.
- `length?`: The number of bytes to read. Defaults to reading until the end of the file.

### Returns:

- A `Promise<Data>` containing the read bytes.

### Example:

```ts
const data = await file.read({ from: 100, length: 50 })
```

***

## `readAll(): Promise<Data>`

Reads the entire contents of the file.

### Returns:

- A `Promise<Data>` containing all file data.

### Example:

```ts
const data = await file.readAll()
```

***

## `write(data: Data, at?: number): Promise<void>`

Writes data to the file.

### Parameters:

- `data`: The binary data to write.
- `at?`: The byte offset at which to start writing.

  - If omitted, behavior depends on the flags used to open the file:

    - `"append"` will write at the end of the file.
    - `"write"` will write from offset 0 unless the implementation maintains a current offset.

### Returns:

- A promise that resolves when the write completes.

### Example:

```ts
await file.write(Data.fromRawString("Hello world"))
```

***

## `close(): Promise<void>`

Closes the file handle.
After closing, `isActive` becomes `false`, and no further reads or writes are allowed.

### Example:

```ts
await file.close()
```

***

## Usage Example

```ts
// Open file in read mode
const file = await sftp.openFile("/home/user/info.txt", ["read"])

// Get file attributes
const attrs = await file.readAttributes()

// Read the entire file
const allData = await file.readAll()

// Read part of the file
const partialData = await file.read({ from: 50, length: 100 })

// Close the file
await file.close()
```



---
url: /guide/Utilities/SSH/SSH Authentication Method.md
---

# SSH Authentication Method

Represents a method for authenticating with an SSH server. This class provides static methods for creating different types of SSH authentication strategies, including password-based, RSA key, ED25519, and ECDSA (P-256, P-384, P-521) private key authentication.

This class is essential when connecting to an SSH server using the `SSHClient.connect()` method.

## Static Methods

### `static passwordBased(username: string, password: string): SSHAuthenticationMethod`

Creates a password-based authentication method.

#### Parameters:

- `username` (string):
  The username to use when logging into the SSH server.

- `password` (string):
  The password corresponding to the provided username.

#### Returns:

- An instance of `SSHAuthenticationMethod` configured for password-based login.

#### Example:

```ts
const auth = SSHAuthenticationMethod.passwordBased("user1", "mypassword")
```

***

### `static rsa(username: string, sshRsa: Data, decryptionKey?: Data): SSHAuthenticationMethod | null`

Creates an RSA private key–based authentication method.

#### Parameters:

- `username` (string):
  The username for SSH login.

- `sshRsa` (`Data`):
  The RSA private key in OpenSSH format. You can load the key using the `Data.fromString()` or similar method.

- `decryptionKey` (`Data`, optional):
  If the private key is encrypted, provide the decryption password as a `Data` object.

#### Returns:

- An instance of `SSHAuthenticationMethod` configured with RSA authentication, or `null` if the key is invalid.

#### Example:

```ts
const rsaKey = Data.fromString(privateKeyContent)!
const auth = SSHAuthenticationMethod.rsa("user1", rsaKey)
```

***

### `static ed25519(username: string, sshEd25519: Data, decryptionKey?: Data): SSHAuthenticationMethod | null`

Creates an ED25519 private key–based authentication method.

#### Parameters:

- `username` (string):
  The SSH username.

- `sshEd25519` (`Data`):
  The ED25519 private key content.

- `decryptionKey` (`Data`, optional):
  Optional decryption key if the private key is encrypted.

#### Returns:

- An instance of `SSHAuthenticationMethod`, or `null` if the key is not valid.

#### Example:

```ts
const edKey = Data.fromString(ed25519KeyContent)!
const auth = SSHAuthenticationMethod.ed25519("user1", edKey)
```

***

### `static p256(username: string, pemRepresentation: string): SSHAuthenticationMethod | null`

Creates a P-256 (ECDSA) authentication method from a PEM-formatted private key.

#### Parameters:

- `username` (string):
  The username for SSH login.

- `pemRepresentation` (string):
  The PEM-formatted private key string for ECDSA P-256.

#### Returns:

- An instance of `SSHAuthenticationMethod`, or `null` if the PEM is not valid.

#### Example:

```ts
const auth = SSHAuthenticationMethod.p256("user1", pemKeyContent)
```

***

### `static p384(username: string, pemRepresentation: string): SSHAuthenticationMethod | null`

Creates a P-384 (ECDSA) authentication method using a PEM-formatted private key.

#### Parameters:

- `username` (string):
  The SSH username.

- `pemRepresentation` (string):
  The PEM-formatted private key string.

#### Returns:

- An instance of `SSHAuthenticationMethod`, or `null` if the PEM format is invalid.

***

### `static p521(username: string, pemRepresentation: string): SSHAuthenticationMethod | null`

Creates a P-521 (ECDSA) authentication method using a PEM-formatted private key.

#### Parameters:

- `username` (string):
  The SSH username.

- `pemRepresentation` (string):
  The PEM-formatted private key string.

#### Returns:

- An instance of `SSHAuthenticationMethod`, or `null` if the PEM format is invalid.

***

## Usage Example

```ts
// Example with password
const passwordAuth = SSHAuthenticationMethod.passwordBased("root", "secret123")

// Example with RSA private key
const privateKey = await FileManager.readAsData("/path/to/id_rsa")
const rsaAuth = SSHAuthenticationMethod.rsa("root", privateKey)

// Connect to server
const ssh = await SSHClient.connect({
  host: "192.168.0.1",
  authenticationMethod: rsaAuth
})
```



---
url: /guide/Utilities/SSH/SSH Client.md
---

# SSH Client

The `SSHClient` class provides an interface for connecting to a remote SSH server, executing commands, opening TTY or PTY sessions, transferring files via SFTP, and performing multi-hop SSH jumps. It supports both command-based and interactive terminal-based workflows.

This class is central to establishing and managing SSH sessions in your script.

***

## Static Methods

### `SSHClient.connect(options): Promise<SSHClient>`

Establishes a connection to a remote SSH server.

#### Parameters:

- `options` (`object`):

  - `host` (`string`):
    The hostname or IP address of the SSH server.

  - `port?` (`number`):
    The port number to connect to. Defaults to `22`.

  - `authenticationMethod` (`SSHAuthenticationMethod`):
    The authentication method to use (e.g., password, RSA key).

  - `trustedHostKeys?` (`string[]`):
    Optional list of trusted server public keys. If provided, the client will validate the server against this list.

  - `reconnect?` (`"never" | "once" | "always"`):
    Optional strategy for reconnecting if the connection drops. Default is `"never"`.

#### Returns:

- A `Promise` that resolves to an `SSHClient` instance upon successful connection.

#### Example:

```ts
const ssh = await SSHClient.connect({
  host: "192.168.0.10",
  authenticationMethod: SSHAuthenticationMethod.passwordBased("root", "password")
})
```

***

## Properties

### `onDisconnect: (() => void) | null`

Callback function to be invoked when the SSH connection is lost or closed.

#### Example:

```ts
ssh.onDisconnect = () => {
  console.log("Disconnected from SSH server.")
}
```

***

## Instance Methods

### `executeCommand(command: string, options?): Promise<string | Data>`

Executes a shell command on the remote server and returns its output.

#### Parameters:

- `command` (`string`):
  The command to execute.

- `options?` (`object`):

  - `maxResponseSize?` (`number`):
    Maximum number of bytes to return.

  - `includeStderr?` (`boolean`):
    If `true`, includes standard error output in the result.

  - `inShell?` (`boolean`):
    If `true`, executes the command inside a shell (e.g., `sh -c`). Default is `false`.

  - `encoding?` (`"utf8" | "ascii" | "binary"`):
    How to decode the command output. Defaults to `"utf8"`.
    - `"utf8"` and `"ascii"`: lossy decode — invalid bytes are replaced with `U+FFFD`. The result is a `string`.
    - `"binary"`: returns raw bytes as `Data` with no decoding. Use this for commands whose output may contain binary or terminal control characters (e.g. `softwareupdate -l`, commands that emit `\r` progress bars or ANSI escapes). You can then post-process the bytes yourself (strip control chars, decode with a different encoding, etc.).

#### Returns:

- A `Promise` that resolves to the command output. Returns `string` when `encoding` is `"utf8"` (default) or `"ascii"`, `Data` when `encoding` is `"binary"`.

#### Example:

```ts
// default utf8 decoding
const result = await ssh.executeCommand("uname -a")

// binary mode: keep raw bytes so control characters can be stripped manually
const raw = await ssh.executeCommand("softwareupdate -l", { encoding: "binary" })
// raw is Data — decode after cleaning if needed
const clean = raw.toDecodedString()
```

***

### `executeCommandStream(command, onOutput, options?): Promise<void>`

Executes a command and streams its output line-by-line.

#### Parameters:

- `command` (`string`):
  The command to run.

- `onOutput` (`function`):
  Callback `(data: Data, isStderr: boolean) => boolean`
  Called for each line of output. Return `false` to stop receiving output.

- `options?`:

  - `inShell?` (`boolean`):
    Whether to run the command in a shell.

#### Returns:

- A `Promise` that resolves when the command completes.

#### Example:

```ts
const output = Data.fromIntArray([])
await ssh.executeCommandStream("ping -c 4 google.com", (data, isStderr) => {
  output.append(data)
  return true
})
console.log(output.toDecodedString()())
```

***

### `withPTY(options): Promise<TTYStdinWriter>`

Opens a PTY (pseudo-terminal) session.

#### Parameters:

- `options` (`object`):

  - `wantReply?` (`boolean`):
    Whether to wait for a reply from the server. Defaults to `true`.

  - `term?` (`string`):
    Terminal type (default is `"xterm"`).

  - `terminalCharacterWidth?` (`number`):
    Terminal character width. Default is `80`.

  - `terminalRowHeight?` (`number`):
    Terminal row height. Default is `24`.

  - `terminalPixelWidth?` (`number`):
    Terminal pixel width. Default is `0`.

  - `terminalPixelHeight?` (`number`):
    Terminal pixel height. Default is `0`.

  - `onOutput` (`function`):
    Callback `(data: Data, isStderr: boolean) => boolean` for receiving terminal output.

  - `onError?` (`function`):
    Optional error callback `(error: string) => void`.

#### Returns:

- A `Promise` that resolves to a `TTYStdinWriter` instance.

#### Example:

```ts
let output: Data | undefined
let timerId: number | undefined
const writer = await ssh.withPTY({
  onOutput: (data, isStderr) => {
    if (output == null) {
      output = data
    } else {
      output.append(data)
    }
    clearTimeout(timerId)
    timerId = setTimeout(() => {
      console.log(output.toDecodedString()())
      output = undefined
    }, 500)
    return true
  }
})
await writer.write("top\n")
```

***

### `withTTY(options): Promise<TTYStdinWriter>`

Opens a TTY session with simplified options (without explicit dimensions).

#### Parameters:

- `options` (`object`):

  - `onOutput` (`function`):
    Callback `(data: Data, isStderr: boolean) => boolean` for receiving terminal output.

  - `onError?` (`function`):
    Optional error callback `(error: string) => void`.

#### Returns:

- A `Promise` that resolves to a `TTYStdinWriter`.

***

### `openSFTP(): Promise<SFTPClient>`

Opens an SFTP session for file transfer operations.

#### Returns:

- A `Promise` that resolves to an `SFTPClient` instance.

#### Example:

```ts
const sftp = await ssh.openSFTP()
await sftp.writeFile("/tmp/test.txt", "Hello world")
```

***

### `jump(options): Promise<SSHClient>`

Performs an SSH jump (proxy) to another remote host from the current SSH session.

#### Parameters:

- `options` (`object`):

  - `host` (`string`):
    The destination host to jump to.

  - `port?` (`number`):
    Port to connect to (default is `22`).

  - `authenticationMethod` (`SSHAuthenticationMethod`):
    Authentication method for the next host.

  - `trustedHostKeys?` (`string[]`):
    Optional list of trusted host keys.

#### Returns:

- A `Promise` that resolves to a new `SSHClient` representing the jump connection.

#### Example:

```ts
const nextHop = await ssh.jump({
  host: "10.0.0.2",
  authenticationMethod: SSHAuthenticationMethod.passwordBased("user2", "pass2")
})
```

***

### `close(): Promise<void>`

Closes the SSH connection and releases associated resources.

> **Important:** You should call this method when the SSH client is no longer needed to avoid potential memory or socket leaks.

#### Returns:

- A `Promise` that resolves when the SSH connection is successfully closed.

#### Example:

```ts
await ssh.close()
```

***

## Usage Example

```ts
const ssh = await SSHClient.connect({
  host: "192.168.1.10",
  authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "password")
})

const output = await ssh.executeCommand("uptime")
console.log("Uptime:", output)

const sftp = await ssh.openSFTP()
await sftp.writeFile("/tmp/hello.txt", "Hello SSH")

await ssh.close()
```



---
url: /guide/Utilities/SSH/TTY Stdin Writer.md
---

# TTY Stdin Writer

Represents a writable input stream for a TTY (teletypewriter) session opened over SSH. This class allows writing text to the remote terminal’s standard input and resizing the terminal window dynamically.

This class is typically returned from methods such as `SSHClient.withPTY()` and `SSHClient.withTTY()`.

***

## Methods

### `write(data: string): Promise<void>`

Writes the given string to the standard input of the TTY session.

#### Parameters:

- `data` (`string`):
  The string data to send to the remote terminal’s `stdin`. This can include control characters (e.g., `"\r"` for Enter, `"\x03"` for Ctrl+C).

#### Returns:

- A `Promise` that resolves when the data has been successfully written to the TTY stream.

#### Example:

```ts
const writer = await ssh.withTTY({
  onOutput: (text) => {
    console.log("Output:", text)
    return true
  }
})
await writer.write("ls -la\n")
```

***

### `changeSize(options: { cols: number; rows: number; pixelWidth: number; pixelHeight: number }): Promise<void>`

Resizes the remote terminal window. This is useful for applications that rely on terminal dimensions, such as text editors or full-screen tools (e.g., `vim`, `htop`).

#### Parameters:

- `options` (`object`):
  An object describing the new terminal dimensions:

  - `cols` (`number`):
    The number of character columns in the terminal (e.g., 80).

  - `rows` (`number`):
    The number of character rows in the terminal (e.g., 24).

  - `pixelWidth` (`number`):
    The pixel width of the terminal window. Use `0` if not applicable.

  - `pixelHeight` (`number`):
    The pixel height of the terminal window. Use `0` if not applicable.

#### Returns:

- A `Promise` that resolves once the terminal size has been successfully updated.

#### Example:

```ts
await writer.changeSize({
  cols: 100,
  rows: 30,
  pixelWidth: 0,
  pixelHeight: 0
})
```

***

## Usage Example

```ts
const ssh = await SSHClient.connect({
  host: "192.168.1.10",
  authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "password")
})

const writer = await ssh.withPTY({
  term: "xterm",
  onOutput: (text, isStderr) => {
    console.log(text)
    return true
  }
})

await writer.write("top\n")

// Resize the terminal after 2 seconds
await new Promise(resolve => setTimeout(resolve, 2000))
await writer.changeSize({
  cols: 120,
  rows: 40,
  pixelWidth: 0,
  pixelHeight: 0
})
```



---
url: /guide/Utilities/Safari Browser Scripts.md
---

# Safari Browser Scripts

Safari Browser Scripts let Scripting run userscripts in Safari through the Safari Web Extension. The runtime supports Greasemonkey-style `GM.*` APIs and selected Scripting APIs.

***

## Where Scripts Run

There are two sources:

- `browser.tsx` in a Scripting script project. It is built to `browser.js`.
- Installed `.user.js` / `.js` files from Safari's extension popup.

Scripts installed from Safari's extension popup are stored under:

```ts
scripting-safari-extension/userscripts/
```

Downloads and GM storage live in the same root:

```ts
scripting-safari-extension/downloads/
scripting-safari-extension/storages/
```

This root follows the Safari Browser Data storage location configured in Settings, including WebDAV when enabled.

***

## Script Format

Create or install a `.user.js` / `.js` file with a userscript metadata block:

```js
// ==UserScript==
// @name GitHub Demo
// @match https://github.com/*
// @grant GM.log
// @grant Scripting.FileManager
// ==/UserScript==

GM.log("loaded", location.href)
```

Common metadata keys:

```ts
// @name
// @namespace
// @version
// @description
// @author
// @match
// @include
// @exclude
// @exclude-match
// @connect
// @grant
// @require
// @resource
// @run-at document-start | document-body | document-end | document-idle
// @inject-into auto | content | page
// @weight 1..999
// @noframes
// @homepageURL
// @supportURL
// @updateURL
// @downloadURL
// @license
```

`@weight` controls execution order when multiple scripts match the page. Larger weights run first. If no `@run-at` is provided, scripts run at `document-end`.

`@inject-into` defaults to `auto`. With `auto`, a script that declares any `@grant` (`GM.*` or `Scripting.*`) runs in the **content world** (privileged APIs available, isolated from the page's JavaScript), while a script with `@grant none` or no grant runs in the **page world** (shares the page's real `window`, can read page globals). Use `@inject-into content` or `@inject-into page` to force a world explicitly. `GM.*`, `Scripting.*`, and extension messaging are only available in the content world; grants are ignored in the page world. On pages whose Content-Security-Policy blocks injected scripts, `auto` page-world scripts automatically fall back to the content world.

***

## Permissions

Privileged APIs must be declared with `@grant`.

```js
// @grant GM.getValue
// @grant GM.setValue
// @grant GM.xmlHttpRequest
// @grant GM.cookie
// @grant Scripting.FileManager
```

`@grant none` disables GM APIs, but `GM_info` and `GM.info` remain available for compatibility.

Cross-origin network, download, resource, and cookie access must be allowed with `@connect`.

```js
// @connect api.github.com
// @connect https://api.github.com/*
// @connect *
```

When a required grant or connect rule is missing, the runtime throws an error with a stable `code` such as `permissionDenied` or `connectDenied`.

***

## `GM_info`

`GM_info` and `GM.info` expose parsed metadata and runtime details:

```ts
GM_info.script.name
GM_info.script.version
GM_info.script.matches
GM_info.script.connects
GM_info.script.runAt
GM_info.script.injectInto
GM_info.script.weight
GM_info.scriptHandler
GM_info.version
```

***

## Supported GM APIs

### Storage

```ts
await GM.getValue(key, defaultValue)
await GM.setValue(key, value)
await GM.deleteValue(key)
await GM.listValues()

const id = GM.addValueChangeListener(key, (key, oldValue, newValue, remote) => {})
GM.removeValueChangeListener(id)
```

GM storage is stored as JSON under `scripting-safari-extension/storages/`.

### DOM and Menu

```ts
GM.log(...items)
GM.addStyle(css)
GM.addElement("div", { textContent: "Hello" })
GM.addElement(document.body, "button", { textContent: "Run" })

const id = GM.registerMenuCommand("Run", () => {})
GM.unregisterMenuCommand(id)
GM.removeMenuCommand(id)
```

Menu commands are shown in Safari's extension popup for the current page.

### Tabs, Clipboard, Notification

```ts
const tab = await GM.openInTab("https://github.com/trending", { active: false })
tab.close()
await GM.closeTab()

await GM.setClipboard("Hello")
await GM.notification({ title: "Scripting", text: "Done" })
```

`GM.closeTab()` closes the current tab when supported by Safari. `GM.openInTab()` returns a tab control with `close()`.

### Resources

```ts
const text = await GM.getResourceText("name")
const url = await GM.getResourceURL("name")
```

Declare resources in the metadata block:

```js
// @resource name https://example.com/file.txt
```

### Download

```ts
await GM.download({
  url: "https://example.com/file.txt",
  name: "file.txt",
  onload(response) {
    GM.log(response.path)
  }
})
```

Downloaded files are stored under `scripting-safari-extension/downloads/`.

### XHR

```ts
await GM.xmlHttpRequest({
  method: "GET",
  url: "https://api.github.com/zen",
  responseType: "text",
  overrideMimeType: "text/plain",
  onloadstart(event) {},
  onprogress(event) {},
  onreadystatechange(response) {},
  onload(response) {},
  onloadend(response) {}
})
```

The runtime supports `responseType` values `text`, `json`, `arraybuffer`, `blob`, and `document`, plus `user`, `password`, `headers`, `data`, `timeout`, `binary`, `overrideMimeType`, `upload` callbacks, `finalUrl`, and `responseURL`.

### Cookies

```ts
await GM.cookie.set({
  url: location.href,
  name: "scripting_test",
  value: "1",
  path: "/",
  secure: true
})

const cookies = await GM.cookie.list({ url: location.href, name: "scripting_test" })
await GM.cookie.delete({ url: location.href, name: "scripting_test" })
```

Callback style is also supported:

```ts
GM.cookie.list({ url: location.href }, cookies => {
  GM.log(cookies)
})
```

***

## `Scripting.FileManager`

Use `@grant Scripting.FileManager` or `@grant Scripting.*` to access the API.

### Properties

```ts
Scripting.FileManager.documentsDirectory: string
Scripting.FileManager.iCloudDocumentsDirectory: string | null
Scripting.FileManager.appGroupDocumentsDirectory: string | null
Scripting.FileManager.safariBrowserDirectory: string
Scripting.FileManager.safariBrowserStorageDirectory: string
Scripting.FileManager.safariBrowserDownloadsDirectory: string
Scripting.FileManager.safariBrowserUserscriptsDirectory: string
Scripting.FileManager.isiCloudEnabled: boolean
```

In regular Scripting app scripts, the same Safari data directories are available as `FileManager.safariBrowserDirectory`, `FileManager.safariBrowserStorageDirectory`, `FileManager.safariBrowserDownloadsDirectory`, and `FileManager.safariBrowserUserscriptsDirectory`.

### Methods

```ts
await Scripting.FileManager.readAsString(path)
await Scripting.FileManager.writeAsString(path, contents)
await Scripting.FileManager.createDirectory(path, true)
await Scripting.FileManager.readDirectory(path)
await Scripting.FileManager.exists(path)
await Scripting.FileManager.remove(path)
```

All file operations are limited to directories exposed by `Scripting.FileManager`.

***

## Installed Scripts

Safari's extension popup can install userscripts from the current page or from a URL. Installed scripts can be enabled, disabled, updated, or deleted in the popup and in Tools > Development > Safari Browser Scripts.

Use the Tools page to inspect:

- Installed userscripts.
- GM storage JSON files.
- Downloads created by `GM.download`.

***

## Example

```ts
// ==UserScript==
// @name Save Page URL
// @match https://github.com/*
// @grant GM.log
// @grant Scripting.FileManager
// ==/UserScript==

const fm = Scripting.FileManager
const dir = `${fm.appGroupDocumentsDirectory ?? fm.documentsDirectory}/Safari Notes`
const file = `${dir}/last-url.txt`

await fm.createDirectory(dir)
await fm.writeAsString(file, location.href)

GM.log(await fm.readAsString(file))
```



---
url: /guide/Utilities/Search Shortcuts.md
---

# Search Shortcuts

Search Shortcuts let you type a trigger word followed by a query in Safari's address bar and jump straight to a site's search results — for example, typing `gh hello world` can take you to GitHub's search for "hello world".

This feature requires Scripting PRO.

***

## How It Works

When you search from Safari's address bar, Scripting looks at the first word of your query. If it matches a shortcut's trigger, the rest of the query is sent to that shortcut's search URL instead of your default search engine.

- The **first word** is the trigger. A shortcut can have several triggers, and any of them activates it.
- **Everything after it** becomes the search query.
- The query is URL-encoded and substituted into the shortcut's URL where you put `%s`.

It works with Safari's address-bar search on common search engines (Google, Bing, DuckDuckGo, Yahoo, Baidu, Ecosia, Startpage). Make sure your query starts with the trigger word.

***

## Add a Shortcut

In the Safari Browser Scripts settings, open **Search Shortcuts** and tap **Add**:

- **Triggers** — one or more words with no spaces, e.g. `gh`. Add several (such as `gh` and `git`) and any of them activates the shortcut. Use **Add trigger** to add more, and the minus button to remove one.
- **Name** — an optional label for the list.
- **Search URL** — the destination, with `%s` where the query should go.

Each shortcut has an **Enabled** switch. Tap a row to edit it, or swipe to delete.

### Different URLs for iPhone/iPad and Mac

By default one search URL is used on every device. If you want a mobile-optimized site on iPhone/iPad and the full site on Mac, turn on **Use different URLs for iPhone/iPad and Mac**. Both fields are pre-filled with your current URL, so you only change the side you need — for example an `m.` mobile host for iPhone/iPad and the desktop host for Mac. The extension picks the URL that matches the device you are searching on.

***

## Examples

| Triggers    | Search URL                                        |
| ----------- | ------------------------------------------------- |
| `gh`, `git` | `https://github.com/search?q=%s`                  |
| `yt`        | `https://www.youtube.com/results?search_query=%s` |
| `npm`       | `https://www.npmjs.com/search?q=%s`               |
| `w`         | `https://en.wikipedia.org/w/index.php?search=%s`  |

With the `gh` shortcut above, searching `gh swiftui` — or `git swiftui` — opens `https://github.com/search?q=swiftui`.

The destination does not have to be a web search. A custom app URL scheme or a Universal Link also works, so a shortcut can open another app's search directly.

***

## Notes

- Shortcuts are matched only when the first word equals one of the triggers. A normal query that does not start with a trigger passes through to your default search engine unchanged.
- Triggers are matched case-insensitively.
- Changes you make in the settings take effect on your next search.



---
url: /guide/Utilities/Shell.md
---

# Shell

The `Shell` global runs shell commands inside the Scripting app via the embedded `ios_system` runtime. Useful for ad-hoc tooling — listing and editing files, processing text streams, fetching URLs with `curl`, archiving with `tar`, running `python`, etc.

> **Available commands are limited to what `ios_system` ships.** This is _not_ a full POSIX shell. Only commands provided by the bundled `ios_system` modules work: roughly the basic file / text / network utilities (`ls`, `cp`, `mv`, `rm`, `cat`, `echo`, `grep`, `sed`, `awk`, `cut`, `sort`, `uniq`, `head`, `tail`, `wc`, `find`, `xargs`, `tar`, `gzip`, `curl`, `scp`, `sftp`, `ssh`, `python`, ...) plus shell builtins (`cd`, `pwd`, `env`, `export`, pipes, redirects). External tools that are **not** bundled — `git`, `make`, `node`, `npm`, `brew`, `gcc`, etc. — are unavailable, and you cannot execute arbitrary binaries shipped with a script (iOS sandbox restriction).

`Shell.run` and `Python.run` share a single serial queue: while one is running, others wait. This is intentional — `ios_system` and the embedded Python interpreter share global state (env vars, `sys.modules`, current working directory) and cannot run concurrently.

***

## Methods

### `Shell.run(command, options?): Promise<ShellExecutionResult>`

Execute a shell command. Returns when the command exits or the timeout is reached. Non-zero exit codes resolve normally; only argument validation errors reject the promise.

```ts
function run(command: string, options?: ShellRunOptions): Promise<ShellExecutionResult>
```

#### `ShellRunOptions`

| Name            | Type                    | Required | Description                                                                                                                                                                              |
| --------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cwd             | string                  | No       | Working directory for the command. Relative paths are resolved against the documents directory; `~/` is expanded to the documents directory.                                             |
| timeout         | number                  | No       | Maximum execution time in seconds. Defaults to `120`. When exceeded, the command is killed and the promise resolves with `timedOut: true`.                                               |
| env             | Record\<string, string> | No       | Extra environment variables injected for this invocation only. Restored to their previous values after the command finishes.                                                             |
| queryParameters | Record\<string, string> | No       | String key/value pairs serialized as JSON and exposed to the subprocess via the `SCRIPTING_QUERY_PARAMETERS` environment variable. Mirrors `Script.queryParameters` for ad-hoc commands. |

#### `ShellExecutionResult`

| Name      | Type    | Description                                                                                                                                                                                |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| output    | string  | Combined stdout + stderr produced by the command. The underlying `ios_system` pipes both into a single stream, so they cannot be separated.                                                |
| exitCode  | number  | Process exit code. `0` means success. Non-zero values are surfaced as resolved promises (no rejection), so the caller can handle expected non-zero exits (e.g. `grep` finding no matches). |
| timedOut  | boolean | `true` when the command was killed because it exceeded `options.timeout`.                                                                                                                  |
| cancelled | boolean | `true` when the command was cancelled by the host.                                                                                                                                         |

***

## Examples

### Basic command

```ts
const r = await Shell.run("echo hi && pwd", { cwd: "/tmp" })
console.log(r.output)   // "hi\n/tmp\n"
console.log(r.exitCode) // 0
```

### Handling non-zero exits

```ts
const r = await Shell.run("grep -q needle haystack.txt")
if (r.exitCode === 0) {
  console.log("found")
} else if (r.exitCode === 1) {
  console.log("not found")
} else {
  console.log("error:", r.output)
}
```

### Passing parameters via env

```ts
const r = await Shell.run("echo $GREETING", {
  env: { GREETING: "hello world" },
})
console.log(r.output) // "hello world\n"
```

### Sharing parameters with `Script.queryParameters`

```ts
const r = await Shell.run('python -c "import os, json; print(json.loads(os.environ[\\"SCRIPTING_QUERY_PARAMETERS\\"]))"', {
  queryParameters: { name: "Alice", count: "3" },
})
console.log(r.output) // "{'name': 'Alice', 'count': '3'}\n"
```

### Detecting a timeout

```ts
const r = await Shell.run("sleep 30", { timeout: 2 })
if (r.timedOut) {
  console.log("killed by timeout")
}
```



---
url: /guide/Utilities/Storage (Python).md
---

# 

***

title: Storage (Python)
description: Python-side Storage API mirroring the JS Storage namespace: per-script and shared key-value persistence.

***

The `scripting` Python package exposes `Storage`, mirroring the JS-side `Storage` namespace. It provides a per-script persistent key-value store backed by `UserDefaults`, so Python and JS index scripts can share the same value when they read/write the same key.

```python
import scripting; Storage = scripting.Storage
```

By default each script's keys are isolated from other scripts. Pass `shared=True` to read/write the cross-script shared domain.

***

## Methods

### `Storage.set(key, value, shared=False) -> bool`

Persist `value` under `key`. `value` must be JSON-serializable (`str`, `int`, `float`, `bool`, `None`, `list`, `dict` and combinations). Returns `True` on success.

```python
Storage.set("counter", 42)
Storage.set("user", {"name": "Alice", "premium": True})
```

### `Storage.get(key, shared=False) -> Any | None`

Read the value previously stored under `key`. Returns `None` if the key doesn't exist.

```python
n = Storage.get("counter") or 0
user = Storage.get("user")  # {"name": "Alice", "premium": True}
```

### `Storage.remove(key, shared=False) -> None`

Delete the entry under `key`. No-op if the key doesn't exist.

### `Storage.contains(key, shared=False) -> bool`

Whether the key exists in storage.

### `Storage.keys() -> list[str]`

List all keys belonging to the current script (per-script namespace only — not the shared domain).

### `Storage.clear() -> None`

Remove all per-script keys for the current script. Does not affect the shared domain or other scripts' data.

***

## Parameters

| Name   | Type | Required       | Description                                                                                                             |
| ------ | ---- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| key    | str  | Yes            | The storage key. Per-script keys are automatically prefixed with the script's name; shared keys are used verbatim.      |
| value  | Any  | Yes (set only) | JSON-serializable value to store.                                                                                       |
| shared | bool | No             | When `True`, operates on the cross-script shared domain instead of the current script's namespace. Defaults to `False`. |

***

## Examples

### Counter that survives across runs

```python
import scripting; Storage = scripting.Storage; Script = scripting.Script

count = (Storage.get("hits") or 0) + 1
Storage.set("hits", count)
Script.exit({"hits": count})
```

### Sharing data with the JS side

```python
# Python side
import scripting; Storage = scripting.Storage
Storage.set("session_token", "abc123", shared=True)
```

```ts
// JS side reads the same value
const token = Storage.get<string>("session_token", { shared: true })
```

### Listing and clearing this script's data

```python
import scripting; Storage = scripting.Storage

print("Stored keys:", Storage.keys())
Storage.clear()  # wipe everything this script wrote
```



---
url: /guide/Utilities/Storage.md
---

# Storage

The `Storage` module provides a lightweight persistent key-value storage system for scripts. It allows scripts to save and retrieve simple typed data as well as binary data (`Data`). All data is persisted asynchronously in the background.

By default, all values are stored in the **private domain** of the current script, which means other scripts cannot access them. To share data across multiple scripts, set the `shared: true` option to use the **shared domain** instead.

***

## Supported Data Types

The following types can be stored using the Storage API:

- `string`
- `number`
- `boolean`
- `JSON` (any JSON-serializable structure)
- `Data` (using `setData` / `getData`)

***

## Storage Domains

| Domain  | Default                       | Accessible By           | Use Case                                                        |
| ------- | ----------------------------- | ----------------------- | --------------------------------------------------------------- |
| Private | Yes                           | Only the current script | Script-specific settings, preferences, cached content           |
| Shared  | No (must pass `shared: true`) | All scripts             | Global settings, shared preferences, multi-script communication |

***

## API Reference

## 1. `Storage.set(key, value, options?)`

```ts
function set<T>(key: string, value: T, options?: { shared: boolean }): boolean
```

Stores a value in persistent storage. Supports `string`, `number`, `boolean`, and JSON-serializable values.

### Parameters

| Name           | Type      | Required | Description                                    |
| -------------- | --------- | -------- | ---------------------------------------------- |
| key            | `string`  | Yes      | The key under which the value is stored        |
| value          | `T`       | Yes      | The value to store                             |
| options.shared | `boolean` | No       | Store the value in the shared domain when true |

### Returns

- `boolean` — whether the operation was successful.

***

## 2. `Storage.get(key, options?)`

```ts
function get<T>(key: string, options?: { shared: boolean }): T | null
```

Retrieves a stored value. Returns `null` if the key does not exist.

### Returns

- `T | null` — the value associated with the key or `null`.

***

## 3. `Storage.setData(key, data, options?)`

```ts
function setData(key: string, data: Data, options?: { shared: boolean }): void
```

Stores a `Data` object in persistent storage.

***

## 4. `Storage.getData(key, options?)`

```ts
function getData(key: string, options?: { shared: boolean }): Data | null
```

Retrieves a stored `Data` object. Returns `null` if the key does not exist.

***

## 5. `Storage.remove(key, options?)`

```ts
function remove(key: string, options?: { shared: boolean }): void
```

Removes the entry associated with the specified key.

***

## 6. `Storage.contains(key, options?)`

```ts
function contains(key: string, options?: { shared: boolean }): boolean
```

Checks whether the storage contains the specified key.

***

## 7. `Storage.clear()`

```ts
function clear(): void
```

Removes all entries from the **private storage domain**.
This does **not** affect shared storage.

***

## 8. `Storage.keys()`

```ts
function keys(): string[]
```

Returns an array of all keys stored in the current storage domain.

***

## Usage Examples

## Example 1: Store and retrieve simple values

```ts
Storage.set("username", "Thom")

const name = Storage.get<string>("username")
console.log(name) // "Thom"
```

***

## Example 2: Store a JSON object

```ts
Storage.set("profile", {
  name: "Alice",
  age: 30
})

const profile = Storage.get<{ name: string; age: number }>("profile")
console.log(profile?.age) // 30
```

***

## Example 3: Store and read binary Data

```ts
const bytes = Data.fromUTF8("hello")
Storage.setData("payload", bytes)

const result = Storage.getData("payload")
console.log(result?.toUTF8()) // "hello"
```

***

## Example 4: Shared domain usage

```ts
Storage.set("theme", "dark", { shared: true })

const theme = Storage.get<string>("theme", { shared: true })
console.log(theme) // "dark"
```

***

## Example 5: Check existence and remove

```ts
if (Storage.contains("token")) {
  Storage.remove("token")
}
```

***

## Example 6: List all keys

```ts
console.log(Storage.keys()) // ["username", "profile", ...]
```

***

## Notes and Best Practices

1. All writes are persisted asynchronously, but the method returns immediately with a success flag.
2. `Data` cannot be stored using `Storage.set()`. Use `setData()` / `getData()` instead.
3. JSON values must be fully serializable.
4. Storage is intended for small, simple data. Avoid storing large binary blobs.
5. `Storage.clear()` only clears the private domain.



---
url: /guide/Utilities/Thread.md
---

# Thread

Scripting’s UI rendering system and the vast majority of JavaScript execution run on the main thread by default. In normal usage, developers rarely need to manually switch threads.

However, some system APIs or internal operations may occasionally execute on a background thread. To ensure UI updates are always safe, and to support running heavy work without blocking the main thread, Scripting provides the global `Thread` API.

`Thread` is a global namespace and does not require imports.

***

## `Thread.isMainThread: boolean`

Indicates whether the current JavaScript execution context is running on the main thread.

Most of the time this value is `true`, but certain system callbacks or asynchronous operations may occur on background threads. When performing UI updates, this property can be used to confirm that the current thread is safe for UI operations.

```ts
if (Thread.isMainThread) {
  console.log('On main thread')
} else {
  console.log('On background thread')
}
```

***

## `Thread.runInMain(execute: () => void): void`

Executes the given function on the main thread.

Because JavaScript normally runs on the main thread, you usually do not need to call this method explicitly. It is mainly useful when:

- A system API callback happens on a background thread and you need to update the UI
- You want to strictly ensure that a specific piece of logic runs on the main thread

This method does not return a value and does not switch back to the previous thread. It simply guarantees synchronous execution on the main thread.

```ts
Thread.runInMain(() => {
  title.value = 'Updated on main thread'
})
```

***

## `Thread.runInBackground<T>(execute: () => T | Promise<T>): Promise<T>`

Runs the provided function on a background thread and returns its result as a Promise.
Once the background task completes, the result is delivered back on the thread that initiated the call (typically the main thread).

This is ideal for:

- CPU-intensive tasks
- Large data processing
- Any work that should not block the UI

The function may return either a value or a Promise.

```ts
const total = await Thread.runInBackground(() => {
  let v = 0
  for (let i = 0; i < 5_000_000; i++) v += i
  return v
})

console.log('Computed result:', total)
```

Async example:

```ts
const filtered = await Thread.runInBackground(async () => {
  const image = await loadImage()
  return applyFilter(image)
})

Thread.runInMain(() => {
  setImage(filtered)
})
```

***

## Automatic Thread Switching in Asynchronous I/O

Many **asynchronous I/O methods in Scripting already run on background threads automatically**, so developers do **not** need to manually call `runInBackground` for them.

Example:

```ts
const text = await FileManager.readAsString(path)
```

`readAsString` automatically performs file reading on a background thread, then returns the result back on the thread where the call was made (usually the main thread).

This means asynchronous I/O will **not** block the UI, even if you call them directly in your UI logic.

### Only synchronous I/O runs on the main thread

For example:

```ts
const text = FileManager.readAsStringSync(path)
```

Synchronous methods **always** execute on the main thread and do **not** switch threads internally.

Therefore:

- Avoid using synchronous I/O on large files
- Prefer asynchronous versions (e.g., `readAsString`) for better performance
- Use `runInBackground` only when you must perform blocking synchronous work or heavy computation

***

## Recommendations

- JavaScript runs on the main thread by default; `runInMain` is rarely needed
- Asynchronous I/O methods already run on background threads automatically
- Use `runInBackground` for CPU-heavy or blocking synchronous tasks
- If an API callback occurs on a background thread, use `runInMain` to safely update UI
- Do not manipulate UI inside `runInBackground`; switch back first



---
url: /guide/Utilities/UIImage.md
---

# UIImage

The `UIImage` class represents an image object that can be loaded, encoded, converted, and displayed.
It supports creating images from file paths, binary data, or Base64 strings and provides multiple format conversion methods (PNG/JPEG).
`UIImage` can be displayed directly in an `Image` component or used with the `Data` class for storage, uploading, or encryption.

***

## Overview

`UIImage` is the core class for handling images in the scripting environment. It is commonly used for:

- Loading images from local files, binary data, Base64 strings or networl URL.
- Accessing image dimensions and scale
- Converting image formats (e.g., PNG, JPEG)
- Generating Base64-encoded strings
- Adjusting rendering and resizing modes
- Flipping or tinting images
- Generating thumbnails
- Displaying dynamic images that switch between light and dark modes

***

## Properties

### `width: number`

The width of the image in pixels.

```ts
const image = UIImage.fromFile("/path/to/image.png")
console.log(image?.width)
```

***

### `height: number`

The height of the image in pixels.

```ts
const image = UIImage.fromFile("/path/to/image.png")
console.log(image?.height)
```

***

### `scale: number`

The scale factor of the image, usually `1` or `2` for Retina displays.

```ts
console.log(image?.scale)
```

***

### `imageOrientation: string`

The orientation of the image. Possible values:

- `"up"`
- `"down"`
- `"left"`
- `"right"`
- `"upMirrored"`
- `"downMirrored"`
- `"leftMirrored"`
- `"rightMirrored"`
- `"unknown"`

***

### `isSymbolImage: boolean`

Indicates whether the image is an SF Symbol image.

```ts
const symbol = UIImage.fromSFSymbol("heart.fill")
console.log(symbol?.isSymbolImage) // true
```

***

### `renderingMode: "automatic" | "alwaysOriginal" | "alwaysTemplate" | "unknown"`

The rendering mode of the image:

- `automatic`: Automatically determined by the system
- `alwaysOriginal`: Display the image in its original color
- `alwaysTemplate`: Render the image as a template (can be tinted)

***

### `resizingMode: "tile" | "stretch" | "unknown"`

The resizing mode of the image:

- `"tile"`: The image is tiled to fill the area
- `"stretch"`: The image is stretched to fit

***

### `capInsets: { top: number, left: number, bottom: number, right: number }`

The cap insets that define the stretchable area of the image.

***

### `flipsForRightToLeftLayoutDirection: boolean`

Indicates whether the image automatically flips in right-to-left (RTL) layout directions.

***

## Instance Methods

### `preparingThumbnail(size: Size): UIImage | null`

Creates a thumbnail with the specified size.

- **Parameters:**

  - `size.width`: Width of the thumbnail
  - `size.height`: Height of the thumbnail

- **Returns:**
  A new `UIImage` instance, or `null` if creation fails.

**Example:**

```ts
const image = UIImage.fromFile("/path/to/photo.jpg")
const thumb = image?.preparingThumbnail({ width: 200, height: 200 })
```

***

### `withBaselineOffset(offset: number): UIImage`

Returns a new image with the specified baseline offset, it is useful for aligning text to the bottom of an image.

```ts
const offset = image?.withBaselineOffset(10)
```

***

### `withHorizontallyFlippedOrientation(): UIImage`

Returns a new image with horizontally flipped orientation.

```ts
const flipped = image?.withHorizontallyFlippedOrientation()
```

***

### `withTintColor(color: string, renderingMode?: "automatic" | "alwaysOriginal" | "alwaysTemplate"): UIImage | null`

Applies a tint color to the image using the specified rendering mode.

- **Parameters:**

  - `color`: The tint color as a string, e.g. `"#ffcc00"` or `"rgb(255,128,0)"`
  - `renderingMode`: The rendering mode to use. Defaults to `"automatic"`

**Example:**

```ts
const symbol = UIImage.fromSFSymbol("star.fill")
const tinted = symbol?.withTintColor("#ffcc00", "alwaysTemplate")
```

***

### `withRenderingMode(renderingMode: "automatic" | "alwaysOriginal" | "alwaysTemplate"): UIImage | null`

Returns a new version of the image using the specified rendering mode.

```ts
const templated = image?.withRenderingMode("alwaysTemplate")
```

***

### `resizableImage(capInsets, resizingMode?): UIImage | null`

Returns a new version of the image with specified cap insets and resizing mode.

- **Parameters:**

  - `capInsets`: `{ top, left, bottom, right }`
  - `resizingMode`: `"tile"` or `"stretch"` (default `"tile"`)

**Example:**

```ts
const resizable = image?.resizableImage(
  { top: 10, left: 10, bottom: 10, right: 10 },
  "stretch"
)
```

***

### `renderedInCircle(radius?: number | null, fitEntireImage?: boolean): UIImage`

Returns a new version of the image rendered as a circle, with optional radius and fit behavior.

- **Parameters:**

  - `radius` (optional): The radius of the circle in points.

    - If not specified:

      - When `fitEntireImage` is `false`, the circle uses the **shortest dimension** of the image.
      - When `fitEntireImage` is `true`, the circle uses the **longest dimension** of the image.
  - `fitEntireImage` (optional): Whether to fit the entire image inside the circle.

    - Default value: `true`.
    - If set to `false`, the image fills the circular area and may be cropped.

- **Returns:**

  - A new `UIImage` instance representing the circular rendering.

**Example 1: Create a default circular avatar**

```ts
const image = UIImage.fromFile("/path/to/avatar.jpg")
const circle = image?.renderedInCircle()
<Image image={circle} />
```

**Example 2: Specify radius and fit entire image**

```ts
const image = UIImage.fromFile("/path/to/photo.png")
const circle = image?.renderedInCircle(60, true)
<Image image={circle} />
```

**Example 3: Fill mode (may crop parts of the image)**

```ts
const image = UIImage.fromFile("/path/to/icon.png")
const circle = image?.renderedInCircle(50, false)
<Image image={circle} />
```

***

### `renderedIn(size: { width: number, height: number }, source?: {  position?: ..., size?: ... }): UIImage | null`

Returns a new version of the image rendered with the specified size and optional source region.

- **Parameters:**

  - `size`: `{ width: number, height: number }` - The size of the rendered image.
  - `source`: `{ position?: { x: number, y: number }, size?: { width: number, height: number } }` - The source region of the image.

- **Returns:**

  - A new `UIImage` instance if rendering succeeds, or `null` if it fails.

**Example 1: Scale entire image into a rectangle**

```ts
const image = UIImage.fromFile("/path/to/photo.jpg")
const rendered = image?.renderedIn({width: 200, height: 200 })
<Image image={rendered} />
```

**Example 2: Crop and render a specific region**

```ts
const image = UIImage.fromFile("/path/to/landscape.jpg")
const cropped = image?.renderedIn({
    width: 150, height: 150 
  },
  position: { x: 100, y: 50 },
  size: { width: 300, height: 300 }
)
<Image image={cropped} />
```

***

### `applySymbolConfiguration(config: UIImageSymbolConfiguration | UIImageSymbolConfiguration[]): UIImage | null`

Returns a new version of the image with the specified **symbol configuration** (`UIImageSymbolConfiguration`).
This method is primarily used to customize the appearance of **SF Symbols** images, including color, weight, size, rendering mode, and palette.

- **Parameters:**

  - `config`: The symbol configuration to apply to the image.

    - Can be a single `UIImageSymbolConfiguration` instance, or
    - An array of configurations, which will be applied sequentially (later configurations may override earlier ones).

- **Returns:**

  - A new `UIImage` instance representing the symbol with applied configuration, or `null` if the operation fails.

**Example 1: Display a symbol in multicolor**

```ts
const image = UIImage.fromFile("/path/to/sf_symbol.png")
const config = UIImageSymbolConfiguration.preferringMulticolor()
const colored = image?.applySymbolConfiguration(config)
<Image image={colored} />
```

**Example 2: Apply both scale and weight configurations**

```ts
const image = UIImage.fromFile("/path/to/sf_symbol.png")
const config = [
  UIImageSymbolConfiguration.scale("large"),
  UIImageSymbolConfiguration.weight("bold")
]
const boldLarge = image?.applySymbolConfiguration(config)
<Image image={boldLarge} />
```

**Example 3: Set hierarchical and palette colors**

```ts
const image = UIImage.fromFile("/path/to/symbol.png")
const config = [
  UIImageSymbolConfiguration.hierarchicalColor(Color.blue()),
  UIImageSymbolConfiguration.paletteColors([Color.red(), Color.orange()])
]
const customized = image?.applySymbolConfiguration(config)
<Image image={customized} />
```

***

## UIImageSymbolConfiguration

`UIImageSymbolConfiguration` is a class used to define appearance configurations for **symbol images (SF Symbols)**.
Instances created with its static methods can be passed to `applySymbolConfiguration()` to modify how the symbol is rendered.

### Available Static Methods

| Method                      | Description                                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `preferringMonochrome()`    | Prefers monochrome rendering for the symbol.                                                                                                                       |
| `preferringMulticolor()`    | Prefers multicolor rendering for the symbol.                                                                                                                       |
| `scale(value)`              | Sets the scale of the symbol. Possible values: `"default"`, `"large"`, `"medium"`, `"small"`, `"unspecified"`.                                                     |
| `weight(value)`             | Sets the stroke weight of the symbol. Possible values: `"ultraLight"`, `"thin"`, `"light"`, `"regular"`, `"medium"`, `"semibold"`, `"bold"`, `"heavy"`, `"black"`. |
| `pointSize(value)`          | Sets the point size of the symbol.                                                                                                                                 |
| `paletteColors(value)`      | Sets a color palette (array of `Color`) for multicolor or layered symbols.                                                                                         |
| `hierarchicalColor(value)`  | Applies a hierarchical color (used for layered shading effects).                                                                                                   |
| `variableValueMode(value)`  | Sets how variable-value symbols are displayed. Possible values: `"automatic"`, `"color"`, `"draw"`.                                                                |
| `colorRenderingMode(value)` | Sets the color rendering mode. Possible values: `"automatic"`, `"flat"`, `"gradient"`.                                                                             |
| `locale(identifier)`        | Sets the locale for localized symbol variants (e.g., `"en"`, `"zh-Hans"`).                                                                                         |

***

**Example: Combine multiple symbol configurations**

```ts
const config = [
  UIImageSymbolConfiguration.scale("medium"),
  UIImageSymbolConfiguration.weight("semibold"),
  UIImageSymbolConfiguration.preferringMonochrome(),
  UIImageSymbolConfiguration.colorRenderingMode("flat")
]

const image = UIImage.fromFile("/path/to/symbol.png")
const result = image?.applySymbolConfiguration(config)
<Image image={result} />
```

***

### `toJPEGData(compressionQuality?: number): Data | null`

Converts the image to JPEG data.

- **Parameters:**

  - `compressionQuality`: A number between `0` and `1`, default is `1`.
- **Returns:**
  A `Data` instance or `null`.

***

### `toPNGData(): Data | null`

Converts the image to PNG data.
Returns a `Data` instance or `null`.

***

### `toJPEGBase64String(compressionQuality?: number): string | null`

Converts the image to a Base64-encoded JPEG string.

***

### `toPNGBase64String(): string | null`

Converts the image to a Base64-encoded PNG string.

***

## Static Methods

### `UIImage.fromData(data: Data): UIImage | null`

Creates an image from a `Data` instance containing PNG or JPEG data.

***

### `UIImage.fromFile(filePath: string): UIImage | null`

Creates an image from a file path (supports PNG, JPG, JPEG).

***

### `UIImage.fromBase64String(base64String: string): UIImage | null`

Creates an image from a Base64 string.

***

### `UIImage.fromSFSymbol(name: string): UIImage | null`

Creates an image from a system SF Symbol.

**Example:**

```ts
const heart = UIImage.fromSFSymbol("heart.fill")
<Image image={heart} />
```

***

### `UIImage.fromURL(url: string): Promise<UIImage | null>`

Creates an image from a URL.

**Example:**

```ts
const image = await UIImage.fromURL("https://example.com/image.jpg")
<Image image={image} />
```

***

## Using UIImage in the UI

`UIImage` can be displayed directly in the `<Image>` component.

### Component Definition

```ts
declare const Image: FunctionComponent<UIImageProps>
```

***

### Props Definition

```ts
type UIImageProps = {
  image: UIImage | DynamicImageSource<UIImage>
}
```

***

### Dynamic Image Type

```ts
type DynamicImageSource<T> = {
  light: T
  dark: T
}
```

Used for automatically switching images in light and dark mode.

***

### Example: Display a Single Image

```ts
const image = UIImage.fromFile("/path/to/avatar.png")
<Image image={image} />
```

***

### Example: Light and Dark Mode

```ts
const lightImage = UIImage.fromFile("/path/to/light-logo.png")
const darkImage = UIImage.fromFile("/path/to/dark-logo.png")

<Image image={{ light: lightImage, dark: darkImage }} />
```

***

## Common Usage Examples

### 1. Convert Image to Base64

```ts
const image = UIImage.fromFile("/path/to/image.png")
const base64 = image?.toPNGBase64String()
```

***

### 2. Compress and Save as JPEG

```ts
const image = UIImage.fromFile("/path/to/photo.jpg")
const jpegData = image?.toJPEGData(0.6)
if (jpegData) {
  // Save the data to a local file
}
```

***

### 3. Restore Image from Base64 String

```ts
const base64 = "iVBORw0KGgoAAAANSUhEUgAA..."
const image = UIImage.fromBase64String(base64)
<Image image={image} />
```

***

### 4. Convert PNG to JPEG and Upload

```ts
const image = UIImage.fromFile("/path/to/logo.png")
const jpegData = image?.toJPEGData(0.8)
if (jpegData) {
  const response = await fetch("https://example.com/upload", {
    method: "POST",
    body: jpegData.toUint8Array()
  })
}
```

***

### 5. Create and Tint an SF Symbol

```ts
const symbol = UIImage.fromSFSymbol("star.fill")
const colored = symbol?.withTintColor("#ffcc00", "alwaysTemplate")
<Image image={colored} />
```

***

### 6. Generate a Thumbnail

```ts
const image = UIImage.fromFile("/path/to/large.jpg")
const thumb = image?.preparingThumbnail({ width: 120, height: 120 })
<Image image={thumb} />
```

***

## Summary

`UIImage` is the core class for image manipulation in the Scripting environment. It provides:

- Loading from files, binary data, or Base64 strings
- Support for SF Symbols
- Access to dimensions, scale, orientation, and rendering information
- Methods for flipping, tinting, and resizing
- PNG/JPEG conversion and Base64 encoding
- Thumbnail generation and customizable rendering modes
- Seamless integration with the `<Image>` component
- Light and dark mode image switching support



---
url: /guide/Utilities/URLSession/BackgroundURLSession.md
---

# BackgroundURLSession

`BackgroundURLSession` provides APIs in the **Scripting app** for creating, resuming, and managing background download and upload tasks that continue running even when your script or app is not active.

> **Availability:** Only available when your script is running in the main app (`Script.env === "index"`).

***

## Namespace: `BackgroundURLSession`

### 1) `startDownload(options): URLSessionDownloadTask`

**Description:**
Starts a new background download task.

**Signature**

```ts
function startDownload(options: {
  url: string
  destination: string
  headers?: Record<string, string>
  notifyOnFinished?: {
    success: string
    failure: string
  }
}): URLSessionDownloadTask
```

**Parameters**

- `url` (`string`): The URL of the file to download.
- `destination` (`string`): The local file path where the downloaded file will be saved.
- `headers` (`Record<string, string>`, optional): Custom HTTP headers.
- `notifyOnFinished` (`{ success: string, failure: string }`, optional): Whether to show a local notification when the download finishes.

**Returns**

- `URLSessionDownloadTask`: A download task object (the task starts automatically).

**Example**

```ts
const task = BackgroundURLSession.startDownload({
  url: 'https://example.com/file.zip',
  destination: '/var/mobile/Containers/.../Downloads/file.zip',
  headers: { 'User-Agent': 'Scripting/1.0' },
  notifyOnFinished: {
    success: 'Download completed',
    failure: 'Download failed'
  }
})

task.resum()

task.onProgress = d => console.log('Progress:', d.progress)
task.onFinishDownload = (err, info) => {
  if (!err) console.log('Download completed at:', info.destination)
}
```

***

### 2) `resumeDownload(options): URLSessionDownloadTask`

**Description:**
Resumes a previously paused or interrupted download task using resume data.

**Signature**

```ts
function resumeDownload(options: {
  resumeData: Data
  destination: string
  notifyOnFinished?: {
    success: string
    failure: string
  }
}): URLSessionDownloadTask
```

**Parameters**

- `resumeData` (`Data`): The resume data returned by `cancelByProducingResumeData()`.
- `destination` (`string`): The path to save the resumed download.
- `notifyOnFinished` (`{ success: string, failure: string }`, optional): Whether to show a local notification when the download finishes.

**Returns**

- `URLSessionDownloadTask`: A resumed download task (starts automatically).

**Example**

```ts
const task = BackgroundURLSession.resumeDownload({
  resumeData,
  destination: '/.../Downloads/file.zip',
  notifyOnFinished: {
    success: 'Resumed download completed',
    failure: 'Resumed download failed'
  }
})

task.resume()

task.onFinishDownload = (err, info) => {
  if (!err) console.log('Resumed download completed:', info.destination)
}
```

***

### 3) `getDownloadTasks(): Promise<URLSessionDownloadTask[]>`

**Description:**
Retrieves all active or pending background download tasks currently managed by the system.
Useful when your script is restarted or relaunched — you can restore callbacks and monitor ongoing tasks.

**Signature**

```ts
function getDownloadTasks(): Promise<URLSessionDownloadTask[]>
```

**Returns**

- `Promise<URLSessionDownloadTask[]>`: An array of active `URLSessionDownloadTask` objects.

**Example**

```ts
const tasks = await BackgroundURLSession.getDownloadTasks()
for (const task of tasks) {
  console.log('Task ID:', task.id, 'State:', task.state)
  task.onComplete = err => {
    if (err) console.error('Download failed:', err)
  }
}
```

***

### 4) `startUpload(options): URLSessionUploadTask`

**Description:**
Starts a new background upload task.

**Signature**

```ts
function startUpload(options: {
  filePath: string
  toURL: string
  method?: string
  headers?: Record<string, string>
  notifyOnFinished?: {
    success: string
    failure: string
  }
}): URLSessionUploadTask
```

**Parameters**

- `filePath` (`string`): The local file path to upload.
- `toURL` (`string`): The destination server URL.
- `method` (`string`, optional, default `"POST"`): The HTTP method to use.
- `headers` (`Record<string, string>`, optional): Custom HTTP headers.
- `notifyOnFinished` (`{ success: string, failure: string }`, optional): Whether to show a local notification when the upload finishes.

**Returns**

- `URLSessionUploadTask`: An upload task object (the task starts automatically).

**Example**

```ts
const task = BackgroundURLSession.startUpload({
  filePath: '/.../upload.bin',
  toURL: 'https://api.example.com/upload',
  method: 'PUT',
  headers: { Authorization: 'Bearer token' },
  notifyOnFinished: {
    success: 'Upload completed',
    failure: 'Upload failed'
  }
})

task.resume()

task.onComplete = err => {
  if (!err) console.log('Upload completed')
  else console.error('Upload failed:', err)
}
```

***

### 5) `resumeUpload(options): URLSessionUploadTask`

**Description:**
Resumes a paused or failed upload task using previously saved resume data (if supported by the server).

**Signature**

```ts
function resumeUpload(options: {
  resumeData: Data
  notifyOnFinished?: {
    success: string
    failure: string
  }
}): URLSessionUploadTask
```

**Parameters**

- `resumeData` (`Data`): Resume data returned from a previous incomplete upload.
- `notifyOnFinished` (`{ success: string, failure: string }`, optional): Whether to show a local notification when the upload finishes.

**Returns**

- `URLSessionUploadTask`: A new resumed upload task (starts automatically).

**Example**

```ts
const task = BackgroundURLSession.resumeUpload({
  resumeData,
  notifyOnFinished: {
    success: 'Resumed upload completed',
    failure: 'Resumed upload failed'
  }
})

task.resume()

task.onComplete = err => {
  if (!err) console.log('Resumed upload completed successfully')
}
```

***

### 6) `getUploadTasks(): Promise<URLSessionUploadTask[]>`

**Description:**
Retrieves all active or pending background upload tasks currently managed by the system.
Use this method after restarting your script to reattach callbacks to ongoing uploads.

**Signature**

```ts
function getUploadTasks(): Promise<URLSessionUploadTask[]>
```

**Returns**

- `Promise<URLSessionUploadTask[]>`: An array of active `URLSessionUploadTask` objects.

**Example**

```ts
const tasks = await BackgroundURLSession.getUploadTasks()
for (const task of tasks) {
  console.log('Task ID:', task.id, 'State:', task.state)
  task.onComplete = err => {
    if (err) console.error('Upload failed:', err)
  }
}
```

***

## Usage Notes and Best Practices

- **Start tasks:** Tasks begin in a suspended state, so you need to call `resume()` manually.
- **Pause and resume:** You can temporarily pause a task using `task.suspend()` and later call `task.resume()` to continue.
- **Resume support:** Download tasks can generate resume data via `cancelByProducingResumeData()`. Upload resumability depends on server capabilities.
- **Task restoration:** Even if your script is terminated, ongoing background tasks continue running. When restarted, use `getDownloadTasks()` or `getUploadTasks()` to retrieve them and reattach event handlers.
- **Local notifications:** The `notifyOnFinished` option only controls whether a notification is shown when a task completes; it does not affect task lifecycle or callbacks.



---
url: /guide/Utilities/URLSession/URLSessionDownloadTask.md
---

# URLSessionDownloadTask

`URLSessionDownloadTask` represents a background download task created by
`BackgroundURLSession.startDownload()` or `BackgroundURLSession.resumeDownload()`.
It allows scripts in the **Scripting app** to download files in the foreground or background, and the task can continue even if the script is terminated or the app is suspended.

Each download task is managed by the system and provides detailed state, progress, and event callbacks.

***

## Properties

### `id: string`

A unique identifier for the download task.
You can use this ID to recognize or reattach to the same task when your script restarts.

**Example**

```ts
console.log(task.id) // Prints the unique task ID
```

***

### `state: URLSessionTaskState`

The current state of the task.

Possible values:

- `"running"` — The task is currently downloading.
- `"suspended"` — The task is paused.
- `"canceling"` — The task is being canceled.
- `"completed"` — The task has finished.
- `"unknown"` — The state is unknown (usually when the task has been removed by the system).

**Example**

```ts
if (task.state === "running") {
  console.log("Download in progress...")
}
```

***

### `progress: URLSessionProgress`

Real-time progress information for the task.

Contains the following fields:

- `fractionCompleted: number` — Progress fraction between `0` and `1`.
- `totalUnitCount: number` — Total number of bytes to download.
- `completedUnitCount: number` — Number of bytes downloaded so far.
- `isFinished: boolean` — Whether the task has completed.
- `estimatedTimeRemaining: number | null` — Estimated remaining time (in seconds), or `null` if unknown.

**Example**

```ts
const p = task.progress
console.log(`Completed ${(p.fractionCompleted * 100).toFixed(2)}%`)
```

***

### `priority: number`

The priority of the download task (range: `0.0–1.0`).
Defaults to `0.5`.
Higher values increase the likelihood that the system will prioritize this task.

**Example**

```ts
task.priority = 0.8
```

***

### `earliestBeginDate?: Date | null`

The earliest date when the download task is allowed to begin.
Useful for delaying downloads or optimizing bandwidth usage.

**Example**

```ts
task.earliestBeginDate = new Date(Date.now() + 10_000) // start after 10 seconds
```

***

### `countOfBytesClientExpectsToSend: number`

A best-guess upper bound on the number of bytes expected to send (for system estimation only).

### `countOfBytesClientExpectsToReceive: number`

A best-guess upper bound on the number of bytes expected to receive (for system estimation only).

***

## Callbacks

### `onProgress?: (details) => void`

Called periodically as the download progresses.

**details** includes:

- `progress: number` — Progress fraction between `0` and `1`.
- `bytesWritten: number` — Bytes written since the last update.
- `totalBytesWritten: number` — Total bytes downloaded so far.
- `totalBytesExpectedToWrite: number` — Total expected bytes for the download.

**Example**

```ts
task.onProgress = details => {
  console.log(`Download progress: ${(details.progress * 100).toFixed(1)}%`)
}
```

***

### `onFinishDownload?: (error, details) => void`

Called when the download finishes (successfully or with an error).

**Parameters**

- `error: Error | null` — Error object if the download failed, otherwise `null`.
- `details.temporary: string` — The temporary file path used by the system.
- `details.destination: string | null` — The final destination path (if successful) or `null` if the download failed.

> The downloaded file is automatically moved to the specified `destination` path upon completion.

**Example**

```ts
task.onFinishDownload = (error, details) => {
  if (error) {
    console.error("Download failed:", error)
  } else {
    console.log("Download completed at:", details.destination)
  }
}
```

***

### `onComplete?: (error, resumeData) => void`

Called when the task finishes completely (either successfully or unsuccessfully).

**Parameters**

- `error: Error | null` — Error object if the download failed, otherwise `null`.
- `resumeData: Data | null` — Resume data available if the download can be resumed later.

**Example**

```ts
task.onComplete = (error, resumeData) => {
  if (error) {
    console.error("Download error:", error)
    if (resumeData) {
      console.log("Resume data is available for resuming the download")
    }
  } else {
    console.log("Download completed successfully")
  }
}
```

***

## Methods

### `suspend(): void`

Suspends the download task.
While suspended, the task produces no network activity and is not subject to timeouts.
You can later call `resume()` to continue.

**Example**

```ts
task.suspend()
console.log("Task suspended")
```

***

### `resume(): void`

Resumes a suspended task.
Call this only if the task is in a `"suspended"` state.

**Example**

```ts
task.resume()
console.log("Task resumed")
```

***

### `cancel(): void`

Cancels the download task immediately.
The task enters the `"canceling"` state, and the `onComplete` callback is triggered with an error once cancellation finishes.

**Example**

```ts
task.cancel()
console.log("Task canceled")
```

***

### `cancelByProducingResumeData(): Promise<Data | null>`

Cancels the download task and attempts to produce resume data.
If resumable, the returned promise resolves to `Data` which can be used later with
`BackgroundURLSession.resumeDownload()`.
Otherwise, it resolves to `null`.

**Example**

```ts
const resumeData = await task.cancelByProducingResumeData()
if (resumeData) {
  console.log("Download canceled; resume data available for later resumption")
}
```

***

## Example Usage

```ts
const task = BackgroundURLSession.startDownload({
  url: "https://example.com/largefile.zip",
  destination: "/.../Downloads/largefile.zip",
  notifyOnFinished: true
})

task.onProgress = ({ progress }) => {
  console.log(`Progress: ${(progress * 100).toFixed(1)}%`)
}

task.onFinishDownload = (error, details) => {
  if (error) {
    console.error("Download failed:", error)
  } else {
    console.log("Download completed at:", details.destination)
  }
}

task.onComplete = async (error, resumeData) => {
  if (error && resumeData) {
    console.log("Resume data available — save it to resume later")
  }
}
```

***

## Notes and Best Practices

- You need to call `resume()` start the download when you create a task by `BackgroundURLSession.startDownload()`.
- Use `cancelByProducingResumeData()` to implement **download resumption**.
- Even if the script exits or is terminated, downloads continue in the background.
- After restarting the script, use `BackgroundURLSession.getDownloadTasks()` to recover existing tasks and reattach callbacks.
- For long-running tasks, use `notifyOnFinished` to inform the user when a download completes.



---
url: /guide/Utilities/URLSession/URLSessionUploadTask.md
---

# URLSessionUploadTask

`URLSessionUploadTask` represents a background upload task instance.
It is created via `BackgroundURLSession.startUpload()` or `BackgroundURLSession.resumeUpload()` and allows file uploads to continue in the **Scripting app**, even when the app is in the background or the script is terminated.

Each upload task provides real-time state, progress, and event callbacks for tracking upload activity.

***

## Properties

### `id: string`

A unique identifier for the upload task.
This value can be used to recognize and reattach to the same task after restarting a script.

**Example**

```ts
console.log(task.id) // Prints the unique task ID
```

***

### `state: URLSessionTaskState`

The current state of the upload task.

Possible values:

- `"running"` — The task is currently uploading
- `"suspended"` — The task is paused
- `"canceling"` — The task is being canceled
- `"completed"` — The task has completed
- `"unknown"` — The task’s state is unknown (usually if removed by the system)

**Example**

```ts
if (task.state === "running") {
  console.log("Upload in progress...")
}
```

***

### `progress: URLSessionProgress`

Real-time progress information for the upload task.

Contains the following fields:

- `fractionCompleted: number` — Completion ratio between `0` and `1`
- `totalUnitCount: number` — Total number of bytes expected to upload
- `completedUnitCount: number` — Number of bytes uploaded so far
- `isFinished: boolean` — Whether the task has finished
- `estimatedTimeRemaining: number | null` — Estimated remaining time in seconds (may be `null`)

**Example**

```ts
const p = task.progress
console.log(`Upload progress: ${(p.fractionCompleted * 100).toFixed(1)}%`)
```

***

### `priority: number`

The upload priority (range: `0.0–1.0`).
Defaults to `0.5`.
Higher values indicate a higher scheduling priority for the system.

**Example**

```ts
task.priority = 0.8
```

***

### `earliestBeginDate?: Date | null`

Specifies the earliest date and time when the upload task may begin.
Useful for delaying uploads until conditions like network availability or power are favorable.

**Example**

```ts
task.earliestBeginDate = new Date(Date.now() + 5000) // Begin after 5 seconds
```

***

### `countOfBytesClientExpectsToSend: number`

A best-guess upper bound of bytes expected to send (for system estimation only).

### `countOfBytesClientExpectsToReceive: number`

A best-guess upper bound of bytes expected to receive (for system estimation only).

***

## Callbacks

### `onReceiveData?: (data: Data) => void`

Triggered when response data is received from the server.
The `data` parameter contains binary data from the server.

**Example**

```ts
task.onReceiveData = data => {
  console.log("Received response data:", data.length, "bytes")
}
```

***

### `onComplete?: (error: Error | null, resumeData: Data | null) => void`

Triggered when the upload task finishes, whether successfully or with an error.

**Parameters**

- `error`: If the upload failed, contains the error object; otherwise `null`.
- `resumeData`: If the upload failed and can be resumed, contains resume data (`Data`); otherwise `null`.

**Example**

```ts
task.onComplete = (error, resumeData) => {
  if (error) {
    console.error("Upload failed:", error)
    if (resumeData) {
      console.log("Upload is resumable — save resumeData for later recovery")
    }
  } else {
    console.log("Upload completed successfully!")
  }
}
```

***

## Methods

### `suspend(): void`

Pauses the upload task.
A suspended task produces no network traffic and isn’t subject to timeouts.
Use `resume()` to continue the upload later.

**Example**

```ts
task.suspend()
console.log("Task suspended")
```

***

### `resume(): void`

Resumes a suspended upload task.
Newly-initialized tasks begin in a suspended state, so you need to call this method to start the task.

**Example**

```ts
task.resume()
console.log("Upload resumed")
```

***

### `cancel(): void`

Cancels the upload task immediately.
The task enters the `"canceling"` state, and the `onComplete` callback is invoked with an error once cancellation finishes.

**Example**

```ts
task.cancel()
console.log("Task canceled")
```

***

## Example Usage

```ts
const task = BackgroundURLSession.startUpload({
  filePath: "/path/to/file.txt",
  toURL: "https://api.example.com/upload",
  method: "POST",
  headers: { Authorization: "Bearer my_token" },
  notifyOnFinished: true
})

task.resume()

task.onReceiveData = data => {
  console.log("Received response:", data.length, "bytes")
}

task.onComplete = (error, resumeData) => {
  if (error) {
    console.error("Upload error:", error)
    if (resumeData) console.log("Resume data available — can retry later")
  } else {
    console.log("Upload completed successfully")
  }
}
```

***

## Notes and Best Practices

- You can pause a task with `suspend()` and later resume it with `resume()`.
- Some servers support resumable uploads; if supported, you can use `resumeData` for recovery.
- Uploads can continue even if the script or app is suspended or terminated.
- Use `BackgroundURLSession.getUploadTasks()` to retrieve and reattach callbacks to ongoing uploads after restarting your script.
- Setting `notifyOnFinished` allows a local notification to alert users when the upload completes.
- When including authorization information (e.g., `Authorization` headers), ensure credentials are stored and managed securely.



---
url: /guide/Utilities/UUID.md
---

# UUID

The `UUID` module provides an easy way to generate unique UUID strings.

***

## Functions

### `string(): string`

Generates a new UUID (Universally Unique Identifier) in string format.

- **Returns**:\
  A UUID string (e.g., `"550e8400-e29b-41d4-a716-446655440000"`).

***

## Usage Example

```tsx
const id = UUID.string()
console.log('Generated UUID:', id)
```



---
url: /guide/Utilities/WebScoket.md
---

# WebScoket

The `WebSocket` class provides an interface for creating and managing WebSocket connections, allowing for real-time communication with a server. You can send and receive both text and binary data, including byte buffers, over the WebSocket connection.

***

## Overview

WebSocket is a communication protocol that allows full-duplex communication between a client and a server. This makes it ideal for real-time applications like live messaging, notifications, or streaming data.

***

## Class: `WebSocket`

### Constructor

#### `new WebSocket(url: string)`

Creates a new WebSocket connection to the specified URL and attempts to establish a connection immediately.

- **Parameters**:
  - `url: string`: The WebSocket server URL to connect to. Example: `"ws://example.com/socket"` or `"wss://example.com/socket"` for secure WebSocket connections.

- **Returns**: A `WebSocket` object representing the connection.

***

### Properties

- **`url: string`**\
  The URL to which the WebSocket is connected. This property is read-only.

- **`onopen?: () => void`**\
  Optional callback function triggered when the WebSocket connection is successfully established.

- **`onerror?: (error: Error) => void`**\
  Optional callback function triggered when an error occurs during the WebSocket connection or communication.

- **`onmessage?: (message: string | Data) => void`**\
  Optional callback function triggered when a message is received from the WebSocket server. The `message` parameter can be either a string or binary data, represented by the `Data` class.

- **`onclose?: (reason?: string) => void`**\
  Optional callback function triggered when the WebSocket connection is closed. The `reason` parameter provides an optional explanation for the closure.

***

### Methods

#### `send(message: string | Data): void`

Sends data to the server over the WebSocket connection.

- **Parameters**:
  - `message: string | Data`: The data to be sent to the server. It can be a string or an instance of the `Data` class.

- **Returns**: `void`

#### `close(code?: 1000 | 1001 | 1002 | 1003, reason?: string): void`

Closes the WebSocket connection. If the connection is already closed, this method does nothing.

- **Parameters**:
  - `code?: 1000 | 1001 | 1002 | 1003`: An optional WebSocket connection close code. Common codes include:
    - `1000`: Normal closure
    - `1001`: Going away
    - `1002`: Protocol error
    - `1003`: Unsupported data type
  - `reason?: string`: An optional reason for closing the connection. This string must be no longer than 123 bytes (UTF-8 encoded).

- **Returns**: `void`

***

### Event Handling

You can listen for WebSocket events using `addEventListener` and remove event listeners with `removeEventListener`.

#### `addEventListener(event: "open", listener: () => void): void`

Adds an event listener for the `"open"` event, triggered when the WebSocket connection is established.

#### `addEventListener(event: "error", listener: (error: Error) => void): void`

Adds an event listener for the `"error"` event, triggered when an error occurs during the WebSocket connection.

#### `addEventListener(event: "message", listener: (message: string | Data) => void): void`

Adds an event listener for the `"message"` event, triggered when a message is received from the WebSocket server.

#### `addEventListener(event: "close", listener: (reason?: string) => void): void`

Adds an event listener for the `"close"` event, triggered when the WebSocket connection is closed.

#### `removeEventListener(event: "open", listener: () => void): void`

Removes an event listener for the `"open"` event.

#### `removeEventListener(event: "error", listener: (error: Error) => void): void`

Removes an event listener for the `"error"` event.

#### `removeEventListener(event: "message", listener: (message: string | Data) => void): void`

Removes an event listener for the `"message"` event.

#### `removeEventListener(event: "close", listener: (reason?: string) => void): void`

Removes an event listener for the `"close"` event.

***

## Example Usage

### Establishing a WebSocket Connection

```ts
const ws = new WebSocket("wss://example.com/socket")

// Set up event listeners
ws.addEventListener("open", () => {
  console.log("Connection established!")
  ws.send("Hello, Server!")
})

ws.addEventListener("message", (message) => {
  console.log("Received message:", message)
})

ws.addEventListener("error", (error) => {
  console.log("WebSocket error:", error)
})

ws.addEventListener("close", (reason) => {
  console.log("Connection closed:", reason)
})
```

### Sending a String Message

```ts
const ws = new WebSocket("wss://example.com/socket")

ws.addEventListener("open", () => {
  ws.send("Hello, this is a test message!")
})
```

### Sending Binary Data Using `Data`

```ts
const ws = new WebSocket("wss://example.com/socket")

ws.addEventListener("open", () => {
  const data = Data.fromString("some message")
  ws.send(data) // Send binary data
})
```

### Handling Binary Data

```ts
const ws = new WebSocket("wss://example.com/socket")

ws.addEventListener("message", (message) => {
  if (message instanceof Data) {
    const byteArray = message.getBytes()
    if (byteArray) {
      console.log("Received binary data:", byteArray)
    }
  }
})
```

### Closing the WebSocket Connection

```ts
const ws = new WebSocket("wss://example.com/socket")

ws.addEventListener("open", () => {
  console.log("Connection established!")
  // Close the connection with a custom reason
  ws.close(1000, "Closing connection after test")
})
```

***

## Notes

- The `send()` method can handle both text and binary data. For binary data, you can use the `Data` class to handle the byte buffer.
- For binary data, ensure that your WebSocket server is capable of handling binary data, such as `ArrayBuffer` or `Uint8Array`.
- The `close()` method can take a `code` and an optional `reason` to specify how the WebSocket connection should close.



---
url: /guide/Utilities/WebScraper.md
---

The `WebScraper` module provides a lightweight web scraping service that allows scripts to reliably load web pages and retrieve their HTML content or extract structured data from them.

The module loads web pages in a controlled environment and supports multiple waiting strategies (such as DOM completion, network idle, or waiting for specific elements). These strategies help ensure stability when scraping modern websites that rely on dynamic rendering.

Typical use cases include:

- Retrieving the final rendered HTML of a page
- Extracting structured data by running JavaScript in the page context
- Waiting for dynamic content to load before scraping
- Writing stable automation scripts for web data extraction

All operations are executed as **asynchronous tasks**. Each task has a unique `taskId`, which can be used to track or cancel the task.

***

# Type Definitions

## WaitOptions

Defines the strategy used to determine when a page has finished loading.

```ts
type WaitOptions =
  | "domComplete"
  | "networkIdle"
  | {
      mode: "domComplete"
    }
  | {
      mode: "networkIdle"
      idleSeconds?: number
    }
  | {
      mode: "selector"
      selector: string
    }
```

### Available Modes

#### `"domComplete"`

Waits until `document.readyState === "complete"`.

Suitable for:

- Static websites
- Simple pages
- Websites that do not rely heavily on asynchronous loading

Example:

```ts
wait: "domComplete"
```

***

#### `"networkIdle"`

Waits until the page network activity becomes idle.

When no new network requests occur within a period of time, the page is considered fully loaded.

Suitable for:

- SPA applications
- Pages that fetch data via APIs
- Websites with dynamic content loading

Example:

```ts
wait: "networkIdle"
```

You may also specify the idle duration:

```ts
wait: {
  mode: "networkIdle",
  idleSeconds: 2
}
```

***

#### `"selector"`

Waits until a specific DOM element appears.

When an element matching the selector exists in the document, the task continues.

Suitable for:

- Dynamically rendered content
- Waiting for specific UI components
- Precisely controlling when scraping begins

Example:

```ts
wait: {
  mode: "selector",
  selector: ".article-content"
}
```

***

# Error

Represents error information when a scraping task fails.

```ts
type Error = {
  code: string
  message: string
}
```

### Properties

#### code

An error code identifying the type of failure.

Examples:

```
NETWORK_ERROR
TIMEOUT
SCRIPT_ERROR
```

#### message

A human-readable error message describing the failure.

Example:

```
Request timed out
```

***

# Timing

Represents execution timing information for a task.

```ts
type Timing = {
  totalMs: number
}
```

### Properties

#### totalMs

The total execution time of the task in milliseconds.

***

# Result

All `WebScraper` APIs return results using the `Result` type.

```ts
type Result<T = any> = {
  ok: boolean
  taskId: string
  url?: string
  html?: string
  data?: T
  error?: Error
  timing?: Timing
}
```

### Properties

#### ok

Indicates whether the task completed successfully.

```
true   task succeeded
false  task failed
```

***

#### taskId

The unique identifier of the task.

If `taskId` is not specified when starting the task, the system automatically generates one.

It can be used to cancel the task:

```ts
WebScraper.cancel(taskId)
```

***

#### url

The final loaded URL.

If redirects occurred during navigation, this field contains the final destination URL.

***

#### html

The final HTML of the page.

This is typically the **rendered DOM HTML**, not the raw HTML response.

***

#### data

The data returned by `extractScript` or `eval`.

The type of this field is defined by the generic parameter `T`.

***

#### error

Returned when the task fails.

Contains error information.

***

#### timing

Timing information about the task execution.

***

# API

## load

Loads a web page and returns the final HTML.

```ts
function load(options: {
  url: string
  wait?: WaitOptions
  timeout?: number
  taskId?: string
}): Promise<Result<string>>
```

### Parameters

#### url

The URL of the page to load.

Example:

```ts
url: "https://example.com"
```

***

#### wait

The waiting strategy used to determine when the page is ready.

Default:

```
"domComplete"
```

***

#### timeout

The maximum allowed time for the task in **seconds**.

If the task does not finish within the specified time, it fails with a timeout error.

Example:

```
timeout: 15
```

***

#### taskId

An optional task identifier.

If not provided, the system automatically generates one.

***

### Example

```ts
const result = await WebScraper.load({
  url: "https://example.com",
  wait: "networkIdle"
})

if (result.ok) {
  console.log(result.html)
}
```

***

# scrape

Loads a page and optionally executes an extraction script in the page context.

```ts
function scrape<T = any>(options: {
  url: string
  wait?: WaitOptions
  timeout?: number
  extractScript?: string
  taskId?: string
}): Promise<Result<T>>
```

This method performs the following steps:

1. Load the page
2. Wait until the specified condition is satisfied
3. Execute `extractScript` in the page context
4. Return both the HTML and extracted data

***

### Parameters

#### extractScript

JavaScript code executed in the page context.

The script should return the data to extract.

Example:

```ts
extractScript: `
  return {
    title: document.title,
    articles: Array.from(document.querySelectorAll("article")).map(el => ({
      title: el.querySelector("h2")?.innerText,
      link: el.querySelector("a")?.href
    }))
  }
`
```

***

### Example

```ts
const result = await WebScraper.scrape({
  url: "https://news.ycombinator.com",
  wait: {
    mode: "selector",
    selector: ".athing"
  },
  extractScript: `
    return Array.from(document.querySelectorAll(".athing")).map(el => ({
      title: el.querySelector(".titleline a")?.innerText,
      url: el.querySelector(".titleline a")?.href
    }))
  `
})

if (result.ok) {
  console.log(result.data)
}
```

***

# eval

Evaluates JavaScript in the page context and returns the result.

```ts
function eval<T = any>(options: {
  url: string
  script: string
  wait?: WaitOptions
  timeout?: number
  taskId?: string
}): Promise<Result<T>>
```

This method is intended for executing custom JavaScript logic inside the page.

Compared to `scrape`:

- `eval` focuses on executing arbitrary JavaScript
- `scrape` is designed specifically for extracting data

***

### Parameters

#### script

JavaScript code executed in the page context.

The script must return a value.

***

### Example

```ts
const result = await WebScraper.eval({
  url: "https://example.com",
  script: `
    return {
      title: document.title,
      links: document.links.length
    }
  `
})

if (result.ok) {
  console.log(result.data)
}
```

***

# cancel

Cancels a running scraping task.

```ts
function cancel(taskId: string): Promise<boolean>
```

### Parameters

#### taskId

The identifier of the task to cancel.

***

### Return Value

```
true   task was successfully cancelled
false  task not found or already finished
```

***

### Example

```ts
const taskId = "scrape-news"

WebScraper.scrape({
  url: "https://example.com",
  taskId
})

await WebScraper.cancel(taskId)
```

***

# Usage Recommendations

## Choose an Appropriate Waiting Strategy

Different types of websites benefit from different strategies.

| Scenario                      | Recommended wait |
| ----------------------------- | ---------------- |
| Static pages                  | `"domComplete"`  |
| SPA applications              | `"networkIdle"`  |
| Waiting for specific elements | `"selector"`     |

***

## Prefer selector Waiting for Dynamic Content

For dynamic pages, waiting for a specific element improves reliability.

```ts
wait: {
  mode: "selector",
  selector: ".content"
}
```

***

## Adjust Timeout for Complex Pages

Complex sites may require longer timeouts.

```
timeout: 20
```

***

## Prefer extractScript Instead of Parsing HTML

Instead of retrieving HTML and parsing it manually:

```ts
const html = result.html
```

It is often more efficient to extract data directly in the page:

```ts
extractScript: `
  return document.title
`
```

This approach reduces script complexity and improves performance.



---
url: /guide/Utilities/socket.io.md
---

# socket.io

The `Socket.IO` API provides robust tools for managing real-time, bidirectional communication between clients and servers. It includes a `SocketManager` for handling multiple namespaces and a `SocketIOClient` for individual socket connections. This document provides an overview of the API, including setup, configuration, and usage.

***

## Getting Started

The `Socket.IO` API allows you to create and manage WebSocket connections using a `SocketManager`. Each `SocketManager` can handle multiple namespaces and configurations.

### Example:

```typescript
// Create a SocketManager instance
const manager = new SocketManager("http://localhost:8080", {
    reconnects: true,
    reconnectAttempts: 5,
    compress: true
})

// Access the default namespace socket
const defaultSocket = manager.defaultSocket

// Create a socket for a specific namespace
const roomASocket = manager.socket("/roomA")
```

***

## API Reference

### SocketManager

#### Constructor

**`constructor(url: string, config?: SocketManagerConfig)`**

- **`url`**: The URL of the Socket.IO server.
- **`config`**: Optional configuration object.

#### Properties

- **`socketURL: string`**: The server URL.
- **`status: SocketIOStatus`**: The manager's connection status (`connected`, `connecting`, `disconnected`, etc.).
- **`defaultSocket: SocketIOClient`**: The socket for the default namespace (`"/"`).

#### Methods

- **`socket(namespace: string): SocketIOClient`**
  - Returns a `SocketIOClient` for the specified namespace.

- **`setConfigs(config: SocketManagerConfig): void`**
  - Updates the manager's configuration.

- **`disconnect(): void`**
  - Disconnects all sockets managed by this instance.

- **`reconnect(): void`**
  - Attempts to reconnect to the server.

### SocketIOClient

#### Properties

- **`id: string | null`**: The unique identifier for the socket connection.
- **`status: SocketIOStatus`**: The client's connection status (`connected`, `connecting`, etc.).

#### Methods

- **`connect(): void`**
  - Initiates a connection.

- **`disconnect(): void`**
  - Disconnects the socket.

- **`emit(event: string, data: any): void`**
  - Sends an event to the server with associated data.

- **`on(event: string, callback: (data: any[], ack: (value?: any) => void) => void): void`**
  - Registers an event listener.

***

## Configuration

The `SocketManagerConfig` object allows you to customize connection behavior.

### Key Options:

- **`compress`**: Enables compression for WebSocket transport.
- **`connectParams`**: A dictionary of GET parameters included in the connection URL.
- **`cookies`**: An array of cookies to send during the initial connection.
- **`forceNew`**: Ensures a new engine is created for every connection.
- **`reconnects`**: Enables automatic reconnection.
- **`reconnectAttempts`**: Sets the maximum number of reconnection attempts.
- **`reconnectWait`**: Minimum time (in seconds) between reconnection attempts.

### Example:

```typescript
const config: SocketManagerConfig = {
    compress: true,
    reconnects: true,
    reconnectAttempts: 5,
    reconnectWait: 2,
    extraHeaders: {
        Authorization: "Bearer token"
    }
}
const manager = new SocketManager("http://example.com", config)
```

***

## Common Use Cases

### Emit and Listen to Events

```typescript
const socket = manager.defaultSocket

socket.on("connect", () => {
    console.log("Connected to server")
    socket.emit("joinRoom", { room: "roomA" })
})

socket.on("message", (data) => {
    console.log("Message received:", data)
})
```

### Handle Reconnection

```typescript
manager.setConfigs({ reconnects: true, reconnectAttempts: 10 })

manager.defaultSocket.on("reconnect", () => {
    console.log("Reconnected to server")
})
```

### Use Namespaces

```typescript
const chatSocket = manager.socket("/chat")

chatSocket.on("newMessage", (data) => {
    console.log("New message in chat:", data)
})
```

***

## Best Practices

1. **Manage Lifecycles:** Always call `disconnect()` when sockets are no longer needed.
2. **Namespace Isolation:** Use separate namespaces for logically distinct communication channels.
3. **Reconnection Strategies:** Configure reconnection parameters based on your app's requirements.
4. **Error Handling:** Register an `on("error")` handler to gracefully handle connection issues.
5. **Secure Connections:** Use secure WebSocket (WSS) for sensitive data and configure `secure: true`.

***

## Full Example

```typescript
// Create a SocketManager with configuration
const manager = new SocketManager("https://example.com", {
    reconnects: true,
    reconnectAttempts: -1,
    reconnectWait: 1
})

// Access the default namespace
const socket = manager.defaultSocket

// Register event handlers
socket.on("connect", () => {
    console.log("Connected to server")
    socket.emit("join", { room: "lobby" })
})

socket.on("message", (data) => {
    console.log("Message received:", data)
})

socket.on("disconnect", () => {
    console.log("Disconnected from server")
})

// Emit a custom event
socket.emit("sendMessage", { text: "Hello, world!" })

// Disconnect when done
setTimeout(() => {
    manager.disconnect()
}, 60000)
```



---
url: /guide/View Modifiers/Animation and Transition.md
---

# Animation and Transition

Scripting Animation & Transition System

## Animation Class

The `Animation` class describes how values animate in time.

## Factory Methods

### `Animation.default()`

Creates a default system animation.

```ts
static default(): Animation
```

***

### `Animation.linear(duration?)`

```ts
static linear(duration?: number | null): Animation
```

Constant-speed animation.

***

### `Animation.easeIn(duration?)`

```ts
static easeIn(duration?: number | null): Animation
```

***

### `Animation.easeOut(duration?)`

```ts
static easeOut(duration?: number | null): Animation
```

***

### `Animation.bouncy(options?)`

```ts
static bouncy(options?: {
  duration?: number
  extraBounce?: number
}): Animation
```

Spring-like animation with additional bounce.

***

### `Animation.smooth(options?)`

```ts
static smooth(options?: {
  duration?: number
  extraBounce?: number
}): Animation
```

***

### `Animation.snappy(options?)`

```ts
static snappy(options?: {
  duration?: number
  extraBounce?: number
}): Animation
```

***

### `Animation.spring(options?)`

Supports two mutually exclusive modes.

```ts
static spring(options?: {
  blendDuration?: number
} & (
  | {
      duration?: number
      bounce?: number
      response?: never
      dampingFraction?: never
    }
  | {
      response?: number
      dampingFraction?: number
      duration?: never
      bounce?: never
    }
)): Animation
```

***

### `Animation.interactiveSpring(options?)`

```ts
static interactiveSpring(options?: {
  response?: number
  dampingFraction?: number
  blendDuration?: number
}): Animation
```

***

### `Animation.interpolatingSpring(options?)`

```ts
static interpolatingSpring(options?: {
  mass?: number
  stiffness: number
  damping: number
  initialVelocity?: number
} | {
  duration?: number
  bounce?: number
  initialVelocity?: number
  mass?: never
  stiffness?: never
  damping?: never
}): Animation
```

***

## Modifier Methods

### `.delay(time)`

```ts
delay(time: number): Animation
```

### `.repeatCount(count, autoreverses)`

```ts
repeatCount(count: number, autoreverses?: boolean): Animation
```

### `.repeatForever(autoreverses)`

```ts
repeatForever(autoreverses?: boolean): Animation
```

***

## Transition Class

`Transition` describes how a view enters or leaves the hierarchy.

## Instance Methods

### `.animation(animation)`

Attach a specific animation to a transition.

```ts
animation(animation?: Animation): Transition
```

### `.combined(other)`

Combine transitions.

```ts
combined(other: Transition): Transition
```

***

## Static Transitions

### Identity

```ts
Transition.identity()
```

### Move

```ts
Transition.move(edge: Edge)
```

### Offset

```ts
Transition.offset(position?: Point)
```

### Push

```ts
Transition.pushFrom(edge: Edge)
```

### Opacity

```ts
Transition.opacity()
```

### Scale

```ts
Transition.scale(scale?: number, anchor?: Point | KeywordPoint)
```

### Slide

```ts
Transition.slide()
```

### Fade

```ts
Transition.fade(duration?: number)
```

### Flip transitions

```ts
Transition.flipFromLeft(duration?)
Transition.flipFromRight(duration?)
Transition.flipFromTop(duration?)
Transition.flipFromBottom(duration?)
```

### Asymmetric

```ts
Transition.asymmetric(insertion: Transition, removal: Transition)
```

***

## withAnimation

```ts
function withAnimation(body: () => void): Promise<void>
function withAnimation(animation: Animation, body: () => void): Promise<void>
function withAnimation(
  animation: Animation,
  completionCriteria: "logicallyComplete" | "removed",
  body: () => void
): Promise<void>
```

Wraps a state update and animates any affected values.

Example:

```ts
withAnimation(Animation.easeOut(0.3), () => {
  visible.setValue(false)
})
```

***

## Correct Usage of the animation View Modifier

### (Important Correction)

In Scripting, the `animation` prop is **not**:

```tsx
animation={anim}     // incorrect
```

The correct format is:

```tsx
animation={{
  animation: anim,
  value: <observable or value>
}}
```

### Meaning:

| Field       | Description                                           |
| ----------- | ----------------------------------------------------- |
| `animation` | The `Animation` instance to use                       |
| `value`     | The observable value whose changes should be animated |

This mirrors SwiftUI’s `.animation(animation, value: value)` modifier.

***

## Correct Examples

### Example: Animate size changes

```tsx
const size = useObservable(100)
const anim = Animation.spring({ duration: 0.3, bounce: 0.3 })

<Rectangle
  frame={{ width: size.value, height: size.value }}
  animation={{ animation: anim, value: size.value }}
/>

<Button
  title="Toggle Size"
  action={() => {
    size.setValue(size.value === 100 ? 200 : 100)
  }}
/>
```

### Example: Animate color changes

```tsx
const isOn = useObservable(false)

<Text
  color={isOn.value ? "red" : "blue"}
  animation={{
    animation: Animation.easeIn(0.25),
    value: isOn.value
  }}
>
  Changing color
</Text>
```

### Example: Animate layout changes

```tsx
const expanded = useObservable(false)

<VStack
  spacing={expanded.value ? 40 : 10}
  animation={{
    animation: Animation.smooth({ duration: 0.3 }),
    value: expanded.value
  }}
>
```

***

## Transition Usage Examples

### Simple visibility toggle with transition

```tsx
const visible = useObservable(true)

<VStack>
  {visible.value &&
    <Text
      transition={Transition
        .slide()
        .combined(Transition.opacity())
      }
    >
      Slide + Fade
    </Text>
  }

  <Button
    title="Toggle"
    action={() => {
      withAnimation(() => {
        visible.setValue(!visible.value)
      })
    }}
  />
</VStack>
```

***

## Combined Example: Animation + Transition

```tsx
const visible = useObservable(true)
const anim = Animation.spring({ duration: 0.4, bounce: 0.25 })

<VStack spacing={12}>
  {visible.value &&
    <Text
      transition={Transition
        .move("bottom")
        .combined(Transition.opacity())
        .animation(anim)
      }
    >
      Animated panel
    </Text>
  }

  <Button
    title="Toggle"
    action={() => {
      withAnimation(anim, () => {
        visible.setValue(!visible.value)
      })
    }}
  />
</VStack>
```

***

## Summary

### Key Points

- `useObservable` drives UI updates.
- `withAnimation` animates state changes.
- `Transition` defines enter/exit effects.
- **Correct animation modifier usage**:

```tsx
animation={{ animation: myAnimation, value: myValue }}
```



---
url: /guide/View Modifiers/Chaining View Modifiers.md
---

# Chaining View Modifiers

The `modifiers` property allows you to apply multiple view modifiers to a view using a fluent, chainable syntax. This API is a flexible and expressive alternative to the traditional single `modifier` attribute on a view in TSX, which only supports one layer of modification.

With `modifiers`, you can apply the same modifier multiple times (e.g., nested paddings or backgrounds), control modifier order explicitly, and build view style stacks that are closer in spirit to SwiftUI.

***

## Type

```ts
declare function modifiers(): ViewModifiers;

declare class ViewModifiers {
  // Example methods:
  padding(value): this;
  background(value): this;
  opacity(value): this;
  frame(value): this;
  font(value): this;
  // ... and many more (same as `CommonViewProps`)
}
```

> The `ViewModifiers` class contains chainable methods for nearly all standard SwiftUI view modifiers, including layout, styling, interaction, and animation. Each method returns `this`, enabling fluent chaining.

***

## Benefits

- **Supports multiple instances** of the same modifier (e.g., multiple `.padding()` or `.background()` layers).
- **Preserves modifier order**, ensuring layout and appearance behave as expected.
- **Increased modularity**, making it easier to abstract and reuse modifier chains.
- **SwiftUI-like syntax**, aligning more closely with native SwiftUI best practices.

***

## Usage Examples

### Example 1: Layered background and padding

```tsx
<VStack
  modifiers={
    modifiers()
      .padding()
      .background("red")
      .padding()
      .background("blue")
  }
>
  <Text>Hello</Text>
</VStack>
```

This will produce a layout similar to:

```swift
Text("Hello")
  .padding()
  .background(Color.red)
  .padding()
  .background(Color.blue)
```

### Example 2: Reusable modifier chain

```ts
const myModifiers = modifiers()
  .padding(12)
  .background("gray")
  .cornerRadius(8)
  .opacity(0.9)

<List modifiers={myModifiers}>
  <Text>Item 1</Text>
</List>
```

### Example 3: Composing modifiers dynamically

```ts
const base = modifiers().padding()

if (isDarkMode) {
  base.background("black")
} else {
  base.background("white")
}

return <HStack modifiers={base}>...</HStack>
```

***

## When to Use

Use `modifiers` when:

- You need multiple layers of the same modifier (e.g., multiple paddings or backgrounds).
- You want to cleanly separate style logic into reusable chains.
- You prefer an imperative, fluent way to express modifier order.
- You are dynamically building view styles based on runtime conditions.

***

## Full Modifier List

`ViewModifiers` exposes methods for over 200 modifiers, covering:

- **Layout**: `padding`, `frame`, `offset`, `position`, `zIndex`, etc.
- **Styling**: `background`, `foregroundStyle`, `opacity`, `shadow`, `clipShape`, etc.
- **Text and Font**: `font`, `bold`, `italic`, `underline`, `kerning`, etc.
- **Interactions**: `onTapGesture`, `onAppear`, `onDisappear`, `contextMenu`, etc.
- **Scroll and Navigation**: `scrollDisabled`, `navigationTitle`, `sheet`, `popover`, etc.
- **Charts**: `chartXAxis`, `chartYAxisLabel`, `chartSymbolScale`, etc.
- **Widget-specific**: `widgetURL`, `widgetBackground`, etc.

> See the full type definition for all supported modifier methods.

***

## Notes

- Modifiers are applied in the **exact order** they are chained.
- Each call to `modifiers()` returns a fresh instance. If you call it multiple times, they do **not** merge.
- `modifiers` is preferred for complex chains.

***

This feature enhances expressiveness and power when building UI with TSX, offering a richer and more modular view configuration approach.



---
url: /guide/View Modifiers/ChartMarkProps/index.md
---

# ChartMarkProps

`ChartMarkProps` defines a set of visual and behavioral modifiers applicable to individual chart marks such as bars, lines, or areas. These modifiers allow developers to customize the appearance, layout, and dynamic behavior of chart elements in `BarChart`, `LineChart`, `AreaChart`, and other mark-based components.

***

## 1. Style Modifiers

### `foregroundStyle`

Specifies the fill style of the chart content.

- Type: `ShapeStyle | DynamicShapeStyle`
- Example:

  ```tsx
  foregroundStyle: "systemGreen"
  ```

### `opacity`

Sets the opacity of the mark, ranging from `0.0` (fully transparent) to `1.0` (fully opaque).

- Type: `number`
- Example:

  ```tsx
  opacity: 0.6
  ```

### `cornerRadius`

Sets the corner radius for shapes such as bars or capsules.

- Type: `number`
- Example:

  ```tsx
  cornerRadius: 8
  ```

### `lineStyle`

Applies stroke styles for line marks.

- Type: `StrokeStyle`
- Structure:

  ```ts
  {
    lineWidth?: number
    lineCap?: 'butt' | 'round' | 'square'
    lineJoin?: 'bevel' | 'miter' | 'round'
    mitterLimit?: number
    dash?: number[]
    dashPhase?: number
  }
  ```
- Example:

  ```tsx
  lineStyle: {
    lineWidth: 2,
    lineCap: "round",
    dash: [4, 2]
  }
  ```

### `interpolationMethod`

Controls how lines or areas interpolate between data points.

- Type: `ChartInterpolationMethod`
- Options:
  `"cardinal"`, `"catmullRom"`, `"linear"`, `"monotone"`, `"stepCenter"`, `"stepEnd"`, `"stepStart"`
- Example:

  ```tsx
  interpolationMethod: "catmullRom"
  ```

### `alignsMarkStylesWithPlotArea`

Determines whether styles align with the chart’s plot area.

- Type: `boolean`
- Example:

  ```tsx
  alignsMarkStylesWithPlotArea: true
  ```

***

## 2. Symbol Configuration (for Line/Scatter Charts)

### `symbol`

Sets a symbol type or a custom view as the plotting symbol.

- Type: `ChartSymbolShape | VirtualNode`
- Options:
  `"circle"`, `"square"`, `"triangle"`, `"diamond"`, `"cross"`, `"plus"`, `"asterisk"`, `"pentagon"`
- Example:

  ```tsx
  symbol: "triangle"
  ```

### `symbolSize`

Controls the symbol’s size.

- Type: `number | { width: number; height: number }`
- Example:

  ```tsx
  symbolSize: 18
  // or
  symbolSize: { width: 16, height: 16 }
  ```

***

## 3. Annotations

### `annotation`

Adds an annotation view positioned relative to a mark.

- Type: `VirtualNode | { position?, alignment?, spacing?, overflowResolution?, content }`
- Structure:

  ```ts
  {
    position?: AnnotationPosition
    alignment?: Alignment
    spacing?: number
    overflowResolution?: {
      x?: AnnotationOverflowResolutionStrategy
      y?: AnnotationOverflowResolutionStrategy
    }
    content: VirtualNode
  }
  ```
- Example:

  ```tsx
  annotation: {
    position: "top",
    alignment: "center",
    spacing: 4,
    overflowResolution: {
      x: "fit",
      y: "padScale"
    },
    content: <Text>Label</Text>
  }
  ```

#### `AnnotationPosition`

Defines where the annotation is placed relative to the mark.

- Type: string
- Values:

  - `"automatic"`
  - `"top"`, `"topLeading"`, `"topTrailing"`
  - `"bottom"`, `"bottomLeading"`, `"bottomTrailing"`
  - `"leading"`, `"trailing"`
  - `"overlay"` (overlay the mark itself)

#### `AnnotationOverflowResolutionStrategy`

Specifies how to handle annotation layout overflow.

- Type: string
- Values:

  - `"automatic"`: Selects the best resolution strategy automatically
  - `"fit"`: Adjusts the annotation to stay within the boundary
  - `"fitToPlot"`: Fits annotation within the plot area
  - `"fitToChart"`: Fits within the full chart bounds
  - `"fitToAutomatic"`: Automatically chooses between chart and plot bounds
  - `"padScale"`: Extends the chart scale to fit the annotation
  - `"disabled"`: Disables overflow resolution (allows clipping)

***

## 4. Shape Effects

### `clipShape`

Applies a clipping shape to the mark.

- Type: `'rect' | 'circle' | 'capsule' | 'ellipse' | 'buttonBorder' | 'containerRelative'`
- Example:

  ```tsx
  clipShape: "capsule"
  ```

### `shadow`

Adds a drop shadow to the mark.

- Type:

  ```ts
  {
    color?: string // e.g. "systemGray"
    radius: number
    x?: number
    y?: number
  }
  ```
- Example:

  ```tsx
  shadow: {
    color: "systemGray",
    radius: 5,
    x: 2,
    y: 2
  }
  ```

### `blur`

Applies a Gaussian blur effect.

- Type: `number`
- Example:

  ```tsx
  blur: 6
  ```

### `zIndex`

Controls the rendering order of the mark relative to others.

- Type: `number`
- Example:

  ```tsx
  zIndex: 2
  ```

### `offset`

Offsets the mark in one or more dimensions.

- Supported formats:

  - `{ x, y }`
  - `{ x, yStart, yEnd }`
  - `{ xStart, xEnd, y }`
  - `{ xStart, xEnd, yStart, yEnd }`
- Example:

  ```tsx
  offset: { x: 10, y: -5 }
  ```

***

## 5. Dynamic Data Mapping (`xxxBy`)

These properties dynamically bind mark appearance or position to data fields. They should not be used in combination with their corresponding static properties (e.g. `foregroundStyleBy` vs. `foregroundStyle`).

### `foregroundStyleBy`

Maps a data field to a foreground style.

- Type: `string | number | Date | { value, label }`
- Example:

  ```tsx
  foregroundStyleBy: {
    value: item.color,
    label: "Color"
  }
  ```

### `lineStyleBy`

Maps a data field to a line style.

- Example:

  ```tsx
  lineStyleBy: {
    value: item.pattern,
    label: "Line Style"
  }
  ```

### `positionBy`

Maps a data field to mark position and axis alignment.

- Type:

  ```ts
  {
    value: string | number | Date
    label?: string
    axis: 'horizontal' | 'vertical'
    span?: MarkDimension
  }
  ```
- Example:

  ```tsx
  positionBy: {
    value: item.category,
    axis: "horizontal",
    span: {
      type: "ratio",
      value: 0.8
    }
  }
  ```

#### `MarkDimension`

Controls the spacing or sizing behavior of the mark within its axis.

- Type: `"automatic"` or an object:

  ```ts
  {
    type: "inset" | "fixed" | "ratio"
    value: number
  }
  ```
- Explanation:

  - `"automatic"`: Lets the system determine the size
  - `"inset"`: Shrinks the size by an inset margin
  - `"fixed"`: Fixed screen-space size (in points)
  - `"ratio"`: Relative to available axis spacing (0 to 1)

### `symbolBy`

Maps a field to different symbol shapes.

- Example:

  ```tsx
  symbolBy: {
    value: item.category,
    label: "Type"
  }
  ```

### `symbolSizeBy`

Maps a field to symbol size.

- Example:

  ```tsx
  symbolSizeBy: {
    value: item.score,
    label: "Score"
  }
  ```

***

## Example: Grouped Bar Chart

```tsx
<BarChart
  marks={data.map(item => ({
    label: item.type,
    value: item.count,
    positionBy: {
      value: item.color,
      axis: "horizontal"
    },
    foregroundStyleBy: item.color,
    cornerRadius: 8
  }))}
/>
```



---
url: /guide/View Modifiers/Charts Style.md
---

# Charts Style

The Chart component in the Scripting app provides a highly customizable interface for creating and displaying various types of charts. This documentation explains how to use the properties of the Chart view to configure axes, scales, labels, legends, and more.

### **1. Axis Visibility**

- **`chartXAxis`**
  - **Type**: `"automatic" | "hidden" | "visible"`
  - **Description**: Sets the visibility of the X-axis.
  - **Example**:
    ```tsx
    <Chart chartXAxis="visible">
      <BarChart ... />
    </Chart>
    ```

- **`chartYAxis`**
  - **Type**: `"automatic" | "hidden" | "visible"`
  - **Description**: Sets the visibility of the Y-axis.
  - **Example**:
    ```tsx
    <Chart chartYAxis="hidden">
      <LineChart ... />
    </Chart>
    ```

***

### **2. Axis Labels**

- **`chartXAxisLabel`**
  - **Type**:
    ```ts
    {
      position?: "automatic" | "bottom" | "bottomLeading" | "bottomTrailing" | "leading" | "overlay" | "top" | "topLeading" | "topTrailing" | "trailing";
      alignment?: "leading" | "center" | "trailing";
      spacing?: number;
      content: VirtualNode;
    }
    ```
  - **Description**: Adds a label to the X-axis.
  - **Example**:
    ```tsx
    <Chart
      chartXAxisLabel={{
        position: "bottom",
        alignment: "center",
        spacing: 10,
        content: <Text>X Axis Label</Text>,
      }}
    >
      <BarChart ... />
    </Chart>
    ```

- **`chartYAxisLabel`**
  - **Type**: Same as `chartXAxisLabel`.
  - **Description**: Adds a label to the Y-axis.
  - **Example**:
    ```tsx
    <Chart
      chartYAxisLabel={{
        position: "leading",
        content: <Text>Y Axis Label</Text>,
      }}
    >
      <LineChart ... />
    </Chart>
    ```

***

### **3. Legend**

- **`chartLegend`**
  - **Type**:
    ```ts
    "automatic" | "hidden" | "visible" | {
      position?: "automatic" | "bottom" | "bottomLeading" | "bottomTrailing" | "leading" | "overlay" | "top" | "topLeading" | "topTrailing" | "trailing";
      alignment?: "leading" | "center" | "trailing";
      spacing?: number;
      content?: VirtualNode;
    }
    ```
  - **Description**: Configures the chart legend.
  - **Example**:
    ```tsx
    <Chart
      chartLegend={{
        position: "top",
        alignment: "center",
        content: <Text>Legend</Text>,
      }}
    >
      <AreaChart ... />
    </Chart>
    ```

***

### **4. Scales**

- **`chartXScale` / `chartYScale`**
  - **Type**:
    ```ts
    ClosedRange<number> | ClosedRange<Date> | string[] | "category" | "date" | "linear" | "log" | "squareRoot" | "symmetricLog" | {
      domain: ClosedRange<number> | ClosedRange<Date> | string[];
      type: "category" | "date" | "linear" | "log" | "squareRoot" | "symmetricLog";
    }
    ```
  - **Description**: Configures the X or Y-axis scale.
  - **Example**:
    ```tsx
    <Chart
      chartXScale={{ domain: { from: 0, to: 100 }, type: "linear" }}
      chartYScale={["A", "B", "C"]}
    >
      <LineChart ... />
    </Chart>
    ```

***

### **5. Background**

- **`chartBackground`**
  - **Type**:
    ```ts
    VirtualNode | {
      alignment?: "leading" | "center" | "trailing";
      content: VirtualNode;
    }
    ```
  - **Description**: Adds a background to the chart container.
  - **Example**:
    ```tsx
    <Chart
      chartBackground={{
        alignment: "center",
        content: <Rectangle fill="gray" />,
      }}
    >
      <PieChart ... />
    </Chart>
    ```

***

### **6. Foreground Style**

- **`chartForegroundStyleScale`**
  - **Type**:
    ```ts
    Record<string, ShapeStyle>;
    ```
  - **Description**: Customizes colors for marks in the chart.
  - **Example**:
    ```tsx
    <Chart
      chartForegroundStyleScale={{
        "Category 1": { color: "blue" },
        "Category 2": { color: "red" },
      }}
    >
      <BarChart ... />
    </Chart>
    ```

***

### **7. Scrollable Axes**

- **`chartScrollableAxes`**
  - **Type**:
    ```ts
    "vertical" | "horizontal" | "all"
    ```
  - **Description**: Enables scrolling for the specified axes.
  - **Example**:
    ```tsx
    <Chart chartScrollableAxes="horizontal">
      <LineChart ... />
    </Chart>
    ```

***

### **8. Selection**

- **`chartXSelection` / `chartYSelection` / `chartAngleSelection`**
  - **Type**:
    ```ts
    {
      value: string | number | null;
      onChanged: (newValue: string | number | null) => void;
      valueType: "string" | "number";
    }
    ```
  - **Description**: Enables selection for the specified axis.
  - **Example**:
    ```tsx
    <Chart
      chartXSelection={{
        value: "Category 1",
        onChanged: (newValue) => console.log("Selected:", newValue),
        valueType: "string",
      }}
    >
      <BarChart ... />
    </Chart>
    ```

***

### **9. Scroll Position**

- **`chartScrollPositionX` / `chartScrollPositionY`**
  - **Type**:
    ```ts
    number | string | {
      value: number | string;
      onChanged: (newValue: number | string) => void;
    }
    ```
  - **Description**: Sets the initial scroll position along the X or Y-axis.
  - **Example**:
    ```tsx
    <Chart
      chartScrollPositionX={{
        value: 0,
        onChanged: (newValue) => console.log("Scroll X:", newValue),
      }}
    >
      <BarChart ... />
    </Chart>
    ```

***

## **Comprehensive Example**

The following example demonstrates the usage of multiple properties to create a fully customized chart:

```tsx
<Chart
  chartXAxis="visible"
  chartYAxis="visible"
  chartXAxisLabel={{
    position: "bottom",
    alignment: "center",
    spacing: 8,
    content: <Text>X Axis Label</Text>,
  }}
  chartYAxisLabel={{
    position: "leading",
    content: <Text>Y Axis Label</Text>,
  }}
  chartLegend={{
    position: "top",
    alignment: "center",
    content: <Text>Chart Legend</Text>,
  }}
  chartXScale={{ domain: { from: 0, to: 100 }, type: "linear" }}
  chartScrollableAxes="all"
  chartForegroundStyleScale={{
    "Category A": { color: "green" },
    "Category B": { color: "blue" },
  }}
  chartBackground={{
    content: <Rectangle fill="lightgray" />,
  }}
>
  <BarChart
    marks={[
      { label: "A", value: 30, foregroundStyle: { color: "red" } },
      { label: "B", value: 70 },
    ]}
  />
  <LineChart
    marks={[
      { label: "A", value: 40 },
      { label: "B", value: 80 },
    ]}
  />
</Chart>
```

This example combines axis labels, scrolling, legend, scales, foreground styles, and multiple chart types in a single `Chart` container. Use it as a template for building your own charts.



---
url: /guide/View Modifiers/Grid Layout Control.md
---

# Grid Layout Control

These view modifiers are used to control the layout behavior of individual views placed inside a `Grid` structure. They provide fine-grained control over cell spanning, alignment, and sizing, consistent with SwiftUI’s grid system.

***

### `gridCellColumns`

Tells a view in a grid to span across multiple columns.

#### Type

```ts
gridCellColumns?: number
```

#### Description

Use this modifier to expand a single view across two or more columns. This is typically used for headers or wide content rows.

#### Example

```tsx
<Grid>
  <GridRow>
    <Text gridCellColumns={2}>This spans 2 columns</Text>
  </GridRow>
  <GridRow>
    <Text>Cell A</Text>
    <Text>Cell B</Text>
  </GridRow>
</Grid>
```

***

### `gridCellAnchor`

Specifies a custom alignment anchor within the grid cell.

#### Type

```ts
gridCellAnchor?: KeywordPoint | Point
```

#### Description

Use this modifier to align the content of a cell to a specific anchor point, either using a named keyword (such as `"center"` or `"topLeading"`) or a custom `{ x, y }` point.

#### Example

```tsx
<Grid>
  <GridRow>
    <Text gridCellAnchor="topLeading">Anchored to top leading</Text>
  </GridRow>
</Grid>
```

***

### `gridCellUnsizedAxes`

Prevents the view from expanding in the specified directions when placed in a grid cell.

#### Type

```ts
gridCellUnsizedAxes?: AxisSet
```

#### Description

This modifier tells the grid not to assign extra size to the view along specified axes, allowing the view to tightly wrap its content.

#### Options

- `"horizontal"` – Prevent horizontal expansion
- `"vertical"` – Prevent vertical expansion
- `"all"` – Prevent expansion in both directions

#### Example

```tsx
<Grid>
  <GridRow>
    <Image
      gridCellUnsizedAxes="horizontal"
      imageUrl="https://example.com/icon.png"
    />
    <Text>Description</Text>
  </GridRow>
</Grid>
```

***

### `gridColumnAlignment`

Overrides the default horizontal alignment of the column the view appears in.

#### Type

```ts
gridColumnAlignment?: "leading" | "center" | "trailing"
```

#### Description

Affects how all cells in the column are aligned horizontally. Only one view in a column needs to specify this to affect the whole column.

#### Example

```tsx
<Grid>
  <GridRow>
    <Text gridColumnAlignment="trailing">Right-aligned column</Text>
    <Text>Next Cell</Text>
  </GridRow>
</Grid>
```

***

## Grid and GridRow Structure

These modifiers are only applicable within the context of the `Grid` and `GridRow` components.

### `Grid`

A container that lays out content in a two-dimensional grid.

#### Props

- `alignment?: Alignment` – Alignment of child views in grid cells
- `horizontalSpacing?: number` – Spacing between columns
- `verticalSpacing?: number` – Spacing between rows

#### Example

```tsx
<Grid>
  <GridRow>
    <Text>Hello</Text>
    <Image systemName="globe" />
  </GridRow>
  <Divider />
  <GridRow>
    <Image systemName="hand.wave" />
    <Text>World</Text>
  </GridRow>
</Grid>
```

### `GridRow`

Represents a horizontal row of views inside a `Grid`.

#### Props

- `alignment?: VerticalAlignment` – Vertical alignment for cells in the row

***

## Summary

| Modifier              | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `gridCellColumns`     | Allows a view to span multiple columns in the grid          |
| `gridCellAnchor`      | Sets a specific anchor point for the view within its cell   |
| `gridCellUnsizedAxes` | Prevents the view from expanding along specified axes       |
| `gridColumnAlignment` | Overrides the horizontal alignment of the containing column |



---
url: /guide/View Modifiers/Image Style.md
---

# Image Style

These modifiers are specifically designed for views that render images (e.g., system symbols, local or remote images). They control layout behavior, scaling, and rendering characteristics of the image content.

***

## `scaleToFit`

### Definition

```ts
scaleToFit?: boolean
```

### Description

Scales the image **proportionally** to fit within its parent container. The image's **aspect ratio is preserved**, and the entire image will be visible. Any remaining space in the container is left empty.

Equivalent to:

```swift
.aspectRatio(contentMode: .fit)
```

### Behavior

- Resizes the image without cropping
- Preserves the original width-to-height ratio
- May introduce padding if aspect ratios do not match

### Example

```tsx
<Image
  filePath="path/to/local.jpg"
  scaleToFit={true}
/>
```

***

## `scaleToFill`

### Definition

```ts
scaleToFill?: boolean
```

### Description

Scales the image **proportionally** to completely fill its parent container. The image's **aspect ratio is preserved**, but the image may be **cropped** to fit.

Equivalent to:

```swift
.aspectRatio(contentMode: .fill)
```

### Behavior

- Image fills the entire container
- Maintains aspect ratio
- Portions of the image may be clipped

### Example

```tsx
<Image
  imageUrl="https://example.com/banner.jpg"
  scaleToFill={true}
/>
```

***

## `aspectRatio`

### Definition

```ts
aspectRatio?: {
  value?: number | null
  contentMode: "fit" | "fill"
}
```

### Description

Constrains the view’s dimensions to a specific **width-to-height ratio**, and determines how the image should be resized (`fit` or `fill`).

- `value`: A numeric aspect ratio (e.g. `16 / 9`) or `null` to preserve the original image’s ratio.
- `contentMode`: `"fit"` ensures the entire image fits within the view; `"fill"` ensures the view is fully filled, potentially cropping the image.

### Example: Set aspect ratio to 3:2 and fit

```tsx
<Image
  filePath="path/to/photo.jpg"
  aspectRatio={{
    value: 3 / 2,
    contentMode: "fit"
  }}
/>
```

### Example: Use original aspect ratio and fill the space

```tsx
<Image
  systemName="photo"
  aspectRatio={{
    value: null,
    contentMode: "fill"
  }}
/>
```

***

## `imageScale`

### Definition

```ts
imageScale?: "small" | "medium" | "large"
```

### Description

Sets the rendering size of **symbol-based images** (SF Symbols). This modifier does **not affect the layout size**, only the visual scale of the symbol image.

- `"small"`: Reduced symbol size
- `"medium"`: Default scale
- `"large"`: Enlarged symbol rendering

> Note: This modifier only applies to system symbol images created with `systemName`.

### Example

```tsx
<Image
  systemName="bolt.fill"
  imageScale="large"
/>
```

***

## Summary

| Modifier      | Purpose                                   | Affects Layout? | Cropping? | Symbol Only? |
| ------------- | ----------------------------------------- | --------------- | --------- | ------------ |
| `scaleToFit`  | Fit image proportionally within container | Yes             | No        | No           |
| `scaleToFill` | Fill container with proportional scaling  | Yes             | Yes       | No           |
| `aspectRatio` | Constrain view to a specific aspect ratio | Yes             | Optional  | No           |
| `imageScale`  | Adjust rendering size of symbol images    | No              | No        | **Yes**      |



---
url: /guide/View Modifiers/Lifecycle Events.md
---

# Lifecycle Events

Scripting supports SwiftUI-style lifecycle hooks `onAppear` and `onDisappear` to execute custom logic when a view becomes visible or is removed from the visible interface. These hooks allow you to trigger animations, start data loading, update state, or perform cleanup when views enter or exit the screen.

***

## Property Definitions

```ts
onAppear?: () => void
onDisappear?: () => void
```

### Property Descriptions

| Property      | Type         | Description                                          |
| ------------- | ------------ | ---------------------------------------------------- |
| `onAppear`    | `() => void` | Called when the view becomes visible.                |
| `onDisappear` | `() => void` | Called when the view is no longer visible on screen. |

***

## Example

```tsx
import { VStack, Text, useState } from "scripting"

function Example() {
  const [message, setMessage] = useState("")

  return <VStack
    onAppear={() => setMessage("View is visible")}
    onDisappear={() => setMessage("View is hidden")}
    padding
  >
    <Text>{message}</Text>
  </VStack>
}
```



---
url: /guide/View Modifiers/Liquid Glass/Glass Effect Transition/index.md
---

# Glass Effect Transition

This document provides a comprehensive explanation of **Glass Effect Transitions** in Scripting, including how Liquid Glass materials animate during view changes, how geometry matching works, and how to correctly use `NamespaceReader` to access SwiftUI’s `@Namespace` within TSX code.

Contents include:

- Overview of Liquid Glass transitions
- The three transition types
- Relationship among `glassEffectTransition`, `glassEffectID`, and `namespace`
- Role of `glassEffectUnion`
- Purpose and behavior of `GlassEffectContainer`
- Design and usage of `NamespaceReader`
- Detailed walkthrough of the provided example
- Best practice recommendations

***

## 1. Overview: What Is a Glass Effect Transition?

A **Glass Effect Transition** defines how a Liquid Glass material animates when:

- A view is inserted or removed
- Layout changes
- Views switch between two states

```ts
type GlassEffectTransition = 'identity' | 'materialize' | 'matchedGeometry'
```

These transitions affect **only the Liquid Glass material**—not the rest of the view’s opacity or scale.

A transition controls:

1. How the glass material appears or disappears
2. Whether the shape of the glass participates in animation
3. Whether the glass attempts to match geometry with other shapes

***

## 2. Transition Types

## 2.1 identity

```tsx
glassEffectTransition="identity"
```

Behavior:

- No animation or geometry change.
- The glass effect appears immediately with no fade or shape transformation.

Use cases:

- Disabling animations
- Static UI
- Debugging transitions

***

## 2.2 materialize

```tsx
glassEffectTransition="materialize"
```

Behavior:

- The material fades in or out smoothly.
- No attempt is made to match geometry with any other glass shape.
- Content transitions in a simple, clean way.

Use cases:

- Basic menu transitions
- Buttons appearing or disappearing
- When geometric continuity is not needed

***

## 2.3 matchedGeometry (most powerful)

```tsx
glassEffectTransition="matchedGeometry"
```

Behavior:

- The Liquid Glass shape morphs between views that share the same ID and namespace.
- Creates smooth, fluid transitions between corresponding glass shapes.
- Requires `glassEffectID` and `namespace`.

Use cases:

- Menu switching (e.g., Edit → Home)
- Toolbar reconfiguration
- Any UI element where continuity matters

***

## 3. glassEffectID and namespace

**The core of geometric matching**

Liquid Glass’ geometric-matching transitions require the ability to identify and relate specific glass shapes.

***

## 3.1 Why IDs Are Required

To animate a shape from state A → state B, the system must know:

- which old shape matches which new shape

The identity is provided by:

```tsx
glassEffectID={{
  id: 1,
  namespace
}}
```

Views with the same `id` in the same namespace are treated as the **same conceptual glass entity** across states.

***

## 3.2 Why a namespace Is Required

SwiftUI’s matchedGeometry system requires an `@Namespace` to define the animation scope.

Since TSX cannot define SwiftUI property wrappers, Scripting provides:

```tsx
<NamespaceReader>
  {namespace => (...)}
</NamespaceReader>
```

Inside the closure:

- `namespace` refers to a real SwiftUI `@Namespace`
- All `glassEffectID` and `glassEffectUnion` inside this closure must use this namespace

Benefits:

- Provides correct scope for geometry transitions
- Prevents accidental cross-scope animation
- Ensures matchedGeometry and unions behave predictably

Without a namespace, geometric matching does not work.

***

## 4. glassEffectUnion: Unifying Glass Regions

`glassEffectUnion` merges multiple views into a **single continuous glass material region**.

```tsx
glassEffectUnion={{
  id: 1,
  namespace
}}
```

Effects:

- Buttons appear to share a single underlying piece of glass
- Material may shift or reflow cohesively
- Enhances visual coherence in grouped UI elements

Typically paired with matchedGeometry transitions.

***

## 5. GlassEffectContainer

The container provides:

- A shared environment for geometry matching
- A rendering boundary for unioned glass
- Optimized rendering for clusters of Liquid Glass views

Example:

```tsx
<GlassEffectContainer>
  <HStack> ... </HStack>
</GlassEffectContainer>
```

Every view participating in glass transitions should be placed inside the same container.

***

## 6. NamespaceReader

**Exposing SwiftUI’s `@Namespace` to TSX**

## 6.1 Why NamespaceReader Exists

SwiftUI defines matchedGeometry transitions using:

```swift
@Namespace private var namespace
```

But TSX code cannot create Swift `@Namespace` values.
Therefore Scripting provides:

```tsx
<NamespaceReader>
  {namespace => (...)}
</NamespaceReader>
```

### Purpose:

- Internally creates and manages a real SwiftUI `@Namespace`
- Makes the namespace accessible to JavaScript/TypeScript
- Ensures all participating views share the same namespace
- Enables matchedGeometry transitions to work in TSX

## 6.2 How It Works

- NamespaceReader creates a SwiftUI view containing `@Namespace`.
- That namespace is passed to the TSX children via a function parameter.
- All `glassEffectID` and `glassEffectUnion` must use this namespace.
- All participating views inside the closure are guaranteed to match within the same namespace.

***

## 7. Example Analysis

Below is the provided example, demonstrating a dynamic menu switching between two states:

- Menu A: Home / Settings
- Menu B: Edit / Erase / Delete
- Using animation for transitions
- Using matchedGeometry via ID sharing
- Using union IDs for continuous material appearance

### Key excerpts:

```tsx
isAlternativeMenu.value
  ? <>
      <Button
        title="Home"
        glassEffectID={{id:1, namespace}}
        glassEffectUnion={{id:1,namespace}}
      />
      <Button
        title="Settings"
        glassEffectID={{id:2, namespace}}
        glassEffectUnion={{id:1,namespace}}
      />
    </>
  : <>
      <Button
        title="Edit"
        glassEffectID={{id:1, namespace}}
        glassEffectUnion={{id:1,namespace}}
      />
      <Button
        title="Erase"
        glassEffectID={{id:3, namespace}}
        glassEffectUnion={{id:1,namespace}}
        glassEffectTransition="materialize"
      />
      <Button
        title="Delete"
        glassEffectID={{id:2, namespace}}
        glassEffectUnion={{id:1,namespace}}
      />
    </>
```

### 1. Shared union (id = 1)

All buttons belong to the same glass union.
This produces a smooth, unified underlying glass region.

### 2. Shared glassEffectID for corresponding buttons

- `Home` and `Edit` share `id = 1`
- `Settings` and `Delete` share `id = 2`

→ They animate between each other using `matchedGeometry`.

### 3. “Erase” uses a different transition

```tsx
glassEffectTransition="materialize"
```

This button fades its material rather than matching geometry, making its appearance more distinct.

### 4. Animation is triggered explicitly

```tsx
withAnimation(() => {
  isAlternativeMenu.setValue(
    !isAlternativeMenu.value
  )
})
```

Glass transitions attach themselves to this animation transaction automatically.

***

## 8. Best Practices

### 1. Use a single GlassEffectContainer

All participating glass views must share one container.

### 2. Use one NamespaceReader per animated region

Do not create multiple namespaces unless intentionally separating animation scopes.

### 3. Use consistent glassEffectID between states

Both old and new states must contain the same ID to animate geometrically.

### 4. Use glassEffectUnion for cohesive material appearance

Especially in toolbars and menus.

### 5. Prefer matchedGeometry for sophisticated transitions

Use materialize only for elements needing simple appearance behavior.

***

## 9. Summary

Glass Effect Transitions enable highly expressive and fluid animations for Liquid Glass materials in iOS 26.
In Scripting:

- `glassEffectTransition` defines how the material animates
- `glassEffectID` and `namespace` enable geometric matching
- `glassEffectUnion` creates unified material regions
- `GlassEffectContainer` manages the animation environment
- `NamespaceReader` exposes SwiftUI’s `@Namespace` to TSX, making advanced animations possible



---
url: /guide/View Modifiers/Liquid Glass/Glass Effect Transition/index_example.md
---

# Example

```tsx
import { Button, GlassEffectContainer, HStack, NamespaceReader, Navigation, Script, VStack, useObservable } from "scripting"

function View() {

  const isAlternativeMenu = useObservable(false)

  return <NamespaceReader>{namespace => <VStack
    spacing={50}
    frame={{
      maxWidth: 'infinity',
      maxHeight: 'infinity'
    }}
    background="systemYellow"
  >
    <GlassEffectContainer
    >
      <HStack
        spacing={0}
        font="largeTitle"
        imageScale="large"
        buttonStyle="glass"
        labelStyle="iconOnly"
      >
        {
          isAlternativeMenu.value
            ? <>
              <Button
                title="Home"
                systemImage="house"
                action={() => { }}
                glassEffectID={{
                  id: 1,
                  namespace
                }}
                glassEffectUnion={{
                  id: 1,
                  namespace
                }}
              />
              <Button
                title="Settings"
                systemImage="gear"
                action={() => { }}
                glassEffectID={{
                  id: 2,
                  namespace
                }}
                glassEffectUnion={{
                  id: 1,
                  namespace
                }}
              />
            </>

            : <>
              <Button
                title="Edit"
                systemImage="pencil"
                action={() => { }}
                glassEffectID={{
                  id: 1,
                  namespace
                }}
                glassEffectUnion={{
                  id: 1,
                  namespace
                }}
              />
              <Button
                title="Erase"
                systemImage="eraser"
                action={() => { }}
                glassEffectID={{
                  id: 3,
                  namespace
                }}
                glassEffectUnion={{
                  id: 1,
                  namespace
                }}
                glassEffectTransition="materialize"
              />
              <Button
                title="Delete"
                systemImage="trash"
                action={() => { }}
                glassEffectID={{
                  id: 2,
                  namespace
                }}
                glassEffectUnion={{
                  id: 1,
                  namespace
                }}
              />
            </>
        }
      </HStack>
    </GlassEffectContainer>

    <Button
      title="Toggle"
      buttonStyle="bordered"
      action={() => {
        withAnimation(() => {
          isAlternativeMenu.setValue(
            !isAlternativeMenu.value
          )
        })
      }}
    />
  </VStack>
  }</NamespaceReader>
}

async function run() {
  await Navigation.present(<View />)

  Script.exit()
}

run()
```



---
url: /guide/View Modifiers/Liquid Glass/Liquid Glass Effect/index.md
---

# Liquid Glass Effect

Scripting provides full support for the new **Liquid Glass** visual system introduced in iOS 26. This includes `glassEffect`, `GlassEffectContainer`, `UIGlass`, and related geometry-matching and transition APIs. These APIs allow scripts to create rich translucent materials, fluid glass shapes, matched geometry animations, and unioned glass regions directly within TSX.

This document explains how the Liquid Glass APIs are used in Scripting, including:

- Concepts and fundamentals
- How to apply glass effects
- UIGlass configuration
- Geometry transitions
- glassEffect identifiers and unions
- GlassEffectContainer behavior
- Practical examples and best practices

***

## 1. Overview of Liquid Glass

Liquid Glass is a new material and animation system in iOS 26. Compared to earlier blur or material effects, Liquid Glass provides:

- Fluid, dynamic shapes that follow view geometry
- Tintable and interactive glass materials
- Geometry-matched transitions
- Grouped “glass unions” to merge multiple regions
- High-performance rendering inside containers

***

## 2. The `glassEffect` Modifier

Any view that adopts `GlassProps` can apply a Liquid Glass effect using the `glassEffect` property.

### Definition

```ts
type GlassProps = {
  glassEffect?: boolean | UIGlass | Shape | {
    glass: UIGlass
    shape: Shape
  }

  glassEffectTransition?: GlassEffectTransition

  glassEffectID?: {
    id: string | number
    namespace: NamespaceID
  }

  glassEffectUnion?: {
    id: string | number
    namespace: NamespaceID
  }
}
```

***

## 2.1 Ways to Use `glassEffect`

### **1. Enable default Liquid Glass material**

```tsx
<Text glassEffect>Foo</Text>
```

Equivalent to `UIGlass.regular()`.

***

### **2. Apply a specific UIGlass instance**

```tsx
<Text glassEffect={UIGlass.regular().interactive(false)}>
  Foo
</Text>
```

You can chain configuration calls such as `interactive()` and `tint()`.

***

### **3. Provide a specific Shape**

```tsx
<Text
  glassEffect={{
    glass: UIGlass.regular(),
    shape: { type: 'rect', cornerRadius: 10 }
  }}
>
  Foo
</Text>
```

Or directly provide a Shape object:

```tsx
<Text glassEffect={{ type: 'rect', cornerRadius: 10 }}>
  Foo
</Text>
```

The glass material will be clipped to the shape’s geometry.

***

### **4. Boolean shorthand**

```tsx
<View glassEffect />
```

Acts the same as default Liquid Glass material.

***

## 3. The `UIGlass` Class

`UIGlass` represents the Liquid Glass material configuration.

### Static factories

| Method               | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| `UIGlass.clear()`    | Fully clear variant, used for overlay or blending composition. |
| `UIGlass.regular()`  | Standard Liquid Glass material.                                |
| `UIGlass.identity()` | Identity material that leaves content visually unchanged.      |

### Instance configuration

```ts
interactive(value?: boolean): UIGlass
tint(color: Color): UIGlass
```

Example:

```tsx
glassEffect={UIGlass.regular().interactive().tint("red")}
```

***

## 4. Glass Effect Transitions

```ts
type GlassEffectTransition = 'identity' | 'materialize' | 'matchedGeometry'
```

### Transition Types

| Transition          | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `'identity'`        | No change or animation applied.                                             |
| `'materialize'`     | Fades in content and animates the glass material without geometry matching. |
| `'matchedGeometry'` | Matches the geometry of other glass shapes during transitions.              |

### Usage

```tsx
<Text
  glassEffect
  glassEffectTransition="materialize"
>
  Foo
</Text>
```

`matchedGeometry` works best with **glassEffectID** or **glassEffectUnion**.

***

## 5. glassEffectID and glassEffectUnion

Liquid Glass can identify or group glass effects to create smooth geometry animations or unified material regions.

***

## 5.1 glassEffectID

Assigns a unique identity to a glass effect for matched geometry animations.

```tsx
<Text
  glassEffect
  glassEffectID={{ id: "avatar", namespace }}
>
  Foo
</Text>
```

Views with the same `id + namespace` can participate in matched geometry transitions.

***

## 5.2 glassEffectUnion

Groups multiple glass effects into a single unioned glass region.

```tsx
<Text
  glassEffect
  glassEffectUnion={{ id: 1, namespace }}
/>
```

This merges material rendering across multiple views.

***

## 6. GlassEffectContainer

`GlassEffectContainer` is used to group and manage correlated glass effects. Views inside the container:

- Participate in matched geometry
- Support glass unions
- Render glass transitions more efficiently

### Example

```tsx
<GlassEffectContainer>
  <HStack spacing={40}>
    <Image systemName="1.circle" glassEffect />
    <Image systemName="2.circle" glassEffect />
  </HStack>
</GlassEffectContainer>
```

No configuration is required; the container acts as a shared environment.

***

## 7. Glass Button Styles

Scripting supports additional iOS 26 button styles:

- `"glass"`
- `"glassProminent"`

### Examples

```tsx
<Button title="Glass" buttonStyle="glass" />

<Button title="Glass Prominent" buttonStyle="glassProminent" />

<Button
  title="Glass & Tint"
  buttonStyle="glass"
  tint="red"
/>
```

These styles use Liquid Glass materials and integrate with tint and interaction behaviors.

***

## 8. Practical Example

Below is a real example combining multiple features:

- Glass buttons
- GlassEffectContainer
- UIGlass configurations
- Shape-based glass
- Offset effects

```tsx
<GlassEffectContainer>
  <HStack spacing={40}>
    <Image
      systemName="1.circle"
      frame={{ width: 80, height: 80 }}
      font={36}
      glassEffect
      offset={{ x: 30, y: 0 }}
    />
    <Image
      systemName="2.circle"
      frame={{ width: 80, height: 80 }}
      font={36}
      glassEffect
      offset={{ x: -30, y: 0 }}
    />
  </HStack>
</GlassEffectContainer>
```

***

## 9. Best Practices

### 1. Place related glass views inside a single GlassEffectContainer

Improves performance and produces more consistent transitions.

### 2. Provide glassEffectID for matched geometry animations

Without IDs, transitions cannot interpolate shapes.

### 3. Use glassEffectUnion to merge nearby glass regions

Creates a seamless material surface.

### 4. Avoid deeply nested glass hierarchies

Prefer using a container with ZStack for organization.

### 5. Use UIGlass.identity when structure must remain but material disabled

Useful for conditionally enabling glass without changing layout.



---
url: /guide/View Modifiers/Liquid Glass/Liquid Glass Effect/index_example.md
---

# Example

```tsx
import { Button, Navigation, NavigationStack, Script, Text, VStack, ZStack, Image, Path, GlassEffectContainer, HStack } from "scripting"

function View({
  image
}: {
  image: UIImage
}) {
  // Access dismiss function.
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <VStack
      navigationTitle="GlassEffect DEMO"
      navigationBarTitleDisplayMode="inline"
      toolbar={{
        topBarLeading: <Button
          title="Done"
          action={dismiss}
        />
      }}
    >
      <ZStack>
        <Image
          image={image}
          resizable
          scaleToFill
        />
        <VStack>
          <HStack>
            <Button
              title="Glass"
              action={() => { }}
              buttonStyle="glass"
            />
            <Button
              title="Glass & Tint"
              action={() => { }}
              buttonStyle="glass"
              tint="red"
            />
          </HStack>
          <HStack>
            <Button
              title="Glass Prominent"
              action={() => { }}
              buttonStyle="glassProminent"
            />
            <Button
              title="Glass Prominent & Tint"
              action={() => { }}
              buttonStyle="glassProminent"
              tint="red"
            />
          </HStack>
          <GlassEffectContainer>
            <HStack spacing={40}>
              <Image
                systemName="1.circle"
                frame={{ width: 80, height: 80 }}
                font={36}
                glassEffect
                offset={{ x: 30, y: 0 }}
              />
              <Image
                systemName="2.circle"
                frame={{ width: 80, height: 80 }}
                font={36}
                glassEffect
                offset={{ x: -30, y: 0 }}
              />
            </HStack>
          </GlassEffectContainer>
          <HStack spacing={12}>
            <Text
              padding
              glassEffect
            >Foo</Text>
            <Text
              padding
              glassEffect={{
                type: 'rect',
                cornerRadius: 10
              }}
            >Foo</Text>
            <Text
              padding
              glassEffect={UIGlass.regular().interactive()}
            >Foo</Text>
            <Text
              padding
              glassEffect={UIGlass.regular().tint("red")}
              foregroundStyle="white"
            >Foo</Text>
          </HStack>
        </VStack>
      </ZStack>
    </VStack>
  </NavigationStack>
}

async function run() {
  try {
    const image = (await Photos.pickPhotos(1))?.at(0)
    if (!image) {
      throw new Error("You must pick an image as the background.")
    }
    // Present view.
    await Navigation.present({
      element: <View
        image={image}
      />
    })
  } catch (e) {
    console.present()
    console.error(e)
  }

  // Avoiding memory leaks.
  Script.exit()
}

run()
```



---
url: /guide/View Modifiers/List and Section View Modifiers/Common.md
---

# Common

These modifiers allow you to customize how rows and sections behave and appear inside a `<List>` component.

## Applies To:

- Individual **rows** (e.g., `<Text>`, `<HStack>`, etc. inside `<List>`)
- Entire **sections** (e.g., `<Section>`)
- Or directly on the `<List>` component itself

***

## `listItemTint`

Sets the **tint color** applied to the row or its accessories (e.g., icons, buttons).

### Type

```ts
listItemTint?: Color
```

### Description

- Use this to override the inherited tint color for a row or its content.
- Use `null` to avoid overriding the inherited tint.

### Example

```tsx
<Text
  listItemTint="green"
>
  Tinted Row
</Text>
```

***

## `listRowInsets`

Applies **padding (insets)** to a row in a list.

### Type

```ts
listRowInsets?: number | EdgeInsets
```

### Description

- Use a single `number` to apply uniform padding.
- Use an `EdgeInsets` object to apply individual insets for top, bottom, leading, and trailing.

### Example

```tsx
<Text
  listRowInsets={{
    top: 10,
    bottom: 10,
    leading: 20,
    trailing: 20
  }}
>
  Custom Insets Row
</Text>
```

***

## `listRowSpacing`

Controls the **vertical spacing** between adjacent rows.

### Type

```ts
listRowSpacing?: number
```

### Example

```tsx
<List listRowSpacing={12}>
  <Text>Row 1</Text>
  <Text>Row 2</Text>
</List>
```

***

## `listRowSeparator`

Sets the **visibility of the separator line** for a specific row.

### Type

```ts
listRowSeparator?: Visibility | {
  visibility: Visibility
  edges: VerticalEdgeSet
}
```

### `Visibility` options:

- `"visible"` – Always show the separator
- `"hidden"` – Hide the separator
- `"automatic"` – System default behavior

### `VerticalEdgeSet` options:

- `"top"` | `"bottom"` | `"all"`

### Example

```tsx
<Text
  listRowSeparator={{
    visibility: "hidden",
    edges: "bottom"
  }}
>
  No Bottom Separator
</Text>
```

***

## `listRowSeparatorTint`

Sets the **tint color of the separator** for a specific row.

### Type

```ts
listRowSeparatorTint?: Color | {
  color: Color
  edges: VerticalEdgeSet
}
```

### Example

```tsx
<Text
  listRowSeparatorTint={{
    color: "rgba(255,0,0,0.5)",
    edges: "bottom"
  }}
>
  Colored Separator
</Text>
```

***

## `listRowBackground`

Places a **custom background** behind a list row.

### Type

```ts
listRowBackground?: VirtualNode
```

### Example

```tsx
<Text
  listRowBackground={
    <Rectangle fill="#f0f0f0" cornerRadius={10} />
  }
>
  Row with background
</Text>
```

***

## `listSectionSpacing`

Controls the **spacing between adjacent list sections**.

### Type

```ts
listSectionSpacing?: ListSectionSpacing
```

### `ListSectionSpacing` options:

- `"default"` – System default spacing
- `"compact"` – Smaller spacing
- A `number` – Custom spacing in points

### Example

```tsx
<List listSectionSpacing="compact">
  <Section>...</Section>
  <Section>...</Section>
</List>
```

***

## `listSectionSeparator`

Controls the **visibility of the separator** between list sections.

### Type

```ts
listSectionSeparator?: Visibility | {
  visibility: Visibility
  edges: VerticalEdgeSet
}
```

### Example

```tsx
<Section
  listSectionSeparator={{
    visibility: "hidden",
    edges: "top"
  }}
>
  <Text>Section Content</Text>
</Section>
```

***

## `listSectionSeparatorTint`

Sets the **separator tint color** for a section.

### Type

```ts
listSectionSeparatorTint?: Color | {
  color: Color
  edges: VerticalEdgeSet
}
```

### Example

```tsx
<Section
  listSectionSeparatorTint={{
    color: "#cccccc",
    edges: "bottom"
  }}
>
  <Text>Styled Section</Text>
</Section>
```

***

## Supporting Types

## `EdgeInsets`

```ts
{
  top: number
  bottom: number
  leading: number
  trailing: number
}
```

## `Visibility`

```ts
"automatic" | "visible" | "hidden"
```

## `VerticalEdgeSet`

```ts
"top" | "bottom" | "all"
```

## `Color` formats

You can define color in three ways:

- Named keyword: `"green"`, `"label"`, etc.
- Hex: `"#ff0000"`
- RGBA: `"rgba(255,0,0,1)"`

***

## Summary Table

| Modifier                   | Scope   | Description                       |
| -------------------------- | ------- | --------------------------------- |
| `listItemTint`             | Row     | Sets tint color for row content   |
| `listRowInsets`            | Row     | Custom padding for row            |
| `listRowSpacing`           | List    | Vertical spacing between rows     |
| `listRowSeparator`         | Row     | Controls row separator visibility |
| `listRowSeparatorTint`     | Row     | Tint color of row separator       |
| `listRowBackground`        | Row     | Background behind a specific row  |
| `listSectionSpacing`       | List    | Spacing between sections          |
| `listSectionSeparator`     | Section | Visibility of section separator   |
| `listSectionSeparatorTint` | Section | Tint color of section separator   |



---
url: /guide/View Modifiers/List and Section View Modifiers/New List View Modifiers.md
---

# New List View Modifiers

## Overview of Properties

| Property                     | Type                                                        | Availability | Description                                                        |   |   |
| ---------------------------- | ----------------------------------------------------------- | ------------ | ------------------------------------------------------------------ | - | - |
| `listSectionIndexVisibility` | `Visibility`                                                | iOS 26.0+    | Controls the visibility of the List's right-side section index     |   |   |
| `listSectionMargins`         | `number \| EdgeSets \| { edges: EdgeSets; length: number }` | iOS 26.0+    | Customizes section margins, replacing SwiftUI’s automatic defaults |   |   |
| `sectionIndexLabel`          | `string`                                                    | iOS 26.0+    | Sets the character displayed in the section index                  |   |   |
| `sectionActions`             | `VirtualNode`                                               | iOS 18.0+    | Adds custom actions to the section header area                     |   |   |

***

## 1. listSectionIndexVisibility

```ts
/**
 * Sets the visibility of the list section index.
 * @available iOS 26.0+.
 */
listSectionIndexVisibility?: Visibility
```

### Description

Controls whether the List shows the right-side section index (commonly used for A–Z navigation in contact lists).

Possible values:

- `"visible"`
- `"hidden"`
- `"automatic"` (default system behavior)

### Example

```tsx
<List listSectionIndexVisibility="visible">
  <ForEach
    data={groups}
    builder={group => (
      <Section
        header={<Text>{group.title}</Text>}
        sectionIndexLabel={group.title}
      >
        {group.items.map(item => <Text key={item}>{item}</Text>)}
      </Section>
    )}
  />
</List>
```

***

## 2. listSectionMargins

```ts
/**
 * Set the section margins for the specific edges.
 * @available iOS 26.0+.
 */
listSectionMargins?: number | EdgeSets | {
  edges: EdgeSets
  length: number
}
```

### Description

Customizes the margins of a section. When set, it **fully replaces** SwiftUI’s default section margin rules.

### Supported Formats

### 2.1 Single number

Applies the same margin to all edges.

```tsx
listSectionMargins={12}
```

### 2.2 EdgeSets

Applies the specified edges with the default margin.

```tsx
listSectionMargins={["horizontal", "top"]}
```

### 2.3 Specific edges with length

Applies a margin of `length` only to the specified edges.

```tsx
listSectionMargins={{
  edges: "horizontal",
  length: 20
}}
```

Equivalent to SwiftUI:

```swift
.listSectionMargins(.horizontal, 20)
```

### Example

```tsx
<Section
  header={<Text>Favorites</Text>}
  listSectionMargins={{
  edges: "horizontal",
  length: 20
  }}
>
  <Text>Item A</Text>
  <Text>Item B</Text>
</Section>
```

***

## 3. sectionIndexLabel

```ts
/**
 * Sets the label that is used in a section index.
 * @available iOS 26.0+.
 */
sectionIndexLabel?: string
```

### Description

Sets the character or text displayed in the right-side section index for this section. Typically a single letter.

### Example

```tsx
<Section
  header={<Text>A</Text>}
  sectionIndexLabel="A"
>
  <Text>Adam</Text>
  <Text>Ana</Text>
</Section>
```

***

## 4. sectionActions

```ts
/**
 * Adds custom actions to a section.
 * @available iOS 18.0+
 */
sectionActions?: VirtualNode
```

### Description

Adds custom UI elements such as buttons or menus to the section header’s trailing (accessory) area.

### Example: Refresh button

```tsx
<Section
  header={<Text>Downloads</Text>}
  sectionActions={
    <Button title="Refresh" action={() => doRefresh()} />
  }
>
  <Text>File 1</Text>
  <Text>File 2</Text>
</Section>
```

### Example: Menu with multiple actions

```tsx
<Section
  header={<Text>Photos</Text>}
  sectionActions={
    <Menu title="Actions">
      <Button title="Upload All" action={() => uploadAll()} />
      <Button title="Delete All" action={() => deleteAll()} />
    </Menu>
  }
>
  {photos.map(photo => <Text key={photo.id}>{photo.name}</Text>)}
</Section>
```

***

## Full Example

```tsx
<List listSectionIndexVisibility="visible">
  <ForEach
    data={groups}
    builder={group => (
      <Section
        header={<Text>{group.title}</Text>}
        sectionIndexLabel={group.title}
        listSectionMargins={12}
        sectionActions={
          <Button title="Refresh" action={() => refreshGroup(group)} />
        }
      >
        {group.items.map(item => <Text key={item}>{item}</Text>)}
      </Section>
    )}
  />
</List>
```



---
url: /guide/View Modifiers/LiveActivity View Modifiers.md
---

# LiveActivity View Modifiers

Scripting provides two view modifiers that customize the appearance of Live Activities on the Lock Screen. These modifiers control the background tint color of the Live Activity and the foreground color of the system-provided action button.

These properties are designed to match SwiftUI’s Live Activity customization options.

***

## Modifier Definitions

```ts
/**
 * Sets the tint color for the background of a Live Activity that appears on the Lock Screen.
 */
activityBackgroundTint?: Color | {
  light: Color
  dark: Color
}

/**
 * Sets the text (foreground) color for the system-provided auxiliary action button
 * that appears next to a Live Activity on the Lock Screen.
 */
activitySystemActionForegroundColor?: Color | {
  light: Color
  dark: Color
}
```

***

## Usage Constraints

These modifiers **can only be applied to the `content` view** of the Live Activity UI.

They **do not** take effect when placed in:

- `compactLeading`
- `compactTrailing`
- `minimal`

Only the **full-size Lock Screen presentation** (the `content` region) supports these appearance customizations.

***

## Modifier Details

## 1. activityBackgroundTint

**Type:** `Color | { light: Color; dark: Color }`
**Description:**
Sets the tint color used as the background of the Live Activity when displayed on the Lock Screen.

This influences the main card background rendered by the system.

### Typical Use Cases

- Applying a brand color as the Live Activity background
- Giving different Live Activities distinct themes
- Improving readability by contrasting text and background colors

***

## 2. activitySystemActionForegroundColor

**Type:** `Color | { light: Color; dark: Color }`
**Description:**
Specifies the foreground (text/icon) color of the system’s auxiliary action button that may appear next to the Live Activity on the Lock Screen.

### Typical Use Cases

- Ensuring button text is readable on dark or bright backgrounds
- Highlighting an important system-provided action
- Matching the app’s color theme

***

## Usage Example (Content Only)

These modifiers must be applied to the **content** view inside your Live Activity UI builder:

```tsx
function ActivityView() {
  <LiveActivityUI
    content={
      <ContentView
        activityBackgroundTint={"blue"}
        activitySystemActionForegroundColor={"white"}
      />
    }
    compactLeading={...}
    compactTrailing={...}
    minimal={<Image systemName="clock" />}
  >
    <LiveActivityUIExpandedCenter>
      <ContentView />
    </LiveActivityUIExpandedCenter>
  </LiveActivityUI>
}
```

***

## Additional Notes

1. These modifiers affect only the Lock Screen presentation of the Live Activity.
2. They do not modify the compact or minimal variants shown in the Dynamic Island.
3. If not provided, the system will use default styles consistent with SwiftUI’s behavior.



---
url: /guide/View Modifiers/Navigation View Modifiers.md
---

# Navigation View Modifiers

The Scripting app supports a set of navigation-related view modifiers that enable developers to control how views are presented within navigation stacks. These modifiers allow for the customization of navigation titles, title display styles, and back button behavior—closely following the conventions of SwiftUI's navigation system.

***

## `navigationTitle`

```ts
navigationTitle?: string
```

Specifies the navigation title of the view.

### Description

- On **iOS**, the navigation title appears in the navigation bar when the view is part of a navigation stack.
- On **iPadOS**, the title of the primary navigation destination is also used as the app window's title in the App Switcher.

***

## `navigationBarTitleDisplayMode`

```ts
navigationBarTitleDisplayMode?: NavigationBarTitleDisplayMode
```

Controls the display style of the navigation title.

### Enum: `NavigationBarTitleDisplayMode`

```ts
type NavigationBarTitleDisplayMode = "automatic" | "large" | "inline"
```

- **`automatic`**: The system chooses the most appropriate display style based on context.
- **`large`**: Displays the title in a prominent, large style (typically for root views).
- **`inline`**: Displays the title in-line with the navigation bar controls, using a compact layout.

***

## `navigationBarBackButtonHidden`

```ts
navigationBarBackButtonHidden?: boolean
```

Hides or shows the navigation bar back button.

### Description

- When set to `true`, the default back button is not shown for the view.
- This is useful when implementing custom navigation controls or when the default back action should be disabled.

***

## Usage Example

```tsx
<VStack
  navigationTitle={"Profile"}
  navigationBarTitleDisplayMode={"inline"}
  navigationBarBackButtonHidden={true}
>
  <Text>Welcome to the Profile screen</Text>
</VStack>
```

In this example:

- The view’s title is set to `"Profile"` and will be shown in the navigation bar.
- The title uses the `inline` display style.
- The default back button is hidden.



---
url: /guide/View Modifiers/Picture in Pictuer View Modifiers.md
---

# Picture in Pictuer View Modifiers

Scripting provides a set of Picture in Picture (PiP) view modifiers that allow developers to render any SwiftUI view inside a system PiP window.
These APIs abstract away the underlying `AVPictureInPicture` implementation and provide a declarative, script-friendly way to control PiP presentation, interaction, and lifecycle.

PiP is suitable for the following scenarios:

- Real-time status display (timers, workouts, progress indicators)
- Audio or video playback companion UI
- Lightweight views that should remain visible when the app enters background

***

## 1. PiPProps API Definition

```ts
type PiPProps = {
  pip?: {
    isPresented: Observable<boolean>
    maximumUpdatesPerSecond?: number
    content: VirtualNode
  }
  
  onPipStart?: () => void
  onPipStop?: () => void
  onPipPlayPauseToggle?: (isPlaying: boolean) => void
  onPipSkip?: (isForward: boolean) => void
  onPipRenderSizeChanged?: (size: Size) => void

  pipHideOnForeground?: boolean
  pipShowOnBackground?: boolean
}
```

***

## 2. Core Properties

### 2.1 `pip.isPresented`

```ts
isPresented: Observable<boolean>
```

- The **single source of truth** for PiP presentation
- `true`: PiP window is presented
- `false`: PiP window is dismissed

This value is typically controlled by user actions or app lifecycle events.

***

### 2.2 `pip.content`

```ts
content: VirtualNode
```

- The view rendered inside the PiP window
- Strongly recommended to be a **dedicated PiP view**
- Should be minimal, stable, and predictable in layout

***

### 2.3 `pip.maximumUpdatesPerSecond`

```ts
maximumUpdatesPerSecond?: number
```

- **Default value: 30**
- Limits how often the PiP view can be re-rendered per second
- One of the most important performance-related parameters

#### Recommended values

- **No animation / low-frequency updates**
  Use `1–5`

- **Animated PiP views**
  Can be set to `60`

Important:
Setting this value to `60` has a **significant performance impact**, increasing both CPU and GPU usage. This should only be used when animation is strictly required.

***

## 3. PiP Lifecycle Callbacks

(Only valid inside the PiP view)

### 3.1 `onPipStart`

```ts
onPipStart?: () => void
```

- Called when the PiP window is successfully presented
- Typical use cases:

  - Start timers
  - Begin state updates
  - Subscribe to data streams

***

### 3.2 `onPipStop`

```ts
onPipStop?: () => void
```

- Called when PiP is dismissed or stopped by the system
- All side effects should be cleaned up here:

  - Timers
  - Subscriptions
  - Long-running tasks

***

## 4. PiP Interaction Callbacks

(Only valid inside the PiP view)

### 4.1 Play / Pause Toggle

```ts
onPipPlayPauseToggle?: (isPlaying: boolean) => void
```

- Triggered when the user taps the play/pause control in the PiP window
- `isPlaying` indicates the resulting playback state
- Commonly used for audio, video, or workout scenarios

***

### 4.2 Skip Forward / Backward

```ts
onPipSkip?: (isForward: boolean) => void
```

- `true`: skip forward
- `false`: skip backward

***

## 5. Render Size Changes

### `onPipRenderSizeChanged`

```ts
onPipRenderSizeChanged?: (size: Size) => void
```

- Called whenever the PiP render size changes
- Can be used to adapt layout for different PiP sizes or orientations

***

## 6. Foreground and Background Behavior

(Only valid inside the PiP view)

### 6.1 `pipHideOnForeground`

```ts
pipHideOnForeground?: boolean
```

- When the app enters foreground:

  - Determines whether an active PiP session should be stopped
- Default: `false`

***

### 6.2 `pipShowOnBackground`

```ts
pipShowOnBackground?: boolean
```

- Automatically starts PiP when the app moves to background
- Commonly used for audio playback or real-time status displays

***

## 7. Complete Code Example

### 7.1 PiP Content View

```tsx
function PipView() {
  const started = useObservable(false)
  const count = useObservable(0)

  useEffect(() => {
    if (!started.value) {
      return
    }

    let timerId: number

    function startTimer() {
      timerId = setTimeout(() => {
        count.setValue(count.value + 1)
        startTimer()
      }, 1000)
    }

    startTimer()

    return () => {
      clearTimeout(timerId)
    }
  }, [started.value])

  return <HStack
    onPipStart={() => {
      started.setValue(true)
    }}
    frame={{
      width: Device.screen.width,
      height: 50
    }}
    background="systemBlue"
  >
    <Image
      systemName="figure.walk"
      font="title"
    />
    <Text foregroundStyle="white">
      Count: {count.value}
    </Text>
  </HStack>
}
```

***

### 7.2 Enabling PiP on a Page

```tsx
function PageView() {
  const dismiss = Navigation.useDismiss()
  const pipPresented = useObservable(false)

  return <NavigationStack>
    <List
      navigationTitle="PiP Demo"
      navigationBarTitleDisplayMode="inline"
      toolbar={{
        topBarLeading: <Button
          title="Done"
          action={dismiss}
        />
      }}
      pip={{
        isPresented: pipPresented,
        content: <PipView />
      }}
    >
      <Button
        title="Toggle PiP"
        action={() => {
          pipPresented.setValue(!pipPresented.value)
        }}
      />
    </List>
  </NavigationStack>
}
```

***

## 8. Critical Notes

### 8.1 PiP views are constructed even when not presented

When `isPresented` is `false`:

- The PiP view is **not visible**
- But it is still constructed and participates in state binding

Therefore:

- Do not perform heavy computation in the view body
- Delay all side effects until `onPipStart`
- Always clean up in `onPipStop`

***

### 8.2 PiP-specific modifiers must be used only in the PiP view

The following properties and callbacks:

- `onPipStart`
- `onPipStop`
- `onPipPlayPauseToggle`
- `onPipSkip`
- `onPipRenderSizeChanged`
- `pipHideOnForeground`
- `pipShowOnBackground`

**Must be declared on the PiP content view (PipView)**.

Declaring them on a normal page view will result in:

- No callbacks being triggered
- Missing or incorrect state updates
- Undefined behavior

***

### 8.3 PiP is not suitable for complex UI

Avoid using the following inside PiP:

- `List` or `ScrollView`
- Complex or chained animations
- High-frequency state updates
- Network-driven UI rendering

PiP is designed for:

Lightweight, stable, and continuously visible system-level companion views.

***

## 9. Recommended Best Practices

- Design a dedicated, minimal PiP view
- Keep layout fixed and predictable
- Tune `maximumUpdatesPerSecond` carefully
- Start all logic in `onPipStart`
- Always release resources in `onPipStop`
- Never reuse complex page-level views inside PiP



---
url: /guide/View Modifiers/Presentation View Modifiers.md
---

# Presentation View Modifiers

These view modifiers customize the appearance, sizing, and interaction behavior of views presented using `sheet` in the **Scripting** app. They allow for adaptive presentations, resizing with detents, background interaction control, and more.

> Apply these modifiers to the **root view** of the sheet content (e.g., `<VStack>`, `<NavigationStack>`, or `<List>`).

***

## `presentationCompactAdaptation`

Defines how a sheet adapts in **compact horizontal or vertical size classes**.

### Type

```ts
presentationCompactAdaptation?: PresentationAdaptation | {
  horizontal: PresentationAdaptation
  vertical: PresentationAdaptation
}
```

### `PresentationAdaptation` options:

- `"automatic"` – System default behavior
- `"fullScreenCover"` – Adapts to full-screen presentation
- `"sheet"` – Adapts to sheet-style presentation
- `"popover"` – Adapts to popover-style (where supported)
- `"none"` – Disables adaptation

### Example

```tsx
<NavigationStack
  presentationCompactAdaptation={{
    horizontal: "fullScreenCover",
    vertical: "sheet"
  }}
>
  {/* Sheet content */}
</NavigationStack>
```

***

## `presentationDragIndicator`

Controls visibility of the drag indicator at the top of the sheet.

### Type

```ts
presentationDragIndicator?: "visible" | "hidden" | "automatic"
```

### Example

```tsx
<VStack presentationDragIndicator="visible">
  <Text>Pull the indicator to resize</Text>
</VStack>
```

***

## `presentationDetents`

Defines the **available heights** ("detents") that the sheet can rest at. If multiple detents are provided, the user can **drag the sheet** to resize it.

### Type

```ts
presentationDetents?: PresentationDetent[]
```

### `PresentationDetent` values:

- `"medium"` – Approximately half screen height (not available in compact vertical size class)
- `"large"` – Full screen height
- `number > 1` – A fixed height in points
- `number between 0 and 1` – A **fractional height** (e.g., `0.5` means 50% of available height)

### Example

```tsx
<VStack presentationDetents={[200, "medium", "large"]}>
  <Text>Drag the sheet to change its height</Text>
</VStack>
```

***

## `presentationBackgroundInteraction`

Defines whether and how the user can interact with **views behind** the presented sheet.

### Type

```ts
presentationBackgroundInteraction?:
  | "automatic"
  | "enabled"
  | "disabled"
  | { enabledUpThrough: PresentationDetent }
```

### Example

Allow background interaction **up to** a certain sheet size:

```tsx
<VStack presentationBackgroundInteraction={{
  enabledUpThrough: "medium"
}}>
  <Text>Background is interactive when sheet is small</Text>
</VStack>
```

***

## `presentationContentInteraction`

Controls how the sheet prioritizes **resizing vs scrolling** when the user swipes up.

### Type

```ts
presentationContentInteraction?: "automatic" | "resizes" | "scrolls"
```

### Description

- `"resizes"`: Swipe gesture first resizes the sheet, then scrolls content.
- `"scrolls"`: Content inside (e.g., `ScrollView`) scrolls immediately.
- `"automatic"`: System default (usually prefers resizing first).

### Example

```tsx
<ScrollView presentationContentInteraction="scrolls">
  {/* Scrolls immediately, doesn't trigger resize */}
</ScrollView>
```

***

## `presentationCornerRadius`

Sets a custom **corner radius** for the sheet background.

### Type

```ts
presentationCornerRadius?: number
```

### Example

```tsx
<VStack presentationCornerRadius={16}>
  <Text>Sheet has rounded corners</Text>
</VStack>
```

***

## Full Usage Example

```tsx
function SheetPage({ onDismiss }: {
  onDismiss: () => void
}) {
  return <NavigationStack>
    <List navigationTitle="Other Page">
      <Text font="title" padding={50}>
        Drag the indicator to resize the sheet height.
      </Text>
      <Button
        title="Dismiss"
        action={onDismiss}
      />
    </List>
  </NavigationStack>
}

<Button
  title="Present"
  action={() => setIsPresented(true)}
  sheet={{
    isPresented: isPresented,
    onChanged: setIsPresented,
    content: <SheetPage
      presentationDragIndicator="visible"
      presentationDetents={[200, "medium", "large"]}
      onDismiss={() => setIsPresented(false)}
    />
  }}
/>
```

***

## Summary

| Modifier                            | Description                                                             |
| ----------------------------------- | ----------------------------------------------------------------------- |
| `presentationCompactAdaptation`     | Defines how the sheet adapts in compact size classes                    |
| `presentationDragIndicator`         | Shows or hides the drag indicator                                       |
| `presentationDetents`               | Defines the heights the sheet can rest at                               |
| `presentationBackgroundInteraction` | Controls interaction with the background view during sheet presentation |
| `presentationContentInteraction`    | Determines whether sheet resizes or content scrolls on swipe            |
| `presentationCornerRadius`          | Sets a custom corner radius for the sheet                               |



---
url: /guide/View Modifiers/Redaction View Modifiers.md
---

# Redaction View Modifiers

## Redaction View Modifiers

The Scripting app supports view modifiers for applying redaction to a view hierarchy. Redaction allows views to display placeholder, obscured, or invalidated content, commonly used to indicate loading states, protect sensitive data, or mark content as outdated.

These modifiers closely follow SwiftUI's `redacted(reason:)` and `unredacted()` API behavior.

***

## `redacted`

```ts
redacted?: RedactedReason | null
```

Applies a redaction reason to the view hierarchy, changing the visual appearance of content according to the specified context.

### Description

Redaction visually alters the view and its descendants to reflect the current content state without modifying the underlying data. Use this modifier to display placeholders, hide private data, or indicate invalid content.

### Enum: `RedactedReason`

```ts
type RedactedReason = "placeholder" | "invalidated" | "privacy"
```

- **`placeholder`**: Displays generic placeholder visuals, typically used during loading.
- **`invalidated`**: Indicates the content is stale or awaiting a refresh.
- **`privacy`**: Obscures content to protect private or sensitive information.

### Example

```tsx
<Text
  redacted={"placeholder"}
>
  Loading text...
</Text>
```

In this example, the text will be displayed as a placeholder until real data is available.

***

## `unredacted`

```ts
unredacted?: boolean
```

Removes any previously applied redaction from the view hierarchy.

### Description

Set this property to `true` to opt a view out of inherited redaction, restoring its original appearance even when an ancestor view is redacted.

### Example

```tsx
<VStack redacted={"placeholder"}>
  <Text>Loading...</Text>
  <Text unredacted={true}>This content is not redacted</Text>
</VStack>
```

In this example, the entire `VStack` is redacted, but the second `Text` view will render normally due to `unredacted: true`.

***

## Usage Notes

- Redaction is purely visual and does not alter layout or accessibility semantics.
- `unredacted` is effective only when applied to a view that inherits redaction from an ancestor.
- Setting `redacted` to `null` removes any redaction from the current view.



---
url: /guide/View Modifiers/Safe Area.md
---

# Safe Area

Safe area modifiers in **Scripting** allow you to **adjust layout behavior relative to the system-defined safe areas**, such as the areas around notches, toolbars, or the on-screen keyboard.

***

## `safeAreaPadding`

Adds custom padding inside the safe area of a view. This modifier adjusts the visible content region by extending or inseting from the edges defined by the system’s safe area (e.g., accounting for the notch, home indicator, or rounded corners).

### Type

```ts
safeAreaPadding?: 
  true | 
  number | 
  {
    horizontal?: number | true
    vertical?: number | true
    leading?: number | true
    trailing?: number | true
    top?: number | true
    bottom?: number | true
  }
```

***

### Description

This modifier gives fine-grained control over how much padding should be added inside the safe area for specific edges or directions. You can either apply:

- **A default system padding** by passing `true`
- **A uniform padding** value by passing a `number`
- **Directional padding** for each edge using a detailed configuration object

This modifier is particularly useful when you want the view to respect or override the system safe area while maintaining proper layout spacing.

***

### Usage Options

- `true`: Applies default system padding on all safe area edges
- `number`: Applies the specified number of points as uniform padding on all edges
- `object`: Specifies padding per edge or direction

***

### Object Properties

- `horizontal`: Padding for both `leading` and `trailing` edges
- `vertical`: Padding for both `top` and `bottom` edges
- `leading`, `trailing`, `top`, `bottom`: Individual edge-specific padding
- Values can be a `number` or `true` to apply system default padding for that edge

***

### Example: Default Padding

```tsx
<VStack safeAreaPadding={true}>
  <Text>Hello</Text>
</VStack>
```

Applies system default padding on all safe area edges.

***

### Example: Custom Padding

```tsx
<VStack
  safeAreaPadding={{
    top: 20,
    bottom: true,
    horizontal: 12
  }}
>
  <Text>Content</Text>
</VStack>
```

Adds 20 points of padding at the top, system default padding at the bottom, and 12 points on both horizontal edges.

***

## `safeAreaInset`

Inserts a custom view into the safe area edge of another view.

### Type

```ts
safeAreaInset?: {
  top?: {
    alignment?: HorizontalAlignment
    spacing?: number
    content: VirtualNode
  },
  bottom?: {
    alignment?: HorizontalAlignment
    spacing?: number
    content: VirtualNode
  },
  leading?: {
    alignment?: VerticalAlignment
    spacing?: number
    content: VirtualNode
  },
  trailing?: {
    alignment?: VerticalAlignment
    spacing?: number
    content: VirtualNode
  }
}
```

***

### Description

- Adds content (such as toolbars, controls, or info bars) to the specified safe area edge: `top`, `bottom`, `leading`, or `trailing`.
- You can control **alignment** (horizontal or vertical) and **spacing** between the original view and the inserted content.
- Typically used in scrollable or full-screen layouts where you want to place persistent UI elements without obstructing core content.

***

### Example

```tsx
<ScrollView
  safeAreaInset={{
    bottom: {
      alignment: "center",
      spacing: 8,
      content: <Text>Toolbar here</Text>
    }
  }}
>
  <VStack>
    <Text>Scrollable content</Text>
  </VStack>
</ScrollView>
```

***

### Alignment Options

- **Horizontal** (for `top` and `bottom`): `"leading"`, `"center"`, `"trailing"`
- **Vertical** (for `leading` and `trailing`): `"top"`, `"center"`, `"bottom"`

### Notes

- `spacing` is optional. If omitted, a default system spacing will be applied.
- The `spacing` typo in the `leading`/`trailing` definition should be interpreted as `spacing`.

***

## `ignoresSafeArea`

Expands a view’s content to extend into one or more safe area regions.

### Type

```ts
ignoresSafeArea?: boolean | {
  regions?: SafeAreaRegions
  edges?: EdgeSet
}
```

***

### Description

- Allows a view to "ignore" the system-defined safe areas and occupy the full screen or extend under system UI.
- Useful for immersive layouts like full-screen images, maps, or background layers.

### Boolean Usage

```tsx
<Image
  imageUrl="https://example.com/background.jpg"
  ignoresSafeArea
/>
```

> This will ignore all safe area regions on all edges.

### Object Usage

```tsx
<VStack
  ignoresSafeArea={{
    regions: "all",
    edges: "bottom"
  }}
>
  <Text>Bottom edge extends under home indicator</Text>
</VStack>
```

### `regions` (optional)

| Value         | Description                                    |
| ------------- | ---------------------------------------------- |
| `"all"`       | Ignores all regions (default)                  |
| `"container"` | Ignores container padding (e.g., nav/tab bars) |
| `"keyboard"`  | Ignores the software keyboard area             |

### `edges` (optional)

| Value          | Description                            |
| -------------- | -------------------------------------- |
| `"top"`        | Ignores the top safe area              |
| `"bottom"`     | Ignores the bottom safe area           |
| `"leading"`    | Ignores the leading (left) safe area   |
| `"trailing"`   | Ignores the trailing (right) safe area |
| `"vertical"`   | Ignores top + bottom                   |
| `"horizontal"` | Ignores leading + trailing             |
| `"all"`        | Ignores all edges (default if omitted) |



---
url: /guide/View Modifiers/Search Interactions.md
---

# Search Interactions

The Scripting app supports advanced search interactions similar to SwiftUI. You can add a search bar, control its visibility and placement, react to changes in input, and display dynamic suggestions.

***

## `searchable`

Marks a view as searchable by displaying a search field and binding it to a state value.

### Type

```ts
searchable?: {
  value: string
  onChanged: (value: string) => void
  placement?: SearchFieldPlacement
  prompt?: string
  presented?: {
    value: boolean
    onChanged: (value: boolean) => void
  }
}
```

### Description

- Displays a search field in the view (typically above a `<List>`).
- The `value` is the current search query, which you control via state.
- The `onChanged` callback updates the state when the user types.
- Optionally provide a `prompt` as placeholder text.
- Use `placement` to customize where the search field appears.
- Use `presented` to programmatically show or dismiss the search field.

### Example

```tsx
function SearchExample() {
  const [query, setQuery] = useState("")
  const [showSearch, setShowSearch] = useState(false)

  return (
    <List
      searchable={{
        value: query,
        onChanged: setQuery,
        placement: "navigationBarDrawer",
        prompt: "Search items",
        presented: {
          value: showSearch,
          onChanged: setShowSearch,
        }
      }}
    >
      <Text>Searching: {query}</Text>
    </List>
  )
}
```

### `SearchFieldPlacement` options

| Value                                   | Description                                                |
| --------------------------------------- | ---------------------------------------------------------- |
| `'automatic'`                           | Default behavior, automatically selected placement.        |
| `'navigationBarDrawer'`                 | Appears as a drawer below the navigation bar.              |
| `'navigationBarDrawerAlwaysDisplay'`    | Always shows the drawer, even when inactive.               |
| `'navigationBarDrawerAutomaticDisplay'` | Shows drawer only when needed.                             |
| `'toolbar'`                             | Displays the search field in the toolbar.                  |
| `'sidebar'`                             | Places the search field in the sidebar (iPad/macOS-style). |

***

## `searchSuggestions`

Displays a list of suggestions below the search field as the user types.

### Type

```ts
searchSuggestions?: VirtualNode
```

### Description

Use this to return a list of suggestions, typically based on the user's input.

### Example

```tsx
const suggestions = useMemo(() => [
  {
    label: "🍎 Apple",
    value: "Apple"
  },
  {
    label: "🍌 Bananer",
    value: "Bananer"
  }
], [])
const filteredSuggestions = useMemo(() => {
  if (!/\S+/.test(query)) {
    return suggestions
  }
  const q = query.toLowerCase()
  return suggestions.filter(s =>
    s.label.toLowerCase().includes(q) ||
    s.value.toLowerCase().includes(q))
}, [query, suggestions])

<List
  searchable={{
    value: query,
    onChanged: setQuery
  }}
  searchSuggestions={
    <>
      {filteredSuggestions.map(s =>
        <Text
          searchCompletion={s.value}
        >{s.label}</Text>
      )}
    </>
  }
/>
```

***

## `searchSuggestionsVisibility`

Controls when and where search suggestions are shown.

### Type

```ts
searchSuggestionsVisibility?: {
  visibility: 'visible' | 'hidden'
  placements: SearchSuggestionsPlacementSet
}
```

### `SearchSuggestionsPlacementSet` options

| Value       | Description                                 |
| ----------- | ------------------------------------------- |
| `'content'` | Shows suggestions inline with the content.  |
| `'menu'`    | Shows suggestions in a popover or dropdown. |
| `'all'`     | Applies to all available placements.        |

### Example

```tsx
<List
  searchSuggestionsVisibility={{
    visibility: 'visible',
    placements: 'menu'
  }}
/>
```

***

## `searchCompletion`

Associates a tappable search suggestion with a complete search query string.

### Type

```ts
searchCompletion?: string
```

### Description

Apply this modifier to suggestion views (such as `<Text>`) to indicate what value should be filled into the search field when the user taps the suggestion.

### Example

```tsx
<Text searchCompletion="Mango">🥭 Mango</Text>
```

When tapped, this will set the search field to `"Mango"`.

***

## Summary

| Modifier                      | Purpose                                               |
| ----------------------------- | ----------------------------------------------------- |
| `searchable`                  | Adds a search field with bindings and customization.  |
| `searchSuggestions`           | Provides a list of custom suggestions.                |
| `searchSuggestionsVisibility` | Controls where and when suggestions are shown.        |
| `searchCompletion`            | Defines the value used when a suggestion is selected. |

These modifiers work together to create a responsive, interactive search experience in any scrollable view like `<List>`.



---
url: /guide/View Modifiers/Set environment values (environments).md
---

# Set environment values (environments)

The `environments` view modifier allows injecting specific environment values into the current view hierarchy.
It serves a role similar to SwiftUI’s `.environment()`, but with a more explicit and controlled design tailored for Scripting.

Currently, the modifier supports:

- `editMode` — controls editing behavior in views such as `List`
- `layoutDirection` — sets the layout direction for descendant views
- `openURL` — customizes how links are handled when tapped

These environment values affect all descendants within the modified view subtree.

***

## Modifier Definition

```ts
environments?: {
  editMode?: Observable<EditMode>;
  layoutDirection?: "leftToRight" | "rightToLeft";
  openURL?: (url: string) => OpenURLActionResult;
};
```

***

## 1. editMode Environment

The `editMode` environment value controls the editing state of views that support editing behavior, such as `List` with row deletion or movement.

It must be provided as an `Observable<EditMode>` so views can reactively update when the editing state changes.

## EditMode Type

```ts
class EditMode {
  readonly value: "active" | "inactive" | "transient" | "unknown";
  readonly isEditing: boolean;

  static active(): EditMode;
  static inactive(): EditMode;
  static transient(): EditMode;
}
```

### Meaning of `value`

| Value       | Description                   |
| ----------- | ----------------------------- |
| `active`    | Editing mode is enabled       |
| `inactive`  | Editing mode is disabled      |
| `transient` | Temporary transitional state  |
| `unknown`   | Undefined or unexpected state |

***

## editMode Example

```tsx
const editMode = useObservable(() => EditMode.active())

<List
  environments={{
    editMode: editMode
  }}
>
  <ForEach
    editActions="all"
    data={items}
    builder={item => <Text key={item.id}>{item}</Text>}
  />
</List>
```

***

## 2. layoutDirection Environment

The `layoutDirection` environment value controls whether descendant views lay out from left to right or from right to left.

## Type

```ts
layoutDirection?: "leftToRight" | "rightToLeft";
```

## layoutDirection Example

```tsx
<HStack
  environments={{
    layoutDirection: "rightToLeft"
  }}
>
  <Text>First</Text>
  <Text>Second</Text>
</HStack>
```

***

## 3. openURL Environment

The `openURL` environment value customizes how URLs are handled when interacted with inside the view tree.
It overrides the default behavior of components such as `<Link>`.

This is useful for:

- Deciding whether URLs should open inside the app or externally
- Filtering or validating URLs
- Redirecting URLs to different handlers

## Function Signature

```ts
openURL?: (url: string) => OpenURLActionResult;
```

***

## OpenURLActionResult

```ts
class OpenURLActionResult {
  type: string;

  static handled(): OpenURLActionResult;
  static discarded(): OpenURLActionResult;

  static systemAction(options?: {
    url?: string;
    /**
     * Whether the system should prefer opening the URL in-app.
     * Requires iOS 26.0+.
     */
    prefersInApp: boolean;
  }): OpenURLActionResult;
}
```

### Result Behavior

| Method           | Meaning                                                     |
| ---------------- | ----------------------------------------------------------- |
| `handled()`      | The URL is considered fully handled; default behavior stops |
| `discarded()`    | The URL is ignored                                          |
| `systemAction()` | Requests the system to open a (possibly modified) URL       |

### iOS Requirement

- `prefersInApp` **requires iOS 26.0+**
- On earlier versions, the parameter may have no effect and system defaults will apply

***

## openURL Example

```tsx
<Group
  environments={{
    openURL: (url) => {
      return OpenURLActionResult.systemAction({
        url,
        prefersInApp: false   // Requires iOS 26.0+
      })
    }
  }}
>
  {urls.map(url =>
    <Link url={url}>{url}</Link>
  )}
</Group>
```

***

## Combined Example (editMode + openURL)

```tsx
const editMode = useObservable(() => EditMode.inactive())

<VStack
  environments={{
    editMode,
    layoutDirection: "leftToRight",
    openURL: (url) => {
      if (url.startsWith("https://safe.com")) {
        return OpenURLActionResult.systemAction({
          url,
          prefersInApp: true   // iOS 26.0+ only
        })
      }
      return OpenURLActionResult.discarded()
    }
  }}
>
  <Button
    title="Toggle Edit"
    action={() => {
      editMode.value = editMode.value.isEditing
        ? EditMode.inactive()
        : EditMode.active()
    }}
  />

  <List>
    ...
  </List>

  <Link url="https://safe.com">Safe Link</Link>
  <Link url="https://blocked.com">Blocked Link</Link>
</VStack>
```

***

## Notes & Behavior Summary

1. The `environments` modifier applies only to the subtree where it is used.
2. `editMode` must be an `Observable<EditMode>` for reactive updates.
3. `layoutDirection` accepts `"leftToRight"` or `"rightToLeft"`.
4. `openURL` replaces default URL-handling behavior for all descendant views.
5. Returning `handled()` stops further URL processing.
6. `systemAction()` delegates handling back to the system.
7. **`prefersInApp` requires iOS 26.0+** and may be ignored on earlier versions.
8. Scripting’s environment system is explicit—only the values you define are injected.



---
url: /guide/View Modifiers/Status Bar & System Overlays.md
---

# Status Bar & System Overlays

Controls the visibility of the status bar and the non-transient system overlays (such as the Home indicator) for a page — useful for building immersive, full-screen experiences.

## Type

```ts
// Hide the status bar.
statusBarHidden?: boolean

// Preferred visibility of system overlays such as the Home indicator.
// "hidden" lets the system auto-hide them; "visible" keeps them shown; "automatic" lets the system decide.
// Requires iOS 16.0 or later.
persistentSystemOverlays?: "automatic" | "visible" | "hidden"
```

## Important

For these to take effect:

- **Apply them to the page's root view** — for example the `NavigationStack`, not an inner child. A navigation container intercepts the preference, so applying it to a nested view does nothing.
- **Present the page full screen.** In a sheet presentation the status bar and system overlays are owned by the presenting page, so the preference is ignored:

  ```ts
  Navigation.present({
    element: <MyImmersivePage />,
    modalPresentationStyle: "fullScreen",
  })
  ```

Notes:

- `persistentSystemOverlays="visible"` is the default state, so it produces no observable change. Use `"hidden"` to see an effect.
- iOS never removes the Home indicator permanently — `"hidden"` only dims and auto-hides it; it reappears on interaction.

## Example

```tsx
function ImmersivePage() {
  return <NavigationStack
    statusBarHidden={true}
    persistentSystemOverlays="hidden"
  >
    <VStack frame={Device.screen}>
      <Text>Immersive full-screen content</Text>
    </VStack>
  </NavigationStack>
}

// Present full screen so the modifiers take effect.
Navigation.present({
  element: <ImmersivePage />,
  modalPresentationStyle: "fullScreen",
})
```

You can also apply them as chainable modifiers:

```tsx
<NavigationStack>
  ...
</NavigationStack>
  .statusBarHidden(true)
  .persistentSystemOverlays("hidden")
```



---
url: /guide/View Modifiers/Swipe Actions/index.md
---

# Swipe Actions

In the **Scripting** app, you can attach swipe actions to views used as rows in a `<List>` (such as `<HStack>`) to support contextual interactions like deleting, editing, marking favorites, etc.

To improve clarity and ease of use in TypeScript, the SwiftUI `swipeActions` modifier is split into two separate modifiers:

- `leadingSwipeActions`: For swipe gestures from left to right.
- `trailingSwipeActions`: For swipe gestures from right to left.

***

## `leadingSwipeActions`

Adds swipe actions to the **leading** (left) edge of a list row.

### Type

```ts
leadingSwipeActions?: {
  allowsFullSwipe?: boolean
  actions: VirtualNode[]
}
```

### Description

- `actions`: An array of `<Button>` elements that will appear when the user swipes right on the row.
- `allowsFullSwipe`: If `true` (default), a full swipe will automatically invoke the **first action** in the list.

***

## `trailingSwipeActions`

Adds swipe actions to the **trailing** (right) edge of a list row.

### Type

```ts
trailingSwipeActions?: {
  allowsFullSwipe?: boolean
  actions: VirtualNode[]
}
```

### Description

- `actions`: An array of `<Button>` elements that appear when the user swipes left on the row.
- `allowsFullSwipe`: If `true` (default), a full swipe will automatically trigger the **first action**.

***

## Example Usage

```tsx
<List>
  {list.map(item => 
    <HStack
      trailingSwipeActions={{
        allowsFullSwipe: true,
        actions: [
          <Button
            title="Delete"
            role="destructive"
            action={() => deleteItem(item)}
          />,
          <Button
            title="Edit"
            tint="accentColor"
            action={() => editItem(item)}
          />
        ]
      }}
    >
      <Image systemName={item.icon} />
      <Text>{item.title}</Text>
    </HStack>
  )}
</List>
```

You can also add leading actions:

```tsx
<HStack
  leadingSwipeActions={{
    actions: [
      <Button
        title="Favorite"
        tint="orange"
        action={() => markAsFavorite(item)}
      />
    ]
  }}
>
  <Text>{item.title}</Text>
</HStack>
```

***

## Button Roles and Styling

Each swipe action must be a `<Button>` component. You can customize buttons with:

- `title`: Text label for the button.
- `action`: The function to execute when tapped.
- `role` (optional): `"destructive"` for delete-like actions.
- `tint` (optional): Use system color names like `"accentColor"` or any custom color string.

***

## Notes

- You can use both `leadingSwipeActions` and `trailingSwipeActions` on the same row.
- Only views used within a scrollable list (like `<List>`) support swipe actions.
- If `allowsFullSwipe` is disabled, the user must tap the button rather than relying on a full swipe gesture.



---
url: /guide/View Modifiers/Swipe Actions/index_example.md
---

# Example

```tsx
import { Button, Circle, HStack, Label, List, Navigation, NavigationStack, Script, Text, useState, VStack } from "scripting"

type Message = {
  from: string
  content: string
  isUnread: boolean
}

function MessageCell({
  message
}: {
  message: Message
}) {
  return <HStack>
    <Circle
      fill={message.isUnread ? "systemBlue" : "clear"}
      frame={{
        width: 16,
        height: 16,
      }}
    />
    <VStack
      alignment={"leading"}
    >
      <Text font={"headline"}>{message.from}</Text>
      <Text>{message.content}</Text>
    </VStack>
  </HStack>
}

function Example() {
  const [messages, setMessages] = useState<Message[]>(() => [
    {
      from: "Maria Ruiz",
      content: "If you have a list of messages, you can add an action to toggle a message as unread on a swipe from the leading edge, and actions to delete or flag messages on a trailing edge swipe.",
      isUnread: true,
    },
    {
      from: "Mei Chen",
      content: "Actions appear in the order you list them, starting from the swipe’s originating edge. In the example, the Delete action appears closest to the screen’s trailing edge",
      isUnread: true,
    },
    {
      from: "Maria Ruiz",
      content: "By default, the user can perform the first action for a given swipe direction with a full swipe. The user can perform both the toggle unread and delete actions with full swipes. You can opt out of this behavior for an edge by setting the allowsFullSwipe parameter to false.",
      isUnread: false,
    },
    {
      from: "Mei Chen",
      content: "When you set a role for a button using one of the values from the ButtonRole, system styles the button according to its role. In the example above, the delete action appears in red because it has the destructive role. If you want to set a different color, add the tint property to the button",
      isUnread: true,
    }
  ])

  function toggleUnread(message: Message) {
    setMessages(messages.map(item => item !== message ? item : {
      ...message,
      isUnread: !item.isUnread
    }))
  }

  function deleteMessage(message: Message) {
    setMessages(messages.filter(item => item !== message))
  }

  return <NavigationStack>
    <List
      navigationTitle={"Messages"}
      navigationBarTitleDisplayMode={"inline"}
      listStyle={"inset"}
    >
      {messages.map(message =>
        <MessageCell
          message={message}
          leadingSwipeActions={{
            allowsFullSwipe: false,
            actions: [
              <Button
                action={() => toggleUnread(message)}
                tint={"systemBlue"}
              >
                {message.isUnread
                  ? <Label title={"Read"} systemImage={"envelope.open"} />
                  : <Label title={"Unread"} systemImage={"envelope.badge"} />
                }
              </Button>
            ]
          }}
          trailingSwipeActions={{
            actions: [
              <Button
                role={"destructive"}
                action={() => deleteMessage(message)}
              >
                <Label title={"Delete"} systemImage={"trash"} />
              </Button>,
              <Button
                action={() => { }}
                tint={"systemOrange"}
              >
                <Label title={"Flag"} systemImage={"flag"} />
              </Button>
            ]
          }}
        />
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/View Modifiers/Symbol Style/index.md
---

# Symbol Style

These modifiers allow you to customize how **SF Symbols** are displayed and animated inside views, particularly with the `Image` component.

***

## `symbolRenderingMode`

Sets the **rendering mode** for symbol images within the view.

### Type

```ts
symbolRenderingMode?: SymbolRenderingMode
```

### Options (`SymbolRenderingMode`)

- `"monochrome"` – A single-color version using the foreground style
- `"hierarchical"` – Multiple layers with different opacities for depth (good for semantic coloring)
- `"multicolor"` – Uses the symbol's built-in colors
- `"palette"` – Allows layered tinting (like using multiple `foregroundStyle` layers)

### Example

```tsx
<Image
  systemName="star.fill"
  symbolRenderingMode="palette"
  foregroundStyle={{
    primary: "red",
    secondary: "orange",
    tertiary: "yellow"
  }}
/>
```

### Explanation:

- `symbolRenderingMode="palette"` tells the system to render the symbol in **multiple layered styles**.
- `foregroundStyle` now uses an object with `primary`, `secondary`, and optionally `tertiary` layers to color those symbol layers individually.

> This matches SwiftUI's behavior with `.symbolRenderingMode(.palette)` and `.foregroundStyle(primary, secondary, tertiary)`.

***

## `symbolVariant`

Displays the symbol with a particular **visual variant**.

### Type

```ts
symbolVariant?: SymbolVariants
```

### Options (`SymbolVariants`)

- `"none"` – Default symbol with no variant
- `"circle"` – Encapsulated in a circle
- `"square"` – Encapsulated in a square
- `"rectangle"` – Encapsulated in a rectangle
- `"fill"` – Filled symbol
- `"slash"` – Adds a slash over the symbol (often used to indicate "off" states)

### Example

```tsx
<Image
  systemName="wifi"
  symbolVariant="slash"
/>
```

***

## `symbolEffect`

Applies a **symbol animation effect** to the view. This can include transitions (appear/disappear), scale, bounce, rotation, breathing, pulsing, and wiggle effects. You can also bind the effect to a value so it animates when the value changes.

### Type

```ts
symbolEffect?: SymbolEffect
```

There are two forms of usage:

***

### 1. **Simple effects** (transition, scale, etc.)

You can directly assign a symbol effect name:

#### Examples

```tsx
<Image
  systemName="heart"
  symbolEffect="appear"
/>

<Image
  systemName="checkmark"
  symbolEffect="scaleByLayer"
/>
```

***

### 2. **Value-bound discrete effects**

These effects animate when the associated value changes.

#### Type

```ts
symbolEffect?: {
  effect: DiscreteSymbolEffect
  value: string | number | boolean
  options?: SymbolEffectOptions
}
```

#### Example

```tsx
<Image
  systemName="star.fill"
  symbolEffect={{
    effect: "bounce",
    value: isFavorited
  }}
/>
```

In this example, each time `isFavorited` changes, the bounce animation is triggered.

***

### 3. **Trigger effects** (`isActive`, mirrors SwiftUI `symbolEffect(_:options:isActive:)`)

In SwiftUI's trigger form, the **steady state is `isActive = false`** (symbol visible). Flipping `isActive` plays the effect's animation; the direction depends on the effect:

| Effect        | `isActive=false` (steady) | `isActive=true` (effect engaged)         |
| ------------- | ------------------------- | ---------------------------------------- |
| `appear`      | invisible                 | visible (appears)                        |
| `disappear`   | visible                   | invisible (disappears)                   |
| `scale`       | base size                 | scaled                                   |
| **`drawOn`**  | **visible** (drawn)       | **invisible** (draw-off animation plays) |
| **`drawOff`** | **invisible**             | **visible** (draw-on animation plays)    |

Note that `drawOn` / `drawOff` describe the **animation style** (stroke-by-stroke drawing) — not the final state. `.drawOn` behaves like `.disappear` with a draw-style animation; `.drawOff` behaves like `.appear` with a draw-style animation.

```tsx
const [hidden, setHidden] = useState(false)

<Image
  systemName="checkmark.circle"
  symbolEffect={{
    effect: "drawOn",
    isActive: hidden,
  }}
/>

<Button title={hidden ? "Show" : "Hide"} action={() => setHidden(!hidden)} />
```

> `drawOn` / `drawOff` are SF Symbols 7 effects (iOS 26+). On earlier iOS the bridge silently passes content through unchanged.

***

### 4. **Animation options** (`SymbolEffectOptions`)

Attach `options` to either the value-bound or the trigger form. **Note:** SwiftUI treats trigger-form transitions like `drawOn` / `drawOff` / `appear` / `disappear` as single-shot — `repeat` is honored most reliably on value-bound effects (`pulse`, `bounce`, etc.).

```tsx
<Image
  systemName="bell.fill"
  symbolEffect={{
    effect: "pulse",
    value: pulseTick,
    options: {
      speed: 0.7,
      repeat: { count: 3, delay: 0.4 },
    },
  }}
/>
```

```ts
type SymbolEffectOptions = {
  /** Animation speed multiplier. `2` = twice as fast. */
  speed?: number
  /** Force a one-shot. Mutually exclusive with `repeat` — if both are set, `nonRepeating` wins and a warning is logged. */
  nonRepeating?: boolean
  /**
   * Repetition policy:
   *  - `"continuous"`: loop forever (iOS 18+; on iOS 17 falls back to `.repeating`)
   *  - `{ count, delay? }`: periodic — `count` cycles with optional `delay` (seconds) between them (iOS 18+)
   *  - `{ delay }`: periodic with delay only (iOS 18+)
   */
  repeat?:
    | "continuous"
    | { count: number; delay?: number }
    | { delay: number; count?: number }
}
```

***

## Available Discrete Effects (`DiscreteSymbolEffect`)

Use these with the value-bound form — animation replays whenever `value` changes.

| Category          | Effects                                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bounce**        | `bounce`, `bounceByLayer`, `bounceDown`, `bounceUp`, `bounceWholeSymbol`                                                                                                              |
| **Breathe**       | `breathe`, `breatheByLayer`, `breathePlain`, `breathePulse`, `breatheWholeSymbol`                                                                                                     |
| **Pulse**         | `pulse`, `pulseByLayer`, `pulseWholeSymbol`                                                                                                                                           |
| **Rotate**        | `rotate`, `rotateByLayer`, `rotateClockwise`, `rotateCounterClockwise`, `rotateWholeSymbol`                                                                                           |
| **VariableColor** | `variableColor`, `variableColorCumulative`, `variableColorDimInactiveLayers`, `variableColorHideInactiveLayers`, `variableColorIterative`                                             |
| **Wiggle**        | `wiggle`, `wiggleByLayer`, `wiggleWholeSymbol`, `wiggleLeft`, `wiggleRight`, `wiggleUp`, `wiggleDown`, `wiggleForward`, `wiggleBackward`, `wiggleClockwise`, `wiggleCounterClockwise` |

## Available Trigger Effects (`TriggerSymbolEffect`)

Use these with the `isActive` form. `drawOn` / `drawOff` are iOS 26+; the rest are iOS 17+.

| Category                               | Effects                                                                                 |
| -------------------------------------- | --------------------------------------------------------------------------------------- |
| **Appear**                             | `appear`, `appearByLayer`, `appearUp`, `appearDown`, `appearWholeSymbol`                |
| **Disappear**                          | `disappear`, `disappearByLayer`, `disappearUp`, `disappearDown`, `disappearWholeSymbol` |
| **Scale**                              | `scale`, `scaleByLayer`, `scaleUp`, `scaleDown`, `scaleWholeSymbol`                     |
| **DrawOn** _(iOS 26+ / SF Symbols 7)_  | `drawOn`, `drawOnByLayer`, `drawOnWholeSymbol`, `drawOnIndividually`                    |
| **DrawOff** _(iOS 26+ / SF Symbols 7)_ | `drawOff`, `drawOffByLayer`, `drawOffWholeSymbol`, `drawOffIndividually`                |

***

## Full Example

```tsx
<Image
  systemName="bell.fill"
  symbolRenderingMode="hierarchical"
  symbolVariant="circle"
  symbolEffect={{
    effect: "breathePulse",
    value: isNotified
  }}
  foregroundStyle="indigo"
/>
```

This image uses:

- a hierarchical rendering mode
- a circular variant around the symbol
- a pulsing animation bound to `isNotified` state

***

## Summary

| Modifier              | Description                                                             |
| --------------------- | ----------------------------------------------------------------------- |
| `symbolRenderingMode` | Sets how SF Symbols are rendered (monochrome, multicolor, etc.)         |
| `symbolVariant`       | Applies a visual variant like `fill`, `circle`, or `slash`              |
| `symbolEffect`        | Adds visual animation effects; can be static or bound to a state change |



---
url: /guide/View Modifiers/Symbol Style/index_example.md
---

# Example

```tsx
import { Button, HStack, Image, Navigation, NavigationStack, Script, Text, useState, VStack } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  // drawOn: isActive=false is the steady "drawn" state (visible).
  // Flipping isActive false→true triggers the DRAW-OFF animation (the symbol erases away).
  // Flipping back triggers the DRAW-ON animation (the symbol redraws).
  const [hiddenDefault, setHiddenDefault] = useState(false)
  const [hiddenByLayer, setHiddenByLayer] = useState(false)
  const [hiddenIndividually, setHiddenIndividually] = useState(false)

  // options demo: pulse on a value change, with speed + finite repeat.
  // value-form effects honor `repeat` reliably; trigger-form drawOn does not (single-shot).
  const [pulseTick, setPulseTick] = useState(0)

  // appear/disappear via isActive (iOS 17+) — analogous trigger family.
  const [hiddenStar, setHiddenStar] = useState(false)

  // existing value-form regression
  const [bounceCounter, setBounceCounter] = useState(0)

  return <NavigationStack>
    <VStack
      navigationTitle="symbolEffect"
      navigationBarTitleDisplayMode="inline"
      toolbar={{
        topBarTrailing: <Button title="Done" action={dismiss} />
      }}
    >
      <VStack
        spacing={24}
        padding
        alignment="leading"
      >
        {/* drawOn / drawOff (iOS 26+) */}
        <VStack alignment="leading" spacing={8}>
          <Text font="headline">drawOn (iOS 26+)</Text>
          <Text font="caption" foregroundStyle="secondaryLabel">
            With drawOn, isActive=false is the "drawn" steady state. Tap Hide to play
            the draw-OFF animation (erases away); tap Show to play draw-ON (redraws).
            byLayer / individually only change how layered symbols animate.
          </Text>
          <HStack spacing={24}>
            <VStack spacing={6}>
              <Image
                systemName="checkmark.circle"
                font={48}
                foregroundStyle="systemGreen"
                symbolEffect={{ effect: "drawOn", isActive: hiddenDefault }}
              />
              <Button
                title={hiddenDefault ? "Show" : "Hide"}
                action={() => setHiddenDefault(!hiddenDefault)}
                controlSize="small"
                buttonStyle="bordered"
              />
              <Text font="caption2">drawOn</Text>
            </VStack>
            <VStack spacing={6}>
              <Image
                systemName="square.and.arrow.up"
                font={48}
                foregroundStyle="systemBlue"
                symbolEffect={{ effect: "drawOnByLayer", isActive: hiddenByLayer }}
              />
              <Button
                title={hiddenByLayer ? "Show" : "Hide"}
                action={() => setHiddenByLayer(!hiddenByLayer)}
                controlSize="small"
                buttonStyle="bordered"
              />
              <Text font="caption2">byLayer</Text>
            </VStack>
            <VStack spacing={6}>
              <Image
                systemName="cloud.sun"
                font={48}
                foregroundStyle="systemOrange"
                symbolEffect={{ effect: "drawOnIndividually", isActive: hiddenIndividually }}
              />
              <Button
                title={hiddenIndividually ? "Show" : "Hide"}
                action={() => setHiddenIndividually(!hiddenIndividually)}
                controlSize="small"
                buttonStyle="bordered"
              />
              <Text font="caption2">individually</Text>
            </VStack>
          </HStack>
        </VStack>

        {/* options on a value-form effect (where speed + repeat are reliably honored) */}
        <VStack alignment="leading" spacing={8}>
          <Text font="headline">options (speed + repeat)</Text>
          <Text font="caption" foregroundStyle="secondaryLabel">
            Tap Pulse to replay the pulse animation 3 times at 0.7x speed with a 0.4s gap.
            options.repeat works on value-bound effects; trigger-form drawOn is single-shot.
          </Text>
          <HStack spacing={16}>
            <Image
              systemName="bell.fill"
              font={48}
              foregroundStyle="systemRed"
              symbolEffect={{
                effect: "pulse",
                value: pulseTick,
                options: { speed: 0.7, repeat: { count: 3, delay: 0.4 } },
              }}
            />
            <Button
              title="Pulse"
              action={() => setPulseTick(pulseTick + 1)}
              buttonStyle="borderedProminent"
              controlSize="small"
            />
            <Text font="caption" monospaced>tick: {pulseTick}</Text>
          </HStack>
        </VStack>

        {/* appear / disappear via isActive */}
        <VStack alignment="leading" spacing={8}>
          <Text font="headline">disappear (isActive)</Text>
          <Text font="caption" foregroundStyle="secondaryLabel">
            The same trigger form works for the iOS 17+ appear / disappear / scale family.
            disappear isActive=true hides the symbol (fade-style), parallel to drawOn isActive=true.
          </Text>
          <HStack spacing={16}>
            <Image
              systemName="star.fill"
              font={48}
              foregroundStyle="systemYellow"
              symbolEffect={{ effect: "disappear", isActive: hiddenStar }}
            />
            <Button
              title={hiddenStar ? "Show" : "Hide"}
              action={() => setHiddenStar(!hiddenStar)}
              buttonStyle="bordered"
              controlSize="small"
            />
          </HStack>
        </VStack>

        {/* value-form regression */}
        <VStack alignment="leading" spacing={8}>
          <Text font="headline">value-bound (bounce on change)</Text>
          <Text font="caption" foregroundStyle="secondaryLabel">
            Existing form: animation replays whenever value changes.
          </Text>
          <HStack spacing={16}>
            <Image
              systemName="heart.fill"
              font={48}
              foregroundStyle="systemPink"
              symbolEffect={{ effect: "bounce", value: bounceCounter }}
            />
            <Button
              title="Bounce"
              action={() => setBounceCounter(bounceCounter + 1)}
              buttonStyle="bordered"
              controlSize="small"
            />
            <Text font="caption" monospaced>{bounceCounter}</Text>
          </HStack>
        </VStack>
      </VStack>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />,
  })

  Script.exit()
}

run()

```



---
url: /guide/View Modifiers/Text Field.md
---

# Text Field

The following modifiers customize the behavior and appearance of `TextField` components. These allow you to control keyboard behavior, input handling, and submission logic.

***

## `onSubmit`

Adds an action to perform when the user submits a value from the text field.

### Type

```ts
onSubmit?: (() => void) | {
  triggers: SubmitTriggers
  action: () => void
}
```

### Behavior

- If provided as a function:

  ```tsx
  <TextField onSubmit={() => console.log('Submitted')} />
  ```

  This is equivalent to:

  ```tsx
  <TextField
    onSubmit={{
      triggers: 'text',
      action: () => console.log('Submitted')
    }}
  />
  ```

- You can explicitly define what kind of submission should trigger the action using the `triggers` option:

  ```tsx
  <TextField
    onSubmit={{
      triggers: 'search',
      action: () => console.log('Search submitted')
    }}
  />
  ```

### `SubmitTriggers` values:

- `"text"`: Triggered by text input views like `TextField`, `SecureField`, etc.
- `"search"`: Triggered by search fields (e.g., those using the `searchable` modifier).

***

## `keyboardType`

Specifies the type of keyboard to display when the text field is focused.

### Type

```ts
keyboardType?: KeyboardType
```

### Options

- `'default'`
- `'numberPad'`
- `'phonePad'`
- `'namePhonePad'`
- `'URL'`
- `'decimalPad'`
- `'asciiCapable'`
- `'asciiCapableNumberPad'`
- `'emailAddress'`
- `'numbersAndPunctuation'`
- `'twitter'`
- `'webSearch'`

### Example

```tsx
<TextField keyboardType="emailAddress" />
```

***

## `autocorrectionDisabled`

Controls whether the system autocorrection is enabled.

### Type

```ts
autocorrectionDisabled?: boolean
```

### Default

- `true` — autocorrection is disabled by default.

### Example

```tsx
<TextField autocorrectionDisabled={false} />
```

***

## `textInputAutocapitalization`

Sets how the text input system should automatically capitalize text.

### Type

```ts
textInputAutocapitalization?: TextInputAutocapitalization
```

### Options

- `"never"` – No capitalization.
- `"characters"` – All letters capitalized.
- `"sentences"` – First letter of each sentence capitalized.
- `"words"` – First letter of each word capitalized.

### Example

```tsx
<TextField textInputAutocapitalization="words" />
```

***

## `textContentType`

Sets the semantic meaning expected for the text input. The system can use it for autofill and keyboard suggestions.

### Type

```ts
textContentType?: TextContentType
```

### Options

- `"cellularEID"`
- `"cellularIMEI"`
- `"URL"`
- `"namePrefix"`
- `"name"`
- `"nameSuffix"`
- `"givenName"`
- `"middleName"`
- `"familyName"`
- `"nickname"`
- `"organizationName"`
- `"jobTitle"`
- `"location"`
- `"fullStreetAddress"`
- `"streetAddressLine1"`
- `"streetAddressLine2"`
- `"addressCity"`
- `"addressCityAndState"`
- `"addressState"`
- `"postalCode"`
- `"sublocality"`
- `"countryName"`
- `"username"`
- `"password"`
- `"newPassword"`
- `"oneTimeCode"`
- `"emailAddress"`
- `"telephoneNumber"`
- `"creditCardNumber"`
- `"creditCardExpiration"`
- `"creditCardExpirationMonth"`
- `"creditCardExpirationYear"`
- `"creditCardSecurityCode"`
- `"creditCardType"`
- `"creditCardName"`
- `"creditCardGivenName"`
- `"creditCardMiddleName"`
- `"creditCardFamilyName"`
- `"birthdate"`
- `"birthdateDay"`
- `"birthdateMonth"`
- `"birthdateYear"`
- `"dateTime"`
- `"flightNumber"`
- `"shipmentTrackingNumber"`

### Example

```tsx
<TextField textContentType="oneTimeCode" />
```

***

## `submitScope`

Prevents submission triggers from this view from propagating upward to parent views with submission handlers.

### Type

```ts
submitScope?: boolean
```

### Default

- `false` — submission actions bubble up by default.

### Example

```tsx
<TextField submitScope />
```

This ensures that `onSubmit` handlers defined higher up in the view hierarchy won’t be called when this field is submitted.

## `submitLabel`

Sets the label for the submit button.

### Type

```ts
submitLabel?: "continue" | "return" | "send" | "go" | "search" | "join" | "done" | "next" | "route"
```

### Example

```tsx
<TextField submitLabel="search" />
```



---
url: /guide/View Modifiers/Text View Modifiers.md
---

# Text View Modifiers

The following properties allow you to style and format text-based views, such as `Text` or `Label`, in ways that closely mirror SwiftUI’s built-in modifiers. By customizing these properties, you can control the font, weight, design, spacing, and other typographic attributes of the displayed text.

## Overview

These properties are generally passed to text-related views like `Text` or `Label` components as attributes. For example, you can specify a font size, enable bold formatting, or add an underline with a custom color—all without manually calling multiple modifiers.

```tsx
<Text
  font={{ name: 'SystemFontName', size: 18 }}
  fontWeight="semibold"
  italic
  underline="red"
  lineLimit={2}
  multilineTextAlignment="center"
>
  Stylish Text Here
</Text>
```

In the example above, the text uses a custom font, semibold weight, italic style, a red underline, limits to two lines, and centers the text.

***

## Font Configuration

### `font`

Defines the font and size to apply to the text.

- **Number**: When you provide a number (e.g., `14`), it applies the system font at that size.
- **Preset Font Name** (`Font` type): Use one of the built-in text styles (`"largeTitle"`, `"title"`, `"headline"`, `"subheadline"`, `"body"`, `"callout"`, `"footnote"`, `"caption"`). The system determines the size and weight based on that style.
- **Object with name and size**: Apply a custom font by specifying the `name` and `size`.

```tsx
<Text font={20}>System Font, Size 20</Text>
<Text font="headline">System Headline Font</Text>
<Text font={{ name: "CustomFontName", size: 16 }}>Custom Font</Text>
```

***

### `fontWeight`

Sets the thickness of the font’s stroke. Options range from `"ultraLight"` to `"black"`.

```tsx
<Text fontWeight="bold">Bold Text</Text>
```

***

### `fontWidth`

Specifies the width variant of the font if available. Possible values include `"compressed"`, `"condensed"`, `"expanded"`, and `"standard"`. You can also use a numeric value if supported.

```tsx
<Text fontWidth="condensed">Condensed Width Font</Text>
```

***

### `fontDesign`

Modifies the font design. Options include `"default"`, `"monospaced"`, `"rounded"`, `"serif"`.

```tsx
<Text fontDesign="rounded">Rounded Font Design</Text>
```

***

## Text Formatting

### `minScaleFactor`

A number between 0 and 1 that indicates how much the text can shrink if it doesn’t fit the available space. For example, `0.5` means the text can shrink down to 50% of its original size to fit.

```tsx
<Text minScaleFactor={0.8}>This text shrinks slightly if it doesn't fit.</Text>
```

***

### `bold`

Applies a bold font weight if `true`.

```tsx
<Text bold>This text is bold</Text>
```

***

### `baselineOffset`

Adjusts the text’s vertical position relative to its baseline. Positive values move the text up, negative values move it down.

```tsx
<Text baselineOffset={5}>Text shifted up</Text>
```

***

### `kerning`

Controls the spacing between characters. A positive value increases spacing; a negative value decreases it.

```tsx
<Text kerning={2}>Extra spaced text</Text>
```

***

### `italic`

Applies an italic style if `true`.

```tsx
<Text italic>Italic text</Text>
```

***

### `monospaced`

Forces all child text to use a monospaced variant, if available.

```tsx
<Text monospaced>Monospaced text</Text>
```

***

### `monospacedDigit`

Uses fixed-width digits while leaving other characters as they are. This helps align numbers vertically, useful for tables or timers.

```tsx
<Text monospacedDigit>Digits aligned in monospace 1234</Text>
```

***

## Text Decorations

### `strikethrough`

Applies a strikethrough (line through the text). You can provide a color, or an object specifying a pattern and color.

- **Color only**: `strikethrough="red"`
- **Object**: `strikethrough={{ pattern: 'dash', color: 'blue' }}`

```tsx
<Text strikethrough="gray">Strikethrough text in gray</Text>
<Text strikethrough={{ pattern: 'dot', color: 'red' }}>Dotted red strikethrough</Text>
```

***

### `underline`

Applies an underline in a similar way to `strikethrough`.

- **Color only**: `underline="blue"`
- **Object**: `underline={{ pattern: 'dashDot', color: 'green' }}`

```tsx
<Text underline="blue">Underlined text in blue</Text>
<Text underline={{ pattern: 'dot', color: 'pink' }}>Dotted pink underline</Text>
```

***

## Line & Layout Control

### `lineLimit`

Specifies how many lines of text can display. You can provide:

- A single number for a maximum line limit.
- An object `{ min?: number; max: number; reservesSpace?: boolean }` to specify a minimum and maximum number of lines, and whether the text should reserve space for all those lines even when not used.

```tsx
<Text lineLimit={1}>This text will be truncated if it doesn't fit on one line.</Text>
<Text lineLimit={{ min: 2, max: 4, reservesSpace: true }}>
  This text can display between 2 and 4 lines, and always reserves space for 4 lines, preventing layout shifts.
</Text>
```

***

### `lineSpacing`

Sets the spacing between lines, in pixels.

```tsx
<Text lineSpacing={5}>Line spacing set to 5 pixels</Text>
```

***

### `multilineTextAlignment`

Sets the text alignment for multi-line text: `"leading"`, `"center"`, or `"trailing"`.

```tsx
<Text multilineTextAlignment="center">
  This text is centered across multiple lines.
</Text>
```

***

### `truncationMode`

Specifies how to truncate a line of text when it is too long to fit within the available horizontal space.

#### Type

```ts
type TruncationMode = "head" | "middle" | "tail"
```

#### Description

Defines the position at which the text is truncated:

- `"head"`: Truncates the beginning of the line, preserving the end.

- `"middle"`: Truncates the middle of the line, preserving both the beginning and end.

- `"tail"`: Truncates the end of the line, preserving the beginning.

```tsx
<Text
  truncationMode="middle"
>
  This is a very long piece of text that may be truncated.
</Text>
```

***

### `allowsTightening?: boolean`

Determines whether the system is allowed to reduce the spacing between characters to fit the text within a line when needed.

#### Type

`boolean`

#### Default

`false`

#### Description

When set to true, the system may compress the character spacing to avoid truncation and better fit the content. This is typically used to improve layout responsiveness in constrained environments.

```tsx
<Text
  allowsTightening={true}
>
  Condensed text if necessary
</Text>
```

***

## Summary

By combining these properties, you can fully control the typography of your text-based views without needing multiple wrapper components or modifiers. Whether you need a bold, italic headline font with custom kerning and underline, or a simple body font that truncates after two lines, these options cover a broad range of text styling needs.



---
url: /guide/View Modifiers/Toast.md
---

# Toast

The `toast` view modifier displays a temporary notification message (toast) over the current view.
It is typically used to show short feedback messages such as “Saved successfully,” “Action completed,” or “Network error.”

You can show a simple text message or provide a fully custom view as the toast’s content.
You can also control its duration, position, background color, text color, corner radius, and shadow style.

***

## Type Definition

```ts
toast?: {
  duration?: number | null
  position?: "top" | "bottom" | "center"
  backgroundColor?: Color | null
  textColor?: Color | null
  cornerRadius?: number | null
  shadowRadius?: number | null
} & (
  | { message: string; content?: never }
  | { message?: never; content: VirtualNode }
) & ({
  isPresented: boolean
  onChanged: (isPresented: boolean) => void
} | {
  isPresented: Observable<boolean>
})
```

***

## Property Descriptions

### `isPresented: boolean` and `onChanged(isPresented: boolean): void`

**Description**:
Uses the `isPresented` and `onChanged` properties to control the visibility and behavior of the toast.

**Example**:

```tsx
const [showToast, setShowToast] = useState(false)

toast={{
  isPresented: showToast,
  onChanged: setShowToast,
  message: "Saved successfully"
}}
```

***

### `isPresented: Observable<boolean>`

**Description**:
Uses the `isPresented` observable to control the visibility and behavior of the toast.

**Example**:

```tsx
const showToast = useObservable(false)

toast={{
  isPresented: showToast,
  message: "Saved successfully"
}}
```

***

### `duration?: number | null`

**Description**:
Specifies how long (in seconds) the toast should remain visible.
Defaults to `2` seconds.

**Example**:

```tsx
toast={{
  isPresented: showToast,
  onChanged: setShowToast,
  duration: 3,
  message: "Action completed"
}}
```

***

### `position?: "top" | "bottom" | "center"`

**Description**:
Controls where the toast appears on the screen.

Available values:

- `"top"` – Displays the toast at the top.
- `"bottom"` – Displays the toast at the bottom (default).
- `"center"` – Displays the toast in the center.

**Example**:

```tsx
toast={{
  isPresented: showToast,
  onChanged: setShowToast,
  position: "top",
  message: "New message received"
}}
```

***

### `backgroundColor?: Color | null`

**Description**:
Sets the background color of the toast.

**Example**:

```tsx
toast={{
  isPresented: showToast,
  onChanged: setShowToast,
  backgroundColor: "blue",
  message: "Upload successful"
}}
```

***

### `textColor?: Color | null`

**Description**:
Sets the text color of the toast message.

**Example**:

```tsx
toast={{
  isPresented: showToast,
  onChanged: setShowToast,
  textColor: "white",
  message: "Download failed"
}}
```

***

### `cornerRadius?: number | null`

**Description**:
Sets the corner radius of the toast.
Defaults to `16`.

**Example**:

```tsx
toast={{
  isPresented: showToast,
  onChanged: setShowToast,
  cornerRadius: 8,
  message: "Item added"
}}
```

***

### `shadowRadius?: number | null`

**Description**:
Sets the blur radius of the toast’s shadow.
Defaults to `4`.

**Example**:

```tsx
toast={{
  isPresented: showToast,
  onChanged: setShowToast,
  shadowRadius: 6,
  message: "Success"
}}
```

***

## Displaying a Simple Message

**Example**:

```tsx
function View() {
  const [showToast, setShowToast] = useState(false)

  return (
    <List
      toast={{
        isPresented: showToast,
        onChanged: setShowToast,
        message: "Data saved successfully",
        duration: 2,
        position: "bottom",
        backgroundColor: "green",
        textColor: "white"
      }}
    >
      <Button
        title="Save"
        action={() => setShowToast(true)}
      />
    </List>
  )
}
```

When the button is pressed, a green toast with the message “Data saved successfully” appears at the bottom for 2 seconds.

***

## Displaying Custom Content

**Description**:
Instead of plain text, you can provide a custom `VirtualNode` (view) as the toast content.
This allows you to include icons, multiple text lines, or other view layouts.

**Example**:

```tsx
function View() {
  const [showToast, setShowToast] = useState(false)

  return (
    <List
      toast={{
        isPresented: showToast,
        onChanged: setShowToast,
        content: (
          <HStack spacing={8}>
            <Image systemName="checkmark.circle.fill" />
            <Text foregroundStyle="white">Upload Complete</Text>
          </HStack>
        ),
        backgroundColor: "black",
        cornerRadius: 12
      }}
    >
      <Button
        title="Show Toast"
        action={() => setShowToast(true)}
      />
    </List>
  )
}
```

This example shows a custom toast with an icon and message inside a black rounded background.

***

## Best Practices

1. **Keep state synchronized**
   Always ensure `isPresented` and `onChanged` stay in sync so the toast can be properly dismissed.

2. **Use for lightweight notifications**
   Toasts should only display short, transient messages and should not include complex interactions.

3. **Avoid multiple simultaneous toasts**
   Displaying more than one toast at the same time may confuse users.

4. **Combine with user actions**
   Pair the toast with `Button`, `Form`, or other components to provide quick feedback after an action.



---
url: /guide/View Modifiers/ToolBar View Modifiers.md
---

# ToolBar View Modifiers

The Scripting app supports a collection of view modifiers that control the visibility, appearance, and behavior of system toolbars, including the navigation bar, bottom bar, and tab bar. These modifiers align closely with SwiftUI's APIs and provide declarative control over toolbar configuration at the view level.

***

## Visibility Modifiers

These modifiers control the visibility of various interface bars on a per-view basis.

```ts
bottomBarVisibility?: Visibility
navigationBarVisibility?: Visibility
tabBarVisibility?: Visibility
```

### Enum: `Visibility`

```ts
type Visibility = "automatic" | "hidden" | "visible"
```

- **`automatic`**: Defers visibility decision to the system.
- **`hidden`**: Explicitly hides the bar.
- **`visible`**: Forces the bar to be shown.

***

## Toolbar Title Menu

```ts
toolbarTitleMenu?: VirtualNode
```

Adds a custom menu that appears when tapping the navigation title. This feature is often used to expose contextual actions relevant to the current screen or view hierarchy.

***

## Toolbar Background Style

```ts
toolbarBackground?: ShapeStyle | DynamicShapeStyle | {
  style: ShapeStyle | DynamicShapeStyle
  bars?: ToolbarPlacement[]
}
```

Specifies the preferred background style of toolbars. You can apply a color, material, or gradient background, and optionally limit the scope to specific bars.

### `bars` (optional)

```ts
type ToolbarPlacement = "automatic" | "tabBar" | "bottomBar" | "navigationBar"
```

- Use this field to apply the background style only to specific system bars.
- If `bars` is omitted, the style applies automatically based on system behavior.

***

## Toolbar Background Visibility (iOS 18+)

```ts
toolbarBackgroundVisibility?: Visibility | {
  visibility: Visibility
  bars?: ToolbarPlacement[]
}
```

Controls the visibility of the toolbar background. You can use this to make toolbars appear translucent or completely hidden in specific contexts.

- **`visibility`**: A value of `"automatic"`, `"visible"`, or `"hidden"`.
- **`bars`** (optional): Targeted bars for applying the visibility change. If omitted, all toolbars are affected.

***

## Toolbar Color Scheme

```ts
toolbarColorScheme?: ColorScheme | {
  colorScheme: ColorScheme | null
  bars?: ToolbarPlacement[]
}
```

Specifies the color scheme used by toolbars and their contents.

### Enum: `ColorScheme`

```ts
type ColorScheme = "light" | "dark"
```

- **`light`**: Enforces a light appearance.
- **`dark`**: Enforces a dark appearance.
- **`null`**: Resets to the system default.

The `bars` field limits the color scheme application to selected bars, such as `navigationBar` or `tabBar`.

***

## Toolbar Title Display Mode

```ts
toolbarTitleDisplayMode?: ToolbarTitleDisplayMode
```

Controls how the navigation bar title is displayed.

### Enum: `ToolbarTitleDisplayMode`

```ts
type ToolbarTitleDisplayMode = "automatic" | "large" | "inline" | "inlineLarge"
```

- **`automatic`**: The system chooses between large or inline style based on context.
- **`large`**: Displays a large navigation title when appropriate.
- **`inline`**: Displays the title inline with the navigation bar.
- **`inlineLarge`**: Enables inline layout while preserving large title characteristics (e.g., custom styling).

***

## Usage Notes

- These modifiers can be combined to achieve consistent toolbar customization across different views.
- `toolbarBackground`, `toolbarColorScheme`, and `toolbarBackgroundVisibility` accept scoped configuration via the `bars` field, enabling precise visual adjustments.
- iOS 18 is required for `toolbarBackgroundVisibility`.



---
url: /guide/View Modifiers/blur.md
---

# blur

Applies a Gaussian blur effect to the view.

## Type

```ts
blur?: number | {
  radius: number
  opaque: boolean
}
```

## Example

Simple blur:

```tsx
<Image blur={10} />
```

Custom blur:

```tsx
<Image
  blur={{
    radius: 12,
    opaque: false
  }}
/>
```



---
url: /guide/View Modifiers/border.md
---

# border

The `border` property adds a border around the view using the specified `style` and optional `width`. This allows you to visually outline views with solid colors, gradients, or system materials, and support light/dark mode adaptations.

## Definition

```ts
border?: {
  style: ShapeStyle | DynamicShapeStyle
  width?: number
}
```

- **`style`**: Required. Defines the visual appearance of the border. Accepts `ShapeStyle` or `DynamicShapeStyle`.
- **`width`**: Optional. Specifies the thickness of the border in pixels. Defaults to `1`.

## Usage Examples

### Basic Solid Color Border

```tsx
<Text
  border={{
    style: "systemRed",
    width: 2
  }}
>
  Bordered Text
</Text>
```

### Default Width Border (1px)

```tsx
<HStack
  border={{
    style: "#000000"
  }}
>
  ...
</HStack>
```

### Gradient Border

```tsx
<Text
  border={{
    style: {
      gradient: [
        { color: "red", location: 0 },
        { color: "blue", location: 1 }
      ],
      startPoint: { x: 0, y: 0 },
      endPoint: { x: 1, y: 1 }
    },
    width: 3
  }}
>
  Gradient Border
</Text>
```

### Dynamic Border Style (Light/Dark Mode)

```tsx
<Text
  border={{
    style: {
      light: "gray",
      dark: "white"
    },
    width: 1.5
  }}
>
  Adaptive Border
</Text>
```

## Notes

- The border surrounds the entire view, respecting its layout and frame.
- You can use any `ShapeStyle`, including material blur styles like `"regularMaterial"` or `"ultraThinMaterial"` for a more iOS-native look.



---
url: /guide/View Modifiers/buttonStyle.md
---

# buttonStyle

The `buttonStyle` property allows you to customize the interaction behavior and appearance of buttons within a view hierarchy in your UI.

## Property Declaration

```tsx
buttonStyle?: ButtonStyle;
```

### Description

The `buttonStyle` property applies a specific style to all buttons within a view hierarchy, enabling you to customize their appearance and interaction behavior.

### Accepted Values

The `buttonStyle` property accepts the following string values:

- **`automatic`**: The default button style, adapting to the button’s context.
- **`bordered`**: Applies standard border artwork based on the button’s context.
- **`borderedProminent`**: Applies prominent border artwork for buttons.
- **`borderless`**: A style that doesn’t apply a border.
- **`plain`**: A style that avoids decoration while idle but may indicate the button's pressed, focused, or enabled state visually.

### Default Behavior

If `buttonStyle` is not specified, the default style (`automatic`) is applied based on the button’s context.

## Usage Example

Here’s how you can apply the `buttonStyle` property in your TypeScript code:

### Example: Bordered Button Style

```tsx
<Button
  title="Press Me"
  buttonStyle="bordered"
  action={() => console.log('Button pressed!')}
/>
```

This creates a button with a standard border.

### Example: Borderless Button Style

```tsx
<Button
  title="Press Me"
  buttonStyle="borderless"
  action={() => console.log('Button pressed!')}
/>
```

This creates a button without any border.

### Example: Plain Button Style

```tsx
<Button
  title="Press Me"
  buttonStyle="plain"
  action={() => console.log('Button pressed!')}
/>
```

This creates a button that does not decorate its content while idle but visually indicates interaction states.

## Notes

- The `buttonStyle` property directly maps to SwiftUI’s `buttonStyle` modifier.
- Ensure the string value matches one of the predefined styles listed above to avoid runtime errors.



---
url: /guide/View Modifiers/clipShape.md
---

# clipShape

Clips the view to the specified shape while maintaining its aspect ratio.

### Type

```ts
clipShape?: Shape
```

### Example

```tsx
<Image 
  filePath="path/to/photo.jpg"
  clipShape="Circle"
/>

<Image 
  filePath="path/to/photo.jpg"
  clipShape={
    type: "rect",
    cornerRadius: 12
  }
/>
```



---
url: /guide/View Modifiers/clipped.md
---

# clipped

Clips the view to its rectangular bounds. You can specify whether to apply anti-aliasing for smooth edges.

## Type

```ts
clipped?: boolean
```

## Example

```tsx
<Text
  fixedSize
  frame={{
    width: 175,
    height: 100
  }}
  clipped={true}
  border={{
    style: "gray"
  }}
>This long text string is clipped</Text>
```



---
url: /guide/View Modifiers/colorConvert.md
---

# colorConvert

Inverts the colors in this view. Useful for accessibility or visual emphasis.

### Type

```ts
colorConvert?: boolean
```

### Example

```tsx
<Image
  colorConvert={true}
  imageUrl="https://example.com/imgs/example.jpg"
/>
```



---
url: /guide/View Modifiers/containerRelativeFrame.md
---

# containerRelativeFrame

Positions the view within an invisible frame whose size and position are relative to its nearest container. This modifier is especially useful when working with container views like `ScrollView`, `Grid`, or layout stacks to achieve proportional layout behavior.

## Type

```ts
containerRelativeFrame?: {
  axes: AxisSet
  alignment?: Alignment
  count: never
  span: never
  spacing: never
} | {
  axes: AxisSet
  alignment?: Alignment
  count: number
  span?: number
  spacing: number
}
```

***

## Description

This modifier allows a view to size and position itself based on its container’s dimensions. It is often used to create layouts where the view should occupy a specific fraction of the available space or follow container-aligned scrolling behavior.

***

## Properties

- **`axes`** (`AxisSet`, required)
  The axes (`horizontal`, `vertical`, or `all`) along which to apply the relative sizing and positioning.

- **`alignment`** (`Alignment`, optional, default: `"center"`)
  The alignment of the view within its container-relative frame.

- **`count`** (`number`, optional in second form)
  The number of equal-sized segments to divide the container's space into.

- **`span`** (`number`, optional, default: `1`)
  The number of segments the view should span within the container.

- **`spacing`** (`number`, required in second form)
  The spacing between views laid out using this modifier.

***

## Behavior

There are two configuration modes:

1. **Auto-Sizing Mode**
   The view positions itself within a relative container frame without defining how the space is divided.

   ```tsx
   containerRelativeFrame={{
     axes: 'horizontal',
     alignment: 'leading'
   }}
   ```

2. **Grid-Like Division Mode**
   The container is divided into equal parts, and each view can occupy one or more spans with spacing.

   ```tsx
   containerRelativeFrame={{
     axes: 'horizontal',
     count: 4,
     span: 2,
     spacing: 10
   }}
   ```

***

## Example

```tsx
<HStack>
  <Text
    containerRelativeFrame={{
      axes: 'horizontal',
      count: 3,
      span: 1,
      spacing: 8,
      alignment: 'center'
    }}
  >
    One Third
  </Text>
</HStack>
```

This example places the text in a frame that takes up one-third of the container’s width with spacing of 8 points between items.

***

## See Also

- [Apple Documentation](https://developer.apple.com/documentation/swiftui/view/containerrelativeframe%28_:alignment:%29)
- [Hacking with Swift: containerRelativeFrame](https://www.hackingwithswift.com/quick-start/swiftui/how-to-adjust-the-size-of-a-view-relative-to-its-container)



---
url: /guide/View Modifiers/contentMargins.md
---

# contentMargins

The `contentMargins` modifier configures custom margins around a view’s content. This allows precise control over layout spacing, particularly in scrollable containers such as `ScrollView`, `List`, or `Form`. You can apply margins uniformly or selectively to certain edges and placement contexts.

***

## Type

```ts
contentMargins?: 
  | number
  | EdgeInsets
  | {
      edges?: EdgeSet
      insets: number | EdgeInsets
      placement?: ContentMarginPlacement
    }
```

***

## Parameters

## `insets` (required)

Defines the margin values to apply. You can provide:

- A single number (applied to all specified edges)
- An `EdgeInsets` object for per-edge customization

### Example – uniform insets:

```tsx
<ScrollView
  contentMargins={20}
>
  <Text>Applies 20 points of margin on all sides</Text>
</ScrollView>
```

### Example – edge-specific insets:

```tsx
<ScrollView
  contentMargins={{
    top: 10,
    bottom: 30,
    leading: 16,
    trailing: 16
  }}
>
  <Text>Custom edge insets</Text>
</ScrollView>
```

***

## `edges` (optional)

Defines which edges the insets should apply to. If omitted, all edges are used.

### Type

```ts
type EdgeSet = "top" | "bottom" | "leading" | "trailing" | "vertical" | "horizontal" | "all"
```

### Example – apply to top and bottom only:

```tsx
<ScrollView
  contentMargins={{
    edges: "vertical",
    insets: 12
  }}
>
  <Text>Vertical-only margins</Text>
</ScrollView>
```

***

## `placement` (optional)

Specifies **where** in the layout the margins should be applied. This is especially relevant in scrollable views that have both scrollable content and indicators.

### Type

```ts
type ContentMarginPlacement = "automatic" | "scrollContent" | "scrollIndicators"
```

### Options

| Value                | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| `"automatic"`        | System chooses appropriate placement (default)                |
| `"scrollContent"`    | Margins apply to the main scrollable content only             |
| `"scrollIndicators"` | Margins apply only to scroll indicators (e.g. scrollbar area) |

### Example – margin applied only to scrollable content:

```tsx
<ScrollView
  contentMargins={{
    insets: 24,
    placement: "scrollContent"
  }}
>
  <Text>Scroll content margins only</Text>
</ScrollView>
```

***

## Full Configuration Example

```tsx
<ScrollView
  contentMargins={{
    edges: "horizontal",
    insets: { leading: 20, trailing: 20, top: 0, bottom: 0 },
    placement: "scrollContent"
  }}
>
  <VStack spacing={10}>
    <Text>Margin is applied only to horizontal scroll content area</Text>
  </VStack>
</ScrollView>
```

***

## Summary

| Property    | Description                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `insets`    | Required. Margin values to apply. Can be a number or `EdgeInsets`.                                |
| `edges`     | Optional. Specifies which edges to apply the margins to. Default is `all`.                        |
| `placement` | Optional. Defines where the margins apply (scroll content or indicators). Default is `automatic`. |



---
url: /guide/View Modifiers/contentShape.md
---

# contentShape

The `contentShape` property defines the **interactive or visual boundary shape** of a view's content. This shape can influence how a view behaves during interactions such as tapping, dragging, accessibility focus, hover effects, and previews. It is commonly used to fine-tune the **hit-testing area** or provide a custom **visual outline** for advanced interaction features.

This is especially useful for views like `Button`, `ListRow`, or custom views where the tappable or interactive area should differ from the visual content.

***

## Definition

```ts
contentShape?: Shape | {
  kind: ContentShapeKinds
  shape: Shape
}
```

## Supported Formats

### 1. Simple Shape

You can specify a standalone `Shape` to define the default content shape for all purposes.

```tsx
contentShape="circle"
```

This applies to all interactions (tap, accessibility, drag, etc.) unless overridden.

***

### 2. Typed Shape by Purpose

You can define a content shape with a specific **interaction kind**, using the following structure:

```ts
{
  kind: ContentShapeKinds
  shape: Shape
}
```

This lets you control the content shape behavior in specific contexts (e.g., drag previews or accessibility hit-testing).

***

## Supported `ContentShapeKinds`

| Kind                   | Description                                                                |
| ---------------------- | -------------------------------------------------------------------------- |
| `"interaction"`        | Defines the hit-testing area (taps, clicks, gestures)                      |
| `"dragPreview"`        | Used for shaping drag-and-drop previews                                    |
| `"contextMenuPreview"` | Used when displaying a context menu preview                                |
| `"hoverEffect"`        | Defines the area for hover interactions (e.g., when using pointer devices) |
| `"accessibility"`      | Defines the shape used for accessibility focus, highlighting, and ordering |

***

## Examples

### Default shape for all interactions

```tsx
<Button
  title="Click Me"
  contentShape="capsule"
  action={() => {

  }}
/>
```

### Custom shape for accessibility only

```tsx
<Button
  title="Accessible Button"
  action={() => {

  }}
  contentShape={{
    kind: "accessibility",
    shape: {
      type: "rect",
      cornerRadius: 12
    }
  }}
/>
```

### Custom interaction area using an ellipse

```tsx
<Text
  contentShape={{
    kind: "interaction",
    shape: "ellipse"
  }}
>
  Custom Tap Area
</Text>
```

***

## Notes

- `contentShape` does not alter how the view **looks**, only how it **responds** to interactions or previews.
- When using custom shapes, ensure the shape aligns appropriately with the view’s layout frame.
- For symbol-based views (e.g., buttons with icons), defining a `contentShape` can make tap targets more accessible.



---
url: /guide/View Modifiers/contentTransition.md
---

# contentTransition

The `contentTransition` modifier specifies a transition animation to apply when the **content within a single view changes**. Unlike view-level transitions (such as `.transition(.move)`), `contentTransition` animates **changes in content** rather than the insertion or removal of the view itself.

This is particularly useful when updating the contents of views like `Text`, `Image`, or symbol-based `Image(systemName: ...)`, providing smooth visual feedback on state or data changes.

***

## Type

```ts
contentTransition?: ContentTransition
```

***

## Supported `ContentTransition` Values

| Value | Description |
| ----- | ----------- |

### `"identity"`

- No animation is applied to the content change.
- The view updates instantly with no visual transition.

```tsx
<Text contentTransition="identity">{value}</Text>
```

***

### `"interpolate"`

- The view attempts to interpolate between the old and new content where appropriate.
- Best used with animatable types such as `Color`, `Shape`, or `View` interpolations.

```tsx
<Rectangle fill={color} contentTransition="interpolate" />
```

***

### `"opacity"`

- Applies a fade effect: old content fades out while new content fades in.
- Works well with general-purpose views.

```tsx
<Text contentTransition="opacity">{message}</Text>
```

***

### `"numericText"`

- Specialized transition for `Text` views displaying numbers.
- Animates character changes in a way that emphasizes numerical progression.

```tsx
<Text contentTransition="numericText">{score}</Text>
```

***

### `"numericTextCountsUp"`

- Similar to `"numericText"`, but optimized for numeric **increments**.
- Intended for counter-like transitions.

```tsx
<Text contentTransition="numericTextCountsUp">{level}</Text>
```

***

### `"numericTextCountsDown"`

- Optimized for numeric **decrements**.
- Useful for countdowns or decreasing counters.

```tsx
<Text contentTransition="numericTextCountsDown">{remainingTime}</Text>
```

***

### `"symbolEffect"`

- Applies a default symbol animation when a **symbol image** changes.
- Only affects symbol-based images (`Image(systemName: ...)`) and has no effect on other views.

```tsx
<Image
  systemName={isOn ? "lightbulb.fill" : "lightbulb"}
  contentTransition="symbolEffect"
/>
```

***

### `"symbolEffectAutomatic"`

- Uses platform-adaptive symbol animation depending on context.
- Typically provides fade, scale, or morphing effects between symbols.

```tsx
<Image
  systemName={icon}
  contentTransition="symbolEffectAutomatic"
/>
```

***

### `"symbolEffectReplace"`

- Replaces the layers of one symbol image with another.
- Provides a more visually fluid symbol swap than abrupt replacement.

```tsx
<Image
  systemName={currentSymbol}
  contentTransition="symbolEffectReplace"
/>
```

***

### `"symbolEffectAppear"` / `"symbolEffectDisappear"`

- Explicit transitions for symbol insertion and removal, respectively.
- These may be combined with visibility-based state changes.

```tsx
{isShown
  ? <Image
    systemName="checkmark"
    contentTransition="symbolEffectAppear"
  />
  : null}
```

***

### `"symbolEffectScale"`

- Scales the symbol up or down during the content change.
- Works well for symbol emphasis or status feedback.

```tsx
<Image
  systemName={statusIcon}
  contentTransition="symbolEffectScale"
/>
```

***

## Summary

| Transition              | Best Used For                                |
| ----------------------- | -------------------------------------------- |
| `identity`              | No animation at all                          |
| `interpolate`           | Animatable content (e.g. color, shape)       |
| `opacity`               | General-purpose fade-in/fade-out transitions |
| `numericText`           | Text views displaying numbers                |
| `numericTextCountsUp`   | Animated numeric increases                   |
| `numericTextCountsDown` | Animated numeric decreases                   |
| `symbolEffect`          | Transition between two SF Symbols            |
| `symbolEffectAutomatic` | Platform-determined symbol transitions       |
| `symbolEffectReplace`   | Replacing symbol layers smoothly             |
| `symbolEffectAppear`    | Animate symbol appearing                     |
| `symbolEffectDisappear` | Animate symbol disappearing                  |
| `symbolEffectScale`     | Scaling effect on symbol changes             |

***

This modifier is ideal for providing subtle, performant feedback in data-driven UI updates while maintaining view identity and layout stability. It is particularly effective in dashboards, counters, toggles, icon transitions, and numerically dynamic interfaces.



---
url: /guide/View Modifiers/contextMenu.md
---

# contextMenu

The `contextMenu` property allows a view to present a contextual menu when the user performs a long-press or right-click gesture. This behavior is consistent with the system-provided context menus in iOS and iPadOS. Developers can define menu items and optionally include a preview view that appears alongside the menu.

***

## Definition

```ts
contextMenu?: {
  menuItems: VirtualNode
  preview?: VirtualNode
}
```

***

## Properties

- **`menuItems`**: A `VirtualNode` that defines the contents of the context menu. This typically consists of one or more `Button` components grouped within a `Group` element.

- **`preview`** (optional): A `VirtualNode` representing a preview view. This preview is displayed adjacent to the context menu, giving users a visual hint of the item or action being contextualized.

***

## Behavior

When applied to a view, the `contextMenu` modifier activates when the user performs a long press (on touch devices) or right-click (on pointer-based devices). The system then displays the defined `menuItems`, and if provided, renders the `preview` view.

***

## Example

```tsx
function View() {
  return <Text
    contextMenu={{
      menuItems: <Group>
        <Button
          title="Add"
          action={() => {
            // Handle add action
          }}
        />
        <Button
          title="Delete"
          role="destructive"
          action={() => {
            // Handle delete action
          }}
        />
      </Group>
    }}
  >
    Long Press to Open Context Menu
  </Text>
}
```

In this example, the `Text` view is enhanced with a context menu that appears on long press. The menu presents two actions: "Add" and "Delete", with the "Delete" button styled as destructive.

***

## Notes

- The context menu is automatically styled by the system and adapts to platform conventions.
- If the `preview` property is not provided, only the menu items will be displayed.
- The `menuItems` should be structured within a `Group` to ensure proper layout and interaction handling.



---
url: /guide/View Modifiers/controlGroupStyle.md
---

# controlGroupStyle

The `controlGroupStyle` property allows you to set the visual and interactive style for control groups within your view, reflecting the look and feel found in SwiftUI. By defining a `ControlGroupStyle`, you can influence how related controls—such as buttons, toggles, or other interactable elements—are grouped and presented to the user.

## Overview

In SwiftUI, you might set a `controlGroupStyle` like this:

```swift
ControlGroup {
    Button("Action 1") { ... }
    Button("Action 2") { ... }
}
.controlGroupStyle(.navigation)
```

**In Scripting (TypeScript/TSX),** you can achieve similar styling by using the `controlGroupStyle` property on a view that contains control group components:

```tsx
<ControlGroup
  title="Text Formatting"
  controlGroupStyle="navigation"
>
  <Button title="Bold" action={() => console.log('Bold pressed')} />
  <Button title="Italic" action={() => console.log('Italic pressed')} />
  <Button title="Underline" action={() => console.log('Underline pressed')} />
</ControlGroup>
```

## Available Styles

You can assign any of the following string values to `controlGroupStyle` to define how the control group is displayed:

- **`automatic`**: Let the system decide an appropriate style based on the context.
- **`compactMenu`**: Presents the controls as a compact menu when tapped, or as a submenu if nested within a larger menu.
- **`menu`**: Displays the controls in a menu format when pressed, or as a submenu when nested.
- **`navigation`**: Styles the controls to fit within a navigation context, often aligning with platform-specific navigation styles.
- **`palette`**: Presents the controls in a palette-like grouping, often showing multiple actions at once.

## Example Usage

### Setting the `controlGroupStyle` to a Menu

```tsx
<ControlGroup
  controlGroupStyle="menu"
>
  {/* Your content here, possibly a set of controls */}
</ControlGroup>
```

In this example, the controls will appear as a menu. Tapping or interacting with the group will present the items in a menu-like interface.

### Using a Palette Style

```tsx
<ControlGroup
  title="Text Formatting"
  controlGroupStyle="palette"
>
  <Button title="Bold" action={() => console.log('Bold pressed')} />
  <Button title="Italic" action={() => console.log('Italic pressed')} />
  <Button title="Underline" action={() => console.log('Underline pressed')} />
</ControlGroup>
```

Here, the controls may be displayed together in a palette, which could show multiple styling options together for quick selection.

### Automatic Style

If you’re unsure which style is best, or want to let the system pick a suitable style, you can choose `automatic`:

```tsx
<ControlGroup
  title="Media Controls"
  controlGroupStyle="automatic"
>
  <Button title="Action A" action={() => console.log('Action A')} />
  <Button title="Action B" action={() => console.log('Action B')} />
</ControlGroup>
```

## Summary

By setting `controlGroupStyle`, you guide how your set of controls are displayed and interacted with. Whether you choose a `menu`, `compactMenu`, `navigation`, `palette`, or rely on `automatic`, this property helps ensure that your script’s controls feel naturally integrated with the platform’s UI conventions and user expectations.



---
url: /guide/View Modifiers/datePickerStyle.md
---

# datePickerStyle

The `datePickerStyle` property allows you to customize the appearance and interaction of the `DatePicker` view in your UI.

## Property Declaration

```tsx
DatePickerStyle = "automatic" | "compact" | "graphical" | "wheel" | "field" | "stepperField"
DatePickerComponents = "hourAndMinute" | "date" | "hourMinuteAndSecond"
```

***

## `DatePickerStyle` Values

The `DatePickerStyle` property accepts the following string values to define the appearance and interaction:

- **`automatic`**: The default style for date pickers.
- **`compact`**: Displays the date picker components in a compact, textual format.
- **`graphical`**: Displays the date picker as an interactive calendar or clock.
- **`wheel`**: Displays the date picker components as columns in a scrollable wheel.
- **`field`** _(macOS only)_: Displays the components in an editable field.
- **`stepperField`** _(macOS only)_: Displays the components in an editable field with an adjoining stepper to increment or decrement the selected component.

***

## `DatePickerComponents` Values

The `displayedComponents` property specifies which components of the date are shown and editable. Accepted values are:

- **`date`**: Displays the day, month, and year based on the locale.
- **`hourAndMinute`**: Displays the hour and minute components based on the locale.
- **`hourMinuteAndSecond`** _(watchOS only)_: Displays the hour, minute, and second components based on the locale.

***

## Usage Example

### Example 1: Graphical Date Picker

```tsx
function View() {
  const [date, setDate] = useState(Date.now())

  return <DatePicker
    title="Select Date"
    value={date}
    onChanged={setDate}
    startDate={Date.now() - 31556926000} // 1 year ago
    endDate={Date.now() + 31556926000}  // 1 year ahead
    displayedComponents={["date"]}
    datePickerStyle="graphical"
  />
}
```

This creates a graphical date picker for selecting a date.

***

### Example 2: Compact Date Picker with Time Selection

```tsx
function View() {
  const [time, setTime] = useState(Date.now())
  return <DatePicker
    title="Select Time"
    value={time}
    onChanged={setTime}
    displayedComponents={["hourAndMinute"]}
    datePickerStyle="compact"
  />
}
```

This creates a compact date picker for selecting the hour and minute.

***

### Example 3: Wheel Date Picker

```tsx
function View() {
  const [date, setDate] = useState(Date.now())
  return <DatePicker
    title="Choose Date and Time"
    value={date}
    onChanged={setDate}
    displayedComponents={["hourAndMinute", "date"]}
    datePickerStyle="wheel"
  />
}
```

This creates a date picker with a scrollable wheel for date and time selection.

***

## Notes

- The `DatePickerStyle` property maps directly to SwiftUI’s `datePickerStyle` modifier.
- Ensure that the `displayedComponents` and `datePickerStyle` values are compatible with the target platform to avoid runtime errors.
- For macOS-specific styles (`field` and `stepperField`), ensure the app is running on macOS.

With `DatePickerStyle`, you can create versatile date pickers to suit your app’s design and functional requirements.



---
url: /guide/View Modifiers/disabled.md
---

# disabled

Disables user interactions for this view and its children. Visual elements typically appear dimmed.

## Type

```ts
disabled?: boolean
```

## Example

```tsx
<Button
 title="Submit" 
 disabled={submitDisabled}
 action={submit}
/>
```



---
url: /guide/View Modifiers/fixedSize.md
---

# fixedSize

Fixes the size of a view to its ideal dimensions, preventing the view from being compressed or expanded beyond its natural size.

## Type

```ts
fixedSize?: boolean | {
  horizontal: boolean
  vertical: boolean
}
```

## Overview

The `fixedSize` modifier tells the layout system to size a view according to its ideal content size, rather than allowing it to stretch or shrink to fit the parent’s constraints. This is especially useful when you want text or other content to fully display without being truncated, or to prevent the view from being resized to fill available space.

This modifier behaves similarly to SwiftUI’s [`fixedSize()`](https://developer.apple.com/documentation/swiftui/view/fixedsize%28%29).

## Usage

You can apply `fixedSize` in one of two ways:

### 1. Boolean Form

```tsx
<Text fixedSize>
  This text won't be truncated or compressed.
</Text>
```

This is equivalent to:

```tsx
<Text fixedSize={{ horizontal: true, vertical: true }}>
  This text won't be truncated or compressed.
</Text>
```

### 2. Object Form

Use this to fix only the horizontal or vertical dimensions:

```tsx
<Text fixedSize={{ horizontal: true, vertical: false }}>
  This text won't compress horizontally, but can grow or shrink vertically.
</Text>
```

## Behavior

- `horizontal: true`: Prevents the view from compressing or expanding horizontally. Ideal for avoiding text truncation.
- `vertical: true`: Prevents the view from compressing or expanding vertically.
- When both are `false`, the modifier has no effect.
- If a parent container attempts to resize the view, the fixed dimensions take precedence, and the view will remain at its ideal size in those axes.

## Example

```tsx
<VStack>
  <Text fixedSize>
    Long text that should wrap and never be truncated or compressed.
  </Text>
  <Text fixedSize={{ horizontal: true, vertical: false }}>
    This text can grow vertically but keeps its natural width.
  </Text>
</VStack>
```

## Notes

- Common use cases include making sure `Text` views don’t get truncated or `HStack`/`VStack` layouts don’t force views to resize.
- When using this modifier, be mindful of the parent layout, as it may cause content to overflow if not handled properly.



---
url: /guide/View Modifiers/flipsForRightToLeftLayoutDirection.md
---

# flipsForRightToLeftLayoutDirection

Determines whether the view should horizontally mirror its contents when the system layout direction is right-to-left (RTL), such as when the user interface is set to a right-to-left language (e.g., Arabic or Hebrew).

## Type

`flipsForRightToLeftLayoutDirection?: boolean`

## Description

When set to `true`, this modifier causes the view to flip its horizontal layout to match the RTL direction, aligning the visual appearance with the reading flow of right-to-left languages. This is especially useful for custom views or components that require explicit mirroring behavior in internationalized layouts.

When set to `false`, the view maintains its left-to-right layout regardless of the system layout direction.

## Default

`false` (The view does not flip by default unless explicitly configured.)

## Example

```tsx
<Image
  filePath="path/to/icon.png"
  flipsForRightToLeftLayoutDirection={true}
/>
```

In this example, the image will automatically flip its horizontal orientation when displayed in a right-to-left layout environment.



---
url: /guide/View Modifiers/foregroundStyle & background.md
---

# foregroundStyle & background

These two modifiers—`foregroundStyle` and `background`—allow you to customize the visual styling of view content and its background, supporting a wide range of styles including solid colors, gradients, materials, and dynamic appearances for light/dark mode.

***

## `foregroundStyle`

### Definition

```ts
foregroundStyle?: ShapeStyle | DynamicShapeStyle | {
  primary: ShapeStyle | DynamicShapeStyle
  secondary: ShapeStyle | DynamicShapeStyle
  tertiary?: ShapeStyle | DynamicShapeStyle
}
```

Sets the style of a view’s foreground content, such as the color of text, shapes, or symbols. You can pass a single style or a layered style object (`primary`, `secondary`, `tertiary`) to support multi-layered rendering, such as in SF Symbols or decorated text.

### Usage Examples

#### Basic Foreground Color

```tsx
<Text foregroundStyle="white">
  Hello World!
</Text>
```

#### Foreground with Dynamic Colors (Light/Dark Mode)

```tsx
<Text
  foregroundStyle={{
    light: "black",
    dark: "white"
  }}
>
  Adaptive Text
</Text>
```

#### Multi-layer Foreground Style

```tsx
<Text
  foregroundStyle={{
    primary: "red",
    secondary: "orange",
    tertiary: "yellow"
  }}
>
  Layered Style
</Text>
```

> Use layered styles primarily with views that support multistage rendering like system icons or stylized text.

***

## `background`

### Definition

```ts
background?: 
  | ShapeStyle 
  | DynamicShapeStyle 
  | { style: ShapeStyle | DynamicShapeStyle, shape: Shape }
  | VirtualNode 
  | { content: VirtualNode, alignment: Alignment }
```

Sets the background of a view. You can apply simple colors or gradients, or supply a custom shape or view as the background.

### Background Variants

1. **ShapeStyle**: Use a solid color, gradient, or material.
2. **DynamicShapeStyle**: Automatically switches styles between light and dark mode.
3. **Shape with Fill Style**: Use a shape (e.g., `RoundedRectangle`) with a style applied to it.
4. **VirtualNode**: Use another component as the background.
5. **Custom Alignment**: Align a background content explicitly behind the main view.

### Usage Examples

#### Solid Color Background

```tsx
<Text background="systemBlue">
  Hello
</Text>
```

#### Gradient Background

```tsx
<Text
  background={{
    gradient: [
      { color: "purple", location: 0 },
      { color: "blue", location: 1 }
    ],
    startPoint: { x: 0, y: 0 },
    endPoint: { x: 1, y: 1 }
  }}
>
  Gradient Background
</Text>
```

#### Dynamic Background

```tsx
<Text
  background={{
    light: "white",
    dark: "black"
  }}
>
  Mode-aware Background
</Text>
```

#### Background with a Shape

```tsx
<Text
  background={
    <RoundedRectangle fill="systemBlue" />
  }
>
  Hello World!
</Text>
```

#### Background with Custom Alignment

```tsx
<Text
  background={{
    content: <Image filePath="path/to/background.jpg" />,
    alignment: "center"
  }}
>
  Overlayed Text
</Text>
```

***

## Related Types

- **`ShapeStyle`**
  A visual style that defines how a foreground or background is rendered—this can be a color, gradient, or material. Supports `"red"`, `"systemBlue"`, `"#FF0000"`, `rgba(...)`, and gradient definitions.

- **`DynamicShapeStyle`**
  A light/dark mode–aware style with separate definitions for each appearance. The system automatically applies the appropriate style based on the current UI mode.

- **`VirtualNode`**
  A component used as a background, such as `<Image />`, `<RoundedRectangle />`, or any view that returns a `JSX.Element`.

- **`Shape`**
  A predefined shape such as `RoundedRectangle`, `Circle`, or `Capsule`, used for styled background shapes.

***

## Summary

| Property          | Purpose                             | Value Types                                            |
| ----------------- | ----------------------------------- | ------------------------------------------------------ |
| `foregroundStyle` | Styles text/icons/foreground shapes | `ShapeStyle`, `DynamicShapeStyle`, layered object      |
| `background`      | Renders a styled background         | `ShapeStyle`, `DynamicShapeStyle`, shape + style, view |

These properties give you fine-grained control over visual styling and are essential for building rich, adaptive interfaces in the Scripting app.



---
url: /guide/View Modifiers/formStyle.md
---

# formStyle

The `FormStyle` type defines how a form’s content is visually arranged and presented. By choosing a particular style, you can influence the layout of labels, controls, and sections within your form, providing a more organized and intuitive user experience.

## Overview

A `Form` view can contain various controls (such as text fields, toggles, pickers, etc.) arranged in rows. The `FormStyle` determines how these rows are displayed—whether labels and values line up in columns or if controls are grouped within visually distinct sections.

## Available Styles

- **`automatic`**:
  Let the system choose the most appropriate style based on context. This is often a good default choice when you don’t have specific layout requirements.

- **`columns`**:
  Displays a non-scrolling form where labels appear in a trailing-aligned column on the left, and their associated values or controls appear in a leading-aligned column on the right. This style is well-suited for forms where alignment and quick scanning of label-value pairs is important.

- **`grouped`**:
  Organizes the form into visually grouped sections. Each row typically has a leading-aligned label and a trailing-aligned control. This style helps segment related input fields into distinct categories, making long or complex forms easier to navigate.

## Example Usage

**Columns Style**

```tsx
<Form formStyle="columns">
  <TextField
    title="First Name"
    value={firstName} 
    onChanged={setFirstName}
  />
  <TextField 
    title="Last Name" 
    value={lastName} 
    onChanged={setLastName} 
  />
  <Toggle 
    title="Subscribe" 
    value={subscribe} 
    onChanged={setSubscribe} 
  />
</Form>
```

In this layout, the labels (e.g., “First Name”, “Last Name”, “Subscribe”) appear in a neat column on one side, with their corresponding input fields or toggles aligned next to them.

**Grouped Style**

```tsx
<Form formStyle="grouped">
  <Section 
    header={
      <Text>Personal Information</Text>
    }>
    <TextField 
      title="Email" 
      value={email} 
      onChanged={setEmail} 
    />
    <TextField 
      title="Phone" 
      value={phone} 
      onChanged={setPhone} 
    />
  </Section>
  <Section 
    header={
      <Text>Settings</Text>
    }>
    <Toggle 
      title="Enable Notifications" 
      value={notificationsEnabled} 
      onChanged={setNotificationsEnabled} 
    />
    <Toggle 
      title="Auto-Update" 
      value={autoUpdate} 
      onChanged={setAutoUpdate} 
    />
  </Section>
</Form>
```

Here, fields are grouped into sections like “Personal Information” and “Settings.” Each section’s rows present a clear label and control pair, helping users understand the logical grouping of inputs.

**Automatic Style**

```tsx
<Form formStyle="automatic">
  <TextField 
    title="Username" 
    value={username} 
    onChanged={setUsername} 
  />
  <SecureField 
    title="Password" 
    value={password} 
    onChanged={setPassword} 
  />
</Form>
```

With `automatic`, the system picks a default style. This is a convenient option for simple forms or when you want to allow the system’s default styling to adapt to different contexts or platforms.

## Summary

- Use **`columns`** for a structured, two-column layout that makes scanning labels and values straightforward.
- Choose **`grouped`** for visually distinct sections that help users navigate more complex forms.
- Select **`automatic`** to let the system handle layout decisions, making it ideal for simpler or more adaptable interfaces.

By setting the `formStyle` on a `Form`, you can fine-tune the presentation to best suit your form’s complexity and user needs.



---
url: /guide/View Modifiers/frame.md
---

# frame

The `frame` property defines the size and alignment of a view. You can specify it in one of two formats:

***

#### 1. Fixed Width and Height

```ts
frame?: {
  width?: number
  height?: number
  alignment?: Alignment
}
```

This format allows you to specify a fixed width and/or height for the view, as well as how it is aligned within that frame.

##### Example

```tsx
<VStack
  frame={{
    width: 100,
    height: 100,
    alignment: 'center'
  }}
>
  <Text>Fixed size</Text>
</VStack>
```

***

#### 2. Flexible Frame Constraints

```ts
frame?: {
  alignment?: Alignment
  minWidth?: number
  minHeight?: number
  maxWidth?: number | 'infinity'
  maxHeight?: number | 'infinity'
  idealWidth?: number | 'infinity'
  idealHeight?: number | 'infinity'
}
```

This format gives more control over layout by specifying minimum, maximum, and ideal dimensions for the frame. These values can be numeric or `'infinity'`, which instructs the view to expand to fill available space.

##### Example

```tsx
<HStack
  frame={{
    minWidth: 100,
    maxWidth: 'infinity',
    minHeight: 50,
    idealHeight: 100,
    alignment: 'leading'
  }}
>
  <Text>Expandable width</Text>
</HStack>
```

***

## Alignment

The `alignment` property determines how the view is positioned within the frame. Common alignment values include:

- `'center'`
- `'top'`
- `'bottom'`
- `'leading'`
- `'trailing'`
- `'topLeading'`
- `'topTrailing'`
- `'bottomLeading'`
- `'bottomTrailing'`

> **Note**: Alignment only affects layout when the frame size exceeds the view’s natural size.

##### Example

```tsx
<Text
  frame={{
    width: 200,
    height: 100,
    alignment: 'bottomTrailing'
  }}
>
  Aligned Text
</Text>
```

***

## Best Practices

- Use the fixed `width` and `height` format when you want precise dimensions.
- Use the flexible format with `min` / `max` / `ideal` values when working with responsive layouts.
- Avoid specifying both `width`/`height` and `minWidth`/`maxWidth`, etc., in the same frame object — choose one format to avoid conflicts.

***

## Summary

The `frame` property in `CommonViewProps` allows fine-grained control over layout sizing and alignment, closely mirroring SwiftUI’s native `frame` modifier. Use it to design clean and adaptable interfaces across different screen sizes.



---
url: /guide/View Modifiers/gaugeStyle.md
---

# gaugeStyle

The `GaugeStyle` type defines how a gauge is visually represented. By selecting a particular style, you control whether the gauge appears as a ring, a bar, or uses markers to indicate the current value. Some styles only apply on specific platforms (notably watchOS), while others are more broadly available.

## Overview

A `Gauge` component visually represents a value within a specified range. For example, you might use it to show a battery level, download progress, or temperature reading. By combining a `Gauge` with a chosen `GaugeStyle`, you can tailor the gauge’s appearance to match your app’s design language or functional requirements.

**Key points:**

- Choose a style that best suits the data you’re representing—rings for circular contexts, bars for linear contexts.
- Some styles show a marker at the current value; others show a filled segment or partial capacity.
- Certain styles are only available on watchOS, as noted below.

## Available Styles

- **`automatic`**:\
  Relies on the system’s default style for the current platform and context. This is a good starting point if you don’t have a strong preference.

- **`accessoryCircular`**:\
  Shows an open ring with a marker that points to the current value along the ring’s circumference. Great for showing levels or percentages in a compact, circular form.

- **`accessoryCircularCapacity`**:\
  Similar to `accessoryCircular` but shows a closed ring partially filled in up to the current value. This works well to indicate capacity levels, such as a storage meter.

- **`circular`** _(Only available on watchOS)_:\
  Like `accessoryCircular`, this displays an open ring with a marker. Useful for watchOS complications or similar small form factor displays.

- **`linearCapacity`**:\
  Displays a horizontal bar that fills from the leading edge to the trailing edge as the value increases. Ideal for progress bars, battery meters, or memory usage indicators.

- **`accessoryLinear`**:\
  A linear gauge that shows a marker along a bar, indicating the exact point of the current value rather than a filled segment.

- **`accessoryLinearCapacity`**:\
  Combines aspects of `linearCapacity` with the `accessoryLinear` style. It shows a filled bar segment that grows with the value, suitable for showing capacity or progress out of a whole.

- **`linear`** _(Only available on watchOS)_:\
  Similar to `accessoryLinear` but watchOS-specific. It shows a marker along a bar for the current value.

## Example Usage

```tsx
<Gauge
  value={0.7}
  min={0}
  max={1}
  label={<Text>Battery</Text>}
  currentValueLabel={<Text>70%</Text>}
  minValueLabel={<Text>0%</Text>}
  maxValueLabel={<Text>100%</Text>}
  gaugeStyle="accessoryCircularCapacity"
/>
```

In this example, the gauge shows a partially filled circular ring indicating that the battery level is at 70%.

Switching to a linear capacity style:

```tsx
<Gauge
  value={0.7}
  min={0}
  max={1}
  label={<Text>Download Progress</Text>}
  currentValueLabel={<Text>70%</Text>}
  gaugeStyle="linearCapacity"
/>
```

This would show a horizontal bar filled from left to right up to 70% of its length.

If you prefer a style that shows a marker instead of a fill, you could do:

```tsx
<Gauge
  value={0.7}
  min={0}
  max={1}
  label={<Text>Temperature</Text>}
  currentValueLabel={<Text>Warm</Text>}
  gaugeStyle="accessoryCircular"
/>
```

This style displays an open ring with a marker pointing to the current value (70%) rather than a filled segment.

## When to Use Each Style

- **`circular` and `accessoryCircular` styles:**\
  Ideal for data that you intuitively represent in a circular format, such as a timer, speedometer-like reading, or capacity shown as a ring.

- **`linear` and `accessoryLinear` styles:**\
  Best for data that’s inherently linear, like progress bars, completion percentages, or levels that are typically read left to right.

- **`Capacity` styles:**\
  Perfect for scenarios where you want a filled segment to indicate how “full” or “complete” something is, such as battery life, storage space used, or loading progress.

- **`automatic`:**\
  Let the system decide and adapt style based on context. Good as a default choice if you’re unsure.

## Summary

By setting the `gaugeStyle` on a `Gauge`, you have full control over the visual representation of your data. Whether you want a circular ring, a linear bar, a simple marker, or a filled capacity indicator, `GaugeStyle` provides flexible options to present information in a way that feels both intuitive and aesthetically pleasing.



---
url: /guide/View Modifiers/hidden.md
---

# hidden

If `true`, the view is invisible and does not respond to interactions. However, it still occupies layout space in the view hierarchy.

## Type

```ts
hidden?: boolean
```

## Example

```tsx
<Text hidden={true}>This text is hidden</Text>
```



---
url: /guide/View Modifiers/labelsHidden.md
---

# labelsHidden

Hides the labels of controls (e.g. `Picker`, `DatePicker`) contained within the view. The controls remain visible and functional.

## Type

```ts
labelsHidden?: boolean
```

## Example

```tsx
<Picker
  title="Picker"
  labelsHidden={true}
  value={value}
  onChanged={onChanged}
>
  <Text tag={0}>Option 1</Text>
  <Text tag={1}>Option 2</Text>
</Picker>
```



---
url: /guide/View Modifiers/layoutDirectionBehavior.md
---

# layoutDirectionBehavior

Controls how a view responds to left-to-right and right-to-left layout directions.

## Type

```ts
layoutDirectionBehavior?: "fixed" | "mirrors" | {
  mirrors: "leftToRight" | "rightToLeft"
}
```

## Values

| Value                        | Description                                                             |
| ---------------------------- | ----------------------------------------------------------------------- |
| `"fixed"`                    | Keeps the view fixed instead of mirroring for layout direction changes. |
| `"mirrors"`                  | Mirrors the view using the current layout direction.                    |
| `{ mirrors: "leftToRight" }` | Mirrors as if the layout direction is left-to-right.                    |
| `{ mirrors: "rightToLeft" }` | Mirrors as if the layout direction is right-to-left.                    |

## Example

```tsx
<Image
  systemName="arrow.forward"
  layoutDirectionBehavior="mirrors"
/>
```

## Availability

`layoutDirectionBehavior` requires iOS 18.0 or later.



---
url: /guide/View Modifiers/layoutPriority.md
---

# layoutPriority

`layoutPriority` determines how much priority a view has when its parent layout allocates space among multiple child views, especially when space is constrained.

When multiple child views compete for space within a layout, those with a higher layout priority will be allocated more space, while those with a lower priority may be compressed or truncated.

## Parameter

- `layoutPriority` _(optional)_
  A number that defines the layout priority of the view.
  Higher values indicate higher priority. The default is `0`. Decimal values are supported.

## Usage Example

Suppose you want to create a horizontal stack of text views and ensure that a title is prioritized over a subtitle when space is limited:

```tsx
<HStack>
  <Text layoutPriority={1}>Title</Text>
  <Text>Subtitle (can be compressed)</Text>
</HStack>
```

In this example, the `"Title"` text has a higher layout priority, so it will be allocated space first. If space runs out, the `"Subtitle"` will be truncated or compressed before the title.

## Notes

- `layoutPriority` only has an effect when the parent layout needs to resolve space conflicts among its children.
- If all child views have the same priority, space is distributed evenly.
- Useful in layout containers like `HStack`, `VStack`, and `ZStack` where views might compete for limited space.

***

The `layoutPriority` modifier is a powerful tool for controlling how views behave in constrained layouts. By adjusting priority values, you can create more adaptive and user-friendly interfaces.



---
url: /guide/View Modifiers/listStyle.md
---

# listStyle

The `listStyle` property allows you to customize the behavior and appearance of a list in your UI when using the `List` view.

## Property Declaration

```tsx
listStyle?: ListStyle;
```

### Description

The `listStyle` property defines the visual style of a list, allowing you to choose from various predefined list styles.

### Accepted Values

The `listStyle` property accepts the following string values:

- **`automatic`**: Uses the platform’s default behavior and appearance for a list.
- **`bordered`**: Displays a list with standard borders.
- **`carousel`**: Applies a carousel-like appearance to the list.
- **`elliptical`**: Gives the list an elliptical style.
- **`grouped`**: Displays the list in a grouped format.
- **`inset`**: Applies an inset appearance to the list.
- **`insetGroup`**: Combines inset and grouped styles for the list.
- **`plain`**: Displays the list in a plain style without additional decorations.
- **`sidebar`**: Renders the list in a sidebar-like appearance.

### Default Behavior

If `listStyle` is not specified, the default style is determined by the platform.

## Usage Example

Here’s how you can apply the `listStyle` property in your TypeScript code:

### Example: Plain List Style

```tsx
<List
  listStyle="plain"
>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
  <Text>Item 3</Text>
</List>
```

This creates a list with a plain style.

### Example: Grouped List Style

```tsx
<List
  listStyle="grouped"
>
  <Section header={
    <Text>Fruits</Text>
  }>
    <Text>Apple</Text>
    <Text>Banana</Text>
  </Section>
  <Section header={
    <Text>Vegetables</Text>
  }>
    <Text>Carrot</Text>
    <Text>Broccoli</Text>
  </Section>
</List>
```

This creates a grouped list with sections.

### Example: Sidebar List Style

```tsx
<List
  listStyle="sidebar"
>
  <Text>Home</Text>
  <Text>Settings</Text>
  <Text>Profile</Text>
</List>
```

This creates a sidebar-style list.

## Notes

- The `listStyle` property directly maps to SwiftUI’s `listStyle` modifier.
- Make sure to match the string value with one of the predefined styles listed above to avoid runtime errors.



---
url: /guide/View Modifiers/mask.md
---

# mask

The `mask` modifier clips the visual rendering of a view using the **alpha channel** of another view. Only the parts of the original view that align with the opaque (non-transparent) portions of the mask remain visible; the rest is hidden.

This is commonly used to apply custom shapes, spotlight effects, or partial reveals.

***

## Type

```ts
mask?: VirtualNode | {
  alignment: Alignment
  content: VirtualNode
}
```

***

## Usage

## 1. Simple Form

Apply a mask view directly. The mask is centered on the base view by default.

```tsx
<Image
  filePath="path/to/photo.png"
  frame={{ width: 100, height: 100 }}
  mask={<Circle />}
 />
```

In this example, the image is clipped to a circular shape using a `Circle` as the mask. Only the circular portion of the image is visible.

***

## 2. Object Form (with Alignment)

Use this form when you want to position the mask relative to the base view.

### Structure:

```ts
{
  alignment: Alignment
  content: VirtualNode
}
```

### `Alignment` values:

- `"top"` | `"bottom"` | `"leading"` | `"trailing"`
- `"topLeading"` | `"topTrailing"` | `"bottomLeading"` | `"bottomTrailing"`
- `"center"`

### Example – apply a top-aligned rectangular mask:

```tsx
<Rectangle
  fill="blue"
  frame={{ width: 100, height: 100 }}
  mask={{
    alignment: "top",
    content: <Rectangle frame={{ width: 100, height: 50 }} />
  }}
/>
```

Only the top half of the blue rectangle will be visible, defined by the opaque rectangle used as the mask.

***

## Behavior

- The **mask view’s opacity** determines the visibility of the base view.

  - Opaque areas (alpha = 1) show the base view.
  - Transparent areas (alpha = 0) hide it.
- The mask does **not affect layout**, only how the content is rendered.
- Use `frame={{ width, height }}` on both base and mask views to ensure proper alignment and coverage.

***

## Common Use Cases

- Cropping images into non-rectangular shapes (e.g., circle, capsule)
- Creating spotlight or reveal effects
- Masking decorative or semantic content

***

## Summary

| Field                | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `mask` (VirtualNode) | A view that defines the clipping mask; centered by default |
| `alignment`          | Optional. Aligns the mask view relative to the base view   |
| `content`            | The actual masking content used to clip rendering          |



---
url: /guide/View Modifiers/matchedGeometryEffect.md
---

# matchedGeometryEffect

`matchedGeometryEffect` establishes a **geometric relationship between different views**, allowing them to animate smoothly when transitioning across:

- Different layouts
- Different containers
- Different conditional render states
- Different size and position configurations

It corresponds to SwiftUI’s `matchedGeometryEffect` and is a **component-level geometry animation system**, independent of navigation.

***

## 1. API Definition

```ts
matchedGeometryEffect?: {
  id: string | number
  namespace: NamespaceID
  properties?: MatchedGeometryProperties
  anchor?: Point | KeywordPoint
  isSource?: boolean
}
```

```ts
type MatchedGeometryProperties = "frame" | "position" | "size"
```

***

## 2. Core Purpose

The core purpose of `matchedGeometryEffect` is:

> To make two views that represent the same logical element share geometry information across different layouts, producing a continuous animated transition instead of a visual jump.

This solves issues such as:

- Sudden jumps when a view moves between containers
- Abrupt size changes when expanding a card
- Layout discontinuity between list and detail views
- Teleport-like behavior of tab indicators

***

## 3. Parameter Details

### 3.1 `id` — Geometry Matching Identifier

```ts
id: string | number
```

- Identifies which views belong to the same geometry group.
- Only views with the **same `id` inside the same `namespace`** will match.
- Typically derived from:

  - Model identifiers
  - Index values
  - Stable business keys

Rules:

- The `id` must remain stable during animation.
- One `id` can have **only one `isSource = true` at any moment**.

***

### 3.2 `namespace` — Geometry Namespace

```ts
namespace: NamespaceID
```

- Defines the animation scope.
- Even if two views share the same `id`, they **will not animate** unless the `namespace` is also the same.
- Must be created and injected via `NamespaceReader`.

Rules:

- Source and target **must use the exact same namespace instance**.
- Cross-namespace matching is not allowed.

***

### 3.3 `properties` — Geometry Properties to Match

```ts
properties?: "frame" | "position" | "size"
```

Default:

```ts
properties = "frame"
```

Meaning:

| Value        | Description                      |
| ------------ | -------------------------------- |
| `"frame"`    | Matches both position and size   |
| `"position"` | Matches only the center position |
| `"size"`     | Matches only width and height    |

Guidelines:

- Use `"frame"` for natural transitions
- Use `"position"` for indicators and sliding highlights
- Use `"size"` for zooming and expansion effects

***

### 3.4 `anchor` — Animation Anchor Point

```ts
anchor?: Point | KeywordPoint
```

Default:

```ts
anchor = "center"
```

Controls how the geometry alignment is calculated during animation.

Common values:

- `"center"`
- `"topLeading"`
- `"topTrailing"`
- `"bottomLeading"`
- `"bottomTrailing"`

Usage examples:

- Expanding a card from the top-left
- Zooming an avatar from the top-right
- Sliding a panel upward from the bottom

***

### 3.5 `isSource` — Geometry Data Provider

```ts
isSource?: boolean
```

Default:

```ts
isSource = true
```

Meaning:

| Value   | Behavior                              |
| ------- | ------------------------------------- |
| `true`  | This view provides geometry data      |
| `false` | This view receives geometry animation |

Standard pattern:

- Original view → `isSource: true`
- Target view → `isSource: false`

If omitted:

- The first appearing view becomes the source by default.

***

## 4. Minimal Working Example (Position + Size Matching)

This example shows a circle moving and scaling smoothly between two containers.

```tsx
const expanded = useObservable(false)

<NamespaceReader>
  {namespace => (
    <VStack spacing={40}>
      <Button
        title="Toggle"
        onTapGesture={() => {
          expanded.setValue(!expanded.value)
        }}
      />

      <ZStack
        frame={{ width: 300, height: 200 }}
        background="systemGray6"
      >
        {!expanded.value && (
          <Circle
            fill="systemOrange"
            frame={{ width: 60, height: 60 }}
            matchedGeometryEffect={{
              id: "circle",
              namespace
            }}
          />
        )}
      </ZStack>

      <ZStack
        frame={{ width: 300, height: 300 }}
        background="systemGray4"
      >
        {expanded.value && (
          <Circle
            fill="systemOrange"
            frame={{ width: 150, height: 150 }}
            matchedGeometryEffect={{
              id: "circle",
              namespace,
              isSource: false
            }}
          />
        )}
      </ZStack>
    </VStack>
  )}
</NamespaceReader>
```

### Behavior

- The same logical circle:

  - Moves downward
  - Grows in size
  - Maintains continuous animation
- No visual teleportation occurs

***

## 5. Position-Only Matching (Tab Indicator)

```tsx
const selected = useObservable(0)

<NamespaceReader>
  {namespace => (
    <HStack spacing={24}>
      <Text
        onTapGesture={() => selected.setValue(0)}
        matchedGeometryEffect={{
          id: "indicator",
          namespace,
          properties: "position",
          isSource: selected.value === 0
        }}
      >
        Tab 1
      </Text>

      <Text
        onTapGesture={() => selected.setValue(1)}
        matchedGeometryEffect={{
          id: "indicator",
          namespace,
          properties: "position",
          isSource: selected.value === 1
        }}
      >
        Tab 2
      </Text>
    </HStack>
  )}
</NamespaceReader>
```

Used for:

- Tab selection indicators
- Sliding highlights
- Moving selection backgrounds

***

## 6. Size-Only Matching (Zoom Animation)

```tsx
const expanded = useObservable(false)

<NamespaceReader>
  {namespace => (
    <ZStack>
      <Circle
        fill="systemBlue"
        frame={{
          width: expanded.value ? 200 : 80,
          height: expanded.value ? 200 : 80
        }}
        matchedGeometryEffect={{
          id: "avatar",
          namespace,
          properties: "size"
        }}
        onTapGesture={() => {
          expanded.setValue(!expanded.value)
        }}
      />
    </ZStack>
  )}
</NamespaceReader>
```

Suitable for:

- Avatar zooming
- Card expansion
- Press feedback animations

***

## 7. Multi-Element Matching (Card → Detail View)

```tsx
const showDetail = useObservable(false)

<NamespaceReader>
  {namespace => (
    <ZStack>
      {!showDetail.value && (
        <VStack spacing={16}>
          <Image
            source="cover"
            matchedGeometryEffect={{
              id: "card.image",
              namespace
            }}
            onTapGesture={() => {
              showDetail.setValue(true)
            }}
          />

          <Text
            matchedGeometryEffect={{
              id: "card.title",
              namespace
            }}
          >
            Card Title
          </Text>
        </VStack>
      )}

      {showDetail.value && (
        <VStack spacing={24}>
          <Image
            source="cover"
            frame={{ width: 300, height: 200 }}
            matchedGeometryEffect={{
              id: "card.image",
              namespace,
              isSource: false
            }}
          />

          <Text
            font="largeTitle"
            matchedGeometryEffect={{
              id: "card.title",
              namespace,
              isSource: false
            }}
          >
            Card Title
          </Text>
        </VStack>
      )}
    </ZStack>
  )}
</NamespaceReader>
```

Effect:

- Image and title animate together
- Transition from compact card to expanded detail layout
- No navigation system required

***

## 8. Key Usage Rules

1. **`namespace` must be identical**
2. **`id` must be identical**
3. At any time:

   - One `id` → only one `isSource = true`
4. Default behavior:

   ```ts
   properties = "frame"
   anchor = "center"
   isSource = true
   ```
5. Source and target must switch within the same render cycle
6. If both views are marked as `isSource: true`, results are undefined
7. Live Activity and Widget environments do not fully support matched geometry animations

***

## 9. Suitable Use Cases

Recommended:

- Tab indicators
- Card-to-detail transitions
- Image zoom previews
- List selection animations
- Split-view selection synchronization

Not recommended:

- High-frequency updating lists
- Large grids with many simultaneous matches
- Real-time chart rendering



---
url: /guide/View Modifiers/matchedTransitionSource.md
---

# matchedTransitionSource

`matchedTransitionSource` marks a view as the **geometric source of a navigation transition**. It allows a view to act as the starting point of a page-level transition animation, such as a **zoom (Hero-style) transition**.

This API corresponds to SwiftUI’s `matchedTransitionSource` and is intended **only for navigation transitions**, not for component-level layout animations.

Typical use cases include:

- Image → Image detail zoom
- Card → Detail page Hero animation
- Avatar → Profile page transition

***

## 1. API Definition

```ts
/**
 * Identifies this view as the source of a navigation transition, such as a zoom transition.
 * @available iOS 18.0+
 */
matchedTransitionSource?: {
  id: string | number
  namespace: NamespaceID
}
```

***

## 2. Core Purpose

The core purpose of `matchedTransitionSource` is:

> To define **which exact view** should be used as the **starting geometry** of a navigation transition.

It solves the following problems:

- Eliminates the visual disconnect between a tapped view and the destination page
- Prevents “disappear → new page appears” jump cuts
- Enables spatial continuity between the source element and the destination layout

With this API, the system can:

- Read the source view’s real on-screen frame
- Compute the destination page’s final layout frame
- Animate smoothly between the two

***

## 3. Parameter Details

### 3.1 `id` — Transition Source Identifier

```ts
id: string | number
```

Meaning:

- Uniquely identifies **which view is the transition source**
- Must **exactly match** the destination page’s `navigationTransition.sourceID`

Rules:

- Within the same `namespace`, `id` must be unique
- Per navigation transition:

  - Only **one** `matchedTransitionSource` may match the `sourceID`

***

### 3.2 `namespace` — Transition Namespace

```ts
namespace: NamespaceID
```

Meaning:

- Defines the **transition animation scope**
- Created and injected by `NamespaceReader`

Rules:

1. The source view and the destination page **must use the exact same namespace**
2. Different namespaces will **never** produce a matched transition
3. Even if `id` is the same, a different namespace disables the animation

***

## 4. How matchedTransitionSource Works

A successful navigation zoom transition requires **all four conditions** to be satisfied:

1. A view defines `matchedTransitionSource`
2. The destination page defines `navigationTransition`
3. `navigationTransition.sourceID === matchedTransitionSource.id`
4. Both sides use the **same `namespace`**

Only when all conditions are met will the system:

- Capture the source view’s:

  - Frame
  - Position
  - Scale
- Capture the destination layout’s final frame
- Compute:

  - Translation path
  - Scale ratio
- Perform the full transition animation

***

## 5. Minimal Working Example: Image → Detail Zoom

```tsx
<NamespaceReader>
  {namespace => (
    <NavigationLink
      destination={
        <DetailPage
          navigationTransition={{
            type: "zoom",
            namespace,
            sourceID: "cover"
          }}
        />
      }
    >
      <Image
        source="cover"
        frame={{
          width: 120,
          height: 160
        }}
        matchedTransitionSource={{
          id: "cover",
          namespace
        }}
      />
    </NavigationLink>
  )}
</NamespaceReader>
```

### Resulting Behavior

1. The user taps the image
2. Navigation begins
3. The destination page does not appear instantly
4. Instead, it **zooms smoothly from the tapped image’s position and size**

***

## 6. Card → Detail Hero Transition Example

```tsx
<NamespaceReader>
  {namespace => (
    <NavigationLink
      destination={
        <DetailPage
          navigationTransition={{
            type: "zoom",
            namespace,
            sourceID: "card-1"
          }}
        />
      }
    >
      <VStack
        frame={{
          width: 280,
          height: 180
        }}
        background="systemGray6"
        matchedTransitionSource={{
          id: "card-1",
          namespace
        }}
      >
        <Text>Card Title</Text>
      </VStack>
    </NavigationLink>
  )}
</NamespaceReader>
```

Effect:

- The entire card becomes the transition origin
- The detail page expands naturally from that card
- Produces a classic Hero-style animation

***

## 7. Difference Between matchedTransitionSource and matchedGeometryEffect

| Aspect                      | matchedTransitionSource | matchedGeometryEffect  |
| --------------------------- | ----------------------- | ---------------------- |
| Scope                       | Page-level navigation   | Component-level layout |
| Requires Navigation         | Yes                     | No                     |
| Multiple elements supported | No                      | Yes                    |
| Needs `sourceID`            | Yes                     | No                     |
| Geometry property control   | No                      | Yes                    |
| Internal layout animation   | No                      | Yes                    |

Summary:

- `matchedTransitionSource`: controls **where a page transition starts**
- `matchedGeometryEffect`: controls **how layout changes animate inside views**

***

## 8. Common Issues and Debug Checklist

### 8.1 Transition Does Not Trigger

Check:

- Does `sourceID` exactly match `matchedTransitionSource.id`?
- Are both using the same `namespace` instance?
- Is the navigation actually triggered via `NavigationLink`?

***

### 8.2 Wrong Direction or Scaling Artifacts

Common causes:

- The source view uses:

  - `scaleEffect`
  - `offset`
  - `rotation`
- Or is wrapped by:

  - `clipShape`
  - `mask`
  - `containerShape`

These affect how the system reads the real geometry frame.

***

### 8.3 Multiple Sources with the Same ID

Incorrect:

- Multiple views share the same `id`
- All define `matchedTransitionSource`

Result:

- The system cannot determine the true source
- The transition becomes undefined or fails

***

## 9. Platform and Environment Limitations

1. `matchedTransitionSource` works only with:

   - Navigation-based transitions
2. It is **not supported or is limited** in:

   - Widgets
   - Live Activities
3. It should not be used for:

   - Tab switching
   - Collapsing/expanding menus
   - Component state animations

Use `matchedGeometryEffect` for those cases.

***

## 10. Recommended Use Cases

Highly suitable:

- Image → full-screen preview
- Article cover → reading page
- Product card → product detail
- Avatar → profile page
- Large card → immersive detail view

Not suitable:

- High-frequency UI state changes
- Dense grid transitions
- Real-time updating interfaces



---
url: /guide/View Modifiers/offset.md
---

# offset

Moves the view from its original position by the specified x and y distances.

## Type

```ts
offset?: { x: number, y: number }
```

## Example

```tsx
<Text 
  offset={{
    x: 10,
    y: -20
  }}
>Offset Text</Text>
```



---
url: /guide/View Modifiers/onDrag and onDrop View Modifiers.md
---

# onDrag and onDrop View Modifiers

Scripting provides a Drag & Drop API closely aligned with the SwiftUI drag-and-drop interaction model. It enables views to act as drag sources, drop destinations, or both, supporting intra-app and cross-app drag-and-drop scenarios.

The API is composed of three core parts:

- **onDrag**: Declares a view as a drag source
- **onDrop**: Declares a view as a drop destination
- **DropInfo / ItemProvider / UTType**: Context objects describing drag content and state

Drag and drop is a system-controlled interaction. Certain APIs are only valid during specific callbacks. These constraints are explicitly documented below and must be respected.

***

## Core Types

### DropInfo

`DropInfo` represents the real-time state of a drag operation relative to a specific drop target view.
It is only valid within `onDrop` callbacks.

### Properties

#### location: Point

- The current drag location
- Expressed in the **local coordinate space of the drop view**
- Commonly used for:

  - Insertion indicators
  - Reordering logic
  - Position-based highlighting

### Methods

#### hasItemsConforming(types: UTType\[]): boolean

- Indicates whether at least one dragged item conforms to any of the specified UTTypes
- Commonly used in:

  - `validateDrop`
  - `dropEntered`
  - `dropUpdated`
- This method performs capability checks only and does not load data

#### itemProviders(types: UTType\[]): ItemProvider\[]

- Returns all `ItemProvider` instances conforming to the specified UTTypes
- **Only valid inside the `performDrop` callback**
- After `performDrop` returns, access to the dragged data is revoked by the system

> Critical constraint
> You must **start loading the contents** of the returned `ItemProvider` instances **within the scope of `performDrop`**.
> Loading may complete later, but it must be initiated synchronously before `performDrop` returns.

***

## DropOperation

`DropOperation` describes the action a drop target intends to perform.

Available values:

- `"copy"`
  Copies the dragged data (default and most common)

- `"move"`
  Moves the data instead of copying it (typically internal to the app)

- `"cancel"`
  Cancels the drag operation and transfers no data

- `"forbidden"`
  Explicitly disallows the drop at the current location

`DropOperation` is usually returned from `dropUpdated` to dynamically control the drag behavior.

***

## DragDropProps

`DragDropProps` defines the optional drag-and-drop capabilities that a view may adopt.

***

## onDrag

### Purpose

Marks the view as a **drag source**, allowing the user to initiate a drag operation from it.

### Definition

```ts
onDrag?: {
  data: () => ItemProvider
  preview: VirtualNode
}
```

### Parameters

#### data

```ts
data: () => ItemProvider
```

- Returns an `ItemProvider` describing the dragged data
- Supports text, images, files, URLs, and custom types
- Invoked each time a drag begins

Recommended practice:
Create a new `ItemProvider` instance for each drag operation. Do not reuse instances.

#### preview

```ts
preview: VirtualNode
```

- A view used as the drag preview
- Rendered by the system as a floating representation during dragging
- Centered over the source view by default

***

## onDrop

### Purpose

Marks the view as a **drop destination** and provides fine-grained control over validation, interaction updates, and data handling.

### Definition

```ts
onDrop?: {
  types: UTType[]
  validateDrop?: (info: DropInfo) => boolean
  dropEntered?: (info: DropInfo) => void
  dropUpdated?: (info: DropInfo) => DropOperation | null
  dropExited?: (info: DropInfo) => void
  performDrop: (info: DropInfo) => boolean
}
```

***

### onDrop.types

```ts
types: UTType[]
```

- Declares the content types this view can accept
- If the dragged content does not conform to any listed type:

  - The drop target does not activate
  - `validateDrop` is not called
  - Visual feedback is not shown

***

### validateDrop

```ts
validateDrop?: (info: DropInfo) => boolean
```

- Determines whether the drop operation should be allowed to begin
- Returning `false` immediately rejects the drag
- Common use cases:

  - Checking item count
  - Enforcing application state constraints

Default behavior: always returns `true`

***

### dropEntered

```ts
dropEntered?: (info: DropInfo) => void
```

- Called when the drag enters the drop target area
- Typically used to:

  - Show highlight states
  - Display insertion placeholders
  - Trigger animations

***

### dropUpdated

```ts
dropUpdated?: (info: DropInfo) => DropOperation | null
```

- Called repeatedly as the drag moves within the drop target
- Used to dynamically specify the intended `DropOperation`

Return value behavior:

- Returning a `DropOperation` updates the active operation
- Returning `null`:

  - Reuses the last valid operation
  - Falls back to `"copy"` if none was previously returned

***

### dropExited

```ts
dropExited?: (info: DropInfo) => void
```

- Called when the drag leaves the drop target area
- Commonly used to clear highlight or placeholder UI

***

### performDrop

```ts
performDrop: (info: DropInfo) => boolean
```

- **The most critical callback**
- Indicates that the user has released the drag and data access is permitted
- Return value:

  - `true` if the drop was successfully handled
  - `false` if the drop failed

#### Mandatory constraints

- Within this method, you must:

  - Call `info.itemProviders(...)`
  - Immediately initiate data loading from the returned providers
- You must not:

  - Store `ItemProvider` references for later use
  - Defer loading to unrelated callbacks

These constraints are enforced by the operating system for security reasons.

***

## Typical Interaction Flow

1. The user initiates a drag from an `onDrag` view
2. The system checks compatibility using `onDrop.types`
3. `validateDrop` is invoked
4. The drag enters the drop target → `dropEntered`
5. The drag moves within the target → repeated `dropUpdated`
6. The drag leaves the target → `dropExited`
7. The user releases the drag → `performDrop`
8. Data is loaded and processed

***

## Design Guidelines and Best Practices

- Declare UTTypes as narrowly as possible
- Use `"forbidden"` in `dropUpdated` to explicitly block invalid drops
- Perform heavy parsing or processing only after `ItemProvider` loading completes
- Prefer system-standard UTTypes (text, image, file, URL) for cross-app drag-and-drop



---
url: /guide/View Modifiers/onDropContent.md
---

# onDropContent

`onDropContent` is a view modifier provided by Scripting that allows a view to act as a **drop target**, receiving files, images, or text dragged in from other applications.

***

## Overview

With `onDropContent`, you can:

- Receive drag-and-drop content from other apps
- Restrict acceptable content using UTType identifiers
- Track whether a drag operation is hovering over the view
- Start loading dropped content through `ItemProvider`
- Establish persistent access to security-scoped files when needed

***

## Modifier Definition

```ts
onDropContent?: {
  types: UTType[]
  isTarget: {
    value: boolean
    onChanged: (value: boolean) => void
  } | Observable<boolean>
  perform: (attachments: ItemProvider[]) => boolean
}
```

***

## Parameters

### types

Specifies the list of content types that the view can accept, expressed as UTType strings.

If the drag operation does not contain any of the specified types:

- The view does not activate as a drop target
- `isTarget` does not update
- `perform` is not called

Example:

```ts
types: ["public.image", "public.movie"]
```

***

### isTarget

Indicates whether the drag operation is currently hovering over the view.

- The value is `true` when the drag enters the view’s area
- The value is `false` when the drag exits the area

Two forms are supported:

- Binding object form

  ```ts
  {
    value: boolean
    onChanged: (value: boolean) => void
  }
  ```

- Observable form

  ```ts
  Observable<boolean>
  ```

The observable form works well with `useObservable` and provides a more concise reactive binding.

***

### perform

Called when content matching the specified `types` is dropped onto the view.

```ts
perform: (attachments: ItemProvider[]) => boolean
```

- `attachments` is an array of `ItemProvider`
- Each `ItemProvider` represents one dropped item
- The return value indicates whether the drop was successfully handled

Return value semantics:

- Return `true` to indicate the drop was accepted
- Return `false` to indicate the drop was not handled

***

## Execution Rules for perform

The following rules must be followed inside `perform`:

- Loading of `ItemProvider` contents must be **started synchronously within the execution scope of `perform`**
- Asynchronous completion is allowed using `Promise` or `then`
- Loading must not be initiated later from a different callback or event
- If `perform` returns `false`, the system treats the drop as unhandled

Reasoning:

- Dropped content is protected by system security rules
- Access to the dropped payload is only valid while `perform` is executing
- If loading does not begin within this scope, the content may no longer be accessible

***

## Working with ItemProvider

Within `perform`, you should inspect each `ItemProvider` and start loading based on its capabilities.

Typical steps include:

- Checking type conformance using `hasItemConforming`
- Selecting an appropriate loading method
- Handling files, images, or text accordingly

***

## Example Usage

```tsx
const isTarget = useObservable(false)

return <VStack
  onDropContent={{
    types: ["public.image", "public.movie"],
    isTarget: isTarget,
    perform: (attachments) => {
      const images: UIImage[] = []
      const videos: string[] = []

      let found = false

      for (const attachment of attachments) {
        if (attachment.hasItemConforming("public.png")) {
          found = true
          attachment.loadUIImage().then(image => {
            if (image != null) {
              images.push(image)
            }
          })
        } else if (attachment.hasItemConforming("public.movie")) {
          found = true
          attachment.loadFilePath("public.movie").then(filePath => {
            if (filePath != null) {
              // Create a bookmark for the security-scoped file
              FileManager.addFileBookmark(filePath)
              videos.push(filePath)
            }
          })
        }
      }

      return found
    }
  }}
>
  ...
</VStack>
```

***

## Security-Scoped File Access

File paths obtained via `onDropContent` are typically **security-scoped resources**.

These paths may become invalid when:

- `perform` returns
- The app restarts
- The script lifecycle ends

To retain long-term access, you should create a file bookmark as soon as the path is obtained.

***

## FileManager.addFileBookmark

```ts
FileManager.addFileBookmark(path: string, name?: string): string | null
```

Description:

- Creates a security-scoped bookmark for a file or folder
- Intended for paths obtained via APIs such as `Photos` or `onDropContent`
- Returns the bookmark name, or `null` if creation fails

Example:

```ts
const bookmarkName = FileManager.addFileBookmark(filePath)
```

***

## FileManager.removeFileBookmark

```ts
FileManager.removeFileBookmark(name: string): boolean
```

Description:

- Removes a previously created file bookmark
- Should be called when access to the file is no longer needed
- Returns whether the removal was successful

Example:

```ts
FileManager.removeFileBookmark(bookmarkName)
```

***

## Usage Recommendations

- Specify `types` as precisely as possible
- Use `perform` only to start loading, not to wait for results
- Load images and lightweight data as objects when appropriate
- Prefer file paths for large resources such as videos or documents
- Create bookmarks for files that require long-term access
- Remove bookmarks when the associated files are no longer needed



---
url: /guide/View Modifiers/opacity.md
---

# opacity

Sets the transparency level of a view. A value of `0` makes the view completely transparent (invisible), while `1` means fully opaque.

## Type

```ts
opacity?: number
```

## Example

```tsx
<Text opacity={0.5}>Semi-transparent Text</Text>
```



---
url: /guide/View Modifiers/overlay.md
---

# overlay

The `overlay` modifier places a view on top of the modified view, creating a layered composition. This is useful for adding decorations, badges, shadows, visual indicators, or interactive elements such as buttons or loading spinners.

***

## Type

```ts
overlay?: VirtualNode | {
  alignment: Alignment
  content: VirtualNode
}
```

***

## Parameters

### 1. `VirtualNode` (Simple Form)

Directly specifies the overlay view to be layered on top of the current view. The overlay is aligned to the center by default.

```tsx
<Image
  imageUrl="https://example.com/avatar.png"
  overlay={<Circle fill="black" opacity={0.2} />}
/>
```

### 2. Object Form with Alignment

Provides both the overlay content and a custom alignment for positioning.

#### Structure

```ts
{
  alignment: Alignment
  content: VirtualNode
}
```

#### `Alignment` options:

- `"top"` | `"bottom"` | `"leading"` | `"trailing"`
- `"topLeading"` | `"topTrailing"`
- `"bottomLeading"` | `"bottomTrailing"`
- `"center"`

#### Example – badge overlay in top trailing corner:

```tsx
<Image
  imageUrl="https://example.com/avatar.png"
  overlay={{
    alignment: "topTrailing",
    content: <Circle 
      fill="red"
      frame={{
        width: 10,
        height: 10
      }}
   />
  }}
/>
```

***

## Behavior

- The overlay is drawn **in front** of the base view.
- The overlay respects the bounds of the base view unless clipped.
- Layout and size of the base view are unaffected by the overlay.

***

## Common Use Cases

- Adding notification badges
- Overlaying loading indicators
- Adding visual highlights or status icons
- Layering semi-transparent effects

***

## Example – Overlay with Text

```tsx
<Rectangle
  fill="blue"
  frame={{
    width: 100,
    height: 100
  }}
  overlay={{
    alignment: "center",
    content: <Text foregroundColor="white">Hello</Text>
  }}
/>
```

This renders a white "Hello" text centered on top of a blue rectangle.

***

## Summary

| Parameter     | Description                                             |
| ------------- | ------------------------------------------------------- |
| `VirtualNode` | A view to layer on top (centered by default)            |
| `alignment`   | (Optional) Position of the overlay within the base view |
| `content`     | The overlay content to display                          |



---
url: /guide/View Modifiers/padding.md
---

# padding

The `padding` property adds space around the content of a view, mirroring the behavior of SwiftUI’s `padding` modifier. It helps separate a view from surrounding elements and improve layout clarity.

## Definition

```ts
padding?: true | number | {
  horizontal?: number | true
  vertical?: number | true
  leading?: number | true
  trailing?: number | true
  top?: number | true
  bottom?: number | true
}
```

## Supported Formats

You can specify padding in multiple ways:

***

### 1. Default Padding

```ts
padding: true
```

Applies the system default padding on all sides.

#### Example:

```tsx
<Text padding={true}>
  Default Padding
</Text>
```

***

### 2. Uniform Padding

```ts
padding: 8
```

Applies the same number of points of padding to all edges.

#### Example:

```tsx
<VStack padding={12}>
  <Text>Even Padding</Text>
</VStack>
```

***

### 3. Directional Padding Object

Specify individual edges or edge groups.

```ts
padding: {
  horizontal: 16,
  vertical: 8
}
```

#### Supported Keys:

| Key          | Description                               |
| ------------ | ----------------------------------------- |
| `horizontal` | Padding for both `leading` and `trailing` |
| `vertical`   | Padding for both `top` and `bottom`       |
| `leading`    | Padding on the leading edge (LTR: left)   |
| `trailing`   | Padding on the trailing edge (LTR: right) |
| `top`        | Padding on the top                        |
| `bottom`     | Padding on the bottom                     |

Each value can be a number or `true`. When set to `true`, it applies the default system padding for that edge.

#### Example:

```tsx
<Text
  padding={{
    top: 10,
    bottom: 10,
    horizontal: 16
  }}
>
  Custom Edge Padding
</Text>
```

#### Example with `true` for specific edges:

```tsx
<Text
  padding={{
    top: true,
    horizontal: 12
  }}
>
  Mixed Padding
</Text>
```

***

## Notes

- Padding does **not** affect the size of the view’s content directly, but adjusts the space around it.
- Combining directional keys allows for precise control over layout spacing.
- `horizontal`/`vertical` and `leading`/`trailing` can be combined. The more specific key (like `leading`) overrides the group key (like `horizontal`) if both are provided.



---
url: /guide/View Modifiers/pickerStyle.md
---

# pickerStyle

The `pickerStyle` property allows you to customize the appearance and behavior of pickers within a view hierarchy in your UI.

## Property Declaration

```tsx
pickerStyle?: PickerStyle;
```

### Description

The `pickerStyle` property sets the visual style of pickers, enabling you to adapt them to the context and desired user experience.

### Accepted Values

The `pickerStyle` property accepts the following string values:

- **`automatic`**: The default picker style, adapting to the picker’s context.
- **`inline`**: Displays each option inline with other views in the current container.
- **`menu`**: Presents the options as a menu when the user presses a button or as a submenu when nested within a larger menu.
- **`navigationLink`**: Represents a picker style where the options are presented by pushing a List-style picker view via a navigation link.
- **`palette`**: Presents the options as a row of compact elements.
- **`segmented`**: Displays the options in a segmented control.
- **`wheel`**: Displays the options in a scrollable wheel, showing the selected option and a few neighboring options.

### Default Behavior

If `pickerStyle` is not specified, the default style (`automatic`) is applied based on the picker’s context.

## Usage Example

Here’s how you can apply the `pickerStyle` property in your TypeScript code:

### Example: Inline Picker Style

```tsx
function View() {
  const [
    value,
    setValue
  ] = useState(0)

  return <Picker
    title="Picker"
    pickerStyle="inline"
    value={value}
    onChanged={(value) => {
      setValue(value)
      console.log('Selected:', value)
    }}
  >
    <Text tag={0}>Option 1</Text>
    <Text tag={1}>Option 2</Text>
    <Text tag={2}>Option 3</Text>
  </Picker>
}
```

This creates a picker with an inline style.

### Example: Segmented Picker Style

```tsx
function View() {
  const [
    value,
    setValue
  ] = useState(0)

  return <Picker
    title="Picker"
    pickerStyle="segmented"
    value={value}
    onChanged={(value) => {
      setValue(value)
      console.log('Selected:', value)
    }}
  >
    <Text tag={0}>Option 1</Text>
    <Text tag={1}>Option 2</Text>
    <Text tag={2}>Option 3</Text>
  </Picker>
}
```

This creates a picker displayed in a segmented control.

### Example: Wheel Picker Style

```tsx
function View() {
  const [
    value,
    setValue
  ] = useState(0)

  return <Picker
    title="Picker"
    pickerStyle="wheel"
    value={value}
    onChanged={(value) => {
      setValue(value)
      console.log('Selected:', value)
    }}
  >
    <Text tag={0}>Option 1</Text>
    <Text tag={1}>Option 2</Text>
    <Text tag={2}>Option 3</Text>
  </Picker>
}
```

This creates a picker with a scrollable wheel style.

## Notes

- The `pickerStyle` property directly maps to SwiftUI’s `pickerStyle` modifier.
- Ensure the string value matches one of the predefined styles listed above to avoid runtime errors.

With `pickerStyle`, you can customize the appearance of pickers to suit various contexts and provide a seamless user experience.



---
url: /guide/View Modifiers/position.md
---

# position

Positions the center of the view at the given x and y coordinates within its parent’s coordinate space.

## Type

```ts
position?: { x: number, y: number }
```

## Example

```tsx
<Text
  position={{ 
    x: 100,
    y: 200 
  }}
>Positioned Text</Text>
```



---
url: /guide/View Modifiers/preferredColorScheme.md
---

# preferredColorScheme

Sets the preferred system appearance (light or dark) for the view hierarchy. Only affects non-transient system overlays.

## Type

```ts
preferredColorScheme?: "light" | "dark"
```

## Example

```tsx
<NavigationStack>
  <List preferredColorScheme="dark">
    <Text>Dark mode view</Text>
  </List>
</NavigationStack>
```



---
url: /guide/View Modifiers/progressViewStyle.md
---

# progressViewStyle

The `progressViewStyle` property allows you to customize the appearance of a progress view in your UI.

## Property Declaration

```tsx
progressViewStyle?: ProgressViewStyle;
```

### Description

The `progressViewStyle` property defines the style of a progress view, allowing you to select a visual representation that best fits your app’s context.

### Accepted Values

The `progressViewStyle` property accepts the following string values:

- **`automatic`**: Uses the default progress view style, adapting to the current context of the view being styled.
- **`circular`**: Displays a circular gauge to indicate the partial completion of an activity. On platforms other than macOS, this style may appear as an indeterminate indicator.
- **`linear`**: Displays a horizontal bar to visually indicate progress.

### Default Behavior

If `progressViewStyle` is not specified, the default style (`automatic`) is applied based on the view’s context.

***

## Progress View Properties

### Timer Interval Progress View Properties

Use these properties to display a progress view for a time-based task:

- **`timerFrom`**: The starting date range timestamp over which the view progresses.
- **`timerTo`**: The ending date range timestamp over which the view progresses.
- **`countsDown`** _(optional)_: If true (default), the view empties as time passes.
- **`label`** _(optional)_: A view that describes the task in progress.
- **`currentValueLabel`** _(optional)_: A view that describes the level of completed progress of the task.

### Normal Progress View Properties

Use these properties to display a progress view for a task with a defined scope:

- **`value`** _(optional)_: The completed amount of the task to this point, in a range of 0.0 to `total`, or `nil` if the progress is indeterminate.
- **`total`** _(optional)_: The full amount representing the complete scope of the task (default is 1.0).
- **`title`** _(optional)_: A title describing the task in progress.
- **`label`** _(optional)_: A view that describes the task in progress.
- **`currentValueLabel`** _(optional)_: A view that describes the level of completed progress of the task.

***

## Usage Example

### Example 1: Timer Interval Progress View

```tsx
<ProgressView
  progressViewStyle="circular"
  timerFrom={Date.now()}
  timerTo={Date.now() + 3600000}
  countsDown={true}
  label={<Text>Timer Progress</Text>}
  currentValueLabel={<Text>Remaining Time</Text>}
/>
```

This creates a circular progress view for a timer interval task.

### Example 2: Normal Progress View

```tsx
<ProgressView
  progressViewStyle="linear"
  value={0.5}
  total={1.0}
  title="File Upload"
  label={<Text>Uploading...</Text>}
  currentValueLabel={<Text>50%</Text>}
/>
```

This creates a linear progress view for a task with 50% completion.

***

## Notes

- The `progressViewStyle` property directly maps to SwiftUI’s `progressViewStyle` modifier.
- Ensure the string value matches one of the predefined styles listed above to avoid runtime errors.



---
url: /guide/View Modifiers/refresable/index.md
---

# refresable

Marks a scrollable view as **refreshable**, enabling the user to pull down to trigger an asynchronous data reload.

## Type

```ts
refreshable?: () => Promise<void>
```

***

## Overview

Use the `refreshable` modifier on scrollable views—such as `<List>`—to implement pull-to-refresh functionality. When the user pulls down past the top of the view, the framework executes the asynchronous handler defined by `refreshable`.

Inside the handler, you can perform any asynchronous operations (e.g., fetching network data or updating local state), and once the operation completes, the refresh control will automatically dismiss.

This behavior closely mirrors SwiftUI’s [`refreshable`](https://developer.apple.com/documentation/swiftui/view/refreshable%28action:%29) modifier.

***

## Usage Example

```tsx
<List
  navigationTitle="Refreshable List"
  navigationBarTitleDisplayMode="inline"
  refreshable={refresh}
/>
```

### Full Example

```tsx
function Example() {
  const [data, setData] = useState(generateRandomList)

  function generateRandomList() {
    const data: number[] = []
    const count = Math.ceil(Math.random() * 100 + 10)

    for (let i = 0; i < count; i++) {
      const num = Math.ceil(Math.random() * 1000)
      data.push(num)
    }

    return data
  }

  async function refresh() {
    return new Promise<void>(resolve => {
      setTimeout(() => {
        setData(generateRandomList())
        resolve()
      }, 2000)
    })
  }

  return <NavigationStack>
    <List
      navigationTitle="Refreshable List"
      navigationBarTitleDisplayMode="inline"
      refreshable={refresh}
    >
      <Section header={
        <Text textCase={null}>Pull down to refresh</Text>
      }>
        {data.map(item =>
          <Text>Number: {item}</Text>
        )}
      </Section>
    </List>
  </NavigationStack>
}
```

***

## Behavior Notes

- The `refreshable` function **must return a `Promise<void>`**. The refresh control remains visible until the promise resolves.
- Use `await` inside the refresh function to perform async tasks:

  ```ts
  refreshable={async () => {
    const result = await fetchData()
    updateState(result)
  }}
  ```
- This modifier is only effective on **scrollable containers**, such as `<List>`.
- You should update the relevant state inside the handler to reflect new data.
- Avoid long-running or blocking tasks without feedback; always resolve the promise in a timely manner to dismiss the refresh spinner.

***

## Best Practices

- Keep refresh logic short and efficient.
- Always **resolve** the promise to ensure the UI doesn’t hang.
- If needed, use a short delay to simulate refresh animations during development:

  ```ts
  await new Promise(resolve => setTimeout(resolve, 1000))
  ```



---
url: /guide/View Modifiers/refresable/refreshable_list.md
---

# Example

```tsx
import { List, Navigation, NavigationStack, Script, Section, Text, useState } from "scripting"

function Example() {
  const [data, setData] = useState(generateRandomList)

  function generateRandomList() {
    const data: number[] = []
    const count = Math.ceil(Math.random() * 100 + 10)

    for (let i = 0; i < count; i++) {
      const num = Math.ceil(Math.random() * 1000)
      data.push(num)
    }

    return data
  }

  async function refresh() {
    return new Promise<void>(resolve => {
      setTimeout(() => {
        setData(generateRandomList())
        resolve()
      }, 1000 * 2)
    })
  }

  return <NavigationStack>
    <List
      navigationTitle={"Refreshable List"}
      navigationBarTitleDisplayMode={"inline"}
      refreshable={refresh}
    >
      <Section header={
        <Text textCase={null}>Pull down to refresh</Text>
      }>
        {data.map(item =>
          <Text>Number: {item}</Text>
        )}
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/View Modifiers/rotationEffect.md
---

# rotationEffect

Rotates the view by a specified angle in degrees. You can optionally set the anchor point around which the rotation occurs.

## Type

```ts
rotationEffect?: number | {
  degrees: number
  anchor: KeywordPoint | Point
}
```

## Example

```tsx
<Text rotationEffect={45}>Rotated</Text>
```

With anchor point:

```tsx
<Text
  rotationEffect={{
    degrees: 30,
    anchor: "bottomTrailing"
  }}
>
  Custom Anchor
</Text>
```



---
url: /guide/View Modifiers/scaleEffect.md
---

# scaleEffect

Scales the view horizontally and vertically. You can specify a common value or separate values, and optionally provide an anchor point.

## Type

```ts
scaleEffect?: number | {
  x: number
  y: number
  anchor?: KeywordPoint | Point
}
```

## Example

```tsx
<Text scaleEffect={1.5}>Scaled</Text>
```

Custom scale:

```tsx
<Text
  scaleEffect={{
    x: 1.2,
    y: 0.8,
    anchor: "center"
  }}
>
  Non-uniform Scale
</Text>
```



---
url: /guide/View Modifiers/shadow.md
---

# shadow

Applies a shadow behind the view. You can control color, blur radius, and x/y offset.

## Type

```ts
shadow?: {
  color: Color
  radius: number
  x?: number
  y?: number
}
```

## Example

```tsx
<Text
  shadow={{
    color: "black",
    radius: 5,
    x: 2,
    y: 4
  }}
>
  Shadowed Text
</Text>
```



---
url: /guide/View Modifiers/textFieldStyle.md
---

# textFieldStyle

The `textFieldStyle` property determines the visual style of your text fields, influencing how their borders, backgrounds, and layout appear. Different styles can help your text fields blend seamlessly into various UI designs, or provide subtle cues about their functionality.

## Overview

A `TextField` provides a way for users to enter text. By selecting a `textFieldStyle`, you can define whether your text fields have a plain, borderless appearance, or a more pronounced, rounded border that sets them apart from surrounding elements.

## Available Styles

- **`automatic`**:\
  Allows the system to choose an appropriate style based on the platform and context. This is a convenient default if you don’t have a strong styling preference.

- **`plain`**:\
  Displays the text field with minimal adornment. This style often looks like plain text, making it suitable for layouts where you want the field to appear unobtrusive.

- **`roundedBorder`**:\
  Surrounds the text field with a rounded rectangle border. This helps make the input area stand out, making it more obvious to users that they can type into it. Ideal for forms or places where user input is a primary action.

## Basic Usage

Below is an example showing how you might use a `TextField` with a specific style:

```tsx
<TextField
  title="Username"
  value={username}
  onChanged={newVal => setUsername(newVal)}
  textFieldStyle="roundedBorder"
  prompt="Enter your username"
/>
```

In this example, the `textFieldStyle="roundedBorder"` will visually highlight the input field, giving users a clear indication that they can tap and start typing.

## Other Useful Properties

- **`value: string`**:\
  The current text content of the field. Update this when the user types to keep the displayed text in sync.

- **`onChanged: (value: string) => void`**:\
  A callback invoked whenever the text in the field changes, allowing you to respond to user input.

- **`prompt?: string`**:\
  A hint or placeholder text guiding the user about what to type.

- **`axis?: Axis`**:\
  Determines how text can scroll if it doesn’t fit. This is useful if you expect long input that might exceed the available space.

- **`autofocus?: boolean` (default: false)**:\
  If true, focuses the text field automatically when it appears, making it ready for immediate typing.

- **`onFocus?: () => void` and `onBlur?: () => void`**:\
  Callbacks triggered when the text field gains or loses focus, respectively. This can help you provide visual feedback, run validation, or update other parts of your UI.

## Example

```tsx
<TextField
  label={<Text style={{fontWeight: 'bold'}}>Email:</Text>}
  value={email}
  onChanged={setEmail}
  prompt="you@example.com"
  textFieldStyle="plain"
  autofocus={true}
  onFocus={() => console.log('Focused')}
  onBlur={() => console.log('Lost focus')}
/>
```

In this example, the text field is styled as `plain`, appearing more integrated into the surrounding content. The `autofocus` property ensures that the user can start typing immediately upon arrival at this view.

## Summary

`textFieldStyle` lets you adapt the appearance of your input fields to different contexts. Whether you opt for the subtlety of `plain` or the more structured look of `roundedBorder`, choosing the right style helps create a clear and intuitive user experience. If unsure, use `automatic` to let the system decide the most appropriate look.



---
url: /guide/View Modifiers/tint.md
---

# tint

The `tint` property overrides the default accent color for a specific view using a given style. Unlike the global app accent color (which may be modified by user settings), `tint` is always respected and should be used to convey semantic meaning or visual emphasis at the component level.

## Definition

```ts
tint?: ShapeStyle | DynamicShapeStyle
```

## Supported Values

- **`ShapeStyle`**: A solid color, gradient, or material.
- **`DynamicShapeStyle`**: A color or gradient that adapts to light/dark mode.

## Common Use Cases

- Apply a local accent color to controls like `Toggle`, `Slider`, `Button`, or `ProgressView`.
- Visually differentiate elements in lists, forms, or modal components.
- Ensure consistent behavior regardless of system or user theme overrides.

## Example: Basic Tint

```tsx
<Toggle 
  tint="systemGreen"
  // ...
/>
```

## Example: Gradient Tint

```tsx
<ProgressView
  value={0.6}
  tint={{
    gradient: [
      { color: "red", location: 0 },
      { color: "orange", location: 1 }
    ],
    startPoint: { x: 0, y: 0 },
    endPoint: { x: 1, y: 1 }
  }}
/>
```

## Example: Dynamic Tint

```tsx
<Slider
  tint={{
    light: "blue",
    dark: "purple"
  }}
  // ...
/>
```



---
url: /guide/View Modifiers/toggleStyle.md
---

# toggleStyle

The `toggleStyle` property defines how a `Toggle` (commonly known as a switch or checkbox) visually appears and behaves. By selecting a style, you can influence the toggle’s look—whether it looks like a traditional switch, a button-like state indicator, or let the system decide what’s best.

## Overview

A `Toggle` is used to represent a boolean on/off state. It might appear as a switch, a tappable button, or use the platform’s default look based on context. The `toggleStyle` property allows you to specify which appearance to use, ensuring your UI remains consistent with your app’s overall design language.

## Available Styles

- **`automatic`**:\
  Lets the system select the most appropriate style based on the platform and context. If you’re unsure which style to choose, `automatic` is a good default.

- **`switch`**:\
  Renders the toggle as a classic switch, similar to what you’d see in iOS Settings. The switch slides between off and on states, providing a familiar interaction for most users.

- **`button`**:\
  Presents the toggle as a button-like element. Instead of sliding, tapping toggles it on or off. This can fit well into UI layouts where toggles should feel more like selectable options rather than switches.

## Example Usage

### Switch Style

```tsx
<Toggle
  title="Enable Notifications"
  value={notificationsEnabled}
  onChanged={(newVal) => setNotificationsEnabled(newVal)}
  toggleStyle="switch"
/>
```

Here, the toggle is displayed as a switch. When the user taps it, the knob slides, turning the option on or off.

### Button Style

```tsx
<Toggle
  title="Dark Mode"
  value={darkMode}
  onChanged={(newVal) => setDarkMode(newVal)}
  toggleStyle="button"
/>
```

In this scenario, the toggle looks like a button that changes state when tapped. It may be useful in contexts where a more pronounced, clickable style feels appropriate.

### Automatic Style

```tsx
<Toggle
  title="Use Cellular Data"
  value={useCellular}
  onChanged={(newVal) => setUseCellular(newVal)}
  toggleStyle="automatic"
/>
```

With `automatic`, the system chooses the style. This is a good choice if you trust the system’s default styling to match the platform’s conventions, or if you’re aiming for maximum consistency without manually specifying a style.

## Other Toggle Properties

- **`value: boolean`**:\
  Indicates the current state of the toggle (on or off).

- **`onChanged(value: boolean): void`**:\
  A callback that fires when the toggle changes state. Use this to update your app’s data model accordingly.

- **`intent: AppIntent<any>` (optional)**:\
  Instead of handling state changes locally, you can associate a toggle with an `AppIntent` for certain widget or Live Activity scenarios. This lets you trigger predefined app actions directly from the toggle’s state changes.

- **`title` and `systemImage`**:\
  Provide a descriptive text label and optionally an image to convey the toggle’s purpose clearly.

- **`children`**:\
  Instead of a title or image, you can provide custom content (e.g., a text node, an icon, or a combination) as the label for the toggle.

## Summary

By adjusting the `toggleStyle`, you control how your toggle looks and feels. Whether you choose a familiar switch, a button-like toggle, or leave it to `automatic`, this property ensures that the toggle fits cohesively into your script's design and provides a clear and intuitive way for users to change a Boolean setting.



---
url: /guide/View Modifiers/toolbar/Use with Toolbar Component.md
---

# Use with Toolbar Component

In Scripting, views can populate their navigation bar or toolbar area using either the original `ToolBarProps` object or the declarative component-based API that mirrors SwiftUI’s toolbar system. This document explains in detail how to use the `Toolbar`, `ToolbarItem`, `ToolbarItemGroup`, `ToolbarSpacer`, and `DefaultToolbarItem` components, including parameters, types, and usage patterns.

***

## Overview

The `toolbar` property can be used in two ways:

- By passing a `ToolBarProps` object
- By passing a **VirtualNode**, which **must be a `<Toolbar>` component**

When using the component-based API, all toolbar content is declared inside a `<Toolbar>` container, and each item defines its placement explicitly. This provides clearer structure and more precise layout control, similar to SwiftUI.

```tsx
<List
  toolbar={
    <Toolbar>
      {/* toolbar items here */}
    </Toolbar>
  }
>
  {/* main content */}
</List>
```

***

## Toolbar

The `<Toolbar>` component serves as a container for toolbar content. It does not define placement itself; instead, `ToolbarItem` and `ToolbarItemGroup` determine where items go.

## Example

```tsx
<List
  toolbar={
    <Toolbar>
      <ToolbarItem placement="topBarLeading">
        <Button title="Close" action={dismiss} />
      </ToolbarItem>
      <ToolbarItem placement="topBarTrailing">
        <Button title="Done" action={handleDone} />
      </ToolbarItem>
    </Toolbar>
  }
>
  {/* content */}
</List>
```

***

## ToolbarItem

`ToolbarItem` represents a single toolbar element placed at a specific position.

## Parameters

| Parameter   | Type                   | Default     | Description                                                                  |
| ----------- | ---------------------- | ----------- | ---------------------------------------------------------------------------- |
| `placement` | `ToolbarItemPlacement` | `automatic` | Position of the item, such as `topBarLeading`, `navigation`, `primaryAction` |
| `children`  | `VirtualNode`          | required    | The item’s content, usually a button or text                                 |

## Example

```tsx
<Toolbar>
  <ToolbarItem placement="navigation">
    <Button title="Back" action={Navigation.useDismiss()} />
  </ToolbarItem>
</Toolbar>
```

***

## ToolbarItemGroup

`ToolbarItemGroup` allows multiple toolbar items to be grouped together in a single placement.

## Parameters

| Parameter   | Type                    | Default     | Description                    |
| ----------- | ----------------------- | ----------- | ------------------------------ |
| `placement` | `ToolbarItemPlacement`  | `automatic` | Placement for the entire group |
| `children`  | multiple `VirtualNode`s | required    | The grouped toolbar items      |

## Example

```tsx
<Toolbar>
  <ToolbarItemGroup placement="topBarTrailing">
    <Button title="Refresh" action={reload} />
    <Button title="More" action={openMenu} />
  </ToolbarItemGroup>
</Toolbar>
```

***

## ToolbarSpacer

`ToolbarSpacer` inserts empty space in a toolbar. It can be used to fine-tune layout between items.

## Parameters

| Parameter   | Type                    | Default     | Description                                          |
| ----------- | ----------------------- | ----------- | ---------------------------------------------------- |
| `sizing`    | `'fixed' \| 'flexible'` | `flexible`  | Determines whether the spacer expands or stays fixed |
| `placement` | `ToolbarItemPlacement`  | `automatic` | Placement for the  spacer                            |

### Behavior

- `flexible`: Expands to fill available space.
- `fixed`: Adds a fixed separation between items.

## Example

```tsx
<Toolbar>
  <ToolbarItem placement="topBarTrailing">
    <Button title="Edit" action={edit} />
  </ToolbarItem>

  <ToolbarSpacer sizing="fixed" />

  <ToolbarItem placement="topBarTrailing">
    <Button title="Save" action={save} />
  </ToolbarItem>
</Toolbar>
```

***

## DefaultToolbarItem

`DefaultToolbarItem` inserts system-provided toolbar items, such as the sidebar toggle button or search button.

## Parameters

| Parameter   | Type                                     | Default     | Description                           |
| ----------- | ---------------------------------------- | ----------- | ------------------------------------- |
| `kind`      | `"sidebarToggle" \| "search" \| "title"` | required    | Specifies which system item to insert |
| `placement` | `ToolbarItemPlacement`                   | `automatic` | Toolbar placement                     |

## Example

```tsx
<Toolbar>
  <DefaultToolbarItem kind="search" placement="topBarTrailing" />
</Toolbar>
```

***

## Complete Example

```tsx
<NavigationStack>
  <List
    toolbar={
      <Toolbar>

        {/* Navigation button */}
        <ToolbarItem placement="navigation">
          <Button title="Back" action={Navigation.useDismiss()} />
        </ToolbarItem>

        {/* Title */}
        <DefaultToolbarItem kind="title" />

        {/* Trailing group */}
        <ToolbarItem placement="topBarTrailing">
          <Button title="Edit" action={edit} />
        </ToolbarItem>
        <ToolbarSpacer sizing="fixed" />
        <ToolbarItem placement="topBarTrailing">
          <Button title="Done" action={finish} />
        </ToolbarItem>

        {/* Bottom bar item */}
        <ToolbarItem placement="bottomBar">
          <Button title="Help" action={showHelp} />
        </ToolbarItem>

      </Toolbar>
    }
  >
    {/* content */}
  </List>
</NavigationStack>
```

***

## Relationship with ToolBarProps

| Method                                    | Description                                              |
| ----------------------------------------- | -------------------------------------------------------- |
| `toolbar={{ topBarTrailing: <Button/> }}` | Simple and declarative for straightforward scenarios     |
| `toolbar={<Toolbar>...</Toolbar>}`        | More explicit, structured, and ideal for complex layouts |

Both approaches remain fully supported. When a `VirtualNode` is passed, it **must be a `<Toolbar>` component** to ensure proper layout interpretation.



---
url: /guide/View Modifiers/toolbar/Use with ToolbarProps.md
---

# Use with ToolbarProps

The `toolbar` property allows you to populate a view’s navigation or toolbar area with various items, mirroring the functionality of SwiftUI's `toolbar` view modifier. By setting `toolbar` on a component, you can place items in the navigation bar or bottom toolbar, and specify their semantic roles.

## Overview

The `toolbar` property accepts a `ToolBarProps` object. Each key within `ToolBarProps` corresponds to a specific toolbar placement or action type. The values you provide should be either a single `VirtualNode` or an array of `VirtualNode` elements, which represent your custom UI items.

**In SwiftUI (for reference):**

```swift
// SwiftUI code example
YourView()
    .toolbar {
        ToolbarItem(placement: .confirmationAction) {
            Button("Save") {
                // Handle save
            }
        }
    }
```

**In Scripting (TypeScript/TSX):**

```tsx
<NavigationStack>
  <List
    toolbar={{
      confirmationAction: <Button title="Save" action={() => handleSave()} />,
      cancellationAction: <Button title="Cancel" action={() => handleCancel()} />,
      topBarLeading: [
        <Button title="Edit" action={() => handleEdit()} />,
        <Button title="Refresh" action={() => handleRefresh()} />
      ]
    }}
  >
    {/* Your main content here */}
  </List>
</NavigationStack>
```

## Toolbar Placements

The following keys can be used within `ToolBarProps` to specify where and how an item is placed:

- **automatic**: Automatically determines placement based on context and platform.
- **bottomBar**: Places the item in a bottom toolbar.
- **cancellationAction**: Represents a cancellation action in a modal interface.
- **confirmationAction**: Represents a confirmation action in a modal interface (e.g., "Save").
- **destructiveAction**: Represents an action that performs a destructive task (e.g., "Delete").
- **keyboard**: Places the item in a toolbar associated with the keyboard.
- **navigation**: Represents a navigation-related action (e.g., "Back", "Close").
- **primaryAction**: Represents the primary action of the interface.
- **principal**: Places the item in the principal item section of the toolbar (often centered in the navigation bar).
- **topBarLeading**: Places the item on the leading edge (e.g., left side) of the top bar.
- **topBarTrailing**: Places the item on the trailing edge (e.g., right side) of the top bar.

## Example Usage

### Single Item

If you want to add a single `confirmationAction` button to the toolbar:

```tsx
<NavigationStack>
  <VStack
    toolbar={{
      confirmationAction: <Button
        title="Save"
        action={() => console.log('Saving...')}
      />
    }}
  >
    {/* Main content */}
  </Vstack>
</NavigationStack>
```

### Multiple Items

You can also pass an array of nodes to a single placement, allowing multiple items in the same area:

```tsx
<NavigationStack>
  <VStack
    toolbar={{
      topBarLeading: [
        <Button title="Edit" action={() => console.log('Edit pressed')} />,
        <Button title="Settings" action={() => console.log('Settings pressed')} />
      ],
      topBarTrailing: <Button title="Done" action={() => console.log('Done pressed')} />
    }}
  >
    {/* Main content */}
  </Vstack>
</NavigationStack>
```

### Combining Multiple Toolbar Placements

You can mix and match different toolbar placements as needed:

```tsx
<NavigationStack>
  <List
    toolbar={{
      navigation: <Button title="Back" action={() => console.log('Back pressed')} />,
      principal: <Text fontWeight={"bold"}>Title</Text>,
      primaryAction: <Button title="Share" action={() => console.log('Share pressed')} />,
      bottomBar: <Button title="Help" action={() => console.log('Help pressed')} />
    }}
  >
    {/* Main content */}
  </List>
</NavigationStack>
```

## Summary

By using the `toolbar` property, you can easily replicate the behavior of SwiftUI’s `toolbar` modifier in your Scripting app. Assigning `VirtualNode` elements to the appropriate keys in `ToolBarProps` allows you to build rich, contextual toolbars and navigation bars for your pages.



---
url: /guide/View Modifiers/translationHost.md
---

# translationHost

The `translationHost` view modifier is used to provide a translation service context to your UI. This modifier enables user interaction with system-level translation dialogs, such as downloading required languages or selecting ambiguous source languages.

***

## Purpose

Apply the `translationHost` modifier to the **root view** of your page when using the `Translation` class for localized translations. It ensures that:

- If the **source or target language** is not currently available on the device, the system will **prompt the user to download** the necessary language resources.
- If the **source language is not specified** and cannot be inferred from the text content, the system will **prompt the user to select a source language**.

Without applying this modifier, such user prompts may not function correctly, and your translation session may fail silently or throw an error.

***

## Type

```ts
translationHost?: Translation
```

The value of this modifier must be an instance of the `Translation` class.

***

## Usage Example

```tsx
function View() {
  const translation = useMemo(() => new Translation(), [])
  const [translated, setTranslated] = useState<Record<string, string>>({})
  const texts = ["Hello", "Goodbye"]
  
  useEffect(() => {
    translation.translateBatch({
      texts,
      source: "en",
      target: "fr"
    }).then(result => {
      const map: Record<string, string> = {}
      result.forEach((item, index) => {
        map[texts[index]] = item
      })
      setTranslated(map)
    })
  }, [])

  return <VStack translationHost={translation}>
    {texts.map(text => (
      <Text key={text}>
        {translated[text] || text}
      </Text>
    ))}
  </VStack>
}
```

In this example:

- A `Translation` instance is created using `useMemo`.
- A batch of English texts is translated to French.
- The `VStack` view is wrapped with the `translationHost` modifier so the system can show download or language selection prompts if necessary.

***

## Best Practices

- Always apply `translationHost` to the **top-level container view** when performing translation-related operations.
- Use a **consistent `Translation` instance** that matches the one used for calling `.translate()` or `.translateBatch()`.
- Avoid creating multiple `Translation` instances for the same session if possible.



---
url: /guide/View Modifiers/widgetBackground.md
---

# widgetBackground

The `widgetBackground` modifier is used to define background styles specifically for **widgets**, with behavior optimized for **iOS 18’s accented (tinted)** rendering mode.

## Purpose

In **accented mode**, iOS displays nearly all view colors—including backgrounds—as white, unless the view is explicitly marked with `widgetAccentable`. This can cause unintended visual issues in widgets.

The `widgetBackground` modifier addresses this by:

- **Automatically hiding the background** when the widget is displayed in accented mode.
- **Rendering the background normally** in all other display modes (default or full-color).

This ensures your widget layout remains visually consistent and unaffected by system-imposed tinting rules.

***

## Supported Background Variants

The `widgetBackground` modifier accepts several input formats:

### 1. **Solid Color (ShapeStyle)**

Apply a simple color to the background.

```tsx
<Text widgetBackground="systemBlue">
  Hello
</Text>
```

***

### 2. **Dynamic Color (DynamicShapeStyle)**

Apply different styles for light and dark modes.

```tsx
<Text
  widgetBackground={{
    light: "white",
    dark: "black"
  }}
>
  Mode-aware Background
</Text>
```

***

### 3. **Shape with Fill Style**

Use a **shape** along with a **fill style**. This form provides structured and stylized backgrounds.

```tsx
<Text
  widgetBackground={{
    style: "systemGray6",
    shape: {
      type: "rect",
      cornerRadius: 12,
      style: "continuous"
    }
  }}
>
  Rounded Background
</Text>
```

You may use any supported built-in or custom shape types, such as:

- `'rect'`, `'circle'`, `'capsule'`, `'ellipse'`, `'buttonBorder'`, `'containerRelative'`
- Custom rounded rectangles with `cornerRadius`, `cornerSize`, or `cornerRadii`

***

## Behavior in Accented Mode

- **In accented (tinted) mode**: The background is **automatically hidden** to prevent it from rendering as solid white.
- **In default and full-color modes**: The background displays as defined.

This conditional behavior ensures better design control and visual integrity across widget contexts.

***

## Best Practices

- Use `widgetBackground` only in **widget-specific views**.
- Do not use it for essential visual meaning, since the background may be hidden in accented mode.
- Combine it with `widgetAccentable` to precisely control which parts of the widget are subject to system tinting.



---
url: /guide/Views/AVPlayerView.md
---

# AVPlayerView

`AVPlayerView` is a video playback component introduced in Scripting that wraps the system-native `AVPlayerViewController`.
Unlike `VideoPlayer`, `AVPlayerView` **fully supports system Picture in Picture (PiP)** and exposes PiP lifecycle state to scripts.

This component is intended for **media-centric scenarios** where native playback behavior, PiP, Now Playing integration, and background playback are required.

***

## 1. When to Use AVPlayerView

Use `AVPlayerView` when you need:

- System Picture in Picture (PiP) for video
- Native playback controls
- Integration with Now Playing / Control Center / Lock Screen
- Automatic PiP when entering background
- Fine-grained observation of PiP lifecycle

If you do **not** need PiP, `VideoPlayer` remains a lighter alternative.

***

## 2. Core Properties Explained

### 2.1 `player`

```ts
player: AVPlayer
```

- The underlying media player
- Fully managed by the developer
- Supports local files, remote URLs, HLS streams, etc.

`AVPlayerView` **does not own the player lifecycle**.
The player must remain alive while PiP is active.

***

### 2.2 `pipStatus`

```ts
pipStatus: Observable<PIPStatus>
```

Provides real-time updates for the PiP lifecycle.

Possible values:

| Value              | Meaning               |
| ------------------ | --------------------- |
| `willStart`        | PiP is about to start |
| `didStart`         | PiP has started       |
| `willStop`         | PiP is about to stop  |
| `didStop`          | PiP has stopped       |
| `undefined / null` | No PiP activity yet   |

This value is **system-controlled**.
You should **observe it only**, never assign values manually.

***

## 3. Picture in Picture Configuration

### 3.1 `allowsPictureInPicturePlayback`

- Enables or disables PiP entirely
- Default: `true`

When set to `false`:

- PiP controls are hidden
- PiP cannot be activated

***

### 3.2 `canStartPictureInPictureAutomaticallyFromInline`

- If enabled, PiP starts automatically when:

  - The app moves to background
  - Video is playing inline
- Default: `false`

Recommended for:

- Media apps
- Continuous playback experiences

***

### 3.3 `updatesNowPlayingInfoCenter`

- Controls automatic updates to:

  - Lock screen
  - Control Center
  - External playback controls
- Default: `true`

Should generally remain enabled for video playback apps.

***

## 4. Full-Screen Playback Behavior

### 4.1 `entersFullScreenWhenPlaybackBegins`

- Automatically enters full screen on play
- Default: `false`

***

### 4.2 `exitsFullScreenWhenPlaybackEnds`

- Automatically exits full screen on completion
- Default: `false`

***

## 5. Video Scaling (`videoGravity`)

```ts
videoGravity?: AVLayerVideoGravity
```

| Value              | Behavior                                    |
| ------------------ | ------------------------------------------- |
| `resize`           | Stretch to fill (no aspect ratio)           |
| `resizeAspect`     | Preserve aspect ratio, fit inside (default) |
| `resizeAspectFill` | Preserve aspect ratio, fill and crop        |

***

## 6. Complete Demo Example

The following example demonstrates:

- Creating and configuring `AVPlayer`
- Activating audio playback session
- Observing PiP lifecycle
- Controlling playback state
- Proper cleanup

```tsx
function Example() {
  const dismiss = Navigation.useDismiss()
  const [status, setStatus] = useState<TimeControlStatus>(
    TimeControlStatus.paused
  )
  const pipstatus = useObservable<PIPStatus>()

  console.log(pipstatus.value)

  const player = useMemo(() => {
    const player = new AVPlayer()

    player.setSource(
      "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
    )

    player.onTimeControlStatusChanged = status => {
      setStatus(status)
    }

    SharedAudioSession.setActive(true)
    SharedAudioSession.setCategory(
      "playback",
      ["defaultToSpeaker"]
    )

    return player
  }, [])

  useEffect(() => {
    return () => {
      player.dispose()
    }
  }, [])

  return <NavigationStack>
    <VStack
      navigationTitle="VideoPlayer"
      navigationBarTitleDisplayMode="inline"
      toolbar={{
        cancellationAction: <Button
          title="Done"
          action={dismiss}
        />
      }}
    >
      <AVPlayerView
        player={player}
        pipStatus={pipstatus}
        canStartPictureInPictureAutomaticallyFromInline
        updatesNowPlayingInfoCenter
        entersFullScreenWhenPlaybackBegins
      />

      <Button
        title={
          status === TimeControlStatus.paused
            ? "Play"
            : "Pause"
        }
        action={() => {
          if (status === TimeControlStatus.paused) {
            player.play()
          } else {
            player.pause()
          }
        }}
      />
    </VStack>
  </NavigationStack>
}
```

***

## 7. PiP Lifecycle Notes

Typical PiP state progression:

1. `willStart`
2. `didStart`
3. PiP running
4. `willStop`
5. `didStop`

The system may skip stages in error or interruption scenarios.
Always treat `didStart` and `didStop` as authoritative.

***

## 8. Important Notes and Constraints

### 8.1 AVPlayerView PiP is System-Level PiP

- Uses native video PiP
- Completely separate from Scripting’s custom PiP View Modifiers
- These two mechanisms must not be mixed

***

### 8.2 Audio Session Is Required

For PiP to work reliably:

- An active audio session is required
- Category should be `playback`
- Background audio capability must be enabled

Failing to configure the audio session may cause PiP to fail silently.

***

### 8.3 Do Not Dispose AVPlayer While PiP Is Active

- Disposing or replacing `AVPlayer` during PiP
- Will force PiP to stop unexpectedly
- May result in system errors

Always wait until `pipStatus` reaches `didStop` before releasing the player.

***

## 9. Recommended Best Practices

- Use `AVPlayerView` exclusively for video PiP
- Treat `pipStatus` as read-only state
- Keep `AVPlayer` lifecycle stable during PiP
- Configure audio session explicitly
- Avoid frequent player replacement
- Clean up resources only after PiP has fully stopped



---
url: /guide/Views/AccessoryWidgetBackground.md
---

# AccessoryWidgetBackground

An adaptive background view that provides a standard appearance based on the widget’s environment.

## Overview

The `AccessoryWidgetBackground` component is designed to be used inside accessory widgets—such as Lock Screen widgets or StandBy widgets—where it applies a system-defined background appropriate for the widget's context.

Using this view ensures that your widget maintains visual consistency with the surrounding system UI, adapting automatically to light and dark modes, transparency effects, and other environmental styling set by the system.

You typically use `AccessoryWidgetBackground` as a background layer in combination with other views, such as `ZStack`, to provide system-adaptive styling while layering custom content above it.

## Example

```tsx
import { AccessoryWidgetBackground, Text, ZStack } from "scripting"

function AccessoryView() {
  return (
    <ZStack>
      <AccessoryWidgetBackground />
      <Text font="caption">Weather</Text>
    </ZStack>
  )
}
```

In this example, `AccessoryWidgetBackground` provides the adaptive system background, and the `Text` element is rendered on top of it. This layout is useful for Lock Screen widgets where consistent and legible appearance is important.

## Best Practices

- Always place `AccessoryWidgetBackground` beneath your content using a stacking layout like `ZStack`.
- Do not apply custom colors or effects directly to `AccessoryWidgetBackground`; it automatically adapts to system appearance.
- Combine it with other SwiftUI-inspired components to maintain a consistent style with iOS system widgets.

## Compatibility

This component is intended for use in accessory widgets and may not have any visual effect outside that context. Use it to ensure your widget blends seamlessly with the native iOS design system.



---
url: /guide/Views/Button.md
---

# Button

The `Button` component in the **Scripting** app allows you to create interactive elements with customizable actions, labels, styles, and roles. Buttons can trigger actions, execute intents, and display various visual styles based on the configuration. This documentation provides a detailed guide on how to use the `Button` API, including its properties, roles, styles, and examples.

***

## `Button`

### Description

You create a button by providing an **action** or an **intent** and a **label**. The label can be a simple text, an icon, or a complex view. Buttons are essential for creating interactive interfaces, such as submitting forms or navigating between pages.

### Properties

| **Property**  | **Type**                                                         | **Description**                                                                                                                                          |
| ------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`       | `string`                                                         | The text label displayed on the button.                                                                                                                  |
| `systemImage` | `string` _(optional)_                                            | The name of a system icon to display alongside the button's title.                                                                                       |
| `children`    | `VirtualNode` or `VirtualNode[]`                                 | Custom view(s) to be used as the button label instead of `title`.                                                                                        |
| `role`        | `'destructive' \| 'cancel' \| 'close' \| 'confirm'` _(optional)_ | Describes the purpose of the button. `destructive` highlights the button as performing a potentially dangerous action, while `cancel` implies dismissal. |
| `intent`      | `AppIntent<any>`                                                 | An intent to execute when the button is triggered. Available for `Widget` or `LiveActivity`. See the `Interactive Widget and LiveActivity`.              |
| `action`      | `() => void`                                                     | A function to execute when the user triggers the button.                                                                                                 |

***

### `ButtonStyle`

Defines the visual appearance of the button.

| **Value**           | **Description**                                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `automatic`         | The default style based on the button's context.                                                            |
| `bordered`          | A standard bordered style.                                                                                  |
| `borderedProminent` | A prominent bordered style that stands out.                                                                 |
| `borderless`        | A style without any border.                                                                                 |
| `plain`             | A plain style with minimal decoration, though it may indicate pressed, focused, or enabled states visually. |

***

### `ButtonBorderShape`

Specifies the shape of the button's border when using `bordered` or `borderedProminent` styles.

| **Value**                            | **Description**                                                   |
| ------------------------------------ | ----------------------------------------------------------------- |
| `automatic`                          | Defers to the system to determine the appropriate shape.          |
| `capsule`                            | A capsule-shaped border.                                          |
| `circle`                             | A circular border.                                                |
| `roundedRectangle`                   | A rectangle with rounded corners.                                 |
| `buttonBorder`                       | Defers to the environment to determine the resolved border shape. |
| `{ roundedRectangleRadius: number }` | A rounded rectangle with a specific corner radius.                |

***

### `ControlSize`

Defines the size of the button and other controls.

| **Value**    | **Description**                                                                  |
| ------------ | -------------------------------------------------------------------------------- |
| `mini`       | The smallest control size.                                                       |
| `small`      | A compact control size.                                                          |
| `regular`    | The standard control size.                                                       |
| `large`      | A large control size.                                                            |
| `extraLarge` | The largest control size, typically for high emphasis or accessibility purposes. |

***

### `CommonViewProps`

These properties can be applied to customize the appearance and behavior of buttons within a view.

| **Property**        | **Type**            | **Description**                                                                         |
| ------------------- | ------------------- | --------------------------------------------------------------------------------------- |
| `controlSize`       | `ControlSize`       | Sets the size for controls within this view.                                            |
| `buttonStyle`       | `ButtonStyle`       | Applies custom interaction behavior and appearance to buttons.                          |
| `buttonBorderShape` | `ButtonBorderShape` | Specifies the shape of the border for `bordered` and `borderedProminent` button styles. |

***

## Example Usage

### Basic Button with Action

```tsx
<Button title="Sign in" action={handleSignIn} />
```

### Button with System Image

```tsx
<Button title="Delete" systemImage="trash" role="destructive" action={handleDelete} />
```

### Button with Custom Label

```tsx
<Button>
  <Text>Custom Label</Text>
</Button>
```

### Button Executing an AppIntent

```tsx
<Button
  title="Start Workout"
  intent={MyStartWorkoutIntent({ duration: 30 })}
  buttonStyle="borderedProminent"
/>
```

### Styling Buttons

```tsx
<Group
  buttonStyle="bordered"
  buttonBorderShape={{ roundedRectangleRadius: 8 }}
  controlSize="large"
>
  <Button title="Save" action={handleSave} />
</Group>
```

***

### Notes

- Use `role` to indicate buttons with specific purposes, such as canceling or destructive actions.
- Combine `buttonStyle` and `buttonBorderShape` for consistent theming across views.
- The `intent` property integrates buttons with `Widget` and `LiveActivity` for seamless interactions.

For further details on `AppIntent`, refer to the `Interactive Widget and LiveActivity` documentation.



---
url: /guide/Views/Charts/AreaStackChart/index.md
---

# AreaStackChart

The `AreaStackChart` component displays a series of values as stacked areas over a shared axis, allowing for a clear comparison of data parts and totals across categories or time.

## Usage

```tsx
<Chart frame={{ height: 300 }}>
  <AreaStackChart
    marks={[
      {
        category: "Cheese",
        label: "2020",
        value: 0.26,
        stacking: "standard"
      },
      ...
    ]}
  />
</Chart>
```

## Props

### `marks: Array<object>` **(required)**

An array of data points to render on the chart.

Each mark supports the following properties:

- `category: string`
  A category label for the mark, typically used to group data in the stacked chart.

- `label: string | Date`
  The x-axis label for this mark. Can be a year, date, or other descriptor.

- `value: number`
  The numeric value to be represented by the mark.

- `unit?: CalendarComponent`
  Specifies the calendar component for time-based values (e.g., `"year"`, `"month"`, `"day"`). Useful when rendering time series.

- `stacking?: ChartMarkStackingMethod`
  Controls how marks are stacked:

  - `"standard"`: Stack values from a common baseline (default).
  - `"normalized"`: Normalize all values to represent a percentage of the total.
  - `"center"`: Stack around a central axis for symmetrical data.
  - `"unstacked"`: Render without stacking.

- Other optional `ChartMarkProps`:
  Includes extensive styling and behavior options such as:

  - `foregroundStyle`
  - `opacity`
  - `cornerRadius`
  - `interpolationMethod`
  - `symbol`, `symbolSize`, `annotation`, `clipShape`, `shadow`, `blur`, `zIndex`, `offset`, etc.

Refer to `ChartMarkProps` for detailed mark customization.

### `labelOnYAxis?: boolean`

Whether to display the `label` values on the Y-axis instead of the default X-axis.
Defaults to `false`.

## Example

```tsx
<AreaStackChart
  labelOnYAxis={false}
  marks={[
    {
      category: "Burger",
      label: 2020,
      value: 0.6,
      stacking: "standard"
    },
    {
      category: "Cheese",
      label: 2020,
      value: 0.26,
      stacking: "standard"
    },
    {
      category: "Bun",
      label: 2020,
      value: 0.24,
      stacking: "standard"
    }
  ]}
/>
```



---
url: /guide/Views/Charts/AreaStackChart/index_example.md
---

# Example

```tsx
import { AreaStackChart, Chart, ChartMarkStackingMethod, Navigation, NavigationStack, Picker, Script, Text, useState, VStack } from "scripting"

const data = [
  { name: "Burger", price: 0.07, year: 1960 },
  { name: "Cheese", price: 0.03, year: 1960 },
  { name: "Bun", price: 0.05, year: 1960 },

  { name: "Burger", price: 0.10, year: 1970 },
  { name: "Cheese", price: 0.04, year: 1970 },
  { name: "Bun", price: 0.06, year: 1970 },

  { name: "Burger", price: 0.15, year: 1980 },
  { name: "Cheese", price: 0.10, year: 1980 },
  { name: "Bun", price: 0.1, year: 1980 },

  { name: "Burger", price: 0.23, year: 1990 },
  { name: "Cheese", price: 0.12, year: 1990 },
  { name: "Bun", price: 0.13, year: 1990 },

  { name: "Burger", price: 0.32, year: 2000 },
  { name: "Cheese", price: 0.15, year: 2000 },
  { name: "Bun", price: 0.15, year: 2000 },

  { name: "Burger", price: 0.49, year: 2010 },
  { name: "Cheese", price: 0.20, year: 2010 },
  { name: "Bun", price: 0.19, year: 2010 },

  { name: "Burger", price: 0.60, year: 2020 },
  { name: "Cheese", price: 0.26, year: 2020 },
  { name: "Bun", price: 0.24, year: 2020 },
]

const stackings: ChartMarkStackingMethod[] = [
  'center',
  'normalized',
  'standard',
  'unstacked'
]

function Example() {
  const [stacking, setStacking] = useState<ChartMarkStackingMethod>('standard')

  return <NavigationStack>
    <VStack
      navigationTitle={"AreaStackChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Picker
        title={"StackingMethod"}
        value={stacking}
        onChanged={setStacking as any}
        pickerStyle={"menu"}
      >
        {stackings.map(item =>
          <Text tag={item}>{item}</Text>
        )}
      </Picker>
      <Chart
        frame={{
          height: 300
        }}
      >
        <AreaStackChart
          marks={data.map(item => ({
            category: item.name,
            label: item.year.toString(),
            value: item.price,
            stacking: stacking,
          }))}
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/Axis Customization/index.md
---

# Axis Customization

This example demonstrates how to customize chart axes using `chartXAxis` and `chartYAxis`. Beyond the legacy `Visibility` toggle, both modifiers now accept an `AxisMarksConfig` object that maps to SwiftUI Charts' `AxisMarks` + `AxisGridLine` + `AxisTick` + `AxisValueLabel`.

***

## Quick reference

```ts
chartXAxis?: Visibility | AxisMarksConfig
chartYAxis?: Visibility | AxisMarksConfig

type AxisMarksConfig = {
  position?: AxisMarkPosition       // 'automatic' | 'leading' | 'trailing' | 'top' | 'bottom'
  preset?: AxisMarkPreset           // 'automatic' | 'aligned' | 'extended' | 'inset'
  values?: AxisMarkValues
  stroke?: StrokeStyle
  gridLine?: AxisGridLineConfig     // boolean | { centered?, stroke? }
  tick?: AxisTickConfig             // boolean | { centered?, length?, stroke? }
  valueLabel?: AxisValueLabelConfig // boolean | string | { format?, content?, ... }
}
```

`AxisMarkValues` accepts:

- `'automatic'`
- `{ type: 'automatic', desiredCount?, roundLowerBound?, roundUpperBound? }`
- `{ type: 'stride', by: number }` — for `Double` axis data
- `{ type: 'strideDate', by: CalendarComponent, count? }` — for `Date` axis data
- `{ type: 'values', values: number[] | string[] | Date[] }` — explicit ticks (the array element type **must** match the chart's plotted axis type)

***

## Example sections

### 1. Default axes (backward-compatible)

If you do not set `chartXAxis` / `chartYAxis`, the system picks defaults — exactly as before.

### 2. Stride + dashed grid + currency labels

```tsx
<Chart
  chartYAxis={{
    values: { type: "stride", by: 1000 },
    gridLine: { stroke: { lineWidth: 0.5, dash: [4, 2] } },
    tick: { length: 6 },
    valueLabel: { format: "currency" },
  }}
>
  <LineChart marks={...} />
</Chart>
```

- `values: { type: 'stride', by: 1000 }` puts a tick every 1000 units along the Y axis.
- `gridLine.stroke.dash` produces a dashed grid line.
- `valueLabel.format: 'currency'` formats each tick label using the device locale's currency style.

### 3. Explicit values + percent labels

```tsx
chartYAxis={{
  values: { type: "values", values: [0, 0.1, 0.2, 0.3, 0.4, 0.5] },
  valueLabel: { format: "percent" },
}}
```

- Pins ticks at exactly the values you list.
- `format: 'percent'` shows `10%`, `20%`, etc.

### 4. Custom view label

```tsx
chartXAxis={{
  position: "bottom",
  gridLine: false,
  valueLabel: {
    multiLabelAlignment: "center",
    content: <Text font={"caption2"} fontWeight={"bold"} foregroundStyle={"orange"}>YR</Text>,
  },
}}
```

- Replaces every X-axis tick label with a custom view.
- `gridLine: false` hides grid lines entirely.
- **Performance note:** the view content is rebuilt for every tick — keep the view tree small.

### 5. Legacy Visibility tokens

```tsx
chartXAxis={"hidden"}
chartYAxis={"hidden"}
```

The original `'automatic' | 'visible' | 'hidden'` form is fully preserved.

***

## Format tokens

`valueLabel.format` accepts these tokens:

| token      | numeric data   | date data                   |
| ---------- | -------------- | --------------------------- |
| `number`   | `1,234.56`     | (falls through to dateTime) |
| `percent`  | `42%`          | (n/a)                       |
| `currency` | `$1,200`       | (n/a)                       |
| `date`     | (n/a)          | `01/15/2024`                |
| `time`     | (n/a)          | `4:30 PM`                   |
| `dateTime` | (n/a, default) | `01/15/2024, 4:30 PM`       |

***

## Pitfalls

- **`values` array element type must match the chart's axis data type.** Passing `[Date]` when the chart's X-axis data is `string` renders an empty axis (silent fallback, not a crash).
- **`multiLineTextAlignment` is deprecated** — use `multiLabelAlignment` (mirrors the SwiftUI Charts SDK name and accepts the full 9-direction `Alignment`). The deprecated alias still works for backward compatibility but only accepts `'leading' | 'center' | 'trailing'`.
- **Custom `valueLabel.content` re-renders every tick.** Keep the view light and avoid heavy computation inside.

***

## Conclusion

`AxisMarksConfig` lifts a previously hidden ceiling: anything you could express through SwiftUI's `AxisMarks { ... }` content closure is now available as a declarative chart prop, while the original `Visibility` form continues to work unchanged.



---
url: /guide/Views/Charts/Axis Customization/index_example.md
---

# Example

```tsx
import { BarChart, Chart, LineChart, Navigation, NavigationStack, Script, ScrollView, Section, Text, VStack } from "scripting"

const sales = [
  { year: '2020', value: 1200 },
  { year: '2021', value: 1400 },
  { year: '2022', value: 2000 },
  { year: '2023', value: 2500 },
  { year: '2024', value: 3600 },
]

const growth = [
  { year: '2020', rate: 0.14 },
  { year: '2021', rate: 0.16 },
  { year: '2022', rate: 0.42 },
  { year: '2023', rate: 0.25 },
  { year: '2024', rate: 0.44 },
]

function Example() {
  return <NavigationStack>
    <ScrollView
      navigationTitle={"Axis Customization"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <VStack
        alignment={"leading"}
        spacing={24}
        padding
      >

        {/* 1. Default axes — backward-compatible Visibility-only path. */}
        <Section
          header={
            <Text font={"headline"}>1. Default axes</Text>
          }
        >
          <Chart frame={{ height: 200 }}>
            <BarChart marks={sales.map(d => ({ label: d.year, value: d.value }))} />
          </Chart>
        </Section>

        {/* 2. Custom Y axis — stride, grid line stroke, tick length, currency format. */}
        <Section
          header={
            <Text font={"headline"}>2. Stride + dashed grid + currency labels</Text>
          }
        >
          <Chart
            frame={{ height: 220 }}
            chartYAxis={{
              values: { type: "stride", by: 1000 },
              gridLine: {
                stroke: { lineWidth: 0.5, dash: [4, 2] },
              },
              tick: { length: 6 },
              valueLabel: {
                format: "currency",
              },
            }}
          >
            <LineChart
              marks={sales.map(d => ({
                label: d.year,
                value: d.value,
                interpolationMethod: "catmullRom",
                symbol: "circle",
              }))}
            />
          </Chart>
        </Section>

        {/* 3. Explicit values + percent format — axis ticks pinned to specific values. */}
        <Section
          header={
            <Text font={"headline"}>3. Explicit values + percent labels</Text>
          }
        >
          <Chart
            frame={{ height: 220 }}
            chartYAxis={{
              values: { type: "values", values: [0, 0.1, 0.2, 0.3, 0.4, 0.5] },
              valueLabel: { format: "percent" },
            }}
          >
            <LineChart
              marks={growth.map(d => ({
                label: d.year,
                value: d.rate,
                interpolationMethod: "catmullRom",
                symbol: "circle",
              }))}
            />
          </Chart>
        </Section>

        {/* 4. Custom view label + bottom-positioned axis. Note: each tick re-renders the view. */}
        <Section
          header={
            <Text font={"headline"}>4. Custom view label (X axis)</Text>
          }
        >
          <Chart
            frame={{ height: 220 }}
            chartXAxis={{
              position: "bottom",
              gridLine: false,
              valueLabel: {
                multiLabelAlignment: "center",
                content: <Text
                  font={"caption2"}
                  fontWeight={"bold"}
                  foregroundStyle={"orange"}
                >YR</Text>,
              },
            }}
          >
            <BarChart marks={sales.map(d => ({ label: d.year, value: d.value }))} />
          </Chart>
        </Section>

        {/* 5. Hidden axes via the legacy Visibility token — still works. */}
        <Section
          header={
            <Text font={"headline"}>5. Hidden axes (legacy Visibility)</Text>
          }
        >
          <Chart
            frame={{ height: 200 }}
            chartXAxis={"hidden"}
            chartYAxis={"hidden"}
          >
            <LineChart
              marks={sales.map(d => ({
                label: d.year,
                value: d.value,
                interpolationMethod: "catmullRom",
              }))}
            />
          </Chart>
        </Section>

      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Views/Charts/Bar1DChart/index.md
---

# Bar1DChart

The `Bar1DChart` component renders a one-dimensional bar chart for comparing numerical values across discrete categories. Each bar represents a single category with its corresponding value, making it ideal for simple horizontal or vertical bar comparisons.

## Usage

```tsx
<Chart
  padding={0}
  frame={{ height: 400 }}
>
  <Bar1DChart
    marks={[
      { category: "Gadgets", value: 3800 },
      { category: "Gizmos", value: 4400 },
      { category: "Widgets", value: 6500 },
    ]}
  />
</Chart>
```

## Props

### `labelOnYAxis?: boolean`

If set to `true`, category labels will be displayed on the Y-axis and bars will be laid out horizontally.
Defaults to `false`, where labels appear on the X-axis and bars are rendered vertically.

### `marks: Array<object>` **(required)**

An array of data points defining each bar. Each mark includes:

- `category: string`
  The category label for the bar.

- `value: number`
  The numeric value represented by the bar length.

- Additional optional `ChartMarkProps`:
  Use `ChartMarkProps` to further style or annotate the bars, including:

  - `foregroundStyle`
  - `opacity`
  - `symbol`
  - `annotation`
  - `offset`
  - `zIndex`, etc.

## Example

```tsx
const data = [
  { type: "Gadgets", profit: 3800 },
  { type: "Gizmos", profit: 4400 },
  { type: "Widgets", profit: 6500 },
]

function Example() {
  return <NavigationStack>
    <VStack
      navigationTitle={"Bar1DChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        padding={0}
        frame={{ height: 400 }}
      >
        <Bar1DChart
          marks={data.map(item => ({
            category: item.type,
            value: item.profit,
          }))}
        />
      </Chart>
    </VStack>
  </NavigationStack>
}
```

## Run the Chart

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```

## Use Cases

`Bar1DChart` is best suited for:

- Comparing discrete values across categories
- Displaying ranked items or sorted values
- Visualizing simple datasets in a clear and minimal layout



---
url: /guide/Views/Charts/Bar1DChart/index_example.md
---

# Example

```tsx
import { Bar1DChart, Chart, Navigation, NavigationStack, Script, VStack } from "scripting"

const data = [
  { type: "Gadgets", profit: 3800 },
  { type: "Gizmos", profit: 4400 },
  { type: "Widgets", profit: 6500 },
]

function Example() {
  return <NavigationStack>
    <VStack
      navigationTitle={"Bar1DChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        padding={0}
        frame={{
          height: 400
        }}
      >
        <Bar1DChart
          marks={data.map(item => ({
            category: item.type,
            value: item.profit,
          }))}
        />
      </Chart>
    </VStack>
  </NavigationStack >
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/BarChart/index.md
---

# BarChart

The `BarChart` component renders a standard bar chart, enabling visual comparison of numeric values across different categories. Each bar corresponds to a label and represents its associated value through height (vertical layout) or length (horizontal layout).

## Example Scenario

This example displays the count of different toy shapes — `Cube`, `Sphere`, and `Pyramid`. The chart provides an optional toggle to switch between vertical and horizontal layouts using the `labelOnYAxis` property.

## Usage

```tsx
<Chart frame={{ height: 400 }}>
  <BarChart
    labelOnYAxis={false}
    marks={[
      { label: "Cube", value: 5 },
      { label: "Sphere", value: 4 },
      { label: "Pyramid", value: 4 },
    ]}
  />
</Chart>
```

## Props

### `labelOnYAxis?: boolean`

- If `true`, labels will be displayed on the **Y-axis**, and bars will be rendered **horizontally**.
- If `false` (default), labels appear on the **X-axis**, and bars are rendered **vertically**.

### `marks: Array<object>` **(required)**

Each data point defines a bar and includes:

- `label: string | Date`
  The name or identifier for the category.

- `value: number`
  The numeric value represented by the bar.

- `unit?: CalendarComponent` _(optional)_
  Used when displaying time-based values.

- Optional `ChartMarkProps`
  Provides additional customization, such as:

  - `foregroundStyle`
  - `opacity`
  - `cornerRadius`
  - `symbol`
  - `annotation`
  - etc.

## Example Code

```tsx
const toysData = [
  { type: "Cube", count: 5 },
  { type: "Sphere", count: 4 },
  { type: "Pyramid", count: 4 },
]

<BarChart
  marks={toysData.map(toy => ({
    label: toy.type,
    value: toy.count,
  }))}
/>
```

## Use Cases

The `BarChart` component is ideal for:

- Comparing values across discrete categories
- Displaying survey results, item counts, or rankings
- Switching between horizontal and vertical layouts with minimal configuration



---
url: /guide/Views/Charts/BarChart/index_example.md
---

# Example

```tsx
import { BarChart, Chart, List, Navigation, NavigationStack, Script, Section, Toggle, useState, } from "scripting"

type ToyShape = {
  type: string
  count: number
}

const toysData: ToyShape[] = [
  {
    type: "Cube",
    count: 5,
  },
  {
    type: "Sphere",
    count: 4,
  },
  {
    type: "Pyramid",
    count: 4
  }
]

function Example() {
  const [labelOnYAxis, setLabelOnYAxis] = useState(false)

  return <NavigationStack>
    <List
      navigationTitle={"BarChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section>
        <Toggle
          title={"labelOnYAxis"}
          value={labelOnYAxis}
          onChanged={setLabelOnYAxis}
        />
      </Section>
      <Chart
        chartXVisibleDomain={10}
        frame={{
          height: 400
        }}
      >
        <BarChart
          labelOnYAxis={labelOnYAxis}
          marks={toysData.map(toy => ({
            label: toy.type,
            value: toy.count,
          }))}
        />
      </Chart>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/BarGanttChart/index.md
---

# BarGanttChart

The `BarGanttChart` component visualizes time intervals across multiple categories, making it ideal for illustrating schedules, timelines, or task durations. It displays bars that span from a start to an end value on a continuous axis, grouped by labeled categories.

## Usage

```tsx
<Chart frame={{ height: 400 }}>
  <BarGanttChart
    labelOnYAxis
    marks={[
      { label: "Job 1", start: 0, end: 15 },
      { label: "Job 2", start: 5, end: 25 },
      ...
    ]}
  />
</Chart>
```

## Props

### `labelOnYAxis?: boolean`

If `true`, the category labels will be displayed on the **Y-axis**, and bars will extend horizontally along the X-axis (typical Gantt chart layout).
Default is `false`, which would render a vertical layout with labels on the X-axis.

### `marks: Array<object>` **(required)**

Defines the time intervals for each bar. Each object must include:

- `label: string`
  The category label associated with the time interval (e.g., task or job name).

- `start: number`
  The starting value (usually representing time or progress) of the bar.

- `end: number`
  The ending value of the bar. The bar will visually span from `start` to `end`.

Additional `ChartMarkProps` can also be provided for customization.

## Example

```tsx
const data = [
  { job: "Job 1", start: 0, end: 15 },
  { job: "Job 2", start: 5, end: 25 },
  { job: "Job 1", start: 20, end: 35 },
  { job: "Job 1", start: 40, end: 55 },
  { job: "Job 2", start: 30, end: 60 },
  { job: "Job 2", start: 30, end: 60 },
]

function Example() {
  return <NavigationStack>
    <VStack
      navigationTitle={"BarGanttChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart frame={{ height: 400 }}>
        <BarGanttChart
          labelOnYAxis
          marks={data.map(item => ({
            label: item.job,
            start: item.start,
            end: item.end,
          }))}
        />
      </Chart>
    </VStack>
  </NavigationStack>
}
```

## Execution

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```

## Use Cases

`BarGanttChart` is ideal for:

- Project planning and task scheduling
- Visualizing task overlaps and durations
- Representing resource allocation over time



---
url: /guide/Views/Charts/BarGanttChart/index_example.md
---

# Example

```tsx
import { BarGanttChart, Chart, Navigation, NavigationStack, Script, VStack } from "scripting"

const data = [
  { job: "Job 1", start: 0, end: 15 },
  { job: "Job 2", start: 5, end: 25 },
  { job: "Job 1", start: 20, end: 35 },
  { job: "Job 1", start: 40, end: 55 },
  { job: "Job 2", start: 30, end: 60 },
  { job: "Job 2", start: 30, end: 60 },
]

function Example() {
  return <NavigationStack>
    <VStack
      navigationTitle={"BarGanttChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        frame={{
          height: 400
        }}
      >
        <BarGanttChart
          labelOnYAxis
          marks={data.map(item => ({
            label: item.job,
            start: item.start,
            end: item.end
          }))}
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/BarGroupChart/index.md
---

# BarGroupChart

This example demonstrates how to create grouped bars in a `BarChart` by using the `positionBy` property to segment bars by a secondary dimension (e.g., "color") and `foregroundStyleBy` to apply distinct colors to each group. This pattern is useful when comparing subcategories within a larger category.

## Example Scenario

The dataset includes different object types (`Cube`, `Sphere`, `Pyramid`) grouped by color (`Green`, `Purple`, `Pink`, `Yellow`). The chart displays the count of each shape per color, with grouped and color-coded bars.

## Key Concepts

### `positionBy`

```ts
positionBy: {
  value: item.color,
  axis: 'horizontal',
}
```

- Groups bars by the specified `value` (e.g., color).
- The `axis` indicates how the bars are positioned:

  - `'horizontal'`: groups by Y-axis (stacked vertically within each color group).
  - `'vertical'`: groups by X-axis (used for transposed layouts).

### `foregroundStyleBy`

```ts
foregroundStyleBy: item.color
```

- Applies a unique foreground color to each bar based on the color group.
- This helps visually distinguish between grouped items.

## Code Summary

```tsx
const data = [
  { color: "Green", type: "Cube", count: 2 },
  { color: "Purple", type: "Sphere", count: 1 },
  ...
]

const list = data.map(item => ({
  label: item.type,              // Primary label (e.g., Cube, Sphere)
  value: item.count,             // Numeric value
  positionBy: {
    value: item.color,           // Grouping key
    axis: 'horizontal',
  },
  foregroundStyleBy: item.color, // Color grouping
  cornerRadius: 8,
}))
```

## Full Example

```tsx
<Chart frame={{ height: 400 }}>
  <BarChart marks={list} />
</Chart>
```

This chart will render vertical groups of bars by color (e.g., Green, Purple...), and each group will contain the respective shapes (Cube, Sphere, Pyramid) with the appropriate height and color.

## Use Cases

This grouped bar layout is ideal for:

- Comparing subcategories within grouped categories (e.g., survey responses by demographic).
- Visualizing segmented data distributions.
- Highlighting clusters of related values in a compact chart.



---
url: /guide/Views/Charts/BarGroupChart/index_example.md
---

# Example

```tsx
import { BarChart, BarChartProps, Button, Chart, Navigation, NavigationStack, Script, VStack, useMemo } from "scripting"

const data = [
  { color: "Green", type: "Cube", count: 2 },
  { color: "Green", type: "Sphere", count: 0 },
  { color: "Green", type: "Pyramid", count: 1 },
  { color: "Purple", type: "Cube", count: 1 },
  { color: "Purple", type: "Sphere", count: 1 },
  { color: "Purple", type: "Pyramid", count: 1 },
  { color: "Pink", type: "Cube", count: 1 },
  { color: "Pink", type: "Sphere", count: 2 },
  { color: "Pink", type: "Pyramid", count: 0 },
  { color: "Yellow", type: "Cube", count: 1 },
  { color: "Yellow", type: "Sphere", count: 1 },
  { color: "Yellow", type: "Pyramid", count: 2 },
]

function View() {
  // Access dismiss function.
  const dismiss = Navigation.useDismiss()

  const list = useMemo(() => {
    return data.map(item => ({
      label: item.type,
      value: item.count,
      positionBy: {
        value: item.color,
        axis: 'horizontal',
      },
      foregroundStyleBy: item.color,
      cornerRadius: 8,
    }) as BarChartProps["marks"][0])
  }, [])

  return <NavigationStack>
    <VStack
      navigationTitle="Page Title"
      navigationBarTitleDisplayMode="inline"
      toolbar={{
        topBarLeading: <Button
          title="Done"
          action={dismiss}
        />
      }}
    >
      <Chart
        frame={{
          height: 400
        }}
      >
        <BarChart
          marks={list}
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  // Present view.
  await Navigation.present({
    element: <View />
  })

  // Avoiding memory leaks.
  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/BarStackChart/index.md
---

# BarStackChart

The `BarStackChart` component renders grouped values as stacked bars, enabling visual comparison of cumulative totals and their individual components across categories. Each bar is split into colored segments that represent different subcategories within a shared label.

## Example Scenario

This example visualizes toy counts grouped by **type** (`Cube`, `Sphere`, `Pyramid`) and stacked by **color** (`Green`, `Purple`, `Pink`, `Yellow`). The stacked bar chart shows how each color contributes to the total count per shape.

## Usage

```tsx
<Chart frame={{ height: 400 }}>
  <BarStackChart
    labelOnYAxis={false}
    marks={[
      { label: "Cube", value: 2, category: "Green" },
      { label: "Cube", value: 1, category: "Purple" },
      ...
    ]}
  />
</Chart>
```

## Props

### `labelOnYAxis?: boolean`

- If `true`, category labels will be displayed on the **Y-axis**, rendering the bars horizontally.
- If `false` (default), labels appear on the **X-axis**, and bars are drawn vertically.

### `marks: Array<object>` **(required)**

Each mark represents a segment in the stacked bar and includes the following fields:

- `label: string | Date`
  The shared label used to group segments into one bar (e.g., "Cube", "Sphere").

- `category: string`
  The subcategory used to split the bar into segments (e.g., color groups like "Green", "Pink").

- `value: number`
  The numeric value for this segment.

- `unit?: CalendarComponent`
  _(Optional)_ Used when rendering time-based charts.

- Additional optional `ChartMarkProps`
  For customizing appearance, including:

  - `foregroundStyle`
  - `cornerRadius`
  - `symbol`
  - `annotation`
  - etc.

## Full Example

```tsx
const data = [
  { color: "Green", type: "Cube", count: 2 },
  { color: "Purple", type: "Cube", count: 1 },
  ...
]

<BarStackChart
  labelOnYAxis={labelOnYAxis}
  marks={data.map(item => ({
    label: item.type,
    value: item.count,
    category: item.color,
  }))}
/>
```

## Dynamic Layout Toggle

The example also includes a toggle to switch between vertical and horizontal layouts using `labelOnYAxis`.

## Execution

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}
```

## Use Cases

`BarStackChart` is ideal for:

- Showing composition of totals across categories
- Comparing group contributions visually
- Displaying part-to-whole relationships over multiple items



---
url: /guide/Views/Charts/BarStackChart/index_example.md
---

# Example

```tsx
import { BarStackChart, Chart, List, Navigation, NavigationStack, Script, Section, Toggle, useState, } from "scripting"

type ToyShape = {
  color: string
  type: string
  count: number
}

const toyWithColorData: ToyShape[] = [
  { color: "Green", type: "Cube", count: 2 },
  { color: "Green", type: "Sphere", count: 0 },
  { color: "Green", type: "Pyramid", count: 1 },
  { color: "Purple", type: "Cube", count: 1 },
  { color: "Purple", type: "Sphere", count: 1 },
  { color: "Purple", type: "Pyramid", count: 1 },
  { color: "Pink", type: "Cube", count: 1 },
  { color: "Pink", type: "Sphere", count: 2 },
  { color: "Pink", type: "Pyramid", count: 0 },
  { color: "Yellow", type: "Cube", count: 1 },
  { color: "Yellow", type: "Sphere", count: 1 },
  { color: "Yellow", type: "Pyramid", count: 2 },
]

function Example() {
  const [labelOnYAxis, setLabelOnYAxis] = useState(false)

  return <NavigationStack>
    <List
      navigationTitle={"BarStackChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section>
        <Toggle
          title={"labelOnYAxis"}
          value={labelOnYAxis}
          onChanged={setLabelOnYAxis}
        />
      </Section>
      <Chart
        frame={{
          height: 400
        }}
      >
        <BarStackChart
          labelOnYAxis={labelOnYAxis}
          marks={toyWithColorData.map(toy => ({
            label: toy.type,
            value: toy.count,
            category: toy.color,
          }))}
        />
      </Chart>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/Chart Overlay & Range Selection/index.md
---

# Chart Overlay & Range Selection

This example demonstrates four chart interaction / customization features:

- **`ChartOverlay`** — a reader-style child of `<Chart>` that gives custom content access to a `ChartProxy` for hit-testing, value↔coordinate conversion, and reading the plot area frame. Mirrors SwiftUI Charts' `chartOverlay(alignment:content:) { proxy in ... }`.
- **Range selection** — pass `from` / `to` (instead of `value`) to `chartXSelection` / `chartYSelection` and the bridge wires up SwiftUI's `chartXSelection(range:)` / `chartYSelection(range:)` overload.
- **`ChartGesture`** — another reader-style child of `<Chart>`. The closure returns any `Gesture` descriptor and receives a writable `ChartProxy` so you can drive selection with custom gestures (e.g. single-finger drag-range on a categorical String axis). Mirrors `chartGesture(_:) { proxy in ... }`.
- **`ChartPlotStyle`** — a reader-style child whose closure builds a chain of plot-area modifiers (background / border / frame / shadow / corner radius / clip shape / opacity). Mirrors `chartPlotStyle { plot in plot.background(...).border(...) }`.

***

## ChartOverlay quick reference

```tsx
import { Chart, ChartOverlay, ChartProxy } from "scripting"

<Chart>
  <BarChart marks={...} />
  <ChartOverlay alignment={"topLeading"}>
    {(proxy: ChartProxy) => (
      // Render any view on top of the chart.
      // proxy.value / proxy.position / proxy.plotAreaSize are available here.
    )}
  </ChartOverlay>
</Chart>
```

`ChartProxy` is synchronous and returns `null` when the type token does not match the chart's actual axis data type:

```ts
interface ChartProxy {
  // Read: lookup / position / plot area
  value(args: { atX?: number; atY?: number; as: 'string' | 'number' | 'date' })
    : string | number | Date | null
  position(args: { x?: string | number | Date; y?: string | number | Date })
    : { x: number; y: number } | null
  readonly plotAreaSize: { width: number; height: number }
  readonly plotAreaFrame: { x: number; y: number; width: number; height: number }

  // Write: drive selection (use inside <ChartGesture>)
  selectXRange(args: { from: number; to: number }): void
  selectYRange(args: { from: number; to: number }): void
  selectXValue(args: { at: number }): void
  selectYValue(args: { at: number }): void
  selectAngleValue(args: { atRadians: number }): void
}
```

***

## Range selection quick reference

```tsx
const [range, setRange] = useState<{ from: string; to: string } | null>(null)

<Chart
  chartXSelection={{
    valueType: "string",
    from: range?.from,
    to: range?.to,
    onChanged: setRange,
  }}
>
  ...
</Chart>
```

- The bridge dispatches on the **presence of `from` / `to`** to pick the SwiftUI `chartXSelection(range:)` overload. Single-value selection (`value` + `onChanged`) keeps working unchanged.
- `valueType: 'string' | 'number' | 'date'` — must match the chart's plotted axis data type.
- `onChanged` fires whenever the selection changes and again with `null` when the selection is cleared.

> **Axis-type constraint**: range selection only works on **continuous axes** (number / date). On categorical String axes SwiftUI Charts neither responds to the default range gesture nor reverse-maps screen-pixel coordinates back to a category, so even `<ChartGesture>` + `proxy.selectXRange(...)` cannot drive a String-axis range. For String axes use the single-value form (`ChartSelection`) instead.

### Activation gesture (platform-specific)

`chartXSelection(range:)` default gesture differs by platform — **this is a SwiftUI Charts SDK behaviour, not a bridge limitation**:

- **iOS**: a **two-finger tap** on the chart. In iOS Simulator, hold **⌥ Option** while clicking the chart to simulate a two-finger touch.
- **macOS**: a **drag gesture**.

Single-finger long-press-and-drag does NOT trigger range selection by default. If you need a single-finger interaction or any custom activation, use `<ChartGesture>` to take over the chart's gesture handling.

Sources: [Mastering charts in SwiftUI · Selection](https://swiftwithmajid.com/2023/07/18/mastering-charts-in-swiftui-selection/), [WWDC23 · Explore pie charts and interactivity in Swift Charts](https://developer.apple.com/videos/play/wwdc2023/10037/).

The two forms are mutually exclusive on a given axis. Use a single-value selection for tap interactions, and the range form for drag-to-zoom or drag-to-summarize gestures.

***

## Axis-label precision (ChartAxisLabelFormat)

In addition to the short string tokens (`'number' | 'percent' | 'currency' | 'date' | 'time' | 'dateTime'`), the `valueLabel.format` field of `chartXAxis` / `chartYAxis` accepts a native `ChartAxisLabelFormat` instance. Use it when you need fraction-digit precision, a fixed currency code, or a non-default date / time style — mirrors SwiftUI Foundation's `FormatStyle` family.

```tsx
<Chart chartYAxis={{
  valueLabel: {
    format: ChartAxisLabelFormat.currency({ currencyCode: "CNY", fractionDigits: 2 })
  }
}}>
  ...
</Chart>
```

Available factories:

| Factory                                | Plottable | Options                                                                             |
| -------------------------------------- | --------- | ----------------------------------------------------------------------------------- |
| `ChartAxisLabelFormat.number({...})`   | `Double`  | `fractionDigits` (max) / `minFractionDigits` (min)                                  |
| `ChartAxisLabelFormat.percent({...})`  | `Double`  | same as number (`0.42` → `42%`)                                                     |
| `ChartAxisLabelFormat.currency({...})` | `Double`  | `fractionDigits` / `minFractionDigits` / `currencyCode` (defaults to device locale) |
| `ChartAxisLabelFormat.date({...})`     | `Date`    | `dateStyle`: `omitted` / `numeric` / `abbreviated` / `long` / `complete`            |
| `ChartAxisLabelFormat.time({...})`     | `Date`    | `timeStyle`: `omitted` / `shortened` / `standard` / `complete`                      |
| `ChartAxisLabelFormat.dateTime({...})` | `Date`    | both `dateStyle` and `timeStyle`                                                    |

> Short string tokens stay fully supported; pick whichever fits. Use the class when you need precision / currency / style; otherwise the concise `format: 'number'` form is plenty.

***

## ChartGesture quick reference

```tsx
import { Chart, ChartGesture, DragGesture } from "scripting"

<Chart
  chartXSelection={{ valueType: "number", from, to, onChanged: setRange }}
>
  ...marks...
  <ChartGesture>
    {(proxy) =>
      DragGesture({ minDistance: 0 })
        .onChanged(v => proxy.selectXRange({
          from: v.startLocation.x,
          to: v.location.x,
        }))
    }
  </ChartGesture>
</Chart>
```

- The closure returns a `Gesture` descriptor (`DragGesture()` / `TapGesture()` / `LongPressGesture()` / `MagnifyGesture()` / `RotateGesture()`), equivalent to SwiftUI's `chartGesture { proxy in ... }`.
- `proxy.selectXRange / selectYRange / selectXValue / selectYValue / selectAngleValue` accept **screen-space pixel coordinates** (not data values) — feed `DragGesture` event `startLocation.x` / `location.x` directly without reverse-mapping.
- After writing the selection, the matching `chartXSelection / chartYSelection / chartAngleSelection` binding fires `onChanged` with the bound data values.
- Only the first `<ChartGesture>` child of a chart is used (same rule as `<ChartOverlay>`).
- Use this to **replace** the default gesture (single-finger drag, custom activation, etc.).
- **Axis-type constraint**: same as the default range gesture — only number / date axes are supported. On categorical String axes the SDK can't reverse-map pixels back to a category, so `proxy.selectXRange` on a String axis won't fire `onChanged`.

***

## ChartPlotStyle quick reference

```tsx
import { Chart, ChartPlotStyle } from "scripting"

<Chart>
  <BarChart marks={...} />
  <ChartPlotStyle>
    {(plot) =>
      plot
        .background({ color: "gray", opacity: 0.1 })
        .border({ color: "gray", width: 1 })
        .frame({ height: 240 })
    }
  </ChartPlotStyle>
</Chart>
```

The closure receives an empty `ChartPlotProxy` and must return a (possibly transformed) `ChartPlotProxy`. Each chained call returns a new immutable proxy and accumulates an op; the bridge replays the ops on the real `ChartPlotContent` view inside `chartPlotStyle { plot in ... }`.

Available builder methods:

| Method             | Args                                                                   | Maps to                                         |
| ------------------ | ---------------------------------------------------------------------- | ----------------------------------------------- |
| `.background(arg)` | `Color` string, `Material` token, or `{ color?, material?, opacity? }` | `.background(...)`                              |
| `.border(arg)`     | `{ color?, width? }`                                                   | `.border(color, width:)`                        |
| `.frame(arg)`      | `{ width?, height? }`                                                  | `.frame(width:height:)`                         |
| `.padding(arg?)`   | `number` / `EdgeInsets` / `{ horizontal?, vertical? }` / no-arg        | `.padding(...)`                                 |
| `.cornerRadius(r)` | `number`                                                               | `.clipShape(RoundedRectangle(cornerRadius: r))` |
| `.opacity(v)`      | `number`                                                               | `.opacity(v)`                                   |
| `.shadow(arg)`     | `{ color?, radius?, x?, y? }`                                          | `.shadow(color:radius:x:y:)`                    |
| `.clipShape(arg)`  | `'capsule'` / `'rect'` / `{ rounded: <radius> }`                       | `.clipShape(...)`                               |

`Material` tokens: `'ultraThin'` / `'thin'` / `'regular'` / `'thick'` / `'ultraThick'` / `'bar'` (suffix `Material` is also accepted, e.g. `'regularMaterial'`).

> Like `<ChartOverlay>` and `<ChartGesture>`, only the FIRST `<ChartPlotStyle>` child of a chart is honored. The closure body must remain pure — `setState` calls inside will trigger an infinite chart-rebuild loop. Use it as a pure builder.

***

## Mark Accessibility

Each mark accepts three optional VoiceOver fields directly on its `ChartMarkProps`:

```tsx
<BarChart
  marks={data.map(d => ({
    label: d.year,
    value: d.sales,
    accessibilityLabel: `Year ${d.year}`,
    accessibilityValue: `${d.sales} dollars`,
    // accessibilityHidden: true,  // exclude this mark entirely
  }))}
/>
```

| Field                           | Maps to                                     | Effect                                                                                    |
| ------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `accessibilityLabel?: string`   | `.accessibilityLabel(_:)` on `ChartContent` | Overrides the SDK's default label (which is synthesized from the mark's plotted values).  |
| `accessibilityValue?: string`   | `.accessibilityValue(_:)`                   | Sets the spoken value separately from the label.                                          |
| `accessibilityHidden?: boolean` | `.accessibilityHidden(_:)`                  | When `true`, the mark is excluded from the VoiceOver tree (won't be focusable or spoken). |

These work on every mark type (`BarMark`, `LineMark`, `PointMark`, `RuleMark`, `RectangleMark`, `AreaMark`, sectors, ...) and are applied through the same `ChartContent.applyModifiers` path as `foregroundStyle` / `opacity` / etc.

> Test on a real device or in Simulator with `Settings → Accessibility → VoiceOver`. Swipe on the chart, then swipe right between marks to hear the labels you set.

***

## Pitfalls

- **`ChartOverlay` proxy is `null` on the very first synchronous render.** `<ChartOverlay>` falls back to `EmptyView` until SwiftUI has built the chart and injected a real proxy. Build for that case in your render function.
- **`SelectedRange / selectedRangeAxis` are NOT exposed on `ChartProxy`.** SwiftUI Charts does not surface range-selection state through `ChartProxy` — observe it through the `chartXSelection(range:)` / `chartYSelection(range:)` binding instead. The TS interface deliberately omits these.
- **`chartOverlay` does not have a `spacing` parameter.** Only `alignment` is supported (matches the SwiftUI API).
- **Keep overlay content cheap.** SwiftUI rebuilds the overlay closure every time the chart re-renders. Avoid heavy work or async kick-off inside.
- **`<ChartGesture>` / `<ChartOverlay>` closure body MUST stay pure.** SwiftUI Charts re-runs the closure on every chart rebuild; calling `setState` inside the body triggers a React re-render → another chart rebuild → the closure runs again → **infinite loop**. Push state changes into the gesture's `onChanged / onEnded` callbacks (which are user-event triggered) instead.
- **The `<ChartGesture>` closure must return a `GestureInfo`** (the value returned by `DragGesture()` / `TapGesture()` / etc.). Returning `null` or any other type is silently ignored.



---
url: /guide/Views/Charts/Chart Overlay & Range Selection/index_example.md
---

# Example

```tsx
import { BarChart, Chart, ChartGesture, ChartOverlay, ChartPlotStyle, Color, DragGesture, GeometryReader, LineChart, Navigation, NavigationStack, PointChart, Rectangle, RoundedRectangle, RuleLineForLabelChart, Script, ScrollView, Spacer, Text, useState, VStack, ZStack } from "scripting"

const data = [
  { year: '2020', sales: 1200 },
  { year: '2021', sales: 1400 },
  { year: '2022', sales: 2000 },
  { year: '2023', sales: 2500 },
  { year: '2024', sales: 3600 },
]

function Example() {
  // Section 1 — single-value selection (existing API; shown alongside overlay-driven tooltip).
  const [hover, setHover] = useState<string | null>(null)
  const hoverPoint = hover != null ? data.find(d => d.year === hover) : null

  // Section 2 — range selection on a NUMERIC X axis (categorical String axes do
  // NOT respond to range-selection gestures in SwiftUI Charts; SDK limitation).
  const [range, setRange] = useState<{ from: number; to: number } | null>(null)
  const [rawDetails, setRawDetails] = useState<string>("(awaiting range gesture)")
  const inRangeIdx = (i: number) =>
    range != null && i >= range.from && i <= range.to

  // Section 3 — single-finger drag-range via <ChartGesture>. We feed pixel coords to
  // proxy.selectXRange so it works on a continuous axis even WITHOUT the SDK's default
  // two-finger gesture. Only number / date axes are supported; categorical String axes
  // can't reverse-map pixels back to a category, so they don't work even via this path.
  const [gestureRange, setGestureRange] = useState<{ from: number; to: number } | null>(null)
  const inGestureRange = (i: number) =>
    gestureRange != null && i >= gestureRange.from && i <= gestureRange.to

  return <NavigationStack>
    <ScrollView>
      <VStack
        navigationTitle={"Chart Overlay & Range Selection"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={32}
        padding
      >

        {/* 1. ChartOverlay: hit-test → custom tooltip */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. ChartOverlay tooltip (hit-test via ChartProxy)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}
            styledText={{
              content: [
                {
                  content: "Tap or drag on the chart. The overlay reads the X coordinate via",
                  font: "caption",
                  foregroundColor: "secondaryLabel",
                },
                {
                  content: " proxy.value({atX, as: 'string'})",
                  font: "caption",
                  foregroundColor: "label",
                  monospaced: true,
                },
                {
                  content: "and draws a custom annotation.",
                  font: "caption",
                  foregroundColor: "secondaryLabel",
                },
              ]
            }}
          />
          <Chart
            frame={{ height: 240 }}
            chartXSelection={{
              value: hover,
              onChanged: (v: any) => {
                setHover(v ?? null)
              },
              valueType: "string",
            }}
          >
            <LineChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                interpolationMethod: "catmullRom",
                symbol: "circle",
                // VoiceOver 三件套：以 mark 为单位 override SDK 默认拼接的 label/value。
                // 开启 VoiceOver 后，左右滑动每个圆点会朗读这里的字符串而不是默认的 "Year 2024 Sales 3600"。
                accessibilityLabel: `Year ${d.year}`,
                accessibilityValue: `${d.sales} dollars`,
              }))}
            />
            {hoverPoint != null
              ? <RuleLineForLabelChart
                marks={[{
                  label: hoverPoint.year,
                  foregroundStyle: { color: "gray", opacity: 0.4 },
                }]}
              />
              : null}
            <ChartOverlay alignment={"topLeading"}>
              {(proxy) => (
                hoverPoint == null
                  ? <Spacer />
                  : <ZStack
                    padding={6}
                    background={
                      <RoundedRectangle cornerRadius={4} fill={"regularMaterial"} />
                    }
                  >
                    <Text font={"caption2"}>
                      {hoverPoint.year}: ${hoverPoint.sales}
                    </Text>
                  </ZStack>
              )}
            </ChartOverlay>
          </Chart>
        </VStack>

        {/* 2. Range selection: NUMERIC X axis (PointChart). String axes do not respond. */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Range selection (chartXSelection range form)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            On iOS, the default range-selection gesture is a TWO-FINGER tap on the chart
            (in Simulator: hold ⌥ Option then click). On macOS it's a drag.
            Selected: {range == null ? "(none)" : `${range.from} → ${range.to}`}
          </Text>
          <Text font={"caption2"} foregroundStyle={"orange"} monospaced>
            raw onChanged details: {rawDetails}
          </Text>
          <Chart
            frame={{ height: 240 }}
            chartXSelection={{
              valueType: "number",
              from: range?.from,
              to: range?.to,
              onChanged: (v: any) => {
                setRawDetails(JSON.stringify(v))
                setRange(v)
              },
            }}
          >
            <PointChart
              marks={data.map((d, i) => ({
                x: i,
                y: d.sales,
                foregroundStyle: inRangeIdx(i) ? "orange" : "gray",
                symbolSize: inRangeIdx(i) ? 120 : 60,
              }))}
            />
          </Chart>
        </VStack>

        {/* 3. Single-finger drag-range via <ChartGesture> (number axis). */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. Single-finger drag-range (chartGesture)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Drag with a single finger anywhere on the chart — covered points turn orange.
            chartGesture takes over the chart's gesture handling, so this works without the
            two-finger default. Pair with chartXSelection(range:) to get bound data values.
            {"\n"}Selected: {gestureRange == null ? "(none)" : `${gestureRange.from} → ${gestureRange.to}`}
          </Text>
          <Chart
            frame={{ height: 240 }}
            chartXSelection={{
              valueType: "number",
              from: gestureRange?.from,
              to: gestureRange?.to,
              onChanged: setGestureRange,
            }}
          >
            <PointChart
              marks={data.map((d, i) => ({
                x: i,
                y: d.sales,
                foregroundStyle: inGestureRange(i) ? "orange" : "blue",
                symbolSize: inGestureRange(i) ? 120 : 60,
              }))}
            />
            <ChartGesture>
              {(proxy) =>
                DragGesture({ minDistance: 0 })
                  .onChanged(v => proxy.selectXRange({
                    from: v.startLocation.x,
                    to: v.location.x,
                  }))
              }
            </ChartGesture>
          </Chart>
        </VStack>

        {/* 4. ChartAxisLabelFormat — Y 轴用 currency / number 精度形态 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>4. ChartAxisLabelFormat (axis label precision)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Two charts share the same data; the only difference is the Y-axis valueLabel.format.
            Top chart uses the short token "currency" (default fraction digits, device locale).
            Bottom chart uses ChartAxisLabelFormat.currency with explicit fractionDigits + currencyCode.
          </Text>

          <Text font={"caption2"} foregroundStyle={"label"}>
            Top: format: 'currency'
          </Text>
          <Chart
            frame={{ height: 180 }}
            chartYAxis={{
              valueLabel: {
                format: 'currency',
              },
            }}
          >
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "blue",
              }))}
            />
          </Chart>

          <Text font={"caption2"} foregroundStyle={"label"}>
            Bottom: format: ChartAxisLabelFormat.currency({"{"} currencyCode: "CNY", fractionDigits: 2 {"}"})
          </Text>
          <Chart
            frame={{ height: 180 }}
            chartYAxis={{
              valueLabel: {
                format: ChartAxisLabelFormat.currency({
                  currencyCode: "CNY",
                  fractionDigits: 2,
                }),
              },
            }}
          >
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "orange",
              }))}
            />
          </Chart>

          <Text font={"caption2"} foregroundStyle={"label"}>
            Plain number with one fraction digit:
          </Text>
          <Chart
            frame={{ height: 180 }}
            chartYAxis={{
              valueLabel: {
                format: ChartAxisLabelFormat.number({
                  fractionDigits: 1,
                  minFractionDigits: 1,
                }),
              },
            }}
          >
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "green",
              }))}
            />
          </Chart>
        </VStack>

        {/* 5. ChartPlotStyle — plot 区域自定义视觉 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>5. ChartPlotStyle (custom plot-area styling)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            ChartPlotStyle is a reader-style child whose closure receives a builder proxy.
            Each chained call accumulates an op (background / border / frame / shadow / ...);
            on the Swift side the bridge replays the ops on the real ChartPlotContent view.
          </Text>

          <Text font={"caption2"} foregroundStyle={"label"}>
            5a. background + border (gray fill, 1pt gray outline):
          </Text>
          <Chart frame={{ height: 180 }}>
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "blue",
              }))}
            />
            <ChartPlotStyle>
              {(plot) =>
                plot
                  .background({ color: "gray", opacity: 0.12 })
                  .border({ color: "gray", width: 1 })
              }
            </ChartPlotStyle>
          </Chart>

          <Text font={"caption2"} foregroundStyle={"label"}>
            5b. material background + corner radius (regularMaterial, 12pt rounded corners):
          </Text>
          <Chart frame={{ height: 180 }}>
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "orange",
              }))}
            />
            <ChartPlotStyle>
              {(plot) =>
                plot
                  .background({ material: "regularMaterial" })
                  .cornerRadius(12)
              }
            </ChartPlotStyle>
          </Chart>

          <Text font={"caption2"} foregroundStyle={"label"}>
            5c. shadow + frame (drop shadow + fixed plot height):
          </Text>
          <Chart frame={{ height: 200 }}>
            <BarChart
              marks={data.map(d => ({
                label: d.year,
                value: d.sales,
                foregroundStyle: "green",
              }))}
            />
            <ChartPlotStyle>
              {(plot) =>
                plot
                  .background({ color: "white" })
                  .shadow({ color: "gray", radius: 6, x: 0, y: 2 })
                  .frame({ height: 140 })
              }
            </ChartPlotStyle>
          </Chart>
        </VStack>

      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Views/Charts/Chart Scroll Target Behavior/index.md
---

# Chart Scroll Target Behavior

`chartScrollTargetBehavior` controls where a chart's scroll _parks_ when the user lifts a finger after a swipe. Without it, scrolling a chart with `chartScrollableAxes` feels free-form — release the gesture mid-scroll and the leading edge can sit on any pixel. With it, scroll deceleration always lands on a meaningful data boundary (a day, a week, an integer index, ...).

Mirrors SwiftUI Charts' `chartScrollTargetBehavior(.valueAligned(...))`. Only the `valueAligned` form is bridged — there's no `paging` shortcut on Chart in SwiftUI either; what people usually mean by "paging" is `valueAligned(... majorAlignment: .page)`.

***

## API

```ts
chartScrollTargetBehavior?: ChartScrollTargetBehavior

type ChartScrollTargetBehavior = {
  unit?: number           // numeric axis: snap step
  matching?: DateComponents // date axis: snap step
  majorAlignment?: 'page' | 'unit' | { unit: number } | { matching: DateComponents }
}
```

- **`unit` / `matching` are mutually exclusive.** Pick `unit` for a numeric x axis, `matching` for a date x axis. Mixing both is not supported.
- **`matching` expects a `DateComponents` instance** (the global `new DateComponents({...})` exposed by the bridge — same class used for notifications/triggers). Pass `{ day: 1 }` for "snap by day", `{ day: 7 }` for "snap by week", `{ month: 1 }` for "snap by month", etc.
- **`majorAlignment` is the secondary "page" snap.** SwiftUI Charts uses it to decide where larger paging boundaries sit (e.g. snap by day, but page by month — releasing a longer swipe always parks at month edges).
  - `'page'` — major boundaries at viewport-page edges.
  - `'unit'` — no separate major alignment; reuses the primary step. (This is the SDK default; passing `'unit'` is the same as omitting `majorAlignment`.)
  - `{ unit: N }` — major boundaries every N numeric units (only valid when the primary step is `unit`).
  - `{ matching: DateComponents }` — major boundaries on those calendar boundaries (only valid when the primary step is `matching`).

> The bridge silently drops a cross-form `majorAlignment` (e.g. `{ unit: 7 }` paired with a `matching: ...` primary), since SwiftUI Charts' `MajorValueAlignment<Value>` is statically typed.

***

## Required pairings

`chartScrollTargetBehavior` does nothing on its own. Pair it with:

- **`chartScrollableAxes`** — turns scrolling on. Without it the chart just renders the full domain at once; there's nothing to snap.
- **`chartXVisibleDomain`** (or `chartYVisibleDomain` for vertical) — fixes the visible window's size in data units. Determines what counts as a "page" for `majorAlignment: 'page'`.

```tsx
<Chart
  chartScrollableAxes={"horizontal"}
  chartXVisibleDomain={86400 * 14}     // 14 days visible
  chartScrollTargetBehavior={{
    matching: new DateComponents({ day: 1 }),
    majorAlignment: { matching: new DateComponents({ month: 1 }) },
  }}
>
  ...
</Chart>
```

***

## Recipes

```tsx
// Date axis, snap daily, page by month
chartScrollTargetBehavior={{
  matching: new DateComponents({ day: 1 }),
  majorAlignment: { matching: new DateComponents({ month: 1 }) },
}}

// Date axis, snap weekly, page by viewport
chartScrollTargetBehavior={{
  matching: new DateComponents({ day: 7 }),
  majorAlignment: 'page',
}}

// Numeric axis, snap to integer index, page by viewport
chartScrollTargetBehavior={{
  unit: 1,
  majorAlignment: 'page',
}}

// Date axis, just snap by day, no major alignment override (SDK default)
chartScrollTargetBehavior={{
  matching: new DateComponents({ day: 1 }),
}}
```

***

## Pitfalls

- **Categorical (String) axes are not supported.** SwiftUI Charts' `ValueAligned` requires `Plottable + Numeric` (numeric axes) or `Date` (date axes). On a String x axis the modifier silently does nothing. To get a numeric x axis with `BarChart` / `LineChart` you need a `Date` label; for pure numeric x, use `PointChart` (whose marks are `{ x: number, y: number }`).
- **`unit` is in _data units_, not pixels.** For a Double axis, `unit: 1` means "snap every 1 unit on the chart's data domain". For a date axis, you must use `matching` instead.
- **`majorAlignment` defaults to `'unit'` when omitted.** Pass `'page'` explicitly if you want page-level snapping.
- **`chartXVisibleDomain` must be set for paging to feel right.** Without an explicit visible domain, the SDK picks one and your "page" boundaries will land in unexpected places.
- **Set `unit: 'day'` (etc.) on each mark for date-axis charts.** That's a property on the _mark itself_ (`ChartMarkProps.unit`), unrelated to `chartScrollTargetBehavior`. Without it Charts logs `Falling back to a fixed dimension size for a mark. Consider adding unit to the data...` and bars/lines render at a fixed pixel width that may not match the date stride. Match the `unit` on marks to the smallest sensible granularity of your data (typically `'day'` for daily data, `'hour'` for hourly, etc.).



---
url: /guide/Views/Charts/Chart Scroll Target Behavior/index_example.md
---

# Example

```tsx
import { BarChart, Chart, LineChart, Navigation, NavigationStack, PointChart, Script, ScrollView, Text, VStack } from "scripting"

// 60 天的"日访问量"假数据，用于演示 date 轴按日 stop / 按月 major 对齐。
const dailyData: { date: Date; visits: number }[] = (() => {
  const arr: { date: Date; visits: number }[] = []
  const start = new Date(2026, 0, 1) // 2026-01-01
  for (let i = 0; i < 60; i++) {
    const d = new Date(start.getTime() + i * 86400_000)
    // 简单合成的波动 + 偶尔尖峰
    const base = 200 + Math.round(Math.sin(i / 4) * 60)
    const spike = i % 9 === 0 ? 120 : 0
    arr.push({ date: d, visits: base + spike })
  }
  return arr
})()

// 60 个连续 index 的"评分"假数据，演示 numeric 轴按 unit=1 stop / page 主对齐。
const numericData: { x: number; y: number }[] = Array.from({ length: 60 }, (_, i) => ({
  x: i,
  y: 50 + Math.round(Math.cos(i / 3) * 25 + (i % 7 === 0 ? 18 : 0)),
}))

function Example() {
  return <NavigationStack>
    <ScrollView>
      <VStack
        navigationTitle={"Chart Scroll Target Behavior"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={28}
        padding
      >

        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          chartScrollTargetBehavior tells SwiftUI Charts where to "park" the scroll deceleration.
          Without it, scrolling a chart with chartScrollableAxes feels free-form; with it, releasing
          a swipe lands on a meaningful data boundary (a day, a month, an integer index).
          {"\n\n"}
          Pair it with chartScrollableAxes (otherwise the chart isn't scrollable, and snapping has
          nothing to act on) and chartXVisibleDomain (controls how much of the data is visible at
          once — also determines what counts as a "page").
        </Text>

        {/* 1. 日期轴：按日 stop，按月 major 对齐 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. Date axis — daily stops, monthly major</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            60 days of synthetic visit data. Swipe horizontally; release and the visible window
            should snap so the leading edge sits on a day boundary, with month edges acting as the
            larger "page" alignment.
          </Text>
          <Chart
            frame={{ height: 220 }}
            chartScrollableAxes={"horizontal"}
            chartXVisibleDomain={86400 * 14}
            chartScrollTargetBehavior={{
              matching: new DateComponents({ day: 1 }),
              majorAlignment: { matching: new DateComponents({ month: 1 }) },
            }}
            chartXAxis={{
              valueLabel: { format: "date" },
            }}
          >
            <LineChart
              marks={dailyData.map(d => ({
                label: d.date,
                value: d.visits,
                // unit: "day" 告诉 Charts 每个 mark 在 X 轴上占多大 —— 否则 SDK 会回落到固定像素宽度
                // 并 log "Falling back to a fixed dimension size for a mark"。
                unit: "day",
                interpolationMethod: "monotone",
                foregroundStyle: "blue",
              }))}
            />
          </Chart>
        </VStack>

        {/* 2. 日期轴：按周 stop（page 主对齐） */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Date axis — weekly stops, page major</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Same data, but stops snap on weekly boundaries (every 7 days) and the major alignment is
            the visible page. Useful when you want exactly N visible weeks per "page".
          </Text>
          <Chart
            frame={{ height: 220 }}
            chartScrollableAxes={"horizontal"}
            chartXVisibleDomain={86400 * 21}
            chartScrollTargetBehavior={{
              matching: new DateComponents({ day: 7 }),
              majorAlignment: "page",
            }}
            chartXAxis={{
              valueLabel: { format: "date" },
            }}
          >
            <BarChart
              marks={dailyData.map(d => ({
                label: d.date,
                value: d.visits,
                unit: "day",
                foregroundStyle: "orange",
              }))}
            />
          </Chart>
        </VStack>

        {/* 3. 数值轴：按 1 unit stop，page 主对齐 —— 必须用 numeric x 的 mark（PointChart），
            BarChart 的 label 是 string/Date，会走 categorical 轴，chartScrollTargetBehavior 在
            categorical 轴上不生效（SDK 限制）。 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. Numeric axis — unit stops, page major</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Numeric x axis (0..59). Each scroll deceleration snaps so the leading edge lands on an
            integer; major alignment is the visible page (10 units wide). Note: this requires a
            numeric-x mark (PointChart), since BarChart's `label` field becomes a categorical String
            axis on which chartScrollTargetBehavior is silently no-op.
          </Text>
          <Chart
            frame={{ height: 220 }}
            chartScrollableAxes={"horizontal"}
            chartXVisibleDomain={10}
            chartScrollTargetBehavior={{
              unit: 1,
              majorAlignment: "page",
            }}
          >
            <PointChart
              marks={numericData.map(d => ({
                x: d.x,
                y: d.y,
                foregroundStyle: "green",
                symbolSize: 80,
              }))}
            />
          </Chart>
        </VStack>

      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Views/Charts/DonutChart/index.md
---

# DonutChart

The `DonutChart` component displays data as a circular ring divided into segments, where each segment’s angle represents a proportion of the whole. It is ideal for visualizing part-to-whole relationships with an inner radius that distinguishes it from a traditional pie chart.

## Props

### `marks: Array<object>` **(required)**

Each mark represents a sector (slice) of the donut chart and includes the following properties:

***

### `category: string`

A label representing the category for the segment (e.g., product name, region).

### `value: number`

Determines the angular size of the segment. The segment’s angle will be proportional to this value in relation to the total of all segments.

***

### `innerRadius?: MarkDimension`

Defines the **inner radius** of the donut.
This determines the size of the "hole" in the center.

- Format:

  ```ts
  {
    type: 'ratio' | 'inset';
    value: number;
  }
  ```

- `type: 'ratio'`
  The radius is a ratio (e.g., `0.618`) of the outer radius.

- `type: 'inset'`
  The radius is an absolute inset in points from the outer radius.

***

### `outerRadius?: MarkDimension`

Defines the **outer radius** of the segment.
Controls how far each segment extends from the center.

- Format:

  ```ts
  {
    type: 'inset';
    value: number;
  }
  ```

- `type: 'inset'`
  Specifies how much to inset the outer edge from the edge of the chart’s plot area.

***

### `angularInset?: number`

Optional gap (in degrees) between each segment.
This controls how rounded or spaced out each slice appears.

***

### Inherited from `ChartMarkProps`

You can also use all styling and behavior properties from `ChartMarkProps`, including:

- `foregroundStyle` – sets the color of each slice
- `annotation` – attaches labels or icons
- `opacity`, `cornerRadius`, `offset`, `shadow`, etc.

## Example

```tsx
<DonutChart
  marks={data.map(item => ({
    category: item.name,
    value: item.sales,
    innerRadius: {
      type: 'ratio',
      value: 0.618
    },
    outerRadius: {
      type: 'inset',
      value: 10
    },
    angularInset: 1
  }))}
/>
```

## Use Cases

- Showing sales distribution across products
- Visualizing market share or demographic segments
- Comparing multiple values as part of a total



---
url: /guide/Views/Charts/DonutChart/index_example.md
---

# Example

```tsx
import { Chart, DonutChart, Navigation, NavigationStack, Script, VStack } from "scripting"

let data = [
  { name: "Cachapa", sales: 9631 },
  { name: "Crêpe", sales: 6959 },
  { name: "Injera", sales: 4891 },
  { name: "Jian Bing", sales: 2506 },
  { name: "American", sales: 1777 },
  { name: "Dosa", sales: 625 },
]

function Example() {
  return <NavigationStack>
    <VStack
      navigationTitle={"DonutChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        frame={{
          height: 300
        }}
      >
        <DonutChart
          marks={
            data.map(item => ({
              category: item.name,
              value: item.sales,
              innerRadius: {
                type: 'ratio',
                value: 0.618
              },
              outerRadius: {
                type: 'inset',
                value: 10,
              },
              angularInset: 1,
            }))
          }
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/HeatMapChart/index.md
---

# HeatMapChart

The `HeatMapChart` component displays data values as a grid of cells, where the color intensity of each cell represents the magnitude of a numeric value. It is ideal for visualizing bivariate data distributions or correlations across two categorical dimensions.

## Usage Example

```tsx
<Chart
  aspectRatio={{
    value: 1,
    contentMode: 'fit'
  }}
>
  <HeatMapChart
    marks={[
      { x: "+", y: "+", value: 125 },
      { x: "+", y: "-", value: 10 },
      { x: "-", y: "-", value: 80 },
      { x: "-", y: "+", value: 1 },
    ]}
  />
</Chart>
```

## Props

### `marks: Array<object>` **(required)**

Each item in the array represents a single cell in the heatmap, defined by its X/Y coordinates and a value that determines the cell's color intensity.

#### Fields:

- `x: string`
  The horizontal coordinate (e.g., category or label on the X-axis).

- `y: string`
  The vertical coordinate (e.g., category or label on the Y-axis).

- `value: number`
  A numeric value used to determine the color intensity of the cell. Higher values typically produce darker or more saturated colors.

- Inherits all `ChartMarkProps` for styling and customization, such as:

  - `foregroundStyle`
  - `opacity`
  - `annotation`
  - `cornerRadius`
  - `zIndex`, etc.

## Use Cases

`HeatMapChart` is suitable for:

- Displaying correlation matrices
- Analyzing two-dimensional categorical data
- Visualizing frequency, density, or performance across paired factors

## Full Example

```tsx
const data = [
  { positive: "+", negative: "+", num: 125 },
  { positive: "+", negative: "-", num: 10 },
  { positive: "-", negative: "-", num: 80 },
  { positive: "-", negative: "+", num: 1 },
]

<HeatMapChart
  marks={data.map(item => ({
    x: item.positive,
    y: item.negative,
    value: item.num,
  }))}
/>
```



---
url: /guide/Views/Charts/HeatMapChart/index_example.md
---

# Example

```tsx
import { Chart, HeatMapChart, Navigation, NavigationStack, Script, VStack } from "scripting"

const data = [
  { positive: "+", negative: "+", num: 125 },
  { positive: "+", negative: "-", num: 10 },
  { positive: "-", negative: "-", num: 80 },
  { positive: "-", negative: "+", num: 1 },
]

function Example() {

  return <NavigationStack>
    <VStack
      navigationTitle={"HeatMapChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        aspectRatio={{
          value: 1,
          contentMode: 'fit'
        }}
      >
        <HeatMapChart
          marks={
            data.map(item => ({
              x: item.positive,
              y: item.negative,
              value: item.num,
            }))
          }
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/LineCategoryChart/index.md
---

# LineCategoryChart

The `LineCategoryChart` component displays multiple line series categorized by a secondary key, allowing you to compare trends across distinct groups (categories) along a shared axis of discrete labels.

It is ideal for grouped comparisons across labeled segments (e.g., departments, months, stages) and is especially useful for showing how each category's values evolve over the same set of labels.

***

## Example Scenario

In this example, different departments (`Production`, `Marketing`, `Finance`) are plotted along the X-axis, and each product category (`Gizmos`, `Gadgets`, `Widgets`) is represented by its own line.

***

## Usage

```tsx
<LineCategoryChart
  labelOnYAxis={false}
  marks={[
    { label: "Production", value: 4000, category: "Gizmos" },
    { label: "Marketing", value: 2000, category: "Gizmos" },
    ...
  ]}
/>
```

***

## Props

### `labelOnYAxis?: boolean`

- If `true`, the category labels (e.g., "Production", "Marketing") are displayed on the **Y-axis**, and the lines are drawn **horizontally**.
- If `false` (default), labels are on the **X-axis**, and lines are rendered **vertically**.

***

### `marks: Array<object>` **(required)**

Each item defines a data point on the chart. It must include:

- `label: string | Date`
  The shared axis label (e.g., phase, department, month) across which each line progresses.

- `value: number`
  The value to be plotted at that label for the corresponding category.

- `category: string`
  Defines the group to which this point belongs. Each `category` generates its own line.

Additional fields from `ChartMarkProps` may also be used for styling (e.g., `foregroundStyle`, `symbol`, `annotation`).

***

## Full Example

```tsx
const data = [
  { label: "Production", value: 4000, category: "Gizmos" },
  { label: "Marketing", value: 2000, category: "Gizmos" },
  { label: "Finance", value: 2000.5, category: "Gizmos" },

  { label: "Production", value: 5000, category: "Gadgets" },
  { label: "Marketing", value: 1000, category: "Gadgets" },
  { label: "Finance", value: 3000, category: "Gadgets" },

  { label: "Production", value: 6000, category: "Widgets" },
  { label: "Marketing", value: 5000.9, category: "Widgets" },
  { label: "Finance", value: 5000, category: "Widgets" },
]

<LineCategoryChart
  labelOnYAxis={labelOnYAxis}
  marks={data}
/>
```

***

## Use Cases

`LineCategoryChart` is useful for:

- Visualizing grouped comparisons across discrete stages
- Showing category trends over consistent labels
- Comparing multi-line metrics in business, finance, marketing, etc.



---
url: /guide/Views/Charts/LineCategoryChart/index_example.md
---

# Example

```tsx
import { Chart, LineCategoryChart, List, Navigation, NavigationStack, Script, Section, Toggle, useState } from "scripting"

const data = [
  { label: "Production", value: 4000, category: "Gizmos" },
  { label: "Production", value: 5000, category: "Gadgets" },
  { label: "Production", value: 6000, category: "Widgets" },
  { label: "Marketing", value: 2000, category: "Gizmos" },
  { label: "Marketing", value: 1000, category: "Gadgets" },
  { label: "Marketing", value: 5000.9, category: "Widgets" },
  { label: "Finance", value: 2000.5, category: "Gizmos" },
  { label: "Finance", value: 3000, category: "Gadgets" },
  { label: "Finance", value: 5000, category: "Widgets" },
]

function Example() {
  const [labelOnYAxis, setLabelOnYAxis] = useState(false)

  return <NavigationStack>
    <List
      navigationTitle={"LineCategoryChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section>
        <Toggle
          title={"labelOnYAxis"}
          value={labelOnYAxis}
          onChanged={setLabelOnYAxis}
        />
      </Section>
      <Chart
        frame={{
          height: 300
        }}
      >
        <LineCategoryChart
          labelOnYAxis={labelOnYAxis}
          marks={data}
        />
      </Chart>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/LineChart/index.md
---

# LineChart

The `LineChart` component renders a single continuous line across discrete labeled points. It is useful for visualizing simple trends or progressions where each data point is mapped to a category or label.

It shares the same API as `BarChart` and is ideal for basic one-line comparisons over labeled axes.

***

## Example Scenario

This example visualizes the count of different toy shapes (`Cube`, `Sphere`, `Pyramid`) using a single line. The user can toggle between horizontal and vertical layouts using `labelOnYAxis`.

***

## Usage

```tsx
<Chart>
  <LineChart
    labelOnYAxis={false}
    marks={[
      { label: "Cube", value: 5 },
      { label: "Sphere", value: 4 },
      { label: "Pyramid", value: 4 },
    ]}
  />
</Chart>
```

***

## Props

### `labelOnYAxis?: boolean`

- When `true`, category labels are shown on the **Y-axis**, and the line is plotted **horizontally**.
- When `false` (default), labels appear on the **X-axis**, and the line is plotted **vertically**.

***

### `marks: Array<object>` **(required)**

Each item defines a point on the line:

- `label: string | Date`
  The axis label corresponding to the point (e.g., category, time, name).

- `value: number`
  The numeric value for this point.

- Optional fields from `ChartMarkProps` can also be applied:

  - `foregroundStyle`
  - `symbol`
  - `annotation`
  - `cornerRadius`
  - `opacity`, etc.

***

## Full Example

```tsx
const toysData = [
  { type: "Cube", count: 5 },
  { type: "Sphere", count: 4 },
  { type: "Pyramid", count: 4 },
]

<LineChart
  marks={toysData.map(toy => ({
    label: toy.type,
    value: toy.count,
  }))}
/>
```

***

## Use Cases

`LineChart` is useful for:

- Showing a basic trend or progression over a labeled axis
- Comparing changes across a single dimension
- Minimal visualizations with one continuous line



---
url: /guide/Views/Charts/LineChart/index_example.md
---

# Example

```tsx
import { Chart, LineChart, List, Navigation, NavigationStack, Script, Section, Toggle, useState, } from "scripting"

type ToyShape = {
  type: string
  count: number
}

const toysData: ToyShape[] = [
  {
    type: "Cube",
    count: 5,
  },
  {
    type: "Sphere",
    count: 4,
  },
  {
    type: "Pyramid",
    count: 4
  }
]

function Example() {
  const [labelOnYAxis, setLabelOnYAxis] = useState(false)

  return <NavigationStack>
    <List
      navigationTitle={"LineChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section>
        <Toggle
          title={"labelOnYAxis"}
          value={labelOnYAxis}
          onChanged={setLabelOnYAxis}
        />
      </Section>
      <Chart>
        <LineChart
          labelOnYAxis={labelOnYAxis}
          marks={toysData.map(toy => ({
            label: toy.type,
            value: toy.count,
          }))}
        />
      </Chart>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/LinePlot & AreaPlot (function curves)/index.md
---

# LinePlot & AreaPlot (function curves)

`LinePlot` / `AreaPlot` (iOS 18+) plot a smooth curve / area from a **JS function**, not from a data array. SwiftUI Charts samples the function on each chart layout (≈ viewport-width samples) and renders a continuous curve.

The bridge wires the JS callback through `emitWidgetEventSync` (the same channel used for synchronous gesture / drop callbacks), so each sample is one JSCore round-trip.

> **iOS 17 fallback**: the bridge logs an `API deprecated` warning and renders nothing for this mark. Other marks in the same chart still work.

***

## API — three forms

### 1. Single-variable `y = fn(x)`

```tsx
<LinePlot
  x="X"
  y="Y"
  domain={[0, Math.PI * 4]}        // optional
  fn={(x) => Math.sin(x)}
/>
```

- `domain` is optional. Omit to let the chart's visible x domain drive sampling.
- `fn(x: number) => number`. Return `NaN` / non-finite → SwiftUI Charts skips that sample.

### 2. Parametric `(x, y) = fn(t)`

```tsx
<LinePlot
  x="X" y="Y" t="t"
  domain={[0, Math.PI * 2]}        // required for parametric form
  fn={(t) => ({ x: Math.cos(t), y: Math.sin(t) })}
/>
```

- Bridge dispatches on the presence of `t`.
- `domain` is **required** here (the parametric form has no implicit visible-domain fallback).
- `fn` must return `{ x, y }`. Missing fields → that sample is dropped (NaN).

### 3. AreaPlot `(yStart, yEnd) = fn(x)`

```tsx
<AreaPlot
  x="X" yStart="lo" yEnd="hi"
  domain={[0, Math.PI * 4]}        // optional
  fn={(x) => ({ yStart: Math.sin(x) - 0.5, yEnd: Math.sin(x) + 0.5 })}
/>
```

- Fills the vertical band between `yStart` and `yEnd`. Common use: confidence band / envelope.

All three forms accept the standard `ChartMarkProps` (`foregroundStyle` / `opacity` / `lineStyle` / `interpolationMethod` / `accessibilityLabel` / ...) like any other mark — they're applied through the same `applyModifiers` path.

***

## Performance and correctness

- **Pure functions only.** SwiftUI Charts re-runs the closure on every chart layout. Calling `setState` or any other React state mutation inside `fn` triggers an infinite layout loop (same trap as `<ChartGesture>` / `<ChartOverlay>` / `<ChartPlotStyle>` closure bodies).
- **Each sample is a JSCore call (\~5µs).** A 400-pixel-wide chart re-samples ≈ 400 times per layout, ≈ 2 ms. Fine for static / occasionally-updating charts; visible jank on continuous scroll / pinch / per-frame state updates.
- **Stabilize React re-renders.** Each React render that touches the LinePlot's parent rebuilds the `fn` reference, gives it a new bridge callback id, and forces SwiftUI to fully re-layout. `useCallback` keeps the JS reference stable, but does **not** prevent SwiftUI from re-laying out; the bridge still mints a new SwiftUI `LinePlot` value each render. To minimize re-renders, lift state out of the chart tree or memoize the surrounding component.
- **Callback-id accumulation.** Currently every render registers a fresh callback id; old ids stay in the per-component map until the parent component unmounts. For long-lived charts with frequent updates the map grows by O(renders × plots). Acceptable for typical usage but watch out in scrubbing-heavy UIs.
- **Errors / non-finite.** Throwing inside `fn`, returning `undefined`, or returning `NaN` / `Infinity` → bridge substitutes `Double.nan` and SwiftUI Charts skips that sample. Don't rely on this for control flow; design `fn` to be total over its domain.
- **`@Sendable` thread.** SwiftUI Charts marks the closure `@Sendable`; in practice it's invoked on the main thread (where JSContext lives). The bridge `assert`s this. If a future SDK version starts dispatching off-main, the assert will catch it.

***

## See also

- `ChartGesture` — for closures driven by user gestures (pure-body rule applies the same way).
- `ChartPlotStyle` — another reader-style mark child whose closure is repeatedly evaluated.



---
url: /guide/Views/Charts/LinePlot & AreaPlot (function curves)/index_example.md
---

# Example

```tsx
import { AreaPlot, Chart, LinePlot, Navigation, NavigationStack, Script, ScrollView, Text, useState, VStack } from "scripting"

function Example() {
  // Drive amplitude with state to show that SwiftUI Charts re-samples the fn on every render.
  const [amplitude, setAmplitude] = useState(1)

  return <NavigationStack>
    <ScrollView>
      <VStack
        navigationTitle={"LinePlot & AreaPlot"}
        navigationBarTitleDisplayMode={"inline"}
        spacing={28}
        padding
      >

        <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
          LinePlot / AreaPlot are Chart marks introduced in iOS 18+. You pass a JS function
          (not an array of samples); SwiftUI Charts samples it across the viewport at layout
          time and connects the points into a curve.
          {"\n\n"}
          The fn closure must stay pure (no setState, no external side effects). SwiftUI
          Charts re-samples it hundreds of times per layout pass, and each sample is one
          JSCore call — keep the body cheap.
        </Text>

        {/* 1. Single variable y = fn(x) */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>1. y = sin(x) — single variable</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            domain [0, 4π]. Toggle the link below to change the amplitude and watch the
            whole curve re-render (every render re-samples the function).
          </Text>
          <Chart frame={{ height: 220 }}>
            <LinePlot
              x={"X"}
              y={"Y"}
              domain={[0, Math.PI * 4]}
              fn={(x) => amplitude * Math.sin(x)}
              foregroundStyle={"blue"}
            />
          </Chart>
          <Text font={"caption2"}>amplitude: {amplitude.toFixed(2)}</Text>
          {/* Minimal amplitude toggle */}
          <Text
            foregroundStyle={"link"}
            onTapGesture={() => setAmplitude(amplitude === 1 ? 1.6 : 1)}
          >
            tap to toggle amplitude (1 ↔ 1.6)
          </Text>
        </VStack>

        {/* 2. Parametric curve (x, y) = fn(t) */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>2. Parametric — circle (cos t, sin t)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            t ∈ [0, 2π]. fn returns a {`{ x, y }`} tuple, which the bridge converts to
            SwiftUI's (x: Double, y: Double) tuple. Traces a full circle.
          </Text>
          <Chart
            frame={{ height: 240, width: 240 }}
            chartXScale={{ from: -1.2, to: 1.2 }}
            chartYScale={{ from: -1.2, to: 1.2 }}
          >
            <LinePlot
              x={"X"}
              y={"Y"}
              t={"t"}
              domain={[0, Math.PI * 2]}
              fn={(t) => ({ x: Math.cos(t), y: Math.sin(t) })}
              foregroundStyle={"orange"}
            />
          </Chart>
        </VStack>

        {/* 3. AreaPlot — vertical band */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>3. AreaPlot — sin envelope ±0.5</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            fn returns {`{ yStart, yEnd }`}, and AreaPlot fills the vertical interval from
            yStart to yEnd at every x — typical use cases are confidence bands and envelopes.
          </Text>
          <Chart frame={{ height: 220 }}>
            <AreaPlot
              x={"X"}
              yStart={"lo"}
              yEnd={"hi"}
              domain={[0, Math.PI * 4]}
              fn={(x) => ({
                yStart: Math.sin(x) - 0.5,
                yEnd: Math.sin(x) + 0.5,
              })}
              foregroundStyle={{ color: "green", opacity: 0.35 }}
            />
            <LinePlot
              x={"X"}
              y={"Y"}
              domain={[0, Math.PI * 4]}
              fn={(x) => Math.sin(x)}
              foregroundStyle={"green"}
            />
          </Chart>
        </VStack>

      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()

```



---
url: /guide/Views/Charts/Multiple Charts Example/index.md
---

# Multiple Charts Example

This example demonstrates how to combine multiple chart types in a single chart context, dynamically display annotations based on user interaction, and customize appearance and interactivity using chart overlays.

## Example Code

```tsx
const data = [
  { sales: 1200, year: '2020', growth: 0.14, },
  { sales: 1400, year: '2021', growth: 0.16, },
  { sales: 2000, year: '2022', growth: 0.42, },
  { sales: 2500, year: '2023', growth: 0.25, },
  { sales: 3600, year: '2024', growth: 0.44, },
]

function Example() {
  const [chartSelection, setChartSelection] = useState<string | null>()
  const selectedItem = useMemo(() => {
    if (chartSelection == null) {
      return null
    }
    return data.find(item => item.year === chartSelection)
  }, [chartSelection])

  return <NavigationStack>
    <VStack
      navigationTitle={"Multiple Charts"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Text>
        Press and move on the chart to view the details.
      </Text>
      <Chart
        frame={{
          height: 300,
        }}
        chartXSelection={{
          value: chartSelection,
          onChanged: setChartSelection,
          valueType: "string"
        }}
      >
        <LineChart
          marks={data.map(item => ({
            label: item.year,
            value: item.sales,
            interpolationMethod: "catmullRom",
            symbol: "circle",
          }))}
        />
        <AreaChart
          marks={data.map(item => ({
            label: item.year,
            value: item.sales,
            interpolationMethod: "catmullRom",
            foregroundStyle: ["rgba(255,100,0,1)", "rgba(255,100,0,0.2)"]
          }))}
        />
        {selectedItem != null
          ? <RuleLineForLabelChart
            marks={[{
              label: selectedItem.year,
              foregroundStyle: { color: "gray", opacity: 0.5 },
              annotation: {
                position: "top",
                overflowResolution: {
                  x: "fit",
                  y: "disabled"
                },
                content: <ZStack
                  padding
                  background={
                    <RoundedRectangle
                      cornerRadius={4}
                      fill={"regularMaterial"}
                    />
                  }
                >
                  <Text
                    foregroundStyle={"white"}
                  >Sales: {selectedItem.sales}</Text>
                </ZStack>
              }
            }]}
          />
          : null}
      </Chart>
    </VStack>
  </NavigationStack>
}
```

## Overview

The example uses the following components together:

- [`LineChart`](#linechart): Plots discrete points and connects them with curved lines.
- [`AreaChart`](#areachart): Fills the area under a line graph, visually indicating magnitude.
- [`RuleLineForLabelChart`](#rulelineforlabelchart): Draws a reference line at the selected label and overlays a custom annotation.
- `chartXSelection`: Enables user interaction by tracking X-axis selection.

***

## Data Format

The dataset used represents yearly sales performance:

```ts
const data = [
  { sales: 1200, year: '2020', growth: 0.14 },
  { sales: 1400, year: '2021', growth: 0.16 },
  { sales: 2000, year: '2022', growth: 0.42 },
  { sales: 2500, year: '2023', growth: 0.25 },
  { sales: 3600, year: '2024', growth: 0.44 },
]
```

Each entry includes:

- `sales`: Numeric value to be plotted
- `year`: Used as the label on the X-axis
- `growth`: Additional metric (not directly visualized here)

***

## Key Features

### Chart Selection

```tsx
chartXSelection={{
  value: chartSelection,
  onChanged: setChartSelection,
  valueType: "string"
}}
```

- Enables users to tap or drag on the chart to select a point based on its label (`year`).
- Triggers the `setChartSelection` callback to update the selected year.

### LineChart

```tsx
<LineChart
  marks={data.map(item => ({
    label: item.year,
    value: item.sales,
    interpolationMethod: "catmullRom",
    symbol: "circle",
  }))}
/>
```

- Plots sales values with labeled X-axis.
- Uses `"catmullRom"` for smooth curves between points.
- Displays circular symbols for each point.

### AreaChart

```tsx
<AreaChart
  marks={data.map(item => ({
    label: item.year,
    value: item.sales,
    interpolationMethod: "catmullRom",
    foregroundStyle: ["rgba(255,100,0,1)", "rgba(255,100,0,0.2)"]
  }))}
/>
```

- Overlays a filled area beneath the line, enhancing visual weight.
- Uses a two-stop gradient from solid to transparent orange.

### RuleLineForLabelChart (Dynamic Annotation)

```tsx
<RuleLineForLabelChart
  marks={[{
    label: selectedItem.year,
    foregroundStyle: { color: "gray", opacity: 0.5 },
    annotation: {
      position: "top",
      overflowResolution: { x: "fit", y: "disabled" },
      content: <ZStack
        padding
        background={<RoundedRectangle cornerRadius={4} fill={"regularMaterial"} />}
      >
        <Text foregroundStyle={"white"}>Sales: {selectedItem.sales}</Text>
      </ZStack>
    }
  }]}
/>
```

- Shows a vertical gray reference line at the selected year.
- Displays a floating tooltip with the `sales` value in a styled background.
- Uses `ZStack` and `RoundedRectangle` to build a custom annotation view.

***

## User Interaction Flow

1. The user touches the chart.
2. The closest label (`year`) is selected and passed to `chartSelection`.
3. `selectedItem` is computed using `useMemo`.
4. A rule line is rendered at the selected label.
5. A floating annotation displays detailed data (e.g., `Sales: 2500`).

***

## Conclusion

This example demonstrates how to:

- Combine multiple charts (`LineChart`, `AreaChart`, `RuleLineForLabelChart`) within a single `<Chart>` container.
- Use `chartXSelection` to enable touch-based exploration.
- Render contextual annotations that enhance data storytelling.
- Apply modern styling using gradient fills, translucent overlays, and SwiftUI-inspired layout components.

This pattern is ideal for dashboards and interactive reports where data insight and responsiveness are key.



---
url: /guide/Views/Charts/Multiple Charts Example/index_example.md
---

# Example

```tsx
import { AreaChart, Chart, LineChart, Navigation, NavigationStack, RoundedRectangle, RuleLineForLabelChart, Script, Text, useMemo, useState, VStack, ZStack } from "scripting"

const data = [
  { sales: 1200, year: '2020', growth: 0.14, },
  { sales: 1400, year: '2021', growth: 0.16, },
  { sales: 2000, year: '2022', growth: 0.42, },
  { sales: 2500, year: '2023', growth: 0.25, },
  { sales: 3600, year: '2024', growth: 0.44, },
]

function Example() {
  const [chartSelection, setChartSelection] = useState<string | null>()
  const selectedItem = useMemo(() => {
    if (chartSelection == null) {
      return null
    }
    return data.find(item => item.year === chartSelection)
  }, [chartSelection])

  return <NavigationStack>
    <VStack
      navigationTitle={"Multiple Charts"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Text>
        Press and move on the chart to view the details.
      </Text>
      <Chart
        frame={{
          height: 300,
        }}
        chartXSelection={{
          value: chartSelection,
          onChanged: setChartSelection,
          valueType: "string"
        }}
      >
        <LineChart
          marks={data.map(item => ({
            label: item.year,
            value: item.sales,
            interpolationMethod: "catmullRom",
            symbol: "circle",
          }))}
        />
        <AreaChart
          marks={data.map(item => ({
            label: item.year,
            value: item.sales,
            interpolationMethod: "catmullRom",
            foregroundStyle: ["rgba(255,100,0,1)", "rgba(255,100,0,0.2)"]
          }))}
        />
        {selectedItem != null
          ? <RuleLineForLabelChart
            marks={[{
              label: selectedItem.year,
              foregroundStyle: { color: "gray", opacity: 0.5 },
              annotation: {
                position: "top",
                overflowResolution: {
                  x: "fit",
                  y: "disabled"
                },
                content: <ZStack
                  padding
                  background={
                    <RoundedRectangle
                      cornerRadius={4}
                      fill={"regularMaterial"}
                    />
                  }
                >
                  <Text
                    foregroundStyle={"white"}
                  >Sales: {selectedItem.sales}</Text>
                </ZStack>
              }
            }]}
          />
          : null}
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/PieChart/index.md
---

# PieChart

The `PieChart` component displays part-to-whole relationships using circular slices. Each slice represents a category, and its angle is proportional to the numeric value it contributes to the total.

This chart is well-suited for visualizing distribution, market share, or proportions across categories.

***

## Usage Example

```tsx
<PieChart
  marks={[
    { category: "Cachapa", value: 9631 },
    { category: "Crêpe", value: 6959 },
    { category: "Injera", value: 4891 },
    ...
  ]}
/>
```

***

## Props

### `marks: Array<object>` **(required)**

Defines the segments (slices) of the pie chart.

Each mark must include:

- `category: string`
  A label for the slice. It identifies the category the value belongs to.

- `value: number`
  The numeric value used to determine the slice’s angle. All values are summed and each slice’s angle is proportional to its fraction of the total.

- Inherits additional properties from `ChartMarkProps` for styling:

  - `foregroundStyle` – set color per category
  - `annotation` – attach labels or icons
  - `opacity`, `cornerRadius`, `zIndex`, etc.

***

## Full Example

```tsx
const data = [
  { name: "Cachapa", sales: 9631 },
  { name: "Crêpe", sales: 6959 },
  { name: "Injera", sales: 4891 },
  { name: "Jian Bing", sales: 2506 },
  { name: "American", sales: 1777 },
  { name: "Dosa", sales: 625 },
]

<PieChart
  marks={data.map(item => ({
    category: item.name,
    value: item.sales
  }))}
/>
```

***

## Use Cases

`PieChart` is suitable for:

- Displaying proportions across a fixed set of categories
- Visualizing market share, vote distribution, or sales ratios
- Representing totals broken down by labeled segments



---
url: /guide/Views/Charts/PieChart/index_example.md
---

# Example

```tsx
import { Chart, Navigation, NavigationStack, PieChart, Script, VStack } from "scripting"

let data = [
  { name: "Cachapa", sales: 9631 },
  { name: "Crêpe", sales: 6959 },
  { name: "Injera", sales: 4891 },
  { name: "Jian Bing", sales: 2506 },
  { name: "American", sales: 1777 },
  { name: "Dosa", sales: 625 },
]

function Example() {

  return <NavigationStack>
    <VStack
      navigationTitle={"PieChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        frame={{
          height: 300
        }}
      >
        <PieChart
          marks={
            data.map(item => ({
              category: item.name,
              value: item.sales,
            }))
          }
        />
      </Chart>
    </VStack>
  </NavigationStack>
}


async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/PointCategoryChart/index.md
---

# PointCategoryChart

The `PointCategoryChart` component displays categorized points on a 2D plane, allowing for flexible visual encoding using color, symbol type, or symbol size. It is ideal for representing multi-category scatter plots, surveys, or segmented data comparisons.

***

## Usage Example

```tsx
<PointCategoryChart
  representsDataUsing="foregroundStyle"
  marks={[
    { category: "Apple", x: 10, y: 42 },
    { category: "Apple", x: 20, y: 37 },
    { category: "Orange", x: 30, y: 62 },
    ...
  ]}
/>
```

***

## Props

### `marks: Array<object>` **(required)**

Each mark defines a data point on the chart and must include:

- `x: number`
  The value on the horizontal axis (e.g., age, time, score).

- `y: number`
  The value on the vertical axis (e.g., quantity, percentage).

- `category: string`
  A grouping key. Each category may be visually differentiated using color, symbol, or size.

- Additional optional properties from `ChartMarkProps` can be used for further customization:

  - `foregroundStyle`
  - `symbol`
  - `symbolSize`
  - `annotation`
  - `opacity`, etc.

***

### `representsDataUsing?: "foregroundStyle" | "symbol" | "symbolSize"`

Controls how the chart visually distinguishes different categories:

- `"foregroundStyle"` – uses different colors per category.
- `"symbol"` – uses different shapes (e.g., circles, squares) per category.
- `"symbolSize"` – varies the size of symbols based on the category (or data magnitude).

> This is an alternative to setting `foregroundStyleBy`, `symbolBy`, or `symbolSizeBy` manually.

***

## Full Example

```tsx
const favoriteFruitsData = [
  { fruit: "Apple", age: 10, count: 42 },
  { fruit: "Apple", age: 20, count: 37 },
  ...
]

<PointCategoryChart
  representsDataUsing="symbol"
  marks={favoriteFruitsData.map(item => ({
    category: item.fruit,
    x: item.age,
    y: item.count,
  }))}
/>
```

You can dynamically switch how data is represented using a `<Picker>` and bind it to the `representsDataUsing` prop.

***

## Use Cases

`PointCategoryChart` is suitable for:

- Comparing multiple categories over time or value ranges
- Visualizing multivariate distributions
- Highlighting categorical distinctions within scatter plots



---
url: /guide/Views/Charts/PointCategoryChart/index_example.md
---

# Example

```tsx
import { Chart, List, Navigation, NavigationStack, Picker, PointCategoryChart, Script, Text, useState, VStack } from "scripting"

const favoriteFruitsData = [
  { fruit: 'Apple', age: 10, count: 42 },
  { fruit: 'Apple', age: 20, count: 37 },
  { fruit: 'Apple', age: 30, count: 11 },

  { fruit: 'Bananer', age: 10, count: 23 },
  { fruit: 'Bananer', age: 20, count: 58 },
  { fruit: 'Bananer', age: 30, count: 79 },

  { fruit: 'Orange', age: 10, count: 36 },
  { fruit: 'Orange', age: 20, count: 24 },
  { fruit: 'Orange', age: 30, count: 62 },
]

function Example() {
  const [representsDataUsing, setRepresentsDataUsing] = useState<string>('foregroundStyle')
  const options: string[] = [
    'foregroundStyle',
    'symbol',
    'symbolSize'
  ]

  return <NavigationStack>
    <List
      navigationTitle={"PointCategoryChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Picker
        title={"representsDataUsing"}
        value={representsDataUsing}
        onChanged={setRepresentsDataUsing}
        pickerStyle={"menu"}
      >
        {options.map(option =>
          <Text tag={option}>{option}</Text>
        )}
      </Picker>
      <Chart
        frame={{
          height: 300
        }}
      >
        <PointCategoryChart
          representsDataUsing={representsDataUsing as any}
          marks={favoriteFruitsData.map(item => ({
            category: item.fruit,
            x: item.age,
            y: item.count,
          }))}
        />
      </Chart>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/PointChart/index.md
---

# PointChart

The `PointChart` component renders a basic 2D scatter plot, plotting individual points on an X-Y coordinate system. Each point is defined by a pair of numeric values and can be customized using standard mark styling properties.

This chart is ideal for visualizing correlations, distributions, or individual measurements across two continuous dimensions.

***

## Usage Example

```tsx
<PointChart
  marks={[
    { x: 0, y: 2 },
    { x: 1, y: 3 },
    { x: 2, y: 4 },
    { x: 3, y: 3 },
    { x: 4, y: 6 },
  ]}
/>
```

***

## Props

### `marks: Array<object>` **(required)**

Defines the set of points to render. Each point must include:

- `x: number`
  The X-axis coordinate.

- `y: number`
  The Y-axis coordinate.

You may also use additional `ChartMarkProps` to customize the appearance of each point:

- `symbol` – the shape of the plotted point (e.g., circle, square)
- `foregroundStyle` – sets the color of the point
- `symbolSize` – adjusts the size of each point
- `opacity`, `annotation`, `offset`, `zIndex`, etc.

***

## Full Example

```tsx
const data = [
  { x: 0, y: 2 },
  { x: 1, y: 3 },
  { x: 2, y: 4 },
  { x: 3, y: 3 },
  { x: 4, y: 6 },
]

<PointChart marks={data} />
```

The above example plots five points on a chart, creating a simple scatter plot.

***

## Use Cases

`PointChart` is suitable for:

- Plotting relationships between two continuous variables
- Displaying experimental measurements, coordinates, or trends
- Creating simple scatter plots with optional visual annotations



---
url: /guide/Views/Charts/PointChart/index_example.md
---

# Example

```tsx
import { Chart, Navigation, NavigationStack, PointChart, Script, VStack } from "scripting"

const data = [
  { x: 0, y: 2 },
  { x: 1, y: 3 },
  { x: 2, y: 4 },
  { x: 3, y: 3 },
  { x: 4, y: 6 },
]

function Example() {

  return <NavigationStack>
    <VStack
      navigationTitle={"PointChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        frame={{
          height: 300
        }}>
        <PointChart
          marks={data}
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/RangeAreaChart/index.md
---

# RangeAreaChart

The `RangeAreaChart` component displays a shaded area between a range of values for each data point, typically between a `start` and `end` value. It is ideal for visualizing value intervals, such as temperature ranges, confidence intervals, or min/max ranges over time.

***

## Usage Example

```tsx
<RangeAreaChart
  marks={[
    { label: "Jan", start: 0, end: 4 },
    { label: "Feb", start: 2, end: 6 },
    ...
  ]}
/>
```

***

## Props

### `marks: Array<object>` **(required)**

Each `mark` defines the area range for one category.

- `label: string | Date`
  The X-axis label (e.g., month, category name, time).

- `start: number`
  The lower boundary of the range.

- `end: number`
  The upper boundary of the range.

- _(Optional)_ properties from `ChartMarkProps`:

  - `foregroundStyle` – fill color of the area
  - `opacity`, `interpolationMethod`, `annotation`, etc.

***

### `interpolationMethod?: string`

Specifies how the area curve is drawn between points.
For example, `'catmullRom'` produces a smooth, curved shape between ranges.

***

## Full Example

```tsx
const weatherData = [
  { month: "Jan", min: 0, max: 4 },
  { month: "Feb", min: 2, max: 6 },
  ...
]

<RangeAreaChart
  marks={weatherData.map(item => ({
    label: item.month,
    start: item.min,
    end: item.max,
    interpolationMethod: "catmullRom"
  }))}
/>
```

This example plots monthly temperature ranges using a smooth interpolated area chart.

***

## Use Cases

`RangeAreaChart` is well-suited for:

- Temperature ranges over time
- Visualizing confidence intervals in statistics
- Min/max stock prices, performance bands, or uncertainty areas



---
url: /guide/Views/Charts/RangeAreaChart/index_example.md
---

# Example

```tsx
import { Chart, Navigation, NavigationStack, RangeAreaChart, Script, VStack } from "scripting"

const weatherData = [
  { month: 'Jan', min: 0, max: 4 },
  { month: 'Feb', min: 2, max: 6 },
  { month: 'Mar', min: 3, max: 8 },
  { month: 'Apr', min: 5, max: 10 },
  { month: 'May', min: 7, max: 14 },
  { month: 'Jun', min: 10, max: 25 },
  { month: 'Jul', min: 15, max: 30 },
  { month: 'Aug', min: 20, max: 33 },
  { month: 'Sep', min: 24, max: 35 },
  { month: 'Oct', min: 18, max: 30 },
  { month: 'Nov', min: 10, max: 23 },
  { month: 'Dec', min: 5, max: 10 },
]

function Example() {

  return <NavigationStack>
    <VStack
      navigationTitle={"RangeAreaChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        frame={{
          height: 300
        }}
      >
        <RangeAreaChart
          marks={weatherData.map(item => ({
            label: item.month,
            start: item.min,
            end: item.max,
            interpolationMethod: 'catmullRom'
          }))}
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/RectAreaChart/index.md
---

# RectAreaChart

The `RectAreaChart` component renders rectangular areas over a 2D chart coordinate space. It is useful for highlighting regions, data clusters, or ranges of interest on a chart. You can combine it with other charts like `PointChart` for layered visualizations.

***

## Usage Example

```tsx
<RectAreaChart
  marks={[
    { xStart: 2.5, xEnd: 3.5, yStart: 4.5, yEnd: 5.5 },
    { xStart: 1.0, xEnd: 2.0, yStart: 1.0, yEnd: 2.0 },
  ]}
/>
```

***

## Props

### `marks: Array<object>` **(required)**

Each `mark` defines a rectangular area with the following fields:

- `xStart: number`
  The starting X-axis value of the rectangle.

- `xEnd: number`
  The ending X-axis value of the rectangle.

- `yStart: number`
  The starting Y-axis value of the rectangle.

- `yEnd: number`
  The ending Y-axis value of the rectangle.

#### Optional from `ChartMarkProps`:

- `opacity` – Controls the transparency of the rectangle.
- `foregroundStyle` – Fill color or style of the rectangle.
- `annotation` – Optional label or annotation on the mark.

***

## Full Example

```tsx
const data = [
  { x: 5, y: 5 },
  { x: 2.5, y: 2.5 },
  { x: 3, y: 3 },
]

<RectAreaChart
  marks={data.map(item => ({
    xStart: item.x - 0.25,
    xEnd: item.x + 0.25,
    yStart: item.y - 0.25,
    yEnd: item.y + 0.25,
    opacity: 0.2,
  }))}
/>

<PointChart marks={data} />
```

This example overlays transparent rectangles centered around each data point, providing a visual range or margin around them.

***

## Use Cases

- Highlight clusters of points or zones on a scatter plot.
- Visualize regions of interest or acceptable ranges.
- Represent uncertainty or tolerance around data values.



---
url: /guide/Views/Charts/RectAreaChart/index_example.md
---

# Example

```tsx
import { Chart, Navigation, NavigationStack, PointChart, RectAreaChart, Script, VStack } from "scripting"

const data = [
  { x: 5, y: 5 },
  { x: 2.5, y: 2.5 },
  { x: 3, y: 3 },
]

function Example() {
  return <NavigationStack>
    <VStack
      navigationTitle={"RectAreaChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        frame={{
          height: 300
        }}
      >
        <RectAreaChart
          marks={
            data.map(item => ({
              xStart: item.x - 0.25,
              xEnd: item.x + 0.25,
              yStart: item.y - 0.25,
              yEnd: item.y + 0.25,
              opacity: 0.2,
            }))
          }
        />

        <PointChart
          marks={data}
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/RectChart/index.md
---

# RectChart

The `RectChart` component renders a bar-like rectangular chart that visualizes value-based data associated with labels. It is similar in usage to `BarChart` and uses the same `BarChartProps` interface.

***

## Example

```tsx
<RectChart
  labelOnYAxis={false}
  marks={[
    { label: "Cube", value: 5 },
    { label: "Sphere", value: 4 },
    { label: "Pyramid", value: 4 },
  ]}
/>
```

***

## Props

### `labelOnYAxis` (optional)

- **Type:** `boolean`
- **Default:** `false`
- **Description:**
  If `true`, the labels will appear along the Y-axis and the chart will display as horizontal bars. If `false`, labels are on the X-axis with vertical bars.

***

### `marks` (required)

- **Type:** `Array<{ label: string | Date; value: number; unit?: CalendarComponent } & ChartMarkProps>`
- **Description:**
  Defines each data point to render as a rectangle in the chart.

#### `mark` object fields:

- `label`: The category label shown on the axis (e.g., “Cube”).
- `value`: The numeric value determining the height or width of the rectangle.
- `unit`: _(Optional)_ A calendar unit used for time-based data.

You may also use optional visual properties inherited from `ChartMarkProps`, such as:

- `foregroundStyle`
- `cornerRadius`
- `annotation`
- `opacity`

***

## Full Example

```tsx
const toysData = [
  { type: "Cube", count: 5 },
  { type: "Sphere", count: 4 },
  { type: "Pyramid", count: 4 },
]

<RectChart
  labelOnYAxis={true}
  marks={toysData.map(toy => ({
    label: toy.type,
    value: toy.count,
  }))}
/>
```

***

## Use Cases

- Comparing categorical quantities visually.
- Displaying metrics in dashboards or reports.
- Alternative to traditional bar charts with customizable rendering.



---
url: /guide/Views/Charts/RectChart/index_example.md
---

# Example

```tsx
import { Chart, List, Navigation, NavigationStack, RectChart, Script, Section, Toggle, useState } from "scripting"

type ToyShape = {
  type: string
  count: number
}

const toysData: ToyShape[] = [
  {
    type: "Cube",
    count: 5,
  },
  {
    type: "Sphere",
    count: 4,
  },
  {
    type: "Pyramid",
    count: 4
  }
]

function Example() {
  const [labelOnYAxis, setLabelOnYAxis] = useState(false)

  return <NavigationStack>
    <List
      navigationTitle={"RectChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section>
        <Toggle
          title={"labelOnYAxis"}
          value={labelOnYAxis}
          onChanged={setLabelOnYAxis}
        />
      </Section>
      <Chart>
        <RectChart
          labelOnYAxis={labelOnYAxis}
          marks={toysData.map(toy => ({
            label: toy.type,
            value: toy.count,
          }))}
        />
      </Chart>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/RuleChart/index.md
---

# RuleChart

## `RuleChart`

The `RuleChart` component displays a range or duration for each labeled item as a horizontal or vertical rule. It is suitable for visualizing time spans, data ranges, or active periods across categories.

***

## Example

```tsx
<RuleChart
  labelOnYAxis
  marks={[
    { label: "Trees", start: 1, end: 10 },
    { label: "Grass", start: 3, end: 11 },
    { label: "Weeds", start: 4, end: 12 },
  ]}
/>
```

***

## Props

### `labelOnYAxis` (optional)

- **Type:** `boolean`
- **Default:** `false`
- **Description:**
  When set to `true`, the chart switches to horizontal mode and displays category labels along the Y-axis. Otherwise, labels appear on the X-axis with vertical rules.

***

### `marks` (required)

- **Type:**

  ```ts
  Array<{
    label: string | Date;
    start: number;
    end: number;
    unit?: CalendarComponent;
  } & ChartMarkProps>
  ```
- **Description:**
  Defines the rules (lines or spans) to be drawn on the chart.

#### Each mark includes:

- `label`: The category label or time unit (e.g., `"Trees"` or a `Date`).
- `start`: The numeric starting value of the rule.
- `end`: The numeric ending value of the rule.
- `unit`: _(optional)_ The time unit, useful when the chart represents calendar-based data (e.g., `.month`, `.day`).

Additional `ChartMarkProps` can be applied to customize visual styling:

- `foregroundStyle` — Controls color or style
- `annotation` — Adds annotation labels
- `opacity` — Adjusts transparency

***

## Full Example

```tsx
const data = [
  { startMonth: 1, numMonths: 9, source: "Trees" },
  { startMonth: 12, numMonths: 1, source: "Trees" },
  { startMonth: 3, numMonths: 8, source: "Grass" },
  { startMonth: 4, numMonths: 8, source: "Weeds" },
]

<RuleChart
  labelOnYAxis
  marks={data.map(item => ({
    start: item.startMonth,
    end: item.startMonth + item.numMonths,
    label: item.source,
  }))}
/>
```

***

## Use Cases

- Displaying periods of activity or growth (e.g., pollen seasons)
- Showing task durations or project phases
- Visualizing ranges in data for different categories



---
url: /guide/Views/Charts/RuleChart/index_example.md
---

# Example

```tsx
import { Chart, Navigation, NavigationStack, RuleChart, Script, VStack } from "scripting"

const data = [
  { startMonth: 1, numMonths: 9, source: "Trees" },
  { startMonth: 12, numMonths: 1, source: "Trees" },
  { startMonth: 3, numMonths: 8, source: "Grass" },
  { startMonth: 4, numMonths: 8, source: "Weeds" },
]

function Example() {

  return <NavigationStack>
    <VStack
      navigationTitle={"RuleChart"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Chart
        frame={{
          height: 300
        }}
      >
        <RuleChart
          labelOnYAxis
          marks={
            data.map(item => ({
              start: item.startMonth,
              end: item.startMonth + item.numMonths,
              label: item.source,
            }))
          }
        />
      </Chart>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Charts/RuleLineForLabelChart.md
---

# RuleLineForLabelChart

`RuleLineForLabelChart` overlays vertical or horizontal reference lines based on label (or date) positions in a chart. It is commonly used to highlight specific categories or time points in combination with other chart types, such as `BarChart` or `LineChart`.

***

## Declaration

```ts
declare const RuleLineForLabelChart: FunctionComponent<{
  /**
   * If specified as true, the chart will display labels on the Y-axis, causing rule lines to be drawn horizontally. Defaults to false (vertical lines).
   */
  labelOnYAxis?: boolean;

  /**
   * An array of rule marks, each specifying the label or date to draw a reference line at.
   */
  marks: Array<{
    /**
     * The label (string or Date) where the rule line should be placed.
     */
    label: string | Date;

    /**
     * Optional calendar component (e.g., 'month', 'day') if using a Date label.
     */
    unit?: CalendarComponent;
  } & ChartMarkProps>;
}>;
```

***

## Properties

| Property       | Type      | Description                                                                                         |
| -------------- | --------- | --------------------------------------------------------------------------------------------------- |
| `labelOnYAxis` | `boolean` | If `true`, rule lines are drawn **horizontally** using Y-axis label positions. Default is vertical. |
| `marks`        | `Array`   | An array of labeled rule definitions. Each mark can include styling options from `ChartMarkProps`.  |

Each item in `marks` can include:

- `label`: The string or date at which to draw the rule.
- `unit`: Optional, only relevant for date-based axes.
- `foregroundStyle`: Optional. Controls the color.
- `opacity`: Optional. Controls line transparency.
- `lineStyle`: Optional. Allows custom dashing (e.g., `[3, 2]`).

***

## Example: Marking Categories in a Bar Chart

```tsx
import {
  Chart,
  RuleLineForLabelChart,
  BarChart,
  Navigation,
  NavigationStack,
  Script,
  VStack
} from "scripting"

const data = [
  { label: "Q1", value: 1500 },
  { label: "Q2", value: 2300 },
  { label: "Q3", value: 1800 },
  { label: "Q4", value: 2700 },
]

const referenceLines = [
  { label: "Q2", foregroundStyle: "blue", lineStyle: { dash: [3, 2] } },
  { label: "Q4", foregroundStyle: "red", opacity: 0.5 },
]

function Example() {
  return (
    <NavigationStack>
      <VStack
        navigationTitle="BarChart with Reference Lines"
        navigationBarTitleDisplayMode="inline"
      >
        <Chart frame={{ height: 300 }}>
          <BarChart marks={data} />
          <RuleLineForLabelChart marks={referenceLines} />
        </Chart>
      </VStack>
    </NavigationStack>
  )
}

async function run() {
  await Navigation.present({ element: <Example /> })
  Script.exit()
}

run()
```

***

## Use Cases

- Highlight important events or milestones in a timeline.
- Visually separate regions in a categorical chart.
- Indicate thresholds or labels of significance.



---
url: /guide/Views/Charts/RuleLineForValueChart.md
---

# RuleLineForValueChart

The `RuleLineForValueChart` component is used to draw one or more horizontal or vertical reference lines on a chart, based on numeric values. This is useful for highlighting thresholds, targets, or reference levels in your data visualization.

***

## Usage Example

```tsx
<Chart>
  <RuleLineForValueChart
    marks={[
      { value: 50 },
      { value: 75, lineStyle: { dash: [2, 4] } },
    ]}
  />
</Chart>
```

This example renders two rule lines:

- A solid line at value `50`
- A dashed line at value `75`, with a dash pattern of 2-point dash and 4-point gap

***

## Props

### `labelOnYAxis` (optional)

- **Type:** `boolean`
- **Default:** `false`
- **Description:**
  When set to `true`, the chart displays value labels on the **Y Axis**, and rule lines are rendered **vertically**.
  When `false`, labels appear on the X Axis and lines are **horizontal**.

***

### `marks` (required)

- **Type:**

  ```ts
  Array<{
    value: number;
  } & ChartMarkProps>
  ```
- **Description:**
  Each item in the `marks` array defines a rule line at a specific `value`.

#### `value`

- The coordinate value at which the rule line should appear.

#### `ChartMarkProps` (optional extensions)

You can also customize each line using standard chart mark properties:

- `foregroundStyle`: Set color or gradient
- `opacity`: Set line transparency
- `lineStyle`: Customize the stroke pattern (e.g., dashed lines)

***

## Use Cases

- Indicating statistical thresholds (e.g., average, median)
- Highlighting min/max limits or control boundaries
- Marking goals or performance targets

***

## Summary

`RuleLineForValueChart` is a minimal yet powerful overlay chart component that enables enhanced readability and interpretation by visually marking important numerical values on your chart. It can be used alongside other chart types such as `BarChart`, `LineChart`, or `PointChart` to enrich data visualization.



---
url: /guide/Views/ConcentricRectangle.md
---

# ConcentricRectangle

`ConcentricRectangle` is a **concentric rectangle shape view** introduced in iOS 26+. It is designed to create rectangles with **progressively inset (concentric) corner geometry**, which adapts naturally to modern UI designs.

It is especially suitable for:

- Glass-style buttons
- Card backgrounds
- Interactive clipping regions
- Glass transition masks
- Layered container UI

In Scripting, `ConcentricRectangle` can be used both as:

- A **standalone Shape view**
- A **specialized shape inside**:

  - `clipShape`
  - `background`
  - `contentShape`

***

## 1. ConcentricRectangle Core Definition

```ts
type ConcentricRectangleProps = ShapeProps & ConcentricRectangleShape

/**
 * A concentric rectangle aligned inside the frame of the view containing it.
 * @available iOS 26+.
 */
declare const ConcentricRectangle: FunctionComponent<ConcentricRectangleProps>
```

### Description

- `ConcentricRectangle` is a standard **Shape component**
- Supports:

  - Fill
  - Stroke
  - Trimmed paths
  - Advanced corner distribution via `ConcentricRectangleShape`
- Always renders **inside the parent view’s frame**
- Available on **iOS 26 and later only**

***

## 2. Corner Style System: EdgeCornerStyle

The core visual behavior of `ConcentricRectangle` is controlled through `EdgeCornerStyle`, which defines how each corner behaves.

```ts
type EdgeCornerStyle =
  | {
      style: "fixed"
      radius: number
    }
  | {
      style: "concentric"
      minimum: number
    }
  | "concentric"
```

***

### 2.1 Fixed Corner Style

```ts
{
  style: "fixed"
  radius: number
}
```

Used to create traditional fixed-radius rounded corners.

| Property | Description                   |
| -------- | ----------------------------- |
| `radius` | Fixed corner radius in points |

This mode is appropriate for classic static cards and buttons.

***

### 2.2 Concentric Corner Style

```ts
{
  style: "concentric"
  minimum: number
}
```

Creates a dynamically inset **concentric corner effect**.

| Property  | Description                                                                |
| --------- | -------------------------------------------------------------------------- |
| `minimum` | The minimum inner corner radius used as the base for automatic progression |

Recommended for:

- Glass-style controls
- Dynamic cards
- Layered UI surfaces
- Animated masking effects

***

### 2.3 Shorthand Mode

```ts
"concentric"
```

Equivalent to:

```ts
{
  style: "concentric"
  minimum: systemDefault
}
```

***

## 3. ConcentricRectangleShape (Corner Distribution Rules)

`ConcentricRectangleShape` defines **how corner styles are distributed** across all four corners.
It supports **seven structural configuration patterns**.

***

### 3.1 Uniform Corners (Most Common)

```ts
{
  corners: EdgeCornerStyle
  isUniform?: boolean
}
```

| Property    | Description                                  |
| ----------- | -------------------------------------------- |
| `corners`   | Corner style applied to all four corners     |
| `isUniform` | Forces strict uniformity, default is `false` |

Example:

```tsx
<ConcentricRectangle
  corners={{
    style: "concentric",
    minimum: 8
  }}
  fill="red"
/>
```

***

### 3.2 Fully Independent Corners

```ts
{
  topLeadingCorner?: EdgeCornerStyle
  topTrailingCorner?: EdgeCornerStyle
  bottomLeadingCorner?: EdgeCornerStyle
  bottomTrailingCorner?: EdgeCornerStyle
}
```

Used for:

- Asymmetric cards
- Special edge treatments
- Adaptive container layouts

***

### 3.3 Uniform Bottom Corners

```ts
{
  uniformBottomCorners?: EdgeCornerStyle
  topLeadingCorner?: EdgeCornerStyle
  topTrailingCorner?: EdgeCornerStyle
}
```

Typical for bottom sheets and lifted panels.

***

### 3.4 Uniform Top Corners

```ts
{
  uniformTopCorners?: EdgeCornerStyle
  bottomLeadingCorner?: EdgeCornerStyle
  bottomTrailingCorner?: EdgeCornerStyle
}
```

Typical for modal headers and floating top panels.

***

### 3.5 Uniform Top and Bottom

```ts
{
  uniformTopCorners?: EdgeCornerStyle
  uniformBottomCorners?: EdgeCornerStyle
}
```

***

### 3.6 Uniform Leading Corners

```ts
{
  uniformLeadingCorners?: EdgeCornerStyle
  topTrailingCorner?: EdgeCornerStyle
  bottomTrailingCorner?: EdgeCornerStyle
}
```

***

### 3.7 Uniform Leading and Trailing

```ts
{
  uniformLeadingCorners?: EdgeCornerStyle
  uniformTrailingCorners?: EdgeCornerStyle
}
```

***

## 4. Shared Shape Properties (ShapeProps)

```ts
type ShapeProps = {
  trim?: {
    from: number
    to: number
  }

  fill?: ShapeStyle | DynamicShapeStyle

  stroke?: ShapeStyle | DynamicShapeStyle | {
    shapeStyle: ShapeStyle | DynamicShapeStyle
    strokeStyle: StrokeStyle
  }
}
```

***

### 4.1 trim (Path Trimming)

```ts
trim={{
  from: 0.0,
  to: 0.5
}}
```

Used for:

- Progressive path animations
- Partial rendering effects
- Stroke-only transitions

***

### 4.2 fill (Shape Fill)

```ts
fill="red"
fill="ultraThinMaterial"
```

Supports:

- Solid colors
- System materials
- Gradient styles

***

### 4.3 stroke (Outline Rendering)

```ts
stroke="blue"

stroke={{
  shapeStyle: "blue",
  strokeStyle: {
    lineWidth: 2
  }
}}
```

***

## 5. Using ConcentricRectangle in View Modifiers

### 5.1 As clipShape

```ts
clipShape?: Shape | "concentricRect" | ({
  type: "concentricRect"
} & ConcentricRectangleShape)
```

Example:

```tsx
<VStack
  clipShape={{
    type: "concentricRect",
    corners: {
      style: "concentric",
      minimum: 10
    }
  }}
/>
```

Used for:

- Actual visual clipping
- Glass transition masking
- Blur boundary control

***

### 5.2 As background

```ts
background?: ShapeStyle | DynamicShapeStyle | {
  style: ShapeStyle | DynamicShapeStyle
  shape: Shape | "concentricRect" | ({
    type: "concentricRect"
  } & ConcentricRectangleShape)
} | VirtualNode | {
  content: VirtualNode
  alignment: Alignment
}
```

Example:

```tsx
<VStack
  background={{
    style: "ultraThinMaterial",
    shape: {
      type: "concentricRect",
      corners: "concentric"
    }
  }}
/>
```

***

### 5.3 As contentShape (Hit Testing Area)

```ts
contentShape?: Shape | {
  kind: ContentShapeKinds
  shape: Shape | "concentricRect" | ({
    type: "concentricRect"
  } & ConcentricRectangleShape)
}
```

Defines the interactive region for:

- Taps
- Gestures
- Hover detection
- Drag operations

***

## 6. Full Example Breakdown

```tsx
<ZStack
  frame={{
    width: 300,
    height: 200
  }}
  containerShape={{
    type: "rect",
    cornerRadius: 32
  }}
>
  <ConcentricRectangle
    corners={{
      style: "concentric",
      minimum: 8
    }}
    fill="red"
  />
</ZStack>
```

This configuration produces:

- A fixed-radius outer container
- A concentric inner rectangle
- A layered depth effect between the two shapes
- A visually emphasized inner hierarchy via red fill

***

## 7. Design and Implementation Notes

1. `minimum` should never exceed half of the smallest side of the container.
2. Concentric corner styles work best when combined with:

   - Glass material
   - Blur
   - Opacity layering
3. When used as `contentShape`, it only affects hit-testing, not rendering.
4. When used as `clipShape`, it physically clips the rendered content.
5. Nested `ConcentricRectangle` layers create stronger depth cues than uniform rounded rectangles.



---
url: /guide/Views/Controls/ColorPicker/index.md
---

# ColorPicker

The `ColorPicker` component provides a system color picker UI that allows users to select a color and passes the selected color back to the application via the `onChanged` event. It supports the following formats for colors:

- Keyword colors (e.g., `green`, `red`, `blue`, etc.)
- Hexadecimal color strings (e.g., `#FF5733` or `#333`)
- CSS rgba strings (e.g., `rgba(255,0,0,1)`)

***

## `ColorPickerProps`

`ColorPickerProps` is the type of properties for the `ColorPicker` component. It can be defined in the following two ways:

### 1. Using the `title` property

- **`title`** (`string`): Provides a title for the color picker, describing its purpose or offering guidance to the user.

### 2. Using the `children` property

- **`children`** (`VirtualNode | undefined | null | (VirtualNode | undefined | null)[]` | `VirtualNode`): A custom view that describes the usage of the selected color. The system color picker UI will use the text of this view to set the title. If you don't use `children`, you can simply use `title`.

### Additional properties

- **`value`** (`Color`): The current selected color value. It can be a keyword color, hexadecimal color string, or RGBA string.

- **`onChanged`** (`(value: Color) => void`): A callback function triggered when the color changes. This callback is invoked with the new color value when the user selects a new color.

- **`supportsOpacity`** (`boolean`, optional): If set to `true`, allows the user to adjust the opacity of the selected color. The default is `true`.

***

### Example Code

```tsx
import { useState } from 'scripting'
import { ColorPicker } from 'scripting'

const MyComponent = () => {
  const [color, setColor] = useState<Color>('#FF5733')

  return (
    <ColorPicker
      title="Pick a Color"
      value={color}
      onChanged={setColor}
    />
  )
}
```

### Explanation

In the example above:

- The `ColorPicker` component’s `title` is set to `"Pick a Color"`, instructing the user to choose a color.
- The initial color value is `#FF5733`.
- The `onChanged` callback is triggered when the color changes, updating the `color` state.

### Optional Opacity Support

If you wish to allow adjusting the opacity of the selected color, you can enable this feature by setting the `supportsOpacity` property:

```tsx
<ColorPicker
  title="Pick a Color"
  value={color}
  onChanged={setColor}
  supportsOpacity={true}
/>
```

## `Color` Type

The `Color` type is used to define various color formats, including:

- **Keyword colors**: such as `"red"`, `"green"`, `"blue"`, etc.
- **Hexadecimal strings**: such as `"#FF5733"`.
- **CSS rgba strings**: such as `rgba(255, 0, 0, 0.5)`.

### Example

```tsx
const color: Color = 'rgba(255, 0, 0, 0.5)'
```



---
url: /guide/Views/Controls/ColorPicker/index_example.md
---

# Example

```tsx
import { Color, ColorPicker, Navigation, NavigationStack, Script, Text, useState, VStack } from "scripting"

function Example() {
  const [value, setValue] = useState<Color>('blue')

  return <NavigationStack>
    <VStack
      navigationTitle={"Color Picker"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <ColorPicker
        value={value}
        onChanged={setValue}
      >
        <Text>Current color: {value}</Text>
      </ColorPicker>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Controls/ContentUnavailableView/index.md
---

# ContentUnavailableView

`ContentUnavailableView` is a UI component designed to present a view when the content in your app is unavailable. It typically shows a title, an optional description, and an action area, making it clear to users that content is missing or not yet available. This component can be used in places like lists, where no data is available to show to the user.

## Props

### Common Properties

You can pass one of two structures of properties to the `ContentUnavailableView` component:

1. **String-based Props:**
   - `title` (string): The main title to display, typically describing the content that is unavailable.
   - `systemImage` (string): A system icon to visually represent the unavailable content. This is used to enhance the UI and provide an intuitive, recognizable symbol.
   - `description` (string, optional): A brief text description of the unavailable content. This is optional and can be omitted if not needed.

2. **VirtualNode-based Props:**
   - `label` (VirtualNode): A virtual node, typically a `Text` or any other UI component, that will serve as the label describing the unavailable content.
   - `description` (VirtualNode | null, optional): A virtual node, usually a `Text` component, that provides more detailed information about the unavailable content. If you don't need a description, this can be set to `null`.
   - `actions` (Array of VirtualNode | null, optional): An optional list of action buttons or links to display. These actions can be buttons, links, or other components, and they can be `null` if no actions are needed.

## Example Usage

### 1. Simple Usage with Strings

```tsx
function View({documents}: {documents: {name: string}[]}) {
  return (
    <NavigationStack>
      <List
        overlay={
          documents.length > 0
            ? undefined
            : <ContentUnavailableView
                title="No documents"
                systemImage="tray.fill"
              />
        }
      >
        {documents.map(item => (
          <Text>{item.name}</Text>
        ))}
      </List>
    </NavigationStack>
  )
}
```

In this example, `ContentUnavailableView` is used to show a message with an icon when the list of documents is empty. If the `documents` array is empty, the view will show the title "No documents" and a system icon `"tray.fill"`.

### 2. Advanced Usage with VirtualNode

```tsx
function View({documents}: {documents: {name: string}[]}) {
  return (
    <NavigationStack>
      <List
        overlay={
          documents.length > 0
            ? undefined
            : <ContentUnavailableView
                label={<Text>No documents available</Text>}
                description={<Text>Please check back later for available documents.</Text>}
                actions={[<Button onClick={handleRefresh}>Refresh</Button>]}
              />
        }
      >
        {documents.map(item => (
          <Text>{item.name}</Text>
        ))}
      </List>
    </NavigationStack>
  )
}
```

In this example, the `ContentUnavailableView` is passed virtual nodes for the label and description. It also includes an action button to refresh the list of documents.

## Notes

- You can choose to use either the string-based or virtual node-based properties depending on how dynamic you want the content of the unavailable view to be.
- The component is flexible and can be integrated into lists, stacks, and other complex layouts.

## API Details

- **`title`** and **`systemImage`**: Provide a simple, static way to show unavailable content with a string title and system icon.
- **`label`** and **`description`**: Allow you to customize the label and description with full control, using `VirtualNode` components.
- **`actions`**: Optional actions can be added to guide users, like buttons or links, that perform actions like refreshing content or redirecting users to another screen.

This component is ideal for UIs where content might be temporarily unavailable and you want to display a consistent and clear message to users.



---
url: /guide/Views/Controls/ContentUnavailableView/index_example.md
---

# Example

```tsx
import { useState, List, ContentUnavailableView, Button, Text, NavigationStack, Navigation, Script } from "scripting"

function Example() {
  const [list, setList] = useState<string[]>([])

  return <NavigationStack>
    <List
      navigationTitle={"ContentUnavailableView"}
      navigationBarTitleDisplayMode={"inline"}
      overlay={
        list.length ? undefined
          : <ContentUnavailableView
            title="No data"
            systemImage="tray.fill"
          />
      }
      toolbar={{
        bottomBar: [
          <Button
            title="Add"
            action={() => {
              setList(list => {
                let newList = [
                  (Math.random() * 1000 | 0).toString(),

                  ...list
                ]
                return newList
              })
            }}
          />,
          <Button
            title="Clear"
            action={() => {
              setList([])
            }}
          />
        ]
      }}
    >
      {list.map(name => <Text>{name}</Text>)}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Controls/DatePicker/index.md
---

# DatePicker

The `DatePicker` is a UI component for selecting a date (and optionally a time). It supports various interactive display styles, such as calendar views, wheel selectors, and compact text formats. This component is ideal for scenarios where users need to select a specific date and time, such as choosing an event start date or a task deadline.

## Props

### `DatePickerProps` Type

- **`title`** (required): `string`

  The title of the date picker, typically used to describe the purpose of the selection, such as "Select Date."

- **`children`** (optional): `(VirtualNode | undefined | null | (VirtualNode | undefined | null)[])[] | VirtualNode`

  Used for rendering custom child content. If no custom content is required, this property can be omitted.

- **`value`** (required): `number`

  The timestamp (in milliseconds) representing the currently selected date. This value is passed to the `onChanged` handler.

- **`onChanged`** (required): `(value: number) => void`

  A callback function that is called when the date value changes. The argument is the new timestamp.

- **`startDate`** (optional): `number`

  The starting date for selectable dates. The user can only select dates greater than or equal to this value.

- **`endDate`** (optional): `number`

  The ending date for selectable dates. The user can only select dates less than or equal to this value.

- **`displayedComponents`** (optional): `DatePickerComponents[]`

  An optional array specifying the date components the user can view and edit. The default value is `['hourAndMinute', 'date']`, which displays both the date and time (hour and minute). If you need to show seconds (only available on watchOS), you can use `['hourMinuteAndSecond']`.

### `DatePickerComponents` Type

This type defines the components that can be displayed in the date picker:

- **`date`**: Displays the day, month, and year based on the locale.
- **`hourAndMinute`**: Displays the hour and minute based on the locale.
- **`hourMinuteAndSecond`**: Available only on watchOS. Displays the hour, minute, and second components based on the locale.

### `DatePickerStyle` Type

Defines the style of the `DatePicker` component. The following options are available:

- **`automatic`**: The default style for the date picker, which automatically selects the most appropriate display format.
- **`compact`**: A compact style that displays the components in a textual format.
- **`graphical`**: A graphical style that shows an interactive calendar or clock.
- **`wheel`**: A wheel style where each component is displayed as a scrollable column.
- **`field`**: Available only on macOS. A field style that displays the components in an editable text field.
- **`stepperField`**: Available only on macOS. A system style that displays the components in an editable field, with an adjoining stepper to increment or decrement the selected component.

## Example Code

Here’s an example of how to use the `DatePicker` component:

```tsx
<DatePicker
  title="Select Date and Time"
  value={new Date().getTime()}
  onChanged={(newDate) => console.log('New Date:', newDate)}
  startDate={new Date('2024-01-01').getTime()}
  endDate={new Date('2024-12-31').getTime()}
  displayedComponents={['date', 'hourAndMinute']}
  datePickerStyle="wheel"
/>
```

## Usage Notes

The `DatePicker` component allows you to control the displayed components via the `displayedComponents` prop. By default, it will show both the date and time (hour and minute), but you can customize which components to display according to your needs. For example, on watchOS devices, you can show the hour, minute, and second components.

The appearance and interaction style of the date picker can be further customized using the `datePickerStyle` prop. Different styles provide varying user experiences, and you can choose the one most suitable for your platform and use case.

## Considerations

- The `startDate` and `endDate` properties are used to limit the selectable date range, ensuring that users can only select valid dates.
- The `displayedComponents` property can be adjusted according to your requirements. If you don't need time selection, you can opt to display only the date component.
- The `DatePicker` supports different experiences on various platforms (e.g., `stepperField` is only available on macOS), so make sure to adjust the style options based on the platform.



---
url: /guide/Views/Controls/DatePicker/index_example.md
---

# Example

```tsx
import { DatePicker, DatePickerComponents, DatePickerStyle, HStack, Image, List, Navigation, NavigationStack, Picker, Script, Section, Spacer, Text, Toggle, useMemo, useState, } from "scripting"

const oneDay = 1000 * 60 * 60 * 24

 function Example() {
  const [date, setDate] = useState(() => Date.now())
  const [startDateEnabled, setStartDateEnabled] = useState(false)
  const [endDateEnabled, setEndDateEnabled] = useState(false)
  const startDate = useMemo(() => Date.now() - oneDay * 7, [])
  const endDate = useMemo(() => Date.now() + oneDay * 7, [])
  const components = useMemo<DatePickerComponents[]>(() => [
    'date',
    'hourAndMinute'
  ], [])
  const [displayedComponents, setDisplayedComponents] = useState<DatePickerComponents[]>([
    'date', 'hourAndMinute'
  ])
  const datePickerStyles = useMemo<DatePickerStyle[]>(() => [
    'compact',
    'graphical',
    'wheel',
  ], [])
  const [selectedStyle, setSelectedStyle] = useState<DatePickerStyle>('graphical')

  return <NavigationStack>
    <List
      navigationTitle={"DatePicker"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section>
        <Toggle
          title={"Use startDate"}
          value={startDateEnabled}
          onChanged={setStartDateEnabled}
        />

        <Toggle
          title={"Use endDate"}
          value={endDateEnabled}
          onChanged={setEndDateEnabled}
        />
        {components.map(name =>
          <HStack
            contentShape={'rect'}
            onTapGesture={() => {
              if (displayedComponents.includes(name)) {
                if (displayedComponents.length > 1) {
                  setDisplayedComponents(displayedComponents.filter(e => e !== name))
                }
              } else {
                setDisplayedComponents([name, ...displayedComponents])
              }
            }}
          >
            <Text>Display: {name}</Text>
            <Spacer />
            {displayedComponents.includes(name)
              ? <Image
                systemName={"checkmark"}
                foregroundStyle={"systemBlue"}
              />
              : undefined}
          </HStack>
        )}

        <Picker
          title={"DatePicker Style"}
          value={selectedStyle}
          onChanged={setSelectedStyle as any}
          pickerStyle={'menu'}
        >
          {datePickerStyles.map(style =>
            <Text tag={style}>{style}</Text>
          )}
        </Picker>
      </Section>

      <DatePicker
        title={"DatePicker"}
        value={date}
        onChanged={setDate}
        startDate={startDateEnabled ? startDate : undefined}
        endDate={endDateEnabled ? endDate : undefined}
        displayedComponents={displayedComponents}
        datePickerStyle={selectedStyle}
      />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Controls/Gauge/index.md
---

# Gauge

The `Gauge` component is a view used to display the current value in relation to a specified finite capacity, similar to a fuel gauge in an automobile. The `Gauge` component is highly configurable and can display any combination of the current value, the range the gauge can display, and a label describing the purpose of the gauge itself. It is suitable for showing the current value of a limited capacity, such as progress, level, or quantity.

## Properties

### `value` (Required)

- **Type**: `number`
- **Description**: The current value to display in the gauge. This value should be within the range defined by the `min` and `max` properties.

### `label` (Required)

- **Type**: `VirtualNode`
- **Description**: A view element that describes the purpose of the gauge. For example, this could display descriptive text such as "Battery Level" or "Temperature".

### `min` (Optional)

- **Type**: `number`
- **Description**: The minimum valid value of the gauge, defaulting to `0`. It represents the lower bound of the gauge.

### `max` (Optional)

- **Type**: `number`
- **Description**: The maximum valid value of the gauge, defaulting to `1`. It represents the upper bound of the gauge.

### `currentValueLabel` (Optional)

- **Type**: `VirtualNode`
- **Description**: A view element that describes the current value of the gauge. For example, it could show a text label displaying the current value (e.g., "70%").

### `minValueLabel` (Optional)

- **Type**: `VirtualNode`
- **Description**: A view element that describes the lower bound of the gauge. For example, it could display a label like "0%" or "Min" at the minimum value position.

### `maxValueLabel` (Optional)

- **Type**: `VirtualNode`
- **Description**: A view element that describes the upper bound of the gauge. For example, it could display a label like "100%" or "Max" at the maximum value position.

### `gaugeStyle` (Optional)

- **Type**: `GaugeStyle`
- **Description**: The style of the gauge view. This property controls the visual appearance of the gauge and has the following options:
  - **`automatic`**: The default style based on the current context of the view being styled.
  - **`accessoryCircular`**: Displays an open circular ring with a marker that appears at a point along the ring to indicate the current value.
  - **`accessoryCircularCapacity`**: Displays a closed circular ring that is partially filled to indicate the current value.
  - **`circular`**: **(Available only on watchOS)** Displays an open circular ring with a marker that appears at a point along the ring to indicate the current value.
  - **`linearCapacity`**: Displays a bar that fills from the leading to trailing edge as the value increases.
  - **`accessoryLinear`**: Displays a bar with a marker that appears at a point along the bar to indicate the current value.
  - **`accessoryLinearCapacity`**: Displays a bar that fills from the leading to trailing edge as the value increases.
  - **`linear`**: **(Available only on watchOS)** Displays a bar with a marker that appears at a point along the bar to indicate the current value.

## Example Code

```tsx
<Gauge
  value={0.7}
  label={<Text>Battery Level</Text>}
  min={0}
  max={1}
  currentValueLabel={<Text>70%</Text>}
  minValueLabel={<Text>0%</Text>}
  maxValueLabel={<Text>100%</Text>}
  gaugeStyle="accessoryCircular"
/>
```

## Use Cases

The `Gauge` component is ideal for the following use cases:

- Displaying progress (e.g., task completion, download progress).
- Showing device status (e.g., battery level, signal strength).
- Displaying performance metrics (e.g., temperature, humidity, CPU usage).

By customizing properties such as `label` and `currentValueLabel`, the `Gauge` component can be adapted for various display needs, helping users understand the current state more clearly.

## Notes

- The `value` property should be within the range specified by `min` and `max` to ensure proper display.
- If `min` and `max` are not provided, the gauge will default to the range `[0, 1]`.
- Different `gaugeStyle` options provide varied visual representations. Select an appropriate style based on the device and context to enhance user experience.



---
url: /guide/Views/Controls/Gauge/index_example.md
---

# Example

```tsx
import { Gauge, List, Navigation, NavigationStack, Script, Section, Text } from "scripting"

function Example() {

  return <NavigationStack>
    <List
      navigationTitle={"Gauge"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        header={
          <Text>accessoryCircular</Text>
        }
      >
        <Gauge
          value={0.4}
          label={<Text>0 100</Text>}
          currentValueLabel={<Text>40%</Text>}
          gaugeStyle={"accessoryCircular"}
          tint={"systemGreen"}
        />
      </Section>

      <Section
        header={
          <Text>accessoryCircularCapacity</Text>
        }
      >
        <Gauge
          value={0.4}
          label={<Text>Battery Level</Text>}
          currentValueLabel={<Text>40%</Text>}
          gaugeStyle={"accessoryCircularCapacity"}
        />
      </Section>

      <Section
        header={
          <Text>linearCapacity</Text>
        }
      >
        <Gauge
          value={0.4}
          label={<Text>Battery Level</Text>}
          currentValueLabel={<Text>40%</Text>}
          gaugeStyle={"linearCapacity"}
        />
      </Section>

      <Section
        header={
          <Text>accessoryLinear</Text>
        }
      >
        <Gauge
          value={0.4}
          label={<Text>Battery Level</Text>}
          currentValueLabel={<Text>40%</Text>}
          gaugeStyle={"accessoryLinear"}
        />
      </Section>
      <Section
        header={
          <Text>accessoryLinearCapacity</Text>
        }
      >
        <Gauge
          value={0.4}
          label={<Text>Battery Level</Text>}
          currentValueLabel={<Text>40%</Text>}
          gaugeStyle={"accessoryLinearCapacity"}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Controls/Picker/index.md
---

# Picker

The `Picker` component is used to select a single value from a set of mutually exclusive options. It supports various display styles and allows users to choose a single value. The selected value and the change event can be managed using the `value` and `onChanged` properties.

## Type Definitions

- `PickerValue`: The type of the selected value, which can be either `number` or `string`.
- `PickerProps<T extends PickerValue>`: The property type for the `Picker` component, which includes:
  - `value`: The current selected value, which can be a `number` or `string` (optional).
  - `onChanged`: A callback function triggered when the selected value changes, with the new value (`T`) as the parameter.
  - `children`: The option views, where each child must have a `tag` property to indicate its value. This can be a `JSX.Element` or an array of `JSX.Element`s.
  - `title`: A string describing the option's purpose, used in certain cases.
  - `systemImage`: The name of the system image resource, used in certain cases.
  - `label`: A `JSX.Element` that describes the purpose of the selection, used in certain cases.

## Component Functionality

The `Picker` component manages the user's selection through the `value` and `onChanged` properties. The `value` is the current selected value, and the `onChanged` is a callback function that is invoked when the user changes the selection. The `children` property defines the options' views, allowing multiple layouts to be used for displaying the options. Each `children` element must have a `tag` property to mark its value, for example, `<Text tag={1}>Option 1</Text>`.

## Picker Styles

The `Picker` component supports the following styles to adjust how the component is displayed:

- `automatic`: The default style, automatically determined based on the picker’s context.
- `inline`: Displays each option inline with other views in the current container.
- `menu`: Displays the options in a menu that opens when the user presses a button or as a submenu within a larger menu.
- `navigationLink`: Displays a navigation link that presents the options in a List-style picker view when clicked.
- `palette`: Displays the options as a row of compact elements.
- `segmented`: Displays the options in a segmented control style.
- `wheel`: Displays the options in a scrollable wheel, showing the selected option and a few neighboring options.

## Example Usage

Below are examples of how to use the `Picker` component:

### Example 1: Picker with Numeric Values

```tsx
import { Picker, Text, useState } from 'scripting'

const MyPicker = () => {
  const [selectedValue, setSelectedValue] = useState<number>(1)

  return (
    <Picker
      value={selectedValue}
      onChanged={(newValue) => setSelectedValue(newValue)}
      pickerStyle="inline"
    >
      <Text tag={1}>Option 1</Text>
      <Text tag={2}>Option 2</Text>
      <Text tag={3}>Option 3</Text>
    </Picker>
  )
}
```

### Example 2: Picker with String Values

```tsx
import { Picker, Text, useState } from 'scripting'

const MyPicker = () => {
  const [selectedValue, setSelectedValue] = useState<string>("Option 1")

  return (
    <Picker
      value={selectedValue}
      onChanged={(newValue) => setSelectedValue(newValue)}
      pickerStyle="segmented"
    >
      <Text tag="Option 1">Option 1</Text>
      <Text tag="Option 2">Option 2</Text>
      <Text tag="Option 3">Option 3</Text>
    </Picker>
  )
}
```

### Example 3: Picker with Title and System Image

```tsx
import { Picker, Text, useState } from 'scripting'

const MyPicker = () => {
  const [selectedValue, setSelectedValue] = useState<string>("Option 1")

  return (
    <Picker
      value={selectedValue}
      onChanged={(newValue) => setSelectedValue(newValue)}
      pickerStyle="menu"
      title="Choose an option"
      systemImage="star"
    >
      <Text tag="Option 1">Option 1</Text>
      <Text tag="Option 2">Option 2</Text>
      <Text tag="Option 3">Option 3</Text>
    </Picker>
  )
}
```

## Common Use Cases for `Picker`

1. **Form Selection**: `Picker` can be used in forms to select a single value from a predefined set of options.
2. **Settings Interface**: In app settings, `Picker` can be used to choose colors, themes, languages, etc.
3. **Navigation Options**: In more complex interfaces, `Picker` can serve as a tool for selecting options within multi-level menus.

## Notes

- Each `children` element in the `Picker` must use the `tag` property to mark its value, for example: `<Text tag={1}>Option 1</Text>`.
- The `value` and `onChanged` properties must be used together to ensure correct functionality when the user changes the selected value.
- The `pickerStyle` property provides various styles to enhance the user experience. Select the one that fits your use case best.

### Related APIs

- `JSX.Element`: The type used for defining the view structure. The `Picker` component’s `children` property relies on this type.
- `useState`: A React hook for managing the selected value’s state.



---
url: /guide/Views/Controls/Picker/index_example.md
---

# Example

```tsx
import { List, Navigation, NavigationStack, Picker, PickerStyle, Script, Section, Text, useMemo, useState, } from "scripting"

function Example() {
  const [value, setValue] = useState<number>(0)
  const options = useMemo<PickerStyle[]>(() => [
    'automatic',
    'inline',
    'menu',
    'navigationLink',
    'palette',
    'segmented',
    'wheel'
  ], [])
  const users = useMemo<string[]>(() => [
    "Jobs", "Elon", "Zack", "Joe"
  ], [])

  return <NavigationStack>
    <List
      navigationTitle={"Picker"}
      navigationBarTitleDisplayMode={"inline"}
    >
      {options.map((style) =>
        <Section
          header={
            <Text>Picker: {style}</Text>}
        >
          <Picker
            title={"Picker: " + style}
            pickerStyle={style}
            value={value}
            onChanged={setValue}
          >
            {users.map((user, index) =>
              <Text
                tag={index}
              >{user}</Text>
            )}
          </Picker>
        </Section>
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Controls/ProgressView/index.md
---

# ProgressView

`ProgressView` is a UI component that visually represents the progress of a task or operation. It can display both determinate (percentage complete) and indeterminate (progressing or not) types of progress. Additionally, it offers customizable progress view styles, including linear and circular representations.

You can use `ProgressView` to display the progress of various tasks, such as downloading a file, completing a process, or waiting for an event. The component can also show additional details like labels for the task description and current progress.

## Usage

### Component Declaration

The `ProgressView` component accepts two possible sets of properties, depending on whether you want to represent a time-based interval or a general progress task. These are specified through the `ProgressViewProps` type, which can be one of the following:

- `TimerIntervalProgressViewProps`
- `NormalProgressViewProps`

You can create a determinate progress view by binding the `value` and `total` properties to represent progress. Additionally, the component supports custom styling through the `progressViewStyle` property.

### Example: Timer-Based Progress View

```tsx
<ProgressView
  timerFrom={startTimestamp}
  timerTo={endTimestamp}
  countsDown={true}
  label={<Text>Task in Progress</Text>}
  currentValueLabel={<Text>50% Complete</Text>}
/>
```

### Example: Normal Progress View

```tsx
<ProgressView
  value={0.5}
  total={1.0}
  title="Loading"
  label={<Text>File Download</Text>}
  currentValueLabel={<Text>50% Complete</Text>}
/>
```

## Props

### `TimerIntervalProgressViewProps`

- **`timerFrom`** (`number`):\
  The start timestamp (in milliseconds) that defines the beginning of the progress interval. This is used to calculate how much time has passed in the progress view.

- **`timerTo`** (`number`):\
  The end timestamp (in milliseconds) that defines the completion of the progress interval. This marks the end point of the progress view.

- **`countsDown`** (`boolean`, optional, default: `true`):\
  If set to `true`, the progress view counts down from the `timerFrom` to `timerTo` timestamp. If `false`, it will count up.

- **`label`** (`VirtualNode`, optional):\
  A virtual node that provides additional context or description about the task in progress. This could be a text label or another type of view.

- **`currentValueLabel`** (`VirtualNode`, optional):\
  A virtual node that describes the current value or progress of the task. For example, this could show the current percentage of completion.

### `NormalProgressViewProps`

- **`value`** (`number`, optional):\
  The completed progress of the task so far. This is a floating-point number between `0.0` and `total`, representing the task's completion percentage. If `nil`, the progress is indeterminate.

- **`total`** (`number`, optional, default: `1.0`):\
  The total amount representing 100% completion of the task. The progress is considered complete when `value` equals `total`. Defaults to `1.0`.

- **`title`** (`string`, optional):\
  The title or name of the task that is being represented in the progress view.

- **`label`** (`VirtualNode`, optional):\
  A virtual node that describes the task in progress, similar to the `label` property in `TimerIntervalProgressViewProps`.

- **`currentValueLabel`** (`VirtualNode`, optional):\
  A virtual node that shows the current progress value of the task, similar to the `currentValueLabel` in `TimerIntervalProgressViewProps`.

### `CommonViewProps`

- **`progressViewStyle`** (`ProgressViewStyle`, optional):\
  The style of the progress view. The available styles are:
  - **`automatic`**: The default style based on the current context of the view being styled.
  - **`circular`**: A circular gauge style to show progress. On platforms other than macOS, this may appear as an indeterminate indicator.
  - **`linear`**: A horizontal bar style indicating the task's progress.

### `ProgressViewStyle`

- **`linear`**: A progress view that visually indicates its progress using a horizontal bar.
- **`circular`**: A circular progress view that indicates the partial completion of an activity. On non-macOS platforms, this may be used for indeterminate progress.
- **`automatic`**: The default style, which automatically chooses the appropriate style based on the context.

## Notes

- `ProgressView` automatically adjusts its display based on the values provided in the `TimerIntervalProgressViewProps` or `NormalProgressViewProps`.
- If both `value` and `total` are provided, the progress will be determinate. If either of them is `nil`, the progress view will be indeterminate.
- You can use the `label` and `currentValueLabel` properties to customize the UI by passing any type of view, including text, images, or custom components.
- The `progressViewStyle` can be set to customize the visual style of the progress indicator. By default, it uses the `automatic` style, but you can choose `linear` or `circular` depending on your needs.

## Examples

### Determinate Progress (with value and total)

```tsx
<ProgressView
  value={0.75}
  total={1.0}
  title="Task Progress"
  label={<Text>Task is 75% complete</Text>}
  currentValueLabel={<Text>75%</Text>}
  progressViewStyle="linear"
/>
```

### Indeterminate Progress (without value)

```tsx
<ProgressView
  title="Loading"
  label={<Text>Loading file...</Text>}
  progressViewStyle="circular"
/>
```

## Conclusion

`ProgressView` is a flexible and easy-to-use UI component that supports both determinate and indeterminate progress states. It allows you to display progress through either a linear or circular visual representation. With the ability to customize progress details and UI style, `ProgressView` is an ideal choice for indicating task progress in various scenarios.



---
url: /guide/Views/Controls/ProgressView/index_example.md
---

# Example

```tsx
import { List, Navigation, NavigationStack, ProgressView, Script, Section, Text, useState, } from "scripting"

function Example() {
  const [timerFrom] = useState(() => Date.now())
  const timerTo = timerFrom + 1000 * 60

  return <NavigationStack>
    <List
      navigationTitle={"ProgressView"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        header={
          <Text>circular</Text>
        }
      >
        <ProgressView
          progressViewStyle={'circular'}
        />
      </Section>

      <Section
        header={
          <Text>linear</Text>
        }
      >
        <ProgressView
          progressViewStyle={'linear'}
          total={100}
          value={50}
          label={<Text>Progress 50%</Text>}
          currentValueLabel={<Text>50</Text>}
        />
      </Section>

      <Section
        header={
          <Text>TimerInterval</Text>
        }
      >
        <ProgressView
          progressViewStyle={'linear'}
          timerFrom={timerFrom}
          timerTo={timerTo}
          countsDown={false}
          label={<Text>Workout</Text>}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Controls/Slider/index.md
---

# Slider

The `Slider` component allows users to select a value from a bounded linear range of values. You can configure the slider by setting the minimum value, maximum value, step size, and the current value. The component also supports custom labels to describe the minimum and maximum values, as well as the slider itself. Additionally, it provides callbacks for handling value changes and editing state changes.

## SliderProps Type

`SliderProps` defines the properties for the `Slider` component, which includes the following fields:

- **min** (`number`):
  - The minimum value of the slider.
  - **Required**.

- **max** (`number`):
  - The maximum value of the slider.
  - **Required**.

- **step** (`number`):
  - The step size between each valid value of the slider.
  - **Optional**, defaults to `1`.

- **value** (`number`):
  - The selected value within bounds.
  - **Required**, must be between `min` and `max`.

- **onChanged** (`(value: number) => void`):
  - A callback function that is called whenever the slider value changes.
  - **Required**, called each time the value is updated.

- **onEditingChanged** (`(value: boolean) => void`):
  - An optional callback function called when the editing state of the slider changes.
  - `value` is `true` when editing starts, and `false` when editing ends.

- **label** (`VirtualNode`):
  - An optional view that describes the purpose of the slider. Even if some slider styles do not display the label, the system uses it for accessibility purposes (e.g., VoiceOver).
  - **Optional**.

- **minValueLabel** (`VirtualNode`):
  - An optional view that describes the minimum value of the slider.
  - **Optional**, used only in the `SliderWithRangeValueLabelProps` mode.

- **maxValueLabel** (`VirtualNode`):
  - An optional view that describes the maximum value of the slider.
  - **Optional**, used only in the `SliderWithRangeValueLabelProps` mode.

## SliderWithRangeValueLabelProps Type

`SliderWithRangeValueLabelProps` is a type that defines additional properties for labeling the slider's range. It includes:

- **label** (`VirtualNode`):
  - The label that describes the purpose of the slider.

- **minValueLabel** (`VirtualNode`):
  - The label that describes the minimum value of the slider.

- **maxValueLabel** (`VirtualNode`):
  - The label that describes the maximum value of the slider.

## Other Properties

- **sliderThumbVisibility** (`Visibility`):
  - Sets the visibility of the slider's thumb.
  - iOS 26+ only.

## Usage Example

Here’s an example of using the `Slider` component:

```tsx
import { Slider } from 'scripting'

const ExampleSlider = () => {
  const [value, setValue] = useState(50)

  const handleChange = (newValue: number) => {
    setValue(newValue)
  }

  return (
    <Slider
      min={0}
      max={100}
      value={value}
      onChanged={handleChange}
      label={<Text>Adjust Volume</Text>}
      minValueLabel={<Text>0</Text>}
      maxValueLabel={<Text>100</Text>}
    />
  )
}
```

In this example, the `Slider` component is configured with a range from `0` to `100`, with the default value set to `50`. Labels for the slider's purpose, as well as the minimum and maximum values, are provided.

## Important Notes

- The `min` and `max` properties of the `Slider` must be numeric, and the `value` must be within this range.
- The `onChanged` callback will trigger whenever the slider's value changes, passing the new value.
- If you use `SliderWithRangeValueLabelProps`, you must provide appropriate view elements for `minValueLabel` and `maxValueLabel`.

## Summary

The `Slider` component is a versatile UI control suitable for scenarios where the user needs to select a numerical value. With its flexible properties and callbacks, it can handle a wide range of use cases, especially when labels for the minimum, maximum values, or the slider itself are needed.



---
url: /guide/Views/Controls/Slider/index_example.md
---

# Example

```tsx
import { useState, Slider, Text, VStack, NavigationStack, Navigation, Script } from "scripting"

function Example() {
  const [value, setValue] = useState(15)

  return <NavigationStack>
    <VStack
      navigationTitle={"Slider"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Slider
        min={0}
        max={100}
        value={value}
        onChanged={setValue}
        label={<Text>{value}</Text>}
        minValueLabel={<Text>0</Text>}
        maxValueLabel={<Text>100</Text>}
      />
      <Text>Current value: {value}</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Controls/Stepper/index.md
---

# Stepper

The `Stepper` is a control used for performing increment and decrement actions. It allows the user to increase or decrease a value by tapping the “+” or “-” buttons. The component also supports triggering callback functions when editing starts or ends.

## Properties

### 1. `title` (Optional, String)

- **Description**: Specifies the title of the stepper, typically used to describe the purpose of the stepper.
- **Type**: `string`
- **Example**:
  ```tsx
  <Stepper
    title="Adjust Volume" 
    onIncrement={handleIncrement} 
    onDecrement={handleDecrement} 
  />
  ```

### 2. `children` (Optional, VirtualNode)

- **Description**: A view that describes the purpose of this stepper. Multiple child views can be used to build the appearance of the control. This property is mutually exclusive with the `title` property.
- **Type**: `(VirtualNode | undefined | null | (VirtualNode | undefined | null)[])[] | VirtualNode`
- **Example**:
  ```tsx
  <Stepper 
    onIncrement={handleIncrement} 
    onDecrement={handleDecrement}
  >
    <Text>Adjust Volume</Text>
  </Stepper>
  ```

### 3. `onIncrement` (Required, Callback Function)

- **Description**: A function executed when the user clicks or taps the “+” button.
- **Type**: `() => void`
- **Example**:
  ```tsx
  const handleIncrement = () => {
    console.log("Incremented")
  }

  <Stepper onIncrement={handleIncrement} onDecrement={handleDecrement} />
  ```

### 4. `onDecrement` (Required, Callback Function)

- **Description**: A function executed when the user clicks or taps the “-” button.
- **Type**: `() => void`
- **Example**:
  ```tsx
  const handleDecrement = () => {
    console.log("Decremented")
  }

  <Stepper 
    onIncrement={handleIncrement} 
    onDecrement={handleDecrement} 
  />
  ```

### 5. `onEditingChanged` (Optional, Callback Function)

- **Description**: A function called when editing begins and ends. For example, on iOS, when the user touches and holds the increment or decrement buttons on a Stepper, it triggers the `onEditingChanged` callback to indicate the start and end of the editing gesture.
- **Type**: `(value: boolean) => void`
- **Example**:
  ```tsx
  const handleEditingChanged = (isEditing: boolean) => {
    console.log("Editing started:", isEditing)
  }

  <Stepper
    onIncrement={handleIncrement}
    onDecrement={handleDecrement}
    onEditingChanged={handleEditingChanged}
  />
  ```

## Example Code

Here is a complete example showing how to use the `Stepper` component:

```tsx
const handleIncrement = () => {
  console.log("Volume increased")
}

const handleDecrement = () => {
  console.log("Volume decreased")
}

const handleEditingChanged = (isEditing: boolean) => {
  console.log("Editing started:", isEditing)
}

<Stepper
  title="Volume Control"
  onIncrement={handleIncrement}
  onDecrement={handleDecrement}
  onEditingChanged={handleEditingChanged}
/>
```

## Notes

- The `title` and `children` properties are mutually exclusive. You can use one or the other to describe the purpose of the stepper.
- The `onEditingChanged` callback is optional and only triggered when editing is supported, such as when the user long presses the buttons.

## Summary

The `Stepper` control provides a simple interface to increment and decrement values, with support for triggering callbacks during user interaction. You can configure the `title` or `children` properties to describe the purpose of the control, and use the `onIncrement` and `onDecrement` functions to define actions when the buttons are clicked.



---
url: /guide/Views/Controls/Stepper/index_example.md
---

# Example

```tsx
import { useState, useMemo, Color, Stepper, Text, VStack, RoundedRectangle, HStack, Spacer, NavigationStack, Navigation, Script } from "scripting"

function Example() {
  const [value, setValue] = useState(0)
  const colors = useMemo<Color[]>(() => ['blue', 'red', 'green', 'purple'], [])
  const color = colors[value]

  function incrementStep() {
    if (value + 1 >= colors.length) {
      setValue(0)
    } else {
      setValue(value + 1)
    }
  }

  function decrementStep() {
    if (value - 1 < 0) {
      setValue(colors.length - 1)
    } else {
      setValue(value - 1)
    }
  }

  return <NavigationStack>
    <VStack
      navigationTitle={"Stepper"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Stepper
        title={"Stepper"}
        onIncrement={incrementStep}
        onDecrement={decrementStep}
      />
      <HStack>
        <Text>Value: {value}</Text>
        <Spacer />
        <RoundedRectangle
          fill={color}
          cornerRadius={4}
          frame={{
            width: 120,
            height: 30
          }}
        />
      </HStack>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Controls/Toggle/index.md
---

# Toggle

The `Toggle` component in the Scripting app provides a view control that allows users to toggle between "on" and "off" states. It supports various configuration options to suit different use cases, including user interaction handlers, intents for automation, and customization for display purposes.

## ToggleProps

The `ToggleProps` type defines the configuration options for the `Toggle` component.

### Properties

#### **value**

- **Type**: `boolean`
- **Description**: Indicates whether the toggle is currently in the "on" (`true`) or "off" (`false`) state.
- **Required**: Yes

***

#### **onChanged**

- **Type**: `(value: boolean) => void`
- **Description**: A handler function that is invoked whenever the toggle state changes. It receives the new state (`true` or `false`) as a parameter.
- **Required**: Yes, if `intent` is not provided.

***

#### **intent**

- **Type**: `AppIntent<any>`
- **Description**: An `AppIntent` to execute when the toggle is toggled. This is available only for `Widget` or `LiveActivity` contexts.
- **Required**: Yes, if `onChanged` is not provided.

***

#### **title**

- **Type**: `string`
- **Description**: A short string describing the purpose of the toggle.
- **Optional**: Yes, mutually exclusive with `children`.

***

#### **systemImage**

- **Type**: `string`
- **Description**: The name of an image resource to display alongside the toggle, typically for enhancing the description.
- **Optional**: Yes, available only if `title` is provided.

***

#### **children**

- **Type**: `(VirtualNode | undefined | null | (VirtualNode | undefined | null)[])[] | VirtualNode`
- **Description**: A custom view that describes the purpose of the toggle, offering a more flexible alternative to `title`.
- **Optional**: Yes, mutually exclusive with `title`.

***

## ToggleStyle

Defines the appearance and behavior of the `Toggle`. It can be configured through the `toggleStyle` property in `CommonViewProps`.

### Options

- **`'automatic'`**: Automatically chooses the most appropriate style based on context.
- **`'switch'`**: Displays the toggle as a traditional switch.
- **`'button'`**: Displays the toggle as a button.

***

## CommonViewProps

`CommonViewProps` provides additional customization options for the `Toggle`.

### Properties

#### **toggleStyle**

- **Type**: `'automatic' | 'switch' | 'button'`
- **Description**: Specifies the appearance and behavior of the toggle. Defaults to `'automatic'` if not set.
- **Optional**: Yes

***

## Usage Examples

### Example 1: Basic Toggle with State Change Handler

```tsx
import { Toggle } from 'scripting'

function MyComponent() {
  const [isEnabled, setIsEnabled] = useState(false)

  return (
    <Toggle 
      value={isEnabled} 
      onChanged={newValue => setIsEnabled(newValue)} 
      title="Enable Notifications" 
      systemImage="bell"
    />
  )
}
```

***

### Example 2: Toggle with AppIntent

```tsx
import { Toggle, } from 'scripting'
import { SomeToggleIntent } from "./app_intents"

function MyWidget() {
  const checked = getCheckedState()
  return (
    <Toggle 
        value={checked} 
        intent={SomeToggleIntent(checked)} 
        title="Perform Action" 
        systemImage="action"
    />
  )
}
```

## See `Interactive Widget and LiveActivity` documentation for more information about `AppIntent`.

### Example 3: Toggle with Custom View

```tsx
import { Toggle, HStack } from 'scripting'

function MyComponent() {
  const [isEnabled, setIsEnabled] = useState(false)

  return (
    <Toggle 
      value={isEnabled} 
      onChanged={newValue => setIsEnabled(newValue)}
    >
      <HStack>
        <Text>Enable Feature</Text>
        <Image imageUrl="https://example.com/feature-icon.png" />
      </HStack>
    </Toggle>
  )
}
```

***

### Example 4: Toggle with `toggleStyle`

```tsx
import { Toggle } from 'scripting'

function StyledToggle() {
  const [isActive, setIsActive] = useState(false)

  return (
    <Toggle 
      value={isActive} 
      onChanged={newValue => setIsActive(newValue)} 
      title="Styled Toggle" 
      toggleStyle="button"
    />
  )
}
```

***

This documentation ensures developers can utilize the `Toggle` component effectively, leveraging its versatility for creating dynamic and interactive UI experiences in the Scripting app.



---
url: /guide/Views/Controls/Toggle/index_example.md
---

# Example

```tsx
import { useState, VStack, Toggle, Text, Navigation, Script, NavigationStack } from "scripting"

function Example() {
  const [on, setOn] = useState(false)

  return <NavigationStack>
    <VStack
      navigationTitle={"Toggle"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Toggle
        title={"Toggle Switch"}
        value={on}
        onChanged={setOn}
      />
      <Text>Current: {on ? 'on' : 'off'}</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Dialog (Python).md
---

# 

***

title: Dialog (Python)
description: Python-side Dialog API mirroring the JS Dialog namespace: synchronous alert / confirm / prompt / actionSheet wrappers around the host's modal UI.

***

The `scripting` Python package exposes `Dialog`, mirroring the JS-side `Dialog` namespace. It provides synchronous wrappers around the host's modal UI — alerts, confirms, prompts and action sheets. Each call blocks until the user dismisses the dialog and returns the result.

```python
import scripting; Dialog = scripting.Dialog
```

The dialog is displayed on top of the currently visible view controller, so this only makes sense when the host app is in the foreground (e.g. when the user explicitly ran the script from the app).

***

## Methods

### `Dialog.alert(message, title=None, buttonLabel=None) -> None`

Show a single-button alert. Returns when the user taps the dismiss button.

```python
import scripting; Dialog = scripting.Dialog
Dialog.alert("Operation completed", title="Done")
```

| Param       | Type | Required | Description                                              |
| ----------- | ---- | -------- | -------------------------------------------------------- |
| message     | str  | Yes      | Body text of the alert.                                  |
| title       | str  | No       | Optional title above the message.                        |
| buttonLabel | str  | No       | Custom dismiss button label. Defaults to localized `OK`. |

### `Dialog.confirm(message, title=None, cancelLabel=None, confirmLabel=None) -> bool`

Show a two-button confirm dialog. Returns `True` when the user taps the confirm button, `False` for cancel.

```python
import scripting; Dialog = scripting.Dialog

if Dialog.confirm("Delete the file?", title="Confirm",
                  cancelLabel="Keep", confirmLabel="Delete"):
    delete_file()
```

| Param        | Type | Required | Description                  |
| ------------ | ---- | -------- | ---------------------------- |
| message      | str  | Yes      | Body text.                   |
| title        | str  | No       | Title.                       |
| cancelLabel  | str  | No       | Custom cancel button label.  |
| confirmLabel | str  | No       | Custom confirm button label. |

### `Dialog.prompt(title=None, message=None, defaultValue=None, placeholder=None, obscureText=False, cancelLabel=None, confirmLabel=None) -> str | None`

Show a text-input prompt. Returns the entered string, or `None` if the user cancelled.

```python
import scripting; Dialog = scripting.Dialog

name = Dialog.prompt(title="Your name", placeholder="Alice")
if name is not None:
    print(f"Hello, {name}")
```

| Param        | Type | Required | Description                                                         |
| ------------ | ---- | -------- | ------------------------------------------------------------------- |
| title        | str  | No       | Title.                                                              |
| message      | str  | No       | Optional supporting text below the title.                           |
| defaultValue | str  | No       | Pre-filled text in the input.                                       |
| placeholder  | str  | No       | Placeholder shown when the input is empty.                          |
| obscureText  | bool | No       | When `True`, masks the input (password style). Defaults to `False`. |
| cancelLabel  | str  | No       | Custom cancel button label.                                         |
| confirmLabel | str  | No       | Custom confirm button label.                                        |

### `Dialog.actionSheet(title, actions, message=None, cancelButton=True) -> int | None`

Show an action sheet with multiple choices. Returns the index of the chosen action (0-based), or `None` if cancelled.

```python
import scripting; Dialog = scripting.Dialog

idx = Dialog.actionSheet(
    title="Choose an export format",
    actions=[
        {"label": "JSON"},
        {"label": "CSV"},
        {"label": "Delete original", "destructive": True},
    ],
)
if idx == 0:
    export_json()
elif idx == 1:
    export_csv()
elif idx == 2:
    delete_original()
```

| Param        | Type        | Required | Description                                                                                   |
| ------------ | ----------- | -------- | --------------------------------------------------------------------------------------------- |
| title        | str         | Yes      | Sheet title.                                                                                  |
| actions      | list\[dict] | Yes      | List of `{"label": str, "destructive": bool?}`. `destructive=True` renders the action in red. |
| message      | str         | No       | Optional supporting text.                                                                     |
| cancelButton | bool        | No       | Show a cancel button (defaults to `True`).                                                    |



---
url: /guide/Views/Dialog/index.md
---

# Dialog

The `Dialog` module provides convenient methods to present various types of user interface dialogs such as alerts, confirmations, prompts, and action sheets. These dialogs are useful for requesting user input or interaction during script execution.

***

## Module: `Dialog`

### ▸ `Dialog.alert(options: { message: string, title?: string, buttonLabel?: string }): Promise<void>`

Displays a simple alert dialog with a message and an optional title and button label. The dialog shows a single button and resolves when the user dismisses it.

#### Parameters

- `message` (`string`) – The main message displayed in the alert.
- `title?` (`string`) – Optional title shown above the message.
- `buttonLabel?` (`string`) – The text for the dismiss button. Defaults to `"OK"`.

#### Returns

- A `Promise<void>` that resolves after the user taps the button.

#### Example

```ts
await Dialog.alert({
  title: 'Notice',
  message: 'This operation completed successfully.',
  buttonLabel: 'Got it'
})
```

***

### ▸ `Dialog.confirm(options: { message: string, title?: string, cancelLabel?: string, confirmLabel?: string }): Promise<boolean>`

Displays a confirmation dialog with cancel and confirm options. Resolves to `true` if the user confirms, or `false` if the user cancels.

#### Parameters

- `message` (`string`) – The confirmation message.
- `title?` (`string`) – Optional title.
- `cancelLabel?` (`string`) – Label for the cancel button. Defaults to `"Cancel"`.
- `confirmLabel?` (`string`) – Label for the confirm button. Defaults to `"OK"`.

#### Returns

- A `Promise<boolean>` indicating the user's choice.

#### Example

```ts
const confirmed = await Dialog.confirm({
  title: 'Delete File',
  message: 'Are you sure you want to delete this file?',
  cancelLabel: 'No',
  confirmLabel: 'Yes'
})

if (confirmed) {
  // Proceed with deletion
}
```

***

### ▸ `Dialog.prompt(options: {...}): Promise<string | null>`

Displays a prompt dialog where the user can enter text. The result is a string if the user confirms or `null` if the user cancels.

#### Parameters

- `title` (`string`) – Required title explaining what the prompt is for.
- `message?` (`string`) – Optional supporting message.
- `defaultValue?` (`string`) – Pre-filled text in the input field.
- `obscureText?` (`boolean`) – Whether to obscure input (e.g., for passwords).
- `selectAll?` (`boolean`) – Whether the input text should be fully selected initially.
- `placeholder?` (`string`) – Placeholder text for the input.
- `cancelLabel?` (`string`) – Text for the cancel button.
- `confirmLabel?` (`string`) – Text for the confirm button.
- `keyboardType?` (`KeyboardType`) – The type of keyboard to display (e.g., numeric, email).

#### Returns

- A `Promise<string | null>` with the user's input, or `null` if canceled.

#### Example

```ts
const name = await Dialog.prompt({
  title: 'Enter your name',
  placeholder: 'Full name',
  defaultValue: 'John Doe',
  confirmLabel: 'Submit',
  cancelLabel: 'Cancel'
})

if (name != null) {
  console.log(`Hello, ${name}`)
}
```

***

### ▸ `Dialog.actionSheet(options: {...}): Promise<number | null>`

Displays an action sheet with multiple selectable options. Resolves to the index of the selected action, or `null` if canceled.

#### Parameters

- `title` (`string`) – Title of the action sheet.
- `message?` (`string`) – Optional descriptive message.
- `cancelButton?` (`boolean`) – Whether to show a cancel button. Defaults to `true`.
- `actions` (`{ label: string, destructive?: boolean }[]`) – A list of actions. Use `destructive: true` to visually highlight a destructive action.

#### Returns

- A `Promise<number | null>` indicating the index of the selected action, or `null` if the user canceled.

#### Example

```ts
const index = await Dialog.actionSheet({
  title: 'Do you want to delete this image?',
  actions: [
    { label: 'Delete', destructive: true },
    { label: 'Keep' }
  ]
})

if (index === 0) {
  // User chose "Delete"
} else if (index === 1) {
  // User chose "Keep"
} else {
  // User canceled
}
```

***

## Summary

| Function      | Purpose                          | Return Type                |   |
| ------------- | -------------------------------- | -------------------------- | - |
| `alert`       | Show a message with an OK button | `Promise<void>`            |   |
| `confirm`     | Ask for confirmation (Yes/No)    | `Promise<boolean>`         |   |
| `prompt`      | Ask for user input               | `Promise<string  \| null>` |   |
| `actionSheet` | Show multiple options            | `Promise<number  \| null>` |   |



---
url: /guide/Views/Dialog/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, } from "scripting"

function Example() {

  return <NavigationStack>
    <List
      navigationTitle={"Dialog"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Button
        title={"Dialog.alert"}
        action={async () => {
          await Dialog.alert({
            message: "This is message",
            title: "Alert",
          })
          console.log("Alert dismissed")
        }}
      />

      <Button
        title={"Dialog.prompt"}
        action={async () => {
          const result = await Dialog.prompt({
            title: "Rename script",
            placeholder: "Enter script name",
          })

          Dialog.alert({
            message: result == null
              ? "You cancel the prompt"
              : "The new script name is: " + result
          })
        }}
      />

      <Button
        title={"Dialog.actionSheet"}
        action={async () => {
          const selectedIndex = await Dialog.actionSheet({
            title: "Are you sure to delete this script?",
            message: "This operation cannot be undone.",
            cancelButton: true,
            actions: [
              {
                label: "Delete",
                destructive: true,
              }
            ]
          })

          if (selectedIndex === 0) {
            Dialog.alert({
              message: "The script is deleted."
            })
          }
        }}
      />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/DirectoryBrowserView/index.md
---

# DirectoryBrowserView

`DirectoryBrowserView` displays the contents of a local directory and provides built-in file management actions.

It can preview text files in the editor, preview binary files with Quick Look, import files, export files, rename items, delete items, and navigate into subdirectories.

## Props

```ts
type DirectoryBrowserViewProps = {
  title: string
  directoryPath?: string | null
  onFilesChanged?: () => void
}
```

| Property         | Type             | Description                                                          |
| ---------------- | ---------------- | -------------------------------------------------------------------- |
| `title`          | `string`         | The title displayed in the navigation bar.                           |
| `directoryPath`  | `string \| null` | The directory to browse. If omitted, the view shows an empty folder. |
| `onFilesChanged` | `() => void`     | Called after importing, renaming, deleting, or saving a file.        |

## Example

```tsx
<NavigationStack>
  <DirectoryBrowserView
    title="Workspace"
    directoryPath={Script.directoryPath}
    onFilesChanged={() => console.log("Files changed")}
  />
</NavigationStack>
```

## Notes

- Place this view inside `NavigationStack` so subdirectory navigation works naturally.
- The view creates the target directory if it does not already exist.
- Text files open in the editor and can be saved back to disk.
- Non-text files open with Quick Look.
- `onFilesChanged` is useful when you need to refresh dependent state after file operations.



---
url: /guide/Views/DirectoryBrowserView/index_example.md
---

# Example

```tsx
import { DirectoryBrowserView, Navigation, NavigationStack, Script } from "scripting"

function Example() {
  return <NavigationStack>
    <DirectoryBrowserView
      title="Script Directory"
      directoryPath={Script.directoryPath}
      onFilesChanged={() => console.log("Files changed")}
    />
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Displaying text/Quick Start/index.md
---

# Quick Start

The `Text` component is used to display one or more lines of read-only text in the Scripting app. It supports plain text, attributed text (Markdown), and rich text styling.

***

## **Type Definitions**

### `TextProps`

Defines the properties that can be passed to the `Text` component. There are three possible structures for the `TextProps` type:

1. **Plain Text Props**
   - `children` (optional):
     - Type: `null | string | number | boolean | Array<string | number | boolean | undefined | null>`
     - Description: The content to render as plain text. Can be a single value or an array of values.
   - Example:
     ```tsx
     <Text>Simple plain text</Text>
     ```

2. **Markdown Text Props**
   - `attributedString` (optional):
     - Type: `string`
     - Description: Specifies the text content in Markdown format.
   - Example:
     ```tsx
     <Text attributedString="**Bold** _Italic_ [Link](https://example.com)" />
     ```

3. **Rich Text Props**
   - `styledText` (optional):
     - Type: `StyledText`
     - Description: Specifies rich text content with customizable styles and attributes.
   - Example:
     ```tsx
     const richText: StyledText = {
       font: "title",
       bold: true,
       underlineStyle: "single",
       underlineColor: "#0000FF",
       content: "Rich styled text"
     }
     <Text styledText={richText} />
     ```

***

### `UnderlineStyle`

Defines the available underline styles for rich text:

- `"byWord"`: Underline each word.
- `"double"`: Double underline.
- `"patternDash"`: Dashed underline.
- `"patternDashDot"`: Dash-dot underline.
- `"patternDashDotDot"`: Dash-dot-dot underline.
- `"patternDot"`: Dotted underline.
- `"single"`: Single underline.
- `"thick"`: Thick underline.

***

### `StyledText`

Defines the structure for rich text styling:

- `font` (optional): Specifies the font name. Example: `"title"`, `"body"`.
- `fontDesign` (optional): Customizes the font design. Example: `"serif"`, `"monospaced"`.
- `fontWeight` (optional): Adjusts font weight. Example: `"light"`, `"bold"`.
- `italic` (optional): Adds italic styling. Type: `boolean`.
- `bold` (optional): Adds bold styling. Type: `boolean`.
- `baselineOffset` (optional): Adjusts text's baseline position. Type: `number`.
- `kerning` (optional): Adjusts spacing between characters. Type: `number`.
- `monospaced` (optional): Uses a monospaced font. Type: `boolean`.
- `monospacedDigit` (optional): Ensures consistent width for numeric characters. Type: `boolean`.
- `underlineColor` (optional): Color for the underline. Type: `Color`.
- `underlineStyle` (optional): Style for the underline. Type: `UnderlineStyle`.
- `strokeColor` (optional): Color for the text stroke. Type: `Color`.
- `strokeWidth` (optional): Width of the text stroke. Type: `number`.
- `strikethroughColor` (optional): Color for the strikethrough. Type: `Color`.
- `strikethroughStyle` (optional): Style for the strikethrough. Type: `UnderlineStyle`.
- `foregroundColor` (optional): Text color. Type: `Color`.
- `backgroundColor` (optional): Background color for the text. Type: `Color`.
- `content` (required): Specifies the text content. Can be a string or an array of strings and `StyledText` objects.
- `link` (optional): URL to linkify the text. Type: `string`.
- `onTapGesture` (optional): A function to execute when the text is tapped. Type: `() => void`.

***

## **`Text` Component**

### **Description**

A view that displays one or more lines of read-only text. The content can be styled using the properties in `TextProps`.

### **Example Usages**

1. **Plain Text**
   ```tsx
   <Text font="title">
     Hello world!
   </Text>
   ```

2. **Markdown Text**
   ```tsx
   <Text attributedString="This is **bold**, _italic_, and a [link](https://example.com)." />
   ```

3. **Rich Text**
   ```tsx
   const richText: StyledText = {
     font: "body",
     bold: true,
     underlineStyle: "single",
     underlineColor: "#00FF00",
     foregroundColor: "#FF0000",
     content: [
       "Part 1, ",
       {
         content: "Styled",
         italic: true,
         strokeColor: "#0000FF",
         strokeWidth: 2
       },
       ", Part 2"
     ]
   }

   <Text styledText={richText} />
   ```

***

## Notes

- **Default Font:** When `font` is not specified, the default system font is used.
- **Performance:** For dynamic or frequently updating content, ensure the `styledText` object remains immutable to avoid unnecessary re-renders.
- **Tap Gestures:** Use the `onTapGesture` property within `StyledText` to add interactivity.



---
url: /guide/Views/Displaying text/Quick Start/index_example.md
---

# Example

```tsx
import { Label, List, Markdown, Navigation, NavigationStack, Script, Section, Text, VStack } from "scripting"

function View() {
  return <NavigationStack>
    <List>
      <Section title={"Text"}>
        <VStack>
          <Text
            font={"title"}
            foregroundStyle={"systemRed"}
          >
            Title
          </Text>
          <Text
            font={"body"}
            foregroundStyle={"systemBlue"}
          >Hello Scripting!</Text>
          <Text
            foregroundStyle={"systemGreen"}
            font={"footnote"}
            italic
          >
            This is a footnote.
          </Text>
        </VStack>
      </Section>

      <Section title="AttributedString">
        <Text
          attributedString={`This is regular text.
* This is **bold** text, this is *italic* text, and this is ***bold, italic*** text.
~~A strikethrough example~~
\`Monospaced works too\`
Visit Apple: [click here](https://apple.com)`}
        />
      </Section>

      <Section title={"Label"}>
        <Label
          title={"Hello world"}
          systemImage={"globe"}
        />
      </Section>

      <Section title={"Markdown"}>
        <Markdown
          content={`
# Scripting App
Run your *ideas* quickly **with** scripts.
      `}
        />
      </Section>

      <Section title={"RichText"}>
        <Text
          font={16}
          styledText={{
            content: [
              "I agree the ",
              {
                content: "Terms",
                foregroundColor: "systemOrange",
                underlineColor: "systemBlue",
                bold: true,
                onTapGesture: () => {
                  Dialog.alert({
                    message: "OK!"
                  })
                }
              }
            ]
          }}
        />
      </Section>

    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present(<View />)
  Script.exit()
}

run()
```



---
url: /guide/Views/Displaying text/Rich Text.md
---

# Rich Text

The `Text` component supports rendering rich text using the `styledText` property, allowing fine-grained control beyond plain text or Markdown rendering.

With `StyledText`, developers can:

- Apply detailed text styling such as fonts, colors, strokes, and decorations
- Build nested rich text structures
- Add tappable links or gesture handlers
- Control paragraph-level layout and typography

The newly introduced `paragraphStyle` field provides advanced paragraph layout control. It maps conceptually to native paragraph layout systems (similar to `NSParagraphStyle`) and enables:

- Text alignment control
- Line spacing and paragraph spacing
- First-line indentation
- Truncation strategies
- Automatic hyphenation
- Multi-language writing direction support

***

## StyledText

### Type Definition

```ts
type StyledText = {
  font?
  fontDesign?
  fontWeight?
  italic?
  bold?
  baselineOffset?
  kerning?
  monospaced?
  monospacedDigit?

  underlineColor?
  underlineStyle?

  strokeColor?
  strokeWidth?

  strikethroughColor?
  strikethroughStyle?

  foregroundColor?
  backgroundColor?

  paragraphStyle?: ParagraphStyle

  content: string | (string | StyledText)[]
  link?: string
  onTapGesture?: () => void
}
```

***

### content

Defines the text content.

Can be:

- A string
- An array of strings and nested `StyledText` objects

Example:

```tsx
<Text
  styledText={{
    content: [
      "Hello ",
      {
        content: "world",
        bold: true,
        foregroundColor: "blue"
      }
    ]
  }}
/>
```

***

### Font-related Properties

| Property        | Description          |
| --------------- | -------------------- |
| font            | Font style           |
| fontDesign      | Font design variant  |
| fontWeight      | Font weight          |
| italic          | Applies italic style |
| bold            | Applies bold style   |
| baselineOffset  | Baseline offset      |
| kerning         | Character spacing    |
| monospaced      | Monospaced font      |
| monospacedDigit | Monospaced digits    |

***

### Decoration Properties

#### Underline

```ts
underlineColor
underlineStyle
```

Supported `UnderlineStyle` values:

- single
- double
- thick
- byWord
- patternDash
- patternDashDot
- patternDashDotDot
- patternDot

***

#### Strikethrough

```ts
strikethroughColor
strikethroughStyle
```

***

#### Stroke (Outline)

```ts
strokeColor
strokeWidth
```

***

### Color Properties

```ts
foregroundColor
backgroundColor
```

***

### Interaction Properties

#### link

Defines a URL link.

#### onTapGesture

Tap gesture callback.

***

## ParagraphStyle

### Overview

`paragraphStyle` controls paragraph-level typography and layout behavior.

Recommended for:

- Multi-line text layouts
- Reading interfaces
- Rich typography layouts
- Multi-language content

***

### alignment

Text alignment.

```ts
alignment?: "left" | "center" | "right" | "justified" | "natural"
```

- left: left-aligned
- center: centered
- right: right-aligned
- justified: fully justified
- natural: system default

***

### firstLineHeadIndent

Indentation applied only to the first line.

```ts
firstLineHeadIndent?: number
```

Example:

```tsx
paragraphStyle: {
  firstLineHeadIndent: 20
}
```

***

### headIndent

Left indentation applied to lines except the first.

***

### tailIndent

Right-side indentation.

Note:

- Positive values are measured from the left
- Negative values are measured from the right

***

### paragraphSpacing

Additional spacing between paragraphs.

***

### lineSpacing

Line spacing between lines.

***

### lineBreakMode

Text truncation and wrapping strategy.

```ts
lineBreakMode?:
  | "byCharWrapping"
  | "byClipping"
  | "byTruncatingHead"
  | "byTruncatingTail"
  | "byTruncatingMiddle"
```

Descriptions:

- byCharWrapping: wrap by character
- byClipping: clip overflow
- byTruncatingHead: truncate at head
- byTruncatingTail: truncate at tail
- byTruncatingMiddle: truncate in middle

***

### minLineHeight / maxLineHeight

Control minimum and maximum line height.

***

### lineHeightMultiple

Multiplier applied to the natural line height.

Example:

```ts
lineHeightMultiple: 1.5
```

***

### baseWritingDirection

Writing direction.

```ts
baseWritingDirection?: "natural" | "leftToRight" | "rightToLeft"
```

Useful for:

- RTL language support
- Mixed-direction text

***

### hyphenationFactor

Hyphenation level (0–1).

Higher values increase likelihood of word splitting.

***

### usesDefaultHyphenation

Whether to use system default hyphenation behavior.

***

## Full Example

```tsx
<Text
  styledText={{
    content: "This is a rich text paragraph example demonstrating paragraphStyle.",
    foregroundColor: "label",
    paragraphStyle: {
      alignment: "justified",
      firstLineHeadIndent: 20,
      lineSpacing: 6,
      paragraphSpacing: 12,
      lineHeightMultiple: 1.4
    }
  }}
/>
```

***

## Usage Recommendations

### When to Use paragraphStyle

Recommended scenarios:

- Long-form reading interfaces
- Article typography
- Chat bubble layout improvements
- Multi-language typesetting
- Custom text layout

***

### Choosing Between styledText and Markdown

| Scenario                       | Recommendation              |
| ------------------------------ | --------------------------- |
| Simple formatting              | Markdown                    |
| Highly customizable styling    | styledText                  |
| Paragraph-level layout control | styledText + paragraphStyle |

***

### Performance Tips

- Avoid excessively deep nesting
- Reuse style objects when possible
- For long content, consider splitting into segments



---
url: /guide/Views/Editor/index.md
---

# Editor

A powerful code editor that can be controlled programmatically or embedded into a user interface. It supports syntax highlighting, read/write access, and flexible presentation using the `EditorController` class and the `Editor` component.

***

## EditorController

### Overview

`EditorController` is used to manage an instance of the editor. It allows you to configure the editor content, track changes, present the UI, and release resources.

### Constructor

Creates a new editor controller instance.

**Parameters**:

- `content` (optional): The initial text content displayed in the editor.
- `ext` (optional): The file extension used to determine syntax highlighting. Supported values include `tsx`, `ts`, `js`, `jsx`, `txt`, `md`, `css`, `html`, and `json`.
- `readOnly` (optional): If `true`, the editor is set to read-only mode. Defaults to `false`.

***

### Properties

#### `ext`

A read-only string indicating the file extension type provided during initialization. It determines the language syntax used in the editor.

#### `content`

A string representing the current content of the editor. You can assign a new value to update the editor programmatically.

#### `onContentChanged`

An optional callback function that will be triggered when the content is changed by the user. This callback is **not called immediately**, but approximately 100 milliseconds after editing occurs. This allows for debounced content tracking or autosave behavior.

***

### Methods

#### `present(options?)`

Displays the editor modally.

**Parameters**:

- `navigationTitle` (optional): Set the navigation title of the editor.
- `scriptName` (optional): A custom script name that overrides the default `Script.name` while the editor is running. Defaults to `"Temporary Script"`.
- `fullscreen` (optional): A boolean value that determines whether the editor should be presented in fullscreen mode. Defaults to `false`.

**Returns**: A Promise that resolves when the editor is dismissed.

#### `dismiss()`

Dismisses the currently presented editor view. This does **not** dispose of the controller instance, so you can call `present()` again later.

**Returns**: A Promise that resolves when dismissal is complete.

#### Navigation

- `scrollToLine(line)`: Scroll so the given **1-based** line is centered and place the cursor there.
- `scrollToPosition(position)`: Scroll so the given character offset is centered and place the cursor there.
- `scrollSelectionIntoView()`: Scroll so the current selection is visible.

#### Selection & text

- `getSelectedText(): Promise<string>`: Get the currently selected text (empty string when there is no selection). The promise **rejects** if the editor is not presented (timeout) or has been disposed.
- `setSelection(start, end)`: Select the range `[start, end)` and scroll it into view.
- `replaceSelection(text)`: Replace the current selection with `text`. When there is no selection, the text is inserted at the cursor.
- `selectAll()`: Select all text.

#### Search

- `searchText(query, options?): Promise<EditorTextRange[]>`: Search the whole document and return all matched ranges (`{ start, end, line }`). `options` supports `caseSensitive`, `regexp`, and `wholeWord`. The matching runs inside the editor, so you don't have to compute offsets yourself.

Scripting does not impose a built-in search UI — combine `searchText` (or your own matching over `content`) with `setSelection` to highlight a match and `replaceSelection` to replace it, so you can build a search & replace experience that fits your script.

#### Editing

- `undo()` / `redo()`: Undo or redo the last change.
- `toggleLineComment()` / `toggleBlockComment()`: Toggle line or block comments around the current selection.

#### `dispose()`

Releases the resources held by the editor controller. This must be called when the controller is no longer needed to avoid memory leaks. Once disposed, the controller cannot be used again.

***

## Editor Component

The `Editor` component is a React-style view that renders the editor inline within your UI. It is typically used in conjunction with an `EditorController` instance.

**Props**:

- `controller`: An `EditorController` instance that manages the editor's content and behavior.
- `scriptName` (optional): Overrides the default script name for the embedded editor session.
- `showAccessoryView` (optional): Whether to show the accessory view when the keyboard is visible. This is useful for showing buttons like "Move Left", "Move Right", "Delete", "Dissmiss Keyboard", etc. Defaults to `false`. It is recommended to set this to `true` when the editor is fully visible on the screen, such as when the editor is the only view in the screen.

***

### Example Usage

```tsx
function MyEditor() {
  const controller = useMemo(() => {
    return new EditorController({
      content: `const text = "Hello, World!"`,
      ext: "ts",
      readOnly: false,
    })
  }, [])
  
  useEffect(() => {
    return () => {
      controller.dispose()
    }
  }, [controller])

  return (
    <Editor
      controller={controller}
      scriptName="My Script"
      showAccessoryView
    />
  )
}
```

***

### Example: a custom search & replace bar (`index.tsx`)

This example builds its own search UI on top of the interaction APIs: `searchText` finds the
matches, `setSelection` highlights the current one, and `replaceSelection` replaces it.

```tsx
import { useEffect, useMemo, useState } from "scripting"

function EditorWithSearch() {
  const controller = useMemo(() => new EditorController({
    ext: "ts",
    content: [
      `const greeting = "hello"`,
      `console.log(greeting)`,
      `console.log(greeting.toUpperCase())`,
    ].join("\n"),
  }), [])

  const [query, setQuery] = useState("")
  const [replacement, setReplacement] = useState("")
  const [matches, setMatches] = useState<EditorTextRange[]>([])
  const [index, setIndex] = useState(0)

  useEffect(() => () => controller.dispose(), [controller])

  async function runSearch() {
    const result = await controller.searchText(query, { caseSensitive: false })
    setMatches(result)
    setIndex(0)
    if (result.length > 0) {
      const m = result[0]
      controller.setSelection(m.start, m.end)
    }
  }

  function goTo(next: number) {
    if (matches.length === 0) return
    const i = (next + matches.length) % matches.length
    setIndex(i)
    controller.setSelection(matches[i].start, matches[i].end)
  }

  function replaceCurrent() {
    if (matches.length === 0) return
    // The current match is already selected, so just replace the selection,
    // then re-run the search since offsets shifted.
    controller.replaceSelection(replacement)
    runSearch()
  }

  return (
    <VStack>
      <HStack>
        <TextField title="Find" value={query} onChanged={setQuery} />
        <Button title="Search" action={runSearch} />
      </HStack>
      <HStack>
        <TextField title="Replace" value={replacement} onChanged={setReplacement} />
        <Button title="Replace" action={replaceCurrent} />
      </HStack>
      <HStack>
        <Text>{matches.length > 0 ? `${index + 1} / ${matches.length}` : "No matches"}</Text>
        <Button title="Prev" action={() => goTo(index - 1)} />
        <Button title="Next" action={() => goTo(index + 1)} />
      </HStack>
      <Editor controller={controller} showAccessoryView />
    </VStack>
  )
}
```



---
url: /guide/Views/Editor/index_example.md
---

# Example

```tsx
import { Button, Editor, HStack, Navigation, NavigationStack, Script, Spacer, Text, TextField, useEffect, useMemo, useState, VStack } from "scripting"

// 这个示例基于 EditorController 的交互 API 自建一个搜索 / 替换栏：
//   - searchText  查找所有匹配（编辑器内完成，返回 { start, end, line }）
//   - setSelection 高亮当前匹配并滚动到可见
//   - replaceSelection 替换当前选中的匹配
//   - scrollToLine 跳转到指定行
// Scripting 不内置搜索 UI，你可以像这样组合出契合脚本的体验。

function Example() {
  const controller = useMemo(() => new EditorController({
    ext: "ts",
    content: [
      `const greeting = "hello"`,
      `console.log(greeting)`,
      `console.log(greeting.toUpperCase())`,
      `console.log(greeting.length)`,
    ].join("\n"),
  }), [])

  const [query, setQuery] = useState("greeting")
  const [replacement, setReplacement] = useState("message")
  const [matches, setMatches] = useState<EditorTextRange[]>([])
  const [index, setIndex] = useState(0)

  // 不再使用时释放编辑器资源。
  useEffect(() => () => controller.dispose(), [controller])

  async function runSearch() {
    const result = await controller.searchText(query, { caseSensitive: false })
    setMatches(result)
    setIndex(0)
    if (result.length > 0) {
      controller.setSelection(result[0].start, result[0].end)
    }
  }

  function goTo(next: number) {
    if (matches.length === 0) {
      return
    }
    const i = (next + matches.length) % matches.length
    setIndex(i)
    controller.setSelection(matches[i].start, matches[i].end)
  }

  async function replaceCurrent() {
    if (matches.length === 0) {
      return
    }
    // 当前匹配已被选中，直接替换选区；替换后偏移变化，重新搜索。
    controller.replaceSelection(replacement)
    await runSearch()
  }

  return <NavigationStack>
    <VStack
      navigationTitle={"Editor Search"}
      navigationBarTitleDisplayMode={"inline"}
      spacing={8}
      padding
    >
      <HStack>
        <TextField title={"Find"} value={query} onChanged={setQuery} />
        <Button title={"Search"} action={runSearch} />
      </HStack>

      <HStack>
        <TextField title={"Replace"} value={replacement} onChanged={setReplacement} />
        <Button title={"Replace"} action={replaceCurrent} />
      </HStack>

      <HStack>
        <Text>{matches.length > 0 ? `${index + 1} / ${matches.length}` : "No matches"}</Text>
        <Spacer />
        <Button title={"Prev"} action={() => goTo(index - 1)} />
        <Button title={"Next"} action={() => goTo(index + 1)} />
        <Button title={"Top"} action={() => controller.scrollToLine(1)} />
      </HStack>

      <Editor controller={controller} showAccessoryView />
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/EnvironmentValuesReader.md
---

# EnvironmentValuesReader

`EnvironmentValuesReader` is a Scripting component that allows you to read environment values from the current view hierarchy.
It serves a similar role to SwiftUI’s `@Environment`, but with a more explicit and controlled design:
**You must specify which environment keys you want to read**, and the component will inject only those values into the `children` callback.

This makes environment access predictable, explicit, and optimized.

***

## EnvironmentValues Type

```ts
type EnvironmentValues = {
    colorScheme: ColorScheme;
    colorSchemeContrast: ColorSchemeContrast;
    displayScale: number;
    horizontalSizeClass: UserInterfaceSizeClass | null;
    verticalSizeClass: UserInterfaceSizeClass | null;
    dismiss: () => void;
    dismissSearch: () => void;
    editMode: EditMode | null;
    layoutDirection: "leftToRight" | "rightToLeft";
    widgetRenderingMode: WidgetRenderingMode;
    showsWidgetContainerBackground: boolean;
    isSearching: boolean;
    isPresented: boolean;
    activityFamily: "small" | "medium";
    tabViewBottomAccessoryPlacement: 'expanded' | 'inline';
};
```

Below are the descriptions of each field.

***

## Field Descriptions

### 1. colorScheme

Type: `ColorScheme`
The current system color appearance (`light` or `dark`).

***

### 2. colorSchemeContrast

Type: `ColorSchemeContrast`
Represents contrast settings such as `standard` or `increased`.

***

### 3. displayScale

Type: `number`
The display scale factor of the device (e.g., **2.0**, **3.0**).

***

### 4. horizontalSizeClass

Type: `UserInterfaceSizeClass | null`
The horizontal size class of the current environment: `compact` or `regular`.

***

### 5. verticalSizeClass

Type: `UserInterfaceSizeClass | null`
The vertical size class, same categories as above.

***

### 6. dismiss

Type: `() => void`
A function to dismiss the currently presented view (equivalent to SwiftUI’s `dismiss()`).

***

### 7. dismissSearch

Type: `() => void`
A function that dismisses the current searchable field, if active.

***

### 8. editMode

Type: `EditMode | null`
Indicates whether the view is in editing mode (e.g., during List editing).

***

### 9. layoutDirection

Type: `"leftToRight" | "rightToLeft"`
The current layout direction of the view hierarchy.

***

### 10. widgetRenderingMode

Type: `WidgetRenderingMode`
The current widget rendering mode (e.g., `fullColor`, `accented`).

***

### 11. showsWidgetContainerBackground

Type: `boolean`
Indicates whether the widget is showing the system-provided container background.

***

### 12. isSearching

Type: `boolean`
Whether the view is currently in a searching state triggered by `searchable`.

***

### 13. isPresented

Type: `boolean`
Whether the view is currently being shown, unlike `onAppear` which is called every time the view appears, `isPresented` is called only once when the view is first shown.

***

### 14. activityFamily

Type: `"small" | "medium"`
The current LiveActivity size, similar to SwiftUI's `activityFamily`, used to determine the size of LiveActivity UI.

***

### 15. tabViewBottomAccessoryPlacement

Type: `'expanded' | 'inline'`
The current TabView bottom accessory placement, similar to SwiftUI's `tabViewBottomAccessoryPlacement`.

***

## EnvironmentValuesReader Component

```ts
type EnvironmentValuesReaderProps = {
    /**
     * The keys to read from the environment values.
     */
    keys: Array<keyof EnvironmentValues>;
    /**
     * The callback function that receives the environment values.
     */
    children: (values: EnvironmentValues) => VirtualNode;
};
```

***

## Props Description

### keys

Type: `Array<keyof EnvironmentValues>`
Specifies exactly which environment keys you want to read.
Only these keys will be retrieved and passed to the callback.

***

### children(values)

Type: `(values: EnvironmentValues) => VirtualNode`
A rendering callback that receives the requested environment values and returns the corresponding view.

***

## Component Definition

```ts
declare const EnvironmentValuesReader: FunctionComponent<EnvironmentValuesReaderProps>;
```

***

## Usage Examples

## Example 1 — Reading colorScheme and displayScale

```tsx
import { EnvironmentValuesReader, Text, VStack } from "scripting"

function View() {
  return <EnvironmentValuesReader keys={["colorScheme", "displayScale"]}>
    {(env) => {
      return <VStack>
        <Text>Color Scheme: {env.colorScheme}</Text>
        <Text>Scale: {env.displayScale}</Text>
      </VStack>
    }}
  </EnvironmentValuesReader>
}
```

***

## Example 2 — Accessing dismiss

```tsx
<EnvironmentValuesReader keys={["dismiss"]}>
  {(env) => {
    return <Button
      title="Close"
      action={() => env.dismiss()}
    />
  }}
</EnvironmentValuesReader>
```

***

## Example 3 — Dynamic layout using size classes

```tsx
<EnvironmentValuesReader keys={["horizontalSizeClass"]}>
  {(env) => {
    const compact = env.horizontalSizeClass === "compact"
    return compact
      ? <Text>Compact Layout</Text>
      : <Text>Regular Layout</Text>
  }}
</EnvironmentValuesReader>
```

***

## Behavior Notes

1. **Only the explicitly listed keys are read**. All other environment values will not be included in the callback.
2. When any of the requested environment values change, the `children()` callback re-renders automatically.
3. `dismiss` and `dismissSearch` are real functional operations that behave like their SwiftUI equivalents.
4. Environment values originate from the parent view hierarchy (Navigation, searchable, editMode, Widget context, etc.).
5. If a key is not included in `keys`, it will not appear in the `values` object.
6. This API is not intended for global state management—only for accessing the contextual environment of the current view.



---
url: /guide/Views/GeometryReader.md
---

# GeometryReader

`GeometryReader` in Scripting is the equivalent of SwiftUI’s GeometryReader. It provides layout information about the container in which its content is placed, including size, safe-area insets, and (on supported systems) container corner insets.

This component is essential for building responsive layouts that depend on the parent container’s geometry.

***

## GeometryProxy

When `GeometryReader` constructs its child content, it injects a `GeometryProxy` instance into the `children` callback. This proxy exposes real-time layout information about the container.

```ts
interface GeometryProxy {
  readonly size: Size;
  readonly safeAreaInsets: {
    leading: number;
    top: number;
    trailing: number;
    bottom: number;
  };
  /**
   * Requires iOS 26.0+.
   */
  readonly containerCornerInsets: {
    bottomLeading: Size;
    bottomTrailing: Size;
    topLeading: Size;
    topTrailing: Size;
  } | null;
}
```

***

## GeometryProxy Properties

## 1. size

```ts
readonly size: Size
```

The actual size of the container during layout.

### Size structure

```ts
type Size = {
  width: number
  height: number
}
```

Use this property when calculating adaptive layout behavior, such as scaling, alignment, or proportional spacing.

***

## 2. safeAreaInsets

```ts
readonly safeAreaInsets: {
  leading: number
  top: number
  trailing: number
  bottom: number
}
```

Represents the safe-area insets of the current container.
This ensures content does not overlap with the device notch, home indicator, or other system UI elements.

### Common use cases

- Adjusting content away from the screen edges
- Implementing custom navigation bars or toolbars
- Ensuring layout compatibility across devices

***

## 3. containerCornerInsets (iOS 26.0+)

```ts
readonly containerCornerInsets: {
  bottomLeading: Size
  bottomTrailing: Size
  topLeading: Size
  topTrailing: Size
} | null
```

Available only on **iOS 26+**.
Provides layout insets corresponding to the physical or visual rounded corners of the container.

### Use cases

- Adapting UI for windowed environments
- Handling rounded container corners (Stage Manager, split view, floating scenes)
- Performing precision layout aligned to dynamic corner geometry

If the platform does not support it, the value will be `null`.

***

## GeometryReader Component

```ts
type GeometryReaderProps = {
  children: (proxy: GeometryProxy) => VirtualNode;
};
declare const GeometryReader: FunctionComponent<GeometryReaderProps>;
```

## Props

| Name     | Type                                    | Required | Description                                                               |
| -------- | --------------------------------------- | -------- | ------------------------------------------------------------------------- |
| children | `(proxy: GeometryProxy) => VirtualNode` | Yes      | A callback that receives the geometry proxy and returns the view content. |

***

## Behavior

1. GeometryReader occupies the available space in its parent.
2. During layout, it computes size, safe-area insets, and corner insets.
3. It passes these values to the `children(proxy)` callback.
4. The returned VirtualNode content is laid out using these values.

This behavior matches SwiftUI’s GeometryReader model.

***

## Example: Centered Content

```tsx
import { GeometryReader, Text, VStack } from "scripting"

function View() {
  return <GeometryReader>
    {(proxy) => {
      return <VStack
        frame={{
          width: proxy.size.width,
          height: proxy.size.height,
          alignment: "center"
        }}
      >
        <Text>Hello Geometry</Text>
        <Text>
          width: {proxy.size.width}
        </Text>
        <Text>
          height: {proxy.size.height}
        </Text>
      </VStack>
    }}
  </GeometryReader>
}
```

***

## Example: Adjusting Layout by Safe Area

```tsx
<GeometryReader>
  {(proxy) => {
    return <VStack
      padding={{
        top: proxy.safeAreaInsets.top,
        bottom: proxy.safeAreaInsets.bottom
      }}
    >
      <Text>Content inside safe area.</Text>
    </VStack>
  }}
</GeometryReader>
```

***

## Example (iOS 26+): Using containerCornerInsets

```tsx
<GeometryReader>
  {(proxy) => {
    const corners = proxy.containerCornerInsets
    return <Text>
      {corners == null
        ? "Corner insets not available"
        : `Top Leading Corner: ${corners.topLeading.width}, ${corners.topLeading.height}`
      }
    </Text>
  }}
</GeometryReader>
```

***

## Best Practices

- Use GeometryReader only when needed, as it creates a flexible layout container.
- Prefer using it for adaptive, responsive layouts where container size matters.
- Avoid placing complex or deeply nested views inside GeometryReader unless required.



---
url: /guide/Views/Gestures.md
---

# Gestures

The **Scripting app** provides a gesture system similar to SwiftUI, allowing any view (`<VStack>`, `<HStack>`, `<Text>`, etc.) to respond to touch interactions such as tapping, long pressing, dragging, rotating, and magnifying.

You can use:

- Simplified gesture properties like `onTapGesture`, `onLongPressGesture`, `onDragGesture`, or
- Advanced gesture objects such as `TapGesture()`, `LongPressGesture()`, and the `gesture` modifiers for composition and priority control.

***

## 1. Simple Gesture Properties

These are convenient, shorthand ways to add gestures directly to a view.

***

### `onTapGesture`

Executes an action when a tap gesture is recognized.

#### Type

```ts
onTapGesture?: (() => void) | {
  count: number
  perform: () => void
}
```

#### Parameters

| Name      | Type         | Default | Description                                                  |
| --------- | ------------ | ------- | ------------------------------------------------------------ |
| `count`   | `number`     | `1`     | Number of taps required (1 for single tap, 2 for double tap) |
| `perform` | `() => void` | —       | Action to perform when the tap is recognized                 |

#### Examples

```tsx
// Single tap
<VStack onTapGesture={() => console.log('Tapped')} />

// Double tap
<HStack
  onTapGesture={{
    count: 2,
    perform: () => console.log('Double tapped')
  }}
/>
```

***

### `onLongPressGesture`

Executes an action when a long press gesture is recognized.

#### Type

```ts
onLongPressGesture?: (() => void) | {
  minDuration?: number
  maxDuration?: number
  perform: () => void
  onPressingChanged?: (state: boolean) => void
}
```

#### Parameters

| Name                | Type                       | Default | Description                                             |
| ------------------- | -------------------------- | ------- | ------------------------------------------------------- |
| `minDuration`       | `number`                   | `500`   | Minimum press duration (ms) before the gesture succeeds |
| `maxDuration`       | `number`                   | `10000` | Maximum duration before the gesture fails (ms)          |
| `perform`           | `() => void`               | —       | Action to execute when the long press succeeds          |
| `onPressingChanged` | `(state: boolean) => void` | —       | Called when pressing starts or ends (`true` = pressing) |

#### Examples

```tsx
// Simple usage
<VStack onLongPressGesture={() => console.log('Long pressed')} />

// Custom duration and press state callback
<HStack
  onLongPressGesture={{
    minDuration: 800,
    maxDuration: 3000,
    perform: () => console.log('Long press success'),
    onPressingChanged: isPressing =>
      console.log(isPressing ? 'Pressing...' : 'Released')
  }}
/>
```

***

### `onDragGesture`

Adds a drag gesture to a view, tracking position, offset, and velocity.

#### Type

```ts
onDragGesture?: {
  minDistance?: number
  coordinateSpace?: 'local' | 'global'
  onChanged?: (details: DragGestureDetails) => void
  onEnded?: (details: DragGestureDetails) => void
}
```

#### Parameters

| Name              | Type                                    | Default    | Description                                            |                                 |
| ----------------- | --------------------------------------- | ---------- | ------------------------------------------------------ | ------------------------------- |
| `minDistance`     | `number`                                | `10`       | Minimum movement (in points) before the gesture starts |                                 |
| `coordinateSpace` | `'local'`                               | `'global'` | `'local'`                                              | Coordinate space of the gesture |
| `onChanged`       | `(details: DragGestureDetails) => void` | —          | Called as the drag changes                             |                                 |
| `onEnded`         | `(details: DragGestureDetails) => void` | —          | Called when the drag ends                              |                                 |

#### `DragGestureDetails`

```ts
type DragGestureDetails = {
  time: number
  location: Point
  startLocation: Point
  translation: Size
  velocity: Size
  predictedEndLocation: Point
  predictedEndTranslation: Size
}
```

| Field                     | Description                              |
| ------------------------- | ---------------------------------------- |
| `time`                    | Timestamp of the drag event (ms)         |
| `location`                | Current pointer position `{x, y}`        |
| `startLocation`           | Initial drag position                    |
| `translation`             | Offset from start to current position    |
| `velocity`                | Current velocity in points per second    |
| `predictedEndLocation`    | Predicted end position based on velocity |
| `predictedEndTranslation` | Predicted total translation              |

#### Example

```tsx
<VStack
  onDragGesture={{
    minDistance: 5,
    coordinateSpace: 'global',
    onChanged: details => {
      console.log('Location:', details.location)
      console.log('Offset:', details.translation)
    },
    onEnded: details => {
      console.log('Predicted end:', details.predictedEndLocation)
    }
  }}
/>
```

***

## 2. Gesture Classes (Advanced Usage)

For complex interaction handling or gesture composition, use the gesture constructors and modifiers.

***

### `GestureInfo` Class

All gesture constructors return a `GestureInfo` object that defines configuration and callbacks.

```ts
class GestureInfo<Options, Value> {
  type: string
  options: Options
  onChanged(callback: (value: Value) => void): this
  onEnded(callback: (value: Value) => void): this
}
```

| Method                | Description                                              |
| --------------------- | -------------------------------------------------------- |
| `onChanged(callback)` | Called when the gesture changes (e.g. dragging, zooming) |
| `onEnded(callback)`   | Called when the gesture finishes                         |

#### Example

```tsx
<Text
  gesture={
    TapGesture()
      .onEnded(() => console.log('Tapped'))
  }
/>
```

***

### `TapGesture`

Detects single or multiple taps.

```ts
declare function TapGesture(count?: number): GestureInfo<number | undefined, void>
```

| Parameter | Type     | Default | Description             |
| --------- | -------- | ------- | ----------------------- |
| `count`   | `number` | `1`     | Number of taps required |

#### Example

```tsx
<Text
  gesture={
    TapGesture(2)
      .onEnded(() => console.log('Double tapped'))
  }
/>
```

***

### `LongPressGesture`

Detects press and hold gestures.

```ts
declare function LongPressGesture(options?: LongPressGestureOptions): GestureInfo<LongPressGestureOptions, boolean>

type LongPressGestureOptions = {
  minDuration?: number
  maxDuration?: number
}
```

| Parameter     | Default | Description                          |
| ------------- | ------- | ------------------------------------ |
| `minDuration` | `500`   | Minimum press duration (ms)          |
| `maxDuration` | `10000` | Maximum duration before failure (ms) |

#### Example

```tsx
<Text
  gesture={
    LongPressGesture({ minDuration: 800 })
      .onChanged(() => console.log('Pressing...'))
      .onEnded(() => console.log('Long press finished'))
  }
/>
```

***

### `DragGesture`

Tracks finger or pointer movement.

```ts
declare function DragGesture(options?: DragGestureOptions): GestureInfo<DragGestureOptions, DragGestureDetails>

type DragGestureOptions = {
  minDistance?: number
  coordinateSpace?: 'local' | 'global'
}
```

#### Example

```tsx
<VStack
  gesture={
    DragGesture({ coordinateSpace: 'global' })
      .onChanged(d => console.log('Offset', d.translation))
      .onEnded(d => console.log('Velocity', d.velocity))
  }
/>
```

***

### `MagnifyGesture`

Detects pinch zoom gestures.

```ts
declare function MagnifyGesture(minScaleDelta?: number | null): GestureInfo<number | null | undefined, MagnifyGestureValue>

type MagnifyGestureValue = {
  time: Date
  magnification: number
  startAnchor: Point
  startLocation: Point
  velocity: number
}
```

#### Example

```tsx
<Text
  gesture={
    MagnifyGesture(0.05)
      .onChanged(v => console.log('Scale', v.magnification))
      .onEnded(() => console.log('Zoom ended'))
  }
/>
```

***

### `RotateGesture`

Detects rotation gestures.

```ts
declare function RotateGesture(minAngleDelta?: Angle | null): GestureInfo<Angle | null | undefined, RotateGestureValue>

type RotateGestureValue = {
  rotation: AngleValue
  velocity: AngleValue
  startAnchor: Point
  time: Date
}

type AngleValue = {
  radians: number
  degrees: number
  magnitude: number
  animatableData: number
}
```

#### Example

```tsx
<ZStack
  gesture={
    RotateGesture()
      .onChanged(v => console.log('Rotation', v.rotation.degrees))
      .onEnded(() => console.log('Rotation ended'))
  }
/>
```

***

## 3. Gesture Modifiers for Views

All views support the following gesture-related properties.

```ts
type GesturesProps = {
  gesture?: GestureProps
  simultaneousGesture?: GestureProps
  highPriorityGesture?: GestureProps
  defersSystemGestures?: EdgeSet
}
```

***

### `gesture`

Adds a gesture to the view.

```tsx
<Text
  gesture={
    TapGesture()
      .onEnded(() => console.log('Tapped'))
  }
/>
```

***

### `highPriorityGesture`

Adds a gesture with higher priority than existing ones on the view.

```tsx
<Text
  highPriorityGesture={
    TapGesture(2)
      .onEnded(() => console.log('Double tap takes priority'))
  }
/>
```

***

### `simultaneousGesture`

Allows multiple gestures to be recognized simultaneously.

```tsx
<Text
  simultaneousGesture={
    LongPressGesture()
      .onEnded(() => console.log('Long pressed'))
  }
  gesture={
    TapGesture()
      .onEnded(() => console.log('Tapped'))
  }
/>
```

***

### `defersSystemGestures`

Gives your custom gestures precedence over system gestures originating from screen edges.

```tsx
<VStack defersSystemGestures="all">
  <Text>Custom gestures take precedence</Text>
</VStack>
```

#### Accepted Values

| Value          | Description                          |
| -------------- | ------------------------------------ |
| `'top'`        | Top edge                             |
| `'leading'`    | Leading edge (left, or right in RTL) |
| `'trailing'`   | Trailing edge                        |
| `'bottom'`     | Bottom edge                          |
| `'horizontal'` | Left and right edges                 |
| `'vertical'`   | Top and bottom edges                 |
| `'all'`        | All edges                            |

***

## 4. GestureMask

Controls how adding a gesture affects other gestures on the same view or its subviews.

```ts
type GestureMask = "all" | "gesture" | "subviews" | "none"
```

| Value        | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| `"all"`      | Enables both the added gesture and subview gestures (default) |
| `"gesture"`  | Enables only the added gesture, disables subview gestures     |
| `"subviews"` | Enables subview gestures, disables the added gesture          |
| `"none"`     | Disables all gestures                                         |

#### Example

```tsx
<VStack
  gesture={{
    gesture: TapGesture().onEnded(() => console.log('Tapped')),
    mask: 'gesture'
  }}
>
  <Text>Tap here</Text>
</VStack>
```

***

## 5. Summary Table

| Gesture Type | Description                     | Class Constructor    | Shorthand Property   | Common Callbacks             |
| ------------ | ------------------------------- | -------------------- | -------------------- | ---------------------------- |
| Tap          | Detects single or multiple taps | `TapGesture()`       | `onTapGesture`       | `.onEnded()`                 |
| Long Press   | Detects hold gestures           | `LongPressGesture()` | `onLongPressGesture` | `.onChanged()`, `.onEnded()` |
| Drag         | Detects movement                | `DragGesture()`      | `onDragGesture`      | `.onChanged()`, `.onEnded()` |
| Magnify      | Detects pinch zoom              | `MagnifyGesture()`   | —                    | `.onChanged()`, `.onEnded()` |
| Rotate       | Detects rotation                | `RotateGesture()`    | —                    | `.onChanged()`, `.onEnded()` |



---
url: /guide/Views/Image/index.md
---

# Image

The `Image` component allows you to display images from various sources, such as system symbols, network URLs, local files, or `UIImage` objects. It supports dynamic image sources that change based on light or dark color schemes. Additionally, several view modifiers are available to customize the behavior and appearance of the `Image` component.

***

## **Type Definitions**

### `ImageResizable`

Defines how the image should be resized:

- **`boolean`**:

  - `true`: Enables default resizing.
  - `false`: Disables resizing.

- **`object`**:

  - `capInsets` _(optional)_: `EdgeInsets`
    Defines insets for image stretching to control which parts of the image stretch and which remain fixed.

  - `resizingMode` _(optional)_: `ImageResizingMode`
    Specifies the resizing mode, such as scaling or tiling.

### `ImageScale`

Specifies relative image sizes available within the view:

- `'large'`: Renders the image at a large size.
- `'medium'`: Renders the image at a medium size.
- `'small'`: Renders the image at a small size.

### `DynamicImageSource<T>`

Defines a dynamic source that changes based on the system color scheme:

```ts
type DynamicImageSource<T> = {
  dark: T
  light: T
}
```

Used for adapting the image resource for light/dark modes. Supported in:

- `imageUrl` (network images)
- `filePath` (local file images)
- `image` (`UIImage` objects)

***

## **Source Props**

### `SystemImageProps`

- **`systemName`** _(string, required)_
  The name of a system-provided symbol.
  Refer to the [SF Symbols](https://developer.apple.com/design/resources/#sf-symbols) library or use the [SF Symbols Browser](https://apps.apple.com/cn/app/sf-symbols-reference/id1491161336?l=en-GB) app to browse available symbol names.

- **`variableValue`** _(number, optional)_
  A value between `0.0` and `1.0` for customizing the appearance of a variable symbol.
  _(Has no effect for symbols that do not support variable values.)_

- **`resizable`** _(ImageResizable, optional)_
  Configures how the image is resized to fit its allocated space.

### `NetworkImageProps`

- **`imageUrl`** _(string | DynamicImageSource\<string>, required)_
  The URL of the image to load. Supports dynamic sources via `DynamicImageSource`.

- **`placeholder`** _(VirtualNode, optional)_
  A view displayed while the image is loading.

- **`resizable`** _(ImageResizable, optional)_
  Configures how the image is resized to fit its allocated space.

- **`onError`** _((error) => void, optional)_
  A callback invoked when the image fails to load.

### `FileImageProps`

- **`filePath`** _(string | DynamicImageSource\<string>, required)_
  The path to the local image file. Supports dynamic sources via `DynamicImageSource`.

- **`resizable`** _(ImageResizable, optional)_
  Configures how the image is resized to fit its allocated space.

### `UIImageProps`

- **`image`** _(UIImage | DynamicImageSource\<UIImage>, required)_
  A `UIImage` object to display. Supports dynamic sources via `DynamicImageSource`.

- **`resizable`** _(ImageResizable, optional)_
  Configures how the image is resized to fit its allocated space.

***

## **CommonViewProps**

Modifiers applicable to the `Image` component and other views:

- **`scaleToFit`** _(boolean, optional)_
  Scales the view to fit its parent container.

- **`scaleToFill`** _(boolean, optional)_
  Scales the view to fill its parent container.

- **`aspectRatio`** _(object, optional)_
  Configures the view's aspect ratio:

  - **`value`** _(number or null, optional)_: The width-to-height ratio. If `null`, maintains the current aspect ratio.
  - **`contentMode`** _(ContentMode, required)_: Determines whether the content fits or fills its parent.

- **`imageScale`** _(ImageScale, optional)_
  Adjusts the size of images within the view. Options: `'large'`, `'medium'`, `'small'`.

- **`foregroundStyle`** _(ShapeStyle or DynamicShapeStyle or object, optional)_
  Configures the view's foreground elements:

  - **`primary`**: Style for the primary foreground elements.
  - **`secondary`**: Style for secondary elements.
  - **`tertiary`** _(optional)_: Style for tertiary elements.

***

### Rendering Behavior (`ImageRenderingBehaviorProps`)

| Prop                          | Type                                        | Default      | Description                                                     |
| ----------------------------- | ------------------------------------------- | ------------ | --------------------------------------------------------------- |
| `resizable`                   | `boolean \| object`                         | `false`      | Controls whether the image resizes to fit its frame (see below) |
| `renderingMode`               | `'original' \| 'template'`                  | `'original'` | Use `"template"` to allow tinting via `foregroundColor`         |
| `interpolation`               | `'none' \| 'low' \| 'medium' \| 'high'`     | `'medium'`   | Sets interpolation quality when scaling the image               |
| `antialiased`                 | `boolean`                                   | `false`      | Whether the image should use anti-aliasing                      |
| `widgetAccentedRenderingMode` | `WidgetAccentedRenderingMode` (Widget-only) | —            | Defines how the image renders in Widget accented mode           |

***

## **Usage Examples**

1. **Dynamic Network Image Based on Color Scheme**

```tsx
<Image
  imageUrl={{
    light: "https://example.com/image-light.png",
    dark: "https://example.com/image-dark.png"
  }}
  placeholder={<Text>Loading...</Text>}
/>
```

2. **Dynamic Local File Image**

```tsx
<Image
  filePath={{
    light: Path.join(Script.directory, "light-mode.jpg"),
    dark: Path.join(Script.directory, "dark-mode.jpg")
  }}
  resizable={true}
/>
```

3. **Dynamic UIImage Object**

```tsx
const lightImg = UIImage.fromFile('/path/to/light.png')
const darkImg = UIImage.fromFile('/path/to/dark.png')

<Image image={{ light: lightImg, dark: darkImg }} />
```

4. **System Symbol with Aspect Ratio and Scaling**

```tsx
<Image
  systemName="square.and.arrow.up.circle"
  scaleToFit={true}
  aspectRatio={{ value: 1.0, contentMode: "fit" }}
  imageScale="medium"
  foregroundStyle={{
    primary: "blue",
    secondary: "gray",
  }}
/>
```

***

## Notes

- Use `DynamicImageSource` to adapt images for light/dark mode with minimal logic.
- Combine view modifiers like `scaleToFit`, `scaleToFill`, and `aspectRatio` to achieve precise layout configurations.
- Use the `foregroundStyle` property for detailed styling of icons or symbols.
- Ensure URLs and file paths provided for dynamic image sources are valid and accessible.



---
url: /guide/Views/Image/index_example.md
---

# Example

```tsx
import { Button, Image, List, Markdown, Navigation, NavigationStack, ProgressView, QRImage, Script, Section, Text, VStack } from "scripting"

function View() {
  const dismiss = Navigation.useDismiss()
  const url = "https://github.com"

  return <NavigationStack>
    <List
      navigationTitle={"Image"}
      toolbar={{
        topBarLeading: <Button
          title={"Close"}
          action={dismiss}
        />
      }}
    >

      <Section title={"Network Image"}>
        <Image
          imageUrl={'https://developer.apple.com/assets/elements/icons/swiftui/swiftui-96x96_2x.png'}
          resizable
          scaleToFit
          placeholder={<ProgressView
            progressViewStyle={'circular'}
          />}
        />
      </Section>

      <Section title={"SF Symbol"}>
        <Image
          systemName={"phone"}
          resizable
          scaleToFit
          frame={{
            width: 32,
            height: 32,
          }}
          foregroundStyle={"systemGreen"}
        />
      </Section>

      <Section title={"Local Image"}>
        <Markdown
          content={`\`\`\`tsx
<Image
  filePath={Path.join(Script.directory, "test.jpg")}
/>
\`\`\``}
        />
      </Section>

      <Section title={"QR Code Image"}>
        <VStack>
          <Text>URL: {url}</Text>
          <QRImage
            data={url}
          />
        </VStack>
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present(<View />)
  Script.exit()
}

run()
```



---
url: /guide/Views/Layout/FlowLayout/index.md
---

# FlowLayout

`FlowLayout` is a flow-based layout component that arranges its children horizontally and automatically wraps items to the next line when there is insufficient space. It is ideal for displaying a group of elements with dynamic widths such as tags, buttons, or icon lists.

***

## Import

```ts
import { FlowLayout } from "scripting"
```

***

## Props

### `spacing?: number`

The base spacing between items, applied to **both** the horizontal and vertical axes.

- **Type:** `number`
- **Default:** `8`

Defines the amount of space inserted between child items. Override a single axis with `horizontalSpacing` / `verticalSpacing`.

### `horizontalSpacing?: number`

The horizontal spacing between items within the same row. Overrides `spacing` on the horizontal axis when set.

- **Type:** `number`
- **Default:** falls back to `spacing`

### `verticalSpacing?: number`

The vertical spacing between wrapped rows. Overrides `spacing` on the vertical axis when set.

- **Type:** `number`
- **Default:** falls back to `spacing`

### `children?: VirtualNode | (VirtualNode | undefined | null | (VirtualNode | undefined | null)[])[]`

The child elements to be displayed inside the layout.

- Supports a single node or multiple nodes
- `undefined` and `null` children will be ignored
- Nested arrays are supported (useful when rendering with `.map()`)

***

## Examples

### Basic Usage

```ts
import { FlowLayout, Text } from "scripting"

export default function Example() {
  return (
    <FlowLayout spacing={12}>
      <Text>Tag One</Text>
      <Text>Tag Two</Text>
      <Text>Tag Three</Text>
      <Text>Tag Four</Text>
    </FlowLayout>
  )
}
```

### Rendering from an Array

```ts
const tags = ["Apple", "Orange", "Banana", "Pear", "Grape"]

export default function TagsExample() {
  return (
    <FlowLayout spacing={6}>
      {tags.map(tag => <Text>{tag}</Text>)}
    </FlowLayout>
  )
}
```

### Using Default Spacing

```ts
<FlowLayout>
  <Text>A</Text>
  <Text>B</Text>
  <Text>C</Text>
</FlowLayout>
```

***

## Recommended Use Cases

FlowLayout is suitable for layouts where elements vary in width and should wrap naturally, such as:

- Tag clouds and keyword lists
- Dynamic button groups
- Icon or avatar lists
- Adaptive content containers



---
url: /guide/Views/Layout/FlowLayout/index_example.md
---

# Example

```tsx
import { FlowLayout, List, Navigation, NavigationStack, Script, Section, Slider, Text, useState, VStack, } from "scripting"

const tags = [
  "Apple", "Orange", "Banana", "Pear", "Grape", "Mango",
  "Peach", "Cherry", "Lemon", "Kiwi", "Melon", "Plum",
]

function Example() {
  const [spacing, setSpacing] = useState(8)
  const [horizontalSpacing, setHorizontalSpacing] = useState(8)
  const [verticalSpacing, setVerticalSpacing] = useState(8)

  return <NavigationStack>
    <List
      navigationTitle={"FlowLayout"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        header={<Text>Spacing</Text>}
        footer={
          <Text>
            spacing is the base for both axes. horizontalSpacing / verticalSpacing
            override it per axis.
          </Text>
        }
      >
        <VStack alignment={"leading"}>
          <Text>{`spacing: ${Math.round(spacing)}`}</Text>
          <Slider value={spacing} min={0} max={40} onChanged={setSpacing} />
        </VStack>
        <VStack alignment={"leading"}>
          <Text>{`horizontalSpacing: ${Math.round(horizontalSpacing)}`}</Text>
          <Slider value={horizontalSpacing} min={0} max={40} onChanged={setHorizontalSpacing} />
        </VStack>
        <VStack alignment={"leading"}>
          <Text>{`verticalSpacing: ${Math.round(verticalSpacing)}`}</Text>
          <Slider value={verticalSpacing} min={0} max={40} onChanged={setVerticalSpacing} />
        </VStack>
      </Section>

      <Section header={<Text>Preview</Text>}>
        <FlowLayout
          spacing={spacing}
          horizontalSpacing={horizontalSpacing}
          verticalSpacing={verticalSpacing}
        >
          {tags.map(tag =>
            <Text
              key={tag}
              padding={{ horizontal: 12, vertical: 6 }}
              background={"systemBlue"}
              foregroundStyle={"white"}
            >{tag}</Text>
          )}
        </FlowLayout>
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Layout/Grid/index.md
---

# Grid

The `Grid` component in the **Scripting app** provides a flexible container for arranging child views in a two-dimensional grid layout. It supports customizable alignment, spacing, and nested child components to create visually appealing layouts.

***

### `Grid` Component

A container view that arranges other views in a two-dimensional layout.

### Import Path

```ts
import { Grid, GridRow } from 'scripting'
```

***

### Type: `GridProps`

| Property            | Type                                                                                          | Default          | Description                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `alignment`         | `Alignment`                                                                                   | `center`         | The alignment for child views within each grid cell. Options include `leading`, `center`, or `trailing`.    |
| `horizontalSpacing` | `number`                                                                                      | Platform-defined | The horizontal distance, in points, between each cell. Defaults to a platform-appropriate value if not set. |
| `verticalSpacing`   | `number`                                                                                      | Platform-defined | The vertical distance, in points, between each cell. Defaults to a platform-appropriate value if not set.   |
| `children`          | `(VirtualNode \| undefined \| null \| (VirtualNode \| undefined \| null)[])[] \| VirtualNode` | N/A              | The child components or nodes to be arranged in the grid.                                                   |

***

### `GridRow` Component

A child component of `Grid` that represents a horizontal row in the grid layout. Use `GridRow` to group and align child views horizontally within the grid.

***

### Type: `GridRowProps`

| Property    | Type                                                                                          | Default  | Description                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `alignment` | `VerticalAlignment`                                                                           | `center` | Aligns the content vertically within the row. Options include `top`, `center`, or `bottom`. |
| `children`  | `(VirtualNode \| undefined \| null \| (VirtualNode \| undefined \| null)[])[] \| VirtualNode` | N/A      | The child components or nodes to be arranged horizontally in the row.                       |

***

## Usage Example

Below is an example demonstrating how to use the `Grid` and `GridRow` components to create a layout with rows, text, images, and dividers.

```tsx
<Grid
  alignment="center"
  horizontalSpacing={10}
  verticalSpacing={15}
>
  <GridRow alignment="center">
    <Text>Hello</Text>
    <Image systemName="globe" />
  </GridRow>
  <Divider />
  <GridRow alignment="bottom">
    <Image systemName="hand.wave" />
    <Text>World</Text>
  </GridRow>
</Grid>
```

**Output Layout**

- **First Row:** Contains a `Text` element ("Hello") and an `Image` with the `globe` icon, aligned vertically to the center.
- **Divider:** Separates the two rows.
- **Second Row:** Contains an `Image` with the `wave` icon and a `Text` element ("World"), aligned vertically to the bottom.

***

### Properties in Detail

1. **Grid: Alignment**
   - Aligns the content of each cell in the grid.
   - Possible values:
     - `leading`: Aligns content to the start of the cell.
     - `center`: Centers content within the cell (default).
     - `trailing`: Aligns content to the end of the cell.
   - Example:
     ```tsx
     <Grid alignment="leading">
       <GridRow>
         <Text>Aligned to start</Text>
       </GridRow>
     </Grid>
     ```

2. **GridRow: Alignment**
   - Aligns the content vertically within each row.
   - Possible values:
     - `top`: Aligns content to the top of the row.
     - `center`: Centers content vertically within the row (default).
     - `bottom`: Aligns content to the bottom of the row.
   - Example:
     ```tsx
     <Grid>
       <GridRow alignment="top">
         <Text>Top-aligned</Text>
       </GridRow>
       <GridRow alignment="bottom">
         <Text>Bottom-aligned</Text>
       </GridRow>
     </Grid>
     ```

3. **Horizontal and Vertical Spacing**
   - Customize the spacing between cells and rows.
   - Example:
     ```tsx
     <Grid horizontalSpacing={5} verticalSpacing={20}>
       <GridRow>
         <Text>Item 1</Text>
         <Text>Item 2</Text>
       </GridRow>
     </Grid>
     ```

4. **Children**
   - Accepts any combination of `VirtualNode` components, including `Text`, `Image`, `GridRow`, and custom components.
   - Nested arrays or null values are allowed for flexibility in dynamic layouts.

***

## Nested Components

The `Grid` and `GridRow` components work seamlessly with other supported UI elements:

- **`Divider`**: Adds a visual separator between rows.
- **`Text`, `Image`, and Custom Components**: Use any supported UI components as children of `GridRow`.

***

## Rendering Example with Image

The following showcases an image of the output:

![Grid Example](https://docs-assets.developer.apple.com/published/f20954fd2b30390306220984d444d0cf/Grid-2-iOS@2x.png)

This layout corresponds to the example provided, showing two rows with a divider.

***

## Notes

- **Default Spacing:** Horizontal and vertical spacing values are optimized for iOS but can be customized for specific design needs.
- **Alignment Options:** Combine `Grid`'s cell alignment with `GridRow`'s vertical alignment for precise layout control.
- **Dynamic Layouts:** The flexibility of `Grid` and `GridRow` makes them suitable for responsive designs with varying content.

Feel free to experiment with different child components and spacing configurations to create tailored designs for your UIs!



---
url: /guide/Views/Layout/Grid/index_example.md
---

# Example

```tsx
import { Divider, ForEach, Grid, GridRow, Image, List, Navigation, NavigationStack, Rectangle, Script, Section, Text, Toggle, useState, VStack } from "scripting"

function Example() {
  const [gridCellUnsizedAxes, setGridCellUnsizedAxes] = useState(false)

  return <NavigationStack>
    <List
      navigationTitle={"Grid"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        header={
          <Text>Grid</Text>
        }
      >
        <Grid>
          <GridRow>
            <Text>Hello</Text>
            <Image systemName={"globe"} />
          </GridRow>
          <GridRow>
            <Image systemName={"hand.wave"} />
            <Text>World</Text>
          </GridRow>
        </Grid>
      </Section>

      <Section
        header={<Text>Grid Divider</Text>}
      >
        <VStack>
          <Toggle
            title={"gridCellUnsizedAxes"}
            value={gridCellUnsizedAxes}
            onChanged={setGridCellUnsizedAxes}
          />
          <Grid>
            <GridRow>
              <Text>Hello</Text>
              <Image systemName={"globe"} />
            </GridRow>
            <Divider
              gridCellUnsizedAxes={gridCellUnsizedAxes
                ? 'horizontal'
                : undefined}
            />
            <GridRow>
              <Image systemName={"hand.wave"} />
              <Text>World</Text>
            </GridRow>
          </Grid>
        </VStack>
      </Section>

      <Section
        header={
          <Text>Column count, cell spacing, alignment</Text>
        }
      >
        <Grid
          alignment={"bottom"}
          verticalSpacing={1}
          horizontalSpacing={1}
        >
          <GridRow>
            <Text>Row 1</Text>
            <ForEach
              count={2}
              itemBuilder={index =>
                <Rectangle
                  fill={"red"}
                  key={index.toString()}
                />
              }
            />
          </GridRow>
          <GridRow>
            <Text>Row 2</Text>
            <ForEach
              count={5}
              itemBuilder={index =>
                <Rectangle
                  fill={"green"}
                  key={index.toString()}
                />
              }
            />
          </GridRow>
          <GridRow>
            <Text>Row 3</Text>
            <ForEach
              count={5}
              itemBuilder={index =>
                <Rectangle
                  fill={"blue"}
                  key={index.toString()}
                />
              }
            />
          </GridRow>
        </Grid>
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()
```



---
url: /guide/Views/Layout/HStack/index.md
---

# HStack

The `HStack` component in the Scripting app provides a convenient way to arrange views horizontally with flexible alignment and spacing options. This component is essential for creating layouts that require side-by-side positioning of subviews.

***

## `HStackProps`

### Properties

1. **`alignment`** (optional)
   - **Type**: `VerticalAlignment`
   - **Description**: Specifies the vertical alignment of the subviews within the stack. Each subview is aligned according to the same vertical screen coordinate.
   - **Default Value**: `"center"`
   - **Options**:
     - `"top"`: Align subviews to the top edge.
     - `"center"`: Align subviews to the vertical center.
     - `"bottom"`: Align subviews to the bottom edge.
     - `"firstTextBaseline"`: Align subviews to the first text baseline.
     - `"lastTextBaseline"`: Align subviews to the last text baseline.
   - **Example**:
     ```tsx
     <HStack alignment="top">
       <Text>Item 1</Text>
       <Text>Item 2</Text>
     </HStack>
     ```

2. **`spacing`** (optional)
   - **Type**: `number`
   - **Description**: Specifies the distance between adjacent subviews. If not provided, the stack automatically determines the default spacing.
   - **Default Value**: `undefined` (uses default spacing)
   - **Example**:
     ```tsx
     <HStack spacing={15}>
       <Text>Item 1</Text>
       <Text>Item 2</Text>
     </HStack>
     ```

3. **`children`** (optional)
   - **Type**:
     ```ts
     (VirtualNode | undefined | null | (VirtualNode | undefined | null)[])[] | VirtualNode | undefined
     ```
   - **Description**: Specifies the subviews to be arranged in the stack. It can accept a single child, multiple children, or nested arrays of children.
   - **Example**:
     ```tsx
     <HStack>
       <Text>Item 1</Text>
       <Text>Item 2</Text>
       <Text>Item 3</Text>
     </HStack>
     ```

***

## `VerticalAlignment`

`VerticalAlignment` is an enumerated type that specifies how subviews are aligned vertically in an `HStack`.

### Options:

- **`"top"`**: Aligns the top edge of subviews.
- **`"center"`**: Aligns subviews along the vertical center axis.
- **`"bottom"`**: Aligns the bottom edge of subviews.
- **`"firstTextBaseline"`**: Aligns subviews to the first baseline of the text content.
- **`"lastTextBaseline"`**: Aligns subviews to the last baseline of the text content.

***

## **`HStack` Component**

### Description

The `HStack` component is a layout container that arranges its subviews in a horizontal line. It provides options for aligning views vertically and specifying the spacing between them.

### Syntax

```tsx
<HStack alignment="center" spacing={10}>
  {children}
</HStack>
```

### Example 1: Basic Horizontal Stack

```tsx
function Example1() {
  return (
    <HStack>
      <Text>Item 1</Text>
      <Text>Item 2</Text>
      <Text>Item 3</Text>
    </HStack>
  )
}
```

### Example 2: Custom Spacing and Alignment

```tsx
function Example2() {
  return (
    <HStack alignment="bottom" spacing={20}>
      <Text>Aligned Bottom</Text>
      <Text>With Spacing</Text>
    </HStack>
  )
}
```

### Example 3: Complex Children

```tsx
function Example3() {
  return (
    <HStack spacing={10}>
      {[1, 2, 3].map((item) => (
        <Text key={item.toString()}>Item {item}</Text>
      ))}
    </HStack>
  )
}
```

### Notes:

- Ensure that all child components passed to `HStack` are valid `VirtualNode` elements.
- For advanced layouts, combine `HStack` with other components like `VStack` or `Spacer`.

### See Also:

- `VStack` for vertical stacking of views.
- `Spacer` to create flexible spacing in stacks.
- `Text` for rendering text content.

***

### Diagram

The following diagram shows how vertical alignments work within an `HStack`:

![Vertical Alignment](https://docs-assets.developer.apple.com/published/a63aa800a94319cd283176a8b21bb7af/VerticalAlignment-1-iOS@2x.png)



---
url: /guide/Views/Layout/HStack/index_example.md
---

# Example

```tsx
import { HStack, Navigation, NavigationStack, Script, Text } from "scripting"

function Example() {
  const list = [0, 1, 2, 3, 4]

  return <NavigationStack>
    <HStack
      navigationTitle={"HStack"}
      alignment={"top"}
      spacing={10}
    >
      {list.map((_, index) =>
        <Text>Item{index + 1}</Text>
      )}
    </HStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()
```



---
url: /guide/Views/Layout/LazyHGrid/index.md
---

# LazyHGrid

The `LazyHGrid` component is part of the **Scripting** app's UI library. It arranges its children in a grid layout with rows defined by customizable sizing and alignment options. Items are created and displayed only as needed, optimizing performance for large or dynamic data sets.

***

## LazyHGrid

## Type: `FunctionComponent<LazyHGridProps>`

A `LazyHGrid` arranges its children in a grid that grows horizontally. Unlike a regular grid, it loads and displays items lazily, creating them only when they are about to appear on the screen. This makes it ideal for grids with large or dynamic content.

***

## LazyHGridProps

| Property      | Type                                                                                          | Default                       | Description                                                                                                                                          |
| ------------- | --------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows`        | `GridItem[]`                                                                                  | **Required**                  | Defines the configuration for the rows in the grid, including their size and alignment.                                                              |
| `alignment`   | `VerticalAlignment`                                                                           | `undefined`                   | Controls how the grid is aligned vertically within its parent view.                                                                                  |
| `spacing`     | `number`                                                                                      | `undefined` (default spacing) | The spacing between the grid and the next item in its parent view.                                                                                   |
| `pinnedViews` | `'sectionHeaders'` \| `'sectionFooters'` \| `'sectionHeadersAndFooters'`                      | `undefined`                   | Specifies which child views remain pinned to the bounds of the parent scroll view.                                                                   |
| `children`    | `(VirtualNode \| undefined \| null \| (VirtualNode \| undefined \| null)[])[] \| VirtualNode` | `undefined`                   | The content to be displayed in the grid. Accepts one or multiple `VirtualNode` elements, including arrays and optional `null` or `undefined` values. |

***

## GridItem

Defines the properties for a single row in the grid.

| Property    | Type        | Default                       | Description                                                                                        |
| ----------- | ----------- | ----------------------------- | -------------------------------------------------------------------------------------------------- |
| `alignment` | `Alignment` | `undefined`                   | Specifies the alignment to use when placing each child view in this row.                           |
| `spacing`   | `number`    | `undefined` (default spacing) | The spacing between items in this row and the next.                                                |
| `size`      | `GridSize`  | **Required**                  | Defines the size of the row. Can be a fixed size or a flexible/adaptive size based on the content. |

***

## GridSize

Defines the size of a row or column in the grid layout.

| Type       | Properties                                   | Description                                                                                            |
| ---------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `number`   | _N/A_                                        | A fixed size for the row or column.                                                                    |
| `adaptive` | `min: number`, `max?: number \|'infinity'`   | Specifies a flexible size that adapts to the content, with a minimum and optional maximum constraint.  |
| `flexible` | `min?: number`, `max?: number \| 'infinity'` | Specifies a single flexible size that adjusts dynamically, constrained by optional min and max values. |

***

## PinnedScrollViews

Defines which views in the grid remain pinned to the parent scroll view's bounds as it scrolls:

- `'sectionHeaders'`: Pins only the section headers
- `'sectionFooters'`: Pins only the section footers
- `'sectionHeadersAndFooters'`: Pins both section headers and footers

***

## Example Usage

```tsx
import { LazyHGrid, Text } from 'scripting'

const Example = () => {
  const rows = [
    { size: 50 },
    { size: { type: 'adaptive', min: 30, max: 80 } },
    { size: { type: 'flexible', min: 20, max: 'infinity' } }
  ]
  
  return (
    <ScrollView
      axes="horizontal"
    >
      <LazyHGrid 
        rows={rows} 
        alignment="center" 
        spacing={12} 
      >
        <Text>Item 1</Text>
        <Text>Item 2</Text>
        <Text>Item 3</Text>
      </LazyHGrid>
    </ScrollView>
  )
}
```

### Explanation:

- Defines three rows with different sizing:
  - A fixed row with a size of 50
  - An adaptive row with a minimum size of 30 and a maximum size of 80
  - A flexible row with a minimum size of 20 and no maximum size
- The grid is centered vertically in its parent view with 12 points of spacing

***

## Notes

- `LazyHGrid` is ideal for horizontally growing grid layouts with large or dynamic content
- Use `GridSize` to define flexible or adaptive layouts based on the available space
- The `pinnedViews` property ensures critical views like headers or footers remain visible during scrolling

This API provides flexibility and performance optimizations for grid-based horizontal layouts.



---
url: /guide/Views/Layout/LazyHGrid/index_example.md
---

# Example

```tsx
import { Color, LazyHGrid, Navigation, NavigationStack, RoundedRectangle, Script, ScrollView, Text, useMemo, VStack } from "scripting"

function Example() {
  const colors = useMemo(() => {
    const colors: {
      name: string
      value: Color
    }[] = []

    const numToHex = (n: number) => {
      return n === 0 ? '00' : n.toString(16)
    }

    for (let r = 0x00; r <= 0xff; r += 0x11) {
      for (let g = 0x00; g <= 0xff; g += 0x11) {
        for (let b = 0x00; b <= 0xff; b += 0x11) {
          const name = `${numToHex(r)}${numToHex(g)}${numToHex(b)}`
          const value: Color = `#${name}`
          colors.push({
            name,
            value
          })
        }
      }
    }

    return colors
  }, [])

  return <NavigationStack>
    <ScrollView
      navigationTitle={"LazyHGrid"}
      navigationBarTitleDisplayMode={"inline"}
      axes={"horizontal"}
    >
      <LazyHGrid
        spacing={2}
        rows={[
          { size: 100 },
          { size: 100 },
          { size: 100 },
          { size: 100 },
        ]}
      >
        {colors.map((color) =>
          <VStack>
            <Text>
              {color.name}
            </Text>
            <RoundedRectangle
              fill={color.value}
              cornerRadius={4}
              frame={{
                width: 50,
                height: 50
              }}
            />
          </VStack>
        )}
      </LazyHGrid>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()
```



---
url: /guide/Views/Layout/LazyHStack/index.md
---

# LazyHStack

The `LazyHStack` component is part of the **Scripting** app's UI library. It arranges its children in a horizontal stack, creating and displaying items only as needed, which improves performance for large data sets.

## LazyHStack

## Type: `FunctionComponent<LazyHStackProps>`

A `LazyHStack` arranges its children in a line that grows horizontally. Unlike a regular horizontal stack, it loads and displays views lazily, creating them only when they are about to appear on the screen. This makes it ideal for scenarios involving large or dynamic data.

***

## LazyHStackProps

| Property      | Type                                                                                          | Default                       | Description                                                                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alignment`   | `VerticalAlignment`                                                                           | `undefined`                   | Determines how the children are aligned vertically within the stack. All child views share the same vertical screen coordinate.                       |
| `spacing`     | `number`                                                                                      | `undefined` (default spacing) | The space between adjacent subviews. If `undefined`, the stack uses a default spacing value.                                                          |
| `pinnedViews` | `'sectionHeaders'` \| `'sectionFooters'` \| `'sectionHeadersAndFooters'`                      | `undefined`                   | Specifies which child views remain pinned to the bounds of the scroll view during scrolling.                                                          |
| `children`    | `(VirtualNode \| undefined \| null \| (VirtualNode \| undefined \| null)[])[] \| VirtualNode` | `undefined`                   | The content to be displayed in the stack. Accepts one or multiple `VirtualNode` elements, including arrays and optional `null` or `undefined` values. |

***

## PinnedScrollViews

The `PinnedScrollViews` type defines which kinds of child views can remain pinned to the scroll view's bounds as it scrolls:

- `'sectionHeaders'`: Pins only the section headers.
- `'sectionFooters'`: Pins only the section footers.
- `'sectionHeadersAndFooters'`: Pins both section headers and footers.

***

## Example Usage

```tsx
import { LazyHStack, Text, ScrollView, Section } from 'scripting'

const Example = () => {
  return (
    <ScrollView
      axes="horizontal"
    >
      <LazyHStack
        alignment="center"
        spacing={10}
        pinnedViews="sectionHeaders"
      >
        {list.map(item =>
          <Section
            key={item.id}
            header={
              <Text>{item.title}</Text>
            }
          >
            <ItemView
              item={item}
            />
          </Section>
        )}
      </LazyHStack>
    </ScrollView>
  )
}
```

### Explanation:

- The stack arranges the `Section` views horizontally with `10` points of spacing.
- The `alignment` property centers the items vertically within the stack.
- The `pinnedViews` property ensures that section headers remain pinned to the top of the scroll view when scrolling.

***

## Notes

- Lazy loading improves performance by creating views only as they become visible.
- Use `spacing` to adjust the distance between items and `alignment` to control vertical positioning.
- The `pinnedViews` property is particularly useful for table-like layouts where headers or footers should remain visible during scrolling.

This API allows you to efficiently handle horizontally growing content while providing customization for layout and scrolling behavior.



---
url: /guide/Views/Layout/LazyHStack/index_example.md
---

# Example

```tsx
import { ForEach, LazyHStack, Navigation, NavigationStack, Script, ScrollView, Text, VStack } from "scripting"

function Example() {

  return <NavigationStack>
    <VStack
      navigationTitle={"LazyHStack"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <ScrollView
        axes={"horizontal"}
      >
        <LazyHStack
          alignment={"top"}
          spacing={10}
        >
          <ForEach
            count={100}
            itemBuilder={index =>
              <Text
                padding
                background={"systemIndigo"}
                key={index.toString()}
              >Column {index}</Text>
            }
          />
        </LazyHStack>
      </ScrollView>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()
```



---
url: /guide/Views/Layout/LazyVGrid/index.md
---

# LazyVGrid

The `LazyVGrid` component is part of the **Scripting** app's UI library. It arranges its children in a grid layout with columns defined by customizable sizing and alignment options. Items are created and displayed only as needed, optimizing performance for large or dynamic data sets.

***

## LazyVGrid

## Type: `FunctionComponent<LazyVGridProps>`

A `LazyVGrid` arranges its children in a grid that grows vertically. Unlike a regular grid, it loads and displays items lazily, creating them only when they are about to appear on the screen. This makes it ideal for grids with large or dynamic content.

***

## LazyVGridProps

| Property      | Type                                                                                          | Default                       | Description                                                                                                                                          |
| ------------- | --------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columns`     | `GridItem[]`                                                                                  | **Required**                  | Defines the configuration for the columns in the grid, including their size and alignment.                                                           |
| `alignment`   | `HorizontalAlignment`                                                                         | `undefined`                   | Controls how the grid is aligned horizontally within its parent view.                                                                                |
| `spacing`     | `number`                                                                                      | `undefined` (default spacing) | The distance between adjacent grid items. If `undefined`, the grid uses a default spacing value.                                                     |
| `pinnedViews` | `'sectionHeaders'` \| `'sectionFooters'` \| `'sectionHeadersAndFooters'`                      | `undefined`                   | Specifies which child views remain pinned to the bounds of the parent scroll view.                                                                   |
| `children`    | `(VirtualNode \| undefined \| null \| (VirtualNode \| undefined \| null)[])[] \| VirtualNode` | `undefined`                   | The content to be displayed in the grid. Accepts one or multiple `VirtualNode` elements, including arrays and optional `null` or `undefined` values. |

***

## GridItem

Defines the properties for a single column in the grid.

| Property    | Type        | Default                       | Description                                                                                           |
| ----------- | ----------- | ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| `alignment` | `Alignment` | `undefined`                   | Specifies the alignment to use when placing each child view in this column.                           |
| `spacing`   | `number`    | `undefined` (default spacing) | The spacing between items in this column and the next.                                                |
| `size`      | `GridSize`  | **Required**                  | Defines the size of the column. Can be a fixed size or a flexible/adaptive size based on the content. |

***

## GridSize

Defines the size of a row or column in the grid layout.

| Type       | Properties                                   | Description                                                                                            |
| ---------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `number`   | _N/A_                                        | A fixed size for the row or column.                                                                    |
| `adaptive` | `min: number`, `max?: number \| 'infinity'`  | Specifies a flexible size that adapts to the content, with a minimum and optional maximum constraint.  |
| `flexible` | `min?: number`, `max?: number \| 'infinity'` | Specifies a single flexible size that adjusts dynamically, constrained by optional min and max values. |

***

## PinnedScrollViews

Defines which views in the grid remain pinned to the parent scroll view's bounds as it scrolls:

- `'sectionHeaders'`: Pins only the section headers
- `'sectionFooters'`: Pins only the section footers
- `'sectionHeadersAndFooters'`: Pins both section headers and footers

***

## Example Usage

```tsx
import { LazyVGrid, Text } from 'scripting'

const Example = () => {
  const columns = [
    { size: 50 },
    { size: { type: 'adaptive', min: 40, max: 100 } },
    { size: { type: 'flexible', min: 30, max: 'infinity' } }
  ]

  return (
    <ScrollView>
      <LazyVGrid
        columns={columns}
        alignment="leading"
        spacing={16}
      >
        <Text>Item 1</Text>
        <Text>Item 2</Text>
        <Text>Item 3</Text>
      </LazyVGrid>
    </ScrollView>
  )
}
```

### Explanation:

- Defines three columns with different sizing:
  - A fixed column with a size of 50
  - An adaptive column with a minimum size of 40 and a maximum size of 100
  - A flexible column with a minimum size of 30 and no maximum size
- The grid is aligned to the leading edge of its parent view with 16 points of spacing

***

## Notes

- `LazyVGrid` is ideal for vertically growing grid layouts with large or dynamic content
- Use `GridSize` to define flexible or adaptive layouts based on the available space
- The `pinnedViews` property ensures critical views like headers or footers remain visible during scrolling

This API provides flexibility and performance optimizations for grid-based vertical layouts.



---
url: /guide/Views/Layout/LazyVGrid/index_example.md
---

# Example

```tsx
import { Color, LazyVGrid, Navigation, NavigationStack, RoundedRectangle, Script, ScrollView, Text, useMemo, VStack } from "scripting"

function Example() {
  const colors = useMemo(() => {
    const colors: {
      name: string
      value: Color
    }[] = []

    const numToHex = (n: number) => {
      return n === 0 ? '00' : n.toString(16)
    }

    for (let r = 0x00; r <= 0xff; r += 0x11) {
      for (let g = 0x00; g <= 0xff; g += 0x11) {
        for (let b = 0x00; b <= 0xff; b += 0x11) {
          const name = `${numToHex(r)}${numToHex(g)}${numToHex(b)}`
          const value: Color = `#${name}`
          colors.push({
            name,
            value
          })
        }
      }
    }

    return colors
  }, [])

  return <NavigationStack>
    <ScrollView
      navigationTitle={"LazyVGrid"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <LazyVGrid
        spacing={2}
        columns={[
          { size: 100 },
          { size: 100 },
          { size: 100 },
          { size: 100 },
        ]}
      >
        {colors.map((color) =>
          <VStack>
            <Text>
              {color.name}
            </Text>
            <RoundedRectangle
              fill={color.value}
              cornerRadius={4}
              frame={{
                width: 50,
                height: 50
              }}
            />
          </VStack>
        )}
      </LazyVGrid>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()
```



---
url: /guide/Views/Layout/LazyVStack/index.md
---

# LazyVStack

The `LazyVStack` component is part of the **Scripting** app's UI library. It arranges its children in a vertical stack, creating and displaying items only as needed, optimizing performance for large data sets.

## LazyVStack

## Type: `FunctionComponent<LazyVStackProps>`

A `LazyVStack` arranges its children in a line that grows vertically. Unlike a regular vertical stack, it lazily loads and displays views only when they are about to appear on the screen. This makes it ideal for lists or large sets of dynamically generated content.

***

## LazyVStackProps

| Property      | Type                                                                                          | Default                       | Description                                                                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alignment`   | `HorizontalAlignment`                                                                         | `undefined`                   | Determines how the children are aligned horizontally within the stack. All child views share the same horizontal screen coordinate.                   |
| `spacing`     | `number`                                                                                      | `undefined` (default spacing) | The space between adjacent subviews. If `undefined`, the stack uses a default spacing value.                                                          |
| `pinnedViews` | `'sectionHeaders'` \| `'sectionFooters'` \| `'sectionHeadersAndFooters'`                      | `undefined`                   | Specifies which child views remain pinned to the bounds of the scroll view during scrolling.                                                          |
| `children`    | `(VirtualNode \| undefined \| null \| (VirtualNode \| undefined \| null)[])[] \| VirtualNode` | `undefined`                   | The content to be displayed in the stack. Accepts one or multiple `VirtualNode` elements, including arrays and optional `null` or `undefined` values. |

***

## PinnedScrollViews

The `PinnedScrollViews` type defines which kinds of child views can remain pinned to the scroll view's bounds as it scrolls:

- `'sectionHeaders'`: Pins only the section headers
- `'sectionFooters'`: Pins only the section footers
- `'sectionHeadersAndFooters'`: Pins both section headers and footers

***

## Example Usage

```tsx
import { LazyVStack, Text, ScrollView, Section } from 'scripting'

const Example = () => {
  return (
    <ScrollView>
      <LazyVStack alignment="leading" spacing={12} pinnedViews="sectionHeaders">
        {list.map(item => 
          <Section
            key={item.id}
            header={
              <Text>{item.title}</Text>
            }
          >
            <ItemView
              item={item}
            />
          </Section>
        )}
      </LazyVStack>
    </ScrollView>
  )
}
```

### Explanation:

- The stack arranges the `Section` views vertically with `12` points of spacing
- The `alignment` property aligns the items to the leading edge of the stack
- The `pinnedViews` property ensures that section headers remain pinned to the top of the scroll view when scrolling

***

## Notes

- Lazy loading ensures that views are only created as they become visible, which improves performance for large content
- Use `spacing` to control the vertical distance between items and `alignment` to customize the horizontal alignment
- The `pinnedViews` property is especially useful for table or list-like layouts with sticky headers or footers

This API allows you to efficiently manage vertically growing content while offering customization for layout and scrolling behavior.



---
url: /guide/Views/Layout/LazyVStack/index_example.md
---

# Example

```tsx
import { HStack, LazyVStack, Navigation, NavigationStack, Script, ScrollView, Section, Spacer, Text, useMemo } from "scripting"

function Example() {
  const groups = useMemo(() => {
    const groups: {
      name: string
      items: number[]
    }[] = []

    for (let i = 1; i < 10; i++) {
      const list: {
        name: string
        items: number[]
      } = {
        name: "Group " + i,
        items: []
      }

      for (let j = 0; j < 10; j++) {
        list.items.push(i * 10 + j)
      }

      groups.push(list)
    }

    return groups
  }, [])

  return <NavigationStack>
    <ScrollView
      navigationTitle={"LazyVStack"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <LazyVStack
        alignment={"leading"}
        spacing={10}
        pinnedViews={"sectionHeaders"}
      >
        {groups.map(group =>
          <Section
            header={
              <HStack
                background={"purple"}
              >
                <Text>{group.name}</Text>
                <Spacer />
              </HStack>
            }
          >
            {group.items.map(item =>
              <Text>Row {item}</Text>
            )}
          </Section>
        )}
      </LazyVStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()
```



---
url: /guide/Views/Layout/VStack/index.md
---

# VStack

The `VStack` component in the Scripting app is a layout view that arranges its child views vertically. It provides flexible options for aligning its subviews and controlling the spacing between them.

***

## **`VStack` Component**

### **Type Declaration**

```ts
declare const VStack: FunctionComponent<VStackProps>
```

### **Description**

The `VStack` component arranges its child views in a vertical line, making it ideal for creating vertically stacked layouts. You can customize the alignment of subviews and the spacing between them to suit your design needs.

***

## **Properties**

### `alignment` (Optional)

- **Type**: `HorizontalAlignment`
- **Default**: `"center"`
- **Description**: Determines the horizontal alignment of the subviews within the stack. The alignment specifies how views are positioned relative to each other horizontally when placed vertically in the `VStack`.
- **Accepted Values**:
  - `"leading"`: Aligns views to the left.
  - `"center"`: Centers views horizontally.
  - `"trailing"`: Aligns views to the right.

#### **Example**

```tsx
<VStack alignment="leading">
  <Text>Leading Aligned</Text>
  <Text>Another Item</Text>
</VStack>
```

***

### `spacing` (Optional)

- **Type**: `number | undefined`
- **Default**: Automatically calculated based on the child views if not specified.
- **Description**: Sets the distance in pixels between adjacent subviews. Use `undefined` to let the stack automatically determine the optimal spacing.

#### **Example**

```tsx
<VStack spacing={10}>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
</VStack>
```

***

### `children` (Optional)

- **Type**:
  ```ts
  (VirtualNode | undefined | null | (VirtualNode | undefined | null)[])[] | VirtualNode | undefined
  ```
- **Description**: The child elements to display within the stack. You can pass individual elements, arrays of elements, or `undefined`/`null` values. Nullish values are ignored, allowing for dynamic layouts.

#### **Example**

```tsx
<VStack>
  <Text>First Item</Text>
  <Image systemName="star" />
</VStack>
```

***

## **`HorizontalAlignment` Type**

Horizontal alignment guides control how views are positioned relative to each other when placed vertically in a `VStack`.

### **Type Declaration**

```ts
type HorizontalAlignment = 'leading' | 'center' | 'trailing'
```

### **Alignment Options**

- **`leading`**: Aligns all subviews to the left edge of the stack.
- **`center`**: Centers all subviews horizontally.
- **`trailing`**: Aligns all subviews to the right edge of the stack.

### **Visual Guide**

Below is an illustration of the three alignment options:

![Horizontal Alignment](https://docs-assets.developer.apple.com/published/cb8ad6030a1ebcfee545d02f406500ee/HorizontalAlignment-1-iOS@2x.png)

***

## **Usage Example**

```tsx
<VStack alignment="leading" spacing={10}>
  <Image systemName="globe" />
  <Text>Leading Aligned Item</Text>
  <Text>Another Item</Text>
</VStack>
```

### **Explanation**

1. **`alignment="leading"`**: Aligns all subviews to the left.
2. **`spacing={10}`**: Adds 10 pixels of space between each subview.
3. Contains two child views:
   - An `Image` view displaying a system icon.
   - Two `Text` views displaying labeled items.

***

## **Best Practices**

1. Use `alignment` to control horizontal positioning when stacking text and icons for better visual consistency.
2. Leverage `spacing` to create breathable and aesthetically pleasing layouts.
3. Pass dynamic or conditional children without worrying about `null` or `undefined` values.

This documentation ensures you can confidently use the `VStack` component to create clean, vertically stacked layouts in your Scripting app projects.



---
url: /guide/Views/Layout/VStack/index_example.md
---

# Example

```tsx
import { Navigation, NavigationStack, Script, Text, VStack } from "scripting"

function Example() {
  const list = [0, 1, 2, 3, 4]

  return <NavigationStack>
    <VStack
      navigationTitle={"VStack"}
      alignment={"leading"}
      spacing={10}
    >
      {list.map((_, index) =>
        <Text>Item{index + 1}</Text>
      )}
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()
```



---
url: /guide/Views/Layout/ZStack/index.md
---

# ZStack

The `ZStack` component in the Scripting app allows you to arrange subviews on top of each other in a layered stack. It provides flexibility in aligning the layers along both the x- and y-axes using predefined alignment guides.

***

## `ZStackProps`

The `ZStack` component accepts the following props:

| Property    | Type                                                                                          | Default Value | Description                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------- |
| `alignment` | `Alignment` (optional)                                                                        | `"center"`    | Determines how the subviews are aligned along the x- and y-axes.                              |
| `children`  | `(VirtualNode \| undefined \| null \| (VirtualNode \| undefined \| null)[])[] \| VirtualNode` | `undefined`   | The child components to be displayed in the stack. Can be a single node or an array of nodes. |

***

## `Alignment`

The `Alignment` type defines a set of common alignments for stacking views. These alignments combine horizontal and vertical guides. The diagram below illustrates these alignments:

![Alignment](https://docs-assets.developer.apple.com/published/09693fd98ab76356519a900fd33d9e7f/Alignment-1-iOS@2x.png)

### Supported Values:

| Value                         | Description                                                         |
| ----------------------------- | ------------------------------------------------------------------- |
| `"top"`                       | Aligns views at the top edge of the stack.                          |
| `"center"`                    | Centers views along both horizontal and vertical axes.              |
| `"bottom"`                    | Aligns views at the bottom edge of the stack.                       |
| `"leading"`                   | Aligns views at the leading edge (left in left-to-right layouts).   |
| `"trailing"`                  | Aligns views at the trailing edge (right in left-to-right layouts). |
| `"bottomLeading"`             | Aligns views at the bottom-left corner.                             |
| `"bottomTrailing"`            | Aligns views at the bottom-right corner.                            |
| `"centerFirstTextBaseline"`   | Aligns views at the center using the first text baseline.           |
| `"centerLastTextBaseline"`    | Aligns views at the center using the last text baseline.            |
| `"leadingFirstTextBaseline"`  | Aligns views at the leading edge using the first text baseline.     |
| `"leadingLastTextBaseline"`   | Aligns views at the leading edge using the last text baseline.      |
| `"topLeading"`                | Aligns views at the top-left corner.                                |
| `"topTrailing"`               | Aligns views at the top-right corner.                               |
| `"trailingFirstTextBaseline"` | Aligns views at the trailing edge using the first text baseline.    |
| `"trailingLastTextBaseline"`  | Aligns views at the trailing edge using the last text baseline.     |

***

## `ZStack` Component

The `ZStack` is a function component that arranges its children in a layered stack. Each child is placed relative to the alignment defined in the `alignment` property.

### Importing the Component

To use the `ZStack` component, ensure you import it from the Scripting app's `scripting` package:

```tsx
import { ZStack } from 'scripting'
```

***

## Example Usage

### 1. Basic Example

Align child views at the top:

```tsx
<ZStack alignment="top">
  <Image systemName="globe" />
  <Text>
    Hello world.
  </Text>
</ZStack>
```

### 2. Advanced Alignments

Use complex alignments such as `bottomLeading` to position child elements:

```tsx
<ZStack alignment="bottomLeading">
  <Rectangle fill="gray" />
  <Text>
    Bottom Leading Text
  </Text>
</ZStack>
```

### 3. Nested `ZStack` Example

Combine `ZStack` with other layout components for complex arrangements:

```tsx
<ZStack alignment="center">
  <Rectangle fill="blue" />
  <ZStack alignment="topTrailing">
    <Image systemName="star" />
    <Text>
      Nested ZStack
    </Text>
  </ZStack>
</ZStack>
```

***

## Notes

- **Performance Considerations**: Avoid adding too many child views to the `ZStack` to prevent potential performance bottlenecks in complex layouts.
- **Composable Layouts**: Use `ZStack` alongside other components like `VStack` and `HStack` for flexible and dynamic UIs.



---
url: /guide/Views/Layout/ZStack/index_example.md
---

# Example

```tsx
import { Button, Circle, Color, List, Navigation, NavigationLink, NavigationStack, Rectangle, Script, Section, Text, VStack, ZStack } from "scripting"

function Example() {
  const colors: Color[] = [
    "red",
    "orange",
    "yellow",
    "green",
    "blue",
    "purple",
  ]

  return <NavigationStack>
    <List
      navigationTitle={"ZStack"}
    >
      <Section
        header={
          <Text
            textCase={null}
          >ZStack</Text>
        }
      >
        <ZStack>
          {colors.map((color, index) =>
            <Rectangle
              fill={color}
              frame={{
                width: 100,
                height: 100,
              }}
              offset={{
                x: index * 10,
                y: index * 10
              }}
            />
          )}
        </ZStack>
      </Section>

      <Section
        header={
          <Text
            textCase={null}
          >background</Text>
        }
      >
        <Text
          background={{
            content: <Rectangle
              fill={"systemBlue"}
              frame={{
                width: 100,
                height: 50,
              }}
            />,
            alignment: "center",
          }}
        >Hello Scripting!</Text>
      </Section>

      <Section
        header={
          <Text
            textCase={null}
          >overlay</Text>
        }
      >
        <Circle
          fill={"yellow"}
          frame={{
            width: 100,
            height: 100,
          }}
          overlay={{
            content: <Rectangle
              fill={"blue"}
              frame={{
                width: 50,
                height: 50,
              }}
            />,
            alignment: "center"
          }}
        />
      </Section>

      <Section
        title={"containerBackground (iOS 18.0+)"}
      >
        <Button
          title={"Present"}
          action={() => {
            Navigation.present({
              element: <ContainerBackgroundExample />,
              modalPresentationStyle: "pageSheet"
            })
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

function ContainerBackgroundExample() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <List
      navigationTitle={"containerBackground"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />,
      }}
    >
      <NavigationLink
        title={"Red Page"}
        destination={
          <VStack
            navigationContainerBackground={"red"}
            frame={{
              maxWidth: 'infinity',
              maxHeight: 'infinity'
            }}
          >
            <Text>A red page</Text>
          </VStack>
        }
      />
      <NavigationLink
        title={"Blue Page"}
        destination={
          <VStack
            navigationContainerBackground={"blue"}
            frame={{
              maxWidth: 'infinity',
              maxHeight: 'infinity'
            }}
          >
            <Text>A blue page</Text>
          </VStack>
        }
      />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })
  Script.exit()
}

run()

```



---
url: /guide/Views/Link.md
---

# Link

The `Link` component provides a way to create tappable controls that navigate to a specified URL. This component can be used to open web pages, app-specific URLs, or other schemes.

> **Note**: If the `Link` component is used within a widget, the `widgetURL` modifier will be ignored.

### Props

| Name       | Type                      | Description                                                                  |
| ---------- | ------------------------- | ---------------------------------------------------------------------------- |
| `url`      | `string`                  | The destination URL to open when tapped.                                     |
| `children` | `string` \| `VirtualNode` | The content displayed inside the link. Can be plain text or a custom layout. |

### Example

```tsx
<Link url={Script.createOpenURLScheme('Script A')}>
  Open Script A
</Link>

<Link url="https://example.com">
  <HStack>
    <Image
      systemName="globe"
      width={20}
      height={20}
      padding={{ trailing: 8 }}
    />
    <Text>Open Link</Text>
  </HStack>
</Link>
```

This component supports both simple text and complex layouts as its children. When tapped, it opens the provided `url` using the appropriate handler (e.g., Safari, another app, or a custom scheme).



---
url: /guide/Views/List/DisclosureGroup/index.md
---

# DisclosureGroup

The `DisclosureGroup` component allows you to organize related content into collapsible sections. This is useful for grouping items in a list, especially when dealing with hierarchical or optional content.

This example demonstrates how to create a top-level disclosure group that can be toggled open or closed, and how to nest additional `DisclosureGroup` components for sub-sections.

***

## Overview

You will learn how to:

- Use `DisclosureGroup` to create expandable sections
- Bind the expanded state to local component state
- Nest disclosure groups to represent hierarchical content
- Combine with other controls such as `Toggle`, `Text`, and `Button`

***

## Example Code

### 1. Import Dependencies

```tsx
import { Button, DisclosureGroup, List, Navigation, NavigationStack, Script, Text, Toggle, useState } from "scripting"
```

### 2. Define Component State

Manage the expanded state and toggle values using `useState`:

```tsx
const [topExpanded, setTopExpanded] = useState(true)
const [oneIsOn, setOneIsOn] = useState(false)
const [twoIsOn, setTwoIsOn] = useState(true)
```

### 3. Layout UI with Disclosure Groups

The main layout includes a `List` within a `NavigationStack`. A `Button` is provided to toggle the top-level group manually. The `DisclosureGroup` itself contains multiple child views and a nested `DisclosureGroup`:

```tsx
return <NavigationStack>
  <List
    navigationTitle={"DislcosureGroup"}
    navigationBarTitleDisplayMode={"inline"}
  >
    <Button
      title={"Toggle expanded"}
      action={() => setTopExpanded(!topExpanded)}
    />
    <DisclosureGroup
      title={"Items"}
      isExpanded={topExpanded}
      onChanged={setTopExpanded}
    >
      <Toggle
        title={"Toggle 1"}
        value={oneIsOn}
        onChanged={setOneIsOn}
      />
      <Toggle
        title={"Toggle 2"}
        value={twoIsOn}
        onChanged={setTwoIsOn}
      />
      <DisclosureGroup
        title={"Sub-items"}
      >
        <Text>Sub-item 1</Text>
      </DisclosureGroup>
    </DisclosureGroup>
  </List>
</NavigationStack>
```

### 4. Present the View and Exit

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```

***

## Key Concepts

- **DisclosureGroup**: An expandable view that reveals or hides its content.
- **isExpanded**: Binds the expanded/collapsed state to a Boolean value.
- **onChanged**: Callback that triggers when the user expands or collapses the group.
- **Nested Groups**: You can include one `DisclosureGroup` inside another to create a hierarchy.
- **Integration**: Works seamlessly with controls such as `Toggle`, `Text`, `Button`, etc.

***

## Use Cases

- Grouping settings into categories
- Creating collapsible FAQs or toolboxes
- Displaying nested data like folders, sections, or filters

This pattern provides a clean and user-friendly way to organize complex or optional content within a scrollable list.



---
url: /guide/Views/List/DisclosureGroup/index_example.md
---

# Example

```tsx
import { Button, DisclosureGroup, List, Navigation, NavigationStack, Script, Text, Toggle, useState } from "scripting"

function Example() {
  const [topExpanded, setTopExpanded] = useState(true)
  const [oneIsOn, setOneIsOn] = useState(false)
  const [twoIsOn, setTwoIsOn] = useState(true)

  return <NavigationStack>
    <List
      navigationTitle={"DislcosureGroup"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Button
        title={"Toggle expanded"}
        action={() => setTopExpanded(!topExpanded)}
      />
      <DisclosureGroup
        title={"Items"}
        isExpanded={topExpanded}
        onChanged={setTopExpanded}
      >
        <Toggle
          title={"Toggle 1"}
          value={oneIsOn}
          onChanged={setOneIsOn}
        />
        <Toggle
          title={"Toggle 2"}
          value={twoIsOn}
          onChanged={setTwoIsOn}
        />

        <DisclosureGroup
          title={"Sub-items"}
        >
          <Text>Sub-item 1</Text>
        </DisclosureGroup>
      </DisclosureGroup>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/List/Display data inside a row/index.md
---

# Display data inside a row

This example demonstrates how to use the `List` component to present structured data using custom row layouts. Each row displays a person's name and phone number in a clean and readable format, using stack-based layout components inspired by SwiftUI.

## Overview

You will learn how to:

- Define a custom row component (`PersonRowView`)
- Use `List` to display a collection of items
- Apply text styling and system icons
- Structure layouts using `VStack` and `HStack`

***

## Example Code

### 1. Import Dependencies and Define Data

```tsx
import { HStack, Label, List, Navigation, NavigationStack, Script, Text, VStack } from "scripting"

type Person = {
  name: string
  phoneNumber: string
}
```

### 2. Create a Row Component

The `PersonRowView` component renders the content of a single list row. It uses a vertical stack to separate the name and phone number, with appropriate font styles and colors.

```tsx
function PersonRowView({
  person
}: {
  person: Person
}) {
  return <VStack
    alignment={"leading"}
    spacing={3}
  >
    <Text
      foregroundStyle={"label"}
      font={"headline"}
    >{person.name}</Text>
    <HStack
      spacing={3}
      foregroundStyle={"secondaryLabel"}
      font={"subheadline"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}
```

### 3. Display the List in a Navigation Stack

Use `NavigationStack` and `List` to display all rows. The navigation title is set to describe the purpose of the view.

```tsx
function Example() {
  const staff: Person[] = [
    {
      name: "Juan Chavez",
      phoneNumber: "(408) 555-4301",
    },
    {
      name: "Mei Chen",
      phoneNumber: "(919) 555-2481"
    }
  ]

  return <NavigationStack>
    <List
      navigationTitle={"Display data inside a row"}
      navigationBarTitleDisplayMode={"inline"}
    >
      {staff.map(person =>
        <PersonRowView
          person={person}
        />
      )}
    </List>
  </NavigationStack>
}
```

### 4. Present the View

Use `Navigation.present` to show the view, then exit the script after dismissal:

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```

***

## Summary

This pattern shows how to **display data inside a row** by:

- Structuring UI with layout components (`VStack`, `HStack`)
- Defining reusable, typed row components
- Presenting data collections cleanly using `List`
- Integrating icons and labels for better visual clarity

It is ideal for rendering lists of structured objects such as contacts, messages, or any custom data rows.



---
url: /guide/Views/List/Display data inside a row/index_example.md
---

# Example

```tsx
import { HStack, Label, List, Navigation, NavigationStack, Script, Text, VStack } from "scripting"

type Person = {
  name: string
  phoneNumber: string
}

function PersonRowView({
  person
}: {
  person: Person
}) {
  return <VStack
    alignment={"leading"}
    spacing={3}
  >
    <Text
      foregroundStyle={"label"}
      font={"headline"}
    >{person.name}</Text>
    <HStack
      spacing={3}
      foregroundStyle={"secondaryLabel"}
      font={"subheadline"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

function Example() {
  const staff: Person[] = [
    {
      name: "Juan Chavez",
      phoneNumber: "(408) 555-4301",
    },
    {
      name: "Mei Chen",
      phoneNumber: "(919) 555-2481"
    }
  ]

  return <NavigationStack>
    <List
      navigationTitle={"Display data inside a row"}
      navigationBarTitleDisplayMode={"inline"}
    >
      {staff.map(person =>
        <PersonRowView
          person={person}
        />
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/List/Editable List/index.md
---

# Editable List

This example demonstrates how to build an **editable list** in the Scripting app using `List`, `ForEach`, and `EditButton` components. The list supports item deletion and reordering with built-in editing controls.

***

## Overview

You will learn how to:

- Display a list of items using `ForEach`
- Enable deletion and reordering of items
- Use `EditButton` to toggle editing mode
- Handle state updates using `useState`

***

## Example Code

### 1. Import Required Modules

```tsx
import { Color, EditButton, ForEach, List, Navigation, NavigationStack, Script, Text, useState } from "scripting"
```

### 2. Define Component State

The list is initialized with an array of `Color` strings:

```tsx
const [colors, setColors] = useState<Color[]>([
  "red",
  "orange",
  "yellow",
  "green",
  "blue",
  "purple",
])
```

### 3. Handle Item Deletion

The `onDelete` function removes items from the list based on selected indices:

```tsx
function onDelete(indices: number[]) {
  setColors(colors.filter((_, index) => !indices.includes(index)))
}
```

### 4. Handle Item Reordering

The `onMove` function repositions selected items to a new offset in the list:

```tsx
function onMove(indices: number[], newOffset: number) {
  const movingItems = indices.map(index => colors[index])
  const newColors = colors.filter((_, index) => !indices.includes(index))
  newColors.splice(newOffset, 0, ...movingItems)
  setColors(newColors)
}
```

### 5. Build the Editable List

The main UI is constructed using a `NavigationStack` and a `List` containing a `ForEach` loop. The `EditButton` is added to the toolbar to enable editing mode:

```tsx
return <NavigationStack>
  <List
    navigationTitle={"Editable List"}
    navigationBarTitleDisplayMode={"inline"}
    toolbar={{
      confirmationAction: [
        <EditButton />,
      ]
    }}
  >
    <ForEach
      count={colors.length}
      itemBuilder={index =>
        <Text
          key={colors[index]} // A unique key is required!
        >{colors[index]}</Text>
      }
      onDelete={onDelete}
      onMove={onMove}
    />
  </List>
</NavigationStack>
```

### 6. Launch the View

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```

***

## Key Components

- **List**: Displays a scrollable, editable list of items.
- **ForEach**: Dynamically generates views based on item count.
- **EditButton**: Automatically enables editing mode in the list when tapped.
- **onDelete / onMove**: Callback functions triggered during item removal or reordering.
- **useState**: Tracks the current array of items in the list.

***

## Notes

- Always provide a unique `key` for each item in `ForEach` to ensure correct rendering.
- Reordering and deletion are only available while in editing mode, which is toggled using `EditButton`.

***

## Use Cases

- Reorderable lists (e.g., task prioritization)
- Editable collections (e.g., color palette, items, settings)
- Dynamic UI that responds to user input

This example provides a flexible foundation for interactive lists in your custom scripts or tools.



---
url: /guide/Views/List/Editable List/index_example.md
---

# Example

```tsx
import { Color, EditButton, ForEach, List, Navigation, NavigationStack, Script, Text, useState } from "scripting"

function Example() {
  const [colors, setColors] = useState<Color[]>([
    "red",
    "orange",
    "yellow",
    "green",
    "blue",
    "purple",
  ])

  function onDelete(indices: number[]) {
    setColors(colors.filter((_, index) => !indices.includes(index)))
  }

  function onMove(indices: number[], newOffset: number) {
    const movingItems = indices.map(index => colors[index])
    const newColors = colors.filter((_, index) => !indices.includes(index))
    newColors.splice(newOffset, 0, ...movingItems)
    setColors(newColors)
  }

  return <NavigationStack>
    <List
      navigationTitle={"Editable List"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        confirmationAction: [
          <EditButton />,
        ]
      }}
    >
      <ForEach
        count={colors.length}
        itemBuilder={index =>
          <Text
            key={colors[index]} // Must provide a unique key!!!
          >{colors[index]}</Text>
        }
        onDelete={onDelete}
        onMove={onMove}
      />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/List/List interaction/index.md
---

# List interaction

This example demonstrates how to implement interactive list items in the **Scripting** app using **swipe gestures**. By leveraging `leadingSwipeActions` and `trailingSwipeActions`, you can provide contextual actions such as marking a message as unread, deleting a message, or flagging it.

***

## Overview

You will learn how to:

- Display a list of messages using a custom cell layout
- Implement swipe actions on both leading and trailing edges
- Configure swipe behavior (e.g. disabling full swipe)
- Use `Button`, `Label`, and `Circle` for interactive UI elements

***

## Example Code

### 1. Define Message Data Type

```ts
type Message = {
  from: string
  content: string
  isUnread: boolean
}
```

### 2. Create a Custom Message Cell

Each message is rendered with a colored indicator (for unread status), sender name, and content using `HStack` and `VStack`.

```tsx
function MessageCell({
  message
}: {
  message: Message
}) {
  return <HStack>
    <Circle
      fill={message.isUnread ? "systemBlue" : "clear"}
      frame={{
        width: 16,
        height: 16,
      }}
    />
    <VStack alignment={"leading"}>
      <Text font={"headline"}>{message.from}</Text>
      <Text>{message.content}</Text>
    </VStack>
  </HStack>
}
```

### 3. Manage State and Actions

```tsx
const [messages, setMessages] = useState<Message[]>(...)

function toggleUnread(message: Message) {
  setMessages(messages.map(item =>
    item !== message ? item : { ...message, isUnread: !item.isUnread }
  ))
}

function deleteMessage(message: Message) {
  setMessages(messages.filter(item => item !== message))
}
```

### 4. Construct the List with Swipe Actions

```tsx
return <NavigationStack>
  <List
    navigationTitle={"Messages"}
    navigationBarTitleDisplayMode={"inline"}
    listStyle={"inset"}
  >
    {messages.map(message =>
      <MessageCell
        message={message}
        leadingSwipeActions={{
          allowsFullSwipe: false,
          actions: [
            <Button
              action={() => toggleUnread(message)}
              tint={"systemBlue"}
            >
              {message.isUnread
                ? <Label title={"Read"} systemImage={"envelope.open"} />
                : <Label title={"Unread"} systemImage={"envelope.badge"} />
              }
            </Button>
          ]
        }}
        trailingSwipeActions={{
          actions: [
            <Button
              role={"destructive"}
              action={() => deleteMessage(message)}
            >
              <Label title={"Delete"} systemImage={"trash"} />
            </Button>,
            <Button
              action={() => {}}
              tint={"systemOrange"}
            >
              <Label title={"Flag"} systemImage={"flag"} />
            </Button>
          ]
        }}
      />
    )}
  </List>
</NavigationStack>
```

### 5. Present the View and Exit

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```

***

## Key Features

- **leadingSwipeActions**: Add actions triggered by swiping from the leading edge (left-to-right in LTR layouts).
- **trailingSwipeActions**: Add actions triggered by swiping from the trailing edge.
- **allowsFullSwipe**: When set to `false`, prevents full swipe from automatically triggering the first action.
- **Button Roles**: Use roles like `"destructive"` to style buttons (e.g., red for delete).
- **tint**: Customize button color for better visual context.

***

## Use Cases

- **Email/Messaging Scripts**: Mark messages as read/unread, delete, archive, or flag.
- **To-Do Lists**: Complete or remove tasks with quick gestures.
- **Custom Tools**: Attach context-specific actions to list items.

Swipe actions provide an efficient and intuitive way for users to perform actions directly within list views, improving interaction speed and user experience.



---
url: /guide/Views/List/List interaction/index_example.md
---

# Example

```tsx
import { Button, Circle, HStack, Label, List, Navigation, NavigationStack, Script, Text, useState, VStack } from "scripting"

type Message = {
  from: string
  content: string
  isUnread: boolean
}

function MessageCell({
  message
}: {
  message: Message
}) {
  return <HStack>
    <Circle
      fill={message.isUnread ? "systemBlue" : "clear"}
      frame={{
        width: 16,
        height: 16,
      }}
    />
    <VStack
      alignment={"leading"}
    >
      <Text font={"headline"}>{message.from}</Text>
      <Text>{message.content}</Text>
    </VStack>
  </HStack>
}

function Example() {
  const [messages, setMessages] = useState<Message[]>(() => [
    {
      from: "Maria Ruiz",
      content: "If you have a list of messages, you can add an action to toggle a message as unread on a swipe from the leading edge, and actions to delete or flag messages on a trailing edge swipe.",
      isUnread: true,
    },
    {
      from: "Mei Chen",
      content: "Actions appear in the order you list them, starting from the swipe’s originating edge. In the example, the Delete action appears closest to the screen’s trailing edge",
      isUnread: true,
    },
    {
      from: "Maria Ruiz",
      content: "By default, the user can perform the first action for a given swipe direction with a full swipe. The user can perform both the toggle unread and delete actions with full swipes. You can opt out of this behavior for an edge by setting the allowsFullSwipe parameter to false.",
      isUnread: false,
    },
    {
      from: "Mei Chen",
      content: "When you set a role for a button using one of the values from the ButtonRole, system styles the button according to its role. In the example above, the delete action appears in red because it has the destructive role. If you want to set a different color, add the tint property to the button",
      isUnread: true,
    }
  ])

  function toggleUnread(message: Message) {
    setMessages(messages.map(item => item !== message ? item : {
      ...message,
      isUnread: !item.isUnread
    }))
  }

  function deleteMessage(message: Message) {
    setMessages(messages.filter(item => item !== message))
  }

  return <NavigationStack>
    <List
      navigationTitle={"Messages"}
      navigationBarTitleDisplayMode={"inline"}
      listStyle={"inset"}
    >
      {messages.map(message =>
        <MessageCell
          message={message}
          leadingSwipeActions={{
            allowsFullSwipe: false,
            actions: [
              <Button
                action={() => toggleUnread(message)}
                tint={"systemBlue"}
              >
                {message.isUnread
                  ? <Label title={"Read"} systemImage={"envelope.open"} />
                  : <Label title={"Unread"} systemImage={"envelope.badge"} />
                }
              </Button>
            ]
          }}
          trailingSwipeActions={{
            actions: [
              <Button
                role={"destructive"}
                action={() => deleteMessage(message)}
              >
                <Label title={"Delete"} systemImage={"trash"} />
              </Button>,
              <Button
                action={() => { }}
                tint={"systemOrange"}
              >
                <Label title={"Flag"} systemImage={"flag"} />
              </Button>
            ]
          }}
        />
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/List/List style/index.md
---

# List style

The `listStyle` property allows you to customize the behavior and appearance of a list in your UI when using the `List` view.

## Property Declaration

```tsx
listStyle?: ListStyle;
```

### Description

The `listStyle` property defines the visual style of a list, allowing you to choose from various predefined list styles.

### Accepted Values

The `listStyle` property accepts the following string values:

- **`automatic`**: Uses the platform’s default behavior and appearance for a list.
- **`bordered`**: Displays a list with standard borders.
- **`carousel`**: Applies a carousel-like appearance to the list.
- **`elliptical`**: Gives the list an elliptical style.
- **`grouped`**: Displays the list in a grouped format.
- **`inset`**: Applies an inset appearance to the list.
- **`insetGroup`**: Combines inset and grouped styles for the list.
- **`plain`**: Displays the list in a plain style without additional decorations.
- **`sidebar`**: Renders the list in a sidebar-like appearance.

### Default Behavior

If `listStyle` is not specified, the default style is determined by the platform.

## Usage Example

Here’s how you can apply the `listStyle` property in your TypeScript code:

### Example: Plain List Style

```tsx
<List
  listStyle="plain"
>
  <Text>Item 1</Text>
  <Text>Item 2</Text>
  <Text>Item 3</Text>
</List>
```

This creates a list with a plain style.

### Example: Grouped List Style

```tsx
<List
  listStyle="grouped"
>
  <Section header={
    <Text>Fruits</Text>
  }>
    <Text>Apple</Text>
    <Text>Banana</Text>
  </Section>
  <Section header={
    <Text>Vegetables</Text>
  }>
    <Text>Carrot</Text>
    <Text>Broccoli</Text>
  </Section>
</List>
```

This creates a grouped list with sections.

### Example: Sidebar List Style

```tsx
<List
  listStyle="sidebar"
>
  <Text>Home</Text>
  <Text>Settings</Text>
  <Text>Profile</Text>
</List>
```

This creates a sidebar-style list.

## Notes

- The `listStyle` property directly maps to SwiftUI’s `listStyle` modifier.
- Make sure to match the string value with one of the predefined styles listed above to avoid runtime errors.



---
url: /guide/Views/List/List style/list_style.md
---

# Example

```tsx
import { List, ListStyle, Navigation, NavigationStack, Picker, Script, Section, Text, useMemo, useState } from "scripting"

function Example() {
  const [listStyle, setListStyle] = useState<ListStyle>("automatic")
  const listStyleOptions = useMemo<ListStyle[]>(() => [
    "automatic",
    "bordered",
    "carousel",
    "elliptical",
    "grouped",
    "inset",
    "insetGroup",
    "plain",
    "sidebar",
  ], [])

  return <NavigationStack>
    <List
      navigationTitle={"List Style"}
      navigationBarTitleDisplayMode={"inline"}
      listStyle={listStyle}
    // listSectionSpacing={5} // apply for all sections
    >
      <Picker
        title={"ListStyle"}
        value={listStyle}
        onChanged={setListStyle as any}
        pickerStyle={"menu"}
      >
        {listStyleOptions.map(listStyle =>
          <Text tag={listStyle}>{listStyle}</Text>
        )}
      </Picker>

      <Section>
        <Text
          badge={10} // Use a badge to convey optional, supplementary information about a view
        >Recents</Text>
        <Text>Favorites</Text>
      </Section>

      <Section
        header={<Text>Colors</Text>}
        listItemTint={"systemBlue"}
      >
        <Text>Red</Text>
        <Text>Blue</Text>
      </Section>

      <Section
        header={<Text>Shapes</Text>}
      >
        <Text>Rectangle</Text>
        <Text>Circle</Text>
      </Section>

      <Section
        header={<Text>Borders</Text>}
        listSectionSpacing={10} // specify on an individual Section
      >
        <Text>Dashed</Text>
        <Text>Solid</Text>
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/List/Refresable List/index.md
---

# Refresable List

Marks a scrollable view as **refreshable**, enabling the user to pull down to trigger an asynchronous data reload.

## Type

```ts
refreshable?: () => Promise<void>
```

***

## Overview

Use the `refreshable` modifier on scrollable views—such as `<List>`—to implement pull-to-refresh functionality. When the user pulls down past the top of the view, the framework executes the asynchronous handler defined by `refreshable`.

Inside the handler, you can perform any asynchronous operations (e.g., fetching network data or updating local state), and once the operation completes, the refresh control will automatically dismiss.

This behavior closely mirrors SwiftUI’s [`refreshable`](https://developer.apple.com/documentation/swiftui/view/refreshable%28action:%29) modifier.

***

## Usage Example

```tsx
<List
  navigationTitle="Refreshable List"
  navigationBarTitleDisplayMode="inline"
  refreshable={refresh}
/>
```

### Full Example

```tsx
function Example() {
  const [data, setData] = useState(generateRandomList)

  function generateRandomList() {
    const data: number[] = []
    const count = Math.ceil(Math.random() * 100 + 10)

    for (let i = 0; i < count; i++) {
      const num = Math.ceil(Math.random() * 1000)
      data.push(num)
    }

    return data
  }

  async function refresh() {
    return new Promise<void>(resolve => {
      setTimeout(() => {
        setData(generateRandomList())
        resolve()
      }, 2000)
    })
  }

  return <NavigationStack>
    <List
      navigationTitle="Refreshable List"
      navigationBarTitleDisplayMode="inline"
      refreshable={refresh}
    >
      <Section header={
        <Text textCase={null}>Pull down to refresh</Text>
      }>
        {data.map(item =>
          <Text>Number: {item}</Text>
        )}
      </Section>
    </List>
  </NavigationStack>
}
```

***

## Behavior Notes

- The `refreshable` function **must return a `Promise<void>`**. The refresh control remains visible until the promise resolves.
- Use `await` inside the refresh function to perform async tasks:

  ```ts
  refreshable={async () => {
    const result = await fetchData()
    updateState(result)
  }}
  ```
- This modifier is only effective on **scrollable containers**, such as `<List>`.
- You should update the relevant state inside the handler to reflect new data.
- Avoid long-running or blocking tasks without feedback; always resolve the promise in a timely manner to dismiss the refresh spinner.

***

## Best Practices

- Keep refresh logic short and efficient.
- Always **resolve** the promise to ensure the UI doesn’t hang.
- If needed, use a short delay to simulate refresh animations during development:

  ```ts
  await new Promise(resolve => setTimeout(resolve, 1000))
  ```



---
url: /guide/Views/List/Refresable List/refreshable_list.md
---

# Example

```tsx
import { List, Navigation, NavigationStack, Script, Section, Text, useState } from "scripting"

function Example() {
  const [data, setData] = useState(generateRandomList)

  function generateRandomList() {
    const data: number[] = []
    const count = Math.ceil(Math.random() * 100 + 10)

    for (let i = 0; i < count; i++) {
      const num = Math.ceil(Math.random() * 1000)
      data.push(num)
    }

    return data
  }

  async function refresh() {
    return new Promise<void>(resolve => {
      setTimeout(() => {
        setData(generateRandomList())
        resolve()
      }, 1000 * 2)
    })
  }

  return <NavigationStack>
    <List
      navigationTitle={"Refreshable List"}
      navigationBarTitleDisplayMode={"inline"}
      refreshable={refresh}
    >
      <Section header={
        <Text textCase={null}>Pull down to refresh</Text>
      }>
        {data.map(item =>
          <Text>Number: {item}</Text>
        )}
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/List/Represent data hierarchy in sections/index.md
---

# Represent data hierarchy in sections

This example demonstrates how to use the `Section` component in the **Scripting** app to visually organize hierarchical data within a `List`. The content is structured by grouping related items—such as staff members by department—into labeled sections for better readability and navigation.

***

## Overview

You will learn how to:

- Display structured data using `List` and `Section`
- Group related items under section headers
- Create reusable row components for clarity
- Bind hierarchical data (Company → Departments → Staff) into a readable layout

***

## Data Model

The example defines a three-level hierarchy representing a company structure:

```ts
type Person = {
  name: string
  phoneNumber: string
}

type Department = {
  name: string
  staff: Person[]
}

type Company = {
  name: string
  departments: Department[]
}
```

### Sample Data

```ts
const companyA: Company = {
  name: "Company A",
  departments: [
    {
      name: "Sales",
      staff: [
        { name: "Juan Chavez", phoneNumber: "(408) 555-4301" },
        { name: "Mei Chen", phoneNumber: "(919) 555-2481" }
      ]
    },
    {
      name: "Engineering",
      staff: [
        { name: "Bill James", phoneNumber: "(408) 555-4450" },
        { name: "Anne Johnson", phoneNumber: "(417) 555-9311" }
      ]
    }
  ]
}
```

***

## Person Row Component

`PersonRowView` is a reusable component that displays a person's name and phone number with appropriate formatting.

```tsx
function PersonRowView({ person }: { person: Person }) {
  return <VStack alignment={"leading"} spacing={3}>
    <Text font={"headline"} foregroundStyle={"label"}>{person.name}</Text>
    <HStack spacing={3} font={"subheadline"} foregroundStyle={"secondaryLabel"}>
      <Label title={person.phoneNumber} systemImage={"phone"} />
    </HStack>
  </VStack>
}
```

***

## Main View Layout

The main view uses a `NavigationStack` containing a `List` where each department is represented as a separate `Section`. The section header displays the department name, and each person is rendered using the `PersonRowView`.

```tsx
function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"Represent data hierarchy in sections"}
      navigationBarTitleDisplayMode={"inline"}
    >
      {companyA.departments.map(department =>
        <Section
          header={<Text>{department.name}</Text>}
        >
          {department.staff.map(person =>
            <PersonRowView person={person} />
          )}
        </Section>
      )}
    </List>
  </NavigationStack>
}
```

***

## Entry Point

The script presents the view and exits upon dismissal:

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```

***

## Key Components

- **List**: Provides a scrollable container for content.
- **Section**: Groups related items under a common header.
- **NavigationStack**: Enables title display and navigation context.
- **Reusable View**: `PersonRowView` ensures clean, consistent row formatting.

***

## Use Cases

- Grouping contacts by department or team
- Displaying categorized lists (e.g., tasks, inventory, regions)
- Organizing any data set that has a parent-child structure

Using `Section` within `List` improves both visual structure and user comprehension when working with hierarchical data.



---
url: /guide/Views/List/Represent data hierarchy in sections/index_example.md
---

# Example

```tsx
import { HStack, Label, List, Navigation, NavigationStack, Script, Section, Text, VStack } from "scripting"

type Department = {
  name: string
  staff: Person[]
}

type Company = {
  name: string
  departments: Department[]
}

type Person = {
  name: string
  phoneNumber: string
}

const companyA: Company = {
  name: "Company A",
  departments: [
    {
      name: "Sales",
      staff: [
        {
          name: "Juan Chavez",
          phoneNumber: "(408) 555-4301",
        },
        {
          name: "Mei Chen",
          phoneNumber: "(919) 555-2481",
        }
      ]
    },
    {
      name: "Engineering",
      staff: [
        {
          name: "Bill James",
          phoneNumber: "(408) 555-4450"
        },
        {
          name: "Anne Johnson",
          phoneNumber: "(417) 555-9311"
        }
      ]
    }
  ]
}

function PersonRowView({
  person
}: {
  person: Person
}) {
  return <VStack
    alignment={"leading"}
    spacing={3}
  >
    <Text
      foregroundStyle={"label"}
      font={"headline"}
    >{person.name}</Text>
    <HStack
      spacing={3}
      foregroundStyle={"secondaryLabel"}
      font={"subheadline"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"Represent data hierarchy in sections"}
      navigationBarTitleDisplayMode={"inline"}
    >
      {companyA.departments.map(department =>
        <Section
          header={
            <Text>{department.name}</Text>
          }
        >
          {department.staff.map(person =>
            <PersonRowView
              person={person}
            />
          )}
        </Section>
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/List/Selectable List.md
---

# Selectable List

`List.selection` provides **selection state binding** for the `List` component. It enables:

- Single selection mode
- Multiple selection mode
- Integration with edit mode via `EditButton`
- Automatic synchronization with user interaction

***

## 1. API Definition

```ts
type ListProps = {
  selection?: Observable<string | null> | Observable<string[]>
  ...
}

declare const List: FunctionComponent<ListProps>
```

***

## 2. selection Type Description

The selection mode is determined by the generic type of `Observable`:

| Mode               | Observable Type              | Description                                   |
| ------------------ | ---------------------------- | --------------------------------------------- |
| Single selection   | `Observable<string \| null>` | Only one item can be selected                 |
| Multiple selection | `Observable<string[]>`       | Multiple items can be selected simultaneously |

***

## 3. Automatic Binding Rules with ForEach

When `List` is bound to `selection`, **every item inside `ForEach.data` must conform to the following structure**:

```ts
{
  id: string
}
```

Binding behavior:

1. The `id` property is automatically used as the **unique selection identifier**
2. When a list item is tapped:

   - Single selection mode: `selected.value` is automatically set to the tapped item’s `id`
   - Multiple selection mode: the `id` is automatically added to or removed from `selected.value`
3. Manual tap handling is not required
4. The `id` value must remain unique and stable; otherwise, selection behavior becomes undefined

***

## 4. Single Selection Mode

### 1. Definition

```tsx
const selected = useObservable<string | null>(null)
```

### 2. Usage Example

```tsx
function View() {
  const selected = useObservable<string | null>(null)

  const options = useObservable<{ id: string }[]>(() =>
    new Array(10).fill(0).map((_, i) => ({ 
      id: i.toString() 
    }))
  )

  return <NavigationStack>
    <List selection={selected}>
      <ForEach
        data={options}
        builder={item =>
          <Text>{item.id}</Text>
        }
      />
    </List>
  </NavigationStack>
}
```

### 3. State Description

- `null`: no item is currently selected
- `"3"`: the item whose `id` is `"3"` is selected

***

## 5. Multiple Selection Mode

### 1. Definition

```tsx
const selected = useObservable<string[]>([])
```

### 2. Usage Example

```tsx
function View() {
  const dismiss = Navigation.useDismiss()
  const selected = useObservable<string[]>([])

  const options = useObservable<{ id: string }[]>(() =>
    new Array(30).fill(0).map((_, i) => ({
      id: i.toString()
    }))
  )

  console.log(selected.value)

  return <NavigationStack>
    <List
      navigationTitle="Page Title"
      navigationBarTitleDisplayMode="inline"
      toolbar={{
        topBarLeading: <Button
          title="Done"
          action={dismiss}
        />,
        topBarTrailing: <EditButton />
      }}
      selection={selected}
    >
      <ForEach
        data={options}
        builder={item =>
          <Text>{item.id}</Text>
        }
      />
    </List>
  </NavigationStack>
}
```

### 3. State Description

`selected.value` is always an array of strings, for example:

```ts
["2", "5", "8"]
```

This indicates that three items are currently selected.

***

## 6. Interaction Between selection and EditButton

When `List` is bound to `selection`:

1. `EditButton` automatically enables list editing mode
2. While in edit mode:

   - Single selection: tapping an item replaces the current selection
   - Multiple selection: multiple items can be selected simultaneously
3. After exiting edit mode:

   - `selected.value` is **automatically reset**

     - Single selection resets to `null`
     - Multiple selection resets to an empty array `[]`

This behavior matches SwiftUI’s native edit mode behavior.

***

## 7. Programmatic Control of selection

In addition to user interaction, selection can be modified by code.

### Single Selection

```ts
selected.setValue("5")
```

### Multiple Selection

```ts
selected.setValue(["1", "3", "7"])
```

The UI will update automatically to reflect the new selection state.

***

## 8. Compatibility with NavigationStack

`List.selection` is fully compatible with `NavigationStack` and does not affect:

- Navigation behavior
- Toolbar layout
- Edit mode interactions
- Back navigation behavior

Recommended structure:

```tsx
<NavigationStack>
  <List selection={selected}>
    ...
  </List>
</NavigationStack>
```

***

## 9. Common Errors and Misuse

### 1. Incorrect selection Type

Incorrect:

```ts
const selected = useObservable<number | null>(null)
```

Correct:

```ts
const selected = useObservable<string | null>(null)
```

Currently, only `string` is supported as the selection identifier type.

***

### 2. Incorrect Initialization for Multiple Selection

Incorrect:

```ts
const selected = useObservable<string[]>(null)
```

Correct:

```ts
const selected = useObservable<string[]>([])
```

***

### 3. Missing id in ForEach.data

Incorrect:

```tsx
const options = [{ name: "A" }, { name: "B" }]
```

This will cause:

- Selection to fail
- Unstable checked state
- List reuse inconsistencies

***

## 10. Typical Use Cases

`List.selection` is suitable for:

- Single-choice settings (themes, languages, preferences)
- Batch deletion
- Batch export
- Batch sharing
- File managers
- Contact pickers
- Task lists with selection



---
url: /guide/Views/List/Use list for navigations/index.md
---

# Use list for navigations

This example demonstrates how to build a navigable list-based interface in the **Scripting** app. It organizes structured data into expandable sections using `DisclosureGroup`, and allows users to navigate to detail views using `NavigationLink`.

***

## Overview

You will learn how to:

- Use `List` to display a directory of departments and staff
- Use `DisclosureGroup` to group related items under collapsible headers
- Use `NavigationLink` to navigate to a detailed view for each item
- Build reusable view components for clarity and modularity

***

## Data Model

The example defines a nested data structure representing a company, its departments, and the staff within each department.

```ts
type Person = {
  name: string
  phoneNumber: string
}

type Department = {
  name: string
  staff: Person[]
}

type Company = {
  name: string
  departments: Department[]
}
```

### Sample Data

```ts
const companyA: Company = {
  name: "Company A",
  departments: [
    {
      name: "Sales",
      staff: [
        { name: "Juan Chavez", phoneNumber: "(408) 555-4301" },
        { name: "Mei Chen", phoneNumber: "(919) 555-2481" }
      ]
    },
    {
      name: "Engineering",
      staff: [
        { name: "Bill James", phoneNumber: "(408) 555-4450" },
        { name: "Anne Johnson", phoneNumber: "(417) 555-9311" }
      ]
    }
  ]
}
```

***

## View Components

### `PersonRowView`

A reusable component to display a person's name and phone number in a vertically stacked layout.

```tsx
function PersonRowView({ person }: { person: Person }) {
  return <VStack alignment={"leading"} spacing={3}>
    <Text font={"headline"} foregroundStyle={"label"}>{person.name}</Text>
    <HStack spacing={3} font={"subheadline"} foregroundStyle={"secondaryLabel"}>
      <Label title={person.phoneNumber} systemImage={"phone"} />
    </HStack>
  </VStack>
}
```

### `PersonDetailView`

Displays detailed information about a selected person.

```tsx
function PersonDetailView({ person }: { person: Person }) {
  return <VStack>
    <Text font={"title"} foregroundStyle={"label"}>{person.name}</Text>
    <HStack foregroundStyle={"secondaryLabel"}>
      <Label title={person.phoneNumber} systemImage={"phone"} />
    </HStack>
  </VStack>
}
```

***

## Main View Layout

The root view uses a `NavigationStack` and displays departments grouped in a `List`. Each `DisclosureGroup` expands to show staff members. Selecting a person navigates to their detail view.

```tsx
function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"Staff Directory"}
      navigationBarTitleDisplayMode={"inline"}
    >
      {companyA.departments.map(department =>
        <DisclosureGroup title={department.name}>
          {department.staff.map(person =>
            <NavigationLink
              destination={<PersonDetailView person={person} />}
            >
              <PersonRowView person={person} />
            </NavigationLink>
          )}
        </DisclosureGroup>
      )}
    </List>
  </NavigationStack>
}
```

***

## Launching the View

```tsx
async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```

***

## Key Components

- **List**: Displays a vertically scrollable list of items.
- **DisclosureGroup**: Organizes content into expandable/collapsible sections.
- **NavigationLink**: Enables navigation to another view when tapped.
- **NavigationStack**: Provides navigation context for view transitions.

***

## Use Cases

- Building directory-style interfaces (e.g., org charts, contact lists)
- Organizing hierarchical data with drill-down navigation
- Providing a structured browsing experience

This example offers a clean and scalable pattern for navigating through structured lists and accessing detailed information with ease.



---
url: /guide/Views/List/Use list for navigations/index_example.md
---

# Example

```tsx
import { DisclosureGroup, HStack, Label, List, Navigation, NavigationLink, NavigationStack, Script, Text, VStack } from "scripting"

type Person = {
  name: string
  phoneNumber: string
}

type Department = {
  name: string
  staff: Person[]
}

type Company = {
  name: string
  departments: Department[]
}

const companyA: Company = {
  name: "Company A",
  departments: [
    {
      name: "Sales",
      staff: [
        {
          name: "Juan Chavez",
          phoneNumber: "(408) 555-4301",
        },
        {
          name: "Mei Chen",
          phoneNumber: "(919) 555-2481",
        }
      ]
    },
    {
      name: "Engineering",
      staff: [
        {
          name: "Bill James",
          phoneNumber: "(408) 555-4450"
        },
        {
          name: "Anne Johnson",
          phoneNumber: "(417) 555-9311"
        }
      ]
    }
  ]
}

function PersonRowView({
  person
}: {
  person: Person
}) {
  return <VStack
    alignment={"leading"}
    spacing={3}
  >
    <Text
      foregroundStyle={"label"}
      font={"headline"}
    >{person.name}</Text>
    <HStack
      spacing={3}
      foregroundStyle={"secondaryLabel"}
      font={"subheadline"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

function Example() {

  return <NavigationStack>
    <List
      navigationTitle={"Staff Directory"}
      navigationBarTitleDisplayMode={"inline"}
    >
      {companyA.departments.map(department =>
        <DisclosureGroup
          title={department.name}
        >
          {department.staff.map(person =>
            <NavigationLink
              destination={
                <PersonDetailView
                  person={person}
                />
              }
            >
              <PersonRowView
                person={person}
              />
            </NavigationLink>
          )}
        </DisclosureGroup>
      )}
    </List>
  </NavigationStack>
}

function PersonDetailView({
  person
}: {
  person: Person
}) {

  return <VStack>
    <Text
      font={"title"}
      foregroundStyle={"label"}
    >{person.name}</Text>
    <HStack
      foregroundStyle={"secondaryLabel"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/LivePhotoView.md
---

# LivePhotoView

`LivePhoto` represents a system Live Photo, which consists of:

- A high-resolution still image
- A short video clip bound to that image

In Scripting, `LivePhoto` is a **system-managed object**. It cannot be instantiated directly with `new` and is typically obtained from:

- A photo picker result
- Asynchronous construction from local image and video files

LivePhoto is commonly used to:

- Display Live Photos in the UI
- Access underlying image and video resources
- Decompose, rebuild, or re-save Live Photos

***

## LivePhoto Class

### size

```ts
readonly size: Size
```

The pixel size of the Live Photo, corresponding to its still image component.

Typical use cases include layout calculation, scaling decisions, and inspecting the original resolution.

***

### getAssetResources()

```ts
getAssetResources(): Promise<{
  data: Data
  assetLocalIdentifier: string
  contentType: UTType
  originalFilename: string
  pixelHeight: number
  pixelWidth: number
}[]>
```

Retrieves the **underlying asset resources** of the Live Photo.

A Live Photo usually contains at least:

- One still image resource (JPEG / HEIC)
- One video resource (QuickTime MOV)

Each returned resource object includes:

- `data`
  The raw binary data of the resource

- `assetLocalIdentifier`
  The Photos framework local identifier for this resource

- `contentType`
  The uniform type identifier (UTType), indicating image or video

- `originalFilename`
  The original filename in the photo library

- `pixelWidth` / `pixelHeight`
  The actual resolution of the resource

Common scenarios include exporting Live Photos, splitting them into image and video files, or re-saving them without intermediate temporary files.

***

### LivePhoto.from(options)

```ts
static from(options: {
  imagePath: string
  videoPath: string
  targetSize?: Size | null
  placeholderImage: UIImage | null
  contentMode?: "aspectFit" | "aspectFill"
  onResult: (
    result: LivePhoto | null,
    info: {
      error: string | null
      degraded: boolean | null
      cancelled: boolean | null
    }
  ) => void
}): Promise<() => void>
```

Asynchronously constructs a Live Photo from a still image file and a matching video file.

Key characteristics:

- The operation is asynchronous
- `onResult` may be invoked multiple times
- Supports degraded (low-quality) intermediate results
- Can be cancelled explicitly

#### Parameters

- `imagePath`
  Path to the still image file (JPEG / HEIC)

- `videoPath`
  Path to the associated video file (MOV)

- `targetSize`
  The desired output size of the Live Photo
  Pass `null` to preserve the original size

- `placeholderImage`
  A UIImage displayed while the Live Photo is loading

- `contentMode`
  How the placeholder image is rendered

  - `aspectFit`: preserves aspect ratio
  - `aspectFill`: fills the container, possibly cropping

- `onResult(result, info)`
  Callback invoked when loading completes or updates

#### info Object

- `error`
  Error message if the request fails

- `degraded`
  Indicates whether the result is a lower-quality version

- `cancelled`
  Indicates whether the request was cancelled

#### Return Value

Returns a Promise that resolves to a **cancellation function**:

```ts
() => void
```

Calling this function cancels the Live Photo loading request.

***

## LivePhotoView

`LivePhotoView` is a native UI component used to **display and play a Live Photo**, matching the behavior of the system Photos app.

It is purely a presentation component and does not handle loading, permissions, or persistence.

***

### LivePhotoViewProps

```ts
type LivePhotoViewProps = {
  livePhoto: Observable<LivePhoto | null>
}
```

#### livePhoto

- Type: `Observable<LivePhoto | null>`
- Required

An observable binding to the Live Photo being displayed.

Using `Observable` allows:

- Asynchronous loading workflows
- Dynamic replacement of the Live Photo
- Automatic UI updates without manual refresh logic

When the observable value changes, `LivePhotoView` updates accordingly.

***

## LivePhotoView Example

The following concise example demonstrates how to display a Live Photo using `LivePhotoView`.

```tsx
import { LivePhotoView, Button, useObservable } from "scripting"

function Example() {
  const livePhoto = useObservable<LivePhoto | null>(null)

  return <>
    <Button
      title="Set Live Photo"
      action={async () => {
        const lp = await getLivePhotoSomehow()
        livePhoto.setValue(lp)
      }}
    />

    <LivePhotoView
      livePhoto={livePhoto}
      frame={{ idealHeight: 300 }}
    />
  </>
}
```

### Explanation

- `useObservable<LivePhoto | null>`
  Declares an observable Live Photo state

- `livePhoto.setValue(lp)`
  Updates the observable once the Live Photo is available

- `LivePhotoView`
  Automatically renders and plays the Live Photo when the observable value is non-null

This pattern highlights the core design principles:

- Data acquisition and UI presentation are decoupled
- UI updates are driven by reactive state
- No manual invalidation or redraw logic is required

***

## Design Notes

- `LivePhoto` instances are system-managed objects
- `LivePhotoView` must be driven by an `Observable`
- A single LivePhoto can be shared across multiple views
- The recommended pattern is always **state-driven rendering**

***

## Summary

Live Photo support in Scripting consists of two core components:

- **LivePhoto**
  A data model for representing, constructing, and inspecting system Live Photos

- **LivePhotoView**
  A native UI component for rendering Live Photos with dynamic updates



---
url: /guide/Views/Markdown.md
---

# Markdown

The `Markdown` component renders styled Markdown content within your script’s user interface. It supports different visual themes and syntax highlighter styles for displaying code blocks, making it ideal for rendering documentation, previews, or custom rich-text content.

***

## Import

```ts
import { Markdown } from 'scripting'
```

***

## Usage

```tsx
<Markdown content="# Hello\nThis is a **markdown** view." />
```

***

## Props

### `content: string` **(required)**

The Markdown-formatted text to display. This should follow standard Markdown syntax.

```tsx
<Markdown content="## Features\n- Supports **bold**, *italic*, and `code` blocks." />
```

***

### `theme?: 'basic' | 'github' | 'docC'`

Sets the visual theme for the Markdown content. Available options:

- `'basic'`: A simple, neutral theme.
- `'github'`: GitHub-style styling (default for code-like docs).
- `'docC'`: A theme inspired by Apple's DocC documentation style.

```tsx
<Markdown content="**Hello**" theme="docC" />
```

***

### `highlighterTheme?: 'midnight' | 'presentation' | 'sundellsColors' | 'sunset' | 'wwdc17' | 'wwdc18'`

Specifies a syntax highlighting theme for code blocks within the Markdown content. If not set, no highlighting theme is applied by default.

Available options:

- `'midnight'`
- `'presentation'`
- `'sundellsColors'`
- `'sunset'`
- `'wwdc17'`
- `'wwdc18'`

````tsx
<Markdown
  content="```js\nconsole.log('Hello')\n```"
  highlighterTheme="wwdc18"
/>
````

***

### `useDefaultHighlighterTheme?: boolean`

If set to `true`, the Markdown view will automatically use the default highlighter theme based on the system’s color scheme (light or dark).

> ⚠️ This has no effect if `highlighterTheme` is explicitly set.

````tsx
<Markdown
  content="```swift\nprint(\"Hello\")\n```"
  useDefaultHighlighterTheme={true}
/>
````

***

### `scrollable?: boolean`

Default: `true`

Controls whether the Markdown view is scrollable. Set to `false` to embed static Markdown content in a fixed area (e.g. inside a scrollable parent container).

```tsx
<Markdown content="# Title" scrollable={false} />
```

***

## Example

```tsx
<Markdown
  content={`
## Welcome to Scripting

Here's a quick example:

\`\`\`ts
const hello = "world"
console.log(hello)
\`\`\`
  `}
  theme="github"
  highlighterTheme="sunset"
/>
```



---
url: /guide/Views/Menu/index.md
---

# Menu

The `Menu` component in Scripting is a user interface control that presents a list of actions or nested submenus. It functions as a container for contextual actions and supports both text-based and custom visual labels. Inspired by SwiftUI’s `Menu`, this component is especially useful in toolbars, context menus, and compact UI layouts.

***

## Purpose

Use `Menu` to group multiple related actions under a single interaction point. A menu can include `Button` components and even other nested `Menu` components for hierarchical command structures.

***

## Props

```ts
type MenuProps = {
  primaryAction?: () => void
  children?: VirtualNode | (VirtualNode | undefined | null)[] 
} & (
  | {
      title: string
      systemImage?: string
    }
  | {
      label: VirtualNode
    }
)
```

### Base Properties

| Property        | Type                             | Description                                                                                                    |
| --------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `primaryAction` | `() => void` (optional)          | An action that executes when the menu is tapped directly, without expanding it. Useful for a default behavior. |
| `children`      | `VirtualNode` \| `VirtualNode[]` | The menu’s content—usually a list of `Button` components or nested `Menu` components.                          |

### Label Configuration (choose one of the following)

You must specify **either** a text-based `title` or a custom `label`.

#### Option 1: `title` with optional system image

| Property      | Type                | Description                                                     |
| ------------- | ------------------- | --------------------------------------------------------------- |
| `title`       | `string`            | A text string describing the menu’s purpose.                    |
| `systemImage` | `string` (optional) | The name of a system SF Symbol image to display with the title. |

#### Option 2: `label` (custom view)

| Property | Type          | Description                                                                      |
| -------- | ------------- | -------------------------------------------------------------------------------- |
| `label`  | `VirtualNode` | A custom view node (e.g., `Text`, `Image`, `HStack`) to use as the menu’s label. |

***

## Example

```tsx
<Menu title="Actions">
  <Button title="Rename" action={rename} />
  <Button title="Delete" action={delete} />
  <Menu title="Copy">
    <Button title="Copy" action={copy} />
    <Button title="Copy Formatted" action={copyFormatted} />
  </Menu>
</Menu>
```

In this example:

- A top-level menu labeled **"Actions"** contains:

  - A "Rename" button
  - A "Delete" button
  - A nested **"Copy"** submenu with two more buttons

***

## Example with `primaryAction` and `systemImage`

```tsx
<Menu
  title="More"
  systemImage="ellipsis"
  primaryAction={() => console.log("Menu tapped")}
>
  <Button title="Settings" action={openSettings} />
  <Button title="Help" action={openHelp} />
</Menu>
```

- If the user taps the menu directly, `primaryAction` is executed.
- If the user long-presses or clicks to expand, the menu shows its child items.

***

## Example with Custom Label

```tsx
<Menu
  label={
    <HStack>
      <Image systemName="gear" />
      <Text>Options</Text>
    </HStack>
  }
>
  <Button title="Configure" action={configure} />
</Menu>
```

This example uses a custom label combining an icon and text.

***

## Notes

- Menus are often used inside `toolbar`, `contextMenu`, or as part of compact user interfaces.
- Menus can be nested without restriction to create multi-level action hierarchies.
- Use `primaryAction` for lightweight actions that don't require expansion.



---
url: /guide/Views/Menu/index_example.md
---

# Example

```tsx
import { Button, Group, List, Menu, Navigation, NavigationStack, Script, ScrollView, Section, Text, VStack } from "scripting"

function Example() {

  return <NavigationStack>
    <List
      navigationTitle={"Menu"}
      navigationBarTitleDisplayMode={"inline"}
    >

      <Section
        header={
          <Text>Menu</Text>
        }
      >
        <Menu
          title={"Open Menu"}
        >
          <Button
            title="Rename"
            action={() => console.log("Rename")}
          />
          <Button
            title="Delete"
            role={"destructive"}
            action={() => console.log("Delete")}
          />
          <Menu title="Copy">
            <Button
              title="Copy"
              action={() => console.log("Copy")}
            />
            <Button
              title="Copy Formated"
              action={() => console.log("Copy fomatted")}
            />
          </Menu>
        </Menu>
      </Section>

      <Section
        header={
          <Text>ContextMenu</Text>
        }
      >
        <Text
          foregroundStyle={"link"}
          contextMenu={{
            menuItems: <Group>
              <Button
                title="Add"
                action={() => {
                  // Add
                }}
              />
              <Button
                title="Delete"
                role="destructive"
                action={() => {
                  // Delete
                }}
              />
            </Group>
          }}
        >Long Press to open context menu</Text>
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Modal presentaions/index.md
---

# Modal presentaions

The Scripting app supports SwiftUI-style modal view presentations through declarative properties applied to UI components. These include support for `sheet`, `popover`, `fullScreenCover`, `alert`, and `confirmationDialog`. Each of these is defined using structured configuration objects that allow you to present views based on application state.

***

## Alert

Displays an alert with a title, optional message, and one or more actions when the specified condition is true.

```ts
alert?: {
  title: string
  isPresented: boolean
  onChanged: (isPresented: boolean) => void
  actions: VirtualNode
  message?: VirtualNode
}
```

### Properties

- **`title`**: A string used as the title of the alert.
- **`isPresented`**: A boolean value that controls the visibility of the alert.
- **`onChanged`**: A callback function invoked when the `isPresented` value changes. You must update this value to `false` when dismissing the alert.
- **`actions`**: A `VirtualNode` representing the alert’s actions.
- **`message`** (optional): A `VirtualNode` that describes the alert’s message content.

***

## Confirmation Dialog

Displays a confirmation dialog with a title, optional message, and a set of actions. The dialog is shown when the `isPresented` condition is true.

```ts
confirmationDialog?: {
  title: string
  titleVisibility?: Visibility
  isPresented: boolean
  onChanged: (isPresented: boolean) => void
  actions: VirtualNode
  message?: VirtualNode
}
```

### Properties

- **`title`**: The title text for the dialog.
- **`titleVisibility`** (optional): Determines the visibility of the title. Defaults to `"automatic"`.
- **`isPresented`**: Controls whether the dialog is currently visible.
- **`onChanged`**: A callback that updates the `isPresented` state when the dialog is dismissed.
- **`actions`**: A `VirtualNode` representing the dialog’s action buttons.
- **`message`** (optional): A `VirtualNode` providing a descriptive message.

```ts
type Visibility = "automatic" | "hidden" | "visible"
```

***

## Sheet

Presents a modal sheet from the bottom of the screen when the `isPresented` condition is true. Multiple sheets can be registered using an array of presentation objects.

```ts
sheet?: ModalPresentation | ModalPresentation[]
```

***

## Full Screen Cover

Presents a modal view that covers the entire screen. Multiple views can be registered using an array of presentation objects.

```ts
fullScreenCover?: ModalPresentation | ModalPresentation[]
```

***

## Popover

Presents a popover when the `isPresented` condition is true. Popovers can be configured with arrow direction and adaptation strategies.

```ts
popover?: PopoverPresentation | PopoverPresentation[]
```

### PopoverPresentation

```ts
type PopoverPresentation = ModalPresentation & {
  arrowEdge?: Edge
  presentationCompactAdaptation?: PresentationAdaptation | {
    horizontal: PresentationAdaptation
    vertical: PresentationAdaptation
  }
}
```

#### Properties

- **`arrowEdge`** (optional): Defines the edge of the anchor that the popover arrow points to. Defaults to `"top"`.
- **`presentationCompactAdaptation`** (optional): Specifies how the presentation adapts in compact size classes.

```ts
type Edge = "top" | "bottom" | "leading" | "trailing"
```

***

## ModalPresentation

Defines a common interface used by `sheet`, `popover`, and `fullScreenCover`.

```ts
type ModalPresentation = {
  isPresented: boolean
  onChanged: (isPresented: boolean) => void
  content: VirtualNode
}
```

### Properties

- **`isPresented`**: A boolean value indicating whether the modal is shown.
- **`onChanged`**: A callback that updates the `isPresented` state when the modal is dismissed.
- **`content`**: A `VirtualNode` representing the modal view content.

***

## PresentationAdaptation

Specifies the strategy used when adapting modal presentations to different size classes.

```ts
type PresentationAdaptation =
  | "automatic"
  | "fullScreenCover"
  | "none"
  | "popover"
  | "sheet"
```

- **`automatic`**: Uses the system default adaptation.
- **`fullScreenCover`**: Prefers a full-screen cover style.
- **`popover`**: Prefers a popover style.
- **`sheet`**: Prefers a sheet style.
- **`none`**: Disables adaptation if possible.

***

## Example Usage

### Presenting a Sheet

```tsx
<Button
  title={"Present"}
  action={() => setIsPresented(true)}
  sheet={{
    isPresented: isPresented,
    onChanged: setIsPresented,
    content: <VStack>
      <Text>Sheet content</Text>
      <Button title={"Dismiss"} action={() => setIsPresented(false)} />
    </VStack>
  }}
/>
```

### Presenting a Popover

```tsx
<Button
  title={"Show Popover"}
  action={() => setIsPresented(true)}
  popover={{
    isPresented: isPresented,
    onChanged: setIsPresented,
    presentationCompactAdaptation: "popover",
    content: <Text>Popover content</Text>,
    arrowEdge: "top",
  }}
/>
```

### Presenting a Full Screen Cover

```tsx
<Button
  title={"Present"}
  action={() => setIsPresented(true)}
  fullScreenCover={{
    isPresented: isPresented,
    onChanged: setIsPresented,
    content: <VStack>
      <Text>A full-screen modal view.</Text>
    </VStack>
  }}
/>
```

### Configuring Sheet Height

```tsx
sheet={{
  isPresented: isPresented,
  onChanged: setIsPresented,
  content: <VStack
    presentationDetents={[200, "medium", "large"]}
    presentationDragIndicator={"visible"}
  >
    <Text>Resizable sheet</Text>
  </VStack>
}}
```

### Presenting an Alert

```tsx
<Button
  title={"Present"}
  action={() => setIsPresented(true)}
  alert={{
    isPresented: isPresented,
    onChanged: setIsPresented,
    title: "Alert",
    message: <Text>Everything is OK</Text>,
    actions: <Button title={"OK"} action={() => {}} />
  }}
/>
```

### Presenting a Confirmation Dialog

```tsx
<Button
  title={"Present"}
  action={() => setIsPresented(true)}
  confirmationDialog={{
    isPresented,
    onChanged: setIsPresented,
    title: "Do you want to delete this image?",
    actions: <Button title={"Delete"} role={"destructive"} action={() => {}} />
  }}
/>
```



---
url: /guide/Views/Modal presentaions/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationLink, NavigationStack, Script, Section, Text, Toggle, useState, VStack } from "scripting"

function SheetExample() {
  const [isPresented, setIsPresented] = useState(false)

  return <Section header={<Text>Showing a sheet</Text>}>
    <Button
      title={"Present"}
      action={() => setIsPresented(true)}
      sheet={{
        isPresented: isPresented,
        onChanged: setIsPresented,
        content: <VStack presentationDragIndicator={"visible"}>
          <Text font={"title"} padding={50}>Sheet content</Text>
          <Button title={"Dismiss"} action={() => setIsPresented(false)} />
        </VStack>
      }}
    />
  </Section>
}

function PopoverExample() {
  const [isPresented, setIsPresented] = useState(false)

  return <Section header={<Text>Showing a popover</Text>}>
    <Button
      title={"Show Popover"}
      action={() => setIsPresented(true)}
      popover={{
        isPresented: isPresented,
        onChanged: setIsPresented,
        presentationCompactAdaptation: "popover",
        content: <Text padding>Popover content</Text>,
        arrowEdge: "top",
      }}
    />
  </Section>
}

function FullScreenCoverExample() {
  const [isPresented, setIsPresented] = useState(false)

  return <Section header={<Text>Showing a full screen cover</Text>}>
    <Button
      title={"Present"}
      action={() => setIsPresented(true)}
      fullScreenCover={{
        isPresented: isPresented,
        onChanged: setIsPresented,
        content: <VStack
          onTapGesture={() => setIsPresented(false)}
          foregroundStyle={"white"}
          frame={{ maxHeight: "infinity", maxWidth: "infinity" }}
          background={"blue"}
          ignoresSafeArea
        >
          <Text>A full-screen modal view.</Text>
          <Text>Tap to dismiss</Text>
        </VStack>
      }}
    />
  </Section>
}

function ConfiguringSheetHeightExample() {
  const [isPresented, setIsPresented] = useState(false)

  return <Section header={<Text>Configuring sheet height</Text>}>
    <Button
      title={"Present"}
      action={() => setIsPresented(true)}
      sheet={{
        isPresented: isPresented,
        onChanged: setIsPresented,
        content: <VStack
          presentationDragIndicator={"visible"}
          presentationDetents={[200, "medium", "large"]}
        >
          <Text font={"title"} padding={50}>Drag the indicator to resize the sheet height.</Text>
          <Button title={"Dismiss"} action={() => setIsPresented(false)} />
        </VStack>
      }}
    />
  </Section>
}

function PresentAlertExample() {
  const [isPresented, setIsPresented] = useState(false)

  return <Section header={<Text>Present an alert view</Text>}>
    <Button
      title={"Present"}
      action={() => setIsPresented(true)}
      alert={{
        isPresented: isPresented,
        onChanged: setIsPresented,
        actions: <Button title={"OK"} action={() => { }} />,
        title: "Alert",
        message: <Text>Everything is OK</Text>
      }}
    />
  </Section>
}

function PresentConfirmationDialogExample() {
  const [isPresented, setIsPresented] = useState(false)

  return <Section header={<Text>Present a confirmation dialog</Text>}>
    <Button
      title={"Present"}
      action={() => setIsPresented(true)}
      confirmationDialog={{
        isPresented,
        onChanged: setIsPresented,
        title: "Do you want to delete this image?",
        actions: <Button
          title={"Delete"}
          role={"destructive"}
          action={() => {
            Dialog.alert({ message: "The image has been deleted." })
          }}
        />
      }}
    />
  </Section>
}

function MultiSheetArrayCase() {
  const [aPresented, setAPresented] = useState(false)
  const [bPresented, setBPresented] = useState(false)

  return <Section
    header={<Text>Case A · sheet[] array, two slots</Text>}
    footer={<Text font="caption">
      Tap each button to present its sheet. The Dismiss button inside
      should close only that sheet.
    </Text>}
  >
    <Button
      title="Present Sheet A"
      action={() => setAPresented(true)}
      sheet={[
        {
          isPresented: aPresented,
          onChanged: setAPresented,
          content: <VStack padding={30}>
            <Text font="title" foregroundStyle={"blue"}>Sheet A</Text>
            <Text>useDismiss should close Sheet A.</Text>
            <DismissButton expected="Sheet A" />
          </VStack>
        },
        {
          isPresented: bPresented,
          onChanged: setBPresented,
          content: <VStack padding={30}>
            <Text font="title" foregroundStyle={"orange"}>Sheet B</Text>
            <Text>useDismiss should close Sheet B.</Text>
            <DismissButton expected="Sheet B" />
          </VStack>
        }
      ]}
    />
    <Button
      title="Present Sheet B"
      action={() => setBPresented(true)}
    />
  </Section>
}

function MixedKindsCase() {
  const [sheetOn, setSheetOn] = useState(false)
  const [popoverOn, setPopoverOn] = useState(false)
  const [coverOn, setCoverOn] = useState(false)

  return <Section
    header={<Text>Case B · sheet + popover + fullScreenCover mixed</Text>}
    footer={<Text font="caption">
      Present each modal in turn. Dismiss inside each should close only
      that layer.
    </Text>}
  >
    <Button
      title="Present Sheet"
      action={() => setSheetOn(true)}
      sheet={{
        isPresented: sheetOn,
        onChanged: setSheetOn,
        content: <VStack padding={30}>
          <Text font="title">Sheet layer</Text>
          <DismissButton expected="Sheet layer" />
        </VStack>
      }}
      popover={{
        isPresented: popoverOn,
        onChanged: setPopoverOn,
        presentationCompactAdaptation: "popover",
        arrowEdge: "top",
        content: <VStack padding={20}>
          <Text>Popover layer</Text>
          <DismissButton expected="Popover layer" />
        </VStack>
      }}
      fullScreenCover={{
        isPresented: coverOn,
        onChanged: setCoverOn,
        content: <VStack
          frame={{ maxWidth: "infinity", maxHeight: "infinity" }}
          background={"black"}
          foregroundStyle={"white"}
          ignoresSafeArea
        >
          <Text font="title">FullScreenCover layer</Text>
          <DismissButton expected="FullScreenCover layer" />
        </VStack>
      }}
    />
    <Button
      title="Present Popover"
      action={() => setPopoverOn(true)}
    />
    <Button
      title="Present FullScreenCover"
      action={() => setCoverOn(true)}
    />
  </Section>
}

function ConditionalModifierShiftCase() {
  const [withPopover, setWithPopover] = useState(false)
  const [sheetOn, setSheetOn] = useState(false)
  const [popoverOn, setPopoverOn] = useState(false)

  return <Section
    header={<Text>Case C · conditional modifier (drift test)</Text>}
    footer={<Text font="caption">
      Toggle "Mount popover" a few times, then present Sheet. The Dismiss
      inside Sheet should always close Sheet — never any other layer.
    </Text>}
  >
    <Toggle
      title="Mount popover"
      value={withPopover}
      onChanged={setWithPopover}
    />
    <Button
      title="Present Sheet"
      action={() => setSheetOn(true)}
      sheet={{
        isPresented: sheetOn,
        onChanged: setSheetOn,
        content: <VStack padding={30}>
          <Text font="title">Sheet (Case C)</Text>
          <Text>Dismiss should close Sheet regardless of popover state.</Text>
          <DismissButton expected="Sheet (Case C)" />
        </VStack>
      }}
      popover={withPopover ? {
        isPresented: popoverOn,
        onChanged: setPopoverOn,
        presentationCompactAdaptation: "popover",
        arrowEdge: "top",
        content: <VStack padding={20}>
          <Text>Popover (Case C)</Text>
          <DismissButton expected="Popover (Case C)" />
        </VStack>
      } : undefined}
    />
    {withPopover && <Button
      title="Present Popover"
      action={() => setPopoverOn(true)}
    />}
  </Section>
}

function NavigationLinkWithSheetCase() {
  const [sheetOn, setSheetOn] = useState(false)

  return <Section
    header={<Text>Case D · NavigationLink + sheet on same component</Text>}
    footer={<Text font="caption">
      Push to Detail then Dismiss — should pop the detail, not close Sheet.
      Present Sheet then Dismiss — should close Sheet, not pop navigation.
    </Text>}
  >
    <NavigationLink
      destination={
        <VStack padding={20} navigationTitle="Detail D">
          <Text font="title">NavigationLink Detail</Text>
          <Text>useDismiss should pop this layer.</Text>
          <DismissButton expected="Detail D (pop)" />
        </VStack>
      }
    >
      <Text>Push to Detail</Text>
    </NavigationLink>
    <Button
      title="Present Sheet"
      action={() => setSheetOn(true)}
      sheet={{
        isPresented: sheetOn,
        onChanged: setSheetOn,
        content: <VStack padding={30}>
          <Text font="title">Sheet (Case D)</Text>
          <DismissButton expected="Sheet (Case D)" />
        </VStack>
      }}
    />
  </Section>
}

function DismissButton({ expected }: { expected: string }) {
  const dismiss = Navigation.useDismiss()
  return <Button
    title={`Dismiss (expected target: ${expected})`}
    action={() => dismiss()}
    padding
  />
}

function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"Modal presentations"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <SheetExample />
      <ConfiguringSheetHeightExample />
      <FullScreenCoverExample />
      <PopoverExample />
      <PresentAlertExample />
      <PresentConfirmationDialogExample />

      <MultiSheetArrayCase />
      <MixedKindsCase />
      <ConditionalModifierShiftCase />
      <NavigationLinkWithSheetCase />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/NamespaceReader.md
---

# NamespaceReader

`NamespaceReader` is used to **create and manage a geometry animation namespace (Namespace)**.
This namespace is the **foundational requirement** for enabling:

- `matchedGeometryEffect` (component-level geometry animation)
- `matchedTransitionSource` (page-level navigation transition)
- `navigationTransition` (such as zoom transitions)

You can think of `NamespaceReader` as:

> A “geometry animation coordinate provider” that defines which views belong to the **same animation scope**.

***

## 1. Role of NamespaceReader

`NamespaceReader` is **not a visual UI component**. It is a **namespace generator** whose responsibilities are:

- Creating a brand-new `NamespaceID`
- Exposing that namespace via a render function
- Defining the **boundary of a geometry animation group**

In Scripting, this corresponds conceptually to SwiftUI’s:

- `@Namespace`
- `Namespace.ID`

***

## 2. Basic Usage Pattern

### 2.1 Minimal Structure

```tsx
<NamespaceReader>
  {namespace => (
    // All views inside this scope
    // can use this namespace for matched geometry animations
  )}
</NamespaceReader>
```

Explanation:

- `NamespaceReader` accepts a **function as its child**
- This function receives a single argument: `namespace`
- The returned `namespace` is the unique animation scope for all child views

***

## 3. The True Purpose of a Namespace

### 3.1 What a Namespace Really Does

The real purpose of a `namespace` is to:

- Declare a group of views as **eligible for shared geometry animation**
- Explicitly define **which views are allowed to match each other**

Without using the same `namespace`:

- Even if two views have the **same `id`**
- **No geometry animation will ever happen**

***

### 3.2 Isolation Provided by Namespaces

| Condition                              | Geometry Matching Occurs |
| -------------------------------------- | ------------------------ |
| Same `id` + Same `namespace`           | Yes                      |
| Same `id` + Different `namespace`      | No                       |
| Different `id` + Same `namespace`      | No                       |
| Different `id` + Different `namespace` | No                       |

Conclusion:

> **Both `id` and `namespace` must match exactly for geometry animation to be established.**

***

## 4. Relationship with the Geometry Animation System

### 4.1 Relationship with matchedGeometryEffect

- `matchedGeometryEffect` relies on `namespace` to establish cross-view geometry mapping
- `NamespaceReader` is a **mandatory prerequisite** for `matchedGeometryEffect`
- Without `NamespaceReader`:

  - `matchedGeometryEffect` cannot function

***

### 4.2 Relationship with matchedTransitionSource

- Page-level navigation transitions also depend on `namespace` to pair:

  - The source view
  - The destination page
- `NamespaceReader` is used to:

  - Create the namespace on the source page
  - Pass the same namespace into the destination page

***

## 5. Basic NamespaceReader Example (Component-Level)

```tsx
const expanded = useObservable(false)

<NamespaceReader>
  {namespace => (
    <VStack>
      {!expanded.value && (
        <Circle
          matchedGeometryEffect={{
            id: "shape",
            namespace
          }}
          onTapGesture={() => {
            expanded.setValue(true)
          }}
        />
      )}

      {expanded.value && (
        <Circle
          frame={{ width: 200, height: 200 }}
          matchedGeometryEffect={{
            id: "shape",
            namespace,
            isSource: false
          }}
        />
      )}
    </VStack>
  )}
</NamespaceReader>
```

In this example:

- `NamespaceReader` provides the animation coordinate system
- Both `Circle` views share:

  - The same `id`
  - The same `namespace`
- Therefore, they are geometrically linked

***

## 6. Typical NamespaceReader Structure in Navigation Transitions

```tsx
<NamespaceReader>
  {namespace => (
    <NavigationLink
      destination={
        <DetailPage
          navigationTransition={{
            type: "zoom",
            namespace,
            sourceID: "cover"
          }}
        />
      }
    >
      <Image
        source="cover"
        matchedTransitionSource={{
          id: "cover",
          namespace
        }}
      />
    </NavigationLink>
  )}
</NamespaceReader>
```

This structure demonstrates:

- `namespace` is created by `NamespaceReader`
- The same `namespace` is used by:

  - The source view
  - The destination page
- This enables full page-level shared-geometry transitions

***

## 7. Namespace Lifecycle and Scope

### 7.1 Lifecycle

- Every time `NamespaceReader` is created:

  - A **new namespace instance** is generated
- The namespace:

  - Exists only within the current component tree
  - Is destroyed automatically when the component is unmounted

***

### 7.2 Scope

- A namespace is valid **only inside the render function of its `NamespaceReader`**
- It is **not shared automatically across component hierarchies**
- If cross-component sharing is required:

  - The namespace must be passed explicitly via props

***

## 8. Common Errors and Debugging Tips

### 8.1 Geometry Animations Do Not Trigger

Check the following:

- Is `NamespaceReader` actually present?
- Is the `namespace` correctly received and passed?
- Are both source and target using **the exact same namespace instance**?

***

### 8.2 Animations Are Unstable or Occasionally Fail

Common cause:

- `NamespaceReader` is being conditionally rendered and destroyed repeatedly
- Each destruction/recreation produces a **new namespace**
- The old and new views are no longer in the same animation coordinate system

Recommendation:

- Place `NamespaceReader` in a **stable parent node**
- Avoid wrapping it in `if` or ternary conditions

***

### 8.3 Nested NamespaceReader Causing Unexpected Behavior

Symptoms:

- `id` appears to be correct
- But geometry matching still fails

Likely cause:

- Source and target views are actually using **different NamespaceReader instances**
- Even though their `id` values are the same

***

## 9. Design Guidelines

1. Use **one NamespaceReader per independent animation region**
2. Do not create a separate NamespaceReader for every individual view
3. For page-level transitions:

   - Place `NamespaceReader` near the page root
4. For component-level animations:

   - Place `NamespaceReader` around the logical animation group
5. Inside the same namespace:

   - Do not reuse the same `id` for unrelated views

***

## 10. Recommended Use Cases

Appropriate scenarios for using `NamespaceReader`:

- Card → Detail shared-element transitions
- Tab indicator geometry animation
- Image zoom previews
- List item → Detail content transitions
- Spatially continuous multi-view animations

Scenarios where `NamespaceReader` is **not required**:

- Simple opacity or scale animations
- Single-view internal transitions
- Animations that do not involve cross-view geometry matching



---
url: /guide/Views/Navigation/NavigationSplitView (for iPad)/Collapsed split views.md
---

# Collapsed split views

```tsx
import { Navigation, NavigationSplitView, NavigationSplitViewColumn, Script, Text, useState, VStack } from "scripting"

function Example() {
  const [preferredColumn, setPreferredColumn] = useState<NavigationSplitViewColumn>("detail")

  return <NavigationSplitView
    preferredCompactColumn={{
      value: preferredColumn,
      onChanged: (value) => {
        console.log("preferredCompactColumn changed to", value)
        setPreferredColumn(value)
      }
    }}
    sidebar={
      <VStack
        navigationContainerBackground={"yellow"}
        frame={{
          maxWidth: "infinity",
          maxHeight: "infinity",
        }}
      >
        <Text>Yellow</Text>
      </VStack>
    }
  >
    <VStack
      navigationContainerBackground={"blue"}
      frame={{
        maxWidth: "infinity",
        maxHeight: "infinity",
      }}
    >
      <Text>Blue</Text>
    </VStack>
  </NavigationSplitView>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Navigation/NavigationSplitView (for iPad)/Control column visibility.md
---

# Control column visibility

```tsx
import { HStack, Label, List, Navigation, NavigationSplitView, NavigationSplitViewVisibility, Script, Text, useState, VStack } from "scripting"

type Department = {
  name: string
  staff: Person[]
}

type Company = {
  name: string
  departments: Department[]
}

type Person = {
  name: string
  phoneNumber: string
}

const companyA: Company = {
  name: "Company A",
  departments: [
    {
      name: "Sales",
      staff: [
        {
          name: "Juan Chavez",
          phoneNumber: "(408) 555-4301",
        },
        {
          name: "Mei Chen",
          phoneNumber: "(919) 555-2481",
        }
      ]
    },
    {
      name: "Engineering",
      staff: [
        {
          name: "Bill James",
          phoneNumber: "(408) 555-4450"
        },
        {
          name: "Anne Johnson",
          phoneNumber: "(417) 555-9311"
        }
      ]
    }
  ]
}

const companies: Company[] = [
  {
    name: "Company A",
    departments: [
      {
        name: "Sales",
        staff: [
          {
            name: "Juan Chavez",
            phoneNumber: "(408) 555-4301",
          },
          {
            name: "Mei Chen",
            phoneNumber: "(919) 555-2481",
          }
        ]
      },
      {
        name: "Engineering",
        staff: [
          {
            name: "Bill James",
            phoneNumber: "(408) 555-4450"
          },
          {
            name: "Anne Johnson",
            phoneNumber: "(417) 555-9311"
          }
        ]
      }
    ]
  },
  {
    name: "Company B",
    departments: [
      {
        name: "Human resources",
        staff: [
          {
            name: "Lily",
            phoneNumber: "(111) 555-5552"
          },
          {
            name: "Ross",
            phoneNumber: "(222) 666-8888"
          }
        ]
      },
      {
        name: "Sales",
        staff: [
          {
            name: "John",
            phoneNumber: "(1) 888-4444"
          }
        ]
      }
    ]
  }
]

function PersonRowView({
  person
}: {
  person: Person
}) {
  return <VStack
    alignment={"leading"}
    spacing={3}
  >
    <Text
      foregroundStyle={"label"}
      font={"headline"}
    >{person.name}</Text>
    <HStack
      spacing={3}
      foregroundStyle={"secondaryLabel"}
      font={"subheadline"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

function PersonDetailView({
  person
}: {
  person: Person
}) {

  return <VStack>
    <Text
      font={"title"}
      foregroundStyle={"label"}
    >{person.name}</Text>
    <HStack
      foregroundStyle={"secondaryLabel"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

 function Example() {
  const [columnVisibility, setColumnVisibility] = useState<NavigationSplitViewVisibility>("detailOnly")
  const [selectedPerson, setSelectedPerson] = useState<Person>()

  return <NavigationSplitView
    columnVisibility={{
      value: columnVisibility,
      onChanged: (value) => {
        console.log("columnVisibility changed to", value)
        setColumnVisibility(value)
      },
    }}
    sidebar={
      <List>
        {companyA.departments[0].staff.map(person =>
          <PersonRowView
            person={person}
            contentShape={"rect"}
            onTapGesture={() => {
              setSelectedPerson(person)
            }}
          />
        )}
      </List>
    }
  >
    {selectedPerson != null
      ? <PersonDetailView
        person={selectedPerson}
      />
      : <Text>Please select a person.</Text>
    }
  </NavigationSplitView>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Navigation/NavigationSplitView (for iPad)/Three-column.md
---

# Three-column

```tsx
import { HStack, Label, List, Navigation, NavigationSplitView, Script, Section, Text, useState, VStack } from "scripting"

type Department = {
  name: string
  staff: Person[]
}

type Company = {
  name: string
  departments: Department[]
}

type Person = {
  name: string
  phoneNumber: string
}

const companyA: Company = {
  name: "Company A",
  departments: [
    {
      name: "Sales",
      staff: [
        {
          name: "Juan Chavez",
          phoneNumber: "(408) 555-4301",
        },
        {
          name: "Mei Chen",
          phoneNumber: "(919) 555-2481",
        }
      ]
    },
    {
      name: "Engineering",
      staff: [
        {
          name: "Bill James",
          phoneNumber: "(408) 555-4450"
        },
        {
          name: "Anne Johnson",
          phoneNumber: "(417) 555-9311"
        }
      ]
    }
  ]
}

const companies: Company[] = [
  {
    name: "Company A",
    departments: [
      {
        name: "Sales",
        staff: [
          {
            name: "Juan Chavez",
            phoneNumber: "(408) 555-4301",
          },
          {
            name: "Mei Chen",
            phoneNumber: "(919) 555-2481",
          }
        ]
      },
      {
        name: "Engineering",
        staff: [
          {
            name: "Bill James",
            phoneNumber: "(408) 555-4450"
          },
          {
            name: "Anne Johnson",
            phoneNumber: "(417) 555-9311"
          }
        ]
      }
    ]
  },
  {
    name: "Company B",
    departments: [
      {
        name: "Human resources",
        staff: [
          {
            name: "Lily",
            phoneNumber: "(111) 555-5552"
          },
          {
            name: "Ross",
            phoneNumber: "(222) 666-8888"
          }
        ]
      },
      {
        name: "Sales",
        staff: [
          {
            name: "John",
            phoneNumber: "(1) 888-4444"
          }
        ]
      }
    ]
  }
]

function PersonRowView({
  person
}: {
  person: Person
}) {
  return <VStack
    alignment={"leading"}
    spacing={3}
  >
    <Text
      foregroundStyle={"label"}
      font={"headline"}
    >{person.name}</Text>
    <HStack
      spacing={3}
      foregroundStyle={"secondaryLabel"}
      font={"subheadline"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

function PersonDetailView({
  person
}: {
  person: Person
}) {

  return <VStack>
    <Text
      font={"title"}
      foregroundStyle={"label"}
    >{person.name}</Text>
    <HStack
      foregroundStyle={"secondaryLabel"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

function Example() {
  const [selectedCompany, setSelectedCompany] = useState<Company>()
  const [selectedPerson, setSelectedPerson] = useState<Person>()

  return <NavigationSplitView
    sidebar={
      <List>
        {companies.map(company =>
          <Text
            onTapGesture={() => {
              setSelectedCompany(company)
            }}
          >{company.name}</Text>
        )}
      </List>
    }
    content={
      selectedCompany != null
        ? <List>
          {selectedCompany.departments.map(department =>
            <Section
              header={<Text>{department.name}</Text>}
            >
              {department.staff.map(person =>
                <PersonRowView
                  person={person}
                  contentShape={"rect"}
                  onTapGesture={() => {
                    setSelectedPerson(person)
                  }}
                />
              )}
            </Section>
          )}
        </List>
        : <Text>Select a company</Text>
    }
  >
    {selectedPerson != null
      ? <PersonDetailView
        person={selectedPerson}
      /> :
      <Text>Select a person</Text>}
  </NavigationSplitView>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Navigation/NavigationSplitView (for iPad)/Two-column.md
---

# Two-column

```tsx
import { HStack, Label, List, Navigation, NavigationSplitView, Script, Text, useState, VStack } from "scripting"

type Department = {
  name: string
  staff: Person[]
}

type Company = {
  name: string
  departments: Department[]
}

type Person = {
  name: string
  phoneNumber: string
}

const companyA: Company = {
  name: "Company A",
  departments: [
    {
      name: "Sales",
      staff: [
        {
          name: "Juan Chavez",
          phoneNumber: "(408) 555-4301",
        },
        {
          name: "Mei Chen",
          phoneNumber: "(919) 555-2481",
        }
      ]
    },
    {
      name: "Engineering",
      staff: [
        {
          name: "Bill James",
          phoneNumber: "(408) 555-4450"
        },
        {
          name: "Anne Johnson",
          phoneNumber: "(417) 555-9311"
        }
      ]
    }
  ]
}

function PersonRowView({
  person
}: {
  person: Person
}) {
  return <VStack
    alignment={"leading"}
    spacing={3}
  >
    <Text
      foregroundStyle={"label"}
      font={"headline"}
    >{person.name}</Text>
    <HStack
      spacing={3}
      foregroundStyle={"secondaryLabel"}
      font={"subheadline"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

function PersonDetailView({
  person
}: {
  person: Person
}) {

  return <VStack>
    <Text
      font={"title"}
      foregroundStyle={"label"}
    >{person.name}</Text>
    <HStack
      foregroundStyle={"secondaryLabel"}
    >
      <Label
        title={person.phoneNumber}
        systemImage={"phone"}
      />
    </HStack>
  </VStack>
}

function Example() {
  const [selectedPerson, setSelectedPerson] = useState<Person>()

  return <NavigationSplitView
    sidebar={
      <List>
        {companyA.departments[0].staff.map(person =>
          <PersonRowView
            person={person}
            contentShape={"rect"}
            onTapGesture={() => {
              setSelectedPerson(person)
            }}
          />
        )}
      </List>
    }
  >
    {selectedPerson != null
      ? <PersonDetailView
        person={selectedPerson}
      />
      : <Text>Please select a person.</Text>
    }
  </NavigationSplitView>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Navigation/NavigationStack/NavigationStack with path.md
---

# NavigationStack with path

`NavigationStack.path` provides **observable, programmatic control over the navigation stack**. It allows direct manipulation of the navigation history using a bound observable array.

It enables:

- Programmatic navigation
- Multi-level stack control
- Returning to the root view
- Dynamic page resolution via `NavigationDestination`

***

## 1. API Definition

```ts
type NavigationStackProps = {
  path?: Observable<string[]>
  ...
}

declare const NavigationStack: FunctionComponent<NavigationStackProps>
```

***

## 2. Type and Semantics of path

```ts
path?: Observable<string[]>
```

`path` is an observable string array representing the **current navigation stack**.

Rules:

- Each `string` represents a unique page identifier
- The array order defines the navigation order
- The last element is the currently visible page
- An empty array represents the root view

Examples:

```ts
[]
```

Represents the root view

```ts
["a"]
```

Represents navigation to page `a`

```ts
["a", "b"]
```

Represents navigation to page `a`, then to page `b`, with `b` as the active page

***

## 3. Basic Usage Example

```tsx
function Page() {
  const path = useObservable<string[]>(["a"])

  return <NavigationStack
    path={path}
  >
    <VStack
      navigationTitle="Navigation Demo"
      navigationDestination={
        <NavigationDestination>
          {(page) =>
            <VStack>
              <Text>
                Current page:
                {page}
              </Text>
              {path.value.length > 1
                && <Button
                  title="Go to Root"
                  action={() => {
                    path.setValue([])
                  }}
                />}
            </VStack>
          }
        </NavigationDestination>
      }
    >
      <Button
        title="Show page a"
        action={() => {
          path.setValue(["a"])
        }}
      />
      <Button
        title="Show page b"
        action={() => {
          path.setValue(["b"])
        }}
      />
      <Button
        title="Show page a then b"
        action={() => {
          path.setValue(["a", "b"])
        }}
      />
    </VStack>
  </NavigationStack>
}
```

***

## 4. How path Controls Navigation

### 4.1 path as the Single Source of Navigation State

When `path` is bound:

- The full navigation stack is determined exclusively by `path.value`
- UI navigation state stays fully synchronized with `path`
- Implicit push/pop navigation is replaced by explicit state control

***

### 4.2 Pushing Pages

```ts
path.setValue(["a"])
```

System behavior:

- Pushes page `a` onto the stack
- Displays page `a`

```ts
path.setValue(["a", "b"])
```

System behavior:

- Pushes page `a`
- Then pushes page `b`
- Displays page `b`

***

### 4.3 Popping Pages and Returning to Root

```ts
path.setValue([])
```

System behavior:

- Clears the entire navigation stack
- Immediately returns to the root view

***

## 5. Relationship Between path and NavigationDestination

`NavigationDestination` dynamically renders destination views based on the **current value of `path`**:

```tsx
<NavigationDestination>
  {(page) => ...}
</NavigationDestination>
```

Rules:

- `page` is always equal to the **last element of `path.value`**
- When `path` changes:

  - `page` updates automatically
  - The destination view re-renders automatically

Mapping result examples:

```ts
["a"]        -> page === "a"
["a", "b"]   -> page === "b"
```

***

## 6. Controlling Navigation with Buttons

Navigate to page `a`:

```ts
path.setValue(["a"])
```

Navigate to page `b`:

```ts
path.setValue(["b"])
```

Navigate through multiple pages:

```ts
path.setValue(["a", "b"])
```

Return to the root view:

```ts
path.setValue([])
```

***

## 7. Synchronization with System Back Gestures

When the user navigates back using:

- The system back gesture
- The navigation bar back button

Then:

- `path.value` is automatically updated
- The navigation stack and UI remain fully synchronized
- No manual back handling is required

***

## 8. Typical Use Cases

`NavigationStack.path` is suitable for:

- Deep linking
- Multi-step navigation flows
- Programmatic routing
- Script-driven navigation
- Navigation state restoration
- Wizard-style navigation
- Cross-page navigation control

***

## 9. Common Errors

### 9.1 Incorrect Initialization

Incorrect:

```ts
const path = useObservable<string[]>(null)
```

Correct:

```ts
const path = useObservable<string[]>([])
```

***

### 9.2 Invalid Path Element Types

Incorrect:

```ts
path.setValue([1, 2])
```

Correct:

```ts
path.setValue(["1", "2"])
```

Currently, only `string[]` is supported as the navigation path type.

***

## 10. Difference Between Using path and Default NavigationStack

| Feature                   | Without path  | With path        |
| ------------------------- | ------------- | ---------------- |
| Manual push/pop           | Supported     | Not recommended  |
| Programmatic navigation   | Not supported | Fully supported  |
| Multi-level routing       | Limited       | Fully supported  |
| State restoration         | Difficult     | Simple           |
| Centralized routing state | Not available | Fully controlled |



---
url: /guide/Views/Navigation/NavigationStack/Use with NavigationLink.md
---

# Use with NavigationLink

```tsx
import { Color, List, Navigation, NavigationLink, NavigationStack, Script, Text, VStack } from "scripting"

function NavigationDetailView({
  color
}: {
  color: Color
}) {

  return <VStack
    navigationContainerBackground={color}
    frame={{
      maxWidth: "infinity",
      maxHeight: "infinity"
    }}
  >
    <Text>{color}</Text>
  </VStack>
}


function Example() {
  const colors: Color[] = [
    "red", "green", "blue", "orange", "purple"
  ]

  return <NavigationStack>
    <List
      navigationTitle={"NavigationStack with links"}
      navigationBarTitleDisplayMode={"inline"}
    >
      {colors.map(color =>
        <NavigationLink
          destination={
            <NavigationDetailView
              color={color}
            />
          }
        >
          <Text>Navigation to {color} view</Text>
        </NavigationLink>
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Navigation/NavigationStack/Use with navigationDestination.md
---

# Use with navigationDestination

```tsx
import { useState, Color, NavigationStack, List, Text, HStack, Spacer, Image, VStack, Navigation, Script } from "scripting"

function NavigationDetailView({
  color
}: {
  color: Color
}) {

  return <VStack
    navigationContainerBackground={color}
    frame={{
      maxWidth: "infinity",
      maxHeight: "infinity"
    }}
  >
    <Text>{color}</Text>
  </VStack>
}

function Example() {
  const colors: Color[] = [
    "red", "green", "blue", "orange", "purple"
  ]
  const [selectedColor, setSelectedColor] = useState<Color | null>()

  return <NavigationStack>
    <List
      navigationTitle={"With Navigation Destination"}
      navigationDestination={{
        isPresented: selectedColor != null,
        onChanged: value => {
          if (!value) {
            setSelectedColor(null)
          }
        },
        content: selectedColor != null
          ? <NavigationDetailView
            color={selectedColor}
          />
          : <Text>Select a color</Text>
      }}
    >
      {colors.map(color =>
        <HStack
          contentShape={"rect"}
          onTapGesture={() => {
            setSelectedColor(color)
          }}
        >
          <Text>Navigation to {color} view</Text>
          <Spacer />
          <Image
            systemName={"chevron.right"}
            foregroundStyle={"secondaryLabel"}
          />
        </HStack>
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Navigation/TabView/TabView with badge.md
---

# TabView with badge

```tsx
import { Label, Navigation, Script, TabView, Text, useState } from "scripting"

function Example() {
  const [tabIndex, setTabIndex] = useState(0)

  return <TabView
    tabIndex={tabIndex}
    onTabIndexChanged={setTabIndex}
  >
    <ReceivedView
      tag={0}
      tabItem={
        <Label
          title={"Received"}
          systemImage={"tray.and.arrow.down.fill"}
        />
      }
      badge={2}
    />
    <SendView
      tag={1}
      tabItem={
        <Label
          title={"Send"}
          systemImage={"tray.and.arrow.up.fill"}
        />
      }
    />
    <AccountView
      tag={2}
      badge={"!"}
      tabItem={
        <Label
          title={"Account"}
          systemImage={"person.crop.circle.fill"}
        />
      }
    />
  </TabView>
}

function ReceivedView() {
  return <Text>Received view</Text>
}

function SendView() {
  return <Text>Send view</Text>
}

function AccountView() {
  return <Text>Account view</Text>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Navigation/TabView/TabView with multiple scrolling pages.md
---

# TabView with multiple scrolling pages

```tsx
import { Color, Navigation, NavigationStack, Script, TabView, Text, VStack } from "scripting"

function Example() {
  const colors: Color[] = [
    "red",
    "green",
    "blue",
    "purple"
  ]

  return <NavigationStack>
    <VStack
      navigationTitle={"TabView"}
    >
      <TabView
        tabViewStyle={"page"}
        frame={{
          height: 200
        }}
      >
        {colors.map(color =>
          <ColorView
            color={color}
          />
        )}
      </TabView>
    </VStack>
  </NavigationStack>
}

function ColorView({
  color,
}: {
  color: Color
}) {
  return <VStack
    frame={{
      maxWidth: "infinity",
      maxHeight: "infinity"
    }}
    background={color}
  >
    <Text>{color}</Text>
  </VStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Navigation/TabView/TabView.md
---

# TabView

Scripting provides a modern Tab system aligned with iOS 18+:

- `TabView` — container that manages multiple tabs and switching between them
- `Tab` — a single tab and its associated content
- `TabSection` — a way to group tabs into sections, each with its own configuration and header

Combined with TabView-level options and `TabViewCustomization`, this enables rich tab layouts, including sidebar representations, customization, and persistence.

This document focuses on:

- How to structure tab content using `TabView`, `Tab`, and `TabSection`
- How to configure tab bar and sidebar behaviors
- How to use `TabViewCustomization` to persist and restore user customizations

***

## 1. Basic Usage: TabView + Tab

In the simplest case, `TabView` hosts multiple `Tab` elements. Each `Tab` defines:

- A title and system image for the tab item
- A value used for selection
- An optional role (for example `search`)
- The actual view content

```tsx
import { TabView, Tab, useObservable } from 'scripting'

function RootView() {
  const selection = useObservable<number>(0)

  return (
    <TabView selection={selection}>
      <Tab
        title="Home"
        systemImage="house.fill"
        value={0}
      >
        <HomeView />
      </Tab>

      <Tab
        title="Search"
        systemImage="magnifyingglass"
        value={1}
        role="search"
      >
        <SearchView />
      </Tab>

      <Tab
        title="Settings"
        systemImage="gearshape.fill"
        value={2}
      >
        <SettingsView />
      </Tab>
    </TabView>
  )
}
```

Key points:

- `TabView selection={selection}` binds the **current tab** to an observable value.
- Each `Tab`’s `value` must match the observable’s type (`number` or `string`).
- Tabs with `role="search"` integrate with `tabViewSearchActivation` behavior (see below).

***

## 2. Grouping Tabs with TabSection

When you have many tabs, or when you want a sidebar-like structure, use `TabSection` to group related tabs.

The structure becomes:

```text
TabView
 ├─ TabSection
 │   ├─ Tab
 │   ├─ Tab
 │   └─ ...
 ├─ TabSection
 │   ├─ Tab
 │   └─ ...
```

### 2.1 Using `title` as a section header

```tsx
function MailRootView() {
  const selection = useObservable<string>('inbox')

  return (
    <TabView selection={selection}>
      <TabSection title="Mailboxes">
        <Tab
          title="Inbox"
          systemImage="tray.full.fill"
          value="inbox"
        >
          <InboxView />
        </Tab>

        <Tab
          title="Sent"
          systemImage="paperplane.fill"
          value="sent"
        >
          <SentView />
        </Tab>
      </TabSection>

      <TabSection title="Labels">
        <Tab
          title="Important"
          systemImage="star.fill"
          value="important"
        >
          <ImportantView />
        </Tab>
      </TabSection>
    </TabView>
  )
}
```

### 2.2 Using `header` for a custom section header

If you need a richer header (icon + text + description, etc.), use `header` instead of `title`:

```tsx
<TabSection
  header={
    <HStack spacing={8}>
      <Image systemName="folder.fill" />
      <VStack alignment="leading">
        <Text fontWeight="bold">Projects</Text>
        <Text fontSize={12} foregroundColor="secondary">
          Recently opened projects
        </Text>
      </VStack>
    </HStack>
  }
>
  <Tab title="Project A" systemImage="doc.fill" value="projectA">
    <ProjectAView />
  </Tab>

  <Tab title="Project B" systemImage="doc.fill" value="projectB">
    <ProjectBView />
  </Tab>
</TabSection>
```

`title` and `header` are mutually exclusive: use one or the other per section.

***

## 3. Section-Level Configuration: Layout, Actions, Drag & Drop

`TabSection` can control how a section is presented and how it behaves.

### 3.1 `tabPlacement`

Controls where and how the section’s tabs appear. Common values:

- `automatic` — let the system decide based on environment.
- `pinned` — pins tabs so they remain visible in the bar.
- `sidebarOnly` — show tabs only in the sidebar representation.

Example: a section that only appears in the sidebar:

```tsx
<TabSection
  title="Tags"
  tabPlacement="sidebarOnly"
>
  <Tab title="Important" systemImage="star.fill" value="important">
    <ImportantView />
  </Tab>
</TabSection>
```

### 3.2 `sectionActions`

Provides extra actions associated with a section, such as “Add” or “More”.

```tsx
<TabSection
  title="Lists"
  sectionActions={
    <Button
      title="Add"
      systemImage="plus"
      action={addNewList}
    />
  }
>
  <Tab title="Today" systemImage="sun.max.fill" value="today">
    <TodayView />
  </Tab>
</TabSection>
```

### 3.3 Visibility and customization behavior

At the section level you can configure:

- Default visibility in different placements (tab bar, sidebar)
- Customization behavior (whether users can reorder or adjust the section)

Typical use-case: a section that users can reorder in a Tab layout editor:

```tsx
<TabSection
  title="Files"
  customizationID="files-section"
  customizationBehavior="reorderable"
>
  <Tab title="Recent" systemImage="clock.fill" value="recent">
    <RecentFilesView />
  </Tab>
</TabSection>
```

### 3.4 Drag & drop integration

Both `TabSection` and `Tab` can participate in drag & drop via:

- `draggable` — logical drag identifier
- `dropDestination` — handler for dropped items

Example:

```tsx
<TabSection
  title="Files"
  draggable="files-section"
  dropDestination={items => handleDroppedItems(items)}
>
  <Tab title="Recent" systemImage="clock.fill" value="recent">
    <RecentFilesView />
  </Tab>
</TabSection>
```

***

## 4. TabView-Level Configuration

On the TabView (or the view owning the TabView) you can configure global behavior such as:

- Tab bar minimization
- Bottom accessories
- Search activation behavior
- Sidebar header/footer/bottom bar
- Customization state (`tabViewCustomization`)

### 4.1 `tabBarMinimizeBehavior` (iOS 26.0+)

Controls how the tab bar minimizes in response to scrolling:

- `automatic`
- `never`
- `onScrollDown`
- `onScrollUp`

```tsx
<TabView
  selection={selection}
  tabBarMinimizeBehavior="onScrollDown"
>
  {/* sections + tabs */}
</TabView>
```

### 4.2 `tabViewBottomAccessory` (iOS 26.0+)

Places a view at the bottom of the TabView—below the tab bar or tab area.

```tsx
<TabView
  selection={selection}
  tabViewBottomAccessory={
    <HStack spacing={8}>
      <Text fontSize={12}>Swipe left or right to switch tabs</Text>
      <Spacer />
      <Button title="Got it" action={dismissHint} />
    </HStack>
  }
>
  {/* sections + tabs */}
</TabView>
```

### 4.3 `tabViewSearchActivation` (iOS 26.0+)

Configures how search is activated for tabs with `role="search"`:

- `automatic`
- `searchTabSelection` — activate search when the search tab is selected

```tsx
<TabView
  selection={selection}
  tabViewSearchActivation="searchTabSelection"
>
  <Tab title="Home" systemImage="house.fill" value="home">
    <HomeView />
  </Tab>

  <Tab
    title="Search"
    systemImage="magnifyingglass"
    value="search"
    role="search"
  >
    <SearchView />
  </Tab>
</TabView>
```

### 4.4 Sidebar-specific views (iOS 18.0+)

For sidebar-style TabView, you can add:

- `tabViewSidebarHeader` — top area (user info, app logo, etc.)
- `tabViewSidebarFooter` — bottom area (settings, logout)
- `tabViewSidebarBottomBar` — bar between main content and bottom edge

```tsx
<TabView
  selection={selection}
  tabViewSidebarHeader={
    <VStack alignment="leading" spacing={4}>
      <Image systemName="person.circle.fill" fontSize={32} />
      <Text fontWeight="bold">User Name</Text>
      <Text fontSize={12} foregroundColor="secondary">
        Welcome back
      </Text>
    </VStack>
  }
  tabViewSidebarFooter={
    <Button title="Settings" systemImage="gearshape" action={openSettings} />
  }
  tabViewSidebarBottomBar={
    <Button title="Upgrade to Pro" systemImage="star.fill" action={upgrade} />
  }
>
  {/* sections + tabs */}
</TabView>
```

***

## 5. TabViewCustomization: Persisting Layout and Visibility

`TabViewCustomization` is the core object that represents the customization state of a TabView. It can:

- Track section order
- Track tab order within each section
- Track tab visibility (tab bar vs sidebar)
- Reset section order or visibility
- Be serialized to / from `Data` for persistence

The typical pattern is:

1. Initialize `TabViewCustomization` from storage (if present), otherwise create a new instance.
2. Observe changes to it and save serialized data back to storage.
3. Use it to query and modify section and tab customizations.
4. Pass it into the TabView via `tabViewCustomization`.

### 5.1 Initializing and persisting TabViewCustomization

Below is the **correct example** using `useObservable` and `Storage`:

```tsx
const customization = useObservable<TabViewCustomization>(() => {
  const data = Storage.get('tab_customization')
  if (data) {
    return TabViewCustomization.fromData(data) ?? new TabViewCustomization()
  }
  return new TabViewCustomization()
})

useEffect(() => {
  const listener = (newValue: TabViewCustomization) => {
    const data = newValue.toData()
    if (data) {
      Storage.set('tab_customization', data)
    }
  }
  customization.subscribe(listener)
  return () => {
    customization.unsubscribe(listener)
  }
}, [])
```

Explanation:

- The initializer:

  - Reads raw `Data` from `Storage` using the key `tab_customization`.
  - Uses `TabViewCustomization.fromData(data)` to recreate a customization object.
  - Falls back to `new TabViewCustomization()` if the data is invalid or missing.
- The `useEffect`:

  - Subscribes to changes on the observable.
  - Every time the `TabViewCustomization` changes, `toData()` is called and persisted.
  - Cleans up the subscription on unmount.

This ensures the layout is restored on launch and any user changes are saved automatically.

### 5.2 Using TabViewCustomization with TabView

You typically pass the observable itself into the TabView:

```tsx
<TabView
  selection={selection}
  tabViewCustomization={customization}
>
  {/* TabSection + Tab structure */}
</TabView>
```

Internally, the Tab system updates the `TabViewCustomization` object as the user edits the layout, reorders sections, hides tabs, and so on. The observable subscription persists these updates.

### 5.3 Working with sections: getSection and section order

You can query a section by its `customizationID`:

```tsx
const filesSection = customization.value.getSection('files-section')
```

A section customization can:

- Expose `tabOrder`: the array of tab IDs in this section (or `null` if not customized).
- Provide `resetTabOrder()`: to restore the original system-defined order of tabs in this section.

Example:

```tsx
function resetFilesSectionOrder() {
  const section = customization.value.getSection('files-section')
  section?.resetTabOrder()
}
```

### 5.4 Working with tabs: getTab and visibility

You can query a tab by its `customizationID`:

```tsx
const importantTab = customization.value.getTab('important-tab')
```

A tab customization exposes:

- `tabBarVisibility` — read-only current visibility in the tab bar.
- `sidebarVisibility` — read/write visibility in the sidebar representation.

Example: hiding a tab from the sidebar only:

```tsx
const importantTab = customization.value.getTab('important-tab')
if (importantTab) {
  importantTab.sidebarVisibility = 'hidden'
}
```

This allows you to:

- Implement “show/hide in sidebar” toggles.
- Sync visibility with user preferences or other settings.

### 5.5 Global resets: section order and visibility

Two convenience methods reset parts of the customization:

```tsx
customization.value.resetSectionOrder()
customization.value.resetVisibility()
```

Typical usage: a “Reset layout” button.

```tsx
<Button
  title="Restore Default Layout"
  action={() => {
    customization.value.resetSectionOrder()
    customization.value.resetVisibility()
  }}
/>
```

This restores both:

- Section ordering
- Tab visibility (in tab bar and sidebar)

to their original default state.

***

## 6. Relationship with `tabItem`-based API

Earlier examples in the project may use a `tabItem` view modifier to configure tab labels. That approach is documented elsewhere and is suitable for simple Tab views.

However, for:

- Grouped tabs (`TabSection`)
- Sidebar representations
- Tab reordering and visibility customization (`TabViewCustomization`)
- Per-section actions and layouts

you should use the `TabView + Tab + TabSection + TabViewCustomization` structure described here.

It provides a clearer model, matches modern iOS Tab APIs, and is designed to work seamlessly with customization and persistence.



---
url: /guide/Views/Present views/Dismissing a presented view/index.md
---

# Dismissing a presented view

This example demonstrates how to **programmatically dismiss a presented view** using the `Navigation.useDismiss` hook. It is useful when you want to close a custom view in response to user interaction, such as tapping a button or a text label.

***

## Purpose

You will learn how to:

- Access the dismiss function via `Navigation.useDismiss`
- Call the dismiss function to close the currently presented view
- Safely exit the script using `Script.exit` to avoid memory leaks

***

## Example Code

```tsx
import { Navigation, NavigationStack, Script, Text, VStack } from "scripting"

function View() {
  // Access the `dismiss` function of the context.
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <VStack
      navigationTitle={"Dismiss a view"}
    >
      <Text
        foregroundStyle={'link'}
        onTapGesture={() => {
          dismiss()
        }}
      >Tap and dismiss</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <View />
  })

  // Avoiding memory leaks.
  Script.exit()
}

run()
```

***

## Key Concepts

### `Navigation.useDismiss()`

This hook returns the `dismiss` function from the current view context. When called, it dismisses the view presented via `Navigation.present()`.

### When to use it

- To manually close a presented UI view
- As part of form submission, cancellation, or navigation control logic

### Example usage

In the example, a tappable `Text` is rendered:

```tsx
<Text
  foregroundStyle={'link'}
  onTapGesture={() => {
    dismiss()
  }}
>
  Tap and dismiss
</Text>
```

Tapping the text triggers `dismiss()`, closing the view.

***

## Best Practices

- Always call `Script.exit()` after `Navigation.present()` completes to avoid memory leaks.
- Wrap your view in `NavigationStack` to support title bars and navigation behavior.
- Ensure `useDismiss` is only used inside the component tree presented via `Navigation.present()`.

***

## Result

This script will present a simple view with a link-style text labeled **“Tap and dismiss”**. When the user taps it, the view will close.



---
url: /guide/Views/Present views/Dismissing a presented view/index_example.md
---

# Example

```tsx
import { Navigation, NavigationStack, Script, Text, VStack } from "scripting"

function View() {
  // Access the `dismiss` function of the context.
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <VStack
      navigationTitle={"Dismiss a view"}
    >
      <Text
        foregroundStyle={'link'}
        onTapGesture={() => {
          dismiss()
        }}
      >Tap and dismiss</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <View />
  })

  // Avoiding memory leaks.
  Script.exit()
}

run()
```



---
url: /guide/Views/Present views/Present a simple view/index.md
---

# Present a simple view

This example demonstrates how to display a basic UI screen in the Scripting app using the `Navigation.present` API. It also shows how to set up navigation-related features such as the navigation stack and page title.

***

## Overview

You will learn how to:

- Present a custom view using `Navigation.present`
- Create a structured layout using `NavigationStack` and `VStack`
- Set the navigation bar title using `navigationTitle`

***

## Example Code

```tsx
import { Navigation, NavigationStack, Script, Text, VStack } from "scripting"

function View() {

  return <NavigationStack>
    <VStack
      navigationTitle={"Present a simple view"}
    >
      <Text>Hello Scripting!</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <View />
  })

  Script.exit()
}

run()
```

***

## Key Components

### `Navigation.present(options)`

This function displays the given UI element modally as a full screen page. It takes an `element` property that defines the root view to show.

```ts
await Navigation.present({
  element: <View />
})
```

### `NavigationStack`

This component provides a navigation container that supports title display, navigation bar buttons, and structured transitions. It must be the outermost wrapper for views that use navigation features.

### `VStack`

A vertical layout container that stacks children in a top-to-bottom arrangement. In this example, it holds a single `Text` component.

### `navigationTitle`

Set on `VStack`, this prop sets the title shown in the navigation bar.

***

## Output

This example displays a simple page with the title **"Present a simple view"** and a message reading **"Hello Scripting!"** in the center of the screen.

***

## Notes

- Always wrap your views in `NavigationStack` if you want navigation behavior like back buttons, titles, or toolbars.
- Don’t forget to call `Script.exit()` after `Navigation.present()` resolves to avoid memory leaks.



---
url: /guide/Views/Present views/Present a simple view/index_example.md
---

# Example

```tsx
import { Navigation, NavigationStack, Script, Text, VStack } from "scripting"

function View() {

  return <NavigationStack>
    <VStack
      navigationTitle={"Present a simple view"}
    >
      <Text>Hello Scripting!</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <View />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/SVG.md
---

# SVG

The `SVG` component is used to display SVG (Scalable Vector Graphics) images. It supports loading SVG content from the following sources:

- A **remote URL**
- A **local file path**
- **Inline SVG code**

SVGs are rendered as bitmap images. You can choose to render them in **template mode** to apply tint colors using `foregroundColor`.

***

## Import

```tsx
import { SVG } from 'scripting'
```

***

## Props

### Image Source (choose exactly one)

| Prop       | Type                                   | Description                            |
| ---------- | -------------------------------------- | -------------------------------------- |
| `url`      | `string \| DynamicImageSource<string>` | Displays an SVG from a network URL     |
| `filePath` | `string \| DynamicImageSource<string>` | Displays an SVG from a local file path |
| `code`     | `string \| DynamicImageSource<string>` | Displays an SVG from inline SVG code   |

> These three props are mutually exclusive — only one should be provided.

***

### Rendering Behavior (`ImageRenderingBehaviorProps`)

| Prop                          | Type                                        | Default      | Description                                                     |
| ----------------------------- | ------------------------------------------- | ------------ | --------------------------------------------------------------- |
| `resizable`                   | `boolean \| object`                         | `false`      | Controls whether the image resizes to fit its frame (see below) |
| `renderingMode`               | `'original' \| 'template'`                  | `'original'` | Use `"template"` to allow tinting via `foregroundColor`         |
| `interpolation`               | `'none' \| 'low' \| 'medium' \| 'high'`     | `'medium'`   | Sets interpolation quality when scaling the image               |
| `antialiased`                 | `boolean`                                   | `false`      | Whether the image should use anti-aliasing                      |
| `widgetAccentedRenderingMode` | `WidgetAccentedRenderingMode` (Widget-only) | —            | Defines how the image renders in Widget accented mode           |

***

### `resizable` Prop Details

| Type                          | Meaning                                                                    |
| ----------------------------- | -------------------------------------------------------------------------- |
| `true`                        | Image resizes to fit its container (stretch)                               |
| `false`                       | Image maintains original size                                              |
| `{ capInsets, resizingMode }` | Allows defining cap insets and resizing mode (for 9-patch or tiled images) |

***

## Examples

### Display SVG from a local file (template mode with tint)

```tsx
<SVG
  filePath="/path/to/local/image.svg"
  resizable
  frame={{ width: 50, height: 50 }}
  renderingMode="template"
  foregroundColor="red"
/>
```

***

### Display SVG from inline code

```tsx
<SVG
  code={`<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
    <circle cx="50" cy="50" r="40" stroke="green" stroke-width="4" fill="yellow" />
  </svg>`}
  frame={{ width: 100, height: 100 }}
/>
```

***

## Notes

- SVGs are now rendered **as bitmap images** only.
- The `vectorDrawing` prop has been removed and is no longer supported.
- To apply tinting, use `renderingMode="template"` along with `foregroundColor`.
- Only one of `url`, `filePath`, or `code` may be specified at a time.



---
url: /guide/Views/Scroll views/index.md
---

# Scroll views

The `ScrollView` component displays its content within a scrollable region. As the user performs scroll gestures, the visible portion of the content is updated accordingly. You can scroll vertically, horizontally, or in both directions using the `axes` prop.

## Type

```ts
type ScrollViewProps = {
  axes?: AxisSet
  children?: VirtualNode | VirtualNode[] | (VirtualNode | undefined | null)[]
}
```

## Overview

- Scroll direction is controlled by the `axes` property.
- Contents are placed inside children, typically using layouts like `<VStack>` or `<HStack>`.
- Zooming is not supported.

## Default Behavior

- The default scroll axis is **vertical**.
- Scroll indicators are shown based on platform conventions unless configured via modifiers.

## Example

```tsx
<ScrollView>
  <VStack>
    {new Array(100).fill('').map((_, index) => (
      <Text>Row {index}</Text>
    ))}
  </VStack>
</ScrollView>
```

***

## ScrollView Modifiers

You can apply the following view modifiers to configure scroll-related behavior.

***

## `scrollIndicator`

Controls the visibility of scroll indicators.

### Type

```ts
scrollIndicator?: ScrollScrollIndicatorVisibility | {
  visibility: ScrollScrollIndicatorVisibility
  axes: AxisSet
}
```

### `ScrollScrollIndicatorVisibility` options:

- `"automatic"`: Follows platform default behavior.
- `"visible"`: Indicators appear but may auto-hide based on OS behavior.
- `"hidden"`: Hidden unless overridden by system behavior.
- `"never"`: Never show indicators.

### Example

```tsx
<ScrollView scrollIndicator="never">
  <VStack>{/* content */}</VStack>
</ScrollView>
```

With axis-specific visibility:

```tsx
<ScrollView
  scrollIndicator={{
    visibility: "hidden",
    axes: "vertical"
  }}
>
  <VStack>{/* content */}</VStack>
</ScrollView>
```

***

## `scrollDisabled`

Enables or disables scrolling behavior entirely.

### Type

```ts
scrollDisabled?: boolean
```

### Example

```tsx
<ScrollView scrollDisabled>
  <Text>This scroll view is locked.</Text>
</ScrollView>
```

***

## `scrollClipDisabled`

Controls whether the scroll view clips content that extends beyond its bounds.

### Type

```ts
scrollClipDisabled?: boolean
```

### Example

```tsx
<ScrollView scrollClipDisabled>
  {/* Content may overflow scroll bounds visually */}
</ScrollView>
```

***

## `scrollDismissesKeyboard`

Determines how the scroll interaction affects the software keyboard.

### Type

```ts
scrollDismissesKeyboard?: ScrollDismissesKeyboardMode
```

### Options

- `"automatic"`: Default behavior based on context.
- `"immediately"`: Dismiss keyboard as soon as scrolling starts.
- `"interactively"`: Allow user to drag to dismiss keyboard.
- `"never"`: Scrolling will not dismiss the keyboard.

### Example

```tsx
<ScrollView scrollDismissesKeyboard="interactively">
  {/* Content with text input */}
</ScrollView>
```

***

## `defaultScrollAnchor`

Defines which point in the content should be visible initially or stay anchored when content size changes.

### Type

```ts
defaultScrollAnchor?: KeywordPoint | Point
```

### `KeywordPoint` values

- `"top"`, `"bottom"`, `"leading"`, `"trailing"`, `"center"`, `"topLeading"`, `"bottomTrailing"` etc.

### Example

```tsx
<ScrollView defaultScrollAnchor="bottom">
  <VStack>
    {/* New content will appear anchored to the bottom */}
  </VStack>
</ScrollView>
```

***

## `AxisSet`

Defines the scrollable directions for a scroll view.

### Type

```ts
type AxisSet = 'vertical' | 'horizontal' | 'all'
```

### Usage

```tsx
<ScrollView axes="horizontal">
  <HStack>{/* horizontally scrollable content */}</HStack>
</ScrollView>
```

***

## `scrollTargetLayout`

Applies this modifier to layout containers such as LazyHStack, LazyVStack, HStack, or VStack that represent the main repeating content inside a ScrollView.

### Type

```ts
scrollTargetLayout?: boolean
```

### Usage

When set to `true`, this modifier designates the associated layout container as a scroll target region within the `ScrollView`. It allows the scroll behavior system to determine how scrolling should align to elements within the container.

```tsx
<ScrollView axes="horizontal">
  <LazyHStack scrollTargetLayout>
    {items.map(item => <Text>{item.title}</Text>)}
  </LazyHStack>
</ScrollView>
```

***

## `scrollTargetBehavior`

Defines how scrollable views behave when aligning content to scroll targets.

### Type

```ts
scrollTargetBehavior?: ScrollTargetBehavior
```

```ts
type ScrollTargetBehavior =
  | "paging"
  | "viewAligned"
  | "viewAlignedLimitAutomatic"
  | "viewAlignedLimitAlways"
  | "viewAlignedLimitNever"
  | "viewAlignedLimitAlwaysByFew"
  | "viewAlignedLimitAlwaysByOne"
```

#### Description of Variants

- **`"paging"`**: Scrolls one page at a time, aligned to the container’s dimensions.
- **`"viewAligned"`**: Scrolls to align views directly, based on view frames.
- **`"viewAlignedLimitAutomatic"`**: Limits scrolling in compact horizontal size classes, but allows full scrolling otherwise.
- **`"viewAlignedLimitAlways"`**: Always restricts scrolling to a limited number of items.
- **`"viewAlignedLimitNever"`**: Allows unrestricted scrolling without view-based limitations.
- **`"viewAlignedLimitAlwaysByFew"`** _(iOS 18.0+)_: Limits scrolling to a small number of views per gesture, automatically determined.
- **`"viewAlignedLimitAlwaysByOne"`** _(iOS 18.0+)_: Restricts each scroll gesture to advance exactly one view at a time.

### Description

This modifier configures the scroll behavior, such as paging and alignment strategy, for views within a scrollable container.

***

## `scrollPosition`

Two-way binds the **id of the leading visible item** in a `ScrollView` to JS state. Mirrors SwiftUI's `.scrollPosition(id:anchor:)` — no `ScrollViewReader` wrapper required.

### Type

```ts
scrollPosition?:
  | Observable<string>
  | Observable<number>
  | Observable<string | null>
  | Observable<number | null>
  | { value: Observable<string | number | null>; anchor?: KeywordPoint | Point }
  | {
      value: string | number | null
      onChanged: (newValue: string | number | null) => void
      anchor?: KeywordPoint | Point
    }
```

### Setup

1. The container directly under the `ScrollView` (typically `LazyVStack` / `LazyHStack` / `VStack`) needs `scrollTargetLayout`.
2. Each child you want to be a scroll target needs a `key="..."` prop — the bridge maps it to SwiftUI's `.id()`.
3. Bind `scrollPosition` to a state — `Observable` form or `{ value, onChanged }` form.

### Example

```tsx
const [visibleId, setVisibleId] = useState<string | null>(null)

<ScrollView
  scrollPosition={{ value: visibleId, onChanged: setVisibleId, anchor: "top" }}
>
  <LazyVStack scrollTargetLayout>
    {items.map(it => (
      <HStack key={it.id}>{/* row content */}</HStack>
    ))}
  </LazyVStack>
</ScrollView>
```

- `id` may be `string` or `number`. Pick the type when initialising the state and stick with it — the bridge dispatches on the runtime type.
- Setting the state to `null` lets SwiftUI manage the scroll position; setting it to a known id scrolls that item to the anchor.
- `anchor` is a `UnitPoint`: a string keyword (`"top"` / `"center"` / `"leading"` / ...) or `{ x, y }`.

### Pitfalls

- **Forgetting `scrollTargetLayout`.** Without it, SwiftUI doesn't know which subview is the "current" scroll target — the binding silently does nothing.
- **Mixing id types.** A `Observable<number>` won't bind against a child whose `key` was rendered as a string. Keep both sides consistent.
- **Type changes mid-flight.** Initialise the observable with a real value (e.g. `useState<string|null>("first")`) so the bridge can detect the type at modifier time. A purely-`null`-initial observable defaults to the string path.
- **ScrollViewReader vs scrollPosition.** Don't bind both to the same scroll view — the imperative `scrollTo(id:)` and declarative `scrollPosition` will fight each other. Pick one.

***

## `onScrollTargetVisibilityChange`

iOS 18+. Reports the **set of currently-visible scroll target ids** whenever it changes (filtered by `threshold`). Mirrors SwiftUI's `.onScrollTargetVisibilityChange(idType:threshold:_:)`.

### Type

```ts
onScrollTargetVisibilityChange?: {
  idType: "string" | "number"
  threshold?: number   // 0.0 - 1.0, default 0.5
  onChanged: (ids: string[] | number[]) => void
}
```

### Setup

Same as `scrollPosition`:

1. The layout container needs `scrollTargetLayout`.
2. Children must be marked with `key="..."` or `key={123}`.
3. **`idType` must match the runtime type of the keys.** The SwiftUI API is generic, and the bridge has to dispatch statically at modifier-creation time — there's no way to recover the ID type from `[AnyHashable]` at runtime. Use `"string"` for string keys, `"number"` for number keys.

### Example

```tsx
const [visibleIds, setVisibleIds] = useState<string[]>([])

<ScrollView
  onScrollTargetVisibilityChange={{
    idType: "string",
    threshold: 0.5,
    onChanged: (ids) => setVisibleIds(ids as string[]),
  }}
>
  <LazyVStack scrollTargetLayout>
    {items.map(it => <Row key={it.id} />)}
  </LazyVStack>
</ScrollView>
```

### Pitfalls

- **iOS 17 fallback.** On iOS 17 the bridge logs an `API deprecated` warning and skips the modifier — content passes through. Other modifiers are unaffected.
- **`threshold` semantics.** `0.5` = the view must be at least 50% within the viewport to count as visible. `0` = any pixel triggers; `1` = the entire view must be visible.
- **Callback frequency.** During scrolling the callback is invoked on the main thread inline (no throttling). A list with \~30 items where \~5 are visible is fine; for very dense lists with rapid scrolling, keep the callback body cheap.
- **Compatible with `scrollPosition`.** They serve different purposes — `scrollPosition` gives you the leading id, `onScrollTargetVisibilityChange` gives you the entire visible set. Using both on the same scroll view is safe.

***

## `scrollContentBackground`

Specifies the visibility of the background for scrollable views, such as `ScrollView`, within the current view context.

### Type

```ts
scrollContentBackground?: Visibility
```

### Description

This modifier controls whether the default background behind scrollable content (typically a system-provided background) is shown, hidden, or determined automatically based on system behavior.

It is commonly used when customizing the appearance of scrollable views or when layering custom backgrounds behind scroll content.

### Visibility Options

- **`'automatic'`**
  The system decides whether the background should be visible based on the current context and platform conventions.

- **`'hidden'`**
  Hides the scroll view’s default background, allowing custom background layers or transparent effects.

- **`'visible'`**
  Forces the default scroll content background to be shown, even if a custom background is present.

### Example: Hiding Scroll Background

```tsx
<List scrollContentBackground="hidden">
  <Text>No background here</Text>
</List>
```

This example removes the default background from the scroll view, making it fully transparent or allowing underlying views to show through.

***

## Summary

| Modifier / Prop                  | Description                                                              |
| -------------------------------- | ------------------------------------------------------------------------ |
| `axes`                           | Defines scroll direction (`vertical`, `horizontal`, or `all`)            |
| `scrollIndicator`                | Controls scroll indicator visibility and supports axis-specific config   |
| `scrollDisabled`                 | Disables scrolling entirely when set to `true`                           |
| `scrollClipDisabled`             | Prevents clipping of content that overflows the scroll bounds            |
| `scrollDismissesKeyboard`        | Configures how scrolling interacts with the software keyboard            |
| `defaultScrollAnchor`            | Sets the initial or persistent scroll anchor point in the content        |
| `scrollTargetLayout`             | Marks a container (like `LazyHStack`) as the scroll target for alignment |
| `scrollTargetBehavior`           | Determines how content aligns and scrolls within the scroll view         |
| `scrollPosition`                 | Two-way binds the leading visible item's id to JS state                  |
| `onScrollTargetVisibilityChange` | iOS 18+, subscribes to the visible id set                                |
| `scrollContentBackground`        | Sets the visibility of the scroll view’s default background              |



---
url: /guide/Views/Scroll views/index_example.md
---

# Example

```tsx
import { Button, Color, ForEach, HStack, KeywordPoint, LazyVStack, Navigation, NavigationStack, Picker, RoundedRectangle, Script, ScrollView, Text, useState, VStack } from "scripting"

function Example() {
  const colors: Color[] = [
    "systemRed",
    "systemOrange",
    "systemYellow",
    "systemGreen",
    "systemBlue",
    "systemPurple",
    "systemIndigo",
    "systemPink",
  ]
  const [scrollAnchor, setScrollAnchor] = useState<KeywordPoint>("bottom")

  // scrollPosition demo —— 把 leading 可见 item id 双向绑到 state；
  // 子节点用 `key=...`，bridge 会映射到 SwiftUI `.id()`。
  const positionItems = Array.from({ length: 50 }, (_, i) => ({
    id: `pos-${i}`,
    title: `Row ${i + 1}`,
    color: colors[i % colors.length],
  }))
  const [visibleId, setVisibleId] = useState<string | null>(null)

  // onScrollTargetVisibilityChange demo —— iOS 18+，跟踪当前可见 id 集合（threshold ≥ 0.5）。
  const visItems = Array.from({ length: 30 }, (_, i) => ({
    id: `vis-${i}`,
    title: `Item ${i + 1}`,
    color: colors[i % colors.length],
  }))
  const [visibleIds, setVisibleIds] = useState<string[]>([])

  return <NavigationStack>
    <ScrollView
      navigationTitle={"ScrollView"}
      defaultScrollAnchor={scrollAnchor}
      navigationBarTitleDisplayMode={"inline"}
      key={scrollAnchor}
    >
      <VStack
        spacing={16}
        padding
      >
        <Picker
          title={"Default Scroll Anchor"}
          value={scrollAnchor}
          onChanged={setScrollAnchor as any}
          pickerStyle={"menu"}
        >
          <Text tag={"top"}>Top</Text>
          <Text tag={"center"}>Center</Text>
          <Text tag={"bottom"}>Bottom</Text>
        </Picker>

        <ScrollView
          axes={"horizontal"}
          frame={{
            height: 64
          }}
        >
          <HStack spacing={8}>
            <ForEach
              count={15}
              itemBuilder={index =>
                <RoundedRectangle
                  key={index.toString()}
                  fill={"systemIndigo"}
                  cornerRadius={6}
                  frame={{
                    width: 64,
                    height: 64,
                  }}
                  overlay={
                    <Text>{index}</Text>
                  }
                />
              }
            />
          </HStack>
        </ScrollView>

        <ForEach
          count={colors.length}
          itemBuilder={index => {
            const color = colors[index]
            return <RoundedRectangle
              key={color}
              fill={color}
              cornerRadius={16}
              frame={{
                height: 100
              }}
            />
          }}
        />

        {/* scrollPosition section —— 把 leading 可见 item id 同步给 JS，并支持 jump-to-id */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>scrollPosition(id:anchor:)</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            Two-way binds the leading visible item's id. Tap a Jump button to scroll to a row.
          </Text>
          <HStack spacing={6}>
            <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>Visible:</Text>
            <Text font={"caption"} monospaced>{visibleId ?? "—"}</Text>
          </HStack>
          <HStack spacing={8}>
            <Button title={"Jump to first"} action={() => setVisibleId("pos-0")} buttonStyle={"borderedProminent"} controlSize={"small"} />
            <Button title={"Jump to 25"} action={() => setVisibleId("pos-24")} buttonStyle={"borderedProminent"} controlSize={"small"} />
            <Button title={"Jump to last"} action={() => setVisibleId("pos-49")} buttonStyle={"borderedProminent"} controlSize={"small"} />
          </HStack>
          <ScrollView
            frame={{ height: 280 }}
            background={
              <RoundedRectangle cornerRadius={12} fill={"secondarySystemBackground"} />
            }
            scrollPosition={{
              value: visibleId,
              onChanged: (id) => setVisibleId(id as string | null),
              anchor: "top",
            }}
          >
            <LazyVStack scrollTargetLayout spacing={8} padding={8}>
              {positionItems.map(it => (
                <HStack
                  key={it.id}
                  spacing={12}
                  padding={10}
                  background={
                    <RoundedRectangle cornerRadius={10} fill={{ color: it.color, opacity: 0.18 }} />
                  }
                >
                  <RoundedRectangle cornerRadius={6} frame={{ width: 24, height: 24 }} fill={it.color} />
                  <Text font={"body"}>{it.title}</Text>
                  <Text font={"caption"} foregroundStyle={"secondaryLabel"}>{it.id}</Text>
                </HStack>
              ))}
            </LazyVStack>
          </ScrollView>
        </VStack>

        {/* onScrollTargetVisibilityChange section —— iOS 18+，整组可见 id 跟踪 */}
        <VStack alignment={"leading"} spacing={8}>
          <Text font={"headline"}>onScrollTargetVisibilityChange</Text>
          <Text font={"caption"} foregroundStyle={"secondaryLabel"}>
            iOS 18+. Reports the array of currently-visible scroll-target ids (≥ 50% visible).
          </Text>
          <Text font={"caption2"} foregroundStyle={"secondaryLabel"}>
            visible ({visibleIds.length}):
          </Text>
          <Text font={"caption"} monospaced>
            {visibleIds.length > 0 ? visibleIds.join(", ") : "—"}
          </Text>
          <ScrollView
            frame={{ height: 220 }}
            background={
              <RoundedRectangle cornerRadius={12} fill={"secondarySystemBackground"} />
            }
            onScrollTargetVisibilityChange={{
              idType: "string",
              threshold: 0.5,
              onChanged: (ids) => setVisibleIds(ids as string[]),
            }}
          >
            <LazyVStack scrollTargetLayout spacing={8} padding={8}>
              {visItems.map(it => (
                <HStack
                  key={it.id}
                  spacing={12}
                  padding={10}
                  background={
                    <RoundedRectangle cornerRadius={10} fill={{ color: it.color, opacity: 0.18 }} />
                  }
                >
                  <RoundedRectangle cornerRadius={6} frame={{ width: 24, height: 24 }} fill={it.color} />
                  <Text font={"body"}>{it.title}</Text>
                  <Text font={"caption"} foregroundStyle={"secondaryLabel"}>{it.id}</Text>
                </HStack>
              ))}
            </LazyVStack>
          </ScrollView>
        </VStack>
      </VStack>
    </ScrollView>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()


```



---
url: /guide/Views/ScrollViewReader.md
---

# ScrollViewReader

The **ScrollViewReader** component equivalent to SwiftUI’s ScrollViewReader, allowing scripts to programmatically control scrolling position within scrollable content such as `List` or `ScrollView`.

***

## ScrollViewProxy

`ScrollViewProxy` represents the programmatic interface for controlling scrolling. It is provided by `ScrollViewReader` during rendering.

```ts
interface ScrollViewProxy {
    scrollTo: (id: string | number, anchor?: KeywordPoint | Point) => void
}
```

## Methods

### scrollTo(id, anchor?)

Scrolls the closest scrollable container until the element with the specified `key` becomes visible.

#### Parameters

| Parameter | Type           | Required | Description |                                                                                                          |
| --------- | -------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| id        | `string`       | `number` | Yes         | The `key` of the target element. Must match the `key` assigned to a child inside the scrollable content. |
| anchor    | `KeywordPoint` | `Point`  | No          | Controls how the target is aligned within the visible area. Optional.                                    |

### KeywordPoint

Predefined scroll alignment keywords:

- `'top'`
- `'center'`
- `'bottom'`

### Point

Precise alignment coordinates:

```ts
type Point = {
  x: number
  y: number
}
```

***

## ScrollViewReader Component

```ts
type ScrollViewReaderProps = {
    children: (scrollViewProxy: ScrollViewProxy) => VirtualNode;
};
declare const ScrollViewReader: FunctionComponent<ScrollViewReaderProps>;
```

## Props

| Name     | Type                                      | Required | Description                                                                  |
| -------- | ----------------------------------------- | -------- | ---------------------------------------------------------------------------- |
| children | `(proxy: ScrollViewProxy) => VirtualNode` | Yes      | A function that receives a `ScrollViewProxy` and returns scrollable content. |

***

## Behavior and Usage Notes

1. ScrollViewReader must wrap a `List`, `ScrollView`, or another scrollable container.
2. The `proxy` is created once during rendering. Use `useRef` if you need to store it.
3. `scrollTo` works only with elements that have a **unique `key`**.
4. Using `withAnimation` enables smooth scrolling.
5. The API follows React’s identity model, but scroll behavior matches SwiftUI.

***

## Example Usage

```tsx
import {
  Button,
  Navigation,
  NavigationStack,
  Script,
  Text,
  List,
  ScrollViewReader,
  ScrollView,
  VStack,
  useRef,
  ScrollViewProxy,
} from "scripting"


function Item({ index }: { index: number }) {
  return <Text>
    Item - {index}
  </Text>
}

function View() {
  const dismiss = Navigation.useDismiss()
  const proxyRef = useRef<ScrollViewProxy>()

  return <NavigationStack>
    <VStack navigationTitle="ScrollViewReader">

      <ScrollViewReader>
        {(proxy) => {
          // Store the proxy instance
          proxyRef.current = proxy

          return <List>
            {new Array(100).fill(0).map((_, index) =>
              <Item
                key={index}
                index={index}
              />
            )}
            <Text key="bottom">
              Bottom
            </Text>
          </List>
        }}
      </ScrollViewReader>

      <Button
        title="Jump"
        action={() => {
          if (proxyRef.current == null) {
            console.log("no proxy found")
            return
          }

          const index = Math.random() * 100 | 0

          withAnimation(() => {
            proxyRef.current?.scrollTo(index)

            // Scroll to the element identified by key="bottom"
            // proxyRef.current?.scrollTo("bottom", "bottom")
          })
        }}
      />

    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <View />
  })
  Script.exit()
}

run()
```

***

## How `key` Works in Scripting

Scripting does not support `.id()` as in SwiftUI.
Instead:

```tsx
<Text key="bottom">Bottom</Text>
```

- `key` identifies the element within the virtual node tree
- `scrollTo("bottom")` will scroll to this element
- `key` must be stable and unique, similar to React and SwiftUI’s `.id()`

***

## Animation Support

Scroll operations can be wrapped in `withAnimation` to enable smooth transitions:

```tsx
withAnimation(() => {
  proxy.scrollTo("targetKey", "center")
})
```

The animation behavior follows SwiftUI’s animation engine.

***

## Important Notes

1. Every scroll target must have a unique `key`.
2. `scrollTo` will not work without a matching `key`.
3. The scrollable content must be inside the same ScrollViewReader.
4. The alignment anchor is optional but useful for precise positioning.
5. The API mirrors SwiftUI’s ScrollViewReader logic but adopts React-style identity handling.



---
url: /guide/Views/Search/index.md
---

# Search

The Scripting app supports advanced search interactions similar to SwiftUI. You can add a search bar, control its visibility and placement, react to changes in input, and display dynamic suggestions.

***

## `searchable`

Marks a view as searchable by displaying a search field and binding it to a state value.

### Type

```ts
searchable?: {
  value: string
  onChanged: (value: string) => void
  placement?: SearchFieldPlacement
  prompt?: string
  presented?: {
    value: boolean
    onChanged: (value: boolean) => void
  }
}
```

### Description

- Displays a search field in the view (typically above a `<List>`).
- The `value` is the current search query, which you control via state.
- The `onChanged` callback updates the state when the user types.
- Optionally provide a `prompt` as placeholder text.
- Use `placement` to customize where the search field appears.
- Use `presented` to programmatically show or dismiss the search field.

### Example

```tsx
function SearchExample() {
  const [query, setQuery] = useState("")
  const [showSearch, setShowSearch] = useState(false)

  return (
    <List
      searchable={{
        value: query,
        onChanged: setQuery,
        placement: "navigationBarDrawer",
        prompt: "Search items",
        presented: {
          value: showSearch,
          onChanged: setShowSearch,
        }
      }}
    >
      <Text>Searching: {query}</Text>
    </List>
  )
}
```

### `SearchFieldPlacement` options

| Value                                   | Description                                                |
| --------------------------------------- | ---------------------------------------------------------- |
| `'automatic'`                           | Default behavior, automatically selected placement.        |
| `'navigationBarDrawer'`                 | Appears as a drawer below the navigation bar.              |
| `'navigationBarDrawerAlwaysDisplay'`    | Always shows the drawer, even when inactive.               |
| `'navigationBarDrawerAutomaticDisplay'` | Shows drawer only when needed.                             |
| `'toolbar'`                             | Displays the search field in the toolbar.                  |
| `'sidebar'`                             | Places the search field in the sidebar (iPad/macOS-style). |

***

## `searchSuggestions`

Displays a list of suggestions below the search field as the user types.

### Type

```ts
searchSuggestions?: VirtualNode
```

### Description

Use this to return a list of suggestions, typically based on the user's input.

### Example

```tsx
const suggestions = useMemo(() => [
  {
    label: "🍎 Apple",
    value: "Apple"
  },
  {
    label: "🍌 Bananer",
    value: "Bananer"
  }
], [])
const filteredSuggestions = useMemo(() => {
  if (!/\S+/.test(query)) {
    return suggestions
  }
  const q = query.toLowerCase()
  return suggestions.filter(s =>
    s.label.toLowerCase().includes(q) ||
    s.value.toLowerCase().includes(q))
}, [query, suggestions])

<List
  searchable={{
    value: query,
    onChanged: setQuery
  }}
  searchSuggestions={
    <>
      {filteredSuggestions.map(s =>
        <Text
          searchCompletion={s.value}
        >{s.label}</Text>
      )}
    </>
  }
/>
```

***

## `searchSuggestionsVisibility`

Controls when and where search suggestions are shown.

### Type

```ts
searchSuggestionsVisibility?: {
  visibility: 'visible' | 'hidden'
  placements: SearchSuggestionsPlacementSet
}
```

### `SearchSuggestionsPlacementSet` options

| Value       | Description                                 |
| ----------- | ------------------------------------------- |
| `'content'` | Shows suggestions inline with the content.  |
| `'menu'`    | Shows suggestions in a popover or dropdown. |
| `'all'`     | Applies to all available placements.        |

### Example

```tsx
<List
  searchSuggestionsVisibility={{
    visibility: 'visible',
    placements: 'menu'
  }}
/>
```

***

## `searchCompletion`

Associates a tappable search suggestion with a complete search query string.

### Type

```ts
searchCompletion?: string
```

### Description

Apply this modifier to suggestion views (such as `<Text>`) to indicate what value should be filled into the search field when the user taps the suggestion.

### Example

```tsx
<Text searchCompletion="Mango">🥭 Mango</Text>
```

When tapped, this will set the search field to `"Mango"`.

***

## Summary

| Modifier                      | Purpose                                               |
| ----------------------------- | ----------------------------------------------------- |
| `searchable`                  | Adds a search field with bindings and customization.  |
| `searchSuggestions`           | Provides a list of custom suggestions.                |
| `searchSuggestionsVisibility` | Controls where and when suggestions are shown.        |
| `searchCompletion`            | Defines the value used when a suggestion is selected. |

These modifiers work together to create a responsive, interactive search experience in any scrollable view like `<List>`.



---
url: /guide/Views/Search/index_example.md
---

# Example

```tsx
import { List, Navigation, NavigationStack, Script, Text, useMemo, useState } from "scripting"

function Example() {
  const [searchText, setSearchText] = useState("")
  const languages = useMemo(() => [
    "Java",
    "Objective-C",
    "Swift",
    "Python",
    "JavaScript",
    "C++",
    "Ruby",
    "Lua"
  ], [])

  const filteredLanguages = useMemo(() => {
    if (searchText.length === 0) {
      return languages
    }

    const text = searchText.toLowerCase()

    return languages.filter(language =>
      language.toLowerCase().includes(text)
    )
  }, [searchText, languages])

  return <NavigationStack>
    <List
      navigationTitle={"Searchable List"}
      navigationBarTitleDisplayMode={"inline"}
      searchable={{
        value: searchText,
        onChanged: setSearchText,
      }}
    >
      {filteredLanguages.map(language =>
        <Text>{language}</Text>
      )}
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Shapes/index.md
---

# Shapes

Scripting provides a suite of shape components for creating scalable, vector-based UI elements such as rectangles, circles, capsules, ellipses, and rounded rectangles. These shapes support customizable fill, stroke, trimming, and sizing, making them ideal for dashboards, decorative elements, and interactive visuals.

***

## Common `ShapeProps`

All shape components support the following properties for visual customization:

```ts
type ShapeProps = {
  trim?: {
    from: number
    to: number
  }
  fill?: ShapeStyle | DynamicShapeStyle
  stroke?: ShapeStyle | DynamicShapeStyle | {
    shapeStyle: ShapeStyle | DynamicShapeStyle
    strokeStyle: StrokeStyle
  }
  strokeLineWidth?: number // Deprecated
}
```

### Property Descriptions

| Property          | Type                                                                 | Description                                                                                              |
| ----------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `trim`            | `{ from: number; to: number }`                                       | Renders only a portion of the shape’s path. Both `from` and `to` are fractions between `0.0` and `1.0`.  |
| `fill`            | `ShapeStyle` \| `DynamicShapeStyle`                                  | Fills the shape with a solid color or gradient.                                                          |
| `stroke`          | `ShapeStyle` \| `DynamicShapeStyle` \| `{ shapeStyle, strokeStyle }` | Outlines the shape with a customizable stroke. Supports color, gradient, and stroke style configuration. |
| `strokeLineWidth` | `number` (Deprecated)                                                | Sets the stroke width. Prefer `strokeStyle.lineWidth` for more control.                                  |

***

## StrokeStyle

To define the appearance of a shape’s stroke, you can use the `strokeStyle` object:

```ts
type StrokeStyle = {
  lineWidth?: number
  lineCap?: 'butt' | 'round' | 'square'
  lineJoin?: 'bevel' | 'miter' | 'round'
  mitterLimit?: number
  dash?: number[]
  dashPhase?: number
}
```

### StrokeStyle Options

| Property      | Description                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------- |
| `lineWidth`   | Width of the stroke line in points.                                                         |
| `lineCap`     | Shape of the endpoints: `"butt"` (flat), `"round"` (rounded), or `"square"` (square-ended). |
| `lineJoin`    | Join style for corners: `"miter"`, `"round"`, or `"bevel"`.                                 |
| `mitterLimit` | Limit for miter joins. Used when `lineJoin` is `"miter"`.                                   |
| `dash`        | Array of numbers that define the lengths of painted and unpainted segments.                 |
| `dashPhase`   | How far into the dash pattern to start the drawing.                                         |

***

## Supported Shape Components

### `Rectangle`

A basic rectangle.

```tsx
<Rectangle
  fill="orange"
  stroke={{
    shapeStyle: "red",
    strokeStyle: {
      lineWidth: 3,
      lineJoin: "round"
    }
  }}
  frame={{ width: 100, height: 100 }}
/>
```

***

### `RoundedRectangle`

A rectangle with uniformly or dimensionally rounded corners.

```tsx
<RoundedRectangle
  fill="blue"
  cornerRadius={16}
  frame={{ width: 100, height: 100 }}
/>
```

***

### `UnevenRoundedRectangle`

A rectangle with individually configurable corner radii.

```tsx
<UnevenRoundedRectangle
  fill="brown"
  topLeadingRadius={16}
  topTrailingRadius={0}
  bottomLeadingRadius={0}
  bottomTrailingRadius={16}
  frame={{ width: 100, height: 50 }}
/>
```

***

### `Circle`

A circle centered within its frame.

```tsx
<Circle
  stroke="purple"
  strokeLineWidth={4}
  frame={{ width: 100, height: 100 }}
/>
```

***

### `Capsule`

An elongated shape with fully rounded ends.

```tsx
<Capsule
  fill="systemIndigo"
  frame={{ width: 100, height: 40 }}
/>
```

***

### `Ellipse`

An oval shape fitted inside a rectangular frame.

```tsx
<Ellipse
  fill="green"
  frame={{ width: 40, height: 100 }}
/>
```

***

## Notes

- To apply advanced stroke customization (e.g. dashed outlines), use the `strokeStyle` object.
- The `strokeLineWidth` property is deprecated and should be replaced with `stroke.strokeStyle.lineWidth`.
- The `trim` modifier is particularly useful for animations (e.g., animated drawing of progress rings).
- All shapes are compatible with layout modifiers like `frame`, `padding`, and `background`.



---
url: /guide/Views/Shapes/index_example.md
---

# Example

```tsx
import { Capsule, Circle, Ellipse, List, Navigation, NavigationStack, Rectangle, RoundedRectangle, Script, Section, Text, UnevenRoundedRectangle, } from "scripting"

function Example() {

  return <NavigationStack>
    <List
      navigationTitle={"Shapes"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <Section
        header={
          <Text>Rectangle</Text>
        }
      >
        <Rectangle
          fill={"orange"}
          stroke={{
            shapeStyle: "red",
            strokeStyle: {
              lineWidth: 3,
            }
          }}
          frame={{
            width: 100,
            height: 100,
          }}
        />
      </Section>

      <Section
        header={
          <Text>RoundedRectangle</Text>
        }
      >
        <RoundedRectangle
          fill={"blue"}
          cornerRadius={16}
          frame={{
            width: 100,
            height: 100,
          }}
        />
      </Section>

      <Section
        header={
          <Text>Circle</Text>
        }
      >
        <Circle
          stroke={{
            shapeStyle: "purple",
            strokeStyle: {
              lineWidth: 4,
            }
          }}
          frame={{
            width: 100,
            height: 100,
          }}
        />
      </Section>

      <Section
        header={
          <Text>Capsule</Text>
        }
      >
        <Capsule
          fill={"systemIndigo"}
          frame={{
            width: 100,
            height: 40,
          }}
        />
      </Section>

      <Section
        header={
          <Text>Ellipse</Text>
        }
      >
        <Ellipse
          fill={"green"}
          frame={{
            width: 40,
            height: 100,
          }}
        />
      </Section>

      <Section
        header={
          <Text>UnevenRoundedRectangle</Text>
        }
      >
        <UnevenRoundedRectangle
          fill={"brown"}
          topLeadingRadius={16}
          topTrailingRadius={0}
          bottomLeadingRadius={0}
          bottomTrailingRadius={16}
          frame={{
            width: 100,
            height: 50,
          }}
        />
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Text input/Keyboard.md
---

# Keyboard

The `Keyboard` API, along with the `useKeyboardVisible` hook, allows you to interact with the software keyboard in the Scripting app. You can check the keyboard's visibility, hide it, listen for visibility changes, and access the current visibility state reactively in functional components.

***

## Overview

The `Keyboard` API enables:

1. Checking if the keyboard is currently visible.
2. Hiding the keyboard programmatically.
3. Listening for keyboard visibility changes.
4. Using the `useKeyboardVisible` hook for a reactive approach to track the keyboard's visibility.

***

## Module: `Keyboard`

### Properties

- **`visible: boolean`**\
  A read-only property that indicates whether the keyboard is currently visible.
  - `true`: The keyboard is visible.
  - `false`: The keyboard is hidden.

***

### Methods

#### `Keyboard.hide(): void`

Hides the keyboard if it is currently visible.

- **Usage**:
  - If the keyboard is already hidden, this method does nothing.
  - Typically used to programmatically dismiss the keyboard.

***

#### `Keyboard.addVisibilityListener(listener: (visible: boolean) => void): void`

Adds a listener function that is triggered whenever the keyboard's visibility changes.

- **Parameters**:
  - `listener: (visible: boolean) => void`: A callback function that receives a `visible` parameter:
    - `true`: Keyboard becomes visible.
    - `false`: Keyboard becomes hidden.

- **Usage**:
  - Use this method to execute custom logic when the keyboard appears or disappears.

***

#### `Keyboard.removeVisibilityListener(listener: (visible: boolean) => void): void`

Removes a previously added visibility listener.

- **Parameters**:
  - `listener: (visible: boolean) => void`: The callback function to remove. It must match a function previously added with `addVisibilityListener`.

***

## Hook: `useKeyboardVisible`

### `useKeyboardVisible(): boolean`

A hook to access the current keyboard visibility state. The hook provides a reactive way to track whether the keyboard is visible.

- **Returns**:
  - `true`: The keyboard is currently visible.
  - `false`: The keyboard is currently hidden.

- **Usage**:
  - This hook is ideal for functional components to conditionally render UI elements or execute logic based on the keyboard's visibility state.

***

## Example Usage

### Check Keyboard Visibility with `Keyboard.visible`

```ts
if (Keyboard.visible) {
  console.log("The keyboard is visible.")
} else {
  console.log("The keyboard is hidden.")
}
```

***

### Hide the Keyboard

```ts
Keyboard.hide()
console.log("Keyboard hidden programmatically.")
```

***

### Add and Remove a Visibility Listener

```ts
// Define the listener
function handleKeyboardVisibility(visible: boolean) {
  if (visible) {
    console.log("Keyboard is now visible.")
  } else {
    console.log("Keyboard is now hidden.")
  }
}

// Add the listener
Keyboard.addVisibilityListener(handleKeyboardVisibility)

// Remove the listener
Keyboard.removeVisibilityListener(handleKeyboardVisibility)
console.log("Keyboard visibility listener removed.")
```

***

### Use `useKeyboardVisible` in a Functional Component

```tsx
import { useKeyboardVisible, VStack, Text } from 'scripting'

function KeyboardStatus() {
  const isKeyboardVisible = useKeyboardVisible()

  return (
    <VStack>
      {isKeyboardVisible ? (
        <Text>The keyboard is currently visible.</Text>
      ) : (
        <Text>The keyboard is currently hidden.</Text>
      )}
    </VStack>
  )
}
```

***

## Notes

1. **Reactive State with Hook**: Use the `useKeyboardVisible` hook in functional components for a clean and reactive way to track keyboard visibility.
2. **Static State with `Keyboard.visible`**: Use the `Keyboard.visible` property for quick, non-reactive checks.
3. **Event Listeners**: Add multiple visibility listeners with `addVisibilityListener` as needed, and ensure you remove them when no longer required to prevent memory leaks.
4. **Programmatic Dismissal**: The `Keyboard.hide()` method is useful for scenarios where you want to close the keyboard, such as when submitting a form or tapping outside an input field.



---
url: /guide/Views/Text input/SecureField/index.md
---

# SecureField

The `SecureField` component in Scripting provides a secure, private text input field intended for entering sensitive information such as passwords. The entered text is visually obscured and not displayed in plain text, mirroring the behavior of SwiftUI’s `SecureField`.

This component is useful in authentication forms, PIN inputs, or any context where user privacy is essential.

***

## Props

```ts
type SecureFieldProps = (
  | { title: string }
  | { label: VirtualNode }
) & {
  value: string
  onChanged: (value: string) => void
  prompt?: string
  autofocus?: boolean
  onFocus?: () => void
  onBlur?: () => void
}
```

### Property Descriptions

| Property    | Type                      | Description                                                                       |
| ----------- | ------------------------- | --------------------------------------------------------------------------------- |
| `title`     | `string`                  | A simple string label displayed with the field. _(Use either `title` or `label`)_ |
| `label`     | `VirtualNode`             | A custom view node label. _(Use instead of `title`)_                              |
| `value`     | `string`                  | The current value of the secure text field.                                       |
| `onChanged` | `(value: string) => void` | Callback function invoked when the value changes.                                 |
| `prompt`    | `string` (optional)       | A placeholder prompt shown when the field is empty.                               |
| `autofocus` | `boolean` (optional)      | Automatically focuses the field on mount. Defaults to `false`.                    |
| `onFocus`   | `() => void` (optional)   | Callback triggered when the field receives focus.                                 |
| `onBlur`    | `() => void` (optional)   | Callback triggered when the field loses focus.                                    |

***

## Example

```tsx
import { useState, VStack, SecureField } from "scripting"

function LoginForm() {
  const [password, setPassword] = useState("")

  return <VStack padding>
    <SecureField
      title="Password"
      value={password}
      onChanged={setPassword}
      prompt="Enter your password"
    />
  </VStack>
}
```

In this example:

- A secure input field is used to capture a password.
- The input is visually hidden to ensure privacy.
- The `prompt` guides the user when no text is entered.

***

## Notes

- Either `title` or `label` must be provided (but not both).
- The field behaves similarly to `TextField`, with added security features for sensitive input.
- This component is suitable for use in login, signup, and settings forms where password entry is required.



---
url: /guide/Views/Text input/SecureField/index_example.md
---

# Example

```tsx
import { useState, SecureField, VStack, Text, NavigationStack, Navigation, Script } from "scripting"

function Example() {
  const [password, setPassword] = useState('')

  return <NavigationStack>
    <VStack
      navigationTitle={"SecureField"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <SecureField
        title={"Password"}
        value={password}
        onChanged={setPassword}
        prompt={"Enter password"}
      />
      <Text>Password: {password}</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/Text input/TextField/index.md
---

# TextField

The `TextField` component in the Scripting app provides a declarative way to create a text input field, similar to SwiftUI’s `TextField`. It supports both single-line and multiline input, custom labels, placeholder prompts, scroll direction, focus handling, and line constraints.

This component is ideal for collecting short inputs like usernames or longer inputs like messages, with seamless integration into reactive view hierarchies.

***

## Props

```ts
type TextFieldProps = (
  | { title: string }
  | { label: VirtualNode }
) & {
  value: string
  onChanged: (value: string) => void
  prompt?: string
  axis?: Axis
  autofocus?: boolean
  onFocus?: () => void
  onBlur?: () => void
}
```

### Property Details

| Property    | Type                                      | Description                                                                              |
| ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------------- |
| `title`     | `string`                                  | A simple string label displayed alongside the field. _(Required if `label` is not used)_ |
| `label`     | `VirtualNode`                             | A custom node-based label. _(Use instead of `title`)_                                    |
| `value`     | `string`                                  | The current text input value.                                                            |
| `onChanged` | `(value: string) => void`                 | Callback triggered whenever the input text changes.                                      |
| `prompt`    | `string` (optional)                       | A hint or placeholder to guide the user’s input.                                         |
| `axis`      | `"horizontal"` \| `"vertical"` (optional) | Scroll direction when content exceeds bounds. Use `"vertical"` for multiline support.    |
| `autofocus` | `boolean` (optional)                      | If `true`, the field receives focus on mount. Default is `false`.                        |
| `onFocus`   | `() => void` (optional)                   | Called when the field gains focus.                                                       |
| `onBlur`    | `() => void` (optional)                   | Called when the field loses focus.                                                       |

***

## Example: Multiline, Vertically Scrollable TextField

```tsx
import { useState, VStack, TextField } from "scripting"

function ScrollableTextInput() {
  const [text, setText] = useState("")

  return <VStack padding>
    <TextField
      title="Message"
      value={text}
      onChanged={setText}
      prompt="Enter your message"
      axis="vertical"
      lineLimit={{ min: 3, max: 8 }}
    />
  </VStack>
}
```

### Behavior

- The field grows from 3 to 8 lines in height as text is entered.
- When content exceeds 8 lines, it becomes scrollable.
- The `prompt` is shown as placeholder text until input is provided.

***

## Example: Basic Single-Line TextField

```tsx
import { useState, VStack, TextField, Text } from "scripting"

function UsernameInput() {
  const [username, setUsername] = useState("")

  return <VStack padding>
    <TextField
      title="Username"
      value={username}
      onChanged={setUsername}
      prompt="Enter your username"
    />
    <Text>Username: {username}</Text>
  </VStack>
}
```

***

## Notes

- You must provide either `title` or `label`, not both.
- For multiline input, set `axis="vertical"` and define a `lineLimit`.
- `TextField` integrates seamlessly with state hooks like `useState` to enable real-time reactivity.
- Focus and blur events are helpful for validating or tracking input behavior.



---
url: /guide/Views/Text input/TextField/index_example.md
---

# Example

```tsx
import { useState, TextField, VStack, Text, NavigationStack, Navigation, Script } from "scripting"

function Example() {
  const [username, setUsername] = useState('')

  return <NavigationStack>
    <VStack
      navigationTitle={"TextField"}
    >
      <TextField
        title={"Username"}
        value={username}
        onChanged={setUsername}
        prompt={"Enter username"}
      />
      <Text>Username: {username}</Text>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()
```



---
url: /guide/Views/Time-based label views.md
---

# Time-based label views

Scripting provides a set of convenient time-related label components that wrap SwiftUI's `Text` styles. These components allow you to display live-updating or formatted date and time strings in widgets and views, with support for dynamic behaviors like relative time and timers.

***

## `DateLabel`

Displays a dynamic label representing a single point in time using a specified style. This is ideal for widgets that need to show time-based data even when not actively running.

### Props

```ts
type DateLabelProps = {
  date: Date
  style: 'date' | 'time' | 'timer' | 'relative' | 'offset'
} | {
  /**
   * @deprecated Use `date` instead
   */
  timestamp: number
  style: 'date' | 'time' | 'timer' | 'relative' | 'offset'
}
```

- `date`: A `Date` object representing the date to be displayed.

- `timestamp`: A UNIX timestamp in milliseconds representing the date to be , deprecated, use `date` instead.

- `style`: The display style. Can be:
  - `"date"`: e.g. `"June 3, 2019"`
  - `"time"`: e.g. `"11:23PM"`
  - `"timer"`: a running timer string
  - `"relative"`: e.g. `"2 hours, 23 minutes"`
  - `"offset"`: e.g. `+2 hours`, `-3 months`

### Example

```tsx
<DateLabel
  date={new Date}
  style="date"
/>

<DateLabel
  date={new Date}
  style="timer"
/>
```

***

## `DateRangeLabel`

Displays a localized textual representation of a time range between two dates.

### Props

```ts
type DateRangeLabelProps = {
  from: number
  to: number
}
```

| Property | Description                               |
| -------- | ----------------------------------------- |
| `from`   | The start date timestamp in milliseconds. |
| `to`     | The end date timestamp in milliseconds.   |

### Example

```tsx
<DateRangeLabel
  from={Date.now()}
  to={Date.now() + 1000 * 60}
/>
```

***

## `DateIntervalLabel`

Displays a formatted time interval, typically between two times on the same day (e.g., for event scheduling).

### Props

Same as `DateRangeLabelProps`:

```ts
type DateIntervalLabelProps = {
  from: number
  to: number
}
```

### Example

```tsx
let fromDate = new Date()
fromDate.setHours(9)
fromDate.setMinutes(30)

let toDate = new Date()
toDate.setHours(15)
toDate.setMinutes(30)

<DateIntervalLabel
  from={fromDate.getTime()}
  to={toDate.getTime()}
/>
```

Output example: `"9:30 AM – 3:30 PM"`

***

## `TimerIntervalLabel`

Displays a live-updating timer counting up or down between two timestamps. Optionally, the timer can pause at a specific point.

### Props

```ts
type TimerIntervalLabelProps = {
  from: number
  to: number
  pauseTime?: number
  countsDown?: boolean
  showsHours?: boolean
}
```

| Property     | Description                                                                                         |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `from`       | Start timestamp of the interval.                                                                    |
| `to`         | End timestamp of the interval.                                                                      |
| `pauseTime`  | (Optional) A timestamp at which the timer should pause. If undefined, the timer runs to completion. |
| `countsDown` | (Optional) Whether to count down. Defaults to `true`.                                               |
| `showsHours` | (Optional) Whether to show the hour component when over 60 minutes. Defaults to `true`.             |

### Example

```tsx
<TimerIntervalLabel
  from={Date.now()}
  to={Date.now() + 1000 * 60 * 12}
  pauseTime={Date.now() + 1000 * 60 * 10}
/>
```

This displays a countdown from 12 minutes and pauses at the 10-minute mark.



---
url: /guide/Views/Toolbars/index.md
---

# Toolbars

The `toolbar` property allows you to populate the navigation bar, bottom toolbar, or keyboard accessory area with custom UI elements. This system is modeled after SwiftUI’s toolbar API and provides fine-grained placement control across various regions of the user interface.

This feature is useful for adding primary or contextual actions, organizing control groups, and enhancing keyboard interactions.

***

## Definition

```ts
toolbar?: ToolBarProps
```

### ToolBarProps

```ts
type ToolBarProps = {
  bottomBar?: VirtualNode | VirtualNode[]
  cancellationAction?: VirtualNode | VirtualNode[]
  confirmationAction?: VirtualNode | VirtualNode[]
  destructiveAction?: VirtualNode | VirtualNode[]
  keyboard?: VirtualNode | VirtualNode[]
  navigation?: VirtualNode | VirtualNode[]
  primaryAction?: VirtualNode | VirtualNode[]
  principal?: VirtualNode | VirtualNode[]
  topBarLeading?: VirtualNode | VirtualNode[]
  topBarTrailing?: VirtualNode | VirtualNode[]
}
```

***

## Placement Options

Each property of `ToolBarProps` determines where the specified items will be placed. You can use either a single `VirtualNode` or an array of nodes for each region.

- **`automatic`** _(implicit)_: Lets the system decide optimal placement based on context. Not explicitly defined as a prop.
- **`bottomBar`**: Adds items to the bottom toolbar.
- **`cancellationAction`**: Represents a cancellation action, typically used in modal contexts.
- **`confirmationAction`**: Represents a confirmation action, typically used in modal contexts.
- **`destructiveAction`**: Represents a destructive action, often styled with visual emphasis (e.g., red).
- **`keyboard`**: Displays the item in the keyboard accessory view when a text input is focused.
- **`navigation`**: Represents a navigation action (e.g., back or close).
- **`primaryAction`**: Marks an item as the primary action in the current context.
- **`principal`**: Positions the item in the center of the top navigation bar.
- **`topBarLeading`**: Places items on the leading edge (left in LTR languages) of the top navigation bar.
- **`topBarTrailing`**: Places items on the trailing edge (right in LTR languages) of the top navigation bar.

***

## Example

```tsx
<VStack
  navigationTitle={"Toolbars"}
  navigationBarTitleDisplayMode={"inline"}
  toolbar={{
    topBarTrailing: [
      <Button
        title={"Select"}
        action={() => {}}
      />,
      <ControlGroup
        label={
          <Button
            title={"Add"}
            systemImage={"plus"}
            action={() => {}}
          />
        }
        controlGroupStyle={"palette"}
      >
        <Button
          title={"New"}
          systemImage={"plus"}
          action={() => {}}
        />
        <Button
          title={"Import"}
          systemImage={"square.and.arrow.down"}
          action={() => {}}
        />
      </ControlGroup>
    ],
    bottomBar: [
      <Button
        title={"New Sub Category"}
        action={() => {}}
      />,
      <Button
        title={"Add category"}
        action={() => {}}
      />
    ],
    keyboard: <HStack padding>
      <Spacer />
      <Button
        title={"Done"}
        action={() => {
          Keyboard.hide()
        }}
      />
    </HStack>
  }}
>
  <TextField
    title={"TextField"}
    value={text}
    onChanged={setText}
    textFieldStyle={"roundedBorder"}
    prompt={"Focus to show the keyboard toolbar"}
  />
</VStack>
```

This example demonstrates:

- A **top bar** with a "Select" button and a **control group** offering "New" and "Import" options.
- A **bottom toolbar** with actions for creating categories.
- A **keyboard accessory view** with a “Done” button aligned to the right, which hides the keyboard when pressed.

***

## Notes

- All toolbar items support dynamic updates—changes in state will automatically reflect in the toolbar UI.
- Items placed in the `keyboard` section will only be visible when a text input field is focused.
- `ControlGroup` components are useful for grouping related toolbar buttons visually and functionally.



---
url: /guide/Views/Toolbars/index_example.md
---

# Example

```tsx
import { Button, ControlGroup, HStack, Navigation, NavigationStack, Script, Spacer, TextField, useState, VStack } from "scripting"

function Example() {
  const [text, setText] = useState("")

  return <NavigationStack>
    <VStack
      navigationTitle={"Toolbars"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        topBarTrailing: [
          <Button
            title={"Select"}
            action={() => { }}
          />,
          <ControlGroup
            label={
              <Button
                title={"Add"}
                systemImage={"plus"}
                action={() => { }}
              />
            }
            controlGroupStyle={"palette"}
          >
            <Button
              title={"New"}
              systemImage={"plus"}
              action={() => { }}
            />
            <Button
              title={"Import"}
              systemImage={"square.and.arrow.down"}
              action={() => { }}
            />
          </ControlGroup>
        ],
        bottomBar: [
          <Button
            title={"New Sub Category"}
            action={() => { }}
          />,
          <Button
            title={"Add category"}
            action={() => { }}
          />
        ],
        keyboard: <HStack
          padding
        >
          <Spacer />
          <Button
            title={"Done"}
            action={() => {
              Keyboard.hide()
            }}
          />
        </HStack>
      }}
      padding
    >
      <TextField
        title={"TextField"}
        value={text}
        onChanged={setText}
        textFieldStyle={"roundedBorder"}
        prompt={"Focus to show the keyboard toolbar"}
      />
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/View groupings/ControlGroup.md
---

# ControlGroup

```tsx
import { Button, ControlGroup, ControlGroupStyle, Label, List, Navigation, NavigationStack, Picker, Script, Text, useMemo, useState } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()
  const [style, setStyle] = useState<ControlGroupStyle>("palette")
  const styles = useMemo<ControlGroupStyle[]>(() => [
    'automatic',
    'compactMenu',
    'menu',
    'navigation',
    'palette'
  ], [])

  return <NavigationStack>
    <List
      navigationTitle={"ControlGroup"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />,
        confirmationAction: [
          <ControlGroup
            label={
              <Label
                title={"Plus"}
                systemImage={"plus"}
              />
            }
            controlGroupStyle={style}
          >
            <Button
              title={"Edit"}
              systemImage={"pencil"}
              action={() => { }}
            />
            <Button
              title={"Delete"}
              systemImage={"trash"}
              role={"destructive"}
              action={() => { }}
            />
          </ControlGroup>
        ]
      }}
    >
      <Picker
        title={"Control Group Style"}
        value={style}
        onChanged={setStyle as any}
      >
        {styles.map(style =>
          <Text tag={style}>{style}</Text>
        )}
      </Picker>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/View groupings/ForEach/index.md
---

# ForEach

The `ForEach` component renders a dynamic list of child views. It is used to display collections, create editable lists, and enable system-standard interactions such as swipe-to-delete. It is fully integrated with the Scripting app’s `Observable` state system and mirrors the design of SwiftUI’s `ForEach`.

`ForEach` supports two usage modes:

1. **Deprecated mode**: `count + itemBuilder`
2. **Recommended mode**: `data: Observable<T[]> + builder`

***

## 1. Type Definitions

## ForEachDeprecatedProps (Not Recommended)

```ts
type ForEachDeprecatedProps = {
  count: number;
  itemBuilder: (index: number) => VirtualNode;
  onDelete?: (indices: number[]) => void;
  onMove?: (indices: number[], newOffset: number) => void;
};
```

### Property Details

#### count: number

Specifies how many items to render. The `itemBuilder` function will be called for indices from 0 to `count - 1`.

#### itemBuilder(index)

Builds a `VirtualNode` for each index.

#### onDelete(indices)

Enables system-standard swipe-to-delete when the ForEach is placed inside a `List`.
This callback is invoked after the row has already been removed from the list UI.
You must manually delete the corresponding items from your data source inside this callback.

#### onMove(indices, newOffset)

Enables drag-to-reorder behavior.
To disable item movement, pass `null`.

***

## 2. ForEachProps (Recommended)

```ts
type ForEachProps<T extends { id: string }> =
  | ForEachDeprecatedProps
  | {
      data: Observable<T[]>;
      builder: (item: T, index: number) => VirtualNode;
      editActions?: "delete" | "move" | "all" | null;
    };
```

### Property Details

#### data: Observable\<T\[]>

An observable array of items.
Each item **must** contain a unique `id: string`.

Benefits of using `Observable<T[]>`:

- Automatic refresh when the collection changes
- Supports animation
- Behavior closer to SwiftUI’s `ForEach($items)`
- Integrates cleanly with `List`, `NavigationStack`, and other components

#### builder(item, index)

Builds a VirtualNode for the element at the given index.

**Important: You must provide a unique `key` (usually `item.id`) on the returned node.**

#### editActions: "delete" | "move" | "all" | null

Defines the editing capabilities of the ForEach component.

| Value      | Description                        |
| ---------- | ---------------------------------- |
| `"delete"` | Enables deletion only              |
| `"move"`   | Enables reordering only            |
| `"all"`    | Enables both deletion and movement |
| `null`     | No editing actions (default)       |

When used inside a `List`, these actions automatically map to system-standard interactions.

***

## 3. ForEachComponent Interface

```ts
interface ForEachComponent {
  <T extends { id: string }>(props: ForEachProps<T>): VirtualNode;
}
```

The component is generic and supports any item type containing an `id`.

***

## 4. Enabling System-Standard Deletion (Example)

When `ForEach` is placed inside a `List`, using `data` and `builder` will automatically activate swipe-to-delete. The only requirement is that each item has a unique `id`.

### Example

```tsx
function View() {
  const fruits = useObservable(() =>
    ["Apple", "Bananer", "Papaya", "Mango"].map((name, index) => ({
      id: index.toString(),
      name,
    }))
  );

  return (
    <NavigationStack>
      <List
        navigationTitle="Fruits"
        toolbar={{
          topBarTrailing: <EditButton />,
        }}>
        <ForEach data={fruits} builder={(item, index) => <Text key={item.id}>{item.name}</Text>} />
      </List>
    </NavigationStack>
  );
}
```

***

## 5. Best Practices and Usage Guidelines

### 1. Prefer the `data: Observable<T[]>` API

This mode provides:

- Better performance
- Full type inference
- Proper list diffing and animations
- Consistent behavior with SwiftUI

### 2. Every item must have a unique `id: string`

This ensures:

- Correct diff computation
- Smooth animations
- Accurate deletion and movement behavior

### 3. Always define `key={item.id}` in the builder

Failing to do so may result in:

- Broken animations
- Incorrect row updates
- Misaligned delete/move behavior

### 4. To support editing, place ForEach inside a `List`

And optionally add an `EditButton`, for example:

```tsx
toolbar={{
  topBarTrailing: <EditButton />
}}
```



---
url: /guide/Views/View groupings/ForEach/iterating.md
---

# Example

```tsx
import { Button, Font, ForEach, List, Navigation, NavigationStack, Script, Section, Text, useObservable, VStack } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  const namedFonts = useObservable(() => {
    return [
      "largeTitle",
      "title",
      "headline",
      "body",
      "caption"
    ].map(e => ({
      id: e,
      name: e as Font
    }))
  })

  return <NavigationStack>
    <List
      navigationTitle={"Iterating"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section
        header={
          <Text
            textCase={null}
          >ForEach</Text>
        }
      >
        <ForEach
          data={namedFonts}
          builder={(namedFont) => {
            return <Text
              key={namedFont.id}
              font={namedFont.name}
            >{namedFont.name}</Text>
          }}
        />
      </Section>

      <Section
        header={
          <Text
            textCase={null}
          >Iterating in code block</Text>
        }
      >
        <VStack>
          {namedFonts.value.map(namedFont =>
            <Text
              font={namedFont.name}
            >{namedFont.name}</Text>
          )}
        </VStack>
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/View groupings/Form.md
---

# Form

```tsx
import { Button, Form, Navigation, NavigationStack, Picker, Script, Section, Text, Toggle, useState } from "scripting"

type NotifyMeAboutType = "directMessages" | "mentions" | "anything"
type ProfileImageSize = "large" | "medium" | "small"

function Example() {
  const dismiss = Navigation.useDismiss()
  const [notifyMeAbout, setNotifyMeAbout] = useState<NotifyMeAboutType>("directMessages")
  const [playNotificationSounds, setPlayNotificationSounds] = useState(true)
  const [profileImageSize, setprofileImageSize] = useState<ProfileImageSize>("medium")
  const [sendReadReceipts, setSendReadReceipts] = useState(false)

  return <NavigationStack>
    <Form
      navigationTitle={"Form"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section
        header={<Text>Notifications</Text>}
      >
        <Picker
          title={"Notify Me About"}
          value={notifyMeAbout}
          onChanged={setNotifyMeAbout as any}
        >
          <Text
            tag={"directMessages"}
          >Direct Messages</Text>
          <Text
            tag={"mentions"}
          >Mentions</Text>
          <Text
            tag={"anything"}
          >Anything</Text>
        </Picker>

        <Toggle
          title={"Play notification sounds"}
          value={playNotificationSounds}
          onChanged={setPlayNotificationSounds}
        />
        <Toggle
          title={"Send read receipts"}
          value={sendReadReceipts}
          onChanged={setSendReadReceipts}
        />
      </Section>

      <Section
        header={<Text>User Profiles</Text>}
      >
        <Picker
          title={"Profile Image Size"}
          value={profileImageSize}
          onChanged={setprofileImageSize as any}
        >
          <Text
            tag={"large"}
          >Large</Text>
          <Text
            tag={"medium"}
          >Medium</Text>
          <Text
            tag={"small"}
          >Small</Text>
        </Picker>

        <Button
          title={"Clear Image Cache"}
          action={() => { }}
        />
      </Section>
    </Form>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/View groupings/Group.md
---

# Group

```tsx
import { Button, Group, List, Navigation, NavigationStack, Script, Section, Text, VStack } from "scripting"

function Example() {
  const dimiss = Navigation.useDismiss()

  return <NavigationStack>
    <List
      navigationTitle={"Group"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dimiss}
        />
      }}
    >
      <Section
        footer={
          <Text>Apply the headline font to all Text views</Text>
        }
      >
        <Group
          font={"headline"}
        >
          <Text>Scripting</Text>
          <Text>TypeScript</Text>
          <Text>TSX</Text>
        </Group>
      </Section>

      <Section
        footer={
          <Text>Group some views as a view</Text>
        }
      >
        <VStack>
          <Group
            foregroundStyle={"red"}
          >
            <Text>1</Text>
            <Text>2</Text>
            <Text>3</Text>
            <Text>4</Text>
            <Text>5</Text>
            <Text>6</Text>
            <Text>7</Text>
          </Group>
          <Text>8</Text>
        </VStack>
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/View groupings/GroupBox.md
---

# GroupBox

```tsx
import { Button, GroupBox, Label, Navigation, NavigationStack, Script, ScrollView, Text, Toggle, useState, VStack } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()
  const [userAgreed, setUserAgreed] = useState(false)
  const agreementText = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."

  return <NavigationStack>
    <VStack
      navigationTitle={"GroupBox"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <GroupBox
        label={
          <Label
            title={"End-User Agreement"}
            systemImage={"building.columns"}
          />
        }
      >
        <ScrollView
          frame={{
            height: 100,
          }}
        >
          <Text>{agreementText}</Text>
        </ScrollView>
        <Toggle
          value={userAgreed}
          onChanged={setUserAgreed}
        >
          <Text>I agree to the above terms</Text>
        </Toggle>
      </GroupBox>
    </VStack>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/View groupings/LabeledContent.md
---

# LabeledContent

```tsx
import { Button, Form, Image, Label, LabeledContent, Menu, Navigation, NavigationStack, Script, Section, Text } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()

  return <NavigationStack>
    <Form
      navigationTitle={"LabeledContent"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />
      }}
    >
      <Section
        header={<Text>value shorthand</Text>}
      >
        {/* A `value` string renders as the trailing content. */}
        <LabeledContent title={"Version"} value={"1.0.0"} />
        <LabeledContent title={"Build"} value={"24"} />
      </Section>

      <Section
        header={<Text>custom content</Text>}
      >
        {/* Provide `children` instead of `value` for a custom trailing view. */}
        <LabeledContent title={"Status"}>
          <Image
            systemName={"checkmark.seal.fill"}
            foregroundStyle={"systemGreen"}
          />
        </LabeledContent>
      </Section>

      <Section
        header={<Text>custom label</Text>}
      >
        {/* Provide a `label` view instead of a `title` string. */}
        <LabeledContent
          label={
            <Label
              title={"Battery"}
              systemImage={"battery.100"}
            />
          }
          value={"100%"}
        />
      </Section>

      <Section
        header={<Text>menuOrder modifier</Text>}
        footer={<Text>menuOrder controls the order of items within a Menu or menu-style Picker.</Text>}
      >
        <Menu
          title={"Fixed order"}
          menuOrder={"fixed"}
        >
          <Button title={"First"} action={() => { }} />
          <Button title={"Second"} action={() => { }} />
          <Button title={"Third"} action={() => { }} />
        </Menu>
      </Section>
    </Form>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/View groupings/Section.md
---

# Section

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text, useState } from "scripting"

function Example() {
  const dismiss = Navigation.useDismiss()
  const [isExpanded, setIsExpanded] = useState(true)

  return <NavigationStack>
    <List
      navigationTitle={"Section"}
      navigationBarTitleDisplayMode={"inline"}
      toolbar={{
        cancellationAction: <Button
          title={"Done"}
          action={dismiss}
        />,
      }}
    >
      <Section>
        <Text>Row 1</Text>
        <Text>Row 2</Text>
        <Text>Row 3</Text>
        <Text>Row 4</Text>
      </Section>

      <Section
        header={<Text>Section with header</Text>}
      >
        <Text>Row 1</Text>
        <Text>Row 2</Text>
        <Text>Row 3</Text>
        <Text>Row 4</Text>
      </Section>

      <Section
        footer={<Text>Section with footer</Text>}
      >
        <Text>Row 1</Text>
        <Text>Row 2</Text>
        <Text>Row 3</Text>
        <Text>Row 4</Text>
      </Section>

      <Section
        header={
          <Text
            onTapGesture={() => setIsExpanded(!isExpanded)}
          >Collapsable Section</Text>
        }
        isExpanded={isExpanded}
        onChanged={setIsExpanded}
      >
        <Text>Row 1</Text>
        <Text>Row 2</Text>
        <Text>Row 3</Text>
        <Text>Row 4</Text>
      </Section>
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Views/WebView.md
---

# WebView

```tsx
import { Button, HStack, Image, List, Navigation, NavigationStack, Script, Section, Text, TextField, useMemo, useState, VStack, WebView } from "scripting"

function WebViewControllerExample() {
  const [logs, setLogs] = useState<{
    content: string
    error: boolean
  }[]>([])

  function addLog(content: string, error = false) {
    setLogs(logs => [...logs, { content, error }])
  }

  async function runCode() {
    setLogs([])
    const controller = new WebViewController()

    addLog("WebViewController created.")
    addLog("Start loading...")

    if (await controller.loadURL("https://github.com")) {
      addLog("Website is loaded.")
      addLog("Calling controller.evaluateJavaScript...")
      const title = await controller.evaluateJavaScript<string>("document.title")

      if (title != null) {
        addLog(`Title: ${title}`)
      } else {
        addLog("Failed to get the title.", true)
      }
    } else {
      addLog("Failed to load the website.", true)
    }

    controller.dispose()
    addLog("The controller is disposed.")
  }

  return <Section
    header={
      <Text>WebView controller</Text>
    }
  >
    <VStack
      frame={{
        maxWidth: "infinity"
      }}
      alignment={"leading"}
    >
      <Text font={"headline"}>This example will follow these steps:</Text>
      <VStack
        padding={{
          leading: 16
        }}
        spacing={16}
        foregroundStyle={"secondaryLabel"}
        alignment={"leading"}
      >
        <Text>Create a WebViewController instane</Text>
        <Text>Load https://github.com</Text>
        <Text>Call evaluateJavaScript and get the title of the website</Text>
      </VStack>
      <HStack
        alignment={"center"}
        frame={{
          maxWidth: "infinity"
        }}
      >
        <Button
          title={"Run"}
          action={runCode}
        />
      </HStack>

      <VStack
        alignment={"leading"}
        spacing={8}
      >
        {logs.map(log =>
          <Text
            font={"caption"}
            monospaced
            padding={{
              leading: 16
            }}
            foregroundStyle={log.error ? "systemRed" : "systemGreen"}
          >{log.content}</Text>
        )}
      </VStack>
    </VStack>
  </Section>
}

function PresentWebViewExample() {

  function run() {
    const controller = new WebViewController()
    controller.loadURL("https://github.com")

    controller.present({
      fullscreen: true,
      navigationTitle: "Github"
    }).then(() => {
      console.log("WebView is dismissed")
      controller.dispose()
    })
  }

  return <Section
    header={
      <Text>Present a WebView as a independent page</Text>
    }
  >
    <Button
      title={"Present"}
      action={run}
    />
  </Section>
}

function EmbedAWebViewExample() {
  const controller = useMemo(() => new WebViewController(), [])
  const [url, setUrl] = useState("")

  return <Section
    header={
      <Text>Embed a WebView</Text>
    }
  >
    <VStack>
      <HStack>
        <Button action={() => {
          controller.goBack()
        }}>
          <Image
            systemName={"arrow.left"}
          />
        </Button>
        <Button action={() => {
          controller.goForward()
        }}>
          <Image
            systemName={"arrow.right"}
          />
        </Button>
        <Button action={() => {
          controller.reload()
        }}>
          <Image
            systemName={"arrow.clockwise"}
          />
        </Button>
        <TextField
          title={"Website URL"}
          textFieldStyle={"roundedBorder"}
          value={url}
          onChanged={setUrl}
          keyboardType={"URL"}
          textInputAutocapitalization={"never"}
          frame={{
            maxWidth: "infinity"
          }}
        />
        <Button
          action={() => controller.loadURL(url)}
        >
          <Image
            systemName={"arrow.right.circle"}
          />
        </Button>
      </HStack>
      <WebView
        controller={controller}
        frame={{
          height: 400
        }}
      />
    </VStack>
  </Section>
}

function Example() {
  return <NavigationStack>
    <List
      navigationTitle={"WebView"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <WebViewControllerExample />
      <PresentWebViewExample />
      <EmbedAWebViewExample />
    </List>
  </NavigationStack>
}

async function run() {
  await Navigation.present({
    element: <Example />
  })

  Script.exit()
}

run()

```



---
url: /guide/Widget/AccessoryWidgetBackground.md
---

# AccessoryWidgetBackground

An adaptive background view that provides a standard appearance based on the widget’s environment.

## Overview

The `AccessoryWidgetBackground` component is designed to be used inside accessory widgets—such as Lock Screen widgets or StandBy widgets—where it applies a system-defined background appropriate for the widget's context.

Using this view ensures that your widget maintains visual consistency with the surrounding system UI, adapting automatically to light and dark modes, transparency effects, and other environmental styling set by the system.

You typically use `AccessoryWidgetBackground` as a background layer in combination with other views, such as `ZStack`, to provide system-adaptive styling while layering custom content above it.

## Example

```tsx
import { AccessoryWidgetBackground, Text, ZStack } from "scripting"

function AccessoryView() {
  return (
    <ZStack>
      <AccessoryWidgetBackground />
      <Text font="caption">Weather</Text>
    </ZStack>
  )
}
```

In this example, `AccessoryWidgetBackground` provides the adaptive system background, and the `Text` element is rendered on top of it. This layout is useful for Lock Screen widgets where consistent and legible appearance is important.

## Best Practices

- Always place `AccessoryWidgetBackground` beneath your content using a stacking layout like `ZStack`.
- Do not apply custom colors or effects directly to `AccessoryWidgetBackground`; it automatically adapts to system appearance.
- Combine it with other SwiftUI-inspired components to maintain a consistent style with iOS system widgets.

## Compatibility

This component is intended for use in accessory widgets and may not have any visual effect outside that context. Use it to ensure your widget blends seamlessly with the native iOS design system.



---
url: /guide/Widget/Animation for Widget and LiveActivity.md
---

# Animation for Widget and LiveActivity

These APIs allow you to display animation in a widget.

## `AnimatedFrames` Component

### Description

The `AnimatedFrames` component allows you to display a frame animation in a widget by cycling through the provided child views as frames. The duration of the animation is customizable, and each frame corresponds to a view passed in as a child element.

### Props

- **`duration`**: `DurationInSeconds`\
  The animation duration, in seconds.

- **`children`**: `VirtualNode[]`\
  The array of views to toggle as the frames of the animation. Each child will be displayed sequentially during the animation.

### Example

```tsx
<AnimatedFrames duration={4}>
  <Circle fill="red" frame={{width: 20, height: 20}} />
  <Circle fill="red" frame={{width: 25, height: 25}} />
  <Circle fill="red" frame={{width: 30, height: 30}} />
  <Circle fill="red" frame={{width: 35, height: 35}} />
</AnimatedFrames>
```

***

## `AnimatedGif` Component

### Description

The `AnimatedGif` component renders an animated GIF in a widget. You can provide a custom path to the GIF file, and optionally, a duration for the animation.

### Props

- **`path`**: `string`\
  The file path of the GIF image.

- **`duration`**: `DurationInSeconds` _(Optional)_\
  The animation duration in seconds. If not provided, the default duration is used.

### Example

```tsx
<AnimatedGif
  path={Path.join(Script.directory, "test.gif")}
  duration={4}
/>
```

***

## `SwingAnimation` Type

### Description

The `SwingAnimation` type defines the configuration for animating a view in a swinging motion along the X and Y axes.

### Props

- **`duration`**: `DurationInSeconds`\
  The animation duration, in seconds.

- **`distance`**: `number`\
  The distance the view swings along the given axis.

***

## `ClockHandRotationEffectPeriod` Type

### Description

The `ClockHandRotationEffectPeriod` type is used to define the period of rotation for the clock hand effect. You can use predefined values like `"hourHand"`, `"minuteHand"`, or `"secondHand"`, or provide a custom duration.

***

## `AnimatedImage` Component

### Description

The `AnimatedImage` component renders an animated image in a widget. You can display either `SFSymbol` images or `UIImage` objects. The animation duration and content mode (fit or fill) can be customized.

### Props

- **`systemImages`**: `(string | { name: string; variableValue: number })[]` _(Optional)_\
  An array of `SFSymbol` names and variable values to display as a sequence of animated images.

- **`images`**: `UIImage[]` _(Optional)_\
  An array of `UIImage` objects to use as the animated frames.

- **`contentMode`**: `ContentMode` _(Optional)_\
  A flag indicating whether the image should fit or fill the parent context. The default is `"fit"`.\
  Possible values: `"fit"`, `"fill"`.

- **`duration`**: `DurationInSeconds`\
  The animation duration, in seconds.

### Example (using `SFSymbol`)

```tsx
<AnimatedImage
  duration={6}
  systemImages={[
    {name: "chart.bar.fill", variableValue: 0},
    {name: "chart.bar.fill", variableValue: 0.3},
    {name: "chart.bar.fill", variableValue: 0.6},
    {name: "chart.bar.fill", variableValue: 1},
  ]}
  contentMode="fit"
/>
```

### Example (using `UIImage`)

```tsx
const image1 = Path.join(Script.directory, "image1.png")
const image2 = Path.join(Script.directory, "image2.png")

<AnimatedImage
  duration={4}
  images={[
    UIImage.fromFile(image1),
    UIImage.fromFile(image2),
  ]}
  contentMode="fill"
/>
```

***

## `CommonViewProps` Type

### Description

This type defines common properties for views that support animation effects, including swing animations and clock hand rotation effects.

### Props

- **`swingAnimation`**: `{ x?: SwingAnimation, y?: SwingAnimation }` _(Optional)_\
  Defines the animation configuration for swinging the view along the X and/or Y axis. Each axis can have its own animation settings:
  - **`x`**: The animation configuration for the horizontal axis.
  - **`y`**: The animation configuration for the vertical axis.

- **`clockHandRotationEffect`**: `ClockHandRotationEffectPeriod | { anchor: KeywordPoint | Point, period: ClockHandRotationEffectPeriod }` _(Optional)_\
  Defines the rotation effect for simulating a clock hand. You can specify the anchor point (optional) and the period (e.g., `"hourHand"`, `"minuteHand"`, `"secondHand"`), or provide a custom duration for the rotation.

### Example (Swing Animation)

```tsx
<Circle
  fill="systemRed"
  frame={{width: 50, height: 50}}
  swingAnimation={{
    x: {duration: 4, distance: 250},
    y: {duration: 2, distance: 50},
  }}
/>
```

### Example (Clock Hand Rotation Effect)

```tsx
<Circle
  fill="systemBlue"
  frame={{width: 50, height: 50}}
  clockHandRotationEffect="minuteHand"
/>
```



---
url: /guide/Widget/Tinted Mode Adaptation Guide.md
---

# Tinted Mode Adaptation Guide

iOS 18 introduces a new widget rendering mode called **accented mode**, which tints the widget’s content using system-defined accent colors. To support this behavior in your widgets, the **Scripting** app provides three view modifiers:

- `widgetAccentable`
- `widgetAccentedRenderingMode`
- `widgetBackground`

These modifiers allow you to control which parts of your widget participate in the system’s accenting logic, enabling more expressive and adaptable designs.

***

## `widgetAccentable`

### Description

Marks a view and all of its subviews as part of the **accented group**. When a widget is displayed in **accented rendering mode**, the system applies a distinct tint color to the accented group and another to the default group. The colors are applied as if views were template images — the system ignores any explicit color and only uses the view’s alpha channel.

This modifier helps create layered visual effects, especially useful in tinted widgets where you want to differentiate between elements.

### Usage

```tsx
<VStack>
  <Text
    widgetAccentable
    font="caption"
  >
    MON
  </Text>
  <Text font="title">
    6
  </Text>
</VStack>
```

In the above example:

- The first `Text` is added to the **accented group**, and will be tinted with the accent color.
- The second `Text` belongs to the **default group**, and will be tinted with the default (typically lighter) color.

***

## `widgetAccentedRenderingMode` (for `Image` components)

### Description

Defines how an `Image` should be rendered when displayed in **accented widget mode**. This modifier allows you to fine-tune how image content responds to system tinting.

### Available Modes

- `'accented'`: Renders the image as part of the **accented group**, using the accent color.
- `'accentedDesaturated'`: Converts the image’s luminance to alpha and applies the accent color.
- `'desaturated'`: Converts the image’s luminance to alpha and applies the default group color.
- `'fullColor'`: Preserves the image’s original colors with no tinting — available only on iOS.

### Usage

```tsx
<Image
  filePath="/path/to/image.png"
  widgetAccentedRenderingMode="fullColor"
/>
```

This ensures the image will retain its full color and not be affected by system tints — useful for branding elements or complex images where tinting would degrade clarity.

***

## `widgetBackground`

### Description

The `widgetBackground` modifier allows you to define background colors or shapes in a way that automatically adapts to **accented mode**. When the widget is displayed in accented mode, the background is **automatically hidden** to avoid being forced into a white or unintended rendering by the system.

This modifier is especially important because iOS 18 **ignores background colors** in accented mode, unless transparency (`alpha`) is used. With `widgetBackground`, you can safely define decorative backgrounds without worrying about white overlays.

### Supported Formats

You can use the following formats:

#### Solid Color

```tsx
<Text widgetBackground="systemGray5">
  Hello
</Text>
```

#### Dynamic Light/Dark Color

```tsx
<Text
  widgetBackground={{
    light: "white",
    dark: "black"
  }}
>
  Mode-aware Background
</Text>
```

#### Shape with Style

```tsx
<Text
  widgetBackground={{
    style: "systemGray6",
    shape: {
      type: "rect",
      cornerRadius: 12,
      style: "continuous"
    }
  }}
>
  Shaped Background
</Text>
```

### Notes

- Background is hidden in **accented mode**.
- Background is fully rendered in **default or full-color modes**.
- Works seamlessly with `widgetAccentable` and layering effects.

***

## Behavior Notes (iOS 18+ Specific)

- In **tinted mode**, **all colors (including background colors)** are ignored unless alpha is less than `1`. This means setting a solid background color will be rendered as white if not made semi-transparent.
- Use `alpha` values to introduce visual hierarchy. For example, a fully opaque accentable element (`alpha = 1`) will be strongly tinted, while one with `alpha = 0.3` will appear more subtle.
- **Do not rely on color values** directly for styling in accented widgets — use tint layering via the accent group instead.
- **Use `widgetBackground`** instead of `background` when defining decorative backgrounds, to ensure proper behavior under accenting.

***

## Example

```tsx
<VStack
  widgetBackground={{
    style: "systemGray6",
    shape: {
      type: "rect",
      cornerRadius: 12
    }
  }}
  spacing={4}
>
  <Image
    filePath="/path/to/icons/calendar.png"
    widgetAccentedRenderingMode="accentedDesaturated"
  />
  <Text widgetAccentable font="caption">
    MON
  </Text>
  <Text font="title">
    6
  </Text>
</VStack>
```

This layout:

- Applies a rounded background that is visible only in non-accented modes.
- Places the icon and weekday label in the **accented group**.
- Leaves the date number in the **default group**.
- Maintains consistent visual separation, even with iOS's tinting behavior.

***

## Tips

- Use `widgetAccentable` to group multiple views into the accent layer — don’t apply it to the entire widget unless necessary.
- For icons or logos, consider using `widgetAccentedRenderingMode="fullColor"` if the image must retain its original branding.
- Use `widgetBackground` in place of `background` to ensure backgrounds disappear cleanly in accented mode.
- Use semi-transparent fills (`alpha < 1`) for layered effects that survive tint flattening.

***

This setup ensures your widgets are fully optimized for iOS 18’s dynamic accenting system, while retaining control over visual composition and user experience.



---
url: /guide/Widget/Widget API.md
---

# Widget API

The `Widget` class provides static methods and properties to interact with home screen widgets created using the Scripting app. This API enables rendering widgets, handling configuration parameters, previewing widget layouts, and managing widget timelines.

***

## Class: `Widget`

This class cannot be instantiated. All its members are static.

***

### Properties

#### `Widget.family: WidgetFamily`

Returns the widget family configured by the user. The `WidgetFamily` determines the size and layout constraints of the widget.
Common values include:

- `"systemSmall"` – small widget
- `"systemMedium"` – medium widget
- `"systemLarge"` – large widget
- `"accessoryRectangular"` – Lock Screen rectangular widget
- `"accessoryCircular"` – Lock Screen circular widget

> **Type:** `WidgetFamily`

***

#### `Widget.displaySize: WidgetDisplaySize`

Returns the widget’s display size in points (width and height), depending on its family and the device's screen.

> **Type:** `{ width: number; height: number }`

***

#### `Widget.parameter: string`

Returns the value of the parameter configured in the widget’s settings when the script is executed via a home screen widget tap.
This is useful for customizing widget content dynamically based on user-defined input.

> **Type:** `string`

***

### Methods

#### `Widget.present(element, options?): void`

##### Type Definition

```ts
Widget.present(element: VirtualNode, reloadPolicy?: WidgetReloadPolicy): void

Widget.present(element: VirtualNode, optoins?: {
  reloadPolicy?: WidgetReloadPolicy
  relevance?: WidgetRelevance
}): void
```

Renders the widget UI using a React-like virtual node (`JSX.Element`).
You can optionally specify a reload policy to instruct the system when to request an updated timeline.

##### Parameters

- `element` (`VirtualNode`) – A JSX element representing the widget UI tree.
- `reloadPolicy` (`WidgetReloadPolicy`, optional) – Specifies when WidgetKit should request a new timeline. Defaults to `atEnd`.
- `relevance` (`WidgetRelevance`, optional) – Specifies the relevance of the widget, which affects its display priority.

##### Example

```tsx
function WidgetView() {
  return <VStack>
    <Image
      systemName="globe"
      resizable
      scaleToFit
      frame={{
        width: 28,
        height: 28
      }}
    />
    <Text>Hello Scripting!</Text>
  </VStack>
}

Widget.present(<WidgetView />, {
  policy: "after",
  date: new Date(Date.now() + 1000 * 60 * 5) // 5 minutes later
})
```

> **Returns:** `void`

***

#### `Widget.preview(options?: PreviewOptions): Promise<void>`

Previews the widget with the specified configuration. This method is available only in `index.tsx`, not in `widget.tsx` or `intent.tsx`.

##### Parameters

- `options` (optional) – Configuration for previewing the widget.

```ts
interface PreviewOptions {
  family?: WidgetFamily
  parameters?: {
    options: Record<string, string> // Map of parameter names to JSON stringified values
    default: string                 // The default parameter key to use
  }
}
```

##### Example

```tsx
const options = {
  "Param 1": JSON.stringify({ color: "red" }),
  "Param 2": JSON.stringify({ color: "blue" }),
}

await Widget.preview({
  family: "systemSmall",
  parameters: {
    options,
    default: "Param 1"
  }
})
console.log("Widget preview dismissed")
```

> **Returns:** `Promise<void>`
> Throws an error if parameters are not formatted correctly.

***

#### `Widget.reloadAll(): void`

Requests WidgetKit to reload the timelines for **all** widgets created using the Scripting app.
This is useful when the data or appearance of widgets may have changed and needs to be refreshed.

> **Returns:** `void`

***

#### `Widget.openApp(bundleID: string): void`

Opens the app identified by the specified bundle ID. This API requires Scripting PRO.

##### Parameters

- `bundleID` (`string`) – The bundle ID of the app to open, such as `"com.apple.MobileSMS"`.

##### Example

```ts
Widget.openApp("com.apple.MobileSMS")
```

> **Returns:** `void`

***

## Related Types

### `WidgetFamily`

A string enum representing available widget sizes. Typical values:

```ts
type WidgetFamily =
  | "systemSmall"
  | "systemMedium"
  | "systemLarge"
  | "accessoryCircular"
  | "accessoryRectangular"
```

***

### `WidgetDisplaySize`

An object representing the widget’s current width and height in points:

```ts
interface WidgetDisplaySize {
  width: number
  height: number
}
```

***

### `WidgetReloadPolicy`

An object specifying when WidgetKit should request a new timeline:

```ts
type WidgetReloadPolicy =
  | { policy: "atEnd" } // Reload after the timeline ends (default)
  | { policy: "after", date: Date } // Reload after a specific date
```

***

### `WidgetRelevance`

An object specifying the relevance of a widget:

```ts
type WidgetRelevance = {
  score: number // A score used to determine widget priority
  duration?: number // Optional duration in seconds
}
```

***

## Usage Notes

- `Widget.present` should be used inside `widget.tsx` to define and display the actual widget content.
- `Widget.preview` is a development utility used in `index.tsx` to simulate how widgets look and behave with different parameters.
- You must call `Script.exit()` at the end of the widget script to ensure proper lifecycle handling.
- When using parameters, remember to parse `Widget.parameter` as JSON if it contains structured data.



---
url: /guide/Widget/Widget Background in Tinted Mode.md
---

# Widget Background in Tinted Mode

The `widgetBackground` modifier is used to define background styles specifically for **widgets**, with behavior optimized for **iOS 18’s accented (tinted)** rendering mode.

## Purpose

In **accented mode**, iOS displays nearly all view colors—including backgrounds—as white, unless the view is explicitly marked with `widgetAccentable`. This can cause unintended visual issues in widgets.

The `widgetBackground` modifier addresses this by:

- **Automatically hiding the background** when the widget is displayed in accented mode.
- **Rendering the background normally** in all other display modes (default or full-color).

This ensures your widget layout remains visually consistent and unaffected by system-imposed tinting rules.

***

## Supported Background Variants

The `widgetBackground` modifier accepts several input formats:

### 1. **Solid Color (ShapeStyle)**

Apply a simple color to the background.

```tsx
<Text widgetBackground="systemBlue">
  Hello
</Text>
```

***

### 2. **Dynamic Color (DynamicShapeStyle)**

Apply different styles for light and dark modes.

```tsx
<Text
  widgetBackground={{
    light: "white",
    dark: "black"
  }}
>
  Mode-aware Background
</Text>
```

***

### 3. **Shape with Fill Style**

Use a **shape** along with a **fill style**. This form provides structured and stylized backgrounds.

```tsx
<Text
  widgetBackground={{
    style: "systemGray6",
    shape: {
      type: "rect",
      cornerRadius: 12,
      style: "continuous"
    }
  }}
>
  Rounded Background
</Text>
```

You may use any supported built-in or custom shape types, such as:

- `'rect'`, `'circle'`, `'capsule'`, `'ellipse'`, `'buttonBorder'`, `'containerRelative'`
- Custom rounded rectangles with `cornerRadius`, `cornerSize`, or `cornerRadii`

***

## Behavior in Accented Mode

- **In accented (tinted) mode**: The background is **automatically hidden** to prevent it from rendering as solid white.
- **In default and full-color modes**: The background displays as defined.

This conditional behavior ensures better design control and visual integrity across widget contexts.

***

## Best Practices

- Use `widgetBackground` only in **widget-specific views**.
- Do not use it for essential visual meaning, since the background may be hidden in accented mode.
- Combine it with `widgetAccentable` to precisely control which parts of the widget are subject to system tinting.



---
url: /guide/Widget/Widget Quick Start.md
---

# Widget Quick Start

**Scripting** is an app that allows you to create iOS Home Screen widgets using **TypeScript** and React-like **TSX** syntax.
You can define your widget’s UI inside a `widget.tsx` file using SwiftUI-inspired components.

***

## 1. Quick Start

### Step 1: Create a Script Project

1. Open the **Scripting** app.
2. Create a new script project and give your widget a name.

### Step 2: Add a `widget.tsx` File

1. In the project, create a new file named `widget.tsx`.
2. Define your widget’s interface using a functional component.
3. Import the required components and APIs from the `scripting` package.

#### Example:

```tsx
// widget.tsx
import { VStack, Text, Widget } from 'scripting'

function MyWidgetView() {
  return (
    <VStack>
      <Text>Hello world</Text>
    </VStack>
  )
}

Widget.present(<MyWidgetView />)
```

Calling `Widget.present()` renders the widget on the Home Screen.

***

## 2. Accessing the Widget Context

You can use the following `Widget` API properties to adapt layout and content:

| Property             | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| `Widget.displaySize` | The actual pixel size of the widget at runtime.                                  |
| `Widget.family`      | The widget size: `'small'`, `'medium'`, or `'large'`.                            |
| `Widget.parameter`   | The user-defined custom parameter configured in the Home Screen widget settings. |

These properties help you dynamically adjust content and layout based on the widget’s size or user preferences.

***

## 3. Add to Home Screen

1. Add the **Scripting** widget to your iOS Home Screen.
2. Long-press the widget and tap **Edit Widget**.
3. Select the script you created and configure its **Parameter** if needed.

Once configured, the UI defined in your `widget.tsx` file will appear directly on the Home Screen.

***

## 4. Building the View

Use SwiftUI-inspired built-in components such as `VStack`, `HStack`, `Text`, and `Image` to compose your widget UI.
You can also separate logic and UI across multiple files and import them as needed.

***

## 5. Development Constraints and Best Practices

### Hooks Are Not Active in Widgets

While you can technically use React hooks such as `useState` or `useEffect`, they **don’t take effect** inside widgets because widgets are **rendered once** and have no persistent interactive lifecycle.
Avoid relying on dynamic state logic.

### Memory Limit

iOS enforces an approximate **30 MB memory limit** per widget. To stay within it:

- Avoid deep view hierarchies.
- Minimize image usage.
- Avoid memory leaks or large data references.

If a widget fails to render or appears blank, it’s often due to exceeding this limit.

### Context Is Immediately Destroyed

After calling `Widget.present(...)`, the current execution context is **immediately destroyed**:

- Prepare all data before calling `Widget.present()`.
- Do not place code after `Widget.present()`, as it will never run.
- Treat the widget function as a one-time UI renderer.

***

## 6. Interaction Support

Although widgets are mostly static, **basic interactivity** can be achieved via **AppIntent**:

- Use `<Button>` or `<Toggle>` components to trigger AppIntents.
- See the **Interactive Widget** and **LiveActivity** documentation for more details.

***

## 7. View Compatibility

**Not all SwiftUI views are supported** in WidgetKit.
Some layout containers and visual effects are unavailable.
Refer to Apple’s official documentation: [Supported SwiftUI views in WidgetKit](https://developer.apple.com/documentation/widgetkit/swiftui-views).

***

## 8. Widget Preview Limitations

Widget previews inside the **Scripting** app are only **approximations**.
The actual rendering on the Home Screen may differ slightly in:

- Text alignment
- Widget size
- Corner radius
- Layout behavior

Always **test on the Home Screen** to verify the final layout.

***

## 9. Refreshing Widgets

### General Refresh Methods

- Call `Widget.reloadAll()` to refresh **all** widgets (both user and developer kinds).
- You can invoke it in `index.tsx` or inside an AppIntent.
- Alternatively, use the **Refresh Widgets** button in the Scripting app during development.

This enables rapid iteration on layout and logic.

***

### New: User Widgets vs Developer Widgets

Scripting now distinguishes between two kinds of widgets:

| Type             | Description                                                                  |
| ---------------- | ---------------------------------------------------------------------------- |
| **User Widgets** | Regular widgets intended for end-users to add and use on the Home Screen.    |
| **Test Widgets** | Developer-only widgets used for debugging and previewing during development. |

Each kind has its own `kind` identifier, allowing isolation between user and developer widgets.
This ensures that refreshing test widgets doesn’t affect the user’s actual widgets.

***

### New Refresh Methods

| Method                       | Description                                                                         |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| `Widget.reloadUserWidgets()` | Refreshes **User Widgets only**, without affecting any developer Test Widgets.      |
| `Widget.reloadTestWidgets()` | Refreshes **Test Widgets only**, without affecting user widgets on the Home Screen. |

These methods were introduced to **isolate user and developer environments**.
When developing, refreshing Test Widgets won’t disturb any user widgets already installed.

#### Example

```tsx
// During development
await Widget.reloadTestWidgets()

// When publishing or updating user widgets
await Widget.reloadUserWidgets()
```

#### Usage Recommendations

- **During development:** use `Widget.reloadTestWidgets()` for testing.
- **For production or user updates:** use `Widget.reloadUserWidgets()` or `Widget.reloadAll()`.

This separation helps prevent interference between development experiments and user-facing widgets.

***

## 10. Documentation and Support

- Refer to the **Views Documentation** for a complete list of available components and modifiers.
- Check the **API Documentation** for advanced integrations (e.g., Calendar, FileManager, AVPlayer, etc.).

***

## 11. Using `Widget.preview` for In-App Development Preview

During development, you can use `Widget.preview()` in your `index.tsx` to preview layout and parameter configurations **without leaving the app**.

### Method: `Widget.preview(options)`

This method simulates widget rendering for various sizes and parameters, suitable for **development-only testing**.
It can **only** be called from the **`index.tsx` environment** (not from `widget.tsx` or `intent.tsx`).

### Parameters

| Property             | Type                     | Description                                                               |                 |                                                               |
| -------------------- | ------------------------ | ------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------- |
| `family`             | `'systemSmall'`          | `'systemMedium'`                                                          | `'systemLarge'` | Optional. The preview widget size (default: `'systemSmall'`). |
| `parameters.options` | `Record<string, string>` | Key–value map of parameter options. Values must be JSON-parsable strings. |                 |                                                               |
| `parameters.default` | `string`                 | Specifies which parameter option to use by default.                       |                 |                                                               |

### Example

```tsx
const options = {
  "Param 1": JSON.stringify({ color: "red" }),
  "Param 2": JSON.stringify({ color: "blue" }),
}

await Widget.preview({
  family: "systemSmall",
  parameters: {
    options,
    default: "Param 1"
  }
})
console.log("Widget preview dismissed")
```

This allows testing visual differences under different parameter inputs such as colors, text, or layout configurations.

### Notes

- Must be called **from `index.tsx`** — not from `widget.tsx` or `intent.tsx`.
- If the parameter format is invalid, an error will be thrown.
- Preview results are still subject to the [limitations listed in Section 8](#8-widget-preview-limitations); always verify the final look on the Home Screen.



---
url: /privacy/policy.md
---

# Privacy Policy

## Introduction

Welcome to Scripting! Your privacy is important to us. This Privacy Policy explains how your data is handled when you use our app.

## No Data Collection

The Scripting app does not collect or store any personal data. All activities and data generated through the app remain on your device.

## Voluntary Communication

If you choose to contact us via email, we may receive and store the information you provide, such as your name, email address, and any message content. This information is used solely to respond to your inquiry and will not be shared with third parties.

## Third-Party Integrations

The Scripting app may interact with third-party services, such as the Shortcuts app or other integrations on your device. Any data shared through these integrations is managed entirely by those services and is not collected by us.

When you use Third-Party Model Integration features, the provided API Key is stored locally on the device and is only used to send and receive requests to the AI model for your tasks. The app does not collect, transmit, or use the API Key for any other purpose.

## Health Data and HealthKit

Scripting provides an optional interface to Apple’s HealthKit framework, allowing scripts you write to read from and write to your Health data on device. We respect your privacy and have designed this feature so that:

### No Storage or Analysis

Scripting does not collect, transmit, analyze, or store any of your HealthKit data. All health-related operations occur entirely within your device.

### User Control & Consent

Access to your Health data is controlled by you. Whenever a script requests permission to read or write HealthKit samples, iOS will prompt you to grant or deny that permission. You remain in full control and can revoke access at any time in your system Settings.

### Script-Only Access

HealthKit permissions granted are scoped only to the scripts you run within Scripting. Neither the app itself nor its developers can access your Health data outside of those scripts.

### Transparency

Any script that uses HealthKit APIs must explicitly request the types of data it needs. You can review those requests before granting permission, ensuring you know exactly which health metrics are involved.

## Data Security

As the Scripting app does not collect or store data, there is no risk of unauthorized access to your personal information. Any data shared voluntarily via email will be handled with care and securely stored.

## Changes to This Privacy Policy

We may update this Privacy Policy from time to time. Any changes will be posted on this page, and the "Last Updated" date will be revised accordingly.

## Contact Us

If you have any questions or concerns about this Privacy Policy, please reach out to us at:

Email: [tilfon@live.com](mailto:tilfon@live.com)



---
url: /privacy/service.md
---

# Terms of Service & EULA

## General

Welcome to the Scripting App! Before using this application, please read this agreement carefully. This agreement applies to all users of the application, including free users and Scripting Pro users.

## End-User License Agreement (EULA)

- **License Scope:** You are granted a non-exclusive, non-transferable license for personal use only.

- **Intellectual Property:** All content, designs, and code of this application belong to the developer and are protected by law.

- **Prohibited Actions:** You may not reverse engineer, modify, or distribute this application.

- **Termination:** We reserve the right to terminate your use of this application if you violate the terms.

## Terms of Service

- **Service Description:** This application provides a script development environment and advanced features (e.g., custom themes, code templates).
  Subscription Plans:

- **One-time purchase:** Unlock all features with lifetime validity.
  - Monthly and annual subscriptions: Automatically renew services.

  - Purchase and Confirmation: You can confirm the purchase of the Scripting Pro subscription via your iTunes account. Payment will be charged to your iTunes account upon confirmation of purchase.

- **Canceling Subscriptions:** You can cancel your subscriptions anytime through your iTunes account settings. To avoid auto-renewal, the subscription must be canceled at least 24 hours before the current subscription period ends. If not canceled within this time frame, the subscription will auto-renew.

- **Renewals and Charges:** Within 24 hours before the end of the current subscription period, the subscription will automatically renew, and the associated fee will be charged to your iTunes account. The renewal fee will match the initial subscription price unless you have changed the subscription plan.

- **Free Trial Notice:** After the free trial period ends, the subscription will automatically renew into a paid plan, and the corresponding fee will be charged to your iTunes account. If you do not cancel during the trial period, it will be deemed that you accept the subscription terms.

- **Third-Party Model Integration:** Scripting App acts as a bridge to external AI models, relying entirely on the user-provided API Key to interact with these services (e.g., OpenAI GPT). All AI-related interactions comply with the third-party model provider’s terms of use.

- **Privacy Policy:** For more details, please refer to our [Privacy Policy](/privacy/policy.md)

## Limitation of Liability

This application is provided "as is," and the developer is not responsible for any direct or indirect losses arising from the use of this application.

## Dispute Resolution and Governing Law

- **Governing Law:** This agreement is governed by the laws of your jurisdiction.

- **Dispute Resolution:** Both parties should resolve disputes amicably, and unresolved issues shall be handled in accordance with the law.

## Contact Us

If you have any questions, please contact us via:

Email: [tilfon@live.com](mailto:tilfon@live.com)

Website: scripting.fun



---
url: /index.md
---

# Scripting

iOS Automation Tool

> by thomfang

[Start](/guide/Quick Start) | [Download](https://apps.apple.com/app/apple-store/id6479691128)

## Features

- /home/custom.svg **Highly Customizable**: <div>· Wraps a large number of native APIs (such as Calendar, Notifications, Bluetooth...)<br>· Supports custom widgets, Control Center widgets, Dynamic Island, custom keyboards, Shortcuts, Share Sheet...</div>
- /home/ai.svg **AI Integration**: <div>· Chat with various AI services using your own API keys<br>· Call your own script tools, local knowledge bases, generate and run code to accomplish complex tasks</div>
- /home/search.svg **Excellent Developer Experience**: <div>· Provides a VS Code development scaffold with real-time preview on mobile devices<br>· Built-in multilingual editor with enhanced TypeScript support, including auto-completion, syntax highlighting, and error checking</div>