Introduction

Perry is a native TypeScript compiler that compiles TypeScript source code directly to native executables. No JavaScript runtime, no JIT warmup, no V8 — your TypeScript compiles to a real binary.

// demonstrates: the one-liner hello shown on the docs landing page
// docs: docs/src/introduction.md
// platforms: macos, linux, windows
// targets: wasm, web, android

console.log("Hello from Perry!")

$ perry hello.ts -o hello
$ ./hello
Hello from Perry!

Why Perry?

• Native performance — Compiles to machine code via LLVM. Integer-heavy code like Fibonacci runs 2x faster than Node.js.
• Real multi-threading — parallelMap and spawn give you actual OS threads with compile-time safety. No isolates, no message passing overhead. Something no JS runtime can do.
• Small binaries — A hello world is ~300KB. Perry detects what runtime features you use and only links what’s needed.
• Native UI — Build desktop and mobile apps with declarative TypeScript that compiles to real AppKit, UIKit, GTK4, Win32, or DOM widgets.
• Terminal UI — Build interactive CLIs with ink-shape React hooks (useState, useEffect, useApp) on a native cell-grid renderer. No Node, no reconciler — just a single static binary.
• 7 targets — macOS, iOS, Android, Windows, Linux, Web, and WebAssembly from the same source code.
• Familiar ecosystem — Use npm packages like fastify, mysql2, redis, bcrypt, lodash, and more — compiled natively.
• Zero config — Point Perry at a .ts file and get a binary. No tsconfig.json required.

What Perry Compiles

Perry supports a practical subset of TypeScript:

• Variables, functions, classes, enums, interfaces
• Async/await, closures, generators
• Destructuring, spread, template literals
• Arrays, Maps, Sets, typed arrays
• Regular expressions, JSON, Promises
• Module imports/exports
• Generic type erasure

See Supported Features for the complete list.

Quick Example: Native App

// demonstrates: minimal stateful UI — label + increment button
// docs: docs/src/ui/state.md
// platforms: macos, linux, windows
// targets: ios-simulator, visionos-simulator, tvos-simulator, watchos-simulator, android, web, wasm

import { App, VStack, Text, Button, State } from "perry/ui"

const count = State(0)

App({
    title: "Counter",
    width: 400,
    height: 300,
    body: VStack(16, [
        Text(`Count: ${count.value}`),
        Button("Increment", () => count.set(count.value + 1)),
    ]),
})

$ perry counter.ts -o counter
$ ./counter  # Opens a native macOS/Windows/Linux window

This produces a ~3MB native app with real platform widgets — no Electron, no WebView.

How It Works

TypeScript (.ts)
    ↓ Parse (SWC)
    ↓ Lower to HIR
    ↓ Transform (inline, closure conversion, async)
    ↓ Codegen (LLVM)
    ↓ Link (system linker)
    ↓
Native Executable

Perry uses SWC for TypeScript parsing and LLVM for native code generation. Types are erased at compile time (like tsc), and values are represented at runtime using NaN-boxing for efficient 64-bit tagged values.

Next Steps

• Install Perry
• Write your first program
• Build a native app

Installation

Prerequisites

Perry compiles TypeScript to native binaries by linking with your system’s C toolchain, so every install path needs a linker:

• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: gcc or clang (apt install build-essential on Debian/Ubuntu, apk add build-base on Alpine)
• Windows: LLVM (winget install LLVM.LLVM) + perry setup windows (lightweight, ~1.5 GB, no Visual Studio needed), or MSVC Build Tools with the “Desktop development with C++” workload — see the Windows platform guide for both options

The source install additionally needs the Rust toolchain via rustup.

Install Perry

npm / npx (recommended — any platform)

Perry ships as a prebuilt-binary npm package. This is the fastest way to get started and the only path that covers all seven supported platforms (macOS arm64/x64, Linux x64/arm64 glibc + musl, Windows x64) with a single command:

# Project-local (pins Perry's version alongside your deps)
npm install @perryts/perry
npx perry compile src/main.ts -o myapp && ./myapp

# Global
npm install -g @perryts/perry
perry compile src/main.ts -o myapp

# Zero-install, one-shot
npx -y @perryts/perry compile src/main.ts -o myapp

@perryts/perry is a thin launcher; npm automatically picks the matching prebuilt via optionalDependencies (@perryts/perry-darwin-arm64, @perryts/perry-linux-x64-musl, etc.) based on your os / cpu / libc. Requires Node.js ≥ 16.

Homebrew (macOS)

brew install perryts/perry/perry

winget (Windows)

winget install PerryTS.Perry

APT (Debian / Ubuntu)

curl -fsSL https://perryts.github.io/perry-apt/perry.gpg.pub | sudo gpg --dearmor -o /usr/share/keyrings/perry.gpg
echo "deb [signed-by=/usr/share/keyrings/perry.gpg] https://perryts.github.io/perry-apt stable main" | sudo tee /etc/apt/sources.list.d/perry.list
sudo apt update && sudo apt install perry

From Source

git clone https://github.com/PerryTS/perry.git
cd perry
cargo build --release

The binary is at target/release/perry. Add it to your PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="/path/to/perry/target/release:$PATH"

Self-Update

Once installed, Perry can update itself:

perry update

This downloads the latest release and atomically replaces the binary.

Verify Installation

perry doctor

This checks your installation, shows the current version, and reports if an update is available.

perry --version

Platform-Specific Setup

macOS

No additional setup needed. Perry uses the system cc linker and AppKit for UI apps.

For iOS development, install Xcode (not just Command Line Tools) for the iOS SDK and simulator.

Linux

Install GTK4 + libshumate + GStreamer development libraries for UI apps. (You only need these if you build for --target linux — pure-CLI / cross-compile to other platforms doesn’t require them.)

# Ubuntu / Debian
sudo apt install libgtk-4-dev libshumate-dev libgstreamer1.0-dev

# Fedora
sudo dnf install gtk4-devel libshumate-devel gstreamer1-devel \
                 gstreamer1-plugins-base-devel

# Arch
sudo pacman -S gtk4 libshumate gstreamer gst-plugins-base

Windows

Two toolchain options — pick one. Both produce identical binaries.

Lightweight (recommended, ~1.5 GB, no Visual Studio):

winget install LLVM.LLVM
perry setup windows

perry setup windows downloads the Microsoft CRT + Windows SDK libraries via xwin after prompting for license acceptance. Pass --accept-license to skip the prompt in CI.

MSVC Build Tools (~8 GB):

Install Visual Studio Build Tools with the “Desktop development with C++” workload — via the Visual Studio Installer, or:

winget install Microsoft.VisualStudio.2022.BuildTools --override `
  "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

Run perry doctor to verify the toolchain. See the Windows platform guide for details.

What’s Next

• Write your first program
• Build a native app

Hello World

Your First Program

Create a file called hello.ts:

// demonstrates: the minimal Perry program in the docs
// docs: docs/src/getting-started/hello-world.md
// platforms: macos, linux, windows
// targets: wasm, web, android

console.log("Hello, Perry!")

Compile and run it:

perry hello.ts -o hello
./hello

Output:

Hello, Perry!

That’s it. Perry compiled your TypeScript to a native executable — no Node.js, no bundler, no runtime.

A Slightly Bigger Example

// demonstrates: recursive fib as a perf-vs-node talking point
// docs: docs/src/getting-started/hello-world.md
// platforms: macos, linux, windows
// targets: wasm, web, android

function fibonacci(n: number): number {
    if (n <= 1) return n
    return fibonacci(n - 1) + fibonacci(n - 2)
}

const start = Date.now()
const result = fibonacci(35)
const elapsed = Date.now() - start

console.log(`fibonacci(35) = ${result}`)
console.log(`Completed in ${elapsed}ms`)

perry fib.ts -o fib
./fib

This runs about 2x faster than Node.js because Perry compiles to native machine code with integer specialization.

Using Variables and Functions

const name: string = "World"
const items: number[] = [1, 2, 3, 4, 5]

const doubled = items.map((x) => x * 2)
const sum = doubled.reduce((acc, x) => acc + x, 0)

console.log(`Hello, ${name}!`)
console.log(`Sum of doubled: ${sum}`)

Async Code

// demonstrates: async/await fetch shown in hello-world.md
// docs: docs/src/getting-started/hello-world.md
// platforms: macos, linux, windows
// run: false

async function fetchData(): Promise<string> {
    const response = await fetch("https://httpbin.org/get")
    const data = await response.json() as { origin: string }
    return data.origin
}

const ip = await fetchData()
console.log(`Your IP: ${ip}`)

perry fetch.ts -o fetch
./fetch

Perry compiles async/await to a native async runtime backed by Tokio.

Multi-Threading

Perry can do something no JavaScript runtime can — run your code on multiple CPU cores:

// demonstrates: parallelMap + spawn shown in hello-world.md
// docs: docs/src/getting-started/hello-world.md
// platforms: macos, linux, windows

import { parallelMap, parallelFilter, spawn } from "perry/thread"

const data = [1, 2, 3, 4, 5, 6, 7, 8]

// Process all elements across all CPU cores
const doubled = parallelMap(data, (x: number) => x * 2)
console.log(doubled) // [2, 4, 6, 8, 10, 12, 14, 16]

// Run heavy work in the background
const result = await spawn(() => {
    let sum = 0
    for (let i = 0; i < 100_000_000; i++) sum += i
    return sum
})
console.log(result)

// parallelFilter is also available for the lift-and-parallelize case:
const evens = parallelFilter(data, (x: number) => x % 2 === 0)
console.log(evens)

This is real OS-level parallelism, not web workers or separate isolates. See Multi-Threading for details.

What the Compiler Produces

When you run perry file.ts -o output, Perry:

1. Parses your TypeScript with SWC
2. Lowers the AST to an intermediate representation (HIR)
3. Applies optimizations (inlining, closure conversion, etc.)
4. Generates native machine code with LLVM
5. Links with your system’s C compiler

The result is a standalone executable with no external dependencies.

Binary Size

Perry automatically detects which runtime features you use and only links what’s needed.

Next Steps

• Build a native UI app
• Configure your project
• Explore supported TypeScript features

First Native App

Perry compiles declarative TypeScript UI code to native platform widgets. No Electron, no WebView — real AppKit on macOS, UIKit on iOS, GTK4 on Linux, Win32 on Windows. Every example on this page is a real source file under docs/examples/ that CI compiles and runs on every PR.

A Simple Counter

// demonstrates: minimal stateful UI — label + increment button
// docs: docs/src/ui/state.md
// platforms: macos, linux, windows
// targets: ios-simulator, visionos-simulator, tvos-simulator, watchos-simulator, android, web, wasm

import { App, VStack, Text, Button, State } from "perry/ui"

const count = State(0)

App({
    title: "Counter",
    width: 400,
    height: 300,
    body: VStack(16, [
        Text(`Count: ${count.value}`),
        Button("Increment", () => count.set(count.value + 1)),
    ]),
})

Compile and run:

perry counter.ts -o counter
./counter

A native window opens with a label and two buttons. Clicking “Increment” updates the count in real-time.

How It Works

• App({ title, width, height, body }) — Creates a native application window. body is the root widget.
• State(initialValue) — Creates reactive state. .value reads, .set(v) writes and triggers UI updates.
• VStack(spacing, [...]) — Vertical stack layout (like SwiftUI’s VStack or CSS flexbox column). The first arg is the gap in points between children.
• Text(string) — A text label. Template literals referencing ${state.value} bind reactively.
• Button(label, onClick) — A native button with a click handler.

A Todo App

// demonstrates: complete reactive todo app combining State, ForEach, and widget tree mutation
// docs: docs/src/ui/state.md
// platforms: macos, linux, windows
// targets: ios-simulator, tvos-simulator, watchos-simulator, web, wasm

import {
    App,
    Text,
    Button,
    TextField,
    VStack,
    HStack,
    State,
    ForEach,
    Spacer,
    Divider,
} from "perry/ui"

const todos = State<string[]>([])
const count = State(0)
const input = State("")

App({
    title: "Todo App",
    width: 480,
    height: 600,
    body: VStack(16, [
        Text("My Todos"),

        HStack(8, [
            TextField("What needs to be done?", (value: string) => input.set(value)),
            Button("Add", () => {
                const text = input.value
                if (text.length > 0) {
                    todos.set([...todos.value, text])
                    count.set(count.value + 1)
                    input.set("")
                }
            }),
        ]),

        Divider(),

        ForEach(count, (i: number) =>
            HStack(8, [
                Text(todos.value[i]),
                Spacer(),
                Button("Delete", () => {
                    todos.set(todos.value.filter((_, idx) => idx !== i))
                    count.set(count.value - 1)
                }),
            ]),
        ),

        Spacer(),
        Text(`${count.value} items`),
    ]),
})

ForEach(count, render) iterates by index — keep an item array and a count state in sync, then read items via array.value[i] inside the closure. See State Management for the full pattern.

Cross-Platform

The same code runs on all 6 platforms:

# macOS (default)
perry app.ts -o app
./app

# iOS Simulator
perry app.ts -o app --target ios-simulator

# Web (compiles to WebAssembly + DOM bridge in a self-contained HTML file)
perry app.ts -o app --target web   # alias: --target wasm
open app.html

# Other platforms
perry app.ts -o app --target windows
perry app.ts -o app --target linux
perry app.ts -o app --target android

Each target compiles to the platform’s native widget toolkit. See Platforms for details.

Adding Styling

Styling is applied via free functions that take the widget handle as their first argument. Colors are RGBA floats in [0.0, 1.0] — divide a hex byte by 255 to convert (0x33 / 255 ≈ 0.2).

// demonstrates: counter from getting-started/first-app.md with styled widgets
// docs: docs/src/getting-started/first-app.md
// platforms: macos, linux, windows
// targets: ios-simulator, tvos-simulator, watchos-simulator, web, wasm
// run: false

import {
    App, VStack, Text, Button, State,
    textSetFontSize, textSetColor,
    setCornerRadius, setPadding,
    widgetSetBackgroundColor,
} from "perry/ui"

const count = State(0)

const label = Text(`Count: ${count.value}`)
textSetFontSize(label, 24)
textSetColor(label, 0.2, 0.2, 0.2, 1.0)        // RGBA in [0,1] — same as #333333

const btn = Button("Increment", () => count.set(count.value + 1))
setCornerRadius(btn, 8)
widgetSetBackgroundColor(btn, 0.0, 0.478, 1.0, 1.0)  // system blue

const stack = VStack(20, [label, btn])
setPadding(stack, 20, 20, 20, 20)

App({
    title: "Styled Counter",
    width: 400,
    height: 300,
    body: stack,
})

See Styling for all available style properties.

Next Steps

• Project Configuration — Set up package.json for Perry projects
• UI Overview — Complete guide to Perry’s UI system
• Widgets Reference — All available widgets
• State Management — Reactive state and bindings

Project Configuration

Perry projects use perry.toml and package.json for configuration. No special config file is required for basic usage, but larger projects benefit from Perry-specific settings.

Looking for the full perry.toml reference? See perry.toml Reference for every field, section, platform option, and environment variable.

Basic Setup

perry init my-project
cd my-project

This creates a package.json and a starter src/index.ts.

package.json

{
  "name": "my-project",
  "version": "1.0.0",
  "main": "src/index.ts",
  "perry": {
    "compilePackages": []
  }
}

Perry Configuration

The perry field in package.json controls compiler behavior:

compilePackages

List npm packages to compile natively instead of routing through the JavaScript runtime:

{
  "perry": {
    "compilePackages": ["@noble/curves", "@noble/hashes"]
  }
}

When a package is listed here, Perry:

1. Resolves the package in node_modules/
2. Prefers TypeScript source (src/index.ts) over compiled JavaScript (lib/index.js)
3. Compiles all functions natively through LLVM
4. Deduplicates across nested node_modules/ to prevent duplicate linker symbols

This is useful for pure TypeScript/JavaScript packages that don’t rely on Node.js APIs. Packages that use native bindings, eval(), or dynamic require() won’t work.

codegen

Perry is an ahead-of-time compiler: it never runs a code string at runtime. Many libraries that would normally JIT a function from a schema or a config (ajv, fast-json-stringify, Prisma, Drizzle, …) ship a build-time mode that emits plain, eval-free source instead. The codegen field declares the commands that produce that source. Perry runs them before compiling, then compiles the generated output natively — so the shipped binary links no JavaScript engine.

{
  "perry": {
    "codegen": [
      { "label": "ajv validators", "command": "node scripts/generate-validators.mjs" }
    ]
  }
}

Each entry is either a bare command string or an object with command (required) and an optional label shown in build output. Commands run in declaration order, with the working directory set to the folder containing this package.json, so relative script paths resolve as expected. If a command exits non-zero the build fails and prints its captured stdout/stderr.

Security: codegen is read only from the host project’s package.json — never from a dependency’s — so a transitive dependency can’t smuggle in a build command (the same trust boundary as compilePackages). Skip the steps for a reproducible or sandboxed build (where the generated output is already committed) with perry compile --no-codegen or PERRY_SKIP_CODEGEN=1.

Worked example: ajv/standalone

ajv validates against a JSON Schema. Its default mode JITs the validator with new Function; its standalone mode emits the same validator as plain source. The generator script:

// scripts/generate-validators.mjs
import Ajv from "ajv";
import standaloneCode from "ajv/dist/standalone/index.js";
import { writeFileSync } from "node:fs";

const schema = {
  $id: "Config",
  type: "object",
  properties: { host: {}, port: {} },
  required: ["host", "port"],
  additionalProperties: false,
};

const ajv = new Ajv({ code: { source: true } }); // standalone source
const moduleCode = standaloneCode(ajv, ajv.compile(schema));
writeFileSync(new URL("../generated/validator.cjs", import.meta.url), moduleCode);

Then import the generated validator like any other module:

import validate from "./generated/validator.cjs";
if (!validate(input)) throw new Error("invalid config");

perry compile runs the codegen step, ajv emits generated/validator.cjs (no new Function), and Perry compiles it natively. See test-files/test_ajv_standalone.ts for a runnable, byte-parity-tested sample.

Same convention, other tools

The convention is library-agnostic — point a codegen command at any build-time generator and import its output:

Libraries that JIT at runtime with no standalone mode (e.g. fast-json-stringify, find-my-way) are handled separately — see the eval / new Function strategy.

splash

Configure a native splash screen for iOS and Android. The splash screen appears instantly during cold start, before your app code runs.

Minimal (both platforms share the same splash):

{
  "perry": {
    "splash": {
      "image": "logo/icon-256.png",
      "background": "#FFF5EE"
    }
  }
}

Per-platform overrides:

{
  "perry": {
    "splash": {
      "image": "logo/icon-256.png",
      "background": "#FFF5EE",
      "ios": {
        "image": "logo/splash-ios.png",
        "background": "#FFFFFF"
      },
      "android": {
        "image": "logo/splash-android.png",
        "background": "#FFFFFF"
      }
    }
  }
}

Full custom override (complete control):

{
  "perry": {
    "splash": {
      "ios": {
        "storyboard": "splash/LaunchScreen.storyboard"
      },
      "android": {
        "layout": "splash/splash_background.xml",
        "theme": "splash/themes.xml"
      }
    }
  }
}

Resolution order per platform:

1. Custom file override (storyboard / layout+theme)
2. Platform-specific image/color (splash.{platform}.image)
3. Universal image/color (splash.image)
4. No splash key → blank white screen (backward compatible)

Using npm Packages

Perry natively supports many popular npm packages without any configuration:

// demonstrates: importing built-in stdlib npm packages (project-config.md)
// docs: docs/src/getting-started/project-config.md
// platforms: macos, linux, windows
// run: false

// These four imports are Perry's most-used built-in stdlib shims:
// fastify (HTTP server), mysql2 (db), ioredis (Redis), bcrypt (password
// hashing). They're compiled to native code via Perry's per-package
// implementations — no `compilePackages` needed.
//
// `// run: false` because each one needs a live external service (DB,
// Redis, network port) to actually do anything; the binary still has to
// link cleanly, which is the drift check we want.

import fastify from "fastify"
import mysql from "mysql2/promise"
import Redis from "ioredis"
import bcrypt from "bcrypt"

const app = fastify({ logger: false })
const db = mysql.createPool({ host: "localhost", user: "root", database: "test" })
const redis = new Redis()
const hashed = await bcrypt.hash("hunter2", 10)

console.log(typeof app, typeof db, typeof redis, hashed.length)

These are compiled to native code using Perry’s built-in implementations. See Standard Library for the full list.

For packages not natively supported, use compilePackages for pure TS/JS packages, or the JavaScript runtime fallback for complex packages.

Project Structure

Perry is flexible about project structure. Common patterns:

my-project/
├── package.json
├── src/
│   └── index.ts
└── node_modules/      # Only needed for compilePackages

For UI apps:

my-app/
├── package.json
├── src/
│   ├── index.ts       # Main app entry
│   └── components/    # UI components
└── assets/            # Images, etc.

Compilation

# Compile a file
perry src/index.ts -o build/app

# Compile with a specific target
perry src/index.ts -o build/app --target ios-simulator

# Debug: print intermediate representation
perry src/index.ts --print-hir

See CLI Commands for all options.

Next Steps

• CLI Commands — All compiler commands and flags
• Supported Features — What TypeScript features work
• Standard Library — Supported npm packages

Supported TypeScript Features

Perry compiles a practical subset of TypeScript to native code. This page lists what’s supported.

Primitive Types

function primitives(): void {
    const n: number = 42;
    const s: string = "hello";
    const b: boolean = true;
    const u: undefined = undefined;
    const nl: null = null;

    console.log(`primitives: n=${n} s=${s} b=${b} u=${u} nl=${nl}`)
}

All primitives are represented as 64-bit NaN-boxed values at runtime.

Variables and Constants

function variables(): void {
    let x = 10;
    const y = "immutable";
    var z = true; // var is supported but let/const preferred

    console.log(`variables: x=${x} y=${y} z=${z}`)
}

Perry infers types from initializers — let x = 5 is inferred as number without an explicit annotation.

Functions

function functionsDemo(): void {
    function add(a: number, b: number): number {
        return a + b;
    }

    // Optional parameters
    function greet(name: string, greeting: string = "Hello"): string {
        return `${greeting}, ${name}!`;
    }

    // Rest parameters
    function sum(...nums: number[]): number {
        return nums.reduce((a, b) => a + b, 0);
    }

    // Arrow functions
    const double = (x: number) => x * 2;

    console.log(`functions: add=${add(2, 3)} greet=${greet("Perry")} sum=${sum(1, 2, 3)} double=${double(5)}`)
}

Classes

class Animal {
    name: string;

    constructor(name: string) {
        this.name = name;
    }

    speak(): string {
        return `${this.name} makes a noise`;
    }
}

class Dog extends Animal {
    speak(): string {
        return `${this.name} barks`;
    }
}

// Static methods
class Counter {
    private static instance: Counter;
    private count: number = 0;

    static getInstance(): Counter {
        if (!Counter.instance) {
            Counter.instance = new Counter();
        }
        return Counter.instance;
    }
}

Supported class features:

• Constructors
• Instance and static methods
• Instance and static properties
• Inheritance (extends)
• Method overriding
• instanceof checks (via class ID chain)
• Singleton patterns (static method return type inference)

Enums

// Numeric enums
enum Direction {
    Up,
    Down,
    Left,
    Right,
}

// String enums
enum Color {
    Red = "RED",
    Green = "GREEN",
    Blue = "BLUE",
}

const dir = Direction.Up;
const color = Color.Red;

Enums are compiled to constants and work across modules.

Interfaces and Type Aliases

interface User {
    name: string;
    age: number;
    email?: string;
}

type Point = { x: number; y: number };
type StringOrNumber = string | number;
type Callback = (value: number) => void;

Interfaces and type aliases are erased at compile time (like tsc). They exist only for documentation and editor tooling.

Arrays

function arraysDemo(): void {
    const nums: number[] = [1, 2, 3];

    // Array methods
    nums.push(4);
    nums.pop();
    const len = nums.length;
    const doubled = nums.map((x) => x * 2);
    const filtered = nums.filter((x) => x > 2);
    const sum = nums.reduce((acc, x) => acc + x, 0);
    const found = nums.find((x) => x === 3);
    const idx = nums.indexOf(3);
    const joined = nums.join(", ");
    const sliced = nums.slice(1, 3);
    nums.splice(1, 1);
    nums.unshift(0);
    const sorted = nums.sort((a, b) => a - b);
    const reversed = nums.reverse();
    const includes = nums.includes(3);
    const every = nums.every((x) => x > 0);
    const some = nums.some((x) => x > 2);
    nums.forEach((x) => console.log(x));
    const flat = [[1, 2], [3]].flat();
    const concatted = nums.concat([5, 6]);

    // Array.from
    const arr = Array.from([10, 20, 30]);

    // Array.isArray
    const value: any = [1, 2, 3]
    if (Array.isArray(value)) { /* ... */ }

    // for...of iteration
    for (const item of nums) {
        console.log(item);
    }

    console.log(`arrays: len=${len} doubled=${doubled.length} filtered=${filtered.length} sum=${sum} found=${found} idx=${idx} joined=${joined} sliced=${sliced.length} sorted=${sorted.length} reversed=${reversed.length} includes=${includes} every=${every} some=${some} flat=${flat.length} concatted=${concatted.length} arr=${arr.length}`)
}

Objects

function objectsDemo(): void {
    const obj: { name: string; version: number; [k: string]: any } = { name: "Perry", version: 1 };
    obj.name = "Perry 2";

    // Dynamic property access
    const key = "name";
    const val = obj[key];

    // Object.keys, Object.values, Object.entries
    const keys = Object.keys(obj);
    const values = Object.values(obj);
    const entries = Object.entries(obj);

    // Spread
    const copy = { ...obj, extra: true };

    // delete
    delete obj[key];

    console.log(`objects: val=${val} keys=${keys.length} values=${values.length} entries=${entries.length} copy=${copy.extra}`)
}

Destructuring

function destructuringDemo(): void {
    // Array destructuring
    const [a, b, ...rest] = [1, 2, 3, 4, 5];

    const user = { name: "Alice", age: 30, email: "a@example.com", id: 1 }
    const obj = { id: 2, role: "admin", level: 5 }

    // Object destructuring
    const { name, age, email = "none" } = user;

    // Rename
    const { name: userName } = user;

    // Rest pattern
    const { id, ...remaining } = obj;

    // Function parameter destructuring
    function process({ name, age }: { name: string; age: number }) {
        console.log(name, age);
    }

    process(user)
    console.log(`destructuring: a=${a} b=${b} rest=${rest.length} name=${name} age=${age} email=${email} userName=${userName} id=${id}`)
}

Template Literals

function templateLiteralsDemo(): void {
    const name = "world";
    const greeting = `Hello, ${name}!`;
    const multiline = `
  Line 1
  Line 2
`;
    const expr = `Result: ${1 + 2}`;

    console.log(`template-literals: greeting=${greeting} multiline_len=${multiline.length} expr=${expr}`)
}

Spread and Rest

function spreadRestDemo(): void {
    const arr1 = [1, 2]
    const arr2 = [3, 4]
    const defaults = { theme: "light", size: "md" }
    const overrides = { size: "lg" }

    // Array spread
    const combined = [...arr1, ...arr2];

    // Object spread
    const merged = { ...defaults, ...overrides };

    // Rest parameters
    function log(...args: any[]) { /* ... */ }

    log("a", "b", "c")
    console.log(`spread-rest: combined=${combined.length} merged=${merged.size}`)
}

Closures

function closuresDemo(): void {
    function makeCounter() {
        let count = 0;
        return {
            increment: () => ++count,
            get: () => count,
        };
    }

    const counter = makeCounter();
    counter.increment();
    console.log(counter.get()); // 1
}

Perry performs closure conversion — captured variables are stored in heap-allocated closure objects.

Async/Await

async function asyncAwaitDemo(): Promise<void> {
    interface Profile { id: number; name: string }

    async function fetchUser(id: number): Promise<Profile> {
        // The docs example uses fetch(...) here; we inline a synthetic
        // result so the snippet compiles and runs hermetically.
        return { id, name: `user-${id}` }
    }

    const data = await fetchUser(1);
    console.log(`async-await: id=${data.id} name=${data.name}`)
}

Perry compiles async functions to a state machine backed by Tokio’s async runtime.

Promises

async function promisesDemo(): Promise<void> {
    const p = new Promise<number>((resolve, reject) => {
        resolve(42);
    });

    p.then((value) => console.log(value));

    // Promise.all
    const results = await Promise.all([
        Promise.resolve("a"),
        Promise.resolve("b"),
    ]);

    console.log(`promises: results=${results.length}`)
}

Generators

function generatorsDemo(): void {
    function* range(start: number, end: number) {
        for (let i = start; i < end; i++) {
            yield i;
        }
    }

    for (const n of range(0, 10)) {
        console.log(n);
    }
}

Map and Set

function mapSetDemo(): void {
    const map = new Map<string, number>();
    map.set("a", 1);
    map.get("a");
    map.has("a");
    map.delete("a");
    map.size;

    const set = new Set<number>();
    set.add(1);
    set.has(1);
    set.delete(1);
    set.size;

    console.log(`map-set: map_size=${map.size} set_size=${set.size}`)
}

Regular Expressions

function regexDemo(): void {
    const re = /hello\s+(\w+)/;
    const match = "hello world".match(re);

    if (re.test("hello perry")) {
        console.log("Matched!");
    }

    const replaced = "hello world".replace(/world/, "perry");

    console.log(`regex: match=${match !== null} replaced=${replaced}`)
}

Error Handling

function errorsDemo(): void {
    try {
        throw new Error("something went wrong");
    } catch (e: any) {
        console.log(e.message);
    } finally {
        console.log("cleanup");
    }
}

JSON

function jsonDemo(): void {
    const obj = JSON.parse('{"key": "value"}');
    const str = JSON.stringify(obj);
    const pretty = JSON.stringify(obj, null, 2);

    console.log(`json: str_len=${str.length} pretty_len=${pretty.length}`)
}

typeof and instanceof

function typeofInstanceofDemo(): void {
    const x: any = "hello"
    if (typeof x === "string") {
        console.log(x.length);
    }

    const obj: any = new Dog("Rex")
    if (obj instanceof Dog) {
        obj.speak();
    }
}

typeof checks NaN-boxing tags at runtime. instanceof walks the class ID chain.

Modules

ES module syntax is fully supported: named exports, default exports, and re-exports.

The exporting module:

// Named exports
export function helper(x: number): number { return x + 1 }
export const VALUE = 42

// Default export
export default class MyClass {
    name: string
    constructor(name: string) {
        this.name = name
    }
}

The importing module:

// Default + named imports from a sibling module
import MyClass, { helper, VALUE } from "./utils"

// Re-export
export { helper } from "./utils"

BigInt

function bigintDemo(): void {
    const big = BigInt(9007199254740991);
    const result = big + BigInt(1);

    // Bitwise operations
    const and = big & BigInt(0xFF);
    const or = big | BigInt(0xFF);
    const xor = big ^ BigInt(0xFF);
    const shl = big << BigInt(2);
    const shr = big >> BigInt(2);
    const not = ~big;

    console.log(`bigint: result_ok=${result !== null} and_ok=${and !== null} or_ok=${or !== null}`)
}

String Methods

function stringMethodsDemo(): void {
    const s = "Hello, World!";
    s.length;
    s.toUpperCase();
    s.toLowerCase();
    s.trim();
    s.split(", ");
    s.includes("World");
    s.startsWith("Hello");
    s.endsWith("!");
    s.indexOf("World");
    s.slice(0, 5);
    s.substring(0, 5);
    s.replace("World", "Perry");
    s.repeat(3);
    s.charAt(0);
    s.padStart(20);
    s.padEnd(20);

    console.log(`string-methods: ${s.toUpperCase()}`)
}

Math

function mathDemo(): void {
    Math.floor(3.7);
    Math.ceil(3.2);
    Math.round(3.5);
    Math.abs(-5);
    Math.max(1, 2, 3);
    Math.min(1, 2, 3);
    Math.sqrt(16);
    Math.pow(2, 10);
    Math.random();
    Math.PI;
    Math.E;
    Math.log(10);
    Math.sin(0);
    Math.cos(0);

    console.log(`math: floor=${Math.floor(3.7)} sqrt=${Math.sqrt(16)}`)
}

Date

function dateDemo(): void {
    const now = Date.now();
    const d = new Date();
    d.getTime();
    d.toISOString();

    console.log(`date: now_positive=${now > 0}`)
}

Console

function consoleDemo(): void {
    console.log("message");
    console.error("error");
    console.warn("warning");
    console.time("label");
    console.timeEnd("label");
}

Garbage Collection

Perry includes a mark-sweep garbage collector. It runs automatically when memory pressure is detected (~8MB arena blocks), but you can also trigger it manually:

function gcDemo(): void {
    gc(); // Explicit garbage collection
}

The GC uses conservative stack scanning to find roots and supports arena-allocated objects (arrays, objects) and malloc-allocated objects (strings, closures, promises, BigInts, errors).

JSX/TSX

Perry’s parser and HIR understand JSX syntax (parsed via SWC, lowered in crates/perry-hir/src/jsx.rs) and .tsx files link through Perry’s built-in jsx() / jsxs() runtime path. You do not need a local react/jsx-runtime package just to compile TSX.

import { Box, Text } from "perry/tui";

function Greeting({ name }: { name: string }) {
  return <Text>{`Hello, ${name}!`}</Text>;
}

const page = <div className="card"><Greeting name="Perry" /></div>;
const app = <Box><Greeting name="TUI" /></Box>;

JSX elements are transformed to function calls via the jsx() / jsxs() runtime. Perry’s built-in adapter supports HTML-style intrinsic tags, fragments, function components, and compile-time rewrites for perry/tui Box / Text so those TUI JSX forms lower to the same native builders as the function-call form.

Caveat: this is Perry’s TSX runtime, not React DOM or full React reconciler semantics. For perry/ui, or for perry/tui intrinsics whose JSX rewrite has not landed yet, the function-call form remains the canonical native API.

Next Steps

• Type System — Type inference and checking
• Limitations — What’s not supported yet

Type System

Perry erases types at compile time, similar to how tsc removes type annotations when emitting JavaScript. However, Perry also performs type inference to generate efficient native code.

Type Inference

Perry infers types from expressions without requiring annotations:

function inferenceBasics(): void {
    let x = 5;           // inferred as number
    let s = "hello";     // inferred as string
    let b = true;        // inferred as boolean
    let arr = [1, 2, 3]; // inferred as number[]

    console.log(`inference: x=${x} s=${s} b=${b} arr_len=${arr.length}`)
}

Inference works through:

• Literal values: 5 → number, "hi" → string
• Binary operations: a + b where both are numbers → number
• Variable propagation: if x is number, then let y = x is number
• Method returns: "hello".trim() → string, [1,2].length → number
• Function returns: user-defined function return types are propagated to callers

function inferenceFunction(): void {
    function double(n: number): number {
        return n * 2;
    }
    let result = double(5); // inferred as number

    console.log(`inference-function: result=${result}`)
}

Type Annotations

Standard TypeScript annotations work:

interface Config {
    port: number;
    host: string;
}

function annotations(): void {
    let name: string = "Perry";
    let count: number = 0;
    let items: string[] = [];

    function greet(name: string): string {
        return `Hello, ${name}`;
    }

    const cfg: Config = { port: 8080, host: "localhost" }
    console.log(`annotations: ${greet(name)} count=${count} items=${items.length} port=${cfg.port}`)
}

Utility Types

Common TypeScript utility types are erased at compile time (they don’t affect code generation):

type MyPartial<T> = { [P in keyof T]?: T[P] };
type MyPick<T, K extends keyof T> = { [P in K]: T[P] };
type MyRecord<K extends string, V> = { [P in K]: V };
type MyOmit<T, K extends keyof T> = MyPick<T, Exclude<keyof T, K>>;
type MyReturnType<T extends (...args: any) => any> = T extends (...args: any) => infer R ? R : never;
type MyReadonly<T> = { readonly [P in keyof T]: T[P] };

These are all recognized and erased — they won’t cause compilation errors.

Generics

Generic type parameters are erased:

function identity<T>(value: T): T {
    return value;
}

class Box<T> {
    value: T;
    constructor(value: T) {
        this.value = value;
    }
}

function genericsDemo(): void {
    const box = new Box<number>(42);
    const id = identity<string>("hello")
    console.log(`generics: box.value=${box.value} id=${id}`)
}

At runtime, all values are NaN-boxed — the generic parameter doesn’t affect code generation.

Type Checking with --type-check

For stricter type checking, Perry can integrate with Microsoft’s TypeScript checker:

perry file.ts --type-check

This resolves cross-file types, interfaces, and generics via an IPC protocol. It falls back gracefully if the type checker is not installed.

Without --type-check, Perry relies on its own inference engine, which handles common patterns but doesn’t perform full TypeScript type checking.

Union and Intersection Types

Union types are recognized syntactically but don’t affect code generation:

type StringOrNumber = string | number;

function process(value: StringOrNumber) {
    if (typeof value === "string") {
        console.log(value.toUpperCase());
    } else {
        console.log(value + 1);
    }
}

Use typeof checks for runtime type narrowing.

Type Guards

function isString(value: any): value is string {
    return typeof value === "string";
}

function typeGuardsDemo(): void {
    const x: any = "hello"
    if (isString(x)) {
        console.log(x.toUpperCase());
    }
}

The value is string annotation is erased, but the typeof check works at runtime.

Next Steps

• Supported Features — Complete feature list
• Limitations — What’s not supported

Decorators

This page states Perry’s stance on TypeScript decorators and shows the recommended decorator-free pattern for porting Angular / NestJS / TypeORM code.

Stance

Perry treats decorators as a legacy compatibility surface, not a language primitive. The TypeScript ecosystem has been steadily migrating away from decorators since around 2020 — modern frameworks like Drizzle, Hono, tRPC, Prisma, Zod, SolidJS, and Vue 3’s Composition API use plain functions and schema-as-code. Even Angular’s Ivy compiler already AOT-deletes most decorator metadata at build time, and TC39’s new stage-3 decorator spec deliberately drops the runtime type reflection that NestJS and TypeORM rely on.

Perry still follows the modern direction: types are erased at compile time (see Limitations) and there is no runtime DI container. A small legacy compatibility path exists for libraries that only need AOT-lowerable decorator side effects and metadata. Code that depends on richer decorator behavior still needs one of the patterns below.

What works today

Perry parses legacy / experimental TypeScript decorator syntax and supports two paths:

• Legacy class decorators, method decorators, property decorators, constructor parameter decorators, and method parameter decorators for Nest-style DI and route metadata canaries. Decorator functions run for side effects, Reflect.defineMetadata, Reflect.getMetadata, Reflect.getOwnMetadata, Reflect.hasMetadata, Reflect.hasOwnMetadata, Reflect.getMetadataKeys, Reflect.getOwnMetadataKeys, Reflect.deleteMetadata, and @Reflect.metadata(...) are available. Perry emits design:paramtypes for decorated classes/methods and design:type for decorated properties.
• Compile-time-only transforms. The bundled @log transform is the canonical example — it rewrites a decorated method into a wrapper that prints entry/exit at compile time, with zero runtime decorator machinery. See crates/perry-hir/src/decorator_log.rs for the implementation.

What does not work

• Accessor decorators and descriptor replacement
• Decorator class replacement return values. If a class decorator returns anything other than undefined, Perry throws a TypeError at decorator application time. Real-world decorators like @Memoize, @Throttle, and GraphQL resolver wrappers that return wrapped classes need a Perry-aware port — the lowered class is fixed in the IR and cannot be replaced at runtime.
• General Reflect.metadata(...) helper calls outside decorator syntax
• Symbol(...) as a metadata key
• emitDecoratorMetadata beyond class/method design:paramtypes and property design:type
• Runtime DI containers that resolve dependencies by type beyond the reduced class-constructor canary (tsyringe, full NestJS injector behavior, Angular’s root injector)
• class-validator, type-graphql, TypeORM runtime metadata flows

If your code depends on any of these, the port path is still explicit wiring or a dedicated AOT transform, not relying on the full legacy TypeScript decorator runtime.

Recommended pattern: explicit construction

The Perry-native idiom is plain classes wired together in a single services.ts module in dependency order. This is how a Go or Rust program would compose services, and it is how decorator-free TS frameworks (Hono, tRPC servers, Drizzle apps) already work.

// services.ts
export const api = new ApiService();
export const rating = new RatingService(api);
export const chat = new ChatService(api, rating);

There is no container, no @Injectable, no providedIn: 'root' — construction order is the dependency graph, and it is checked by the TypeScript compiler.

Migration recipe: an Angular service

The example below is a real service from sharity-app (src/app/services/rating.service.ts, ~80 lines), shown in its original Angular form and ported to Perry.

Before — Angular

import { Injectable } from '@angular/core';
import { Observable } from 'rxjs';
import { ApiService } from './api.service';
import { Rating } from '../models/user';

@Injectable({
  providedIn: 'root'
})
export class RatingService {
  private basePath = '/api/ratings';

  constructor(private api: ApiService) { }

  getUserRatings(userId: string): Observable<any> {
    return this.api.get(`${this.basePath}/user/${userId}`);
  }

  createRating(recipientId: string, rating: { stars: number; comment?: string }): Observable<any> {
    return this.api.post(this.basePath, {
      recipientId,
      stars: rating.stars,
      comment: rating.comment,
    });
  }

  calculateAverageRating(ratings: Rating[]): number {
    if (!ratings || ratings.length === 0) return 0;
    const sum = ratings.reduce((acc, curr) => acc + curr.rating, 0);
    return sum / ratings.length;
  }
}

After — Perry

Three mechanical changes:

1. Drop @Injectable. It carried no information that the class shape does not already carry.
2. Replace Observable<T> with Promise<T> for HTTP calls. Most Angular Observables-from-HTTP are single-value and behave like Promises. (For multi-value streams, use AsyncIterable.)
3. Replace constructor-parameter properties (private api: ApiService) with explicit field declarations. Perry supports parameter properties, but explicit fields read more clearly when the class is instantiated by hand rather than by a container.

import { ApiService } from './api.service';
import { Rating } from '../models/user';

export class RatingService {
  private basePath = '/api/ratings';
  private api: ApiService;

  constructor(api: ApiService) {
    this.api = api;
  }

  async getUserRatings(userId: string): Promise<unknown> {
    return this.api.get(`${this.basePath}/user/${userId}`);
  }

  async createRating(
    recipientId: string,
    rating: { stars: number; comment?: string },
  ): Promise<unknown> {
    return this.api.post(this.basePath, {
      recipientId,
      stars: rating.stars,
      comment: rating.comment,
    });
  }

  calculateAverageRating(ratings: Rating[]): number {
    if (!ratings || ratings.length === 0) return 0;
    const sum = ratings.reduce((acc, curr) => acc + curr.rating, 0);
    return sum / ratings.length;
  }
}

Wiring

// services.ts — single source of truth for service construction
import { ApiService } from './services/api.service';
import { RatingService } from './services/rating.service';

export const api = new ApiService();
export const rating = new RatingService(api);

// any consumer
import { rating } from './services';

const avg = rating.calculateAverageRating(myRatings);
const list = await rating.getUserRatings('user-123');

That is the entire migration. The @Injectable decorator, the providedIn: 'root' token, the implicit container lookup — all of it collapses into one new RatingService(api) line in services.ts.

What about Angular components, NestJS controllers, TypeORM entities?

Perry’s reduced legacy path is enough for small Nest-style constructor-injection and route-metadata canaries, but it is not full Angular, NestJS, or TypeORM compatibility. The Path-B option of recognizing @Component / @Controller / @Entity at the compiler level (analogous to Angular Ivy’s AOT step) is reserved for if and when a concrete port needs it — see issue #581 for the tracking discussion. For now, the recommendation is the same: drop the decorator where possible, write the equivalent explicit construction, register routes or schema as plain function calls / module-level constants.

Future direction

New feature work should prefer the TC39 stage-3 form because it aligns better with Perry’s “types erased, compile to native” architecture. The legacy TypeScript path exists for compatibility and will stay focused on narrow AOT-lowerable metadata cases rather than becoming a full tsc decorator runtime.

Limitations

Perry compiles a practical subset of TypeScript. This page documents what’s not supported or works differently from Node.js/tsc.

No Runtime Type Validation

Declared TypeScript types are not enforced at runtime — Perry doesn’t generate type guards from annotations, so a parameter typed string will accept a number without throwing.

function someFunction(): number {
    return 42
}

function erasedTypes(): void {
    // These annotations are erased — no runtime effect
    const x: number = someFunction(); // No runtime check that result is actually a number
    console.log(`erased-types: x=${x}`)
}

Annotations are mostly erased, with one exception: when emitDecoratorMetadata applies, the design:type / design:paramtypes reflection metadata is derived from the annotations on decorated members and survives to runtime (see Decorators). Runtime type discrimination is available via explicit typeof checks and instanceof.

No eval() or Dynamic Code

Perry compiles to native code ahead of time. Dynamic code execution is not possible:

// Not supported
eval("console.log('hi')");
new Function("return 42");

Test262 rows that only observe parsing or executing a code string remain intentional AOT exclusions, not runtime dynamic-code work. This includes the language/white-space/comment-{multi,single}-{form-feed,horizontal-tab,nbsp,space,vertical-tab}.js rows and the direct-eval reference row language/types/reference/8.7.2-1-s.js; they map to the AOT eval tracker (#1677), eval classifier diagnostics (#1678), and the limited literal Function folding work (#1679).

Decorators

Perry parses decorator syntax, supports compile-time-only transforms (see the bundled @log example), and has a reduced legacy TypeScript compatibility path for class decorators, method decorators, constructor parameter decorators, method parameter decorators, and property decorators. That path emits design:paramtypes for decorated classes/methods, design:type for decorated properties, and implements Reflect.defineMetadata, Reflect.getMetadata, Reflect.getOwnMetadata, Reflect.hasMetadata, Reflect.hasOwnMetadata, Reflect.getMetadataKeys, Reflect.getOwnMetadataKeys, Reflect.deleteMetadata, and @Reflect.metadata(...).

Accessor decorators, descriptor replacement, general Reflect.metadata(...) calls outside decorator syntax, Symbol metadata keys, and full Angular / NestJS / TypeORM runtime metadata flows are not supported. See Decorators for details and a worked migration recipe.

No Runtime Metadata Reflection

Perry implements a small metadata subset for legacy decorators. General runtime reflection is not supported:

Reflect.getMetadata("design:type", target, key);
Reflect.getMetadataKeys(target, key);
// Not supported as a general helper call outside decorator syntax
Reflect.metadata("design:type", String)(target, key);

No User-Space CommonJS require()

Use static ESM imports in Perry source:

// Supported
import { foo } from "./module";

// Not supported
const mod = require("./module");
const mod = await import("./module");

Perry has internal CommonJS compatibility paths for some npm package wrappers, but user-written modules should use static import declarations.

Limited Prototype Manipulation

Perry compiles classes to fixed structures. Dynamic prototype modification is not supported:

// Not supported
MyClass.prototype.newMethod = function() {};
Object.setPrototypeOf(obj, proto);

Object.getPrototypeOf(...) and Reflect.getPrototypeOf(...) are supported for class/prototype inspection patterns, but Object.setPrototypeOf(...) / Reflect.setPrototypeOf(...) do not mutate Perry’s fixed class layout.

Weak References Retain Their Targets

WeakMap, WeakSet, WeakRef, and FinalizationRegistry are implemented and their APIs behave as expected — set / get / has / delete, add, deref(), and register / unregister all work and return the right values. WeakMap and WeakSet use reference equality, so two distinct objects never collide on the same slot.

The one caveat is that Perry’s garbage collector does not yet treat these references as weak, so targets are retained rather than collected. The current runtime stores WeakRef targets and FinalizationRegistry registrations in ordinary object/array fields (crates/perry-runtime/src/weakref.rs), and the adjacent GC root scanners do not have a weak-slot clearing/finalizer queue hook yet. In practice:

• WeakRef.deref() always returns the original target (it is never reported as collected).
• FinalizationRegistry records registrations but never fires its cleanup callback.
• WeakMap / WeakSet keep their keys alive (they behave like a reference-keyed Map / Set).

This is safe for correctness — code that reads through these APIs gets the right values. It only matters if you depend on collection timing to reclaim memory or to run finalizer side effects.

Limited Proxy Trapping

Proxy support is not a full engine-level trap layer for every possible dynamic object access. Prefer plain objects and explicit APIs unless a package only needs Perry’s supported Proxy surface.

Threading Model

Perry supports real multi-threading via parallelMap and spawn from perry/thread. See Multi-Threading.

Threads do not share mutable state — closures passed to thread primitives cannot capture mutable variables (enforced at compile time). Values are deep-copied across thread boundaries. There is no SharedArrayBuffer or Atomics.

npm Package Compatibility

Not all npm packages work with Perry:

• Natively supported: ~50 popular packages (fastify, mysql2, redis, etc.) — these are compiled natively. See Standard Library.
• compilePackages: Pure TS/JS packages can be compiled natively via configuration.
• Not supported: Packages requiring native addons (.node files), eval(), dynamic require(), or Node.js internals.

Workarounds

Dynamic Behavior

For cases where you need dynamic behavior, use the JavaScript runtime fallback:

import { jsEval } from "perry/jsruntime";
// Routes specific code through QuickJS for dynamic evaluation

Type Narrowing

Since there’s no runtime type checking, use explicit checks:

function processValue(value: string | number) {
    // Instead of relying on type narrowing from generics
    if (typeof value === "string") {
        // String path
        console.log(`string path: ${value}`)
    } else if (typeof value === "number") {
        // Number path
        console.log(`number path: ${value}`)
    }
}

Next Steps

• Supported Features — What does work
• Type System — How types are handled

Porting npm Packages

Status: experimental. This guide — and the port-npm-to-perry skill that ships alongside it — is a first pass at systematizing what Perry contributors have been doing ad-hoc. Results will vary by package. Feedback at issue #115.

Perry compiles a practical subset of TypeScript. Most pure TS/JS packages can be pulled into a native compile via perry.compilePackages, but some will need small patches to avoid the constructs Perry doesn’t support. This page is a field guide for doing that port — by hand, or by driving a coding agent with the prompt template below.

When porting makes sense

Known-working packages

These work end-to-end via compilePackages with no patches required:

• hono — the full hono app.fetch surface including middleware (hono/logger, hono/cors, hono/jwt), route groups, JSON responses. Enough for testing and edge-runtime deploys (CF Workers / Vercel Edge / Lambda / Deno Deploy). See HTTP & Networking → Hono. Long-lived HTTP server deployment via @hono/node-server or hand-rolled node:http is currently blocked on #589. Closed via issues #421 / #486 / #487 / #577.
• @bradenmacdonald/s3-lite-client — pure-TS AWS S3 / S3-compatible storage client (R2, MinIO, B2, Spaces, Supabase, LocalStack). Full SigV4 signing chain (Put/Get/Head/Delete/List + presigned URLs) verified byte-identical to bun. See HTTP & Networking → AWS S3 for the usage pattern. Closed via #551
  • 15 general-purpose stdlib fixes (Web Crypto, Web Streams subclassing, typed-array marshalling, extends Error, namespace imports, etc.).

The workflow

1. Add it to compilePackages

In your project’s package.json:

{
  "perry": {
    "compilePackages": ["@noble/curves", "@noble/hashes"]
  }
}

This is what tells Perry to pull the package into the native compile instead of routing it through a JavaScript runtime. See Project Configuration for the full semantics — including how first-resolved directories get cached so transitive copies dedup.

2. Try compiling

perry compile src/main.ts -o /tmp/port-test && /tmp/port-test

Most of the time this is where you find out what’s actually broken. Compile-time errors cite a file:line in the package — that’s your patch list.

3. Patch the gaps

See Common gaps for the typical fixes. Keep patches minimal and localized — the goal is a clean compile, not a refactor.

Record each patch in a file at your project root (convention: perry-patches/<package>.md) so you can reapply them after npm install blows them away. Until compilePackages grows a native patch-file convention, this is the one bit of maintenance overhead.

4. Re-check after each compile

Iterate: compile, patch the next error, compile again. Don’t try to catch everything in a single pass — some errors only surface after earlier ones are fixed.

Common gaps

Perry’s full limitations list is the canonical reference. In practice, these are the ones you hit when porting:

Lookbehind regex

Perry uses Rust’s regex crate, which doesn’t support lookbehind ((?<=…) / (?<!…)).

// Not supported
str.match(/(?<=prefix)\w+/);

// Rewrite — capture the prefix and slice
const m = str.match(/prefix(\w+)/);
const rest = m ? m[1] : null;

Symbol

Not supported as a primitive. When a package uses Symbol as a sentinel (the common case — e.g., for unique keys in a registry), swap for a string:

// Before
const REGISTRY_KEY = Symbol("registry");

// After
const REGISTRY_KEY = "__pkg_registry__";

When Symbol is used to implement Symbol.iterator/Symbol.asyncIterator, check whether the iteration is actually reached in your use case — often the class has a for-loop method alongside the iterator and you can ignore the iterator path.

Proxy, Reflect

Not supported. These are usually load-bearing for the package’s public API, so porting is often not feasible. If the Proxy is only in an optional path (e.g., dev-mode warnings), delete that branch.

WeakMap / WeakRef / FinalizationRegistry

Not implemented. Swap WeakMap for a regular Map if the GC semantics aren’t critical for correctness (most caches can tolerate this — they’ll just hold references slightly longer).

Decorators

// Not supported
@Component
class Foo {}

// Remove the decorator and inline the behavior, or use a factory function
const Foo = Component(class Foo {});

Dynamic require() / await import(…)

Perry only supports static imports. If a package branches on typeof require !== "undefined" for a Node/browser split, pick the branch that works natively and delete the other.

Prototype manipulation

// Not supported
Object.setPrototypeOf(obj, proto);
MyClass.prototype.newMethod = function() {};

Usually appears in fallback shims for older runtimes. Often dead code in the Perry path — just delete it.

Computed property keys in object literals

// Not supported
const obj = { [key]: value };

// Rewrite
const obj: Record<string, V> = {};
obj[key] = value;

Using a coding agent

A general coding agent (Claude Code, Cursor, Codex, Aider) can drive most of this workflow. If you’re using a skill-aware agent, invoke the port-npm-to-perry skill directly. Otherwise, paste this prompt:

I want to port the npm package <NAME> to run under Perry
(https://github.com/PerryTS/perry). Perry compiles a subset of TypeScript
natively; the subset's gaps are documented at
https://github.com/PerryTS/perry/blob/main/docs/src/language/limitations.md.

Please:

1. Read the package at node_modules/<NAME>/. Check package.json for
   native addons (binding.gyp, gypfile, prebuilds/ — stop if present).
2. Scan for unsupported constructs: eval, new Function, dynamic require,
   Symbol, Proxy, WeakMap, WeakRef, Reflect, decorators, lookbehind
   regex (?<= / ?<!), Object.setPrototypeOf, computed property keys.
3. Report a triage: what rules the package out vs. what's patchable.
4. If patchable: add the package to perry.compilePackages in
   package.json, apply minimal localized patches, and record each
   patch in perry-patches/<NAME>.md.
5. Verify by running `perry compile` against a small file that imports
   the package.

Don't patch blindly — a grep hit inside a string or comment isn't real.
Show me the triage before applying substantial patches.

This is intentionally an agent-agnostic prompt — it’ll work with any competent coding agent. The skill version bundles the same instructions with richer context and is auto-discovered by Claude Code.

Giving feedback

This whole workflow is experimental. If a port fails in a way that feels like Perry should handle it — or if the guide misses a common gap — please comment on issue #115 so we can iterate.

Native bindings — overview

Perry compiles TypeScript to native executables. When user code says import { createConnection } from "mysql2", the call doesn’t bottom out in JavaScript-engine glue — it lands on a Rust function that’s been linked into the binary as extern "C". This page is the map of how that works end-to-end.

The big picture

There are four layers, from most stable to most flexible:

┌─────────────────────────────────────────────────────────────────┐
│  Layer 4: User TypeScript                                        │
│    import { createConnection } from "mysql2";                     │
│    const c = await createConnection({ host, user, password });    │
│    const [rows] = await c.query("SELECT 1");                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ resolved at compile time → maps to
                              │ js_mysql2_* extern "C" symbols
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 3: Bindings packages                                      │
│    Three sources, queried in this order:                          │
│                                                                   │
│    a. node_modules/<name>/ with perry.nativeLibrary               │
│       → the user installed an external binding via                │
│         `bun add @scope/<name>`. Wins over (b) and (c).           │
│                                                                   │
│    b. node_modules/<name>/ without perry.nativeLibrary            │
│       → fall through to V8/JS interpretation.                     │
│                                                                   │
│    c. well-known table (well_known_bindings.toml)                 │
│       → Perry ships the binding in its install. ~30 names like   │
│         dotenv / mysql2 / axios / ws / lru-cache / commander.     │
│                                                                   │
│    d. nothing matches → resolution error at compile time.         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ all wrapper crates depend on this:
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 2: perry-ffi crate (the stable ABI)                       │
│    pub fn alloc_string(s: &str) -> JsString                       │
│    pub fn read_string(JsString) -> Option<&'static str>           │
│    pub struct JsValue(u64); JsPromise; JsClosure; ...             │
│                                                                   │
│    9 surface dimensions: strings, async/Promise, handle           │
│    registry, JsValue/objects/arrays, binary bytes, closures,     │
│    GC root scanner, BigInt, Buffer, JSON-stringify, event-pump.  │
│                                                                   │
│    Wrapper authors depend ONLY on perry-ffi. perry-runtime's     │
│    internals (NaN-box tags, struct layouts) can change between    │
│    releases without breaking wrappers.                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ implementation detail of:
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 1: perry-runtime / perry-stdlib internals                 │
│    StringHeader / ArrayHeader / ObjectHeader layouts, NaN-      │
│    boxing tags, generational GC, arena allocator, async runtime,│
│    the 30+ in-tree native modules (perry/ui, perry/thread, ...).│
│    Free to change between Perry releases — the perry-ffi semver  │
│    is the only stable contract.                                  │
└─────────────────────────────────────────────────────────────────┘

The whole point: anyone can publish a binding. A third-party crate ships an npm package containing a Rust crate, a package.json with a perry.nativeLibrary block, and prebuilt staticlibs. Users bun add it. Perry’s compiler picks it up automatically. No PR to the Perry repo, no central registry approval, no @perryts/ namespace required.

Worked example: import { createConnection } from "mysql2"

Step by step, what happens when you perry compile a program with that import:

1. Module resolution

Perry’s resolver (crates/perry/src/commands/compile/resolve.rs) walks each search path looking for node_modules/mysql2/:

• If node_modules/mysql2/package.json exists with a perry.nativeLibrary block: parse the manifest, treat the package as a native binding. Skip layers (c) and (d).
• If node_modules/mysql2/ exists without a perry.nativeLibrary block: this is a JS-only npm package; fall through to the V8 / JS interpretation path (separate compilation flow).
• If node_modules/mysql2/ doesn’t exist at all: consult the well-known table at crates/perry/well_known_bindings.toml. The table maps mysql2 → perry-ext-mysql2 (a Rust crate that ships in the Perry install). The user didn’t npm install anything; Perry handles it.
• If nothing matches: compile error pointing at the import line.

2. ABI version check

If the resolved binding has a perry.nativeLibrary.abiVersion field (required from v0.6.0 onwards; warning-only in v0.5.x), Perry verifies the declared semver range covers the bundled perry-ffi version. A binding declaring "0.5" loads under any 0.5.x Perry; one declaring "^1.0" loads only under 1.x. Mismatches are a hard compile error with a recipe pointing at the offending package.

See manifest-v1.md for the full schema.

3. Symbol mapping

The manifest’s functions[] block lists every extern "C" symbol the staticlib exports plus their TypeScript-visible signature:

{
  "functions": [
    {
      "name": "js_mysql2_create_connection",
      "params": ["jsvalue"],
      "returns": "promise"
    },
    {
      "name": "js_mysql2_connection_query",
      "params": ["i64", "string", "jsvalue"],
      "returns": "promise"
    }
  ]
}

Perry’s codegen translates the user’s TS-side calls (mysql.createConnection(config), c.query(sql, params)) into direct calls to these symbols, with the right argument coercion (JsValue NaN-box ↔ f64 ABI shim, string-pointer extraction, etc.).

Those manifest entries are native ABI descriptors, not TypeScript types. A descriptor like f32 or usize chooses the native slot used for the C call and still appears to user code as a JavaScript number; buffer+len consumes one Buffer/Uint8Array-shaped argument and emits (ptr, usize) native slots; handle<T> and promise<T> carry metadata while remaining opaque runtime handles at the boundary. See manifest-v1.md for the full descriptor vocabulary and the legacy string aliases that remain accepted.

4. Linking

The staticlib (libperry_ext_mysql2.a for the well-known case, or a prebuilt artifact in node_modules/mysql2/prebuilt/<target>/ for the external case) joins the link line alongside libperry_runtime.a and libperry_stdlib.a. The js_mysql2_* symbol references in the user’s compiled code resolve at link time.

If the binding ships only Rust source (no prebuilt), Perry runs cargo build --release on the wrapper at compile time. Slow first build, then cached.

5. Runtime

User code runs. Calls into js_mysql2_* happen at native speed — function call overhead is one register-pass for the receiver handle plus one each per param. Promise resolution / closure invocation / async work bridge through perry-ffi’s surface (JsPromise, JsClosure, spawn_blocking + tokio::Handle::current().block_on). The wrapper sees Perry’s NaN-boxed JsValues directly; user TypeScript sees a normal Promise / object / array.

What perry-ffi guarantees

The 9 surface dimensions perry-ffi exposes today are:

A wrapper that uses anything outside this list (e.g. reaches into perry_runtime::* types directly) is off-contract — its build will break the next time those types change. Stay on perry-ffi.

The abi.md page is the source of truth for what’s in each surface. The semver promise: breaking changes to anything documented there bump perry-ffi major, regardless of what perry-runtime does internally.

Code organization

crates/
  perry-ffi/              ← Layer 2: the stable ABI surface
  perry-runtime/          ← Layer 1: NaN-boxing, GC, arena, JS objects
  perry-stdlib/           ← Layer 1: in-tree wrappers (perry/ui, fs,
                            crypto helpers, etc. — anything genuinely
                            coupled to runtime internals)
  perry-ext-<name>/       ← Layer 3, well-known: mysql2, pg, ioredis,
                            cron, decimal, dayjs, axios, ethers,
                            commander, … (~27 today). All depend on
                            perry-ffi only.

External native bindings (Layer 3, third-party — Rust + perry-ffi):
  PerryTS/tursodb-bindings    → bun add @perryts/tursodb
  PerryTS/iroh-bindings       → bun add @perryts/iroh
  <anyone>/whatever-bindings  → user publishes themselves

External pure-TypeScript drivers (compiled via compilePackages):
  PerryTS/postgres            → bun add @perryts/postgres
  PerryTS/mysql               → bun add @perryts/mysql
  PerryTS/mongodb             → bun add @perryts/mongodb
  PerryTS/redis               → bun add @perryts/redis

The split between well-known in-tree wrappers and external is a packaging convention, not a technical distinction. Both depend only on perry-ffi; both ship extern "C" symbols Perry’s codegen calls. The well-known set is the ~30 packages every JS dev expects to import without an npm install step (dotenv, axios, mysql2, …). External wrappers are everything else.

The two existing external native wrappers (tursodb, iroh) cover functionality that doesn’t have an in-tree perry-stdlib equivalent — they’re net-new bindings that originated as third-party packages. That validates the contract: perry-ffi is sufficient to write a real wrapper without forking Perry.

Three paths to a database driver (postgres / mysql / mongodb / redis)

Perry currently ships two parallel database-driver families. Picking one is a packaging trade-off, not a feature trade-off:

Resolution precedence (per layer (a) → (b) → (c) above): an installed @perryts/mysql does not override import 'mysql2' because the package names are different. If you bun add @perryts/mysql and also import 'mysql2' in the same program, both drivers ship in the binary — they’re independent. To opt out of the well-known mysql2 shim, just don’t import mysql2.

When to pick which:

• Well-known native (mysql2 / pg / mongodb) — zero install step, fastest path to “it works”; you accept that the driver’s feature set tracks Perry’s release cadence.
• @perryts/postgres / @perryts/mysql / @perryts/mongodb / @perryts/redis — you want to read / fork / patch the driver in plain TypeScript; you want the same code running on Node.js or Bun for fallback; you need a feature ahead of Perry’s next release.
• External native binding — you’re wrapping a Rust crate that doesn’t have a JS-only equivalent (Tursodb’s embedded SQLite- compatible engine, Iroh’s QUIC transport).

Concrete how-tos

Authoring a binding — the 60-second tour

# Scaffold
perry native init my-pdf --description "PDF rendering bindings" \
  --upstream-dep 'pdfium-render = "0.8"'
cd my-pdf

# Edit src/lib.rs — add your `js_*` functions, all using only
# `perry_ffi::*` types
$EDITOR src/lib.rs

# Edit src/index.ts — declare the TS surface user code imports
$EDITOR src/index.ts

# Edit package.json — list every js_* export in the
# perry.nativeLibrary.functions[] block
$EDITOR package.json

# Verify
perry native validate
# ✅ manifest matches the staticlib

# Publish
git tag v0.1.0 && git push --tags  # the scaffolded release.yml
                                    # builds prebuilts for all targets
                                    # and attaches them to the release
npm publish

A user can now bun add my-pdf and import { renderPdf } from "my-pdf" in their Perry program.

Versioning policy

• perry-ffi semver: tracks Perry’s minor today (perry-ffi = "0.5" for Perry 0.5.x). Backwards-incompatible changes to anything documented in abi.md bump perry-ffi major — independent of perry-runtime. Wrappers depend on perry-ffi = "0.5" and stay buildable across Perry’s 0.5.x releases.
• Manifest spec v1: locked at abiVersion: "0.5"; missing field is warning-only in v0.5.x, hard error from v0.6.0. Schema changes bump the spec version (v2) and ship alongside a new manifest schema file.
• Wrappers: each ships independent semver; users bun update a binding without touching Perry.

Consumption today (v0.5.x)

Until the v0.6.0 type-source-of-truth refactor lands, perry-ffi is not yet on crates.io. External wrappers depend on it via git URL:

[dependencies]
perry-ffi = { git = "https://github.com/PerryTS/perry", branch = "main" }

PerryTS/tursodb-bindings and PerryTS/iroh-bindings use this shape and cargo build against live main. The git-URL approach is the supported consumption mechanism for the v0.5.x cycle; the v0.6.0 plan inverts type ownership so perry-ffi becomes the source of truth and can publish to crates.io as perry-ffi = "0.6".

Limits

• Bindings are build-time linked. Perry doesn’t dlopen plugins at runtime — the staticlib joins the link line, the binary stands on its own.
• Bindings can’t bring their own JS runtime — they extend Perry’s, not replace it. A binding that wants its own GC / event loop / threading is out of scope.
• Cross-target prebuilds are the binding author’s responsibility. The scaffolded GitHub Actions workflow handles the common matrix (x86_64+aarch64 macOS/Linux + Windows); other targets need manual additions.

Next pages

• abi.md — the perry-ffi surface, reference grade.
• manifest-v1.md — the perry.nativeLibrary schema, every field documented.
• API reference — auto-generated list of every stdlib symbol Perry implements.

Authoring a native binding

Step-by-step guide to writing and publishing a Rust binding that Perry programs can import like any npm package.

For the architectural picture this fits into, see Native bindings — overview.

Prerequisites

• A Rust crate you want to expose to TypeScript (e.g. pdfium-render, image, your own internal library).
• Rust toolchain installed.
• perry on your PATH (the perry native subcommand ships with the install).
• A GitHub account if you want the prebuild release-CI scaffold to Just Work.

1. Scaffold

perry native init my-bindings \
  --description "Native bindings for <upstream crate>" \
  --upstream-dep '<crate-name> = "<version>"' \
  --github-owner <your-handle>

cd my-bindings

This creates:

my-bindings/
├── Cargo.toml                           # perry-ffi dep + your upstream
├── src/
│   ├── lib.rs                           # one example #[no_mangle] fn
│   └── index.ts                         # TS surface user code imports
├── package.json                         # perry.nativeLibrary block
├── README.md
├── LICENSE                              # MIT, swap if needed
├── .gitignore
└── .github/workflows/release.yml        # multi-target prebuild on tag

2. Add bindings

Each TypeScript-visible function should forward to one extern "C" Rust export.

src/lib.rs

The example template starts with one js_<name>_hello function. Replace it with your bindings — one #[no_mangle] pub extern "C" fn per TypeScript-visible call, using only types from perry_ffi:

#![allow(unused)]
fn main() {
use perry_ffi::{alloc_string, StringHeader};

/// `pdf.parse(buf) -> string` — extract text from a PDF buffer.
///
/// # Safety
///
/// `buf_ptr` must be null or valid for `buf_len` bytes. Perry passes
/// this pair from a `buffer+len` manifest parameter.
#[no_mangle]
pub unsafe extern "C" fn js_pdf_parse(buf_ptr: *const u8, buf_len: usize) -> *mut StringHeader {
    let bytes = if buf_ptr.is_null() {
        &[]
    } else {
        std::slice::from_raw_parts(buf_ptr, buf_len)
    };
    match pdfium_render::Pdfium::default().load_pdf_from_byte_slice(bytes, None) {
        Ok(doc) => {
            let text = doc.pages().iter().map(|p| p.text().unwrap()).collect::<String>();
            alloc_string(&text).as_raw()
        }
        Err(_) => std::ptr::null_mut(),
    }
}
}

Key rules:

• Don’t use perry_runtime::*. perry-runtime’s internals (NaN-box tags, struct layouts) change between Perry releases. perry-ffi is the stable contract.
• Use unsafe extern "C" for any function that takes pointer args. *const StringHeader etc. require unsafe at the call site.
• Document # Safety for unsafe fns — at minimum say “the pointer must be null or a Perry-runtime <Header>”.
• Async returns *mut Promise. Pattern: JsPromise::new() → spawn_blocking(move || { tokio::runtime::Handle::current().block_on(async {...}); promise.resolve(...) }) → return promise.as_raw().

src/index.ts

Declare the FFI symbol from your manifest, then export the TypeScript surface user code imports. Perry’s FFI dispatch keys on the call-site identifier, so the wrapper body must explicitly call the js_* symbol listed in perry.nativeLibrary.functions[].

declare function js_pdf_parse(buf: Uint8Array): string;

/**
 * Extract text from a PDF buffer.
 */
export function parse(buf: Uint8Array): string {
  return js_pdf_parse(buf);
}

package.json

The perry.nativeLibrary block tells Perry’s compiler about every extern "C" export plus the build config. Schema details in manifest-v1.md.

{
  "name": "my-bindings",
  "version": "0.1.0",
  "main": "src/index.ts",
  "types": "src/index.ts",
  "perry": {
    "nativeLibrary": {
      "abiVersion": "0.5",
      "functions": [
        {
          "name": "js_pdf_parse",
          "params": [{ "kind": "buffer+len" }],
          "returns": "string"
        }
      ],
      "targets": {
        "macos":   { "crate": "native", "lib": "perry_ext_my_bindings" },
        "linux":   { "crate": "native", "lib": "perry_ext_my_bindings" },
        "windows": { "crate": "native", "lib": "perry_ext_my_bindings" }
      }
    }
  }
}

Every entry in functions[] must:

• have a name matching exactly the symbol the staticlib exports (Perry’s perry native validate verifies this for you)
• declare params and returns so codegen knows the calling convention

Manifest descriptors are native ABI descriptors, not TypeScript surface types. Existing strings such as "string", "number", "i64", and "void" still work. Use the explicit vocabulary when you need native precision or metadata: "f32", "u32", "u64", "usize", "buffer_len", { "kind": "buffer+len" }, { "kind": "handle", "type": "MyThing" }, and { "kind": "promise", "result": "jsvalue" }.

Handles are opaque Perry native handle objects in JavaScript, not raw numbers. Legacy "handle" and "handle<T>" descriptors still parse as borrowed handles; structured descriptors can add ownership, nullability, thread affinity, debug names, and an owned-return finalizer:

{
  "kind": "handle",
  "type": "MyThing",
  "ownership": "owned",
  "thread": "creator",
  "finalizer": "my_thing_free",
  "debugName": "MyThing"
}

The finalizer symbol must use void(ptr, ptr) ABI and must only free native resources. It can run from GC finalization, so it must not call Perry JS APIs or allocate JS values. Use "ptr" when an API intentionally accepts a raw pointer payload instead of a managed handle.

3. Verify

perry native validate

This runs cargo build --release, locates the resulting .a, walks nm -gP over its symbols, and diffs against the manifest’s functions[]. The output flags two failure modes:

• ❌ declared function has NO matching symbol — your manifest lists a function the staticlib doesn’t export. Either you typo’d the name, or you forgot #[no_mangle].
• ⚠ js_* symbol NOT in the manifest — your staticlib exports a function user code can’t reach. Either add it to functions[], rename it (drop the js_ prefix), or remove it.

A green run looks like:

perry native validate
======================
  package:    my-bindings
  abiVersion: 0.5
  staticlib:  ./target/release/libperry_ext_my_bindings.a
  declared functions:           1
  exported `js_*` symbols:      1
  ✅ manifest matches the staticlib.

4. Test in a Perry program

In a separate directory:

mkdir test-app && cd test-app
perry init
bun add file:../my-bindings   # or any path your tooling supports

Add to your TS:

import { parse } from "my-bindings";
const buf = await Bun.file("input.pdf").bytes();
console.log(parse(buf));

Then perry compile main.ts -o main && ./main.

5. Publish

Tag a release

git tag v0.1.0
git push --tags

The scaffolded .github/workflows/release.yml builds prebuilt staticlibs for x86_64 + aarch64 macOS/Linux + Windows on tag and attaches them to the GitHub release. Add or remove targets in the workflow’s matrix block as needed.

npm publish

npm publish

The scaffolded package.json includes the right files: [...] list to bundle src/ + Cargo.toml + the README. If you also vendor the prebuilt artifacts in the npm tarball, add them to the files block.

Two distribution models

There are two ways your users get the staticlib:

Vendoring is the friendlier default for npm consumers. Source-only makes sense if your matrix is too big for one tarball or if you’re publishing a private wrapper to a small audience.

The manifest’s targets.<target>.prebuilt field tells Perry where to find a prebuilt for the user’s compile target:

{
  "perry": {
    "nativeLibrary": {
      "targets": {
        "macos":   { "prebuilt": "./prebuilt/macos/libperry_ext_my_bindings.a" },
        "linux":   { "prebuilt": "./prebuilt/linux/libperry_ext_my_bindings.a" },
        "windows": { "prebuilt": "./prebuilt/windows/perry_ext_my_bindings.lib" }
      }
    }
  }
}

If a prebuilt field is present, Perry treats the archive as required for that target and fails with a diagnostic when it cannot be resolved or linked. Omit prebuilt and provide crate / lib when the target should build from source instead.

Backend-aware packaging

Graphics or compute wrappers can describe backend-owned artifacts without adding app-specific APIs to Perry. Put backend metadata under the target that can actually use it:

{
  "perry": {
    "nativeLibrary": {
      "targets": {
        "ios": {
          "prebuilt": "./prebuilt/ios/libdemo.a",
          "backends": {
            "metal": {
              "frameworks": ["Metal", "QuartzCore"],
              "shaderSources": ["shaders/default.metal"],
              "shaderOutputs": ["prebuilt/default.metallib"],
              "resources": ["resources/metal"]
            }
          }
        },
        "linux": {
          "prebuilt": "./prebuilt/linux/libdemo.a",
          "backends": {
            "vulkan": {
              "libs": ["vulkan"],
              "shaderOutputs": ["prebuilt/default.spv"]
            }
          }
        },
        "windows": {
          "prebuilt": "./prebuilt/windows/demo.lib",
          "backends": {
            "d3d12": {
              "libs": ["d3d12", "dxgi", "dxguid"],
              "shaderOutputs": ["prebuilt/default.dxil"]
            }
          }
        }
      }
    }
  }
}

Perry validates the backend/target pairing early: Metal is Apple-only, Vulkan is available on macOS/Linux/Windows/Android/HarmonyOS, and D3D12 is Windows-only. Precompiled shader outputs and resources are copied under NativeLibraries/<package>/<backend>/ in app bundles.

6. Update over time

• A new perry-ffi feature lands: bump your Cargo.toml’s perry-ffi version, rebuild prebuilts, tag a new release. Users bun update to pick it up. Perry’s manifest spec stays at v1 unless the schema changes.
• A new Perry minor: same — perry-ffi’s semver moves with Perry’s minor. The git-URL consumption (v0.5.x) means rebuilding against main picks it up automatically.
• Breaking change to the js_* surface you exported: bump your package’s major version (1.0.0 → 2.0.0). Users who pin a major aren’t affected.

Common patterns

Async one-shot (HTTP request, DB query)

#![allow(unused)]
fn main() {
use perry_ffi::{alloc_string, spawn_blocking, JsPromise, JsValue, Promise};

#[no_mangle]
pub extern "C" fn js_my_fetch(url_ptr: *const StringHeader) -> *mut Promise {
    let promise = JsPromise::new();
    let raw = promise.as_raw();
    let url = unsafe { read_str(url_ptr) }.unwrap_or_default();

    spawn_blocking(move || {
        let outcome = tokio::runtime::Handle::current().block_on(async move {
            reqwest::get(&url).await.and_then(|r| Ok(r.text())).await
        });
        match outcome {
            Ok(body) => promise.resolve(JsValue::from_string_ptr(alloc_string(&body).as_raw())),
            Err(e)   => promise.reject_string(&format!("fetch: {}", e)),
        }
    });
    raw
}
}

Sync handle-based class

Use a handle descriptor for synchronous resource-style APIs. The native function receives or returns the raw resource pointer as i64, while TypeScript callers see only the opaque handle object.

#![allow(unused)]
fn main() {
use perry_ffi::{get_handle, register_handle, Handle};

pub struct MyThing { val: u64 }

#[no_mangle]
pub extern "C" fn js_my_thing_new() -> Handle {
    register_handle(MyThing { val: 0 })
}

#[no_mangle]
pub extern "C" fn js_my_thing_get(h: Handle) -> f64 {
    get_handle::<MyThing>(h).map(|t| t.val as f64).unwrap_or(0.0)
}
}

Event listeners (.on(event, cb))

#![allow(unused)]
fn main() {
use perry_ffi::{
    gc_register_root_scanner, get_handle_mut, iter_handles_of, register_handle,
    Handle, JsClosure, RawClosureHeader, StringHeader,
};

pub struct EventEmitter {
    listeners: Vec<i64>,  // closure pointers, kept alive by the GC scanner below
}

static SCANNER_REGISTERED: std::sync::Once = std::sync::Once::new();

fn ensure_scanner() {
    SCANNER_REGISTERED.call_once(|| {
        gc_register_root_scanner(|mark| {
            iter_handles_of::<EventEmitter, _>(|emitter| {
                for &cb in &emitter.listeners {
                    if cb != 0 {
                        let nan_boxed = f64::from_bits(0x7FFD_0000_0000_0000 | (cb as u64 & 0x0000_FFFF_FFFF_FFFF));
                        mark(nan_boxed);
                    }
                }
            });
        });
    });
}

#[no_mangle]
pub extern "C" fn js_emitter_on(h: Handle, cb: i64) -> Handle {
    ensure_scanner();
    if let Some(e) = get_handle_mut::<EventEmitter>(h) {
        e.listeners.push(cb);
    }
    h
}

#[no_mangle]
pub extern "C" fn js_emitter_emit(h: Handle, arg: f64) -> bool {
    if let Some(e) = get_handle_mut::<EventEmitter>(h) {
        for &cb in e.listeners.clone().iter() {
            let closure = unsafe { JsClosure::from_raw(cb as *const RawClosureHeader) };
            let _ = unsafe { closure.call1(arg) };
        }
        true
    } else {
        false
    }
}
}

The GC scanner is load-bearing: without it, a malloc-triggered GC between .on(cb) and .emit() will sweep the closure and the next emit calls freed memory. Always register a scanner if your handles store closure pointers.

When to extend the perry-ffi surface

If your binding genuinely needs something perry-ffi doesn’t expose, file an issue against PerryTS/perry describing:

• the binding you’re writing,
• the perry-runtime function/type you’d otherwise reach into,
• why a higher-level perry-ffi entry would generalize.

The bar for adding to perry-ffi is high — every helper is a forever commitment — but real wrappers driving real needs is exactly the right input. The recent additions (BigInt + Buffer in v0.5.556, JSON-stringify + event-pump in v0.5.567 followups) all came from specific wrappers needing them.

Don’t reach into perry_runtime::* directly to “unblock” your wrapper today — it’ll break the next time those internals change.

See also

• overview.md — the architectural picture.
• abi.md — perry-ffi reference.
• manifest-v1.md — the manifest schema in full.
• PerryTS/tursodb-bindings and PerryTS/iroh-bindings for end-to-end real-world examples.

perry-ffi — the stable ABI for native bindings

This page documents the contract between native bindings packages (perryts/mysql2-bindings, @perry/iroh, perry-ext-dotenv, …) and the Perry runtime they execute inside.

New here? Start with Native Bindings — Overview for the architectural picture and the Authoring Guide for the step-by-step. This page is reference-grade detail.

It is intentionally short. The whole point of the contract is minimum surface area — every helper added is a forever commitment, and Perry’s internals (string layout, NaN-boxing tags, GC) are free to change underneath as long as this surface holds.

Versioning

perry-ffi ships its own semver, currently tracking Perry’s minor: perry-ffi = "0.5" for Perry 0.5.x.

v0.5.x consumption (current): until the v0.6.0 type-source-of-truth refactor lands, perry-ffi re-exports a handful of types from perry-runtime (StringHeader, ArrayHeader, ObjectHeader, BigIntHeader, BufferHeader, ClosureHeader, Promise). That makes it un-publishable to crates.io as-is — perry-runtime is a private dep and not something we want on crates.io. Wrappers depend on perry-ffi via the git URL while we’re in the v0.5.x cycle:

[dependencies]
perry-ffi = { git = "https://github.com/PerryTS/perry", branch = "main" }

PerryTS/tursodb-bindings and PerryTS/iroh-bindings ship this shape and cargo build against the live main branch.

v0.6.0 plan (deferred): invert the type ownership so perry-ffi becomes the source of truth — it defines #[repr(C)] versions of the ABI types itself, exposes opaque pointers for Promise / ClosureHeader (which have private state), and perry-runtime imports the types from perry-ffi. At that point perry-ffi has zero perry-runtime deps and can publish to crates.io as perry-ffi = "0.6" — wrappers switch to cargo add perry-ffi. Tracked under #466 Phase 1 as a v0.6.0 followup; the v0.5.x git-URL approach is supported and tested end-to-end in the meantime.

A wrapper’s package.json declares the ABI it was built against:

{
  "perry": {
    "nativeLibrary": {
      "abiVersion": "0.5",
      "...": "..."
    }
  }
}

The Perry compiler refuses to load a wrapper whose declared abiVersion doesn’t satisfy the bundled perry-ffi’s semver range (strict enforcement lands under issue #466 Phase 2). Backwards- incompatible changes to anything in this document bump perry-ffi’s major version — independent of perry-runtime semver.

Surface (v0.5.x)

The current surface is deliberately minimal — just enough to port the simplest stdlib wrappers (dotenv, nanoid, uuid, slugify). It will grow as real wrappers demand it; we’d rather under-design and add than commit to a helper we later regret.

Strings

#![allow(unused)]
fn main() {
pub struct JsString(/* opaque */);

pub fn alloc_string(s: &str) -> JsString;
pub fn read_string(handle: JsString) -> Option<&'static str>;

impl JsString {
    pub unsafe fn from_raw(ptr: *mut StringHeader) -> Self;
    pub fn as_raw(self) -> *mut StringHeader;
    pub fn is_null(self) -> bool;
}

pub use perry_runtime::StringHeader; // for `*mut StringHeader` in extern "C" sigs
}

alloc_string allocates a fresh string in the runtime’s arena. The handle is owned by the runtime — Perry’s GC reclaims it once no live references remain, including references held by JS code your function returned the handle to.

read_string borrows the underlying UTF-8 bytes for the duration of the FFI call. Returns None on a null handle or invalid UTF-8.

StringHeader is re-exported as the canonical type for extern "C" return / parameter types — wrappers should write pub extern "C" fn js_my_module_thing() -> *mut perry_ffi::StringHeader, not import StringHeader from perry-runtime directly.

What’s NOT in v0.5

These will land as real wrappers force them, tracked under #466 Phase 1’s “Open questions”:

• Array allocation / read (alloc_array, read_array).
• Object field get / set.
• Closure invocation helpers.
• NaN-boxing constants (undefined / null / true / false).
• Async runtime sharing (spawn_async, block_on).
• BigInt allocation.

If your wrapper needs one of these today, add it to perry-ffi in the same PR that ports the wrapper. Treat this document as the review gate: any addition needs a one-line entry above and a unit test in crates/perry-ffi/src/lib.rs.

Reference example: perry-ext-dotenv

The smallest stdlib wrapper Perry ships is the acceptance test for the surface above. Its full FFI surface is two functions:

#![allow(unused)]
fn main() {
use perry_ffi::{alloc_string, read_string, JsString, StringHeader};

#[no_mangle]
pub unsafe extern "C" fn js_dotenv_config_path(
    path_ptr: *const StringHeader,
) -> f64 {
    let handle = JsString::from_raw(path_ptr as *mut _);
    let path = read_string(handle).unwrap_or(".env");
    // … read file, set env vars, return 1.0 / 0.0 …
}

#[no_mangle]
pub unsafe extern "C" fn js_dotenv_parse(
    content_ptr: *const StringHeader,
) -> *mut StringHeader {
    let handle = JsString::from_raw(content_ptr as *mut _);
    let Some(content) = read_string(handle) else {
        return std::ptr::null_mut();
    };
    let parsed = parse_dotenv_content(content);
    let json = serde_json::to_string(&parsed).unwrap_or_else(|_| "{}".into());
    alloc_string(&json).as_raw()
}
}

Source: crates/perry-ext-dotenv/src/lib.rs.

It depends only on perry-ffi and serde_json. Zero references to perry-runtime internals. That’s the bar for every wrapper that moves out of perry-stdlib over the course of #466 Phase 5.

Followup roadmap

• #466 Phase 2 freezes the perry.nativeLibrary manifest spec and enforces abiVersion at resolve time.
• #466 Phase 3 adds perry native init/validate/prebuild for scaffolding new wrapper packages.
• #466 Phase 4 adds the well-known bindings table so import 'dotenv' resolves to perry-ext-dotenv automatically — until it lands, import 'dotenv' continues to bind to the perry-stdlib copy.
• #466 Phase 5 ports the rest of the wrappers in size order (uuid, nanoid, slugify, bcrypt, argon2, then ws, then the database batch).

perry.nativeLibrary manifest — spec v1

New here? Start with Native Bindings — Overview for the architectural picture and the Authoring Guide for a step-by-step that uses this manifest. This page is reference-grade detail.

This page is the authoritative spec for the perry.nativeLibrary field a native-bindings package declares in its package.json. The Perry compiler reads this manifest at resolve time and uses it to:

1. Decide whether the import is “native” (calls into a Rust staticlib) vs. plain TypeScript / JavaScript.
2. Map TypeScript-side function calls onto the right extern "C" symbol with the right calling convention.
3. Pull the right .a archive into the link line, with the right frameworks / system libs / pkg-config dependencies for the user’s compile target.

A companion JSON schema lives at docs/api/manifest.schema.json for editor validation.

Versioning

The schema is versioned via the abiVersion field. Every wrapper declares which perry-ffi ABI it was built against:

{
  "perry": {
    "nativeLibrary": {
      "abiVersion": "0.5",
      "...": "..."
    }
  }
}

The perry binary refuses to load a wrapper whose declared abiVersion doesn’t satisfy the bundled perry-ffi’s semver range.

Transitional rule for the v0.5.x cycle: missing abiVersion is allowed but emits a warning naming the package and pointing at this spec. From v0.6.0 onwards it becomes a hard error.

See docs/src/native-libraries/abi.md for what the v0.5 ABI surface actually contains.

Top-level shape

{
  "perry": {
    "nativeLibrary": {
      // Required from v0.6.0; warning-only in v0.5.x.
      "abiVersion": "0.5",

      // FFI function declarations — what TypeScript-side
      // call sites bind to. See "Functions" below.
      "functions": [
        { "name": "js_my_thing", "params": ["string"], "returns": "string" }
      ],

      // Per-target build configuration. Optional; if omitted, no
      // crate is built and the wrapper is purely a `.d.ts`-style
      // declaration of pre-built symbols (rare).
      "targets": {
        "macos":     { "...": "..." },
        "ios":       { "...": "..." },
        "linux":     { "...": "..." },
        "windows":   { "...": "..." },
        "android":   { "...": "..." },
        "web":       { "...": "..." },
        "harmonyos": { "...": "..." },
        "tvos":      { "...": "..." },
        "watchos":   { "...": "..." },
        "visionos":  { "...": "..." }
      }
    }
  }
}

abiVersion

Semver string (e.g. "0.5", "0.5.3", "^0.5").

The compiler interprets this as a range. The range must include the bundled perry-ffi’s exact version. A wrapper declaring "0.5" loads under any 0.5.x Perry; one declaring "0.5.3" loads only when the runtime is exactly 0.5.3.

When the runtime fails the range check, compilation aborts with:

error: native library `<package>` declares perry-ffi ABI "0.5"
         but this Perry build ships perry-ffi 0.6.1.
       Update the package or use an older Perry release.

functions

Array of function declarations. Each entry binds a TypeScript-visible name to an extern "C" symbol exported by the wrapper’s staticlib.

ABI descriptors describe the native calling convention, not the TypeScript type system. Perry keeps three layers separate:

• JS-visible values (number, string, opaque handles, promises)
• native ABI descriptors in the manifest (f32, usize, buffer+len)
• lowered LLVM/C ABI slots (double, i64, ptr, etc.)

Existing string spellings remain valid. The canonical descriptor vocabulary is:

jsvalue, string, bool, i32, i64, i64_str, u32, u64, usize,
f32, f64, number, ptr, buffer_len, buffer+len, handle<T>,
promise<T>, pod, void

number is a compatibility alias for f64; js_value and boolean are compatibility aliases for jsvalue and bool. Bare handle is the same as an untyped handle<T>. Bare promise is the same as promise<jsvalue>. Unlike handles and promises, pod has no string-only spelling; use object form so the field order and scalar ABI types are explicit.

Descriptors with metadata may also use object form:

{ "kind": "handle", "type": "MyThing" }
{
  "kind": "handle",
  "type": "MyThing",
  "ownership": "owned",
  "nullable": true,
  "thread": "creator",
  "finalizer": "my_thing_free",
  "debugName": "MyThing"
}
{ "kind": "promise", "result": "jsvalue" }
{ "kind": "buffer+len" }
{
  "kind": "pod",
  "name": "Packet",
  "fields": [
    { "name": "tag", "type": "u32" },
    { "name": "count", "type": "usize" },
    { "name": "weight", "abi": { "kind": "f32" } }
  ]
}

Structured handles are GC-managed Perry native handle objects on the JavaScript side. They are opaque and branded; user code cannot forge a valid handle by passing a number or ordinary object. Use "ptr" only when you intentionally want the raw pointer payload escape hatch.

Handle fields:

POD descriptors are parameter-only. A POD parameter describes one closed JavaScript object shape that Perry can copy into verifier-backed C-layout storage and pass to native code as a pointer. The fields array is ordered, and field order is part of the ABI. Each field must have a non-empty name and exactly one of type or abi.

POD field types are restricted to numeric ABI scalars that have stable C layout:

i32, i64, u32, u64, usize, f32, f64, number, buffer_len

number aliases f64; buffer_len is a u32 byte-length scalar. Dynamic or pointerful descriptors such as jsvalue, string, bool, ptr, buffer+len, handle, promise, nested pod, and void are rejected in POD fields.

Param types

Return types

Note on "string" vs. "i64_str": both produce a string on the TypeScript side, but they differ in how Rust returns the pointer. Use "string" / "ptr" when your extern "C" fn is declared -> *const u8 (or *const StringHeader); use "i64_str" when it’s -> i64 and the value happens to be a StringHeader address (closes #222).

"void" is valid only as a return descriptor. "buffer+len" and { "kind": "pod", ... } are valid only as parameter descriptors: "buffer+len" expands one JavaScript argument into two native ABI slots, while pod lowers one object-shaped argument to a pointer to verifier-backed C-layout storage.

Native-only numeric descriptors (f32, u32, u64, usize, buffer_len) render as TypeScript number. Handles remain opaque GC-managed values, even though native functions still receive and return raw i64 resource pointers at the ABI boundary. POD parameters remain ordinary JavaScript objects at the boundary; guarded hot paths may pass native record storage directly, and dynamic values fall back to validated object-field materialization. Promises remain JavaScript promises; the optional promise<T> result metadata is currently recorded in compiler proof artifacts rather than changing the runtime ABI.

targets.<target>

Per-target build configuration. The <target> key is one of: macos, ios, linux, windows, android, web, harmonyos, tvos, watchos, visionos. Simulator variants use the same key as their device counterpart (ios covers both ios-simulator and ios).

When both prebuilt and crate/lib are absent for the user’s compile target, the wrapper is silently skipped on that target — useful for platform-specific bindings that only exist on macOS, etc.

Backend packaging (backends)

targets.<target>.backends describes backend-owned packaging without adding app-specific graphics APIs to Perry. The keys are:

Unsupported combinations fail during manifest parsing or perry native validate, before any SDK-specific tool is invoked.

Each backend block accepts:

Example:

"targets": {
  "macos": {
    "prebuilt": "./prebuilt/macos/libdemo.a",
    "backends": {
      "metal": {
        "frameworks": ["Metal", "QuartzCore"],
        "shaderSources": ["shaders/default.metal"],
        "shaderOutputs": ["prebuilt/default.metallib"],
        "resources": ["resources/metal"],
        "package": {
          "name": "demo-metal",
          "version": "1.0.0",
          "kind": "metallib"
        }
      },
      "vulkan": {
        "libs": ["vulkan"],
        "shaderOutputs": ["prebuilt/default.spv"]
      }
    }
  },
  "windows": {
    "prebuilt": "./prebuilt/windows/demo.lib",
    "backends": {
      "d3d12": {
        "libs": ["d3d12", "dxgi", "dxguid"],
        "shaderOutputs": ["prebuilt/default.dxil"]
      },
      "vulkan": {
        "libs": ["vulkan-1"],
        "shaderOutputs": ["prebuilt/default.spv"]
      }
    }
  }
}

For Apple app-bundle targets, Metal shader sources are compiled into default.metallib. Set PERRY_XCRUN=/path/to/fake-or-real-xcrun to override tool discovery in tests. Vulkan shader sources are compiled with glslc into NativeLibraries/<package>/vulkan/<source>.spv; set PERRY_GLSLC=/path/to/glslc to override discovery. D3D12 shader sources are compiled with dxc into NativeLibraries/<package>/d3d12/<source>.dxil; set PERRY_DXC=/path/to/dxc to override discovery. If your shader build needs custom profiles, entry points, or flags, ship prebuilt shaderOutputs from your package build instead.

Vendored frameworks (optionalFrameworks + frameworksEnv)

Some Apple SDKs can’t be redistributed through npm (licensing) or are too large to vendor — GoogleSignIn is the canonical example. For these, the wrapper declares the SDK’s framework name(s) in optionalFrameworks and the name of an environment variable in frameworksEnv. The app developer builds/downloads the framework locally, points the env var at the directory holding it, and Perry’s linker adds -F <dir> plus -framework <name> for each entry.

"targets": {
  "ios": {
    "crate": "crate-ios",
    "lib": "perry_google_auth",
    "optionalFrameworks": ["GoogleSignIn"],
    "frameworksEnv": "PERRY_GOOGLE_SIGN_IN_FRAMEWORK_DIR"
  }
}

PERRY_GOOGLE_SIGN_IN_FRAMEWORK_DIR=/path/to/Frameworks \
  perry compile app.ts --target ios

When the env var is unset (or points at a non-directory), the optional frameworks are skipped silently. This pairs with a Swift bridge guarded by #if canImport(GoogleSignIn): the no-SDK fallback compiles and the binary still links, returning a runtime “framework not linked” result instead of failing with undefined symbols. The same build.rs opt-in (-F $DIR to swiftc) must gate the bridge’s compile so both halves agree.

Project-relative framework_dir (survives perry publish). The env var works for local perry compile, but perry publish uploads the project to a remote build worker where the dev’s shell env doesn’t transfer and an absolute local path wouldn’t exist anyway. For the round-trip, declare the framework search dir relative to the project root in perry.toml:

[google_auth]
framework_dir = "vendor/google-sign-in/frameworks"   # relative to perry.toml

Perry resolves it to an absolute path and exports it as the package’s frameworksEnv before building the wrapper crate — on the local machine and on the worker — and perry publish forces the directory into the upload tarball (even though it holds the static archive binary, which the default binary-artifact exclusion would otherwise drop). Precedence is explicit env var > framework_dir, so existing local setups are unchanged. Issue #1303.

Contract — static frameworks only. -framework links the archive directly; Perry does not embed the .framework into <app>.app/Frameworks/ or add an @executable_path/Frameworks rpath. A dynamic framework would link but fail to load at runtime. Vendor a statically-linked .framework (or a .xcframework slice containing a static Mach-O). Embedding dynamic frameworks + resource bundles is tracked as future work (#1304).

Resolution

1. The user writes import { foo } from "@perry/iroh".
2. Perry resolves @perry/iroh against node_modules/. If a matching directory has a perry.nativeLibrary manifest in its package.json, this file’s spec applies and the wrapper is used.
3. If node_modules/<name>/ exists without a manifest, the import falls through to V8 (existing behavior — TypeScript / JavaScript package).
4. If no node_modules entry matches, Perry consults its built-in well-known bindings table (see #466 Phase 4) — the same spec applies to the bundled wrapper.
5. None of the above match → resolution error.

A wrapper installed in node_modules always beats the well-known table — that’s how users override a bundled binding with a fork or a beta version.

Reference example

Minimal — three FFI functions, two targets. Matches the perry-ext-dotenv shape:

{
  "name": "@perry/dotenv",
  "version": "0.5.0",
  "perry": {
    "nativeLibrary": {
      "abiVersion": "0.5",
      "functions": [
        { "name": "js_dotenv_config",      "params": [],          "returns": "number" },
        { "name": "js_dotenv_config_path", "params": ["string"],  "returns": "number" },
        { "name": "js_dotenv_parse",       "params": ["string"],  "returns": "string" }
      ],
      "targets": {
        "macos":   { "crate": "native/macos",   "lib": "perry_ext_dotenv" },
        "linux":   { "crate": "native/linux",   "lib": "perry_ext_dotenv" }
      }
    }
  }
}

A larger reference is Bloom Engine’s manifest (~230 functions, 6 targets, frameworks + metal_sources) in the bloom repo.

Compatibility & migration

The manifest schema is itself versioned by abiVersion. The major version of perry-ffi is the major version of this manifest spec — they move in lockstep:

• 0.5.x — current; abiVersion is recommended but optional.
• 0.6.0 — abiVersion becomes required; missing field is a hard resolution error.
• 1.0.0 — first stable release; backwards-compat guarantees begin.

Anything not documented on this page (custom keys, undocumented returns values) is unsupported and may break between releases. File a request under #466 and we’ll consider adding it to v1.

Multi-Threading

Perry gives you real OS threads with a one-line API. No worker setup, no message ports, no structured clone overhead. Just parallelMap, parallelFilter, and spawn.

async function overviewHeader(): Promise<void> {
    const data = [1, 2, 3, 4, 5, 6, 7, 8]
    const records = [
        { score: 50, id: 1 },
        { score: 90, id: 2 },
        { score: 85, id: 3 },
    ]
    const threshold = 80

    // Process a million items across all CPU cores
    const results = parallelMap(data, (item: number) => item * item)

    // Filter a large dataset in parallel
    const valid = parallelFilter(records, (r: { score: number; id: number }) => r.score > threshold)

    // Run expensive work in the background
    const answer = await spawn(() => {
        let acc = 0
        for (let i = 0; i < 100_000; i++) acc += i
        return acc
    })

    console.log(`overview-header results=${results.length} valid=${valid.length} answer=${answer}`)
}

This is something no JavaScript runtime can do. V8, Bun, and Deno are all locked to one thread per isolate. Perry compiles to native code — there are no isolates, no GIL, no structural limitations. Your code runs on real OS threads with the full power of every CPU core.

Why This Matters

JavaScript’s single-threaded model is its biggest performance bottleneck. Here’s how runtimes try to work around it:

The fundamental problem: V8 uses a garbage-collected heap that cannot be shared between threads. Every “worker” is an entirely separate JavaScript engine instance with its own heap, its own GC, and its own copy of your data.

Perry doesn’t have this limitation. It compiles TypeScript to native machine code. Values are transferred between threads using zero-cost copies for numbers and efficient serialization for objects — no separate engine instances, no multi-megabyte overhead per thread.

Three Primitives

parallelMap — Data-Parallel Processing

Split an array across all CPU cores. Each element is processed independently. Results are collected in order.

async function overviewParallelMap(): Promise<void> {
    const prices = [100, 200, 300, 400, 500, 600, 700, 800]
    const adjusted = parallelMap(prices, (price: number) => {
        // Heavy computation runs on a worker thread
        let result = price
        for (let i = 0; i < 1000000; i++) {
            result = Math.sqrt(result * result + i)
        }
        return result
    })

    console.log(`overview-parallel-map len=${adjusted.length}`)
}

Perry automatically:

1. Detects the number of CPU cores
2. Splits the array into chunks (one per core)
3. Spawns OS threads to process each chunk
4. Collects results in the original order
5. Returns a new array

For small arrays, Perry skips threading entirely and processes inline — no overhead for trivial cases.

parallelFilter — Data-Parallel Filtering

Filter a large array across all CPU cores. Like .filter() but parallel:

async function overviewParallelFilter(): Promise<void> {
    const cutoffDate = 1_700_000_000
    const users = [
        { lastLogin: 1_710_000_000, score: 150, name: "alice" },
        { lastLogin: 1_690_000_000, score: 50, name: "bob" },
        { lastLogin: 1_720_000_000, score: 120, name: "carol" },
    ]

    // Filter across all cores — order is preserved
    const active = parallelFilter(users, (user: { lastLogin: number; score: number; name: string }) => {
        return user.lastLogin > cutoffDate && user.score > 100
    })

    console.log(`overview-parallel-filter active=${active.length}`)
}

Same rules as parallelMap: closures cannot capture mutable variables (compile-time enforced), and values are deep-copied between threads.

spawn — Background Threads

Run any computation in the background and get a Promise back. The main thread continues immediately.

async function overviewSpawnBg(): Promise<void> {
    // Start heavy work in the background
    const handle = spawn(() => {
        let sum = 0
        for (let i = 0; i < 100_000; i++) {
            sum += Math.sin(i)
        }
        return sum
    })

    // Main thread keeps running — UI stays responsive
    console.log("Computing...")

    // Get the result when you need it
    const result = await handle
    console.log(`Done: len=${typeof result}`)
}

spawn returns a standard Promise. You can await it, pass it to Promise.all, or chain .then() — it works exactly like any other async operation.

Practical Examples

Parallel Image Processing

async function overviewImage(): Promise<void> {
    const pixels = [
        { r: 100, g: 120, b: 140 },
        { r: 50, g: 60, b: 70 },
        { r: 200, g: 210, b: 220 },
    ]

    // Each pixel processed on a separate core
    const processed = parallelMap(pixels, (pixel: { r: number; g: number; b: number }) => {
        const r = Math.min(255, pixel.r * 1.2)
        const g = Math.min(255, pixel.g * 0.8)
        const b = Math.min(255, pixel.b * 1.1)
        return { r, g, b }
    })

    console.log(`overview-image processed=${processed.length}`)
}

Parallel Cryptographic Hashing

async function overviewCrypto(): Promise<void> {
    // Hash thousands of items across all cores
    const passwords = ["pass1", "pass2", "pass3"]
    const hashed = parallelMap(passwords, (password: string) => {
        // Stand-in for a real hash: deterministic FNV-1a over the bytes.
        let h = 2166136261
        for (let i = 0; i < password.length; i++) {
            h ^= password.charCodeAt(i)
            h = (h * 16777619) >>> 0
        }
        return h
    })

    console.log(`overview-crypto hashed=${hashed.length}`)
}

Multiple Independent Computations

async function overviewMultiple(): Promise<void> {
    const dataA = [1, 2, 3]
    const dataB = [4, 5, 6]
    const dataC = [7, 8, 9]

    // Three independent tasks run simultaneously on three OS threads
    const task1 = spawn(() => {
        let acc = 0
        for (const v of dataA) acc += v * v
        return acc
    })
    const task2 = spawn(() => {
        let acc = 0
        for (const v of dataB) acc += v * v
        return acc
    })
    const task3 = spawn(() => {
        let acc = 0
        for (const v of dataC) acc += v * v
        return acc
    })

    // All three run concurrently
    const [result1, result2, result3] = await Promise.all([task1, task2, task3])
    console.log(`overview-multiple ${result1} ${result2} ${result3}`)
}

Keeping UI Responsive

const responsiveButton = Button("Start Analysis", async () => {
    status.set("Analyzing...")

    // Heavy computation runs on a background thread
    // UI stays responsive — user can still interact
    const value = await spawn(() => {
        let acc = 0
        for (let i = 0; i < 1_000_000; i++) acc += i
        return acc
    })

    status.set(`Done: ${value}`)
})

const responsiveText = Text(`Status: ${status.value}`)

Captured Variables

Closures can capture outer variables. Captured values are automatically deep-copied to each worker thread:

async function overviewCaptured(): Promise<void> {
    const prices = [100, 200, 300, 400]
    const taxRate = 0.08
    const discount = 0.15

    // taxRate and discount are captured and copied to each thread
    const finalPrices = parallelMap(prices, (price: number) => {
        const discounted = price * (1 - discount)
        return discounted * (1 + taxRate)
    })

    console.log(`overview-captured len=${finalPrices.length}`)
}

Numbers and booleans are zero-cost copies (just 64-bit values). Strings, arrays, and objects are deep-copied automatically.

Safety

Perry enforces thread safety at compile time. You don’t need to think about race conditions, mutexes, or data corruption.

No Shared Mutable State

Closures passed to parallelMap and spawn cannot capture mutable variables. The compiler rejects this:

// Reject example — Perry rejects this at compile time:

let counter = 0;

// COMPILE ERROR: Closures passed to parallelMap cannot
// capture mutable variable 'counter'
parallelMap(data, (item) => {
    counter++;  // Not allowed
    return item;
});

This eliminates data races by design. If you need to aggregate results, use the return values:

async function overviewReduceInstead(): Promise<void> {
    const data = [1, 2, 3, 4, 5, 6, 7, 8]

    // Instead of mutating a shared counter, return values and reduce
    const results = parallelMap(data, (item: number) => item * item)
    const total = results.reduce((sum: number, r: number) => sum + r, 0)

    console.log(`overview-reduce-instead total=${total}`)
}

Independent Thread Arenas

Each worker thread has its own memory arena. Objects created on one thread can never be accessed from another thread. Values cross thread boundaries only through deep-copy serialization, which Perry handles automatically and invisibly.

File-system descriptors are also thread-affine. Numeric fds from fs.openSync are just copied numbers in another thread, where the fd registry does not know them, so fd operations fail with EBADF. fs.promises.FileHandle objects cross thread boundaries as detached handles with fd === -1. Pass file paths to spawn/parallelMap and reopen files inside the worker when it needs file I/O.

How It Works

Perry’s threading model is built on three pillars:

1. Native Code, Not Interpreted

Perry compiles TypeScript to native machine code via LLVM. There’s no interpreter, no VM, no isolate. A function pointer is just a function pointer — it’s valid on any thread.

2. Thread-Local Memory

Each thread gets its own memory arena (bump allocator) and garbage collector. No synchronization overhead during computation. When a thread finishes, its arena is freed automatically.

3. Serialized Transfer

Values crossing thread boundaries are serialized to a thread-safe intermediate format and deserialized on the target thread. The cost depends on the value type:

For numeric workloads — the most common parallelizable tasks — the threading overhead is negligible.

Next Steps

• parallelMap Reference — detailed API and performance tips
• parallelFilter Reference — parallel array filtering
• spawn Reference — background threads and Promise integration

parallelMap

Signature: parallelMap<T, U>(data: T[], fn: (item: T) => U): U[] — imported from perry/thread.

Processes every element of an array in parallel across all available CPU cores. Returns a new array with the results in the same order as the input.

Basic Usage

function parallelMapBasic(): void {
    const numbers = [1, 2, 3, 4, 5, 6, 7, 8]
    const doubled = parallelMap(numbers, (x: number) => x * 2)
    // [2, 4, 6, 8, 10, 12, 14, 16]
    console.log(`parallel-map-basic len=${doubled.length}`)
}

How It Works

Input: [a, b, c, d, e, f, g, h]     (8 elements, 4 CPU cores)

  Core 1: [a, b] → map → [a', b']
  Core 2: [c, d] → map → [c', d']
  Core 3: [e, f] → map → [e', f']
  Core 4: [g, h] → map → [g', h']

Output: [a', b', c', d', e', f', g', h']   (same order as input)

Perry automatically detects the number of CPU cores and splits the array into equal chunks. Elements within each chunk are processed sequentially; chunks run concurrently across cores.

Capturing Variables

The mapping function can reference variables from the outer scope. Captured values are deep-copied to each worker thread automatically:

function parallelMapCapture(): void {
    const prices = [100, 200, 300]
    const exchangeRate = 1.12

    const converted = parallelMap(prices, (price: number) => {
        // exchangeRate is captured and copied to each thread
        return price * exchangeRate
    })

    console.log(`parallel-map-capture len=${converted.length}`)
}

What Can Be Captured

Numeric fds and fs.promises.FileHandle objects are thread-affine. A captured fd is not registered in worker threads, and a captured FileHandle is detached with fd === -1. For file-backed parallel work, capture path strings and open the file inside the mapper.

What Cannot Be Captured

Mutable variables — variables that are reassigned anywhere in the enclosing scope — are rejected at compile time:

// Reject example — Perry rejects this at compile time:

let total = 0;

// COMPILE ERROR: Cannot capture mutable variable 'total'
parallelMap(data, (item) => {
    total += item;   // Would be a data race
    return item;
});

Instead, return values and reduce:

function parallelMapReduce(): void {
    const data = [1, 2, 3, 4, 5, 6, 7, 8]
    const results = parallelMap(data, (item: number) => item * 2)
    const total = results.reduce((sum: number, x: number) => sum + x, 0)
    console.log(`parallel-map-reduce total=${total}`)
}

Performance

When to Use parallelMap

Use parallelMap when the computation per element is significantly heavier than the cost of copying the element across threads.

Good candidates (CPU-bound work per element):

function parallelMapGoodCandidates(): void {
    const data = [1.0, 2.0, 3.0, 4.0]
    const documents = ["alpha beta", "gamma delta", "epsilon"]
    const inputs = ["a", "bb", "ccc"]

    // Heavy math
    const out1 = parallelMap(data, (x: number) => {
        let acc = x
        for (let i = 0; i < 1_000; i++) acc = Math.sqrt(acc * acc + i)
        return acc
    })

    // String processing on large strings
    const out2 = parallelMap(documents, (doc: string) => {
        const words = doc.split(" ")
        return { count: words.length, first: words[0] }
    })

    // Cryptographic operations
    const out3 = parallelMap(inputs, (input: string) => {
        let h = 0
        for (let i = 0; i < input.length; i++) h = (h * 31 + input.charCodeAt(i)) >>> 0
        return h
    })

    console.log(`parallel-map-good-candidates ${out1.length} ${out2.length} ${out3.length}`)
}

Poor candidates (trivial work per element):

function parallelMapPoorCandidate(): void {
    const numbers = [1, 2, 3, 4, 5]

    // Too simple — threading overhead outweighs the gain
    const a = parallelMap(numbers, (x: number) => x + 1)

    // For trivial operations, use regular map
    const result = numbers.map((x: number) => x + 1)

    console.log(`parallel-map-poor-candidate ${a.length} ${result.length}`)
}

Small Array Optimization

For arrays with fewer elements than CPU cores, Perry skips threading entirely and processes elements inline on the main thread. There’s zero overhead for small inputs.

Numeric Fast Path

When elements are pure numbers (no strings, objects, or arrays), Perry transfers them between threads at virtually zero cost — just 64-bit value copies with no serialization.

Examples

Matrix Row Processing

function parallelMapMatrix(): void {
    // Process each row of a matrix independently
    const rows = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
    const rowSums = parallelMap(rows, (row: number[]) => {
        let sum = 0
        for (const val of row) sum += val
        return sum
    })
    // [6, 15, 24]
    console.log(`parallel-map-matrix sums=${rowSums[0]},${rowSums[1]},${rowSums[2]}`)
}

Batch Validation

function parallelMapValidation(): void {
    const users = [
        { name: "Alice", email: "alice@example.com" },
        { name: "Bob", email: "invalid" },
        { name: "Charlie", email: "charlie@example.com" },
    ]

    const validationResults = parallelMap(users, (user: { name: string; email: string }) => {
        const emailValid = user.email.includes("@") && user.email.includes(".")
        const nameValid = user.name.length > 0 && user.name.length < 100
        return { name: user.name, valid: emailValid && nameValid }
    })

    console.log(`parallel-map-validation len=${validationResults.length}`)
}

Financial Calculations

function parallelMapMonteCarlo(): void {
    const portfolios = [
        { id: 1, base: 100 },
        { id: 2, base: 200 },
        { id: 3, base: 150 },
    ] // thousands of portfolios

    // Monte Carlo simulation across all cores
    const riskScores = parallelMap(portfolios, (portfolio: { id: number; base: number }) => {
        let totalRisk = 0
        for (let sim = 0; sim < 1000; sim++) {
            // simulateReturns stand-in: deterministic pseudo-random walk.
            let s = portfolio.base + sim
            s = ((s * 1103515245 + 12345) & 0x7fffffff) / 0x7fffffff
            totalRisk += s
        }
        return totalRisk / 1000
    })

    console.log(`parallel-map-monte-carlo len=${riskScores.length}`)
}

parallelFilter

Signature: parallelFilter<T>(data: T[], predicate: (item: T) => boolean): T[] — imported from perry/thread.

Filters an array in parallel across all available CPU cores. Returns a new array containing only the elements where the predicate returned a truthy value. Order is preserved.

Basic Usage

function parallelFilterBasic(): void {
    const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    const evens = parallelFilter(numbers, (x: number) => x % 2 === 0)
    // [2, 4, 6, 8, 10]
    console.log(`parallel-filter-basic len=${evens.length}`)
}

How It Works

Input: [a, b, c, d, e, f, g, h]     (8 elements, 4 CPU cores)

  Core 1: [a, b] → test → [a]       (b filtered out)
  Core 2: [c, d] → test → [c, d]    (both kept)
  Core 3: [e, f] → test → []        (both filtered out)
  Core 4: [g, h] → test → [h]       (g filtered out)

Output: [a, c, d, h]                 (concatenated in original order)

Each core independently tests its chunk of elements. Results are merged in the original element order after all threads complete.

Why Not Just Use .filter()?

Regular .filter() runs on a single thread. For large arrays with expensive predicates, parallelFilter distributes the work:

function parallelFilterVsFilter(): void {
    const data = [1, 2, 3, 4, 5, 6, 7, 8]

    // Single-threaded — one core does all the work
    const a = data.filter((item: number) => item > 3)

    // Parallel — all cores share the work
    const b = parallelFilter(data, (item: number) => item > 3)

    console.log(`parallel-filter-vs-filter ${a.length} ${b.length}`)
}

The tradeoff: parallelFilter has overhead from copying values between threads. Use it when the predicate is expensive enough to justify that cost.

Capturing Variables

Like parallelMap, the predicate can capture outer variables. Captures are deep-copied to each thread:

function parallelFilterCapture(): void {
    const candidates = [
        { name: "Alice", score: 90, age: 28 },
        { name: "Bob", score: 80, age: 35 },
        { name: "Carol", score: 95, age: 25 },
    ]
    const minScore = 85
    const maxAge = 30

    // minScore and maxAge are captured and copied to each thread
    const qualified = parallelFilter(candidates, (c: { name: string; score: number; age: number }) => {
        return c.score >= minScore && c.age <= maxAge
    })

    console.log(`parallel-filter-capture len=${qualified.length}`)
}

Mutable variables cannot be captured — the compiler rejects this at compile time.

Examples

Filtering Large Datasets

function parallelFilterLarge(): void {
    // Stand-in for "millions of records" — same shape, smaller list.
    const transactions = [
        { amount: 15000, country: "US", user: { homeCountry: "DE" }, timestamp: { hour: 4 } },
        { amount: 200, country: "DE", user: { homeCountry: "DE" }, timestamp: { hour: 12 } },
        { amount: 50000, country: "FR", user: { homeCountry: "DE" }, timestamp: { hour: 3 } },
    ]

    const suspicious = parallelFilter(transactions, (tx: {
        amount: number
        country: string
        user: { homeCountry: string }
        timestamp: { hour: number }
    }) => {
        return tx.amount > 10000
            && tx.country !== tx.user.homeCountry
            && tx.timestamp.hour < 6
    })

    console.log(`parallel-filter-large len=${suspicious.length}`)
}

Combined with parallelMap

function parallelFilterCombined(): void {
    const users = [
        { name: "Alice", isActive: true, age: 28, score: 90 },
        { name: "Bob", isActive: false, age: 35, score: 80 },
        { name: "Carol", isActive: true, age: 17, score: 95 },
        { name: "Dave", isActive: true, age: 40, score: 60 },
    ]

    // Step 1: Filter to relevant items (parallel)
    const active = parallelFilter(users, (u: { isActive: boolean; age: number }) => u.isActive && u.age >= 18)

    // Step 2: Transform the filtered results (parallel)
    const profiles = parallelMap(active, (u: { name: string; score: number }) => ({
        name: u.name,
        score: u.score * 2,
    }))

    console.log(`parallel-filter-combined active=${active.length} profiles=${profiles.length}`)
}

Predicate with Heavy Computation

function parallelFilterHeavy(): void {
    const certificates = [
        { id: 1, fingerprint: "aa", revoked: false },
        { id: 2, fingerprint: "bb", revoked: true },
        { id: 3, fingerprint: "cc", revoked: false },
    ]

    // Each predicate call does significant work — perfect for parallelization.
    const valid = parallelFilter(certificates, (cert: { id: number; fingerprint: string; revoked: boolean }) => {
        // Stand-in for a real chain verification: hash the fingerprint a bit
        // then sanity-check the revocation flag.
        let h = 0
        for (let i = 0; i < cert.fingerprint.length; i++) {
            h = (h * 31 + cert.fingerprint.charCodeAt(i)) >>> 0
        }
        return h !== 0 && !cert.revoked
    })

    console.log(`parallel-filter-heavy len=${valid.length}`)
}

Performance

Use parallelFilter when:

• The array has many elements (hundreds or more)
• The predicate function does meaningful work per element
• You need to keep the UI responsive during filtering

For trivial predicates on small arrays, regular .filter() is faster (no threading overhead).

spawn

Signature: spawn<T>(fn: () => T): Promise<T> — imported from perry/thread.

Runs a closure on a new OS thread and returns a Promise that resolves when the thread completes. The main thread continues immediately — UI and other work are not blocked.

Basic Usage

async function spawnBasic(): Promise<void> {
    const result = await spawn(() => {
        // This runs on a separate OS thread.
        let sum = 0
        for (let i = 0; i < 100_000_000; i++) {
            sum += i
        }
        return sum
    })

    console.log(result) // 4999999950000000
}

Non-Blocking

spawn returns immediately. The main thread doesn’t wait:

async function spawnNonBlocking(): Promise<void> {
    console.log("1. Starting background work")

    const handle = spawn(() => {
        // Runs on a background thread — heavier work elided here.
        let n = 0
        for (let i = 0; i < 10_000_000; i++) n++
        return n
    })

    console.log("2. Main thread continues immediately")

    const result = await handle
    console.log(`3. Got result: ${result}`)
}

Output:

1. Starting background work
2. Main thread continues immediately
3. Got result: <computed value>

Multiple Concurrent Tasks

Spawn multiple tasks and they run truly concurrently — one OS thread per spawn call:

async function spawnMultiple(): Promise<void> {
    const t1 = spawn(() => analyseChunk(0, 1_000_000))
    const t2 = spawn(() => analyseChunk(1_000_000, 2_000_000))
    const t3 = spawn(() => analyseChunk(2_000_000, 3_000_000))

    // All three run simultaneously on separate OS threads.
    const results = await Promise.all([t1, t2, t3])

    console.log(`Region A: ${results[0]}`)
    console.log(`Region B: ${results[1]}`)
    console.log(`Region C: ${results[2]}`)
}

function analyseChunk(start: number, end: number): number {
    let acc = 0
    for (let i = start; i < end; i++) acc += i & 0xff
    return acc
}

Unlike Node.js worker_threads, each spawn is a lightweight OS thread (~8MB stack), not a full V8 isolate (~2MB heap + startup cost).

Capturing Variables

Like parallelMap, spawn closures can capture outer variables. They are deep-copied to the background thread:

async function spawnCapture(): Promise<void> {
    const config = { iterations: 1000, seed: 42 }
    const dataset = [1, 2, 3, 4, 5, 6, 7, 8]

    const result = await spawn(() => {
        // config and dataset are deep-copied to this thread.
        let acc = config.seed
        for (let i = 0; i < config.iterations; i++) {
            acc = (acc * 1103515245 + 12345) & 0x7fffffff
        }
        for (const v of dataset) acc ^= v
        return acc
    })

    console.log(`spawn-capture: ${result}`)
}

Mutable variables cannot be captured — this is enforced at compile time.

File System Handles

Do not capture numeric fds or fs.promises.FileHandle objects for file I/O in spawn. Perry’s fd registry is per thread: a numeric fd captured from the main thread is not open in the worker, and a captured FileHandle arrives detached with fd === -1. Capture a path string instead, then call fs.openSync or fs.promises.open inside the spawned function.

Returning Complex Values

spawn can return any value type. Complex values (objects, arrays, strings) are serialized back to the main thread automatically:

async function spawnComplexReturn(): Promise<void> {
    const stats = await spawn(() => {
        const values = [3.0, 1.0, 4.0, 1.0, 5.0, 9.0, 2.0, 6.0]
        let sum = 0
        let max = values[0]
        let min = values[0]
        for (const v of values) {
            sum += v
            if (v > max) max = v
            if (v < min) min = v
        }
        return {
            mean: sum / values.length,
            min,
            max,
            count: values.length,
        }
    })

    console.log(`mean=${stats.mean} min=${stats.min} max=${stats.max} count=${stats.count}`)
}

UI Integration

spawn is ideal for keeping native UIs responsive during heavy computation:

const analyzeButton = Button("Analyze", async () => {
    status.set("Processing...")

    // Background thread — UI stays responsive
    const data = await spawn(() => {
        let count = 0
        for (let i = 0; i < 1_000_000; i++) {
            if ((i & 0xff) === 0) count++
        }
        return { count }
    })

    result.set(`Found ${data.count} patterns`)
    status.set("Done")
})

Without spawn, the analysis would freeze the UI. With spawn, the user can still scroll, tap other buttons, or navigate while the computation runs.

Compared to Node.js worker_threads

// ── Node.js: ~15 lines, separate file needed ──────────
// worker.js
const { parentPort, workerData } = require("worker_threads");
const result = heavyComputation(workerData);
parentPort.postMessage(result);

// main.js
const { Worker } = require("worker_threads");
const worker = new Worker("./worker.js", {
    workerData: inputData,
});
worker.on("message", (result) => {
    console.log(result);
});
worker.on("error", (err) => { /* handle */ });


// ── Perry: 1 line ─────────────────────────────────────
// const result = await spawn(() => heavyComputation(inputData));

No separate files. No message ports. No event handlers. No structured clone. One line.

Examples

Background File Processing

async function spawnBgFile(): Promise<void> {
    // Read and process a "large" file without blocking. We inline a tiny CSV
    // so the snippet runs hermetically — the docs' real version would call
    // readFileSync from "fs".
    const content = "id,value\n1,10\n2,20\n3,30\n"
    const analysis = await spawn(() => {
        const lines = content.split("\n").filter((l: string) => l.length > 0).slice(1)
        let total = 0
        for (const line of lines) {
            const parts = line.split(",")
            total += parseInt(parts[1], 10)
        }
        return { rows: lines.length, total }
    })

    console.log(`spawn-bg-file rows=${analysis.rows} total=${analysis.total}`)
}

Parallel API Calls with Processing

async function spawnApiThenProcess(): Promise<void> {
    // The docs example fetches a remote API; for a hermetic test we
    // just hand-roll the same pipeline shape with synthetic data.
    const rawData = { items: [1, 2, 3, 4, 5] }

    // CPU-intensive processing happens off the main thread
    const processed = await spawn(() => {
        let total = 0
        for (const v of rawData.items) total += v * v
        return { total, count: rawData.items.length }
    })

    console.log(`spawn-api-then-process total=${processed.total} count=${processed.count}`)
}

Deferred Computation

async function spawnDeferred(): Promise<void> {
    const params = { size: 8 }

    // Start computation early, use result later
    const precomputed = spawn(() => {
        const table: number[] = []
        for (let i = 0; i < params.size; i++) table.push(i * i)
        return table
    })

    // ... do other setup work ...

    // Result is ready (or we wait for it)
    const table = await precomputed
    console.log(`spawn-deferred len=${table.length} last=${table[table.length - 1]}`)
}

UI Overview

Perry’s perry/ui module lets you build native desktop and mobile apps with declarative TypeScript. Your UI code compiles directly to platform-native widgets — AppKit on macOS, UIKit on iOS, GTK4 on Linux, Win32 on Windows, and DOM elements on the web.

Quick Start

// demonstrates: the smallest complete Perry UI app
// docs: docs/src/ui/overview.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, Text, VStack } from "perry/ui"

App({
    title: "My App",
    width: 400,
    height: 300,
    body: VStack(16, [
        Text("Hello from Perry!"),
    ]),
})

perry app.ts -o app && ./app

Mental Model

Perry’s UI follows the same model as SwiftUI and Flutter: you compose native widgets using stack-based layout containers (VStack, HStack, ZStack), control alignment and distribution, and style widgets via free functions that take the widget handle as their first argument (textSetColor(label, r, g, b, a), widgetSetEdgeInsets(stack, ...), etc.). If you’re coming from web development, the key shift is:

• Layout is controlled by stack alignment, distribution, and spacers — not CSS properties. See Layout.
• Styling is applied directly to widgets — not through stylesheets. See Styling.
• Absolute positioning uses overlays (widgetAddOverlay + widgetSetOverlayFrame) — not position: absolute/relative.
• Design tokens come from the perry-styling package. See Theming.

App Lifecycle

Every Perry UI app starts with App():

function runAppShell(): void {
    App({
        title: "Window Title",
        width: 800,
        height: 600,
        body: VStack(16, [
            Text("Content here"),
        ]),
    })
}

App({}) accepts a config object with the following properties:

See Multi-Window for full documentation on window properties.

Lifecycle Hooks

onActivate(() => {
    console.log("App became active")
})

onTerminate(() => {
    console.log("App is closing")
})

Widget Tree

Perry UIs are built as a tree of widgets:

function runWidgetTree(): void {
    App({
        title: "Layout Demo",
        width: 400,
        height: 300,
        body: VStack(16, [
            Text("Header"),
            HStack(8, [
                Button("Left", () => console.log("left")),
                Button("Right", () => console.log("right")),
            ]),
            Text("Footer"),
        ]),
    })
}

Widgets are created by calling their constructor functions. Layout containers (VStack, HStack, ZStack) accept a spacing value (in points) followed by an array of child widgets.

Handle-Based Architecture

Under the hood, each widget is a handle — a small integer that references a native platform object. When you call Text("hello"), Perry creates a native NSTextField (macOS), UILabel (iOS), GtkLabel (Linux), or <span> (web) and returns a handle you can use to modify it.

const label = Text("Hello")
textSetFontSize(label, 18)              // Modifies the native widget
textSetColor(label, 1.0, 0.0, 0.0, 1.0) // RGBA floats in [0,1]

Imports

All UI functions are imported from perry/ui:

import {
    // App lifecycle
    App, onActivate, onTerminate,

    // Widgets
    Text, Button, TextField, SecureField, TextArea,
    Toggle, Slider, ProgressView, Picker, ImageFile, ImageSymbol,

    // Layout
    VStack, HStack, ZStack, ScrollView, Spacer, Divider,
    NavStack, TabBar, LazyVStack, Section,
    VStackWithInsets, HStackWithInsets, SplitView, splitViewAddChild,

    // Layout control
    stackSetAlignment, stackSetDistribution, stackSetDetachesHidden,
    widgetMatchParentWidth, widgetMatchParentHeight, widgetSetHugging,
    widgetAddOverlay, widgetSetOverlayFrame,

    // State
    State, ForEach,

    // Dialogs
    openFileDialog, openFolderDialog, saveFileDialog,
    alert, alertWithButtons,
    sheetCreate, sheetPresent, sheetDismiss,

    // Menus
    menuCreate, menuAddItem, menuAddSeparator, menuAddSubmenu,
    menuBarCreate, menuBarAddMenu, menuBarAttach,
    widgetSetContextMenu,

    // Window
    Window,
} from "perry/ui"

Canvas, CameraView, and the virtualized Table widget are wired through the LLVM codegen (closed via #190, #191, and #192). See each widget’s page for the platform-support matrix.

Platform Differences

The same code runs on all platforms, but the look and feel matches each platform’s native style:

Platform-specific behavior is noted on each widget’s documentation page.

Next Steps

• Widgets — All available widgets
• Layout — Arranging widgets
• State Management — Reactive state and bindings
• Styling — Colors, fonts, sizing
• Events — Click, hover, keyboard

Widgets

Perry provides native widgets that map to each platform’s native controls. Every example on this page is a real runnable program verified by CI (scripts/run_doc_tests.sh) — the snippet you read is the same source that’s compiled and launched.

The widget API is free functions, not methods. A widget is a 64-bit opaque handle; you pass it into helpers like textSetFontSize(widget, 18) rather than calling widget.setFontSize(18). That’s the only shape perry/ui supports — no fluent chain, no prototype methods.

Text

Displays read-only text.

// demonstrates: Text widget styling with the real free-function API
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, Text, textSetFontSize, textSetFontWeight, textSetColor, textSetFontFamily } from "perry/ui"

const label = Text("Hello, World!")
textSetFontSize(label, 18)
textSetColor(label, 0.2, 0.2, 0.2, 1.0) // RGBA in [0, 1]
textSetFontFamily(label, "Menlo")

const bold = Text("Bold")
textSetFontWeight(bold, 20, 1.0)

App({
    title: "Text",
    width: 400,
    height: 200,
    body: VStack(8, [label, bold]),
})

Color is RGBA with each channel in [0.0, 1.0] — divide a hex byte by 255 (0x33 / 255 ≈ 0.2).

Helpers: textSetString, textSetFontSize, textSetFontWeight, textSetFontFamily, textSetColor, textSetWraps, textSetSelectable.

Text widgets inside template literals with state.value update automatically — perry detects the state read and rewires the widget to re-render on change. See State Management.

Button

A clickable button.

// demonstrates: Button styling with buttonSet*/widgetSet* helpers
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import {
    App,
    VStack,
    Button,
    buttonSetBordered,
    widgetSetEnabled,
    setCornerRadius,
} from "perry/ui"

// Note: buttonSetContentTintColor is macOS/iOS-only (maps to NSButton /
// UIButton tint). GTK4/Win32 don't have an equivalent — set
// widgetSetBackgroundColor(btn, r, g, b, a) there instead.
const primary = Button("Click Me", () => console.log("Clicked!"))
buttonSetBordered(primary, 1)
setCornerRadius(primary, 8)

const disabled = Button("Can't click me", () => {})
widgetSetEnabled(disabled, 0)

App({
    title: "Button",
    width: 400,
    height: 200,
    body: VStack(12, [primary, disabled]),
})

Helpers: buttonSetTitle, buttonSetBordered, buttonSetImage (SF Symbol name on macOS/iOS), buttonSetImagePosition, buttonSetContentTintColor, buttonSetTextColor, widgetSetEnabled.

TextField

An editable single-line text input.

// demonstrates: TextField + two-way binding via stateBindTextfield
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, Text, TextField, State, stateBindTextfield } from "perry/ui"

const text = State("")
const field = TextField("Placeholder...", (value: string) => text.set(value))
stateBindTextfield(text, field) // programmatic text.set() also updates the field

App({
    title: "TextField",
    width: 400,
    height: 200,
    body: VStack(12, [
        field,
        Text(`You typed: ${text.value}`),
    ]),
})

TextField(placeholder, onChange) fires onChange as the user types. Pair with stateBindTextfield(state, field) for two-way binding so programmatic state.set(…) also updates the visible text.

Helpers: textfieldSetString, textfieldSetFontSize, textfieldSetTextColor, textfieldSetBackgroundColor, textfieldSetBorderless, textfieldSetOnSubmit, textfieldSetOnFocus, textfieldSetNextKeyView.

SecureField

A password input — identical signature to TextField, but text is masked.

// demonstrates: SecureField for password input
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, SecureField, State } from "perry/ui"

const password = State("")

App({
    title: "SecureField",
    width: 400,
    height: 200,
    body: VStack(12, [
        SecureField("Enter password...", (value: string) => password.set(value)),
    ]),
})

Toggle

A boolean on/off switch.

// demonstrates: Toggle widget bound to State
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, Text, Toggle, State } from "perry/ui"

const enabled = State(false)

App({
    title: "Toggle",
    width: 400,
    height: 200,
    body: VStack(12, [
        Toggle("Enable notifications", (on: boolean) => enabled.set(on)),
        Text(`Enabled: ${enabled.value}`),
    ]),
})

Slider

A numeric slider.

// demonstrates: Slider with a numeric range
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, Text, Slider, State } from "perry/ui"

const value = State(50)

App({
    title: "Slider",
    width: 400,
    height: 200,
    body: VStack(12, [
        Slider(0, 100, (v: number) => value.set(v)),
        Text(`Value: ${value.value}`),
    ]),
})

Slider(min, max, onChange) — onChange fires on every drag. Use stateBindSlider(state, slider) for two-way binding.

Picker

A dropdown selection control. Items are added with pickerAddItem.

// demonstrates: Picker with items added via pickerAddItem
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, Text, Picker, State, pickerAddItem } from "perry/ui"

const selected = State(0)
const picker = Picker((index: number) => selected.set(index))
pickerAddItem(picker, "Option A")
pickerAddItem(picker, "Option B")
pickerAddItem(picker, "Option C")

App({
    title: "Picker",
    width: 400,
    height: 200,
    body: VStack(12, [
        picker,
        Text(`Selected index: ${selected.value}`),
    ]),
})

ImageFile / ImageSymbol

Two distinct constructors:

• ImageFile(path) — image from a file path
• ImageSymbol(name) — SF Symbol glyph name (macOS/iOS only)

// demonstrates: ImageSymbol for SF Symbol glyphs (macOS/iOS)
// docs: docs/src/ui/widgets.md
// platforms: macos
// targets: ios-simulator, visionos-simulator, tvos-simulator

import { App, HStack, ImageSymbol, widgetSetWidth, widgetSetHeight } from "perry/ui"

const star = ImageSymbol("star.fill")
widgetSetWidth(star, 32)
widgetSetHeight(star, 32)

const heart = ImageSymbol("heart.fill")
const bell = ImageSymbol("bell.fill")

App({
    title: "ImageSymbol",
    width: 400,
    height: 200,
    body: HStack(12, [star, heart, bell]),
})

Use widgetSetWidth(img, N) / widgetSetHeight(img, N) to size the image.

ProgressView

An indeterminate or determinate progress indicator.

// demonstrates: ProgressView as an indeterminate spinner
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, Text, ProgressView } from "perry/ui"

App({
    title: "ProgressView",
    width: 400,
    height: 200,
    body: VStack(12, [
        Text("Loading..."),
        ProgressView(),
    ]),
})

TextArea

A multi-line text input. Same (placeholder, onChange) signature as TextField but renders as a multi-line box.

// demonstrates: TextArea for multi-line input
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, Text, TextArea, State } from "perry/ui"

const content = State("")

App({
    title: "TextArea",
    width: 500,
    height: 400,
    body: VStack(12, [
        TextArea("Enter multi-line text...", (value: string) => content.set(value)),
        Text(`Length: ${content.value.length}`),
    ]),
})

Helpers: textareaSetString.

Sections

Group controls into labelled sections. Perry has no Form() widget — use a VStack of Section(title)s and attach children via widgetAddChild.

// demonstrates: Section grouping with widgetAddChild (no Form widget in Perry)
// docs: docs/src/ui/widgets.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import {
    App,
    VStack,
    Section,
    TextField,
    Toggle,
    State,
    widgetAddChild,
} from "perry/ui"

const name = State("")
const notifications = State(true)

const personal = Section("Personal Info")
widgetAddChild(personal, TextField("Name", (value: string) => name.set(value)))

const settings = Section("Settings")
widgetAddChild(
    settings,
    Toggle("Notifications", (on: boolean) => notifications.set(on)),
)

App({
    title: "Sections",
    width: 500,
    height: 400,
    body: VStack(16, [personal, settings]),
})

Mobile widgets (issue #553)

BottomNavigation

5-tab bottom bar with icon + label + badge per tab. onSelect(index) fires when the user taps; bottomNavSetSelected is the programmatic counterpart and does NOT fire onSelect.

import {
  BottomNavigation,
  bottomNavAddItem,
  bottomNavSetBadge,
} from "perry/ui";

const bar = BottomNavigation((index) => {
  console.log("tab:", index);
});
bottomNavAddItem(bar, "house", "Home");
bottomNavAddItem(bar, "magnifyingglass", "Search");
bottomNavAddItem(bar, "bell", "Activity");
bottomNavSetBadge(bar, 2, "5");

Real on macOS (NSStackView + NSButton strip with SF Symbol icons), iOS (UITabBar), Android (custom LinearLayout strip with badge overlay), and GTK4 (GtkBox + Adwaita CSS). Stub on Windows, tvOS, visionOS, watchOS.

ImageGallery

Swipeable, paging carousel of images. Local file paths load synchronously; HTTP/HTTPS URLs are fetched on a background queue and applied on the main thread.

import { ImageGallery, imageGalleryAddImage } from "perry/ui";

const gallery = ImageGallery((idx) => console.log("page:", idx));
imageGalleryAddImage(gallery, "/photos/01.jpg", "Hero shot");
imageGalleryAddImage(gallery, "https://cdn.example/photo2.jpg", "Wide angle");

Real on macOS (NSScrollView paging), iOS (UIScrollView with scrollViewDidEndDecelerating), Android (HorizontalScrollView), GTK4 (GtkScrolledWindow + GtkPicture). Stub on Windows, tvOS, visionOS, watchOS.

Pull-to-refresh

Available on ScrollView and LazyVStack. The onPull callback fires once when the user pulls past the threshold; call scrollviewEndRefreshing (or lazyvstackEndRefreshing) when your async fetch settles to dismiss the spinner.

import {
  ScrollView,
  scrollviewSetRefreshControl,
  scrollviewEndRefreshing,
} from "perry/ui";

const scroll = ScrollView();
scrollviewSetRefreshControl(scroll, async () => {
  await refreshFeed();
  scrollviewEndRefreshing(scroll);
});

Real on iOS (UIRefreshControl). The macOS / Android / GTK4 / Windows desktops have no native pull-to-refresh idiom — they’re documented no-ops.

Infinite scroll (onScrollEnd)

Fires once when the user scrolls past thresholdPx (or thresholdItems for LazyVStack) from the bottom; re-arms after the user scrolls back up past the threshold so a single fetch is queued at a time.

import { ScrollView, scrollviewSetScrollEndCallback } from "perry/ui";

const scroll = ScrollView();
scrollviewSetScrollEndCallback(
  scroll,
  () => loadMore(),
  200, // threshold in pixels from the bottom
);

Real on every platform that has a scroll view: macOS (NSViewBoundsDidChangeNotification), iOS (UIScrollViewDelegate.scrollViewDidScroll), Android (View.OnScrollChangeListener), GTK4 (GtkAdjustment::value-changed), Windows (WM_VSCROLL / WM_MOUSEWHEEL).

Platform-specific widgets

These exist only on specific platforms and aren’t verified by the cross-platform doc-tests:

• Table(rows, cols, renderer) — macOS only. Now supports tableSetSortColumn, tableSetFilterText, and multi-select since v0.5.636 (#473).
• QRCode(data, size) — macOS only. Renders a QR code.
• Canvas(width, height, draw) — all desktop platforms. A drawing surface; see Canvas.
• CameraView() — iOS only (other platforms planned). See Camera.

Combobox (issue #475)

Editable text field with a filterable dropdown of suggestions. macOS uses NSComboBox with as-you-type completion; other platforms stub the FFI today (the field falls back to a plain editable field).

import { Combobox, comboboxAddItem, comboboxGetValue } from "perry/ui";

const combo = Combobox("", (v) => console.log("picked:", v));
comboboxAddItem(combo, "apple");
comboboxAddItem(combo, "apricot");
comboboxAddItem(combo, "avocado");

TreeView / Outline (issue #480)

Hierarchical disclosure list. Build the topology bottom-up via TreeNode

• treeNodeAddChild, then mount it via TreeView. macOS uses NSOutlineView; other platforms stub.

import { TreeNode, treeNodeAddChild, TreeView } from "perry/ui";

const dox = TreeNode("docs", "Documents");
treeNodeAddChild(dox, TreeNode("doc-1", "Resume.pdf"));
treeNodeAddChild(dox, TreeNode("doc-2", "Cover Letter.pdf"));
const root = TreeNode("root", "Files");
treeNodeAddChild(root, dox);
const tree = TreeView(root, (id) => console.log("selected:", id));

Calendar (issue #481)

Month-grid date picker. macOS uses NSDatePicker in graphical style; other platforms stub. onChange receives the selected date as an ISO yyyy-MM-dd string.

import { Calendar, calendarGetSelectedDate } from "perry/ui";

const cal = Calendar(2026, 5, (iso) => console.log("date:", iso));

DatePicker (issue #4772)

Compact field-style date picker — the space-saving complement to the month-grid Calendar. Each platform uses its native compact date control: macOS NSDatePicker (text-field-and-stepper), iOS / visionOS UIDatePicker (.compact), Windows SysDateTimePick32, Android android.widget.DatePicker. GTK4 has no native compact date field, so it reuses GtkCalendar; tvOS / watchOS stub. onChange receives the selected date as an ISO yyyy-MM-dd string.

import { DatePicker, datePickerGetSelectedDate } from "perry/ui";

const picker = DatePicker(2026, 5, (iso) => console.log("date:", iso));

Chart (issue #474)

Line / bar / pie via CoreGraphics on macOS. kind is 0=line, 1=bar, 2=pie. Apple Charts framework / SwiftUI Charts integration on iOS 16+ is a follow-up.

import { Chart, chartAddDataPoint, chartSetTitle } from "perry/ui";

const chart = Chart(0, 600, 400);
chartSetTitle(chart, "Visits");
chartAddDataPoint(chart, "Mon", 12);
chartAddDataPoint(chart, "Tue", 18);
chartAddDataPoint(chart, "Wed", 9);

Command palette (issue #477)

⌘K-style fuzzy command launcher. macOS shows a floating NSPanel; other platforms stub. Bind commandPaletteShow() to ⌘K via addKeyboardShortcut to wire the default hotkey.

import {
  commandPaletteRegister,
  commandPaletteShow,
} from "perry/ui";

commandPaletteRegister("save", "Save", "⌘S", () => save());
commandPaletteRegister("export", "Export PDF", "", () => exportPdf());
// then:
commandPaletteShow();

MapView (issue #517)

Wraps MKMapView on macOS / iOS / visionOS / tvOS, libshumate on GTK4, Google Maps SDK on Android (requires API key in AndroidManifest.xml), and the SwiftUI Map view on watchOS. Windows remains a stub (WinUI MapControl needs XAML Islands integration).

import {
  MapView,
  mapViewSetRegion,
  mapViewAddPin,
  mapViewSetMapType,
} from "perry/ui";

const map = MapView(800, 600);
mapViewSetRegion(map, 37.7749, -122.4194, 0.05, 0.05);
mapViewAddPin(map, 37.7749, -122.4194, "San Francisco");
mapViewSetMapType(map, 1); // 0=standard, 1=satellite, 2=hybrid

PdfView (issue #516)

PDFView from PDFKit on macOS / iOS / visionOS. pdfViewLoadFile returns 1 on success, 0 on failure.

import {
  PdfView,
  pdfViewLoadFile,
  pdfViewGetPageCount,
} from "perry/ui";

const pdf = PdfView(800, 600);
if (pdfViewLoadFile(pdf, "/tmp/report.pdf")) {
  console.log("pages:", pdfViewGetPageCount(pdf));
}

RichTextEditor (issue #478)

NSTextView with NSAttributedString storage on macOS. Plain-text and HTML round-trip cover persistence; richTextToggleBold / ToggleItalic / ToggleUnderline cover inline formatting via NSResponder actions.

import {
  RichTextEditor,
  richTextSetHtml,
  richTextGetHtml,
  richTextToggleBold,
} from "perry/ui";

const editor = RichTextEditor(600, 400, (text) => console.log(text));
richTextSetHtml(editor, "<p>Hello <b>world</b></p>");
richTextToggleBold(editor);

Rich tooltip (issue #479)

widgetSetRichTooltip(widget, content, hoverDelayMs) — like widgetSetTooltip but the tooltip content is itself a Perry widget. macOS uses NSPanel + NSTrackingArea; other platforms stub. For plain-text tooltips with VoiceOver / a11y support, prefer the simpler widgetSetTooltip.

WebView (issue #658)

WebView({ url, allowedDomains?, onShouldNavigate?, ... }) embeds a real browser engine — WKWebView on Apple, WebView2 on Windows, WebKitGTK 6.0 on Linux, android.webkit.WebView on Android, sandboxed <iframe> on web. See WebView for the full OAuth / callback-interception pattern and the per-platform notes.

These are linked from their own pages where richer examples exist.

Common widget helpers

Every widget handle accepts these:

See Styling and Events for deeper coverage.

Next Steps

• Layout — Arranging widgets with stacks and containers
• Styling — Colors, fonts, borders
• State Management — Reactive bindings

Layout

Perry provides layout containers that arrange child widgets using the platform’s native layout system. Every snippet below is excerpted from docs/examples/ui/layout/snippets.ts — CI compiles and runs it on every PR.

Layout helpers are free functions: widgetAddChild(parent, child), stackSetAlignment(stack, value), widgetSetEdgeInsets(w, top, left, bottom, right), etc. Stack constructors take a numeric spacing followed by a child array; everything else (alignment, distribution, padding, sizing) is applied post-construction via the free functions on the widget handle.

VStack

Arranges children vertically (top to bottom).

const stack = VStack(16, [
    Text("First"),
    Text("Second"),
    Text("Third"),
])

VStack(spacing, children) — the first argument is the gap in points between children.

HStack

Arranges children horizontally (left to right).

const row = HStack(8, [
    Button("Cancel", noop),
    Spacer(),
    Button("OK", noop),
])

ZStack

Layers children on top of each other (back to front). ZStack() takes no constructor children — populate it with widgetAddChild:

const layered = ZStack()
widgetAddChild(layered, ImageFile("background.png"))
widgetAddChild(layered, Text("Overlay text"))

ScrollView

A scrollable container. Built empty, then filled via scrollviewSetChild:

// ScrollView() takes no args; populate it with `scrollviewSetChild`.
const sv = ScrollView()
const inner = VStack(8, [Text("a"), Text("b"), Text("c")])
scrollviewSetChild(sv, inner)

LazyVStack

A vertically scrolling list that lazily renders items. More efficient than ScrollView + VStack for thousands of rows — on macOS this is backed by NSTableView so only rows in the visible rect are realized.

// `render(index)` is invoked lazily — only rows in the visible rect are realized.
const lazy = LazyVStack(1000, (index: number) => Text(`Row ${index}`))

When the underlying data changes, call lazyvstackUpdate(handle, newCount) to refresh. Override the default 44pt row height with lazyvstackSetRowHeight.

NavStack

A navigation container that supports push/pop navigation. Push a new view with navstackPush(stack, view, title); pop with navstackPop(stack):

const home = VStack(16, [
    Text("Home Screen"),
    Button("Go to Details", () => {
        navstackPush(nav, Text("Details!"), "Details")
    }),
])
const nav = NavStack()
widgetAddChild(nav, home)

Spacer

A flexible space that expands to fill available room.

const toolbar = HStack(8, [
    Text("Left"),
    Spacer(),
    Text("Right"),
])

Use Spacer() inside HStack or VStack to push widgets apart.

Divider

A visual separator line.

const sections = VStack(12, [
    Text("Section 1"),
    Divider(),
    Text("Section 2"),
])

Nesting Layouts

Layouts can be nested freely. This complete example is verified by CI:

// demonstrates: nested VStack/HStack + Spacer + Divider
// docs: docs/src/ui/layout.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import { App, VStack, HStack, Text, Button, Spacer, Divider } from "perry/ui"

App({
    title: "Layout Example",
    width: 800,
    height: 600,
    body: VStack(16, [
        // Header
        HStack(8, [
            Text("My App"),
            Spacer(),
            Button("Settings", () => {}),
        ]),
        Divider(),
        // Content
        VStack(12, [
            Text("Welcome!"),
            HStack(8, [
                Button("Action 1", () => {}),
                Button("Action 2", () => {}),
            ]),
        ]),
        Spacer(),
        // Footer
        Text("v1.0.0"),
    ]),
})

Child Management

Containers support dynamic child management via free functions:

const list = VStack(16, [])
widgetAddChild(list, Text("appended"))            // append
widgetAddChildAt(list, Text("prepended"), 0)      // insert at index
widgetReorderChild(list, 1, 0)                    // move from→to
const removeMe = Text("temporary")
widgetAddChild(list, removeMe)
widgetRemoveChild(list, removeMe)                 // remove
widgetClearChildren(list)                         // remove all

Stack Alignment

Control how children are aligned within a stack using stackSetAlignment:

const centered = VStack(16, [
    Text("Centered"),
    Text("Content"),
])
stackSetAlignment(centered, 9) // CenterX

VStack alignment (cross-axis = horizontal):

HStack alignment (cross-axis = vertical):

Stack Distribution

Control how children share space within a stack using stackSetDistribution:

const buttons = HStack(8, [
    Button("Cancel", noop),
    Button("OK", noop),
])
stackSetDistribution(buttons, 1) // FillEqually — both buttons get equal width

Fill Parent

Pin a child’s edges to its parent container:

const banner = Text("Full width banner")
widgetMatchParentWidth(banner)
const banneredPage = VStack(16, [banner, Text("Normal width")])

• widgetMatchParentWidth(widget) — stretch to fill parent’s width
• widgetMatchParentHeight(widget) — stretch to fill parent’s height

Content Hugging

Control whether a widget resists being stretched beyond its intrinsic size:

const tight = Text("I stay small")
widgetSetHugging(tight, 750) // High priority — resist stretching

const stretchy = Text("I stretch")
widgetSetHugging(stretchy, 1) // Low priority — stretch to fill

• High priority (250–750+): widget resists stretching, stays at its natural size
• Low priority (1–249): widget stretches to fill available space

Overlay Positioning

For absolute positioning, add overlay children to any container:

// Overlay parent must be a ZStack — macOS NSView allows `addSubview` on
// any view, but GTK4 can only float children above siblings inside
// `gtk::Overlay` (which is what ZStack is backed by).
const container = ZStack()
widgetAddChild(container, VStack(16, [Text("Main content")])) // main child

const badge = Text("3")
setCornerRadius(badge, 10)
widgetSetBackgroundColor(badge, 1.0, 0.231, 0.188, 1.0) // RGBA red

widgetAddOverlay(container, badge)
widgetSetOverlayFrame(badge, 280, 10, 20, 20) // x, y, width, height

Overlay children are positioned absolutely relative to their parent — similar to CSS position: absolute.

Split Views

Create resizable split panes for sidebar layouts:

const split = SplitView()

const sidebar = VStack(8, [Text("Navigation"), Text("Item 1"), Text("Item 2")])
const content = VStack(16, [Text("Main Content")])

splitViewAddChild(split, sidebar)
splitViewAddChild(split, content)

The user can drag the divider to resize panes. On macOS this maps to NSSplitView.

Stacks with Built-in Padding

Create a stack with padding in a single call. The order is top, left, bottom, right (CSS-shorthand-style), not top/right/bottom/left:

// VStackWithInsets(spacing, top, left, bottom, right) — note: order is
// top/left/bottom/right (CSS-style), not top/right/bottom/left.
const card = VStackWithInsets(12, 16, 16, 16, 16)
widgetAddChild(card, Text("Padded content"))
widgetAddChild(card, Text("More content"))

HStackWithInsets(spacing, top, left, bottom, right) is the horizontal counterpart. Equivalent to creating a stack and then calling widgetSetEdgeInsets, but more concise. Children are added via widgetAddChild rather than the constructor array.

Detaching Hidden Views

By default, hidden children still occupy space in a stack. To collapse them:

const collapsible = VStack(8, [Text("Always visible"), Text("Sometimes hidden")])
stackSetDetachesHidden(collapsible, 1) // Hidden children leave no gap
// You can then toggle a child:
const sometimesHidden = Text("toggle me")
widgetSetHidden(sometimesHidden, 1) // 1 = hidden, 0 = visible

Common Layout Patterns

Centered content

const page = VStack(16, [Text("Title"), Text("Subtitle")])
stackSetAlignment(page, 9) // CenterX

Search row that fills the width

const searchInput = TextField("Search...", (v: string) => search.set(v))
widgetMatchParentWidth(searchInput)
const results = VStack(8, [])
const searchPage = VStack(12, [searchInput, results])

Floating badge / overlay

// Wrap the icon in a ZStack so the badge can float above it on every
const icon = ZStack()
widgetAddChild(icon, ImageSymbol("bell"))
const dotBadge = Text("3")
widgetAddOverlay(icon, dotBadge)
widgetSetOverlayFrame(dotBadge, 20, -5, 16, 16)

Toolbar with spacers

const titleBar = HStack(8, [
    Button("Back", noop),
    Spacer(),
    Text("Page Title"),
    Spacer(),
    Button("Settings", noop),
])

Next Steps

• Styling — Colors, padding, sizing
• Widgets — All available widgets
• State Management — Dynamic UI with state

Styling

Perry widgets accept an inline style: { ... } object that maps to each platform’s native styling APIs. The same shape works on every Widget constructor — Button, Text, Toggle, Slider, VStack/HStack, and friends — so cross-platform styling code stays the same regardless of target.

Inline style — recommended

Pass a StyleProps object as the trailing argument to any widget constructor. Codegen destructures the literal at HIR time into a sequence of native setter calls, so the runtime shape is the same as hand-writing the imperative pattern below — but the source is much shorter:

const card = Button("Save", () => {
    console.log("saved")
}, {
    backgroundColor: { r: 0.231, g: 0.510, b: 0.965, a: 1.0 },
    borderColor: { r: 0.0, g: 0.0, b: 0.0, a: 0.1 },
    borderWidth: 1,
    borderRadius: 8,
    padding: 12,
    opacity: 0.95,
    shadow: {
        color: { r: 0.0, g: 0.0, b: 0.0, a: 0.25 },
        blur: 12,
        offsetX: 0,
        offsetY: 4,
    },
    tooltip: "Save the current document",
    enabled: true,
})

The style arg is optional; widgets without it look identical to calls before this API existed. See docs/examples/ui/styling/button_inline_style.ts for the full file.

What style accepts

Color values

Color props accept four interchangeable shapes:

backgroundColor: "#3B82F6"                                   // hex 6/8
backgroundColor: "#3B82F6FF"                                 // hex with alpha
backgroundColor: "blue"                                      // named color
backgroundColor: { r: 0.231, g: 0.510, b: 0.965, a: 1.0 }   // PerryColor object
backgroundColor: themeColor                                  // runtime variable

Named colors: white, black, red, green, blue, yellow, cyan, magenta, gray / grey, transparent. Hex forms supported: #RGB, #RGBA, #RRGGBB, #RRGGBBAA.

Literals (the first four forms) compile-time-fold into 4 baked-in float arguments — zero runtime cost. Runtime variables resolve through js_color_parse_channel (a small CSS color parser in perry-runtime) so backgroundColor: someStringVar works the same as the literal form.

Padding shapes

A single number applies to all four sides; an object picks per-side:

padding: 12                                       // all four sides 12
padding: { top: 8, right: 16, bottom: 8, left: 16 }  // per-side

Missing sides default to 0.

Container styling

VStack and HStack accept style after the children array:

// VStack with explicit spacing AND inline style — children + style.
const card = VStack(8, [
    Text("Heading"),
    Text("Subtitle"),
    Button("Action", () => { console.log("clicked") }),
], {
    backgroundColor: { r: 0.96, g: 0.97, b: 0.99, a: 1.0 },
    borderRadius: 12,
    padding: 16,
    shadow: {
        color: { r: 0.0, g: 0.0, b: 0.0, a: 0.1 },
        blur: 8,
        offsetY: 2,
    },
})

// HStack with no explicit spacing (children-array first form) + style.
const toolbar = HStack([
    Text("Left"),
    Text("Right"),
], {
    backgroundColor: { r: 0.2, g: 0.2, b: 0.2, a: 1.0 },
    padding: { top: 8, right: 16, bottom: 8, left: 16 },
    borderRadius: 6,
})

Both shapes work — VStack(children, style?) and VStack(spacing, children, style?).

Coming from CSS

If you’re coming from web, the conceptual mapping is:

See Layout for full details on alignment, distribution, overlays, and split views.

Imperative API (underlying)

The inline style object lowers to the same FFI calls as Perry’s imperative free-function setters: widgetSet*, textSet*, buttonSet*. They take the widget handle as the first argument and remain available for cases where you want fine-grained control or need to mutate styles after creation. Colors here are RGBA floats in [0.0, 1.0] (divide each hex byte by 255 — 0xFF3B30 → (1.0, 0.231, 0.188, 1.0)).

Every snippet below is excerpted from docs/examples/ui/styling/snippets.ts, which CI compiles and runs on every PR — so the API drawn here is always the API the compiler accepts.

import {
    App,
    VStack, VStackWithInsets, HStack, Spacer,
    Text, Button,
    textSetColor, textSetFontSize, textSetFontFamily, textSetFontWeight,
    setCornerRadius, setPadding,
    widgetAddChild,
    widgetSetBackgroundColor, widgetSetBackgroundGradient,
    widgetSetBorderColor, widgetSetBorderWidth,
    widgetSetEdgeInsets,
    widgetSetWidth, widgetSetHeight, widgetMatchParentWidth,
    widgetSetOpacity,
    widgetSetControlSize,
    widgetSetTooltip,
    widgetSetEnabled,
} from "perry/ui"

Colors

const colored = Text("Colored text")
textSetColor(colored, 1.0, 0.0, 0.0, 1.0)              // r, g, b, a in [0,1]
widgetSetBackgroundColor(colored, 0.94, 0.94, 0.94, 1.0)

Fonts

const font = Text("Styled text")
textSetFontSize(font, 24)                  // Font size in points
textSetFontFamily(font, "Menlo")           // Font family name
textSetFontWeight(font, 24, 700)           // Re-set size + weight together

Use "monospaced" for the system monospaced font.

Corner Radius

const rounded = Button("Rounded", () => {})
setCornerRadius(rounded, 12)

Borders

const bordered = VStack(0, [])
widgetSetBorderColor(bordered, 0.8, 0.8, 0.8, 1.0)
widgetSetBorderWidth(bordered, 1)

Padding and Insets

const padded = VStack(8, [Text("Padded content")])
// Both names accept (widget, top, left, bottom, right):
setPadding(padded, 16, 16, 16, 16)
widgetSetEdgeInsets(padded, 10, 20, 10, 20)

Sizing

const sized = VStack(0, [])
widgetSetWidth(sized, 300)
widgetSetHeight(sized, 200)
widgetMatchParentWidth(sized) // expand to fill parent's width

Opacity

const dim = Text("Semi-transparent")
widgetSetOpacity(dim, 0.5) // 0.0 to 1.0

Background Gradient

const grad = VStack(0, [])
// Two RGBA stops + angle (degrees, 0 = top-to-bottom).
widgetSetBackgroundGradient(grad,
    1.0, 0.0, 0.0, 1.0,   // start (red)
    0.0, 0.0, 1.0, 1.0,   // end   (blue)
    0,                    // angle
)

Control Size

const small = Button("Small", () => {})
widgetSetControlSize(small, 0) // 0=mini, 1=small, 2=regular, 3=large

macOS: Maps to NSControl.ControlSize. Other platforms may interpret differently.

Tooltips

const tip = Button("Hover me", () => {})
widgetSetTooltip(tip, "Click to perform action")

macOS/Windows/Linux: Native tooltips. iOS/Android: No tooltip support. Web: HTML title attribute.

Enabled/Disabled

const submit = Button("Submit", () => {})
widgetSetEnabled(submit, 0)  // 0 = disabled, 1 = enabled

Complete Imperative Example

// demonstrates: a styled counter card using the real free-function API
// docs: docs/src/ui/styling.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import {
    App,
    Text,
    Button,
    VStack,
    HStack,
    State,
    Spacer,
    textSetFontSize,
    textSetFontFamily,
    textSetColor,
    widgetSetBackgroundColor,
    widgetSetEdgeInsets,
    setCornerRadius,
} from "perry/ui"

// Note: widgetSetBorderColor / widgetSetBorderWidth are macOS/iOS/Windows
// only — perry-ui-gtk4 doesn't export them (GTK4 borders are CSS-driven).
// Omitted from this demo so it compiles everywhere.

const count = State(0)

const title = Text("Counter")
textSetFontSize(title, 28)
textSetColor(title, 0.1, 0.1, 0.1, 1.0)

const display = Text(`${count.value}`)
textSetFontSize(display, 48)
textSetFontFamily(display, "monospaced")
textSetColor(display, 0.0, 0.478, 1.0, 1.0)

const decBtn = Button("-", () => count.set(count.value - 1))
setCornerRadius(decBtn, 20)
widgetSetBackgroundColor(decBtn, 1.0, 0.231, 0.188, 1.0)

const incBtn = Button("+", () => count.set(count.value + 1))
setCornerRadius(incBtn, 20)
widgetSetBackgroundColor(incBtn, 0.204, 0.78, 0.349, 1.0)

const controls = HStack(8, [decBtn, Spacer(), incBtn])
widgetSetEdgeInsets(controls, 20, 20, 20, 20)

const container = VStack(16, [title, display, controls])
widgetSetEdgeInsets(container, 40, 40, 40, 40)
setCornerRadius(container, 16)
widgetSetBackgroundColor(container, 1.0, 1.0, 1.0, 1.0)

App({
    title: "Styled App",
    width: 400,
    height: 300,
    body: container,
})

Composing Styles (imperative helper functions)

Reduce repetition by creating helper functions:

function card(children: number[]): number {
  const c = VStackWithInsets(12, 16, 16, 16, 16)
  setCornerRadius(c, 12)
  widgetSetBackgroundColor(c, 1.0, 1.0, 1.0, 1.0)
  widgetSetBorderColor(c, 0.9, 0.9, 0.9, 1.0)
  widgetSetBorderWidth(c, 1)
  for (const child of children) widgetAddChild(c, child)
  return c
}

For larger apps, use the perry-styling package to define design tokens in JSON and generate a typed theme file. See Theming for the full workflow.

Platform support

Per-prop, per-platform support is tracked in the styling matrix — auto-generated from crates/perry-ui/src/styling_matrix.rs and CI-checked against each backend’s lib.rs exports on every PR.

Current state (issue #185):

• GTK4 has 4 styling props (widget.on_click, button.content_tint_color, button.image_position, stack.detaches_hidden) that need a Linux contributor — tracked in issue #202. Inline style: {...} calls referencing only the wired props compile and run cleanly today; the missing props silently no-op until that issue lands.
• Windows has 5 props in a “deferred-paint family” (shadow, opacity, border_color, border_width, text.decoration) where the FFI symbol exists and stores the requested params, but a custom WM_PAINT rendering pass is needed to make them visible — tracked in issue #210. User code authoring inline styles compiles and links cleanly on Windows; the visual rendering catches up when that issue lands.

Next Steps

• Widgets — All available widgets
• Layout — Layout containers
• Animation — Animate style changes
• Theming — Design tokens via the perry-styling package

State Management

Perry uses reactive state to automatically update the UI when data changes. Every snippet below is excerpted from docs/examples/ui/state/snippets.ts — CI compiles and runs it on every PR.

Creating State

const counter = State(0)               // number state
const username = State("Perry")        // string state
const items = State<string[]>([])      // array state

State(initialValue) creates a reactive state container.

Reading and Writing

const value = counter.value     // Read current value
counter.set(42)                  // Set new value → triggers UI update

Every .set() call re-renders the widget tree with the new value.

Reactive Text

Template literals with state.value update automatically:

const showCount = State(0)
const countLabel = Text(`Count: ${showCount.value}`)
// The text updates whenever showCount changes.

This works because Perry detects state.value reads inside template literals and creates reactive bindings.

Binding Inputs to State

Input widgets expose an onChange callback. Forward that into a state’s .set(...) to keep the state in sync as the user types/toggles/drags:

const input = State("")
const field = TextField("Type here...", (v: string) => input.set(v))

// Optional: also let input.set("hello") update the field on screen.
stateBindTextfield(input, field)

Input control signatures:

• TextField(placeholder, onChange) — text input, onChange: (value: string) => void
• SecureField(placeholder, onChange) — password input, onChange: (value: string) => void
• Toggle(label, onChange) — boolean toggle, onChange: (value: boolean) => void
• Slider(min, max, onChange) — numeric slider, onChange: (value: number) => void
• Picker(onChange) — dropdown, onChange: (index: number) => void; items via pickerAddItem

For programmatic-to-UI sync (state-drives-widget) use the dedicated binders: stateBindTextfield, stateBindSlider, stateBindToggle, stateBindTextNumeric, stateBindVisibility.

onChange Callbacks

Listen for state changes with the free-function stateOnChange:

const watched = State(0)
stateOnChange(watched, (newValue: number) => {
    console.log(`Count changed to ${newValue}`)
})

ForEach

Render a list from numeric state (the index count):

const fruits = State(["Apple", "Banana", "Cherry"])
const fruitCount = State(3)

const fruitList = VStack(16, [
    ForEach(fruitCount, (i: number) =>
        Text(`${i + 1}. ${fruits.value[i]}`),
    ),
])

Note: ForEach iterates by index over a numeric state. Keep a count state in sync with your array, then read the items via array.value[i] inside the closure.

ForEach re-renders the list when the count state changes:

// Add an item:
fruits.set([...fruits.value, "Date"])
fruitCount.set(fruitCount.value + 1)

// Remove an item:
fruits.set(fruits.value.filter((_, i) => i !== 1))
fruitCount.set(fruitCount.value - 1)

Conditional Rendering

Use state to conditionally show widgets:

const showDetails = State(false)
const detailsLabel: number = showDetails.value
    ? Text("Details are visible!")
    : Spacer()
const detailsPanel = VStack(16, [
    Button("Toggle", () => showDetails.set(!showDetails.value)),
    detailsLabel,
])

Multi-State Text

Text can depend on multiple state values:

const firstName = State("John")
const lastName = State("Doe")

const greeting = Text(`Hello, ${firstName.value} ${lastName.value}!`)
// Updates when either firstName or lastName changes.

State with Objects and Arrays

const user = State({ name: "Perry", age: 0 })

// Update by replacing the whole object:
user.set({ ...user.value, age: 1 })

const todos = State<{ text: string; done: boolean }[]>([])

// Add a todo:
todos.set([...todos.value, { text: "New task", done: false }])

// Toggle a todo (must produce a new array reference):
const next = todos.value.slice()
if (next.length > 0) {
    next[0] = { ...next[0], done: !next[0].done }
    todos.set(next)
}

Note: State uses identity comparison. You must create a new array/object reference for changes to be detected. Mutating in-place without calling .set() with a new reference won’t trigger updates.

Complete Example

// demonstrates: complete reactive todo app combining State, ForEach, and widget tree mutation
// docs: docs/src/ui/state.md
// platforms: macos, linux, windows
// targets: ios-simulator, tvos-simulator, watchos-simulator, web, wasm

import {
    App,
    Text,
    Button,
    TextField,
    VStack,
    HStack,
    State,
    ForEach,
    Spacer,
    Divider,
} from "perry/ui"

const todos = State<string[]>([])
const count = State(0)
const input = State("")

App({
    title: "Todo App",
    width: 480,
    height: 600,
    body: VStack(16, [
        Text("My Todos"),

        HStack(8, [
            TextField("What needs to be done?", (value: string) => input.set(value)),
            Button("Add", () => {
                const text = input.value
                if (text.length > 0) {
                    todos.set([...todos.value, text])
                    count.set(count.value + 1)
                    input.set("")
                }
            }),
        ]),

        Divider(),

        ForEach(count, (i: number) =>
            HStack(8, [
                Text(todos.value[i]),
                Spacer(),
                Button("Delete", () => {
                    todos.set(todos.value.filter((_, idx) => idx !== i))
                    count.set(count.value - 1)
                }),
            ]),
        ),

        Spacer(),
        Text(`${count.value} items`),
    ]),
})

This program is built and run by CI (scripts/run_doc_tests.sh), so the snippet above always matches the compiled artifact under docs/examples/ui/state/todo_app.ts.

Next Steps

• Events — Click, hover, keyboard events
• Widgets — All available widgets
• Layout — Layout containers

Events

Perry widgets support native event handlers for user interaction. Every snippet below is excerpted from docs/examples/ui/events/snippets.ts — CI compiles and runs it on every PR, so the API drawn here is the API the runtime exposes.

Event handlers are registered as free functions that take the widget handle as the first argument. The widget handle itself is opaque (number at the type level); perry’s API is function-first throughout.

onClick

const greet = Button("Click me", () => {
    log.set("Button clicked")
})

// Or attach a click handler to a non-button widget after creation:
const label = Text("Clickable text")
widgetSetOnClick(label, () => {
    log.set("Text clicked")
})

onHover

Triggered when the cursor enters the widget.

const hoverBtn = Button("Hover me", () => {})
widgetSetOnHover(hoverBtn, () => {
    log.set("hovered")
})

Note: Hover events are available on macOS, Windows, Linux, and Web. iOS and Android use touch interactions instead. The callback fires once on enter; if you need a “left” event you’ll have to track it yourself.

onDoubleClick

const dbl = Text("Double-click me")
widgetSetOnDoubleClick(dbl, () => {
    log.set("double-clicked!")
})

Keyboard Shortcuts

Register in-app keyboard shortcuts (active when the app is focused):

// Cmd+N on macOS, Ctrl+N on other platforms (modifier 1 = Cmd/Ctrl).
addKeyboardShortcut("n", 1, () => {
    log.set("New document")
})

// Cmd+Shift+S — modifiers add: 1 (Cmd/Ctrl) + 2 (Shift) = 3.
addKeyboardShortcut("s", 3, () => {
    log.set("Save as...")
})

Modifier bits: 1 = Cmd (macOS) / Ctrl (Windows/Linux), 2 = Shift, 4 = Option (macOS) / Alt (others), 8 = Control (macOS only). Combine by adding — 3 = Cmd+Shift, 5 = Cmd+Option, etc.

Keyboard shortcuts are also available on menu items:

const fileMenu = menuCreate()
menuAddItem(fileMenu, "New", () => log.set("file/new"))
menuAddItem(fileMenu, "Save As", () => log.set("file/saveAs"))

Global Hotkeys

Register a hotkey that fires system-wide, even when the app is in the background:

// System-wide: fires even when the app is in the background.
// macOS: real Carbon RegisterEventHotKey. Other platforms: no-op.
registerGlobalHotkey("F5", 0, () => {
    log.set("Global F5 hotkey fired")
})

// Cmd+Shift+G (modifiers: 1=Cmd + 2=Shift = 3)
registerGlobalHotkey("g", 3, () => {
    log.set("Global Cmd+Shift+G fired")
})

Platform support: macOS uses Carbon RegisterEventHotKey (real implementation). Linux, Windows, iOS, tvOS, visionOS, watchOS, and Android log the registration and no-op — global hotkeys on those platforms require OS-level portal / hook APIs that vary per OS.

Clipboard

// Copy to clipboard
clipboardWrite("Hello, clipboard!")

// Read from clipboard
const text = clipboardRead()
log.set(`clipboard length: ${text.length}`)

Complete Example

// demonstrates: click + hover + double-click + keyboard shortcut all wired to
// a single State-backed status label
// docs: docs/src/ui/events.md
// platforms: macos, linux, windows
// targets: ios-simulator, web, wasm

import {
    App,
    Text,
    Button,
    VStack,
    State,
    Spacer,
    addKeyboardShortcut,
    widgetSetOnHover,
    widgetSetOnDoubleClick,
} from "perry/ui"

const lastEvent = State("No events yet")

// Cmd+R (modifiers: 1 = Cmd/Ctrl).
addKeyboardShortcut("r", 1, () => {
    lastEvent.set("Keyboard: Cmd+R")
})

const hoverBtn = Button("Hover me", () => {})
widgetSetOnHover(hoverBtn, () => {
    lastEvent.set("Hover fired")
})

const dblLabel = Text("Double-click me")
widgetSetOnDoubleClick(dblLabel, () => {
    lastEvent.set("Double-clicked!")
})

App({
    title: "Events Demo",
    width: 400,
    height: 300,
    body: VStack(16, [
        Text(`Last event: ${lastEvent.value}`),
        Spacer(),
        Button("Click me", () => {
            lastEvent.set("Button clicked")
        }),
        hoverBtn,
        dblLabel,
    ]),
})

Next Steps

• Menus — Menu bar and context menus with keyboard shortcuts
• Widgets — All available widgets
• State Management — Reactive state

Canvas

The Canvas widget provides a 2D drawing surface for custom graphics.

Availability: Canvas is wired in the LLVM codegen path (macOS, iOS, Linux, Android) and the JS / web / wasm codegen path. Closed via #190. The snippets below are compile-link verified by the doc-tests harness against docs/examples/ui/canvas/snippets.ts; see that file for the full standalone program.

The drawing API is method-based on the canvas handle (matching the FFI shape — perry_ui_canvas_set_fill_color(handle, r, g, b, a) etc.). Colors are RGBA floats in [0.0, 1.0].

Creating a Canvas

const canvas = Canvas(400, 300)
canvas.setFillColor(1.0, 0.4, 0.0, 1.0)
canvas.fillRect(10, 10, 100, 80)

Canvas(width, height) creates a canvas widget; subsequent draw operations are method calls on the returned handle.

Drawing Shapes

Rectangles

canvas.setFillColor(1.0, 0.0, 0.0, 1.0)    // red
canvas.fillRect(10, 10, 100, 80)

canvas.setStrokeColor(0.0, 0.0, 1.0, 1.0)  // blue
canvas.setLineWidth(2)
canvas.strokeRect(150, 10, 100, 80)

Lines

canvas.setStrokeColor(0.0, 0.0, 0.0, 1.0)
canvas.setLineWidth(1)
canvas.beginPath()
canvas.moveTo(10, 10)
canvas.lineTo(200, 150)
canvas.stroke()

Circles and Arcs

canvas.setFillColor(0.0, 1.0, 0.0, 1.0)
canvas.beginPath()
canvas.arc(200, 150, 50, 0, Math.PI * 2)  // x, y, radius, startAngle, endAngle
canvas.fill()

Text

canvas.setFillColor(0.0, 0.0, 0.0, 1.0)
canvas.setFont("16px sans-serif")
canvas.fillText("Hello Canvas!", 50, 50)

Platform Notes

Next Steps

• Widgets — All available widgets
• Animation — Animating widget properties
• Styling — Widget styling

Menus

Perry supports native menu bars, context menus, and toolbars across all platforms. Every snippet below is excerpted from docs/examples/ui/menus/snippets.ts — CI compiles and runs it on every PR.

The menu API is handle-based and free-function: build menus with menuCreate(), fill them with menuAddItem / menuAddItemWithShortcut, and attach them with menuBarAddMenu(bar, title, menu). Submenus go through menuAddSubmenu(parent, title, submenu).

Menu Bar

// Menus are created independently, then attached. Build child menus first,
// then hand them to `menuBarAddMenu(bar, title, menu)`.
const menuBar = menuBarCreate()

// File menu
const fileMenu = menuCreate()
menuAddItemWithShortcut(fileMenu, "New",         "n", () => status.set("file/new"))
menuAddItemWithShortcut(fileMenu, "Open…",       "o", () => status.set("file/open"))
menuAddSeparator(fileMenu)
menuAddItemWithShortcut(fileMenu, "Save",        "s", () => status.set("file/save"))
menuAddItemWithShortcut(fileMenu, "Save As…",    "S", () => status.set("file/saveAs"))
menuBarAddMenu(menuBar, "File", fileMenu)

// Edit menu
const editMenu = menuCreate()
menuAddItemWithShortcut(editMenu, "Undo", "z", () => status.set("edit/undo"))
menuAddItemWithShortcut(editMenu, "Redo", "Z", () => status.set("edit/redo"))
menuAddSeparator(editMenu)
menuAddItemWithShortcut(editMenu, "Cut",   "x", () => status.set("edit/cut"))
menuAddItemWithShortcut(editMenu, "Copy",  "c", () => status.set("edit/copy"))
menuAddItemWithShortcut(editMenu, "Paste", "v", () => status.set("edit/paste"))
menuBarAddMenu(menuBar, "Edit", editMenu)

// Submenu: View → Zoom
const viewMenu = menuCreate()
const zoomSubmenu = menuCreate()
menuAddItemWithShortcut(zoomSubmenu, "Zoom In",     "+", () => status.set("zoom/in"))
menuAddItemWithShortcut(zoomSubmenu, "Zoom Out",    "-", () => status.set("zoom/out"))
menuAddItemWithShortcut(zoomSubmenu, "Actual Size", "0", () => status.set("zoom/reset"))
menuAddSubmenu(viewMenu, "Zoom", zoomSubmenu)
menuBarAddMenu(menuBar, "View", viewMenu)

menuBarAttach(menuBar)

Menu Bar Functions

Keyboard Shortcuts

The third argument to menuAddItemWithShortcut is the shortcut key:

Uppercase letters imply Shift.

Context Menus

Right-click menus are attached to widgets via widgetSetContextMenu(widget, menu). Build the menu the same way as a menu-bar entry, then bind it:

const label = Text("Right-click me")
const ctx = menuCreate()
menuAddItem(ctx, "Copy",   () => status.set("ctx/copy"))
menuAddItem(ctx, "Paste",  () => status.set("ctx/paste"))
menuAddSeparator(ctx)
menuAddItem(ctx, "Delete", () => status.set("ctx/delete"))
widgetSetContextMenu(label, ctx)

Toolbar

Add a toolbar to a window. toolbarAddItem takes an identifier (used by AppKit to deduplicate items) and a label:

const toolbar = toolbarCreate()
toolbarAddItem(toolbar, "new",  "New",  () => status.set("tb/new"))
toolbarAddItem(toolbar, "save", "Save", () => status.set("tb/save"))
toolbarAddItem(toolbar, "run",  "Run",  () => status.set("tb/run"))

// `toolbarAttach(toolbar, window)` mounts onto a specific window.
const win = Window("Toolbar Demo", 800, 600)
toolbarAttach(toolbar, win as unknown as number)

Platform Notes

iOS: Menu bars are not applicable. Use toolbar and navigation patterns instead.

Next Steps

• Events — Keyboard shortcuts and interactions
• Dialogs — File dialogs and alerts
• Layout — Toolbar and navigation patterns

Tray Icon

Perry ships a cross-platform system tray API on perry/ui (issue #490). The same six functions work on every desktop target — macOS, Windows, Linux/GTK4 — and link as no-ops on the mobile / embedded backends.

The API is handle-based and free-function: build a tray with trayCreate(iconPath), attach a context menu built with the existing menuCreate / menuAddItem API via trayAttachMenu(tray, menu), and register a left-click callback with trayOnClick.

Basic Usage

// Build the tray BEFORE App() — the tray icon installs while the
// runtime is starting up, so it's already live when the main window
// appears.
const tray = trayCreate("")  // empty path → "●" placeholder
traySetTooltip(tray, "My App")

// Right-click (or left-click on macOS) opens the menu attached below.
const menu = menuCreate()
menuAddItem(menu, "Show", () => status.set("tray/show"))
menuAddSeparator(menu)
menuAddItem(menu, "Quit", () => status.set("tray/quit"))
trayAttachMenu(tray, menu)

// Optional: left-click handler. On macOS the menu pops on left-click,
// so this fires only when no menu is attached. On Windows / Linux,
// left-click and the menu are independent — typical usage is
// "left-click → show main window, right-click → menu".
trayOnClick(tray, () => {
    status.set("tray/click")
})

API

Updating the Icon

// Hot-swap the icon. The path can be a PNG (every platform), .icns
// (macOS), or .ico (Windows). Empty path is a no-op.
traySetIcon(tray, "./assets/tray.png")

Removal

// Remove the tray icon. After this, the handle is dead — set_icon /
// set_tooltip / attach_menu calls become no-ops.
trayDestroy(tray)

Platform Notes

Click vs. Menu

Different desktops have different click conventions; Perry exposes both hooks so a single TypeScript app can do the right thing everywhere:

The typical pattern: use onClick to “show / focus the main window” and attachMenu for the user-facing actions. macOS users will see the menu pop on every click, which is the platform-native behavior.

Common Patterns

Background app (no Dock icon, tray-only)

On macOS, set the activation policy to "accessory" so the app has no Dock icon and lives only as a tray-resident process. (See the platform docs for activation-policy details.)

Building the menu after the tray

The menu lookup on every backend happens at click time, not at attach time. This means you can rebuild the menu (menuClear + fresh menuAddItem calls) between user clicks — the new menu wins on the next click without re-attaching.

Next Steps

• Menus — Full menu / submenu / shortcut API used by trayAttachMenu
• State Management — Make tray menu items react to app state
• Multi-Window — Show / hide windows from tray actions

Dialogs

Perry provides native dialog functions for file selection, alerts, and sheets. Every snippet below is excerpted from docs/examples/ui/dialogs/snippets.ts — CI compiles and links the file on every PR, so the API drawn here is the API the runtime exposes.

All file dialogs are callback-based (the OS-modal panel is non-blocking on Apple platforms, so a synchronous return wouldn’t be possible without freezing the app’s run loop). The callback receives an empty string when the user cancels.

File Open Dialog

function pickFile(): void {
    openFileDialog((path: string) => {
        if (path.length > 0) {
            console.log(`Selected: ${path}`)
        } else {
            console.log("Open dialog cancelled")
        }
    })
}

Folder Selection Dialog

function pickFolder(): void {
    openFolderDialog((path: string) => {
        if (path.length > 0) {
            console.log(`Selected folder: ${path}`)
        }
    })
}

Save File Dialog

function pickSaveTarget(): void {
    saveFileDialog((path: string) => {
        if (path.length > 0) {
            console.log(`Will save to: ${path}`)
        }
    }, "untitled", "txt")
}

saveFileDialog(callback, defaultName, extension) pre-fills the name field with defaultName.<extension>.

Alert

Display a native alert dialog:

function showSimpleAlert(): void {
    alert("Operation Complete", "Your file has been saved successfully.")
}

alert(title, message) shows a modal alert with an OK button.

Alert with Buttons

function confirmDelete(): void {
    alertWithButtons(
        "Delete Item?",
        "This action cannot be undone.",
        ["Cancel", "Delete"],
        (index: number) => {
            if (index === 1) {
                console.log("user confirmed delete")
            }
        },
    )
}

alertWithButtons(title, message, buttons, callback) invokes the callback with the 0-based index of the button the user clicked. By convention put a destructive label last and check the index in the callback.

Sheets

Sheets are modal panels attached to a window. Build the body, hand it (with a size) to sheetCreate, then sheetPresent it. To dismiss programmatically, keep the handle around and call sheetDismiss(handle):

function showSheet(): void {
    let sheet = 0
    const body = VStack(16, [
        Text("Sheet Content"),
        Button("Close", () => sheetDismiss(sheet)),
    ])
    sheet = sheetCreate(body, 320, 200)
    sheetPresent(sheet)
}

Platform Notes

Complete Example: minimal text editor

A real program that wires openFileDialog and saveFileDialog into a state-bound TextField:

// demonstrates: file-open / save dialogs wired to a tiny text editor
// docs: docs/src/ui/dialogs.md
// platforms: macos, linux, windows

import {
    App,
    VStack, HStack,
    Text, Button, TextField,
    State,
    openFileDialog, saveFileDialog, alert,
} from "perry/ui"
import { readFileSync, writeFileSync } from "fs"

const content = State("")
const filePath = State("")

App({
    title: "Text Editor",
    width: 800,
    height: 600,
    body: VStack(12, [
        HStack(8, [
            Button("Open", () => {
                openFileDialog((path: string) => {
                    if (path.length === 0) return
                    filePath.set(path)
                    content.set(readFileSync(path, "utf-8") as string)
                })
            }),
            Button("Save As", () => {
                saveFileDialog((path: string) => {
                    if (path.length === 0) return
                    writeFileSync(path, content.value)
                    filePath.set(path)
                    alert("Saved", `File saved to ${path}`)
                }, "untitled", "txt")
            }),
        ]),
        Text(filePath.value === "" ? "No file open" : `File: ${filePath.value}`),
        TextField("Start typing...", (value: string) => content.set(value)),
    ]),
})

Next Steps

• Menus — Menu bar and context menus
• Multi-Window — Multiple windows
• Events — User interaction events

Table

The Table widget displays tabular data with columns, headers, and row selection.

Platform support: real implementation lives on macOS (NSTableView + NSScrollView); the Web target uses an HTML <table>. iOS, Android, Linux/GTK4, Windows, tvOS, visionOS, and watchOS link no-op stubs so cross-platform code compiles everywhere — the table renders nothing and tableGetSelectedRow returns -1. For production lists on platforms without a real impl, use LazyVStack (see Layout).

Creating a Table

const basicTable = Table(10, 3, (row: number, col: number) => {
    return Text(`Row ${row}, Col ${col}`)
})

Table(rowCount, colCount, renderCell) creates a table. The render callback receives (row, col) and must return a Widget (typically Text(...)). The runtime resolves the returned handle as the cell view, which lets cells render images, stacks, or composites — not just plain strings.

Column Headers

const userTable = Table(users.length, 3, (row: number, col: number) => {
    const user = users[row]
    if (col === 0) return Text(user.name)
    if (col === 1) return Text(user.email)
    return Text(user.role)
})

tableSetColumnHeader(userTable, 0, "Name")
tableSetColumnHeader(userTable, 1, "Email")
tableSetColumnHeader(userTable, 2, "Role")

Column Widths

tableSetColumnWidth(userTable, 0, 150)  // Name column
tableSetColumnWidth(userTable, 1, 250)  // Email column
tableSetColumnWidth(userTable, 2, 100)  // Role column

Row Selection

const selectedRow = State(-1)

tableSetOnRowSelect(userTable, (row: number) => {
    selectedRow.set(row)
    console.log(`Selected row: ${row}`)
})

// Read the currently selected row at any time:
const current = tableGetSelectedRow(userTable)

Dynamic Row Count

Update the number of rows after creation:

tableUpdateRowCount(userTable, users.length)

Complete Example

const selectedName = State("None")

const table = Table(users.length, 3, (row: number, col: number) => {
    const user = users[row]
    if (col === 0) return Text(user.name)
    if (col === 1) return Text(user.email)
    return Text(user.role)
})

tableSetColumnHeader(table, 0, "Name")
tableSetColumnHeader(table, 1, "Email")
tableSetColumnHeader(table, 2, "Role")
tableSetColumnWidth(table, 0, 150)
tableSetColumnWidth(table, 1, 250)
tableSetColumnWidth(table, 2, 100)

tableSetOnRowSelect(table, (row: number) => {
    selectedName.set(users[row].name)
})

App({
    title: "Table Demo",
    width: 600,
    height: 400,
    body: VStack(12, [
        table,
        Text(`Selected: ${selectedName.value}`),
    ]),
})

Sort, filter, multi-select (issue #473)

Since v0.5.636 the macOS Table exposes a column-sort callback, multi-row selection, and a passive filter-text slot the user wires to their own row-hiding logic.

import {
  Table,
  tableSetOnSortChange,
  tableSetAllowsMultipleSelection,
  tableGetSelectedRowsCount,
  tableGetSelectedRowAt,
  tableSetFilterText,
  tableGetFilterText,
} from "perry/ui";

const table = Table(rows.length, cols.length, renderCell);

tableSetAllowsMultipleSelection(table, 1);

tableSetOnSortChange(table, (col, ascending) => {
  // Re-sort your data array, then call tableReload(table)
  rows.sort((a, b) =>
    ascending ? a[col].localeCompare(b[col]) : b[col].localeCompare(a[col]),
  );
});

// Multi-select read-back
const n = tableGetSelectedRowsCount(table);
for (let i = 0; i < n; i++) {
  console.log("selected:", tableGetSelectedRowAt(table, i));
}

// Passive filter slot — your TS code reads it back and adjusts
// `tableUpdateRowCount(table, filteredRows.length)`.
tableSetFilterText(table, "alice");
console.log(tableGetFilterText(table));

These are real impls on macOS via NSTableView.sortDescriptors and selectedRowIndexes; other platforms link safe-default stubs.

Next Steps

• Widgets — All available widgets
• Layout — Layout containers
• Events — Event handling

Animation

Perry supports animating widget properties for smooth transitions. Every snippet below is excerpted from docs/examples/ui/animation/snippets.ts — CI compiles and runs it on every PR.

animateOpacity and animatePosition are special: they’re documented as methods on the widget handle (the only methods perry/ui exposes), and the HIR lowers them to widgetAnimateOpacity / widgetAnimatePosition calls under the hood.

Opacity Animation

const fading = Text("Fading text")
// Animate from the widget's current opacity to `target` over `durationSecs`.
fading.animateOpacity(1.0, 0.3) // target, durationSeconds

Position Animation

const moving = Button("Moving", () => {})
// Animate by a delta (dx, dy) relative to the widget's current position.
moving.animatePosition(100, 200, 0.5) // dx, dy, durationSeconds

Example: Fade-In Effect

When the first argument reads from a State.value, Perry auto-subscribes the call to the state — toggling visible re-runs the animation.

// demonstrates: auto-reactive animateOpacity driven by a State toggle
// docs: docs/src/ui/animation.md
// platforms: macos, linux, windows
// targets: ios-simulator, tvos-simulator, watchos-simulator, web, wasm

import { App, Text, Button, VStack, State } from "perry/ui"

const visible = State(false)

const label = Text("Hello!")
label.animateOpacity(visible.value ? 1.0 : 0.0, 0.3)

App({
    title: "Animation Demo",
    width: 400,
    height: 300,
    body: VStack(16, [
        Button("Toggle", () => {
            visible.set(!visible.value)
        }),
        label,
    ]),
})

Platform Notes

Next Steps

• Styling — Widget styling properties
• Widgets — All available widgets
• Events — User interaction

Frame Callbacks (onFrame)

onFrame subscribes a callback to the next display-link “tick”. Use it for time-based rendering — animations driven from code, simulations, games, real-time data visualizations, or custom Canvas transitions — where you need a frame-aligned tick with an accurate timestamp instead of setInterval(cb, 16).

import { onFrame, cancelFrame } from "perry/ui";

function loop(timestampMs: number, deltaMs: number) {
  // advance simulation, redraw...
  onFrame(loop); // schedule the next frame
}

const id = onFrame(loop);
// later, to stop:
cancelFrame(id);

Semantics

• One-shot. The callback fires once. To keep a loop running, call onFrame again from inside the callback (this mirrors the web’s idiomatic requestAnimationFrame shape and avoids the “how do I stop a recurring callback” footgun).
• timestampMs is monotonic time since app start, in milliseconds, double precision.
• deltaMs is the time since the previous fire of this callback (0 on the first call). Tracking is keyed off the callback identity so the idiomatic onFrame(loop) pattern gets accurate deltas without the app bookkeeping anything.
• Order. Subscribers fire in registration order each frame.
• Pause when invisible. The web backend uses requestAnimationFrame, which is paused automatically when the tab is hidden. The native backends drive frames from their main-loop pump; treat that as a soft guarantee for now and a real per-platform display-link driver is a follow-up.

Platform mapping

Multi-Window & Window Management

Perry supports creating multiple native windows and controlling their appearance and behavior. Every snippet below is excerpted from docs/examples/ui/multi_window/snippets.ts — CI compiles and runs it on every PR.

Creating Windows

Window(title, width, height) returns a window handle. Call .setBody() to set its content and .show() to display it:

const settings = Window("Settings", 500, 400)
settings.setBody(VStack(16, [
    Text("Settings panel"),
]))
settings.show()

Window Instance Methods

const win = Window("My Window", 600, 400)

win.setBody(Text("Hello"))   // Set the root widget
win.show()                    // Show the window
win.hide()                    // Hide without destroying
win.setSize(800, 600)         // Resize dynamically
win.onFocusLost(() => {       // Callback when the window loses focus
    win.hide()
})
win.close()                   // Close and destroy

App Window Properties

The main App({}) config object accepts the same window properties for building launcher-style, overlay, or utility apps:

App({
    title: "QuickLaunch",
    width: 600,
    height: 80,
    body: VStack(8, [
        Text("Search..."),
        Button("Open Settings", () => settings.show()),
    ]),
})

App additionally accepts the optional fields frameless, level, transparent, vibrancy, activationPolicy, and icon. They map to the following native primitives:

frameless: true

Removes the window title bar and frame, creating a borderless window.

level: "floating" | "statusBar" | "modal" | "normal"

Controls the window’s z-order level relative to other windows.

transparent: true

Makes the window background transparent, allowing the desktop to show through non-opaque regions of your UI.

vibrancy: string

Applies a native translucent material to the window background. On macOS this uses the system vibrancy effect; on Windows it uses Mica/Acrylic.

macOS materials: "sidebar", "titlebar", "selection", "menu", "popover", "headerView", "sheet", "windowBackground", "hudWindow", "fullScreenUI", "tooltip", "contentBackground", "underWindowBackground", "underPageBackground"

activationPolicy: "regular" | "accessory" | "background"

Controls whether the app appears in the dock/taskbar.

Platform Notes

On mobile platforms, “windows” are presented as modal views or dialogs since mobile apps typically use a single-window model.

Next Steps

• Events — Keyboard shortcuts
• Dialogs — Modal dialogs and sheets
• Menus — Menu bar and toolbar
• UI Overview — Full UI system overview

Theming

The perry-styling package provides a design system bridge for Perry UI — design token codegen and ergonomic styling helpers with compile-time platform detection.

Installation

npm install perry-styling

Design Token Codegen

Generate typed theme files from a JSON token definition:

perry-styling generate --tokens tokens.json --out src/theme.ts

Token Format

{
  "colors": {
    "primary": "#007AFF",
    "primary-dark": "#0A84FF",
    "background": "#FFFFFF",
    "background-dark": "#1C1C1E",
    "text": "#000000",
    "text-dark": "#FFFFFF"
  },
  "spacing": {
    "sm": 4,
    "md": 8,
    "lg": 16,
    "xl": 24
  },
  "radius": {
    "sm": 4,
    "md": 8,
    "lg": 16
  },
  "fontSize": {
    "body": 14,
    "heading": 20,
    "caption": 12
  },
  "borderWidth": {
    "thin": 1,
    "medium": 2
  }
}

Colors with a -dark suffix are used as the dark mode variant. If no dark variant is provided, the light value is used for both modes. Supported color formats: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb()/rgba(), hsl()/hsla(), and CSS named colors.

Generated Types

The codegen produces typed interfaces:

interface PerryColor {
  r: number; g: number; b: number; a: number; // floats in [0, 1]
}

interface PerryTheme {
  light: { [key: string]: PerryColor };
  dark: { [key: string]: PerryColor };
  spacing: { [key: string]: number };
  radius: { [key: string]: number };
  fontSize: { [key: string]: number };
  borderWidth: { [key: string]: number };
}

interface ResolvedTheme {
  colors: { [key: string]: PerryColor };
  spacing: { [key: string]: number };
  radius: { [key: string]: number };
  fontSize: { [key: string]: number };
  borderWidth: { [key: string]: number };
}

Theme Resolution

Resolve a theme at runtime based on the system’s dark mode setting:

import { getTheme } from "perry-styling";
import { theme } from "./theme"; // generated file

const resolved = getTheme(theme);
// resolved.colors.primary → the correct light/dark variant

getTheme() calls isDarkMode() from perry/system and returns the appropriate palette.

Styling Helpers

Ergonomic functions for applying styles to widget handles. Perry’s compiler doesn’t yet support passing PerryColor objects as parameters into user functions, so the helpers take flat primitives: extract the channels at the call site:

import {
  applyBg, applyRadius, applyTextColor, applyFontSize, applyGradient,
} from "perry-styling";

const t = resolved;                    // your ResolvedTheme
const c = t.colors.text;               // a PerryColor
const bg = t.colors.background;
const start = t.colors.primary;
const end = t.colors["primary-dark"];

const label = Text("Hello");
applyTextColor(label, c.r, c.g, c.b, c.a);
applyFontSize(label, t.fontSize.heading);

const card = VStack(16, []);
applyBg(card, bg.r, bg.g, bg.b, bg.a);
applyRadius(card, t.radius.md);
applyGradient(card,
  start.r, start.g, start.b, start.a,
  end.r,   end.g,   end.b,   end.a,
  0,                                   // 0 = vertical, 1 = horizontal
);

Available Helpers

Platform Constants

perry-styling exports compile-time platform constants based on the __platform__ built-in:

import { isMac, isIOS, isAndroid, isWindows, isLinux, isDesktop, isMobile } from "perry-styling";

if (isMobile) {
  applyFontSize(label, 16);
} else {
  applyFontSize(label, 14);
}

These are constant-folded by LLVM at compile time — dead branches are eliminated with zero runtime cost.

Next Steps

• Styling — Widget styling basics
• State Management — Reactive bindings

Camera

The perry/ui module provides a live camera preview widget with color sampling capabilities.

import {
    CameraView,
    cameraStart, cameraStop,
    cameraFreeze, cameraUnfreeze,
    cameraSampleColor, cameraSetOnTap,
} from "perry/ui"

Platform support: real capture is implemented on iOS (AVCaptureSession) and Android (Camera2). On macOS, Linux (GTK4), Windows, and the Web target the runtime exports no-op stubs so cross-platform code compiles and links cleanly — CameraView() returns handle 0 and cameraSampleColor returns -1. Wiring real capture on those platforms (AVFoundation on macOS, GStreamer/V4L2 on Linux, Media Foundation on Windows, getUserMedia on Web) is tracked as a follow-up.

Quick Example

const colorHex = State("#000000")

const cam = CameraView()
cameraStart(cam)

cameraSetOnTap(cam, (x: number, y: number) => {
    const rgb = cameraSampleColor(x, y)
    if (rgb >= 0) {
        const r = Math.floor(rgb / 65536)
        const g = Math.floor((rgb % 65536) / 256)
        const b = Math.floor(rgb % 256)
        colorHex.set(`#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`)
    }
})

App({
    title: "Color Picker",
    width: 400,
    height: 600,
    body: VStack(16, [
        cam,
        Text(`Color: ${colorHex.value}`),
    ]),
})

API Reference

CameraView()

Create a live camera preview widget.

const preview = CameraView()

Returns a widget handle. The camera does not start automatically — call cameraStart() to begin capture.

cameraStart(handle)

Start the live camera feed.

cameraStart(preview)

On iOS, the camera permission dialog is shown automatically on first use.

cameraStop(handle)

Stop the camera feed and release the capture session.

cameraStop(preview)

cameraFreeze(handle)

Pause the live preview (freeze the current frame).

cameraFreeze(preview)

The camera session remains active but the preview stops updating. Useful for “capture” moments where you want to inspect the frozen frame.

cameraUnfreeze(handle)

Resume the live preview after a freeze.

cameraUnfreeze(preview)

cameraSampleColor(x, y)

Sample the pixel color at normalized coordinates.

const rgb = cameraSampleColor(0.5, 0.5) // center of frame

• x, y are normalized coordinates (0.0–1.0)
• Returns packed RGB as a number: r * 65536 + g * 256 + b
• Returns -1 if no frame is available

To extract individual channels:

const r = Math.floor(rgb / 65536)
const g = Math.floor((rgb % 65536) / 256)
const b = Math.floor(rgb % 256)

The color is averaged over a 5x5 pixel region around the sample point for noise reduction.

cameraSetOnTap(handle, callback)

Register a tap handler on the camera view.

cameraSetOnTap(preview, (tx: number, ty: number) => {
    // tx, ty are normalized coordinates (0.0-1.0)
    const tappedRgb = cameraSampleColor(tx, ty)
    console.log(`tapped color: ${tappedRgb}`)
})

The callback receives normalized coordinates of the tap location, which can be passed directly to cameraSampleColor().

Implementation

On iOS, the camera uses AVCaptureSession with AVCaptureVideoPreviewLayer for GPU-accelerated live preview, and AVCaptureVideoDataOutput for frame capture. Color sampling reads pixel data from CVPixelBuffer.

On Android, the camera uses Camera2 with a TextureView preview surface. Color sampling reads from the most recent ImageReader frame.

Next Steps

• Widgets — All available widgets
• Audio Capture — Microphone input and sound metering

WebView

WebView embeds a real browser engine inside the native widget tree — WKWebView on Apple platforms, WebView2 on Windows, WebKitGTK 6.0 on Linux, android.webkit.WebView on Android, and a sandboxed <iframe> on the web target. Use it for OAuth / payment flows, embedded admin pages, help / docs viewers, or any “show this URL as part of my app” surface. (Tracked under issue #658.)

import {
    WebView,
    webviewLoadUrl,
    webviewReload,
    webviewGoBack,
    webviewGoForward,
    webviewCanGoBack,
    webviewEvaluateJs,
    webviewClearCookies,
} from "perry/ui"

Scope. This is a “browser tab embedded in your native widget tree” primitive — explicit non-goals: a Tauri / Electron-style native↔JS RPC bridge, custom protocol / scheme handlers, DevTools, file downloads, WebGL / camera / mic / clipboard permission negotiation, service workers, WebRTC. If you need any of those, reach for Tauri or Electron; the rest of perry/ui still applies.

Basic Usage

const wv = WebView({
    url: "https://example.com",
    width: 800,
    height: 600,
})

App({
    title: "WebView Demo",
    width: 820,
    height: 640,
    body: wv,
})

WebView({...}) returns a Widget you can drop into any layout container. The widget tree’s layout engine controls final size — width and height are hints for the initial bounds.

OAuth / Callback Interception

The load-bearing use case. onShouldNavigate is a synchronous intercept invoked before each navigation; return false to cancel the load. Every backend’s should-load hook is itself sync on the main thread (decidePolicyForNavigationAction, NavigationStarting, shouldOverrideUrlLoading, decide-policy), so the contract is the same everywhere.

const authCode = State("")

const auth = WebView({
    url: "https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=https://myapp.com/oauth/callback&response_type=code&scope=email",
    // Hard host-level allowlist — blocked at the native delegate
    // without round-tripping into TS. Exact match or subdomain match
    // (so "google.com" allows "accounts.google.com").
    allowedDomains: ["accounts.google.com", "google.com", "myapp.com"],
    onShouldNavigate: (url) => {
        if (url.startsWith("https://myapp.com/oauth/callback?")) {
            const code = new URL(url).searchParams.get("code") ?? ""
            authCode.set(code)
            return false  // cancel — we already have what we need
        }
        return true
    },
    onLoaded: (url) => {
        // Fires after every successful page load.
    },
    onError: (code, message) => {
        // DNS / TLS / HTTP / cancellation all flow here.
    },
})

The allowedDomains allowlist is enforced at the native delegate layer — disallowed hosts never reach your onShouldNavigate. Treat it as defense-in-depth against a hijacked OAuth page redirecting the embedded session somewhere unexpected.

Imperative Navigation

Drive the WebView from outside (toolbar buttons, deep links, app-state changes):

// Navigate the WebView from outside (e.g. from a toolbar button).
webviewLoadUrl(wv, "https://perryts.com")
webviewReload(wv)
webviewGoBack(wv)
webviewGoForward(wv)
const hasHistory = webviewCanGoBack(wv)  // 1 or 0

Reading Page State

webviewEvaluateJs(handle, js, callback) runs a one-shot JS expression in the WebView’s content process and delivers the stringified result. Use this for “after the redirect lands, read document.cookie / localStorage.getItem(...)” — not as a general native↔JS RPC channel.

// Read state out of the loaded page after `onLoaded` fires. The
// callback gets the stringified return value (empty string on null /
// undefined / error). Plain string returns are JSON-unwrapped for
// ergonomic `document.cookie` reads.
const reader = WebView({
    url: "https://example.com/auth/callback",
    onLoaded: (_url) => {
        webviewEvaluateJs(reader, "document.cookie", (cookies) => {
            // parseCookies(cookies)
        })
    },
})

The callback receives an empty string on null / undefined / error. Plain string returns are JSON-unwrapped (so document.cookie reads clean, without surrounding quotes).

Cookie Isolation

ephemeral: true is the default — auth flows that silently reuse a user’s logged-in browser session are usually a footgun. Each backend maps this to its native equivalent at construction time:

To opt out:

// Opt out of ephemeral cookies so the user's session survives app
// restarts (like a regular browser profile).
const browser = WebView({
    url: "https://news.ycombinator.com",
    ephemeral: false,
    userAgent: "MyApp/1.0",
})

webviewClearCookies(handle) wipes the data store on demand — useful at logout, or between accounts:

// Wipe the WebView's cookies / localStorage / IndexedDB. Useful at
// logout, or between user accounts in a multi-tenant flow. No-op when
// `ephemeral: true` (the default), since there's nothing persisted to
// clear.
webviewClearCookies(wv)

API

Options

Platform Notes

Cross-Origin Messaging (Web Target)

On the web target, the embedded iframe can window.parent.postMessage out, and the host can window.addEventListener("message", ...) to receive. This is a browser-only pattern — native targets don’t expose postMessage (that’s the Tauri / Electron path Perry’s WebView deliberately avoids).

The portable contract that works on every target:

• Push state in with webviewEvaluateJs(wv, "window.someHook(...)").
• Pull state out by intercepting a known callback URL in onShouldNavigate.

Common Pitfalls

• Don’t reuse one WebView for unrelated sessions. Cookie isolation is per-WebView, not per-call. If you need to log a different user in, call webviewClearCookies(handle) first or destroy and recreate the widget.
• onShouldNavigate runs on the main thread. Keep it cheap — it blocks the navigation until you return. Heavy work belongs in onLoaded or off-thread via spawn.
• WebView2 runtime requirement on older Windows. WebView2 is preinstalled on Windows 10 1803+ and Windows Server 2019+. On older builds the runtime needs to be installed separately (Microsoft ships an evergreen bootstrapper).
• No bidirectional RPC. If you find yourself round-tripping structured data through webviewEvaluateJs callbacks, you’re past the design scope — pick Tauri / Electron instead, or move the logic out of the embedded page.

Next Steps

• Widgets — All available widgets
• State Management — React to onLoaded / onError from the rest of the UI
• Multi-Window — Pop a fresh window with a WebView for isolated sessions

Terminal UI Overview

perry/tui is a native terminal-UI engine built into the Perry runtime. It targets the same use cases as ink (interactive CLIs, dashboards, REPLs, log viewers) but compiles to native code — no Node, no React reconciler, no fiber tree. Your code runs as a single static binary that does a double-buffered ANSI diff each frame.

When to use perry/tui

perry/tui enters the terminal’s alternate screen buffer (so your scrollback isn’t polluted), captures raw-mode keypresses, and re-renders only the cells that changed between frames. The cell grid is a packed Vec<Cell> so an 80×24 terminal fits in ~15 KB — well within L2.

Quick Start

The smallest interactive perry/tui program — a counter that increments on +, decrements on -, and quits on q:

import { Box, Text, useState, useInput, run, exit } from "perry/tui";

run(() => {
    const [n, setN] = useState(0);

    useInput((s: string) => {
        if (s === "+") setN(n + 1);
        if (s === "-") setN(n - 1);
        if (s === "q") exit();
    });

    return Box([Text("count: " + n)]);
});

Compile and run:

perry compile app.ts -o app && ./app

The component closure is called every render. Hooks (useState/useInput/etc.) bind to a per-frame call-site index so the second render’s useState(0) at the same position reads back what the first render wrote — same model as React. The run loop re-renders when any state setter is called and idles between renders.

Mental Model

Perry’s TUI uses the same authoring model as ink:

• Components are functions that return a widget tree. The function is called every render; the tree it returns is diffed against the previous frame’s tree and only changed terminal cells get rewritten.
• State lives in hooks (useState, useRef, useMemo). A change triggers a re-render automatically.
• Layout uses flexbox (powered by Taffy) — flexDirection: "row" | "column", gap, padding, justifyContent, alignItems, flexGrow, etc.

If you’ve used ink, the only real difference at the surface is the factory call form — Box({…opts}, [children]) instead of <Box>…</Box> JSX. JSX works for user-defined component functions today (<App /> calls App(props)), but the <Box> / <Text> intrinsics still need the function-call form until a compile-time JSX→intrinsic rewriter lands.

Architecture in one paragraph

run(component) enters the alt screen, enables raw mode on stdin, spawns a reader thread, and loops: reset hook index → call the component closure → diff the returned widget tree against the front buffer → emit minimal ANSI to reconcile → drain pending keypresses (dispatching to useInput handlers and the focus ring) → if any state changed, immediately re-render; else idle 16 ms. Exit happens when exit() (or useApp().exit()) flips a flag the loop checks at the top of every iteration. On exit, raw mode is restored and the alt screen is left so your terminal returns to exactly the state it was in before the program ran.

What’s next

• Widgets — Box, Text, Input, List, Select, Spinner, ProgressBar, Table, Tabs, and the per-widget style props.
• Hooks — useState, useEffect, useMemo, useRef, useApp, useStdout, useFocus, useInput.
• Examples — counter, chat REPL, file picker, log viewer.

Widgets

perry/tui ships ~10 widgets that cover the typical interactive-CLI surface. All of them are factory functions returning a widget handle — pass them to Box as children, or to render(widget) / run(() => widget) as the root.

Box(opts?, children?)

A flexbox container. Holds any number of children laid out by direction, gap, padding, and alignment rules.

import { Box, Text } from "perry/tui";

// Bare children — vertical column by default.
Box([Text("first"), Text("second")]);

// With style.
Box({ flexDirection: "row", gap: 2, padding: 1 }, [
    Text("left"),
    Text("right"),
]);

Style props

Children can be a literal array ([Text("a"), Text("b")]) or any runtime expression that evaluates to an array — messages.map(m => Text(m)) works the same.

Text(content, style?)

A text node. Single-line; multi-line strings render with \n preserved.

Text("plain");
Text("bold!", { bold: true });
Text("error", { color: "red", bold: true });
Text("subtle", { dimColor: true, italic: true });
Text("removed", { strikethrough: true });
Text("selected", { inverse: true });
Text("custom", { color: "#ff8800", backgroundColor: "#222" });

Style props

Named colors: black, red, green, yellow, blue, magenta, cyan, white, plus their bright* variants. Truecolor (#rrggbb) works on every modern terminal.

Spacer()

A zero-content widget with flexGrow: 1 baked in. Push siblings to the edges of a flex container without spelling out the grow factor:

Box({ flexDirection: "row" }, [
    Text("left"),
    Spacer(),
    Text("right"),
]);

Input(value, cursor?)

A single-line text-input widget. Render a string with an optional inline cursor position (0-indexed); pair with useState for the buffer and useInput to drive it.

const [buf, setBuf] = useState("");
const [cur, setCur] = useState(0);
useInput((s) => { /* … update buf + cur on keypress … */ });
return Input(buf, cur);

perry/tui doesn’t ship a full line editor — it gives you the rendering primitive and you wire the keys yourself. See the chat REPL in Examples for a typical input loop.

TextArea(value)

A multi-line text widget. Same shape as Input but accepts newlines.

List(items, selected?)

A vertically-laid list of strings, with optional highlighted-row index.

List(["Apple", "Banana", "Cherry"], 1);  // "Banana" highlighted

Select(items, selected?)

Like List but with selection indicators (▸ next to the focused row).

const [idx, setIdx] = useState(0);
useInput((s) => {
    if (s === "\x1b[A" /* up */ ) setIdx(Math.max(0, idx - 1));
    if (s === "\x1b[B" /* down */) setIdx(Math.min(items.length - 1, idx + 1));
});
return Select(items, idx);

Spinner(frame)

A static spinner character — - \ | / cycling through frames 0–3. Caller bumps frame from a state counter to animate.

const [tick, setTick] = useState(0);
// On every Enter (or however you want to advance):
setTick(tick + 1);
return Box([Spinner(tick), Text(" working…")]);

Spinner(0) is a static - — useful as a stable bullet if you don’t want animation.

For true wall-clock animation, see AnimatedSpinner({ interval, frames }) which runs its own internal tick (it advances when the render loop polls between frames).

ProgressBar(filled, total, width?)

A simple horizontal bar.

ProgressBar(7, 10);          // ████████░░ at default width
ProgressBar(50, 100, 40);    // 40-cell wide bar

Table({ headers, rows, selected? })

A bordered table. headers is a string array; rows is an array of string arrays.

Table({
    headers: ["Name", "Status", "Latency"],
    rows: [
        ["api-east", "OK", "12ms"],
        ["api-west", "DEGRADED", "412ms"],
    ],
    selected: 1,
});

Tabs({ tabs, active, body })

A horizontal tab bar over a body widget. body is an array parallel to tabs — only the active tab’s body is rendered.

const [active, setActive] = useState(0);
Tabs({
    tabs: ["Files", "Search", "Settings"],
    active,
    body: [filesView, searchView, settingsView],
});

For state + event hooks (the React-shape useState/useInput/useApp/etc.), see Hooks. For complete worked examples, see Examples.

Hooks

perry/tui implements the React-shape hook API on top of a call-site-indexed slot pool. Each useXxx call gets the slot at its position in the component body; the run loop resets the index at the top of every frame, so the second render’s useState at the same position reads back what the first wrote.

This is the same rule-of-hooks model ink/React use: call hooks in the same order on every render. Don’t call them inside if/loops — the slot index would skew and you’d read the wrong slot. Slot kinds are tagged (State / Effect / Memo / Ref / Focus); calling useState at a position previously used by useMemo re-tags the slot rather than corrupting it, but the value resets.

useState(initial)

Per-frame state cell. Returns [value, setter].

const [count, setCount] = useState(0);
// Later, from an input handler:
setCount(count + 1);

The setter writes through to the slot’s bits and flips a global STATE_DIRTY flag — the run loop sees it after useInput drains and immediately re-renders without sleeping.

Setting the same value twice (bit-identical) is a no-op — STATE_DIRTY stays clear and the loop idles. This avoids the “render storm” pattern where unconditional setX(prev) calls would loop forever.

Stale-closure gotcha

The setter captured by a useInput handler reads value from that frame’s closure, not from the slot. If many bytes arrive in one frame (paste, typing fast), the handler fires N times with the same value:

const [n, setN] = useState(0);
useInput((s) => { if (s === "+") setN(n + 1); });
// User pastes "+++" — handler fires 3× with n=0, all three set the slot to 1.

If you need a functional setter for this case, use useRef as a mirror:

const buf = useRef("");
const [, redraw] = useState(0);
useInput((s) => {
    if (s.length === 1 && s >= " " && s <= "~") {
        buf.set(buf.get() + s);     // canonical buffer (no stale capture)
        redraw(buf.get().length);   // trigger re-render
    }
});

useEffect(fn, deps?)

Run a side effect after first render, and again whenever a dep changes.

useEffect(() => {
    // Run-once on mount.
    fetchInitialData();
}, []);

useEffect(() => {
    // Re-run whenever `query` changes.
    runSearch(query);
}, [query]);

useEffect(() => {
    // No deps array → run every render. Rarely what you want.
});

Deps are compared by bit-identity using an FNV-1a hash of the deps’ NaN-boxed values. An empty array [] hashes to a stable non-zero value, giving the React “run once” behaviour; passing no array runs the effect every render.

The effect closure runs synchronously inside the component call. Cleanup-on-dep-change (returning a cleanup function) is not wired yet — the return value is ignored.

useMemo(fn, deps)

Cache the result of fn() keyed by deps. Same hash convention as useEffect.

const sorted = useMemo(
    () => items.slice().sort((a, b) => a.priority - b.priority),
    [items],
);

Recomputes on first call or when deps change. Otherwise returns the cached value.

useRef(initial)

A stable mutable cell that doesn’t trigger re-renders. Use for values you want to mutate but don’t want to drive the UI.

const renderCount = useRef(0);
renderCount.set(renderCount.get() + 1);   // does NOT flip STATE_DIRTY

.get() reads, .set(v) writes. Identity is stable across renders — calling useRef(0) at the same position returns the same handle every time, so closures captured in useEffect / useInput always see the latest value.

Common pattern: use useRef as the canonical buffer for input that gets typed at terminal speed, and pair with a throwaway useState to trigger redraws (see the stale-closure gotcha above).

useApp()

Returns a handle for imperative control of the run loop.

const app = useApp();
// Later:
app.exit();                    // tells run() to break at the top of the next iteration
await app.waitUntilExit();     // blocks until EXIT_FLAG is set (rare; usually `run` itself blocks)

The handle is stable — calling useApp() on every render returns the same singleton. Wrap it in useRef if you want to stash it for a callback that outlives the render.

useStdout()

Terminal dimensions and a raw-write escape hatch.

const stdout = useStdout();
const cols = stdout.columns();    // terminal width in cells (falls back to 80 if not a TTY)
const rows = stdout.rows();       // height in cells (fallback 24)
stdout.write("raw bytes\n");      // bypass the cell-grid diff

Use columns/rows to size dividers, truncate content to fit, or pick a layout direction. write is rarely needed — almost everything should go through widgets so the cell-grid diff can render it efficiently.

useFocus(autoFocus, isActive)

Register the calling widget as a focus candidate. Returns 1.0 when this widget is the currently focused one, else 0.0 (treat as truthy/falsy).

const isFocused = useFocus(1 /* autoFocus */, 1 /* isActive */);
return Box({ flexDirection: "row" }, [
    Text("> ", isFocused ? { color: "cyan", bold: true } : { dimColor: true }),
    Text("name input"),
]);

• autoFocus: pass 1 for one widget to take focus on first render. Subsequent useFocus calls with autoFocus=1 are ignored once focus has been claimed.
• isActive: pass 0 to remove this widget from the Tab cycle (e.g. a disabled field).

Tab and Shift-Tab cycle focus automatically — no boilerplate. The run loop’s input drain handles the \x09 / \x1b[Z byte sequences before forwarding them to your useInput handler.

For imperative focus control, pair with useFocusManager():

const focus = useFocusManager();
// Later:
focus.focusNext();
focus.focusPrevious();
focus.focus(id);   // by focus id (1-based, in registration order)

useInput(handler)

Register a keypress handler. Called once per byte chunk arriving on stdin, in raw mode.

useInput((s: string) => {
    if (s === "\x03") app.exit();               // Ctrl+C
    if (s === "\r" || s === "\n") onSubmit();   // Enter
    if (s === "\x7f" || s === "\b") onErase();  // Backspace
    if (s === "\x1b[A") onUpArrow();            // ANSI up
    if (s.length === 1 && s >= " " && s <= "~") onPrintable(s);
});

The s argument is the raw byte chunk as a string. ANSI escape sequences like arrow keys arrive as a single chunk (\x1b[A, \x1b[B, \x1b[C, \x1b[D); printable characters as one byte; control codes (Ctrl+C, Tab, Enter, Backspace) as their literal byte.

Tab handling: Tab (\x09) and Shift-Tab (\x1b[Z) cycle the focus ring before the handler is called. The handler still sees the byte, so you can branch on it if you want custom Tab behaviour — but for the typical “Tab moves focus” case the framework already did it.

Only one handler is registered at a time (last useInput call wins). For multiple focusable widgets, dispatch from one handler by checking useFocus’s return.

Equivalence with ink

Examples

End-to-end perry/tui programs covering the typical interactive-CLI shapes. Each example also lives in test-files/test_perry_tui_inkcompat_*.ts in the repo and is exercised by CI on every PR.

Counter

The smallest meaningful program: + / - increment/decrement, q quits, the count renders to one row.

import { Box, Text, useState, useInput, run, exit } from "perry/tui";

// Captured so we can print the final count after run() returns.
let finalValue = 0;

run(() => {
    const [n, setN] = useState(0);
    finalValue = n;

    useInput((s: string) => {
        if (s === "+") setN(n + 1);
        if (s === "-") setN(n - 1);
        if (s === "q") exit();
    });

    return Box([Text("count: " + n)]);
});

console.log("FINAL=" + finalValue);

Pipe +++-q and the program prints FINAL=2. The useEffect-less useState(0) initialises the slot on first frame; the handler captures n from the frame it was registered in, so each setter call computes from the value that frame saw.

Chat REPL with stable input buffer

A Claude-Code-shaped chat UI: header row, message history, prompt with cursor, help footer. Demonstrates useState for the message list, useRef as a stale-closure-resistant input buffer, useInput for keypresses, useApp().exit() for Ctrl+C handling.

import {
    Box, Text, Spinner,
    useState, useEffect, useInput, useApp, useStdout, useRef,
    run,
} from "perry/tui";

const CANNED = [
    "Sure, I can help with that.",
    "Read the file, check for null, write a test.",
    "Got it. Anything else?",
];

run(() => {
    const app = useApp();
    const stdout = useStdout();
    const [messages, setMessages] = useState([] as string[]);
    const inputRef = useRef("");
    const [, redraw] = useState(0);
    const [tick, setTick] = useState(0);

    useEffect(() => {
        setMessages([
            "[bot] Hi! Type a message and press Enter. Ctrl+C quits.",
        ]);
    }, []);

    useInput((s: string) => {
        if (s === "\x03") { app.exit(); return; }
        if (s === "\r" || s === "\n") {
            const buf = inputRef.get();
            if (buf.length === 0) return;
            const reply = CANNED[messages.length % CANNED.length];
            setMessages(messages.concat(["[you] " + buf, "[bot] " + reply]));
            inputRef.set("");
            setTick(tick + 1);
            return;
        }
        if (s === "\x7f" || s === "\b") {
            const buf = inputRef.get();
            if (buf.length > 0) {
                inputRef.set(buf.substring(0, buf.length - 1));
                redraw(buf.length - 1);
            }
            return;
        }
        if (s.length === 1) {
            const c = s.charCodeAt(0);
            if (c >= 0x20 && c <= 0x7e) {
                inputRef.set(inputRef.get() + s);
                redraw(c);
            }
        }
    });

    const cols = stdout.columns();
    const rows = messages.map((m: string) => {
        const isUser = m.indexOf("[you]") === 0;
        return Text(m, { color: isUser ? "yellow" : "green" });
    });
    const history = Box({ flexDirection: "column", flexGrow: 1 }, rows);

    let bar = "";
    for (let i = 0; i < cols - 2; i = i + 1) bar = bar + "─";
    const divider = Text(bar, { dimColor: true });

    const promptRow = Box({ flexDirection: "row" }, [
        Spinner(tick),
        Text(" › " + inputRef.get(), { bold: true }),
        Text("█", { color: "cyan" }),
    ]);

    return Box({ flexDirection: "column", padding: 1 }, [
        Text("Perry-Code (demo)", { bold: true, color: "cyan" }),
        history,
        divider,
        promptRow,
        Text("Enter=send · Backspace=erase · Ctrl+C=quit", { dimColor: true }),
    ]);
});

The key insight is inputRef as the canonical buffer: when the user types fast (or pastes), many bytes arrive in one frame; the handler fires N times with the same stale input if it lived in useState. useRef.set() mutates the cell directly, so each byte builds on the previous; the throwaway redraw useState just flips STATE_DIRTY so the loop repaints.

Multi-step prompt with useFocus

A two-field form (name, email) with Tab/Shift-Tab navigation. Demonstrates useFocus with autoFocus + the automatic Tab cycling.

import { Box, Text, useState, useFocus, useInput, run, exit } from "perry/tui";

run(() => {
    const nameFocused = useFocus(1, 1);  // auto-focus first
    const emailFocused = useFocus(0, 1);

    const [name, setName] = useState("");
    const [email, setEmail] = useState("");

    useInput((s: string) => {
        if (s === "\x03") exit();
        // Tab/Shift-Tab handled by the runtime — we don't see them here
        // unless we want to (they DO get dispatched after focus cycles).
        if (s.length === 1 && s >= " " && s <= "~") {
            if (nameFocused) setName(name + s);
            else if (emailFocused) setEmail(email + s);
        }
    });

    return Box({ flexDirection: "column", padding: 1, gap: 1 }, [
        Box({ flexDirection: "row" }, [
            Text(nameFocused ? "▸ " : "  ", { color: "cyan" }),
            Text("Name:  " + name),
        ]),
        Box({ flexDirection: "row" }, [
            Text(emailFocused ? "▸ " : "  ", { color: "cyan" }),
            Text("Email: " + email),
        ]),
        Text("Tab to switch · Ctrl+C to quit", { dimColor: true }),
    ]);
});

Log viewer with useStdout

Sizes content to the terminal width using useStdout().columns(). Truncates each log line to fit; uses useEffect with [] to seed log data on mount.

import { Box, Text, useState, useEffect, useStdout, useInput, run, exit } from "perry/tui";

run(() => {
    const stdout = useStdout();
    const cols = stdout.columns();
    const [lines, setLines] = useState([] as string[]);

    useEffect(() => {
        setLines([
            "2026-05-11 09:01:23 INFO  api-east started",
            "2026-05-11 09:01:24 INFO  api-west started",
            "2026-05-11 09:01:25 WARN  api-east latency degraded (412ms)",
            "2026-05-11 09:01:26 ERROR api-east connection refused",
        ]);
    }, []);

    useInput((s: string) => {
        if (s === "q" || s === "\x03") exit();
    });

    const rows = lines.map((line: string) => {
        const truncated = line.length > cols - 2 ? line.substring(0, cols - 5) + "..." : line;
        const color = line.indexOf("ERROR") >= 0 ? "red"
                    : line.indexOf("WARN") >= 0 ? "yellow"
                    : "white";
        return Text(truncated, { color });
    });

    return Box({ flexDirection: "column", padding: 1 }, rows);
});

Notes on running these locally

perry compile myapp.ts -o myapp
./myapp

The binary enters the alt screen, takes over the terminal until you press Ctrl+C (or whatever exit key the program defines), and restores everything cleanly on exit. Your scrollback is untouched.

For piped (non-interactive) testing — useful for CI assertions — send your test input on stdin and grep stdout for the values your program prints after run() returns:

echo "+++-q" | ./myapp | grep "FINAL="

run() won’t process inputs faster than the loop’s 16 ms idle tick, so very fast piped input can deliver multiple bytes per frame. If your handler captures state via closure, design for that — either compute fresh state on every byte (with useRef) or accept that paste-style input behaves as a single bulk action.

Platform Overview

Perry compiles TypeScript to native executables for 9 platform families from the same source code.

Supported Platforms

Cross-Compilation

# Default: compile for current platform
perry app.ts -o app

# Compile for a specific target
perry app.ts -o app --target ios-simulator
perry app.ts -o app --target visionos-simulator
perry app.ts -o app --target tvos-simulator
perry app.ts -o app --target watchos-simulator
perry app.ts -o app --target web   # alias: --target wasm
perry app.ts -o app --target windows
perry app.ts -o app --target linux
perry app.ts -o app --target android

Platform Detection

Use the __platform__ compile-time constant to branch by platform:

declare const __platform__: number

// Platform constants:
// 0 = macOS
// 1 = iOS
// 2 = Android
// 3 = Windows
// 4 = Linux
// 5 = Web (browser, --target web / --target wasm)
// 6 = tvOS
// 7 = watchOS
// 8 = visionOS

if (__platform__ === 0) {
    console.log("Running on macOS")
} else if (__platform__ === 1) {
    console.log("Running on iOS")
} else if (__platform__ === 3) {
    console.log("Running on Windows")
}

__platform__ is resolved at compile time. The compiler constant-folds comparisons and eliminates dead branches, so platform-specific code has zero runtime cost.

Platform Feature Matrix

Next Steps

• macOS
• iOS
• visionOS
• tvOS
• watchOS
• Android
• Windows
• Linux (GTK4)
• Web
• WebAssembly

macOS

macOS is Perry’s primary development platform. It uses AppKit for native UI.

Requirements

• macOS 13+ (Ventura or later)
• Xcode Command Line Tools: xcode-select --install

Building

# macOS is the default target
perry app.ts -o app
./app

No additional flags needed — macOS is the default compilation target.

UI Toolkit

Perry maps UI widgets to AppKit controls:

Code Signing

For distribution, apps need to be signed. Perry supports automatic signing:

perry publish

This auto-detects your signing identity from the macOS Keychain, exports it to a temporary .p12 file, and signs the binary.

For manual signing:

codesign --sign "Developer ID Application: Your Name" ./app

App Store Distribution

perry app.ts -o MyApp
# Sign with App Store certificate
codesign --sign "3rd Party Mac Developer Application: Your Name" MyApp
# Package
productbuild --sign "3rd Party Mac Developer Installer: Your Name" --component MyApp /Applications MyApp.pkg

macOS-Specific Features

• Menu bar: Full NSMenu support with keyboard shortcuts
• Toolbar: NSToolbar integration
• Dock icon: Automatic for GUI apps
• Dark mode: isDarkMode() detects system appearance
• Keychain: Secure storage via Security.framework
• Notifications: Local notifications via UNUserNotificationCenter
• File dialogs: NSOpenPanel/NSSavePanel

System APIs

import { openURL, isDarkMode, preferencesSet, preferencesGet } from "perry/system"

openURL("https://example.com")          // Opens in default browser
const dark = isDarkMode()               // Check appearance
preferencesSet("key", "value")          // NSUserDefaults
const val = preferencesGet("key")       // NSUserDefaults

Next Steps

• iOS — Cross-compile for iPhone/iPad
• UI Overview — Full UI documentation
• System APIs — System integration

iOS

Perry can cross-compile TypeScript apps for iOS devices and the iOS Simulator.

Requirements

• macOS host (cross-compilation from Linux/Windows is not supported)
• Xcode (full install, not just Command Line Tools) for iOS SDK and Simulator
• Rust iOS targets:

  rustup target add aarch64-apple-ios aarch64-apple-ios-sim
  

Building for Simulator

perry app.ts -o app --target ios-simulator

This uses LLVM cross-compilation with the iOS Simulator SDK. The binary can be run in the Xcode Simulator.

Building for Device

perry app.ts -o app --target ios

This produces an ARM64 binary for physical iOS devices. You’ll need to code sign and package it in an .app bundle for deployment.

Running with perry run

The easiest way to build and run on iOS is perry run:

perry run ios              # Auto-detect device/simulator
perry run ios --console    # Stream live stdout/stderr
perry run ios --remote     # Use Perry Hub build server

Perry auto-discovers available simulators (via simctl) and physical devices (via devicectl). When multiple targets are found, an interactive prompt lets you choose.

For physical devices, Perry handles code signing automatically — it reads your signing identity and team ID from ~/.perry/config.toml (set up via perry setup ios), embeds the provisioning profile, and signs the .app before installing.

If you don’t have the iOS cross-compilation toolchain installed locally, perry run ios automatically falls back to Perry Hub’s remote build server.

UI Toolkit

Perry maps UI widgets to UIKit controls:

App Lifecycle

iOS apps use UIApplicationMain with a deferred creation pattern:

import { App, Text, VStack } from "perry/ui"

App({
    title: "My iOS App",
    width: 400,
    height: 800,
    body: VStack(16, [
        Text("Hello, iPhone!"),
    ]),
})

The App() call triggers UIApplicationMain, and your render function is called via PerryAppDelegate once the app is ready.

iOS Widgets (WidgetKit)

Perry can compile TypeScript widget declarations to native SwiftUI WidgetKit extensions:

perry widget.ts --target ios-widget

See Widgets (WidgetKit) for details.

Splash Screen

Perry auto-generates a native LaunchScreen.storyboard from the perry.splash config in package.json. The splash screen appears instantly during cold start.

{
  "perry": {
    "splash": {
      "image": "logo/icon-256.png",
      "background": "#FFF5EE"
    }
  }
}

The image is centered at 128x128pt with scaleAspectFit. You can provide a custom storyboard for full control:

{
  "perry": {
    "splash": {
      "ios": { "storyboard": "splash/LaunchScreen.storyboard" }
    }
  }
}

See Project Configuration for the full config reference.

Resource Bundling

Perry automatically bundles logo/ and assets/ directories from your project root into the .app bundle. These resources are available at runtime via standard file APIs relative to the app bundle path.

Keyboard Avoidance

Perry apps automatically handle keyboard avoidance on iOS. When the keyboard appears, the root view adjusts its bottom constraint with an animated layout transition, and focused TextFields are auto-scrolled into view above the keyboard.

Differences from macOS

• No menu bar: iOS doesn’t support menu bars. Use toolbar or navigation patterns.
• Touch events: onHover is not available. Use onClick (mapped to touch).
• Slider precision: iOS UISlider uses Float32 internally (automatically converted).
• File dialogs: Limited to UIDocumentPicker.
• Keyboard shortcuts: Not applicable on iOS.

Next Steps

• Widgets (WidgetKit) — iOS home screen widgets
• Platform Overview — All platforms
• UI Overview — UI system

visionOS

Perry can compile TypeScript apps for Apple Vision Pro devices and the visionOS Simulator.

This first pass targets 2D windowed apps only. Perry uses the same UIKit-style perry/ui model as iOS, packaged for visionOS app bundles and scene lifecycle.

Prerequisites

• macOS with Xcode installed
• Rust visionOS targets:

rustup target add aarch64-apple-visionos aarch64-apple-visionos-sim

Compile

perry compile app.ts -o app --target visionos-simulator
perry compile app.ts -o app --target visionos

This produces a .app bundle with visionOS-specific Info.plist metadata and a UIWindowScene configuration.

Run

perry run visionos
perry run visionos --simulator <UDID>
perry run visionos --device <UDID>

Perry auto-detects booted Apple Vision Pro simulators via simctl. Physical device installs use devicectl, like other modern Apple platforms.

Configuration

Configure visionOS-specific settings in perry.toml:

[visionos]
bundle_id = "com.example.myvisionapp"
deployment_target = "1.0"
entry = "src/main_visionos.ts"
encryption_exempt = true

Custom Info.plist keys can be merged through [visionos.info_plist].

Platform Detection

Use __platform__ === 8 to detect visionOS at compile time:

function reportVisionos(): void {
    if (__platform__ === 8) {
        console.log("Running on visionOS")
    }
}

Current Scope

• Supported: 2D windowed apps, simulator/device app bundles, perry run, perry setup, perry publish
• Not supported yet: immersive spaces, volumes, RealityKit scene generation, Geisterhand

Related

• iOS — shared UIKit foundation
• Platform Overview

tvOS

Perry can compile TypeScript apps for Apple TV devices and the tvOS Simulator.

tvOS uses UIKit (the same framework as iOS), so Perry’s tvOS support shares the same UIKit-based widget system. The primary difference is input: Apple TV apps are controlled via the Siri Remote and game controllers rather than touch, and all apps run full-screen.

Requirements

• macOS host (cross-compilation from Linux/Windows is not supported)
• Xcode (full install) for tvOS SDK and Simulator
• Rust tvOS targets:

  rustup target add aarch64-apple-tvos aarch64-apple-tvos-sim
  

Building for Simulator

perry compile app.ts -o app --target tvos-simulator

This produces an ARM64 binary linked with clang against the tvOS Simulator SDK, wrapped in a .app bundle.

Building for Device

perry compile app.ts -o app --target tvos

This produces an ARM64 binary for physical Apple TV hardware.

Running with perry run

perry run tvos                        # Auto-detect booted Apple TV simulator
perry run tvos --simulator <UDID>     # Target a specific simulator

Perry auto-discovers booted Apple TV simulators. To install and launch manually:

xcrun simctl install booted app.app
xcrun simctl launch booted com.perry.app

UI Toolkit

Perry maps UI widgets to UIKit controls on tvOS, identical to iOS:

Focus Engine

tvOS uses a focus-based navigation model instead of direct touch. The Siri Remote’s touchpad and directional buttons move focus between focusable views. Perry widgets that support interaction (buttons, text fields, toggles, etc.) are automatically focusable.

Game Engine Support

tvOS is particularly well-suited for game engines. When using a native library like Bloom, the game engine handles its own windowing, rendering, and input.

Status: illustrative only — Bloom is an external native library (see bloomengine.dev). The snippet below is left as ,no-test because it depends on Bloom’s .a/.so being available at link time; the doc-tests harness compiles every other snippet on this page.

import { initWindow, windowShouldClose, beginDrawing, endDrawing,
         clearBackground, isGamepadButtonDown, Colors } from "bloom";

initWindow(1920, 1080, "My Apple TV Game");

while (!windowShouldClose()) {
  beginDrawing();
  clearBackground(Colors.BLACK);

  if (isGamepadButtonDown(0)) {
    // A button (Siri Remote select) pressed
  }

  endDrawing();
}

Input on tvOS

The Siri Remote acts as a game controller:

Extended game controllers (MFi, PlayStation, Xbox) are fully supported with all axes, buttons, triggers, and D-pad mapped through the standard gamepad API.

App Lifecycle

tvOS apps use UIApplicationMain with the same lifecycle as iOS. When using perry/ui:

import { App, Text, VStack } from "perry/ui"

App({
    title: "My TV App",
    width: 1920,
    height: 1080,
    body: VStack(16, [
        Text("Hello, Apple TV!"),
    ]),
})

When using a game engine with --features ios-game-loop, the runtime starts UIApplicationMain on the main thread and runs your game code on a dedicated game thread.

Configuration

Configure tvOS settings in perry.toml:

[tvos]
bundle_id = "com.example.mytvapp"
deployment_target = "17.0"

Platform Detection

Use __platform__ === 6 to detect tvOS at compile time:

function reportTvos(): void {
    if (__platform__ === 6) {
        console.log("Running on tvOS")
    }
}

App Bundle

Perry generates a .app bundle with an Info.plist containing:

Limitations

tvOS has inherent platform constraints compared to other Perry targets:

• No camera: Apple TV has no camera hardware
• No clipboard: UIPasteboard is not available on tvOS
• No file dialogs: No document picker
• No QR code: No camera for scanning
• No multi-window: Single full-screen window only
• No direct touch: Input is via Siri Remote focus engine and game controllers
• Resolution: Design for 1920x1080 (1080p) or 3840x2160 (4K) displays

Differences from iOS

Next Steps

• iOS — iOS platform reference (shared UIKit base)
• watchOS — watchOS platform reference
• Platform Overview — All platforms

watchOS

Perry can compile TypeScript apps for Apple Watch devices and the watchOS Simulator.

Since watchOS does not support UIKit views, Perry uses a data-driven SwiftUI renderer: your TypeScript code builds a UI tree via the standard perry/ui API, and a fixed SwiftUI runtime (shipped with Perry) queries the tree and renders it reactively. No code generation or transpilation is involved — the binary is fully native.

Requirements

• macOS host (cross-compilation from Linux/Windows is not supported)
• Xcode (full install) for watchOS SDK and Simulator
• Rust watchOS targets:

  rustup target add arm64_32-apple-watchos aarch64-apple-watchos-sim
  

Building for Simulator

perry compile app.ts -o app --target watchos-simulator

This produces an ARM64 binary linked with swiftc against the watchOS Simulator SDK, wrapped in a .app bundle.

Building for Device

perry compile app.ts -o app --target watchos

This produces an arm64_32 (ILP32) binary for physical Apple Watch hardware. Apple Watch uses 32-bit pointers on 64-bit ARM.

Running with perry run

perry run watchos                # Auto-detect booted watch simulator
perry run watchos --simulator <UDID>  # Target a specific simulator

Perry auto-discovers booted Apple Watch simulators. To install and launch manually:

xcrun simctl install booted app_watchos/app.app
xcrun simctl launch booted com.perry.app

UI Toolkit

Perry maps UI widgets to SwiftUI views via a data-driven bridge:

Modifiers

All widgets support these styling modifiers:

• foregroundColor / backgroundColor
• font (size, weight, family)
• frame (width, height)
• padding (uniform or per-edge)
• cornerRadius
• opacity
• hidden / disabled