@qilin-agent/client-test-runtime 0.0.0-stage → 3.1.4

package/lib/types/assembly/bundle-roster.d.ts

@@ -0,0 +1,15 @@
+import { ClientRoster } from './roster.ts';
+/** The `web` profile's bundle layers, in the order `qilin --profile web` applies them (app-boot `PROFILE_TEMPLATES.web`). */
+export declare const WEB_PROFILE_BUNDLES: readonly string[];
+/**
+ * Compose the browser roster of `bundles`, applied in order.
+ * @param bundles - bundle package names in application order.
+ * @param anchor - file whose package resolution locates the bundles; default this package.
+ * @returns the roster in composition order, one row per package.
+ * @throws {Error} when a bundle, its patch file, or an enabled row's package does not resolve, when the patch list
+ * is not a list or does not apply as written, or when a browser row's `disabled` is a `!!js` expression.
+ */
+export declare function bundleRoster(bundles: readonly string[], anchor?: string): ClientRoster;
+/** The `web` profile's browser roster, composed from its bundles at import. */
+export declare const webApp: ClientRoster;
+//# sourceMappingURL=bundle-roster.d.ts.map

package/lib/types/assembly/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whole-client tier entry (deep import only:
+ * `@qilin-agent/client-test-runtime/src/assembly/index.ts`). Kept out of
+ * the package root so slot-tier specs do not load the assembly machinery.
+ * @module @qilin-agent/client-test-runtime/src/assembly
+ */
+export { ClientRoster } from './roster.ts';
+export type { AssemblyPlan, ClientPluginModule, ClientRosterRow } from './roster.ts';
+export { TestClient } from './test-client.ts';
+export type { TestClientOptions } from './test-client.ts';
+export { remoteDefaultResponses } from './remote-default-responses.ts';
+export { bundleRoster, webApp } from './bundle-roster.ts';
+export { createClientTest } from './vitest.ts';
+export type { ClientTestFixtures } from './vitest.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/assembly/modules.d.ts

@@ -0,0 +1,25 @@
+import type { ClientModuleLoader, WebBootGraph } from '@qilin-agent/client-modules/client';
+import type { AssemblyPlan, ClientPluginModule } from './roster.ts';
+/** The bootstrap row: always this process's static namespace, never a dynamic import or a `provide` replacement. */
+export declare const MODULES_PACKAGE = "@qilin-agent/client-modules";
+/**
+ * Resolve each roster row to its plugin module: `plan.provide[name]` when
+ * present, otherwise a `/client` import resolved by the repository's tsconfig
+ * path aliases under Vitest. The bootstrap row is the
+ * statically imported `@qilin-agent/client-modules/client` namespace.
+ * @param plan - validated plan.
+ * @returns package name → module, in roster order.
+ * @throws {Error} when an import fails (the package name prefixes the original message) or the bootstrap row is provided.
+ */
+export declare function loadPluginModules(plan: AssemblyPlan): Promise<ReadonlyMap<string, ClientPluginModule>>;
+/**
+ * Build the production module system over queued factories returning the
+ * loaded namespaces. The bootstrap row uses `bootstrapModule`; `staticModules`
+ * is empty because namespaces already hold their own imports. Missing factories
+ * reject through `loadBundle` without fetching.
+ * @param graph - raw boot graph from `graphFromRoster`; `createClientModuleSystem` parses it.
+ * @param modules - loaded plugin modules keyed by package name.
+ * @returns module system to install as `loader.internal`; its `manifest` is the parsed graph.
+ */
+export declare function createInProcessModules(graph: WebBootGraph, modules: ReadonlyMap<string, ClientPluginModule>): ClientModuleLoader;
+//# sourceMappingURL=modules.d.ts.map

package/lib/types/assembly/remote-default-responses.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default responses for every Remote endpoint the web assembly calls while
+ * booting and rendering with no sessions, no workspaces, and default settings.
+ * The comment above each row names the plugin that calls it; endpoints boot
+ * never touches stay absent so a new call fails loud. `$events` is built into
+ * `RemoteMock`.
+ * @module @qilin-agent/client-test-runtime/src/assembly/remote-default-responses
+ */
+import { type RemoteTable } from '@qilin-agent/remote-mock';
+/** Default responses of the boot-time Remote endpoints; a spec loads it first and layers its own table on top. */
+export declare const remoteDefaultResponses: RemoteTable;
+//# sourceMappingURL=remote-default-responses.d.ts.map

package/lib/types/assembly/remote-proxies.d.ts

@@ -0,0 +1,20 @@
+import type { RemoteMock } from '@qilin-agent/remote-mock';
+import type { ClientPluginModule } from './roster.ts';
+/** The assembly row the proxies stand in for; its generated clients exist only in built `lib/`. */
+export declare const REMOTES_PACKAGE = "@qilin-agent/api-remotes";
+/**
+ * Namespaces to provide: every `remote.<ns>` a roster module injects, plus the
+ * namespace of every endpoint the mock has a rule for.
+ * @param modules - loaded roster modules.
+ * @param mock - the spec's mock.
+ * @returns sorted namespace names.
+ */
+export declare function remoteNamespacesOf(modules: Iterable<ClientPluginModule>, mock: RemoteMock): readonly string[];
+/**
+ * Plugin providing the namespace proxies; `TestClient.start` mounts it before the Loader rows.
+ * @param namespaces - namespaces to provide.
+ * @param mock - the spec's mock, asked for each endpoint's mode.
+ * @returns the plugin.
+ */
+export declare function remoteProxiesPlugin(namespaces: readonly string[], mock: RemoteMock): ClientPluginModule;
+//# sourceMappingURL=remote-proxies.d.ts.map

package/lib/types/assembly/roster.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Client roster: the ordered package-name rows a whole-client test boots, and
+ * the plan that annotates one with the rows the test provides itself. `webApp`
+ * and `bundleRoster` (`./bundle-roster.ts`) read rosters from the bundle patch
+ * files; a spec may also build one inline with {@link ClientRoster.of}.
+ * @module @qilin-agent/client-test-runtime/src/assembly/roster
+ */
+import type { Context } from '@qilin-agent/kylin';
+import type { WebBootGraph } from '@qilin-agent/client-modules/client';
+/** One browser plugin row as `qilin.client` declares it, keyed by package name. */
+export interface ClientRosterRow {
+    /** Package name (== manifest entry id == Loader entry name). */
+    readonly name: string;
+    /** Package-name dependency edges from `qilin.client.inject` ([] when absent). */
+    readonly inject: readonly string[];
+    /** Stage-one prefetch mark from `qilin.client.immediately` (false when absent). */
+    readonly immediately: boolean;
+}
+/**
+ * Synthesize the raw `WebBootGraph` for `rows`: one `application` batch
+ * holding every row, `rev: 'local'`, placeholder `/plugins/<name>/client.js`
+ * URLs, since every module is seeded in process and never fetched. Validation
+ * stays with the production `parseBootManifest` inside the module system:
+ * duplicate names and an empty roster are rejected there, not here.
+ * @param rows - roster rows in composition order.
+ * @returns the unparsed graph, as `createClientModuleSystem` consumes it.
+ */
+export declare function graphFromRoster(rows: readonly ClientRosterRow[]): WebBootGraph;
+/** Immutable, name-addressable roster. */
+export declare class ClientRoster {
+    readonly rows: readonly ClientRosterRow[];
+    /**
+     * Build a roster from rows; duplicate names throw.
+     * @param rows - roster rows in composition order.
+     * @returns roster.
+     */
+    static of(rows: readonly ClientRosterRow[]): ClientRoster;
+    private constructor();
+    /**
+     * Keep only `names`, preserving roster order; an unknown name throws with the roster listed.
+     * @param names - package names to keep.
+     * @returns sub-roster.
+     */
+    pick(names: readonly string[]): ClientRoster;
+    /**
+     * The named rows plus every row they inject, transitively, in roster order: the rows a spec needs to boot the
+     * named plugins as the bundle composes them. The shell's platform modules (`PLATFORM_MODULES`, seeded statically
+     * rather than loaded as rows) end the walk. An unknown name throws with the roster listed; a row injecting any
+     * other package outside the roster throws, since the bundle itself would not boot.
+     * @param names - package names whose dependency cone to keep.
+     * @returns sub-roster.
+     */
+    closure(names: readonly string[]): ClientRoster;
+    /**
+     * Drop `names`; an unknown name throws with the roster listed.
+     * @param names - package names to drop.
+     * @returns sub-roster.
+     */
+    without(names: readonly string[]): ClientRoster;
+    private known;
+}
+/** The module face the Loader materializes for one client plugin row. */
+export interface ClientPluginModule {
+    apply(ctx: Context, config?: unknown): unknown;
+    readonly inject?: readonly string[] | Readonly<Record<string, unknown>>;
+    readonly Config?: unknown;
+}
+/** What to boot and what the test supplies itself. */
+export interface AssemblyPlan {
+    readonly roster: ClientRoster;
+    /** Row replacements by package name (the test's own implementation of that row). Names outside the roster throw. */
+    readonly provide?: Readonly<Record<string, ClientPluginModule>>;
+}
+/**
+ * Validate a plan against its roster.
+ * @param plan - plan to check.
+ * @throws {Error} naming any `provide` key outside the roster.
+ */
+export declare function assertPlan(plan: AssemblyPlan): void;
+//# sourceMappingURL=roster.d.ts.map

package/lib/types/assembly/test-client.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Whole-client test carrier: boots an {@link AssemblyPlan} through the
+ * production `bootClient` over an in-process module table, with a
+ * `RemoteMock` bound to that client's Connection plugin instance.
+ * @module @qilin-agent/client-test-runtime/src/assembly/test-client
+ */
+import { Context } from '@qilin-agent/kylin';
+import { type ConnectionHandle } from '@qilin-agent/client-connection/client';
+import type { RemoteMock } from '@qilin-agent/remote-mock';
+import { type AssemblyPlan } from './roster.ts';
+/** Carrier options. */
+export interface TestClientOptions {
+    /**
+     * Mount `uiRenderer` into an element (a fresh `document.body` child when `true`); requires jsdom and a roster
+     * that provides `uiRenderer`. Default false.
+     */
+    readonly mount?: boolean | HTMLElement;
+    /** Wait for `ctx.connection.state === 'connected'` before returning. Default true. */
+    readonly awaitConnected?: boolean;
+    /** Readiness budget in milliseconds before `start` rejects with the mock log summary. Default 5000. */
+    readonly connectTimeoutMs?: number;
+}
+/** A booted client under test. */
+export declare class TestClient {
+    readonly ctx: Context;
+    readonly mock: RemoteMock;
+    readonly container: HTMLElement | undefined;
+    private readonly restore;
+    /**
+     * Load the roster's modules, bind this client's mock to its Connection row,
+     * hold the jsdom shims, and boot through `bootClient` over the synthesized
+     * boot graph; afterwards optionally mount and wait for the connection. The
+     * bound row replaces only the page-global input adapter: both paths call
+     * `installConnection`, while this path supplies the mock carrier, uses
+     * default recovery timings, and captures the current page hostname once for
+     * later reloads. A caller-provided Connection row remains unchanged and owns
+     * its readiness behavior. The `@qilin-agent/api-remotes` row is
+     * dropped from the roster: its generated Remote clients exist only in built
+     * `lib/`, and the `remote.<ns>` services the roster injects (plus the
+     * namespaces the mock has rules for at this point) are provided as
+     * contract-free proxies over the same Connection instead; a `provide` entry
+     * for that row is refused. On any failure the context is disposed, an owned
+     * mount removed, and this client's hold on the shims released before the
+     * original error is rethrown.
+     * @param plan - roster and annotations.
+     * @param mock - Remote mock answering every Gateway call.
+     * @param options - mount and readiness options.
+     * @returns the booted client.
+     */
+    static start(plan: AssemblyPlan, mock: RemoteMock, options?: TestClientOptions): Promise<TestClient>;
+    private disposing;
+    private constructor();
+    /** The roster's Connection service (no `Context` augmentation declares it); throws when the roster provides none. */
+    get connection(): ConnectionHandle;
+    /** Flush pending React work and microtasks inside `act` (plain microtask flush without a DOM). */
+    flush(): Promise<void>;
+    /**
+     * Rebuild one Loader entry: Client Modules' registry-first fiber teardown, then
+     * `entry.refresh()`. Each client's module table retains its own instance-bound
+     * Connection plugin, so reloads do not coordinate through process globals.
+     * Requires a live client: after `dispose()` the Loader holds no entries and
+     * the lookup throws before teardown.
+     * @param name - package name of the row.
+     */
+    reload(name: string): Promise<void>;
+    /**
+     * Remove one Loader entry and wait for its plugin cleanup.
+     * @param name - package name of the row.
+     */
+    unload(name: string): Promise<void>;
+    /**
+     * Dispose the plugin tree, then drop an owned mount and release this
+     * client's hold on the shared jsdom shims even when the tree fails to dispose,
+     * then `mock.assertNoUnmatched()` last so its failure is the test's reason
+     * without skipping the cleanup; when both the tree and the check fail, one
+     * error carries both messages. The first call owns the teardown and reports
+     * its failure; every later call waits for that teardown and resolves.
+     */
+    dispose(): Promise<void>;
+    private teardown;
+    private entryOf;
+}
+//# sourceMappingURL=test-client.d.ts.map

package/lib/types/assembly/vitest.d.ts

@@ -0,0 +1,24 @@
+/** Test-scoped Remote mock and lazy client boot, owned by native Vitest fixtures. */
+import { type TestAPI } from 'vitest';
+import { RemoteMock, type MockedRemote } from '@qilin-agent/remote-mock';
+import type { AssemblyPlan } from './roster.ts';
+import { TestClient, type TestClientOptions } from './test-client.ts';
+/** Per-test controls; configure the mock before awaiting `start()`. */
+export interface ClientTestFixtures {
+    /** Fresh mock with the assembly's default responses already loaded. */
+    mock: RemoteMock;
+    /** Namespace proxy backed by the same native mocks used by the Connection carrier. */
+    remote: MockedRemote;
+    /** Await the one client owned by this test; rejects after the fixture closes. */
+    start: () => Promise<TestClient>;
+}
+/**
+ * Extend Vitest with a fresh mock and a lazy, automatically disposed client. Repeated `start()` calls share one
+ * promise. Await it to observe startup failures; cleanup waits for startup but does not rethrow its rejection.
+ * Missing mock responses still fail teardown even when no client was started. Page globals remain environment-owned.
+ * @param plan - roster and replacement modules, shared as configuration rather than as a running client.
+ * @param options - mount and readiness settings passed to `TestClient.start`.
+ * @returns Vitest's test function with test-scoped `mock` and `start` fixtures.
+ */
+export declare function createClientTest(plan: AssemblyPlan, options?: TestClientOptions): TestAPI<ClientTestFixtures>;
+//# sourceMappingURL=vitest.d.ts.map

package/lib/types/config-form.d.ts

@@ -0,0 +1,29 @@
+/** Test doubles for settings transport. */
+import { vi } from 'vitest';
+import type { ConfigForm, ConfigFormSnapshot } from '@qilin-agent/client-ui-settings/client';
+/** Handle over one stubbed scope: the scope, its write spy, and publication controls. */
+export interface StubConfigForm<T> {
+    /** The scope face handed to the service under test. */
+    scope: ConfigForm<T>;
+    /** Spy behind `scope.set`; resolves immediately. */
+    set: ReturnType<typeof vi.fn>;
+    /** Spy behind `scope.mutate`; resolves immediately. */
+    mutate: ReturnType<typeof vi.fn<ConfigForm<T>['mutate']>>;
+    /** Spy behind `scope.unset`; resolves immediately. */
+    unset: ReturnType<typeof vi.fn>;
+    /** @returns how many listeners are currently subscribed (disposal assertions). */
+    listenerCount(): number;
+    /**
+     * Replace part of the snapshot and notify subscribers, as a Host
+     * acceptance would.
+     * @param next - snapshot fields to replace.
+     */
+    publish(next: Partial<ConfigFormSnapshot<T>>): void;
+}
+/**
+ * Build an in-memory settings scope for service specs: starts in the host
+ * loading state, records writes, and lets the test publish Host acceptances.
+ * @returns the stub handle.
+ */
+export declare function stubConfigForm<T>(): StubConfigForm<T>;
+//# sourceMappingURL=config-form.d.ts.map

package/lib/types/fixtures.d.ts

@@ -0,0 +1,73 @@
+/** Controller and UI-domain fixture shapes for the client test runtime. */
+import type { ISession, SessionEventLikeEntry, SessionSnapshot, SessionSummary } from '@qilin-agent/api-session-controller/client';
+import type { WorkspaceSnapshot } from '@qilin-agent/api-workspace-controller/client';
+import type { SessionId } from '@qilin-agent/session/types';
+import { type ConversationSnapshot } from '@qilin-agent/client-ui-conversation/client';
+import { type ChatSnapshot } from '@qilin-agent/client-ui-chat/client';
+/**
+ * Fixture overrides for the session behavior face: any subset of the
+ * production ISession verbs (typed against it, so a face change surfaces
+ * here at compile time), plus extra members feature-specific casts consume.
+ * The open Record tail means a misnamed EXTRA member is not caught by the
+ * compiler (it grafts as dead weight); the ISession verbs stay safe — a
+ * misnamed verb leaves the fail-loud stub in place, which names itself at
+ * the first call.
+ */
+export type SessionBehaviorOverrides = Partial<ISession> & Record<string, unknown>;
+/**
+ * act-wrapped mutation runner shared by every runtime object: public mutators
+ * funnel through it so tests never handle SlotCore microtask batching or
+ * React act themselves.
+ */
+export type Stabilizer = (fn: () => void | Promise<void>) => Promise<void>;
+/** Mutable top-level snapshot fields accepted by fixture update callbacks. */
+export type FixtureSnapshot<T> = {
+    -readonly [Key in keyof T]: T[Key];
+};
+/** Writable test representation of the immutable Session Controller snapshot. */
+export type SessionFixtureSnapshot = FixtureSnapshot<SessionSnapshot>;
+/**
+ * Session fixture accepted by {@link TestSessions.add}: identity plus optional
+ * snapshot/list-row overrides and the session behavior face the feature under
+ * test actually calls (kept open — the runtime never fakes methods a test did
+ * not supply, so an unstubbed call fails loud at the call site).
+ */
+export interface SessionFixture {
+    id: string;
+    /** Overrides merged over {@link sessionSnapshot}; Conversation data arrives through the event feed. */
+    snapshot?: Partial<Omit<SessionSnapshot, 'sessionId'>>;
+    /** List-row overrides merged over the defaults derived from `id`. */
+    summary?: Partial<Omit<SessionSummary, 'id'>>;
+    /** Session behavior face: exactly the methods the feature under test calls (ISession subset + extras). */
+    session?: SessionBehaviorOverrides;
+    /** Initial contiguous event window consumed by Conversation assembly. */
+    events?: readonly SessionEventLikeEntry[];
+    /** Whether the initial event window has an older page. */
+    hasMore?: boolean;
+    /** Optional shared initial-opening barrier for the fixture's Client generation. */
+    initialOpen?: (signal: AbortSignal) => void | Promise<void>;
+}
+/**
+ * A complete quiescent Session Controller snapshot.
+ * @param sessionId - owning session id.
+ * @returns the snapshot; spread fixture overrides on top.
+ */
+export declare function sessionSnapshot(sessionId: SessionId): SessionSnapshot;
+/**
+ * A target-neutral Conversation snapshot.
+ * @param overrides - target roster or activity overrides.
+ * @returns an immutable fixture value.
+ */
+export declare function conversationSnapshot(overrides?: Partial<ConversationSnapshot>): ConversationSnapshot;
+/**
+ * A Chat target snapshot.
+ * @param overrides - Chat target overrides.
+ * @returns an immutable fixture value.
+ */
+export declare function chatSnapshot(overrides?: Partial<ChatSnapshot>): ChatSnapshot;
+/**
+ * A ready Workspace Controller snapshot with no Workspace rows.
+ * @returns the initial state of the test Workspace source.
+ */
+export declare function workspaceSnapshot(): WorkspaceSnapshot;
+//# sourceMappingURL=fixtures.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,236 @@
+/**
+ * jsdom slot test runtime: a real small runtime — Cordis `Context`, the
+ * renderer-owned `SlotRegistry`, the `ui-session` adapter, and the UI renderer — assembled around
+ * test-owned session/workspace doubles and a fail-loud file-upload stub, so feature specs exercise
+ * declaration, registration, scope, store, inject, rendering, updates, and
+ * disposal without hand-building the machinery per suite.
+ *
+ * Not part of the product plugin graph (no `qilin.client`); feature packages
+ * depend on it in devDependencies only. It copies no SlotCore/renderer/store
+ * machinery — everything mounts the production implementations.
+ * @module @qilin-agent/client-test-runtime
+ */
+import { Context } from '@qilin-agent/kylin';
+import type { Fiber, Plugin } from '@qilin-agent/kylin';
+import type { RenderResult } from '@testing-library/react';
+import type { queries } from '@testing-library/dom';
+import type { BoundFunctions } from '@testing-library/dom';
+import { SlotRegistry } from '@qilin-agent/client-ui-renderer/client';
+import type { SessionReference } from '@qilin-agent/api-session-controller/client';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { PanelInfo } from '@qilin-agent/client-ui-layout/client';
+import type { ChildrenDecl, ComposedProps, HostObservable, OwnerOf, RenderOpts, SlotComponent, SlotMap, SlotRenderer, SlotFactoryMap, SnapshotSelectorHook, StoredFactory, StoreInstanceLike } from '@qilin-agent/client-ui-slots';
+import { TestRemote } from './remote.ts';
+import { TestSessions } from './sessions.ts';
+import { TestWorkspaces } from './workspaces.ts';
+import type { Stabilizer } from './fixtures.ts';
+export type { UseSession } from '@qilin-agent/client-ui-session/client';
+export { domSnapshotSerializer, registerDomSnapshotSerializer } from './snapshot.ts';
+export { FixtureSession, TestSessions } from './sessions.ts';
+export { stubConfigForm } from './config-form.ts';
+export type { StubConfigForm } from './config-form.ts';
+export { scriptedSettingsRemote } from './settings-remote.ts';
+export type { ScriptedNamespace, ScriptedSettingsRemote } from './settings-remote.ts';
+export { TestWorkspaces } from './workspaces.ts';
+export { RemoteError, TestRemote } from './remote.ts';
+export { chatSnapshot, conversationSnapshot, sessionSnapshot, workspaceSnapshot, } from './fixtures.ts';
+export type { FixtureSnapshot, SessionBehaviorOverrides, SessionFixture, SessionFixtureSnapshot, Stabilizer, } from './fixtures.ts';
+export { makeTranslate } from './translate.ts';
+export { usePinnedBrowserLanguages } from './locale-env.ts';
+/**
+ * Bind an observable source to the production renderer's selector hook.
+ * @param source - Observable snapshot source.
+ * @returns Typed React selector hook.
+ */
+export declare function bindSnapshotSelector<T>(source: HostObservable<T>): SnapshotSelectorHook<T>;
+/**
+ * Create the production slot renderer used by client feature tests.
+ * @returns Slot renderer instance.
+ */
+export declare function createSlotRenderer(): SlotRenderer;
+/** Per-view render options; the caller owns the explicitly supplied Session reference. */
+export interface SlotTestRenderOptions extends RenderOpts {
+    readonly session?: SessionReference | undefined;
+}
+/**
+ * One rendered slot's local view, from {@link SlotTestRuntime.renderSlot}:
+ * the renderer's own `[data-slot]` outlet anchor is the snapshot root
+ * (`expect(view.container).toMatchSnapshot()` captures exactly this slot's
+ * output), Testing Library queries are bound inside it, and `update`
+ * re-renders with new owner props.
+ */
+export interface SlotView<K extends keyof SlotMap & string> {
+    /** The renderer's `<div data-slot="<key>">` anchor around the slot's rendered output. */
+    readonly container: HTMLElement;
+    /** Testing Library queries scoped to {@link SlotView.container}. */
+    readonly view: BoundFunctions<typeof queries>;
+    /**
+     * Replace the owner props and flush the re-render (the render-site update:
+     * in production the owner recomputes the share and React re-renders).
+     * @param owner - the next owner props share.
+     * @param opts - replacement render options and borrowed reference; omission keeps this view's options.
+     */
+    update(owner: OwnerOf<K>, opts?: SlotTestRenderOptions): void;
+}
+/**
+ * Mounted feature plugin handle: the live fiber plus an act-wrapped,
+ * idempotent dispose (unload cascade: entries, declared child slots, store
+ * instances, and provided services all fall together).
+ */
+export interface FeatureHandle {
+    /** The plugin's live Cordis fiber (state assertions, escape hatch). */
+    readonly fiber: Fiber;
+    /**
+     * Dispose the plugin fiber inside React act; repeated calls no-op.
+     * @returns completion of the unload cascade.
+     */
+    dispose(): Promise<void>;
+}
+/** Mutable fail-loud file-upload stub installed by {@link SlotTestRuntime}. */
+export interface TestFileUpload {
+    /** Test-supplied upload behavior; the default rejects every call. */
+    upload: (sessionId: SessionId, ...args: unknown[]) => Promise<unknown>;
+}
+/**
+ * The test-owned 'root' occupant: declares the child slots a suite needs
+ * through the REAL `slots.register`, with a caller-supplied minimal frame —
+ * the runtime never guesses a feature's page structure.
+ */
+export declare class TestRoot {
+    private readonly slots;
+    private readonly stabilize;
+    private disposeEntry;
+    /**
+     * @param slots - the runtime SlotRegistry.
+     * @param stabilize - the owning runtime's act wrapper.
+     */
+    constructor(slots: SlotRegistry, stabilize: Stabilizer);
+    /**
+     * Register the root frame, declaring (and thereby claiming) the child
+     * slots. One declaration per runtime — a second call fails loud in the
+     * core ('root' is a single slot).
+     * @param children - child-slot declaration table (declaration + render authorization + runtime spec).
+     * @param frame - minimal frame component; its props derive from the declared keys (composed-props contract).
+     * @returns completion of the act-wrapped registration.
+     */
+    declare<const D extends ChildrenDecl>(children: D, frame: SlotComponent<ComposedProps<'root', never, keyof NoInfer<D> & keyof SlotMap & string, undefined, object>>): Promise<void>;
+    /** Remove the root registration and collapse its declarations (runtime dispose path). */
+    release(): void;
+}
+/**
+ * The assembled test runtime. Obtain via {@link SlotTestRuntime.create};
+ * dispose with {@link SlotTestRuntime.dispose} (afterEach). Public mutators
+ * are act-wrapped throughout — tests never handle SlotCore microtask
+ * batching or React act themselves.
+ */
+export declare class SlotTestRuntime {
+    /** The runtime's Cordis root for owner APIs and explicit test-only services. */
+    readonly ctx: Context;
+    /** The production SlotRegistry mounted on {@link SlotTestRuntime.ctx}. */
+    readonly slots: SlotRegistry;
+    /** The test-owned 'root' occupant. */
+    readonly root: TestRoot;
+    /** Fixture catalog, explicit references, scoped contexts, and behavior faces. */
+    readonly sessions: TestSessions;
+    /** One Remote double shared by every feature mounted in this runtime. */
+    readonly remote: TestRemote;
+    /** Workspaces double (list observable, recorded intent actions). */
+    readonly workspaces: TestWorkspaces;
+    /** Test-owned panel selection used by the framework's usePanelInfo hook. */
+    readonly panelInfo: import("@qilin-agent/client-store").SnapshotStore<PanelInfo>;
+    /** Mutable file-upload stub; replace `upload` in suites that exercise the capability. */
+    readonly fileUpload: TestFileUpload;
+    private readonly stabilizer;
+    private host;
+    private readonly views;
+    private readonly handles;
+    private disposed;
+    /** Auto-frame state ({@link SlotTestRuntime.declare} / {@link SlotTestRuntime.renderSlot}). */
+    private readonly ownerCell;
+    private readonly autoDeclared;
+    private autoRootView;
+    private readonly disposeWorkspaceSource;
+    private readonly disposePanelInfoSource;
+    private constructor();
+    /**
+     * Assemble a runtime: real Context, mounted SlotRegistry, installed
+     * renderer, and the session/workspace doubles provided as services.
+     * @param options - the shortcuts stub is mounted unless `shortcuts: false`,
+     *   which lets a spec provide the real shortcuts service instead.
+     * @returns the ready runtime.
+     */
+    static create(options?: {
+        shortcuts?: boolean;
+    }): Promise<SlotTestRuntime>;
+    /**
+     * Mount a feature plugin on a real fiber. Required services are prechecked
+     * so a missing provider fails loud instead of suspending the fiber forever
+     * (deliberate load-order suspension tests use `ctx.plugin` directly).
+     * @param plugin - plugin value (function, class, or `{ inject, apply }` object).
+     * @returns handle owning the fiber's explicit disposal.
+     */
+    mount(plugin: Plugin): Promise<FeatureHandle>;
+    /** Release the default Workspace hook before mounting its production owner. */
+    releaseWorkspaceSource(): void;
+    /** Release the default panel hook before mounting the production Layout owner. */
+    releasePanelInfoSource(): void;
+    /**
+     * Render the root slot tree through the ctx-level entry (the shell's own
+     * entry point): `ctx.slots.renderSlot('root', {})` under Testing Library.
+     * @returns the Testing Library view.
+     */
+    renderRoot(): RenderResult;
+    /**
+     * Declare child slots under an auto-generated root frame — the single-slot
+     * mounting path for local DOM snapshots. Each key later supplied through
+     * {@link SlotTestRuntime.renderSlot} renders inside the renderer's own
+     * `<div data-slot="<key>">` outlet anchor (the snapshot root — the frame
+     * adds no wrapper of its own). Mutually exclusive with
+     * {@link TestRoot.declare} ('root' is a single slot); one call per runtime.
+     * @param children - child-slot declaration table (same contract as TestRoot.declare).
+     * @returns completion of the act-wrapped registration.
+     */
+    declare(children: ChildrenDecl): Promise<void>;
+    /**
+     * Render one declared slot with its owner props and return the local view.
+     * The whole root tree mounts through the production assembly path
+     * (renderer, scope providers, store axis); only this key's output lands in
+     * the returned container. Call again with another key to view a sibling
+     * slot of the same tree.
+     * @param key - a key declared through {@link SlotTestRuntime.declare}.
+     * @param owner - owner props share for the render site.
+     * @param opts - explicit entry selection and borrowed Session reference; retained by view updates.
+     * @returns the slot-local view (snapshot container, scoped queries, owner updates).
+     */
+    renderSlot<K extends keyof SlotMap & string>(key: K, owner: OwnerOf<K>, opts?: SlotTestRenderOptions): SlotView<K>;
+    /**
+     * Resolve the store instance the renderer would hand a slot's component
+     * (identity assertions, action-driven writes). Requires a prior
+     * {@link SlotTestRuntime.renderRoot} — the host face exists only inside the
+     * installed renderer, exactly as in production.
+     * @param key - slot key whose first entry declares the store.
+     * @param session - retained Session reference for session-scope slots; omit for root scope.
+     * @returns the live store instance.
+     */
+    storeOf(key: keyof SlotMap & string, session?: SessionReference): StoreInstanceLike;
+    /**
+     * Read one registered Factory definition for direct contract assertions.
+     * @param name - registered Factory name.
+     * @returns the live Factory definition.
+     */
+    factoryOf(name: keyof SlotFactoryMap & string): StoredFactory;
+    /**
+     * Flush pending ledger/store notifications inside act — for mutations made
+     * outside the runtime's own methods (e.g. a direct `slots.register`).
+     * @returns completion of the act pass.
+     */
+    flush(): Promise<void>;
+    /**
+     * Tear down: unmount React trees first, then dispose feature fibers, the
+     * root registration and standard sources, minted session scopes, and persisted test state.
+     * Idempotent.
+     * @returns completion of the teardown.
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/locale-env.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pin `navigator.languages`/`navigator.language` for every test in the
+ * calling file (or describe block), restoring the environment's own values
+ * afterwards. Call at suite level, like the other vitest hooks.
+ * @param primary - most preferred BCP 47 tag; also becomes `navigator.language`.
+ * @param rest - further tags in preference order.
+ */
+export declare function usePinnedBrowserLanguages(primary: string, ...rest: string[]): void;
+//# sourceMappingURL=locale-env.d.ts.map