@fluentui-react-native/desktop-driver 0.2.0

package/lib/wdio/DesktopWebdriver.test.js

@@ -0,0 +1,74 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createDesktopDriverStoryHarness } from '../testing/protocolHarness.js';
+describe('sanctioned WebdriverIO API', () => {
+    test('lists and runs an authored plan through registered browser commands', async () => {
+        const manifest = {
+            endpoint: 'windows',
+            entries: [
+                {
+                    id: 'components-button--default',
+                    name: 'Default',
+                    packageName: '@fluentui-react-native/components',
+                    sourcePath: 'src/components/button/button.stories.tsx',
+                    tags: ['e2e', 'story'],
+                    tests: {
+                        version: 1,
+                        tests: [
+                            {
+                                id: 'click',
+                                steps: [
+                                    { action: 'click', target: { testId: 'button-primary' } },
+                                    { expect: { state: 'focused', target: { testId: 'button-primary' }, value: true } },
+                                ],
+                            },
+                        ],
+                    },
+                    title: 'Components/Button',
+                },
+            ],
+            platformManifestDigest: 'platform-digest',
+            portablePlanDigest: 'portable-digest',
+            schemaVersion: 1,
+        };
+        const harness = await createDesktopDriverStoryHarness(manifest);
+        const artifactsRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-driver-wdio-'));
+        try {
+            const response = await runContract(harness.server.url, harness.target.id, artifactsRoot);
+            expect(response).toMatchObject({
+                manifestEntries: 1,
+                result: {
+                    status: 'passed',
+                    tests: [{ status: 'passed', storyId: 'components-button--default', testId: 'click' }],
+                },
+            });
+            expect(fs.existsSync(path.join(artifactsRoot, 'run.json'))).toBe(true);
+        }
+        finally {
+            await harness.close();
+            fs.rmSync(artifactsRoot, { force: true, recursive: true });
+        }
+    });
+});
+function runContract(url, targetId, artifactsRoot) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [path.join(__dirname, 'wdioRunner.contract.cjs'), url, targetId, artifactsRoot], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        child.once('error', reject);
+        child.once('exit', (code) => {
+            if (code !== 0) {
+                reject(new Error(Buffer.concat(stderr).toString('utf8') || `WebdriverIO runner exited with code ${code}.`));
+                return;
+            }
+            resolve(JSON.parse(Buffer.concat(stdout).toString('utf8')));
+        });
+    });
+}
+//# sourceMappingURL=DesktopWebdriver.test.js.map

package/lib/wdio/DesktopWebdriver.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DesktopWebdriver.test.js","sourceRoot":"","sources":["../../src/wdio/DesktopWebdriver.test.ts"],"names":[],"mappings":"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"}

package/lib/wdio/index.d.ts

@@ -0,0 +1,3 @@
+export { connectDesktopWebdriver, DesktopWebdriverSession } from './DesktopWebdriver.js';
+export type { DesktopWebdriverOptions, DesktopWebdriverRunOptions } from './DesktopWebdriver.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/wdio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wdio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACzF,YAAY,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC"}

package/lib/wdio/index.js

@@ -0,0 +1,2 @@
+export { connectDesktopWebdriver, DesktopWebdriverSession } from './DesktopWebdriver.js';
+//# sourceMappingURL=index.js.map

package/lib/wdio/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/wdio/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}

package/lib/wdio/wdioRunner.contract.cjs

@@ -0,0 +1,64 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+async function main() {
+    const moduleUrl = pathToFileURL(path.resolve(__dirname, '..', '..', 'lib', 'wdio', 'index.js')).href;
+    const { connectDesktopWebdriver } = await Promise.resolve(`${moduleUrl}`).then(s => __importStar(require(s)));
+    const [url, targetId, artifactsRoot] = process.argv.slice(2);
+    const desktop = await connectDesktopWebdriver({
+        platformName: 'windows',
+        targetId,
+        url,
+    });
+    try {
+        const manifest = await desktop.browser.desktopListStories();
+        await desktop.browser.desktopExpect({
+            state: 'enabled',
+            target: { testId: 'button-primary' },
+            value: true,
+        });
+        const result = await desktop.browser.desktopRunStoryTests({ artifactsRoot });
+        process.stdout.write(JSON.stringify({ manifestEntries: manifest.entries.length, result }));
+    }
+    finally {
+        await desktop.delete();
+    }
+}
+main().catch((error) => {
+    process.stderr.write(error.stack ?? error.message);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=wdioRunner.contract.cjs.map

package/lib/wdio/wdioRunner.contract.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"wdioRunner.contract.cjs","sourceRoot":"","sources":["../../src/wdio/wdioRunner.contract.cjs"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AAClC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAE9C,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;IACrG,MAAM,EAAE,uBAAuB,EAAE,GAAG,yBAAa,SAAS,uCAAC,CAAC;IAC5D,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC;QAC5C,YAAY,EAAE,SAAS;QACvB,QAAQ;QACR,GAAG;KACJ,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;QAC5D,MAAM,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC;YAClC,KAAK,EAAE,SAAS;YAChB,MAAM,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE;YACpC,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;QAC7E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7F,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/lib/wdio/wdioRunner.contract.d.cts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=wdioRunner.contract.d.cts.map

package/lib/wdio/wdioRunner.contract.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wdioRunner.contract.d.cts","sourceRoot":"","sources":["../../src/wdio/wdioRunner.contract.cjs"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@fluentui-react-native/desktop-driver",
+  "version": "0.2.0",
+  "description": "W3C WebDriver-compatible automation for React Native desktop applications",
+  "license": "MIT",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/fluentui-react-native.git",
+    "directory": "packages/agentic/desktop-driver"
+  },
+  "bin": "./config/cli.cjs",
+  "type": "module",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./src/index.ts"
+    },
+    "./client": {
+      "types": "./lib/client/index.d.ts",
+      "import": "./lib/client/index.js",
+      "default": "./src/client/index.ts"
+    },
+    "./cli": {
+      "types": "./lib/cli/index.d.ts",
+      "import": "./lib/cli/index.js",
+      "default": "./src/cli/index.ts"
+    },
+    "./authoring": {
+      "types": "./lib/authoring/index.d.ts",
+      "import": "./lib/authoring/index.js",
+      "default": "./src/authoring/index.ts"
+    },
+    "./agent": {
+      "types": "./lib/agent/index.d.ts",
+      "import": "./lib/agent/index.js",
+      "default": "./src/agent/index.ts"
+    },
+    "./artifacts": {
+      "types": "./lib/artifacts/index.d.ts",
+      "import": "./lib/artifacts/index.js",
+      "default": "./src/artifacts/index.ts"
+    },
+    "./server": {
+      "types": "./lib/server/index.d.ts",
+      "import": "./lib/server/index.js",
+      "default": "./src/server/index.ts"
+    },
+    "./storybook": {
+      "types": "./lib/storybook.d.ts",
+      "import": "./lib/storybook.js",
+      "default": "./src/storybook.ts"
+    },
+    "./testing": {
+      "types": "./lib/testing/index.d.ts",
+      "import": "./lib/testing/index.js",
+      "default": "./src/testing/index.ts"
+    },
+    "./wdio": {
+      "types": "./lib/wdio/index.d.ts",
+      "import": "./lib/wdio/index.js",
+      "default": "./src/wdio/index.ts"
+    },
+    "./runner": {
+      "types": "./lib/runner/index.d.ts",
+      "import": "./lib/runner/index.js",
+      "default": "./src/runner/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "fluentui-scripts clean",
+    "format": "fluentui-scripts format",
+    "lint": "fluentui-scripts lint",
+    "test": "fluentui-scripts jest"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "webdriverio": "^9.24.0"
+  },
+  "devDependencies": {
+    "@fluentui-react-native/scripts": "0.1.0"
+  },
+  "furn": {
+    "jestPlatform": "react"
+  },
+  "rnx-kit": {
+    "kitType": "library",
+    "extends": "@fluentui-react-native/scripts/kit-config"
+  }
+}

package/src/agent/DesktopAgent.test.ts

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createDesktopDriverClient } from '../client/DesktopDriverClient.js';
+import type { DesktopStoryManifest } from '../storybook.js';
+import { createDesktopDriverTestHarness } from '../testing/protocolHarness.js';
+import { createDesktopDriverStoryHarness } from '../testing/protocolHarness.js';
+import { connectDesktopAgent } from './DesktopAgent.js';
+
+describe('DesktopAgent', () => {
+  test('lists, explains, inspects, acts, checks, captures, and runs the same authored plan', async () => {
+    const manifest: DesktopStoryManifest = {
+      endpoint: 'windows',
+      entries: [
+        {
+          id: 'components-button--default',
+          name: 'Default',
+          packageName: '@fluentui-react-native/components',
+          sourcePath: 'src/components/button/button.stories.tsx',
+          tags: ['e2e', 'story'],
+          tests: {
+            version: 1,
+            tests: [
+              {
+                id: 'agent-plan',
+                steps: [{ expect: { state: 'enabled', target: { testId: 'button-primary' }, value: true } }],
+              },
+            ],
+          },
+          title: 'Components/Button',
+        },
+      ],
+      platformManifestDigest: 'platform-digest',
+      portablePlanDigest: 'portable-digest',
+      schemaVersion: 1,
+    };
+    const harness = await createDesktopDriverStoryHarness(manifest);
+    const artifactsRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-driver-agent-'));
+    try {
+      const response = await runContract(harness.server.url, harness.target.id, artifactsRoot);
+      expect(response).toMatchObject({
+        check: { passed: true },
+        run: { status: 'passed', tests: [{ testId: 'agent-plan' }] },
+        screenshot: { kind: 'screenshot', name: 'agent-button' },
+        stories: 1,
+        tree: 1,
+      });
+      expect(fs.existsSync(path.join(artifactsRoot, 'run.json'))).toBe(true);
+    } finally {
+      await harness.close();
+      fs.rmSync(artifactsRoot, { force: true, recursive: true });
+    }
+  });
+
+  test('validates the artifact root before reserving a target session', async () => {
+    const harness = await createDesktopDriverTestHarness();
+    const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-driver-agent-invalid-'));
+    const invalidRoot = path.join(temporaryDirectory, 'file');
+    fs.writeFileSync(invalidRoot, 'not a directory');
+    try {
+      await expect(
+        connectDesktopAgent({
+          artifactsRoot: invalidRoot,
+          platformName: 'windows',
+          targetId: harness.target.id,
+          url: harness.server.url,
+        }),
+      ).rejects.toThrow();
+
+      const client = createDesktopDriverClient({ url: harness.server.url });
+      const session = await client.newSession({
+        alwaysMatch: { platformName: 'windows', 'furn:target': harness.target.id },
+      });
+      await session.delete();
+    } finally {
+      await harness.close();
+      fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+    }
+  });
+});
+
+function runContract(url: string, targetId: string, artifactsRoot: string): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [path.join(__dirname, 'agent.contract.cjs'), url, targetId, artifactsRoot], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk));
+    child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk));
+    child.once('error', reject);
+    child.once('exit', (code) => {
+      if (code !== 0) {
+        reject(new Error(Buffer.concat(stderr).toString('utf8') || `Desktop agent exited with code ${code}.`));
+        return;
+      }
+      resolve(JSON.parse(Buffer.concat(stdout).toString('utf8')) as Record<string, unknown>);
+    });
+  });
+}

package/src/agent/DesktopAgent.ts

@@ -0,0 +1,170 @@
+import type { DesktopArtifact, DesktopStoryRunResult } from '../authoring/results.js';
+import type { DesktopStoryExpectation, DesktopStorySelector } from '../authoring/storyTests.js';
+import { ArtifactManager } from '../artifacts/ArtifactManager.js';
+import type { DesktopTreeNode } from '../host/types.js';
+import { DesktopAssertionError, assertDesktopExpectation, findDesktopElement } from '../runner/StoryTestRunner.js';
+import { WebDriverError } from '../protocol/errors.js';
+import type { DesktopStoryManifestEntry } from '../storybook.js';
+import { connectDesktopWebdriver } from '../wdio/DesktopWebdriver.js';
+import type { DesktopWebdriverOptions, DesktopWebdriverSession } from '../wdio/DesktopWebdriver.js';
+
+export type DesktopAgentOptions = DesktopWebdriverOptions & {
+  artifactsRoot: string;
+};
+
+export type DesktopAgentStory = Pick<DesktopStoryManifestEntry, 'id' | 'name' | 'tags' | 'title'> & {
+  tests: readonly { id: string; title: string }[];
+};
+
+export type DesktopAgentElement = {
+  accessibleName: unknown;
+  enabled: boolean;
+  id: string;
+  role: string;
+  selected: boolean;
+  text: string;
+};
+
+export type DesktopAgentCheckResult = {
+  message?: string;
+  passed: boolean;
+};
+
+export type DesktopAgentDescribeOptions = {
+  depth?: number;
+  maxNodes?: number;
+  scope?: 'application' | 'story';
+};
+
+export class DesktopAgent {
+  private readonly artifacts: ArtifactManager;
+  private readonly desktop: DesktopWebdriverSession;
+  private readonly captured: DesktopArtifact[] = [];
+
+  constructor(desktop: DesktopWebdriverSession, artifacts: ArtifactManager) {
+    this.desktop = desktop;
+    this.artifacts = artifacts;
+  }
+
+  async listStories(): Promise<DesktopAgentStory[]> {
+    const manifest = await this.desktop.listStories();
+    return manifest.entries.map((entry) => ({
+      id: entry.id,
+      name: entry.name,
+      tags: entry.tags,
+      tests: (entry.tests?.tests ?? []).map((test) => ({ id: test.id, title: test.title ?? test.id })),
+      title: entry.title,
+    }));
+  }
+
+  async explainStory(storyId: string): Promise<DesktopAgentStory> {
+    const story = (await this.listStories()).find(({ id }) => id === storyId);
+    if (!story) {
+      throw new Error(`Story "${storyId}" is not present in the active platform manifest.`);
+    }
+    return story;
+  }
+
+  openStory(storyId: string): Promise<{ previewGeneration: number; runId: string; storyId: string }> {
+    return this.desktop.openStory(storyId);
+  }
+
+  async describe(options: DesktopAgentDescribeOptions = {}): Promise<DesktopTreeNode[]> {
+    const depth = options.depth ?? 3;
+    const maxNodes = options.maxNodes ?? 100;
+    if (!Number.isInteger(depth) || depth < 0 || !Number.isInteger(maxNodes) || maxNodes < 1) {
+      throw new TypeError('Agent tree depth must be non-negative and maxNodes must be positive.');
+    }
+    const roots = await this.desktop.session.getTree();
+    const scoped =
+      options.scope === 'story'
+        ? roots.flatMap((root) =>
+            findTreeNodes(root, (node) => node.testId === 'story-root' || (node.testId?.endsWith('-story-root') ?? false)),
+          )
+        : roots;
+    let remaining = maxNodes;
+    return scoped.flatMap((root) => {
+      const projected = projectTree(root, depth, () => remaining-- > 0);
+      return projected ? [projected] : [];
+    });
+  }
+
+  async find(selector: DesktopStorySelector): Promise<DesktopAgentElement> {
+    const element = await findDesktopElement(this.desktop.session, selector);
+    return {
+      accessibleName: await element.getAttribute('name'),
+      enabled: await element.isEnabled(),
+      id: element.id,
+      role: await element.getTagName(),
+      selected: await element.isSelected(),
+      text: await element.getText(),
+    };
+  }
+
+  async click(selector: DesktopStorySelector): Promise<void> {
+    await (await findDesktopElement(this.desktop.session, selector)).click();
+  }
+
+  async type(selector: DesktopStorySelector, text: string): Promise<void> {
+    await (await findDesktopElement(this.desktop.session, selector)).sendKeys(text);
+  }
+
+  async check(expectation: DesktopStoryExpectation): Promise<DesktopAgentCheckResult> {
+    try {
+      await assertDesktopExpectation(this.desktop.session, expectation);
+      return { passed: true };
+    } catch (error) {
+      if (error instanceof DesktopAssertionError || (error instanceof WebDriverError && error.code === 'no such element')) {
+        return { message: error.message, passed: false };
+      }
+      throw error;
+    }
+  }
+
+  async screenshot(name: string): Promise<DesktopArtifact> {
+    const artifact = this.artifacts.writeScreenshot('agent', name, await this.desktop.session.takeScreenshot());
+    this.captured.push(artifact);
+    return artifact;
+  }
+
+  runStoryTest(storyId: string, testId: string): Promise<DesktopStoryRunResult> {
+    return this.desktop.runStoryTests({
+      artifactsRoot: this.artifacts.root,
+      selection: { story: storyId, test: testId },
+    });
+  }
+
+  getArtifacts(): readonly DesktopArtifact[] {
+    return [...this.captured];
+  }
+
+  delete(): Promise<void> {
+    return this.desktop.delete();
+  }
+}
+
+export async function connectDesktopAgent(options: DesktopAgentOptions): Promise<DesktopAgent> {
+  const artifacts = new ArtifactManager(options.artifactsRoot);
+  const desktop = await connectDesktopWebdriver(options);
+  return new DesktopAgent(desktop, artifacts);
+}
+
+function findTreeNodes(node: DesktopTreeNode, predicate: (node: DesktopTreeNode) => boolean): DesktopTreeNode[] {
+  return [...(predicate(node) ? [node] : []), ...node.children.flatMap((child) => findTreeNodes(child, predicate))];
+}
+
+function projectTree(node: DesktopTreeNode, depth: number, take: () => boolean): DesktopTreeNode | undefined {
+  if (!take()) {
+    return undefined;
+  }
+  return {
+    ...node,
+    children:
+      depth === 0
+        ? []
+        : node.children.flatMap((child) => {
+            const projected = projectTree(child, depth - 1, take);
+            return projected ? [projected] : [];
+          }),
+  };
+}

package/src/agent/agent.contract.cjs

@@ -0,0 +1,32 @@
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+async function main() {
+  const moduleUrl = pathToFileURL(path.resolve(__dirname, '..', '..', 'lib', 'agent', 'index.js')).href;
+  const { connectDesktopAgent } = await import(moduleUrl);
+  const [url, targetId, artifactsRoot] = process.argv.slice(2);
+  const agent = await connectDesktopAgent({
+    artifactsRoot,
+    platformName: 'windows',
+    targetId,
+    url,
+  });
+  try {
+    const stories = await agent.listStories();
+    const story = await agent.explainStory('components-button--default');
+    await agent.openStory(story.id);
+    const tree = await agent.describe({ depth: 2, maxNodes: 10, scope: 'story' });
+    await agent.click({ testId: 'button-primary' });
+    const check = await agent.check({ state: 'focused', target: { testId: 'button-primary' }, value: true });
+    const screenshot = await agent.screenshot('agent-button');
+    const run = await agent.runStoryTest(story.id, 'agent-plan');
+    process.stdout.write(JSON.stringify({ check, run, screenshot, stories: stories.length, tree: tree.length }));
+  } finally {
+    await agent.delete();
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(error.stack ?? error.message);
+  process.exitCode = 1;
+});

package/src/agent/index.ts

@@ -0,0 +1,8 @@
+export { connectDesktopAgent, DesktopAgent } from './DesktopAgent.js';
+export type {
+  DesktopAgentCheckResult,
+  DesktopAgentDescribeOptions,
+  DesktopAgentElement,
+  DesktopAgentOptions,
+  DesktopAgentStory,
+} from './DesktopAgent.js';

package/src/artifacts/ArtifactManager.test.ts

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { ArtifactManager } from './ArtifactManager.js';
+
+describe('ArtifactManager', () => {
+  test('confines and atomically writes artifacts beneath the run root', () => {
+    const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-driver-artifacts-'));
+    try {
+      const manager = new ArtifactManager(temporaryDirectory);
+      const artifact = manager.writeSource('../story:id', '../source', '<application />');
+
+      expect(artifact.path).toBe('tests/-story-id/-source.xml');
+      expect(fs.readFileSync(path.join(temporaryDirectory, ...artifact.path.split('/')), 'utf8')).toBe('<application />');
+    } finally {
+      fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+    }
+  });
+});