---
url: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/AssistantTool/Assistant Tool With User Approval.md
---

# Assistant Tool With User Approval

The approval-required AssistantTools typically involve **privacy, permissions, data modification, or irreversible actions**, and therefore must obtain explicit user consent before execution.

***

## When Approval Is Required

An AssistantTool **must** use the approval model if it meets any of the following criteria:

- Accesses user-private data (location, photos, contacts, calendar, health data, etc.)
- Triggers system permission prompts
- Modifies, deletes, or batch-writes user files
- Produces long-lasting or irreversible effects
- Requires the user to understand and confirm what will happen before execution

The purpose of approval is **informed consent**, not blocking functionality.

***

## `assistant_tool.json` Configuration

Approval-required tools must explicitly declare approval behavior:

```json
{
  "displayName": "Request Current Location",
  "id": "request_current_location",
  "description": "Requests the user's current location one time.",
  "icon": "location.fill",
  "color": "systemBlue",
  "parameters": [],
  "requireApproval": true,
  "autoApprove": true,
  "scriptEditorOnly": false
}
```

### Key Fields

- `requireApproval: true`
  Indicates that the tool must enter the approval flow before execution (either manual approval or auto-approval).

- `autoApprove` (**tool-level auto-approval permission**)
  `autoApprove` determines **whether this specific tool is allowed to be auto-approved**.

  Auto-approval occurs **only when both conditions are met**:

  1. The user has enabled _auto-approve tools_ in the **chat preset**
  2. The tool itself declares `autoApprove: true`

  As a result:

  - User enables auto-approve, tool sets `autoApprove: false` → **manual approval is still required**
  - Tool sets `autoApprove: true`, user has not enabled auto-approve → **manual approval is still required**
  - User enables auto-approve **and** tool sets `autoApprove: true` → **the tool is automatically approved and executed**

- `scriptEditorOnly`
  Determines whether the tool is restricted to the script editor context.

***

## The Two-Phase Approval Model

Approval-required AssistantTools always follow a **two-phase model**:

1. **Approval Request Phase**
   Generates the approval UI (or explanatory text in auto-approval cases).

2. **Execute-With-Approval Phase**
   Executes the actual logic after approval has been granted (manually or automatically).

These phases are implemented using two separate registration APIs.

***

## Registering the Approval Request Function

### Registration

```ts
AssistantTool.registerApprovalRequest<P>(requestFn)
```

### Function Signature

```ts
type AssistantToolApprovalRequestFn<P> = (
  params: P,
  scriptEditorProvider?: ScriptEditorProvider
) => Promise<{
  title?: string
  message: string
  previewButton?: {
    label: string
    action: () => void
  }
  primaryButtonLabel?: string
  secondaryButtonLabel?: string
}>
```

***

### Approval Request Design Principles

- The `message` must clearly explain **what will happen** and **why approval is required**
- Use user-friendly language, not implementation details
- **No side effects must occur in this phase**
- All real operations must be performed in the execute phase

***

### Basic Example

```ts
const approvalRequest: AssistantToolApprovalRequestFn<{}> = async () => {
  return {
    message: "The assistant wants to request your current location.",
    primaryButtonLabel: "Allow",
    secondaryButtonLabel: "Cancel"
  }
}

AssistantTool.registerApprovalRequest(approvalRequest)
```

***

## Using the Preview Button

The `previewButton` allows users to inspect the **expected outcome before approving**.

Appropriate use cases include:

- File modifications (showing diffs)
- Batch edit previews
- Data export summaries

### Example: File Diff Preview

```ts
const approvalRequest: AssistantToolApprovalRequestFn<{ path: string }> = async (
  params,
  editor
) => {
  if (!editor) {
    return { message: "This tool must be used in the script editor." }
  }

  const current = await editor.getFileContent(params.path)

  return {
    message: `The assistant wants to modify ${params.path}.`,
    primaryButtonLabel: "Apply Changes",
    secondaryButtonLabel: "Cancel",
    previewButton: {
      label: "Preview Diff",
      action: () => {
        if (current != null) {
          editor.openDiffEditor(params.path, current + "\n// New content")
        }
      }
    }
  }
}
```

***

## Registering the Execute-With-Approval Function

### Registration

```ts
AssistantTool.registerExecuteToolWithApproval<P>(executeFn)
```

### Function Signature

```ts
type AssistantToolExecuteWithApprovalFn<P> = (
  params: P,
  userAction: UserActionForApprovalRequest,
  scriptEditorProvider?: ScriptEditorProvider
) => Promise<{
  success: boolean
  message: string
}>
```

***

## Handling `userAction`

```ts
type UserActionForApprovalRequest = {
  primaryConfirmed: boolean
  secondaryConfirmed: boolean
}
```

Handling rules:

- Execute real logic **only if** `primaryConfirmed === true`
- `secondaryConfirmed === true` usually means the user cancelled
- If both values are `false`, treat it as an unconfirmed or aborted flow

### Example: Location Request

```ts
const executeWithApproval: AssistantToolExecuteWithApprovalFn<{}> = async (
  params,
  { primaryConfirmed }
) => {
  if (!primaryConfirmed) {
    return {
      success: false,
      message: "User cancelled the location request."
    }
  }

  try {
    const location = await Location.requestCurrent()
    return {
      success: true,
      message: [
        "User location retrieved successfully.",
        `<latitude>${location.latitude}</latitude>`,
        `<longitude>${location.longitude}</longitude>`
      ].join("\n")
    }
  } catch {
    return {
      success: false,
      message: "Failed to retrieve user location."
    }
  }
}
```

***

## `autoApprove` and `userAction` Semantics

When auto-approval actually occurs (user enables auto-approve **and** the tool sets `autoApprove: true`):

- The system skips manual user interaction
- The execute phase is still invoked
- `userAction` represents an equivalent of **primary confirmation** (e.g. `primaryConfirmed: true`)

Therefore, execution logic must **always** gate side effects on `primaryConfirmed`, ensuring compatibility with:

- Manual approval
- Automatic approval
- Explicit cancellation

***

## `scriptEditorProvider` in Approval-Required Tools

- If `scriptEditorOnly: true`:

  - Both approval request and execute functions receive `scriptEditorProvider`
  - Can be used for diffs, file access, lint inspection, etc.

- If `scriptEditorOnly: false`:

  - `scriptEditorProvider` may be `undefined`
  - Editor capabilities must not be assumed

***

## Designing the Execution Message

For approval-required tools, the returned `message` should:

- Clearly indicate success, failure, or cancellation
- Provide structured output when appropriate
- Help the Assistant reason about the result

Examples:

```text
Location request was cancelled by the user.
```

```text
Location retrieved successfully.
<latitude>39.9042</latitude>
<longitude>116.4074</longitude>
```

***

## Using Test Functions

Registered functions return test helpers:

```ts
testApprovalFn({})
testExecuteFn({}, { primaryConfirmed: true, secondaryConfirmed: false })
```

These are intended for validating logic paths and return values, not for simulating real system permission dialogs.

***

## Design Summary

- Approval exists to ensure **informed user consent**
- `autoApprove` is a **tool-level permission**, not a global switch
- Auto-approval requires both user preset and tool consent
- Never perform side effects during the approval request phase
- Always guard execution logic with `primaryConfirmed`
- Use previews whenever file or data changes are involved



---
url: /TestFlight/guide/AssistantTool/Assistant Tool Without User Approval.md
---

# Assistant Tool Without User Approval

Tools without approval are intended for **low-risk, non-sensitive, and side-effect-free operations** that the Assistant can execute immediately.

***

## 1. When to Use Tools Without Approval

Before choosing this model, you should clearly understand its boundaries.

### Suitable Scenarios

Tools without approval are appropriate when the tool:

- Does not access system permissions or private user data
- Does not read or modify sensitive user information
- Does not perform irreversible or destructive operations
- Performs pure logic, computation, or deterministic transformations

Typical examples include:

- Code or text formatting
- Parsing structured data (JSON, YAML, CSV)
- Generating boilerplate or template code
- Safe and predictable edits inside the script editor

***

### Unsuitable Scenarios

Do **not** use tools without approval when the tool:

- Accesses location, photos, contacts, calendar, or similar data
- Writes or overwrites user files in an irreversible way
- Triggers system dialogs or permission requests
- Produces results that are difficult for the user to anticipate

These cases should use **approval-required AssistantTools** (see Document 3).

***

## 2. Configuration in `assistant_tool.json`

For a tool that does not require approval, the configuration must explicitly declare:

```json
{
  "displayName": "Format Script",
  "id": "format_script",
  "description": "Formats the current script files according to the project style.",
  "icon": "wand.and.stars",
  "color": "systemIndigo",
  "parameters": [],
  "requireApproval": false,
  "autoApprove": false,
  "scriptEditorOnly": true
}
```

### Key Fields

- `requireApproval: false`
  Indicates that the tool will execute immediately without showing an approval dialog.

- `autoApprove`
  Typically irrelevant in this mode and can be set to `false`.

- `scriptEditorOnly`
  Determines whether the tool is restricted to the script editor.
  When `true`, the execution function receives a `ScriptEditorProvider`.

***

## 3. Execution Registration API

Tools without approval register a single execution function:

```ts
AssistantTool.registerExecuteTool<P>(executeFn)
```

The corresponding function signature is:

```ts
type AssistantToolExecuteFn<P> = (
  params: P,
  scriptEditorProvider?: ScriptEditorProvider
) => Promise<{
  success: boolean
  message: string
}>
```

***

## 4. Minimal Example (No Parameters)

```ts
type FormatParams = {}

const formatScript: AssistantToolExecuteFn<FormatParams> = async (
  params,
  scriptEditorProvider
) => {
  if (!scriptEditorProvider) {
    return {
      success: false,
      message: "This tool can only be used inside the script editor."
    }
  }

  const files = scriptEditorProvider.getAllFiles()

  for (const file of files) {
    const content = await scriptEditorProvider.getFileContent(file)
    if (!content) continue

    const formatted = content.trim()
    await scriptEditorProvider.updateFileContent(file, formatted)
  }

  return {
    success: true,
    message: "All script files have been formatted successfully."
  }
}

const testFormatTool = AssistantTool.registerExecuteTool(formatScript)
```

***

## 5. Example with Parameters

### Parameter Definition

```ts
type ReplaceParams = {
  searchText: string
  replaceText: string
}
```

### Execution Logic

```ts
const replaceInScripts: AssistantToolExecuteFn<ReplaceParams> = async (
  params,
  scriptEditorProvider
) => {
  if (!scriptEditorProvider) {
    return {
      success: false,
      message: "Script editor context is required."
    }
  }

  const files = scriptEditorProvider.getAllFiles()
  let affectedFiles = 0

  for (const file of files) {
    const content = await scriptEditorProvider.getFileContent(file)
    if (!content) continue

    if (!content.includes(params.searchText)) continue

    const updated = content.replaceAll(
      params.searchText,
      params.replaceText
    )

    await scriptEditorProvider.updateFileContent(file, updated)
    affectedFiles++
  }

  return {
    success: true,
    message: `Replaced text in ${affectedFiles} file(s).`
  }
}

AssistantTool.registerExecuteTool(replaceInScripts)
```

***

## 6. Designing the Return Message

The `message` field is **consumed by the Assistant** and should be treated as structured output rather than raw logs.

Recommended guidelines:

- The first line should summarize the result
- Avoid returning excessively large or unstructured content
- Use multi-line output or lightweight markup when structure is helpful

Examples:

```text
Operation completed successfully.
Affected files: 3
```

or:

```text
Replacement summary:
<files>3</files>
<search>foo</search>
<replace>bar</replace>
```

***

## 7. Error Handling Guidelines

- Convert all expected failures into `{ success: false, message }`
- Avoid throwing uncaught exceptions
- Error messages should be clear and actionable, without exposing internal details

Example:

```ts
return {
  success: false,
  message: "Invalid parameters: searchText cannot be empty."
}
```

***

## 8. Progress Reporting (Optional)

For long-running tools, progress updates can be reported via:

```ts
AssistantTool.report("Formatting file: index.tsx")
```

Use progress reporting sparingly and only at meaningful stages.

***

## 9. Using the Test Function

`registerExecuteTool` returns a test function that can be executed inside the script editor:

```ts
testFormatTool({})
```

Test functions are useful for:

- Verifying parameter mapping
- Validating execution logic
- Debugging tools without triggering an Assistant conversation

***

## 10. Best Practices Summary

- “No approval” does not mean “no risk” — evaluate carefully
- Keep tool behavior deterministic and predictable
- Avoid hidden side effects
- Design output messages to support the Assistant’s next reasoning step



---
url: /TestFlight/guide/AssistantTool/AssistantTool User-Initiated Cancellation.md
---

# AssistantTool User-Initiated Cancellation

To improve the user experience of long-running tools, AssistantTool introduces support for **user-initiated cancellation**.
When a user cancels a tool while it is executing, developers may optionally provide an `onCancel` callback to return partially completed results. If `onCancel` is not implemented, cancellation is handled automatically by the system and no additional logic is required.

This mechanism is particularly suitable for search, analysis, crawling, batch processing, and other multi-step or time-consuming tools.

***

## Capability Overview

The cancellation mechanism introduces the following APIs:

```ts
type OnCancel = () => string | null | undefined

var onCancel: OnCancel | null | undefined

const isCancelled: boolean
```

***

## Core Semantics

### onCancel Is Optional

- Implementing `onCancel` is optional
- Not implementing `onCancel` is a fully valid and supported usage

When `onCancel` is not set:

- If the user clicks Cancel, the tool is marked as cancelled
- Any results returned by the execution function after cancellation are automatically ignored
- The Assistant does not consume or process those results

The outcome is that developers do not need to write any additional logic to handle cancellation unless they explicitly want to return partial results.

***

### Purpose of onCancel

The sole purpose of implementing `onCancel` is to proactively return **partially completed results** when a user cancels execution.

It is an experience optimization, not a required responsibility.

***

## Semantics of isCancelled

- `AssistantTool.isCancelled` becomes `true` immediately after the user cancels
- It can be read at any point during execution
- It is intended to control whether subsequent steps should continue running

Typical uses include breaking loops, skipping expensive operations, and releasing resources early.

***

## When and Where to Register onCancel

`onCancel` must be registered **inside the tool execution function**.

Reasons:

- Each tool execution has its own lifecycle
- After execution completes, the system automatically resets `onCancel` to `null`
- Registering `onCancel` outside the execution function has no effect

Valid locations include:

- `registerExecuteTool`
- `registerExecuteToolWithApproval`

***

## Minimal Example Without onCancel

```ts
const executeTool = async () => {
  await doSomethingSlow()

  return {
    success: true,
    message: "Operation completed."
  }
}
```

Behavior:

- If the user cancels, the tool is marked as cancelled
- The returned result is automatically ignored
- No additional cancellation handling is required

***

## Example With onCancel and Partial Results

```ts
const executeTool = async () => {
  const partialResults: string[] = []

  AssistantTool.onCancel = () => {
    return [
      "Operation was cancelled by the user.",
      "Partial results:",
      ...partialResults
    ].join("\n")
  }

  for (const item of items) {
    if (AssistantTool.isCancelled) break
    const result = await process(item)
    partialResults.push(result)
  }

  return {
    success: true,
    message: partialResults.join("\n")
  }
}
```

Behavior:

- When the user cancels, `onCancel` is invoked immediately
- Partially completed results are returned to the Assistant
- Subsequent execution stops based on `isCancelled`

***

## Typical Use Cases

Good candidates for implementing `onCancel` include:

- Multi-source search and aggregation
- Crawling and parsing multiple documents
- Project-wide scanning and analysis
- Batch computation or generation tasks
- Long-running reasoning or processing pipelines

Cases where `onCancel` is usually unnecessary include:

- Tools that complete almost instantly
- Operations with no meaningful intermediate results
- Tasks where cancellation produces no useful partial output

***

## Return Value Guidelines for onCancel

Return values from `onCancel` follow these rules:

- Returning a `string`
  The string is used as the cancellation message sent to the Assistant

- Returning `null` or `undefined`
  Indicates that no message should be returned (valid but generally not recommended)

Recommended practices:

- Clearly state that the operation was cancelled by the user
- Explicitly label partial output as partial results when applicable

***

## Relationship to the Approval Flow

- `onCancel` applies only during the execution phase
- It does not affect the Approval Request phase
- It works for both manually approved tools and auto-approved tools

Important distinction:

- `secondaryConfirmed`
  Indicates the user declined execution during the approval phase

- `onCancel`
  Indicates the user cancelled during execution after approval

***

## Common Mistakes and Caveats

### Registering onCancel Outside the Execution Function

This is ineffective because the execution context has already ended.

***

### Performing Expensive or Side-Effect Operations in onCancel

`onCancel` should return quickly and must not initiate network requests, file writes, or other side effects.

***

### Ignoring isCancelled During Execution

Even with `onCancel` implemented, long-running logic should explicitly check `isCancelled` to avoid unnecessary resource usage.

***

## Recommended Execution Structure

```ts
const executeTool = async () => {
  const partial = []

  AssistantTool.onCancel = () => {
    return formatPartialResult(partial)
  }

  for (const item of items) {
    if (AssistantTool.isCancelled) break
    const r = await process(item)
    partial.push(r)
  }

  if (AssistantTool.isCancelled) {
    return
  }

  return {
    success: true,
    message: formatFinalResult(partial)
  }
}
```

***

## Design Philosophy

- User cancellation is a normal interaction, not an error
- `onCancel` is an optional enhancement, not a requirement
- Not implementing `onCancel` does not break tool behavior
- The system automatically ignores results after cancellation
- Implement `onCancel` only to provide a more graceful completion experience

***

## Summary

- AssistantTool supports user-initiated cancellation during execution
- `onCancel` allows returning partially completed results
- `isCancelled` enables early termination of execution logic
- Cancellation is safely handled even without custom logic
- Developers are not required to manage cancellation explicitly



---
url: /TestFlight/guide/AssistantTool/Overview and Workflow.md
---

# Overview and Workflow

AssistantTool is an extensible tool mechanism in **Scripting** that provides system-level capabilities to the Assistant. By defining and implementing Assistant Tools, script authors can expose structured functionality—such as device access, file manipulation, and data processing—that the Assistant can invoke during a conversation and then continue reasoning based on the execution result.

The design of AssistantTool focuses on two core goals:

- Granting the Assistant additional capabilities while maintaining strong control and transparency, especially for sensitive operations that require explicit user approval.
- Providing clear inputs, clear outputs, and testability, so tools can be reasoned about, validated, and safely composed by the Assistant.

***

## Types of AssistantTools

From an execution model perspective, AssistantTool has two primary types, corresponding to two different registration APIs.

### Tools Without User Approval

- `assistant_tool.json`: `requireApproval: false`
- Code registration:

  - `AssistantTool.registerExecuteTool<P>(executeFn)`

Typical use cases include:

- Pure computation or data transformation
- Formatting, parsing, or code generation
- Non-sensitive operations that do not access device permissions or private user data

In this mode, the tool is executed immediately once the Assistant decides to invoke it.

***

### Tools With User Approval

- `assistant_tool.json`: `requireApproval: true`
- Code registration:

  - `AssistantTool.registerApprovalRequest<P>(requestFn)`
  - `AssistantTool.registerExecuteToolWithApproval<P>(executeFn)`

Typical use cases include:

- Accessing privacy-sensitive resources (location, photos, contacts, calendar, etc.)
- Modifying user data or project files
- Any operation where the user should explicitly understand and confirm what will happen

Optionally, tools can provide a preview action that allows the user to inspect the expected outcome before approving execution.

> The `autoApprove` flag determines **whether this specific tool is allowed to be auto-approved**.

***

## Script-Editor-Only Tools

The `scriptEditorOnly` field in `assistant_tool.json` determines whether a tool can only be used inside the script editor.

- `scriptEditorOnly: false`

  - The tool may be invoked in regular Assistant conversations.
  - A `ScriptEditorProvider` instance is usually not available.

- `scriptEditorOnly: true`

  - The tool is restricted to the script editor context.
  - Execution functions receive an additional `scriptEditorProvider?: ScriptEditorProvider` parameter.
  - Intended for editor-centric tools such as code formatting, batch file edits, diff previews, or lint-driven refactors.

***

## Tool Creation and File Structure

When an AssistantTool is created, the system generates two files:

- `assistant_tool.json`
  Declares the tool’s metadata, parameters, and execution constraints.

- `assistant_tool.tsx`
  Contains the implementation logic and registers the tool using the AssistantTool APIs.

### Responsibility of `assistant_tool.json`

The configuration file is responsible for:

- UI presentation (displayName, icon, color, description)
- Tool routing (unique `id`)
- Invocation constraints (parameters, requireApproval, autoApprove, scriptEditorOnly)

Execution logic is never implemented in this file and always lives in `assistant_tool.tsx`.

***

## Parameters and Input Mapping

Tool input parameters are defined in `assistant_tool.json` and are passed into execution functions as a typed `params` object.

These parameters are provided to:

- `AssistantToolApprovalRequestFn<P>(params, scriptEditorProvider?)`
- `AssistantToolExecuteWithApprovalFn<P>(params, userAction, scriptEditorProvider?)`
- `AssistantToolExecuteFn<P>(params, scriptEditorProvider?)`

Key conventions:

- `P` is a TypeScript type declared in `assistant_tool.tsx`.
- The runtime maps JSON parameters into the `params` object.
- Tools without parameters typically use `P = {}`.

***

## Runtime Execution Flow

From a runtime perspective, a complete tool invocation follows one of the flows below.

### Approval-Required Flow

1. The Assistant selects a tool and constructs `params`.
2. The system invokes the registered approval request function.
3. The approval request returns:

   - A message shown to the user
   - Optional title
   - Optional preview button
   - Optional primary and secondary button labels
4. The user’s selection is captured as `UserActionForApprovalRequest`.
5. The system invokes the execution function registered via `registerExecuteToolWithApproval`.
6. The execution function returns `{ success, message }` to the Assistant.

***

### No-Approval Flow

1. The Assistant selects a tool and constructs `params`.
2. The system directly invokes the execution function registered via `registerExecuteTool`.
3. The execution function returns `{ success, message }` to the Assistant.

***

## Tool Output Contract

All execution functions return a uniform result structure:

```ts
{
  success: boolean
  message: string
}
```

The `message` field is treated as structured output consumable by the Assistant. Recommended patterns include:

- Natural language summaries for simple results
- Lightweight markup for structured data
- Multi-line output where the first line is a summary and subsequent lines provide details

Returning excessively large raw data is discouraged. For editor-related tools, previews and diffs should be surfaced through UI mechanisms instead.

***

## Test Functions

Each registration API returns a corresponding test function for use inside the script editor:

- Approval request registration → approval request test function
- Execution with approval registration → execution test function with user action
- Execution without approval registration → execution test function

These functions allow developers to:

- Validate parameter mapping
- Verify execution logic and output
- Debug tools without relying on an actual Assistant conversation

***

## Progress Reporting

`AssistantTool.report(message: string, id?: string)` can be used to emit progress updates while a tool is running. The parameter `id` can be used to update an existing report.

Typical use cases include:

- Long-running operations
- Multi-step processes
- Debugging and observability

Progress messages should be meaningful and not emitted excessively.



---
url: /TestFlight/guide/AssistantTool/ScriptEditorProvider and Editor Types.md
---

# ScriptEditorProvider and Editor Types

This document provides a detailed reference for editor-related capabilities available to AssistantTools in the **script editor context** (`scriptEditorOnly: true`). It explains the `ScriptEditorProvider` interface and its associated types, along with recommended usage patterns and constraints.

***

## 1. Role and Responsibilities of ScriptEditorProvider

`ScriptEditorProvider` is the communication interface between an AssistantTool and the **script editor**.

An instance of this interface is provided when:

- The tool declares `scriptEditorOnly: true` in `assistant_tool.json`
- The tool is executed inside the script editor (including via test functions)

Its primary responsibilities are:

- Providing controlled access to the script project’s file system
- Enabling structured and traceable file modifications
- Exposing lint and syntax diagnostics
- Supporting preview-first workflows via diff visualization

***

## 2. Project-Level Information

### `scriptName`

```ts
readonly scriptName: string
```

Represents the name of the current script project.

Typical use cases:

- Including scope information in the returned `message`
- Providing context in logs or `AssistantTool.report` output

***

## 3. File and Directory Discovery

### Checking File Existence

```ts
exists(relativePath: string): boolean
```

- `relativePath` is relative to the project root
- Commonly used for validation or conditional file creation

***

### Retrieving All Folders

```ts
getAllFolders(): string[]
```

Returns all folder paths in the project (relative paths).

Typical use cases:

- Generating files in bulk
- Inspecting project structure
- Building grouping or navigation logic

***

### Retrieving All Files

```ts
getAllFiles(): string[]
```

Returns all file paths in the project (relative paths).

Typical use cases:

- Project-wide scans
- Batch formatting, search, or replacement
- Mapping lint diagnostics to files

***

## 4. Reading and Writing File Content

### Reading File Content

```ts
getFileContent(relativePath: string): Promise<string | null>
```

- Returns `null` if the file does not exist
- Callers should handle the null case explicitly

***

### Updating an Entire File

```ts
updateFileContent(relativePath: string, content: string): Promise<boolean>
```

- Replaces the entire file content
- Suitable for deterministic operations such as formatting
- Not recommended for complex or fine-grained edits

***

### Writing to a File (Auto-Creation)

```ts
writeToFile(relativePath: string, content: string): Promise<boolean>
```

- Creates the file if it does not exist
- Overwrites existing content
- Commonly used for file generation or templates

***

## 5. Structured Editing APIs (Recommended)

For most editor tools, **structured edits are safer and more predictable** than full-file replacements.

***

### `ScriptEditorFileOperation`

```ts
type ScriptEditorFileOperation = {
  startLine: number
  content: string
}
```

Semantics:

- `startLine` is **1-based**
- `content` is the text to insert or replace
- The end line is implicit and determined by the editing operation

***

### Inserting Content

```ts
insertContent(
  relativePath: string,
  operations: ScriptEditorFileOperation[]
): Promise<boolean>
```

Behavior:

- Inserts content **before** the specified line
- Operations are applied in array order
- Line numbers refer to the original file state

Recommended practice: apply insert operations **from bottom to top** to avoid line-shift issues.

Typical use cases:

- Inserting imports, comments, or new functions
- Augmenting existing code blocks

***

### Replacing Content

```ts
replaceInFile(
  relativePath: string,
  operations: ScriptEditorFileOperation[]
): Promise<boolean>
```

Behavior:

- Replaces content starting at `startLine`
- Intended for precise, line-based substitutions
- Not suitable for fuzzy or pattern-based replacements

***

## 6. Diff Preview Support

### `openDiffEditor`

```ts
openDiffEditor(relativePath: string, content: string): void
```

Displays a diff view comparing:

- The current file content
- The provided prospective content

This method does **not** modify the file.

Recommended usage:

- During the Approval Request phase
- As the action of a `previewButton`
- Before any batch or destructive modifications

***

## 7. Lint and Syntax Diagnostics

### `ScriptLintError`

```ts
type ScriptLintError = {
  line: number
  message: string
}
```

Represents a single lint or syntax error.

***

### Retrieving Lint Errors

```ts
getLintErrors(): Record<string, ScriptLintError[]>
```

Return structure:

- Key: file path (relative)
- Value: array of lint errors for that file

***

### Common Usage Pattern

- Scan all lint errors
- Identify affected files and line numbers
- Optionally attempt safe, deterministic fixes
- Summarize diagnostics in the tool’s result message

Example:

```ts
const errors = editor.getLintErrors()

for (const file in errors) {
  for (const error of errors[file]) {
    // error.line
    // error.message
  }
}
```

***

## 8. Usage Constraints and Safety Guidelines

Important constraints and recommendations:

- All paths must be **relative paths**
- Do not assume file content always exists
- Avoid concurrent modifications to the same file
- Prefer structured edits over full replacements
- Provide diff previews for batch or impactful changes

***

## 9. Recommended Workflow for Editor-Based AssistantTools

A robust editor-based AssistantTool typically follows this flow:

1. Scan the project using `getAllFiles` or `getLintErrors`
2. Compute the intended changes
3. In the Approval Request phase:

   - Clearly explain the changes
   - Provide a diff preview via `openDiffEditor`
4. In the Execute phase:

   - Perform changes only after confirmation
   - Use structured editing APIs
5. Return a concise, structured execution summary

***

## 10. Summary

- `ScriptEditorProvider` is the bridge between AssistantTools and the script editor
- It enables **controlled, structured, and previewable** file operations
- Editor-based tools should prioritize predictability and user trust
- Combining Approval flows with previews leads to high-confidence editing experiences



---
url: /TestFlight/guide/Changelog/2.4.3/Animation and Transition.md
---

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: /TestFlight/guide/Changelog/2.4.3/EnvironmentValuesReader.md
---

`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;
    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. widgetRenderingMode

Type: `WidgetRenderingMode`
The current widget rendering mode (e.g., `fullColor`, `accented`).

***

### 10. showsWidgetContainerBackground

Type: `boolean`
Indicates whether the widget is showing the system-provided container background.

***

### 11. isSearching

Type: `boolean`
Whether the view is currently in a searching state triggered by `searchable`.

***

### 12. 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.

***

### 13. activityFamily

Type: `"small" | "medium"`
The current LiveActivity size, similar to SwiftUI's `activityFamily`, used to determine the size of LiveActivity UI.

***

### 14. 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: /TestFlight/guide/Changelog/2.4.3/ForEach/index.md
---

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: /TestFlight/guide/Changelog/2.4.3/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: /TestFlight/guide/Changelog/2.4.3/GeometryReader.md
---

`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: /TestFlight/guide/Changelog/2.4.3/LiveActivity View Modifiers.md
---

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: /TestFlight/guide/Changelog/2.4.3/LiveActivity.md
---

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: /TestFlight/guide/Changelog/2.4.3/ReorderableForEach/index.md
---

# ReorderableForEach

`ReorderableForEach` is a high-level component in Scripting that provides **built-in drag-to-reorder capability**.
It preserves the familiar usage pattern of `ForEach` while adding native support for:

- Drag gesture recognition
- Active item tracking
- Manual reorder callbacks

This allows developers to implement **sortable lists and grids with minimal effort**.

Typical use cases include:

- Draggable card layouts
- Reorderable grids (`LazyVGrid`, `LazyHGrid`)
- User-defined module arrangements

***

## 1. Component Definition

```ts
type ReorderableForEachProps<T extends {
  id: string
}> = {
  active: Observable<T | null>
  data: T[]
  builder: (item: T, index: number) => VirtualNode
  onMove: (indices: number[], newOffset: number) => void
}

interface ReorderableForEachComponent {
  <T extends {
    id: string
  }>(props: ReorderableForEachProps<T>): VirtualNode
}

declare const ReorderableForEach: ReorderableForEachComponent
```

***

## 2. Generic Constraint

### `id` Is Required and Must Be Stable

The generic type `T` must satisfy:

```ts
T extends { id: string }
```

This means:

- Every item **must contain a unique and stable `id`**
- The `id` is used to:

  - Identify the dragged element
  - Maintain drag consistency
  - Calculate reorder positions correctly

If `id` values are duplicated or change during runtime, drag behavior will become unstable.

***

## 3. Props Reference

### 3.1 `active`

```ts
active: Observable<T | null>
```

Tracks the **currently dragged item**.

Behavior:

- When dragging starts, the active item is assigned to `active.value`
- When dragging ends, `active.value` is automatically reset to `null`

Typical use cases:

- Highlighting the active item
- Adjusting opacity or scale
- Driving linked animations
- Displaying drag helper UI

***

### 3.2 `data`

```ts
data: T[]
```

The current sortable data source.

Important notes:

- `ReorderableForEach` **does NOT mutate this array automatically**
- You **must update the order manually inside `onMove`**
- It is strongly recommended to use an observable source:

```ts
const data = useObservable<T[]>(...)
```

***

### 3.3 `builder`

```ts
builder: (item: T, index: number) => VirtualNode
```

Defines how each item is rendered.

Parameters:

| Parameter | Description                                   |
| --------- | --------------------------------------------- |
| `item`    | The current data item                         |
| `index`   | The **live index** within the reordered array |

The return value must be a valid `VirtualNode`.

Important:

- `index` reflects the reordered position
- Do not rely on previous fixed indices for logic safety inside `builder`

***

### 3.4 `onMove`

```ts
onMove: (indices: number[], newOffset: number) => void
```

Triggered when a drag reorder operation completes.

Parameter reference:

| Parameter   | Type       | Description                         |
| ----------- | ---------- | ----------------------------------- |
| `indices`   | `number[]` | Original indices of the moved items |
| `newOffset` | `number`   | Target insertion start index        |

You must perform the full reorder update manually:

1. Extract the moving items
2. Remove them from the original array
3. Insert them at `newOffset`
4. Call `Observable.setValue` with the new array

Standard implementation:

```ts
const onMove = (indices: number[], newOffset: number) => {
  const movingItems = indices.map(index => data.value[index])
  const newValue = data.value.filter((_, index) => !indices.includes(index))
  newValue.splice(newOffset, 0, ...movingItems)
  data.setValue(newValue)
}
```

***

## 4. Real Purpose of `contentShape` (Drag Preview Consistency)

From your example:

```tsx
.contentShape({
  kind: 'dragPreview',
  shape: {
    type: 'rect',
    cornerRadius: 16
  }
})
```

The **primary purpose of this configuration is**:

> To define the **drag preview shape**, ensuring that the appearance during dragging **matches the non-drag state**, such as preserving the `RoundedRectangle` corner radius.

It is used for:

- Defining the drag hit-testing region
- Synchronizing the visual shape during dragging
- Preventing the drag preview from degrading into a default rectangular mask

If this is omitted:

- The drag preview may revert to a plain rectangle
- Visual consistency with custom rounded backgrounds may be lost

***

## 5. Full Usage Flow Overview

### 5.1 Data Model

```ts
type Item = {
  id: string
  color: Color
}
```

***

### 5.2 Observable Data Source

```ts
const data = useObservable<Item[]>(() => {
  return new Array(30)
    .fill(0)
    .map((_, index) => ({
      id: String(index),
      color: colors[index % colors.length]
    }))
})
```

***

### 5.3 Active Drag State

```ts
const active = useObservable<Item | null>(null)
```

***

### 5.4 Item View with Consistent Drag Preview Shape

```tsx
<VStack
  modifiers={
    modifiers()
      .frame({ height: 80 })
      .frame({ maxWidth: 'infinity' })
      .background(
        <RoundedRectangle
          cornerRadius={16}
          fill={item.color}
        />
      )
      .contentShape({
        kind: 'dragPreview',
        shape: {
          type: 'rect',
          cornerRadius: 16
        }
      })
  }
>
```

***

### 5.5 Usage Inside `LazyVGrid`

```tsx
<ReorderableForEach
  active={active}
  data={data.value}
  builder={(item) =>
    <ItemView item={item} />
  }
  onMove={onMove}
/>
```

***

## 6. Why `ReorderableForEach` Is **Not Recommended Inside `List`**

Although technically it can be placed inside a `List`, it is **generally discouraged**, because `List` applies a strong set of built-in system behaviors:

- Automatic separators
- Fixed row height management
- Native selection system
- Built-in swipe gestures
- System editing mode
- Cell reuse logic

These behaviors often **conflict with custom drag reordering**, causing:

- Drag jumping or snapping
- Incorrect hit-testing
- Unwanted system edit mode activation
- Visual desynchronization

### Recommended Containers

- `ScrollView`
- `LazyVGrid`
- `LazyHGrid`
- Fully custom layout containers

### Not Recommended

- `List`

***

## 7. Internal Behavior Summary

`ReorderableForEach` follows this internal workflow:

1. Builds drag-enabled child nodes from `data`
2. Uses `dragPreview contentShape` to define the drag hit area and preview shape
3. During dragging:

   - Automatically updates `active`
   - Continuously recalculates the target insertion index
4. On drag completion:

   - Calls `onMove`
   - The developer applies the final reorder

***

## 8. Typical Use Cases

- Custom tool layout sorting
- Draggable dashboard modules
- Reorderable widgets
- Visual task priority organization
- Card-based grid layouts



---
url: /TestFlight/guide/Changelog/2.4.3/ReorderableForEach/index_example.md
---

# Example

```tsx
import { Button, Navigation, NavigationStack, Script, Text, ScrollView, useObservable, LazyVGrid, ReorderableForEach, RoundedRectangle, VStack, Toolbar, ToolbarItem, modifiers, Color } from "scripting"

type Item = {
  id: string
  color: Color
}

const colors: Color[] = [
  'systemRed',
  'systemBlue',
  'systemGreen',
  'systemPink',
  'systemOrange',
  'systemPurple',
]

function ItemView({
  item
}: {
  item: Item
}) {

  return <VStack
    modifiers={
      modifiers()
        .frame({
          height: 80
        })
        .frame({
          maxWidth: 'infinity'
        })
        .background(
          <RoundedRectangle
            cornerRadius={16}
            fill={item.color}
          />
        )
        .contentShape({
          kind: 'dragPreview',
          shape: {
            type: 'rect',
            cornerRadius: 16
          }
        })
    }
  >
    <Text
      foregroundStyle="white"
      font="title"
    >{item.id}</Text>
  </VStack>
}

function View() {
  // Access dismiss function.
  const dismiss = Navigation.useDismiss()

  const data = useObservable<Item[]>(() => {
    return new Array(30)
      .fill(0)
      .map((_, index) => ({
        id: String(index),
        color: colors[index % colors.length]
      }))
  })

  const active = useObservable<Item | null>(null)

  const onMove = (indices: number[], newOffset: number) => {
    const movingItems = indices.map(index => data.value[index])
    const newValue = data.value.filter((_, index) => !indices.includes(index))
    newValue.splice(newOffset, 0, ...movingItems)
    data.setValue(newValue)
  }

  return <NavigationStack>
    <ScrollView
      navigationTitle="ReorderableForEach demo"
      toolbar={
        <Toolbar>
          <ToolbarItem
            placement="topBarLeading"
          >
            <Button
              title="Close"
              action={dismiss}
            />
          </ToolbarItem>
        </Toolbar>
      }
    >
      <LazyVGrid
        columns={[
          {
            size: {
              type: 'flexible'
            }
          },
          {
            size: {
              type: 'flexible'
            }
          }
        ]}
        padding={{
          horizontal: true
        }}
      >
        <ReorderableForEach
          active={active}
          data={data.value}
          builder={(item) =>
            <ItemView
              item={item}
            />
          }
          onMove={onMove}
        />
      </LazyVGrid>
    </ScrollView>
  </NavigationStack>
}

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

  // Avoiding memory leaks.
  Script.exit()
}

run()
```



---
url: /TestFlight/guide/Changelog/2.4.3/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>`

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`.

#### Returns:

- A `Promise` that resolves to the command output as a string.

#### Example:

```ts
const result = await ssh.executeCommand("uname -a")
```

***

### `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: /TestFlight/guide/Changelog/2.4.3/ScrollViewReader.md
---

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: /TestFlight/guide/Changelog/2.4.3/Set environment values (environments).md
---

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`
- `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>;
  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. 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,
    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. `openURL` replaces default URL-handling behavior for all descendant views.
4. Returning `handled()` stops further URL processing.
5. `systemAction()` delegates handling back to the system.
6. **`prefersInApp` requires iOS 26.0+** and may be ignored on earlier versions.
7. Scripting’s environment system is explicit—only the values you define are injected.



---
url: /TestFlight/guide/Changelog/2.4.3/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: /TestFlight/guide/Changelog/2.4.3/useObservable.md
---

Scripting provides a reactive state system formed by `Observable<T>` and the `useObservable<T>` hook.
This system drives UI updates, interacts with the animation engine, and aligns closely with SwiftUI’s binding model—enabling future APIs such as `List(selection:)`, `NavigationStack(path:)`, `TextField(text:)`, and more.

***

# 1. Observable\<T>

`Observable<T>` is a reactive container that holds a mutable value.
Whenever the value changes, any UI components that read this value are automatically re-rendered.

## 1.1 Class Definition

```ts
class Observable<T> {
  constructor(initialValue: T);
  value: T;
  setValue(value: T): void;
  subscribe(callback: (value: T, oldValue: T) => void): void;
  unsubscribe(callback: (value: T, oldValue: T) => void): void;
  dispose(): void;
}
```

***

## 1.2 Property & Method Details

### value

The current value stored inside the observable.

### setValue(newValue)

Updates the value and triggers UI re-rendering.

```ts
observable.setValue(newValue);
```

`T` may be **any type**: primitives, arrays, objects, or class instances.

### subscribe / unsubscribe

Allows external listeners to respond to value changes.
Most components do not need to use these manually.

### dispose

Releases internal subscriptions.
Typically only needed when manually managing observables outside the component system.

***

# 2. useObservable\<T>

`useObservable<T>` creates component-local reactive state and provides an `Observable<T>` instance whose value persists across re-renders.

## 2.1 Function Signature

```ts
declare function useObservable<T>(): Observable<T | undefined>;
declare function useObservable<T>(value: T): Observable<T>;
declare function useObservable<T>(initializer: () => T): Observable<T>;
```

***

## 2.2 Initialization Modes

### 1. Without initial value

Value defaults to `undefined`.

```tsx
const data = useObservable<string>();
```

### 2. With initial value

```tsx
const count = useObservable(0);
```

### 3. Lazy initialization

The initializer is executed only on the first render.

```tsx
const user = useObservable(() => createDefaultUser());
```

***

# 3. Using Observable in UI Components

Reading `.value` inside JSX automatically establishes dependency tracking.

```tsx
<Text>{name.value}</Text>
```

Updating the state triggers re-render:

```tsx
<Button title="Change" action={() => name.setValue("Updated")} />
```

This behavior is similar to React’s `useState`, but aligned with SwiftUI’s reactive identity-based rendering.

***

# 4. Integration with Animation

Observable values participate directly in Scripting’s animation system.

There are two main animation mechanisms:

***

## 4.1 Explicit animations: withAnimation

```tsx
withAnimation(() => {
  size.setValue(size.value + 20);
});
```

Any view that depends on `size.value` will animate its change.

***

## 4.2 Implicit animations: the animation modifier

Views can animate whenever a specific dependency changes.

### Correct syntax:

```tsx
animation={{
  animation: Animation.spring({ duration: 0.3 }),
  value: size.value
}}
```

This mirrors SwiftUI’s `.animation(animation, value: value)` API.

Example:

```tsx
<Rectangle
  frame={{
    width: size.value,
    height: size.value,
  }}
  animation={{
    animation: Animation.easeIn(0.25),
    value: size.value,
  }}
/>
```

***

# 5. Forward Compatibility with SwiftUI-Style Binding APIs

`Observable` is the foundation for future SwiftUI-style binding APIs.
Upcoming components will accept `Observable<T>` directly, matching SwiftUI’s `$binding` behavior.

### 5.1 List(selection:)

```tsx
const selection = useObservable<string | undefined>(undefined)

<List selection={selection}>
  ...
</List>
```

***

### 5.2 NavigationStack(path:)

```tsx
const path = useObservable<string[]>([])

<NavigationStack path={path}>
  ...
</NavigationStack>
```

This allows fully type-safe and reactive navigation, mirroring SwiftUI’s native patterns.

***

# 6. ForEach: Recommended Data Binding Pattern

Scripting provides a SwiftUI-aligned ForEach API:

```tsx
<ForEach data={items} builder={(item, index) => <Text>{item.name}</Text>} />
```

Where each item must satisfy:

```ts
T extends { id: string }
```

### Why this is the recommended pattern:

- Enables insertion/removal animations
- Avoids index-based rendering issues
- Improves performance for large lists

Example:

```tsx
const items = useObservable([
  { id: "1", name: "Apple" },
  { id: "2", name: "Banana" }
])

<ForEach
  data={items}
  editActions="all"
  builder={(item) => <Text>{item.name}</Text>}
/>
```

***

# 7. Complete Example

```tsx
export function Demo() {
  const visible = useObservable(true);
  const size = useObservable(100);

  return (
    <VStack spacing={20}>
      {visible.value && (
        <Rectangle
          frame={{
            width: size.value,
            height: size.value,
          }}
          background="blue"
          animation={{
            animation: Animation.spring({ duration: 0.4, bounce: 0.3 }),
            value: size.value,
          }}
          transition={Transition.opacity()}
        />
      )}

      <Button
        title="Toggle Visible"
        action={() => {
          withAnimation(() => {
            visible.setValue(!visible.value);
          });
        }}
      />

      <Button
        title="Resize"
        action={() => {
          withAnimation(Animation.easeOut(0.25), () => {
            size.setValue(size.value === 100 ? 160 : 100);
          });
        }}
      />
    </VStack>
  );
}
```

***

# 8. Summary

- `Observable<T>` is the core reactive state container in Scripting.
- `useObservable` creates component-local observable state.
- Any change to `.value` automatically re-renders dependent UI.
- Observable integrates directly with animations (explicit and implicit).
- It is the foundation for SwiftUI-style binding APIs such as `List(selection:)` and `NavigationStack(path:)`.
- ForEach works best with `data: Observable<Array<T>>` for identity-based diffing and smooth animations.



---
url: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/Glass Effect Transition/index.md
---

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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/Intent.continueInForeground.md
---

`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: /TestFlight/guide/Changelog/2.4.4/Intent.requestConfirmation.md
---

`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: /TestFlight/guide/Changelog/2.4.4/IntentMemoryStorage.md
---

IntentMemoryStorage is an in-memory storage mechanism used inside AppIntent execution environments.
It allows multiple AppIntents—such as multi-step workflows involving SnippetIntents—to share temporary data.

However, **its lifecycle does not follow the lifecycle of AppIntent execution or Script.exit()**.
It is controlled by the **system’s management of the Extension process**, which is unpredictable.

This document describes its real behavior, its storage scopes, how the system manages JSContexts in Shortcuts, Widgets, and Live Activities, and how developers should use it safely.

***

# Overview

Each AppIntent in Scripting runs inside its own **Script Execution Context** (JSContext).
When:

- The AppIntent’s `perform()` finishes, or
- `Script.exit()` is called

the _execution_ ends.

But this does **not** mean that IntentMemoryStorage (or the JSContext) is destroyed.

Instead:

**IntentMemoryStorage persists as long as the system keeps the Extension process alive**

It will only be cleared when:

- The Extension process is terminated by the system
- The system decides to reclaim memory
- The environment hosting the Intent Extension or Widget Extension is destroyed

Therefore:

- **Running the same Shortcut again may read leftover values from the previous run.**
- **Widget or Live Activity AppIntent calls may reuse the same JSContext, preserving MemoryStorage.**
- **MemoryStorage can disappear at any time if the system kills the Extension process.**

This behavior is normal and inherent to the AppExtension lifecycle.

IntentMemoryStorage is:

**A short-lived, extension-scoped, non-persistent memory store**

***

# Storage Scopes

IntentMemoryStorage provides two scopes.

## 1. Script-scoped (default)

When `shared: true` is _not_ provided:

- Storage belongs to a single script project
- Only AppIntents from the same script can access it
- System may keep it alive across executions
- It is cleared when the system finally terminates the Extension process

Useful for multi-step flows inside a single script.

***

## 2. Shared storage

When `{ shared: true }` is specified:

- All scripts can access the same shared memory space
- Useful for cross-script workflow coordination
- Still relies on the same Extension process lifecycle
- Data disappears when the Extension is killed

Both scopes are **temporary** and tied to the system’s handling of the Extension environment.

***

# System Lifecycle and JSContext Behavior

IntentMemoryStorage’s behavior is entirely dependent on how the OS manages the AppIntent/Widget Extension process.

Below is a complete explanation of observed behaviors.

***

## Case 1: Shortcuts running an Intent

When a Shortcut executes an Intent:

- The AppIntent finishes
- The Script.exit() returns a result
- The JSContext used for execution is destroyed

But:

### IntentMemoryStorage does _not_ necessarily clear.

If the system keeps the Intent Extension process alive, the stored data remains in memory.

Therefore:

**Running the same Shortcut again may still read values saved previously.**

This is expected behavior.

***

## Case 2: Widgets calling AppIntents

Widget Extensions behave differently:

- The system prefers **reusing the same JSContext**
- Therefore, IntentMemoryStorage may persist across multiple AppIntent calls
- But the system may kill the Widget Extension at any time
- When this happens, both the JSContext and MemoryStorage are cleared

Hence:

**MemoryStorage may survive across widget updates, or it may vanish unpredictably.**

***

## Case 3: Live Activity calling AppIntents

Live Activity environments also reuse JSContexts:

- Multiple AppIntent calls often share the same JSContext
- MemoryStorage persists as long as the Extension stays alive
- The system may terminate the Live Activity extension at any time
- MemoryStorage then disappears immediately

***

## Final Lifecycle Summary

| Event                              | Does MemoryStorage clear immediately? |
| ---------------------------------- | ------------------------------------- |
| AppIntent finish                   | No                                    |
| Script.exit()                      | No                                    |
| Shortcut flow finishes             | Not necessarily                       |
| Widget AppIntent call              | Not necessarily                       |
| Live Activity AppIntent call       | Not necessarily                       |
| System kills the Extension process | Yes (completely cleared)              |

Therefore:

**MemoryStorage should never be treated as reliable or persistent.**

**It may remain, or it may disappear at any time.**

***

# API Definition

```ts
namespace IntentMemoryStorage {
  function get<T>(key: string, options?: { shared?: boolean }): T | null
  function set(key: string, value: any, options?: { shared?: boolean }): void
  function remove(key: string, options?: { shared?: boolean }): void
  function contains(key: string, options?: { shared?: boolean }): boolean
  function clear(): void
  function keys(): string[]
}
```

Notes:

- `shared` applies only to get / set / remove / contains
- `clear()` and `keys()` operate **only on script-scoped storage**, never on shared storage

***

# API Details

## get

```ts
function get<T>(key: string, options?: { shared?: boolean }): T | null
```

Retrieves a value.

However:

- If the Extension is still alive → may return leftover values
- If the Extension was killed → returns null

Examples:

Script-scoped:

```ts
const color = IntentMemoryStorage.get<string>("color")
```

Shared:

```ts
const token = IntentMemoryStorage.get<string>("token", { shared: true })
```

***

## set

```ts
function set(key: string, value: any, options?: { shared?: boolean }): void
```

Stores a value in the selected scope.

***

## remove

```ts
function remove(key: string, options?: { shared?: boolean }): void
```

Deletes the key in the selected scope.

***

## contains

```ts
function contains(key: string, options?: { shared?: boolean }): boolean
```

Checks whether a key exists.

This depends on whether the Extension process has remained alive.

***

## clear

```ts
function clear(): void
```

Clears **script-scoped** memory only.

To clear shared memory, remove keys manually.

***

## keys

```ts
function keys(): string[]
```

Returns keys in script-scoped storage.

Shared keys must be tracked manually by the developer.

***

# Usage Scenarios

## Script-scoped (default)

Good for:

- Multi-step flows inside a single script
- SnippetIntent → AppIntent → SnippetIntent
- Temporary UI state
- Step numbers, temporary selections

***

## Shared storage

Good for:

- Multi-script cooperation
- Coordinating global workflow IDs
- Sharing ephemeral state across multiple AppIntent calls

***

# Not Recommended For

- Persistent data
- Large objects (images, binary, long text)
- Data that must be reliably present
- Data that must be reliably cleared
- Any workflow requiring deterministic behavior

Use instead:

- `Storage` for durable key–value data
- `FileManager` for files in the shared App Group directory

***

# Examples

## Script-scoped

```ts
IntentMemoryStorage.set("color", "red")

const color = IntentMemoryStorage.get<string>("color")
```

***

## Shared across scripts

Script A:

```ts
IntentMemoryStorage.set("sessionID", "12345", { shared: true })
```

Script B:

```ts
const id = IntentMemoryStorage.get<string>("sessionID", { shared: true })
```

***

# Storage Structure Example

If you store:

```ts
IntentMemoryStorage.set("color", "green")
IntentMemoryStorage.set("step", 2)
IntentMemoryStorage.set("token", "xyz", { shared: true })
```

Then the extension process holds:

Script-scoped:

```json
{
  "color": "green",
  "step": 2
}
```

Shared:

```json
{
  "token": "xyz"
}
```

Both disappear once the system kills the Extension process.

***

# Best Practices

- Treat MemoryStorage as an in-memory _cache_, not a storage layer
- Never assume the value will exist
- Never assume the value will be cleared
- Do not store large data
- Use structured keys like:

  - `"workflow.step"`
  - `"ui.selectedColor"`
  - `"global.sessionID"`
- For persistent or critical data, always use `Storage` or `FileManager`



---
url: /TestFlight/guide/Changelog/2.4.4/Liquid Glass Effect/index.md
---

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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/New List View Modifiers.md
---

# 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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/SFTP Client.md
---

`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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/SnippetIntent.md
---

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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/Use with Toolbar Component.md
---

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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.4/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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/CalendarEvent.md
---

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

### `CalendarEvent.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

***

### `CalendarEvent.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: /TestFlight/guide/Changelog/2.4.5/DateFormatter.md
---

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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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                                    |

Default value:

```ts
accessibility: "unlocked"
```

***

## 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
```

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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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

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.

***

## 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



---
url: /TestFlight/guide/Changelog/2.4.5/Photos/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={"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>
    </List>
  </NavigationStack>
}

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

  Script.exit()
}

run()
```



---
url: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/Reminder.md
---

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

The calendar to which the reminder belongs.
Each reminder must be associated with a calendar.

### 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.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: /TestFlight/guide/Changelog/2.4.5/ReorderableForEach/index.md
---

# ReorderableForEach

`ReorderableForEach` is a high-level component in Scripting that provides **built-in drag-to-reorder capability**.
It preserves the familiar usage pattern of `ForEach` while adding native support for:

- Drag gesture recognition
- Active item tracking
- Manual reorder callbacks

This allows developers to implement **sortable lists and grids with minimal effort**.

Typical use cases include:

- Draggable card layouts
- Reorderable grids (`LazyVGrid`, `LazyHGrid`)
- User-defined module arrangements

***

## 1. Component Definition

```ts
type ReorderableForEachProps<T extends {
  id: string
}> = {
  active: Observable<T | null>
  data: T[]
  builder: (item: T, index: number) => VirtualNode
  onMove: (indices: number[], newOffset: number) => void
}

interface ReorderableForEachComponent {
  <T extends {
    id: string
  }>(props: ReorderableForEachProps<T>): VirtualNode
}

declare const ReorderableForEach: ReorderableForEachComponent
```

***

## 2. Generic Constraint

### `id` Is Required and Must Be Stable

The generic type `T` must satisfy:

```ts
T extends { id: string }
```

This means:

- Every item **must contain a unique and stable `id`**
- The `id` is used to:

  - Identify the dragged element
  - Maintain drag consistency
  - Calculate reorder positions correctly

If `id` values are duplicated or change during runtime, drag behavior will become unstable.

***

## 3. Props Reference

### 3.1 `active`

```ts
active: Observable<T | null>
```

Tracks the **currently dragged item**.

Behavior:

- When dragging starts, the active item is assigned to `active.value`
- When dragging ends, `active.value` is automatically reset to `null`

Typical use cases:

- Highlighting the active item
- Adjusting opacity or scale
- Driving linked animations
- Displaying drag helper UI

***

### 3.2 `data`

```ts
data: T[]
```

The current sortable data source.

Important notes:

- `ReorderableForEach` **does NOT mutate this array automatically**
- You **must update the order manually inside `onMove`**
- It is strongly recommended to use an observable source:

```ts
const data = useObservable<T[]>(...)
```

***

### 3.3 `builder`

```ts
builder: (item: T, index: number) => VirtualNode
```

Defines how each item is rendered.

Parameters:

| Parameter | Description                                   |
| --------- | --------------------------------------------- |
| `item`    | The current data item                         |
| `index`   | The **live index** within the reordered array |

The return value must be a valid `VirtualNode`.

Important:

- `index` reflects the reordered position
- Do not rely on previous fixed indices for logic safety inside `builder`

***

### 3.4 `onMove`

```ts
onMove: (indices: number[], newOffset: number) => void
```

Triggered when a drag reorder operation completes.

Parameter reference:

| Parameter   | Type       | Description                         |
| ----------- | ---------- | ----------------------------------- |
| `indices`   | `number[]` | Original indices of the moved items |
| `newOffset` | `number`   | Target insertion start index        |

You must perform the full reorder update manually:

1. Extract the moving items
2. Remove them from the original array
3. Insert them at `newOffset`
4. Call `Observable.setValue` with the new array

Standard implementation:

```ts
const onMove = (indices: number[], newOffset: number) => {
  const movingItems = indices.map(index => data.value[index])
  const newValue = data.value.filter((_, index) => !indices.includes(index))
  newValue.splice(newOffset, 0, ...movingItems)
  data.setValue(newValue)
}
```

***

## 4. Real Purpose of `contentShape` (Drag Preview Consistency)

From your example:

```tsx
.contentShape({
  kind: 'dragPreview',
  shape: {
    type: 'rect',
    cornerRadius: 16
  }
})
```

The **primary purpose of this configuration is**:

> To define the **drag preview shape**, ensuring that the appearance during dragging **matches the non-drag state**, such as preserving the `RoundedRectangle` corner radius.

It is used for:

- Defining the drag hit-testing region
- Synchronizing the visual shape during dragging
- Preventing the drag preview from degrading into a default rectangular mask

If this is omitted:

- The drag preview may revert to a plain rectangle
- Visual consistency with custom rounded backgrounds may be lost

***

## 5. Full Usage Flow Overview

### 5.1 Data Model

```ts
type Item = {
  id: string
  color: Color
}
```

***

### 5.2 Observable Data Source

```ts
const data = useObservable<Item[]>(() => {
  return new Array(30)
    .fill(0)
    .map((_, index) => ({
      id: String(index),
      color: colors[index % colors.length]
    }))
})
```

***

### 5.3 Active Drag State

```ts
const active = useObservable<Item | null>(null)
```

***

### 5.4 Item View with Consistent Drag Preview Shape

```tsx
<VStack
  modifiers={
    modifiers()
      .frame({ height: 80 })
      .frame({ maxWidth: 'infinity' })
      .background(
        <RoundedRectangle
          cornerRadius={16}
          fill={item.color}
        />
      )
      .contentShape({
        kind: 'dragPreview',
        shape: {
          type: 'rect',
          cornerRadius: 16
        }
      })
  }
>
```

***

### 5.5 Usage Inside `LazyVGrid`

```tsx
<ReorderableForEach
  active={active}
  data={data.value}
  builder={(item) =>
    <ItemView item={item} />
  }
  onMove={onMove}
/>
```

***

## 6. Why `ReorderableForEach` Is **Not Recommended Inside `List`**

Although technically it can be placed inside a `List`, it is **generally discouraged**, because `List` applies a strong set of built-in system behaviors:

- Automatic separators
- Fixed row height management
- Native selection system
- Built-in swipe gestures
- System editing mode
- Cell reuse logic

These behaviors often **conflict with custom drag reordering**, causing:

- Drag jumping or snapping
- Incorrect hit-testing
- Unwanted system edit mode activation
- Visual desynchronization

### Recommended Containers

- `ScrollView`
- `LazyVGrid`
- `LazyHGrid`
- Fully custom layout containers

### Not Recommended

- `List`

***

## 7. Internal Behavior Summary

`ReorderableForEach` follows this internal workflow:

1. Builds drag-enabled child nodes from `data`
2. Uses `dragPreview contentShape` to define the drag hit area and preview shape
3. During dragging:

   - Automatically updates `active`
   - Continuously recalculates the target insertion index
4. On drag completion:

   - Calls `onMove`
   - The developer applies the final reorder

***

## 8. Typical Use Cases

- Custom tool layout sorting
- Draggable dashboard modules
- Reorderable widgets
- Visual task priority organization
- Card-based grid layouts



---
url: /TestFlight/guide/Changelog/2.4.5/ReorderableForEach/index_example.md
---

# Example

```tsx
import { Button, Navigation, NavigationStack, Script, Text, ScrollView, useObservable, LazyVGrid, ReorderableForEach, RoundedRectangle, VStack, Toolbar, ToolbarItem, modifiers, Color } from "scripting"

type Item = {
  id: string
  color: Color
}

const colors: Color[] = [
  'systemRed',
  'systemBlue',
  'systemGreen',
  'systemPink',
  'systemOrange',
  'systemPurple',
]

function ItemView({
  item
}: {
  item: Item
}) {

  return <VStack
    modifiers={
      modifiers()
        .frame({
          height: 80
        })
        .frame({
          maxWidth: 'infinity'
        })
        .background(
          <RoundedRectangle
            cornerRadius={16}
            fill={item.color}
          />
        )
        .contentShape({
          kind: 'dragPreview',
          shape: {
            type: 'rect',
            cornerRadius: 16
          }
        })
    }
  >
    <Text
      foregroundStyle="white"
      font="title"
    >{item.id}</Text>
  </VStack>
}

function View() {
  // Access dismiss function.
  const dismiss = Navigation.useDismiss()

  const data = useObservable<Item[]>(() => {
    return new Array(30)
      .fill(0)
      .map((_, index) => ({
        id: String(index),
        color: colors[index % colors.length]
      }))
  })

  const active = useObservable<Item | null>(null)

  const onMove = (indices: number[], newOffset: number) => {
    const movingItems = indices.map(index => data.value[index])
    const newValue = data.value.filter((_, index) => !indices.includes(index))
    newValue.splice(newOffset, 0, ...movingItems)
    data.setValue(newValue)
  }

  return <NavigationStack>
    <ScrollView
      navigationTitle="ReorderableForEach demo"
      toolbar={
        <Toolbar>
          <ToolbarItem
            placement="topBarLeading"
          >
            <Button
              title="Close"
              action={dismiss}
            />
          </ToolbarItem>
        </Toolbar>
      }
    >
      <LazyVGrid
        columns={[
          {
            size: {
              type: 'flexible'
            }
          },
          {
            size: {
              type: 'flexible'
            }
          }
        ]}
        padding={{
          horizontal: true
        }}
      >
        <ReorderableForEach
          active={active}
          data={data.value}
          builder={(item) =>
            <ItemView
              item={item}
            />
          }
          onMove={onMove}
        />
      </LazyVGrid>
    </ScrollView>
  </NavigationStack>
}

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

  // Avoiding memory leaks.
  Script.exit()
}

run()
```



---
url: /TestFlight/guide/Changelog/2.4.5/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: /TestFlight/guide/Changelog/2.4.5/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()
```

***

## 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.

***

### `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: /TestFlight/guide/Changelog/2.4.6/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 = ["portrait"]
    }
  }, [])
  return <VStack>...</VStack>
}
```

***

## 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: /TestFlight/guide/Changelog/2.4.6/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: /TestFlight/guide/Changelog/2.4.6/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)`                |

***

## 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: /TestFlight/guide/Changelog/2.4.6/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: /TestFlight/guide/Changelog/2.4.6/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: /TestFlight/guide/Changelog/2.4.6/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: /TestFlight/guide/Changelog/2.4.6/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: /TestFlight/guide/Changelog/2.4.6/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. **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: /TestFlight/guide/Changelog/2.4.6/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: /TestFlight/guide/Changelog/2.4.6/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: /TestFlight/guide/Changelog/2.4.7/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: /TestFlight/guide/Changelog/2.4.7/AssistantTool User-Initiated Cancellation.md
---

# AssistantTool User-Initiated Cancellation

To improve the user experience of long-running tools, AssistantTool introduces support for **user-initiated cancellation**.
When a user cancels a tool while it is executing, developers may optionally provide an `onCancel` callback to return partially completed results. If `onCancel` is not implemented, cancellation is handled automatically by the system and no additional logic is required.

This mechanism is particularly suitable for search, analysis, crawling, batch processing, and other multi-step or time-consuming tools.

***

## Capability Overview

The cancellation mechanism introduces the following APIs:

```ts
type OnCancel = () => string | null | undefined

var onCancel: OnCancel | null | undefined

const isCancelled: boolean
```

***

## Core Semantics

### onCancel Is Optional

- Implementing `onCancel` is optional
- Not implementing `onCancel` is a fully valid and supported usage

When `onCancel` is not set:

- If the user clicks Cancel, the tool is marked as cancelled
- Any results returned by the execution function after cancellation are automatically ignored
- The Assistant does not consume or process those results

The outcome is that developers do not need to write any additional logic to handle cancellation unless they explicitly want to return partial results.

***

### Purpose of onCancel

The sole purpose of implementing `onCancel` is to proactively return **partially completed results** when a user cancels execution.

It is an experience optimization, not a required responsibility.

***

## Semantics of isCancelled

- `AssistantTool.isCancelled` becomes `true` immediately after the user cancels
- It can be read at any point during execution
- It is intended to control whether subsequent steps should continue running

Typical uses include breaking loops, skipping expensive operations, and releasing resources early.

***

## When and Where to Register onCancel

`onCancel` must be registered **inside the tool execution function**.

Reasons:

- Each tool execution has its own lifecycle
- After execution completes, the system automatically resets `onCancel` to `null`
- Registering `onCancel` outside the execution function has no effect

Valid locations include:

- `registerExecuteTool`
- `registerExecuteToolWithApproval`

***

## Minimal Example Without onCancel

```ts
const executeTool = async () => {
  await doSomethingSlow()

  return {
    success: true,
    message: "Operation completed."
  }
}
```

Behavior:

- If the user cancels, the tool is marked as cancelled
- The returned result is automatically ignored
- No additional cancellation handling is required

***

## Example With onCancel and Partial Results

```ts
const executeTool = async () => {
  const partialResults: string[] = []

  AssistantTool.onCancel = () => {
    return [
      "Operation was cancelled by the user.",
      "Partial results:",
      ...partialResults
    ].join("\n")
  }

  for (const item of items) {
    if (AssistantTool.isCancelled) break
    const result = await process(item)
    partialResults.push(result)
  }

  return {
    success: true,
    message: partialResults.join("\n")
  }
}
```

Behavior:

- When the user cancels, `onCancel` is invoked immediately
- Partially completed results are returned to the Assistant
- Subsequent execution stops based on `isCancelled`

***

## Typical Use Cases

Good candidates for implementing `onCancel` include:

- Multi-source search and aggregation
- Crawling and parsing multiple documents
- Project-wide scanning and analysis
- Batch computation or generation tasks
- Long-running reasoning or processing pipelines

Cases where `onCancel` is usually unnecessary include:

- Tools that complete almost instantly
- Operations with no meaningful intermediate results
- Tasks where cancellation produces no useful partial output

***

## Return Value Guidelines for onCancel

Return values from `onCancel` follow these rules:

- Returning a `string`
  The string is used as the cancellation message sent to the Assistant

- Returning `null` or `undefined`
  Indicates that no message should be returned (valid but generally not recommended)

Recommended practices:

- Clearly state that the operation was cancelled by the user
- Explicitly label partial output as partial results when applicable

***

## Relationship to the Approval Flow

- `onCancel` applies only during the execution phase
- It does not affect the Approval Request phase
- It works for both manually approved tools and auto-approved tools

Important distinction:

- `secondaryConfirmed`
  Indicates the user declined execution during the approval phase

- `onCancel`
  Indicates the user cancelled during execution after approval

***

## Common Mistakes and Caveats

### Registering onCancel Outside the Execution Function

This is ineffective because the execution context has already ended.

***

### Performing Expensive or Side-Effect Operations in onCancel

`onCancel` should return quickly and must not initiate network requests, file writes, or other side effects.

***

### Ignoring isCancelled During Execution

Even with `onCancel` implemented, long-running logic should explicitly check `isCancelled` to avoid unnecessary resource usage.

***

## Recommended Execution Structure

```ts
const executeTool = async () => {
  const partial = []

  AssistantTool.onCancel = () => {
    return formatPartialResult(partial)
  }

  for (const item of items) {
    if (AssistantTool.isCancelled) break
    const r = await process(item)
    partial.push(r)
  }

  if (AssistantTool.isCancelled) {
    return
  }

  return {
    success: true,
    message: formatFinalResult(partial)
  }
}
```

***

## Design Philosophy

- User cancellation is a normal interaction, not an error
- `onCancel` is an optional enhancement, not a requirement
- Not implementing `onCancel` does not break tool behavior
- The system automatically ignores results after cancellation
- Implement `onCancel` only to provide a more graceful completion experience

***

## Summary

- AssistantTool supports user-initiated cancellation during execution
- `onCancel` allows returning partially completed results
- `isCancelled` enables early termination of execution logic
- Cancellation is safely handled even without custom logic
- Developers are not required to manage cancellation explicitly



---
url: /TestFlight/guide/Changelog/2.4.7/Device.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 = ["portrait"]
    }
  }, [])
  return <VStack>...</VStack>
}
```

***

## 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: /TestFlight/guide/Changelog/2.4.7/Location.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(): Promise<void>
```

Starts continuous heading updates.

### 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.



---
url: /TestFlight/guide/Changelog/2.4.7/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: /TestFlight/guide/Changelog/2.4.7/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: /TestFlight/guide/Changelog/2.4.7/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.transcation([
  { 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: /TestFlight/guide/Changelog/2.4.7/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: /TestFlight/guide/Changelog/2.4.7/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: /TestFlight/guide/Changelog/2.4.7/SQLite/Transcation.md
---

# Transcation

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.

***

## transcation

```ts
db.transcation(
  steps: TranscationStep[],
  options?: {
    kind?: "deferred" | "immediate" | "exclusive"
  }
): Promise<void>
```

`transcation` executes a transaction defined by an ordered list of SQL steps.

***

## Transaction Steps

```ts
type TranscationStep = {
  sql: string
  args?: Arguments | null
}
```

Each transaction step consists of:

- `sql`: the SQL statement to execute
- `args`: optional bound parameters

Example:

```ts
await db.transcation([
  {
    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.transcation([
    { 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: /TestFlight/guide/Changelog/2.4.7/VideoRecorder/Quick Start/index.md
---

# Quick Start

`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: /TestFlight/guide/Changelog/2.4.7/VideoRecorder/Quick Start/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: /TestFlight/guide/Changelog/2.4.7/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: /TestFlight/guide/Changelog/2.4.7/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`

***

## 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: /TestFlight/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: /TestFlight/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

### `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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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)
    }
  }
}
```

## 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.

## 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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Device Capabilities/CalendarEvent.md
---

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

### `CalendarEvent.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

***

### `CalendarEvent.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: /TestFlight/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: /TestFlight/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: /TestFlight/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 = ["portrait"]
    }
  }, [])
  return <VStack>...</VStack>
}
```

***

## 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: /TestFlight/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: /TestFlight/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`.

### `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.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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Device Capabilities/Health/HealthQuantitySample.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Device Capabilities/Health/HealthUnit.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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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                                    |

Default value:

```ts
accessibility: "unlocked"
```

***

## 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
```

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: /TestFlight/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: /TestFlight/guide/Device Capabilities/Location.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(): Promise<void>
```

Starts continuous heading updates.

### 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.



---
url: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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.

### 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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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

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.

***

## 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



---
url: /TestFlight/guide/Device Capabilities/Photos/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={"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>
    </List>
  </NavigationStack>
}

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

  Script.exit()
}

run()
```



---
url: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Device Capabilities/QRCode.md
---

# QRCode

```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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Device Capabilities/Reminder.md
---

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

The calendar to which the reminder belongs.
Each reminder must be associated with a calendar.

### 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.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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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. **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: /TestFlight/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.
- **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.
- `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)
```



---
url: /TestFlight/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: /TestFlight/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`: The transcription as a user-displayable string, with the highest confidence level.

***

## 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`).
- `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)
  }
})
```

### 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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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()
```

***

## 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.

***

### `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: /TestFlight/guide/Intent/Intent.continueInForeground.md
---

`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: /TestFlight/guide/Intent/Intent.requestConfirmation.md
---

`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: /TestFlight/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)`                |

***

## 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: /TestFlight/guide/Intent/SnippetIntent.md
---

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: /TestFlight/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: /TestFlight/guide/LiveActivity.md
---

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: /TestFlight/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: /TestFlight/guide/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, string>`

Key-value pairs parsed from a `run` URL scheme.

```ts
// 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 to pass.
- `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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Utilities/DateFormatter.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/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.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: /TestFlight/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"
```

***

### `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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Utilities/HttpServer/HttpServer.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`

Registers a handler for a specific request path.

**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!"))
})
```

***

### `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)
  }
})
```

***

### `start(options?: { port?: number; forceIPv4?: boolean }): string | null`

Starts the HTTP server.

**Parameters:**

| Name                | Type      | Description                                                                                      |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------ |
| `options.port`      | `number`  | The port to listen on (default: `8080`). If `0` is specified, a random available port is chosen. |
| `options.forceIPv4` | `boolean` | Whether to force IPv4 listening (default: `false`).                                              |

**Returns:**

- Returns `null` if the server starts successfully.
- Returns an error message string if the server fails to start.

**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)
}
```

***

### `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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Utilities/Request/Request & RequestInit.md
---

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: /TestFlight/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
- Support for response streaming (`ReadableStream<Data>`)
- Access to expected content length, MIME type, and text encoding

***

## Definition

```ts
class Response {
  readonly body: 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<Data>` | The response body as a readable stream of `Data` chunks.                |                                                                             |
| **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)
```

***

### `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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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.transcation([
  { 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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Utilities/SQLite/Transcation.md
---

# Transcation

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.

***

## transcation

```ts
db.transcation(
  steps: TranscationStep[],
  options?: {
    kind?: "deferred" | "immediate" | "exclusive"
  }
): Promise<void>
```

`transcation` executes a transaction defined by an ordered list of SQL steps.

***

## Transaction Steps

```ts
type TranscationStep = {
  sql: string
  args?: Arguments | null
}
```

Each transaction step consists of:

- `sql`: the SQL statement to execute
- `args`: optional bound parameters

Example:

```ts
await db.transcation([
  {
    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.transcation([
    { 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: /TestFlight/guide/Utilities/SSH/SFTP Client.md
---

`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: /TestFlight/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: /TestFlight/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 ras(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.ras("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.ras("root", privateKey)

// Connect to server
const ssh = await SSHClient.connect({
  host: "192.168.0.1",
  authenticationMethod: rsaAuth
})
```



---
url: /TestFlight/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>`

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`.

#### Returns:

- A `Promise` that resolves to the command output as a string.

#### Example:

```ts
const result = await ssh.executeCommand("uname -a")
```

***

### `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: /TestFlight/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: /TestFlight/guide/Utilities/Storage.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/View Modifiers/Animation and Transition.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/View Modifiers/Liquid Glass/Glass Effect Transition/index.md
---

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: /TestFlight/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: /TestFlight/guide/View Modifiers/Liquid Glass/Liquid Glass Effect/index.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/View Modifiers/List and Section View Modifiers/New List View Modifiers.md
---

# 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: /TestFlight/guide/View Modifiers/LiveActivity View Modifiers.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/View Modifiers/Redaction View Modifiers.md
---

# 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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/View Modifiers/Set environment values (environments).md
---

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`
- `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>;
  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. 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,
    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. `openURL` replaces default URL-handling behavior for all descendant views.
4. Returning `handled()` stops further URL processing.
5. `systemAction()` delegates handling back to the system.
6. **`prefersInApp` requires iOS 26.0+** and may be ignored on earlier versions.
7. Scripting’s environment system is explicit—only the values you define are injected.



---
url: /TestFlight/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: /TestFlight/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: /TestFlight/guide/View Modifiers/Symbol Style.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
}
```

#### Example

```tsx
<Image
  systemName="star.fill"
  symbolEffect={{
    effect: "bounce",
    value: isFavorited
  }}
/>
```

In this example, each time `isFavorited` changes, the bounce animation is triggered.

***

## Available Discrete Effects (`DiscreteSymbolEffect`)

These effects can be bound to values:

| 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` |

***

## 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: /TestFlight/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" />
```

***

## `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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/View Modifiers/toolbar/Use with Toolbar Component.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Views/Charts/RuleChart/index.md
---

# `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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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.

## 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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Views/Displaying text/index.md
---

# Displaying text

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: /TestFlight/guide/Views/Displaying text/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: /TestFlight/guide/Views/Editor.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.

#### `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
    />
  )
}
```



---
url: /TestFlight/guide/Views/EnvironmentValuesReader.md
---

`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;
    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. widgetRenderingMode

Type: `WidgetRenderingMode`
The current widget rendering mode (e.g., `fullColor`, `accented`).

***

### 10. showsWidgetContainerBackground

Type: `boolean`
Indicates whether the widget is showing the system-provided container background.

***

### 11. isSearching

Type: `boolean`
Whether the view is currently in a searching state triggered by `searchable`.

***

### 12. 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.

***

### 13. activityFamily

Type: `"small" | "medium"`
The current LiveActivity size, similar to SwiftUI's `activityFamily`, used to determine the size of LiveActivity UI.

***

### 14. 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: /TestFlight/guide/Views/GeometryReader.md
---

`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: /TestFlight/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: /TestFlight/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.

### `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: /TestFlight/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: /TestFlight/guide/Views/Layout/FlowLayout.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 spacing between each item (both horizontal and vertical).

- **Type:** `number`
- **Default:** `8`

Defines the amount of space inserted between child items. If not specified, the default spacing value is used.

### `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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Views/Modal presentaions/index_example.md
---

# Example

```tsx
import { Button, List, Navigation, NavigationStack, Script, Section, Text, 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, // fixed height
            "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 a 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 Example() {
  return <NavigationStack>
    <List
      navigationTitle={"Modal presentations"}
      navigationBarTitleDisplayMode={"inline"}
    >
      <SheetExample />
      <ConfiguringSheetHeightExample />
      <FullScreenCoverExample />
      <PopoverExample />
      <PresentAlertExample />
      <PresentConfirmationDialogExample />
    </List>
  </NavigationStack>
}

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

  Script.exit()
}

run()
```



---
url: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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.

***

## `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         |
| `scrollContentBackground` | Sets the visibility of the scroll view’s default background              |



---
url: /TestFlight/guide/Views/Scroll views/index_example.md
---

# Example

```tsx
import { Color, ForEach, HStack, KeywordPoint, 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")

  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
              }}
            />
          }}
        />
      </VStack>
    </ScrollView>
  </NavigationStack>
}

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

  Script.exit()
}

run()


```



---
url: /TestFlight/guide/Views/ScrollViewReader.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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 = {
  timestamp: number
  style: 'date' | 'time' | 'timer' | 'relative' | 'offset'
}
```

- `timestamp`: A UNIX timestamp in milliseconds representing the date to be

- `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
  timestamp={Date.now()}
  style="date"
/>

<DateLabel
  timestamp={Date.now()}
  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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/guide/Views/View groupings/ForEach/index.md
---

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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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`

***

## 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: /TestFlight/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: /TestFlight/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: /TestFlight/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: /TestFlight/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](/TestFlight/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: /TestFlight/index.md
---

# Scripting - TestFlight

iOS Automation Tool

> by thomfang

[Start](/TestFlight/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>