@deveye/types 0.15.2 → 0.16.1

package/src/protocol/agent.ts

@@ -39,9 +39,8 @@ import { ProtocolErrorSchema } from './error';
 
 /**
  * Agent <-> Server wire protocol (distinct from the user feature protocol).
- *
- * The agent authenticates with its device token, then streams metric batches.
- * The server acknowledges and may push commands (reserved for later).
+ * The agent authenticates with its device token, then streams metric batches,
+ * reports and replies; the server acknowledges and pushes orders.
  */
 
 /** Command names the agent may send to the server. */
@@ -301,17 +300,12 @@ export const agentSyncIndexPayloadSchema = z.object({
     entries: z.array(syncIndexEntrySchema).max(SYNC_INDEX_BATCH_MAX),
     done: z.boolean(),
     /**
-     * L'agent a-t-il RÉELLEMENT parcouru le disque ?
-     *
-     * `false` répond à un `sync.scan` en mode `auto` sur un partage que le
-     * watcher sait intact depuis le dernier scan : aucune entrée n'est envoyée,
-     * seule `fingerprint` est renseignée, et c'est au serveur de vérifier qu'elle
-     * correspond à la baseline qu'il détient. Il ne SUPPOSE donc jamais que
-     * l'appareil est à jour, il le VÉRIFIE — une vérification fausse coûte un
-     * scan complet, jamais une divergence.
-     *
-     * Le défaut `true` est ce qui rend un vieil agent inoffensif : sans le champ,
-     * le serveur retombe sur le chemin d'aujourd'hui.
+     * L'agent a-t-il réellement parcouru le disque ? `false` répond à un
+     * `sync.scan` en mode `auto` sur un partage que le watcher sait intact :
+     * aucune entrée, seule `fingerprint` est renseignée, et le serveur VÉRIFIE
+     * qu'elle correspond à sa baseline (une vérification fausse coûte un scan
+     * complet, jamais une divergence). Le défaut `true` rend un vieil agent
+     * inoffensif.
      */
     scanned: z.boolean().default(true),
     /** Empreinte de l'index détenu par l'agent, quand il sait la calculer. */
@@ -520,11 +514,8 @@ export const AGENT_ERROR = 'agent.error' as const;
 export const AGENT_COLLECT = 'agent.collect' as const;
 /**
  * Demande un relevé Sentinelle immédiat (persistance + authentification).
- *
- * Distinct d'`agent.collect` exprès : celui-ci coûte quelques millisecondes et
- * peut être déclenché à volonté, tandis qu'un relevé de persistance empreinte
- * des centaines de fichiers. Les confondre reviendrait à faire payer ce prix à
- * chaque bouton « rafraîchir » de la page Monitoring.
+ * Distinct d'`agent.collect` : celui-ci coûte quelques millisecondes, un relevé
+ * de persistance empreinte des centaines de fichiers.
  */
 export const AGENT_SCAN = 'agent.scan' as const;
 /** Push the per-device collection config (cadences + capture mode) to the agent. */
@@ -731,11 +722,9 @@ export const agentSyncScanPayloadSchema = z.object({
     sessionId: syncOpId,
     shareId: z.number().int().positive(),
     /**
-     * Le défaut `full` est ce qui rend un vieux SERVEUR inoffensif : sans le
-     * champ, un agent récent parcourt le disque comme il l'a toujours fait. Les
-     * deux sens de la dissymétrie de version dégradent donc vers « scan
-     * complet », jamais vers « saut » — sauter exige une empreinte que seul un
-     * agent récent produit et que seul un serveur récent exploite.
+     * Le défaut `full` rend un vieux serveur inoffensif : les deux sens de la
+     * dissymétrie de version dégradent vers « scan complet », jamais vers
+     * « saut ».
      */
     mode: syncScanModeSchema.default('full')
 });
@@ -780,23 +769,20 @@ export const agentSyncApplyChunkPayloadSchema = z.object({
     mode: z.number().int().min(0).max(0o777).nullable().default(null),
     /**
      * Offset de clair à partir duquel CE transfert reprend. Décidé par le
-     * serveur (à partir du `resumeFrom` annoncé par l'agent) et répété sur
-     * chaque frame : l'agent tronque son temporaire à cette valeur avant
-     * d'écrire. C'est ce qui empêche les deux côtés de diverger — l'agent ne
-     * doit jamais présumer de son propre point de reprise.
+     * serveur (d'après le `resumeFrom` de l'agent) et répété sur chaque frame :
+     * l'agent tronque son temporaire à cette valeur avant d'écrire, et ne
+     * présume jamais de son propre point de reprise.
      */
     resumeFrom: z.number().int().nonnegative().default(0)
 });
 export type AgentSyncApplyChunkPayload = z.infer<typeof agentSyncApplyChunkPayloadSchema>;
 
 /**
- * Amorce un download. L'agent répond `sync.opResult` avec `op: 'applyReady'` et
- * un `resumeFrom` : le nombre d'octets de clair qu'il détient DÉJÀ dans son
- * temporaire pour ce hash exact. Le serveur ne renvoie alors que ce qui manque.
- *
- * Le temporaire est nommé par hash et non par `opId`, ce qui rend la reprise
- * auto-corrective : un fichier modifié entre-temps a un autre hash, donc un
- * autre temporaire, donc aucune reprise possible sur des octets périmés.
+ * Amorce un download. L'agent répond `sync.opResult` avec `op: 'applyReady'`
+ * et un `resumeFrom` : les octets de clair qu'il détient DÉJÀ dans son
+ * temporaire pour ce hash exact. Le temporaire est nommé par hash et non par
+ * `opId` : un fichier modifié entre-temps a un autre hash, donc aucune reprise
+ * sur des octets périmés.
  */
 export const AGENT_SYNC_APPLY_START = 'sync.applyStart' as const;
 export const agentSyncApplyStartPayloadSchema = z.object({
@@ -822,10 +808,9 @@ export const agentSyncApplyDirPayloadSchema = z.object({
     shareId: z.number().int().positive(),
     relPath: syncRelPath,
     /**
-     * `dir` autorise la CRÉATION du chemin ; `file` interdit de le créer et se
-     * contente d'ajuster le mode s'il existe. Sans cette distinction, un `chmod`
-     * sur un fichier momentanément absent ferait naître un DOSSIER à sa place —
-     * que le planner écarterait ensuite pour toujours en « conflit de nature ».
+     * `dir` autorise la CRÉATION du chemin ; `file` ne fait qu'ajuster le mode
+     * s'il existe. Sans cette distinction, un `chmod` sur un fichier
+     * momentanément absent ferait naître un DOSSIER à sa place.
      */
     kind: syncEntryKindSchema.default('dir'),
     mode: z.number().int().min(0).max(0o777).nullable().default(null)
@@ -854,13 +839,9 @@ export type AgentSyncApplyLocalPayload = z.infer<typeof agentSyncApplyLocalPaylo
 
 /**
  * Propage un DÉPLACEMENT : l'agent renomme sur place, sans transfert ni
- * corbeille. Le contenu ne bouge pas d'un octet, seul son chemin change — le
- * traiter comme « supprime ici, télécharge là » coûtait une copie intégrale en
- * corbeille, pour une opération qui ne détruit rien.
- *
- * L'agent vérifie que la source porte bien le contenu attendu avant de bouger.
- * En cas d'échec il répond `opResult !ok`, et le serveur retombe sur le chemin
- * ordinaire (téléchargement puis suppression), qui reste sûr.
+ * corbeille, après avoir vérifié que la source porte le contenu attendu. En
+ * cas d'échec il répond `opResult !ok` et le serveur retombe sur le chemin
+ * ordinaire (téléchargement puis suppression).
  */
 export const AGENT_SYNC_MOVE = 'sync.move' as const;
 export const agentSyncMovePayloadSchema = z.object({
@@ -900,13 +881,10 @@ export const agentConfigPayloadSchema = z.object({
     /** How much of the process list to carry on each tick (`off`/`top`/`all`). */
     processCapture: processCaptureSchema,
     /**
-     * Sentinelle est-elle active sur cet appareil ? Éteinte, l'agent ne relève ni
-     * persistance ni authentification — ces deux sondes ne coûtent rien à qui ne
-     * les demande pas, et une machine qui n'est pas surveillée ne doit pas voir
-     * ses journaux lus « au cas où ».
-     *
-     * Facultatif : un serveur antérieur à Sentinelle n'envoie pas le champ, et
-     * l'agent se comporte alors comme avant.
+     * Sentinelle est-elle active sur cet appareil ? Éteinte, l'agent ne relève
+     * ni persistance ni authentification : une machine non surveillée ne doit
+     * pas voir ses journaux lus « au cas où ». Facultatif : absent, l'agent ne
+     * relève rien.
      */
     sentinelEnabled: z.boolean().optional(),
     /** Cadence du manifeste de persistance, en ms. */
@@ -1048,12 +1026,9 @@ export const DEVICE_REPORT_EVENT = 'device.report' as const;
 /** Package-manager inventory, live upgrade progress, and completion (Appareils panel). */
 export const PACKAGE_LIST_EVENT = 'package.list' as const;
 /**
- * Une mise à jour vient d'être **acceptée** pour ce gestionnaire.
- *
- * Émis par le serveur, qui seul sait qu'un verrou vient d'être pris — et avant
- * la première ligne de sortie de l'outil, qui peut se faire attendre. C'est ce
- * qui permet à tous les écrans ouverts, y compris ceux d'autres personnes, de
- * griser le bouton au même instant.
+ * Une mise à jour vient d'être acceptée pour ce gestionnaire. Émis par le
+ * serveur avant la première ligne de sortie de l'outil, pour que tous les
+ * écrans ouverts grisent le bouton au même instant.
  */
 export const PACKAGE_STARTED_EVENT = 'package.started' as const;
 export const PACKAGE_PROGRESS_EVENT = 'package.progress' as const;
@@ -1063,10 +1038,6 @@ export const DEVICE_POWER_EVENT = 'device.powerResult' as const;
 /**
  * Outcome of a persistence/privilege change (autostart, elevate, drop), fanned to
  * subscribers exactly like the power result.
- *
- * Sans lui, la seule trace de l'échec d'une installation de service était une
- * ligne de journal d'audit : l'interface attendait quelques secondes, relisait
- * l'appareil, et n'affichait rien — ni la réussite, ni la raison de l'échec.
  */
 export const DEVICE_SERVICE_EVENT = 'device.serviceResult' as const;
 /** Device log sources inventory + queried log lines, fanned to subscribers. */
@@ -1086,14 +1057,13 @@ export const CLOUD_SYNC_PROGRESS_EVENT = 'cloudSync.progress' as const;
 export const CLOUD_SYNC_STATE_EVENT = 'cloudSync.state' as const;
 export const CLOUD_SYNC_CHUNK_EVENT = 'cloudSync.chunk' as const;
 
-/** Push payloads reuse the agent reply shapes (already carry `deviceId`). */
+// Push payloads reuse the agent reply shapes (they already carry `deviceId`).
+
 /**
- * L'inventaire des gestionnaires, **enrichi** par le serveur de ce que l'agent
- * ne peut pas savoir : quelles mises à jour tournent déjà.
- *
- * Sans ce champ, un écran ouvert pendant qu'une mise à jour est en cours —
- * après avoir refermé la fenêtre, ou chez quelqu'un d'autre — repartait d'un
- * bouton actif et permettait de relancer la même commande.
+ * L'inventaire des gestionnaires, enrichi par le serveur de ce que l'agent ne
+ * peut pas savoir : quelles mises à jour tournent déjà. Sans ce champ, un
+ * écran ouvert pendant une mise à jour permettrait de relancer la même
+ * commande.
  */
 export const packageListPushSchema = agentPkgListResultPayloadSchema.extend({
     running: z.array(packageManagerIdSchema).default([])

package/src/protocol/envelope.ts

@@ -15,16 +15,9 @@ export const clientMessageSchema = z.object({
     command: z.string().min(1),
     /**
      * Espace de travail visé par la commande. Absent → l'espace personnel de
-     * l'appelant.
-     *
-     * Il vit sur l'enveloppe, et non dans le `payload` de chaque commande, pour
-     * trois raisons : aucun schéma d'entrée ne porte de `workspaceId`, aucun site
-     * d'appel client ne le passe à la main (`ws.send` l'estampille), et le
-     * serveur n'a qu'un seul point de résolution et d'autorisation. Le tenir dans
-     * un état de session côté serveur serait plus fragile : la socket se
-     * reconnecte seule (backoff, retour de focus) et une commande émise avant la
-     * ré-activation viserait le mauvais espace — ici chaque message se décrit
-     * lui-même.
+     * l'appelant. Porté par l'enveloppe et non par chaque `payload` : `ws.send`
+     * l'estampille, le serveur n'a qu'un seul point de résolution et
+     * d'autorisation, et chaque message se décrit lui-même, reconnexions comprises.
      */
     workspaceId: z.number().int().positive().optional(),
     payload: z.unknown()

package/src/sdk/client-ambient.d.ts

@@ -1,32 +1,37 @@
 /**
- * Ambient declaration of `deveye-sdk-client` — the runtime barrel the APP
+ * Ambient declaration of `deveye-sdk-client`, the runtime barrel the APP
  * provides when a feature module is compiled in (resolved by alias inside
- * DevEye). The module itself is app code and is published nowhere; this file
- * is its typed portrait, so a module repo can `tsc --noEmit` standalone.
- *
- * How it is consumed:
- *  - a module repo (the template) pulls it into its standalone typecheck via
- *    one tsconfig `include` entry pointing at this file in node_modules;
- *  - DevEye itself verifies MECHANICALLY that the real barrel honours this
- *    declaration (`client/npm run check:sdk`): a drift breaks the app's CI,
- *    never a third-party build.
- *
- * Extend it when the app's stable surface grows — same gesture as before,
- * one file instead of one per module repo.
+ * DevEye). The module itself is app code, published nowhere; this file is its
+ * typed portrait, so a module repo can `tsc --noEmit` standalone (one tsconfig
+ * `include` entry pointing here). DevEye verifies mechanically that the real
+ * barrel honours it (`client/npm run check:sdk`): a drift breaks the app's CI,
+ * never a third-party build.
  */
 declare module 'deveye-sdk-client' {
     import type {
         ButtonHTMLAttributes,
+        CSSProperties,
         ChangeEvent,
         ComponentType,
-        CSSProperties,
         InputHTMLAttributes,
         ReactNode,
+        RefObject,
         SelectHTMLAttributes
     } from 'react';
     import type { z, ZodType } from 'zod';
-    import type { FeatureAccess, FeatureId, WorkspaceCapability } from '@deveye/types';
-    import type { FeatureManifest } from '@deveye/types/sdk';
+    import type {
+        ButtonHTMLAttributes as DialogButtonAttributes,
+        PointerEvent as ReactPointerEvent
+    } from 'react';
+    import type {
+        FeatureAccess,
+        FeatureId,
+        MinimalUser,
+        User,
+        WorkspaceCapability
+    } from '@deveye/types';
+    import type { FeatureManifest, ManifestCommand } from '@deveye/types/sdk';
+    import type { SdkDeviceSummary } from '@deveye/types/sdk/client';
 
     // ── UI kit ─────────────────────────────────────────────────────────────
     export const Button: ComponentType<
@@ -36,7 +41,7 @@ declare module 'deveye-sdk-client' {
         }
     >;
     export const TextInput: ComponentType<
-        InputHTMLAttributes<HTMLInputElement> & { enableShowHideButton?: boolean }
+        InputHTMLAttributes<HTMLInputElement> & { enableShowHideButton?: boolean; error?: string }
     >;
     export const SelectInput: ComponentType<SelectHTMLAttributes<HTMLSelectElement>>;
     export const Checkbox: ComponentType<{
@@ -45,6 +50,7 @@ declare module 'deveye-sdk-client' {
         onChange: (checked: boolean) => void;
         children?: ReactNode;
         disabled?: boolean;
+        className?: string;
         /** Required when there is no visible label. */
         'aria-label'?: string;
     }>;
@@ -78,6 +84,41 @@ declare module 'deveye-sdk-client' {
         fill?: boolean;
         holdSecrecy?: boolean;
     }>;
+    /** The "Annuler" button of a Dialog footer: closes through the guarded close. */
+    export const DialogCancelButton: ComponentType<
+        DialogButtonAttributes<HTMLButtonElement> & {
+            variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
+            icon?: string;
+        }
+    >;
+    /**
+     * The imperative dialog layer over Dialog: mount `<Popup id=...>` once
+     * around a form, then drive it with `OpenPopup(id, input)` (resolves with
+     * whatever `ClosePopup(id, result)` passes, `null` on dismiss).
+     */
+    export function Popup<TInput = unknown>(props: {
+        children: ReactNode;
+        id: string;
+        title?: string;
+        width?: number;
+        headerAction?: ReactNode;
+        onInputChange?: ((input: TInput) => void) | null;
+        onClosePopup?: ((id: string) => void) | null;
+        onSubmit?: () => void;
+        autoFocus?: boolean;
+        dirty?: boolean;
+        onSave?: () => void;
+        tall?: boolean;
+        holdSecrecy?: boolean;
+    }): ReactNode;
+    export function OpenPopup<T = object>(id: string, inputData?: unknown): Promise<T | null>;
+    export function ClosePopup(id: string, data?: unknown): void;
+    /** The app-wide "i" explainer dialog: a heading and a body, one behaviour everywhere. */
+    export function openInfo(input: {
+        title: string;
+        body: ReactNode;
+        width?: number;
+    }): Promise<unknown>;
     /** Request the enclosing Dialog's guarded close (the unsaved-changes prompt included). */
     export function useDialogClose(): () => void;
     /** Register `fn` as the enclosing Dialog's primary action (Enter triggers it); `null` clears it. */
@@ -112,12 +153,69 @@ declare module 'deveye-sdk-client' {
     export const FeatureSettingsButton: ComponentType<{
         scope:
             | { kind: 'feature'; feature: FeatureId }
-            | { kind: 'item'; feature: FeatureId; itemId: number; itemLabel: string };
+            | {
+                  kind: 'item';
+                  feature: FeatureId;
+                  itemId: number | string;
+                  itemLabel: string;
+                  shareable?: boolean;
+              };
         variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
         label?: string;
+        /** The tab a click opens (one of the manifest's tab ids); the first by default. */
+        initialSection?: string;
+        /**
+         * The shell opened or closed (unmount counts as closed): for the one
+         * component that owns the item's presence (`useLiveSegment`) when
+         * nothing else announces the item. The shell never declares the level.
+         */
+        onOpenChange?: (open: boolean) => void;
     }>;
     /** The canonical settings row classes (channelRow, field, sectionHint...). */
     export const settingsStyles: Readonly<Record<string, string>>;
+    /** A plain count on a home card: a big number, a noun, a secondary line. */
+    export type CountState = { kind: 'loading' } | { kind: 'ready'; count: number };
+    export const CountWidget: ComponentType<{
+        state: CountState;
+        /** Singular noun, pluralized with a trailing "s" unless `plural` says otherwise. */
+        noun: string;
+        plural?: string;
+        /** Secondary line when there is at least one item. */
+        hint: string;
+        /** Secondary line when the count is zero. */
+        empty: string;
+        tone?: 'neutral' | 'danger';
+    }>;
+    /**
+     * A workspace count over one of YOUR `.count` commands (or any `...Count`
+     * command answering `{ count }`), re-fetched on reconnect and on
+     * invalidation of that key. Never gated by the password-encryption unlock:
+     * the command must answer while locked.
+     */
+    export function useWorkspaceCount(
+        command: `x-${string}.count` | `${string}.${string}Count`
+    ): CountState;
+    /**
+     * Reorder a list by drag-and-drop, the app's one gesture for it (Pointer
+     * Events, a handle per row, an insertion bar the hook positions itself).
+     * The list container must be `position: relative`; rows carry
+     * `rowSelector`; the handle wires `onGripPointerDown`.
+     */
+    export function useDragReorder<
+        L extends HTMLElement = HTMLElement,
+        B extends HTMLElement = HTMLElement
+    >(options: {
+        ids: (string | number)[];
+        rowSelector: string;
+        onReorder: (ids: (string | number)[]) => void;
+        onDragStateChange?: (dragging: boolean) => void;
+        layout?: 'rows' | 'grid';
+    }): {
+        listRef: RefObject<L | null>;
+        barRef: RefObject<B | null>;
+        onGripPointerDown: (e: ReactPointerEvent, id: string | number) => void;
+        draggingId: string | number | null;
+    };
 
     // ── Server push events ─────────────────────────────────────────────────
     /** Typed push subscription: filters `event`, safeParses, drops mismatches. */
@@ -150,6 +248,29 @@ declare module 'deveye-sdk-client' {
     /** Imperative subscription to one resource key's invalidations. Returns the unsubscribe. */
     export function onResourceChange(key: ExternalResourceKey, cb: () => void): () => void;
     export function humanizeError(error: unknown, fallback: string): string;
+    /** The error a command rejects with: the server's code (or the socket's), its message, and the validation details when any. */
+    export class WsError extends Error {
+        constructor(code: string, message: string, details?: unknown);
+        readonly code: string;
+        readonly details?: unknown;
+    }
+    /**
+     * The typed sender of any list of contracts (`featureApi` is it on a
+     * manifest's commands). `commandsApi(agentCommands)` is how a module talks
+     * to a device: the native agent transport (`agent.*`: files, terminal,
+     * logs, packages, power, live metrics subscription), under the active
+     * workspace's `devices` right; deferred answers arrive through
+     * `onServerEvent`.
+     */
+    export function commandsApi<const C extends readonly ManifestCommand[]>(
+        commands: C
+    ): {
+        send<N extends C[number]['command']>(
+            name: N,
+            input: z.input<Extract<C[number], { command: N }>['input'] & ZodType>,
+            opts?: { timeoutMs?: number }
+        ): Promise<z.output<Extract<C[number], { command: N }>['output'] & ZodType>>;
+    };
     export function featureApi<const M extends FeatureManifest>(
         manifest: M
     ): {
@@ -182,6 +303,14 @@ declare module 'deveye-sdk-client' {
     export function ensureSecrecyUnlocked(): Promise<void>;
     /** Runs `run`; on a `locked` error, opens the unlock prompt and retries once. */
     export function withSecrecy<T>(run: () => Promise<T>): Promise<T>;
+    /** Keep the unlocked session alive during a long operation (a mailbox sync the user is watching). */
+    export function touchSecrecy(): void;
+    /**
+     * The rejection of `ensureSecrecyUnlocked` / `withSecrecy` when the user
+     * dismisses the unlock prompt: a deliberate cancel, not a failure (close a
+     * view that has nothing to show, rather than reporting an error).
+     */
+    export class UnlockCancelledError extends Error {}
 
     // ── Live ───────────────────────────────────────────────────────────────
     export type LiveSegmentKind = 'view' | 'l1' | 'l2' | 'l3' | 'l4';
@@ -216,13 +345,37 @@ declare module 'deveye-sdk-client' {
         /** What the folder is for, said by the caller. */
         description?: string;
     }>;
-    /** The workspace's enrolled devices, live (a polled store, not a bare list). */
+    /**
+     * The workspace's enrolled devices, live: what the Devices module offers
+     * the app (`DEVICES_CLIENT_PROVIDER`), refreshed by the `devices` topic.
+     * Empty, loaded and without error when that module is not installed.
+     */
     export function useDevices(): {
-        devices: { id: string; name: string; online: boolean }[];
+        devices: readonly SdkDeviceSummary[];
         loading: boolean;
         error: string | null;
-        refresh: () => Promise<void>;
     };
+    /**
+     * Acquires a live metrics subscription to a device and returns its release;
+     * consumers of one socket are counted so that none unsubscribes another.
+     */
+    export function acquireMetrics(deviceId: string): () => void;
+    /** Device paths as the agent reports them: Windows or POSIX, joined accordingly. */
+    export function isWinPath(p: string): boolean;
+    export function joinPath(base: string, name: string): string;
+    /**
+     * The DevEye version this interface was built from: what an agent's
+     * reported version is compared against to offer a self-update.
+     */
+    export const APP_VERSION: string;
+    /**
+     * A validated GET on one of the app's HTTP routes (the session cookie
+     * rides along; an expired access token is renewed and the call replayed
+     * once). For the routes that stay HTTP because they serve binaries.
+     */
+    export function httpGet<T>(path: string, outputSchema?: ZodType<T>): Promise<T>;
+    /** Renews the access cookie before a raw `fetch` that bypasses the client (a download). */
+    export function ensureFreshAccess(): Promise<void>;
     export interface LiveOutlineProps {
         'data-live-peer'?: true;
         style?: CSSProperties;
@@ -247,6 +400,60 @@ declare module 'deveye-sdk-client' {
         name: string;
     } | null;
     export function useFeatureLifecycle(hooks: { onUnmount?: () => void }): void;
+    /** The members of the active workspace, as the session lists them (empty before it answers). */
+    export function useWorkspaceMembers(): readonly MinimalUser[];
+    /**
+     * A member's identity dot: their avatar, or their initial on their account
+     * colour (the same one as the live presence). `user` may be undefined: a
+     * deleted account must not break a row.
+     */
+    export const Avatar: ComponentType<{
+        user: MinimalUser | undefined;
+        size?: number;
+        title?: string;
+    }>;
+    /** The CSS variable of an account colour, the one the live presence paints with. */
+    export function userColorVar(color: MinimalUser['color']): string;
+    /**
+     * Two sticky bands, one under the other: measure the top one and hand the
+     * ancestor a `--sticky-head` variable the lower band offsets itself by.
+     */
+    export interface StickyOffset<T extends HTMLElement> {
+        ref: RefObject<T | null>;
+        style: CSSProperties;
+    }
+    export function useStickyOffset<T extends HTMLElement>(): StickyOffset<T>;
+    /**
+     * The client contract another module offers (`FeatureClient.providers`,
+     * keys in `@deveye/types/sdk`): how a module composes another's screens
+     * (Projects renders the linked items of Git, Uptime...). `undefined` when
+     * that module is not installed: degrade, never assume.
+     */
+    export function moduleClientProvider<T>(key: string): T | undefined;
+    /** The signed-in user, `null` before the session answers. */
+    export function useCurrentUser(): User | null;
+    /** Image inputs accepted by `fileToSquareDataUrl`. */
+    export const ACCEPTED_TYPES: readonly string[];
+    export const MAX_INPUT_BYTES: number;
+    /** A picked image, resized to a square data URL under `maxLength` characters; throws a readable message. */
+    export function fileToSquareDataUrl(
+        file: File,
+        opts: { size: number; maxLength: number }
+    ): Promise<string>;
+    /**
+     * Open another feature of the active workspace, on one of its items when
+     * `itemId` is given (the item's presence segment is its bare id): the
+     * host's teleport, the same mechanism as "join someone". The access guard
+     * is the host's; a missing item is ignored after a short grace.
+     */
+    export function openFeature(feature: string, itemId?: number): void;
+    /**
+     * Ask the feature popup for a wider frame (px) while the calling
+     * component is mounted, `null` to ask for nothing. Several requests
+     * coexist; the widest wins. For a view that outgrows the default width
+     * (a table explorer in expanded mode).
+     */
+    export function useRequestPopupWidth(px: number | null): void;
 
     // Change events re-exported for convenience in handlers.
     export type InputChange = ChangeEvent<HTMLInputElement>;