mindoodb-app-sdk 0.0.65 → 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, d9 as MindooDBAppUpdateDocumentInput, l as MindooDBAppDocument, 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, 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.
@@ -323,6 +368,14 @@ interface MountHavenTestHostOptions extends Omit<CreateBrowserTestHostOptions, "
      * 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<{
@@ -346,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;
 
 /**
@@ -487,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
@@ -561,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`. */
@@ -586,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: {
@@ -670,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`. */
@@ -687,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 MockRemoteUpdateOptions, 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 };