mindoodb-app-sdk 0.0.64 → 0.0.66

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { ay as MindooDBAppComponentInfo, bq as MindooDBAppEmbedRect, I as MindooDBAppAgentToolDescriptor, f as MindooDBAppAgentToolErrorCode, V as MindooDBAppBridgeAgentResultMessage, U as MindooDBAppBridgeAgentInvokeMessage, aU as MindooDBAppCreateViewNavigatorInput, de as MindooDBAppViewNavigator, ad as MindooDBAppBridgeRpcRequest, bC as MindooDBAppHostTheme, av as MindooDBAppCapability, j as MindooDBAppDefinition, J as MindooDBAppAttachmentApi, e as MindooDBAppBridge, cQ as MindooDBAppSession, cg as MindooDBAppProposeAppInput, dm as MindooDBAppViewport, d8 as MindooDBAppUiPreferences, cm as MindooDBAppQueryResult, dl as MindooDBAppViewUpdateStats, a9 as MindooDBAppBridgePortMessage, aV as MindooDBAppDatabaseInfo, bl as MindooDBAppEmbedCloseReason, a4 as MindooDBAppBridgeErrorPayload, bX as MindooDBAppLaunchContext, b2 as MindooDBAppDocumentApi, dg as MindooDBAppViewNavigatorOpenOptions, bD as MindooDBAppIdentityApi, d4 as MindooDBAppTimestampApi, b0 as MindooDBAppDirectoryApi, l as MindooDBAppDocument, bz as MindooDBAppFulltextSetup, by as MindooDBAppExtractionSetup, cY as MindooDBAppSummarySetup, ch as MindooDBAppProposeAppResult, bN as MindooDBAppIncomingSource, c as MindooDBAppDragStartResult, bj as MindooDBAppDragProfile, bM as MindooDBAppIncomingResult } from '../types-BeRUxGKN.js';
+import { aC as MindooDBAppComponentInfo, bx as MindooDBAppEmbedRect, bq as MindooDBAppEmbedAgentTools, bz as MindooDBAppEmbeddingLookupOptions, bA as MindooDBAppEmbeddingLookupResult, J as MindooDBAppAgentToolDescriptor, f as MindooDBAppAgentToolErrorCode, X as MindooDBAppBridgeAgentResultMessage, W as MindooDBAppBridgeAgentInvokeMessage, aZ as MindooDBAppCreateViewNavigatorInput, dn as MindooDBAppViewNavigator, af as MindooDBAppBridgeRpcRequest, bL as MindooDBAppHostTheme, ax as MindooDBAppCapability, di as MindooDBAppUpdateDocumentInput, l as MindooDBAppDocument, j as MindooDBAppDefinition, L as MindooDBAppAttachmentApi, e as MindooDBAppBridge, cZ as MindooDBAppSession, cp as MindooDBAppProposeAppInput, dw as MindooDBAppViewport, dh as MindooDBAppUiPreferences, cv as MindooDBAppQueryResult, dv as MindooDBAppViewUpdateStats, ab as MindooDBAppBridgePortMessage, a_ as MindooDBAppDatabaseInfo, bs as MindooDBAppEmbedCloseReason, a6 as MindooDBAppBridgeErrorPayload, c4 as MindooDBAppLaunchContext, b7 as MindooDBAppDocumentApi, dq as MindooDBAppViewNavigatorOpenOptions, bM as MindooDBAppIdentityApi, dd as MindooDBAppTimestampApi, b5 as MindooDBAppDirectoryApi, bI as MindooDBAppFulltextSetup, bH as MindooDBAppExtractionSetup, d5 as MindooDBAppSummarySetup, cq as MindooDBAppProposeAppResult, bW as MindooDBAppIncomingSource, c as MindooDBAppDragStartResult, bo as MindooDBAppDragProfile, bV as MindooDBAppIncomingResult } from '../types-Cuw-0Iou.js';
 import * as mindoodb from 'mindoodb';
 import 'mindoodb-view-language';
 
@@ -13,6 +13,10 @@ interface MockEmbedState {
     visible: boolean;
     /** What the component last reported (`setEmbedDirty`); `undefined` until then. */
     dirty?: boolean;
+    /** Whether it is the active one of its app's embeds (`embed.setActive`, or the newest). */
+    active: boolean;
+    /** The agent tools it offers (`setEmbedAgentTools`), as the host app sees them. */
+    agentTools: MindooDBAppEmbedAgentTools | null;
 }
 /** How an app running as an embedded component finished (`session.embedding`). */
 interface MockEmbeddingFinish {
@@ -20,6 +24,18 @@ interface MockEmbeddingFinish {
     result?: unknown;
     message?: string;
 }
+interface MockEmbedHostOptions {
+    /** What `session.components.list` offers. */
+    components?: MindooDBAppComponentInfo[];
+    /** Called when the app opens an embed, e.g. to draw a stand-in in the test host page. */
+    onEmbedChange?: (embeds: readonly MockEmbedState[]) => void;
+    /**
+     * For an app under test that runs as a component: answers its
+     * `session.embedding.lookup`, as Haven would from the host's database. No results
+     * without it.
+     */
+    embeddingLookup?: (field: string, options: MindooDBAppEmbeddingLookupOptions) => MindooDBAppEmbeddingLookupResult[] | Promise<MindooDBAppEmbeddingLookupResult[]>;
+}
 
 /**
  * Haven's side of agent tools, for tests: what `session.agent` talks to.
@@ -131,6 +147,8 @@ declare function createMockAgentHost(options: MockAgentHostOptions & {
     /** Posts to the app's port; `false` when no app is connected. */
     post(message: MindooDBAppBridgeAgentInvokeMessage): boolean;
     onChange?(): void;
+    /** Whether the app runs as an embedded component: then only its `document` tools count. */
+    embedded?(): boolean;
 }): MockAgentHost;
 
 type EvaluatingViewDocument = {
@@ -152,6 +170,33 @@ declare function loadMindoodbForTesting(): Promise<MindoodbVirtualViews | null>;
  */
 declare function createEvaluatingViewNavigator(input: MindooDBAppCreateViewNavigatorInput, documents: EvaluatingViewDocument[]): Promise<MindooDBAppViewNavigator | null>;
 
+interface TestHostUser {
+    /** Shown above the user's frame. */
+    name: string;
+    username: string;
+}
+declare const DEFAULT_TEST_HOST_USERS: readonly [TestHostUser, TestHostUser];
+/** Window handles of the two-user mode, for Playwright. */
+interface TwoUserTestHost {
+    hosts: [BrowserTestHost, BrowserTestHost];
+    /** Merge the two replicas now; resolves with the number of documents that changed. */
+    sync(): Promise<number>;
+    setAutoSync(on: boolean): void;
+    /** Documents that differ between the replicas. */
+    differences(): number;
+}
+declare global {
+    interface Window {
+        /** Set in two-user mode. */
+        __havenTwoUsers?: TwoUserTestHost;
+    }
+}
+declare function mountTwoUserTestHost(options: Omit<CreateBrowserTestHostOptions, "frame"> & {
+    container?: HTMLElement;
+    title?: string;
+    users?: readonly [TestHostUser, TestHostUser];
+}, createHost: (options: CreateBrowserTestHostOptions) => BrowserTestHost): TwoUserTestHost;
+
 /**
  * A stand-in Haven for a real browser: the app runs in an iframe, exactly as Haven frames
  * it, and talks to the same in-memory mock host the Vitest helpers use.
@@ -244,6 +289,14 @@ interface BrowserTestHost {
     setEnforceCapabilities(enforce: boolean): void;
     /** Replaces the usernames of the tenant directory (`directory.listUsers()`). */
     setDirectoryUsers(users: readonly string[]): void;
+    /**
+     * Another device edits a document and the change syncs in: the app's live queries
+     * update. With Automerge-backed databases (`automerge=1` / `automerge: true`) the
+     * edit is made at `input.json.baseHeads` by another actor and merged, so it is
+     * concurrent to app saves at the same heads. See
+     * `MockMindooDBAppSessionController.applyRemoteUpdate`.
+     */
+    applyRemoteUpdate(databaseId: string, docId: string, input: MindooDBAppUpdateDocumentInput, options?: MockRemoteUpdateOptions): Promise<MindooDBAppDocument>;
     /** Reloads the app frame. The mock data survives; the app's in-memory state does not. */
     reloadApp(): void;
     dispose(): void;
@@ -271,6 +324,8 @@ interface MockDatabasesFromDefinitionOptions {
      * `"none"`: the mock's stateless default.
      */
     attachments?: "memory" | "none";
+    /** Back documents with real Automerge documents (`MockMindooDBAppDatabaseDefinition.automerge`). */
+    automerge?: boolean;
 }
 /**
  * Mock databases for every database a `haven-app.json` declares, granted as requested
@@ -284,10 +339,13 @@ declare function mockDatabasesFromDefinition(definition: Pick<MindooDBAppDefinit
  * - `enforce=1` turns the capability checks on
  * - `users=<count>` fills the directory with generated users
  * - `locale=<tag>`, `theme=dark|light`
+ * - `automerge=1` backs every database with real Automerge documents (concurrent
+ *   `baseHeads` merges, real heads); `automerge=0` turns it off
  */
 interface TestHostUrlSettings {
     overrides: Record<string, MockDatabaseOverride>;
     enforceCapabilities?: boolean;
+    automerge?: boolean;
     directoryUserCount?: number;
     locale?: string;
     theme?: "dark" | "light";
@@ -305,11 +363,19 @@ interface MountHavenTestHostOptions extends Omit<CreateBrowserTestHostOptions, "
         label: string;
     }>;
     /**
-     * Read `db=`, `enforce=`, `users=`, `locale=` and `theme=` from the page URL (see
+     * Read `db=`, `enforce=`, `users=`, `locale=`, `theme=` and `automerge=` from the page URL (see
      * {@link readTestHostUrlSettings}) and keep the URL in sync with the panel. Default
      * true. URL settings win over the options passed here.
      */
     urlSettings?: boolean;
+    /**
+     * Two app frames side by side, each on its own replica of the databases, merged by
+     * "Sync" / auto-sync — for testing concurrent editing by hand. Also `?twoUsers=1`.
+     * See {@link mountTwoUserTestHost}.
+     */
+    twoUsers?: boolean;
+    /** Names of the two users in two-user mode (default Anna and Ben). */
+    users?: readonly [TestHostUser, TestHostUser];
 }
 /** The locales Haven's UI offers; the default of the panel's language switcher. */
 declare const TEST_HOST_LOCALES: ReadonlyArray<{
@@ -333,6 +399,11 @@ declare function previewJson(value: unknown, maxString?: number, maxItems?: numb
  * of notifications, previews, scans and requests (click an entry for details).
  * The returned host is also available as `window.__havenTestHost`.
  */
+/**
+ * "Single user" / "Two users": links to the same test page with or without
+ * `twoUsers=1`, keeping the other URL settings (db, enforce, users, locale, …).
+ */
+declare function modeSwitch(current: "single" | "two"): HTMLElement;
 declare function mountHavenTestHost(options: MountHavenTestHostOptions): BrowserTestHost;
 
 /**
@@ -413,6 +484,22 @@ interface MockMindooDBAppDatabaseDefinition {
      * results the same way they would in Haven.
      */
     summarySetup?: MindooDBAppSummarySetup | null;
+    /**
+     * Back every document with a real Automerge document, like Haven: `update`
+     * applies `set`/`unset`, `json` (at `json.baseHeads`) and `text` patches as
+     * Automerge changes, heads are real Automerge heads, and `applyRemoteUpdate`
+     * on the controller writes as another device so concurrent edits truly
+     * merge. Off by default (plain JSON with `mock-head-N` heads).
+     */
+    automerge?: boolean;
+}
+/** Options of `applyRemoteUpdate`. */
+interface MockRemoteUpdateOptions {
+    /**
+     * Automerge actor id (hex) of the simulated device. Defaults to one fixed
+     * "remote" actor; pass different ids to simulate several devices.
+     */
+    actor?: string;
 }
 /**
  * Stands in for the host-owned sealed channel.
@@ -458,10 +545,22 @@ interface CreateMockMindooDBAppSessionOptions {
      * `methods.directory` still wins.
      */
     directoryUsers?: readonly string[];
+    /**
+     * Automerge actor (hex) of the app's writes in `automerge: true` databases. Mocks
+     * that are synced with each other (`syncMockReplicas`, the test host's two-user
+     * mode) need distinct actors, like two devices.
+     */
+    automergeActor?: string;
     /** What `session.components.list` offers; see `closeEmbed` on the controller. */
     components?: MindooDBAppComponentInfo[];
     /** Called whenever the app opens, moves or closes an embed. */
     onEmbedChange?: (embeds: readonly MockEmbedState[]) => void;
+    /**
+     * For an app under test that runs as a component: answers its
+     * `session.embedding.lookup` (documents a reference may point at), as Haven would
+     * from the host's database. No results without it.
+     */
+    embeddingLookup?: MockEmbedHostOptions["embeddingLookup"];
     /**
      * Answer `embeds.open` with a `container` like a current Haven: with this page
      * for the SDK to frame (e.g. `about:blank`). Without it the host behaves like an
@@ -497,6 +596,15 @@ interface MockMindooDBAppSessionController {
     setEnforceCapabilities(enforce: boolean): void;
     /** Replaces the directory's usernames (see `directoryUsers`). */
     setDirectoryUsers(users: readonly string[]): void;
+    /**
+     * Writes `input` to a document as another device would, then syncs it in:
+     * live queries update like after any write. With `automerge: true` on the
+     * database the edit is made by a different Automerge actor on the history
+     * up to `input.json.baseHeads` (the current state when omitted) and merged,
+     * so it is truly concurrent to app writes at the same heads. Without it, it
+     * is a plain update. Bypasses capability checks (it is not the app writing).
+     */
+    applyRemoteUpdate(databaseId: string, docId: string, input: MindooDBAppUpdateDocumentInput, options?: MockRemoteUpdateOptions): Promise<MindooDBAppDocument>;
     emitThemeChange(theme: MindooDBAppHostTheme): void;
     emitViewportChange(viewport: MindooDBAppViewport): void;
     emitUiPreferencesChange(uiPreferences: MindooDBAppUiPreferences): void;
@@ -523,6 +631,10 @@ interface MockMindooDBAppSessionController {
     getEmbeddingFinish(): MockEmbeddingFinish | null;
     /** As if the embedded component reported (un)saved changes; the app's embed follows. */
     setEmbedDirty(embedId: string, dirty: boolean): void;
+    /** As if the embedded component registered these agent tools (names without prefix). */
+    setEmbedAgentTools(embedId: string, names: string[] | null, options?: {
+        enabled?: boolean;
+    }): void;
     /** Makes the app's next `embed.save()` fail with this message. */
     failNextEmbedSave(message: string): void;
     /** For an app under test that runs as a component: its last `embedding.setDirty`. */
@@ -548,6 +660,20 @@ interface MockIncomingContentInput {
     }>;
 }
 
+type MockReplica = MockMindooDBAppSessionController | FakeBridgeHostController;
+/**
+ * How many documents differ between two mocks (missing on one side, other heads, or
+ * deleted on one side only): what `syncMockReplicas` would bring over.
+ */
+declare function mockReplicaDifferences(a: MockReplica, b: MockReplica): number;
+/**
+ * Syncs two mocks like two Haven devices: every document of every database both have
+ * is merged both ways (Automerge histories with `automerge: true`, so concurrent edits
+ * merge as in Haven; otherwise the newer copy wins), deletions spread, and attachments
+ * missing on one side are copied. Give the mocks distinct `automergeActor`s. Returns
+ * the number of documents that changed on either side.
+ */
+declare function syncMockReplicas(a: MockReplica, b: MockReplica): Promise<number>;
 declare function createMockMindooDBAppSession(options?: CreateMockMindooDBAppSessionOptions): MockMindooDBAppSessionController;
 declare function createMockMindooDBAppBridge(options?: CreateMockMindooDBAppSessionOptions): MockMindooDBAppSessionController;
 type FakeBridgeRequestHandler = (params: unknown, context: {
@@ -622,6 +748,8 @@ interface FakeBridgeHostController {
     /** See {@link CreateMockMindooDBAppSessionOptions.directoryUsers}. */
     setDirectoryUsers(users: readonly string[]): void;
     getDirectoryUsers(): string[];
+    /** See {@link MockMindooDBAppSessionController.applyRemoteUpdate}. */
+    applyRemoteUpdate(databaseId: string, docId: string, input: MindooDBAppUpdateDocumentInput, options?: MockRemoteUpdateOptions): Promise<MindooDBAppDocument>;
     /** Embeds the app has open (`session.embeds.open`). */
     listEmbeds(): MockEmbedState[];
     /** Closes an embed and pushes the `embed-event` to the app. */
@@ -630,6 +758,13 @@ interface FakeBridgeHostController {
     getEmbeddingFinish(): MockEmbeddingFinish | null;
     /** As if the embedded component reported (un)saved changes; pushes the `embed-event`. */
     setEmbedDirty(embedId: string, dirty: boolean): void;
+    /**
+     * As if the embedded component registered these agent tools (names without prefix);
+     * pushes the `embed-event`. `null` or `[]` withdraws them.
+     */
+    setEmbedAgentTools(embedId: string, names: string[] | null, options?: {
+        enabled?: boolean;
+    }): void;
     /** Makes the app's next `embed.save()` fail with this message. */
     failNextEmbedSave(message: string): void;
     /** For an app under test that runs as a component: its last `embedding.setDirty`. */
@@ -647,4 +782,4 @@ interface FakeBridgeHostController {
 }
 declare function createFakeBridgeHost(options?: CreateFakeBridgeHostOptions): FakeBridgeHostController;
 
-export { ALL_CAPABILITIES, type BrowserTestHost, type BrowserTestHostLog, type BrowserTestHostScan, type BrowserTestHostScanMode, type CreateBrowserTestHostOptions, type CreateFakeBridgeHostOptions, type CreateMockMindooDBAppSessionOptions, type EvaluatingViewDocument, type FakeBridgeHostController, type FakeBridgePortMessageHandler, type FakeBridgeRequestHandler, type FakeBridgeRpcResponse, type MockAgentCall, type MockAgentCallResult, type MockAgentConsent, type MockAgentFile, type MockAgentHost, type MockAgentHostController, type MockAgentHostOptions, type MockDatabaseOverride, type MockDatabasesFromDefinitionOptions, type MockEmbedState, type MockEmbeddingFinish, MockForbiddenError, type MockIncomingContentInput, type MockMindooDBAppDatabaseDefinition, type MockMindooDBAppSessionController, type MockSealedChannelOptions, type MockSeedDocument, type MountHavenTestHostOptions, TEST_HOST_LOCALES, type TestHostUrlSettings, capabilitiesForDefinitionPermissions, createBrowserTestHost, createEvaluatingViewNavigator, createFakeBridgeHost, createMemoryAttachments, createMockAgentHost, createMockMindooDBAppBridge, createMockMindooDBAppSession, generateDirectoryUsers, loadMindoodbForTesting, mockAgentToolPrefix, mockDatabasesFromDefinition, mountHavenTestHost, previewJson, readTestHostUrlSettings, validateMockAgentTools };
+export { ALL_CAPABILITIES, type BrowserTestHost, type BrowserTestHostLog, type BrowserTestHostScan, type BrowserTestHostScanMode, type CreateBrowserTestHostOptions, type CreateFakeBridgeHostOptions, type CreateMockMindooDBAppSessionOptions, DEFAULT_TEST_HOST_USERS, type EvaluatingViewDocument, type FakeBridgeHostController, type FakeBridgePortMessageHandler, type FakeBridgeRequestHandler, type FakeBridgeRpcResponse, type MockAgentCall, type MockAgentCallResult, type MockAgentConsent, type MockAgentFile, type MockAgentHost, type MockAgentHostController, type MockAgentHostOptions, type MockDatabaseOverride, type MockDatabasesFromDefinitionOptions, type MockEmbedState, type MockEmbeddingFinish, MockForbiddenError, type MockIncomingContentInput, type MockMindooDBAppDatabaseDefinition, type MockMindooDBAppSessionController, type MockRemoteUpdateOptions, type MockSealedChannelOptions, type MockSeedDocument, type MountHavenTestHostOptions, TEST_HOST_LOCALES, type TestHostUrlSettings, type TestHostUser, type TwoUserTestHost, capabilitiesForDefinitionPermissions, createBrowserTestHost, createEvaluatingViewNavigator, createFakeBridgeHost, createMemoryAttachments, createMockAgentHost, createMockMindooDBAppBridge, createMockMindooDBAppSession, generateDirectoryUsers, loadMindoodbForTesting, mockAgentToolPrefix, mockDatabasesFromDefinition, mockReplicaDifferences, modeSwitch, mountHavenTestHost, mountTwoUserTestHost, previewJson, readTestHostUrlSettings, syncMockReplicas, validateMockAgentTools };