@ai-matrx/applets 0.2.7

package/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog — @ai-matrx/applets
+
+## 0.2.7
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/applets/vnull..npm/applets/v0.2.7 -- apps/shared/applets`).
+No source changes intended and no consumer action required.
+
+## 0.2.6
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/applets/vnull..npm/applets/v0.2.6 -- apps/shared/applets`).
+No source changes intended and no consumer action required.
+
+## 0.2.5
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/applets/vnull..npm/applets/v0.2.5 -- apps/shared/applets`).
+No source changes intended and no consumer action required.
+
+## 0.2.4
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/applets/vnull..npm/applets/v0.2.4 -- apps/shared/applets`).
+No source changes intended and no consumer action required.
+
+## 0.2.3
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/applets/vnull..npm/applets/v0.2.3 -- apps/shared/applets`).
+No source changes intended and no consumer action required.
+
+## 0.2.2
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/applets/vnull..npm/applets/v0.2.2 -- apps/shared/applets`).
+No source changes intended and no consumer action required.
+
+## 0.2.1 — 2026-10-06
+
+`createPlatformHost` binds records' live updates by default: with no `records.realtime` given it uses
+`createRecordsRealtimePort()` from `@ai-matrx/records/realtime` over the host app's mounted
+`@ai-matrx/realtime` manager, so `rows:<alias>` fires with no per-host wiring.
+
+Consumer action: none, unless your host passed its own realtime port only to get live rows — drop it.
+
+## 0.2.0 — 2026-10-06
+
+`@ai-matrx/applets/platform`: `createPlatformHost(opts)`, the real `AppletHost` over the live platform
+(AP-0). Host-neutral — every client is injected: `{ appletId, supabase (the viewer's session), agents
+(`@ai-matrx/agents/intelligence` port), activeOrganizationId, nav: { go, current, subscribe? },
+reportError, surfaces?: { serverActions?, approvals?, door?, maxDepth? }, records?: { realtime?,
+knownDoors? } }`. No framework, no store, no environment reads. Announces itself (`kind: "platform"`).
+
+- `record()` reads `app.definition` through the viewer's client. A row with code only in
+  `component_code` is read as `files: { "App.tsx" }`, one page — a migration bridge that is deleted
+  with AP-0's record migration.
+- `data`: table sources go through records' `createTableDataPort` (the table's own organization for
+  writes; reads span every membership); entity sources refuse `not_supported` by name until AP-3 phase B.
+- `intelligence`: alias → key from the record, `appletId` stamped on every run; a signed-in run with
+  no active organization is refused `organization_required` (held, never picked); guests run with null.
+- `surface`: the `applets/<id>` chain read from `ui.ui_surface*`, resolved with alchemy's
+  `resolveActionChain` and run through `runSurfaceAction`; page Actions go to the declaring Applet's
+  frame on `actions` and settle on `completeAction`; base `write_row` is answered by the data port.
+- `kinds` read `content_ir.kind_definition` / `kind_component`; `pages` refuse `not_supported`
+  (no table-built page store exists yet).
+- `events`: one hub for `rows:<alias>`, `run:<requestId>`, `value:<name>`, `actions`, `nav`.
+- `child(appletId)` answers a scoped host; `dispose()` stops every producer.
+
+### Consumer action
+
+None for existing imports. A host replacing its hand-built web host imports `createPlatformHost` from
+`@ai-matrx/applets/platform` and passes its own clients; until the Applet is saved through
+`ui.save_applet_surface`, `surface.mount` refuses `surface_not_found` by name.
+
+## 0.1.2 — 2026-10-06
+
+Data hooks rebuilt on `@ai-matrx/records/data` (records 0.74, AP-3). One data engine: records'.
+
+- `Column`, `Row`, `Values`, `Query`, `Page`, `DataPort`, `HostDataPort`, `RowsEvent`, `DataSource`,
+  `DataEvents` are re-exported from `@ai-matrx/records/data`; `Filter` = records' `WhereClause`,
+  `SourceInfo` = records' `DataSource`. A DataPort now answers `RecordsResult` (a `RecordsError`);
+  `fromRecordsError` turns it into the §0 `AppletError`.
+- `useRows`, `useRow`, `useColumns`, `useSources` and create/update/archive/restore wrap
+  `useDataRows`/`useDataRow`/`useDataColumns`/`useDataSources`/`useDataMutations`; `AppletFrame`
+  mounts `DataPortProvider` (`port = host.data`, `events = host.events`, `portKey = hostId`). The
+  package's own TanStack row engine is deleted. Additive: `useRows` returns `newer` and `refresh()`,
+  `useRow` returns `refresh()`.
+- Memory host: its data port is a records `HostDataPort` (`control.dataPort`); `spec.data` accepts a
+  real one (`createTableDataPort`) in place of `tables`. `MemoryTableSpec.refuse` returns a
+  `RecordsError` (no `retryable`); an unknown alias refuses `not_found`.
+- `@tanstack/react-query` floor raised to `^5.104.1` (one copy shared with records).
+
+### Consumer action
+
+A host that implemented `AppletHost.data` itself returns `RecordsResult` with a `RecordsErrorCode`;
+a memory-host `refuse` callback drops `retryable`; code matching optimistic ids looks for `pending-`
+(was `optimistic:`). Applet code using §2 hooks needs no change.
+
+## 0.1.1
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/applets/vnull..npm/applets/v0.1.1 -- apps/shared/applets`).
+No source changes intended and no consumer action required.
+
+## 0.1.0 — 2026-10-06
+
+First release (Applets AP-0, CONTRACTS v2 §0–§4, §6, §8).
+
+- `@ai-matrx/applets`: the types this package owns (`Result`, `AppletError`, `Status`,
+  `AppletRecord`), the `AppletHost` doorway and its ports, and the event stream names
+  (`rows:<alias>`, `run:<requestId>`, `value:<name>`, `actions`, `nav`). Types owned elsewhere
+  are re-exported from their owners: `RunRef`, `ServedInput`, `RunEvent` (`@ai-matrx/agents`),
+  `ActionDeclaration`, `ActionInfo`, `ActionContext`, `SurfacePort` (`@ai-matrx/alchemy`),
+  `ScopeSpec` (`@ai-matrx/code-runtime`), `EntityRef`, `Uuid` (`@ai-matrx/records`). `Column`,
+  `Row`, `Values`, `Query`, `Page` and `DataPort` are AP-3's and are written structurally here
+  until `@ai-matrx/records` exports them.
+- `/host`: `createMemoryHost(spec)` — every port over in-memory data; announces itself
+  (`kind: "memory"`).
+- `/react`: `AppletFrame`, `useRows`, `useRow`, `useColumns`, `useSources`, `useJob`, `useJobs`,
+  `useValue`, `useAction`, `defineActions`, `usePage`, `navigate`, `Link`, `Pages`, `Applet`,
+  `Kind`, `DataPage`, on TanStack Query.
+- `/frame`: `mountApplet(record, host, scope)` / `mountAppletAsync` — compile a stored
+  multi-file record through `@ai-matrx/code-runtime` and render it in its frame.
+
+### Consumer action
+
+- None yet: matrx-frontend adopts this package with the in-page host (AP-0's next step).
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @ai-matrx/applets
+
+Applets are custom interfaces an agent builds on a person's own data and the platform's
+features. This package is the doorway between an Applet and whatever hosts it.
+
+| Entry | What it is |
+|---|---|
+| `@ai-matrx/applets` | The contract types and the `AppletHost` interface. No React. |
+| `@ai-matrx/applets/host` | `createMemoryHost(spec)` — an in-memory host for tests and development. |
+| `@ai-matrx/applets/react` | What Applet code imports: `useRows`, `useJob`, `useValue`, `useAction`, `Pages`, … |
+| `@ai-matrx/applets/platform` | `createPlatformHost(opts)` — the real host over the live platform; every client injected. |
+| `@ai-matrx/applets/frame` | `mountApplet(record, host, scope)` — compile a stored Applet and render it. |
+
+```tsx
+import { createMemoryHost } from "@ai-matrx/applets/host";
+import { mountApplet } from "@ai-matrx/applets/frame";
+
+const host = createMemoryHost({ record, tables: { posts: { columns, rows } } });
+const mounted = mountApplet(record, host, { entries: [], shadowDangerousGlobals: true });
+if (mounted.ok) root.render(<mounted.Component />);
+```
+
+Inside an Applet:
+
+```tsx
+import { useRows, useJob, Pages } from "@ai-matrx/applets/react";
+
+export default function Posts() {
+  const { rows, update, error } = useRows("posts");          // optimistic, versioned writes
+  const draft = useJob("draft");                              // a declared job, by alias
+  return <ul>{rows.map((r) => <li key={r._id}>{String(r.title)}</li>)}</ul>;
+}
+```
+
+Hooks never throw: each answers a `status` and an `error` carrying the system's own sentence.
+React and React DOM are peer dependencies. The contract this implements is
+`common-docs/projects/applets/CONTRACTS.md` (v2).

package/dist/context-Dz3PWsJd.d.cts

@@ -0,0 +1,193 @@
+import * as React from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { Uuid as Uuid$1 } from '@ai-matrx/records';
+import { IntelligencePort as IntelligencePort$1 } from '@ai-matrx/agents/intelligence';
+import { SurfacePort as SurfacePort$1, ActionContext } from '@ai-matrx/alchemy/actions';
+import { ScopeSpec } from '@ai-matrx/code-runtime';
+import { DataPort, DataSource } from '@ai-matrx/records/data';
+
+/**
+ * The Applets contract types (CONTRACTS v2 §0, §1, §3, §4, §6, §8).
+ *
+ * One owner per type. Types another package owns are RE-EXPORTED from it,
+ * never redefined; types whose owner has not exported them yet are written
+ * here structurally, each naming its owner and contract section, and are
+ * replaced by a re-export the release the owner ships them.
+ *
+ * Framework-free: no React, no runtime imports. Every import below is a type.
+ */
+
+/** `@ai-matrx/records` — a UUID string. */
+type Uuid = Uuid$1;
+/**
+ * The system's own sentence. Superset of `RecordsError` in the sense of the
+ * contract: `code` + the store's `message`, plus `retryable`.
+ */
+interface AppletError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    diagnostic?: string;
+}
+/** Never throws: every port call and every hook write answers one of these. */
+type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: AppletError;
+};
+type Status = "idle" | "loading" | "ready" | "saving" | "error";
+
+/** One source an Applet declared (CONTRACTS §2 `useSources`, §4 `sources()`) — records' `DataSource`. */
+type SourceInfo = DataSource;
+
+/**
+ * CONTRACTS §3 `IntelligencePort` (owner `@ai-matrx/agents`, AP-1) as a host
+ * port: the agents package's port minus its in-process `events` listener —
+ * across the doorway, run events arrive on the host's `run:<requestId>`
+ * stream instead (no port takes a function).
+ */
+type IntelligencePort = Omit<IntelligencePort$1, "events">;
+/** CONTRACTS §6 `SurfacePort` (owner `@ai-matrx/alchemy`, AP-2). Events: `value:<name>`. */
+type SurfacePort = SurfacePort$1;
+interface AppletPage {
+    path: string;
+    title: string;
+    file: string;
+    parent?: string;
+}
+interface AppletMandate {
+    alias: string;
+    key: string;
+}
+type AppletSource = {
+    alias: string;
+    table_id: Uuid;
+    organization_id: Uuid;
+} | {
+    alias: string;
+    entity: string;
+};
+/** CONTRACTS §8 `AppletRecord` (owner `@ai-matrx/applets`, AP-0). */
+interface AppletRecord {
+    id: Uuid;
+    version: number;
+    organizationId: Uuid;
+    slug: string;
+    published: boolean;
+    files: Record<string, string>;
+    entry: string;
+    scope: ScopeSpec;
+    pages: AppletPage[];
+    mandates: AppletMandate[];
+    sources: AppletSource[];
+    parentId: Uuid | null;
+    /** `applets/<id>` */
+    surfaceName: string;
+}
+interface Viewer {
+    userId: Uuid | null;
+    organizationIds: Uuid[];
+    activeOrganizationId: Uuid | null;
+    guest: boolean;
+}
+interface NavLocation {
+    path: string[];
+    params: Record<string, string>;
+}
+interface KindComponentSource {
+    files: Record<string, string>;
+    entry: string;
+}
+/**
+ * CONTRACTS §1 `AppletHost`. Every call is an async request with JSON in and
+ * JSON out (kind envelopes allowed), scoped to ONE mounted Applet.
+ */
+interface AppletHost {
+    viewer(): Promise<Viewer>;
+    record(): Promise<AppletRecord>;
+    child(appletId: Uuid): Promise<{
+        hostId: string;
+    }>;
+    kinds: {
+        definition(slug: string): Promise<Result<unknown>>;
+        component(slug: string, platform: string): Promise<Result<KindComponentSource | null>>;
+    };
+    pages: {
+        definition(pageId: Uuid): Promise<Result<unknown>>;
+    };
+    data: DataPort;
+    intelligence: IntelligencePort;
+    surface: SurfacePort;
+    nav: {
+        go(to: string): Promise<void>;
+        current(): Promise<NavLocation>;
+    };
+    events: {
+        on(stream: string, filter: unknown): Promise<{
+            subscriptionId: string;
+        }>;
+        off(subscriptionId: string): Promise<void>;
+    };
+    reportError(err: AppletError & {
+        where: string;
+    }): Promise<void>;
+}
+/** What the frame receives for each event (CONTRACTS §1). */
+interface EventMessage {
+    subscriptionId: string;
+    payload: unknown;
+}
+/**
+ * The frame's side of the doorway: the contract's `AppletHost` plus the two
+ * things §1 says the CHANNEL supplies — receiving `{ subscriptionId, payload }`
+ * messages, and addressing a child host by the `hostId` that `child()` answered.
+ * An in-page host implements these in memory; a sandbox host maps them onto a
+ * message channel. Neither is a port: nothing here crosses the doorway as data.
+ */
+interface AppletChannel extends AppletHost {
+    readonly hostId: string;
+    /** Subscribe to every event message for this host. Returns an unsubscribe. */
+    receive(listener: (message: EventMessage) => void): () => void;
+    /** The scoped host for a `hostId` that `child()` answered. */
+    forHost(hostId: string): AppletChannel | null;
+}
+
+/**
+ * The frame: `<AppletFrame host>` and the per-frame machinery every hook reads
+ * (CONTRACTS §1–§2). One frame per mounted Applet; a nested Applet gets its own
+ * frame over the child host, sharing the parent's query cache (keys carry the
+ * hostId, so aliases never collide across nesting).
+ *
+ * The engine is TanStack Query, one QueryClient per frame tree. Rows go through
+ * ONE engine, `@ai-matrx/records/data/react`, which the frame mounts with
+ * `DataPortProvider` (port `host.data`, events `host.events`, portKey `hostId`).
+ */
+
+type PageActionHandler = (input: unknown, ctx: ActionContext) => unknown | Promise<unknown>;
+interface FrameRenderers {
+    /** Renders a kind envelope's data. The real one comes from `@ai-matrx/content-ir-react`. */
+    renderKind?: (kind: string, value: unknown) => React.ReactNode;
+    /** Renders a table-built page from its `pages.definition`. */
+    renderDataPage?: (id: string, definition: unknown) => React.ReactNode;
+    /** Renders a nested Applet over its child host (`mountApplet` supplies this). */
+    renderApplet?: (child: AppletChannel) => React.ReactNode;
+    /** The component for one of the record's page files (`mountApplet` supplies this). */
+    pageComponent?: (file: string) => React.ComponentType<Record<string, unknown>> | null;
+}
+declare function newQueryClient(): QueryClient;
+interface AppletFrameProps extends FrameRenderers {
+    host: AppletChannel;
+    /** Defaults to the parent frame's client, else a new one for this frame. */
+    queryClient?: QueryClient;
+    children?: React.ReactNode;
+}
+/**
+ * Mounts one Applet: provides its host to every hook below, joins its surface
+ * to the runtime chain (`applets/<id>` under the parent frame's surface), and
+ * routes page-Action runs to the handlers `defineActions` registered.
+ */
+declare function AppletFrame({ host, queryClient, children, ...renderers }: AppletFrameProps): React.ReactElement;
+
+export { type AppletError as A, type FrameRenderers as F, type PageActionHandler as P, type Result as R, type Status as S, type Uuid as U, type AppletRecord as a, type AppletChannel as b, type SourceInfo as c, type AppletPage as d, AppletFrame as e, type AppletFrameProps as f, newQueryClient as n };

package/dist/context-Dz3PWsJd.d.ts

@@ -0,0 +1,193 @@
+import * as React from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { Uuid as Uuid$1 } from '@ai-matrx/records';
+import { IntelligencePort as IntelligencePort$1 } from '@ai-matrx/agents/intelligence';
+import { SurfacePort as SurfacePort$1, ActionContext } from '@ai-matrx/alchemy/actions';
+import { ScopeSpec } from '@ai-matrx/code-runtime';
+import { DataPort, DataSource } from '@ai-matrx/records/data';
+
+/**
+ * The Applets contract types (CONTRACTS v2 §0, §1, §3, §4, §6, §8).
+ *
+ * One owner per type. Types another package owns are RE-EXPORTED from it,
+ * never redefined; types whose owner has not exported them yet are written
+ * here structurally, each naming its owner and contract section, and are
+ * replaced by a re-export the release the owner ships them.
+ *
+ * Framework-free: no React, no runtime imports. Every import below is a type.
+ */
+
+/** `@ai-matrx/records` — a UUID string. */
+type Uuid = Uuid$1;
+/**
+ * The system's own sentence. Superset of `RecordsError` in the sense of the
+ * contract: `code` + the store's `message`, plus `retryable`.
+ */
+interface AppletError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    diagnostic?: string;
+}
+/** Never throws: every port call and every hook write answers one of these. */
+type Result<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: AppletError;
+};
+type Status = "idle" | "loading" | "ready" | "saving" | "error";
+
+/** One source an Applet declared (CONTRACTS §2 `useSources`, §4 `sources()`) — records' `DataSource`. */
+type SourceInfo = DataSource;
+
+/**
+ * CONTRACTS §3 `IntelligencePort` (owner `@ai-matrx/agents`, AP-1) as a host
+ * port: the agents package's port minus its in-process `events` listener —
+ * across the doorway, run events arrive on the host's `run:<requestId>`
+ * stream instead (no port takes a function).
+ */
+type IntelligencePort = Omit<IntelligencePort$1, "events">;
+/** CONTRACTS §6 `SurfacePort` (owner `@ai-matrx/alchemy`, AP-2). Events: `value:<name>`. */
+type SurfacePort = SurfacePort$1;
+interface AppletPage {
+    path: string;
+    title: string;
+    file: string;
+    parent?: string;
+}
+interface AppletMandate {
+    alias: string;
+    key: string;
+}
+type AppletSource = {
+    alias: string;
+    table_id: Uuid;
+    organization_id: Uuid;
+} | {
+    alias: string;
+    entity: string;
+};
+/** CONTRACTS §8 `AppletRecord` (owner `@ai-matrx/applets`, AP-0). */
+interface AppletRecord {
+    id: Uuid;
+    version: number;
+    organizationId: Uuid;
+    slug: string;
+    published: boolean;
+    files: Record<string, string>;
+    entry: string;
+    scope: ScopeSpec;
+    pages: AppletPage[];
+    mandates: AppletMandate[];
+    sources: AppletSource[];
+    parentId: Uuid | null;
+    /** `applets/<id>` */
+    surfaceName: string;
+}
+interface Viewer {
+    userId: Uuid | null;
+    organizationIds: Uuid[];
+    activeOrganizationId: Uuid | null;
+    guest: boolean;
+}
+interface NavLocation {
+    path: string[];
+    params: Record<string, string>;
+}
+interface KindComponentSource {
+    files: Record<string, string>;
+    entry: string;
+}
+/**
+ * CONTRACTS §1 `AppletHost`. Every call is an async request with JSON in and
+ * JSON out (kind envelopes allowed), scoped to ONE mounted Applet.
+ */
+interface AppletHost {
+    viewer(): Promise<Viewer>;
+    record(): Promise<AppletRecord>;
+    child(appletId: Uuid): Promise<{
+        hostId: string;
+    }>;
+    kinds: {
+        definition(slug: string): Promise<Result<unknown>>;
+        component(slug: string, platform: string): Promise<Result<KindComponentSource | null>>;
+    };
+    pages: {
+        definition(pageId: Uuid): Promise<Result<unknown>>;
+    };
+    data: DataPort;
+    intelligence: IntelligencePort;
+    surface: SurfacePort;
+    nav: {
+        go(to: string): Promise<void>;
+        current(): Promise<NavLocation>;
+    };
+    events: {
+        on(stream: string, filter: unknown): Promise<{
+            subscriptionId: string;
+        }>;
+        off(subscriptionId: string): Promise<void>;
+    };
+    reportError(err: AppletError & {
+        where: string;
+    }): Promise<void>;
+}
+/** What the frame receives for each event (CONTRACTS §1). */
+interface EventMessage {
+    subscriptionId: string;
+    payload: unknown;
+}
+/**
+ * The frame's side of the doorway: the contract's `AppletHost` plus the two
+ * things §1 says the CHANNEL supplies — receiving `{ subscriptionId, payload }`
+ * messages, and addressing a child host by the `hostId` that `child()` answered.
+ * An in-page host implements these in memory; a sandbox host maps them onto a
+ * message channel. Neither is a port: nothing here crosses the doorway as data.
+ */
+interface AppletChannel extends AppletHost {
+    readonly hostId: string;
+    /** Subscribe to every event message for this host. Returns an unsubscribe. */
+    receive(listener: (message: EventMessage) => void): () => void;
+    /** The scoped host for a `hostId` that `child()` answered. */
+    forHost(hostId: string): AppletChannel | null;
+}
+
+/**
+ * The frame: `<AppletFrame host>` and the per-frame machinery every hook reads
+ * (CONTRACTS §1–§2). One frame per mounted Applet; a nested Applet gets its own
+ * frame over the child host, sharing the parent's query cache (keys carry the
+ * hostId, so aliases never collide across nesting).
+ *
+ * The engine is TanStack Query, one QueryClient per frame tree. Rows go through
+ * ONE engine, `@ai-matrx/records/data/react`, which the frame mounts with
+ * `DataPortProvider` (port `host.data`, events `host.events`, portKey `hostId`).
+ */
+
+type PageActionHandler = (input: unknown, ctx: ActionContext) => unknown | Promise<unknown>;
+interface FrameRenderers {
+    /** Renders a kind envelope's data. The real one comes from `@ai-matrx/content-ir-react`. */
+    renderKind?: (kind: string, value: unknown) => React.ReactNode;
+    /** Renders a table-built page from its `pages.definition`. */
+    renderDataPage?: (id: string, definition: unknown) => React.ReactNode;
+    /** Renders a nested Applet over its child host (`mountApplet` supplies this). */
+    renderApplet?: (child: AppletChannel) => React.ReactNode;
+    /** The component for one of the record's page files (`mountApplet` supplies this). */
+    pageComponent?: (file: string) => React.ComponentType<Record<string, unknown>> | null;
+}
+declare function newQueryClient(): QueryClient;
+interface AppletFrameProps extends FrameRenderers {
+    host: AppletChannel;
+    /** Defaults to the parent frame's client, else a new one for this frame. */
+    queryClient?: QueryClient;
+    children?: React.ReactNode;
+}
+/**
+ * Mounts one Applet: provides its host to every hook below, joins its surface
+ * to the runtime chain (`applets/<id>` under the parent frame's surface), and
+ * routes page-Action runs to the handlers `defineActions` registered.
+ */
+declare function AppletFrame({ host, queryClient, children, ...renderers }: AppletFrameProps): React.ReactElement;
+
+export { type AppletError as A, type FrameRenderers as F, type PageActionHandler as P, type Result as R, type Status as S, type Uuid as U, type AppletRecord as a, type AppletChannel as b, type SourceInfo as c, type AppletPage as d, AppletFrame as e, type AppletFrameProps as f, newQueryClient as n };