@swipt/api 0.0.0-stage → 0.1.0-nightly.0

package/LICENSE

@@ -0,0 +1,17 @@
+Copyright (C) 2026 by nekohasekai <contact-sagernet@sekai.icu>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+In addition, no derivative work may use the name or imply association
+with this application without prior consent.

package/accessibility.d.ts

@@ -0,0 +1,83 @@
+import type { CallOptions, Point, Rect } from "./index";
+import type { TapOptions } from "./input";
+
+export type AccessibilityTrait = "button" | "link" | "image" | "playsSound" | "keyboardKey" | "staticText" | "summaryElement"
+  | "updatesFrequently" | "searchField" | "startsMediaSession" | "adjustable" | "allowsDirectInteraction"
+  | "causesPageTurn" | "tabBar" | "header" | "webContent" | "textEntry";
+
+export type AccessibilityAction = "press" | "increment" | "decrement" | "escape" | "menu"
+  | "scrollUp" | "scrollDown" | "scrollLeft" | "scrollRight" | "scrollToVisible";
+
+export interface AccessibilityElement {
+  readonly role: string;
+  readonly class?: string;
+  readonly traits: readonly AccessibilityTrait[];
+  readonly label?: string;
+  readonly value?: string;
+  readonly identifier?: string;
+  readonly placeholder?: string;
+  readonly hint?: string;
+  readonly url?: string;
+  readonly frame?: Rect;
+  readonly point?: Point;
+  readonly partial?: true;
+  readonly offScreen?: true;
+  readonly inert?: true;
+  readonly remote?: true;
+  readonly disabled?: true;
+  readonly focused?: true;
+  readonly selected?: true;
+  readonly expanded?: boolean;
+  readonly secure?: true;
+  readonly selection?: [location: number, length: number];
+  readonly actions?: readonly string[];
+  readonly children: readonly AccessibilityElement[];
+  readonly parent?: AccessibilityElement;
+  find(selector: AccessibilitySelector): AccessibilityElement | null;
+  findAll(selector: AccessibilitySelector): AccessibilityElement[];
+}
+
+export interface AccessibilitySnapshot {
+  readonly app: string;
+  readonly time: number;
+  readonly root: AccessibilityElement;
+  readonly system?: AccessibilityElement;
+  find(selector: AccessibilitySelector): AccessibilityElement | null;
+  findAll(selector: AccessibilitySelector): AccessibilityElement[];
+}
+
+type TextField = "role" | "class" | "label" | "value" | "identifier" | "placeholder" | "hint" | "url" | "app";
+type Flag = "disabled" | "focused" | "selected" | "expanded" | "secure" | "partial" | "offScreen" | "inert" | "remote";
+
+export type AccessibilityQuery = { traits?: AccessibilityTrait[]; within?: AccessibilityQuery; parent?: AccessibilityQuery; has?: AccessibilityQuery; not?: AccessibilityQuery; index?: number }
+  & { [field in TextField]?: string | RegExp }
+  & { [field in Flag]?: boolean };
+
+export type AccessibilitySelector =
+  | ({ traits?: AccessibilityTrait[]; within?: AccessibilitySelector | AccessibilityElement; parent?: AccessibilitySelector | AccessibilityElement; has?: AccessibilitySelector | AccessibilityElement; not?: AccessibilitySelector | AccessibilityElement; index?: number }
+    & { [field in TextField]?: string | RegExp }
+    & { [field in Flag]?: boolean })
+  | ((element: AccessibilityElement) => boolean);
+
+export interface SnapshotOptions extends CallOptions {
+  readonly scope?: "screen" | "frontApp";
+  readonly full?: boolean;
+}
+
+export interface LocatorOptions extends CallOptions {
+  /** 10000 when omitted; Infinity waits without a limit. */
+  readonly timeoutMs?: number;
+}
+
+export interface AccessibilityLocator {
+  tap(options?: LocatorOptions & TapOptions): Promise<void>;
+  /** Taps each element as it comes to match, once while it stays matched, and resolves when the app in front at the call leaves the front, at once if the query names only other apps. */
+  tapEach(options?: TapOptions): Promise<void>;
+  setText(text: string, options?: LocatorOptions): Promise<void>;
+  perform(action: AccessibilityAction | (string & {}), options?: LocatorOptions): Promise<void>;
+}
+
+export declare function locator(query: AccessibilityQuery | readonly AccessibilityQuery[]): AccessibilityLocator;
+export declare function snapshot(options?: SnapshotOptions): Promise<AccessibilitySnapshot>;
+export declare function find(selector: AccessibilitySelector, options?: CallOptions): Promise<AccessibilityElement | null>;
+export declare function tap(element: AccessibilityElement, options?: TapOptions): Promise<void>;

package/accessibility.mjs

@@ -0,0 +1,8 @@
+const outside = () => {
+  throw new Error("@swipt/api/accessibility runs inside Swipt; build the swiplet with `swiplet build`");
+};
+
+export const locator = outside;
+export const snapshot = outside;
+export const find = outside;
+export const tap = outside;

package/cli.mjs

@@ -0,0 +1,441 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import vm from "node:vm";
+
+import { build } from "esbuild";
+
+const { version, peerDependencies } = JSON.parse(fs.readFileSync(new URL("package.json", import.meta.url), "utf8"));
+
+const appModules = [
+  "react",
+  "react/jsx-runtime",
+  "react-native",
+  "expo",
+  "expo-localization",
+  "@expo/ui",
+  "@expo/ui/*",
+  "@swipt/api",
+  "@swipt/api/swiplet",
+  "@swipt/api/file-system",
+];
+const extensionModules = [
+  "@swipt/api",
+  "@swipt/api/swiplet",
+  "@swipt/api/file-system",
+  "@swipt/api/accessibility",
+  "@swipt/api/input",
+  "@swipt/api/device",
+  "@swipt/api/screen",
+  "@swipt/api/image",
+  "expo-localization",
+];
+
+const idPattern = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+
+const storedSuffixes = [".webp", ".jxl", ".avif", ".heic", ".heif", ".jpg", ".jpeg", ".png", ".gif", ".mp4", ".mov", ".m4a", ".mp3", ".aac", ".zip", ".gz", ".br", ".zst", ".xz"].join(":");
+
+function loadProject(root) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  const config = manifest.swiplet ?? {};
+  if (typeof config.id !== "string" || !idPattern.test(config.id)) {
+    throw new Error('"swiplet.id" in package.json must be 1 to 128 lowercase letters, digits, dots, underscores and hyphens starting with a letter or a digit');
+  }
+  if (typeof config.name !== "string" || config.name === "") {
+    throw new Error('"swiplet.name" in package.json must be a non-empty string');
+  }
+  const localizedNames = config.localizedNames ?? {};
+  if (localizedNames === null || typeof localizedNames !== "object" || !Object.values(localizedNames).every(name => typeof name === "string")) {
+    throw new Error('"swiplet.localizedNames" in package.json must map languages to names');
+  }
+  for (const field of ["description", "updateURL"]) {
+    if (config[field] !== undefined && typeof config[field] !== "string") {
+      throw new Error(`"swiplet.${field}" in package.json must be a string`);
+    }
+  }
+  if (config.versionCode !== undefined && (!Number.isInteger(config.versionCode) || config.versionCode < 1)) {
+    throw new Error('"swiplet.versionCode" in package.json must be a positive integer');
+  }
+  const entry = name => (config[name] === undefined ? undefined : path.resolve(root, config[name]));
+  return { root, manifest, config, localizedNames, app: entry("app"), extension: entry("extension") };
+}
+
+const typeImport = extension => ({
+  name: "swiplet-type-import",
+  setup(build) {
+    build.onLoad({ filter: /.*/ }, args => {
+      if (args.path !== extension) {
+        return undefined;
+      }
+      return { errors: [{ text: `the interface imports ${path.basename(extension)} at run time; import its type with \`import type\`` }] };
+    });
+  },
+});
+
+async function bundle(project) {
+  const out = { app: "", extension: "", extensionMap: "" };
+  if (project.extension) {
+    const result = await build({
+      entryPoints: [project.extension],
+      outfile: path.join(project.root, "dist", project.config.id, "src", "extension.js"),
+      bundle: true,
+      format: "cjs",
+      platform: "neutral",
+      mainFields: ["module", "main"],
+      target: "es2022",
+      external: extensionModules,
+      sourcemap: "external",
+      sourcesContent: false,
+      write: false,
+      logLevel: "silent",
+    });
+    out.extension = result.outputFiles.find(file => file.path.endsWith(".js")).text;
+    out.extensionMap = result.outputFiles.find(file => file.path.endsWith(".map")).text;
+  }
+  if (project.app) {
+    const result = await build({
+      entryPoints: [project.app],
+      bundle: true,
+      format: "cjs",
+      platform: "neutral",
+      mainFields: ["react-native", "browser", "module", "main"],
+      conditions: ["react-native"],
+      resolveExtensions: [".ios.tsx", ".ios.ts", ".native.tsx", ".native.ts", ".tsx", ".ts", ".ios.jsx", ".ios.js", ".native.js", ".jsx", ".js", ".json"],
+      jsx: "automatic",
+      target: "es2020",
+      define: { "process.env.NODE_ENV": '"production"', __DEV__: "false" },
+      external: appModules,
+      write: false,
+      logLevel: "silent",
+      plugins: project.extension ? [typeImport(project.extension)] : [],
+    });
+    out.app = result.outputFiles[0].text;
+  }
+  if (out.app === "" && out.extension === "") {
+    throw new Error('package.json names neither "swiplet.app" nor "swiplet.extension"');
+  }
+  return out;
+}
+
+const definitionKey = Symbol("definition");
+
+function describeExtension(source) {
+  if (source === "") {
+    return { service: false, actions: [] };
+  }
+  const loading = name => {
+    const fail = () => {
+      throw new Error(`${name} is used while extension.js loads; use it inside run or an action`);
+    };
+    const get = (_, key) => (key === "__esModule" ? true : typeof key === "symbol" || key === "then" ? undefined : fail());
+    return new Proxy(fail, { get, apply: fail, construct: fail });
+  };
+  const modules = {
+    "@swipt/api": {},
+    "@swipt/api/swiplet": {
+      defineExtension: definition => ({ [definitionKey]: definition }),
+      defineAction: definition => definition,
+      actions: loading("actions"),
+      useService: loading("useService"),
+    },
+    "@swipt/api/file-system": {
+      get dataDirectory() {
+        throw new Error("dataDirectory is used while extension.js loads; use it inside run or an action");
+      },
+      get assets() {
+        throw new Error("assets is used while extension.js loads; use it inside run or an action");
+      },
+    },
+    "@swipt/api/accessibility": loading("accessibility"),
+    "@swipt/api/input": loading("input"),
+    "@swipt/api/device": loading("device"),
+    "@swipt/api/screen": loading("screen"),
+    "@swipt/api/image": loading("image"),
+    "expo-localization": { getLocales: () => [{ languageTag: "en", languageCode: "en" }], getCalendars: () => [] },
+  };
+  const ignored = () => 0;
+  const context = vm.createContext({
+    console, URL, URLSearchParams, TextEncoder, TextDecoder, atob, btoa, structuredClone, queueMicrotask, crypto,
+    AbortController, AbortSignal, Event, EventTarget, CustomEvent, DOMException, Headers, Request, Response, Blob,
+    fetch: loading("fetch"),
+    setTimeout: ignored, setInterval: ignored, clearTimeout: ignored, clearInterval: ignored,
+    navigator: { userAgent: "Swipt", language: "en", languages: ["en"] },
+  });
+  const factory = vm.runInContext(`(function (require, module, exports) {${source}\n})`, context, { filename: "extension.js" });
+  const module = { exports: {} };
+  factory(
+    specifier => {
+      if (!Object.hasOwn(modules, specifier)) {
+        throw new Error(`Swipt doesn't provide "${specifier}" to extensions; bundle it into extension.js`);
+      }
+      return modules[specifier];
+    },
+    module,
+    module.exports,
+  );
+  const definition = (module.exports.default ?? module.exports)?.[definitionKey];
+  if (definition === undefined) {
+    throw new Error("the extension's default export is not the result of defineExtension");
+  }
+  const schema = (name, value, side) => {
+    if (value === undefined) {
+      return undefined;
+    }
+    const converter = value?.["~standard"]?.jsonSchema;
+    if (typeof converter?.[side] !== "function") {
+      throw new Error(`the ${side} schema of the action ${JSON.stringify(name)} doesn't implement Standard JSON Schema; use a library that does, such as Zod 4`);
+    }
+    return converter[side]({ target: "draft-2020-12" });
+  };
+  const actions = Object.entries(definition.actions ?? {}).map(([name, action]) => {
+    if (typeof action?.title !== "string" || action.title === "") {
+      throw new Error(`the action ${JSON.stringify(name)} needs a title`);
+    }
+    const expose = action.expose ?? [];
+    if (!Array.isArray(expose) || !expose.every(caller => caller === "shortcuts")) {
+      throw new Error(`the action ${JSON.stringify(name)} can only expose itself to "shortcuts"`);
+    }
+    return {
+      name,
+      title: action.title,
+      ...(action.description ? { description: action.description } : {}),
+      ...(expose.length > 0 ? { expose } : {}),
+      ...(action.input ? { input: schema(name, action.input, "input") } : {}),
+      ...(action.output ? { output: schema(name, action.output, "output") } : {}),
+    };
+  });
+  return { service: typeof definition.run === "function", actions };
+}
+
+function swipletManifest(project, output) {
+  const { service, actions } = describeExtension(output.extension);
+  const { config, localizedNames } = project;
+  return {
+    id: config.id,
+    name: config.name,
+    ...(Object.keys(localizedNames).length > 0 ? { localizedNames } : {}),
+    ...(config.description ? { description: config.description } : {}),
+    ...(project.manifest.version ? { version: project.manifest.version } : {}),
+    ...(config.versionCode ? { versionCode: config.versionCode } : {}),
+    ...(config.icon ? { icon: config.icon } : {}),
+    ...(config.updateURL ? { updateURL: config.updateURL } : {}),
+    ...(output.app ? { interface: true } : {}),
+    ...(service ? { service } : {}),
+    ...(actions.length > 0 ? { actions } : {}),
+  };
+}
+
+const sourceFiles = output => ({
+  ...(output.app ? { "app.js": output.app } : {}),
+  ...(output.extension ? { "extension.js": output.extension } : {}),
+});
+
+async function buildCommand(root) {
+  const project = loadProject(root);
+  const output = await bundle(project);
+  const manifest = swipletManifest(project, output);
+  const dist = path.join(root, "dist");
+  const folder = path.join(dist, manifest.id);
+  fs.rmSync(folder, { recursive: true, force: true });
+  fs.mkdirSync(path.join(folder, "src"), { recursive: true });
+  fs.writeFileSync(path.join(folder, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  for (const [file, contents] of Object.entries(sourceFiles(output))) {
+    fs.writeFileSync(path.join(folder, "src", file), contents);
+  }
+  if (output.extensionMap) {
+    fs.writeFileSync(path.join(folder, "src", "extension.js.map"), output.extensionMap);
+  }
+  if (fs.existsSync(path.join(root, "icon.png"))) {
+    fs.copyFileSync(path.join(root, "icon.png"), path.join(folder, "icon.png"));
+  }
+  if (fs.existsSync(path.join(root, "assets"))) {
+    fs.cpSync(path.join(root, "assets"), path.join(folder, "assets"), { recursive: true, filter: source => !path.basename(source).startsWith(".") });
+  }
+  const archive = path.join(dist, `${manifest.id}.swiplet`);
+  fs.rmSync(archive, { force: true });
+  fs.rmSync(path.join(dist, `${manifest.id}.zip`), { force: true });
+  execFileSync("zip", ["-qr", "-n", storedSuffixes, archive, manifest.id, "-x", "*.map"], { cwd: dist });
+  console.log(path.relative(process.cwd(), archive));
+}
+
+const manifestEntry = /^(?:[^/]+\/)?manifest\.json$/;
+
+function sourceCommand(files, base, output) {
+  if (!base) {
+    throw new UsageError("source needs --url, the address the swiplets are published under");
+  }
+  let prefix;
+  try {
+    prefix = new URL(base.endsWith("/") ? base : `${base}/`);
+  } catch {
+    throw new UsageError(`--url ${JSON.stringify(base)} is not an absolute URL`);
+  }
+  const swiplets = new Map();
+  for (const file of files) {
+    const entry = execFileSync("unzip", ["-Z1", file], { encoding: "utf8" }).split("\n").filter(name => manifestEntry.test(name)).sort((a, b) => a.length - b.length)[0];
+    if (entry === undefined) {
+      throw new Error(`${file} has no manifest.json`);
+    }
+    const manifest = JSON.parse(execFileSync("unzip", ["-p", file, entry], { encoding: "utf8" }));
+    if (typeof manifest.id !== "string" || !idPattern.test(manifest.id)) {
+      throw new Error(`${file} has no valid swiplet id in its manifest`);
+    }
+    if (swiplets.has(manifest.id)) {
+      throw new Error(`${manifest.id} is both ${swiplets.get(manifest.id).file} and ${file}`);
+    }
+    const data = fs.readFileSync(file);
+    swiplets.set(manifest.id, {
+      file,
+      entry: { ...manifest, url: new URL(path.basename(file), prefix).href, size: data.length, sha256: createHash("sha256").update(data).digest("hex") },
+    });
+  }
+  const listed = `${JSON.stringify({ swiplets: [...swiplets.keys()].sort().map(id => swiplets.get(id).entry) }, null, 2)}\n`;
+  if (output) {
+    fs.writeFileSync(output, listed);
+  } else {
+    process.stdout.write(listed);
+  }
+}
+
+const idOf = name => name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+/, "").slice(0, 128).replace(/[._-]+$/, "") || "swiplet";
+
+const templates = {
+  "package.json": name =>
+    `${JSON.stringify(
+      {
+        name: idOf(name),
+        version: "0.1.0",
+        private: true,
+        swiplet: {
+          id: idOf(name),
+          name,
+          versionCode: 1,
+          icon: { color: "blue", symbol: "sparkles" },
+          app: "./src/App.tsx",
+          extension: "./src/extension.ts",
+        },
+        scripts: { build: "swiplet build", check: "tsc" },
+        dependencies: { zod: "^4.6.7" },
+        devDependencies: {
+          "@swipt/api": version,
+          typescript: "^7.0.2",
+          ...Object.fromEntries(["@expo/ui", "@types/react", "react"].map(name => [name, peerDependencies[name]])),
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  "tsconfig.json": () =>
+    `${JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022", module: "ESNext", moduleResolution: "Bundler", jsx: "react-jsx", lib: ["ES2023", "DOM"],
+          strict: true, noEmit: true, skipLibCheck: true,
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  ".gitignore": () => "node_modules/\ndist/\n",
+  "src/extension.ts": () => `import * as device from "@swipt/api/device";
+import { defineAction, defineExtension } from "@swipt/api/swiplet";
+
+export default defineExtension({
+  actions: {
+    frontApp: defineAction({
+      title: "Find the App in Front",
+      run: (_, { signal }) => device.foregroundApplication.get({ signal }),
+    }),
+  },
+});
+`,
+  "src/App.tsx": () => `import { Button, Form, Host, Section, Text } from "@expo/ui/swift-ui";
+import { useState } from "react";
+import { actions } from "@swipt/api/swiplet";
+
+import type extension from "./extension";
+
+const { frontApp } = actions<typeof extension>();
+
+export default function App() {
+  const [app, setApp] = useState("");
+  return (
+    <Host style={{ flex: 1 }}>
+      <Form>
+        <Section>
+          <Button label="Find the App in Front" onPress={async () => setApp(await frontApp())} />
+          {app === "" ? null : <Text>{app}</Text>}
+        </Section>
+      </Form>
+    </Host>
+  );
+}
+`,
+};
+
+const quote = value => (/^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`);
+
+function createCommand(directory) {
+  const root = path.resolve(directory);
+  if (fs.existsSync(root) && fs.readdirSync(root).length > 0) {
+    throw new Error(`${directory} is not empty`);
+  }
+  for (const [file, template] of Object.entries(templates)) {
+    fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
+    fs.writeFileSync(path.join(root, file), template(path.basename(root)));
+  }
+  const manager = process.env.npm_config_user_agent?.split("/")[0] ?? "npm";
+  console.log(`cd ${quote(directory)} && ${manager} install && ${manager} run build`);
+}
+
+const usage = `usage: swiplet create <directory>
+       swiplet build
+       swiplet source --url <address> [--output <file>] <swiplet>...
+
+  create   make a swiplet project in a new or empty directory
+  build    bundle the project in this directory into dist/<swiplet.id>.swiplet
+  source   list built swiplets in a source that Swipt installs and updates from
+
+Type-check a project with its "check" script.`;
+
+const commands = { create: 1, build: 0, source: -1 };
+
+class UsageError extends Error {}
+
+try {
+  let parsed;
+  try {
+    parsed = parseArgs({ allowPositionals: true, options: { help: { type: "boolean", short: "h" }, url: { type: "string" }, output: { type: "string" } } });
+  } catch (error) {
+    throw new UsageError(error.message);
+  }
+  const [command, ...rest] = parsed.positionals;
+  if (parsed.values.help) {
+    console.log(usage);
+  } else if (command === undefined) {
+    throw new UsageError("a command is missing");
+  } else if (!Object.hasOwn(commands, command)) {
+    throw new UsageError(`unknown command ${JSON.stringify(command)}`);
+  } else if (commands[command] < 0 ? rest.length === 0 : rest.length !== commands[command]) {
+    throw new UsageError(
+      commands[command] === 0 ? `${command} takes no arguments` : commands[command] < 0 ? `${command} takes one or more swiplets` : `${command} takes one directory`,
+    );
+  } else if (command === "create") {
+    createCommand(rest[0]);
+  } else if (command === "source") {
+    sourceCommand(rest, parsed.values.url, parsed.values.output);
+  } else {
+    await buildCommand(process.cwd());
+  }
+} catch (error) {
+  if (error instanceof UsageError) {
+    console.error(`error: ${error.message}\n\n${usage}`);
+    process.exitCode = 2;
+  } else {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/device.d.ts

@@ -0,0 +1,49 @@
+import type { CallOptions, ObservableState } from "./index";
+import type { FileHandle } from "./file-system";
+
+export type DisplayState = "off" | "dimmed" | "inactiveOn" | "activeOn";
+
+export interface DeviceInfo {
+  readonly name: string;
+  readonly model: string;
+  readonly os: string;
+  readonly build: string;
+  readonly language: string;
+  readonly screen: {
+    readonly width: number;
+    readonly height: number;
+    readonly scale: number;
+    readonly orientation: "portrait" | "portraitUpsideDown" | "landscape";
+  };
+}
+
+export interface InstalledApplication {
+  readonly bundleId: string;
+  readonly name: string;
+  readonly version?: string;
+  readonly build?: string;
+}
+
+export interface ApplicationStateEvent {
+  readonly type: "launch" | "foreground" | "background";
+  readonly bundleId: string;
+  readonly pid: number;
+  readonly time: number;
+}
+
+export declare function info(options?: CallOptions): Promise<DeviceInfo>;
+export declare const foregroundApplication: ObservableState<string>;
+export declare const locked: ObservableState<boolean>;
+export declare const displayState: ObservableState<DisplayState>;
+export declare function unlock(options?: CallOptions): Promise<void>;
+
+export declare function applicationEvents(options?: CallOptions): AsyncIterable<ApplicationStateEvent>;
+export declare function installedApplications(options?: CallOptions): Promise<InstalledApplication[]>;
+export declare function applicationIcon(bundleId: string, options?: CallOptions): Promise<FileHandle>;
+export declare function launchApplication(bundleId: string, options?: CallOptions & { url?: string; restart?: boolean }): Promise<void>;
+
+export declare function pasteboard(options?: CallOptions): Promise<string | null>;
+export declare function setPasteboard(text: string | null, options?: CallOptions): Promise<void>;
+
+export declare function simulateLocation(latitude: number, longitude: number, options?: CallOptions): Promise<void>;
+export declare function clearSimulatedLocation(options?: CallOptions): Promise<void>;

package/device.mjs

@@ -0,0 +1,17 @@
+const outside = () => {
+  throw new Error("@swipt/api/device runs inside Swipt; build the swiplet with `swiplet build`");
+};
+
+export const info = outside;
+export const foregroundApplication = undefined;
+export const locked = undefined;
+export const displayState = undefined;
+export const unlock = outside;
+export const applicationEvents = outside;
+export const installedApplications = outside;
+export const applicationIcon = outside;
+export const launchApplication = outside;
+export const pasteboard = outside;
+export const setPasteboard = outside;
+export const simulateLocation = outside;
+export const clearSimulatedLocation = outside;

package/file-system.d.ts

@@ -0,0 +1,30 @@
+export declare const dataDirectory: DirectoryHandle;
+export declare const assets: DirectoryHandle;
+
+export interface FileStat {
+  readonly size: number;
+  readonly modified: number;
+}
+
+export interface DirectoryHandle {
+  readonly uri: string;
+  readonly name: string;
+  file(path: string): FileHandle;
+  directory(path: string): DirectoryHandle;
+  exists(): Promise<boolean>;
+  create(): Promise<void>;
+  list(): Promise<(FileHandle | DirectoryHandle)[]>;
+  delete(): Promise<void>;
+}
+
+export interface FileHandle {
+  readonly uri: string;
+  readonly name: string;
+  stat(): Promise<FileStat | null>;
+  text(): Promise<string>;
+  bytes(): Promise<Uint8Array>;
+  write(data: string | Uint8Array | Blob): Promise<void>;
+  copy(to: FileHandle): Promise<void>;
+  move(to: FileHandle): Promise<void>;
+  delete(): Promise<void>;
+}

package/file-system.mjs

@@ -0,0 +1,2 @@
+export const dataDirectory = undefined;
+export const assets = undefined;

package/image.d.ts

@@ -0,0 +1,114 @@
+import type { CallOptions, Point, Quad, Rect } from "./index";
+import type { FileHandle } from "./file-system";
+
+export type Color = `#${string}` | readonly [red: number, green: number, blue: number];
+export type ImageFormat = "png" | "jpeg" | "heic";
+
+export interface TemplateMatch {
+  readonly frame: Rect;
+  readonly center: Point;
+  readonly score: number;
+  readonly scale: number;
+}
+
+export interface TemplateMatchOptions extends CallOptions {
+  readonly threshold?: number;
+  readonly region?: Rect;
+  readonly scales?: readonly number[];
+}
+
+export interface ColorCheck {
+  readonly point: Point;
+  readonly color: Color;
+  readonly tolerance?: number;
+}
+
+export interface ConnectedComponent {
+  readonly frame: Rect;
+  readonly pixels: number;
+  readonly centroid: Point;
+}
+
+export interface ImageStats {
+  readonly mean: readonly number[];
+  readonly min: readonly number[];
+  readonly max: readonly number[];
+  readonly deviation: readonly number[];
+}
+
+export interface TextRecognitionOptions extends CallOptions {
+  readonly region?: Rect;
+  readonly languages?: readonly string[];
+  readonly detectLanguage?: boolean;
+  readonly level?: "fast" | "accurate";
+  readonly words?: readonly string[];
+  readonly correction?: boolean;
+  readonly minimumHeight?: number;
+}
+
+export interface RecognizedTextBox {
+  readonly quad: Quad;
+  readonly frame: Rect;
+  readonly center: Point;
+}
+
+export interface RecognizedTextCandidate {
+  readonly text: string;
+  readonly confidence: number;
+  boundingBox(start: number, end: number): RecognizedTextBox | null;
+}
+
+export interface RecognizedTextLine extends RecognizedTextCandidate, RecognizedTextBox {
+  readonly candidates: readonly RecognizedTextCandidate[];
+}
+
+export interface ImageDifference {
+  readonly ratio: number;
+  readonly frames: readonly Rect[];
+}
+
+export interface DetectedBarcode {
+  readonly payload: string | null;
+  readonly symbology: string;
+  readonly quad: Quad;
+  readonly frame: Rect;
+  readonly center: Point;
+}
+
+export interface RasterImage {
+  readonly width: number;
+  readonly height: number;
+  readonly scale: number;
+  readonly frame: Rect;
+  readonly time: number | null;
+
+  crop(rect: Rect): RasterImage;
+  resize(scale: number): RasterImage;
+  resize(size: { readonly width?: number; readonly height?: number }): RasterImage;
+  rotate(degrees: number): RasterImage;
+  grayscale(): RasterImage;
+  threshold(level?: number | "otsu"): RasterImage;
+  mask(color: Color, options?: { readonly tolerance?: number }): RasterImage;
+  mask(range: readonly [low: Color, high: Color]): RasterImage;
+  invert(): RasterImage;
+  dilate(radius?: number): RasterImage;
+  erode(radius?: number): RasterImage;
+
+  encode(format?: ImageFormat, options?: CallOptions & { readonly quality?: number }): Promise<Uint8Array>;
+  save(file: FileHandle | string, options?: CallOptions & { readonly format?: ImageFormat; readonly quality?: number }): Promise<FileHandle>;
+  pixel(point: Point, options?: CallOptions): Promise<[red: number, green: number, blue: number, alpha: number]>;
+  stats(options?: CallOptions & { readonly region?: Rect }): Promise<ImageStats>;
+  release(): void;
+
+  find(template: RasterImage, options?: TemplateMatchOptions): Promise<TemplateMatch | null>;
+  findAll(template: RasterImage, options?: TemplateMatchOptions & { readonly limit?: number; readonly overlap?: number }): Promise<TemplateMatch[]>;
+  matchColors(checks: readonly ColorCheck[], options?: CallOptions): Promise<boolean[]>;
+  components(options?: CallOptions & { readonly minimumPixels?: number }): Promise<ConnectedComponent[]>;
+  recognizeText(options?: TextRecognitionOptions): Promise<RecognizedTextLine[]>;
+  diff(other: RasterImage, options?: CallOptions & { readonly threshold?: number }): Promise<ImageDifference>;
+  distance(other: RasterImage, options?: CallOptions): Promise<number>;
+  nearest(candidates: readonly RasterImage[], options?: CallOptions): Promise<{ readonly index: number; readonly distance: number }>;
+  detectBarcodes(options?: CallOptions): Promise<DetectedBarcode[]>;
+}
+
+export declare function decode(data: Uint8Array | FileHandle | string, options?: CallOptions & { readonly scale?: number }): Promise<RasterImage>;

package/image.mjs

@@ -0,0 +1,5 @@
+const outside = () => {
+  throw new Error("@swipt/api/image runs inside Swipt; build the swiplet with `swiplet build`");
+};
+
+export const decode = outside;

package/index.d.ts

@@ -0,0 +1,23 @@
+export interface CallOptions {
+  readonly signal?: AbortSignal;
+}
+
+export interface ObservableState<T> {
+  get(options?: CallOptions): Promise<T>;
+  values(options?: CallOptions): AsyncIterable<T>;
+}
+
+export type Point = [x: number, y: number];
+export type Rect = [x: number, y: number, width: number, height: number];
+export type Quad = [topLeft: Point, topRight: Point, bottomRight: Point, bottomLeft: Point];
+
+export type ErrorName = "AbortError" | "TimeoutError" | "NotFoundError" | "UnavailableError";
+
+export type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
+
+export type Jsonify<T> = T extends string | number | boolean | null ? T
+  : T extends undefined | symbol | ((...args: any[]) => unknown) ? never
+  : T extends { toJSON(): infer J } ? Jsonify<J>
+  : T extends readonly (infer U)[] ? Jsonify<U>[]
+  : T extends object ? { [K in keyof T]: Jsonify<Exclude<T[K], undefined>> }
+  : never;

package/index.mjs

@@ -0,0 +1 @@
+export {};

package/input.d.ts

@@ -0,0 +1,24 @@
+import type { CallOptions, Point } from "./index";
+
+export interface TapOptions extends CallOptions {
+  readonly count?: number;
+  readonly holdMs?: number;
+}
+
+export type KeyboardKey = "return" | "backspace" | "forwardDelete" | "tab" | "escape" | "space" | "left" | "right" | "up" | "down"
+  | "home" | "end" | "pageUp" | "pageDown" | `f${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12}`;
+export type KeyboardModifier = "cmd" | "shift" | "ctrl" | "alt";
+export type KeyCombination = KeyboardKey | `${KeyboardModifier}+${KeyboardKey}` | (string & {});
+export type TouchSample = [x: number, y: number, ms: number];
+
+export declare function tap(point: Point, options?: TapOptions): Promise<void>;
+export declare function swipe(from: Point, to: Point, options?: CallOptions & { durationMs?: number }): Promise<void>;
+export declare function drag(from: Point, to: Point, options?: CallOptions & { durationMs?: number; pressMs?: number }): Promise<void>;
+export declare function pinch(center: Point, scale: number, options?: CallOptions & { durationMs?: number }): Promise<void>;
+export declare function touch(fingers: readonly (readonly TouchSample[])[], options?: CallOptions): Promise<void>;
+export declare function pressKey(combination: KeyCombination, options?: CallOptions): Promise<void>;
+export declare function pressHome(options?: CallOptions): Promise<void>;
+export declare function openAppSwitcher(options?: CallOptions): Promise<void>;
+export declare function pressPower(options?: CallOptions): Promise<void>;
+export declare function pressVolumeUp(options?: CallOptions): Promise<void>;
+export declare function pressVolumeDown(options?: CallOptions): Promise<void>;

package/input.mjs

@@ -0,0 +1,15 @@
+const outside = () => {
+  throw new Error("@swipt/api/input runs inside Swipt; build the swiplet with `swiplet build`");
+};
+
+export const tap = outside;
+export const swipe = outside;
+export const drag = outside;
+export const pinch = outside;
+export const touch = outside;
+export const pressKey = outside;
+export const pressHome = outside;
+export const openAppSwitcher = outside;
+export const pressPower = outside;
+export const pressVolumeUp = outside;
+export const pressVolumeDown = outside;

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@swipt/api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-nightly.0",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/swipt-automation/swipt.git",
+    "directory": "api"
+  },
+  "type": "module",
+  "bin": {
+    "swiplet": "cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    },
+    "./swiplet": {
+      "types": "./swiplet.d.ts",
+      "default": "./swiplet.mjs"
+    },
+    "./file-system": {
+      "types": "./file-system.d.ts",
+      "default": "./file-system.mjs"
+    },
+    "./accessibility": {
+      "types": "./accessibility.d.ts",
+      "default": "./accessibility.mjs"
+    },
+    "./input": {
+      "types": "./input.d.ts",
+      "default": "./input.mjs"
+    },
+    "./device": {
+      "types": "./device.d.ts",
+      "default": "./device.mjs"
+    },
+    "./screen": {
+      "types": "./screen.d.ts",
+      "default": "./screen.mjs"
+    },
+    "./image": {
+      "types": "./image.d.ts",
+      "default": "./image.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "cli.mjs",
+    "*.d.ts",
+    "*.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "esbuild": "^0.28.2"
+  },
+  "peerDependencies": {
+    "@expo/ui": "~58.0.25",
+    "@types/react": "~19.3.0",
+    "expo": "~58.0.21",
+    "expo-localization": "~58.0.5",
+    "react": "19.3.0",
+    "react-native": "0.88.1"
+  },
+  "peerDependenciesMeta": {
+    "@expo/ui": {
+      "optional": true
+    },
+    "@types/react": {
+      "optional": true
+    },
+    "expo": {
+      "optional": true
+    },
+    "expo-localization": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  }
+}

package/repl.d.ts

@@ -0,0 +1,12 @@
+declare global {
+  const accessibility: typeof import("@swipt/api/accessibility");
+  const input: typeof import("@swipt/api/input");
+  const device: typeof import("@swipt/api/device");
+  const screen: typeof import("@swipt/api/screen");
+  const image: typeof import("@swipt/api/image");
+  const dialog: import("@swipt/api/swiplet").IntentDialog;
+
+  function show(image: import("@swipt/api/image").RasterImage): void;
+}
+
+export {};

package/screen.d.ts

@@ -0,0 +1,63 @@
+import type { CallOptions, ObservableState, Rect } from "./index";
+import type { FileHandle } from "./file-system";
+import type { ImageDifference, RasterImage } from "./image";
+
+export interface WaitOptions extends CallOptions {
+  readonly region?: Rect;
+  readonly timeoutMs?: number;
+  readonly threshold?: number;
+}
+
+export interface ScreenChange {
+  readonly time: number;
+  readonly end: number;
+  readonly frames: readonly Rect[];
+  readonly app: string | null;
+  readonly before: RasterImage;
+  readonly after: RasterImage;
+}
+
+export type TimelineEvent =
+  | { readonly time: number; readonly type: "operation"; readonly name: string; readonly arguments?: readonly unknown[]; readonly durationMs?: number; readonly error?: string }
+  | { readonly time: number; readonly type: "action"; readonly swiplet: string; readonly action: string; readonly caller: "app" | "shortcuts" | "api" }
+  | { readonly time: number; readonly type: "foreground"; readonly app: string }
+  | { readonly time: number; readonly type: "log"; readonly swiplet: string; readonly level: "error" | "warn" | "info" | "debug"; readonly message: string };
+
+export interface ScreenRecording {
+  readonly file: FileHandle;
+  readonly start: number | null;
+  readonly duration: number;
+  readonly width: number;
+  readonly height: number;
+  readonly scale: number;
+  readonly changes: readonly ScreenChange[];
+  readonly events: readonly TimelineEvent[];
+
+  frame(time: number): RasterImage;
+  frames(times: readonly number[] | { readonly everyMs: number; readonly from?: number; readonly to?: number }): RasterImage[];
+  grid(options?: CallOptions & { readonly times?: readonly number[]; readonly columns?: number; readonly width?: number }): Promise<RasterImage>;
+  diff(from: number, to: number, options?: CallOptions & { readonly threshold?: number }): Promise<ImageDifference>;
+  export(options?: CallOptions & {
+    readonly file?: FileHandle | string;
+    readonly from?: number;
+    readonly to?: number;
+    readonly region?: Rect;
+    readonly scale?: number;
+    readonly format?: "mov" | "mp4" | "gif";
+    readonly frameRate?: number;
+  }): Promise<FileHandle>;
+}
+
+export interface RecordingSession {
+  readonly file: FileHandle;
+  readonly start: number;
+  stop(options?: CallOptions): Promise<ScreenRecording>;
+}
+
+export declare function screenshot(options?: CallOptions): Promise<RasterImage>;
+export declare const frames: ObservableState<RasterImage>;
+export declare function waitFor(predicate: (frame: RasterImage) => boolean | Promise<boolean>, options?: CallOptions & { readonly timeoutMs?: number }): Promise<RasterImage>;
+export declare function waitForChange(options?: WaitOptions & { readonly from?: RasterImage }): Promise<RasterImage>;
+export declare function waitForStable(options?: WaitOptions & { readonly durationMs?: number }): Promise<RasterImage>;
+export declare function record(options?: CallOptions & { readonly file?: FileHandle | string }): Promise<RecordingSession>;
+export declare function openRecording(file: FileHandle | string, options?: CallOptions): Promise<ScreenRecording>;

package/screen.mjs

@@ -0,0 +1,11 @@
+const outside = () => {
+  throw new Error("@swipt/api/screen runs inside Swipt; build the swiplet with `swiplet build`");
+};
+
+export const screenshot = outside;
+export const frames = undefined;
+export const waitFor = outside;
+export const waitForChange = outside;
+export const waitForStable = outside;
+export const record = outside;
+export const openRecording = outside;

package/swiplet.d.ts

@@ -0,0 +1,106 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
+
+import type { CallOptions, Jsonify } from "./index";
+
+export type IntentChoiceStyle = "default" | "destructive" | "cancel";
+
+export type ConfirmationActionName = "add" | "addData" | "book" | "buy" | "call" | "checkIn" | "continue" | "create" | "do" | "download"
+  | "filter" | "find" | "get" | "go" | "log" | "open" | "order" | "pay" | "play" | "playSound" | "post" | "request" | "run"
+  | "search" | "send" | "set" | "share" | "start" | "startNavigation" | "toggle" | "turnOff" | "turnOn" | "view";
+
+export interface Person {
+  readonly name: string;
+  readonly handle?: { type: "phoneNumber" | "emailAddress"; value: string };
+}
+
+export interface Placemark {
+  readonly name?: string;
+  readonly coordinate?: [latitude: number, longitude: number];
+  readonly address?: string;
+}
+
+export interface IntentDialog {
+  requestChoice<T extends string | { title: string; style?: IntentChoiceStyle }>(choices: T[], prompt: string, options?: CallOptions): Promise<T>;
+  requestConfirmation(prompt: string, options?: CallOptions & { actionName?: ConfirmationActionName | { accept: string; deny: string; destructive?: boolean } }): Promise<void>;
+  requestValue(type: "text", prompt?: string, options?: CallOptions & { multiline?: boolean; literal?: boolean }): Promise<string>;
+  requestValue(type: "integer", prompt?: string, options?: CallOptions & { stepper?: boolean; min?: number; max?: number }): Promise<number>;
+  requestValue(type: "number", prompt?: string, options?: CallOptions & { min?: number; max?: number }): Promise<number>;
+  requestValue(type: "date" | "time" | "dateTime", prompt?: string, options?: CallOptions): Promise<Date>;
+  requestValue(type: "file", prompt?: string, options?: CallOptions): Promise<{ name: string; type: string; bytes: Uint8Array }>;
+  requestValue(type: "person", prompt?: string, options?: CallOptions): Promise<Person>;
+  requestValue(type: "placemark", prompt?: string, options?: CallOptions): Promise<Placemark>;
+  requestDisambiguation(values: string[], prompt: string, options?: CallOptions): Promise<string>;
+  requestValueConfirmation(value: string, prompt: string, options?: CallOptions): Promise<boolean>;
+  continueInForeground(prompt?: string, options?: CallOptions & { alwaysConfirm?: boolean }): Promise<void>;
+}
+
+export type ActionCaller = "app" | "shortcuts" | "api";
+
+export type Schema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> & StandardJSONSchemaV1<Input, Output>;
+
+declare const types: unique symbol;
+
+export interface Action<Input = void, Output = void> {
+  readonly [types]: { input: Input; output: Output };
+  readonly title: string;
+  readonly description?: string;
+  readonly expose: readonly "shortcuts"[];
+}
+
+export interface Extension<Actions extends Record<string, Action<any, any>> = {}, HasRun extends boolean = boolean> {
+  readonly [types]: { hasRun: HasRun };
+  readonly actions: Actions;
+}
+
+export interface RunContext {
+  readonly signal: AbortSignal;
+  readonly dialog: IntentDialog;
+}
+
+export interface ActionContext extends RunContext {
+  readonly caller: ActionCaller;
+}
+
+type Received<S> = S extends Schema ? StandardSchemaV1.InferOutput<S> : void;
+type Sent<S> = S extends Schema ? StandardSchemaV1.InferInput<S> : void;
+type Returned<S, R> = S extends Schema ? StandardSchemaV1.InferInput<S> : R;
+type Delivered<S, R> = S extends Schema ? StandardSchemaV1.InferOutput<S> : R;
+
+export declare function defineAction<I extends Schema | undefined = undefined, O extends Schema | undefined = undefined, R = void>(definition: {
+  readonly title: string;
+  readonly description?: string;
+  readonly input?: I;
+  readonly output?: O;
+  readonly expose?: readonly "shortcuts"[];
+  run(input: Received<I>, context: ActionContext): Returned<O, R> | Promise<Returned<O, R>>;
+}): Action<Sent<I>, Jsonify<Awaited<Delivered<O, R>>>>;
+
+export declare function defineExtension<Actions extends Record<string, Action<any, any>> = {}>(definition: {
+  run(context: RunContext): Promise<void>;
+  readonly actions?: Actions;
+}): Extension<Actions, true>;
+export declare function defineExtension<Actions extends Record<string, Action<any, any>> = {}>(definition: {
+  readonly actions?: Actions;
+}): Extension<Actions, false>;
+
+export type ServiceStatus = "starting" | "running" | "stopped" | "failed";
+
+type ActionCall<A> = A extends Action<infer Input, infer Output>
+  ? [Input] extends [void]
+    ? (input?: undefined, options?: { signal?: AbortSignal }) => Promise<Output>
+    : (input: Input, options?: { signal?: AbortSignal }) => Promise<Output>
+  : never;
+
+export type ActionCalls<E extends Extension<any, any>> = { readonly [K in keyof E["actions"]]: ActionCall<E["actions"][K]> };
+
+export interface ServiceHandle {
+  readonly enabled: boolean;
+  readonly status: ServiceStatus;
+  readonly error: string | null;
+  readonly since: Date | null;
+  setEnabled(enabled: boolean): Promise<void>;
+}
+
+export declare function actions<E extends Extension<any, any>>(): ActionCalls<E>;
+
+export declare function useService<E extends Extension<any, true>>(): ServiceHandle;

package/swiplet.mjs

@@ -0,0 +1,8 @@
+const outside = () => {
+  throw new Error("@swipt/api/swiplet runs inside Swipt; build the swiplet with `swiplet build`");
+};
+
+export const defineExtension = outside;
+export const defineAction = outside;
+export const actions = outside;
+export const useService = outside;

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.