@r-machine/testing 1.0.0-alpha.11

package/README.md

@@ -0,0 +1,26 @@
+⚠️ **WARNING: THIS LIBRARY IS STILL IN DEVELOPMENT** ⚠️
+
+---
+
+<img src="r-machine.logo.svg" width="158px" align="center" alt="R-Machine logo" />
+
+# @r-machine/testing — Testing utilities for R-Machine
+
+[![NPM Version](https://img.shields.io/npm/v/%40r-machine%2Ftesting?label=latest)](https://www.npmjs.com/package/@r-machine/testing)
+[![R-Machine CI status](https://github.com/codecarvings/r-machine/actions/workflows/ci.yml/badge.svg?event=push&branch=main)](https://github.com/codecarvings/r-machine/actions/workflows/ci.yml?query=branch%3Amain)
+
+---
+
+## License
+
+`@r-machine/testing` is licensed under the
+[GNU Affero General Public License v3.0](./LICENSE) (AGPL-3.0-only).
+
+This means:
+
+- ✅ Free to use in open source projects with a compatible license
+- ✅ Free to modify and distribute under the same terms
+- ❌ **Cannot** be used in closed-source / proprietary software
+
+> If you need to use `@r-machine/testing` in a proprietary project,
+> reach out at licensing@codecarvings.com to discuss a commercial arrangement.

package/errors/error-codes.cjs

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of @r-machine/testing, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERR_VERIFY_SETUP_INVALID = exports.ERR_PLUG_ALREADY_MOCKED = void 0;
+// RMachineUsageError
+exports.ERR_PLUG_ALREADY_MOCKED = "ERR_PLUG_ALREADY_MOCKED";
+exports.ERR_VERIFY_SETUP_INVALID = "ERR_VERIFY_SETUP_INVALID";

package/errors/error-codes.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of @r-machine/testing, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export declare const ERR_PLUG_ALREADY_MOCKED = "ERR_PLUG_ALREADY_MOCKED";
+export declare const ERR_VERIFY_SETUP_INVALID = "ERR_VERIFY_SETUP_INVALID";

package/errors/error-codes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of @r-machine/testing, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export declare const ERR_PLUG_ALREADY_MOCKED = "ERR_PLUG_ALREADY_MOCKED";
+export declare const ERR_VERIFY_SETUP_INVALID = "ERR_VERIFY_SETUP_INVALID";

package/errors/error-codes.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of @r-machine/testing, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+// RMachineUsageError
+export const ERR_PLUG_ALREADY_MOCKED = "ERR_PLUG_ALREADY_MOCKED";
+export const ERR_VERIFY_SETUP_INVALID = "ERR_VERIFY_SETUP_INVALID";

package/errors/index.cjs

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of @r-machine/testing, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERR_VERIFY_SETUP_INVALID = exports.ERR_PLUG_ALREADY_MOCKED = void 0;
+var error_codes_js_1 = require("./error-codes.cjs");
+Object.defineProperty(exports, "ERR_PLUG_ALREADY_MOCKED", { enumerable: true, get: function () { return error_codes_js_1.ERR_PLUG_ALREADY_MOCKED; } });
+Object.defineProperty(exports, "ERR_VERIFY_SETUP_INVALID", { enumerable: true, get: function () { return error_codes_js_1.ERR_VERIFY_SETUP_INVALID; } });

package/errors/index.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of @r-machine/testing, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export { ERR_PLUG_ALREADY_MOCKED, ERR_VERIFY_SETUP_INVALID } from "./error-codes.cjs";

package/errors/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of @r-machine/testing, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export { ERR_PLUG_ALREADY_MOCKED, ERR_VERIFY_SETUP_INVALID } from "./error-codes.js";

package/errors/index.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of @r-machine/testing, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export { ERR_PLUG_ALREADY_MOCKED, ERR_VERIFY_SETUP_INVALID } from "./error-codes.js";

package/lib/event-collector.cjs

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEventCollector = createEventCollector;
+const core_1 = require("r-machine/core");
+/**
+ * Subscribe a buffer to the runtime event bus of the given R-Machine
+ * instance (reached via a strategy or RMachine itself). The returned
+ * collector accumulates every emitted internal event in insertion order
+ * until disposed.
+ *
+ * Designed for test isolation: each call creates a private buffer with
+ * its own subscription, so parallel tests don't share state as long as
+ * each test uses its own strategy/machine instance.
+ */
+function createEventCollector(target) {
+    const events = [];
+    const unsubscribe = target[core_1.BUS_ACCESSOR]().subscribe((event) => {
+        events.push(event);
+    });
+    let disposed = false;
+    return {
+        get events() {
+            return events;
+        },
+        clear() {
+            events.length = 0;
+        },
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            unsubscribe();
+        },
+    };
+}

package/lib/event-collector.d.cts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+import { type BusBridge, type InternalEvent } from "r-machine/core";
+export interface EventCollector {
+    /**
+     * Events collected so far, in emit order. Treat as read-only — mutating
+     * this array will not affect future collection but will surprise other
+     * readers. Use `clear()` to reset.
+     */
+    readonly events: readonly InternalEvent[];
+    /**
+     * Drop all collected events. Useful between phases of a test when you
+     * want to assert on a fresh window without re-creating the collector.
+     */
+    clear(): void;
+    /**
+     * Unsubscribe from the bus. After dispose, `events` no longer grows.
+     * Safe to call multiple times.
+     */
+    dispose(): void;
+}
+/**
+ * Subscribe a buffer to the runtime event bus of the given R-Machine
+ * instance (reached via a strategy or RMachine itself). The returned
+ * collector accumulates every emitted internal event in insertion order
+ * until disposed.
+ *
+ * Designed for test isolation: each call creates a private buffer with
+ * its own subscription, so parallel tests don't share state as long as
+ * each test uses its own strategy/machine instance.
+ */
+export declare function createEventCollector(target: BusBridge): EventCollector;

package/lib/event-collector.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+import { type BusBridge, type InternalEvent } from "r-machine/core";
+export interface EventCollector {
+    /**
+     * Events collected so far, in emit order. Treat as read-only — mutating
+     * this array will not affect future collection but will surprise other
+     * readers. Use `clear()` to reset.
+     */
+    readonly events: readonly InternalEvent[];
+    /**
+     * Drop all collected events. Useful between phases of a test when you
+     * want to assert on a fresh window without re-creating the collector.
+     */
+    clear(): void;
+    /**
+     * Unsubscribe from the bus. After dispose, `events` no longer grows.
+     * Safe to call multiple times.
+     */
+    dispose(): void;
+}
+/**
+ * Subscribe a buffer to the runtime event bus of the given R-Machine
+ * instance (reached via a strategy or RMachine itself). The returned
+ * collector accumulates every emitted internal event in insertion order
+ * until disposed.
+ *
+ * Designed for test isolation: each call creates a private buffer with
+ * its own subscription, so parallel tests don't share state as long as
+ * each test uses its own strategy/machine instance.
+ */
+export declare function createEventCollector(target: BusBridge): EventCollector;

package/lib/event-collector.js

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+import { BUS_ACCESSOR } from "r-machine/core";
+/**
+ * Subscribe a buffer to the runtime event bus of the given R-Machine
+ * instance (reached via a strategy or RMachine itself). The returned
+ * collector accumulates every emitted internal event in insertion order
+ * until disposed.
+ *
+ * Designed for test isolation: each call creates a private buffer with
+ * its own subscription, so parallel tests don't share state as long as
+ * each test uses its own strategy/machine instance.
+ */
+export function createEventCollector(target) {
+    const events = [];
+    const unsubscribe = target[BUS_ACCESSOR]().subscribe((event) => {
+        events.push(event);
+    });
+    let disposed = false;
+    return {
+        get events() {
+            return events;
+        },
+        clear() {
+            events.length = 0;
+        },
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            unsubscribe();
+        },
+    };
+}

package/lib/index.cjs

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyResourceAtlas = exports.mockPlug = exports.createEventCollector = void 0;
+var event_collector_js_1 = require("./event-collector.cjs");
+Object.defineProperty(exports, "createEventCollector", { enumerable: true, get: function () { return event_collector_js_1.createEventCollector; } });
+var mock_plug_js_1 = require("./mock-plug.cjs");
+Object.defineProperty(exports, "mockPlug", { enumerable: true, get: function () { return mock_plug_js_1.mockPlug; } });
+var verify_resource_atlas_js_1 = require("./verify-resource-atlas.cjs");
+Object.defineProperty(exports, "verifyResourceAtlas", { enumerable: true, get: function () { return verify_resource_atlas_js_1.verifyResourceAtlas; } });

package/lib/index.d.cts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export { createEventCollector, type EventCollector } from "./event-collector.cjs";
+export { mockPlug } from "./mock-plug.cjs";
+export { type SourceLocation, type VerifyIssue, type VerifyReport, type VerifyResourceAtlasOptions, verifyResourceAtlas, } from "./verify-resource-atlas.cjs";

package/lib/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export { createEventCollector, type EventCollector } from "./event-collector.js";
+export { mockPlug } from "./mock-plug.js";
+export { type SourceLocation, type VerifyIssue, type VerifyReport, type VerifyResourceAtlasOptions, verifyResourceAtlas, } from "./verify-resource-atlas.js";

package/lib/index.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export { createEventCollector } from "./event-collector.js";
+export { mockPlug } from "./mock-plug.js";
+export { verifyResourceAtlas, } from "./verify-resource-atlas.js";

package/lib/mock-plug.cjs

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockPlug = void 0;
+const core_1 = require("r-machine/core");
+const errors_1 = require("r-machine/errors");
+const errors_2 = require("#r-machine/testing/errors");
+const plugMockSymbol = Symbol("plugMock");
+const mockPlug = (plug) => {
+    return {
+        with: (_data) => {
+            const prevResolve = (0, core_1.getPlugResolve)(plug);
+            if (prevResolve[plugMockSymbol]) {
+                throw new errors_1.RMachineUsageError(errors_2.ERR_PLUG_ALREADY_MOCKED, "Plug is already mocked.");
+            }
+            const resolve = (locale, chain) => {
+                // TODO: WIP - For now, just return the original resolve result.
+                // Plan: read data.$.locale (if set) to override locale; call prevResolve; deep-merge _data.
+                // Caveat: prevResolve may install a lazy getter on $.kit[selfKey] for kit self-reference.
+                // Deep-merging enumerates kit keys and would invoke that getter; if the self-juncture isn't
+                // cached yet (factory still running), the getter throws. Handle this in the merge step —
+                // e.g. skip own-property getters or short-circuit on self-ref keys.
+                return prevResolve(locale, chain);
+            };
+            resolve[plugMockSymbol] = true;
+            (0, core_1.setPlugResolve)(plug, resolve);
+            return () => {
+                (0, core_1.setPlugResolve)(plug, prevResolve);
+            };
+        },
+    };
+};
+exports.mockPlug = mockPlug;

package/lib/mock-plug.d.cts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+import { type AnyListPlugHead, type AnyMapPlugHead, type AnyPlugHead, type ExtractCtx, type ExtractKit, type ExtractResAtlas, type PlugBody } from "r-machine/core";
+import type { MockSurfaceMap } from "./mock-surface.cjs";
+type ResetPlug = () => void;
+interface MapMockPlug<PH extends AnyMapPlugHead> {
+    readonly with: (data: MockPlugMapData<PH>) => ResetPlug;
+}
+interface ListMockPlug<PH extends AnyListPlugHead> {
+    readonly with: (data: MockPlugListData<PH>) => ResetPlug;
+}
+interface MockPlug {
+    <PH extends AnyMapPlugHead>(plug: PlugBody<PH>): MapMockPlug<PH>;
+    <PH extends AnyListPlugHead>(plug: PlugBody<PH>): ListMockPlug<PH>;
+}
+export declare const mockPlug: MockPlug;
+type MockPlugMapDataDeps<PH extends AnyMapPlugHead> = MockSurfaceMap<ExtractResAtlas<PH>, Omit<PH["deps"], "$">>;
+type TupleToObject<T extends readonly unknown[]> = {
+    [K in keyof T as K extends `${number}` ? K : never]: T[K];
+};
+type MockPlugListDeps<PH extends AnyListPlugHead> = MockSurfaceMap<ExtractResAtlas<PH>, Omit<TupleToObject<PH["deps"] extends readonly unknown[] ? PH["deps"] : never>, "$">>;
+type MockCtxContent<PH extends AnyPlugHead, C> = {
+    [K in keyof C]?: K extends "kit" ? MockSurfaceMap<ExtractResAtlas<PH>, ExtractKit<PH>> : K extends "ports" ? Partial<C[K]> : C[K];
+};
+type MockCtx<PH extends AnyPlugHead> = keyof ExtractCtx<PH> extends never ? Record<string, never> : MockCtxContent<PH, ExtractCtx<PH>>;
+type MockPlugMapData<PH extends AnyMapPlugHead> = {
+    $?: MockCtx<PH>;
+} & MockPlugMapDataDeps<PH>;
+type MockPlugListData<PH extends AnyListPlugHead> = {
+    $?: MockCtx<PH>;
+} & MockPlugListDeps<PH>;
+export {};

package/lib/mock-plug.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+import { type AnyListPlugHead, type AnyMapPlugHead, type AnyPlugHead, type ExtractCtx, type ExtractKit, type ExtractResAtlas, type PlugBody } from "r-machine/core";
+import type { MockSurfaceMap } from "./mock-surface.js";
+type ResetPlug = () => void;
+interface MapMockPlug<PH extends AnyMapPlugHead> {
+    readonly with: (data: MockPlugMapData<PH>) => ResetPlug;
+}
+interface ListMockPlug<PH extends AnyListPlugHead> {
+    readonly with: (data: MockPlugListData<PH>) => ResetPlug;
+}
+interface MockPlug {
+    <PH extends AnyMapPlugHead>(plug: PlugBody<PH>): MapMockPlug<PH>;
+    <PH extends AnyListPlugHead>(plug: PlugBody<PH>): ListMockPlug<PH>;
+}
+export declare const mockPlug: MockPlug;
+type MockPlugMapDataDeps<PH extends AnyMapPlugHead> = MockSurfaceMap<ExtractResAtlas<PH>, Omit<PH["deps"], "$">>;
+type TupleToObject<T extends readonly unknown[]> = {
+    [K in keyof T as K extends `${number}` ? K : never]: T[K];
+};
+type MockPlugListDeps<PH extends AnyListPlugHead> = MockSurfaceMap<ExtractResAtlas<PH>, Omit<TupleToObject<PH["deps"] extends readonly unknown[] ? PH["deps"] : never>, "$">>;
+type MockCtxContent<PH extends AnyPlugHead, C> = {
+    [K in keyof C]?: K extends "kit" ? MockSurfaceMap<ExtractResAtlas<PH>, ExtractKit<PH>> : K extends "ports" ? Partial<C[K]> : C[K];
+};
+type MockCtx<PH extends AnyPlugHead> = keyof ExtractCtx<PH> extends never ? Record<string, never> : MockCtxContent<PH, ExtractCtx<PH>>;
+type MockPlugMapData<PH extends AnyMapPlugHead> = {
+    $?: MockCtx<PH>;
+} & MockPlugMapDataDeps<PH>;
+type MockPlugListData<PH extends AnyListPlugHead> = {
+    $?: MockCtx<PH>;
+} & MockPlugListDeps<PH>;
+export {};

package/lib/mock-plug.js

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+import { getPlugResolve, setPlugResolve, } from "r-machine/core";
+import { RMachineUsageError } from "r-machine/errors";
+import { ERR_PLUG_ALREADY_MOCKED } from "#r-machine/testing/errors";
+const plugMockSymbol = Symbol("plugMock");
+export const mockPlug = (plug) => {
+    return {
+        with: (_data) => {
+            const prevResolve = getPlugResolve(plug);
+            if (prevResolve[plugMockSymbol]) {
+                throw new RMachineUsageError(ERR_PLUG_ALREADY_MOCKED, "Plug is already mocked.");
+            }
+            const resolve = (locale, chain) => {
+                // TODO: WIP - For now, just return the original resolve result.
+                // Plan: read data.$.locale (if set) to override locale; call prevResolve; deep-merge _data.
+                // Caveat: prevResolve may install a lazy getter on $.kit[selfKey] for kit self-reference.
+                // Deep-merging enumerates kit keys and would invoke that getter; if the self-juncture isn't
+                // cached yet (factory still running), the getter throws. Handle this in the merge step —
+                // e.g. skip own-property getters or short-circuit on self-ref keys.
+                return prevResolve(locale, chain);
+            };
+            resolve[plugMockSymbol] = true;
+            setPlugResolve(plug, resolve);
+            return () => {
+                setPlugResolve(plug, prevResolve);
+            };
+        },
+    };
+};

package/lib/mock-surface.cjs

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/mock-surface.d.cts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+import type { Action, AnyResAtlas, AnyResDomain, ExtractNamespace, Getter, HandleMap, RelayBrand } from "r-machine/core";
+type MockSurfaceItem<I> = I extends Getter<infer V> ? V : I extends Action<infer F> ? F : I extends RelayBrand ? never : I;
+type MockSurface<RD extends AnyResDomain> = {
+    [K in keyof RD as K extends `$${string}` ? never : K]?: MockSurfaceItem<RD[K]>;
+};
+export type MockSurfaceMap<RA extends AnyResAtlas, HM extends HandleMap<RA>> = {
+    [K in keyof HM]?: MockSurface<RA["shape"][ExtractNamespace<HM[K]>]>;
+};
+export {};

package/lib/mock-surface.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+import type { Action, AnyResAtlas, AnyResDomain, ExtractNamespace, Getter, HandleMap, RelayBrand } from "r-machine/core";
+type MockSurfaceItem<I> = I extends Getter<infer V> ? V : I extends Action<infer F> ? F : I extends RelayBrand ? never : I;
+type MockSurface<RD extends AnyResDomain> = {
+    [K in keyof RD as K extends `$${string}` ? never : K]?: MockSurfaceItem<RD[K]>;
+};
+export type MockSurfaceMap<RA extends AnyResAtlas, HM extends HandleMap<RA>> = {
+    [K in keyof HM]?: MockSurface<RA["shape"][ExtractNamespace<HM[K]>]>;
+};
+export {};

package/lib/mock-surface.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 Sergio Turolla
+ *
+ * This file is part of r-machine, licensed under the
+ * GNU Affero General Public License v3.0 (AGPL-3.0-only).
+ *
+ * You may use, modify, and distribute this file under the terms
+ * of the AGPL-3.0. See LICENSE in this package for details.
+ *
+ * If you need to use this software in a proprietary project,
+ * contact: licensing@codecarvings.com
+ */
+export {};