@theaiplatform/miniapp-sdk 0.2.4 → 0.3.1

package/README.md

@@ -1,16 +1,16 @@
 # The AI Platform Miniapp SDK
 
-`@theaiplatform/miniapp-sdk` is the public package for building portable
-miniapps that run in The AI Platform.
+`@theaiplatform/miniapp-sdk` is the TypeScript SDK for building, testing, and
+shipping portable miniapps on The AI Platform.
 
 ```bash
 pnpm add @theaiplatform/miniapp-sdk
 ```
 
 The package provides the host-injected SDK API, isolated surface lifecycle
-types, browser helpers, portable React UI components, manifest schema, and the
-Rspack/Rslib integration used to produce descriptor-backed Module Federation
-targets.
+types, browser helpers, portable React UI components, manifest schema,
+Rstest/Playwright integration, and the Rspack/Rslib integration used to produce
+descriptor-backed Module Federation targets.
 
 Start with the [Miniapp SDK documentation](https://docs.theaiplatform.app/miniapps/).
 
@@ -27,8 +27,28 @@ Start with the [Miniapp SDK documentation](https://docs.theaiplatform.app/miniap
 - `@theaiplatform/miniapp-sdk/surface`
 - `@theaiplatform/miniapp-sdk/config`
 - `@theaiplatform/miniapp-sdk/rspack`
+- `@theaiplatform/miniapp-sdk/testing/rstest`
 - `@theaiplatform/miniapp-sdk/config-schema.json`
 
+## In-app E2E testing in 0.3.1
+
+The `/testing/rstest` entry point extends Rstest's Playwright fixtures with a
+host-provided miniapp surface and exact TAP session provenance. Tests can assert
+both the rendered UI and the package/surface identity selected by the Test Lab:
+
+```ts
+import { expect, test } from '@theaiplatform/miniapp-sdk/testing/rstest';
+
+test('mounts the miniapp surface', async ({ surface, tap }) => {
+  await expect(surface.locator('body')).toBeVisible();
+  expect(tap.packageId).toBe('tap_pkg_example_0001');
+  expect(tap.surfaceId).toBe('example-surface');
+});
+```
+
+Install `@rstest/core@0.11.3`, `@rstest/playwright@0.11.3`, and Playwright as
+development dependencies when using this optional entry point.
+
 The host API is injected at runtime. Importing an entry point is safe in build
 tools and tests; host-backed calls fail when used outside a supported runtime.
 `sdk.storage` provides revisioned non-secret JSON scoped by the host to the
@@ -54,6 +74,28 @@ are not SDK capabilities. Job-key journaling suppresses
 routine reconnect duplicates, but physical exactly-once printing is impossible;
 every result therefore carries `physicalExactlyOnce: false`.
 
+## Terminal sessions in 0.3.0
+
+`sdk.terminal?.v1` is an optional desktop-only terminal session API introduced
+in SDK 0.3.0. It exposes
+only the fixed `workspace-shell` and `neovim` profiles; package code cannot
+choose an executable, environment, native terminal ID, working directory, or
+filesystem path. `open()` returns a host-owned session with ordered binary
+events, acknowledged binary writes, resize, and idempotent close. A dedicated
+per-session channel applies byte credit and bounded buffering, so terminal
+output never uses the ordinary miniapp host-action bridge as a data plane.
+Packages opening a session declare the selected `terminal` profile and the
+`filesystem-mount` resource `conversation-vfs:read-write`, plus the persisted
+`terminal.session.open`, `filesystem.read`, and `filesystem.write` actions.
+Capability discovery is authoritative: the initial host reports both profiles
+unavailable. `workspace-shell` waits for positive conversation-scoped read
+isolation, and `neovim` additionally waits for an integrity-locked runtime.
+
+See the
+[terminal API reference](https://docs.theaiplatform.app/miniapps/reference/sdk#terminal-sessions)
+for capability detection, the required descriptor authorization, session
+events, limits, and cleanup.
+
 ## Discovery metadata
 
 Descriptor-backed packages may assign up to three unique

package/config-schema.json

@@ -600,27 +600,6 @@
       ],
       "type": "string"
     },
-    "MiniAppReferencesManifest": {
-      "additionalProperties": false,
-      "description": "Manifest that references built TAP miniapp manifests.",
-      "properties": {
-        "$schema": {
-          "description": "Optional JSON Schema reference for editor support.",
-          "type": ["string", "null"]
-        },
-        "references": {
-          "description": "References to built TAP miniapp manifests.\n\nString shorthand remains available for local and mutable development sources. An\nimmutable remote collection uses the object form (`{ \"url\": ..., \"hash\": ... }`) so\nevery child manifest carries its own SHA-256 integrity boundary.",
-          "items": {
-            "$ref": "#/$defs/MiniAppSource"
-          },
-          "minItems": 1,
-          "type": "array"
-        }
-      },
-      "required": ["references"],
-      "title": "Tap Miniapp References Manifest",
-      "type": "object"
-    },
     "MiniAppSource": {
       "description": "Absolute URL or local path. Bundle entry paths are resolved relative to the manifest that declares them.",
       "oneOf": [
@@ -3694,12 +3673,8 @@
     {
       "$ref": "#/$defs/MiniAppBundleManifest",
       "description": "A single miniapp bundle with its runtime entrypoint."
-    },
-    {
-      "$ref": "#/$defs/MiniAppReferencesManifest",
-      "description": "A collection manifest that points at built miniapp manifests."
     }
   ],
-  "description": "Manifest for a Tap miniapp bundle or a collection of built miniapps.",
+  "description": "Manifest for one Tap package or legacy miniapp bundle.",
   "title": "Tap Miniapp Manifest"
 }

package/dist/index.d.ts

@@ -355,6 +355,8 @@ export declare type MiniAppPlatformApi = {
     credentials?: MiniAppCredentialsApi;
     /** Desktop host capability; feature-detect before use on portable targets. */
     printing?: MiniAppReceiptPrintingApi;
+    /** Desktop host capability; feature-detect before opening a terminal. */
+    terminal?: MiniAppTerminalApi;
     /** Browser capabilities appear only when the selected target supports them. */
     auth?: MiniAppAuthApi;
     vfs?: MiniAppVfsApi;
@@ -620,6 +622,76 @@ export declare type MiniAppStorageSetOptions = MiniAppStorageAddress & {
     expectedRevision: number | null;
 };
 
+export declare type MiniAppTerminalApi = {
+    readonly v1: MiniAppTerminalV1Api;
+};
+
+/** Versioned, desktop-only host terminal capability. */
+export declare type MiniAppTerminalV1Api = {
+    getCapabilities(): Promise<MiniAppTerminalV1Capabilities>;
+    open(options: MiniAppTerminalV1OpenOptions): Promise<MiniAppTerminalV1Session>;
+};
+
+export declare type MiniAppTerminalV1Capabilities = {
+    profiles: MiniAppTerminalV1Profile[];
+    limits: MiniAppTerminalV1Limits;
+};
+
+export declare type MiniAppTerminalV1DataEvent = {
+    type: 'data';
+    sequence: number;
+    data: Uint8Array;
+};
+
+export declare type MiniAppTerminalV1Event = MiniAppTerminalV1DataEvent | MiniAppTerminalV1ExitEvent;
+
+export declare type MiniAppTerminalV1ExitEvent = {
+    type: 'exit';
+    sequence: number;
+    code: number | null;
+    signal: string | null;
+    reason: 'exited' | 'closed' | 'revoked' | 'error';
+};
+
+export declare type MiniAppTerminalV1Limits = {
+    maxSessionsPerDocument: number;
+    maxWriteBytes: number;
+    maxOutputBytesInFlight: number;
+    maxCols: number;
+    maxRows: number;
+};
+
+export declare type MiniAppTerminalV1OpenOptions = {
+    profile: MiniAppTerminalV1ProfileId;
+    cols: number;
+    rows: number;
+};
+
+export declare type MiniAppTerminalV1Profile = {
+    id: MiniAppTerminalV1ProfileId;
+    available: boolean;
+    unavailableReason: string | null;
+};
+
+/** Host-owned terminal runtime profiles exposed by `sdk.terminal.v1`. */
+export declare type MiniAppTerminalV1ProfileId = 'workspace-shell' | 'neovim';
+
+export declare type MiniAppTerminalV1ResizeOptions = {
+    cols: number;
+    rows: number;
+};
+
+export declare type MiniAppTerminalV1Session = {
+    /** Opaque host-minted session identity; it carries no ambient authority. */
+    readonly id: string;
+    readonly profile: MiniAppTerminalV1ProfileId;
+    /** Ordered output with byte-sized backpressure owned by the host session. */
+    readonly events: ReadableStream<MiniAppTerminalV1Event>;
+    write(data: Uint8Array): Promise<void>;
+    resize(options: MiniAppTerminalV1ResizeOptions): Promise<void>;
+    close(): Promise<void>;
+};
+
 export declare type MiniAppUserProfile = {
     sub: string;
     name?: string | null;