@cxxi-lab/hub-sdk 0.0.0-stage → 1.12.0

package/types/index.d.ts

@@ -0,0 +1,1089 @@
+// @cxxi-lab/hub-sdk 1.12.0: generated by app/scripts/emit-sdk-types.mjs from app/src/sdk — do not edit.
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { ComponentType, HTMLInputTypeAttribute, MouseEventHandler, ReactNode, TdHTMLAttributes, ThHTMLAttributes } from 'react';
+
+/**
+ * The platform contract: everything the shared UI needs from its host shell.
+ *
+ * `app/` depends only on this file; each shell provides an implementation
+ * (`electron.ts` today, a Capacitor one later). The domain types below are the
+ * single source of truth — the Electron preload imports them from here
+ * (`@hub/app/platform`) so `window.api` cannot drift from this contract.
+ */
+export type VpnStatus = "disabled" | "starting" | "connected" | "error";
+export interface VpnInfo {
+	status: VpnStatus;
+	port: number | null;
+	error: string | null;
+	endpoint: string | null;
+}
+export type UpdatePhase = "available" | "downloading" | "verifying" | "installing" | "error";
+export interface UpdateState {
+	phase: UpdatePhase;
+	version: string;
+	currentVersion: string;
+	progress: {
+		percent: number;
+		transferred: number;
+		total: number;
+		bytesPerSecond: number;
+	} | null;
+	error: string | null;
+}
+export interface IntegrationCookie {
+	name: string;
+	value: string;
+}
+export interface IntegrationReferer {
+	url: string;
+	cdnHostPattern: string;
+}
+export interface WebsiteIntegration {
+	cookies?: IntegrationCookie[];
+	referer?: IntegrationReferer;
+}
+export type CompanionEngineStatus = "off" | "starting" | "on" | "error";
+export interface CompanionEngineInfo {
+	status: CompanionEngineStatus;
+	external: boolean;
+	error: string | null;
+}
+/** One line of a conversation's activity log: what happened in the background. */
+export interface CompanionLogEntry {
+	id: number;
+	at: number;
+	level: "info" | "warn" | "error";
+	text: string;
+	/** raw text behind the line (reply, notes, scene, tags…) */
+	detail?: string;
+}
+/** What the companion is doing right now: writing, recording a voice message or taking a photo. */
+export type CompanionActivity = "typing" | "recording" | "photo" | null;
+export interface CompanionProfile {
+	/** conversation id ('main' for the first one) */
+	id: string;
+	name: string;
+	/** name shown in the app (`name` unless the profile sets another one) */
+	label: string;
+	userName: string;
+	/** media file of the profile picture */
+	avatar: string | null;
+}
+export interface CompanionMessage {
+	id: number;
+	role: "user" | "companion";
+	kind: "text" | "image" | "audio";
+	content: string;
+	mediaPath: string | null;
+	createdAt: number;
+	readAt: number | null;
+	proactive: boolean;
+	userReaction: string | null;
+	userReactionAt: number | null;
+	companionReaction: string | null;
+	replyId: number | null;
+}
+/** A module's window as the host knows it (its component stays in the module). */
+export interface ModuleWindowInfo {
+	moduleId: string;
+	id: string;
+	title: string;
+	width?: number;
+	height?: number;
+	menu?: {
+		label: string;
+		accelerator?: string;
+	};
+}
+/** Unsubscribe handle returned by every `on…` listener. */
+export type Unsubscribe = () => void;
+/**
+ * A module as published or installed: its catalogue entry (app/scripts/build-modules.mjs), enough
+ * to list it before it is installed.
+ */
+export interface ModulePackage {
+	id: string;
+	version: string;
+	/** the SDK range it needs (^x.y.z) */
+	sdk: string;
+	css: boolean;
+	/** it ships models.json (its collections' models); absent in entries from before the flag */
+	models?: boolean;
+	label: string;
+	description?: string;
+	/** its icon's [width, height, svg path] */
+	icon?: [
+		number,
+		number,
+		string
+	] | null;
+	local?: boolean;
+	requires?: string[];
+	requiresCapabilities?: string[];
+}
+/**
+ * A restricted module (offered only to the accounts given it), as the server lists it for this
+ * account: its catalogue entry (JSON, with its files) signed alone with the update key, and a
+ * signed, expiring URL per file.
+ */
+export interface RestrictedModulePackage {
+	entry: string;
+	/** base64 */
+	signature: string;
+	urls: Record<string, string>;
+	/** an entry signed by its publisher's key, not the official one: that key's certificate */
+	publisher?: PublisherCertificate;
+}
+/**
+ * A key allowed to sign one module's entries (a third party's): `certificate` is the JSON text
+ * {"module": <id>, "key": <its Ed25519 public key, SPKI DER, base64>}, `signature` the official
+ * key's (base64). Trusted for that module only.
+ */
+export interface PublisherCertificate {
+	certificate: string;
+	signature: string;
+}
+/** The modules of this device: installed from the server's catalogue (signed), on demand. */
+export interface ModuleStoreApi {
+	/**
+	 * The modules this app can have, one entry each: the installed ones, and the published ones
+	 * compatible with this app (the newest). Without the server (VPN down), the installed ones and
+	 * the last catalogue read.
+	 */
+	list(): Promise<{
+		modules: ModulePackage[];
+		installed: string[];
+	}>;
+	/** Installs a module (its newest compatible version), usable at once. Already installed: at once. */
+	install(id: string): Promise<ModulePackage>;
+	/** Removes a module's files from this device (a loaded one stays until the app restarts). */
+	uninstall(id: string): Promise<void>;
+	/**
+	 * The restricted modules this account was given (the server's list, renderer side: it needs the
+	 * session): the store checks each signature, lists and installs them like the others.
+	 */
+	setRestricted(modules: RestrictedModulePackage[]): Promise<void>;
+	/**
+	 * The newer versions already downloaded than what runs ("id version"). A module's version is
+	 * decided at start; these wait for activate() (or the next start).
+	 */
+	pending(): Promise<string[]>;
+	/** Runs them from now on: the app reloads its page right after. Returns what changed. */
+	activate(): Promise<string[]>;
+}
+/** One of the app's notifications, as the system shows it. */
+export interface SystemNotification {
+	id: number;
+	title: string;
+	body: string | null;
+	/** a state's count (null: an event); shown again when it grows */
+	count: number | null;
+	/** where a click leads in the app */
+	link: string | null;
+}
+/**
+ * The app's notifications shown by the system (desktop: its notification center, the dock marks
+ * hub as having some). The page hands over its whole list at each change.
+ */
+export interface SystemNotificationsApi {
+	sync(items: SystemNotification[]): void;
+	/** a click on one: the app opens its link */
+	onOpen(cb: (link: string) => void): Unsubscribe;
+}
+/** A document of a module's store (docs/plan-module-storage.md), local or on the server. */
+export interface StoredDocument {
+	collection: string;
+	id: string;
+	data: unknown;
+	/** milliseconds: the last write wins */
+	updatedAt: number;
+}
+export interface StoredFile {
+	path: string;
+	size: number;
+	sha256: string;
+}
+/**
+ * The modules' store on this device (desktop: SQLite in the main process): the scopes the account
+ * keeps local. Every call names the account (a hash), the module and the scope.
+ */
+export interface LocalStoreApi {
+	list(account: string, module: string, scope: string, collection?: string): Promise<StoredDocument[]>;
+	get(account: string, module: string, scope: string, collection: string, id: string): Promise<StoredDocument | null>;
+	put(account: string, module: string, scope: string, documents: StoredDocument[]): Promise<void>;
+	delete(account: string, module: string, scope: string, collection: string, id: string): Promise<void>;
+	purge(account: string, module: string, scope: string): Promise<void>;
+	files(account: string, module: string, scope: string): Promise<StoredFile[]>;
+	putFile(account: string, module: string, scope: string, path: string, body: Uint8Array): Promise<void>;
+	getFile(account: string, module: string, scope: string, path: string): Promise<Uint8Array | null>;
+	deleteFile(account: string, module: string, scope: string, path: string): Promise<void>;
+}
+/**
+ * The app's notifications by push (Android: Firebase Cloud Messaging): the server sends each change,
+ * the shell shows it as a system notification, even with the app closed.
+ */
+export interface PushApi {
+	/** Asks the permission to notify (once) and returns this device's token for the server; null: no push. */
+	register(): Promise<{
+		token: string;
+		platform: "android";
+	} | null>;
+	/** a notification tapped: the app opens its link */
+	onOpen(cb: (link: string) => void): Unsubscribe;
+}
+/**
+ * The AI companion. Desktop-only today (local Ollama); a shell without it
+ * reports `capabilities.companion === false` and the UI hides the module.
+ */
+export interface CompanionApi {
+	getEngine(): Promise<CompanionEngineInfo>;
+	setEngine(on: boolean): void;
+	onEngineChange(cb: (info: CompanionEngineInfo) => void): Unsubscribe;
+	listConversations(): Promise<CompanionProfile[]>;
+	getProfile(conversationId: string): Promise<CompanionProfile>;
+	listMessages(conversationId: string, opts: {
+		limit: number;
+		beforeId?: number;
+	}): Promise<CompanionMessage[]>;
+	send(conversationId: string, content: string): Promise<CompanionMessage>;
+	react(conversationId: string, id: number, emoji: string | null): Promise<CompanionMessage | null>;
+	regenerate(conversationId: string): Promise<number[] | null>;
+	onMessagesDeleted(cb: (conversationId: string, ids: number[]) => void): Unsubscribe;
+	onMessageUpdate(cb: (conversationId: string, message: CompanionMessage) => void): Unsubscribe;
+	listImages(conversationId: string): Promise<CompanionMessage[]>;
+	onMessage(cb: (conversationId: string, message: CompanionMessage) => void): Unsubscribe;
+	onActivity(cb: (conversationId: string, activity: CompanionActivity) => void): Unsubscribe;
+	onError(cb: (conversationId: string, error: string) => void): Unsubscribe;
+	getActivity(conversationId: string): Promise<CompanionActivity>;
+	listLog(conversationId: string): Promise<CompanionLogEntry[]>;
+	onLog(cb: (conversationId: string, entry: CompanionLogEntry) => void): Unsubscribe;
+	getUnread(): Promise<Record<string, number>>;
+	onUnreadChange(cb: (counts: Record<string, number>) => void): Unsubscribe;
+	markRead(conversationId: string): void;
+}
+/** What the web layer hands the native player: desktop VideoPlayerModal's webview inputs. */
+export interface NativePlayerOptions {
+	url: string;
+	/** Referer header for the first load (embed mode), null for none */
+	referrer: string | null;
+	/** script run once the DOM is ready; the player is ready when its promise settles (null: ready on load) */
+	bootstrap: string | null;
+	/** shown while the page loads */
+	poster: string | null;
+	/** swipe neighbours: whether there is one each way, and its poster (slides in while swiping) */
+	hasPrev: boolean;
+	hasNext: boolean;
+	prevPoster: string | null;
+	nextPoster: string | null;
+	/** posters to fetch ahead (videos further away), so fast swipes find them ready */
+	preloadPosters: string[];
+}
+/** A Font Awesome icon as drawn natively: viewBox size + SVG path data. */
+export interface NativeIcon {
+	width: number;
+	height: number;
+	path: string;
+}
+/** One of the player's actions, behind its gear button. Taps come back through `onAction`. */
+export interface NativePlayerAction {
+	id: string;
+	label: string;
+	icon: NativeIcon;
+	/** danger: a destructive action awaiting its confirming second tap */
+	tone: "default" | "danger";
+	/** running: shown dimmed, taps ignored */
+	busy: boolean;
+}
+/** Overlay over the video (tags, info); tapping it closes it. */
+export interface NativePlayerPanel {
+	chips?: string[];
+	rows?: Array<[
+		label: string,
+		value: string
+	]>;
+}
+/**
+ * Fullscreen native player above the app (Capacitor). Stands in for the
+ * <webview> of the video player modal on shells without `capabilities.webview`;
+ * only reached when `capabilities.nativePlayer` is true.
+ */
+export interface NativePlayerApi {
+	open(options: NativePlayerOptions): Promise<void>;
+	exec(script: string): Promise<void>;
+	reload(): Promise<void>;
+	close(): Promise<void>;
+	/** the actions behind the gear (the whole list each time), and the icons of the gear and close buttons */
+	setActions(actions: NativePlayerAction[], icons: {
+		menu: NativeIcon;
+		close: NativeIcon;
+	}): Promise<void>;
+	showPanel(panel: NativePlayerPanel | null): Promise<void>;
+	onReady(cb: () => void): Unsubscribe;
+	onClosed(cb: () => void): Unsubscribe;
+	onAction(cb: (id: string) => void): Unsubscribe;
+	/** a swipe went through: the web side switches to that neighbour and opens it */
+	onNavigate(cb: (direction: "prev" | "next") => void): Unsubscribe;
+}
+/**
+ * What the host shell can do. The UI reads these to hide what a shell lacks
+ * (e.g. the Capacitor shell has no native windows and no companion engine).
+ */
+export interface PlatformCapabilities {
+	/** AI companion engine (local LLM) */
+	companion: boolean;
+	/** integrated WireGuard tunnel controllable from the UI */
+	vpn: boolean;
+	/** modules hidden behind a reveal shortcut (Privacy) */
+	privateMode: boolean;
+	/** in-app self-update */
+	updates: boolean;
+	/** per-site cookie/referer injection for the embedded browser/player */
+	integrations: boolean;
+	/** embedded <webview> (the integrated browser and the external player) */
+	webview: boolean;
+	/** fullscreen native player (`platform.player`) instead of an embedded <webview> */
+	nativePlayer: boolean;
+	/** separate native windows (Settings/History/About) vs in-app pages */
+	nativeWindows: boolean;
+	/** global audio mute toggle */
+	mute: boolean;
+	/** developer "local server" toggle */
+	devMode: boolean;
+}
+/**
+ * The host shell, as seen by the shared UI. Method names mirror the Electron
+ * preload so the Electron adapter is a thin pass-through; other shells
+ * implement what they can and advertise the rest through `capabilities`.
+ */
+export interface Platform {
+	readonly name: "electron" | "capacitor";
+	/**
+	 * Value sent in the `X-Hub-Client` header on the server's cookie-authenticated
+	 * auth routes. Must be one of the server's accepted client values
+	 * (SecurityController::CLIENT_HEADER_VALUES).
+	 */
+	readonly client: "desktop" | "android";
+	readonly capabilities: PlatformCapabilities;
+	/** Host runtime info for the About screen (OS + engine versions). */
+	readonly runtime: {
+		os: string;
+		versions: Record<string, string>;
+	};
+	ping(): Promise<string>;
+	getDevMode(): Promise<boolean>;
+	onDevModeChange(cb: (value: boolean) => void): Unsubscribe;
+	notifyAuthState(authenticated: boolean): void;
+	/**
+	 * The server just set a new refresh-token cookie (login, refresh: each
+	 * refresh revokes the previous token). The shell makes it durable at once,
+	 * or an app killed before its cookie store flushes comes back with a revoked
+	 * token and a forced re-login.
+	 */
+	persistSession(): void;
+	/**
+	 * The hidden modules revealed this session (Privacy: their shortcut), shared by the app's
+	 * windows; forgotten at restart. Hidden again all at once by Ctrl+Alt+Q.
+	 */
+	getRevealedModules(): Promise<string[]>;
+	/**
+	 * A secret kept by this device only, encrypted by the system (desktop: the OS keyring through
+	 * safeStorage; Android: the Keystore): the account's data key (core/crypto). null: none.
+	 */
+	getDeviceSecret(name: string): Promise<string | null>;
+	/** null: forgotten. */
+	setDeviceSecret(name: string, value: string | null): Promise<void>;
+	setRevealedModules(ids: string[]): void;
+	onRevealedModulesChange(cb: (ids: string[]) => void): Unsubscribe;
+	onWebviewKey(cb: (event: {
+		key: string;
+		ctrl: boolean;
+		alt: boolean;
+	}) => void): Unsubscribe;
+	showMessage(message: string): Promise<void>;
+	getMuted(): Promise<boolean>;
+	setMuted(value: boolean): void;
+	onMutedChange(cb: (value: boolean) => void): Unsubscribe;
+	getVpnStatus(): Promise<VpnInfo>;
+	startVpn(): Promise<void>;
+	stopVpn(): Promise<void>;
+	onVpnStatusChange(cb: (info: VpnInfo) => void): Unsubscribe;
+	replaceVpnConfig(): Promise<{
+		ok: boolean;
+		path: string | null;
+		error?: string;
+	}>;
+	/** Opens the Settings window, on a screen when given (e.g. 'security'). */
+	openSettings(target?: string): Promise<void>;
+	/** In the Settings window: a screen another window asked for. */
+	onSettingsGoto(cb: (target: string) => void): Unsubscribe;
+	/**
+	 * Opens an OAuth consent page in an app window; resolves with the URL the provider redirected to
+	 * (`redirectUri` + the code), caught before it loads, or null when the window was closed.
+	 */
+	authorizeOAuth(url: string, redirectUri: string): Promise<string | null>;
+	/** Opens a module's window (ModuleManifest.windows), registered beforehand. */
+	openModuleWindow(moduleId: string, windowId: string): Promise<void>;
+	/** The windows of the active modules: what the app menu offers (replaces the previous list). */
+	registerModuleWindows(windows: ModuleWindowInfo[]): Promise<void>;
+	openAbout(): Promise<void>;
+	getAppVersion(): Promise<string>;
+	getUpdateState(): Promise<UpdateState | null>;
+	onUpdateStateChange(cb: (state: UpdateState) => void): Unsubscribe;
+	installUpdate(): Promise<void>;
+	skipUpdate(): Promise<void>;
+	quitApp(): Promise<void>;
+	listIntegrations(): Promise<Array<{
+		host: string;
+		updatedAt: number;
+	}>>;
+	applyIntegration(payload: {
+		host: string;
+		integration: WebsiteIntegration;
+		updatedAt: number;
+	}): Promise<void>;
+	removeIntegration(host: string): Promise<void>;
+	/**
+	 * Hosts the embedded browser / video player blocks (ads, trackers), compiled
+	 * by the back. The shell persists the list; the version lets the UI skip a
+	 * download when it already holds the latest one.
+	 */
+	getPlayerBlocklistVersion(): Promise<string | null>;
+	setPlayerBlocklist(version: string, hosts: string[]): Promise<void>;
+	readonly companion: CompanionApi;
+	readonly player: NativePlayerApi;
+	/** null: the shell shows none (Android: they come by push, `push`) */
+	readonly systemNotifications: SystemNotificationsApi | null;
+	/** null: no push (desktop: the open app shows them itself) */
+	readonly push: PushApi | null;
+	/** null: no local store here (Android, for now): a scope kept local isn't reachable on this device */
+	readonly localStore: LocalStoreApi | null;
+	/** null: the modules come from their sources (development), all of them, nothing to install */
+	readonly moduleStore: ModuleStoreApi | null;
+	/**
+	 * Where an isolated hubby's frame loads from (its own origin: desktop hubby://<id>/, Android
+	 * https://<id>.hubby.localhost/); null where hubbies can't run isolated (yet).
+	 */
+	hubbyUrl(module: string): string | null;
+}
+export declare const platform: Platform;
+/**
+ * Cross-module "timeline" capability. A module MAY expose dated items it owns (e.g.
+ * workout sessions) that any calendar/agenda surface can display, plus an optional
+ * self-contained detail view opened when an item is interacted with.
+ *
+ * Fully agnostic: no producer or consumer is named here. `payload` is opaque data the
+ * PRODUCING module attaches and reads back in its own renderer — consumers never touch it.
+ */
+export interface TimelineItem {
+	/** globally unique, namespaced by the source module, e.g. 'workout:123' */
+	id: string;
+	date: Date;
+	title: string;
+	/** the module that produced it (for grouping / coloring) */
+	moduleId: string;
+	/** where a consumer can send the user for the full item (deep-link fallback) */
+	href: string;
+	/** optional presentation hint: a CSS color used as the chip accent (generic) */
+	color?: string;
+	/** opaque module-private data, read only by the producing module's renderDetail */
+	payload?: unknown;
+}
+/** Fetch a module's dated items overlapping [start, end). */
+export type TimelineItemsProvider = (start: Date, end: Date) => Promise<TimelineItem[]>;
+export interface TimelineDetailContext {
+	onClose: () => void;
+	/** call after a mutation so the consumer can refresh its data */
+	onChanged: () => void;
+}
+/** Render a self-contained detail view (e.g. a modal) for one of the module's items. */
+export type TimelineDetailRenderer = (item: TimelineItem, ctx: TimelineDetailContext) => ReactNode;
+/** Planner's calendar: dated items in a range, and how to show one of them. */
+export interface TimelineContribution {
+	items: TimelineItemsProvider;
+	renderDetail?: TimelineDetailRenderer;
+}
+/**
+ * What a module can offer the others, by contribution point. A module consuming a point never
+ * knows who contributes to it; a contribution lives only while its module is enabled and shown
+ * (a private module's contributions disappear with it outside private mode). New points are added
+ * here, as part of the SDK contract.
+ */
+export interface ContributionPoints {
+	/** Planner's calendar: items dated by another module */
+	timeline: TimelineContribution;
+}
+export type ContributionPoint = keyof ContributionPoints;
+/** One module's contribution to a point. */
+export interface Contribution<P extends ContributionPoint> {
+	moduleId: string;
+	value: ContributionPoints[P];
+}
+export interface ModuleNavItem {
+	to: string;
+	label: string;
+	/** optional live label (e.g. a name read at runtime + a badge), rendered instead of `label` */
+	Label?: ComponentType;
+	/** the block of the sidebar it sits in, under this title (consecutive items share it) */
+	section?: string;
+	/** its icon in the phone's bottom bar (default: its section's, then the module's) */
+	icon?: IconDefinition;
+	/** the page the module opens on (default: the first item) */
+	home?: boolean;
+}
+export interface ModuleWindow {
+	/** unique in the module ([a-z0-9-]) */
+	id: string;
+	title: string;
+	Component: ComponentType;
+	width?: number;
+	height?: number;
+	/** an entry of the app menu (Window) opening it */
+	menu?: {
+		label: string;
+		accelerator?: string;
+	};
+}
+export interface ModuleRoute {
+	path: string;
+	Component: ComponentType;
+	/** kept mounted (KeepAlive) so page state survives navigation */
+	persistent?: boolean;
+	/** also answers the paths under it (an isolated hubby: /<id>/… all go to its frame) */
+	prefix?: boolean;
+}
+/**
+ * Desktop-side module manifest. The desktop owns the module catalogue (which modules
+ * exist, their nav and pages); the server advertises which it can serve + which the
+ * user enabled. `id` must match the server module slug (singular, e.g. 'workout').
+ */
+/**
+ * A shared feature a module may support:
+ *  - 'notifications': its notifications (the top bar's dot, the bell, its settings section);
+ *  - 'vpn': the VPN tunnel, run only while the module is open (its pages wait for it);
+ *  - 'amounts': it shows amounts (money…): its Privacy can blur them (the SDK's Amount).
+ */
+export type ModuleSupport = "notifications" | "vpn" | "amounts";
+/** A scope of a module's data whose place the account chooses (docs/plan-module-storage.md). */
+export interface StorageScope {
+	id: string;
+	/** shown in its settings (Data) */
+	label: string;
+	modes: Array<"local" | "server">;
+	default: "local" | "server";
+	/** each item may live elsewhere than the scope says (notes kept local…) */
+	perItem?: boolean;
+}
+export interface ModuleManifest {
+	id: string;
+	label: string;
+	/** its card on the home page */
+	icon?: IconDefinition;
+	/** one line under its name on the home page */
+	description?: string;
+	/** its own part of its settings screen (Modules > the module), under the common one */
+	Settings?: ComponentType;
+	/**
+	 * Runs entirely on this machine with no server counterpart: always shown, outside the
+	 * server's enabled list and the front/server integrity diff.
+	 */
+	local?: boolean;
+	/**
+	 * Host capabilities this module needs (see PlatformCapabilities). A shell that
+	 * lacks any of them hides the module entirely — e.g. 'companion' and 'webview'
+	 * are desktop-only, so AI never appears in the mobile shell.
+	 */
+	requiresCapabilities?: Array<keyof PlatformCapabilities>;
+	navItems: ModuleNavItem[];
+	/**
+	 * Runs isolated, in a sandboxed frame (docs/plan-module-architecture.md § 4 ter): none of its
+	 * code is loaded in the app; its navigation is the one its frame announces.
+	 */
+	isolated?: boolean;
+	/** the icons of its nav sections (by title): a section is a tab of the phone's bottom bar */
+	navSections?: Record<string, IconDefinition>;
+	routes: ModuleRoute[];
+	/**
+	 * Modules this one cannot work without (ids): it is only active while they all are, and
+	 * the Modules screen says so. For a feature that only makes sense with another module, prefer
+	 * a contribution of that module (`contributes`).
+	 */
+	requires?: string[];
+	/**
+	 * The shared features it supports (as its server module does): each brings its part of the
+	 * module's settings and its plumbing in the app, e.g. 'notifications' (the top bar's badge).
+	 */
+	supports?: ModuleSupport[];
+	/** The scopes of its data that can live on the server or on each device (Data in its settings). */
+	storage?: {
+		scopes: StorageScope[];
+	};
+	/** What this module offers the others, by contribution point (see ContributionPoints). */
+	contributes?: Partial<ContributionPoints>;
+	/**
+	 * Contexts this module needs around the whole app while it is active (e.g. a job followed from
+	 * any page), outermost first.
+	 */
+	providers?: Array<ComponentType<{
+		children: ReactNode;
+	}>>;
+	/** Windows of its own (desktop only), opened with platform.openModuleWindow(moduleId, id). */
+	windows?: ModuleWindow[];
+}
+/**
+ * A module's module.json: its version, the SDK it needs, and how it is described before it is
+ * installed (the store lists modules from these, see scripts/build-modules.mjs). `icon` is a Font
+ * Awesome solid icon name, the one its manifest shows.
+ */
+export interface ModuleInfo {
+	version: string;
+	sdk: string;
+	label: string;
+	description?: string;
+	icon?: string;
+	local?: boolean;
+	requires?: string[];
+	requiresCapabilities?: string[];
+	/** shared features (ModuleSupport) */
+	supports?: string[];
+	/** the scopes of its data the account places (local or server) */
+	storage?: {
+		scopes: StorageScope[];
+	};
+}
+export type Described = Pick<ModuleManifest, "label" | "description" | "local" | "requires" | "requiresCapabilities" | "supports" | "storage">;
+/** The manifest's descriptive part, from its module.json (one source for both). */
+export declare function describe(info: ModuleInfo): Described;
+/**
+ * What the active modules offer at a contribution point (none outside the main window): only
+ * those the account allowed it (their `module:` scope).
+ */
+export declare function useContributions<P extends ContributionPoint>(point: P): Contribution<P>[];
+/** Whether a module's amounts are blurred (its Privacy setting). */
+export declare function useAmountsBlurred(module: string): boolean;
+/** Whether a module shows: not hidden, or revealed this session. */
+export declare function useModuleVisible(id: string): boolean;
+/**
+ * Whether a hidden module is revealed this session (the former "private mode"): the players pause
+ * when it turns false (Ctrl+Alt+Q). Kept for the modules built before useModuleVisible.
+ */
+export declare function usePrivateMode(): boolean;
+/**
+ * An amount of a module (money, a balance…): blurred when the module's Privacy asks for it
+ * (`supports: ['amounts']`), a click shows that one until it is clicked again, the page is left or
+ * Ctrl+Alt+Q. Not for an amount being typed (a field): only shown ones.
+ */
+export declare function Amount({ module, children, className }: {
+	module: string;
+	children: ReactNode;
+	className?: string;
+}): import("react").JSX.Element;
+/**
+ * The modules' generic store (docs/plan-module-storage.md). A module declares scopes of its data
+ * (module.json `storage`); the account chooses, scope by scope, where each one lives:
+ *  - 'server': on the server (/api/data/<module>/_store, App\Service\Storage\DataStore), shared by its devices;
+ *  - 'local': on each device (platform.localStore), never sent anywhere.
+ * The module writes the same way in both (openStore). A scope declared `perItem` lets an item live
+ * elsewhere than the scope says: a list merges both places.
+ */
+export type StorageMode = "local" | "server";
+/** A document as the module sees it: where it lives, with its data. */
+export interface StoreItem<T = unknown> {
+	id: string;
+	collection: string;
+	data: T;
+	updatedAt: number;
+	mode: StorageMode;
+}
+/** Not reachable here: the scope is local and this device has no local store (Android, for now). */
+export declare class StoreUnavailableError extends Error {
+	constructor();
+}
+/** Re-renders when a module's modes change (read, or a move). */
+export declare function useStorageModes(module: string): number;
+export interface Store {
+	/** where the scope lives now */
+	readonly mode: StorageMode;
+	list<T = unknown>(collection: string): Promise<Array<StoreItem<T>>>;
+	get<T = unknown>(collection: string, id: string): Promise<StoreItem<T> | null>;
+	/** writes an item (where the scope lives, or `mode` for a perItem scope) */
+	put<T = unknown>(collection: string, id: string, data: T, options?: {
+		mode?: StorageMode;
+	}): Promise<void>;
+	delete(collection: string, id: string): Promise<void>;
+	putFile(path: string, body: Uint8Array | Blob): Promise<void>;
+	/** a URL an <img>/<audio> can load, null when there is no such file */
+	fileUrl(path: string): Promise<string | null>;
+	deleteFile(path: string): Promise<void>;
+}
+/**
+ * A scope of a module's store, where the account placed it. Read the mode again on each call: a
+ * move between places changes it.
+ */
+export declare function openStore(module: string, scope: string): Store;
+/**
+ * Non-2xx response. `message` stays `HTTP <status>` (callers match on it); `detail`
+ * carries the server's problem+json explanation when there is one.
+ */
+export declare class ApiError extends Error {
+	readonly status: number;
+	readonly detail: string | null;
+	constructor(status: number, detail: string | null);
+}
+/** Best human-readable message for a caught error: server detail first. */
+export declare function errorMessage(err: unknown, fallback?: string): string;
+export declare function api<T>(path: string, options?: RequestInit, retry?: boolean): Promise<T>;
+/**
+ * The server's base URL. Given the path called, the routes of the modules reached through the VPN
+ * (their data, their capabilities, their media: as they declare, core/module/declarations.ts) go to
+ * the name only reachable through it (prod): the desktop routes that name through the tunnel, the
+ * phone routes everything through it in private mode. Development: one local server.
+ */
+export declare function getApiBaseUrl(path?: string): string;
+export type StreamEventHandler = (event: string, data: unknown) => void;
+/**
+ * Opens an authenticated server-sent event stream — over fetch, so it can POST a
+ * body and carry the token — and resolves once the server closes it. Like api(),
+ * a 401 refreshes the token once before giving up.
+ */
+export declare function apiStream(path: string, options: RequestInit, onEvent: StreamEventHandler, retry?: boolean): Promise<void>;
+/**
+ * Parses a text/event-stream body, calling onEvent with each event name and its
+ * JSON-decoded data. Comments, empty blocks and undecodable data are skipped.
+ */
+export declare function readEventStream(body: ReadableStream<Uint8Array>, onEvent: StreamEventHandler): Promise<void>;
+export declare function fetchSettings<T = Record<string, unknown>>(scope: string): Promise<T>;
+export declare function updateSettings<T = Record<string, unknown>>(scope: string, values: Partial<T>): Promise<T>;
+/** Standard JSON envelopes returned by the hub API. */
+export interface SingleResponse<T> {
+	data: T;
+}
+export interface ListResponse<T> {
+	data: T[];
+}
+/** Paginated list envelope (data + page metadata). */
+export interface PaginatedResponse<T> {
+	data: T[];
+	meta: {
+		page: number;
+		limit: number;
+		total: number;
+		pages: number;
+	};
+}
+export declare function ensureIntegrationForUrl(rawUrl: string): Promise<void>;
+/**
+ * Sync probe — true if the domain has already been checked (positive or
+ * negative). Lets call-sites skip the async await on hot paths.
+ */
+export declare function isIntegrationKnownSync(rawUrl: string): boolean;
+/** A site's player scripts, served by the back (the web socle, Resources/<host>/). */
+export interface PlayerScripts {
+	/** run on the video page (page mode) to isolate the player */
+	page: string | null;
+	/** run on a bare embed player (embed mode) */
+	embed: string | null;
+	pause: string | null;
+}
+export interface PlayerConfig {
+	/** the host whose scripts apply to the requested domain */
+	host: string;
+	scripts: PlayerScripts;
+}
+/**
+ * The player config for a domain, null when the back has no scripts for the
+ * site (it is then loaded as-is). A failed lookup resolves null too, and is
+ * retried next time.
+ */
+export declare function getPlayerConfig(domain: string): Promise<PlayerConfig | null>;
+/**
+ * Makes sure the shell holds the back's current player blocklist before a
+ * player loads a site: once per session, a 304 when nothing changed. A failure
+ * leaves the shell's previous list in place and is retried next time.
+ */
+export declare function syncPlayerBlocklist(): Promise<void>;
+export type ButtonColor = "primary" | "secondary" | "danger";
+export interface ButtonProps {
+	label?: ReactNode;
+	children?: ReactNode;
+	icon?: IconDefinition;
+	color?: ButtonColor;
+	isDisabled?: boolean;
+	isLoading?: boolean;
+	className?: string;
+	onClick?: MouseEventHandler<HTMLButtonElement>;
+	type?: "button" | "submit" | "reset";
+	title?: string;
+	"aria-label"?: string;
+}
+export declare function Button({ label, children, icon, onClick, className, color, isDisabled, isLoading, type, ...rest }: ButtonProps): import("react").JSX.Element;
+export type IconButtonColor = "primary" | "secondary" | "danger" | "dark";
+export type IconButtonShape = "square" | "circle";
+export type IconButtonSize = "xxs" | "xs" | "sm" | "md" | "xl";
+export interface IconButtonProps {
+	icon: IconDefinition;
+	onClick?: MouseEventHandler<HTMLButtonElement>;
+	className?: string;
+	active?: boolean;
+	highlighted?: boolean;
+	isDisabled?: boolean;
+	isLoading?: boolean;
+	color?: IconButtonColor;
+	shape?: IconButtonShape;
+	size?: IconButtonSize;
+	type?: "button" | "submit" | "reset";
+	title?: string;
+	"aria-label"?: string;
+	"aria-expanded"?: boolean;
+}
+export declare function IconButton({ icon, onClick, className, active, highlighted, isDisabled, isLoading, color, shape, size, type, ...rest }: IconButtonProps): import("react").JSX.Element;
+type FormData$1 = Record<string, unknown>;
+export interface FormProps {
+	initialData?: FormData$1;
+	title?: string;
+	actions?: ReactNode;
+	onSubmit: (data: FormData$1) => void | Promise<void>;
+	children: ReactNode;
+	className?: string;
+}
+export declare function Form({ initialData, children, ...props }: FormProps): import("react").JSX.Element;
+export interface InputFieldProps {
+	name: string;
+	label?: string;
+	type?: HTMLInputTypeAttribute;
+	required?: boolean;
+	placeholder?: string;
+	autoComplete?: string;
+	autoFocus?: boolean;
+	min?: number | string;
+	max?: number | string;
+	step?: number | string;
+}
+export declare function InputField({ name, label, type, required, placeholder, ...rest }: InputFieldProps): import("react").JSX.Element;
+/**
+ * A switch between two choices (this || that, not on/off): both labels sit in the track, the
+ * thumb slides under the picked one. SwitchField's look, blue on both sides.
+ */
+export declare function ChoiceSwitch<V extends string>({ value, options, label, onChange }: {
+	value: V;
+	/** `count`: a number shown after the label (e.g. results waiting there) */
+	options: [
+		{
+			value: V;
+			label: string;
+			icon?: ReactNode;
+			count?: number;
+		},
+		{
+			value: V;
+			label: string;
+			icon?: ReactNode;
+			count?: number;
+		}
+	];
+	/** said to screen readers */
+	label: string;
+	onChange: (value: V) => void;
+}): import("react").JSX.Element;
+/** The SwitchField switch on its own, outside a form: controlled by `checked`. */
+export declare function Switch({ checked, onChange, title }: {
+	checked: boolean;
+	onChange: (checked: boolean) => void;
+	title?: string;
+}): import("react").JSX.Element;
+/** The CheckboxField box on its own, outside a form: controlled by `checked`, its label beside it. */
+export declare function Checkbox({ checked, label, onChange }: {
+	checked: boolean;
+	label: ReactNode;
+	onChange: (checked: boolean) => void;
+}): import("react").JSX.Element;
+export type DropdownColor = "menu" | "field";
+export type DropdownSide = "left" | "center" | "right";
+export type DropdownHeader = ReactNode | ((isOpen: boolean) => ReactNode);
+export interface DropdownProps {
+	header?: DropdownHeader;
+	children: ReactNode;
+	color?: DropdownColor;
+	side?: DropdownSide;
+	isOpen?: boolean;
+	onOpenChange?: (open: boolean) => void;
+	/** extra classes on the root (e.g. to size it inside a flex row) */
+	className?: string;
+}
+export declare function Dropdown({ header, children, color, side, isOpen: controlledOpen, onOpenChange, className }: DropdownProps): import("react").JSX.Element;
+export type ModalSize = "sm" | "md" | "lg" | "xl" | "full";
+export interface ModalProps {
+	title?: ReactNode;
+	size?: ModalSize;
+	onClose: () => void;
+	children: ReactNode;
+}
+export declare function Modal({ title, size, onClose, children }: ModalProps): import("react").ReactPortal;
+export interface ConfirmationModalProps {
+	title: ReactNode;
+	size?: ModalSize;
+	confirmLabel?: string;
+	confirmColor?: ButtonColor;
+	cancelLabel?: string;
+	onConfirm: () => void | Promise<void>;
+	onClose: () => void;
+	children: ReactNode;
+}
+export declare function ConfirmationModal({ title, size, confirmLabel, confirmColor, cancelLabel, onConfirm, onClose, children }: ConfirmationModalProps): import("react").JSX.Element;
+export interface TableProps {
+	children: ReactNode;
+	className?: string;
+}
+export declare function Table({ children, className }: TableProps): import("react").JSX.Element;
+export type TextAlign = "left" | "center" | "right";
+export interface TableHeadProps extends Omit<ThHTMLAttributes<HTMLTableCellElement>, "children"> {
+	textAlign?: TextAlign;
+	mobile?: boolean;
+	children?: ReactNode;
+}
+export declare function TableHead({ textAlign, mobile, className, children, ...rest }: TableHeadProps): import("react").JSX.Element;
+export declare function TableHeadGroup({ children }: {
+	children: ReactNode;
+}): import("react").JSX.Element;
+export interface TableRowProps {
+	children: ReactNode;
+	highlighted?: boolean;
+	className?: string;
+}
+export declare function TableRow({ children, highlighted, className }: TableRowProps): import("react").JSX.Element;
+export declare function TableRowGroup({ children }: {
+	children: ReactNode;
+}): import("react").JSX.Element;
+export interface TableCellProps extends Omit<TdHTMLAttributes<HTMLTableCellElement>, "children"> {
+	to?: string;
+	textAlign?: TextAlign;
+	mobile?: boolean;
+	children?: ReactNode;
+}
+export declare function TableCell({ to, textAlign, mobile, className, children, ...rest }: TableCellProps): import("react").JSX.Element;
+/** While `open`, the back button closes this (onClose). */
+export declare function useBackHandler(open: boolean, onClose: () => void): void;
+/** Whether `query` (a CSS media query) currently matches; follows its changes. */
+export declare function useMediaQuery(query: string): boolean;
+/** An entry of a tab's menu. */
+export interface BottomBarEntry {
+	key: string;
+	label: string;
+	/** a live label rendered instead of `label` (in the menu) */
+	Label?: ComponentType;
+	icon?: IconDefinition;
+	active: boolean;
+	onClick: () => void;
+	/** a dot: something new there */
+	dot?: boolean;
+	/** a count beside it in the menu (e.g. unread) */
+	count?: number;
+}
+/**
+ * A tab of the bottom bar: an action of its own (`primary`: the page's main action, a round button
+ * in the brand colour, e.g. Mail's new message), or a menu opening upwards (its entries in groups,
+ * under an optional title). An active menu tab stands for its active entry (its icon and label,
+ * highlighted) unless `fixed`: e.g. Mail's "+" while one of its folders is open.
+ */
+export type BottomBarTab = {
+	key: string;
+	label: string;
+	icon: IconDefinition;
+	active: boolean;
+	onClick: () => void;
+	dot?: boolean;
+	primary?: boolean;
+} | {
+	key: string;
+	label: string;
+	icon: IconDefinition;
+	menu: {
+		title?: string;
+		entries: BottomBarEntry[];
+	}[];
+	fixed?: boolean;
+};
+/**
+ * The phone's bottom bar, like Android's: a module's pages (ModuleNav), or a page's own places
+ * (Mail's folders). A menu closes on a choice, on back, on a tap beside it, on navigation.
+ */
+export declare function BottomBar({ tabs }: {
+	tabs: BottomBarTab[];
+}): import("react").JSX.Element;
+/**
+ * A module's declared collection, through the hubbies' generic API (/api/data/{module}/{collection},
+ * docs/spec-module.md § 5): the current account's documents only, checked against the module's
+ * model by the server. For the modules running in the app; an isolated hubby gets the same through
+ * its host (@cxxi-lab/hub-sdk/frame, ui/hub-sdk/frame/sdk.ts).
+ *
+ * The fields its model declares encrypted are sealed here, on the device, before they leave, and
+ * opened when they come back (core/crypto, docs/plan-storage-encryption.md § 3): the server only
+ * ever holds them sealed. A filter on an "equality" one is sent as its blind index.
+ */
+/** What the platform adds to every document. */
+export interface HubbyDocument {
+	id: string;
+	_createdAt: string;
+	_updatedAt: string;
+	_version: number;
+}
+/** A filter's value: equality, or operators (`in` takes a list). Fields: indexed ones only. */
+export type FilterValue = string | number | boolean | null | {
+	eq?: FilterValue;
+	ne?: FilterValue;
+	in?: FilterValue[];
+	gt?: FilterValue;
+	gte?: FilterValue;
+	lt?: FilterValue;
+	lte?: FilterValue;
+	exists?: boolean;
+	prefix?: string;
+};
+export interface CollectionQuery {
+	filter?: Record<string, FilterValue>;
+	/** fields along an index, `-` for descending (e.g. '-_updatedAt'); default '-_updatedAt' */
+	sort?: string;
+	/** 1–200, default 50 */
+	limit?: number;
+	cursor?: string;
+}
+export interface CollectionPage<T> {
+	data: T[];
+	next: string | null;
+}
+export type BatchOperation<T> = {
+	op: "create";
+	data: Partial<T>;
+} | {
+	op: "update";
+	id: string;
+	data: Partial<T>;
+	version?: number;
+} | {
+	op: "delete";
+	id: string;
+};
+/** One of a module's collections. `T`: its declared fields (the platform's are added). */
+export declare function collection<T extends object>(module: string, name: string): {
+	/** One page. */
+	find(q?: CollectionQuery): Promise<CollectionPage<T & HubbyDocument>>;
+	/** Every document matching, page after page (200 at a time). */
+	findAll(q?: Omit<CollectionQuery, "cursor" | "limit">): Promise<(T & HubbyDocument)[]>;
+	get: (id: string) => Promise<T & HubbyDocument>;
+	create(data: Partial<T>): Promise<T & HubbyDocument>;
+	/** The given fields; `version`: refused (409) if the document changed since. */
+	update(id: string, data: Partial<T>, version?: number): Promise<T & HubbyDocument>;
+	/** The whole document (the fields not given are emptied). */
+	replace(id: string, data: T): Promise<T & HubbyDocument>;
+	remove: (id: string) => Promise<void>;
+	/** Up to 100 operations, all or nothing. */
+	batch(operations: BatchOperation<T>[]): Promise<Array<(T & HubbyDocument) | null>>;
+};
+export declare function useVpnStatus(): VpnInfo;
+export declare function formatDuration(seconds: number | null): string;
+export declare function formatDate(iso: string | null): string;
+
+export {
+	FormData$1 as FormData,
+};
+
+export {};