@theaiplatform/miniapp-sdk 0.0.0 → 0.0.1

package/README.md

@@ -8,8 +8,9 @@ pnpm add @theaiplatform/miniapp-sdk
 ```
 
 The package provides the host-injected SDK API, isolated surface lifecycle
-types, browser helpers, manifest schema, and the Rspack/Rslib integration used
-to produce descriptor-backed Module Federation targets.
+types, browser helpers, portable React UI components, manifest schema, and the
+Rspack/Rslib integration used to produce descriptor-backed Module Federation
+targets.
 
 Start with the [Miniapp SDK documentation](https://docs.theaiplatform.app/miniapps/).
 
@@ -18,6 +19,10 @@ Start with the [Miniapp SDK documentation](https://docs.theaiplatform.app/miniap
 - `@theaiplatform/miniapp-sdk`
 - `@theaiplatform/miniapp-sdk/sdk`
 - `@theaiplatform/miniapp-sdk/web`
+- `@theaiplatform/miniapp-sdk/ui`
+- `@theaiplatform/miniapp-sdk/ui/styles.css`
+- `@theaiplatform/miniapp-sdk/ui/tailwind.css`
+- `@theaiplatform/miniapp-sdk/ui-components.json`
 - `@theaiplatform/miniapp-sdk/surface`
 - `@theaiplatform/miniapp-sdk/config`
 - `@theaiplatform/miniapp-sdk/rspack`
@@ -25,6 +30,57 @@ Start with the [Miniapp SDK documentation](https://docs.theaiplatform.app/miniap
 
 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
+active workspace and exact package. `sdk.presence` provides host-stamped,
+ephemeral room membership and state; package code never supplies participant
+identity.
+
+## Portable UI
+
+Import the precompiled stylesheet once at the miniapp entry point, then use
+components from the public UI entry. React 19 is a peer dependency.
+
+```tsx
+import '@theaiplatform/miniapp-sdk/ui/styles.css';
+
+import {
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+} from '@theaiplatform/miniapp-sdk/ui';
+
+export function WelcomeCard() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Ready to build</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button>Continue</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+Tailwind v4 miniapps can instead import the source integration after
+`tailwindcss` and `tw-animate-css`; it supplies the platform theme and scans the
+SDK's UI bundle for component classes.
+
+```css
+@import 'tailwindcss' source(none);
+@import 'tw-animate-css';
+@import '@theaiplatform/miniapp-sdk/ui/tailwind.css';
+
+@source './src';
+```
+
+Use `installMiniAppAppearanceSync()` from the `/web` entry to apply the host's
+light/dark theme and bounded UI scale. Tools and agents can read the exported
+`ui-components.json` catalog to discover the supported component families and
+style entry points without importing application-private packages.
 
 ## License and public policies
 

package/THIRD_PARTY_NOTICES.md

@@ -2,26 +2,52 @@
 
 ## Scope
 
-The `@theaiplatform/miniapp-sdk` package tarball does not embed third-party
-package code. Its `./rspack` entry imports separately installed runtime
-dependencies. Optional peer dependencies are not distributed with this package
-and remain subject to their own licenses.
+The `@theaiplatform/miniapp-sdk` JavaScript entries import separately installed
+runtime dependencies. Its precompiled UI stylesheet is generated with
+Tailwind CSS and `tw-animate-css`; the Tailwind integration stylesheet is
+distributed as source. Optional peer dependencies are not distributed with
+this package and remain subject to their own licenses.
 
 The inventory below records the direct and transitive runtime dependency
-versions resolved by the release workspace lockfile on July 15, 2026. A
+versions resolved by the release workspace lockfile on July 16, 2026. A
 downstream application may resolve a different compatible transitive version
 and is responsible for reviewing the notices required by its own lockfile and
 distribution artifact.
 
-| Relationship     | Package                | Version | License      |
-| ---------------- | ---------------------- | ------: | ------------ |
-| Direct           | `ajv`                  |  8.20.0 | MIT          |
-| Ajv transitive   | `fast-deep-equal`      |   3.1.3 | MIT          |
-| Ajv transitive   | `fast-uri`             |   3.1.2 | BSD-3-Clause |
-| Ajv transitive   | `json-schema-traverse` |   1.0.0 | MIT          |
-| Ajv transitive   | `require-from-string`  |   2.0.2 | MIT          |
-| Direct           | `saxes`                |   6.0.0 | ISC          |
-| Saxes transitive | `xmlchars`             |   2.2.0 | MIT          |
+| Relationship     | Package                        | Version | License      |
+| ---------------- | ------------------------------ | ------: | ------------ |
+| Direct UI        | `@radix-ui/react-alert-dialog` |  1.1.15 | MIT          |
+| Direct UI        | `@radix-ui/react-checkbox`     |   1.3.3 | MIT          |
+| Direct UI        | `@radix-ui/react-compose-refs` |   1.1.2 | MIT          |
+| Direct UI        | `@radix-ui/react-dialog`       |  1.1.15 | MIT          |
+| Direct UI        | `@radix-ui/react-label`        |   2.1.8 | MIT          |
+| Direct UI        | `@radix-ui/react-progress`     |   1.1.8 | MIT          |
+| Direct UI        | `@radix-ui/react-radio-group`  |   1.3.8 | MIT          |
+| Direct UI        | `@radix-ui/react-scroll-area`  |  1.2.10 | MIT          |
+| Direct UI        | `@radix-ui/react-select`       |   2.2.6 | MIT          |
+| Direct UI        | `@radix-ui/react-separator`    |   1.1.8 | MIT          |
+| Direct UI        | `@radix-ui/react-slider`       |   1.3.6 | MIT          |
+| Direct UI        | `@radix-ui/react-slot`         |   1.2.4 | MIT          |
+| Direct UI        | `@radix-ui/react-tabs`         |  1.1.13 | MIT          |
+| Direct UI        | `@radix-ui/react-toggle`       |  1.1.10 | MIT          |
+| Direct UI        | `@radix-ui/react-toggle-group` |  1.1.11 | MIT          |
+| Direct UI        | `@radix-ui/react-tooltip`      |   1.2.8 | MIT          |
+| Direct UI        | `class-variance-authority`     |   0.7.1 | Apache-2.0   |
+| Direct UI        | `clsx`                         |   2.1.1 | MIT          |
+| Direct UI        | `lucide-react`                 |  1.20.0 | ISC          |
+| Direct UI        | `prism-react-renderer`         |   2.4.1 | MIT          |
+| Direct UI        | `react-resizable-panels`       |  4.11.1 | MIT          |
+| Direct UI        | `tailwind-merge`               |   3.6.0 | MIT          |
+| Styles build     | `@tailwindcss/postcss`         |   4.3.0 | MIT          |
+| Styles build     | `tailwindcss`                  |   4.3.0 | MIT          |
+| Styles build     | `tw-animate-css`               |   1.4.0 | MIT          |
+| Direct           | `ajv`                          |  8.20.0 | MIT          |
+| Ajv transitive   | `fast-deep-equal`              |   3.1.3 | MIT          |
+| Ajv transitive   | `fast-uri`                     |   3.1.2 | BSD-3-Clause |
+| Ajv transitive   | `json-schema-traverse`         |   1.0.0 | MIT          |
+| Ajv transitive   | `require-from-string`          |   2.0.2 | MIT          |
+| Direct           | `saxes`                        |   6.0.0 | ISC          |
+| Saxes transitive | `xmlchars`                     |   2.2.0 | MIT          |
 
 ## License texts
 

package/dist/index.d.ts

@@ -245,6 +245,8 @@ export declare type MiniAppPlatformApi = {
         open(options: OpenNavigationOptions): void | Promise<void>;
     };
     chat: MiniAppChatApi;
+    storage: MiniAppStorageApi;
+    presence: MiniAppPresenceApi;
     /** Browser capabilities appear only when the selected target supports them. */
     auth?: MiniAppAuthApi;
     vfs?: MiniAppVfsApi;
@@ -253,6 +255,41 @@ export declare type MiniAppPlatformApi = {
     hasHostHttpRequest?: boolean;
 };
 
+export declare type MiniAppPresenceAddress = {
+    namespace: string;
+    room: string;
+};
+
+/**
+ * Ephemeral realtime presence scoped by the host to the active workspace and
+ * exact package. Participant identity is stamped by the host, not the app.
+ */
+export declare type MiniAppPresenceApi = {
+    join(options: MiniAppPresenceUpdateOptions): MiniAppMaybePromise<MiniAppPresenceSnapshot>;
+    update(options: MiniAppPresenceUpdateOptions): MiniAppMaybePromise<MiniAppPresenceSnapshot>;
+    leave(options: MiniAppPresenceAddress): MiniAppMaybePromise<void>;
+    subscribe(options: MiniAppPresenceAddress, listener: MiniAppPresenceListener): () => void;
+};
+
+export declare type MiniAppPresenceListener = (snapshot: MiniAppPresenceSnapshot) => void;
+
+export declare type MiniAppPresenceParticipant = {
+    /** Host-derived, ephemeral participant identity. */
+    participantId: string;
+    displayName: string;
+    state: MiniAppJsonValue;
+    updatedAtMs: number;
+};
+
+export declare type MiniAppPresenceSnapshot = MiniAppPresenceAddress & {
+    selfParticipantId: string;
+    participants: MiniAppPresenceParticipant[];
+};
+
+export declare type MiniAppPresenceUpdateOptions = MiniAppPresenceAddress & {
+    state: MiniAppJsonValue;
+};
+
 export declare type MiniAppProject = {
     id: string;
     name: string;
@@ -352,6 +389,43 @@ export declare type MiniAppSpecialistTurnResult = {
     };
 };
 
+/** Caller-selected partition inside the host-derived workspace/package scope. */
+export declare type MiniAppStorageAddress = {
+    namespace: string;
+    key: string;
+};
+
+/**
+ * Durable, non-secret JSON storage. The host derives workspace and package
+ * identity from the authenticated frame; apps control only the namespace and
+ * key inside that scope.
+ */
+export declare type MiniAppStorageApi = {
+    get(options: MiniAppStorageAddress): MiniAppMaybePromise<MiniAppStorageEntry>;
+    set(options: MiniAppStorageSetOptions): MiniAppMaybePromise<MiniAppStorageMutationResult>;
+    delete(options: MiniAppStorageDeleteOptions): MiniAppMaybePromise<void>;
+};
+
+export declare type MiniAppStorageDeleteOptions = MiniAppStorageAddress & {
+    expectedRevision: number;
+};
+
+export declare type MiniAppStorageEntry = {
+    value: MiniAppJsonValue | null;
+    /** Null means that no value currently exists at this address. */
+    revision: number | null;
+};
+
+export declare type MiniAppStorageMutationResult = {
+    revision: number;
+};
+
+export declare type MiniAppStorageSetOptions = MiniAppStorageAddress & {
+    value: MiniAppJsonValue;
+    /** Optimistic concurrency token returned by `get`; null creates a missing key. */
+    expectedRevision: number | null;
+};
+
 export declare type MiniAppUserProfile = {
     sub: string;
     name?: string | null;

package/dist/rspack/index.js

@@ -444,8 +444,15 @@ const HOST_ACTION_RESPONSE = 'tap-miniapp-host-action-response';
 const MAX_PENDING_HOST_ACTIONS = 32;
 const MAX_CHECKPOINT_REFERENCE_CHARS = 512;
 const MAX_CHECKPOINT_JSON_BYTES = 32 * 1024;
+const MAX_STORAGE_NAMESPACE_CHARS = 128;
+const MAX_STORAGE_KEY_CHARS = 512;
+const MAX_STORAGE_JSON_BYTES = 5 * 1024 * 1024;
+const MAX_PRESENCE_ROOM_CHARS = 256;
+const MAX_PRESENCE_JSON_BYTES = 16 * 1024;
+const PRESENCE_EVENT = 'tap-miniapp-presence-event';
 const HOST_ACTION_TIMEOUT_MS = 4000;
 const pendingHostActions = new Map();
+const presenceListeners = new Map();
 let hostActionSequence = 0;
 const validCheckpointReference = (reference) =>
   typeof reference === 'string' &&
@@ -465,6 +472,24 @@ const checkedCheckpointValue = (value) => {
   }
   return value;
 };
+const validPlatformPartition = (value, maximumLength) =>
+  typeof value === 'string' &&
+  value.length > 0 &&
+  value.trim() === value &&
+  Array.from(value).length <= maximumLength &&
+  !/[\u0000-\u001f\u007f-\u009f]/u.test(value);
+const checkedPlatformJson = (value, maximumBytes, label) => {
+  let encoded;
+  try {
+    encoded = JSON.stringify(value);
+  } catch {
+    throw new Error(label + ' must be JSON serializable.');
+  }
+  if (encoded === undefined || new TextEncoder().encode(encoded).byteLength > maximumBytes) {
+    throw new Error(label + ' exceeds the allowed size.');
+  }
+  return value;
+};
 const requestHostAction = (action, payload, timeoutMs = HOST_ACTION_TIMEOUT_MS) => {
   if (pendingHostActions.size >= MAX_PENDING_HOST_ACTIONS) {
     return Promise.reject(new Error('Too many miniapp host actions are pending.'));
@@ -619,6 +644,79 @@ const invokeSdkHostAction = (action, options, label, timeoutMs = HOST_ACTION_TIM
   requestHostAction(action, {
     options: requireOptionsObject(options, label),
   }, timeoutMs);
+const checkedStorageAddress = (options, label) => {
+  requireOptionsObject(options, label);
+  if (!validPlatformPartition(options.namespace, MAX_STORAGE_NAMESPACE_CHARS)) {
+    throw new Error(label + ' requires a valid namespace.');
+  }
+  if (!validPlatformPartition(options.key, MAX_STORAGE_KEY_CHARS)) {
+    throw new Error(label + ' requires a valid key.');
+  }
+  return options;
+};
+const storage = Object.freeze({
+  get(options) {
+    checkedStorageAddress(options, 'app.storage.get');
+    return invokeSdkHostAction('tap.platform.storage.get', options, 'app.storage.get');
+  },
+  set(options) {
+    checkedStorageAddress(options, 'app.storage.set');
+    if (options.expectedRevision !== null &&
+        (!Number.isInteger(options.expectedRevision) || options.expectedRevision < 1)) {
+      throw new Error('app.storage.set expectedRevision must be null or a positive integer.');
+    }
+    checkedPlatformJson(options.value, MAX_STORAGE_JSON_BYTES, 'app.storage.set value');
+    return invokeSdkHostAction('tap.platform.storage.set', options, 'app.storage.set', 12000);
+  },
+  delete(options) {
+    checkedStorageAddress(options, 'app.storage.delete');
+    if (!Number.isInteger(options.expectedRevision) || options.expectedRevision < 1) {
+      throw new Error('app.storage.delete expectedRevision must be a positive integer.');
+    }
+    return invokeSdkHostAction('tap.platform.storage.delete', options, 'app.storage.delete');
+  },
+});
+const checkedPresenceAddress = (options, label) => {
+  requireOptionsObject(options, label);
+  if (!validPlatformPartition(options.namespace, MAX_STORAGE_NAMESPACE_CHARS)) {
+    throw new Error(label + ' requires a valid namespace.');
+  }
+  if (!validPlatformPartition(options.room, MAX_PRESENCE_ROOM_CHARS)) {
+    throw new Error(label + ' requires a valid room.');
+  }
+  return options;
+};
+const presenceKey = (options) => options.namespace + '\u0000' + options.room;
+const presence = Object.freeze({
+  join(options) {
+    checkedPresenceAddress(options, 'app.presence.join');
+    checkedPlatformJson(options.state, MAX_PRESENCE_JSON_BYTES, 'app.presence.join state');
+    return invokeSdkHostAction('tap.platform.presence.join', options, 'app.presence.join');
+  },
+  update(options) {
+    checkedPresenceAddress(options, 'app.presence.update');
+    checkedPlatformJson(options.state, MAX_PRESENCE_JSON_BYTES, 'app.presence.update state');
+    return invokeSdkHostAction('tap.platform.presence.update', options, 'app.presence.update');
+  },
+  leave(options) {
+    checkedPresenceAddress(options, 'app.presence.leave');
+    return invokeSdkHostAction('tap.platform.presence.leave', options, 'app.presence.leave');
+  },
+  subscribe(options, listener) {
+    checkedPresenceAddress(options, 'app.presence.subscribe');
+    if (typeof listener !== 'function') {
+      throw new Error('app.presence.subscribe requires a listener.');
+    }
+    const key = presenceKey(options);
+    const listeners = presenceListeners.get(key) ?? new Set();
+    listeners.add(listener);
+    presenceListeners.set(key, listeners);
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) presenceListeners.delete(key);
+    };
+  },
+});
 const channels = Object.freeze({
   create(options) {
     requireOptionString(options?.name, 'app.channels.create name');
@@ -893,6 +991,8 @@ const miniappSdk = Object.freeze({
   workflows,
   navigation,
   chat: miniappChat,
+  storage,
+  presence,
   auth: platformAuth,
   vfs: platformVfs,
   specialist: platformSpecialist,
@@ -1021,6 +1121,24 @@ const onHostMessage = async (event) => {
     }
     return;
   }
+  if (
+    message.type === PRESENCE_EVENT &&
+    validPlatformPartition(message.namespace, MAX_STORAGE_NAMESPACE_CHARS) &&
+    validPlatformPartition(message.room, MAX_PRESENCE_ROOM_CHARS) &&
+    typeof message.selfParticipantId === 'string' &&
+    Array.isArray(message.participants)
+  ) {
+    const snapshot = Object.freeze({
+      namespace: message.namespace,
+      room: message.room,
+      selfParticipantId: message.selfParticipantId,
+      participants: message.participants,
+    });
+    for (const listener of presenceListeners.get(presenceKey(snapshot)) ?? []) {
+      try { await listener(snapshot); } catch { /* isolate observer failures */ }
+    }
+    return;
+  }
   if (message.type === HOST_ACTION_RESPONSE) {
     const requestId = typeof message.id === 'string' ? message.id : '';
     const pending = pendingHostActions.get(requestId);
@@ -1141,6 +1259,7 @@ window.addEventListener('pagehide', () => {
   window.removeEventListener('message', onHostMessage);
   eventListeners.clear();
   hostAuthorityListeners.clear();
+  presenceListeners.clear();
   for (const pending of pendingHostActions.values()) {
     clearTimeout(pending.timeout);
     pending.reject(new Error('The mini app document was removed.'));

package/dist/sdk.d.ts

@@ -234,6 +234,8 @@ export declare type MiniAppPlatformApi = {
         open(options: OpenNavigationOptions): void | Promise<void>;
     };
     chat: MiniAppChatApi;
+    storage: MiniAppStorageApi;
+    presence: MiniAppPresenceApi;
     /** Browser capabilities appear only when the selected target supports them. */
     auth?: MiniAppAuthApi;
     vfs?: MiniAppVfsApi;
@@ -242,6 +244,41 @@ export declare type MiniAppPlatformApi = {
     hasHostHttpRequest?: boolean;
 };
 
+export declare type MiniAppPresenceAddress = {
+    namespace: string;
+    room: string;
+};
+
+/**
+ * Ephemeral realtime presence scoped by the host to the active workspace and
+ * exact package. Participant identity is stamped by the host, not the app.
+ */
+export declare type MiniAppPresenceApi = {
+    join(options: MiniAppPresenceUpdateOptions): MiniAppMaybePromise<MiniAppPresenceSnapshot>;
+    update(options: MiniAppPresenceUpdateOptions): MiniAppMaybePromise<MiniAppPresenceSnapshot>;
+    leave(options: MiniAppPresenceAddress): MiniAppMaybePromise<void>;
+    subscribe(options: MiniAppPresenceAddress, listener: MiniAppPresenceListener): () => void;
+};
+
+export declare type MiniAppPresenceListener = (snapshot: MiniAppPresenceSnapshot) => void;
+
+export declare type MiniAppPresenceParticipant = {
+    /** Host-derived, ephemeral participant identity. */
+    participantId: string;
+    displayName: string;
+    state: MiniAppJsonValue;
+    updatedAtMs: number;
+};
+
+export declare type MiniAppPresenceSnapshot = MiniAppPresenceAddress & {
+    selfParticipantId: string;
+    participants: MiniAppPresenceParticipant[];
+};
+
+export declare type MiniAppPresenceUpdateOptions = MiniAppPresenceAddress & {
+    state: MiniAppJsonValue;
+};
+
 export declare type MiniAppProject = {
     id: string;
     name: string;
@@ -341,6 +378,43 @@ export declare type MiniAppSpecialistTurnResult = {
     };
 };
 
+/** Caller-selected partition inside the host-derived workspace/package scope. */
+export declare type MiniAppStorageAddress = {
+    namespace: string;
+    key: string;
+};
+
+/**
+ * Durable, non-secret JSON storage. The host derives workspace and package
+ * identity from the authenticated frame; apps control only the namespace and
+ * key inside that scope.
+ */
+export declare type MiniAppStorageApi = {
+    get(options: MiniAppStorageAddress): MiniAppMaybePromise<MiniAppStorageEntry>;
+    set(options: MiniAppStorageSetOptions): MiniAppMaybePromise<MiniAppStorageMutationResult>;
+    delete(options: MiniAppStorageDeleteOptions): MiniAppMaybePromise<void>;
+};
+
+export declare type MiniAppStorageDeleteOptions = MiniAppStorageAddress & {
+    expectedRevision: number;
+};
+
+export declare type MiniAppStorageEntry = {
+    value: MiniAppJsonValue | null;
+    /** Null means that no value currently exists at this address. */
+    revision: number | null;
+};
+
+export declare type MiniAppStorageMutationResult = {
+    revision: number;
+};
+
+export declare type MiniAppStorageSetOptions = MiniAppStorageAddress & {
+    value: MiniAppJsonValue;
+    /** Optimistic concurrency token returned by `get`; null creates a missing key. */
+    expectedRevision: number | null;
+};
+
 export declare type MiniAppUserProfile = {
     sub: string;
     name?: string | null;