@marinoscar/platform-web 0.0.0-stage → 0.1.0-next.4

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @marinoscar/platform-web
 
-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.
+The React side of the platform: pages, components and hooks built on MUI, exposed one subpath per slice. ESM with `sideEffects: false`; it loads in plain Node ESM as well as through a bundler.
+
+## Purpose and scope
+
+Pages, components, hooks and settings-page descriptors of the platform's web slices. It does not own the app's router or settings registries; the app binds the package's descriptors into its own. The app's theme is the app's: the shell slice offers one to build on (`createShellTheme`).
+
+Status: pre-release (the current channel and how to install it: the [release runbook](../../docs/runbooks/release-platform-packages.md)). The root export is only the package name (`PLATFORM_PACKAGE`); the slices are subpath exports, each with its own README:
+
+- `@marinoscar/platform-web/core`: the web host ports every packaged page reuses (`PlatformHostProvider`, `PlatformApiClient`, `PlatformViewer`, `PlatformSettingsPage`). [README](src/core/README.md).
+- `@marinoscar/platform-web/testing`: test doubles for those ports (`createTestPlatformHost`). [README](src/testing/README.md).
+- `@marinoscar/platform-web/doctor/headless` and `@marinoscar/platform-web/doctor/ui`: the admin Doctor page, its hook and client, and its settings-page descriptor (#696). [README](src/doctor/README.md).
+- `@marinoscar/platform-web/telemetry/headless` and `@marinoscar/platform-web/telemetry/ui` (plus `/telemetry/ui/settings-page`, `/explorer-page`, `/dashboard-page`): the telemetry settings page, explorer and dashboard, their client, hooks, app adapters, admin cards and theme-token contract (#704). [README](src/telemetry/README.md).
+- `@marinoscar/platform-web/identity/headless` and `@marinoscar/platform-web/identity/ui`: the auth context and route guards, the identity client and data hooks, the sign-in provider registry, and the login, callback, device-activation, Access Tokens, Users & Allowlist and organization pages with their registry entries (#727). [README](src/identity/README.md).
+- `@marinoscar/platform-web/settings/headless` and `@marinoscar/platform-web/settings/ui`: `SettingsHub`, the section registry's types and helpers, the open feature registry (`registerSettingsFeature`) and the settings hooks (`useSystemSettings`, `useUserSettings`, `useOrgSettings`) (#733). [README](src/settings/README.md).
+- `@marinoscar/platform-web/sharing/headless` and `@marinoscar/platform-web/sharing/ui`: the sharing hooks and client (groups, members, invites, grants, link grants, shared with me, the public link), the link-renderer registry, the share dialog, the group pages, the public `/s` page and the groups settings-page descriptor (#731). [README](src/sharing/README.md).
+- `@marinoscar/platform-web/credentials/headless` and `@marinoscar/platform-web/credentials/ui`: the write-only secret field `SecretField` and its unified helper text `savedSecretHelperText` (#735). [README](src/credentials/README.md).
+- `@marinoscar/platform-web/onboarding/headless` and `@marinoscar/platform-web/onboarding/ui`: `OnboardingProvider` and `useOnboarding`, the welcome dialog, the checklist, the Setup guide and Getting started pages, the Activation section, `FeatureUnavailableNotice` and its registry, and the "Getting started" menu item (#745). [README](src/onboarding/README.md).
+- `@marinoscar/platform-web/email/headless` and `@marinoscar/platform-web/email/ui`: the email settings hook `useEmailSettings` and the `/admin/settings/email` page `EmailSettingsPage` (#737). [README](src/email/README.md).
+- `@marinoscar/platform-web/jobs/headless` and `@marinoscar/platform-web/jobs/ui`: the job queue client, hooks and adapters, and the Jobs and Job Insights pages with their registry entries (#854); it re-exports the worker-fleet names of the nodes slice. [README](src/jobs/README.md).
+- `@marinoscar/platform-web/nodes/headless` and `@marinoscar/platform-web/nodes/ui`: the worker-fleet and node-credential client, hooks and adapters, and the Worker Nodes page with its registry entry (#881). [README](src/nodes/README.md).
+- `@marinoscar/platform-web/storage/headless` and `@marinoscar/platform-web/storage/ui`: the storage config hook `useStorageConfig`, the storage-config and objects clients, and the `/admin/settings/storage` page `StorageConfigPage` with its switch dialog (#736). [README](src/storage/README.md).
+- `@marinoscar/platform-web/exports/headless` and `@marinoscar/platform-web/exports/ui`: the exports client and hooks (`useExportSources`, `useExports`, `useCreateExport`, `useExport` with polling), `ExportDialog` (fields from the source's descriptor, `slots.form`), `ExportsList`, `DataExportPage` and the "Download your data" card descriptor (#744). [README](src/exports/README.md).
+- `@marinoscar/platform-web/ai/headless` and `@marinoscar/platform-web/ai/ui`: the organization's own AI keys and effective AI policy hooks (`useOrgAiKeys`, `useOrgAiPolicy`) and the Organization AI keys page `OrgAiKeysPage` (#739). [README](src/ai/README.md).
+- `@marinoscar/platform-web/db-backup/headless` and `@marinoscar/platform-web/db-backup/ui`: the db-backup client `createDbBackupApi`, the hooks `useDbBackupConfig` / `useDbBackupRuns` / `useDbBackupActions`, and the `/admin/settings/db-backup` page `DbBackupPage` with its admin card `dbBackupAdminSections` (#740). [README](src/db-backup/README.md).
+- `@marinoscar/platform-web/notifications/headless` and `@marinoscar/platform-web/notifications/ui`: the notification provider and hooks, the push subscription services, the service-worker helpers, the AppBar bell, the permission banner, the preferences matrix and the user, admin policy, Web Push and Broadcasts pages. [README](src/notifications/README.md).
+- `@marinoscar/platform-web/android-app/headless` and `@marinoscar/platform-web/android-app/ui`: the Trusted Web Activity launch helpers, the Android client and hooks, the update banner and the admin Android app page. [README](src/android-app/README.md).
+- `@marinoscar/platform-web/user-data/headless` and `@marinoscar/platform-web/user-data/ui`: the user Danger Zone page, the admin factory reset page, the organization offboarding dialog, the typed-confirmation dialog and the start-and-poll hook. [README](src/user-data/README.md).
+- `@marinoscar/platform-web/shell/headless` and `@marinoscar/platform-web/shell/ui`: the app shell: `ShellLayout` (the five coupled breakpoint gates), `ShellAppBar`, `ShellNavigationRail` (with Console mode), `ShellBottomNav`, `ShellUserMenu`, the navigation model (`ShellNavigation`, `ShellDestination`), the rail's collapse preference, `createShellTheme` with `ShellThemeProvider` / `ShellRoot`, and `ShellProviders`, with slots for branding and navigation (#868). [README](src/shell/README.md).
+- `@marinoscar/platform-web/host/headless` and `@marinoscar/platform-web/host/ui`: the About page, the admin Maintenance page and the public maintenance screen, with the maintenance recogniser and block store, `createHostApi` and the `useAbout`, `useMaintenance` and `useMaintenanceBlock` hooks (#891). [README](src/host/README.md).
+- `@marinoscar/platform-web/datatable/headless`, `@marinoscar/platform-web/datatable/ui` and `@marinoscar/platform-web/datatable/testing`: the responsive `DataTable` (desktop grid, tablet expander, phone cards) with its filters, view bar, CSV export and bulk actions, the layout-preference port `DataTablePreferencesPort`, and the jsdom layout stubs and conformance suite (#897). [README](src/datatable/README.md).
+
+## Install and peer dependencies
+
+```bash
+npm install @marinoscar/platform-web
+```
+
+Install these in the app; the package never bundles its own copy (a second copy breaks dependency injection, hooks or theme context). Which ones depends on the slices you import: only what `core` needs is required, the rest are optional peers npm does not install for you ([the rule](../../docs/PACKAGES.md#peer-dependencies-per-slice)). Import slices by their subpath, never from the package root, which may touch any slice.
+
+Required by every slice (`core`, with the peers MUI and Emotion need in turn):
+
+| Package | Range |
+|---|---|
+| `@emotion/react` | `^11.14.0` |
+| `@emotion/styled` | `^11.14.1` |
+| `@mui/material` | `^9.1.0` |
+| `react` | `^19.2.7` |
+| `react-dom` | `^19.2.7` |
+
+Optional peers, installed for the slices that need them:
+
+| Package | Range | Needed by |
+|---|---|---|
+| `@mui/icons-material` | `^9.1.0` | every slice with a `/ui` entry (`doctor`, `identity`, `settings`, `sharing`, `onboarding`, `email`, `nodes`, `jobs`, `storage`, `notifications`, `exports`, `ai`, `db-backup`, `android-app`, `user-data`, `shell`, `host`, `datatable`, `telemetry`) |
+| `react-router-dom` | `^7.17.0` | the same slices, except `exports` and `datatable` |
+| `zod` | `^4.4.3` | `nodes`, `jobs` (and the app's own use of `@marinoscar/platform-contract`) |
+| `@mui/x-data-grid` | `^9.10.1` | `datatable/ui` and, since the AI lists use it, `ai/ui`; `telemetry/ui` |
+| `@mui/x-charts` | `^9.14.0` | `telemetry/ui` (#704) |
+| `@uiw/react-codemirror` | `^4.25.12` | `telemetry/ui` |
+| `@codemirror/lang-sql` | `^6.10.0` | `telemetry/ui` |
+| `vitest`, `vitest-axe`, `@testing-library/react`, `@testing-library/user-event` | `^4.1.8`, `^1.0.0-pre.5`, `^16.3.2`, `^14.6.1` | `datatable/testing` only |
+
+A slice also needs what the slices it depends on need (`packages/platform-slices.json`); the exact set per slice is `packages/platform-slice-peers.json`, and `node scripts/check-slice-peers.mjs --table` prints it.
+
+## Quick start
+
+Mount the app's host once, inside the auth provider, then register each packaged page as a card and a route (the reference app: [`platformHost.tsx`](../../apps/web/src/platform/platformHost.tsx), [`adminSections.tsx`](../../apps/web/src/config/adminSections.tsx)):
+
+```tsx
+<PlatformHostProvider host={host}><Layout /></PlatformHostProvider>
+
+// ADMIN_SECTIONS, appended last
+{ ...doctorSettingsPage.card, Icon: doctorSettingsPage.Icon },
+```
+
+See the [core README](src/core/README.md#registering-a-packaged-page-settings-ui-pattern).
+
+## Configuration
+
+None at the package level. `PlatformHostProvider`'s host is documented in the [core README](src/core/README.md#configuration), `DoctorPage`'s props in the [doctor README](src/doctor/README.md#configuration).
+
+## Extension-point catalog
+
+None. The root export is only the package name; the extension points live in the slice catalogs ([core](src/core/README.md#extension-point-catalog), [doctor](src/doctor/README.md#extension-point-catalog)).
+
+The extension ladder and a recipe per extension: [docs/EXTENDING.md](../../docs/EXTENDING.md).
+
+## Data
+
+None. The browser holds no data model; it reads and writes through the API.
+
+## Permissions and settings
+
+The Doctor's card and route require `system_settings:read`, the exact string `@marinoscar/platform-api/doctor` enforces ([README](src/doctor/README.md#permissions-and-settings)). Packaged pages check no permission themselves: the app's route gate does.
+
+## UI
+
+One page so far: the Doctor (`/admin/settings/doctor`), one admin registry card, one slot (`slots.Header`), and the theme tokens `palette.status.*` ([README](src/doctor/README.md#ui)).
+
+## Infra
+
+None. The package ships no deployment configuration and reads no environment variable.
+
+## Observability
+
+None. No slice logs or measures anything in the browser yet.
+
+## Security notes
+
+Pages never hold an API key and never call an AI provider from the browser; they call the API only through the app's transport (`PlatformApiClient`), and authorization stays in the API and the app's route gates.
+
+## Conformance suite
+
+None yet. The package ships no conformance suite; `runPlatformConformance()` and the suites arrive with the platform's conformance harness.
+
+## Upgrade notes
+
+None. No version has been published yet, so there is nothing to migrate from.
+
+## Troubleshooting
+
+None yet. Build and import problems common to every platform package are in [DEVELOPMENT.md § Platform packages](../../docs/DEVELOPMENT.md#platform-packages).
+
+## Links
+
+- [Platform packages spec](../../docs/specs/platform-packages.md): the extension contract and the package documentation standard
+- [Package documentation standard and checks](../../docs/PACKAGES.md): how this README, the TSDoc and the catalog are checked
+- [DEVELOPMENT.md § Platform packages](../../docs/DEVELOPMENT.md#platform-packages): build, test and lint commands

package/dist/ai/headless/adapters.d.ts

@@ -0,0 +1,55 @@
+import type { ComponentType, ReactElement, ReactNode } from 'react';
+/**
+ * What {@link AiWebAdapters.Spinner} takes.
+ *
+ * @stability experimental
+ */
+export interface AiSpinnerProps {
+    /** A whole-page wait. The AI pages never ask for one. */
+    fullScreen?: boolean;
+}
+/**
+ * What the AI pages take from the app. Every member is optional; keep the
+ * object a module constant.
+ *
+ * @example
+ * ```ts
+ * // apps/web/src/platform/aiAdapters.ts
+ * export const appAiAdapters: AiWebAdapters = { Spinner: LoadingSpinner };
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface AiWebAdapters {
+    /** The app's loading spinner. Default an MUI `CircularProgress`. */
+    Spinner?: ComponentType<AiSpinnerProps>;
+}
+/**
+ * Hands the app's {@link AiWebAdapters} to every AI page below it. Mount it
+ * once, around the signed-in shell.
+ *
+ * @param props - `adapters`: the app's adapters (a module constant); `children`: the routed tree.
+ * @returns the provider element.
+ *
+ * @example
+ * ```tsx
+ * <AiWebAdaptersProvider adapters={appAiAdapters}>{shell}</AiWebAdaptersProvider>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function AiWebAdaptersProvider(props: {
+    adapters: AiWebAdapters;
+    children: ReactNode;
+}): ReactElement;
+/**
+ * The adapters in context (an empty object without a provider).
+ *
+ * @returns the app's AI adapters.
+ *
+ * @stability experimental
+ */
+export declare function useAiWebAdapters(): AiWebAdapters;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/ai/headless/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/adapters.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,OAAO,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CACzC;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,YAAY,CAMf;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD"}

package/dist/ai/headless/adapters.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// =============================================================================
+// The AI slice's app adapters (issue #890)
+// =============================================================================
+//
+// What the AI pages need from the app beyond the platform host: the app's
+// spinner (the app owns appearance). The jobs slice's
+// `JobsWebAdaptersProvider` is the model.
+//
+// Without a provider the spinner defaults to an MUI `CircularProgress`.
+// =============================================================================
+import { createContext, useContext } from 'react';
+const NO_ADAPTERS = Object.freeze({});
+const AiWebAdaptersContext = createContext(NO_ADAPTERS);
+AiWebAdaptersContext.displayName = 'AiWebAdaptersContext';
+/**
+ * Hands the app's {@link AiWebAdapters} to every AI page below it. Mount it
+ * once, around the signed-in shell.
+ *
+ * @param props - `adapters`: the app's adapters (a module constant); `children`: the routed tree.
+ * @returns the provider element.
+ *
+ * @example
+ * ```tsx
+ * <AiWebAdaptersProvider adapters={appAiAdapters}>{shell}</AiWebAdaptersProvider>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function AiWebAdaptersProvider(props) {
+    return (_jsx(AiWebAdaptersContext.Provider, { value: props.adapters, children: props.children }));
+}
+/**
+ * The adapters in context (an empty object without a provider).
+ *
+ * @returns the app's AI adapters.
+ *
+ * @stability experimental
+ */
+export function useAiWebAdapters() {
+    return useContext(AiWebAdaptersContext);
+}
+//# sourceMappingURL=adapters.js.map

package/dist/ai/headless/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../../src/ai/headless/adapters.tsx"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,2CAA2C;AAC3C,gFAAgF;AAChF,EAAE;AACF,0EAA0E;AAC1E,sDAAsD;AACtD,0CAA0C;AAC1C,EAAE;AACF,wEAAwE;AACxE,gFAAgF;AAEhF,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AA+BlD,MAAM,WAAW,GAAkB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAErD,MAAM,oBAAoB,GAAG,aAAa,CAAgB,WAAW,CAAC,CAAC;AACvE,oBAAoB,CAAC,WAAW,GAAG,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAGrC;IACC,OAAO,CACL,KAAC,oBAAoB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,YACjD,KAAK,CAAC,QAAQ,GACe,CACjC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,CAAC,oBAAoB,CAAC,CAAC;AAC1C,CAAC"}

package/dist/ai/headless/ai-config-provider.d.ts

@@ -0,0 +1,26 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { AiHookOptions } from './use-ai-api.js';
+/**
+ * Fetches `GET /ai/config` once and shares the answer with every
+ * {@link useAiConfig} and {@link useAiFeatures} below it, so the navigation
+ * chrome and every routed page read one answer. Mount it inside the
+ * authenticated shell (the endpoint needs a session) and around the layout.
+ *
+ * It usually sits ABOVE the `PlatformHostProvider` (the host reads the feature
+ * map this provider holds), so give it the app's transport as `api`.
+ *
+ * @param props - `api`: the transport (a module constant); `children`: the shell.
+ * @returns the provider element.
+ *
+ * @example
+ * ```tsx
+ * <AiConfigProvider api={appPlatformApi}>{shell}</AiConfigProvider>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function AiConfigProvider(props: AiHookOptions & {
+    children: ReactNode;
+}): ReactElement;
+//# sourceMappingURL=ai-config-provider.d.ts.map

package/dist/ai/headless/ai-config-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-config-provider.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/ai-config-provider.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,GAAG,YAAY,CAG7F"}

package/dist/ai/headless/ai-config-provider.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { AiConfigContext, useAiConfigQuery } from './use-ai-config.js';
+/**
+ * Fetches `GET /ai/config` once and shares the answer with every
+ * {@link useAiConfig} and {@link useAiFeatures} below it, so the navigation
+ * chrome and every routed page read one answer. Mount it inside the
+ * authenticated shell (the endpoint needs a session) and around the layout.
+ *
+ * It usually sits ABOVE the `PlatformHostProvider` (the host reads the feature
+ * map this provider holds), so give it the app's transport as `api`.
+ *
+ * @param props - `api`: the transport (a module constant); `children`: the shell.
+ * @returns the provider element.
+ *
+ * @example
+ * ```tsx
+ * <AiConfigProvider api={appPlatformApi}>{shell}</AiConfigProvider>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function AiConfigProvider(props) {
+    const value = useAiConfigQuery(props.api === undefined ? {} : { api: props.api });
+    return _jsx(AiConfigContext.Provider, { value: value, children: props.children });
+}
+//# sourceMappingURL=ai-config-provider.js.map

package/dist/ai/headless/ai-config-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-config-provider.js","sourceRoot":"","sources":["../../../src/ai/headless/ai-config-provider.tsx"],"names":[],"mappings":";AAKA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGvE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA8C;IAC7E,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IAClF,OAAO,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,KAAK,CAAC,QAAQ,GAA4B,CAAC;AAC7F,CAAC"}

package/dist/ai/headless/capability-labels.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Teaches the pages the label of one capability an app registered
+ * (`registerAiCapability` on the API). Call it at module scope, before the
+ * pages render. A later call for the same id replaces the label.
+ *
+ * @param id - the capability id (`speaker_diarization`).
+ * @param label - the short label the pages show (`Diarization`).
+ *
+ * @example
+ * ```ts
+ * registerAiCapabilityLabel('speaker_diarization', 'Diarization');
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerAiCapabilityLabel(id: string, label: string): void;
+/**
+ * Records the labels the API reported (what `useAiCapabilities` does after a fetch).
+ *
+ * @param descriptors - `GET /admin/ai/capabilities`'s `capabilities`.
+ *
+ * @stability experimental
+ */
+export declare function registerAiCapabilityLabels(descriptors: ReadonlyArray<{
+    id: string;
+    label: string;
+}>): void;
+/**
+ * The label registered for `id`, or `undefined`.
+ *
+ * @param id - the capability id.
+ *
+ * @stability experimental
+ */
+export declare function getRegisteredAiCapabilityLabel(id: string): string | undefined;
+/**
+ * Forgets every registered label (tests only).
+ *
+ * @internal
+ */
+export declare function resetAiCapabilityLabelsForTests(): void;
+//# sourceMappingURL=capability-labels.d.ts.map

package/dist/ai/headless/capability-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-labels.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/capability-labels.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAE1G;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}

package/dist/ai/headless/capability-labels.js

@@ -0,0 +1,69 @@
+// =============================================================================
+// Labels of the capabilities an app registered (PP-14.17, issue #935)
+// =============================================================================
+//
+// The capability vocabulary is open: an app adds `speaker_diarization` with
+// `registerAiCapability` on the API, and a model can then declare it. The web
+// draws a capability as its LABEL (chips, filters, the override dialog), and
+// must not need a code change to do it, so the labels come from two places:
+//
+//   - the API: `GET /api/admin/ai/capabilities`, which the admin pages fetch
+//     (`useAiCapabilities`) and record here;
+//   - the app: `registerAiCapabilityLabel('speaker_diarization', 'Diarization')`
+//     at module scope, for a page a viewer without `ai_config:read` sees (the
+//     Playground and the user pages cannot read the admin route).
+//
+// A capability with neither renders as its id: it never vanishes. The built-in
+// fourteen are labelled in `ui/shared/aiCapabilities.ts` and never overridden here.
+// =============================================================================
+const labels = new Map();
+/**
+ * Teaches the pages the label of one capability an app registered
+ * (`registerAiCapability` on the API). Call it at module scope, before the
+ * pages render. A later call for the same id replaces the label.
+ *
+ * @param id - the capability id (`speaker_diarization`).
+ * @param label - the short label the pages show (`Diarization`).
+ *
+ * @example
+ * ```ts
+ * registerAiCapabilityLabel('speaker_diarization', 'Diarization');
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export function registerAiCapabilityLabel(id, label) {
+    if (id && label)
+        labels.set(id, label);
+}
+/**
+ * Records the labels the API reported (what `useAiCapabilities` does after a fetch).
+ *
+ * @param descriptors - `GET /admin/ai/capabilities`'s `capabilities`.
+ *
+ * @stability experimental
+ */
+export function registerAiCapabilityLabels(descriptors) {
+    for (const descriptor of descriptors)
+        registerAiCapabilityLabel(descriptor.id, descriptor.label);
+}
+/**
+ * The label registered for `id`, or `undefined`.
+ *
+ * @param id - the capability id.
+ *
+ * @stability experimental
+ */
+export function getRegisteredAiCapabilityLabel(id) {
+    return labels.get(id);
+}
+/**
+ * Forgets every registered label (tests only).
+ *
+ * @internal
+ */
+export function resetAiCapabilityLabelsForTests() {
+    labels.clear();
+}
+//# sourceMappingURL=capability-labels.js.map

package/dist/ai/headless/capability-labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-labels.js","sourceRoot":"","sources":["../../../src/ai/headless/capability-labels.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,sEAAsE;AACtE,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,4EAA4E;AAC5E,EAAE;AACF,6EAA6E;AAC7E,6CAA6C;AAC7C,iFAAiF;AACjF,8EAA8E;AAC9E,kEAAkE;AAClE,EAAE;AACF,+EAA+E;AAC/E,oFAAoF;AACpF,gFAAgF;AAEhF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,yBAAyB,CAAC,EAAU,EAAE,KAAa;IACjE,IAAI,EAAE,IAAI,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,WAAyD;IAClG,KAAK,MAAM,UAAU,IAAI,WAAW;QAAE,yBAAyB,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;AACnG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B,CAAC,EAAU;IACvD,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B;IAC7C,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC"}

package/dist/ai/headless/chat-attachments.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Chat attachments — issue #445 (API: #441, docs/specs/ai-platform.md §2.9).
+ *
+ * A chat turn may carry the caller's own storage objects as `image`/`file`
+ * content parts, named by `storageObjectId`. The rules mirror the API's
+ * (`apps/api/src/ai/core/types/file-inputs.types.ts`) so a request the API
+ * would refuse is caught before anything is uploaded:
+ *
+ * - MODALITY FOLLOWS THE MIME TYPE, not the button used: PNG/JPEG/GIF/WebP is
+ *   an image and needs `vision_input`; anything else is a file and needs
+ *   `file_input` — each in the model's `capabilities` AND `inputModalities`.
+ * - Images at most 20 MiB, files at most 50 MiB, at most 16 per request.
+ *
+ * The API re-checks all of it; these checks exist so the user learns before
+ * waiting for an upload, not instead of the server's answer.
+ */
+import type { AiContentPart, AiInputItem, UsableAiModel } from './types.js';
+import type { AiErrorInfo } from './errors.js';
+/**
+ * The AI chat image mime types.
+ *
+ * @stability experimental
+ */
+export declare const AI_CHAT_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+/**
+ * The largest image a chat turn may reference (20 MiB).
+ *
+ * @stability experimental
+ */
+export declare const AI_CHAT_IMAGE_MAX_BYTES: number;
+/**
+ * The largest non-image file a chat turn may reference (50 MiB).
+ *
+ * @stability experimental
+ */
+export declare const AI_CHAT_FILE_MAX_BYTES: number;
+/**
+ * The most attachments one turn may carry.
+ *
+ * @stability experimental
+ */
+export declare const AI_CHAT_ATTACHMENTS_MAX = 16;
+/**
+ * The AI attachment kind type.
+ *
+ * @stability experimental
+ */
+export type AiAttachmentKind = 'image' | 'file';
+/**
+ * An attachment once uploaded — what a sent message remembers.
+ *
+ * @stability experimental
+ */
+export interface AiChatAttachment {
+    /** The storage object id. */
+    storageObjectId: string;
+    /** The name. */
+    name: string;
+    /** The mime type. */
+    mimeType: string;
+    /** Bytes. */
+    size: number;
+    /** Which variant this is (the discriminator). */
+    kind: AiAttachmentKind;
+}
+/**
+ * The kind a file is sent as, decided by its MIME type (the API's rule).
+ *
+ * @stability experimental
+ */
+export declare function attachmentKind(mimeType: string): AiAttachmentKind;
+/**
+ * Which kinds `model` can read — capability AND input modality, as the API requires.
+ *
+ * @stability experimental
+ */
+export declare function attachableKinds(model: UsableAiModel | null | undefined): Record<AiAttachmentKind, boolean>;
+/**
+ * Format bytes.
+ *
+ * @stability experimental
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Why `file` cannot be attached for `model`, or `null` when it can.
+ *
+ * @stability experimental
+ */
+export declare function attachmentProblem(file: File, model: UsableAiModel | null | undefined): string | null;
+/**
+ * The content part for one uploaded attachment.
+ *
+ * @stability experimental
+ */
+export declare function attachmentPart(attachment: AiChatAttachment): AiContentPart;
+/**
+ * The request `input` for a turn: the plain prompt string when nothing is
+ * attached (unchanged from #434), otherwise one user message with the text
+ * first and each attachment after it.
+ 
+ *
+ * @stability experimental
+ */
+export declare function chatTurnInput(text: string, attachments: readonly AiChatAttachment[]): string | AiInputItem[];
+/**
+ * A failed turn that carried attachments, explained. The API answers an
+ * attachment that no longer exists with a plain 404, and one that is not
+ * the caller's with a plain 403 (the storage API's own answers, §2.9) —
+ * neither carries an AI code, so without this they would read as a generic
+ * failure. Everything else passes through unchanged.
+ 
+ *
+ * @stability experimental
+ */
+export declare function withAttachmentContext(error: AiErrorInfo, hadAttachments: boolean): AiErrorInfo;
+//# sourceMappingURL=chat-attachments.d.ts.map

package/dist/ai/headless/chat-attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-attachments.d.ts","sourceRoot":"","sources":["../../../src/ai/headless/chat-attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,iEAK3B,CAAC;AACX;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AACxD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAmB,CAAC;AACvD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAGjE;AAcD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GACtC,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAKnC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GACtC,MAAM,GAAG,IAAI,CASf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,gBAAgB,GAAG,aAAa,CAI1E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,SAAS,gBAAgB,EAAE,GACvC,MAAM,GAAG,WAAW,EAAE,CASxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,OAAO,GAAG,WAAW,CAY9F"}