@exponential_app/engine 0.0.0-stage → 0.1.0

package/dist/types/eengine/src/stores.d.ts

@@ -0,0 +1,125 @@
+import type { RecordRow } from "@exponential_app/eui/host";
+import type { Failure, Vault } from "./broker.js";
+import type { BlobStore } from "./tools.js";
+/** One write of a batch (the store's spelling of the outbox writes). */
+export type RecordWrite = {
+    op: `upsert`;
+    id: string;
+    kind: string;
+    data: Record<string, unknown>;
+    create: boolean;
+} | {
+    op: `delete`;
+    id: string;
+};
+/** One call's writes, all or nothing, with its idempotency key. */
+export interface WriteBatch {
+    writeId: string;
+    writes: RecordWrite[];
+    /** ISO time of the write (createdAt / updatedAt of what it touches). */
+    at: string;
+}
+/** The ids in write order; `replayed` = the writeId was applied before. */
+export interface WriteAck {
+    ids: string[];
+    replayed: boolean;
+}
+/** One history event of a record. */
+export interface RecordEvent {
+    recordId: string;
+    op: `create` | `update` | `delete`;
+    actor: string | null;
+    writeId: string;
+    patch: unknown;
+    before: unknown;
+    at: string;
+}
+export interface RecordsDelta {
+    upserts: RecordRow[];
+    deletes: string[];
+}
+/** Where an app's records live. Rejects with a `StoreError`. */
+export interface EngineRecordStore {
+    rows(app: string): Promise<RecordRow[]>;
+    write(app: string, batch: WriteBatch, by: string | null): Promise<WriteAck>;
+    history(app: string, id: string): Promise<RecordEvent[]>;
+    /** Called with every change to `app`'s rows; returns the cancel. */
+    subscribe(app: string, on: (delta: RecordsDelta) => void): () => void;
+}
+/** A store's refusal as an Error carrying the Failure. */
+export declare class StoreError extends Error implements Failure {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Apply one batch to `rows` (all or nothing: throws with nothing changed).
+ *  Answers the next rows, the ack, the delta and the events. */
+export declare function applyBatch(rows: readonly RecordRow[], batch: WriteBatch, by: string | null): {
+    rows: RecordRow[];
+    ack: WriteAck;
+    delta: RecordsDelta;
+    events: RecordEvent[];
+};
+/** One committed batch, what a persistence stores in one transaction. */
+export interface RecordCommit {
+    writeId: string;
+    ids: string[];
+    upserts: RecordRow[];
+    deletes: string[];
+    events: RecordEvent[];
+}
+/** Where a `LocalRecordStore` keeps its rows. */
+export interface RecordPersistence {
+    load(app: string): Promise<RecordRow[]>;
+    /** The ids of an applied writeId, or null. */
+    ack(app: string, writeId: string): Promise<string[] | null>;
+    /** One batch, all or nothing. */
+    commit(app: string, commit: RecordCommit): Promise<void>;
+    history(app: string, id: string): Promise<RecordEvent[]>;
+}
+/** Every app's rows in memory over a persistence; writes run one at a time. */
+export declare class LocalRecordStore implements EngineRecordStore {
+    readonly persistence: RecordPersistence;
+    private cache;
+    private listeners;
+    private queue;
+    constructor(persistence: RecordPersistence);
+    private loaded;
+    rows(app: string): Promise<RecordRow[]>;
+    write(app: string, batch: WriteBatch, by: string | null): Promise<WriteAck>;
+    history(app: string, id: string): Promise<RecordEvent[]>;
+    subscribe(app: string, on: (delta: RecordsDelta) => void): () => void;
+}
+/** The persistence of tests and previews. */
+export declare class MemoryPersistence implements RecordPersistence {
+    private rows;
+    private acks;
+    private events;
+    load(app: string): Promise<RecordRow[]>;
+    ack(app: string, writeId: string): Promise<string[] | null>;
+    commit(app: string, commit: RecordCommit): Promise<void>;
+    history(app: string, id: string): Promise<RecordEvent[]>;
+}
+/** Every app's rows in memory (tests, previews). */
+export declare class MemoryRecordStore extends LocalRecordStore {
+    constructor();
+}
+/** A process-local vault (tests, previews). */
+export declare class MemoryVault implements Vault {
+    readonly values: Map<string, string>;
+    read(key: string): Promise<string | null>;
+    write(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** Record files in memory (tests, previews). */
+export declare class MemoryBlobStore implements BlobStore {
+    readonly files: Map<string, {
+        name: string;
+        mimeType: string;
+        bytes: Uint8Array;
+    }>;
+    put(app: string, name: string, mimeType: string, bytes: Uint8Array): Promise<string>;
+    get(app: string, id: string): Promise<Uint8Array | null>;
+    delete(app: string, id: string): Promise<void>;
+}
+/** The `local` identity's device uuid under `key` in the Vault, created once. */
+export declare function localDeviceId(vault: Vault, key: string): Promise<string>;

package/dist/types/eengine/src/tools.d.ts

@@ -0,0 +1,79 @@
+import type { HubOutcome } from "../../emcp/src/index.js";
+export type JsonSchema = Record<string, unknown>;
+export interface CapabilityTool {
+    name: string;
+    runs: `native` | `engine`;
+    description: string;
+    inputSchema: JsonSchema;
+    nativeOutputSchema: JsonSchema | null;
+    outputSchema: JsonSchema;
+}
+export declare const CAPABILITY_TOOLS: readonly CapabilityTool[];
+export declare const MIME_BY_EXTENSION: Readonly<Record<string, string>>;
+export declare const toolDef: (name: string) => CapabilityTool | null;
+/** A host's native provider of one capability (`name`, like the crate's
+ *  `Capability`); `call` gets the bare tool (`pick`) and the mapped native
+ *  arguments, and answers an MCP call result (`structuredContent` per
+ *  `nativeOutputSchema`, or `isError`). */
+export interface NativeCapability {
+    name: string;
+    call(tool: string, args: Record<string, unknown>): Promise<unknown>;
+}
+/** `bridgeCall`'s `native` over a host's capabilities: `photos_pick` → the
+ *  `photos` provider's `pick`; a capability the host lacks answers `unavailable`. */
+export declare const nativeCaller: (capabilities: readonly NativeCapability[]) => (tool: string, args: Record<string, unknown>) => Promise<unknown>;
+/** The first violation of `value` against `schema` as `<pointer> <keyword>`, or null. */
+export declare function schemaViolation(schema: JsonSchema, value: unknown, path?: readonly string[]): string | null;
+export type ValidateResult = {
+    arguments: Record<string, unknown>;
+} | {
+    error: string;
+};
+/** A call's arguments against the tool's `inputSchema`; a missing top-level
+ *  property with a `default` gets it. */
+export declare function validateToolArguments(tool: string, args: unknown): ValidateResult;
+export declare function base64Encode(bytes: Uint8Array): string;
+/** Strict: the standard alphabet, padded, no whitespace, zero trailing bits; null otherwise. */
+export declare function base64Decode(s: string): Uint8Array | null;
+/** The type the bytes tell (PDF, JPEG, PNG, GIF), or null. */
+export declare function sniffMime(bytes: Uint8Array): string | null;
+/** A file's MIME type: the given one, else its name's extension, else its bytes,
+ *  else text/plain for a text and application/octet-stream. */
+export declare function mimeFor(name: string, bytes: Uint8Array, given: string | null | undefined, isText: boolean): string;
+/** A notification id the app did not name: `n-` + 32 lowercase hex. */
+export declare function newNotificationId(): string;
+export interface BlobStore {
+    get(app: string, id: string): Promise<Uint8Array | null>;
+    /** Stores the bytes as an app file; answers its id. */
+    put(app: string, name: string, mimeType: string, bytes: Uint8Array): Promise<string>;
+}
+export interface BridgeContext {
+    app: string;
+    screens: readonly string[];
+}
+export interface McpCallResult {
+    content: {
+        type: `text`;
+        text: string;
+    }[];
+    structuredContent?: unknown;
+    isError?: true;
+}
+export interface BridgeInput {
+    tool: string;
+    arguments: unknown;
+    context: BridgeContext;
+    blobs: BlobStore;
+    native: (tool: string, args: Record<string, unknown>) => Promise<unknown>;
+    newId?: () => string;
+}
+export interface BridgeOutput {
+    result: McpCallResult;
+    outcome: HubOutcome;
+}
+export declare const toolResult: (structuredContent: unknown) => McpCallResult;
+export declare const toolError: (text: string) => McpCallResult;
+/** One capability call from the broker's `call` verdict to its answer. */
+export declare function bridgeCall(input: BridgeInput): Promise<BridgeOutput>;
+/** print.pdf's default file name: the title with `/\:*?"<>|` and controls as `-`, + `.pdf`. */
+export declare const pdfFileName: (title: string) => string;

package/dist/types/eengine/src/web/index.d.ts

@@ -0,0 +1,20 @@
+import type { OpenPickerOptions, WebPlatform } from "./platform.js";
+export * from "./mcp.js";
+export * from "./platform.js";
+export * from "./stores.js";
+import type { NativeCapability } from "../tools.js";
+export type { NativeCapability };
+export interface WebCapabilityOptions {
+    /** A notification was tapped: `tap` = the lifecycle event posted with it, verbatim. */
+    onTap?(tap: unknown): void;
+}
+/** The OPFS directory that is the app's photo library. */
+export declare const PHOTOS_DIR = "photos";
+/** `accept` (MIME types or `.ext`) as `showOpenFilePicker` types. */
+export declare const pickerTypes: (accept: string[]) => OpenPickerOptions[`types`];
+/**
+ * The web's native capabilities, leaving out what this browser lacks
+ * (no `navigator.share` = no share, no Notification = no notifications).
+ * photos, files and print are always there (photos without OPFS = an empty library).
+ */
+export declare const webCapabilities: (platform?: WebPlatform, opts?: WebCapabilityOptions) => NativeCapability[];

package/dist/types/eengine/src/web/mcp.d.ts

@@ -0,0 +1,27 @@
+/** An MCP call result as a native capability answers it. */
+export type McpResult = {
+    content: [{
+        type: `text`;
+        text: string;
+    }];
+    structuredContent: Record<string, unknown>;
+} | {
+    content: [{
+        type: `text`;
+        text: string;
+    }];
+    isError: true;
+};
+export declare const ok: (structuredContent: Record<string, unknown>) => McpResult;
+export declare const fail: (reason: string) => McpResult;
+export declare const notFound: () => McpResult;
+export declare const unavailable: () => McpResult;
+export declare const failed: (message: string) => McpResult;
+/** The message of anything thrown, short and on one line. */
+export declare const errorMessage: (error: unknown) => string;
+/** A DOMException-style abort (a cancelled picker or share sheet). */
+export declare const isAbort: (error: unknown) => boolean;
+/** Standard padded base64. */
+export declare const encodeBase64: (bytes: Uint8Array) => string;
+/** Strict standard padded base64 (no whitespace, no URL alphabet, zero pad bits); null when malformed. */
+export declare const decodeBase64: (text: string) => Uint8Array | null;

package/dist/types/eengine/src/web/platform.d.ts

@@ -0,0 +1,91 @@
+/** The parts of a `File` the capabilities read. */
+export interface FileLike {
+    readonly name: string;
+    readonly type: string;
+    readonly lastModified: number;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** File System Access / OPFS file handle (the parts used). */
+export interface FileHandleLike {
+    readonly kind: `file`;
+    readonly name: string;
+    getFile(): Promise<FileLike>;
+    createWritable(): Promise<WritableLike>;
+}
+export interface WritableLike {
+    write(data: Blob | Uint8Array): Promise<void>;
+    close(): Promise<void>;
+}
+/** An OPFS directory handle (the parts used). */
+export interface DirectoryHandleLike {
+    readonly kind: `directory`;
+    readonly name: string;
+    getDirectoryHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<DirectoryHandleLike>;
+    getFileHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<FileHandleLike>;
+    values(): AsyncIterable<FileHandleLike | DirectoryHandleLike>;
+}
+/** `showOpenFilePicker` options (File System Access). */
+export interface OpenPickerOptions {
+    multiple: boolean;
+    types?: {
+        description?: string;
+        accept: Record<string, string[]>;
+    }[];
+    excludeAcceptAllOption?: boolean;
+}
+export interface ShareDataLike {
+    title?: string;
+    text?: string;
+    url?: string;
+    files?: File[];
+}
+/** A shown notification (the parts used). */
+export interface NotificationLike {
+    onclick: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    close(): void;
+}
+export interface NotificationsLike {
+    permission(): `default` | `granted` | `denied`;
+    requestPermission(): Promise<`default` | `granted` | `denied`>;
+    show(title: string, options: {
+        body?: string;
+        tag: string;
+    }): NotificationLike;
+}
+export type TimerHandle = unknown;
+export interface WebPlatform {
+    /** File System Access open picker; throws AbortError on cancel. */
+    showOpenFilePicker?(options: OpenPickerOptions): Promise<FileHandleLike[]>;
+    /** File System Access save picker; throws AbortError on cancel. */
+    showSaveFilePicker?(options: {
+        suggestedName: string;
+    }): Promise<FileHandleLike>;
+    /** A hidden `<input type=file>`; resolves [] when the person cancels. */
+    pickWithInput(options: {
+        accept: string;
+        multiple: boolean;
+    }): Promise<FileLike[]>;
+    /** A download through an `<a download>` blob URL. */
+    download(name: string, blob: Blob): void;
+    /** `navigator.share` and `navigator.canShare`. */
+    share?(data: ShareDataLike): Promise<void>;
+    canShare?(data: ShareDataLike): boolean;
+    /** A hidden iframe on a blob URL, `contentWindow.print()` once loaded, then removed. */
+    print(blob: Blob): Promise<void>;
+    /** `navigator.storage.getDirectory()` (OPFS). */
+    storageDirectory?(): Promise<DirectoryHandleLike>;
+    /** The Notification API. */
+    notifications?: NotificationsLike;
+    now(): number;
+    setTimeout(fn: () => void, ms: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+    /** window.focus(). */
+    focus(): void;
+}
+/** The real browser. Call it in a page (it reads `window`, `document` and `navigator`). */
+export declare const browserPlatform: () => WebPlatform;

package/dist/types/eengine/src/web/stores.d.ts

@@ -0,0 +1,125 @@
+import type { RecordRow } from "@exponential_app/eui/host";
+import type { Vault } from "../broker.js";
+import { LocalRecordStore, type RecordCommit, type RecordEvent, type RecordPersistence } from "../stores.js";
+import type { BlobStore } from "../tools.js";
+/** The schema (idempotent): the crate's `sqlite::SCHEMA`, statement for statement. */
+export declare const SQLITE_SCHEMA: string[];
+export type SqlValue = string | number | null;
+export interface SqlStatement {
+    sql: string;
+    bind?: SqlValue[];
+}
+/** A synchronous SQLite connection (sqlite-wasm's oo1 `DB`, `bun:sqlite` in tests). */
+export interface SyncSqlDatabase {
+    /** Rows as objects keyed by column name. */
+    query(sql: string, bind: SqlValue[]): Record<string, SqlValue>[];
+    run(sql: string, bind: SqlValue[]): void;
+}
+/** The page's handle on the worker's database. */
+export interface SqlDatabase {
+    query(sql: string, bind?: SqlValue[]): Promise<Record<string, SqlValue>[]>;
+    /** The statements in ONE transaction: all or nothing. */
+    transaction(statements: SqlStatement[]): Promise<void>;
+}
+type SqlRequest = {
+    id: number;
+    op: `query`;
+    sql: string;
+    bind: SqlValue[];
+} | {
+    id: number;
+    op: `transaction`;
+    statements: SqlStatement[];
+};
+type SqlResponse = {
+    id: number;
+    rows?: Record<string, SqlValue>[];
+    error?: string;
+};
+/** The smallest MessagePort a worker and a page share. */
+export interface PortLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: `message`, listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+/** Run one request against `db` (the worker's half, a transaction rolls back on any failure). */
+export declare function answerSql(db: SyncSqlDatabase, request: SqlRequest): SqlResponse;
+/** Serve `db` over `port` (call it inside the worker once the database is open). */
+export declare function serveSql(db: SyncSqlDatabase, port: PortLike): void;
+/** The page's client of a worker's `serveSql`. */
+export declare function sqlClient(port: PortLike): SqlDatabase;
+/** The crate's `SqliteRecordStore` tables over a `SqlDatabase`. */
+export declare class SqlitePersistence implements RecordPersistence {
+    private readonly db;
+    constructor(db: SqlDatabase);
+    load(app: string): Promise<RecordRow[]>;
+    ack(app: string, writeId: string): Promise<string[] | null>;
+    commit(app: string, c: RecordCommit): Promise<void>;
+    history(app: string, id: string): Promise<RecordEvent[]>;
+}
+/** Open (and create) the runner's IndexedDB database: records, writes, events and the vault. */
+export declare function openRunnerIdb(factory: IDBFactory, name: string): Promise<IDBDatabase>;
+/** The records' fallback when OPFS has no sync access handles: one IndexedDB transaction per batch. */
+export declare class IndexedDbPersistence implements RecordPersistence {
+    private readonly db;
+    constructor(db: IDBDatabase);
+    load(app: string): Promise<RecordRow[]>;
+    ack(app: string, writeId: string): Promise<string[] | null>;
+    commit(app: string, c: RecordCommit): Promise<void>;
+    history(app: string, id: string): Promise<RecordEvent[]>;
+}
+/** The Vault in IndexedDB (runner.json `storage`: the web's keystore). */
+export declare class IndexedDbVault implements Vault {
+    private readonly db;
+    constructor(db: IDBDatabase);
+    read(key: string): Promise<string | null>;
+    write(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** An OPFS directory (the parts the BlobStore uses). */
+export interface OpfsDirectory {
+    getDirectoryHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<OpfsDirectory>;
+    getFileHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<{
+        getFile(): Promise<{
+            arrayBuffer(): Promise<ArrayBuffer>;
+        }>;
+        createWritable(): Promise<{
+            write(data: Uint8Array | string): Promise<void>;
+            close(): Promise<void>;
+        }>;
+    }>;
+    removeEntry(name: string): Promise<void>;
+}
+/** Record files in OPFS: `<root>/<app>/<id>` (+ `<id>.json` with name and mime), the crate's `FsBlobStore` layout. */
+export declare class OpfsBlobStore implements BlobStore {
+    private readonly root;
+    constructor(root: () => Promise<OpfsDirectory>);
+    private dir;
+    private writeFile;
+    put(app: string, name: string, mimeType: string, bytes: Uint8Array): Promise<string>;
+    get(app: string, id: string): Promise<Uint8Array | null>;
+    delete(app: string, id: string): Promise<void>;
+}
+export interface WebStorage {
+    records: LocalRecordStore;
+    /** Which records backend opened: `sqlite` (OPFS) or the `indexeddb` fallback. */
+    backend: `sqlite` | `indexeddb`;
+    vault: Vault;
+    blobs: BlobStore;
+}
+/** The runner's stores: SQLite on OPFS when `openSqlite` opens, else IndexedDB. */
+export declare function openWebStorage(options: {
+    indexedDB: IDBFactory;
+    /** The IndexedDB database name (per app id). */
+    idbName: string;
+    /** Opens the worker's SQLite on OPFS; rejects when OPFS's sync access handles are missing. */
+    openSqlite?: () => Promise<SqlDatabase>;
+    /** The OPFS directory `storage.files` lives in. */
+    files: () => Promise<OpfsDirectory>;
+}): Promise<WebStorage>;
+export {};